Notorious Party Muppets

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

    2.3.13 • Public • Published

    build status dependency status npm downloads

    Motivation

    (Adapted from monocle site)

    Modifying immutable nested object in JavaScript is verbose which makes code difficult to understand and reason about.

    Let's have a look at some examples:

    interface Street {
      num: number
      name: string
    }
    interface Address {
      city: string
      street: Street
    }
    interface Company {
      name: string
      address: Address
    }
    interface Employee {
      name: string
      company: Company
    }

    Let’s say we have an employee and we need to upper case the first character of his company street name. Here is how we could write it in vanilla JavaScript

    const employee: Employee = {
      name: 'john',
      company: {
        name: 'awesome inc',
        address: {
          city: 'london',
          street: {
            num: 23,
            name: 'high street'
          }
        }
      }
    }
    
    const capitalize = (s: string): string => s.substring(0, 1).toUpperCase() + s.substring(1)
    
    const employeeCapitalized = {
      ...employee,
      company: {
        ...employee.company,
        address: {
          ...employee.company.address,
          street: {
            ...employee.company.address.street,
            name: capitalize(employee.company.address.street.name)
          }
        }
      }
    }

    As we can see copy is not convenient to update nested objects because we need to repeat ourselves. Let's see what could we do with monocle-ts

    import { Lens } from 'monocle-ts'
    
    const company = Lens.fromProp<Employee>()('company')
    const address = Lens.fromProp<Company>()('address')
    const street = Lens.fromProp<Address>()('street')
    const name = Lens.fromProp<Street>()('name')

    compose takes two Lenses, one from A to B and another one from B to C and creates a third Lens from A to C. Therefore, after composing company, address, street and name, we obtain a Lens from Employee to string (the street name). Now we can use this Lens issued from the composition to modify the street name using the function capitalize

    const capitalizeName = company.compose(address).compose(street).compose(name).modify(capitalize)
    
    assert.deepStrictEqual(capitalizeName(employee), employeeCapitalized)

    You can use the fromPath API to avoid some boilerplate

    import { Lens } from 'monocle-ts'
    
    const name = Lens.fromPath<Employee>()(['company', 'address', 'street', 'name'])
    
    const capitalizeName = name.modify(capitalize)
    
    assert.deepStrictEqual(capitalizeName(employee), employeeCapitalized) // true

    Here modify lift a function string => string to a function Employee => Employee. It works but it would be clearer if we could zoom into the first character of a string with a Lens. However, we cannot write such a Lens because Lenses require the field they are directed at to be mandatory. In our case the first character of a string is optional as a string can be empty. So we need another abstraction that would be a sort of partial Lens, in monocle-ts it is called an Optional.

    import { Optional } from 'monocle-ts'
    import { some, none } from 'fp-ts/Option'
    
    const firstLetterOptional = new Optional<string, string>(
      (s) => (s.length > 0 ? some(s[0]) : none),
      (a) => (s) => (s.length > 0 ? a + s.substring(1) : s)
    )
    
    const firstLetter = company.compose(address).compose(street).compose(name).asOptional().compose(firstLetterOptional)
    
    assert.deepStrictEqual(firstLetter.modify((s) => s.toUpperCase())(employee), employeeCapitalized)

    Similarly to compose for lenses, compose for optionals takes two Optionals, one from A to B and another from B to C and creates a third Optional from A to C. All Lenses can be seen as Optionals where the optional element to zoom into is always present, hence composing an Optional and a Lens always produces an Optional.

    TypeScript compatibility

    The stable version is tested against TypeScript 3.5.2, but should run with TypeScript 2.8.0+ too

    monocle-ts version required typescript version
    2.0.x+ 3.5+
    1.x+ 2.8.0+

    Note. If you are running < typescript@3.0.1 you have to polyfill unknown.

    You can use unknown-ts as a polyfill.

    Documentation

    Experimental modules (version 2.3+)

    Experimental modules (*) are published in order to get early feedback from the community.

    The experimental modules are independent and backward-incompatible with stable ones.

    (*) A feature tagged as Experimental is in a high state of flux, you're at risk of it changing without notice.

    From monocle@2.3+ you can use the following experimental modules:

    • Iso
    • Lens
    • Prism
    • Optional
    • Traversal
    • At
    • Ix

    which implement the same features contained in index.ts but are pipe-based instead of class-based.

    Here's the same examples with the new API

    interface Street {
      num: number
      name: string
    }
    interface Address {
      city: string
      street: Street
    }
    interface Company {
      name: string
      address: Address
    }
    interface Employee {
      name: string
      company: Company
    }
    
    const employee: Employee = {
      name: 'john',
      company: {
        name: 'awesome inc',
        address: {
          city: 'london',
          street: {
            num: 23,
            name: 'high street'
          }
        }
      }
    }
    
    const capitalize = (s: string): string => s.substring(0, 1).toUpperCase() + s.substring(1)
    
    const employeeCapitalized = {
      ...employee,
      company: {
        ...employee.company,
        address: {
          ...employee.company.address,
          street: {
            ...employee.company.address.street,
            name: capitalize(employee.company.address.street.name)
          }
        }
      }
    }
    
    import * as assert from 'assert'
    import * as L from 'monocle-ts/Lens'
    import { pipe } from 'fp-ts/function'
    
    const capitalizeName = pipe(
      L.id<Employee>(),
      L.prop('company'),
      L.prop('address'),
      L.prop('street'),
      L.prop('name'),
      L.modify(capitalize)
    )
    
    assert.deepStrictEqual(capitalizeName(employee), employeeCapitalized)
    
    import * as O from 'monocle-ts/Optional'
    import { some, none } from 'fp-ts/Option'
    
    const firstLetterOptional: O.Optional<string, string> = {
      getOption: (s) => (s.length > 0 ? some(s[0]) : none),
      set: (a) => (s) => (s.length > 0 ? a + s.substring(1) : s)
    }
    
    const firstLetter = pipe(
      L.id<Employee>(),
      L.prop('company'),
      L.prop('address'),
      L.prop('street'),
      L.prop('name'),
      L.composeOptional(firstLetterOptional)
    )
    
    assert.deepStrictEqual(
      pipe(
        firstLetter,
        O.modify((s) => s.toUpperCase())
      )(employee),
      employeeCapitalized
    )

    Install

    npm i monocle-ts

    DownloadsWeekly Downloads

    204,828

    Version

    2.3.13

    License

    MIT

    Unpacked Size

    368 kB

    Total Files

    103

    Last publish

    Collaborators

    • gcanti