This package has been deprecated

Author message:

Deprecated in favor of @ceramicnetwork/streamid

@ceramicnetwork/docid

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