modify-via-query
Mutate a copy of data without changing the original source with natural and type-safe query.
Why use this library?
This is for users that are sick of updating large states. For example:
setState;
With this library, the code above can be simplified as:
setState modifystate .book .author .nickNames .$set"new name" ;
How to install?
Node.js
npm install modify-via-query --save
Deno
;
Comparison with immutability-helper
Using immutability-helper, taken from this issue:
updatestate, ;
Using modify-via-query:
modifystate .objects .relationships .data .$applystate
Features
- Type-safe
- Autocomplete via Intellisense
- Chainable
- Immutable
- Shallow copy
Main concept
Like the name of this package, you modify by querying the property.
The modify
function make the object modifiable. A modifiable object comes with a few commands like $set
and $apply
.
Basically, the commands can be access in any hierarchy of the object, and once the command is invoked, an updated modifiable object will be returned, such that more modifications can be chained.
Examples
Modify object
modifystate.x.$set3 // {x: 3}
Modify array item
modifystate.$set3 // [3, 2]
Modify nested object array
modifystate.todos.done.$apply!done// {todos: [{content: "code", done: true}, {content: "sleep", done: false}]}
Chaining commands
modifystate .name.$applyname + " " + "squarepants" .job.at.$set"Krabby Patty"// { name: "spongebob squarepants", job: {title: "chef", at: "Krabby Patty"} }
Removing array item
modifystate.filterindex !== 2 // ["a", "b"]
Modify property of optional object
For example, if you have the following state:
Let say you want to update pet.age
, you cannot do this:
modifystate.pet.age.$set9state
You will get compile-error by doing so. The is prohibited in order to maintain the type consistency, else the resulting value would be {pet: {age: 9}}
, which breaks the type of state
, because name
should be present.
To fix this, you have to provide a default value for pet
using the $default
command:
modifystate.pet.$default.age.$set9state
This tells the library that if pet
is undefined, then its name will be "bibi"
otherwise the original name will be used.
Available commands
$set
- to set the value of the queried property
$apply
- to update the value of the queried property based on its previous value
$default
- to provide a default value if the queried property is a nullable object
Usage with React
Function components (useState hook)
Class components
Redux reducers
Can I use this library in non-React projects?
Yes. Although this library is primarily for users who uses React users, this package can actually be used anywhere since it has zero dependency.
Can I use this library with Typescript?
Yes! In fact the default package already contain the type definitions, so you don't have to install it somewhere else.
How this library works?
It works by using Proxy
Overloads
The modify
function is overloaded with two signatures. If you are using React, the first variant will be more convenient. Note that both of the variants can be curried.
// Update -> State -> Statemodify:State; // State -> Update -> Statemodify:State;
References
This library is inspired by: