adaka

adaka

High-precision state management using MongoDB query language.

Install

npm i adaka

Features

• Manage state as a single document modifiable only through the store API.
• Update state using MongoDB update query language.
• Use selectors to precisely observe specific data in state and subscribe to be notified only when they change.
• Subscribers are notified with a frozen immutable object.
• Restrict state notifications with conditions expressed as queries.
• Automatically unsubscribes a listener if it throws an exception.
• Performs value equality using deep equal.
• React integration via react-adaka.

Usage

Import the createStore function to get started.

import { createStore } from "adaka";

Create store and select some data.

type Person = { name: string; age: number; children?: string[] };

const store = createStore<Person>({
  name: "John",
  age: 30,
  children: ["Luke"]
});

// create a selector
const selector = store.select<{ name: string }>({ name: 1 });

// subcriber runs whenever name changes.
const unsubscribe = selector.subscribe(view => {
  console.log("->", view);
});

// first update
store.update({ $set: { name: "Amoah" } }); //output: '-> {name:"Amoah"}'

// can also use selector.getState() to obtain the value directly.
console.log(selector.getState()); // {name: "Amoah"}

// second update
store.update({ $set: { name: "Donkor" } }); //output: '-> {name:"Donkor"}'

// third update on different part of the state. subscriber is not notified.
store.update({ $push: { children: "Ama" } }); // no output

// remove subscriber by calling return method.
unsubscribe();

// subscriber no longer runs
store.update({ $set: { name: "Odame" } }); // no output

Select data only on condition

A selector may use a condition to restrict when listeners are notified. When a condition is used listeners are notified only once for when the condition is false with a return value of undefined. Further updates that do not meet the condition do not trigger anymore notifications. On the other hand, any update that meets the condition triggers a notification.

// store object.
// ------------
// {
//   name: "John",
//   age: 30,
//   children: ["Luke"]
// }

// second child if person under 30.
const selector = store.select<{ secondChild: string }>({
  secondChild: "$children.1"
}, {age: {$lt: 30}});

selector.subscribe(data => {
  console.log("->", data);
});

selector.getState() // undefined

store.update({$set: {age: 25}})
// no second child yet.
selector.getState() // {}

store.update({ $push: { children: "Adrian"} })
selector.getState() // { secondChild: 'Adrian' }. listeners notified.

store.update({ $set: { age: 35 } })
selector.getState() // undefined. listeners notified.

store.update({ $set: { age: 40 } })
selector.getState() // undefined. no notifications because condition is false.

React Integration

The react-adaka and React >=18.2.0 libraries are required to use this integration.

import { createStore, createSelectorHook } from "react-adaka"

// first create your store
const store = createStore({
  status: "error",
  errors: [
    { type:"api", message: "unknown error" }
  ],
});

// create a selector hook some where in global scope. need one per store.
const useSelector = createSelectorHook(store)

// use the hook inside your React component.
function ShowErrorTypes() {
  // select the types of errors only when the status is in "error".
  const { errorTypes } = useSelector({ errorTypes: "$errors.type" }, { status: "error"})

  return errorTypes ? <div>Issues found: {errorTypes.join("\n")} </div> : <div/>
}

MongoDB Query and Update Support

This package uses the mingo library for MongoDB query language support and loads only the basic supported query, projection, expression, and all update operators by default. Refer to the readme page for more information.

The mingo libray is added as a peer dependency to enable users to select only required operators using the context option so that tree-shaking can work effectively. Basic mingo operators are loaded into the global context by default.

TODO

• Support schema validation

License

MIT

Changelog

0.0.11 / 2024-03-22

New

• Add support for multiple update operations in single call.

Fixes

• Restore clone mode default to "copy".