kerfjs 0.9.1 → 0.11.0

package/dist/{testing-CdMgVVoI.d.ts → testing-DNEY7wi3.d.ts}

@@ -30,7 +30,7 @@ interface Store<TState, TActions> {
 }
 interface DefineStoreSpec<TState, TActions> {
     initial: () => TState;
-    actions: (set: (next: TState) => void, get: () => TState) => TActions;
+    actions: (set: (next: TState) => void, get: () => Readonly<TState>) => TActions;
 }
 declare function defineStore<TState, TActions>(spec: DefineStoreSpec<TState, TActions>): Store<TState, TActions>;
 /**

package/dist/testing.d.ts

@@ -1,2 +1,2 @@
-export { c as clearStoreRegistry } from './testing-CdMgVVoI.js';
+export { c as clearStoreRegistry } from './testing-DNEY7wi3.js';
 import '@preact/signals-core';

package/dist/testing.js

@@ -1,4 +1,4 @@
-export { clearStoreRegistry } from './chunk-WUFUTNA7.js';
+export { clearStoreRegistry } from './chunk-IBVKW6WU.js';
 import './chunk-UU2YJEJY.js';
 //# sourceMappingURL=testing.js.map
 //# sourceMappingURL=testing.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kerfjs",
-  "version": "0.9.1",
+  "version": "0.11.0",
   "description": "Tiny reactive UI framework — fine-grained signals + DOM morphing + JSX. Apply the smallest possible cut to update your DOM.",
   "type": "module",
   "sideEffects": false,
@@ -48,7 +48,8 @@
     "./array-signal": {
       "types": "./dist/array-signal.d.ts",
       "import": "./dist/array-signal.js"
-    }
+    },
+    "./ai/*": "./ai/*"
   },
   "files": [
     "dist",

package/dist/chunk-WUFUTNA7.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/dev-store-warn.ts","../src/store.ts"],"names":[],"mappings":"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","file":"chunk-WUFUTNA7.js","sourcesContent":["/**\n * Dev-mode warning for partial-set violations of Hard Rule 8 (KF-212). When\n * the opt-in env var `KERF_DEV_WARN_NARROW_SET=1` is set in a non-production\n * build, `defineStore`'s `set()` calls `maybeWarnNarrowSet(prev, next, ctx)`\n * before assigning. If `next` is a plain object whose own-keys are a strict\n * subset of `prev`'s own-keys, a one-shot `console.warn` fires naming the\n * missing keys and pointing at the canonical `set({ ...get(), ...next })`\n * merge fix.\n *\n * Why opt-in: narrow-set IS legal — sometimes you want to replace state with\n * a smaller shape (a reset() that drops keys, a feature-flag-driven schema\n * change). The warn is the right shape for the canonical bug (\"I wrote\n * `set({filter})` against a replace-semantics store and wiped items+editingId\")\n * but produces false positives for intentional shape changes. Opt-in keeps\n * the warning available to dev/CI environments that want the diagnostic\n * without surprising existing projects.\n *\n * Trigger condition: ANY key in `prev` missing from `next` — strictly broader\n * than \"fewer keys total.\" A `set({a, c})` against `cur = {a, b}` (same count,\n * different keys) also wipes `b`, so it warns. The original partial-set bug\n * shape was always \"at least one key from current is missing in next\"; the\n * key-count check in the original ticket sketch was an early-exit\n * optimization, not the semantic gate.\n *\n * Skips: non-object cur/next (booleans, numbers, strings — no \"keys\" to\n * miss), null/undefined either side, and arrays either side (shrinking-array\n * replacement is normal, not a partial set).\n *\n * Per-store one-shot dedup: each store warns at most once across its\n * lifetime — matches the KF-174 / KF-176 pattern of \"tell the developer\n * about the rule violation once, then trust them to fix it.\" The dedup\n * scope is the store, not the module, so a second store can still warn\n * if it independently hits the same bug.\n *\n * Production behavior is unchanged for zero runtime cost (the env-var read\n * short-circuits before any per-set work runs).\n */\n\nexport interface NarrowSetWarnContext {\n  /** Set once per store; the warner reads/writes this to enforce the per-store one-shot dedup. */\n  warned: boolean;\n}\n\nconst WARNING_PREFIX\n  = 'kerf: defineStore.set() called with keys missing from the current state — ';\nconst WARNING_SUFFIX\n  = '. set() REPLACES state; the missing keys will be undefined after this call. '\n  + 'Use `set({ ...get(), ...next })` to merge instead, or update each call site to pass the full state. '\n  + 'Set KERF_DEV_WARN_NARROW_SET=0 (or unset it) to silence this warning.';\n\nexport function isOptedIn(): boolean {\n  const proc = (globalThis as { process?: { env?: Record<string, string | undefined> } }).process;\n  if (proc?.env?.NODE_ENV === 'production') return false;\n  return proc?.env?.KERF_DEV_WARN_NARROW_SET === '1';\n}\n\nfunction isPlainObjectState(v: unknown): v is Record<string, unknown> {\n  if (v === null || typeof v !== 'object') return false;\n  if (Array.isArray(v)) return false;\n  return true;\n}\n\nexport function maybeWarnNarrowSet(\n  prev: unknown,\n  next: unknown,\n  ctx: NarrowSetWarnContext,\n): void {\n  if (ctx.warned) return;\n  if (!isOptedIn()) return;\n  if (!isPlainObjectState(prev) || !isPlainObjectState(next)) return;\n\n  const missing: string[] = [];\n  for (const k of Object.keys(prev)) {\n    if (!(k in next)) missing.push(k);\n  }\n  if (missing.length === 0) return;\n\n  ctx.warned = true;\n  const keysList = missing.map((k) => `\\`${k}\\``).join(', ');\n  console.warn(`${WARNING_PREFIX}${keysList}${WARNING_SUFFIX}`);\n}\n\n/**\n * Test helper — resets the per-store `warned` flag on a context so a\n * subsequent test in the same module can re-exercise the first-warning\n * path. Not exported from the public barrel; the unit-test file imports it\n * directly via the relative path.\n */\nexport function _resetWarnContext(ctx: NarrowSetWarnContext): void {\n  ctx.warned = false;\n}\n","/**\n * `defineStore({ initial, actions })` — composable testable stores layered on\n * top of `reactive.ts`'s signals.\n *\n * Three rules:\n * 1. `state` is read-only. Consumers read via `state.value` or subscribe via\n *    `effect()`. They cannot write directly.\n * 2. `actions` is the only mutation surface. All writes go through named\n *    action functions. This is what makes stores testable — assert against\n *    actions, not against arbitrary writes.\n * 3. `reset()` resets to `initial()`. Always defined; tests use it for\n *    setup, lifecycle hooks (route change, sign-out, etc.) use it for\n *    tear-down.\n *\n * A module-level registry tracks every store created via `defineStore()`;\n * `resetAllStores()` walks the registry and calls each `reset()`. Useful for\n * tests + project-switch / logout / route-reset scenarios where every piece\n * of client state should return to its initial shape.\n */\n\nimport { maybeWarnNarrowSet, type NarrowSetWarnContext } from './dev-store-warn.js';\nimport type { ReadonlySignal, Signal } from './reactive.js';\nimport { signal } from './reactive.js';\n\nexport interface Store<TState, TActions> {\n  /** Read-only reactive view. Consumers read `state.value` or subscribe via `effect()`. */\n  readonly state: ReadonlySignal<TState>;\n  /** Named mutators — the only way to change state. */\n  readonly actions: TActions;\n  /** Reset state to `initial()`. Used by tests and lifecycle hooks. */\n  reset(): void;\n}\n\ninterface DefineStoreSpec<TState, TActions> {\n  initial: () => TState;\n  actions: (set: (next: TState) => void, get: () => TState) => TActions;\n}\n\nconst REGISTRY: Array<{ reset: () => void }> = [];\n\nconst IS_DEV: boolean = (() => {\n  const proc = (globalThis as { process?: { env?: { NODE_ENV?: string } } }).process;\n  return proc?.env?.NODE_ENV !== 'production';\n})();\n\nexport function defineStore<TState, TActions>(\n  spec: DefineStoreSpec<TState, TActions>,\n): Store<TState, TActions> {\n  const internal: Signal<TState> = signal(spec.initial());\n  // KF-212: per-store one-shot dedup for the opt-in narrow-set warning.\n  // Default off; consumers opt in via `KERF_DEV_WARN_NARROW_SET=1` in dev.\n  // Production behavior is unchanged — `maybeWarnNarrowSet` short-circuits\n  // on the env-var read before any per-set work runs.\n  const warnCtx: NarrowSetWarnContext = { warned: false };\n\n  const set = (next: TState): void => {\n    maybeWarnNarrowSet(internal.value, next, warnCtx);\n    internal.value = next;\n  };\n  // In dev, freeze the snapshot returned to actions so that\n  // `get().count = 42`-style mutations (a documented Rule 8 violation) throw\n  // a native `TypeError: Cannot assign to read only property` instead of\n  // silently landing on the underlying state without notifying subscribers.\n  // Production keeps the bare reference for zero overhead. Read NODE_ENV via\n  // globalThis so the source works untouched in browsers (no bare `process`).\n  const get = (): TState => {\n    const v = internal.value;\n    if (IS_DEV && v !== null && typeof v === 'object') {\n      Object.freeze(v);\n    }\n    return v;\n  };\n\n  const actions = spec.actions(set, get);\n\n  const store: Store<TState, TActions> = {\n    state: internal,\n    actions,\n    reset() {\n      internal.value = spec.initial();\n    },\n  };\n\n  REGISTRY.push(store);\n  return store;\n}\n\n/**\n * Reset every store registered via `defineStore()` to its `initial()` value.\n * Used by tests and by application lifecycle hooks (project switch, logout,\n * route reset).\n */\nexport function resetAllStores(): void {\n  for (const s of REGISTRY) s.reset();\n}\n\n/**\n * Test helper — clears the registry. Exposed via the `kerfjs/testing` subpath,\n * not the main `kerfjs` entry. Unit tests use it to isolate stores between cases.\n */\nexport function clearStoreRegistry(): void {\n  REGISTRY.length = 0;\n}\n"]}