pocket-state 0.0.2

package/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "pocket-state",
+  "version": "0.0.2",
+  "description": "tiny global store",
+  "main": "src/index",
+  "codegenConfig": {
+    "name": "TinystoreSpec",
+    "type": "modules",
+    "jsSrcsDir": "src"
+  },
+  "author": " <@kayda69> (nhh.tcp@gmail.com)",
+  "license": "ISC",
+  "homepage": "#readme"
+}

package/src/globalState/event.ts

@@ -0,0 +1,81 @@
+// event.ts
+import {IEventEmitter, Listener} from './type';
+
+export class EventEmitter implements IEventEmitter {
+  private events = new Map<string, Set<Listener<any>>>();
+  private onceWrappers = new Map<string, Map<Listener<any>, Listener<any>>>();
+
+  on<T>(event: string, listener: Listener<T>): void {
+    let set = this.events.get(event);
+    if (!set) {
+      set = new Set();
+      this.events.set(event, set);
+    }
+    set.add(listener as unknown as Listener<any>);
+  }
+
+  once<T>(event: string, listener: Listener<T>): void {
+    const wrapper: Listener<T> = payload => {
+      this.off(event, wrapper);
+      this.onceWrappers
+        .get(event)
+        ?.delete(listener as unknown as Listener<any>);
+      listener(payload);
+    };
+    if (!this.onceWrappers.has(event)) {
+      this.onceWrappers.set(event, new Map());
+    }
+    this.onceWrappers
+      .get(event)!
+      .set(
+        listener as unknown as Listener<any>,
+        wrapper as unknown as Listener<any>,
+      );
+    this.on(event, wrapper);
+  }
+
+  emit<T>(event: string, payload: T): void {
+    const listeners = this.events.get(event);
+    if (!listeners || listeners.size === 0) return;
+    for (const l of listeners) {
+      try {
+        l(payload);
+      } catch (error) {
+        console.warn(`Error in listener for '${event}':`, error);
+      }
+    }
+  }
+
+  off<T>(event: string, listener?: Listener<T>): void {
+    const set = this.events.get(event);
+    if (!set) return;
+
+    if (listener) {
+      const wrapped = this.onceWrappers
+        .get(event)
+        ?.get(listener as unknown as Listener<any>);
+      if (wrapped) {
+        set.delete(wrapped as unknown as Listener<any>);
+        this.onceWrappers
+          .get(event)!
+          .delete(listener as unknown as Listener<any>);
+        if (this.onceWrappers.get(event)!.size === 0) {
+          this.onceWrappers.delete(event);
+        }
+      } else {
+        set.delete(listener as unknown as Listener<any>);
+      }
+      if (set.size === 0) {
+        this.events.delete(event);
+      }
+      return;
+    }
+    this.events.delete(event);
+    this.onceWrappers.delete(event);
+  }
+
+  clear(): void {
+    this.events.clear();
+    this.onceWrappers.clear();
+  }
+}

package/src/globalState/hooks.ts

@@ -0,0 +1,26 @@
+// useStore.ts
+import {useCallback} from 'react';
+import {useSyncExternalStore} from 'react';
+import type {Store} from './type';
+
+export function useStore<T>(store: Store<T>): T;
+export function useStore<T, S>(store: Store<T>, selector: (state: T) => S): S;
+
+export function useStore<T, S = T>(
+  store: Store<T>,
+  selector?: (state: T) => S,
+): T | S {
+  const subscribe = useCallback(
+    (onChange: () => void) =>
+      selector
+        ? store.subscribe(selector, () => onChange())
+        : store.subscribe(() => onChange()),
+    [store, selector],
+  );
+  const getSnapshot = useCallback(() => {
+    const s = store.getValue();
+    return selector ? selector(s) : (s as T);
+  }, [store, selector]);
+
+  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot) as T | S;
+}

package/src/globalState/shallowEqual.ts

