pocket-state 0.1.2 → 0.1.4

package/README.md

@@ -106,27 +106,61 @@ const unsub = counterStore.subscribe(state => {
   console.log('New state:', state);
 });
 
-// With selector (push model)
+// With selector
 const unsubCount = counterStore.subscribe(
   s => s.count,
   count => console.log('Count changed:', count),
 );
 
-// cleanup
 unsub();
 unsubCount();
 ```
 
-### 6) Using with React
+---
+
+## 🎣 Custom Hooks with `createHook`
+
+A utility to generate custom, type-safe hooks for your stores —  
+allowing you to access the store API without re-renders,  
+or subscribe to selected state slices with precise control.
+
+```ts
+import {createHook} from 'pocket-state';
+import {counterStore} from './counterStore';
+
+// Generate a custom hook
+const useCounter = createHook(counterStore);
+
+// Access only store API (no re-render)
+const {reset, setValue} = useCounter();
+
+// Access selected state (with API), triggers re-render on changes
+const {value: count, reset} = useCounter(state => state.count);
+```
+
+### 🧩 **React Example**
 
 ```tsx
 import React from 'react';
 import {Text, Button, View} from 'react-native';
-import {useStore} from 'pocket-state';
-import {counterStore} from './counterStore';
+import {createStore, createHook} from 'pocket-state';
 
