@storve/core 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,151 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [1.0.0] - 2026-03-14
+
+### Added
+- Getting Started in 5 minutes section in README
+- Migration guides — Redux → Storve, Zustand → Storve
+- StackBlitz interactive demo (Counter, Todo, Async)
+- Bundle size and test count badges
+
+### Changed
+- Roadmap updated to reflect shipped features and planned v1.1–v1.3
+- Test count updated to 937 across 29 test files
+- Coverage badge updated to 99%
+
+### Notes
+- Stable API — no breaking changes planned until v2.0
+- All subpath imports locked: storve, storve/async, storve/computed,
+  storve/persist, storve/signals, storve/devtools, storve/sync
+
+---
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [0.7.0] - 2026-03-14
+
+### Added — `storve/sync`
+- `withSync` — cross-tab state synchronization using `BroadcastChannel`.
+- Automatic state rehydration across tabs on initialization.
+- Selective key synchronization via `SyncOptions`.
+- Tree-shakable subpath import: `storve/sync`.
+- Full integration with existing extensions (DevTools, Persist).
+- 100% test coverage for sync logic.
+
+## [0.6.0] - 2026-03-14
+
+### Added
+- `storve/devtools` entry point for time-travel debugging.
+- `withDevtools` store enhancer for ring-buffer history and Redux DevTools integration.
+- `undo()` and `redo()` API on stores.
+- `canUndo` and `canRedo` flags.
+- `snapshot()` and `restore()` for named state checkpoints.
+- `useDevtools` React hook for reactive access to devtools state.
+- Redux DevTools extension support (JUMP_TO_STATE, RESET).
+
+### Fixed
+- Internal: extensions now receive the store instance and original definition.
+- Internal: added `Object.defineProperties` support for extension method merging.
+- Internal: triggered initial state change notification for early extension initialization.
+
+## [0.5.0] - 2026-03-14
+
+### Added — `storve/signals`
+- `signal(store, key)` — fine-grained reactivity for individual store keys
+- `signal(store, key, transform)` — read-only derived signals with automatic dependency filtering
+- `useSignal(signal)` — React hook for zero-overhead subscription to specific state slices
+- `Object.is` value filtering — zero re-renders unless the specific signal value actually changes
+- 100% test coverage for signals package
+- Tree-shakable subpath import: `storve/signals`
+- Bundle size: < 0.6KB for signals entry point
+
+## [0.4.0] - 2026-03-12
+
+### Added — `storve/persist`
+- `withPersist` — persist store state with pluggable adapters
+- `localStorageAdapter`, `sessionStorageAdapter`, `memoryAdapter`, `indexedDBAdapter`.
+- `compose()` — compose multiple store enhancers cleanly.
+- Version + migration support for schema changes.
+- Configurable debounce on writes.
+- SSR safe — all adapters guard against missing window/indexedDB.
+
+### Added — `storve/async`
+- `createAsync(fetcher, options)` — core engine for async state management.
+- Lifecycle management — automatic tracking of `idle`, `loading`, `success`, and `error` states.
+- Advanced caching — TTL (Time-To-Live) and SWR (Stale-While-Revalidate) support.
+- Optimistic updates — immediate UI feedback with automatic rollback on failure.
+- Argument-aware fetching — separate cache entries based on fetcher arguments.
+
+### Changed — BREAKING
+- **Barrel import removed.** Use subpath imports:
+  - `import { createStore, batch } from 'storve'` — core only (~1.4KB gzipped)
+  - `import { createAsync } from 'storve/async'` — async support (~1.1KB gzipped)
+  - `import { computed } from 'storve/computed'` — computed support (~0.8KB gzipped)
+- Store without async extension: `fetch()` throws with message to import `storve/async`
+
+### Fixed
+- Bundle sizes: core 1.4KB, async 1.1KB, computed 0.8KB (gzipped, with Terser).
+- ESLint: Replaced `@ts-ignore` with `@ts-expect-error` across benchmarks.
+
+---
+
+## [0.3.0] - 2026-03-01
+### Added — `storve-core`
+- `actions` support inside `createStore()` — define methods inline, auto-bound, excluded from state
+- Async action support — actions can be `async` and notify subscribers on completion
+- Immer integration — `setState(draft => { ... })` mutation style via `{ immer: true }` store option
+- `store.batch(fn)` — multiple `setState()` calls inside a batch fire exactly one subscriber notification
+- Nested batch support via internal `batchCount` counter
+- `batchDirty` flag — empty batch fires zero notifications
+- `store.actions` stable reference — same object across renders, safe to spread in hooks
+- Added types: `StoreState<D>`, `StoreActions<D>`, `StoreOptions`
+- Updated `Store<D>` interface — `getState()` returns state only, actions excluded from state type
+- Added `immer` to `peerDependencies` — not bundled, tree-shaken when unused
+- 85+ new tests across `actions.test.ts`, `immer.test.ts`, `batch.test.ts`
+- Week 4 performance benchmarks: action calls, Immer mutations, batch notification overhead
+
+### Fixed — `storve-react`
+- `useStore` regression — hook was merging actions into result even when a selector was provided, causing React to throw "Objects are not valid as a React child" for primitive selector returns
+- Moved selector logic into `getSnapshot` so React correctly detects value changes
+- Selector path now returns selected value directly — no action merging
+- No-selector path merges actions at return time only, after `useSyncExternalStore`
+- Shallow copy in no-selector snapshot fixes Proxy same-reference issue
+- `shallowEqual` on object selector results prevents unnecessary re-renders
+- Store reference change correctly invalidates snapshot cache
+- Confirmed zero hook rule violations — no conditional hook calls
+
+### Fixed — `storve-react` (ESLint)
+- Removed unused `useState` import in `lifecycle.test.tsx`
+- Replaced `any` with typed alternatives across `selector.test.tsx` and `useStore.test.tsx`
+- Fixed `no-unused-vars` in `benchmarks/week3.ts` — replaced `const _ = ...` with `void`
+
+---
+
+## [0.2.0] - 2026-02-28
+### Added — `storve-react`
+- `useStore()` hook using `useSyncExternalStore` (React 18)
+- Selector support as optional second argument to `useStore()`
+- Concurrent mode safety — verified with React 18 concurrent test suite
+- Auto-cleanup of subscriptions on component unmount
+- Integration tests with React Testing Library
+- Performance benchmarks for subscription setup, cleanup, selector execution
+- 55 tests passing across 6 test files
+
+---
+
+## [0.1.0] - 2026-02-28
+### Added — `storve-core`
+- Initial `createStore()` implementation
+- Proxy-based auto-tracking for state mutations with eager wrapping for deep paths
+- Proper interception of arrays (`push`, `pop`, `splice`, index sets)
+- Store subscription mechanism via `subscribe()`
+- `getState()` and `setState()` — plain object and updater function forms
+- Added types: `StoreDefinition`, `Listener`, `Unsubscribe`, `Store`
+- Full test coverage for core store (100% functions, 95%+ statements)
+- Week 3 performance benchmarks and limits verification
+ (100% functions, 95%+ statements)
+- Week 3 performance benchmarks and limits verification