@@ -0,0 +1,74 @@
+const isIterable = (obj: object): obj is Iterable<unknown> =>
+  Symbol.iterator in obj;
+
+const hasIterableEntries = (
+  value: Iterable<unknown>,
+): value is Iterable<unknown> & {
+  entries(): Iterable<[unknown, unknown]>;
+} =>
+  // HACK: avoid checking entries type
+  'entries' in value;
+
+const compareEntries = (
+  valueA: {entries(): Iterable<[unknown, unknown]>},
+  valueB: {entries(): Iterable<[unknown, unknown]>},
+) => {
+  const mapA = valueA instanceof Map ? valueA : new Map(valueA.entries());
+  const mapB = valueB instanceof Map ? valueB : new Map(valueB.entries());
+  if (mapA.size !== mapB.size) {
+    return false;
+  }
+  for (const [key, value] of mapA) {
+    if (!Object.is(value, mapB.get(key))) {
+      return false;
+    }
+  }
+  return true;
+};
+
+// Ordered iterables
+const compareIterables = (
+  valueA: Iterable<unknown>,
+  valueB: Iterable<unknown>,
+) => {
+  const iteratorA = valueA[Symbol.iterator]();
+  const iteratorB = valueB[Symbol.iterator]();
+  let nextA = iteratorA.next();
+  let nextB = iteratorB.next();
+  while (!nextA.done && !nextB.done) {
+    if (!Object.is(nextA.value, nextB.value)) {
+      return false;
+    }
+    nextA = iteratorA.next();
+    nextB = iteratorB.next();
+  }
+  return !!nextA.done && !!nextB.done;
+};
+
+export function shallow<T>(valueA: T, valueB: T): boolean {
+  if (Object.is(valueA, valueB)) {
+    return true;
+  }
+  if (
+    typeof valueA !== 'object' ||
+    valueA === null ||
+    typeof valueB !== 'object' ||
+    valueB === null
+  ) {
+    return false;
+  }
+  if (Object.getPrototypeOf(valueA) !== Object.getPrototypeOf(valueB)) {
+    return false;
+  }
+  if (isIterable(valueA) && isIterable(valueB)) {
+    if (hasIterableEntries(valueA) && hasIterableEntries(valueB)) {
+      return compareEntries(valueA, valueB);
+    }
+    return compareIterables(valueA, valueB);
+  }
+  // assume plain objects
+  return compareEntries(
+    {entries: () => Object.entries(valueA)},
+    {entries: () => Object.entries(valueB)},
+  );
+}

package/src/globalState/store.ts

