Immutable Records for Typescript

Typed Immutable records for TypeScript are a pain. Via code-generation, this module gives you the best of using plain objects - type-safety - with the value semantics you'll want to make efficient use of immutable data.

Currently there is no run-time prevention of mutation - if you fancy this, just Object.freeze the instances.

.equals and .is methods will ensure your comparisons follow value semantics: if all the values of two instances are indentical, the instances should be considered indentical.

Installation

npm install --save ts-immutable-record

Usage

This module works via code-generation, to enable type-safety through sufficiently granular typings.

Calling generate with:

const sourceCode = createRecord({
  name: "Person",
  generics: [`Job`],
  fields: [
    {
      name: "name",
      type: "string",
    },
    {
      name: "age",
      type: "number",
    },
    {
      name: "job",
      type: "Job",
    },
  ],
});

Will result in TypeScript source code that fulfills the below interface. As you can see, this also supports generating records with generics.

export default class Person<Job> {
    new (
        public name: string,
        public age: number,
        public job: Job
    ): Person;

    // returns a Person value with 0 .. many of the fields
    // differing to the current instance, with the rest using
    // the current instance's values. Will be `===` the original
    // if all values are equal to original values.
    derive(update: Update<Job>): Person<Job>;

    // two methods implementing value semantics
    equals(other: Person<{}>): boolean;
    is(other: Person<{}>): boolean;
};

export interface Update<Job> {
    name?: string
    age?: number
    job?: Job
}

 Runtime behaviour

Here's an example of the runtime APIs, running in ES6:

const createRecord = require("ts-immutable-record");
onst fs = require("fs");
const assert = require("assert");


const sourceCode = createRecord({
  name: "Person",
  generics: [`Job`],
  fields: [
    {
      name: "name",
      type: "string",
    },
    {
      name: "age",
      type: "number",
    },
    {
      name: "job",
      type: "Job",
    },
  ],
});

fs.writeFileSync("./Person.ts", sourceCode, { encoding: "utf8" });

// allow us to require Typescript files, compiled on demand
require("ts-node/register");

// generated code targets TS, so uses ES6 exports
const Person = require("./Person").default;

// stub version of Immutable's Map for this demo
class StubImmutableMap extends global.Map {
    // simple
    equals(m2) {
        for(const [k,v] of this) {
            if(m2.get(k) !== v) {
                return false;
            }
        }

        return true;
    }
}

function Map(kvs) {
    return new StubImmutableMap(Object.keys(kvs).map(k => [k, kvs[k]]));
}


const amy1 = new Person("amy", 32, Map({ title: "CEO" }));
const amy2 = new Person("amy", 32, Map({ title: "CEO" }));

assert(amy1.equals(amy2), "supports value equality via .equals");
assert(amy2.is(amy1), "supports value equality via .is");

const youngerAmy = amy2.derive({ age: 28 });
assert.notEqual(youngerAmy, amy2);
assert.equal(amy2.name, "amy", "other fields are not affected");


const amy4 = amy2.derive({ job: Map({ title: "VP "}) });
const amy5 = amy4.derive({ job: Map({ title: "CEO"}) });

assert(!amy4.is(amy2), "equality respects .equals methods of properties");
assert(amy5.is(amy2), "updating non-scalar values with .equals still reflects value semantic");