package/benchmarks/run.ts

@@ -0,0 +1,102 @@
+import { performance } from 'perf_hooks'
+import { createStore } from '../src/index'
+
+type BenchmarkResult = {
+    operation: string
+    averageMs: string
+    status: string
+}
+
+function bench(label: string, fn: () => void, iterations = 100_000): BenchmarkResult {
+    // Warmup
+    for (let i = 0; i < 1000; i++) fn()
+
+    const start = performance.now()
+    for (let i = 0; i < iterations; i++) fn()
+    const avg = (performance.now() - start) / iterations
+
+    const limits: Record<string, number> = {
+        'createStore() call': 1,
+        'getState() read': 0.1,
+        'setState() write + notify (100 subs)': 1,
+        'Nested read (3 levels deep)': 0.1,
+        'Subscribe + Unsubscribe cycle': 0.1,
+    }
+
+    const limit = limits[label]
+    const status = avg <= limit ? '✅ PASS' : '❌ FAIL'
+
+    return {
+        operation: label,
+        averageMs: avg.toFixed(8) + 'ms',
+        status,
+    }
+}
+
+function runBenchmarks(): void {
+    console.log('\n⚡ Storve — Benchmark Results\n')
+
+    const results: BenchmarkResult[] = []
+
+    // 1. createStore
+    results.push(bench('createStore() call', () => {
+        createStore({ count: 0, name: 'test' })
+    }, 10_000))
+
+    // 2. getState
+    const storeForGet = createStore({ count: 0 })
+    results.push(bench('getState() read', () => {
+        storeForGet.getState()
+    }))
+
+    // 3. setState + notify with 100 subscribers
+    const storeForSet = createStore({ count: 0 })
+    for (let i = 0; i < 100; i++) storeForSet.subscribe(() => { })
+    let counter = 0
+    results.push(bench('setState() write + notify (100 subs)', () => {
+        storeForSet.setState({ count: counter++ })
+    }, 10_000))
+
+    // 4. Nested read
+    const storeForNested = createStore({
+        level1: { level2: { level3: { value: 42 } } },
+    })
+    results.push(bench('Nested read (3 levels deep)', () => {
+        storeForNested.getState().level1.level2.level3.value
+    }))
+
+    // 5. Subscribe + Unsubscribe
+    const storeForSub = createStore({ count: 0 })
+    results.push(bench('Subscribe + Unsubscribe cycle', () => {
+        const unsub = storeForSub.subscribe(() => { })
+        unsub()
+    }))
+
+    // Print table
+    const colWidths = { operation: 45, averageMs: 20, status: 10 }
+    const header =
+        'Operation'.padEnd(colWidths.operation) +
+        'Average Time'.padEnd(colWidths.averageMs) +
+        'Status'
+    const divider = '-'.repeat(header.length)
+
+    console.log(header)
+    console.log(divider)
+
+    let allPassed = true
+    for (const r of results) {
+        if (r.status.includes('FAIL')) allPassed = false
+        console.log(
+            r.operation.padEnd(colWidths.operation) +
+            r.averageMs.padEnd(colWidths.averageMs) +
+            r.status
+        )
+    }
+
+    console.log(divider)
+    console.log(allPassed ? '\n✅ All benchmarks passed!\n' : '\n❌ Some benchmarks failed!\n')
+
+    if (!allPassed) process.exit(1)
+}
+
+runBenchmarks()

