@r146023/omniturbo

v0.1.1

Published

14 days ago

A framework-agnostic governed path-state engine with schemas, datatypes, privacy, aliases, history, and subscriptions.

Downloads

268

0High
0Medium
0Low

r146023

state store path schema validation typescript

OmniTurbo

Governed path-state for TypeScript apps.

OmniTurbo is a path-first state store that can be used in two ways:

as a loose in-memory value bag, or
as a governed in-memory path database with schemas, datatypes, privacy, structured results, subscriptions, alerts, coercers, batch initialization, and history.

The core design goal is:

Freedom by default. Guarantees by request.

Use OmniTurbo when state is more than temporary UI state — when paths represent metadata, plugin settings, schema definitions, form values, editor entities, or other application-critical data that should be validated before it becomes observable state.

Why OmniTurbo?

Most state stores let anything write anything:

store.set("entities.node_1.meta.width", "banana");

That is fine for loose state, but it is dangerous when the value represents governed application metadata.

OmniTurbo lets important paths define rules:

omni.schema("entities.*.meta.width", {
  type: "number",
  min: 1,
  max: 5000,
  coerce: true,
});

omni.set("entities.node_1.meta.width", "250");    // accepted, stores 250
omni.set("entities.node_1.meta.width", "banana"); // rejected, old value remains

If validation fails, the value is not committed and side effects do not fire.

Core guarantee

When a path is governed by schema or privacy and a write fails, OmniTurbo should not:

update the stored value,
trigger subscriptions,
trigger alerts,
resolve waiters,
add false successful state to the timeline.

Invalid state should not become observable state.

Install

npm install @r146023/omniturbo

Quick start

import { Omni } from "omniturbo";

const omni = new Omni();

const result = omni.set("settings.theme", "dark");

if (result.success) {
  console.log(omni.get("settings.theme")); // "dark"
}

set() and setObj() return OmniResult objects instead of booleans. This is deliberate: once a write can be coerced, rejected, privacy-blocked, or partially applied, a boolean is not enough information.

const result = omni.set("settings.zoom", "1.25", {
  schema: { type: "number", min: 0.1, max: 4 },
});

console.log(result.success); // true
console.log(result.value);   // 1.25

Governed paths

Schemas can be registered by exact path or wildcard path.

omni.schema("entities.*.meta", {
  type: "object",
  children: {
    width: {
      type: "number",
      min: 1,
      max: 5000,
      coerce: true,
    },
    height: {
      type: "number",
      min: 1,
      max: 5000,
      coerce: true,
    },
    label: {
      type: "string",
      maxLength: 120,
      coerce: true,
    },
    locked: {
      type: "boolean",
      coerce: true,
    },
  },
});

omni.set("entities.node_1.meta.width", "250"); // accepted
omni.set("entities.node_1.meta.width", "bad"); // rejected

Private paths

Private paths can only be updated through the setter returned when the private path is created.

const created = omni.set("entities.node_1.meta.locked", false, {
  privateSet: true,
  owner: "AmberNode:node_1",
});

omni.set("entities.node_1.meta.locked", true); // rejected

created.setter?.(true); // accepted

Private setters can also write child paths:

const meta = omni.setObj(
  { width: 100, height: 80, label: "Node" },
  "entities.node_1.meta",
  { privateSet: true, owner: "AmberNode:node_1" }
);

meta.setter?.("width", 250);   // accepted
omni.set("entities.node_1.meta.width", 300); // rejected

Batch initialization

Batching is intended for initialization and bulk loading. It lets an app load a large state tree without firing thousands of startup-time subscriptions.

omni.batch(() => {
  omni.set("settings.theme", "dark");
  omni.set("settings.zoom", 1);
  omni.set("session.ready", true);
});

By default, batch commits values but suppresses per-path subscriptions and alerts during initialization.

Subscriptions

const unsubscribe = omni.subscribe("settings.theme", (path, value, oldValue) => {
  console.log(path, value, oldValue);
});

omni.set("settings.theme", "light");

unsubscribe();

Tree subscriptions can watch descendants:

omni.subscribeTree("entities.node_1.meta", (root, changedPath, value) => {
  console.log(`${changedPath} changed under ${root}`);
});

Useful for

OmniTurbo is most useful for applications where state needs structure and guarantees:

visual editors
plugin-driven apps
form engines
schema-driven UIs
internal tool builders
metadata-heavy apps
local-first apps
desktop apps
diagram/canvas editors
generated app systems

It is probably overkill for simple UI flags like isDropdownOpen.

What changed in the modular Omni

The old single-file OmniTurbo was refactored into a modular project structure:

omniturbo/
  src/
    index.ts
    Omni.ts
    core/
    types/
    result/
    datatypes/
    schema/
    privacy/
    aliases/
    subscriptions/
    history/
    batch/
  tests/
  docs/

The most important API change is that set() and setObj() now return OmniResult objects instead of booleans.

Documentation map

Getting started

Concepts

API

Schemas and datatypes

Privacy

Side effects, batch, and history

Recipes

Amber integration

Testing and internals

Status

OmniTurbo is currently pre-1.0.

The core direction is stable, but schema, privacy, datatype, and result APIs may evolve as the library is battle-tested in real applications.

Recommended versioning:

0.1.x = experimental / early adopters
0.2.x = API cleanup and adapters
0.3.x = Amber integration proof
1.0.0 = stable public API