@pyreon/store 0.0.1

package/lib/types/index2.d.ts

@@ -0,0 +1,73 @@
+import { Signal, batch, computed, effect, signal } from "@pyreon/reactivity";
+
+//#region src/registry.d.ts
+/**
+ * Override the store registry provider.
+ * Called by @pyreon/runtime-server to inject a per-request isolated registry,
+ * preventing store state from leaking between concurrent SSR requests.
+ *
+ * @example
+ * import { AsyncLocalStorage } from "node:async_hooks"
+ * const als = new AsyncLocalStorage<Map<string, unknown>>()
+ * setRegistryProvider(() => als.getStore() ?? new Map())
+ * // Then wrap each request: als.run(new Map(), () => renderToString(app))
+ */
+declare function setRegistryProvider(fn: () => Map<string, unknown>): void;
+//#endregion
+//#region src/index.d.ts
+interface MutationInfo {
+  storeId: string;
+  type: 'direct' | 'patch';
+  events: {
+    key: string;
+    newValue: unknown;
+    oldValue: unknown;
+  }[];
+}
+type SubscribeCallback = (mutation: MutationInfo, state: Record<string, unknown>) => void;
+interface ActionContext {
+  name: string;
+  storeId: string;
+  args: unknown[];
+  after: (cb: (result: unknown) => void) => void;
+  onError: (cb: (error: unknown) => void) => void;
+}
+type OnActionCallback = (context: ActionContext) => void;
+type StorePlugin = (api: StoreApi<Record<string, unknown>>) => void;
+/** The structured result returned by every store hook. */
+interface StoreApi<T> {
+  /** The user-defined store state, computeds, and actions. */
+  store: T;
+  /** Store identifier. */
+  id: string;
+  /** Read-only snapshot of all signal values. */
+  readonly state: Record<string, unknown>;
+  /** Batch-update multiple signals (object form) or direct access (function form). */
+  patch(partialState: Record<string, unknown>): void;
+  patch(fn: (state: Record<string, any>) => void): void;
+  /** Subscribe to state mutations. Returns an unsubscribe function. */
+  subscribe(callback: SubscribeCallback, options?: {
+    immediate?: boolean;
+  }): () => void;
+  /** Intercept action calls. Returns an unsubscribe function. */
+  onAction(callback: OnActionCallback): () => void;
+  /** Reset all signals to their initial values. */
+  reset(): void;
+  /** Teardown: unsubscribe all listeners and remove from registry. */
+  dispose(): void;
+}
+/** Register a global store plugin. Plugins run when a store is first created. */
+declare function addStorePlugin(plugin: StorePlugin): void;
+/**
+ * Define a store with a unique id and a setup function.
+ * Returns a hook that returns a `StoreApi<T>` with the user's state under `.store`
+ * and framework methods (`patch`, `subscribe`, `onAction`, `reset`, `dispose`) at the top level.
+ */
+declare function defineStore<T extends Record<string, unknown>>(id: string, setup: () => T): () => StoreApi<T>;
+/** Destroy a store by id so next call to useStore() re-runs setup. */
+declare function resetStore(id: string): void;
+/** Destroy all stores — useful for SSR isolation and tests. */
+declare function resetAllStores(): void;
+//#endregion
+export { ActionContext, MutationInfo, OnActionCallback, type Signal, StoreApi, StorePlugin, SubscribeCallback, addStorePlugin, batch, computed, defineStore, effect, resetAllStores, resetStore, setRegistryProvider as setStoreRegistryProvider, signal };
+//# sourceMappingURL=index2.d.ts.map