@@ -0,0 +1,198 @@
+// store.ts
+// import deepEqual from 'fast-deep-equal';
+import {IEventEmitter, Listener, Middleware, Store, UseStoreGet} from './type';
+import {EventEmitter} from './event';
+import {Draft, produce} from 'immer';
+// import {shallow} from './shallowEqual';
+import deepEqual from 'fast-deep-equal';
+export function createStore<T>(
+  initialState: T,
+  middlewares: Middleware<T>[] = [],
+): Store<T> {
+  const emitter: IEventEmitter = new EventEmitter();
+  let state = initialState;
+
+  // Coalesce emits trong cùng 1 microtask
+  let emitScheduled = false;
+  const emitState = () => {
+    if (emitScheduled) return;
+    emitScheduled = true;
+    queueMicrotask(() => {
+      emitScheduled = false;
+      emitter.emit('state', state);
+    });
+  };
+
+  function baseSet(delta: Partial<T>) {
+    const nextState = Array.isArray(state)
+      ? (delta as unknown as T) // với array: replace
+      : {...state, ...delta}; // với object: shallow merge
+
+    if (!deepEqual(state, nextState)) {
+      state = nextState;
+
+      // Dev guard: phát hiện mutate ngoài store
+      if (process.env.NODE_ENV !== 'production') {
+        try {
+          Object.freeze(state as any);
+        } catch {}
+      }
+
+      emitState();
+    }
+  }
+
+  const setFn = middlewares.reduceRight(
+    (next, mw) => mw(next, () => state),
+    baseSet as (patch: Partial<T>) => void,
+  );
+
+  const getValue = ((key?: keyof T | (keyof T)[]) => {
+    if (key === undefined) return state;
+    if (Array.isArray(key)) {
+      const out = {} as Pick<T, (typeof key)[number]>;
+      for (const k of key) (out as any)[k] = (state as any)[k];
+      return out;
+    }
+    return (state as any)[key];
+  }) as UseStoreGet<T>;
+
+  function subscribe(selectorOrListener: any, maybeListener?: any) {
+    let wrapped: Listener<any>;
+
+    if (typeof maybeListener === 'function') {
+      // subscribe(selector, listener)
+      const selector: (s: T) => any = selectorOrListener;
+      let prevSlice = selector(state);
+      wrapped = (next: T) => {
+        const slice = selector(next);
+        if (!deepEqual(slice, prevSlice)) {
+          prevSlice = slice;
+          maybeListener(slice);
+        }
+      };
+    } else {
+      // subscribe(listener)
+      const listener: Listener<T> = selectorOrListener;
+      let prev = state;
+      wrapped = (next: T) => {
+        if (!deepEqual(next, prev)) {
+          prev = next;
+          listener(next);
+        }
+      };
+    }
+
+    emitter.on('state', wrapped);
+
+    // Lưu ý: KHÔNG gọi listener ngay khi subscribe
+    // (để tương thích useSyncExternalStore: initial snapshot lấy qua getSnapshot)
+
+    return () => emitter.off('state', wrapped);
+  }
+
+  function setValue(
+    patch: Partial<T> | ((state: T) => Partial<T> | Promise<Partial<T>>),
+  ): void {
+    (async () => {
+      try {
+        const resolved =
+          typeof patch === 'function' ? await (patch as any)(state) : patch;
+
+        if (resolved && typeof resolved === 'object') {
+          setFn(resolved as Partial<T>);
+        }
+      } catch (error) {
+        console.warn('[store.setValue] patch error:', error);
+      }
+    })();
+  }
+
+  function setImmer(updater: (draft: Draft<T>) => void): void {
+    try {
+      const nextState = produce(state, updater);
+      if (deepEqual(state, nextState)) return;
+
+      if (Array.isArray(state)) {
+        setFn(nextState as unknown as Partial<T>);
+        return;
+      }
+      const delta = {} as Partial<T>;
+      let changed = false;
+      for (const k in nextState as any) {
+        const nv = (nextState as any)[k];
+        const ov = (state as any)[k];
+        if (nv !== ov) {
+          (delta as any)[k] = nv;
+          changed = true;
+        }
+      }
+      for (const k in state as any) {
+        if (!(k in (nextState as any))) {
+          (delta as any)[k] = undefined;
+          changed = true;
+        }
+      }
+      if (changed) setFn(delta);
+    } catch (e) {
+      console.warn('[store.setImmer] error:', e);
+    }
+  }
+
+  function reset(): void;
+  function reset(initialValue?: T | Partial<T>): void;
+  function reset(initialValue?: T | Partial<T>) {
+    const isObj = (
+      v: unknown,
+    ): v is Record<string | symbol | number, unknown> =>
+      typeof v === 'object' && v !== null;
+
+    const cloneShallow = <U>(src: U): U => {
+      if (Array.isArray(src)) return (src as any).slice();
+      if (isObj(src)) return {...(src as any)} as U;
+      return src;
+    };
+
+    let next = cloneShallow(initialState) as T;
+    if (initialValue !== undefined) {
+      if (Array.isArray(initialValue)) {
+        next = (initialValue as any).slice();
+      } else if (isObj(initialValue)) {
+        Object.assign(next as any, initialValue);
+      } else {
+        const current = getValue();
+        if (!Object.is(current as any, initialValue as any)) {
+          setFn(initialValue as unknown as Partial<T>);
+        }
+        return;
+      }
+    }
+    const current = getValue();
+    if (!deepEqual(current, next)) {
+      setFn(next as unknown as Partial<T>);
+    }
+  }
+
+  function getInitialValue(): T {
+    if (Array.isArray(state)) {
+      return (state as any).slice();
+    }
+    if (state && typeof state === 'object') {
+      return {...(state as any)};
+    }
+    return state;
+  }
+
+  function isDirty() {
+    return !deepEqual(state, initialState);
+  }
+  return {
+    getValue,
+    getInitialValue,
+    setValue,
+    setImmer,
+    reset,
+    subscribe,
+    isDirty,
+  };
+}

package/src/globalState/type-helper.d.ts

@@ -0,0 +1,58 @@
+// ---- Path utilities (zero-deps, RHF-like) ----
+type Primitive =
+  | string
+  | number
+  | boolean
+  | bigint
+  | symbol
+  | null
+  | undefined
+  | Date
+  | RegExp
+  | Function;
+
+type IsTuple<A extends readonly unknown[]> = number extends A['length']
+  ? false
+  : true;
+
+type IndexKeys<T> = Extract<keyof T, string>;
+
+/** All dot/bracket-style paths into T (e.g. "user.name", "items.0.qty") */
+export type Path<T> = T extends Primitive
+  ? never
+  : T extends readonly (infer V)[]
+  ? IsTuple<T> extends true
+    ? {
+        [I in Extract<keyof T, `${number}`>]: `${I}` | `${I}.${Path<V>}`;
+      }[Extract<keyof T, `${number}`>]
+    : `${number}` | `${number}.${Path<V>}`
+  : {
+      [K in IndexKeys<T>]: T[K] extends Primitive
+        ? `${K}`
+        : `${K}` | `${K}.${Path<T[K]>}`;
+    }[IndexKeys<T>];
+
+/** Value type at path P */
+export type PathValue<
+  T,
+  P extends string,
+> = P extends `${infer K}.${infer Rest}`
+  ? K extends keyof T
+    ? PathValue<T[K], Rest>
+    : K extends `${number}`
+    ? T extends readonly (infer V)[]
+      ? PathValue<V, Rest>
+      : never
+    : never
+  : P extends keyof T
+  ? T[P]
+  : P extends `${number}`
+  ? T extends readonly (infer V)[]
+    ? V
+    : never
+  : never;
+
+/** Tuple of values for a tuple of paths */
+export type PathValues<T, PS extends readonly string[]> = {
+  [I in keyof PS]: PS[I] extends string ? PathValue<T, PS[I]> : never;
+};

