Nuclear Power Manager

    tsminilens
    TypeScript icon, indicating that this package has built-in type declarations

    2.0.1-alpha • Public • Published

    TsMiniLens: Type-safe mini Lens for TypeScript

    npm i tsminilens
    

    A type-safe and idiomatic way to navigate through nested JSON objects. Written in TypeScript so enjoy intellisense and compiler errors! (instead of null reference errors at run time).

    demo

    Releases

    2.0.1-alpha

    This release adds automatic selection from union types.

    Consider,

    type T1 = { kind: 't1', foo: string };
    type T2 = { kind: 't2', bar: number };
    type U = { element: T1|T2 };
    
    // I want to dot into the fields of T1 or T2 directly
    // this used to fail but will now work
    const l = L<U>().to('element', 'foo');

    The library is able to detect that field name foo identifies the type of element to be T1.

    Previously this requires a type guard e.g. L<U>().to('element').castIf(isT1).

    castIf should now be obsolete, although it's kept for backward compatibility.

    Use cases

    Given

    interface Address { city?: string; street: string };
    interface Person { name?: string; address: Address };
    
    const lensPerson2Street = lensFrom<Person>().to('address', 'street');
    
    // since 1.1.16
    const lensPerson2Street = L<Person>().to('address', 'street');

    view() to navigate safely

    UPDATE: for viewing only, optional chaining would be a better solution. Lens is more useful for updating / modifying data, see below.

    We all know the dreaded null reference exception (Law of demeter applies)

    const street = person.address.street; // error if address is null!

    with lens this never happens, in the following case, if address is null then view() returns null instead of erroring out

    const street = lensPerson2Street.view(person); // safe!

    set() or over() to update easily

    If immutability is a concern, then updating a nested data structure can be tedious.

    const updatedPerson = {
        ...person,
        address: {
            ...person.address,
            street: 'new street'
        }
    };
    // imagine more nesting! :(

    with set() this becomes a breeze. It does a CoW (Copy on Write) to support immutability.

    const personRelocated = lensPerson2Street.set(person, 'new street');
    

    Note personRelocated is a different object than person, or, person !== personRelocated.

    over() is handy if we are to modify (but not replace) the current street,

    const updatedPerson = lensPerson2Street.over(person, street => 'Level 2' + street);
    

    Quiz: how to implement set() in terms of over()?

    chain() and castIf()

    It's also possible to chain lenses with lens1.chain(lens2) or more fluently, lens1.then.to('level1', 'level2')

    lens.castIf(typeGuard) supports navigating through union types safely with type guards.

    arrays

    Operations on arrays are supported as arrays work similar to objects.

    lensFrom<string[]>().to(1).view([ 'aaa', 'bbb', 'ccc' ]);
    // 'bbb'

    Caveats

    Copy-on-write is implemented with the spread operator, e.g. { ...foo, bar: baz }. This works for plain objects and arrays, but is not safe for complex types such as Map, Set, or class etc.

    There are friendly requests to add support for view / set of array elements. The challenge is to not to disrupt the current interfaces too much so my guess it will be work in progress for a (long) while. In the mean time, it's practical to operate on arrays with the likes of map / filter (as one would normally do) over set / view.

    Remember it's mini

    Bear in mind it's mini indeed - there is absolutely no parity with lens proper as in Haskell.

    Install

    npm i tsminilens

    DownloadsWeekly Downloads

    32

    Version

    2.0.1-alpha

    License

    MIT

    Unpacked Size

    176 MB

    Total Files

    1804

    Last publish

    Collaborators

    • hacklew