Truestamp Canonify

Description

A tiny zero-dependency JSON canonicalization library written in Typescript that supports ES Modules, IIFE, and CommonJS loaders and runs in Deno, Node.js, and modern browsers.

Canonicalization of JavaScript/TypeScript data structures to a standard and deterministically ordered output can be very useful for hashing and signing complex nested structures where the ordering is unknown.

This library should fully implements the JSON Canonicalization Scheme (JCS) as documented in RFC8785.

Significant testing was done to ensure the library stays true to JSON.stringify() single argument behaviors.

Usage

Here are some simple usage examples.

There are working code examples for Deno, Node.js, and the Web in the /examples directory. Take a look at the examples/README.md for usage instructions.

Node.js (CommonJS)

Setup Node.js

In your NPM project directory.

npm install --save @truestamp/canonify

Require the @truestamp/canonify CommonJS module in your project.

Node.js Example

const { canonify } = require('@truestamp/canonify');

const example = {
  big: BigInt(42).toString(),
  f: false,
  fun: () => { },
  n: null,
  num: 42,
  s: "string",
  sym: Symbol("hello"),
  t: true,
  u: undefined,
  a: [
    undefined,
    null,
    true,
    false,
    "foo",
    42,
    BigInt(42).toString(),
    Symbol("hello"),
    () => { },
  ],
}

console.log(canonify(example));

Deno (ES Modules)

Deno is a simple, modern and secure runtime for JavaScript and TypeScript that uses V8 and is built in Rust.

Setup Deno

Recent versions of canonify are published to the official Deno third party modules CDN.

https://deno.land/x/canonify

Deno Example

// IMPORTANT : use the current release version of `canonify`
// in the module URL. Replace `@v1.0.1` with the latest version.
// Versions are tied to GitHub release tags.
import { canonify } from "https://deno.land/x/canonify@v1.0.1/mod.ts";

const example = {
  big: BigInt(42).toString(),
  f: false,
  fun: () => { },
  n: null,
  num: 42,
  s: "string",
  sym: Symbol("hello"),
  t: true,
  u: undefined,
  a: [
    undefined,
    null,
    true,
    false,
    "foo",
    42,
    BigInt(42).toString(),
    Symbol("hello"),
    () => { },
  ],
}

console.log(canonify(example));

API Documentation

The TypeScript API documentation for this project is generated and published upon each new release.

Testing

This library aims to maintain 100% code test coverage and it passes 100% of the test vectors provided by the RFC8785 testdata vectors. This should help ensure that its output is consistent with other compliant libraries on other runtimes.

Thanks

Much of the code is ported to TypeScript from, and was based on, the following excellent examples:

Porting to Typescript was necessary for the additional security that strongly typed code provides, as well as for serving as the base for transpilation for use in other runtime contexts.

Contributing

We’d love you to join our network of contributors. Please read CONTRIBUTING.md for help getting started.

Releasing

Commit changes, merge PR’s to main branch
Bump version field in package.json
Cut a new release
New release will trigger workflow to build, test, and publish package to Github Package Registry and NPM.js.

Code of Conduct

We expect all members of the community to respect our Code of Conduct at all times.