@pyreon/state-tree 0.0.1

package/src/devtools.ts

@@ -0,0 +1,87 @@
+/**
+ * @pyreon/state-tree devtools introspection API.
+ * Import: `import { ... } from "@pyreon/state-tree/devtools"`
+ */
+
+import { getSnapshot } from './snapshot'
+
+// Track active model instances (devtools-only, opt-in)
+const _activeModels = new Map<string, WeakRef<object>>()
+const _listeners = new Set<() => void>()
+
+function _notify(): void {
+  for (const listener of _listeners) listener()
+}
+
+/**
+ * Register a model instance for devtools inspection.
+ * Call this when creating instances you want visible in devtools.
+ *
+ * @example
+ * const counter = Counter.create()
+ * registerInstance("app-counter", counter)
+ */
+export function registerInstance(name: string, instance: object): void {
+  _activeModels.set(name, new WeakRef(instance))
+  _notify()
+}
+
+/**
+ * Unregister a model instance.
+ */
+export function unregisterInstance(name: string): void {
+  _activeModels.delete(name)
+  _notify()
+}
+
+/**
+ * Get all registered model instance names.
+ * Automatically cleans up garbage-collected instances.
+ */
+export function getActiveModels(): string[] {
+  for (const [name, ref] of _activeModels) {
+    if (ref.deref() === undefined) _activeModels.delete(name)
+  }
+  return [..._activeModels.keys()]
+}
+
+/**
+ * Get a model instance by name (or undefined if GC'd or not registered).
+ */
+export function getModelInstance(name: string): object | undefined {
+  const ref = _activeModels.get(name)
+  if (!ref) return undefined
+  const instance = ref.deref()
+  if (!instance) {
+    _activeModels.delete(name)
+    return undefined
+  }
+  return instance
+}
+
+/**
+ * Get a snapshot of a registered model instance.
+ */
+export function getModelSnapshot(
+  name: string,
+): Record<string, unknown> | undefined {
+  const instance = getModelInstance(name)
+  if (!instance) return undefined
+  return getSnapshot(instance)
+}
+
+/**
+ * Subscribe to model registry changes. Returns unsubscribe function.
+ */
+export function onModelChange(listener: () => void): () => void {
+  _listeners.add(listener)
+  return () => {
+    _listeners.delete(listener)
+  }
+}
+
+/** @internal — reset devtools registry (for tests). */
+export function _resetDevtools(): void {
+  _activeModels.clear()
+  _listeners.clear()
+}

package/src/index.ts

@@ -0,0 +1,29 @@
+// ─── Core ─────────────────────────────────────────────────────────────────────
+
+export type { ModelDefinition } from './model'
+export { model, resetHook, resetAllHooks } from './model'
+
+// ─── Snapshot ─────────────────────────────────────────────────────────────────
+
+export { applySnapshot, getSnapshot } from './snapshot'
+
+// ─── Patches ─────────────────────────────────────────────────────────────────
+
+export { onPatch, applyPatch } from './patch'
+
+// ─── Middleware ───────────────────────────────────────────────────────────────
+
+export { addMiddleware } from './middleware'
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export type {
+  ActionCall,
+  MiddlewareFn,
+  ModelInstance,
+  ModelSelf,
+  Patch,
+  PatchListener,
+  Snapshot,
+  StateShape,
+} from './types'

package/src/instance.ts