package/lib/types/index2.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index2.d.ts","names":[],"sources":["../../src/registry.ts","../../src/index.ts"],"mappings":";;;;;;AAmBA;;;;;;;;iBAAgB,mBAAA,CAAoB,EAAA,QAAU,GAAA;;;UCiB7B,YAAA;EACf,OAAA;EACA,IAAA;EACA,MAAA;IAAU,GAAA;IAAa,QAAA;IAAmB,QAAA;EAAA;AAAA;AAAA,KAGhC,iBAAA,IACV,QAAA,EAAU,YAAA,EACV,KAAA,EAAO,MAAA;AAAA,UAGQ,aAAA;EACf,IAAA;EACA,OAAA;EACA,IAAA;EACA,KAAA,GAAQ,EAAA,GAAK,MAAA;EACb,OAAA,GAAU,EAAA,GAAK,KAAA;AAAA;AAAA,KAGL,gBAAA,IAAoB,OAAA,EAAS,aAAA;AAAA,KAE7B,WAAA,IAAe,GAAA,EAAK,QAAA,CAAS,MAAA;;UAGxB,QAAA;EALW;EAO1B,KAAA,EAAO,CAAA;EAPgC;EASvC,EAAA;EAPU;EAAA,SASD,KAAA,EAAO,MAAA;;EAEhB,KAAA,CAAM,YAAA,EAAc,MAAA;EACpB,KAAA,CAAM,EAAA,GAAK,KAAA,EAAO,MAAA;EAZqB;EAcvC,SAAA,CACE,QAAA,EAAU,iBAAA,EACV,OAAA;IAAY,SAAA;EAAA;EAbC;EAgBf,QAAA,CAAS,QAAA,EAAU,gBAAA;EAhBI;EAkBvB,KAAA;EAZgB;EAchB,OAAA;AAAA;;iBA8Bc,cAAA,CAAe,MAAA,EAAQ,WAAA;;;;;;iBAWvB,WAAA,WAAsB,MAAA,kBAAA,CACpC,EAAA,UACA,KAAA,QAAa,CAAA,SACN,QAAA,CAAS,CAAA;;iBAqPF,UAAA,CAAW,EAAA;;iBAMX,cAAA,CAAA"}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@pyreon/store",
+  "version": "0.0.1",
+  "description": "Global state management for Pyreon — Pinia-inspired composition stores",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pyreon/fundamentals.git",
+    "directory": "packages/store"
+  },
+  "homepage": "https://github.com/pyreon/fundamentals/tree/main/packages/store#readme",
+  "bugs": {
+    "url": "https://github.com/pyreon/fundamentals/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "lib",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "main": "./lib/index.js",
+  "module": "./lib/index.js",
+  "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"
+    }
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "vl_rolldown_build",
+    "dev": "vl_rolldown_build-watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@pyreon/reactivity": "^0.2.1"
+  },
+  "devDependencies": {
+    "@happy-dom/global-registrator": "^20.8.3",
+    "@pyreon/reactivity": "^0.2.1",
+    "@vitus-labs/tools-lint": "^1.11.0"
+  }
+}

package/src/devtools.ts

@@ -0,0 +1,35 @@
+/**
+ * @pyreon/store devtools introspection API.
+ * Import: `import { ... } from "@pyreon/store/devtools"`
+ */
+
+import { getRegistry } from './registry'
+
+const _listeners = new Set<() => void>()
+
+/** @internal — called by defineStore/resetStore to notify devtools. */
+export function _notifyChange(): void {
+  for (const listener of _listeners) listener()
+}
+
+/** Get all registered store IDs. */
+export function getRegisteredStores(): string[] {
+  return [...getRegistry().keys()]
+}
+
+/** Get a store API by ID (or undefined if not registered). */
+export function getStoreById(
+  id: string,
+): import('./index').StoreApi<Record<string, unknown>> | undefined {
+  return getRegistry().get(id) as
+    | import('./index').StoreApi<Record<string, unknown>>
+    | undefined
+}
+
+/** Subscribe to store registry changes (store added/removed). Returns unsubscribe. */
+export function onStoreChange(listener: () => void): () => void {
+  _listeners.add(listener)
+  return () => {
+    _listeners.delete(listener)
+  }
+}

package/src/index.ts

