@oddkin/state 0.0.0-stage → 1.0.0-beta.1

package/dist/prod/inspect/index.js

@@ -0,0 +1,45 @@
+import { OddkinError } from "@oddkin/core/diagnostics";
+import { INTERNALS, liveCounts } from "../store/store.js";
+function storeStats() {
+  return liveCounts();
+}
+function inspect(store, options) {
+  const internals = store[INTERNALS];
+  if (!internals)
+    throw new OddkinError("state.inspect.unsupported", "");
+  const limit = options?.limit ?? 50;
+  if (!Number.isInteger(limit) || limit < 0)
+    throw new OddkinError("state.inspect.limit", "");
+  const updates = [];
+  let recorded = 0, stopped = !1;
+  const stop = internals.observe({
+    update(record) {
+      recorded++, limit !== 0 && (updates.length === limit && updates.shift(), updates.push({ previous: record.previous, next: record.next, actions: record.actions }));
+    },
+    dispose() {
+      stopped = !0;
+    }
+  });
+  return {
+    store,
+    get updates() {
+      return [...updates];
+    },
+    get recorded() {
+      return recorded;
+    },
+    get subscribers() {
+      return internals.subscribers;
+    },
+    get stopped() {
+      return stopped || store.disposed;
+    },
+    dispose() {
+      stopped || (stopped = !0, stop());
+    }
+  };
+}
+export {
+  inspect,
+  storeStats
+};

package/dist/prod/internal/dev.js

@@ -0,0 +1,4 @@
+const DEV = !1;
+export {
+  DEV
+};

package/dist/prod/persist/index.js

@@ -0,0 +1,140 @@
+import { OddkinError, reportOddkinError } from "@oddkin/core/diagnostics";
+import { computed, signal } from "@oddkin/core/reactive";
+import { action } from "../store/store.js";
+const NOTHING = /* @__PURE__ */ Symbol("nothing written");
+function isEnvelope(value) {
+  if (typeof value != "object" || value === null || !("data" in value))
+    return !1;
+  const version = value.version;
+  return typeof version == "number" && Number.isInteger(version) && version >= 1;
+}
+function persist(store, options) {
+  const { key, version } = options;
+  if (typeof key != "string" || key === "" || !Number.isInteger(version) || version < 1)
+    throw new OddkinError("state.persist.options", "");
+  if (store.disposed)
+    throw new OddkinError("state.store.disposed", "");
+  const select = options.select ?? ((state) => state), restore = options.restore ?? ((_state, saved) => saved), equals = options.equals ?? Object.is, serialize = options.serialize ?? JSON.stringify, deserialize = options.deserialize ?? JSON.parse, status = signal("empty"), fail = (code, message, cause) => {
+    const error = new OddkinError(code, message, cause === void 0 ? void 0 : { cause });
+    if (!options.onError)
+      return reportOddkinError(error, { code, origin: key });
+    try {
+      options.onError(error);
+    } catch (handlerError) {
+      reportOddkinError(handlerError, { code, origin: key });
+    }
+  }, reject = (code, message, cause) => {
+    status.value = "rejected", fail(code, message, cause);
+  };
+  let storage;
+  try {
+    const source = options.storage ?? (() => globalThis.localStorage);
+    storage = (typeof source == "function" ? source() : source) ?? void 0, storage || fail("state.persist.unavailable", "");
+  } catch (error) {
+    storage = void 0, fail("state.persist.unavailable", "", error);
+  }
+  let text = null;
+  if (storage)
+    try {
+      text = storage.getItem(key);
+    } catch (error) {
+      storage = void 0, fail("state.persist.read", "", error);
+    }
+  storage || (status.value = "unavailable");
+  let blocked = !1;
+  if (storage && text !== null) {
+    let envelope, parsed = !0;
+    try {
+      envelope = deserialize(text);
+    } catch (error) {
+      parsed = !1, reject("state.persist.parse", "", error);
+    }
+    if (parsed && !isEnvelope(envelope))
+      reject("state.persist.parse", "");
+    else if (parsed && isEnvelope(envelope) && envelope.version > version)
+      blocked = !0, status.value = "blocked", fail("state.persist.version", "");
+    else if (parsed && isEnvelope(envelope)) {
+      let data = envelope.data, migrated = !0;
+      for (let next = envelope.version + 1; next <= version && migrated; next++) {
+        const step = options.migrate?.[next];
+        if (!step) {
+          migrated = !1, reject("state.persist.migrate", "");
+          break;
+        }
+        try {
+          data = step(data);
+        } catch (error) {
+          migrated = !1, reject("state.persist.migrate", "", error);
+        }
+      }
+      if (migrated) {
+        let valid = !0, cause;
+        try {
+          valid = options.validate ? options.validate(data) : !0;
+        } catch (error) {
+          valid = !1, cause = error;
+        }
+        if (valid)
+          try {
+            action("persist/restore", () => store.update((state) => restore(state, data)))(), status.value = "restored";
+          } catch (error) {
+            valid = !1, cause = error;
+          }
+        valid || reject("state.persist.invalid", "", cause);
+      }
+    }
+  }
+  let written = select(store.getSnapshot()), pending = !1, failing = !1, disposed = !1;
+  const write = () => {
+    if (pending = !1, !storage || blocked)
+      return;
+    const selection = select(store.getSnapshot());
+    if (written !== NOTHING && equals(written, selection))
+      return;
+    let serialized;
+    try {
+      serialized = serialize({ version, data: selection });
+    } catch (error) {
+      failing || fail("state.persist.serialize", "", error), failing = !0;
+      return;
+    }
+    try {
+      storage.setItem(key, serialized);
+    } catch (error) {
+      failing || fail("state.persist.write", "", error), failing = !0;
+      return;
+    }
+    failing = !1, written = selection;
+  }, unsubscribe = store.subscribe(() => {
+    pending || disposed || (pending = !0, queueMicrotask(() => {
+      pending && !disposed && write();
+    }));
+  });
+  return {
+    key,
+    status: computed(() => status.value),
+    get disposed() {
+      return disposed;
+    },
+    flush() {
+      disposed || write();
+    },
+    clear() {
+      if (!(disposed || !storage)) {
+        try {
+          storage.removeItem(key);
+        } catch (error) {
+          fail("state.persist.write", "", error);
+          return;
+        }
+        blocked = !1, written = NOTHING, status.value = "empty";
+      }
+    },
+    dispose() {
+      disposed || (pending && write(), disposed = !0, unsubscribe());
+    }
+  };
+}
+export {
+  persist
+};