package/benchmarks/week2.md

@@ -0,0 +1,9 @@
+# Week 2 Benchmarks
+
+| Operation | Average Time (ms) |
+|---|---|
+| createStore() call | 0.0891ms |
+| getState() read | 0.000001ms |
+| setState() write + notify (100 subs) | 0.001450ms |
+| Nested read (3 levels deep) | 0.000005ms |
+| Subscribe + Unsubscribe cycle | 0.000159ms |

package/benchmarks/week2.ts

@@ -0,0 +1,64 @@
+import { performance } from 'perf_hooks';
+import * as fs from 'fs';
+import * as path from 'path';
+import { createStore } from '../src/store';
+
+function measure(name: string, fn: () => void, iterations = 10000) {
+    const start = performance.now();
+    for (let i = 0; i < iterations; i++) {
+        fn();
+    }
+    const duration = performance.now() - start;
+    const avg = duration / iterations;
+    return `| ${name} | ${avg.toFixed(6)}ms |`;
+}
+
+async function run() {
+    const results = [
+        `# Week 2 Benchmarks`,
+        ``,
+        `| Operation | Average Time (ms) |`,
+        `|---|---|`
+    ];
+
+    // createStore() call (< 1ms)
+    const t0 = performance.now();
+    const store = createStore({ count: 0 });
+    const createTime = performance.now() - t0;
+    results.push(`| createStore() call | ${createTime.toFixed(4)}ms |`);
+
+    // getState() read (< 0.1ms)
+    results.push(measure('getState() read', () => {
+        store.getState();
+    }, 1000000));
+
+    // setState() write + notify (< 1ms for 100 subscribers)
+    const storeWithSubs = createStore({ value: 0 });
+    for (let i = 0; i < 100; i++) {
+        storeWithSubs.subscribe(() => { });
+    }
+    results.push(measure('setState() write + notify (100 subs)', () => {
+        storeWithSubs.setState({ value: Math.random() });
+    }, 1000));
+
+    // Nested read (3 levels deep) (< 0.1ms)
+    const nestedStore = createStore({ root: { level1: { level2: { val: 42 } } } });
+    results.push(measure('Nested read (3 levels deep)', () => {
+        void nestedStore.getState().root.level1.level2.val;
+    }, 1000000));
+
+    // Subscribe + Unsubscribe cycle (< 0.1ms)
+    const subStore = createStore({ x: 1 });
+    results.push(measure('Subscribe + Unsubscribe cycle', () => {
+        const unsub = subStore.subscribe(() => { });
+        unsub();
+    }));
+
+    const content = results.join('\n');
+    console.log(content);
+
+    fs.mkdirSync(path.join(process.cwd(), 'benchmarks'), { recursive: true });
+    fs.writeFileSync(path.join(process.cwd(), 'benchmarks', 'week2.md'), content);
+}
+
+run();

