SoulCache v1.1.1

SoulCache v1.1.1

High-performance data fetching and caching runtime for TypeScript. Zero runtime dependencies. Framework-agnostic.

This is a security patch release following an independent security review. All four
packages (@soulcache/core, @soulcache/react, @soulcache/devtools,
@soulcache/devtools-core) are bumped to 1.1.1. The public API is fully compatible
with v1.1.0 / v1.0.0.

Highlights

• Honest checksum algorithms — checksum: 'sha-256' now writes a real FIPS 180-4
  SHA-256 digest (64-hex) instead of silently reusing the non-cryptographic 32-bit
  djb2 hash that every label produced before. Deprecated labels that were never
  implemented (sha-384, sha-512, md5) are rejected on write; payloads persisted
  by earlier versions under any label remain readable.
• No error.stack in dehydrated state by default — internal file paths no longer
  leak to clients in SSR flows. Opt back in with includeStack: true for
  server-side debugging.
• Hardened hydrate() — malformed entries (non-array queryKey, non-object
  query) are rejected before they can corrupt the cache.
• CSPRNG-generated ids — generateId() uses crypto.randomUUID() when available.

What's Changed

Security

• Checksum integrity (SLC-INTEGRITY-001). JsonSerializer/JsonDeserializer
  now honor the configured ChecksumAlgorithm:
  • sha-256 computes a real, synchronous, zero-dependency SHA-256 digest (FIPS
    180-4) — previously the label silently produced the same 32-bit djb2 value as
    every other label.
  • Writes under sha-384, sha-512, or md5 throw SerializationError (these
    labels were never implemented and are deprecated; migrate to sha-256 or the
    default fast-32).
  • Reads under sha-256 verify against both the real digest and the legacy djb2
    value, so 1.0.0/1.1.0 payloads keep validating; legacy labels remain readable.
• Stack disclosure (SLC-HYDRATE-003). dehydrate() no longer includes
  error.stack by default; pass includeStack: true to preserve it for server-side
  debugging.
• Hydrate tampering (SLC-HYDRATE-001). hydrate() structurally validates every
  entry before writing; malformed entries are skipped. The default overwrite
  merge strategy is unchanged.
• Weak ids (SLC-RNG-001). generateId() prefers crypto.randomUUID(), with the
  legacy scheme retained as a fallback.

Documentation

• SECURITY.md adds secure-usage guidance (query-key scoping, trusted hydrate
  sources, checksum = corruption detection not tamper-proofing, stack opt-in).
• New consumer security page docs/content/docs/security.mdx.
• Release notes and migration guide updated for v1.1.1.

Testing

• New SHA-256 test suite with FIPS 180-4 vectors (empty, "abc", two-block, padding
  boundary) plus serializer/deserializer dual-mode, hydration validation, and
  CSPRNG id tests.
• Root suite green on the release commit; public API verified compatible with the
  v1.0.0 baseline.

Breaking Changes

None. No public API signature changed. Two opt-in/opt-out behavior changes to
review (see Upgrade Notes).

Upgrade Notes

• Dehydrated error entries no longer include error.stack by default. If you used
  stacks from dehydrated state (e.g. SSR debugging), pass
  dehydrate(engine, { includeStack: true }) — and keep stacks server-side.
• If you configured checksum: 'sha-384' | 'sha-512' | 'md5', serialization now
  throws. Switch to sha-256 (real) or drop the option (default fast-32).
  Persisted payloads never need migration; they restore correctly.

Known Limitations

• Checksums are unkeyed: both fast-32 and sha-256 detect accidental corruption,
  not an attacker who can rewrite both payload and checksum. Use authenticated
  storage (HMAC/encryption) where adversarial persistence is in scope.
• Retry engine and the plugin system remain internal modules.

Credits

Maintained by Kasih Agustinus and the SoulCache contributors.

Full Changelog

• CHANGELOG.md
• Compare v1.1.0...v1.1.1
• Documentation
• @soulcache/core on npm

