@stacksjs/cache 0.70.87 → 0.70.88

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stacksjs/cache",
   "type": "module",
-  "version": "0.70.87",
+  "version": "0.70.88",
   "description": "Caching the Stacks way.",
   "author": "Chris Breuer",
   "contributors": [
@@ -54,7 +54,7 @@
     "prepublishOnly": "bun run build"
   },
   "devDependencies": {
-    "@stacksjs/config": "0.70.87",
+    "@stacksjs/config": "0.70.88",
     "@stacksjs/ts-cache": "^0.1.4"
   }
 }

package/dist/drivers/index.d.ts

@@ -1,142 +0,0 @@
-import { CacheManager, MemoryDriver, RedisDriver } from '@stacksjs/ts-cache';
-import { SingleStoreCacheStore } from './singlestore';
-import type { CacheDriver, CacheStats } from '@stacksjs/types';
-import type { SingleStoreCacheOptions } from './singlestore';
-// Re-export the SingleStore store + its options for advanced usage
-export type { SingleStoreCacheOptions } from './singlestore';
-/**
- * Create a memory cache driver
- */
-export declare function createMemoryCache(options?: MemoryOptions): CacheDriver;
-/**
- * Create a Redis cache driver
- */
-export declare function createRedisCache(options?: RedisOptions): CacheDriver;
-/**
- * Create a SingleStore cache driver.
- *
- * Wraps a SingleStore-backed store in the same `StacksCache` façade the memory
- * and Redis drivers use, so it inherits the stampede-protection + tag logic.
- * The store implements the `CacheManager` surface `StacksCache` consumes; the
- * cast bridges the structural gap (it is not a literal `CacheManager` subclass).
- */
-export declare function createSingleStoreCache(options?: SingleStoreCacheOptions): CacheDriver;
-/**
- * Create a cache driver based on the specified type
- */
-export declare function createCache(driver: 'memory', options?: MemoryOptions): CacheDriver;
-export declare function createCache(driver: 'redis', options?: RedisOptions): CacheDriver;
-export declare function createCache(driver: 'singlestore', options?: SingleStoreCacheOptions): CacheDriver;
-/**
- * Default memory cache instance
- */
-export declare const memory: CacheDriver;
-/**
- * Default cache instance (memory)
- */
-export declare const cache: CacheDriver;
-/**
- * Memory cache options
- */
-export declare interface MemoryOptions {
-  stdTTL?: number
-  checkPeriod?: number
-  maxKeys?: number
-  useClones?: boolean
-  prefix?: string
-}
-/**
- * Redis cache options
- */
-export declare interface RedisOptions {
-  url?: string
-  host?: string
-  port?: number
-  username?: string
-  password?: string
-  database?: number
-  tls?: boolean
-  stdTTL?: number
-  prefix?: string
-}
-/**
- * Stacks Cache Wrapper
- *
- * Wraps ts-cache's CacheManager to provide a consistent API
- * that matches the Stacks CacheDriver interface.
- */
-export declare class StacksCache implements CacheDriver {
-  constructor(manager: CacheManager, opts?: { inflightTimeoutMs?: number });
-  get<T>(key: string): Promise<T | undefined>;
-  mget<T>(keys: string[]): Promise<Record<string, T>>;
-  set<T>(key: string, value: T, ttl?: number): Promise<boolean>;
-  mset<T>(entries: Array<{ key: string, value: T, ttl?: number }>): Promise<boolean>;
-  setForever<T>(key: string, value: T): Promise<boolean>;
-  getOrSet<T>(key: string, fetcher: () => T | Promise<T>, ttl?: number): Promise<T>;
-  remember<T>(key: string, ttl: number, callback: () => T | Promise<T>): Promise<T>;
-  rememberForever<T>(key: string, callback: () => T | Promise<T>): Promise<T>;
-  del(keys: string | string[]): Promise<number>;
-  has(key: string): Promise<boolean>;
-  missing(key: string): Promise<boolean>;
-  remove(key: string): Promise<void>;
-  deleteMany(keys: string[]): Promise<number>;
-  clear(): Promise<void>;
-  flush(): Promise<void>;
-  keys(pattern?: string): Promise<string[]>;
-  getTtl(key: string): Promise<number | undefined>;
-  ttl(key: string, ttl: number): Promise<boolean>;
-  take<T>(key: string): Promise<T | undefined>;
-  getStats(): Promise<CacheStats>;
-  close(): Promise<void>;
-  disconnect(): Promise<void>;
-  get cacheManager(): CacheManager;
-  tags(tags: readonly string[]): TaggedCache;
-}
-/**
- * Tag-scoped wrapper around `StacksCache`. Records every write under
- * the named tag(s) so `flush()` can invalidate cascade-style without the
- * caller having to track keys themselves.
- *
- * The tag index is stored as `string[]` on disk (so it survives the
- * Redis driver's serializer), but operated on in memory as a `Set` so
- * each write is `O(1)` instead of `O(N)` over the existing index.
- *
- * `flush()` uses a per-tag in-process mutex so concurrent flushes don't
- * race-and-lose keys: without it, two parallel flushes could both read
- * the index, both delete, and the second flush would succeed against
- * the now-empty index — leaving any keys added between the two reads
- * orphaned.
- */
-export declare class TaggedCache {
-  constructor(cache: StacksCache, tags: readonly string[]);
-  put<T>(key: string, value: T, ttl?: number): Promise<boolean>;
-  set<T>(key: string, value: T, ttl?: number): Promise<boolean>;
-  setForever<T>(key: string, value: T): Promise<boolean>;
-  remember<T>(key: string, ttl: number, callback: () => T | Promise<T>): Promise<T>;
-  rememberForever<T>(key: string, callback: () => T | Promise<T>): Promise<T>;
-  get<T>(key: string): Promise<T | undefined>;
-  has(key: string): Promise<boolean>;
-  flush(): Promise<number>;
-}
-export { SingleStoreCacheStore } from './singlestore';
-// Re-export ts-cache utilities for advanced usage
-export {
-  CacheManager,
-  MemoryDriver,
-  RedisDriver,
-} from '@stacksjs/ts-cache';
-// Re-export patterns and utilities
-export {
-  // Patterns
-  CacheAsidePattern,
-  MultiLevelPattern,
-  RefreshAheadPattern,
-  WriteThroughPattern,
-  // Utilities
-  BatchOperations,
-  CacheInvalidation,
-  CacheLock,
-  CircuitBreaker,
-  memoize,
-  RateLimiter,
-} from '@stacksjs/ts-cache';

