@stacksjs/cache 0.70.23 → 0.70.25

package/dist/src/drivers/index.d.ts

@@ -0,0 +1,127 @@
+import { CacheManager, MemoryDriver, RedisDriver } from '@stacksjs/ts-cache';
+import type { CacheDriver, CacheStats } from '@stacksjs/types';
+/**
+ * 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 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;
+/**
+ * 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);
+  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>;
+}
+// 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/src/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @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';

package/package.json

@@ -1,10 +1,12 @@
 {
   "name": "@stacksjs/cache",
   "type": "module",
-  "version": "0.70.23",
+  "version": "0.70.25",
   "description": "Caching the Stacks way.",
   "author": "Chris Breuer",
-  "contributors": ["Chris Breuer <chris@stacksjs.org>"],
+  "contributors": [
+    "Chris Breuer <chris@stacksjs.com>"
+  ],
   "license": "MIT",
   "funding": "https://github.com/sponsors/chrisbbreuer",
   "homepage": "https://github.com/stacksjs/stacks/tree/main/storage/framework/core/cache#readme",
@@ -26,26 +28,29 @@
   ],
   "exports": {
     ".": {
+      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
     "./*": {
+      "bun": "./src/*",
       "import": "./dist/*"
     }
   },
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
-  "files": ["README.md", "dist"],
+  "sideEffects": false,
+  "files": [
+    "README.md",
+    "dist"
+  ],
   "scripts": {
     "build": "bun build.ts",
     "typecheck": "bun tsc --noEmit",
     "prepublishOnly": "bun run build"
   },
   "devDependencies": {
-    "@aws-sdk/client-dynamodb": "^3.777.0",
-    "@stacksjs/config": "0.70.22",
-    "@stacksjs/development": "0.70.22",
-    "bentocache": "^1.2.1",
-    "dynamodb-tooling": "^0.3.2",
-    "ioredis": "^5.6.0"
+    "@stacksjs/config": "0.70.23",
+    "@stacksjs/ts-cache": "^0.1.4"
   }
 }

package/dist/base.d.ts

@@ -1,77 +0,0 @@
-import type { BentoCache } from 'bentocache';
-import type { CacheDriver } from '@stacksjs/types';
-import type { GetOptions } from 'bentocache/types';
-
-export declare abstract class BaseCacheDriver implements CacheDriver {
-  constructor(protected client: BentoCache<Record<string, any>>) {}
-
-  async set(key: string, value: string, ttl?: number): Promise<void> {
-    const data: { key: string, value: string, gracePeriod?: { enabled: boolean, duration: string } } = {
-      key,
-      value,
-    }
-
-    if (ttl) {
-      data.gracePeriod = {
-        enabled: true,
-        duration: `${ttl}m`,
-      }
-    }
-
-    await this.client.set(data)
-  }
-
-  async setForever(key: string, value: string): Promise<void> {
-    await this.client.setForever({
-      key,
-      value,
-    })
-  }
-
-  async get<T>(key: GetOptions<T>): Promise<T> {
-    return await this.client.get<T>(key)
-  }
-
-  async getOrSet<T>(key: string, value: T): Promise<T> {
-    return await this.client.getOrSet<T>({
-      key,
-      factory: async () => value,
-    })
-  }
-
-  async del(key: string): Promise<void> {
-    await this.client.delete({ key })
-  }
-
-  async deleteMany(keys: string[]): Promise<void> {
-    await this.client.deleteMany({ keys })
-  }
-
-  async remove(key: string): Promise<void> {
-    await this.client.delete({ key })
-  }
-
-  async has(key: string): Promise<boolean> {
-    return await this.client.has({ key })
-  }
-
-  async missing(key: string): Promise<boolean> {
-    return await this.client.missing({ key })
-  }
-
-  async deleteAll(): Promise<void> {
-    await this.client.clear()
-  }
-
-  async clear(): Promise<void> {
-    await this.client.clear()
-  }
-
-  async disconnect(): Promise<void> {
-    await this.client.disconnect()
-  }
-
-  get bentoCacheClient(): BentoCache<Record<string, any>> {
-    return this.client
-  }
-}

package/dist/dynamodb.d.ts

@@ -1,38 +0,0 @@
-export declare interface DynamoDBOptions {
-  endpoint?: string
-  region?: string
-  tableName?: string
-  accessKeyId?: string
-  secretAccessKey?: string
-}
-export declare class DynamoDBCacheDriver extends BaseCacheDriver {
-  constructor(options: DynamoDBOptions = {}) {
-    const awsAccessKeyId = options.accessKeyId ?? config.cache.drivers?.dynamodb?.key ?? 'dummy'
-    const awsSecretAccessKey = options.secretAccessKey ?? config.cache.drivers?.dynamodb?.secret ?? 'dummy'
-    const dynamoEndpoint = options.endpoint ?? config.cache.drivers?.dynamodb?.endpoint ?? 'http:
-    const tableName = options.tableName ?? config.cache.drivers?.dynamodb?.table ?? 'stacks'
-    const region = options.region ?? config.cache.drivers?.dynamodb?.region ?? 'us-east-1'
-
-    const client = new BentoCache({
-      default: 'dynamo',
-      stores: {
-        dynamo: bentostore().useL2Layer(
-          dynamoDbDriver({
-            endpoint: dynamoEndpoint,
-            region,
-            table: {
-              name: tableName,
-            },
-            credentials: {
-              accessKeyId: awsAccessKeyId,
-              secretAccessKey: awsSecretAccessKey,
-            },
-          }),
-        ),
-      },
-    })
-
-    super(client)
-  }
-}
-export declare const dynamodb: DynamoDBCacheDriver;

package/dist/filesystem.d.ts

@@ -1,22 +0,0 @@
-export declare interface FileSystemOptions {
-  directory?: string
-  pruneInterval?: string
-}
-export declare class FileSystemCacheDriver extends BaseCacheDriver {
-  constructor(options: FileSystemOptions = {}) {
-    const client = new BentoCache({
-      default: 'file',
-      stores: {
-        file: bentostore().useL2Layer(
-          fileDriver({
-            directory: options.directory ?? './cache',
-            pruneInterval: options.pruneInterval ?? '1h',
-          }),
-        ),
-      },
-    })
-
-    super(client)
-  }
-}
-export declare const fileSystem: unknown;

package/dist/index.d.ts

@@ -1,2 +0,0 @@
-export * from './drivers'
-export * as dynamoDbTool from 'dynamodb-tooling'

package/dist/memory.d.ts

@@ -1,18 +0,0 @@
-export declare class MemoryCacheDriver extends BaseCacheDriver {
-  constructor(options: { maxSize?: number, maxItems?: number } = {}) {
-    const client = new BentoCache({
-      default: 'memory',
-      stores: {
-        memory: bentostore().useL1Layer(
-          memoryDriver({
-            maxSize: options.maxSize ?? 10 * 1024 * 1024, 
-            maxItems: options.maxItems ?? 1000,
-          }),
-        ),
-      },
-    })
-
-    super(client)
-  }
-}
-export declare const memory: MemoryCacheDriver;

package/dist/redis.d.ts

@@ -1,32 +0,0 @@
-export declare interface RedisOptions {
-  host?: string
-  port?: number
-  username?: string
-  password?: string
-  db?: number
-  tls?: boolean
-}
-export declare class RedisCacheDriver extends BaseCacheDriver {
-  constructor(options: RedisOptions = {}) {
-    const client = new BentoCache({
-      default: 'redis',
-      stores: {
-        redis: bentostore().useL2Layer(
-          redisDriver({
-            connection: {
-              host: options.host ?? '127.0.0.1',
-              port: options.port ?? 6379,
-              ...(options.username && { username: options.username }),
-              ...(options.password && { password: options.password }),
-              ...(options.db !== undefined && { db: options.db }),
-              ...(options.tls && { tls: {} }),
-            },
-          }),
-        ),
-      },
-    })
-
-    super(client)
-  }
-}
-export declare const redis: RedisCacheDriver;