@pyreon/state-tree 0.24.5 → 0.24.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyreon/state-tree",
-  "version": "0.24.5",
+  "version": "0.24.6",
   "description": "Structured reactive state tree — composable models with snapshots, patches, and middleware",
   "homepage": "https://github.com/pyreon/pyreon/tree/main/packages/state-tree#readme",
   "bugs": {
@@ -15,7 +15,6 @@
   "files": [
     "lib",
     "!lib/**/*.map",
-    "src",
     "README.md",
     "LICENSE"
   ],
@@ -26,12 +25,10 @@
   "types": "./lib/types/index.d.ts",
   "exports": {
     ".": {
-      "bun": "./src/index.ts",
       "import": "./lib/index.js",
       "types": "./lib/types/index.d.ts"
     },
     "./devtools": {
-      "bun": "./src/devtools.ts",
       "import": "./lib/devtools.js",
       "types": "./lib/types/devtools.d.ts"
     }
@@ -49,10 +46,10 @@
   "devDependencies": {
     "@happy-dom/global-registrator": "^20.8.9",
     "@pyreon/manifest": "0.13.1",
-    "@pyreon/reactivity": "^0.24.5",
+    "@pyreon/reactivity": "^0.24.6",
     "bun-types": "^1.3.12"
   },
   "dependencies": {
-    "@pyreon/reactivity": "^0.24.5"
+    "@pyreon/reactivity": "^0.24.6"
   }
 }

package/src/devtools.ts

@@ -1,85 +0,0 @@
-/**
- * @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

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

package/src/instance.ts

@@ -1,128 +0,0 @@
-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 ──────────────────────────────────────────────────────
-  // Per-state-key signal allocation at instance CREATION (createInstance
-  // runs once per model instance), not per-render — this is the model's
-  // fine-grained reactive architecture, not the signal-in-render-loop
-  // anti-pattern the rule targets. Disabled per-site below with rationale.
-  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>) ?? {},
-      )
-      // pyreon-lint-disable-next-line pyreon/no-signal-in-loop
-      rawSig = signal(nestedInstance)
-
-      // Propagate nested patches upward with the key as path prefix.
-      onPatch(nestedInstance, (patch) => {
-        meta.emitPatch({ ...patch, path: path + patch.path })
-      })
-    } else {
-      // pyreon-lint-disable-next-line pyreon/no-signal-in-loop
-      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/manifest.ts

@@ -1,161 +0,0 @@
-import { defineManifest } from '@pyreon/manifest'
-
-export default defineManifest({
-  name: '@pyreon/state-tree',
-  title: 'State Tree',
-  tagline:
-    'Structured reactive state tree — composable models with snapshots, patches, and middleware',
-  description:
-    'MobX-State-Tree-inspired structured state management built on Pyreon signals. Models compose state (signals), views (computeds), and actions into self-contained units that support typed snapshots, JSON-patch record/replay, and action interception middleware. Models can nest other models for tree-shaped state, and `.asHook(id)` provides singleton instances scoped to a store-like registry.',
-  category: 'universal',
-  longExample: `import { model, getSnapshot, applySnapshot, onPatch, applyPatch, addMiddleware } from '@pyreon/state-tree'
-
-// Define a model — state (signals), views (derived), actions (mutations):
-const Todo = model({
-  state: { title: '', done: false },
-  views: (self) => ({
-    summary: () => \`\${self.title()} [\${self.done() ? 'x' : ' '}]\`,
-  }),
-  actions: (self) => ({
-    toggle: () => self.done.set(!self.done()),
-    rename: (title: string) => self.title.set(title),
-  }),
-})
-
-const TodoList = model({
-  state: { todos: [] as ReturnType<typeof Todo.create>[] },
-  actions: (self) => ({
-    add: (title: string) => {
-      const todo = Todo.create({ title, done: false })
-      self.todos.update(list => [...list, todo])
-    },
-  }),
-})
-
-// Create instances:
-const list = TodoList.create({ todos: [] })
-list.add('Write tests')
-list.todos()[0].toggle()
-
-// Snapshots — typed recursive serialization:
-const snap = getSnapshot(list)
-applySnapshot(list, { todos: [{ title: 'Restored', done: true }] })
-
-// JSON patches — record/replay for undo, sync, debugging:
-const patches: Patch[] = []
-const dispose = onPatch(list, (patch) => patches.push(patch))
-list.add('New item')
-// Later: applyPatch(list, patches[0]) to replay
-
-// Middleware — intercept any action in the tree:
-addMiddleware(list, (call, next) => {
-  console.log(\`Action: \${call.name}\`, call.args)
-  return next(call)
-})
-
-// Singleton hook for app-wide state:
-const useTodoList = TodoList.asHook('todo-list')
-const { store } = useTodoList() // same instance on every call`,
-  features: [
-    'model({ state, views, actions }) — structured reactive models',
-    'Nested model composition for tree-shaped state',
-    'getSnapshot / applySnapshot — typed recursive serialization',
-    'onPatch / applyPatch — JSON patch record and replay',
-    'addMiddleware — action interception chain',
-    '.create(initial) for instances, .asHook(id) for singleton hooks',
-    'Devtools subpath export with WeakRef-based registry',
-  ],
-  api: [
-    {
-      name: 'model',
-      kind: 'function',
-      signature: '(definition: { state: StateShape, views?: (self: ModelSelf) => Record<string, () => any>, actions?: (self: ModelSelf) => Record<string, (...args: any[]) => any> }) => ModelDefinition',
-      summary:
-        'Define a structured reactive model. `state` declares signal-backed fields with their initial values. `views` are computed derivations. `actions` are the only way to mutate state — enabling middleware interception and patch recording. Returns a `ModelDefinition` with `.create(initial?)` for instances and `.asHook(id)` for singleton access.',
-      example: `const Counter = model({
-  state: { count: 0 },
-  views: (self) => ({
-    doubled: () => self.count() * 2,
-  }),
-  actions: (self) => ({
-    increment: () => self.count.update(n => n + 1),
-  }),
-})
-
-const counter = Counter.create({ count: 10 })
-counter.count()    // 10
-counter.increment()
-counter.doubled()  // 22`,
-      mistakes: [
-        'Mutating state outside of actions — bypasses middleware and patch recording, breaks the structured contract',
-        'Forgetting that `self.count` is a signal — read with `self.count()`, write with `self.count.set(v)` or `.update(fn)` inside actions',
-        'Nesting plain objects in state instead of child models — plain objects are not signal-backed, changes to their properties are not reactive',
-      ],
-      seeAlso: ['getSnapshot', 'applySnapshot', 'onPatch', 'addMiddleware'],
-    },
-    {
-      name: 'getSnapshot',
-      kind: 'function',
-      signature: '(instance: ModelInstance) => Snapshot',
-      summary:
-        'Recursively serialize a model instance into a plain JSON-safe snapshot. Reads all signal values via `.peek()` to avoid tracking subscriptions. Nested models are recursively serialized.',
-      example: `const snap = getSnapshot(counter) // { count: 10 }`,
-      seeAlso: ['applySnapshot', 'model'],
-    },
-    {
-      name: 'applySnapshot',
-      kind: 'function',
-      signature: '(instance: ModelInstance, snapshot: Snapshot) => void',
-      summary:
-        'Replace a model instance\'s state wholesale from a snapshot. Recursively applies to nested models. Triggers patch listeners with replace operations.',
-      example: `applySnapshot(counter, { count: 0 }) // reset to zero`,
-      seeAlso: ['getSnapshot', 'model'],
-    },
-    {
-      name: 'onPatch',
-      kind: 'function',
-      signature: '(instance: ModelInstance, listener: PatchListener) => () => void',
-      summary:
-        'Subscribe to JSON patches emitted by actions on a model instance. Each patch records the path, operation (add/replace/remove), and value. Returns an unsubscribe function. Pairs with `applyPatch` for undo/redo and state synchronization.',
-      example: `const dispose = onPatch(counter, (patch) => {
-  console.log(patch) // { op: 'replace', path: '/count', value: 11 }
-})`,
-      seeAlso: ['applyPatch', 'model'],
-    },
-    {
-      name: 'applyPatch',
-      kind: 'function',
-      signature: '(instance: ModelInstance, patch: Patch | Patch[]) => void',
-      summary:
-        'Apply one or more JSON patches to a model instance. Accepts a single patch or an array for batch replay. Used with `onPatch` for undo/redo and state synchronization.',
-      example: `applyPatch(counter, { op: 'replace', path: '/count', value: 0 })`,
-      seeAlso: ['onPatch', 'model'],
-    },
-    {
-      name: 'addMiddleware',
-      kind: 'function',
-      signature: '(instance: ModelInstance, middleware: MiddlewareFn) => () => void',
-      summary:
-        'Add an action interception middleware to a model instance. The middleware receives the action call context and a `next` function — call `next(call)` to proceed or return early to block the action. Returns an unsubscribe function.',
-      example: `addMiddleware(counter, (call, next) => {
-  console.log(\`\${call.name}(\${call.args.join(', ')})\`)
-  return next(call)
-})`,
-      seeAlso: ['model'],
-    },
-  ],
-  gotchas: [
-    {
-      label: 'Actions only',
-      note: 'State mutations must go through actions — direct `.set()` calls on state signals bypass middleware and patch recording. The model enforces this in dev mode.',
-    },
-    {
-      label: 'Snapshot serialization',
-      note: '`getSnapshot` reads via `.peek()` so it does not subscribe to signals. The snapshot is a one-time read, not a reactive computed.',
-    },
-    {
-      label: 'Devtools',
-      note: 'Import `@pyreon/state-tree/devtools` for a WeakRef-based registry of live model instances. Tree-shakeable — zero cost unless imported.',
-    },
-  ],
-})

package/src/middleware.ts

@@ -1,53 +0,0 @@
-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

@@ -1,107 +0,0 @@
-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)
-}