@@ -0,0 +1,379 @@
+/**
+ * @pyreon/store — global state management built on @pyreon/reactivity signals.
+ *
+ * API (composition style):
+ *
+ *   const useCounter = defineStore("counter", () => {
+ *     const count = signal(0)
+ *     const double = computed(() => count() * 2)
+ *     const increment = () => count.update(n => n + 1)
+ *     return { count, double, increment }
+ *   })
+ *
+ *   // Inside a component (or anywhere):
+ *   const { store, patch, subscribe } = useCounter()
+ *   store.count()       // read state
+ *   store.increment()   // call action
+ *   patch({ count: 5 }) // batch-update
+ *
+ * Stores are singletons — the setup function runs once per store id.
+ * Call `resetStore(id)` or `resetAllStores()` to clear the registry
+ * (useful for testing or HMR).
+ *
+ * For concurrent SSR, call setStoreRegistryProvider() with an
+ * AsyncLocalStorage-backed provider so each request gets isolated store state.
+ */
+
+export type { Signal } from '@pyreon/reactivity'
+export { batch, computed, effect, signal } from '@pyreon/reactivity'
+import { batch } from '@pyreon/reactivity'
+
+export { setRegistryProvider as setStoreRegistryProvider } from './registry'
+import { getRegistry } from './registry'
+import { _notifyChange } from './devtools'
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export interface MutationInfo {
+  storeId: string
+  type: 'direct' | 'patch'
+  events: { key: string; newValue: unknown; oldValue: unknown }[]
+}
+
+export type SubscribeCallback = (
+  mutation: MutationInfo,
+  state: Record<string, unknown>,
+) => void
+
+export interface ActionContext {
+  name: string
+  storeId: string
+  args: unknown[]
+  after: (cb: (result: unknown) => void) => void
+  onError: (cb: (error: unknown) => void) => void
+}
+
+export type OnActionCallback = (context: ActionContext) => void
+
+export type StorePlugin = (api: StoreApi<Record<string, unknown>>) => void
+
+/** The structured result returned by every store hook. */
+export interface StoreApi<T> {
+  /** The user-defined store state, computeds, and actions. */
+  store: T
+  /** Store identifier. */
+  id: string
+  /** Read-only snapshot of all signal values. */
+  readonly state: Record<string, unknown>
+  /** Batch-update multiple signals (object form) or direct access (function form). */
+  patch(partialState: Record<string, unknown>): void
+  patch(fn: (state: Record<string, any>) => void): void
+  /** Subscribe to state mutations. Returns an unsubscribe function. */
+  subscribe(
+    callback: SubscribeCallback,
+    options?: { immediate?: boolean },
+  ): () => void
+  /** Intercept action calls. Returns an unsubscribe function. */
+  onAction(callback: OnActionCallback): () => void
+  /** Reset all signals to their initial values. */
+  reset(): void
+  /** Teardown: unsubscribe all listeners and remove from registry. */
+  dispose(): void
+}
+
+// ─── Detection helpers ───────────────────────────────────────────────────────
+
+/** Duck-typed signal interface for detection without importing concrete types. */
+interface SignalLike {
+  (): unknown
+  set(v: unknown): void
+  peek(): unknown
+  subscribe(l: () => void): () => void
+}
+
+function isSignalLike(v: unknown): v is SignalLike {
+  if (typeof v !== 'function') return false
+  const fn = v as unknown as Record<string, unknown>
+  return typeof fn.set === 'function' && typeof fn.peek === 'function'
+}
+
+function isComputedLike(v: unknown): boolean {
+  if (typeof v !== 'function') return false
+  const fn = v as unknown as Record<string, unknown>
+  return typeof fn.dispose === 'function' && !isSignalLike(v)
+}
+
+// ─── Plugin system ───────────────────────────────────────────────────────────
+
+const _plugins: StorePlugin[] = []
+
+/** Register a global store plugin. Plugins run when a store is first created. */
+export function addStorePlugin(plugin: StorePlugin): void {
+  _plugins.push(plugin)
+}
+
+// ─── defineStore ─────────────────────────────────────────────────────────────
+
+/**
+ * Define a store with a unique id and a setup function.
+ * Returns a hook that returns a `StoreApi<T>` with the user's state under `.store`
+ * and framework methods (`patch`, `subscribe`, `onAction`, `reset`, `dispose`) at the top level.
+ */
+export function defineStore<T extends Record<string, unknown>>(
+  id: string,
+  setup: () => T,
+): () => StoreApi<T> {
+  return function useStore(): StoreApi<T> {
+    const registry = getRegistry()
+    if (registry.has(id)) return registry.get(id) as StoreApi<T>
+
+    const raw = setup()
+
+    // Classify properties
+    const signalKeys: string[] = []
+    const actionKeys: string[] = []
+    const initialValues = new Map<string, unknown>()
+
+    for (const key of Object.keys(raw)) {
+      const val = raw[key]
+      if (isSignalLike(val)) {
+        signalKeys.push(key)
+        initialValues.set(key, val.peek())
+      } else if (isComputedLike(val)) {
+        // computed — skip, just pass through
+      } else if (typeof val === 'function') {
+        actionKeys.push(key)
+      }
+    }
+
+    // ─── subscribe infrastructure ───────────────────────────────────────
+    const subscribers = new Set<SubscribeCallback>()
+    let patchInProgress = false
+    let patchEvents: MutationInfo['events'] = []
+
+    function getState(): Record<string, unknown> {
+      const state: Record<string, unknown> = {}
+      for (const key of signalKeys) {
+        state[key] = (raw[key] as any).peek()
+      }
+      return state
+    }
+
+    function notifyDirect(key: string, oldValue: unknown, newValue: unknown) {
+      if (patchInProgress) {
+        patchEvents.push({ key, newValue, oldValue })
+        return
+      }
+      if (subscribers.size === 0) return
+      const mutation: MutationInfo = {
+        storeId: id,
+        type: 'direct',
+        events: [{ key, newValue, oldValue }],
+      }
+      const state = getState()
+      for (const cb of subscribers) cb(mutation, state)
+    }
+
+    // Subscribe to each signal for change detection
+    const signalUnsubs: (() => void)[] = []
+    for (const key of signalKeys) {
+      const sig = raw[key] as any
+      let prev = sig.peek()
+      const unsub = sig.subscribe(() => {
+        const next = sig.peek()
+        const old = prev
+        prev = next
+        notifyDirect(key, old, next)
+      })
+      signalUnsubs.push(unsub)
+    }
+
+    // ─── onAction infrastructure ────────────────────────────────────────
+    const actionListeners = new Set<OnActionCallback>()
+
+    // Wrap actions
+    function wrapAction(key: string, original: (...args: any[]) => unknown) {
+      return (...args: unknown[]) => {
+        const afterCbs: ((result: unknown) => void)[] = []
+        const errorCbs: ((error: unknown) => void)[] = []
+
+        const context: ActionContext = {
+          name: key,
+          storeId: id,
+          args,
+          after: (cb) => afterCbs.push(cb),
+          onError: (cb) => errorCbs.push(cb),
+        }
+
+        for (const listener of actionListeners) {
+          listener(context)
+        }
+
+        try {
+          const result = original(...args)
+
+          // Handle async actions: if the result is a thenable, wait for
+          // resolution before calling after/onError callbacks.
+          if (result != null && typeof (result as any).then === 'function') {
+            return (result as Promise<unknown>).then(
+              (resolved) => {
+                for (const cb of afterCbs) cb(resolved)
+                return resolved
+              },
+              (err) => {
+                for (const cb of errorCbs) cb(err)
+                throw err
+              },
+            )
+          }
+
+          for (const cb of afterCbs) cb(result)
+          return result
+        } catch (err) {
+          for (const cb of errorCbs) cb(err)
+          throw err
+        }
+      }
+    }
+
+    // ─── Build user store object ────────────────────────────────────────
+    const userStore: Record<string, unknown> = {}
+
+    for (const key of Object.keys(raw)) {
+      if (actionKeys.includes(key)) {
+        userStore[key] = wrapAction(
+          key,
+          raw[key] as (...args: any[]) => unknown,
+        )
+      } else {
+        userStore[key] = raw[key]
+      }
+    }
+
+    // ─── Build StoreApi ─────────────────────────────────────────────────
+    const api: StoreApi<T> = {
+      store: userStore as T,
+
+      id,
+
+      get state() {
+        return getState()
+      },
+
+      patch(
+        partialOrFn:
+          | Record<string, unknown>
+          | ((state: Record<string, any>) => void),
+      ) {
+        patchInProgress = true
+        patchEvents = []
+
+        batch(() => {
+          if (typeof partialOrFn === 'function') {
+            // Functional form: pass an object with the actual signals so user calls .set()
+            const signalMap: Record<string, any> = {}
+            for (const key of signalKeys) {
+              signalMap[key] = raw[key]
+            }
+            partialOrFn(signalMap)
+          } else {
+            // Object form: set values directly (skip reserved proto keys)
+            for (const [key, value] of Object.entries(partialOrFn)) {
+              if (
+                key === '__proto__' ||
+                key === 'constructor' ||
+                key === 'prototype'
+              )
+                continue
+              if (signalKeys.includes(key)) {
+                ;(raw[key] as SignalLike).set(value)
+              }
+            }
+          }
+        })
+
+        patchInProgress = false
+
+        // Emit a single notification for the patch
+        if (subscribers.size > 0 && patchEvents.length > 0) {
+          const mutation: MutationInfo = {
+            storeId: id,
+            type: 'patch',
+            events: patchEvents,
+          }
+          const state = getState()
+          for (const cb of subscribers) cb(mutation, state)
+        }
+        patchEvents = []
+      },
+
+      subscribe(
+        callback: SubscribeCallback,
+        options?: { immediate?: boolean },
+      ): () => void {
+        subscribers.add(callback)
+        if (options?.immediate) {
+          const mutation: MutationInfo = {
+            storeId: id,
+            type: 'direct',
+            events: [],
+          }
+          callback(mutation, getState())
+        }
+        return () => {
+          subscribers.delete(callback)
+        }
+      },
+
+      onAction(callback: OnActionCallback): () => void {
+        actionListeners.add(callback)
+        return () => {
+          actionListeners.delete(callback)
+        }
+      },
+
+      reset() {
+        batch(() => {
+          for (const [key, initial] of initialValues) {
+            ;(raw[key] as any).set(initial)
+          }
+        })
+      },
+
+      dispose() {
+        for (const unsub of signalUnsubs) unsub()
+        signalUnsubs.length = 0
+        subscribers.clear()
+        actionListeners.clear()
+        getRegistry().delete(id)
+      },
+    }
+
+    // Run plugins — errors in one plugin should not break store creation
+    for (const plugin of _plugins) {
+      try {
+        plugin(api as StoreApi<Record<string, unknown>>)
+      } catch (_err) {
+        // Plugin errors should not break store creation
+      }
+    }
+
+    registry.set(id, api)
+    _notifyChange()
+    return api
+  }
+}
+
+// ─── Utilities ───────────────────────────────────────────────────────────────
+
+/** Destroy a store by id so next call to useStore() re-runs setup. */
+export function resetStore(id: string): void {
+  getRegistry().delete(id)
+  _notifyChange()
+}
+
+/** Destroy all stores — useful for SSR isolation and tests. */
+export function resetAllStores(): void {
+  getRegistry().clear()
+  _notifyChange()
+}

