@veloxts/cache 0.6.56 → 0.6.58

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @veloxts/cache
 
+## 0.6.58
+
+### Patch Changes
+
+- feat(router): add OpenAPI 3.0.3 specification generator
+- Updated dependencies
+  - @veloxts/core@0.6.58
+
+## 0.6.57
+
+### Patch Changes
+
+- feat: add DI support to ecosystem packages and main packages
+- Updated dependencies
+  - @veloxts/core@0.6.57
+
 ## 0.6.56
 
 ### Patch Changes

package/README.md

@@ -1,29 +1,8 @@
 # @veloxts/cache
 
-> **Early Preview** - APIs may change before v1.0.
+> **Early Preview (v0.6.x)** - APIs are stabilizing but may still change. Use with caution in production.
 
-Multi-driver caching with tags, locks, and the remember pattern.
-
-## Installation
-
-```bash
-npm install @veloxts/cache
-```
-
-## Quick Start
-
-```typescript
-import { cachePlugin } from '@veloxts/cache';
-
-app.use(cachePlugin({ driver: 'memory' }));
-
-// In your procedures
-const user = await ctx.cache.remember('user:123', '1h', async () => {
-  return db.user.findUnique({ where: { id: '123' } });
-});
-```
-
-See [GUIDE.md](./GUIDE.md) for detailed documentation.
+Multi-driver caching for VeloxTS Framework - provides memory and Redis drivers with tags, locks, and the remember pattern. Learn more at [@veloxts/velox](https://www.npmjs.com/package/@veloxts/velox).
 
 ## License
 

package/dist/index.d.ts

@@ -0,0 +1,65 @@
+/**
+ * @veloxts/cache
+ *
+ * Multi-driver caching layer for VeloxTS framework.
+ *
+ * Features:
+ * - Multiple drivers: memory (lru-cache), Redis (ioredis)
+ * - Type-safe cache operations with automatic serialization
+ * - Cache tags for grouped invalidation
+ * - Distributed locks for exclusive access
+ * - `remember()` pattern for cache-aside
+ * - Human-readable TTL strings ('1h', '30m', '1d')
+ *
+ * @example
+ * ```typescript
+ * import { cachePlugin } from '@veloxts/cache';
+ *
+ * // Register plugin
+ * app.use(cachePlugin({
+ *   driver: 'redis',
+ *   config: { url: process.env.REDIS_URL },
+ * }));
+ *
+ * // In procedures:
+ * const user = await ctx.cache.remember('user:123', '1h', async () => {
+ *   return ctx.db.user.findUnique({ where: { id: '123' } });
+ * });
+ *
+ * // Tags for grouped invalidation
+ * await ctx.cache.tags(['users']).put('user:123', user);
+ * await ctx.cache.tags(['users']).flush();
+ *
+ * // Distributed locks
+ * await ctx.cache.lockAndRun('payment:process', '30s', async () => {
+ *   // Only one process can run this at a time
+ * });
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { createMemoryCache, DRIVER_NAME as MEMORY_DRIVER } from './drivers/memory.js';
+export { createRedisCache, DRIVER_NAME as REDIS_DRIVER } from './drivers/redis.js';
+export { type CacheManager, cache, createCacheManager, type TaggedCache, } from './manager.js';
+export { cachePlugin, closeCache, getCache, getCacheFromInstance, initCache, } from './plugin.js';
+export type { CacheConfig, CacheDriver, CacheEntry, CacheOptions, CachePluginOptions, CacheStore, DurationString, LockOptions, LockResult, MemoryCacheConfig, RedisCacheConfig, TaggableCacheStore, TTL, } from './types.js';
+export { formatTtl, isDurationString, parseTtl, parseTtlMs, } from './utils.js';
+/**
+ * DI tokens and providers for @veloxts/cache
+ *
+ * Use these to integrate cache services with the @veloxts/core DI container.
+ *
+ * @example
+ * ```typescript
+ * import { Container } from '@veloxts/core';
+ * import { registerCacheProviders, CACHE_MANAGER } from '@veloxts/cache';
+ *
+ * const container = new Container();
+ * await registerCacheProviders(container, { driver: 'memory' });
+ *
+ * const cache = container.resolve(CACHE_MANAGER);
+ * await cache.put('key', 'value', '1h');
+ * ```
+ */
+export { registerCacheProviders } from './providers.js';
+export { CACHE_CONFIG, CACHE_MANAGER, CACHE_STORE } from './tokens.js';

package/dist/index.js

@@ -47,3 +47,27 @@ export { cache, createCacheManager, } from './manager.js';
 export { cachePlugin, closeCache, getCache, getCacheFromInstance, initCache, } from './plugin.js';
 // Utilities
 export { formatTtl, isDurationString, parseTtl, parseTtlMs, } from './utils.js';
+// ============================================================================
+// Dependency Injection
+// ============================================================================
+/**
+ * DI tokens and providers for @veloxts/cache
+ *
+ * Use these to integrate cache services with the @veloxts/core DI container.
+ *
+ * @example
+ * ```typescript
+ * import { Container } from '@veloxts/core';
+ * import { registerCacheProviders, CACHE_MANAGER } from '@veloxts/cache';
+ *
+ * const container = new Container();
+ * await registerCacheProviders(container, { driver: 'memory' });
+ *
+ * const cache = container.resolve(CACHE_MANAGER);
+ * await cache.put('key', 'value', '1h');
+ * ```
+ */
+// Provider exports - factory functions for registering services
+export { registerCacheProviders } from './providers.js';
+// Token exports - unique identifiers for DI resolution
+export { CACHE_CONFIG, CACHE_MANAGER, CACHE_STORE } from './tokens.js';

package/dist/providers.d.ts

@@ -0,0 +1,52 @@
+/**
+ * DI Providers for @veloxts/cache
+ *
+ * Factory provider functions for registering cache services with the DI container.
+ * These providers allow services to be managed by the container for testability and flexibility.
+ *
+ * @module cache/providers
+ *
+ * @example
+ * ```typescript
+ * import { Container } from '@veloxts/core';
+ * import { registerCacheProviders, CACHE_MANAGER } from '@veloxts/cache';
+ *
+ * const container = new Container();
+ * await registerCacheProviders(container, { driver: 'memory' });
+ *
+ * const cache = container.resolve(CACHE_MANAGER);
+ * await cache.put('key', 'value', '1h');
+ * ```
+ */
+import type { Container } from '@veloxts/core';
+import type { CachePluginOptions } from './types.js';
+/**
+ * Registers cache providers with a container
+ *
+ * This handles async initialization of the cache manager and registers
+ * the resolved instance directly for synchronous resolution.
+ *
+ * @param container - The DI container to register providers with
+ * @param config - Cache plugin options (driver, prefix, etc.)
+ *
+ * @example
+ * ```typescript
+ * import { Container } from '@veloxts/core';
+ * import { registerCacheProviders, CACHE_MANAGER } from '@veloxts/cache';
+ *
+ * const container = new Container();
+ *
+ * // Memory cache (development)
+ * await registerCacheProviders(container, { driver: 'memory' });
+ *
+ * // Redis cache (production)
+ * await registerCacheProviders(container, {
+ *   driver: 'redis',
+ *   config: { url: process.env.REDIS_URL },
+ * });
+ *
+ * const cache = container.resolve(CACHE_MANAGER);
+ * await cache.put('key', 'value', '30m');
+ * ```
+ */
+export declare function registerCacheProviders(container: Container, config?: CachePluginOptions): Promise<void>;

package/dist/providers.js

@@ -0,0 +1,69 @@
+/**
+ * DI Providers for @veloxts/cache
+ *
+ * Factory provider functions for registering cache services with the DI container.
+ * These providers allow services to be managed by the container for testability and flexibility.
+ *
+ * @module cache/providers
+ *
+ * @example
+ * ```typescript
+ * import { Container } from '@veloxts/core';
+ * import { registerCacheProviders, CACHE_MANAGER } from '@veloxts/cache';
+ *
+ * const container = new Container();
+ * await registerCacheProviders(container, { driver: 'memory' });
+ *
+ * const cache = container.resolve(CACHE_MANAGER);
+ * await cache.put('key', 'value', '1h');
+ * ```
+ */
+import { createCacheManager } from './manager.js';
+import { CACHE_CONFIG, CACHE_MANAGER } from './tokens.js';
+// ============================================================================
+// Bulk Registration Helpers
+// ============================================================================
+/**
+ * Registers cache providers with a container
+ *
+ * This handles async initialization of the cache manager and registers
+ * the resolved instance directly for synchronous resolution.
+ *
+ * @param container - The DI container to register providers with
+ * @param config - Cache plugin options (driver, prefix, etc.)
+ *
+ * @example
+ * ```typescript
+ * import { Container } from '@veloxts/core';
+ * import { registerCacheProviders, CACHE_MANAGER } from '@veloxts/cache';
+ *
+ * const container = new Container();
+ *
+ * // Memory cache (development)
+ * await registerCacheProviders(container, { driver: 'memory' });
+ *
+ * // Redis cache (production)
+ * await registerCacheProviders(container, {
+ *   driver: 'redis',
+ *   config: { url: process.env.REDIS_URL },
+ * });
+ *
+ * const cache = container.resolve(CACHE_MANAGER);
+ * await cache.put('key', 'value', '30m');
+ * ```
+ */
+export async function registerCacheProviders(container, config = {}) {
+    // Register config
+    container.register({
+        provide: CACHE_CONFIG,
+        useValue: config,
+    });
+    // Create cache manager (async operation)
+    const cacheManager = await createCacheManager(config);
+    // Register the resolved cache manager instance directly
+    // This allows synchronous resolution from the container
+    container.register({
+        provide: CACHE_MANAGER,
+        useValue: cacheManager,
+    });
+}

package/dist/tokens.d.ts

@@ -0,0 +1,60 @@
+/**
+ * DI Tokens for @veloxts/cache
+ *
+ * Symbol-based tokens for type-safe dependency injection.
+ * These tokens allow cache services to be registered, resolved, and mocked via the DI container.
+ *
+ * @module cache/tokens
+ *
+ * @example
+ * ```typescript
+ * import { Container } from '@veloxts/core';
+ * import { CACHE_MANAGER, registerCacheProviders } from '@veloxts/cache';
+ *
+ * const container = new Container();
+ * await registerCacheProviders(container, { driver: 'memory' });
+ *
+ * const cache = container.resolve(CACHE_MANAGER);
+ * await cache.put('key', 'value', '1h');
+ * ```
+ */
+import type { CacheManager } from './manager.js';
+import type { CachePluginOptions, TaggableCacheStore } from './types.js';
+/**
+ * Cache manager token
+ *
+ * The main cache manager instance with get/put/remember/tags/lock support.
+ *
+ * @example
+ * ```typescript
+ * const cache = container.resolve(CACHE_MANAGER);
+ * await cache.put('user:123', user, '30m');
+ * const cached = await cache.get('user:123');
+ * ```
+ */
+export declare const CACHE_MANAGER: import("@veloxts/core").SymbolToken<CacheManager>;
+/**
+ * Cache store token
+ *
+ * The underlying cache store (memory or Redis).
+ * Use CACHE_MANAGER for high-level operations; use this for direct store access.
+ *
+ * @example
+ * ```typescript
+ * const store = container.resolve(CACHE_STORE);
+ * await store.putWithTags('key', value, ['users'], '1h');
+ * ```
+ */
+export declare const CACHE_STORE: import("@veloxts/core").SymbolToken<TaggableCacheStore>;
+/**
+ * Cache configuration token
+ *
+ * Contains cache plugin options including driver and driver-specific config.
+ *
+ * @example
+ * ```typescript
+ * const config = container.resolve(CACHE_CONFIG);
+ * console.log(config.driver); // 'memory' or 'redis'
+ * ```
+ */
+export declare const CACHE_CONFIG: import("@veloxts/core").SymbolToken<CachePluginOptions>;

package/dist/tokens.js

@@ -0,0 +1,65 @@
+/**
+ * DI Tokens for @veloxts/cache
+ *
+ * Symbol-based tokens for type-safe dependency injection.
+ * These tokens allow cache services to be registered, resolved, and mocked via the DI container.
+ *
+ * @module cache/tokens
+ *
+ * @example
+ * ```typescript
+ * import { Container } from '@veloxts/core';
+ * import { CACHE_MANAGER, registerCacheProviders } from '@veloxts/cache';
+ *
+ * const container = new Container();
+ * await registerCacheProviders(container, { driver: 'memory' });
+ *
+ * const cache = container.resolve(CACHE_MANAGER);
+ * await cache.put('key', 'value', '1h');
+ * ```
+ */
+import { token } from '@veloxts/core';
+// ============================================================================
+// Core Cache Tokens
+// ============================================================================
+/**
+ * Cache manager token
+ *
+ * The main cache manager instance with get/put/remember/tags/lock support.
+ *
+ * @example
+ * ```typescript
+ * const cache = container.resolve(CACHE_MANAGER);
+ * await cache.put('user:123', user, '30m');
+ * const cached = await cache.get('user:123');
+ * ```
+ */
+export const CACHE_MANAGER = token.symbol('CACHE_MANAGER');
+/**
+ * Cache store token
+ *
+ * The underlying cache store (memory or Redis).
+ * Use CACHE_MANAGER for high-level operations; use this for direct store access.
+ *
+ * @example
+ * ```typescript
+ * const store = container.resolve(CACHE_STORE);
+ * await store.putWithTags('key', value, ['users'], '1h');
+ * ```
+ */
+export const CACHE_STORE = token.symbol('CACHE_STORE');
+// ============================================================================
+// Configuration Tokens
+// ============================================================================
+/**
+ * Cache configuration token
+ *
+ * Contains cache plugin options including driver and driver-specific config.
+ *
+ * @example
+ * ```typescript
+ * const config = container.resolve(CACHE_CONFIG);
+ * console.log(config.driver); // 'memory' or 'redis'
+ * ```
+ */
+export const CACHE_CONFIG = token.symbol('CACHE_CONFIG');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veloxts/cache",
-  "version": "0.6.56",
+  "version": "0.6.58",
   "description": "Multi-driver caching layer for VeloxTS framework",
   "type": "module",
   "main": "dist/index.js",
@@ -31,7 +31,7 @@
     "fastify-plugin": "5.1.0",
     "lru-cache": "11.1.0",
     "superjson": "2.2.2",
-    "@veloxts/core": "0.6.56"
+    "@veloxts/core": "0.6.58"
   },
   "peerDependencies": {
     "ioredis": ">=5.0.0"
@@ -47,7 +47,7 @@
     "ioredis": "5.6.1",
     "typescript": "5.9.3",
     "vitest": "4.0.16",
-    "@veloxts/testing": "0.6.56"
+    "@veloxts/testing": "0.6.58"
   },
   "keywords": [
     "velox",