@soulcache/react@1.1.1

Changelog

All notable changes to this project will be documented in this file.

[1.1.1] - 2026-08-07

Changed

• Version aligned with @soulcache/core@1.1.1 security patch (honest checksum
  algorithms, hydrate entry validation, error.stack opt-in, CSPRNG ids). No
  React-binding API changes.

@soulcache/devtools@1.1.1

Changelog

All notable changes to this project will be documented in this file.

[1.1.1] - 2026-08-07

Changed

• Version aligned with @soulcache/core@1.1.1 security patch. No DevTools API
  changes.

@soulcache/devtools-core@1.1.1

Changelog

All notable changes to this project will be documented in this file.

[1.1.1] - 2026-08-07

Changed

• Version aligned with @soulcache/core@1.1.1 security patch. No DevTools-core API
  changes.

@soulcache/core@1.1.1

Changelog

All notable changes to this project will be documented in this file.

[1.1.1] - 2026-08-07

Security

• Honest checksum algorithms (SLC-INTEGRITY-001). sha-256 now computes a real
  FIPS 180-4 SHA-256 digest (64-hex). Previously every configured label
  (sha-256, sha-384, sha-512, md5, fast-32) silently computed the same
  32-bit djb2 value. Writes under sha-384/sha-512/md5 now throw
  SerializationError (never implemented, deprecated); payloads persisted by
  1.0.0/1.1.0 under any label (including legacy djb2 values labeled sha-256)
  remain readable via dual-mode verification.
• dehydrate() no longer includes error.stack by default (SLC-HYDRATE-003).
  Dehydrated error entries expose only message and name; pass
  includeStack: true to opt back in for server-side debugging.
• hydrate() validates entry structure (SLC-HYDRATE-001). Malformed entries
  (non-array queryKey, non-object query) are rejected before they can corrupt the
  cache; default overwrite merge strategy is unchanged.
• generateId() uses a CSPRNG (SLC-RNG-001). IDs use crypto.randomUUID() when
  available, with the legacy scheme retained as a fallback.

Changed

• JsonSerializer/JsonDeserializer checksum selection is now honored; the
  ChecksumAlgorithm documentation describes the semantics of each label.

[1.1.0] - 2026-08-06

Changed

• LRU eviction score formula corrected so recently/frequently accessed entries are evicted last.
• Mutation onSuccess/onError/onSettled callbacks are isolated per callback; a throwing callback no longer corrupts mutation state or skips onSettled.
• Retry-engine event listeners are individually isolated; toError() preserves name/message for non-Error thrown values.
• InfiniteQuery default maxPages changed from Infinity to 50; navigation flags are recomputed after page-window eviction.
• EventBus adds monotonic sequence numbers and opt-in coalesced delivery.

Security

• MemoryAdapter accepts a maxEntries option to cap stored entries and bound memory use.
• deepEqual guards recursion depth to prevent stack-overflow attacks on pathological input.
• deserialize validates the dehydrated-state shape before hydrating.
• EventBus enforces a per-type handler limit.

[1.0.0] - 2026-07-23

Added

Core Runtime

• Query client with request deduplication
• Cache engine with configurable TTL, garbage collection, and dependency tracking
• Mutation system with optimistic updates and rollback
• Observer system with structured snapshots and real-time subscriptions
• Scheduler with priority-based task scheduling (immediate, high, normal, low, idle)
• Infinite query support with cursor-based and page-based pagination
• Retry engine (internal module) with exponential, linear, and constant backoff strategies
• Plugin system (internal module) with lifecycle hooks for query, mutation, cache, and error events

Storage

• Pluggable storage adapters (Memory)
• Automatic persistence with configurable serialization
• Migration manager for schema versioning
• Restore manager for cache recovery
• Diagnostics and health monitoring
• Persistence coordinator for unified storage management

Hydration