package/benchmarks/week4.md

@@ -0,0 +1,13 @@
+# Week 4 Benchmarks (v0.3)
+
+| Operation | Average Time | Status |
+| :--- | :--- | :--- |
+| action call (no-arg) | 0.00026063ms | ✅ PASS |
+| action call (with arg) | 0.00026390ms | ✅ PASS |
+| action call (async dispatch) | 0.00019697ms | ✅ PASS |
+| setState (immer mutator, primitive) | 0.00077454ms | ✅ PASS |
+| setState (immer mutator, nested object) | 0.00252697ms | ✅ PASS |
+| setState (immer mutator, array push) | 0.00828483ms | ✅ PASS |
+| batch (3x setState, 1 notify) | 0.00259722ms | ✅ PASS |
+| batch (10x setState, 1 notify) | 0.03388838ms | ✅ PASS |
+| action excluded from getState() | 0.00000872ms | ✅ PASS |

package/benchmarks/week4.ts

@@ -0,0 +1,178 @@
+import { createStore } from '../src'
+
+interface BenchmarkResult {
+    operation: string
+    averageMs: string
+    status: string
+}
+
+function bench(
+    label: string,
+    fn: () => void,
+    iterations = 100_000
+): BenchmarkResult {
+    // Warmup
+    for (let i = 0; i < 1000; i++) fn()
+
+    const start = performance.now()
+    for (let i = 0; i < iterations; i++) fn()
+    const end = performance.now()
+
+    const avg = (end - start) / iterations
+
+    const limits: Record<string, number> = {
+        'action call (no-arg)': 0.5,
+        'action call (with arg)': 0.5,
+        'action call (async dispatch)': 1.0,
+        'setState (immer mutator, primitive)': 1.0,
+        'setState (immer mutator, nested object)': 2.0,
+        'setState (immer mutator, array push)': 2.0,
+        'batch (3x setState, 1 notify)': 1.5,
+        'batch (10x setState, 1 notify)': 3.0,
+        'action excluded from getState()': 0.2,
+    }
+
+    const limit = limits[label] ?? 1
+    const status = avg <= limit ? '✅ PASS' : '❌ FAIL'
+    return { operation: label, averageMs: avg.toFixed(8) + 'ms', status }
+}
+
+function runBenchmarks(): void {
+    console.log('\n⚡ Storve Core — Week 4 Benchmark Results (v0.3)\n')
+
+    const results: BenchmarkResult[] = []
+
+    // ── 1. Action call — no argument
+    const store1 = createStore({
+        count: 0,
+        actions: {
+            increment() { store1.setState(s => ({ count: s.count + 1 })) }
+        }
+    })
+    results.push(bench('action call (no-arg)', () => {
+        store1.increment()
+    }))
+
+    // ── 2. Action call — with argument
+    const store2 = createStore({
+        count: 0,
+        actions: {
+            incrementBy(n: number) { store2.setState(s => ({ count: s.count + n })) }
+        }
+    })
+    results.push(bench('action call (with arg)', () => {
+        store2.incrementBy(1)
+    }))
+
+    // ── 3. Async action dispatch (fire, don't await — measures dispatch overhead)
+    const store3 = createStore({
+        count: 0,
+        actions: {
+            async incrementAsync() {
+                await Promise.resolve()
+                store3.setState(s => ({ count: s.count + 1 }))
+            }
+        }
+    })
+    results.push(bench('action call (async dispatch)', () => {
+        void store3.incrementAsync()
+    }, 10_000))
+
+    // ── 4. Immer — primitive mutation
+    const store4 = createStore({ count: 0 }, { immer: true })
+    results.push(bench('setState (immer mutator, primitive)', () => {
+        store4.setState(draft => { draft.count++ })
+    }))
+
+    // ── 5. Immer — nested object mutation
+    const store5 = createStore({
+        user: { name: 'Alice', age: 30, score: 0 }
+    }, { immer: true })
+    results.push(bench('setState (immer mutator, nested object)', () => {
+        store5.setState(draft => { draft.user.score++ })
+    }))
+
+    // ── 6. Immer — array push
+    const store6 = createStore({ items: [] as number[] }, { immer: true })
+    let idCounter = 0
+    results.push(bench('setState (immer mutator, array push)', () => {
+        store6.setState(draft => { draft.items.push(idCounter++) })
+        // Keep array from growing unboundedly
+        if (store6.getState().items.length > 100) {
+            store6.setState({ items: [] })
+        }
+    }, 10_000))
+
+    // ── 7. Batch — 3 setState calls
+    const store7 = createStore({ a: 0, b: 0, c: 0 })
+    let n7 = 0
+    results.push(bench('batch (3x setState, 1 notify)', () => {
+        store7.batch(() => {
+            store7.setState({ a: n7 })
+            store7.setState({ b: n7 })
+            store7.setState({ c: n7++ })
+        })
+    }))
+
+    // ── 8. Batch — 10 setState calls
+    const store8 = createStore({
+        v0: 0, v1: 0, v2: 0, v3: 0, v4: 0,
+        v5: 0, v6: 0, v7: 0, v8: 0, v9: 0,
+    })
+    let n8 = 0
+    results.push(bench('batch (10x setState, 1 notify)', () => {
+        store8.batch(() => {
+            store8.setState({ v0: n8 })
+            store8.setState({ v1: n8 })
+            store8.setState({ v2: n8 })
+            store8.setState({ v3: n8 })
+            store8.setState({ v4: n8 })
+            store8.setState({ v5: n8 })
+            store8.setState({ v6: n8 })
+            store8.setState({ v7: n8 })
+            store8.setState({ v8: n8 })
+            store8.setState({ v9: n8++ })
+        })
+    }))
+
+    // ── 9. Action excluded from getState — confirms no overhead
+    const store9 = createStore({
+        count: 0,
+        actions: { increment() { store9.setState(s => ({ count: s.count + 1 })) } }
+    })
+    results.push(bench('action excluded from getState()', () => {
+        const state = store9.getState()
+        void ('increment' in state)
+    }))
+
+    // ── Print results
+    const colWidths = { operation: 48, averageMs: 22, status: 10 }
+    const header =
+        'Operation'.padEnd(colWidths.operation) +
+        'Average Time'.padEnd(colWidths.averageMs) +
+        'Status'
+    const divider = '─'.repeat(header.length)
+
+    console.log(header)
+    console.log(divider)
+
+    let allPassed = true
+    for (const r of results) {
+        if (r.status.includes('FAIL')) allPassed = false
+        console.log(
+            r.operation.padEnd(colWidths.operation) +
+            r.averageMs.padEnd(colWidths.averageMs) +
+            r.status
+        )
+    }
+
+    console.log(divider)
+    console.log(allPassed
+        ? '\n✅ All Week 4 benchmarks passed!\n'
+        : '\n❌ Some benchmarks failed — investigate before merging.\n'
+    )
+
+    if (!allPassed) process.exit(1)
+}
+
+runBenchmarks()

package/benchmarks/week5.md

@@ -0,0 +1,15 @@
+# Week 5 Benchmarks (v0.4 Async State)
+
+| Operation | Average Time | Status |
+| :--- | :--- | :--- |
+| createAsync() initialization | 0.00023803ms | ✅ PASS |
+| fetch() - cache hit (TTL) | 0.00055767ms | ✅ PASS |
+| fetch() - cache miss (resolved) | 0.00344446ms | ✅ PASS |
+| refetch() - overhead | 0.00452113ms | ✅ PASS |
+| optimistic update - immediate state change | 0.00286880ms | ✅ PASS |
+
+## Observations
+- **Engine Initialization**: `createAsync` is extremely lightweight as it only returns a definition object. The actual engine is lazily initialized when the store is created.
+- **Cache Performance**: TTL cache hits are highly optimized (~0.5ns), adding negligible overhead to state reads.
+- **Engine Overhead**: Cache misses and refetches show roughly 3-4µs overhead. This is well within the 1ms budget for store operations, even considering the overhead of Promise resolution in the benchmark.
+- **Optimistic Updates**: Immediate state updates via optimistic results are fast (~2.8µs), ensuring UI responsiveness during async triggers.