On this page
@std/cbor
This @std package is experimental and its API may change without a major version bump.
Overview Jump to heading
Overview
Concise Binary Object Representation (CBOR) is a binary data serialisation format optimised for compactness and efficiency. It is designed to encode a wide range of data types, including integers, strings, arrays, and maps, in a space-efficient manner. RFC 8949 - Concise Binary Object Representation (CBOR) spec.
Limitations
- This implementation only supports the encoding and decoding of "Text String" keys.
- This implementation encodes decimal numbers with 64 bits. It takes no effort to figure out if the decimal can be encoded with 32 or 16 bits.
- When decoding, integers with a value below 2 ** 32 will be of type number, with all larger integers being of type bigint.
Functions and classes may have more specific limitations listed.
import { assert, assertEquals } from "@std/assert";
import { decodeCbor, encodeCbor } from "@std/cbor";
const rawMessage = "I am a raw Message!";
const encodedMessage = encodeCbor(rawMessage);
const decodedMessage = decodeCbor(encodedMessage);
assert(typeof decodedMessage === "string");
assertEquals(decodedMessage, rawMessage);
Add to your project Jump to heading
deno add jsr:@std/cbor
See all symbols in @std/cbor on
What is CBOR? Jump to heading
CBOR (Concise Binary Object Representation) is like a binary version of JSON. It stores data in a compact binary format instead of text, which reduces size and speeds up parsing.
It supports all the common types (numbers, strings, booleans, null, arrays, maps) plus binary data and big integers. CBOR is typically used for sending data over the network (ideal for IoT or mobile devices where there is limited bandwidth), storing compact payloads, and interop between languages.
Why use @std/cbor? Jump to heading
This package provides simple functions to encode JavaScript objects to CBOR binary and decode CBOR binary back to JavaScript objects.
Examples Jump to heading
import { decodeCbor, encodeCbor } from "@std/cbor";
const obj = { t: "temp", v: 21.5, ts: Date.now() };
const bin = encodeCbor(obj);
const back = decodeCbor(bin);
Binary data (Uint8Array) Jump to heading
import { decodeCbor, encodeCbor } from "@std/cbor";
const bytes = new TextEncoder().encode("hello");
const encoded = encodeCbor(bytes);
const decoded = decodeCbor(encoded);
if (!(decoded instanceof Uint8Array)) throw new Error("expected bytes");
console.log(new TextDecoder().decode(decoded)); // "hello"
Big integers behavior Jump to heading
Integers larger than 2**32 decode as bigint:
import { decodeCbor, encodeCbor } from "@std/cbor";
const bigNumber = 5_000_000_000; // > 2**32
const bigBytes = encodeCbor(bigNumber);
const bigValue = decodeCbor(bigBytes);
console.log(typeof bigValue); // "bigint"
console.log(bigValue === 5_000_000_000n); // true
const smallValue = decodeCbor(encodeCbor(42));
console.log(typeof smallValue); // "number"
Sequences (multiple values) Jump to heading
import { decodeCborSequence, encodeCborSequence } from "@std/cbor";
const packet = encodeCborSequence([{ id: 1 }, { id: 2 }, "done" as const]);
const values = decodeCborSequence(packet);
// values: [{ id: 1 }, { id: 2 }, "done"]
Tagged values (dates) Jump to heading
Use CBOR Tag 1 for epoch-based time (seconds since Unix epoch). How you interpret tags on decode is up to your app.
import { decodeCbor, encodeCbor } from "@std/cbor";
import { CborTag } from "@std/cbor/tag";
const nowSeconds = Math.floor(Date.now() / 1000);
const tagged = new CborTag(1, nowSeconds);
const buf = encodeCbor(tagged);
const out = decodeCbor(buf) as CborTag;
console.log(out.tagNumber); // 1
console.log(out.tagContent); // epoch seconds
Decode guard pattern Jump to heading
When consuming untrusted bytes, check shapes after decode.
import { decodeCbor } from "@std/cbor";
function isRecord(x: unknown): x is Record<string, unknown> {
return typeof x === "object" && x !== null && !Array.isArray(x);
}
const bytesFromNetwork = new Uint8Array(/* ... */);
const value = decodeCbor(bytesFromNetwork);
if (!isRecord(value) || typeof value.type !== "string") {
throw new Error("Unexpected payload");
}
// safe to use
console.log(value.type);