• Server-side prefetching with dehydrate and hydrate
• Structural sharing for efficient re-renders
• Streaming-compatible hydration for Next.js App Router

Error Handling

• Typed error hierarchy (SoulCacheError, ConfigurationError, QueryError, CacheError, RuntimeError)
• Error classification and recovery

Utilities

• generateId for unique query and mutation identifiers
• EventBus for internal event communication
• SubscriptionManager for query subscriptions
• QuerySnapshotManager for snapshot management

[0.1.0] - 2026-07-18

Added

• Initial package scaffold

SoulCache v1.1.0 — Security Hardening, Correctness Fixes, and Performance

SoulCache v1.1.0

High-performance data fetching and caching runtime for TypeScript. Zero runtime dependencies. Framework-agnostic.

This release ships security hardening, correctness fixes, packaging improvements, and documentation accuracy updates. The public API is fully compatible with v1.0.0.

Highlights

• Memory-bounded caching — MemoryAdapter now accepts maxEntries to cap stored entries.
• Hardened serialization — deepEqual guards recursion depth; deserialize validates dehydrated-state shape before hydrating, rejecting malformed or hostile payloads.
• Correct cache eviction — LRU eviction score formula corrected so recently and frequently accessed entries are evicted last.
• Robust mutation callbacks — onSuccess/onError/onSettled are isolated per callback; a throwing callback no longer corrupts mutation state or skips onSettled.
• Smaller, cleaner packages — minification enabled for @soulcache/core and @soulcache/react; DevTools packages no longer bundle the core source tree.
• Bounded infinite queries — default maxPages changed from unbounded to 50; navigation flags are recomputed after page-window eviction.

What's Changed

Security

• MemoryAdapter now accepts a maxEntries option to cap stored entries and bound memory use.
• deepEqual now guards recursion depth to prevent stack-overflow attacks on pathological input.
• deserialize now validates the dehydrated-state shape before hydrating, rejecting malformed or hostile payloads.
• EventBus now enforces a per-type handler limit (maxHandlersPerType) to prevent unbounded listener growth.

Correctness

• LRU eviction score formula corrected so recently/frequently accessed entries are evicted last.
• Mutation onSuccess/onError/onSettled callbacks are now isolated per callback; a throwing callback no longer corrupts mutation state or skips onSettled.
• Retry-engine event listeners are individually isolated; toError() preserves name/message for non-Error thrown values (e.g. DOMException).
• InfiniteQuery default maxPages changed from Infinity to 50; navigation flags are recomputed after page-window eviction.
• Hydration mergeStrategy: 'merge' now preserves existing data and hydrates only entries without data.
• EventBus adds monotonic sequence numbers and opt-in coalesced delivery.

Performance & Packaging

• Build minification enabled for @soulcache/core and @soulcache/react.
• DevTools packages no longer bundle the core source tree (devtools 319 -> 19 files; devtools-core 319 -> 35 files).
• No benchmark regressions; @soulcache/core bundle remains approximately 16 KB (gzip).

Documentation

• Corrected bundle-size, retry, background-refetch, and plugin-system claims across the docs site.
• New DevTools guide; corrected infinite-query, hydration, mutation, and query-client API references.
• Roadmap and release notes updated with verified test counts.

Testing

• 1312/1312 tests passing in the root suite (core + devtools + devtools-core); 199/199 React bindings tests passing.
• New regression suites: EventBus handler caps, InfiniteQuery maxPages window, mutation callback isolation, retry listener isolation, hydration merge.
• Public API verified compatible with the v1.0.0 baseline.

Breaking Changes

None. The public API surface is fully compatible with v1.0.0 (verified against the API baseline).

Upgrade Notes

No code changes are required to upgrade. Review the following behavioral changes:

• InfiniteQuery now defaults to a maxPages window of 50. Configure maxPages explicitly if you relied on unbounded page retention.
• Mutation callbacks are now isolated. If your onSuccess/onError throws, wrap the body in try/catch — other callbacks and onSettled will still run.
• Eviction order may differ for caches near their capacity because of the corrected LRU scoring. With MemoryAdapter.maxEntries, verify eviction behavior in tests.