package/src/globalState/type.d.ts

@@ -0,0 +1,219 @@
+import {Draft} from 'immer';
+
+/**
+ * A callback invoked when an event is emitted with a payload of type `T`.
+ * Keep listeners pure and fast. Long-running side effects should live in
+ * middleware/effects instead of listeners.
+ */
+export interface Listener<T = any> {
+  (payload: T): void;
+}
+
+/**
+ * Immer-style mutation function used for "mutable-looking" updates.
+ *
+ * - Receives a `draft` (a Proxy of your state).
+ * - You can mutate the draft; Immer will produce the next immutable state.
+ * - You may return a new value instead of mutating the draft (less common).
+ * - Can be async, but it's recommended to await first, then mutate, to avoid races.
+ */
+export type MutateFn<T> = (draft: Draft<T>) => void | T | Promise<void | T>;
+
+/**
+ * Store getter API.
+ *
+ * Usage:
+ * ```ts
+ * const all = getValues();          // → T (entire state)
+ * const count = getValues('count'); // → T['count'] (one key)
+ * ```
+ *
+ * Notes:
+ * - Results are expected to be reference-stable when state hasn't changed,
+ *   which helps React avoid unnecessary renders.
+ * - If you want to support reading multiple keys at once, extend the type.
+ */
+export type UseStoreGet<T> = {
+  (): T;
+  <K extends keyof T>(key: K): T[K];
+};
+/**
+ * Store setter API:
+ * - Accepts a `patch` (partial) to shallow-merge into current state,
+ *   or a function that receives the current state and returns a partial.
+ *   The function may be async.
+ *
+ * Examples:
+ * ```ts
+ * setValue({ flag: true });
+ * setValue(s => ({ count: s.count + 1 }));
+ * setValue(async s => {
+ *   const user = await fetchUser();
+ *   return { user };
+ * });
+ * ```
+ *
+ * Notes:
+ * - The store is responsible for equality checks and only emits on real changes.
+ * - Multiple updates in the same tick may be coalesced (implementation-dependent).
+ *
+ * `immer()` (if implemented) is a convenience to enable Immer-style updates.
+ * This type does not define its runtime behavior; see your implementation.
+ */
+export type UseStoreSet<T> = {
+  (patch: Partial<T> | ((state: T) => Partial<T> | Promise<Partial<T>>)): void;
+  immer(): void;
+};
+
+/**
+ * Minimal pub/sub event emitter contract.
+ *
+ * Expected behavior:
+ * - `on` registers a listener for an event name.
+ * - `emit` broadcasts a payload to all listeners of that event.
+ * - `off` removes a specific listener or all listeners for an event.
+ * - `once` registers a listener that runs exactly once, then unregisters itself.
+ * - `clear` removes listeners for all events.
+ *
+ * Implementation guidance:
+ * - Snapshot listeners before emitting to stay safe if `on/off` happens during emit.
+ * - `off(event, original)` should remove a `once` listener even if it's wrapped.
+ */
+export interface IEventEmitter {
+  /** Register a listener for an event name. */
+  on<T = any>(event: string, listener: Listener<T>): void;
+
+  /** Emit an event with a payload. */
+  emit<T = any>(event: string, payload: T): void;
+
+  /**
+   * Remove a listener or all listeners for an event.
+   * Omit `listener` to remove all listeners for the event.
+   */
+  off<T = any>(event: string, listener?: Listener<T>): void;
+
+  /** Register a one-time listener that auto-unregisters after the first emit. */
+  once<T>(event: string, listener: Listener<T>): void;
+
+  /** Remove all listeners for all events. */
+  clear(): void;
+}
+
+/**
+ * Reactive key-value store interface.
+ * Supports:
+ * - Reading current state (`getValues`)
+ * - Updating via partials or functions (`setValue`)
+ * - Immer-style updates (`setImmer`) when available
+ * - Reset to the initial value (`reset`)
+ * - Subscribing to the whole state or to a slice via a selector
+ *
+ * Important notes:
+ * - Listeners are called only when the relevant data actually changes.
+ * - `subscribe` returns an unsubscribe function — call it on unmount to avoid leaks.
+ * - `subscribe` does **not** auto-invoke the listener initially (fits `useSyncExternalStore`);
+ *   if you need an initial call, read the snapshot and invoke it yourself at the call site.
+ */
+export interface Store<T> {
+  /**
+   * Read the full state or a specific property by key.
+   * @param key Optional key within the state.
+   * @returns Without `key` → the full state `T`.
+   *          With `key`    → the value `T[K]`.
+   */
+  getValue: UseStoreGet<T>;
+
+  /**
+   * Update state by shallow-merging `patch`, or by running a function
+   * that returns a `patch`. The function may be async.
+   */
+  setValue(
+    patch: Partial<T> | ((state: T) => Partial<T> | Promise<Partial<T>>),
+  ): void;
+
+  /**
+   * Returns the store's initial state value.
+   *
+   * - For arrays and objects → returns a shallow clone to avoid external mutations.
+   * - For primitive types → returns the value as-is.
+   * - The returned value represents the original initial state, not the current state.
+   */
+  getInitialValue(): T;
+
+  /**
+   * Update state in Immer style.
+   * @example
+   * ```ts
+   * store.setImmer(draft => {
+   *   draft.user.name = 'Hiep';
+   *   draft.items.push({ id: 'x' });
+   * });
+   * ```
+   */
+  setImmer(updater: (draft: Draft<T>) => void): void;
+
+  /**
+   * Resets the state to the initial value (`initialState`) with a new reference (shallow clone).
+   *
+   * - If no argument is provided → the state is reset to `initialState` (new reference).
+   * - If `initialValue` is provided:
+   *   - If it's an object/array → shallow-merge it into a clone of `initialState`.
+   *   - If it's a primitive → replace the state entirely with that value.
+   * - Always creates a new reference; only updates if the result is not shallow-equal to the current state.
+   */
+  reset(initialValue?: T | Partial<T>): void;
+
+  /**
+   * Subscribe to the entire state.
+   * The listener is invoked **after commit** whenever state changes.
+   * @returns Unsubscribe function.
+   */
+  subscribe(listener: Listener<T>): () => void;
+
+  /**
+   * Subscribe to a derived slice of the state.
+   * The listener fires only when the selector's result changes.
+   * @returns Unsubscribe function.
+   */
+  subscribe<S>(selector: (state: T) => S, listener: Listener<S>): () => void;
+
+  /**
+   * Checks whether the current state differs from the initial state.
+   *
+   * - For primitive types → compared using strict equality (`===`).
+   * - For objects/arrays → compared using deep equality.
+   * - Returns `true` if the state is modified, otherwise `false`.
+   *
+   * @example
+   * ```ts
+   * const store = createStore({ count: 0 });
+   * store.isDirty(); // false
+   *
+   * store.setValue({ count: 1 });
+   * store.isDirty(); // true
+   * ```
+   */
+  isDirty(): boolean;
+}
+
+/**
+ * Middleware that intercepts and transforms a `patch` before it is applied.
+ *
+ * Contract:
+ * - Must call `next(patch)` to forward the update (similar to Redux middleware).
+ * - Can read the current state via `getState()`.
+ * - Useful for logging, validation, mapping, batching, devtools bridges, persistence, etc.
+ *
+ * @example Logging middleware:
+ * ```ts
+ * const logger: Middleware<State> = (next, get) => patch => {
+ *   console.log('Before:', get());
+ *   next(patch);
+ *   console.log('After:', get());
+ * };
+ * ```
+ */
+export type Middleware<T> = (
+  next: (patch: Partial<T>) => void,
+  getState: () => T,
+) => (patch: Partial<T>) => void;

package/src/index.tsx

@@ -0,0 +1,22 @@
+import {createStore} from './globalState/store';
+import {useStore} from './globalState/hooks';
+import type {
+  IEventEmitter,
+  Listener,
+  Middleware,
+  MutateFn,
+  UseStoreGet,
+  UseStoreSet,
+  Store,
+} from './globalState/type';
+
+export {createStore, useStore};
+export type {
+  IEventEmitter,
+  Listener,
+  Middleware,
+  MutateFn,
+  UseStoreGet,
+  UseStoreSet,
+  Store,
+};