+// 1. Create your store
+interface Counter {
+  count: number;
+}
+const counterStore = createStore<Counter>({count: 0});
+
+// 2. Create the custom hook
+const useCounter = createHook(counterStore);
+
+// 3. Use inside a React Native component
 export function CounterComponent() {
-  const count = useStore(counterStore, s => s.count);
+  // Only gets API, no re-render
+  const {reset} = useCounter();
+
+  // Gets selected value + API, re-renders when count changes
+  const {value: count, reset: reset2} = useCounter(state => state.count);
 
   return (
     <View>
@@ -135,19 +169,24 @@ export function CounterComponent() {
         title="Inc"
         onPress={() => counterStore.setValue(s => ({count: s.count + 1}))}
       />
+      <Button title="Reset" onPress={reset} />
     </View>
   );
 }
 ```
 
+**Advantages:**
+
+- **No accidental re-renders** when accessing only API methods.
+- **Type-safe selectors** and API usage, with full IDE support.
+- **Simple migration path** for those coming from Zustand or similar libraries.
+
 ---
 
 ## 🎯 Selectors
 
 Selectors let you subscribe to **just part of the state**.
 
-### React
-
 ```tsx
 function FlagDisplay() {
   const flag = useStore(counterStore, s => s.flag);
@@ -155,165 +194,6 @@ function FlagDisplay() {
 }
 ```
 
-### Non‑React
-
-```ts
-// Only listen to count changes
-const off = counterStore.subscribe(
-  s => s.count,
-  c => console.log('Count updated:', c),
-);
-```
-
-### Derived selectors (memoized)
-
-For CPU‑heavy derivations, memoize a selector factory:
-
-```ts
-// simple memo (per invocation)
-const makeExpensiveSelector = () => {
-  let lastIn: number | undefined;
-  let lastOut: number | undefined;
-  return (s: {count: number}) => {
-    if (lastIn === s.count && lastOut !== undefined) return lastOut;
-    // expensive calculation here
-    const out = s.count * 2;
-    lastIn = s.count;
-    lastOut = out;
-    return out;
-  };
-};
-
-const selectDouble = makeExpensiveSelector();
-const double = useStore(counterStore, selectDouble);
-```
-
-> Tip: When selecting multiple fields, prefer returning an **object** and use a shallow equality helper at the hook, or do slice comparison at the store level.
-
----
-
-## 🧪 Advanced Usage
-
-### A) Multiple stores & cross‑updates
-
-```ts
-interface Auth {
-  user?: {id: string; name: string} | null;
-}
-interface Todos {
-  items: {id: string; title: string; done: boolean}[];
-}
-
-export const authStore = createStore<Auth>({user: null});
-export const todoStore = createStore<Todos>({items: []});
-
-// react to auth changes
-authStore.subscribe(s => {
-  if (!s.user) {
-    todoStore.reset({items: []}); // clear todos on logout
-  }
-});
-```
-
-### B) Derived state without reselect libraries
-
-```ts
-type Cart = {items: {id: string; price: number; qty: number}[]};
-export const cartStore = createStore<Cart>({items: []});
-
-const selectTotal = (s: Cart) =>
-  s.items.reduce((sum, it) => sum + it.price * it.qty, 0);
-
-// React:
-const total = useStore(cartStore, selectTotal);
-```
-
-### C) Persist middleware (conceptual)
-
-```ts
-import type {Middleware} from 'pocket-state';
-
-const persist =
-  <T>(key: string): Middleware<T> =>
-  (next, get) =>
-  patch => {
-    next(patch);
-    try {
-      localStorage.setItem(key, JSON.stringify(get()));
-    } catch {}
-  };
-
-const store = createStore({count: 0}, [persist('app:store')]);
-```
-
-### D) Logger middleware
-
-```ts
-const logger =
-  (name = 'store'): Middleware<any> =>
-  (next, get) =>
-  patch => {
-    const prev = get();
-    console.log(`[${name}] prev`, prev);
-    next(patch);
-    console.log(`[${name}] next`, get());
-  };
-```
-
-### E) Push vs Pull model
-
-- **Push** (store filters): `store.subscribe(selector, listener)` fires **only when slice changes**.  
-  Hook can be very light (keep last slice, no equality check).
-- **Pull** (hook filters): store emits on any change; `useStore` runs `selector + equality`.  
-  Useful if your store lacks selector subscriptions.
-
-Pick **one** place to compare slices to avoid double work.
-
-### F) Coalesced emits
-
-If your store batches emits in a microtask, multiple updates in a burst trigger one notify:
-
-```ts
-for (let i = 0; i < 10; i++) {
-  counterStore.setValue(s => ({count: s.count + 1}));
-}
-// With coalescing, subscribers run once.
-```
-
-### G) Using outside React (workers, Node, services)
-
-```ts
-// service.ts
-import {counterStore} from './counterStore';
-
-export function increment() {
-  counterStore.setValue(s => ({count: s.count + 1}));
-}
-
-export function onCountChange(cb: (n: number) => void) {
-  return counterStore.subscribe(s => s.count, cb);
-}
-```
-
-### H) Testing
-
-```ts
-import {expect, test} from 'vitest';
-import {counterStore} from './counterStore';
-
-test('increments', () => {
-  counterStore.reset({count: 0, flag: false});
-  counterStore.setValue(s => ({count: s.count + 1}));
-  expect(counterStore.getValue('count')).toBe(1);
-});
-```
-
-### I) Type‑safe key reads with `getValue(key)`
-
-```ts
-const c = counterStore.getValue('count'); // typed as number
-```
-
 ---
 
 ## 🧩 API Reference
@@ -331,10 +211,21 @@ const c = counterStore.getValue('count'); // typed as number
 
 ### `useStore(store, selector?)` (React)
 
-Lightweight hook built on `useSyncExternalStore` that subscribes to your store and returns the selected slice. It supports both full‑state and slice subscriptions.
+Lightweight hook built on `useSyncExternalStore` that subscribes to your store and returns the selected slice.
+
+### `createHook(store)` (React)
+
+Generates a custom hook for your store.
+
+- `hook()` → store API only, **no re-render**.
+- `hook(selector)` → `{ value, ...api }`, re-renders when selected state changes.
 
 ---
 
+## keyword
+
+pocket-state, state-management, react, react-native, typescript, hooks, store
+
 ## 📜 License
 
 MIT — use it however you like.

package/example/CounterExample.tsx

@@ -0,0 +1,22 @@
+import React from 'react';
+import {Text, Button, View} from 'react-native';
+import {createStore, createHook} from 'pocket-state';
+
+interface Counter {
+  count: number;
+}
+const counterStore = createStore<Counter>({ count: 0 });
+const useCounter = createHook(counterStore);
+
+export function CounterExample() {
+  const {reset} = useCounter();
+  const {value: count} = useCounter(state => state.count);
+
+  return (
+    <View style={{padding: 20}}>
+      <Text>Count: {count}</Text>
+      <Button title="Inc" onPress={() => counterStore.setValue(s => ({count: s.count + 1}))} />
+      <Button title="Reset" onPress={reset} />
+    </View>
+  );
+}

package/example/PressButtonExample.tsx

@@ -0,0 +1,21 @@
+import React from 'react';
+import {Text, Button, View} from 'react-native';
+import {createStore, createHook} from 'pocket-state';
+
+interface Press {
+  press: number;
+}
+const pressStore = createStore<Press>({ press: 0 });
+const usePress = createHook(pressStore);
+
+export function PressButtonExample() {
+  const {value: press} = usePress(state => state.press);
+  const {setValue} = usePress();
+
+  return (
+    <View style={{padding: 20}}>
+      <Text>Press count: {press}</Text>
+      <Button title="Press +" onPress={() => setValue(s => ({press: s.press + 1}))} />
+    </View>
+  );
+}

package/example/SelectorExample.tsx

@@ -0,0 +1,22 @@
+import React from 'react';
+import {Text, View} from 'react-native';
+import {createStore, createHook} from 'pocket-state';
+
+interface User {
+  name: string;
+  age: number;
+}
+const userStore = createStore<User>({ name: 'Alice', age: 25 });
+const useUser = createHook(userStore);
+
+export function SelectorExample() {
+  const {value: name} = useUser(s => s.name);
+  const {value: age} = useUser(s => s.age);
+
+  return (
+    <View style={{padding: 20}}>
+      <Text>User name: {name}</Text>
+      <Text>User age: {age}</Text>
+    </View>
+  );
+}

package/example/SubscriptionExample.tsx

@@ -0,0 +1,28 @@
+import React, {useEffect} from 'react';
+import {Text, View} from 'react-native';
+import {createStore, createHook} from 'pocket-state';
+
+interface Log {
+  count: number;
+}
+const logStore = createStore<Log>({ count: 0 });
+const useLog = createHook(logStore);
+
+export function SubscriptionExample() {
+  const {setValue, subscribe} = useLog();
+  const {value: count} = useLog(s => s.count);
+
+  useEffect(() => {
+    const unsub = subscribe(s => s.count, (c) => {
+      console.log('Count changed:', c);
+    });
+    return unsub;
+  }, [subscribe]);
+
+  return (
+    <View style={{padding: 20}}>
+      <Text>Count: {count}</Text>
+      <Text>(Open console to see subscription logs)</Text>
+    </View>
+  );
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pocket-state",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "tiny global store",
   "main": "src/index",
   "codegenConfig": {

package/src/globalState/create.ts

@@ -0,0 +1,41 @@
+import { useMemo } from "react";
+import { useStore } from "./hooks";
+import { Store } from "./type";
+
+/**
+ * Creates a custom React hook for a store, giving you access to the store API
+ * (such as reset, set, subscribe, etc.) and optionally, reactive state selection.
+ *
+ * Usage:
+ *   // 1. Create your store instance (with custom API)
+ *   const countStore = createStore({ count: 0, ... });
+ *
+ *   // 2. Create the hook
+ *   const useCount = createHook(countStore);
+ *
+ *   // 3. Use inside component:
+ *   // a) Access API only, never triggers re-render
+ *   const { reset, setValue } = useCount();
+ *
+ *   // b) Access selected value (and API), triggers re-render only when value changes
+ *   const { value, reset } = useCount(state => state.count);
+ *
+ * @template T The store state type.
+ * @param store - The store instance implementing the Store<T> API.
+ * @returns A custom hook with two usage patterns:
+ *   1. `useHook()` – Returns store API only (no value, no render on state change).
+ *   2. `useHook(selector)` – Returns `{ value, ...api }` where `value` is the selected state. Re-renders on selected value changes.
+ */
+export function createHook<T>(store: Store<T>) {
+  const api = { ...store };
+
+  function useBoundStore(): typeof api;
+  function useBoundStore<S>(selector: (state: T) => S): { value: S } & typeof api;
+  function useBoundStore<S = T>(selector?: (state: T) => S) {
+    if (!selector) return api;
+    const value = useStore(store, selector);
+    return useMemo(() => ({ value, ...api }), [value]);
+  }
+
+  return useBoundStore;
+}