typeson-registry

What is typeson-registry?

The typeson-registry npm package is a collection of types for Typeson, a library that allows you to serialize and deserialize JavaScript objects with custom types. It provides a registry of common types that can be used to extend the functionality of Typeson.

What are typeson-registry's main functionalities?

Date Serialization

This feature allows you to serialize and deserialize Date objects. The code sample demonstrates how to register the date type from typeson-registry and use it to serialize and deserialize a Date object.

{"import":"import Typeson from 'typeson';\nimport typesonRegistry from 'typeson-registry';","usage":"const typeson = new Typeson().register(typesonRegistry.date);\nconst serialized = typeson.stringify(new Date());\nconst deserialized = typeson.parse(serialized);"}

Set Serialization

This feature allows you to serialize and deserialize Set objects. The code sample demonstrates how to register the set type from typeson-registry and use it to serialize and deserialize a Set object.

{"import":"import Typeson from 'typeson';\nimport typesonRegistry from 'typeson-registry';","usage":"const typeson = new Typeson().register(typesonRegistry.set);\nconst serialized = typeson.stringify(new Set([1, 2, 3]));\nconst deserialized = typeson.parse(serialized);"}

Map Serialization

This feature allows you to serialize and deserialize Map objects. The code sample demonstrates how to register the map type from typeson-registry and use it to serialize and deserialize a Map object.

{"import":"import Typeson from 'typeson';\nimport typesonRegistry from 'typeson-registry';","usage":"const typeson = new Typeson().register(typesonRegistry.map);\nconst serialized = typeson.stringify(new Map([[1, 'one'], [2, 'two']]));\nconst deserialized = typeson.parse(serialized);"}

Other packages similar to typeson-registry

superjson

SuperJSON is a library that allows you to serialize JavaScript objects containing more complex data types like Dates, Maps, Sets, and more. It is similar to typeson-registry in that it provides serialization and deserialization capabilities for complex types, but it is designed to work seamlessly with Next.js and other modern frameworks.

flatted

Flatted is a library that allows you to serialize and deserialize JavaScript objects with circular references. While it does not provide the same type registry as typeson-registry, it offers a solution for handling circular references, which can be a limitation in standard JSON serialization.

circular-json

CircularJSON is another library for serializing and deserializing JavaScript objects with circular references. It is similar to flatted but offers a different approach to handling circular references. Unlike typeson-registry, it does not provide a registry of types but focuses on solving the circular reference problem.

README

typeson-registry

The type registry for typeson.

• Types listed under types
• Presets listed under presets

See below for notes on these types and presets.

Note that some types will require polyfills in Node such as via jsdom. See the testing environment of test/test.js for some examples.

Installation

Note that for Node.js, to use the file or blob types (or the filelist type or structuredCloning and structuredCloningThrowing presets which include them), you will need a polyfill for Blob or File, respectively, as well as FileReader and URL.createObjectURL (and a polyfill for URL if you are using Node < 10.0.0 or an older browser). Note that our URL.createObjectURL polyfill expects a global XMLHttpRequest and location.href predefined before it as well (and one which can handle data: URLs). For Node, you can add it like this:

const url = require('url'); // This line only needed to support Node < 10.0.0
const {createObjectURL} = require('typeson-registry/polyfills/createObjectURL.umd.cjs');

const URL = url.Url; // This line only needed to support Node < 10.0.0
URL.createObjectURL = createObjectURL;

We have not added jsdom as a dependency, but it is required if this polyfill is used.

Besides the polyfills for file or blob, the structuredCloningThrowing preset also needs a global DOMException polyfill.

The filelist type, in addition to the polyfills for file, will need a FileList polyfill (including a FileList string tag).

The imagebitmap type requires a global createImageBitmap polyfill (and an ImageBitmap polyfill (including an ImageBitmap string tag).

The imagedata type requires a global ImageData polyfill (including an ImageData string tag).

You may wish to see our test-environment.js file for how some polyfilling may be done (largely using jsdom).

Building files from Git clone (as opposed to npm installs)

If you have cloned the repo (and not the npm package), you must run npm install to get the devDependencies and then run npm run rollup to get the individual browser scripts built locally (into dist) or to get index.js to be rebuilt based on existing presets and types).

