Observable state
Own object, array, or Map state with synchronous change notifications, deep mutation observation, and optional whole-state runtime validation.
import {Model} from 'white-label-model';const {Model} = require('white-label-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.on('change', state => console.log(state));
profile.update({name: 'Grace'});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}); // falseNested objects, arrays, and Maps are proxied lazily as accessed. Direct writes emit change and a mutate event containing operation, path, oldValue, newValue, and the complete current state.
Writes using __proto__, constructor, or prototype are rejected to avoid prototype-pollution paths.
model.on('mutate', mutation => {
console.log(mutation.path);
});
model.get().user.preferences.theme = 'dark';Accepted non-silent explicit mutations emit change first, followed by the matching operation event: set, update, push, delete, or clear.
Assign name and an EventEmitter-compatible mediator to relay local events as model:<name>:<event>. The package does not import Mediator directly.
new Model(data?, validator?)Create an observable root state container.
| Parameter | Type | Default | Description |
|---|---|---|---|
data | object | unknown[] | Map | — | Initial root state; defaults to {}. |
validator | (state: unknown) => boolean | — | Optional whole-state runtime acceptance check. |
initialize()Start the lifecycle for chaining and composition.
get() / get(key)Read the complete observable root or one object property, array index, or Map entry.
| Parameter | Type | Default | Description |
|---|---|---|---|
key | unknown | — | Optional property/index/Map key. |
set(data, silent?)Replace the complete root state with another supported root shape.
| Parameter | Type | Default | Description |
|---|---|---|---|
data | unknown | — | Replacement root state. |
silent | boolean | false | Suppress change/set events when true. |
update(partial, silent?) / update(key, value, silent?)Shallow-merge an object root or replace/shallow-merge one existing array or Map member.
| Parameter | Type | Default | Description |
|---|---|---|---|
partial | object | — | Fields merged into an object root. |
key | unknown | — | Existing array index or Map key. |
value | unknown | — | Replacement or shallow-merge value. |
silent | boolean | false | Suppress emitted events. |
push(valueOrValues, silent?) / push(key, value, silent?)Append array values or insert Map entries.
| Parameter | Type | Default | Description |
|---|---|---|---|
valueOrValues | unknown | unknown[] | — | Value or values appended to an array root. |
key | unknown | — | Map key. |
value | unknown | — | Map value. |
delete(key, silent?)Delete one object property, array index, or Map entry.
| Parameter | Type | Default | Description |
|---|---|---|---|
key | PropertyKey | number | unknown | — | Member to remove. |
silent | boolean | false | Suppress emitted events. |
clear(silent?)Reset the root to an empty value of the same shape.
destroy()Clear state silently and release listeners.
These methods are publicly declared today but are not part of the recommended state-management workflow. They are documented here so the reference matches the shipped API exactly.
serviceGet()Compatibility placeholder; performs no I/O in the current implementation.
servicePatch()Compatibility placeholder; performs no I/O in the current implementation.
servicePost()Compatibility placeholder; performs no I/O in the current implementation.
servicePut()Compatibility placeholder; performs no I/O in the current implementation.
Model currently inherits these public utility methods. Application code normally does not need them for ordinary Model usage.
isMap(value)Return whether a value is a native Map, including cross-realm Maps.
isFinite(value)Accept finite numeric values without coercion.
isPlainObject(value)Return whether a value is an ordinary or null-prototype object rather than a class instance.
pullAt(array, index)Remove one array member in place.
extend(object1, object2)Create a safe shallow merge while blocking prototype-pollution keys.
message(messages, data)Emit local events and optional namespaced mediator events.
Model<T> describes the supported root state and provides typed get() root access.
TypeScript does not validate runtime data; add the optional validator when an external trust boundary needs enforcement.
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.
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.