@@ -0,0 +1,128 @@
+import type { Computed, Signal } from '@pyreon/reactivity'
+import { signal } from '@pyreon/reactivity'
+import { runAction } from './middleware'
+import { onPatch, trackedSignal } from './patch'
+import { instanceMeta } from './registry'
+import type { InstanceMeta, ModelInstance, Snapshot, StateShape } from './types'
+import { MODEL_BRAND } from './types'
+
+// ─── Model definition detection ───────────────────────────────────────────────
+
+interface AnyModelDef {
+  readonly [MODEL_BRAND]: true
+  readonly _config: ModelConfig<
+    StateShape,
+    Record<string, (...args: unknown[]) => unknown>,
+    Record<string, Signal<unknown>>
+  >
+}
+
+function isModelDef(v: unknown): v is AnyModelDef {
+  if (v == null || typeof v !== 'object') return false
+  return (v as Record<string, unknown>)[MODEL_BRAND] === true
+}
+
+// ─── Config shape ─────────────────────────────────────────────────────────────
+
+export interface ModelConfig<TState extends StateShape, TActions, TViews> {
+  state: TState
+  views?: (self: any) => TViews
+  actions?: (self: any) => TActions
+}
+
+// ─── createInstance ───────────────────────────────────────────────────────────
+
+/**
+ * Create a live model instance from a config + optional initial snapshot.
+ * Called by `ModelDefinition.create()`.
+ */
+export function createInstance<
+  TState extends StateShape,
+  TActions extends Record<string, (...args: any[]) => any>,
+  TViews extends Record<string, Signal<any> | Computed<any>>,
+>(
+  config: ModelConfig<TState, TActions, TViews>,
+  initial: Partial<Snapshot<TState>>,
+): ModelInstance<TState, TActions, TViews> {
+  // Raw object that will become the instance.
+  const instance: Record<string, unknown> = {}
+
+  // Metadata for this instance.
+  const meta: InstanceMeta = {
+    stateKeys: [],
+    patchListeners: new Set(),
+    middlewares: [],
+    emitPatch(patch) {
+      // Guard avoids iterating an empty Set on the hot signal-write path.
+      if (this.patchListeners.size === 0) return
+      for (const listener of this.patchListeners) listener(patch)
+    },
+  }
+  instanceMeta.set(instance, meta)
+
+  // `self` is a live proxy so that actions/views always see the final
+  // (fully-populated) instance — including wrapped actions added later.
+  const self = new Proxy(instance, {
+    get(_, k) {
+      return instance[k as string]
+    },
+  })
+
+  // ── 1. State signals ──────────────────────────────────────────────────────
+  for (const [key, defaultValue] of Object.entries(config.state)) {
+    meta.stateKeys.push(key)
+    const path = `/${key}`
+    const initValue: unknown =
+      key in initial ? (initial as Record<string, unknown>)[key] : undefined
+
+    let rawSig: Signal<unknown>
+
+    if (isModelDef(defaultValue)) {
+      // Nested model — create its instance from the supplied snapshot (or defaults).
+      const nestedInstance = createInstance(
+        defaultValue._config,
+        (initValue as Record<string, unknown>) ?? {},
+      )
+      rawSig = signal(nestedInstance)
+
+      // Propagate nested patches upward with the key as path prefix.
+      onPatch(nestedInstance, (patch) => {
+        meta.emitPatch({ ...patch, path: path + patch.path })
+      })
+    } else {
+      rawSig = signal(initValue !== undefined ? initValue : defaultValue)
+    }
+
+    const tracked = trackedSignal(
+      rawSig,
+      path,
+      (p) => meta.emitPatch(p),
+      () => meta.patchListeners.size > 0,
+    )
+    instance[key] = tracked
+  }
+
+  // ── 2. Views ──────────────────────────────────────────────────────────────
+  if (config.views) {
+    const views = config.views(self)
+    for (const [key, view] of Object.entries(
+      views as Record<string, unknown>,
+    )) {
+      instance[key] = view
+    }
+  }
+
+  // ── 3. Actions (wrapped with middleware runner) ───────────────────────────
+  if (config.actions) {
+    const rawActions = config.actions(self) as Record<
+      string,
+      (...args: unknown[]) => unknown
+    >
+    for (const [key, actionFn] of Object.entries(rawActions)) {
+      instance[key] = (...args: unknown[]) =>
+        runAction(meta, key, actionFn, args)
+    }
+  }
+
+  return instance as ModelInstance<TState, TActions, TViews>
+}

package/src/middleware.ts

