ipld / js-dag-cbor

dag-cbor codec for IPLD

@ipld/dag-cbor

JS implementation of DAG-CBOR

Table of contents

• Install
• Spec
• License
• Contribute

Install

$ npm i @ipld/dag-cbor

This is the new interface meant for use by itself or with multiformats and @ipld/block. It is not used by js-ipld-format which is currently used in IPFS. That library is here.

Usage:

import { encode, decode } from '@ipld/dag-cbor'
import { CID } from 'multiformats'

const obj = {
  x: 1,
  /* CID instances are encoded as links */
  y: [2, 3, CID.parse('QmaozNR7DZHQK1ZcU9p7QdrshMvXqWK6gpu5rmrkPdT3L4')],
  z: {
    a: CID.parse('QmaozNR7DZHQK1ZcU9p7QdrshMvXqWK6gpu5rmrkPdT3L4'),
    b: null,
    c: 'string'
  }
}

let data = encode(obj)
let decoded = decode(data)
decoded.y[0] // 2
CID.asCID(decoded.z.a) // cid instance

// encode/decode options are exported for use with cborg's encodedLength and decodeFirst
import { encodeOptions, decodeOptions } from '@ipld/dag-cbor'
import { encodedLength } from 'cborg/length'
import { decodeFirst } from 'cborg'

// dag-cbor encoded length of obj in bytes
const byteLength = encodedLength(obj, encodeOptions)
byteLength // 104

// concatenate two dag-cbor encoded obj
const concatenatedData = new Uint8Array(data.length * 2)
concatenatedData.set(data)
concatenatedData.set(data, data.length)

// returns dag-cbor decoded obj at the beginning of the buffer as well as the remaining bytes
const [first, remainder] = decodeFirst(concatenatedData, decodeOptions)
assert.deepStrictEqual(first, obj)
assert.deepStrictEqual(remainder, data)

Spec

The dag-cbor specification is in the IPLD specs repo.

License

Licensed under either of

• Apache 2.0, (LICENSE-APACHE / http://www.apache.org/licenses/LICENSE-2.0)
• MIT (LICENSE-MIT / http://opensource.org/licenses/MIT)

Contribute

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

js-dag-cbor's Issues

The automated release is failing 🚨

🚨 The automated release from the master branch failed. 🚨

I recommend you give this issue a high priority, so other packages depending on you can benefit from your bug fixes and new features again.

You can find below the list of errors reported by semantic-release. Each one of them has to be resolved in order to automatically publish your package. I’m sure you can fix this 💪.

Errors are usually caused by a misconfiguration or an authentication problem. With each error reported below you will find explanation and guidance to help you to resolve it.

Once all the errors are resolved, semantic-release will release your package the next time you push a commit to the master branch. You can also manually restart the failed CI job that runs semantic-release.

If you are not sure how to resolve this, here are some links that can help you:

• Usage documentation
• Frequently Asked Questions
• Support channels

If those don’t help, or if this issue is reporting something you think isn’t right, you can always ask the humans behind semantic-release.

---

No npm token specified.

An npm token must be created and set in the NPM_TOKEN environment variable on your CI environment.

Please make sure to create an npm token and to set it in the NPM_TOKEN environment variable on your CI environment. The token must allow to publish to the registry https://registry.npmjs.org/.

---

Good luck with your project ✨

Your semantic-release bot 📦🚀

feature request: export encode/decode -Options

I want to use cborg.decodeFirst with the decodeOptions from this repo.

ERR_PACKAGE_PATH_NOT_EXPORTED when upgrading from v7 to v8

I have a Node.js + Express + Typescript API Server project, which is currently using "@ipld/dag-cbor": "^7.0.2" as a dependency and working fine.

When I try to upgrade to 8.0.0, I get the following when I run the app:

yarn run v1.22.19
$ nodemon src/server.ts
[nodemon] 2.0.20
[nodemon] to restart at any time, enter `rs`
[nodemon] watching path(s): *.*
[nodemon] watching extensions: ts,json
[nodemon] starting `ts-node src/server.ts`
Error [ERR_PACKAGE_PATH_NOT_EXPORTED]: No "exports" main defined in /path-to-my-project/node_modules/@ipld/dag-cbor/package.json
    at new NodeError (node:internal/errors:387:5)
    at throwExportsNotFound (node:internal/modules/esm/resolve:365:9)
    at packageExportsResolve (node:internal/modules/esm/resolve:589:7)
    at resolveExports (node:internal/modules/cjs/loader:522:36)
    at Function.Module._findPath (node:internal/modules/cjs/loader:562:31)
    at Function.Module._resolveFilename (node:internal/modules/cjs/loader:971:27)
    at Function.Module._resolveFilename.sharedData.moduleResolveFilenameHook.installedValue [as _resolveFilename] (/path-to-my-project/node_modules/node_modules/@cspotcode/source-map-support/source-map-support.js:811:30)
    at Function.Module._load (node:internal/modules/cjs/loader:833:27)
    at Module.require (node:internal/modules/cjs/loader:1057:19)
    at require (node:internal/modules/cjs/helpers:103:18) {
  code: 'ERR_PACKAGE_PATH_NOT_EXPORTED'
}

Everything else in my package.json is the same as before. If relevant, using Node 16.18.1 and latest current versions of express, nodemon, ts-node.

Do you have any suggestions how to resolve?

Thanks

Handling of `undefined` for old blocks

We at Ceramic used the legacy codec to store data, when it was the only option. Apparently, some of the data contain undefined. New js-ipfs release can retrieve a block, but can not decode it, as undefined is not allowed anymore in code. IMO, it is a bug to so drastically change the code and not make it visible for a general audience. You know, SemVer was created for a reason.

As ipfs is released with this dag-cbor codec which is more strict than the legacy dag-cbor codec, I am wondering, what is the plan to accomodate for old blocks created by the legacy codec? Could you lift the restrictions for undefined, maybe, so that old IPFS records could be properly decoded still?

can we add option to strip undefined instead of erroring

I've been working on UCAN based RPC system that encodes request / responses into set of CBOR blocks in a CAR. Unfortunately it proved challenging to not encounter errors from CBOR codec due to some field set to undefined or due to some built-in data type like Error been referenced.

Could we add an option to make CBOR codec behave more or less like JSON.stringify does, specifically

1. Just leave out undefined values
2. Don't complain about Error or other built-in instances, instead just include own enumerable properties

Unable to add custom tags

It looks like the exported function configureDecoder should support adding custom tags, but currently the tags on options are ignored: https://github.com/ipld/js-dag-cbor/blob/master/index.js#L89.

I would be happy to submit a PR if this is functionality that would be useful generally?

'decode' is not exported from '@ipld/dag-cbor'

I'm using nft.storage in my project. This library have ipld dependence.

I've got this error when I try generate a project build:

./node_modules/@ipld/car/esm/lib/decoder.js
Attempted import error: 'decode' is not exported from '@ipld/dag-cbor' (imported as 'decodeDagCbor').

Can somebody help me?

Invalid types are generated and published

We had to disable lib check here nftstorage/nft.storage#56 (comment) because js-dag-cbor seems to have invalid types generated. Specifically:

export const encode: (data: T) => import("multiformats/codecs/interface").ByteView<T>;

T generic type parameter is not declared for whatever reason. It maybe related to microsoft/TypeScript#41258