white-label-model

Install and requirements

• Node.js ^22.18.0 or >=24.11.0
• npm, Yarn, or pnpm for installation
• Native EventTarget, CustomEvent, AbortController, and AbortSignal.any support
• Native Proxy support
• Native Map support when using Map state

import {Model} from 'white-label-model';

const {Model} = require('white-label-model');

State model

Model accepts a plain object, array, or Map as its root state. Mutations are synchronous: when a mutating call returns, accepted state is already visible through get() and listeners have already run.

Object update() operations are shallow merges. Array and Map update() operations address one existing member. clear() keeps the current root shape.

const profile = new Model({name: 'Ada'});
profile.addEventListener('change', event => console.log(event.detail));
profile.update({name: 'Grace'});

Runtime validation

The validator is optional. It receives the complete proposed state before construction or an explicit set/update/push/delete mutation is committed. Return true to accept and false to reject.

TypeScript checks source code at development time; the validator checks actual runtime values. Direct nested writes through get() are observable but do not invoke the whole-state validator. clear() and destroy() intentionally bypass it so cleanup cannot be blocked.

const user = new Model({name: 'Ada'}, value =>
    typeof value === 'object' && value !== null &&
    typeof value.name === 'string'
);

user.set({name: 'Grace'}); // true
user.set({name: 42});      // false

Deep observation

Nested objects, arrays, and Maps are proxied lazily as accessed. Direct writes dispatch change and a mutate CustomEvent whose detail contains operation, path, oldValue, newValue, and the complete current state.

Writes using __proto__, constructor, or prototype are rejected to avoid prototype-pollution paths. A proxy retained from a replaced or cleared root can still mutate that detached object, but it no longer publishes Model events for the current root. If a retained proxy becomes stale only because its object moved to a new array index or remains reachable through another live alias, later mutations publish using a current path; truly detached objects remain silent.

model.addEventListener('mutate', event => {
    console.log(event.detail.path);
});
model.get().user.preferences.theme = 'dark';

Events and mediator integration

Accepted non-silent explicit mutations dispatch change first, followed by the matching operation CustomEvent: set, update, push, delete, or clear. Payloads are carried in CustomEvent.detail.

Model uses the native EventTarget listener contract for local events. Assign name and an EventTarget-compatible mediator to relay local events as model:<name>:<event>; the original payload is carried in CustomEvent.detail at both boundaries. The package does not import Mediator directly.

Serverless and request-scoped state

Create mutable Model instances per request or invocation unless shared process-wide state is explicitly intended. Serverless hosts can reuse a warm process, so module-level mutable state can leak data between requests.

Keep persistence outside Model. Load data from the application-owned database, cache, API, or storage layer, validate it at the trust boundary when needed, apply it to the request Model, then discard or destroy that request-owned state.

Related guides

Focused guides for common implementation questions around this package.

• TypeScript state management without React

TypeScript

Model<T> describes the supported root state and narrows known Model event CustomEvent.detail values.

TypeScript does not validate runtime data; add the optional validator when an external trust boundary needs enforcement.

Security and trust boundaries

Prototype-pollution keys are blocked from direct object writes and safe merge paths.

Validate API, storage, decoded JSON, or user-controlled data before treating it as trusted application state.

Design boundaries

Model does not own rendering, routing, networking, persistence, or application-wide event orchestration.

Resolve asynchronous I/O first, then apply the result with a synchronous Model mutation.