@@ -0,0 +1,57 @@
+import { instanceMeta } from './registry'
+import type { ActionCall, InstanceMeta, MiddlewareFn } from './types'
+
+// ─── Action runner ────────────────────────────────────────────────────────────
+
+/**
+ * Run an action through the middleware chain registered on `meta`.
+ * Each middleware receives the call descriptor and a `next` function.
+ * If no middlewares, the action runs directly.
+ */
+export function runAction(
+  meta: InstanceMeta,
+  name: string,
+  fn: (...fnArgs: unknown[]) => unknown,
+  args: unknown[],
+): unknown {
+  const call: ActionCall = { name, args, path: `/${name}` }
+
+  const dispatch = (idx: number, c: ActionCall): unknown => {
+    if (idx >= meta.middlewares.length) return fn(...c.args)
+    const mw = meta.middlewares[idx]
+    if (!mw) return fn(...c.args)
+    return mw(c, (nextCall) => dispatch(idx + 1, nextCall))
+  }
+
+  return dispatch(0, call)
+}
+
+// ─── addMiddleware ────────────────────────────────────────────────────────────
+
+/**
+ * Intercept every action call on `instance`.
+ * Middlewares run in registration order — call `next(call)` to continue.
+ *
+ * Returns an unsubscribe function.
+ *
+ * @example
+ * const unsub = addMiddleware(counter, (call, next) => {
+ *   console.log(`> ${call.name}(${call.args})`)
+ *   const result = next(call)
+ *   console.log(`< ${call.name}`)
+ *   return result
+ * })
+ */
+export function addMiddleware(
+  instance: object,
+  middleware: MiddlewareFn,
+): () => void {
+  const meta = instanceMeta.get(instance)
+  if (!meta)
+    throw new Error('[@pyreon/state-tree] addMiddleware: not a model instance')
+  meta.middlewares.push(middleware)
+  return () => {
+    const idx = meta.middlewares.indexOf(middleware)
+    if (idx !== -1) meta.middlewares.splice(idx, 1)
+  }
+}

package/src/model.ts

