Helpers for handling immutable objects with typescript
Switch branches/tags
Clone or download
maimArt issue#4:
* removed dependency to complete lodash library and added specific dependencies to lodash´s #clonedeep, #get and #set functions to get the library lighter
Latest commit fde5fbb Jul 17, 2018

README.md

typescript-immutable-helper

Helpers for handling immutable objects with typescript

NPM

Replicator

Replicator is a tool to replicate and modify immutable objects.

Syntax

simply replace property by with new value
return ReplicationBuilder.forObject(state).property('party').replaceValueOf('name').with('MyParty').build()
replace property depending on old value
return ReplicationBuilder.forObject(state).property('party').replaceValueOf('partymemberArray').by((oldPartymemberArray) => [...oldPartymemberArray, 'new partymember']).build()
clone property and apply some function on it
return ReplicationBuilder.forObject(state).replaceValueOf('party').withCloneAndDo((clonedParty) => clonedParty.addPartyMember('new partymember')).build()

Characteristics

typesafe properties

image

typesafe property values

image

chainable
return ReplicationBuilder.forObject(state)
    .property('party').replaceValueOf('name').with('MyParty').replaceValueOf('members').by((members) => [...members, newMember])
    .property('initiator').replaceValueOf('prename').with('Party').replaceValueOf('surname').with('guy')
    .build();
refactorable and easy to read

Usage

  1. Load an object by calling ReplicationBuilder.forObject()
  2. Navigate down the object tree through the typesafe function property()
  3. Modify a property with either (see syntax paragraph above)
    • replaceValueOf('prop').with(newValue:T)
    • replaceValueOf('prop').by((T) => newValue:T)
    • replaceValueOf('prop').withCloneAndDo((clonedProp) => clonedProp.doSomething()
    • removeProperty('prop') to remove the property in the resulting object
  4. Repeat step 3 and 4 until all modifications are done
  5. Produce the replica with build()

Behaviour

  • deep copies the source object
  • freeze in --> freeze out. If the source object was frozen (for detecting manipulations while development), then the produced replica will also be deep frozen.
  • warning if source object is not deep frozen (produced replica will be deep frozen)

DeepFreeze

DeepFreeze freezes an object recursively and the developer is pointed to illegal state manipulations by errors in the javascript console.

deepFreeze() applies Object.freeze() recursively on an object to make it immutable isDeepFrozen() checks if an object is recursively frozen.

Example: Usage of Replicator and DeepFreeze in an angular redux module

export class StoreModule {
  constructor(/* ... */) {
    /* ... */
    const rootState = isDevMode()? deepFreeze(INITIAL_ROOTSTATE) : INITIAL_ROOTSTATE    

    store.configureStore(
      rootReducer,
      rootState,
      middlewares,
      storeEnhancer
    )
  }
}

If the state is initially frozen and you are using the Replicator for handling the updates, the state will get frozen again by the replicator.