package/dist/drivers/singlestore.d.ts

@@ -1,35 +0,0 @@
-export declare interface SingleStoreCacheOptions {
-  host?: string
-  port?: number
-  username?: string
-  password?: string
-  database?: string
-  table?: string
-  ssl?: boolean
-  prefix?: string
-  stdTTL?: number
-}
-declare interface CacheStatsShape {
-  hits: number
-  misses: number
-  keys: number
-  ksize: number
-  vsize: number
-}
-export declare class SingleStoreCacheStore {
-  constructor(options?: SingleStoreCacheOptions);
-  get<T>(key: string): Promise<T | undefined>;
-  mget<T>(keys: string[]): Promise<Record<string, T>>;
-  set<T>(key: string, value: T, ttl?: number): Promise<boolean>;
-  mset<T>(entries: Array<{ key: string, value: T, ttl?: number }>): Promise<boolean>;
-  fetch<T>(key: string, fn: () => T | Promise<T>, ttl?: number): Promise<T>;
-  del(keys: string | string[]): Promise<number>;
-  has(key: string): Promise<boolean>;
-  flush(): Promise<void>;
-  keys(pattern?: string): Promise<string[]>;
-  getTtl(key: string): Promise<number | undefined>;
-  ttl(key: string, ttl: number): Promise<boolean>;
-  take<T>(key: string): Promise<T | undefined>;
-  getStats(): Promise<CacheStatsShape>;
-  close(): Promise<void>;
-}

package/dist/index.d.ts

@@ -1,25 +0,0 @@
-/**
- * @stacksjs/cache
- *
- * A high-performance, type-safe caching library powered by ts-cache.
- *
- * @example
- * ```ts
- * import { cache, createCache, createMemoryCache, createRedisCache } from '@stacksjs/cache'
- *
- * // Use the default memory cache
- * await cache.set('key', 'value', 60) // 60 second TTL
- * const value = await cache.get('key')
- *
- * // Create a custom Redis cache
- * const redisCache = createRedisCache({
- *   host: 'localhost',
- *   port: 6379,
- *   prefix: 'myapp',
- * })
- *
- * // Use the factory function
- * const customCache = createCache('memory', { maxKeys: 1000 })
- * ```
- */
-export * from './drivers/index';

package/dist/index.js

