This package has been deprecated

    Author message:

    Deprecated in favor of @ceramicnetwork/streamid

    @ceramicnetwork/docid
    TypeScript icon, indicating that this package has built-in type declarations

    0.5.2 • Public • Published

    Ceramic DocId

    This package contains Ceramic DocID and CommitID implementation.

    Implements Ceramic DocIDs as defined in ceramic spec and CIP, represented as DocID and CommitID for API clarity.

    DocID represents a reference to a document as a whole, thus does not contain commit information.

    CommitID represents a reference to a particular commit in the document evolution.

    <docid> ::= <multibase-prefix><multicodec-docid><doctype><genesis-cid-bytes>
    

    or including DocID commit

    <docid> ::= <multibase-prefix><multicodec-docid><doctype><genesis-cid-bytes><commit-cid-bytes>
    

    Getting started

    Installation

    $ npm install @ceramicnetwork/docid
    

    Usage

    To reference a document as a whole, use DocID. You can create an instance from the parts. Document type string or integer and CID instance or string are required.

    import DocID from '@ceramicnetwork/docid';
    // alternatively: import { DocID } from '@ceramicnetwork/docid'
    
    const docid = new DocId('tile', 'bagcqcerakszw2vsov...');
    
    docid.type; // 0
    docid.typeName; // 'tile'
    docid.bytes; // Uint8Array(41) [ 206,   1,   0,   0,   1, 133,   1, ...]
    docid.cid; // CID('bagcqcerakszw2vsov...')
    docid.toString();
    //k3y52l7mkcvtg023bt9txegccxe1bah8os3naw5asin3baf3l3t54atn0cuy98yws
    docid.toUrl();
    //ceramic://k3y52l7mkcvtg023bt9txegccxe1bah8os3naw5asin3baf3l3t54atn0cuy98yws

    You can also create DocID instance from DocID string or bytes.

    const docid = DocID.fromString('k3y52l7mkcvtg023bt9txe...');
    const docid = DocID.fromBytes(Uint8Array(41) [ 206,   1,   0,   0,   1, 133,   1, ...])

    To reference particular point in a document evolution, use CommitID. In addition to document type (string or integer) and genesis reference (CID instance or string), one is expected to provide a reference to commit (CID instance or string). If you pass 0 or '0' (as string), null or just omit the value, this would reference a genesis commit.

    import { CommitID } from '@ceramicnetwork/docid';
    
    const commitId = new CommitID('tile', 'bagcqcerakszw2vsov...', 'bagcqcerakszw2vsov...');
    
    commitId.type; // 0
    commitId.typeName; // 'tile'
    commitId.bytes; // Uint8Array(41) [ 206,   1,   0,   0,   1, 133,   1, ...]
    commitId.cid; // CID('bagcqcerakszw2vsov...')
    commitId.commit; // CID('bagcqcerakszw2vsov...')
    
    commitId.toString();
    // k3y52l7mkcvtg023bt9txegccxe1bah8os3naw5asin3baf3l3t54atn0cuy98yws
    commitId.toUrl();
    // ceramic://k3y52l7mkcvtg023bt9txegccxe1bah8os3naw5asin3baf3l3t54atn0cuy98yws?version=k3y52l7mkcvt...

    To reference specific CID from DocID or to change commit reference in CommitID, use atCommit method:

    commitId.atCommit('bagcqcerakszw2vsov...'); // #=> new CommitID for the same document
    docId.atCommit('bagcqcerakszw2vsov...'); // #=> new CommitID for the same document

    CommitID (DocID for compatibility also) can get you base DocID via #baseID:

    commitId.baseID; // #=> DocID reference to the document
    docId.baseID; // #=> new DocID reference to the same document, effectively a shallow clone.

    To parse an unknown input into proper CommitID or DocID, you could use DocRef.from:

    import { DocRef } from '@ceramicnetwork/docid';
    const input = 'bagcqcerakszw2vsov...' // could be instance of Uint8Array, DocID, CommitID either; or in URL form
    const docIdOrCommitId = DocRef.from(input) // throws if can not properly parse it into CommitID or DocID

    Development

    Run tests:

    npm test

    Run linter:

    npm run lint

    Contributing

    We are happy to accept small and large contributions. Make sure to check out the Ceramic specifications for details of how the protocol works.

    License

    MIT or Apache-2.0

    Keywords

    Install

    npm i @ceramicnetwork/docid

    DownloadsWeekly Downloads

    50

    Version

    0.5.2

    License

    (Apache-2.0 OR MIT)

    Unpacked Size

    50.9 kB

    Total Files

    31

    Last publish

    Collaborators

    • npm.3box
    • smrz2001
    • oed
    • zachferland
    • paul_lecam
    • stbrody
    • ukstv