maraj v2.10.0

Maraj

A fast lightweight utility for creating immutable updates. Fully typed. Only 600 bytes gziped. Includes usefull utilities for manipulating updates (like remove, select).

Features

• Update and ExtendableUpdate.
• Usefull utilities like "remove", "select".
• Full typescript support.
• Correct type inference.
• Multiple and concurrent updates.
• Nested functional updates.

For Typescript: in tsconfig.json set "strictNullChecks" and "noUncheckedIndexedAccess" to true to be able to infer correctly the type of optional properties and properties with posible undefined value. ( { key?: ... } is not equal to { key: ... | undefined } )

const originalValue = { name: 'one', lastname: 'two' modified: false, files: [{ filename: 'one' }] }

const updatedValue = update(orignalValue, {
   'name': 'updated',
   'modified': (value, fullObject) => !value,
   'files.0.filename': 'zero',
})
// updatedValue = { name: 'updated', lastname: 'two' modified: true, files: [{ filename: 'zero' }] }
originalValue.files[1] === updatedValue.files[1] // true

const newValue = extendableUpdate(orignalValue, {
   'newProp': 'new',
   'data.0.name': 'dataName'
})
// updatedValue = { ... , newProp: 'new', data: [{ name: 'dataName' }] }
originalValue.files[1] === newValue.files[1] // true

Limitations

• Can work with keys containing dots ({ "this.is.dotted.key": 123 }), however those keys (keys containing dots) must exist in the object beforehand (hasOwnProperty) and also must have a non-literal-object/array value to behave properly; like primitives, sets, maps, and so on. For example the path "a.b.c.d" will work properly in the following scenarios:

  • { "a.b.c.d": ... }
  • { a: { "b.c.d": ... } }
  • { a: { b: {"c.d": ... } } }
  • { a: { b: {"c": { d: ... } } } }

  It can still work with dot-paths keys containing an object or array, however the paths targeting nested properties in this key are forbiden. For example having the following object { a: { "b.c": { d: ... } } } you can use the path "a" and "a.b.c", but you cant use "a.b.c.d", this path will create a new property "b" inside "a", then "c" and lastly "d" resulting in the following object { a: { "b.c": { d: ... } }, b: { c: { d: ... } } }

• In "extendableUpdate", numbers inside path will always create a mutable array if the array/object doesnt exist beforehand. If you want an object/tuple/readonlyArray instead of an array, add it beforehand as type.

const updatedValue = extendableUpdate({}, {
   'files.1.name': 'new name',
})
// The "files" prop is an array. updatedValue = { files: [<empty>, { name: 'new name' }] }

// To get an object instead of an array create an object beforehand
const updatedValue2 = extendableUpdate({}, {
   'files': {}, // add an object first, so then i can add props as numbers after it
   'files.1.name': 'new name',
})
// updatedValue2 = { files: { '1': { name: 'new name' } } }

• The type "UpdateObject" (the type of the object provided containing the updates, used as second parameter in the update function) if used to create new update objects using computed properties in a inline syntax { key: value } will always throw a ts error even if the typing is correct, use the second syntax.

const updateFieldStore = <T, TPath extends DotPaths<T>>(
   state: T,
   path: TPath,
   newValue: UpdateValue<T, TPath>
) => {
   // ts error even if the typing is correct (typescript issue)
   const updateObject1: UpdateObject<T> = {
      [path]: newValue
   }

   // All good, no ts error
   const updateObject2: UpdateObject<T> = {}
   updateObject[path] = newValue
   
}

• Use the "set" utility if typescript doesn't infer properly "an optional field" vs a "field which can have 'undefined' as type". Usually happens in nested props inside arrays.

const updatedValue = update(data, {
   'files.0.nonOptionalProperty': 'new name',
   'files.1.nonOptionalProperty': undefined, //no ts error
   'files.0.nonOptionalProperty': set('new name'),
   'files.1.nonOptionalProperty': set(undefined), //throws ts error, undefined cant be a value.
})

Creating a Strict Immutable Update

Arguments:

• Original Object
• Update Object
• Options (to change JS behaviour on non existing props and indexes)
  • 'add': Adds non existing property/index.
  • 'skip': Skips the update in the non-existing prop/index and still applies the rest of the possible updates.
  • 'throw': Throws a JS error, usefull working with indexes making sure there are no "empty" indexes created if a new index is added which is bigger than the length of the current array.

Example

import { update } from "maraj";

const data = {
    profile: { name: "Lukasz" },
    works: ["soum", "fi"],
    history: [
        { title: "soum", size: 90, available: true, info: ["info1"] },
        { title: "fi", size: 30, available: false, info: ["infoA"] },
    ]
}

const newUpdatedObject = update(data, {
    "profile.name": "Lucas", //update values
    "works.1": "gs", //nested array update
    "history.1.available": (currentValue) => (!currentValue), //functional update
    "works": (v) => [...v, 'portfolio'] //add new value to array
})

Creating an Immutable Update allowing new props to be added

Arguments:

• Original Object
• Update Object

Example

import { extendableUpdate } from "maraj";

const data = {
    profile: { name: "Lukasz" },
    works: ["soum", "fi"],
    history: [
        { title: "soum", size: 90, available: true, info: ["info1"] },
        { title: "fi", size: 30, available: false, info: ["infoA"] },
    ]
}

const newUpdatedObject = extendableUpdate(data, {
    "profile.age": 28, //add new property
    "profile.name": "Lucas", //update values
    "works.10": "gs", //increases the array (filling it up with empty/undefined) and sets the value in the index of 10 to "gs"
})

Remove Utility

Removes the key of an object or the index of an array in the key provided in the update.

import {remove} from 'maraj'

const newUpdatedObject = update(person,{
    'profile': (value) => remove(value, 'name'), // returns new value without the "name" prop
    'profile': (value) => remove(value, ['name', 'lastname']), // returns new value without the "name" and "lastname" prop
    'works': (value) => remove(value, 1), // returns new array without the provided index (1)
    'works': (value) => remove(value, [1, "0"]), // returns new array without the provided index "0" and "1"
})

Select Utility

Selects the value of an object/array from a string-dot-path. Usefull in state management libraries.

import {select} from 'maraj'

const stringPath = 'works.1.size'

const work1SizeSelector = (state) => select(state, stringPath) // will behave as (store) => store[works][1][size]

SplitPathAtLastKey Utility

Usefull when you want to retrieve the last key (for example an id).

Splits string path (example:'projects.1.data.size' ) into two:

• remainingPath: the remaining path (in this case 'projects.1.data')
• lastKey: the last key in the path (in this case 'size')

import { splitPathAtLastKey } from 'maraj'

const stringPath = 'works.1.size'

const [remainingPath, lastKey] = splitPathAtLastKey(stringPath)
// lastKey = 'size'
// remainingPath = 'works.1'

Set Utility

In some unusual cases (usually when updating an optional object prop inside an array) typescript infers incorrectly the optional key vs a key with undefined value. To fix this typing issue, use the "set" function so it correctly infers the type in the field.

const updatedValue = update(data, {
   'files.0.optionalProperty': 'new name',
   'files.1.optionalProperty': undefined, //no ts error
   'files.0.optionalProperty': set('new name'),
   'files.1.optionalProperty': set(undefined), //throws ts error, undefined cant be a value.
})