immu-ts

immuts

Type-safe, generic immutable datastructure for Typescript. Can be used as thin wrapper over immutablejs (or similar libraries) or on its own.

Motivation

tbd

Usage

Simple

interface IA {
    id: number;
    name: string;
}

let i = new Immutable<IA>({  
    id: 42,
    name: "foo"
});

let a = i.get();
let a2 = i.set(x => x.id, 23);

// a !== a2 => true

let a3 = i.set(x => x.id, "23"); // Results in compiler error, string cannot be assigned to number 

Nested

The integration is most valuable when used with a nested object:

interface IA {
    id: number;
    name: string;
}

interface IB {
    a1: IA;
    a2: IA;
}

interface IC {
    b: IB;
}

let i = new Immutable<IC>({
        b: {
            a1: {  
                id: 42,
                name: "foo"
            }, 
            a2: {
                id: 23,
                name: "bar"
            }
        }
    });

let c = i.get();
let c2 = i.set(x => x.b.a1.id, 12);
let c3 = i.get();

// c !== c2 => true
// c2 === c3 => true

// c.b.a2 === c2.b.a2 => true
// c.b.a1 !== c2.b.a1 => true

when you execute this:

let c2 = i.set(x => x.b.a1.id, 12);

the root, b, and a1 will be automatically cloned, before the new id is assigned to a1. And again, everything is type-safe, something like

let c4 = i.set(x => x.b.a1.id, "12");

would result in a compiler error, because the types of id and "12" do not match.

Complex Types

Plain JS objects can be easily cloned. When you have more complex objects, you can use a custom CloneStrategy:

class X {
    constructor(public foo: number) { }
}

class CustomCloneStrategy implements IImmutableCloneStrategy {
    public clone<T>(source: X | ICloneable<T>): X | T {
        if (source instanceof X) {
            return new X(source.foo);
        } else if (source.clone) {
            return source.clone();
        }

        throw new Error("Type not supported");
    }
}

let a = new Immutable(new X(23), new DefaultImmutableBackend<X>(new CustomCloneStrategy());
let a2 = a.set(x => x.bar, 42);

// a !== a2 => true

Another example for more complex, richer object hierarchies:

interface ICloneable<T> {
    clone(): T;
}

class Y implements ICloneable<Y> {
    constructor(public bar: string) { }

    public clone(): Y {
        return new Y(this.bar);
    }
}

class CustomCloneStrategy implements IImmutableCloneStrategy {
    public clone<T>(source: ICloneable<T>): T {
        if (source.clone) {
            return source.clone();
        }

        throw new Error("Type not supported");
    }
}

let a = new Immutable(new Y("23"), new DefaultImmutableBackend<Y>(new CustomCloneStrategy()));
let a2 = a.set(x => x.bar, "42");
let a3 = a.update(x => x.bar, x => x + "3");

// a !== a2 => true
// a.bar === "23" => true
// a2.bar === "42" => true
// a3.bar === "423" => true

Other backends

You can build your own backend/adapter or use the provided one for immutable-js:

Usage:

let a = new Immutable<IC>({ ... }, new ImmutableJsAdapterBackend<IC>());

Code:

export class ImmutableJsBackendAdapter<T> implements IImmutableBackend<T> {
    private data: Immutable.Map<string, any>;

    public init(data: T) {
        this.data = Immutable.fromJS(data);
    }

    public set<U>(path: string[], value: U) {
        this.data.setIn(path.concat([key]), value);
    }

    public update<U>(path: string[], update: (target: U) => void) {
        this.data.updateIn(path, update);
    }

    public get(): T {
        return this.data.toJS() as T;
    }
}

Limitations

Internet Explorer and undefined

To build up the property path (i.set(x => x.a.b.c) needs to be captured into ["a", "b", "c"]) the library relies on the ES6 Proxy object. In browsers where this is not suppored (mainly all versions of Internet Explorer) a fallback is used using Object.defineProperty.

This method does not deal correctly with optional properties, so something like this:

interface IA {    
    foo?: string;
    bar: number;
}

let i = new Immutable<IA>({
    // foo: "test", - leave undefined! 
    bar: 42
});

i.set(x => x.foo, "test2");

would fail because foo did not exist at the time of creation. If you don't target Internet Explorer this will not be an issue and everything should work just fine.

Outlook

TODO

• provide example(s) and tests for arrays
• benchmarks
• lots more :)