The 'cids' npm package is used for handling Content Identifiers (CIDs) in the context of IPFS (InterPlanetary File System). CIDs are a fundamental part of IPFS, allowing for unique identification of content based on its cryptographic hash. This package provides utilities for creating, parsing, and working with CIDs.
Creating a CID
This feature allows you to create a new CID instance. The constructor takes the version, codec, and multihash as parameters. The example demonstrates creating a CID of version 1 with the 'dag-pb' codec.
const CID = require('cids');
const cid = new CID(1, 'dag-pb', Buffer.from('1220...'));
console.log(cid.toString());Parsing a CID
This feature allows you to parse an existing CID string. The example shows how to parse a CID and access its version property.
const CID = require('cids');
const cid = new CID('Qm...');
console.log(cid.version);Converting CID to different formats
This feature allows you to convert a CID to different versions. The example demonstrates converting a CID to version 1 and then converting it to a string.
const CID = require('cids');
const cid = new CID('Qm...');
console.log(cid.toV1().toString());The 'multihashes' package provides utilities for working with multihashes, which are a key component of CIDs. While 'cids' focuses on the entire CID structure, 'multihashes' is more specialized in handling the multihash part of CIDs.
The 'multibase' package is used for encoding and decoding data in various base encodings. CIDs often use multibase for encoding their string representations. This package is more focused on the encoding aspect, whereas 'cids' handles the entire CID structure.
The 'ipld' package provides tools for working with InterPlanetary Linked Data (IPLD), which is the data model used by IPFS. While 'cids' is specifically for handling CIDs, 'ipld' provides a broader set of tools for working with the data structures that CIDs point to.
CID implementation in JavaScript.
$ npm install --save cids
The code published to npm that gets loaded on require is in fact an ES5 transpiled version with the right shims added. This means that you can require it and use with your favourite bundler without having to adjust asset management process.
const CID = require('cids')
<script> tagLoading this module through a script tag will make the Cids obj available in the global namespace.
<script src="https://unpkg.com/cids/dist/index.min.js"></script>
<!-- OR -->
<script src="https://unpkg.com/cids/dist/index.js"></script>
You can create an instance from a CID string or CID Uint8Array
const CID = require('cids')
const cid = new CID('bafybeig6xv5nwphfmvcnektpnojts33jqcuam7bmye2pb54adnrtccjlsu')
cid.version // 1
cid.codec // 'dag-pb'
cid.code // 112
cid.multibaseName // 'base32'
cid.toString()
// 'bafybeig6xv5nwphfmvcnektpnojts33jqcuam7bmye2pb54adnrtccjlsu'
or by specifying the cid version, multicodec name and multihash:
const CID = require('cids')
const multihashing = require('multihashing-async')
const bytes = new TextEncoder('utf8').encode('OMG!')
const hash = await multihashing(bytes, 'sha2-256')
const cid = new CID(1, 'dag-pb', hash)
console.log(cid.toString())
// bafybeig6xv5nwphfmvcnektpnojts33jqcuam7bmye2pb54adnrtccjlsu
The multicodec integer code can also be used to create a new CID:
const cid = new CID(1, 112, hash)
console.log(cid.toString())
// bafybeig6xv5nwphfmvcnektpnojts33jqcuam7bmye2pb54adnrtccjlsu
The string form of v1 CIDs defaults to base32 encoding (v0 CIDs are always base58btc encoded). When creating a new instance you can optionally specify the default multibase to use when calling toBaseEncodedString() or toString()
const cid = new CID(1, 'raw', hash, 'base64')
console.log(cid.toString())
// mAXASIN69ets85WVE0ipva5M5b2mAqAZ8LME08PeAG2MxCSuV
If you construct an instance from a valid CID string, the base you provided will be preserved as the default.
// e.g. a base64url encoded CID
const cid = new CID('uAXASIHJSUj5lkfuP5VPWf_VahvhARLRqPkF24QxY-lKaSqvV')
cid.toString()
// uAXASIHJSUj5lkfuP5VPWf_VahvhARLRqPkF24QxY-lKaSqvV
Returns true if object is a valid CID instance, false if not valid.
It's important to use this method rather than instanceof checks in
order to handle CID objects from different versions of this module.
Validates the different components (version, codec, multihash, multibaseName) of the CID
instance. Throws an Error if not valid.
version must be either 0 or 1.
codec must be a string of a valid registered codec.
multihash must be a Uint8Array instance of a valid multihash.
multibaseName optional string. Must be a valid multibase name. Default is base58btc for v0 CIDs or base32 for v1 CIDs.
Additionally, you can instantiate an instance from a base encoded string.
Additionally, you can instantiate an instance from a Uint8Array.
Property containing the string identifier of the codec.
Property containing the integer identifier of the codec.
Property containing the CID version integer.
Property containing the multihash Uint8Array.
Property containing the default base to use when calling .toString
Property containing the full CID encoded as a Uint8Array.
Proprety containing a Uint8Array of the CID version, codec, and the prefix
section of the multihash.
Returns the CID encoded in version 0. Only works for dag-pb codecs.
Throws if codec is not dag-pb.
Returns the CID encoded in version 1.
Returns a base encoded string of the CID. Defaults to the base encoding in this.multibaseName.
The value of this.multibaseName depends on how the instance was constructed:
Uint8Array, or by passing only version + codec + multihash to the constructor), then multibaseName will be base58btc for a v0 CID or base32 for a v1 CID.Shorthand for cid.toBaseEncodedString described above.
Compare cid instance. Returns true if CID's are identical, false if otherwise.
Contributions welcome. Please check out the issues.
Check out our contributing document for more information on how we work, and about contributing in general. Please be aware that all interactions related to multiformats are subject to the IPFS Code of Conduct.
Small note: If editing the Readme, please conform to the standard-readme specification.
MIT
FAQs
CID Implementation in JavaScript
The npm package cids receives a total of 246,465 weekly downloads. As such, cids popularity was classified as popular.
We found that cids demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 5 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
A new Rust RFC proposes "Trusted Publishing" for Crates.io, introducing short-lived access tokens via OIDC to improve security and reduce risks associated with long-lived API tokens.
Security News
Cloudflare is expanding Node.js compatibility for Workers and Pages, enabling developers to use more npm packages through a hybrid approach that combines native code and polyfills for Node.js APIs.
Security News
The Python Software Foundation has expanded its CNA scope to include the Pallets Projects, enabling faster, more reliable CVE tracking for critical frameworks used in Python applications.