Options
All
  • Public
  • Public/Protected
  • All
Menu

Module @ceramicnetwork/streamid

Ceramic StreamID

This package contains Ceramic StreamID and CommitID implementation.

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

StreamID represents a reference to a stream as a whole, thus does not contain commit information.

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

<streamid> ::= <multibase-prefix><multicodec-streamid><type><genesis-cid-bytes>

or including StreamID commit

<streamid> ::= <multibase-prefix><multicodec-streamid><type><genesis-cid-bytes><commit-cid-bytes>

Getting started

Installation

$ npm install @ceramicnetwork/streamid

Usage

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

import StreamID from '@ceramicnetwork/streamid';
// alternatively: import { StreamID } from '@ceramicnetwork/streamid'

const streamid = new StreamID('tile', 'bagcqcerakszw2vsov...');

streamid.type; // 0
streamid.typeName; // 'tile'
streamid.bytes; // Uint8Array(41) [ 206,   1,   0,   0,   1, 133,   1, ...]
streamid.cid; // CID('bagcqcerakszw2vsov...')
streamid.toString();
//k3y52l7mkcvtg023bt9txegccxe1bah8os3naw5asin3baf3l3t54atn0cuy98yws
streamid.toUrl();
//ceramic://k3y52l7mkcvtg023bt9txegccxe1bah8os3naw5asin3baf3l3t54atn0cuy98yws

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

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

To reference particular point in a stream evolution, use CommitID. In addition to stream 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/streamid';

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 StreamID or to change commit reference in CommitID, use atCommit method:

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

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

commitId.baseID; // #=> StreamID reference to the stream
streamId.baseID; // #=> new StreamID reference to the same stream, effectively a shallow clone.

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

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

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

Index

References

CommitID

Re-exports CommitID

StreamID

Re-exports StreamID

StreamRef

Re-exports StreamRef

StreamType

Re-exports StreamType

Variables

Const DEFAULT_BASE

DEFAULT_BASE: "base36" = "base36"

Const STREAMID_CODEC

STREAMID_CODEC: 206 = 206

Const TAG

TAG: unique symbol = Symbol.for('@ceramicnetwork/streamid/StreamID')

Const TAG

TAG: unique symbol = Symbol.for('@ceramicnetwork/streamid/CommitID')

Functions

codeByName

  • codeByName(name: string): number

complain

  • complain(message: string): never

fromBytes

  • fromBytes(bytes: Uint8Array): StreamID

fromBytes

  • fromBytes(bytes: Uint8Array): CommitID

fromString

  • Parse StreamID from string representation.

    see

    [[StreamID#toString]]

    see

    [[StreamID#toUrl]]

    Parameters

    • input: string

      string representation of StreamID, be it base36-encoded string or URL.

    Returns StreamID

fromString

  • Parse CommitID from string representation.

    see

    [[CommitID#toString]]

    see

    [[CommitID#toUrl]]

    Parameters

    • input: string

      string representation of CommitID, be it base36-encoded string or URL.

    Returns CommitID

isCidVersion

  • isCidVersion(input: number): input is 0 | 1

nameByCode

  • nameByCode(index: number): string

parseCID

  • parseCID(input: any): CID | undefined
  • Safely parse CID, be it CID instance or a string representation. Return undefined if not CID.

    Parameters

    • input: any

      CID or string.

    Returns CID | undefined

parseCommit

  • parseCommit(genesis: CID, commit?: CID | string | number): CID | null
  • Parse commit CID from string or number. null result indicates genesis commit. If commit is 0, '0', null or is equal to genesis CID, result is null. Otherwise, return commit as proper CID.

    Parameters

    • genesis: CID

      genesis CID for stream

    • Default value commit: CID | string | number = null

      representation of commit, be it CID, 0, '0', null

    Returns CID | null

readCid

  • readCid(bytes: Uint8Array): [CID, Uint8Array]

readVarint

  • readVarint(bytes: Uint8Array): [number, Uint8Array, number]

tryCatch

  • tryCatch<A>(f: () => A): A

Object literals

Const registry

registry: object

caip10-link

caip10-link: number = 1

tile

tile: number = 0