@@ -0,0 +1,117 @@
+import type { Computed, Signal } from '@pyreon/reactivity'
+import { createInstance, type ModelConfig } from './instance'
+import type { ModelInstance, Snapshot, StateShape } from './types'
+import { MODEL_BRAND } from './types'
+
+// ─── Hook registry ────────────────────────────────────────────────────────────
+
+// Module-level singleton registry for `asHook()` — isolated per package import.
+// Use `resetHook(id)` or `resetAllHooks()` to clear entries (useful for tests / HMR).
+const _hookRegistry = new Map<string, unknown>()
+
+/** Destroy a hook singleton by id so next call re-creates the instance. */
+export function resetHook(id: string): void {
+  _hookRegistry.delete(id)
+}
+
+/** Destroy all hook singletons. */
+export function resetAllHooks(): void {
+  _hookRegistry.clear()
+}
+
+// ─── ModelDefinition ──────────────────────────────────────────────────────────
+
+/**
+ * Returned by `model()`. Call `.create()` for instances or `.asHook(id)` for
+ * a Zustand-style singleton hook.
+ */
+export class ModelDefinition<
+  TState extends StateShape,
+  TActions extends Record<string, (...args: any[]) => any>,
+  TViews extends Record<string, Signal<any> | Computed<any>>,
+> {
+  /** Brand used to identify ModelDefinition objects at runtime (without instanceof). */
+  readonly [MODEL_BRAND] = true as const
+
+  /** @internal — exposed so nested instance creation can read it. */
+  readonly _config: ModelConfig<TState, TActions, TViews>
+
+  constructor(config: ModelConfig<TState, TActions, TViews>) {
+    this._config = config
+  }
+
+  /**
+   * Create a new independent model instance.
+   * Pass a partial snapshot to override defaults.
+   *
+   * @example
+   * const counter = Counter.create({ count: 5 })
+   */
+  create(
+    initial?: Partial<Snapshot<TState>>,
+  ): ModelInstance<TState, TActions, TViews> {
+    return createInstance(this._config, initial ?? {})
+  }
+
+  /**
+   * Returns a hook function that always returns the same singleton instance
+   * for the given `id` — Zustand / Pinia style.
+   *
+   * @example
+   * const useCounter = Counter.asHook("app-counter")
+   * // Any call to useCounter() returns the same instance.
+   * const store = useCounter()
+   */
+  asHook(id: string): () => ModelInstance<TState, TActions, TViews> {
+    return () => {
+      if (!_hookRegistry.has(id)) {
+        _hookRegistry.set(id, this.create())
+      }
+      return _hookRegistry.get(id) as ModelInstance<TState, TActions, TViews>
+    }
+  }
+}
+
+// ─── model() factory ──────────────────────────────────────────────────────────
+
+/**
+ * Define a reactive model with state, views, and actions.
+ *
+ * - **state** — plain JS object; each key becomes a `Signal<T>` on the instance.
+ * - **views** — factory receiving `self`; return computed signals for derived state.
+ * - **actions** — factory receiving `self`; return functions that mutate state.
+ *
+ * Use nested `ModelDefinition` values in `state` to compose models.
+ *
+ * @example
+ * const Counter = model({
+ *   state: { count: 0 },
+ *   views: (self) => ({
+ *     doubled: computed(() => self.count() * 2),
+ *   }),
+ *   actions: (self) => ({
+ *     inc:   () => self.count.update(c => c + 1),
+ *     reset: () => self.count.set(0),
+ *   }),
+ * })
+ *
+ * const c = Counter.create({ count: 5 })
+ * c.count()    // 5
+ * c.inc()
+ * c.doubled()  // 12
+ */
+export function model<
+  TState extends StateShape,
+  TActions extends Record<string, (...args: any[]) => any> = Record<
+    never,
+    never
+  >,
+  TViews extends Record<string, Signal<any> | Computed<any>> = Record<
+    never,
+    never
+  >,
+>(
+  config: ModelConfig<TState, TActions, TViews>,
+): ModelDefinition<TState, TActions, TViews> {
+  return new ModelDefinition(config)
+}

package/src/patch.ts