Known Limitations

• Retry engine and background refetching remain internal modules; integration is targeted for a future milestone.
• The plugin system is internal and not yet part of the public API.

Credits

Maintained by Kasih Agustinus and the SoulCache contributors.

Full Changelog

• CHANGELOG.md
• Compare v1.0.0...v1.1.0
• Documentation
• @soulcache/core on npm

SoulCache v1.0.0

SoulCache v1.0.0

Universal Data Fetching & Caching Runtime for TypeScript

SoulCache is a framework-agnostic data fetching and caching runtime for TypeScript applications. It handles deduplication, background refetching, retry logic, and cache invalidation with zero runtime dependencies.

---

Highlights

Core Runtime

• Stale-while-revalidate caching with configurable TTL
• Request deduplication across concurrent observers
• Automatic garbage collection and cache eviction
• O(1) cache lookups with hash-based key resolution

React Adapter

• useQuery, useMutation, useInfiniteQuery hooks
• SoulCacheProvider context wrapper
• HydrationBoundary for SSR streaming
• Built on useSyncExternalStore for React 18+ compatibility

DevTools

• Floating inspection panel with Ctrl/Cmd+Shift+D shortcut
• Query, Mutation, and Cache state inspection
• Timeline recording with event filtering
• p50/p95/p99 performance metrics
• Session recording and replay

Storage Layer

• MemoryAdapter with pluggable custom adapter support
• Automatic persistence with migration support
• Lifecycle management and diagnostics
• Checksum validation and corruption recovery

Hydration

• Server-side prefetching with dehydrate/hydrate
• Streaming-compatible partial hydration
• Next.js App Router support

Infinite Query

• Cursor-based pagination
• Automatic page deduplication
• Background refetching of stale pages

Plugin System

• Lifecycle hooks for query, mutation, and cache events
• Error isolation per hook
• Automatic dependency resolution

Scheduler

• Task prioritization with configurable queues
• Batch scheduling for performance
• Microtask and macrotask support

Retry Engine

• Exponential, linear, and constant backoff strategies
• Error classification with automatic retry decisions
• Configurable retry policies per query

Documentation

• Full documentation at soulcache.vercel.app
• API reference, migration guides, and examples
• Fumadocs-powered with MDX content

Developer Experience

• Strict TypeScript with minimal any usage
• Full declaration maps and source maps
• ESLint and Prettier configured
• Changesets for version management

Testing

• 756/756 tests passing
• Stress tests for cache and observer performance
• Memory leak detection tests
• Integration tests for storage layer

CI/CD

• GitHub Actions with Node 20 and Node 22 matrix
• Automated release workflow via Changesets
• CodeQL security analysis
• Nightly dependency audits

---

Quality Summary

Metric	Status
Tests	756/756 passing
TypeCheck	Pass
Build	Pass
Documentation	Pass
CI	Pass (Node 20, Node 22)
CodeQL	Pass
Runtime Dependencies	Zero (core)

---

Installation

# npm
npm install @soulcache/core

# pnpm
pnpm add @soulcache/core

# yarn
yarn add @soulcache/core

For React applications:

npm install @soulcache/react @soulcache/core

---

Packages

Package	Description
@soulcache/core	Core runtime with cache, query engine, retry, scheduler, storage, and plugins
@soulcache/react	React hooks and components via useSyncExternalStore
@soulcache/devtools-core	Framework-agnostic inspection and diagnostics
@soulcache/devtools	React DevTools panel with timeline, metrics, and session recording

---

Documentation

• Getting Started
• API Reference
• React Adapter
• Migration Guide
• Architecture

---

License

MIT — Copyright (c) 2026 Kasih Agustinus

---

Links

• Documentation
• GitHub Repository
• npm Package
• Issues
• Contributing