@@ -1,2 +0,0 @@
-// @bun
-import{createCache as V}from"@stacksjs/ts-cache";var{SQL:Y}=globalThis.Bun;function Z(R){return`\`${R.replace(/`/g,"``")}\``}class L{sql;table;qualified;prefix;stdTTL;ready=null;hits=0;misses=0;constructor(R={}){let{host:U="127.0.0.1",port:z=3306,username:B="root",password:D="",database:E="stacks",table:H="stacks_cache",ssl:N=!1}=R;this.table=H,this.qualified=Z(H),this.prefix=R.prefix??"",this.stdTTL=R.stdTTL??0;let W=D?`${B}:${encodeURIComponent(D)}`:B,O=N?"?ssl=true":"";this.sql=new Y(`mysql://${W}@${U}:${z}/${E}${O}`)}async ensureReady(){if(!this.ready)this.ready=this.sql.unsafe(`CREATE ROWSTORE TABLE IF NOT EXISTS ${this.qualified} ( cache_key VARCHAR(255) NOT NULL, value LONGTEXT NOT NULL, expires_at BIGINT NULL, PRIMARY KEY (cache_key) )`).then(()=>{return});await this.ready}k(R){return this.prefix?`${this.prefix}:${R}`:R}nowMs(){return Date.now()}expiryFor(R){let U=R??this.stdTTL;if(!U||U<=0)return null;return this.nowMs()+U*1000}async get(R){await this.ensureReady();let z=(await this.sql.unsafe(`SELECT value, expires_at FROM ${this.qualified} WHERE cache_key = ? LIMIT 1`,[this.k(R)]))[0];if(!z){this.misses++;return}if(z.expires_at!=null&&z.expires_at<=this.nowMs()){await this.del(R),this.misses++;return}return this.hits++,JSON.parse(z.value)}async mget(R){let U={};for(let z of R){let B=await this.get(z);if(B!==void 0)U[z]=B}return U}async set(R,U,z){await this.ensureReady();let B=this.expiryFor(z);return await this.sql.unsafe(`INSERT INTO ${this.qualified} (cache_key, value, expires_at) VALUES (?, ?, ?) ON DUPLICATE KEY UPDATE value = VALUES(value), expires_at = VALUES(expires_at)`,[this.k(R),JSON.stringify(U),B]),!0}async mset(R){for(let U of R)await this.set(U.key,U.value,U.ttl);return!0}async fetch(R,U,z){let B=await this.get(R);if(B!==void 0)return B;let D=await U();return await this.set(R,D,z),D}async del(R){await this.ensureReady();let U=Array.isArray(R)?R:[R];if(U.length===0)return 0;let z=U.map(()=>"?").join(", "),D=(await this.sql.unsafe(`DELETE FROM ${this.qualified} WHERE cache_key IN (${z})`,U.map((E)=>this.k(E)))).affectedRows;return typeof D==="number"?D:U.length}async has(R){return await this.get(R)!==void 0}async flush(){if(await this.ensureReady(),this.prefix)await this.sql.unsafe(`DELETE FROM ${this.qualified} WHERE cache_key LIKE ?`,[`${this.prefix}:%`]);else await this.sql.unsafe(`TRUNCATE TABLE ${this.qualified}`)}async keys(R){await this.ensureReady();let U=`${this.prefix?`${this.prefix}:`:""}${R?R.replace(/\*/g,"%"):"%"}`,z=await this.sql.unsafe(`SELECT cache_key FROM ${this.qualified} WHERE cache_key LIKE ? AND (expires_at IS NULL OR expires_at > ?)`,[U,this.nowMs()]),B=this.prefix?this.prefix.length+1:0;return z.map((D)=>B?D.cache_key.slice(B):D.cache_key)}async getTtl(R){await this.ensureReady();let z=(await this.sql.unsafe(`SELECT expires_at FROM ${this.qualified} WHERE cache_key = ? LIMIT 1`,[this.k(R)]))[0];if(!z)return;return z.expires_at==null?0:z.expires_at}async ttl(R,U){await this.ensureReady();let z=this.expiryFor(U);return((await this.sql.unsafe(`UPDATE ${this.qualified} SET expires_at = ? WHERE cache_key = ?`,[z,this.k(R)])).affectedRows??0)>0}async take(R){let U=await this.get(R);if(U!==void 0)await this.del(R);return U}async getStats(){await this.ensureReady();let R=await this.sql.unsafe(`SELECT COUNT(*) AS n FROM ${this.qualified} WHERE expires_at IS NULL OR expires_at > ?`,[this.nowMs()]);return{hits:this.hits,misses:this.misses,keys:Number(R[0]?.n??0),ksize:0,vsize:0}}async close(){await this.sql.end()}}import{CacheManager as m,MemoryDriver as h,RedisDriver as v}from"@stacksjs/ts-cache";import{CacheAsidePattern as d,MultiLevelPattern as u,RefreshAheadPattern as c,WriteThroughPattern as p,BatchOperations as g,CacheInvalidation as r,CacheLock as l,CircuitBreaker as n,memoize as i,RateLimiter as y}from"@stacksjs/ts-cache";class J{manager;inflight=new Map;inflightTimeoutMs;constructor(R,U={}){this.manager=R,this.inflightTimeoutMs=U.inflightTimeoutMs??30000}async get(R){return await this.manager.get(R)}async mget(R){return await this.manager.mget(R)}async set(R,U,z){return await this.manager.set(R,U,z)}async mset(R){return await this.manager.mset(R)}async setForever(R,U){return await this.manager.set(R,U,0)}async getOrSet(R,U,z){let B=await this.manager.get(R);if(B!==void 0)return B;let D=this.inflight.get(R);if(D)return await D;let E=(async()=>{try{return await this.manager.fetch(R,U,z)}finally{this.inflight.delete(R)}})(),H=this.inflightTimeoutMs,N=new Promise((W,O)=>{let X=setTimeout(()=>{if(this.inflight.get(R)===E)this.inflight.delete(R);O(Error(`[cache] getOrSet('${R}') timed out after ${H}ms`))},H);E.then(()=>clearTimeout(X),()=>clearTimeout(X))});return this.inflight.set(R,E),await Promise.race([E,N])}async remember(R,U,z){return await this.getOrSet(R,z,U)}async rememberForever(R,U){return this.getOrSet(R,U,0)}async del(R){return await this.manager.del(R)}async has(R){return await this.manager.has(R)}async missing(R){return!await this.manager.has(R)}async remove(R){await this.manager.del(R)}async deleteMany(R){return await this.manager.del(R)}async clear(){await this.manager.flush()}async flush(){await this.manager.flush()}async keys(R){return await this.manager.keys(R)}async getTtl(R){return await this.manager.getTtl(R)}async ttl(R,U){return await this.manager.ttl(R,U)}async take(R){return await this.manager.take(R)}async getStats(){let R=await this.manager.getStats(),U=R.hits+R.misses;return{hits:R.hits,misses:R.misses,keys:R.keys,size:R.ksize+R.vsize,hitRate:U>0?R.hits/U:0}}async close(){await this.manager.close()}async disconnect(){await this.manager.close()}get cacheManager(){return this.manager}tags(R){return new G(this,R)}}class G{cache;tags;static TAG_PREFIX="__stacks_tag__:";static flushLocks=new Map;constructor(R,U){this.cache=R;this.tags=U;if(!U||U.length===0)throw Error("cache.tags(...) requires at least one tag")}tagKey(R){return`${G.TAG_PREFIX}${R}`}async indexKey(R){for(let U of this.tags){let z=this.tagKey(U),B=await this.cache.get(z)??[],D=new Set(B);if(!D.has(R))D.add(R),await this.cache.setForever(z,[...D])}}async put(R,U,z){let B=await this.cache.set(R,U,z);if(B)await this.indexKey(R);return B}async set(R,U,z){return this.put(R,U,z)}async setForever(R,U){let z=await this.cache.setForever(R,U);if(z)await this.indexKey(R);return z}async remember(R,U,z){let B=await this.cache.remember(R,U,z);return await this.indexKey(R),B}async rememberForever(R,U){let z=await this.cache.rememberForever(R,U);return await this.indexKey(R),z}async get(R){return this.cache.get(R)}async has(R){return this.cache.has(R)}async flush(){let R=0;for(let U of this.tags){let z=this.tagKey(U),B=G.flushLocks.get(z),D=B?B.catch(()=>0).then(()=>this.doFlushOne(z)):this.doFlushOne(z);G.flushLocks.set(z,D);try{R+=await D}finally{if(G.flushLocks.get(z)===D)G.flushLocks.delete(z)}}return R}async doFlushOne(R){let U=await this.cache.get(R)??[],z=0;if(U.length>0)z=await this.cache.del(U);return await this.cache.del(R),z}}function _(R={}){let U=V({driver:"memory",stdTTL:R.stdTTL??0,checkPeriod:R.checkPeriod??600,maxKeys:R.maxKeys??-1,useClones:R.useClones??!0,prefix:R.prefix});return new J(U)}function $(R={}){let U=V({driver:"redis",url:R.url,host:R.host??"localhost",port:R.port??6379,password:R.password,database:R.database??0,tls:R.tls??!1,stdTTL:R.stdTTL??0,prefix:R.prefix});return new J(U)}function f(R={}){let U=new L(R);return new J(U)}function w(R,U){if(R==="redis")return $(U);if(R==="singlestore")return f(U);return _(U)}var A=V({driver:"memory",stdTTL:0,checkPeriod:600,maxKeys:-1,useClones:!0}),I=new J(A),b=I;export{I as memory,i as memoize,f as createSingleStoreCache,$ as createRedisCache,_ as createMemoryCache,w as createCache,b as cache,p as WriteThroughPattern,G as TaggedCache,J as StacksCache,L as SingleStoreCacheStore,c as RefreshAheadPattern,v as RedisDriver,y as RateLimiter,u as MultiLevelPattern,h as MemoryDriver,n as CircuitBreaker,m as CacheManager,l as CacheLock,r as CacheInvalidation,d as CacheAsidePattern,g as BatchOperations};