@thefoxieflow/signalctx 0.0.1 → 0.1.0

package/README.md

@@ -1,4 +1,4 @@
-# signal-ctx
+# signalctx
 
 A tiny, signal-based state utility for React that **solves the `useContext` re-render problem** using
 **`useSyncExternalStore`**.
@@ -10,7 +10,7 @@ If you’ve ever had this issue:
 // updating count re-renders book components 😡
 ```
 
-`signal-ctx` is designed specifically to fix that.
+`signalctx` is designed specifically to fix that.
 
 ---
 
@@ -57,7 +57,7 @@ So only the components that *actually use* the changed data re-render.
 ## 📦 Installation
 
 ```bash
-npm install @thefoxieflow/signal-ctx
+npm install @thefoxieflow/signalctx
 ```
 
 > **Peer dependency:** React 18+
@@ -100,12 +100,12 @@ type Store<T> = {
 
 ### `createStore(()=>{})`
 
-### `useStoreValue(store, selector?)`
+### `useValue(store, selector?)`
 
 Subscribe to a signal.
 
 ```tsx
-const count = useStoreValue(store, s => s.count)
+const count = useValue(store, s => s.count)
 ```
 
 * Uses `useSyncExternalStore`
@@ -114,12 +114,12 @@ const count = useStoreValue(store, s => s.count)
 
 ---
 
-### `useSetStore(store, selector?)`
+### `useSet(store, selector?)`
 
 Returns a setter function.
 
 ```ts
-const set = useSetStore(store)
+const set = useSet(store)
 
 set(prev => ({ ...prev, count: prev.count + 1 }))
 ```
@@ -327,7 +327,7 @@ Each store is independent.
 
 ## 🌐 Server-Side Rendering (SSR)
 
-`signal-ctx` is SSR-safe.
+`signalctx` is SSR-safe.
 
 * Uses `useSyncExternalStore`
 * Identical snapshot logic on server & client
@@ -368,7 +368,7 @@ MIT
 
 ## ⭐ Philosophy
 
-`signal-ctx` is intentionally small.
+`signalctx` is intentionally small.
 
 It favors:
 
@@ -376,4 +376,4 @@ It favors:
 * Predictable updates
 * Minimal abstraction
 
-If you understand React, you understand `signal-ctx`.
+If you understand React, you understand `signalctx`.

package/dist/index.d.mts

@@ -1,18 +1,38 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { SetStateAction, ReactNode } from 'react';
+import { PropsWithChildren } from 'react';
 
-type Store<T = any> = ReturnType<typeof createStore<T>>;
+type SetStateAction<T> = T | ((prev: T) => T);
 type Subscriber = () => void;
+/** for controlling store internal state without notifying subscribers
+ * @function calling the store internal state reference
+ * @method on subscribe to state changes
+ * @method set update the state without notifying subscribers
+ * @method reset reset the state to initial value without notifying subscribers
+ * @method notify manually notify all subscribers
+ */
+type InnerStore<T> = {
+    (): T;
+    on: (sub: Subscriber) => () => void;
+    notify: () => void;
+    reset: () => void;
+    set: (action: SetStateAction<T>) => void;
+};
 /**
- * @description: create a signal with subscribe and update methods
+ * @function calling the store returns a copy of the internal state
+ * @method on subscribe to state changes
+ * @method set update the state with notifying subscribers
+ * @method reset reset the state to initial value with notifying subscribers
+ * @property $ access to non-notifying methods
  */
-declare function createStore<T = Record<string, any>>(init: () => T): {
+type Store<T> = {
     (): T;
-    subscribe(subscriber: Subscriber): () => boolean;
-    set(action: SetStateAction<T>): void;
+    on: (sub: Subscriber) => () => void;
+    reset: () => void;
+    set: (action: SetStateAction<T>) => void;
+    $: InnerStore<T>;
 };
-declare const useStoreValue: <T extends object, Dest = T>(store: Store<T>, selector?: (state: T) => Dest) => Dest;
-declare const useSetStore: <T extends object = any, Dest extends object = T>(store: Store<T>, selector?: (state: T) => Dest) => (action: SetStateAction<Dest>) => void;
+declare const useValue: <T extends object, Dest = T>(store: Store<T>, selector?: (state: T) => Dest) => Dest;
+declare const useSet: <T extends object = any, Dest extends object = T>(store: Store<T>, selector?: (state: T) => Dest) => (action: SetStateAction<Dest>) => Dest;
 type StoreOption = {
     storeName?: string;
 };
@@ -21,15 +41,9 @@ declare function createCtx<T extends object>(init: () => T): {
     provide: (opt?: {
         value?: T;
         storeName?: string;
-    }) => ({ children }: {
-        children: ReactNode;
-    }) => react_jsx_runtime.JSX.Element;
-    useSetter: <Dest extends object = T>(selector?: (state: T) => Dest, opt?: StoreOption) => (action: SetStateAction<Dest>) => void;
-    useStore: (opt?: StoreOption) => {
-        (): T;
-        subscribe(subscriber: Subscriber): () => boolean;
-        set(action: SetStateAction<T>): void;
-    };
+    }) => ({ children }: PropsWithChildren) => react_jsx_runtime.JSX.Element;
+    useSet: <Dest extends object = T>(selector?: (state: T) => Dest, opt?: StoreOption) => (action: SetStateAction<Dest>) => Dest;
+    useStore: (opt?: StoreOption) => Store<T>;
 };
 
-export { type Store, type StoreOption, type Subscriber, createCtx, useSetStore, useStoreValue };
+export { type InnerStore, type SetStateAction, type Store, type Subscriber, createCtx, useSet, useValue };

package/dist/index.d.ts

@@ -1,18 +1,38 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { SetStateAction, ReactNode } from 'react';
+import { PropsWithChildren } from 'react';
 
-type Store<T = any> = ReturnType<typeof createStore<T>>;
+type SetStateAction<T> = T | ((prev: T) => T);
 type Subscriber = () => void;
+/** for controlling store internal state without notifying subscribers
+ * @function calling the store internal state reference
+ * @method on subscribe to state changes
+ * @method set update the state without notifying subscribers
+ * @method reset reset the state to initial value without notifying subscribers
+ * @method notify manually notify all subscribers
+ */
+type InnerStore<T> = {
+    (): T;
+    on: (sub: Subscriber) => () => void;
+    notify: () => void;
+    reset: () => void;
+    set: (action: SetStateAction<T>) => void;
+};
 /**
- * @description: create a signal with subscribe and update methods
+ * @function calling the store returns a copy of the internal state
+ * @method on subscribe to state changes
+ * @method set update the state with notifying subscribers
+ * @method reset reset the state to initial value with notifying subscribers
+ * @property $ access to non-notifying methods
  */
-declare function createStore<T = Record<string, any>>(init: () => T): {
+type Store<T> = {
     (): T;
-    subscribe(subscriber: Subscriber): () => boolean;
-    set(action: SetStateAction<T>): void;
+    on: (sub: Subscriber) => () => void;
+    reset: () => void;
+    set: (action: SetStateAction<T>) => void;
+    $: InnerStore<T>;
 };
-declare const useStoreValue: <T extends object, Dest = T>(store: Store<T>, selector?: (state: T) => Dest) => Dest;
-declare const useSetStore: <T extends object = any, Dest extends object = T>(store: Store<T>, selector?: (state: T) => Dest) => (action: SetStateAction<Dest>) => void;
+declare const useValue: <T extends object, Dest = T>(store: Store<T>, selector?: (state: T) => Dest) => Dest;
+declare const useSet: <T extends object = any, Dest extends object = T>(store: Store<T>, selector?: (state: T) => Dest) => (action: SetStateAction<Dest>) => Dest;
 type StoreOption = {
     storeName?: string;
 };
@@ -21,15 +41,9 @@ declare function createCtx<T extends object>(init: () => T): {
     provide: (opt?: {
         value?: T;
         storeName?: string;
-    }) => ({ children }: {
-        children: ReactNode;
-    }) => react_jsx_runtime.JSX.Element;
-    useSetter: <Dest extends object = T>(selector?: (state: T) => Dest, opt?: StoreOption) => (action: SetStateAction<Dest>) => void;
-    useStore: (opt?: StoreOption) => {
-        (): T;
-        subscribe(subscriber: Subscriber): () => boolean;
-        set(action: SetStateAction<T>): void;
-    };
+    }) => ({ children }: PropsWithChildren) => react_jsx_runtime.JSX.Element;
+    useSet: <Dest extends object = T>(selector?: (state: T) => Dest, opt?: StoreOption) => (action: SetStateAction<Dest>) => Dest;
+    useStore: (opt?: StoreOption) => Store<T>;
 };
 
-export { type Store, type StoreOption, type Subscriber, createCtx, useSetStore, useStoreValue };
+export { type InnerStore, type SetStateAction, type Store, type Subscriber, createCtx, useSet, useValue };

package/dist/index.js

@@ -21,48 +21,71 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   createCtx: () => createCtx,
-  useSetStore: () => useSetStore,
-  useStoreValue: () => useStoreValue
+  useSet: () => useSet,
+  useValue: () => useValue
 });
 module.exports = __toCommonJS(index_exports);
 var import_react = require("react");
 var import_jsx_runtime = require("react/jsx-runtime");
-var applyAction = (target, action) => {
-  return typeof action === "function" ? action(target) : action;
+var createInnerStore = (init) => {
+  let ref;
+  const subs = /* @__PURE__ */ new Set();
+  const store = () => ref || (ref = init());
+  store.set = (action) => {
+    apply(store(), action);
+  };
+  store.reset = () => {
+    ref = init();
+  };
+  store.notify = () => {
+    subs.forEach((sub) => sub());
+  };
+  store.on = (sub) => {
+    subs.add(sub);
+    return () => subs.delete(sub);
+  };
+  return store;
+};
+var isFunction = (val) => typeof val === "function";
+var setTargetValue = (target, newVal) => {
+  if (Object.is(target, newVal)) return target;
+  Object.keys(target).forEach((k) => delete target[k]);
+  Object.keys(newVal).forEach((k) => target[k] = newVal[k]);
+  return target;
+};
+var apply = (target, action) => {
+  const val = isFunction(action) ? action(target) : action;
+  return setTargetValue(target, val);
 };
 function createStore(init) {
-  let val;
-  let isInit = false;
-  const subscribers = /* @__PURE__ */ new Set();
-  const get = () => {
-    if (!isInit) {
-      val = init();
-      isInit = true;
-    }
-    return val;
+  const $ = createInnerStore(init);
+  const store = () => {
+    const ref = $();
+    return { ...ref };
   };
-  get.subscribe = (subscriber) => {
-    subscribers.add(subscriber);
-    const unsubscribe = () => subscribers.delete(subscriber);
-    return unsubscribe;
+  store.reset = () => {
+    $.reset();
+    $.notify();
   };
-  get.set = (action) => {
-    val = applyAction(val, action);
-    subscribers.forEach((subscriber) => subscriber());
+  store.set = (action) => {
+    $.set(action);
+    $.notify();
   };
-  return get;
+  store.on = $.on;
+  store.$ = $;
+  return store;
 }
-var useStoreValue = (store, selector) => {
-  const getSnapShot = () => selector ? selector(store()) : store();
-  const use = (0, import_react.useSyncExternalStore)(store.subscribe, getSnapShot, getSnapShot);
-  return use;
+var useValue = (store, selector) => {
+  const get = () => selector ? selector(store()) : store();
+  return (0, import_react.useSyncExternalStore)(store.on, get, get);
 };
-var useSetStore = (store, selector) => {
+var useSet = (store, selector) => {
   const setter = (action) => {
     const current = store();
     const target = selector ? selector(current) : current;
-    applyAction(target, action);
+    apply(target, action);
     store.set(current);
+    return target;
   };
   return setter;
 };
@@ -70,29 +93,22 @@ function createCtx(init) {
   const ctx = (0, import_react.createContext)(createStore(init));
   const stores = /* @__PURE__ */ new Map();
   const initStore = (name, init2) => {
-    if (!stores.has(name)) {
-      const store = createStore(init2);
-      stores.set(name, store);
-    }
+    if (!stores.has(name)) stores.set(name, createStore(init2));
     return stores.get(name);
   };
   const useStore = (opt) => {
     const store = (0, import_react.useContext)(ctx);
-    if (opt?.storeName && stores.has(opt.storeName)) {
-      return stores.get(opt.storeName);
-    }
+    if (opt?.storeName && stores.has(opt.storeName)) return stores.get(opt.storeName);
     if (!store) throw new Error("useCtx must be used within a Provider");
     return store;
   };
   const provide = (opt = {}) => {
-    const value = opt.value || init();
+    const storeInit = opt.value ? () => opt.value : init;
     const storeName = opt.storeName || "ctx__store";
     const Provider = ({ children }) => {
-      const store = initStore(storeName, () => value);
-      (0, import_react.useEffect)(() => {
-        return () => {
-          stores.delete(storeName);
-        };
+      const store = initStore(storeName, storeInit);
+      (0, import_react.useEffect)(() => () => {
+        stores.delete(storeName);
       }, []);
       return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(ctx.Provider, { value: store, children });
     };
@@ -100,20 +116,20 @@ function createCtx(init) {
   };
   const use = (selector, opt) => {
     const store = useStore(opt);
-    return useStoreValue(store, selector);
+    return useValue(store, selector);
   };
   const useSetter = (selector, opt) => {
     const store = useStore(opt);
-    return useSetStore(store, selector);
+    return useSet(store, selector);
   };
   use.provide = provide;
-  use.useSetter = useSetter;
+  use.useSet = useSetter;
   use.useStore = useStore;
   return use;
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   createCtx,
-  useSetStore,
-  useStoreValue
+  useSet,
+  useValue
 });

package/dist/index.mjs

@@ -6,42 +6,65 @@ import {
   useSyncExternalStore
 } from "react";
 import { jsx } from "react/jsx-runtime";
-var applyAction = (target, action) => {
-  return typeof action === "function" ? action(target) : action;
+var createInnerStore = (init) => {
+  let ref;
+  const subs = /* @__PURE__ */ new Set();
+  const store = () => ref || (ref = init());
+  store.set = (action) => {
+    apply(store(), action);
+  };
+  store.reset = () => {
+    ref = init();
+  };
+  store.notify = () => {
+    subs.forEach((sub) => sub());
+  };
+  store.on = (sub) => {
+    subs.add(sub);
+    return () => subs.delete(sub);
+  };
+  return store;
+};
+var isFunction = (val) => typeof val === "function";
+var setTargetValue = (target, newVal) => {
+  if (Object.is(target, newVal)) return target;
+  Object.keys(target).forEach((k) => delete target[k]);
+  Object.keys(newVal).forEach((k) => target[k] = newVal[k]);
+  return target;
+};
+var apply = (target, action) => {
+  const val = isFunction(action) ? action(target) : action;
+  return setTargetValue(target, val);
 };
 function createStore(init) {
-  let val;
-  let isInit = false;
-  const subscribers = /* @__PURE__ */ new Set();
-  const get = () => {
-    if (!isInit) {
-      val = init();
-      isInit = true;
-    }
-    return val;
+  const $ = createInnerStore(init);
+  const store = () => {
+    const ref = $();
+    return { ...ref };
   };
-  get.subscribe = (subscriber) => {
-    subscribers.add(subscriber);
-    const unsubscribe = () => subscribers.delete(subscriber);
-    return unsubscribe;
+  store.reset = () => {
+    $.reset();
+    $.notify();
   };
-  get.set = (action) => {
-    val = applyAction(val, action);
-    subscribers.forEach((subscriber) => subscriber());
+  store.set = (action) => {
+    $.set(action);
+    $.notify();
   };
-  return get;
+  store.on = $.on;
+  store.$ = $;
+  return store;
 }
-var useStoreValue = (store, selector) => {
-  const getSnapShot = () => selector ? selector(store()) : store();
-  const use = useSyncExternalStore(store.subscribe, getSnapShot, getSnapShot);
-  return use;
+var useValue = (store, selector) => {
+  const get = () => selector ? selector(store()) : store();
+  return useSyncExternalStore(store.on, get, get);
 };
-var useSetStore = (store, selector) => {
+var useSet = (store, selector) => {
   const setter = (action) => {
     const current = store();
     const target = selector ? selector(current) : current;
-    applyAction(target, action);
+    apply(target, action);
     store.set(current);
+    return target;
   };
   return setter;
 };
@@ -49,29 +72,22 @@ function createCtx(init) {
   const ctx = createContext(createStore(init));
   const stores = /* @__PURE__ */ new Map();
   const initStore = (name, init2) => {
-    if (!stores.has(name)) {
-      const store = createStore(init2);
-      stores.set(name, store);
-    }
+    if (!stores.has(name)) stores.set(name, createStore(init2));
     return stores.get(name);
   };
   const useStore = (opt) => {
     const store = useContext(ctx);
-    if (opt?.storeName && stores.has(opt.storeName)) {
-      return stores.get(opt.storeName);
-    }
+    if (opt?.storeName && stores.has(opt.storeName)) return stores.get(opt.storeName);
     if (!store) throw new Error("useCtx must be used within a Provider");
     return store;
   };
   const provide = (opt = {}) => {
-    const value = opt.value || init();
+    const storeInit = opt.value ? () => opt.value : init;
     const storeName = opt.storeName || "ctx__store";
     const Provider = ({ children }) => {
-      const store = initStore(storeName, () => value);
-      useEffect(() => {
-        return () => {
-          stores.delete(storeName);
-        };
+      const store = initStore(storeName, storeInit);
+      useEffect(() => () => {
+        stores.delete(storeName);
       }, []);
       return /* @__PURE__ */ jsx(ctx.Provider, { value: store, children });
     };
@@ -79,19 +95,19 @@ function createCtx(init) {
   };
   const use = (selector, opt) => {
     const store = useStore(opt);
-    return useStoreValue(store, selector);
+    return useValue(store, selector);
   };
   const useSetter = (selector, opt) => {
     const store = useStore(opt);
-    return useSetStore(store, selector);
+    return useSet(store, selector);
   };
   use.provide = provide;
-  use.useSetter = useSetter;
+  use.useSet = useSetter;
   use.useStore = useStore;
   return use;
 }
 export {
   createCtx,
-  useSetStore,
-  useStoreValue
+  useSet,
+  useValue
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thefoxieflow/signalctx",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "description": "Lightweight signal-based React context store",
   "main": "dist/index.cjs",
   "module": "dist/index.js",