@@ -0,0 +1,173 @@
+import type { Signal } from '@pyreon/reactivity'
+import { batch } from '@pyreon/reactivity'
+import { instanceMeta, isModelInstance } from './registry'
+import type { Patch, PatchListener } from './types'
+
+/** Property names that must never be used as patch path segments. */
+const RESERVED_KEYS = new Set(['__proto__', 'constructor', 'prototype'])
+
+// ─── Tracked signal ───────────────────────────────────────────────────────────
+
+/**
+ * Wraps a signal so that every write emits a JSON patch via `emitPatch`.
+ * Reads are pass-through — no overhead on hot reactive paths.
+ *
+ * @param hasListeners Optional predicate — when provided, patch object allocation
+ *   and snapshotting are skipped entirely when no listeners are registered.
+ */
+export function trackedSignal<T>(
+  inner: Signal<T>,
+  path: string,
+  emitPatch: (patch: Patch) => void,
+  hasListeners?: () => boolean,
+): Signal<T> {
+  const read = (): T => inner()
+
+  read.peek = (): T => inner.peek()
+
+  read.subscribe = (listener: () => void): (() => void) =>
+    inner.subscribe(listener)
+
+  read.set = (newValue: T): void => {
+    const prev = inner.peek()
+    inner.set(newValue)
+    // Skip patch emission entirely when no one is listening — avoids object
+    // allocation and (for nested instances) a full recursive snapshot.
+    if (!Object.is(prev, newValue) && (!hasListeners || hasListeners())) {
+      // For model instances, emit the snapshot rather than the live object
+      // so patches are always plain JSON-serializable values.
+      const patchValue = isModelInstance(newValue)
+        ? snapshotValue(newValue as object)
+        : newValue
+      emitPatch({ op: 'replace', path, value: patchValue })
+    }
+  }
+
+  read.update = (fn: (current: T) => T): void => {
+    read.set(fn(inner.peek()))
+  }
+
+  return read as Signal<T>
+}
+
+/** Shallow snapshot helper (avoids importing snapshot.ts to prevent circular deps). */
+function snapshotValue(instance: object): Record<string, unknown> {
+  const meta = instanceMeta.get(instance)
+  if (!meta) return instance as Record<string, unknown>
+  const out: Record<string, unknown> = {}
+  for (const key of meta.stateKeys) {
+    const sig = (instance as Record<string, Signal<unknown>>)[key]
+    if (!sig) continue
+    const val = sig.peek()
+    out[key] = isModelInstance(val) ? snapshotValue(val as object) : val
+  }
+  return out
+}
+
+// ─── onPatch ──────────────────────────────────────────────────────────────────
+
+/**
+ * Subscribe to every state mutation in `instance` as a JSON patch.
+ * Also captures mutations in nested model instances (path is prefixed).
+ *
+ * Returns an unsubscribe function.
+ *
+ * @example
+ * const unsub = onPatch(counter, patch => {
+ *   // { op: "replace", path: "/count", value: 6 }
+ * })
+ */
+export function onPatch(instance: object, listener: PatchListener): () => void {
+  const meta = instanceMeta.get(instance)
+  if (!meta)
+    throw new Error('[@pyreon/state-tree] onPatch: not a model instance')
+  meta.patchListeners.add(listener)
+  return () => meta.patchListeners.delete(listener)
+}
+
+// ─── applyPatch ─────────────────────────────────────────────────────────────
+
+/**
+ * Apply a JSON patch (or array of patches) to a model instance.
+ * Only "replace" operations are supported (matching the patches emitted by `onPatch`).
+ *
+ * Paths use JSON pointer format: `"/count"` for top-level, `"/profile/name"` for nested.
+ * Nested model instances are resolved automatically.
+ *
+ * @example
+ * applyPatch(counter, { op: "replace", path: "/count", value: 10 })
+ *
+ * @example
+ * // Replay patches recorded from onPatch (undo/redo, time-travel)
+ * applyPatch(counter, [
+ *   { op: "replace", path: "/count", value: 1 },
+ *   { op: "replace", path: "/count", value: 2 },
+ * ])
+ */
+export function applyPatch(instance: object, patch: Patch | Patch[]): void {
+  const patches = Array.isArray(patch) ? patch : [patch]
+
+  batch(() => {
+    for (const p of patches) {
+      if (p.op !== 'replace') {
+        throw new Error(
+          `[@pyreon/state-tree] applyPatch: unsupported op "${p.op}"`,
+        )
+      }
+
+      const segments = p.path.split('/').filter(Boolean)
+      if (segments.length === 0) {
+        throw new Error('[@pyreon/state-tree] applyPatch: empty path')
+      }
+
+      // Walk to the target instance for nested paths
+      let target: object = instance
+      for (let i = 0; i < segments.length - 1; i++) {
+        const segment = segments[i]!
+        if (RESERVED_KEYS.has(segment)) {
+          throw new Error(
+            `[@pyreon/state-tree] applyPatch: reserved property name "${segment}"`,
+          )
+        }
+        const meta = instanceMeta.get(target)
+        if (!meta)
+          throw new Error(
+            `[@pyreon/state-tree] applyPatch: not a model instance at "${segment}"`,
+          )
+        const sig = (target as Record<string, Signal<unknown>>)[segment]
+        if (!sig || typeof sig.peek !== 'function') {
+          throw new Error(
+            `[@pyreon/state-tree] applyPatch: unknown state key "${segment}"`,
+          )
+        }
+        const nested = sig.peek()
+        if (!nested || typeof nested !== 'object' || !isModelInstance(nested)) {
+          throw new Error(
+            `[@pyreon/state-tree] applyPatch: "${segment}" is not a nested model instance`,
+          )
+        }
+        target = nested as object
+      }
+
+      const lastKey = segments[segments.length - 1]!
+      if (RESERVED_KEYS.has(lastKey)) {
+        throw new Error(
+          `[@pyreon/state-tree] applyPatch: reserved property name "${lastKey}"`,
+        )
+      }
+      const meta = instanceMeta.get(target)
+      if (!meta)
+        throw new Error('[@pyreon/state-tree] applyPatch: not a model instance')
+      if (!meta.stateKeys.includes(lastKey)) {
+        throw new Error(
+          `[@pyreon/state-tree] applyPatch: unknown state key "${lastKey}"`,
+        )
+      }
+
+      const sig = (target as Record<string, Signal<unknown>>)[lastKey]
+      if (sig && typeof sig.set === 'function') {
+        sig.set(p.value)
+      }
+    }
+  })
+}

