Store and synchronization reference

The store works with data paths and detached snapshots. Its application facade exposes get, getSnapshot, set, update, on, and batch; administration, history, and synchronization operations belong to the host.

Choose the operation

Use set to replace data, update to compute it synchronously, and batch to validate several writes before performing the first. on delivers notifications in microtasks; tap observes each commit synchronously. hydrate replaces the root without adding ring buffer entries or passing through taps.

Values accept plain data, dense arrays, and codec scalars. Renderer objects, functions, Date, Map, cycles, and promises are not shared-state values. A bigint scalar supported by the store is not necessarily serializable by sync.

A session with an owner

import { wu } from 'wu-framework';

const sync = wu.store.sync({ transport: 'broadcast', room: 'catalog' });
await sync.ready();
wu.store.set('catalog.selectedId', 'p-42');
console.log(sync.status());
// Al terminar la sesión:
sync.stop();

Sync records only writes made after activation. Last Writer Wins ordering applies per path; concurrent parent and child writes do not offer the same convergence as writes to the same path. Keep granularity consistent and authenticate the transport where appropriate.

new WuStore

Creates an independent store with circular history.

new WuStore(bufferSize?: number): WuStore

• Parameters: bufferSize defaults to 256; selects history capacity, not a state byte limit.
• Returns: Instance; buffer size rounded to a power of two.
• Errors: Values written later are validated by the store codec.
• Permissions: Host only; unavailable in the application facade.
• Cleanup: state.dispose() removes sync, listeners, and taps.

import { WuStore } from 'wu-framework';
const state = new WuStore(512);

Reference: src/core/wu-store.js.

wu.store.tap

Observes each commit synchronously, before on notifications.

wu.store.tap(callback): () => void

• Parameters: callback(sequence,path,value); useful for a journal or transport.
• Returns: Cleanup; a non-function argument produces an empty cleanup function.
• Errors: Does not filter by path or deliver an initial snapshot.
• Permissions: Host only; unavailable in the application facade.
• Cleanup: stop() removes the tap.

const stop = wu.store.tap((sequence, path, value) => {
  console.log(sequence, path, value);
});

Reference: src/core/wu-store.js.

wu.store.hydrate

Replaces the entire state and notifies selected paths.

wu.store.hydrate(state, { notifyPaths? }?): void

• Parameters: state: plain object; notifyPaths defaults to the new state’s top-level keys.
• Returns: void; does not add ring buffer entries or trigger taps.
• Errors: WU_STORE_INVALID_VALUE or WU_STORE_INVALID_PATH before replacing state.
• Permissions: Host only; unavailable in the application facade.
• Cleanup: Creates no resources requiring release.

wu.store.hydrate({ cart: { count: 2 } }, { notifyPaths: ['cart.count'] });

Reference: src/core/wu-store.js.

wu.store.getMetrics

Reads counts for reads, writes, notifications, history, and listeners.

wu.store.getMetrics(): object

• Parameters: No arguments.
• Returns: Metrics snapshot.
• Errors: Does not measure network or rendering.
• Permissions: Host only; unavailable in the application facade.
• Cleanup: Creates no resources requiring release.

console.log(wu.store.getMetrics().listenerCount);

Reference: src/core/wu-store.js.

wu.store.getRecentEvents

Queries recent writes with sequence, path, value, and timestamp.

wu.store.getRecentEvents(count?: number): object[]

• Parameters: Finite positive count, default 10, capped by the buffer.
• Returns: List with newest first; values detached from internal state.
• Errors: Nonpositive or nonfinite values return [].
• Permissions: Host only; unavailable in the application facade.
• Cleanup: Creates no resources requiring release.

console.table(wu.store.getRecentEvents(10));

Runtime method not listed in the WuStore declaration.

Reference: src/core/wu-store.js.

wu.store.reset

Clears state and history while keeping subscriptions and taps.

wu.store.reset(): void

• Parameters: No arguments.
• Returns: void.
• Errors: Does not constitute persistent deletion outside this instance.
• Permissions: Host only; unavailable in the application facade.
• Cleanup: Does not automatically notify an empty initial value; sync remains active.

wu.store.reset();

Reference: src/core/wu-store.js.

wu.store.dispose

Stops sync and removes state, listeners, and taps.

wu.store.dispose(): void

• Parameters: No arguments.
• Returns: void.
• Errors: Does not constitute persistent deletion outside this instance.
• Permissions: Host only; unavailable in the application facade.
• Cleanup: Use when removing a store you manage; not on a store shared by another consumer.

wu.store.dispose();

Reference: src/core/wu-store.js.

wu.store.clear

Performs the same complete release as dispose.

wu.store.clear(): void

• Parameters: No arguments.
• Returns: void.
• Errors: Does not constitute persistent deletion outside this instance.
• Permissions: Host only; unavailable in the application facade.
• Cleanup: Also removes subscriptions; it does more than operate on values.

wu.store.clear();

Reference: src/core/wu-store.js.

WuSyncHandle.ready

Waits for the module to load and the transport to start.

sync.ready(): Promise<unknown>

• Parameters: Handle returned by wu.store.sync(options).
• Returns: Promise
• Errors: ready may reject; status.error exposes loading/authorization/transport errors.
• Permissions: Host session; the relay must authenticate peers when using WebSocket.
• Cleanup: stop() cancels the session when its owner finishes.

await sync.ready();

Reference: src/core/wu-store.js.

WuSyncHandle.status

Queries connection, clocks, peers, and synchronization counters.

sync.status(): WuSyncStatus

• Parameters: Handle returned by wu.store.sync(options).
• Returns: WuSyncStatus
• Errors: ready may reject; status.error exposes loading/authorization/transport errors.
• Permissions: Host session; the relay must authenticate peers when using WebSocket.
• Cleanup: Read operation without additional resources.

console.log(sync.status());

Reference: src/core/wu-store.js.

WuSyncHandle.stop

Stops message exchange and write observation.

sync.stop(): void

• Parameters: Handle returned by wu.store.sync(options).
• Returns: void
• Errors: ready may reject; status.error exposes loading/authorization/transport errors.
• Permissions: Host session; the relay must authenticate peers when using WebSocket.
• Cleanup: Removes the tap and closes this session’s transport.

sync.stop();

Reference: src/core/wu-store.js.

WuSyncHandle.connected

Checks whether the session transport is connected.

sync.connected: boolean

• Parameters: Handle returned by wu.store.sync(options).
• Returns: boolean
• Errors: ready may reject; status.error exposes loading/authorization/transport errors.
• Permissions: Host session; the relay must authenticate peers when using WebSocket.
• Cleanup: State read; release the session with stop.

console.log(sync.connected);

Reference: src/core/wu-store.js.