@deijose/nix-js 2.2.2 → 2.3.0

package/dist/lib/nix/store.d.ts

@@ -1,60 +1,125 @@
 import { Signal, type WatchOptions } from "./reactivity";
-export type StoreSignals<T extends Record<string, unknown>> = {
+/**
+ * Maps a plain state object T into a record of Signals — one per key.
+ * This is what the actions/getters factories receive as their argument.
+ *
+ * Given:   { count: number, name: string }
+ * Becomes: { count: Signal<number>, name: Signal<string> }
+ */
+export type StoreSignals<T extends object> = {
     readonly [K in keyof T]: Signal<T[K]>;
 };
+/**
+ * A read-only Signal — extends Signal so it satisfies `instanceof Signal`
+ * checks (used by `watch()`), but throws on any mutation attempt.
+ */
 export declare class ReadonlySignal<T> extends Signal<T> {
     private readonly label;
     constructor(source: Signal<T>, label?: string);
 }
+/**
+ * Maps a getters factory result (a record of Signals) into a record of
+ * read-only Signals exposed on the store.
+ *
+ * The Omit pattern enforces `readonly value` at the type level — TypeScript
+ * blocks `getter.value = x` at compile time. The runtime ReadonlySignal class
+ * also throws on mutation as defense in depth.
+ */
 export type StoreGetters<G extends Record<string, Signal<unknown>>> = {
-    readonly [K in keyof G]: ReadonlySignal<G[K] extends Signal<infer V> ? V : never>;
+    readonly [K in keyof G]: Omit<ReadonlySignal<G[K] extends Signal<infer V> ? V : never>, "value"> & {
+        readonly value: G[K] extends Signal<infer V> ? V : never;
+    };
 };
-export type Store<T extends Record<string, unknown>, A extends Record<string, unknown> = Record<never, never>, G extends Record<string, Signal<unknown>> = Record<never, never>> = StoreSignals<T> & A & StoreGetters<G> & {
+/**
+ * The full store type — combines reactive state signals, action methods,
+ * computed getters (as ReadonlySignals), and the framework-level $-prefixed API.
+ */
+export type Store<T extends object, A extends object = Record<never, never>, G extends Record<string, Signal<unknown>> = Record<never, never>> = StoreSignals<T> & A & StoreGetters<G> & {
     readonly $id: string;
-    /** Current snapshot — reading inside effect/computed creates subscription. */
+    /** Reactive snapshot — reading inside effect/computed creates a subscription to the whole state. */
     readonly $state: T;
     /**
-     * The computed Signal that backs $state.
-     * Plugins receive this to compose new reactive nodes on top.
-     * This is what makes the plugin system reactive-native:
-     * no hooks, just signals all the way down.
+     * Passive snapshot — returns the current state values WITHOUT creating
+     * a reactive subscription. Use this in plugins, loggers, persistence,
+     * or anywhere you need a one-shot read.
+     */
+    $snapshot(): T;
+    /**
+     * The computed Signal that backs $state. Plugins receive this to
+     * compose new reactive nodes on top.
      */
     readonly $stateSignal: ReadonlySignal<T>;
     /** Reset to initial values (batched). */
     $reset(): void;
     /** Partial update (batched). */
     $patch(partial: Partial<T>): void;
-    /**
-     * Watches state changes. This is exactly watch() from reactivity.ts —
-     * no new primitive to learn.
-     */
+    /** Watches state changes. Equivalent to `watch(store.$stateSignal, cb, opts)`. */
     $watch(cb: (next: T, prev: T | undefined) => void, options?: WatchOptions): () => void;
     /** Disposes the store and runs all plugin cleanups. */
     $dispose(): void;
 };
+export type ActionsFactory<T extends object, A extends object> = (signals: StoreSignals<T>) => A;
+export type GettersFactory<T extends object, G extends Record<string, Signal<unknown>>> = (signals: StoreSignals<T>) => G;
 /**
  * A NixPlugin is a function that receives the assembled store and
- * optionally returns a cleanup function.
+ * optionally returns a cleanup function called on $dispose().
  *
- * There are NO lifecycle hooks. The plugin extends the signal graph directly:
+ * There are NO lifecycle hooks. Plugins extend the signal graph directly
+ * using the framework primitives:
  *
  *   watch(store.$stateSignal, ...)        — react to any state change
  *   computed(() => store.someSignal.value) — derive new nodes
- *   store.mySignal = signal(...)           — attach new reactive state
- *   wrapMethod(store, '$patch', ...)       — intercept mutations
- *
- * Because plugins only use Nix.js primitives, they compose with each other
- * naturally — one plugin can observe a signal that another plugin added.
+ *   store.$snapshot()                      — passive read for logging/persistence
+ */
+export type NixPlugin<T extends object, A extends object = Record<never, never>, G extends Record<string, Signal<unknown>> = Record<never, never>> = (store: Store<T, A, G>) => (() => void) | void;
+/**
+ * Options object for createStore. NoInfer<T> on factory parameters ensures
+ * T is inferred ONLY from initialState, never from the factories — this is
+ * what restores the type inference that broke in v2.2.1.
  */
-export type NixPlugin<T extends Record<string, unknown>, A extends Record<string, unknown> = Record<never, never>, G extends Record<string, Signal<unknown>> = Record<never, never>> = (store: Store<T, A, G>) => (() => void) | void;
-export interface CreateStoreOptions<T extends Record<string, unknown>, A extends Record<string, unknown> = Record<never, never>, G extends Record<string, Signal<unknown>> = Record<never, never>> {
-    /** Display name for the store. Used in error messages and devtools. */
+export type CreateStoreOptions<T extends object, A extends object, G extends Record<string, Signal<unknown>>> = {
+    /** Display name. Used in error messages, devtools, and $id. */
     name?: string;
-    /** Factory that receives the raw signals and returns action methods. */
-    actions?: (signals: StoreSignals<T>) => A;
-    /** Factory that receives the raw signals and returns computed getters. */
-    getters?: (signals: StoreSignals<T>) => G;
+    /** Action factory — receives raw signals, returns methods exposed on the store. */
+    actions?: (signals: StoreSignals<NoInfer<T>>) => A;
+    /** Getter factory — receives raw signals, returns computed Signals exposed as ReadonlySignals. */
+    getters?: (signals: StoreSignals<NoInfer<T>>) => G;
     /** Plugins to extend the store. Each receives the assembled store. */
-    plugins?: NixPlugin<T, A, G>[];
-}
-export declare function createStore<T extends Record<string, unknown>, A extends Record<string, unknown> = Record<never, never>, G extends Record<string, Signal<unknown>> = Record<never, never>>(initialState: T, options?: CreateStoreOptions<T, A, G>): Store<T, A, G>;
+    plugins?: NixPlugin<NoInfer<T>, A, G>[];
+};
+/**
+ * Creates a reactive store with optional actions, getters, and plugins.
+ *
+ * @example Just state
+ * ```ts
+ * const counter = createStore({ count: 0 });
+ * counter.count.value++;
+ * ```
+ *
+ * @example State + actions
+ * ```ts
+ * const counter = createStore({ count: 0 }, {
+ *   actions: (s) => ({ increment: () => s.count.value++ }),
+ * });
+ * counter.increment();
+ * ```
+ *
+ * @example State + getters (no actions)
+ * ```ts
+ * const inventory = createStore({ items: [] as Item[] }, {
+ *   getters: (s) => ({ count: computed(() => s.items.value.length) }),
+ * });
+ * inventory.count.value;
+ * ```
+ *
+ * @example Full store
+ * ```ts
+ * const cart = createStore({ items: [] as Item[], discount: 0 }, {
+ *   name: "cart",
+ *   actions: (s) => ({ addItem: (i: Item) => { s.items.value = [...s.items.value, i] } }),
+ *   getters: (s) => ({ total: computed(() => s.items.value.reduce((sum, i) => sum + i.price, 0) * (1 - s.discount.value)) }),
+ *   plugins: [persistPlugin({ key: "cart" })],
+ * });
+ * ```
+ */
+export declare function createStore<T extends object, A extends object = Record<never, never>, G extends Record<string, Signal<unknown>> = Record<never, never>>(initialState: T, options?: CreateStoreOptions<T, A, G>): Store<T, A, G>;

package/dist/lib/store.cjs

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("./signals.cjs");var t=class extends e.Signal{label;constructor(e,t="ReadonlySignal"){super(e.peek()),this.label=t,Object.defineProperty(this,"value",{get:()=>e.value,set:()=>{throw Error(`[Nix] "${this.label}" is read-only.`)},configurable:!1}),this.update=()=>{throw Error(`[Nix] "${this.label}" is read-only.`)},this.dispose=()=>{throw Error(`[Nix] Cannot dispose "${this.label}" directly.`)}}},n=new Set(["$id","$state","$stateSignal","$reset","$patch","$watch","$dispose"]);function r(e){if("__proto__"===e||"constructor"===e||"prototype"===e)throw Error(`[Nix] Store key "${e}" is not allowed for security reasons.`);if(n.has(e))throw Error(`[Nix] Store key "${e}" is reserved.`)}function i(e,t){return!n.has(e)||(console.warn(`[Nix] Store ${t} "${e}" is reserved and will be ignored.`),!1)}function a(e,r){return new t(e,r)}function o(t,o={}){let{name:l="store",actions:s,getters:c,plugins:f=[]}=o,u=Object.keys(t),d={};for(let o of u)r(o),d[o]=e.signal(t[o]);let g,b=d,$=e.computed(()=>{let e={};for(let t of u)e[t]=d[t].value;return e}),h=a($,`store "${l}".$stateSignal`);try{g=structuredClone(t)}catch(e){throw Error(`[Nix] Store "${l}" initialState contains non-serializable data (functions, DOM nodes, Symbols, or WeakRefs). Remove these before creating the store. Original error: ${e}`)}let p=Object.assign(Object.create(null),b,{$reset:function(){e.batch(()=>{for(let e of u)d[e].value=g[e]})},$patch:function(t){e.batch(()=>{for(let e of Object.keys(t))Object.prototype.hasOwnProperty.call(d,e)&&(d[e].value=t[e])})},$watch:function(t,r){return e.watch($,t,r)}});Object.defineProperty(p,"$id",{value:l,writable:!1,enumerable:!1,configurable:!1}),Object.defineProperty(p,"$state",{get:()=>$.value,enumerable:!0,configurable:!1}),Object.defineProperty(p,"$stateSignal",{value:h,writable:!1,enumerable:!1,configurable:!1});let y=new Set([...u,...Array.from(n)]);if(s){let e=s(b);for(let t of Object.keys(e))if(i(t,"action")){if(y.has(t)){console.warn(`[Nix] Store "${l}": action "${t}" collides with an existing signal or getter and will be ignored.`);continue}y.add(t),p[t]=e[t]}}if(c){let t=c(b);for(let r of Object.keys(t)){if(!i(r,"getter"))continue;if(y.has(r)){console.warn(`[Nix] Store "${l}": getter "${r}" collides with an existing signal or action and will be ignored.`);continue}let o=t[r];if(!(o instanceof e.Signal))throw TypeError(`[Nix] Store "${l}": getter "${r}" must return a Signal (wrap it with computed()). Got: ${typeof o}`);y.add(r),p[r]=a(o,`getter "${r}" in store "${l}"`)}}let w=[()=>$.dispose()];for(let e of f)try{let t=e(p);"function"==typeof t&&w.push(t)}catch(e){console.error(`[Nix] Plugin initialization failed for store "${l}":`,e)}return p.$dispose=()=>{for(let e of w)e()},p}exports.ReadonlySignal=t,exports.createStore=o;
+Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("./signals.cjs");var t=class extends e.Signal{label;constructor(e,t="ReadonlySignal"){super(e.peek()),this.label=t,Object.defineProperty(this,"value",{get:()=>e.value,set:()=>{throw Error(`[Nix] "${this.label}" is read-only.`)},configurable:!1}),this.update=()=>{throw Error(`[Nix] "${this.label}" is read-only.`)},this.dispose=()=>{throw Error(`[Nix] Cannot dispose "${this.label}" directly.`)}}},n=new Set(["$id","$state","$stateSignal","$snapshot","$reset","$patch","$watch","$dispose"]);function r(e){if("__proto__"===e||"constructor"===e||"prototype"===e)throw Error(`[Nix] Store key "${e}" is not allowed for security reasons.`);if(n.has(e))throw Error(`[Nix] Store key "${e}" is reserved.`)}function i(e,t){return!n.has(e)||(console.warn(`[Nix] Store ${t} "${e}" is reserved and will be ignored.`),!1)}function a(e,r){return new t(e,r)}function o(t,o){let{name:l="store",actions:s,getters:c,plugins:f=[]}=o??{},u=Object.keys(t),d={};for(let o of u)r(o),d[o]=e.signal(t[o]);let $,g=d,h=e.computed(()=>{let e={};for(let t of u)e[t]=d[t].value;return e}),b=a(h,`store "${l}".$stateSignal`);try{$=structuredClone(t)}catch(e){throw Error(`[Nix] Store "${l}" initialState contains non-serializable data (functions, DOM nodes, Symbols, or WeakRefs). Remove these before creating the store. Original error: ${e}`)}let p=Object.assign(Object.create(null),g,{$reset:function(){e.batch(()=>{for(let e of u)d[e].value=$[e]})},$patch:function(t){e.batch(()=>{for(let e of Object.keys(t))Object.prototype.hasOwnProperty.call(d,e)&&(d[e].value=t[e])})},$watch:function(t,r){return e.watch(h,t,r)},$snapshot:function(){let e={};for(let t of u)e[t]=d[t].peek();return e}});Object.defineProperty(p,"$id",{value:l,writable:!1,enumerable:!1,configurable:!1}),Object.defineProperty(p,"$state",{get:()=>h.value,enumerable:!0,configurable:!1}),Object.defineProperty(p,"$stateSignal",{value:b,writable:!1,enumerable:!1,configurable:!1});let y=new Set([...u,...Array.from(n)]);if(s){let e=s(g);for(let t of Object.keys(e))if(i(t,"action")){if(y.has(t)){console.warn(`[Nix] Store "${l}": action "${t}" collides with an existing signal or getter and will be ignored.`);continue}y.add(t),p[t]=e[t]}}if(c){let t=c(g);for(let r of Object.keys(t)){if(!i(r,"getter"))continue;if(y.has(r)){console.warn(`[Nix] Store "${l}": getter "${r}" collides with an existing signal or action and will be ignored.`);continue}let o=t[r];if(!(o instanceof e.Signal))throw TypeError(`[Nix] Store "${l}": getter "${r}" must return a Signal (wrap it with computed()). Got: ${typeof o}`);y.add(r),p[r]=a(o,`getter "${r}" in store "${l}"`)}}let w=[()=>h.dispose()];for(let e of f)try{let t=e(p);"function"==typeof t&&w.push(t)}catch(e){console.error(`[Nix] Plugin initialization failed for store "${l}":`,e)}return p.$dispose=()=>{for(let e of w)e()},p}exports.ReadonlySignal=t,exports.createStore=o;

package/dist/lib/store.js

@@ -1 +1 @@
-import{Signal as e,batch as t,computed as n,signal as r,watch as i}from"./signals.js";var a=class extends e{label;constructor(e,t="ReadonlySignal"){super(e.peek()),this.label=t,Object.defineProperty(this,"value",{get:()=>e.value,set:()=>{throw Error(`[Nix] "${this.label}" is read-only.`)},configurable:!1}),this.update=()=>{throw Error(`[Nix] "${this.label}" is read-only.`)},this.dispose=()=>{throw Error(`[Nix] Cannot dispose "${this.label}" directly.`)}}},o=new Set(["$id","$state","$stateSignal","$reset","$patch","$watch","$dispose"]);function s(e){if("__proto__"===e||"constructor"===e||"prototype"===e)throw Error(`[Nix] Store key "${e}" is not allowed for security reasons.`);if(o.has(e))throw Error(`[Nix] Store key "${e}" is reserved.`)}function c(e,t){return!o.has(e)||(console.warn(`[Nix] Store ${t} "${e}" is reserved and will be ignored.`),!1)}function l(e,t){return new a(e,t)}function u(a,f={}){let{name:u="store",actions:d,getters:$,plugins:g=[]}=f,h=Object.keys(a),b={};for(let e of h)s(e),b[e]=r(a[e]);let p,w=b,y=n(()=>{let e={};for(let t of h)e[t]=b[t].value;return e}),S=l(y,`store "${u}".$stateSignal`);try{p=structuredClone(a)}catch(e){throw Error(`[Nix] Store "${u}" initialState contains non-serializable data (functions, DOM nodes, Symbols, or WeakRefs). Remove these before creating the store. Original error: ${e}`)}let x=Object.assign(Object.create(null),w,{$reset:function(){t(()=>{for(let e of h)b[e].value=p[e]})},$patch:function(e){t(()=>{for(let t of Object.keys(e))Object.prototype.hasOwnProperty.call(b,t)&&(b[t].value=e[t])})},$watch:function(e,t){return i(y,e,t)}});Object.defineProperty(x,"$id",{value:u,writable:!1,enumerable:!1,configurable:!1}),Object.defineProperty(x,"$state",{get:()=>y.value,enumerable:!0,configurable:!1}),Object.defineProperty(x,"$stateSignal",{value:S,writable:!1,enumerable:!1,configurable:!1});let O=new Set([...h,...Array.from(o)]);if(d){let e=d(w);for(let t of Object.keys(e))if(c(t,"action")){if(O.has(t)){console.warn(`[Nix] Store "${u}": action "${t}" collides with an existing signal or getter and will be ignored.`);continue}O.add(t),x[t]=e[t]}}if($){let t=$(w);for(let r of Object.keys(t)){if(!c(r,"getter"))continue;if(O.has(r)){console.warn(`[Nix] Store "${u}": getter "${r}" collides with an existing signal or action and will be ignored.`);continue}let o=t[r];if(!(o instanceof e))throw TypeError(`[Nix] Store "${u}": getter "${r}" must return a Signal (wrap it with computed()). Got: ${typeof o}`);O.add(r),x[r]=l(o,`getter "${r}" in store "${u}"`)}}let j=[()=>y.dispose()];for(let e of g)try{let t=e(x);"function"==typeof t&&j.push(t)}catch(e){console.error(`[Nix] Plugin initialization failed for store "${u}":`,e)}return x.$dispose=()=>{for(let e of j)e()},x}export{a as ReadonlySignal,u as createStore};
+import{Signal as e,batch as t,computed as n,signal as r,watch as i}from"./signals.js";var a=class extends e{label;constructor(e,t="ReadonlySignal"){super(e.peek()),this.label=t,Object.defineProperty(this,"value",{get:()=>e.value,set:()=>{throw Error(`[Nix] "${this.label}" is read-only.`)},configurable:!1}),this.update=()=>{throw Error(`[Nix] "${this.label}" is read-only.`)},this.dispose=()=>{throw Error(`[Nix] Cannot dispose "${this.label}" directly.`)}}},o=new Set(["$id","$state","$stateSignal","$snapshot","$reset","$patch","$watch","$dispose"]);function s(e){if("__proto__"===e||"constructor"===e||"prototype"===e)throw Error(`[Nix] Store key "${e}" is not allowed for security reasons.`);if(o.has(e))throw Error(`[Nix] Store key "${e}" is reserved.`)}function c(e,t){return!o.has(e)||(console.warn(`[Nix] Store ${t} "${e}" is reserved and will be ignored.`),!1)}function l(e,t){return new a(e,t)}function u(a,f){let{name:u="store",actions:d,getters:$,plugins:h=[]}=f??{},g=Object.keys(a),p={};for(let e of g)s(e),p[e]=r(a[e]);let b,w=p,y=n(()=>{let e={};for(let t of g)e[t]=p[t].value;return e}),S=l(y,`store "${u}".$stateSignal`);try{b=structuredClone(a)}catch(e){throw Error(`[Nix] Store "${u}" initialState contains non-serializable data (functions, DOM nodes, Symbols, or WeakRefs). Remove these before creating the store. Original error: ${e}`)}let x=Object.assign(Object.create(null),w,{$reset:function(){t(()=>{for(let e of g)p[e].value=b[e]})},$patch:function(e){t(()=>{for(let t of Object.keys(e))Object.prototype.hasOwnProperty.call(p,t)&&(p[t].value=e[t])})},$watch:function(e,t){return i(y,e,t)},$snapshot:function(){let e={};for(let t of g)e[t]=p[t].peek();return e}});Object.defineProperty(x,"$id",{value:u,writable:!1,enumerable:!1,configurable:!1}),Object.defineProperty(x,"$state",{get:()=>y.value,enumerable:!0,configurable:!1}),Object.defineProperty(x,"$stateSignal",{value:S,writable:!1,enumerable:!1,configurable:!1});let O=new Set([...g,...Array.from(o)]);if(d){let e=d(w);for(let t of Object.keys(e))if(c(t,"action")){if(O.has(t)){console.warn(`[Nix] Store "${u}": action "${t}" collides with an existing signal or getter and will be ignored.`);continue}O.add(t),x[t]=e[t]}}if($){let t=$(w);for(let r of Object.keys(t)){if(!c(r,"getter"))continue;if(O.has(r)){console.warn(`[Nix] Store "${u}": getter "${r}" collides with an existing signal or action and will be ignored.`);continue}let o=t[r];if(!(o instanceof e))throw TypeError(`[Nix] Store "${u}": getter "${r}" must return a Signal (wrap it with computed()). Got: ${typeof o}`);O.add(r),x[r]=l(o,`getter "${r}" in store "${u}"`)}}let j=[()=>y.dispose()];for(let e of h)try{let t=e(x);"function"==typeof t&&j.push(t)}catch(e){console.error(`[Nix] Plugin initialization failed for store "${u}":`,e)}return x.$dispose=()=>{for(let e of j)e()},x}export{a as ReadonlySignal,u as createStore};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deijose/nix-js",
-  "version": "2.2.2",
+  "version": "2.3.0",
   "description": "A lightweight, fully reactive micro-framework — no virtual DOM, no compiler, just signals and tagged templates.",
   "license": "MIT",
   "author": "Deiver Vasquez",