Usage (Pre-rollup in Node or browser)

import {Typeson, date, error, regexp, typedArrays} from 'typeson-registry';

const TSON = new Typeson().register([
    date,
    error,
    regexp,
    typedArrays
    // ...
]);

const tson = TSON.stringify({
    Hello: 'world',
    date: new Date(),
    error: new Error('test'),
    inner: {
        x: /foo/gui,
        bin: new Uint8Array(64)
    }
}, null, 2);

console.log(tson);
/* Output:

{
  "Hello": "world",
  "date": 1464049031538,
  "error": {
    "name": "Error",
    "message": "test"
  },
  "inner": {
    "x": {
      "source": "foo",
      "flags": "gi"
    },
    "bin": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=="
  },
  "$types": {
    "date": "Date",
    "error": "Error",
    "inner.x": "RegExp",
    "inner.bin": "Uint8Array"
  }
}
*/

const parsedBack = TSON.parse(tson);

console.log(parsedBack.date instanceof Date);
console.log(parsedBack.inner.bin instanceof Uint8Array);

Usage (Node without own Rollup)

const {Typeson, builtin} = require('typeson-registry');

const tson = new Typeson().register([
    builtin
]);

Usage (import in supporting browsers without own Rollup)

<script type="module">

import {Typeson, builtin} from './node_modules/typeson-registry/dist/index.js';

const TSON = new Typeson().register([
    builtin
]);
</script>

Usage (with plain script tags without own Rollup)

All types and presets under dist/ are UMD modules so you could also require them as AMD modules with requirejs if you prefer.

<!DOCTYPE html>
<html>
  <head>
    <script src="https://unpkg.com/typeson/dist/typeson.umd.min.js"></script>
    <script src="https://unpkg.com/typeson-registry/dist/presets/builtin.umd.cjs"></script>
    <script>

    const TSON = new Typeson().register(builtin);
    const tson = TSON.stringify({
        Hello: 'world',
        date: new Date(),
        error: new Error('err'),
        inner: {
            x: /foo/giu,
            bin: new Uint8Array(64)
        }
    }, null, 2);

    alert(tson);
    /* Alerts:

    {
      "Hello": "world",
      "date": 1464049031538,
      "error": {
        "name": "Error",
        "message": "err"
      },
      "inner": {
        "x": {
          "source": "foo",
          "flags": "gi"
        },
        "bin": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=="
      },
      "$types": {
        "date": "Date",
        "error": "Error",
        "inner.x": "RegExp",
        "inner.bin": "Uint8Array"
      }
    }
    */

    </script>
  </head>
</html>

Notes on types and presets

Note that the type name corresponds to the file name in the following manner:

1. Genuine separate words are camel-cased in the type name but hyphenated in the file name (e.g., negativeInfinity and negativity-infinity.js); names whose original API is camel-cased are not hyphenated, however (e.g., arraybuffer and arraybuffer.js given ArrayBuffer).
2. All other portions of names are lower-cased (e.g., date and date.js).
3. Type names that would clash with existing objects when exported (even after lower-casing) must have a separate, preferably abbreviated form (e.g., the type and preset undef and undef.js was necessary for undefined)
4. Type names which are not allowed as ES6 exports (e.g., periods in Intl types are now removed: Intl.Collator -> IntlCollator)
5. Type names should indicate the singular (e.g., userObject) except for files containing multiple related exports (e.g., errors, typed-arrays, and typed-arrays-socketio.js); files with multiple exports whose extra exports are incidental (e.g., filelist) do not need a plural.

Types