package/src/registry.ts

@@ -0,0 +1,16 @@
+import type { InstanceMeta } from './types'
+
+/**
+ * WeakMap from every model instance object → its internal metadata.
+ * Shared across patch, middleware, and snapshot modules.
+ */
+export const instanceMeta = new WeakMap<object, InstanceMeta>()
+
+/** Returns true when a value is a model instance (has metadata registered). */
+export function isModelInstance(value: unknown): boolean {
+  return (
+    value != null &&
+    typeof value === 'object' &&
+    instanceMeta.has(value as object)
+  )
+}

package/src/snapshot.ts

@@ -0,0 +1,66 @@
+import type { Signal } from '@pyreon/reactivity'
+import { batch } from '@pyreon/reactivity'
+import { instanceMeta, isModelInstance } from './registry'
+import type { Snapshot, StateShape } from './types'
+
+// ─── getSnapshot ──────────────────────────────────────────────────────────────
+
+/**
+ * Serialize a model instance to a plain JS object (no signals, no functions).
+ * Nested model instances are recursively serialized.
+ *
+ * @example
+ * getSnapshot(counter)  // { count: 6 }
+ * getSnapshot(app)      // { profile: { name: "Alice" }, title: "My App" }
+ */
+export function getSnapshot<TState extends StateShape>(
+  instance: object,
+): Snapshot<TState> {
+  const meta = instanceMeta.get(instance)
+  if (!meta)
+    throw new Error('[@pyreon/state-tree] getSnapshot: not a model instance')
+
+  const out: Record<string, unknown> = {}
+  for (const key of meta.stateKeys) {
+    const sig = (instance as Record<string, Signal<unknown>>)[key]
+    if (!sig) continue
+    const val = sig.peek()
+    out[key] = isModelInstance(val) ? getSnapshot(val as object) : val
+  }
+  return out as Snapshot<TState>
+}
+
+// ─── applySnapshot ────────────────────────────────────────────────────────────
+
+/**
+ * Restore a model instance from a plain-object snapshot.
+ * All signal writes are coalesced via `batch()` for a single reactive flush.
+ * Keys absent from the snapshot are left unchanged.
+ *
+ * @example
+ * applySnapshot(counter, { count: 0 })
+ */
+export function applySnapshot<TState extends StateShape>(
+  instance: object,
+  snapshot: Partial<Snapshot<TState>>,
+): void {
+  const meta = instanceMeta.get(instance)
+  if (!meta)
+    throw new Error('[@pyreon/state-tree] applySnapshot: not a model instance')
+
+  batch(() => {
+    for (const key of meta.stateKeys) {
+      if (!(key in snapshot)) continue
+      const sig = (instance as Record<string, Signal<unknown>>)[key]
+      if (!sig) continue
+      const val = (snapshot as Record<string, unknown>)[key]
+      const current = sig.peek()
+      if (isModelInstance(current)) {
+        // Recurse into nested model instance
+        applySnapshot(current as object, val as Record<string, unknown>)
+      } else {
+        sig.set(val)
+      }
+    }
+  })
+}