package/dist/prod/store/index.js

@@ -0,0 +1,6 @@
+import { action, createStore, shallowEqual } from "./store.js";
+export {
+  action,
+  createStore,
+  shallowEqual
+};

package/dist/prod/store/store.js

@@ -0,0 +1,167 @@
+import { OddkinError } from "@oddkin/core/diagnostics";
+import { batch, computed, signal, untracked } from "@oddkin/core/reactive";
+const INTERNALS = /* @__PURE__ */ Symbol("oddkin.store.internals"), live = { stores: 0, subscriptions: 0 };
+function liveCounts() {
+  return { ...live };
+}
+const running = [], noop = () => {
+};
+function isPlainObject(value) {
+  const proto = Object.getPrototypeOf(value);
+  return proto === null || Object.getPrototypeOf(proto) === null;
+}
+function freezeSnapshot(root) {
+  const pending = [root];
+  for (; pending.length > 0; ) {
+    const value = pending.pop();
+    if (!(typeof value != "object" || value === null || Object.isFrozen(value))) {
+      if (Array.isArray(value)) {
+        Object.freeze(value);
+        for (let i = 0; i < value.length; i++)
+          pending.push(value[i]);
+      } else if (isPlainObject(value)) {
+        Object.freeze(value);
+        for (const key of Object.keys(value)) {
+          const descriptor = Object.getOwnPropertyDescriptor(value, key);
+          descriptor && "value" in descriptor && pending.push(descriptor.value);
+        }
+      }
+    }
+  }
+}
+class StoreImpl {
+  name;
+  state;
+  #value;
+  #initial;
+  #freeze;
+  #subscriptions = /* @__PURE__ */ new Set();
+  #observers;
+  #updates = 0;
+  #updating = !1;
+  #disposed = !1;
+  constructor(initial, options) {
+    this.name = options?.name, this.#freeze = options?.freeze ?? !0, this.#freeze && freezeSnapshot(initial), this.#initial = initial;
+    const named = this.name === void 0 ? void 0 : { name: this.name };
+    this.#value = signal(initial, named), this.state = computed(() => this.#value.value, named), live.stores++;
+  }
+  get disposed() {
+    return this.#disposed;
+  }
+  getSnapshot = () => this.#value.peek();
+  subscribe = (listener) => {
+    if (this.#disposed)
+      return noop;
+    const off = this.#value.subscribe(listener);
+    let active = !0;
+    const release = () => {
+      active && (active = !1, this.#subscriptions.delete(release), live.subscriptions--, off());
+    };
+    return this.#subscriptions.add(release), live.subscriptions++, release;
+  };
+  update(updater) {
+    this.#check("update");
+    const previous = this.#value.peek();
+    let next;
+    this.#updating = !0;
+    try {
+      next = untracked(() => updater(previous));
+    } finally {
+      this.#updating = !1;
+    }
+    this.#commit(previous, next);
+  }
+  select(selector, options) {
+    return computed(() => selector(this.#value.value), options);
+  }
+  reset() {
+    this.#check("reset"), this.#commit(this.#value.peek(), this.#initial);
+  }
+  dispose() {
+    if (this.#disposed)
+      return;
+    this.#disposed = !0, live.stores--;
+    for (const release of [...this.#subscriptions])
+      release();
+    const observers = this.#observers;
+    if (this.#observers = void 0, observers)
+      for (const observer of observers)
+        observer.dispose();
+  }
+  get [INTERNALS]() {
+    const store = this;
+    return {
+      get subscribers() {
+        return store.#subscriptions.size;
+      },
+      get updates() {
+        return store.#updates;
+      },
+      observe(observer) {
+        return store.#disposed ? (observer.dispose(), noop) : ((store.#observers ??= /* @__PURE__ */ new Set()).add(observer), () => {
+          store.#observers?.delete(observer);
+        });
+      }
+    };
+  }
+  #check(operation) {
+    if (this.#disposed)
+      throw new OddkinError("state.store.disposed", "");
+    if (this.#updating)
+      throw new OddkinError("state.update.reentrant", "");
+  }
+  #commit(previous, next) {
+    Object.is(previous, next) || (this.#freeze && freezeSnapshot(next), batch(() => {
+      this.#value.value = next, this.#updates++;
+      const observers = this.#observers;
+      if (!observers)
+        return;
+      const record = { previous, next, actions: [...running] };
+      for (const observer of [...observers])
+        observer.update(record);
+    }));
+  }
+}
+function createStore(initial, options) {
+  return new StoreImpl(initial, options);
+}
+function action(name, fn) {
+  return (...args) => {
+    running.push(name);
+    try {
+      return batch(() => fn(...args));
+    } finally {
+      running.pop();
+    }
+  };
+}
+function shallowEqual(a, b) {
+  if (Object.is(a, b))
+    return !0;
+  if (typeof a != "object" || typeof b != "object" || a === null || b === null)
+    return !1;
+  if (Array.isArray(a) || Array.isArray(b)) {
+    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length)
+      return !1;
+    for (let i = 0; i < a.length; i++)
+      if (!Object.is(a[i], b[i]))
+        return !1;
+    return !0;
+  }
+  if (!isPlainObject(a) || !isPlainObject(b))
+    return !1;
+  const keys = Object.keys(a);
+  if (keys.length !== Object.keys(b).length)
+    return !1;
+  for (const key of keys)
+    if (!Object.hasOwn(b, key) || !Object.is(a[key], b[key]))
+      return !1;
+  return !0;
+}
+export {
+  INTERNALS,
+  action,
+  createStore,
+  liveCounts,
+  shallowEqual
+};

package/dist/store/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * `@oddkin/state/store` — optional shared stores on Oddkin's reactive graph. DOM-free.
+ * Contract: docs/architecture/core-contracts.md §7.
+ */
+export { action, createStore, shallowEqual } from './store.js';
+export type { SelectOptions, Store, StoreOptions } from './store.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/store/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/store/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/D,YAAY,EAAE,aAAa,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC"}

package/dist/store/index.js

@@ -0,0 +1,6 @@
+/**
+ * `@oddkin/state/store` — optional shared stores on Oddkin's reactive graph. DOM-free.
+ * Contract: docs/architecture/core-contracts.md §7.
+ */
+export { action, createStore, shallowEqual } from './store.js';
+//# sourceMappingURL=index.js.map

package/dist/store/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/store/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC"}

package/dist/store/store.d.ts

@@ -0,0 +1,83 @@
+import { type ExternalSource, type ReactiveOptions, type Readable } from '@oddkin/core/reactive';
+export interface StoreOptions {
+    /** Name used in diagnostics and inspection. */
+    name?: string;
+    /**
+     * Freeze the plain objects and arrays of every snapshot, in development and production alike,
+     * so a mutation throws instead of going unnoticed. Default `true`. Class instances, maps, sets,
+     * dates, and other objects with their own prototype are never frozen.
+     */
+    freeze?: boolean;
+}
+/** Options for `select()`: `equals` decides whether a newly selected value is a change. */
+export type SelectOptions<S> = ReactiveOptions<S>;
+export interface Store<T> extends ExternalSource<T> {
+    readonly name: string | undefined;
+    /** The current snapshot as a read-only readable; `.value` in a tracked context registers a dependency. */
+    readonly state: Readable<T>;
+    /** True after `dispose()`. */
+    readonly disposed: boolean;
+    /** The current snapshot, the same value until the state changes. Bound, so it can be passed around. */
+    readonly getSnapshot: () => T;
+    /**
+     * Call `listener` with the new snapshot after each change: synchronously outside a batch, once at
+     * the outermost boundary inside one. Returns an unsubscribe function. Bound and stable.
+     */
+    readonly subscribe: (listener: (state: T) => void) => () => void;
+    /**
+     * Replace the snapshot with `updater(current)`. Returning the current snapshot is no change.
+     * The updater runs untracked and must not update this store itself.
+     */
+    update(updater: (state: T) => T): void;
+    /** A memoized readable of part of the state that notifies only when the selected value changes. */
+    select<S>(selector: (state: T) => S, options?: SelectOptions<S>): Readable<S>;
+    /** Return to the initial snapshot. */
+    reset(): void;
+    /** Release every subscription. Reads keep the last snapshot; updates throw. Idempotent. */
+    dispose(): void;
+}
+/** @internal One committed update, as `@oddkin/state/inspect` records it. */
+export interface UpdateRecord<T> {
+    readonly previous: T;
+    readonly next: T;
+    /** Names of the running actions, outermost first. */
+    readonly actions: readonly string[];
+}
+/** @internal Receives a store's updates and its disposal (`@oddkin/state/inspect`). */
+export interface StoreObserver<T> {
+    update(record: UpdateRecord<T>): void;
+    dispose(): void;
+}
+/** @internal Counters and update observation, reached through `store[INTERNALS]`. */
+export interface StoreInternals<T> {
+    readonly subscribers: number;
+    readonly updates: number;
+    observe(observer: StoreObserver<T>): () => void;
+}
+/** @internal Key of a store's {@link StoreInternals}. */
+export declare const INTERNALS: unique symbol;
+/** @internal Live stores (created, not disposed) and live `subscribe()` listeners. */
+export declare function liveCounts(): {
+    readonly stores: number;
+    readonly subscriptions: number;
+};
+/**
+ * Create a store holding `initial` as its first snapshot. Update it with `update()`, which takes the
+ * current snapshot and returns the next one; read it through `state`, `select()`, `getSnapshot()`,
+ * or `subscribe()`. No provider, registry, or reducer is needed.
+ */
+export declare function createStore<T>(initial: T, options?: StoreOptions): Store<T>;
+/**
+ * Name a unit of work for inspection. `fn` runs inside `batch()`, so subscribers are notified once
+ * when it returns, and every store update it makes records the name; nested actions record the
+ * whole chain. Batching is not a transaction: if `fn` throws, updates it already made stay. Only
+ * synchronous work belongs to the action; updates after an `await` do not.
+ */
+export declare function action<A extends unknown[], R>(name: string, fn: (...args: A) => R): (...args: A) => R;
+/**
+ * Equality for `select()` results built from several fields: the same value, or arrays or plain
+ * objects with the same entries compared with `Object.is`. Maps, sets, and class instances are
+ * equal only when identical.
+ */
+export declare function shallowEqual<V>(a: V, b: V): boolean;
+//# sourceMappingURL=store.d.ts.map

package/dist/store/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/store/store.ts"],"names":[],"mappings":"AAUA,OAAO,EAKL,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,QAAQ,EAEd,MAAM,uBAAuB,CAAC;AAE/B,MAAM,WAAW,YAAY;IAC3B,+CAA+C;IAC/C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,2FAA2F;AAC3F,MAAM,MAAM,aAAa,CAAC,CAAC,IAAI,eAAe,CAAC,CAAC,CAAC,CAAC;AAElD,MAAM,WAAW,KAAK,CAAC,CAAC,CAAE,SAAQ,cAAc,CAAC,CAAC,CAAC;IACjD,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,0GAA0G;IAC1G,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC;IAC5B,8BAA8B;IAC9B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,uGAAuG;IACvG,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,KAAK,MAAM,IAAI,CAAC;IACjE;;;OAGG;IACH,MAAM,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC;IACvC,mGAAmG;IACnG,MAAM,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;IAC9E,sCAAsC;IACtC,KAAK,IAAI,IAAI,CAAC;IACd,2FAA2F;IAC3F,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,6EAA6E;AAC7E,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IACjB,qDAAqD;IACrD,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED,uFAAuF;AACvF,MAAM,WAAW,aAAa,CAAC,CAAC;IAC9B,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IACtC,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,qFAAqF;AACrF,MAAM,WAAW,cAAc,CAAC,CAAC;IAC/B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,OAAO,CAAC,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI,CAAC;CACjD;AAED,yDAAyD;AACzD,eAAO,MAAM,SAAS,EAAE,OAAO,MAAyC,CAAC;AAIzE,sFAAsF;AACtF,wBAAgB,UAAU,IAAI;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;CAAE,CAExF;AAwKD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,KAAK,CAAC,CAAC,CAAC,CAE3E;AAED;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,CAAC,SAAS,OAAO,EAAE,EAAE,CAAC,EAC3C,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,CAAC,GACpB,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,CAAC,CASnB;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,OAAO,CAiBnD"}