Custom Types

Codables allows you to define custom serialization for your own types using createCodableType and custom Coder instances.

When using Declarative Serialization, in most cases custom types will be created automatically for you.

Creating Custom Types


import { createCodableType, Coder } from "codables";
 
class Point {
  constructor(public x: number, public y: number) {}
}
 
const $$point = createCodableType(
  "Point", // name of the type
  (value) => value instanceof Point, // how to detect some value should be encoded using this type
  (point) => [point.x, point.y], // how to encode the value (might return rich data like `Map` or `Set`, or even other custom types)
  ([x, y]) => new Point(x, y) // how to recreate the value from the encoded data
);
 
// Create a custom coder instance that is aware of your custom type
const coder = new Coder([$$point]);
 
// Create your instance like normal
const point = new Point(10, 20);
const encoded = coder.encode(point);
// { $$Point: [10, 20] }
 
const decoded = coder.decode(encoded);
// decoded instanceof Point === true

It is intentionally not possible to globally register custom types. You can only register custom types on a custom coder instance.

Nested Custom Types

Custom types can contain other custom types and built-in types.

In this example, we create classes that use other custom types or complex built-in types like Date.

You don’t need to worry about recursive encoding/decoding. Codables will handle it for you.


class Address {
  constructor(public street: string, public city: string) {}
}
 
class Person {
  constructor(public name: string, public address: Address, public bornAt: Date) {}
}
 
const $$address = createCodableType(
  "Address",
  (value) => value instanceof Address,
  (addr) => [addr.street, addr.city],
  ([street, city]) => new Address(street, city)
);
 
const $$person = createCodableType(
  "Person", 
  (value) => value instanceof Person,
  (person) => ({ name: person.name, address: person.address, bornAt: person.bornAt }),
  (data) => new Person(data.name, data.address, data.bornAt)
);
 
const coder = new Coder([$$person, $$address]);
 
const person = new Person("Jane", new Address("123 Main St", "New York"), new Date("1990-01-01"));
const encoded = coder.encode(person);
/** 
 * { 
 *   $$Person: { 
 *     name: "Jane", 
 *     address: { $$Address: ["123 Main St", "New York"] }, 
 *     bornAt: { $$Date: "1990-01-01T00:00:00.000Z" } 
 *   } 
 * }
 */
 
const decoded = coder.decode(encoded);
// decoded instanceof Person === true