Stores you declare, composed into trees, typed exactly as you wrote them.
primitive: one whole value.composite: named branches, each a store.collection: branches made by key, on first use.A kind is declared, never guessed. A branch is a store, so a part of your state has the same API as the whole. Reads return the type you gave, so brands, dates, class instances and interfaces come back as written. Portal does not copy or rewrite your values.
pnpm add @ibnlanre/portal
React 19 is a peer dependency (for $use and the hooks). Types ship with the
package.
import { collection, composite, primitive } from "@ibnlanre/portal";
const app = composite({
theme: primitive<"dark" | "light">("light"),
picked: primitive<null | string>(null),
user: composite({ name: "Taylor" }),
toggle() {
app.theme.$set((theme) => (theme === "light" ? "dark" : "light"));
},
});
app.user.name.$set("Jordan");
app.$get(); // { theme: "light", picked: null, user: { name: "Jordan" } }
const drafts = collection((id: string) =>
composite({ lines: primitive<string[]>([]) })
);
drafts("acme").lines.$set(["a"]);
In a component:
function Name() {
const [name, setName] = app.user.name.$use();
return <input value={name} onChange={(e) => setName(e.target.value)} />;
}
| Constructor | Meaning |
|---|---|
primitive<V>(initial \| () => V) |
One whole value. A write swaps it; reads return your reference. |
composite(shape) |
A tree. A store member is a branch, a function is a method, anything else (including a plain object) is a leaf. Write composite({ ... }) to branch an object. |
collection(make) |
drafts(key) makes an entry on first use; keys are strings. $has, $keys, $delete, $clear. |
Every store has $get, $use, $set, $subscribe, $reset, $dispose and
$onDispose. A store may be a branch of any number of composites, never copied. A write to a
composite writes each listed branch by that branch’s own rule; replace everything
with $reset() then $set(value).
Notification is synchronous, once per outermost write, to the written store, its
descendants and every composite connected to it.
batch(fn) is a top-level function: writes made inside it, to any stores, are one
outermost write, so each subscriber is called at most once, after fn returns.
Nested calls join the outer one. Replace everything with
batch(() => { cart.$reset(); cart.$set(next); }).
import { localAdapter, persist } from "@ibnlanre/portal";
const adapter = localAdapter<{ lines: string[] }>("draft", {
version: 1,
});
const persistor = persist(draft, adapter);
persist hydrates a store, writes later changes (never before hydration) and
follows other tabs and windows by default (local storage; sync: false opts out). asyncAdapter follows other tabs with watch: true. For a collection, give a function from key to
adapter. Adapters: local, session, cookie, browser (sync) and async, each with
version, migrate and validate. See the
persistence guide.
contextStore for stores scoped to a React provider.useAsync, useSync, useVersion.cookieStorage: direct, optionally signed, cookie access.The guides live in docs/content/docs: the store API,
reading and setting state, subscriptions, React integration, persistence and
cookie storage.
Issues and pull requests are welcome at github.com/ibnlanre/portal.
BSD-3-Clause.