package/src/registry.ts

@@ -0,0 +1,26 @@
+// ─── Registry ─────────────────────────────────────────────────────────────────
+
+// Default: module-level singleton (CSR and single-threaded SSR).
+// For concurrent SSR, @pyreon/runtime-server replaces this with an
+// AsyncLocalStorage-backed provider via setRegistryProvider().
+const _defaultRegistry = new Map<string, unknown>()
+let _registryProvider: () => Map<string, unknown> = () => _defaultRegistry
+
+/**
+ * Override the store registry provider.
+ * Called by @pyreon/runtime-server to inject a per-request isolated registry,
+ * preventing store state from leaking between concurrent SSR requests.
+ *
+ * @example
+ * import { AsyncLocalStorage } from "node:async_hooks"
+ * const als = new AsyncLocalStorage<Map<string, unknown>>()
+ * setRegistryProvider(() => als.getStore() ?? new Map())
+ * // Then wrap each request: als.run(new Map(), () => renderToString(app))
+ */
+export function setRegistryProvider(fn: () => Map<string, unknown>): void {
+  _registryProvider = fn
+}
+
+export function getRegistry(): Map<string, unknown> {
+  return _registryProvider()
+}

package/src/tests/devtools.test.ts

@@ -0,0 +1,70 @@
+import { signal } from '@pyreon/reactivity'
+import { getRegisteredStores, getStoreById, onStoreChange } from '../devtools'
+import { defineStore, resetAllStores } from '../index'
+
+afterEach(() => resetAllStores())
+
+describe('store devtools', () => {
+  test('getRegisteredStores returns empty initially', () => {
+    expect(getRegisteredStores()).toEqual([])
+  })
+
+  test('getRegisteredStores returns store IDs after creation', () => {
+    const useCounter = defineStore('counter', () => ({ count: signal(0) }))
+    useCounter()
+    expect(getRegisteredStores()).toContain('counter')
+  })
+
+  test('getStoreById returns the store instance', () => {
+    const useCounter = defineStore('counter', () => ({ count: signal(0) }))
+    const store = useCounter()
+    const retrieved = getStoreById('counter')
+    expect(retrieved).toBe(store)
+  })
+
+  test('getStoreById returns undefined for non-existent store', () => {
+    expect(getStoreById('nope')).toBeUndefined()
+  })
+
+  test('onStoreChange fires when a store is created', () => {
+    const calls: number[] = []
+    const unsub = onStoreChange(() => calls.push(1))
+
+    const useCounter = defineStore('counter', () => ({ count: signal(0) }))
+    useCounter()
+    expect(calls.length).toBe(1)
+
+    unsub()
+  })
+
+  test('onStoreChange fires when a store is reset', () => {
+    const useCounter = defineStore('counter', () => ({ count: signal(0) }))
+    useCounter()
+
+    const calls: number[] = []
+    const unsub = onStoreChange(() => calls.push(1))
+
+    resetAllStores()
+    expect(calls.length).toBe(1)
+
+    unsub()
+  })
+
+  test('onStoreChange unsubscribe stops notifications', () => {
+    const calls: number[] = []
+    const unsub = onStoreChange(() => calls.push(1))
+    unsub()
+
+    const useCounter = defineStore('counter', () => ({ count: signal(0) }))
+    useCounter()
+    expect(calls.length).toBe(0)
+  })
+
+  test('multiple stores are tracked', () => {
+    const useA = defineStore('a', () => ({ val: signal(1) }))
+    const useB = defineStore('b', () => ({ val: signal(2) }))
+    useA()
+    useB()
+    expect(getRegisteredStores().sort()).toEqual(['a', 'b'])
+  })
+})