This minimal library decodes and encodes most useful CBOR structures into
prespecified JavaScript structures through a schema at runtime! When used in
TypeScript, parsed outputs will have the types you expect too. See
tiny-cbor, which is automatically
included, for limitations on what CBOR types are supported. It works in a
similar way to Zod where you define a schema object with functions exported by
this library. With this schema in hand, you can use the fromCBOR and toCBOR
functions to read, update, and write CBOR binary data.
You can install the latest version with:
Node
npm i @levischuck/tiny-cbor-schemaDeno
deno add jsr:@levischuck/tiny-cbor-schemaBun
bunx jsr add "@levischuck/tiny-cbor-schema"CBOR decoding example, this outputs a javascript value mapped with the schemo specified, which is a CBOR sequence / array of string, string, number.
To check that the decoded CBOR matches a schema you expect, or to access it more naturally in TypeScript and JavaScript, you may do something like the following:
// NPM
// import { cs } from "@levischuck/tiny-cbor-schema";
// or JSR
// import { cs } from "jsr:@levischuck/tiny-cbor-schema";
// (Use one of the above imports! The import below makes this documentation testable)
import { cs } from "./index.ts";
// Utility to demonstrate the type is known at type-check time
type AssertEqual<T, Expected> = T extends Expected ? Expected extends T ? T
: never
: never;
const HELLO_WORLD_BYTES = new Uint8Array([
0x83, // Array (3)
0x65, // text (5),
0x68, // h
0x65, // e
0x6C, // l
0x6C, // l
0x6F, // o
0x65, // text(5),
0x77, // w
0x6F, // o
0x72, // r
0x6C, // l
0x64, // d
0x01, // 1
]);
const schema = cs.tuple([cs.string, cs.string, cs.integer]);
const parsed = cs.fromCBOR(schema, HELLO_WORLD_BYTES);
// parsed will have the type [string, string, number]
// You don't need to use AssertEqual, this is just for demonstration that the type is preserved
const doubleChecked: AssertEqual<[string, string, number], typeof parsed> =
parsed;
// If the type failed, this will be `never`, which it should not, since fromCBORType will throw
if (
!Array.isArray(doubleChecked) || doubleChecked.length != 3 ||
doubleChecked[0] !== "hello" || doubleChecked[1] !== "world" ||
doubleChecked[2] !== 1
) {
// Is never thrown!
throw new Error("Did not parse as expected");
}
const encoded = cs.toCBOR(schema, parsed);
if (encoded.length != HELLO_WORLD_BYTES.length) {
// Is never thrown!
throw new Error("Length differs");
}
for (let i = 0; i < HELLO_WORLD_BYTES.length; i++) {
if (encoded[i] !== HELLO_WORLD_BYTES[i]) {
// Is never thrown!
throw new Error(`Different byte at ${i}`);
}
}
console.log("Success");