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. Supported operators include;
  • Field Update Operators; $currentDate, $inc, $max, $min, $mul, $set, $unset.
  • Array Update Operators; $[], $[<identifier>], $addToSet, $pop, $pull, $pullAll, $push.
• Create selectors to observe a view of the state with full access to query language for reshaping data.
• Listen for changes in state view in order to react to updates.
• Restrict state notifications with conditions expressed as MongoDB queries.
• Automatically unsubscribes a listener if it throws an exception.
• Performs value equality using deep equal.
• React integration via createSelectorHook.

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.listen(view => {
  console.log("->", view);
});

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

// can also use selector.get() to obtain the value directly.
console.log(selector.get()); // {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

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

selector.get() // undefined

store.update({$set: {age: 25}})

// no second child yet.
selector.get() // {}

store.update({ $push: { children: "Adrian"} })

selector.get() // { secondChild: 'Adrian' }

React Integration

React >=18.0.0 is required to use this integration. The library expects it as a peer dependency.

import { createStore } from "adaka";
import { createSelectorHook } from "adaka/react"

// 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 Support

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

TODO

• Support schema validation

License

MIT

Changelog

0.0.0 / 2023-06-03

• Initial release.
• Support update operators with array filters;
  • $currentDate, $inc, $max, $min, $mul.
  • $[], $[<identifier>], $addToSet, $pop, $pull, $pullAll, $push.
  • $set, $unset.
• Support registering listeners to observe custom views of state.
• React integration via createSelectorHook.