@codebelt/classy-store 0.0.1

package/README.md

@@ -0,0 +1,48 @@
+# @codebelt/classy-store
+
+**Class-based reactive state management for React.**
+
+[![npm version](https://img.shields.io/npm/v/@codebelt/classy-store.svg)](https://www.npmjs.com/package/@codebelt/classy-store)
+[![CI](https://github.com/codebelt/classy-store/actions/workflows/ci.yml/badge.svg)](https://github.com/codebelt/classy-store/actions/workflows/ci.yml)
+[![License](https://img.shields.io/npm/l/@codebelt/classy-store.svg)](https://github.com/codebelt/classy-store/blob/main/LICENSE)
+
+## 📚 Documentation
+
+Visit the **[Documentation Website](https://codebelt.github.io/classy-store/)** for tutorials, API reference, and examples.
+
+## 🚀 Features
+
+- **Class-Based**: Define state and logic using standard ES6 classes.
+- **Reactive**: Automatic reactivity using Proxies.
+- **React Integration**: Seamless integration with React 18+ hooks.
+- **TypeScript**: Written in TypeScript with first-class type support.
+
+## 📦 Installation
+
+```bash
+npm install @codebelt/classy-store
+# or
+bun add @codebelt/classy-store
+```
+
+## 🛠️ Development
+
+This project uses [Bun](https://bun.sh) for development.
+
+```bash
+# Install dependencies
+bun install
+
+# Run tests
+bun run test
+
+# Run build
+bun run build
+
+# Start docs website locally
+bun run docs:dev
+```
+
+## 🤝 Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for details on how to contribute and the release workflow.

package/dist/index.cjs

@@ -0,0 +1,234 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_snapshot = require('./snapshot-TbHIUjvP.cjs');
+let proxy_compare = require("proxy-compare");
+let react = require("react");
+
+//#region src/collections.ts
+/**
+* A Map-like class backed by a plain array so `store()` can proxy mutations.
+*
+* Native `Map` uses internal slots that ES6 Proxy can't intercept, so mutations
+* like `.set()` would be invisible to the store. `ReactiveMap` solves this by
+* storing entries in a plain array (`_entries`) that the proxy can track.
+*
+* Usage:
+* ```ts
+* const myStore = store({ users: reactiveMap<string, User>() });
+* myStore.users.set('id1', { name: 'Alice' }); // reactive
+* ```
+*/
+var ReactiveMap = class {
+	static [require_snapshot.PROXYABLE] = true;
+	/** @internal Backing storage — proxied by store(). */
+	_entries = [];
+	/** Deduplicates initial entries by key (last value wins, matching native `Map`). */
+	constructor(initial) {
+		if (initial) for (const [k, v] of initial) {
+			const index = this._entries.findIndex(([ek]) => Object.is(ek, k));
+			if (index !== -1) this._entries[index] = [k, v];
+			else this._entries.push([k, v]);
+		}
+	}
+	/** Returns the number of entries. */
+	get size() {
+		return this._entries.length;
+	}
+	/** Returns the value for `key`, or `undefined`. O(n) linear scan. */
+	get(key) {
+		const entry = this._entries.find(([k]) => Object.is(k, key));
+		return entry ? entry[1] : void 0;
+	}
+	/** Returns `true` if `key` exists. O(n) linear scan. */
+	has(key) {
+		return this._entries.some(([k]) => Object.is(k, key));
+	}
+	/** Sets `key` to `value`. Updates in-place if key exists, appends otherwise. */
+	set(key, value) {
+		const index = this._entries.findIndex(([k]) => Object.is(k, key));
+		if (index !== -1) this._entries[index] = [key, value];
+		else this._entries.push([key, value]);
+		return this;
+	}
+	/** Removes the entry for `key`. Returns `true` if found. */
+	delete(key) {
+		const index = this._entries.findIndex(([k]) => Object.is(k, key));
+		if (index === -1) return false;
+		this._entries.splice(index, 1);
+		return true;
+	}
+	/** Removes all entries. Uses splice to trigger proxy notification. */
+	clear() {
+		this._entries.splice(0, this._entries.length);
+	}
+	/** Returns an iterator over the keys. */
+	keys() {
+		return this._entries.map(([k]) => k)[Symbol.iterator]();
+	}
+	/** Returns an iterator over the values. */
+	values() {
+		return this._entries.map(([, v]) => v)[Symbol.iterator]();
+	}
+	/** Returns an iterator over [key, value] pairs. */
+	entries() {
+		return this._entries.map(([k, v]) => [k, v])[Symbol.iterator]();
+	}
+	/** Calls `callback` for each entry, matching the native `Map.forEach` signature. */
+	forEach(callback) {
+		for (const [k, v] of this._entries) callback(v, k, this);
+	}
+	/** Enables `for...of` iteration over [key, value] pairs. */
+	[Symbol.iterator]() {
+		return this.entries();
+	}
+};
+/**
+* A Set-like class backed by a plain array so `store()` can proxy mutations.
+*
+* Native `Set` uses internal slots that ES6 Proxy can't intercept, so mutations
+* like `.add()` would be invisible to the store. `ReactiveSet` solves this by
+* storing items in a plain array (`_items`) that the proxy can track.
+*
+* Usage:
+* ```ts
+* const myStore = store({ tags: reactiveSet<string>(['urgent']) });
+* myStore.tags.add('bug'); // reactive
+* ```
+*/
+var ReactiveSet = class {
+	static [require_snapshot.PROXYABLE] = true;
+	/** @internal Backing storage — proxied by store(). */
+	_items = [];
+	/** Deduplicates initial values using `Object.is` comparison. */
+	constructor(initial) {
+		if (initial) {
+			for (const v of initial) if (!this._items.some((item) => Object.is(item, v))) this._items.push(v);
+		}
+	}
+	/** Returns the number of unique items. */
+	get size() {
+		return this._items.length;
+	}
+	/** Returns `true` if `value` exists. O(n) linear scan. */
+	has(value) {
+		return this._items.some((item) => Object.is(item, value));
+	}
+	/** Adds `value` if not already present (no-op for duplicates). */
+	add(value) {
+		if (!this.has(value)) this._items.push(value);
+		return this;
+	}
+	/** Removes `value`. Returns `true` if found. */
+	delete(value) {
+		const index = this._items.findIndex((item) => Object.is(item, value));
+		if (index === -1) return false;
+		this._items.splice(index, 1);
+		return true;
+	}
+	/** Removes all items. Uses splice to trigger proxy notification. */
+	clear() {
+		this._items.splice(0, this._items.length);
+	}
+	/** Returns an iterator over the values (same as `values()`, matching Set API). */
+	keys() {
+		return this._items[Symbol.iterator]();
+	}
+	/** Returns an iterator over the values. */
+	values() {
+		return this._items[Symbol.iterator]();
+	}
+	/** Returns an iterator over [value, value] pairs, matching the native Set API. */
+	entries() {
+		return this._items.map((v) => [v, v])[Symbol.iterator]();
+	}
+	/** Calls `callback` for each item, matching the native `Set.forEach` signature. */
+	forEach(callback) {
+		for (const v of this._items) callback(v, v, this);
+	}
+	/** Enables `for...of` iteration over values. */
+	[Symbol.iterator]() {
+		return this.values();
+	}
+};
+/**
+* Creates a reactive Map-like collection backed by a plain array.
+* Wrap the parent object with `store()` for full reactivity.
+*
+* @param initial - Optional iterable of `[key, value]` pairs.
+*/
+function reactiveMap(initial) {
+	return new ReactiveMap(initial);
+}
+/**
+* Creates a reactive Set-like collection backed by a plain array.
+* Wrap the parent object with `store()` for full reactivity.
+*
+* @param initial - Optional iterable of values.
+*/
+function reactiveSet(initial) {
+	return new ReactiveSet(initial);
+}
+
+//#endregion
+//#region src/useStore.ts
+function useStore(proxyStore, selector, isEqual) {
+	require_snapshot.getInternal(proxyStore);
+	const subscribe$1 = (0, react.useCallback)((onStoreChange) => require_snapshot.subscribe(proxyStore, onStoreChange), [proxyStore]);
+	const snapRef = (0, react.useRef)(void 0);
+	const resultRef = (0, react.useRef)(void 0);
+	const affected = (0, react.useRef)(/* @__PURE__ */ new WeakMap()).current;
+	const proxyCache = (0, react.useRef)(/* @__PURE__ */ new WeakMap()).current;
+	const prevSnapRef = (0, react.useRef)(void 0);
+	const wrappedRef = (0, react.useRef)(void 0);
+	const getSnapshot = () => selector ? getSelectorSnapshot(proxyStore, snapRef, resultRef, selector, isEqual) : getAutoTrackSnapshot(proxyStore, affected, proxyCache, prevSnapRef, wrappedRef);
+	return (0, react.useSyncExternalStore)(subscribe$1, getSnapshot, getSnapshot);
+}
+/**
+* `getSnapshot` implementation for selector mode.
+*
+* Fast-paths when the snapshot reference hasn't changed (O(1)). Otherwise
+* runs the selector against the new snapshot and compares the result to the
+* previous one via `Object.is` (or a custom `isEqual`). Returns the previous
+* result reference when equal, preventing unnecessary React re-renders.
+*
+* Pure function -- no hooks, safe to call from `useSyncExternalStore`.
+*/
+function getSelectorSnapshot(proxyStore, snapRef, resultRef, selector, isEqual) {
+	const nextSnap = require_snapshot.snapshot(proxyStore);
+	if (snapRef.current === nextSnap && resultRef.current !== void 0) return resultRef.current;
+	const nextResult = selector(nextSnap);
+	snapRef.current = nextSnap;
+	if (resultRef.current !== void 0 && (isEqual ? isEqual(resultRef.current, nextResult) : Object.is(resultRef.current, nextResult))) return resultRef.current;
+	resultRef.current = nextResult;
+	return nextResult;
+}
+/**
+* `getSnapshot` implementation for auto-tracked (selectorless) mode.
+*
+* Uses `proxy-compare` to diff only the properties the component actually read.
+* If the snapshot reference is the same, returns the cached tracking proxy.
+* If the snapshot changed but no tracked property differs (`isChanged` returns
+* false), also returns the cached proxy -- avoiding re-render. Only when a
+* relevant property changed does it create a new `createProxy` wrapper.
+*
+* Pure function -- no hooks, safe to call from `useSyncExternalStore`.
+*/
+function getAutoTrackSnapshot(proxyStore, affected, proxyCache, prevSnapRef, wrappedRef) {
+	const nextSnap = require_snapshot.snapshot(proxyStore);
+	if (prevSnapRef.current === nextSnap) return wrappedRef.current;
+	if (prevSnapRef.current !== void 0 && !(0, proxy_compare.isChanged)(prevSnapRef.current, nextSnap, affected)) return wrappedRef.current;
+	prevSnapRef.current = nextSnap;
+	const wrapped = (0, proxy_compare.createProxy)(nextSnap, affected, proxyCache);
+	wrappedRef.current = wrapped;
+	return wrapped;
+}
+
+//#endregion
+exports.getVersion = require_snapshot.getVersion;
+exports.reactiveMap = reactiveMap;
+exports.reactiveSet = reactiveSet;
+exports.shallowEqual = require_snapshot.shallowEqual;
+exports.snapshot = require_snapshot.snapshot;
+exports.store = require_snapshot.store;
+exports.subscribe = require_snapshot.subscribe;
+exports.useStore = useStore;
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":["PROXYABLE","subscribe","coreSubscribe","snapshot"],"sources":["../src/collections.ts","../src/useStore.ts"],"sourcesContent":["import {PROXYABLE} from './utils';\n\n// ── ReactiveMap ───────────────────────────────────────────────────────────────\n\n/**\n * A Map-like class backed by a plain array so `store()` can proxy mutations.\n *\n * Native `Map` uses internal slots that ES6 Proxy can't intercept, so mutations\n * like `.set()` would be invisible to the store. `ReactiveMap` solves this by\n * storing entries in a plain array (`_entries`) that the proxy can track.\n *\n * Usage:\n * ```ts\n * const myStore = store({ users: reactiveMap<string, User>() });\n * myStore.users.set('id1', { name: 'Alice' }); // reactive\n * ```\n */\nexport class ReactiveMap<K, V> {\n  static [PROXYABLE] = true;\n\n  /** @internal Backing storage — proxied by store(). */\n  _entries: [K, V][] = [];\n\n  /** Deduplicates initial entries by key (last value wins, matching native `Map`). */\n  constructor(initial?: Iterable<[K, V]>) {\n    if (initial) {\n      for (const [k, v] of initial) {\n        const index = this._entries.findIndex(([ek]) => Object.is(ek, k));\n        if (index !== -1) {\n          this._entries[index] = [k, v];\n        } else {\n          this._entries.push([k, v]);\n        }\n      }\n    }\n  }\n\n  /** Returns the number of entries. */\n  get size(): number {\n    return this._entries.length;\n  }\n\n  /** Returns the value for `key`, or `undefined`. O(n) linear scan. */\n  get(key: K): V | undefined {\n    const entry = this._entries.find(([k]) => Object.is(k, key));\n    return entry ? entry[1] : undefined;\n  }\n\n  /** Returns `true` if `key` exists. O(n) linear scan. */\n  has(key: K): boolean {\n    return this._entries.some(([k]) => Object.is(k, key));\n  }\n\n  /** Sets `key` to `value`. Updates in-place if key exists, appends otherwise. */\n  set(key: K, value: V): this {\n    const index = this._entries.findIndex(([k]) => Object.is(k, key));\n    if (index !== -1) {\n      this._entries[index] = [key, value];\n    } else {\n      this._entries.push([key, value]);\n    }\n    return this;\n  }\n\n  /** Removes the entry for `key`. Returns `true` if found. */\n  delete(key: K): boolean {\n    const index = this._entries.findIndex(([k]) => Object.is(k, key));\n    if (index === -1) return false;\n    this._entries.splice(index, 1);\n    return true;\n  }\n\n  /** Removes all entries. Uses splice to trigger proxy notification. */\n  clear(): void {\n    this._entries.splice(0, this._entries.length);\n  }\n\n  /** Returns an iterator over the keys. */\n  keys(): IterableIterator<K> {\n    return this._entries.map(([k]) => k)[Symbol.iterator]();\n  }\n\n  /** Returns an iterator over the values. */\n  values(): IterableIterator<V> {\n    return this._entries.map(([, v]) => v)[Symbol.iterator]();\n  }\n\n  /** Returns an iterator over [key, value] pairs. */\n  entries(): IterableIterator<[K, V]> {\n    return this._entries.map(([k, v]) => [k, v] as [K, V])[Symbol.iterator]();\n  }\n\n  /** Calls `callback` for each entry, matching the native `Map.forEach` signature. */\n  forEach(callback: (value: V, key: K, map: ReactiveMap<K, V>) => void): void {\n    for (const [k, v] of this._entries) {\n      callback(v, k, this);\n    }\n  }\n\n  /** Enables `for...of` iteration over [key, value] pairs. */\n  [Symbol.iterator](): IterableIterator<[K, V]> {\n    return this.entries();\n  }\n}\n\n// ── ReactiveSet ───────────────────────────────────────────────────────────────\n\n/**\n * A Set-like class backed by a plain array so `store()` can proxy mutations.\n *\n * Native `Set` uses internal slots that ES6 Proxy can't intercept, so mutations\n * like `.add()` would be invisible to the store. `ReactiveSet` solves this by\n * storing items in a plain array (`_items`) that the proxy can track.\n *\n * Usage:\n * ```ts\n * const myStore = store({ tags: reactiveSet<string>(['urgent']) });\n * myStore.tags.add('bug'); // reactive\n * ```\n */\nexport class ReactiveSet<T> {\n  static [PROXYABLE] = true;\n\n  /** @internal Backing storage — proxied by store(). */\n  _items: T[] = [];\n\n  /** Deduplicates initial values using `Object.is` comparison. */\n  constructor(initial?: Iterable<T>) {\n    if (initial) {\n      for (const v of initial) {\n        if (!this._items.some((item) => Object.is(item, v))) {\n          this._items.push(v);\n        }\n      }\n    }\n  }\n\n  /** Returns the number of unique items. */\n  get size(): number {\n    return this._items.length;\n  }\n\n  /** Returns `true` if `value` exists. O(n) linear scan. */\n  has(value: T): boolean {\n    return this._items.some((item) => Object.is(item, value));\n  }\n\n  /** Adds `value` if not already present (no-op for duplicates). */\n  add(value: T): this {\n    if (!this.has(value)) {\n      this._items.push(value);\n    }\n    return this;\n  }\n\n  /** Removes `value`. Returns `true` if found. */\n  delete(value: T): boolean {\n    const index = this._items.findIndex((item) => Object.is(item, value));\n    if (index === -1) return false;\n    this._items.splice(index, 1);\n    return true;\n  }\n\n  /** Removes all items. Uses splice to trigger proxy notification. */\n  clear(): void {\n    this._items.splice(0, this._items.length);\n  }\n\n  /** Returns an iterator over the values (same as `values()`, matching Set API). */\n  keys(): IterableIterator<T> {\n    return this._items[Symbol.iterator]();\n  }\n\n  /** Returns an iterator over the values. */\n  values(): IterableIterator<T> {\n    return this._items[Symbol.iterator]();\n  }\n\n  /** Returns an iterator over [value, value] pairs, matching the native Set API. */\n  entries(): IterableIterator<[T, T]> {\n    return this._items.map((v) => [v, v] as [T, T])[Symbol.iterator]();\n  }\n\n  /** Calls `callback` for each item, matching the native `Set.forEach` signature. */\n  forEach(callback: (value: T, key: T, set: ReactiveSet<T>) => void): void {\n    for (const v of this._items) {\n      callback(v, v, this);\n    }\n  }\n\n  /** Enables `for...of` iteration over values. */\n  [Symbol.iterator](): IterableIterator<T> {\n    return this.values();\n  }\n}\n\n// ── Factory functions ─────────────────────────────────────────────────────────\n\n/**\n * Creates a reactive Map-like collection backed by a plain array.\n * Wrap the parent object with `store()` for full reactivity.\n *\n * @param initial - Optional iterable of `[key, value]` pairs.\n */\nexport function reactiveMap<K, V>(\n  initial?: Iterable<[K, V]>,\n): ReactiveMap<K, V> {\n  return new ReactiveMap(initial);\n}\n\n/**\n * Creates a reactive Set-like collection backed by a plain array.\n * Wrap the parent object with `store()` for full reactivity.\n *\n * @param initial - Optional iterable of values.\n */\nexport function reactiveSet<T>(initial?: Iterable<T>): ReactiveSet<T> {\n  return new ReactiveSet(initial);\n}\n","import {createProxy, isChanged} from 'proxy-compare';\nimport {useCallback, useRef, useSyncExternalStore} from 'react';\nimport {subscribe as coreSubscribe, getInternal} from './core';\nimport {snapshot} from './snapshot';\nimport type {Snapshot} from './types';\n\n// ── Overloads ─────────────────────────────────────────────────────────────────\n\n/**\n * Subscribe to a store proxy with an explicit selector.\n *\n * Re-renders only when the selected value changes (compared via `Object.is`\n * by default, or a custom `isEqual`).\n *\n * @param proxyStore - A reactive proxy created by `store()`.\n * @param selector  - Picks data from the immutable snapshot.\n * @param isEqual   - Optional custom equality function (default: `Object.is`).\n */\nexport function useStore<T extends object, S>(\n  proxyStore: T,\n  selector: (snap: Snapshot<T>) => S,\n  isEqual?: (a: S, b: S) => boolean,\n): S;\n\n/**\n * Subscribe to a store proxy **without** a selector (auto-tracked mode).\n *\n * Returns a `proxy-compare` tracking proxy over the immutable snapshot.\n * The component only re-renders when a property it actually read changes.\n *\n * @param proxyStore - A reactive proxy created by `store()`.\n */\nexport function useStore<T extends object>(proxyStore: T): Snapshot<T>;\n\n// ── Implementation ────────────────────────────────────────────────────────────\n\nexport function useStore<T extends object, S>(\n  proxyStore: T,\n  selector?: (snap: Snapshot<T>) => S,\n  isEqual?: (a: S, b: S) => boolean,\n): Snapshot<T> | S {\n  // Validate that the argument is actually a store proxy (throws if not).\n  getInternal(proxyStore);\n\n  // Stable subscribe function (internal identity never changes for a given store).\n  const subscribe = useCallback(\n    (onStoreChange: () => void) => coreSubscribe(proxyStore, onStoreChange),\n    [proxyStore],\n  );\n\n  // ── Refs used by both modes (always allocated to satisfy Rules of Hooks) ──\n\n  // Selector mode refs\n  const snapRef = useRef<Snapshot<T> | undefined>(undefined);\n  const resultRef = useRef<S | undefined>(undefined);\n\n  // Auto-track mode refs\n  const affected = useRef(new WeakMap<object, unknown>()).current;\n  const proxyCache = useRef(new WeakMap<object, unknown>()).current;\n  const prevSnapRef = useRef<Snapshot<T> | undefined>(undefined);\n  const wrappedRef = useRef<Snapshot<T> | undefined>(undefined);\n\n  // ── Single getSnapshot for useSyncExternalStore ───────────────────────────\n\n  const getSnapshot = (): Snapshot<T> | S =>\n    selector\n      ? getSelectorSnapshot(proxyStore, snapRef, resultRef, selector, isEqual)\n      : getAutoTrackSnapshot(\n          proxyStore,\n          affected,\n          proxyCache,\n          prevSnapRef,\n          wrappedRef,\n        );\n\n  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);\n}\n\n// ── Selector mode logic (pure function, no hooks) ─────────────────────────────\n\n/**\n * `getSnapshot` implementation for selector mode.\n *\n * Fast-paths when the snapshot reference hasn't changed (O(1)). Otherwise\n * runs the selector against the new snapshot and compares the result to the\n * previous one via `Object.is` (or a custom `isEqual`). Returns the previous\n * result reference when equal, preventing unnecessary React re-renders.\n *\n * Pure function -- no hooks, safe to call from `useSyncExternalStore`.\n */\nfunction getSelectorSnapshot<T extends object, S>(\n  proxyStore: T,\n  snapRef: React.RefObject<Snapshot<T> | undefined>,\n  resultRef: React.RefObject<S | undefined>,\n  selector: (snap: Snapshot<T>) => S,\n  isEqual?: (a: S, b: S) => boolean,\n): S {\n  const nextSnap = snapshot(proxyStore);\n\n  // Fast path: same snapshot reference → same result.\n  if (snapRef.current === nextSnap && resultRef.current !== undefined) {\n    return resultRef.current;\n  }\n\n  const nextResult = selector(nextSnap);\n  snapRef.current = nextSnap;\n\n  // Check equality with previous result.\n  if (\n    resultRef.current !== undefined &&\n    (isEqual\n      ? isEqual(resultRef.current, nextResult)\n      : Object.is(resultRef.current, nextResult))\n  ) {\n    return resultRef.current;\n  }\n\n  resultRef.current = nextResult;\n  return nextResult;\n}\n\n// ── Auto-tracked (selectorless) mode logic (pure function, no hooks) ──────────\n\n/**\n * `getSnapshot` implementation for auto-tracked (selectorless) mode.\n *\n * Uses `proxy-compare` to diff only the properties the component actually read.\n * If the snapshot reference is the same, returns the cached tracking proxy.\n * If the snapshot changed but no tracked property differs (`isChanged` returns\n * false), also returns the cached proxy -- avoiding re-render. Only when a\n * relevant property changed does it create a new `createProxy` wrapper.\n *\n * Pure function -- no hooks, safe to call from `useSyncExternalStore`.\n */\nfunction getAutoTrackSnapshot<T extends object>(\n  proxyStore: T,\n  affected: WeakMap<object, unknown>,\n  proxyCache: WeakMap<object, unknown>,\n  prevSnapRef: React.RefObject<Snapshot<T> | undefined>,\n  wrappedRef: React.RefObject<Snapshot<T> | undefined>,\n): Snapshot<T> {\n  const nextSnap = snapshot(proxyStore);\n\n  // If the raw snapshot is the same reference, nothing changed.\n  if (prevSnapRef.current === nextSnap) {\n    return wrappedRef.current as Snapshot<T>;\n  }\n\n  // Check if any property the component actually read has changed.\n  if (\n    prevSnapRef.current !== undefined &&\n    !isChanged(prevSnapRef.current, nextSnap, affected)\n  ) {\n    // No property the component cares about changed → return same wrapped proxy.\n    return wrappedRef.current as Snapshot<T>;\n  }\n\n  // Something relevant changed — create a new tracking proxy.\n  prevSnapRef.current = nextSnap;\n  const wrapped = createProxy(nextSnap, affected, proxyCache) as Snapshot<T>;\n  wrappedRef.current = wrapped;\n  return wrapped;\n}\n"],"mappings":"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"}

package/dist/index.d.cts

@@ -0,0 +1,215 @@
+//#region src/utils.d.ts
+/**
+ * Symbol that class instances can use to opt-in to deep proxying.
+ * Classes with `static [PROXYABLE] = true` will be wrapped by the store proxy
+ * just like plain objects, enabling nested reactivity.
+ */
+declare const PROXYABLE: unique symbol;
+/**
+ * Shallow-equal comparison for objects and arrays.
+ * Useful as a custom `isEqual` for `useStore` selectors that return objects/arrays.
+ *
+ * - Primitives compared with `Object.is`.
+ * - Arrays: length + element-wise `Object.is`.
+ * - Objects: key count + value-wise `Object.is`.
+ */
+declare function shallowEqual<T>(a: T, b: T): boolean;
+//#endregion
+//#region src/collections.d.ts
+/**
+ * A Map-like class backed by a plain array so `store()` can proxy mutations.
+ *
+ * Native `Map` uses internal slots that ES6 Proxy can't intercept, so mutations
+ * like `.set()` would be invisible to the store. `ReactiveMap` solves this by
+ * storing entries in a plain array (`_entries`) that the proxy can track.
+ *
+ * Usage:
+ * ```ts
+ * const myStore = store({ users: reactiveMap<string, User>() });
+ * myStore.users.set('id1', { name: 'Alice' }); // reactive
+ * ```
+ */
+declare class ReactiveMap<K, V> {
+  static [PROXYABLE]: boolean;
+  /** @internal Backing storage — proxied by store(). */
+  _entries: [K, V][];
+  /** Deduplicates initial entries by key (last value wins, matching native `Map`). */
+  constructor(initial?: Iterable<[K, V]>);
+  /** Returns the number of entries. */
+  get size(): number;
+  /** Returns the value for `key`, or `undefined`. O(n) linear scan. */
+  get(key: K): V | undefined;
+  /** Returns `true` if `key` exists. O(n) linear scan. */
+  has(key: K): boolean;
+  /** Sets `key` to `value`. Updates in-place if key exists, appends otherwise. */
+  set(key: K, value: V): this;
+  /** Removes the entry for `key`. Returns `true` if found. */
+  delete(key: K): boolean;
+  /** Removes all entries. Uses splice to trigger proxy notification. */
+  clear(): void;
+  /** Returns an iterator over the keys. */
+  keys(): IterableIterator<K>;
+  /** Returns an iterator over the values. */
+  values(): IterableIterator<V>;
+  /** Returns an iterator over [key, value] pairs. */
+  entries(): IterableIterator<[K, V]>;
+  /** Calls `callback` for each entry, matching the native `Map.forEach` signature. */
+  forEach(callback: (value: V, key: K, map: ReactiveMap<K, V>) => void): void;
+  /** Enables `for...of` iteration over [key, value] pairs. */
+  [Symbol.iterator](): IterableIterator<[K, V]>;
+}
+/**
+ * A Set-like class backed by a plain array so `store()` can proxy mutations.
+ *
+ * Native `Set` uses internal slots that ES6 Proxy can't intercept, so mutations
+ * like `.add()` would be invisible to the store. `ReactiveSet` solves this by
+ * storing items in a plain array (`_items`) that the proxy can track.
+ *
+ * Usage:
+ * ```ts
+ * const myStore = store({ tags: reactiveSet<string>(['urgent']) });
+ * myStore.tags.add('bug'); // reactive
+ * ```
+ */
+declare class ReactiveSet<T> {
+  static [PROXYABLE]: boolean;
+  /** @internal Backing storage — proxied by store(). */
+  _items: T[];
+  /** Deduplicates initial values using `Object.is` comparison. */
+  constructor(initial?: Iterable<T>);
+  /** Returns the number of unique items. */
+  get size(): number;
+  /** Returns `true` if `value` exists. O(n) linear scan. */
+  has(value: T): boolean;
+  /** Adds `value` if not already present (no-op for duplicates). */
+  add(value: T): this;
+  /** Removes `value`. Returns `true` if found. */
+  delete(value: T): boolean;
+  /** Removes all items. Uses splice to trigger proxy notification. */
+  clear(): void;
+  /** Returns an iterator over the values (same as `values()`, matching Set API). */
+  keys(): IterableIterator<T>;
+  /** Returns an iterator over the values. */
+  values(): IterableIterator<T>;
+  /** Returns an iterator over [value, value] pairs, matching the native Set API. */
+  entries(): IterableIterator<[T, T]>;
+  /** Calls `callback` for each item, matching the native `Set.forEach` signature. */
+  forEach(callback: (value: T, key: T, set: ReactiveSet<T>) => void): void;
+  /** Enables `for...of` iteration over values. */
+  [Symbol.iterator](): IterableIterator<T>;
+}
+/**
+ * Creates a reactive Map-like collection backed by a plain array.
+ * Wrap the parent object with `store()` for full reactivity.
+ *
+ * @param initial - Optional iterable of `[key, value]` pairs.
+ */
+declare function reactiveMap<K, V>(initial?: Iterable<[K, V]>): ReactiveMap<K, V>;
+/**
+ * Creates a reactive Set-like collection backed by a plain array.
+ * Wrap the parent object with `store()` for full reactivity.
+ *
+ * @param initial - Optional iterable of values.
+ */
+declare function reactiveSet<T>(initial?: Iterable<T>): ReactiveSet<T>;
+//#endregion
+//#region src/types.d.ts
+/**
+ * Primitive types that should not be proxied or snapshot-cloned.
+ * Used by `Snapshot<T>` to identify leaf types that pass through unchanged.
+ */
+type Primitive = string | number | boolean | null | undefined | symbol | bigint;
+/**
+ * Function type shorthand.
+ * Functions are treated as snapshot leaves -- they pass through unchanged
+ * because freezing or cloning them would break callable references.
+ */
+type AnyFunction = (...args: unknown[]) => unknown;
+/**
+ * Types that `snapshot()` returns as-is (no deep clone or freeze).
+ * These are either already immutable-ish (Date, RegExp), use internal slots
+ * that proxies can't intercept (Map, Set, WeakMap, WeakSet), or can't be
+ * meaningfully frozen (functions, Promises, Errors).
+ */
+type SnapshotLeaf = Primitive | AnyFunction | Date | RegExp | Error | Map<unknown, unknown> | Set<unknown> | WeakMap<object, unknown> | WeakSet<object> | Promise<unknown>;
+/**
+ * Recursively converts an object type to a deeply readonly version.
+ * Leaf types (primitives, Date, Map, etc.) pass through unchanged.
+ */
+type Snapshot<T> = T extends SnapshotLeaf ? T : T extends Array<infer U> ? ReadonlyArray<Snapshot<U>> : T extends object ? { readonly [K in keyof T]: Snapshot<T[K]> } : T;
+//#endregion
+//#region src/core.d.ts
+/**
+ * Wraps a class instance in a reactive proxy.
+ *
+ * - Mutations (property writes, array push/splice, etc.) are intercepted and
+ *   batched into a single notification per microtask.
+ * - Class getters are automatically memoized — they only recompute when a
+ *   dependency they read changes.
+ * - Methods are automatically bound so `this` mutations go through the proxy.
+ *
+ * @param instance - A class instance (or plain object) to make reactive.
+ * @returns The same object wrapped in a reactive Proxy.
+ */
+declare function store<T extends object>(instance: T): T;
+/**
+ * Subscribe to store changes. The callback fires once per batched mutation
+ * (coalesced via `queueMicrotask`), not once per individual property write.
+ *
+ * @param proxy - A reactive proxy created by `store()`.
+ * @param callback - Invoked after each batched mutation.
+ * @returns An unsubscribe function. Call it to stop receiving notifications.
+ */
+declare function subscribe(proxy: object, callback: () => void): () => void;
+/**
+ * Returns the current version number of a store proxy.
+ *
+ * Versions are monotonically increasing and bump on any mutation in the
+ * store's subtree (child mutations propagate up to the root). Useful for
+ * debugging, custom cache invalidation, or testing whether a store has changed.
+ */
+declare function getVersion(proxy: object): number;
+//#endregion
+//#region src/snapshot.d.ts
+/**
+ * Creates an immutable, deeply-frozen snapshot of the store proxy's current state.
+ *
+ * **Structural sharing:** unchanged sub-trees reuse the previous snapshot's
+ * object reference, so `===` comparison can cheaply detect changes.
+ *
+ * **Version-cached:** calling `snapshot()` multiple times without intervening
+ * mutations returns the identical snapshot object (O(1) cache hit).
+ *
+ * **Getters:** class getters are automatically memoized — they compute once
+ * per snapshot and their results are stable across snapshots when dependencies
+ * haven't changed (cross-snapshot memoization).
+ *
+ * @param proxyStore - A reactive proxy created by `store()`.
+ * @returns A deeply frozen plain-JS object (Snapshot<T>).
+ */
+declare function snapshot<T extends object>(proxyStore: T): Snapshot<T>;
+//#endregion
+//#region src/useStore.d.ts
+/**
+ * Subscribe to a store proxy with an explicit selector.
+ *
+ * Re-renders only when the selected value changes (compared via `Object.is`
+ * by default, or a custom `isEqual`).
+ *
+ * @param proxyStore - A reactive proxy created by `store()`.
+ * @param selector  - Picks data from the immutable snapshot.
+ * @param isEqual   - Optional custom equality function (default: `Object.is`).
+ */
+declare function useStore<T extends object, S>(proxyStore: T, selector: (snap: Snapshot<T>) => S, isEqual?: (a: S, b: S) => boolean): S;
+/**
+ * Subscribe to a store proxy **without** a selector (auto-tracked mode).
+ *
+ * Returns a `proxy-compare` tracking proxy over the immutable snapshot.
+ * The component only re-renders when a property it actually read changes.
+ *
+ * @param proxyStore - A reactive proxy created by `store()`.
+ */
+declare function useStore<T extends object>(proxyStore: T): Snapshot<T>;
+//#endregion
+export { type ReactiveMap, type ReactiveSet, type Snapshot, getVersion, reactiveMap, reactiveSet, shallowEqual, snapshot, store, subscribe, useStore };
+//# sourceMappingURL=index.d.cts.map

package/dist/index.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.cts","names":[],"sources":["../src/utils.ts","../src/collections.ts","../src/types.ts","../src/core.ts","../src/snapshot.ts","../src/useStore.ts"],"mappings":"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"}