• arraybuffer
• bigintObject
• bigint
• blob - Has sync and async encapsulation/replacements (though sync only via deprecated means)
• cloneable - Looks for Symbol.for('cloneEncapsulate') and Symbol.for('cloneRevive') methods to allow for a means of extending our built-in structured cloning presets (though if you are polyfilling a standard object, we welcome you to submit back as a PR!). The clones cannot be revived past the current window session, however.
• cryptokey
• dataview
• date
• domexception
• dommatrix
• dommatrixreadonly
• dompoint
• dompointreadonly
• domquad
• domrect
• domrectreadonly
• error.js (Error) and errors.js (TypeError, RangeError, SyntaxError, ReferenceError, EvalError, URIError, InternalError) - These provide a means of resurrecting error object across cloning boundaries (since they are not otherwise treated as cloneable by the Structured Cloning Algorithm).
• file - Has sync and async encapsulation/replacements (though sync only via deprecated means)
• filelist - HTML does not provide a means of creating a FileList object dynamically, so we polyfill one for revival. This method also sets File
• imagebitmap - Has sync and async revivers. If OffscreenCanvas is not supported, the sync method does not produce a genuine ImageBitmap but instead produces a canvas element which can frequently be used in a similar context to ImageBitmap.
• imagedata
• infinity - Preserves positive infinity
• intl-types.js (Intl.Collator, Intl.DateTimeFormat, Intl.NumberFormat) - Not all properties can be preserved
• map
• nan - Preserves NaN (not a number)
• negativeInfinity - Preserves negative infinity
• negativeZero - Preserves -0 (produces + or - Infinity when used as divisor)
• nonBuiltInIgnore - For roughly detecting non-builtin objects and to avoid adding them as properties
• primitive-objects.js (StringObject, BooleanObject, NumberObject)
• regexp
• resurrectable - Resurrects any non-array object, function, or symbol; can only be revived for the current window session.
• set
• typed-arrays-socketio.js (Int8Array, Uint8Array, Uint8ClampedArray, Int16Array, Uint16Array, Int32Array, Uint32Array, Float32Array, Float64Array) - See typeson#environmentformat-support and presets/socketio.js
• typed-arrays.js (Int8Array, Uint8Array, Uint8ClampedArray, Int16Array, Uint16Array, Int32Array, Uint32Array, Float32Array, Float64Array) - Base64-encodes
• undef (for undefined) (See also presets/undefined.js and presets/sparse-undefined.js)
• userObjects - Allows for inherited objects but ensures the prototype chain inherits from Object (or null). Should be low priority if one is matching other objects as it will readily match many objects.

Presets

• array-nonindex-keys.js
• builtin.js - Types that are built into the JavaScript language itself. Types that were added in ES6 or beyond will be checked before inclusion so that this module can be consumed by both ES5 and ES6 environments. Some imperfectly serializable objects (such as functions and Symbols) are not included in this preset.
• postmessage.js - This preset is intended as a utility to expand on what is cloneable via strcutured-cloning.js and supports Error objects.
• socketio.js
• sparse-undefined.js (sparseArrays and sparseUndefined) - Supports reconstructing sparse arrays (with missing properties not even assigned an explicit undefined). See types/undefined.js for the explicit case or presets/undefined.js for a utility combining both.
• special-numbers.js (preserves NaN, Infinity, -Infinity)
• structured-cloning.js - For the Structured Cloning Algorithm used by the likes of postMessage and indexedDB. See also the cloneable type.
• structured-cloning-throwing.js - Same as structured-cloning.js but throws with non-recognized types. See also the cloneable type.
• undef.js - Supports reconstructing explicit and implicit (sparse) uses of undefined.
• universal.js- Meant for de-facto universal types. Currently includes built-ins only.

Functions (support not included)

If you are looking for a way to resurrect functions, you can use the following, but please bear in mind that it uses eval which is prohibited by some Content Security Policies (CSP) (so we are not packaging it with our builds), that it is unsafe, and also that the function might not behave deterministically when revived (e.g., if the function were provided from another context).

const functionType = {functionType: [
    function (x) { return typeof x === 'function'; },
    function (funcType) { return '(' + funcType.toString() + ')'; },
    // eslint-disable-next-line no-eval
    function (o) { return eval(o); }
]};

const typeson = new Typeson().register(functionType);
const tson = typeson.stringify(function () { return 'abc'; });
const back = typeson.parse(tson);
back(); // 'abc'

Development

node-canvas is used to test ImageData.

Be sure to follow the installation steps.

On Windows, besides following the Windows installation steps, this helped complete the installation. If you need to have it rebuilt, you can run npm i inside of the node_modules/canvas directory.

These steps were also necessary but you can run npm run windows after install to get these steps applied. These are the only steps which should need to be re-run if you have deleted your local node-canvas copy.

See also

• typeson