Skip to content

SoulCache v1.0.0

Choose a tag to compare

View all tags
@kasihagustinusT kasihagustinusT released this 24 Jul 06:29
· 50 commits to main since this release
v1.0.0
da44b75

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

License

MIT — Copyright (c) 2026 Kasih Agustinus

Links

Assets 2
Loading