@thefoxieflow/signalctx 0.0.1

package/README.md

@@ -0,0 +1,379 @@
+# signal-ctx
+
+A tiny, signal-based state utility for React that **solves the `useContext` re-render problem** using
+**`useSyncExternalStore`**.
+
+If you’ve ever had this issue:
+
+```ts
+{ count, book }
+// updating count re-renders book components 😡
+```
+
+`signal-ctx` is designed specifically to fix that.
+
+---
+
+## ✨ Why signal-ctx?
+
+### ❌ The Problem with `useContext`
+
+React Context subscribes to the **entire value**.
+
+```tsx
+const { book } = useContext(StoreCtx)
+```
+
+When **any property changes**, **every consumer re-renders** — even if they don’t use it.
+
+This is not a bug. Context has **no selector mechanism**.
+
+---
+
+### ✅ The Solution
+
+`signal-ctx`:
+
+* Moves state **outside React**
+* Uses **external subscriptions**
+* Allows **selector-based updates**
+
+So only the components that *actually use* the changed data re-render.
+
+---
+
+## ✨ Features
+
+* ⚡ Signal-style state container
+* 🎯 Selector-based subscriptions
+* 🧵 React 18 concurrent-safe
+* 🧩 Context-backed but not context-driven
+* 📦 Very small bundle size
+* 🌳 Tree-shakable
+* 🧠 Explicit and predictable
+
+---
+
+## 📦 Installation
+
+```bash
+npm install @thefoxieflow/signal-ctx
+```
+
+> **Peer dependency:** React 18+
+
+---
+
+## 🧠 Core Idea
+
+Context **does not store state**.
+
+It stores a **stable signal reference**.
+
+```tsx
+<Provider value={store} />
+```
+
+The state lives **outside React**, and components subscribe **directly to the signal**.
+
+---
+
+## 🔹 Signal Store
+
+A signal is:
+
+* A function that returns state
+* Can be subscribed to
+* Can be updated imperatively
+
+```ts
+type Store<T> = {
+  (): T
+  subscribe(fn: () => void): () => void
+  set(action: SetStateAction<T>): void
+}
+```
+
+---
+
+## 🔹 Low-Level Hooks
+
+### `createStore(()=>{})`
+
+### `useStoreValue(store, selector?)`
+
+Subscribe to a signal.
+
+```tsx
+const count = useStoreValue(store, s => s.count)
+```
+
+* Uses `useSyncExternalStore`
+* Re-renders only when the selected value changes
+* Selector is optional
+
+---
+
+### `useSetStore(store, selector?)`
+
+Returns a setter function.
+
+```ts
+const set = useSetStore(store)
+
+set(prev => ({ ...prev, count: prev.count + 1 }))
+```
+
+Scoped update:
+
+```ts
+// book must be object for selector
+const setBook = useSetSignal(store, s => s.book)
+
+
+// put: update an object
+setBook({
+    title : "book"
+})
+
+// patch: update partially
+setBook((b)=>{
+    b.title = "book"
+})
+```
+
+⚠️ Updates are **mutation-based**. Spread manually if you want immutability.
+
+---
+
+## 🔹 Context-Based API
+
+### `createCtx(init)`
+
+Creates a **context-backed signal store hook**.
+
+```ts
+import { createCtx } from "@your-scope/signal-ctx"
+
+export const useStore = createCtx(() => ({
+  count: 0,
+  book: { title: "1984" }
+}))
+```
+
+---
+
+## 🚀 Usage
+
+### 1. Create a Provider
+
+```tsx
+// use default initial value from useStore
+type Props = {
+  children: React.ReactNode
+}
+
+export function StoreProvider({ children }: Props) {
+  const Provider = useStore.provide()
+  return <Provider>{children}</Provider>
+}
+
+// overwrite value
+export function StoreProvider({ children }: Props) {
+  const Provider = useStore.provide({
+    value: {
+      count: 10,
+      book: { title: "Brave New World" }
+    }
+  })
+
+  return <Provider>{children}</Provider>
+}
+```
+
+```tsx
+<StoreProvider>
+  <App />
+</StoreProvider>
+```
+
+---
+
+### 2. Read only what you need
+
+```tsx
+function Count() {
+  const count = useStore(s => s.count)
+  return <div>{count}</div>
+}
+
+function Book() {
+  const book = useStore(s => s.book)
+  return <div>{book.title}</div>
+}
+```
+
+---
+
+### 3. Update state
+
+```tsx
+function Increment() {
+  const set = useStore.useSetter()
+
+  return (
+    <button onClick={() =>
+      set(s => ({ ...s, count: s.count + 1 }))
+    }>
+      +
+    </button>
+  )
+}
+```
+
+✅ Updating `count` **does NOT re-render** `Book`.
+
+---
+
+## 🧩 Why This Works
+
+* Context value never changes
+* React does not re-render on context updates
+* `useSyncExternalStore` compares selected snapshots
+* Only changed selectors trigger re-renders
+
+This is the **same model** used by:
+
+* Redux `useSelector`
+* Zustand selectors
+* React’s official external store docs
+
+---
+
+## ⚠️ Important Rule
+
+> **Never destructure the entire state.**
+> Always select the smallest possible slice.
+
+❌ Bad:
+
+```ts
+const state = useStore(s => s)
+```
+
+✅ Good:
+
+```ts
+const count = useStore(s => s.count)
+```
+
+---
+
+## 🧩 Multiple Stores
+
+You can create isolated stores using `storeName`.
+
+```tsx
+type Props = {
+  children: React.ReactNode
+  storeName: string
+  initialValue?: { count: number; book: { title: string } }
+}
+
+export function StoreProvider({ children, storeName, initialValue }: Props) {
+  const Provider = useStore.provide({
+    storeName,
+    value: initialValue || { count: 0, book: { title: "1984" } }
+  })
+
+  return <Provider>{children}</Provider>
+}
+```
+
+### Usage
+```tsx
+<StoreProvider storeName="storeA" initialValue={{ count: 1, book: { title: "A" } }}>
+  <AppA />
+  <StoreProvider storeName="storeB" initialValue={{ count: 5, book: { title: "B" } }}>
+    <AppB />
+  </StoreProvider>
+</StoreProvider>
+
+function AppB(){
+  // book from parent context; parent = "storeA" so book.title = "A"
+  const book = useStore(s => s.book)
+
+  // but i want a book from storeA; so it requires storeName
+  // book.title = "B"
+  const storeABook = useStore(s => s.book,{ storeName :"storeA" })
+
+  // same apply to setter
+  const setBookStoreA = useStore.useSetter((s)=>s.book, {storeName : "storeA"})
+
+  const handleClick = (text)=>{
+    setCountStoreA((s) => {
+       s.title = "change A to AA"
+       return s
+    })
+  }
+}
+```
+
+
+
+Each store is independent.
+
+---
+
+## 🌐 Server-Side Rendering (SSR)
+
+`signal-ctx` is SSR-safe.
+
+* Uses `useSyncExternalStore`
+* Identical snapshot logic on server & client
+* No shared global state between requests
+
+---
+
+## ⚠️ Caveats
+
+* No middleware
+* No devtools
+* No persistence
+* Mutation-based updates by design
+
+Best suited for:
+
+* UI state
+* App-level shared state
+* Lightweight global stores
+
+---
+
+## 🧪 TypeScript
+
+Fully typed with generics and inferred selectors.
+
+```ts
+const count = useStore(s => s.count) // number
+```
+
+---
+
+## 📄 License
+
+MIT
+
+---
+
+## ⭐ Philosophy
+
+`signal-ctx` is intentionally small.
+
+It favors:
+
+* Explicit ownership
+* Predictable updates
+* Minimal abstraction
+
+If you understand React, you understand `signal-ctx`.

package/dist/index.d.mts

@@ -0,0 +1,35 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { SetStateAction, ReactNode } from 'react';
+
+type Store<T = any> = ReturnType<typeof createStore<T>>;
+type Subscriber = () => void;
+/**
+ * @description: create a signal with subscribe and update methods
+ */
+declare function createStore<T = Record<string, any>>(init: () => T): {
+    (): T;
+    subscribe(subscriber: Subscriber): () => boolean;
+    set(action: SetStateAction<T>): void;
+};
+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;
+type StoreOption = {
+    storeName?: string;
+};
+declare function createCtx<T extends object>(init: () => T): {
+    <Dest = any>(selector: (state: T) => Dest, opt?: StoreOption): Dest;
+    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;
+    };
+};
+
+export { type Store, type StoreOption, type Subscriber, createCtx, useSetStore, useStoreValue };

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { SetStateAction, ReactNode } from 'react';
+
+type Store<T = any> = ReturnType<typeof createStore<T>>;
+type Subscriber = () => void;
+/**
+ * @description: create a signal with subscribe and update methods
+ */
+declare function createStore<T = Record<string, any>>(init: () => T): {
+    (): T;
+    subscribe(subscriber: Subscriber): () => boolean;
+    set(action: SetStateAction<T>): void;
+};
+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;
+type StoreOption = {
+    storeName?: string;
+};
+declare function createCtx<T extends object>(init: () => T): {
+    <Dest = any>(selector: (state: T) => Dest, opt?: StoreOption): Dest;
+    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;
+    };
+};
+
+export { type Store, type StoreOption, type Subscriber, createCtx, useSetStore, useStoreValue };

package/dist/index.js

@@ -0,0 +1,119 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.tsx
+var index_exports = {};
+__export(index_exports, {
+  createCtx: () => createCtx,
+  useSetStore: () => useSetStore,
+  useStoreValue: () => useStoreValue
+});
+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;
+};
+function createStore(init) {
+  let val;
+  let isInit = false;
+  const subscribers = /* @__PURE__ */ new Set();
+  const get = () => {
+    if (!isInit) {
+      val = init();
+      isInit = true;
+    }
+    return val;
+  };
+  get.subscribe = (subscriber) => {
+    subscribers.add(subscriber);
+    const unsubscribe = () => subscribers.delete(subscriber);
+    return unsubscribe;
+  };
+  get.set = (action) => {
+    val = applyAction(val, action);
+    subscribers.forEach((subscriber) => subscriber());
+  };
+  return get;
+}
+var useStoreValue = (store, selector) => {
+  const getSnapShot = () => selector ? selector(store()) : store();
+  const use = (0, import_react.useSyncExternalStore)(store.subscribe, getSnapShot, getSnapShot);
+  return use;
+};
+var useSetStore = (store, selector) => {
+  const setter = (action) => {
+    const current = store();
+    const target = selector ? selector(current) : current;
+    applyAction(target, action);
+    store.set(current);
+  };
+  return setter;
+};
+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);
+    }
+    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 (!store) throw new Error("useCtx must be used within a Provider");
+    return store;
+  };
+  const provide = (opt = {}) => {
+    const 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);
+        };
+      }, []);
+      return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(ctx.Provider, { value: store, children });
+    };
+    return Provider;
+  };
+  const use = (selector, opt) => {
+    const store = useStore(opt);
+    return useStoreValue(store, selector);
+  };
+  const useSetter = (selector, opt) => {
+    const store = useStore(opt);
+    return useSetStore(store, selector);
+  };
+  use.provide = provide;
+  use.useSetter = useSetter;
+  use.useStore = useStore;
+  return use;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createCtx,
+  useSetStore,
+  useStoreValue
+});

package/dist/index.mjs

@@ -0,0 +1,97 @@
+// src/index.tsx
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useSyncExternalStore
+} from "react";
+import { jsx } from "react/jsx-runtime";
+var applyAction = (target, action) => {
+  return typeof action === "function" ? action(target) : action;
+};
+function createStore(init) {
+  let val;
+  let isInit = false;
+  const subscribers = /* @__PURE__ */ new Set();
+  const get = () => {
+    if (!isInit) {
+      val = init();
+      isInit = true;
+    }
+    return val;
+  };
+  get.subscribe = (subscriber) => {
+    subscribers.add(subscriber);
+    const unsubscribe = () => subscribers.delete(subscriber);
+    return unsubscribe;
+  };
+  get.set = (action) => {
+    val = applyAction(val, action);
+    subscribers.forEach((subscriber) => subscriber());
+  };
+  return get;
+}
+var useStoreValue = (store, selector) => {
+  const getSnapShot = () => selector ? selector(store()) : store();
+  const use = useSyncExternalStore(store.subscribe, getSnapShot, getSnapShot);
+  return use;
+};
+var useSetStore = (store, selector) => {
+  const setter = (action) => {
+    const current = store();
+    const target = selector ? selector(current) : current;
+    applyAction(target, action);
+    store.set(current);
+  };
+  return setter;
+};
+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);
+    }
+    return stores.get(name);
+  };
+  const useStore = (opt) => {
+    const store = useContext(ctx);
+    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 storeName = opt.storeName || "ctx__store";
+    const Provider = ({ children }) => {
+      const store = initStore(storeName, () => value);
+      useEffect(() => {
+        return () => {
+          stores.delete(storeName);
+        };
+      }, []);
+      return /* @__PURE__ */ jsx(ctx.Provider, { value: store, children });
+    };
+    return Provider;
+  };
+  const use = (selector, opt) => {
+    const store = useStore(opt);
+    return useStoreValue(store, selector);
+  };
+  const useSetter = (selector, opt) => {
+    const store = useStore(opt);
+    return useSetStore(store, selector);
+  };
+  use.provide = provide;
+  use.useSetter = useSetter;
+  use.useStore = useStore;
+  return use;
+}
+export {
+  createCtx,
+  useSetStore,
+  useStoreValue
+};

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@thefoxieflow/signalctx",
+  "version": "0.0.1",
+  "description": "Lightweight signal-based React context store",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.tsx --format esm,cjs --dts --out-dir dist",
+    "prepublishOnly": "npm run build",
+    "publish": "npm publish"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/foxie-io/thefoxieflow",
+    "directory": "signalctx"
+  },
+  "sideEffects": false,
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.8",
+    "react": "^18.2.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  },
+  "keywords": [
+    "react",
+    "state",
+    "store",
+    "context",
+    "signal"
+  ]
+}