@veloxts/cache 0.7.1 → 0.7.3

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @veloxts/cache
 
+## 0.7.3
+
+### Patch Changes
+
+- feat(cli): auto-populate Zod schemas from Prisma model fields
+- Updated dependencies
+  - @veloxts/core@0.7.3
+
+## 0.7.2
+
+### Patch Changes
+
+- Updated dependencies
+  - @veloxts/core@0.7.2
+
 ## 0.7.1
 
 ### Patch Changes

package/dist/drivers/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Cache Drivers
+ *
+ * Re-exports all cache driver implementations.
+ */
+export { createMemoryCache, DRIVER_NAME as MEMORY_DRIVER } from './memory.js';
+export { createRedisCache, DRIVER_NAME as REDIS_DRIVER } from './redis.js';

package/dist/drivers/memory.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Memory Cache Driver
+ *
+ * In-memory cache implementation using LRU-cache.
+ * Best for development or single-instance deployments.
+ */
+import type { MemoryCacheConfig, TaggableCacheStore } from '../types.js';
+/**
+ * Create a memory cache store.
+ *
+ * @param config - Memory cache configuration
+ * @returns Cache store implementation
+ *
+ * @example
+ * ```typescript
+ * const cache = createMemoryCache({ maxSize: 500 });
+ *
+ * await cache.put('user:123', { name: 'John' }, '30m');
+ * const user = await cache.get('user:123');
+ * ```
+ */
+export declare function createMemoryCache(config?: Omit<MemoryCacheConfig, 'driver'>): TaggableCacheStore;
+/**
+ * Memory cache driver name.
+ */
+export declare const DRIVER_NAME: "memory";

package/dist/drivers/redis.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Redis Cache Driver
+ *
+ * Redis cache implementation using ioredis.
+ * Best for production and multi-instance deployments.
+ */
+import type { RedisCacheConfig, TaggableCacheStore } from '../types.js';
+/**
+ * Create a Redis cache store.
+ *
+ * @param config - Redis cache configuration
+ * @returns Cache store implementation
+ *
+ * @example
+ * ```typescript
+ * const cache = await createRedisCache({
+ *   url: process.env.REDIS_URL,
+ *   prefix: 'myapp:',
+ * });
+ *
+ * await cache.put('user:123', { name: 'John' }, '30m');
+ * const user = await cache.get('user:123');
+ * ```
+ */
+export declare function createRedisCache(config: Omit<RedisCacheConfig, 'driver'>): Promise<TaggableCacheStore>;
+/**
+ * Redis cache driver name.
+ */
+export declare const DRIVER_NAME: "redis";

package/dist/manager.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Cache Manager
+ *
+ * High-level cache API with remember, tags, and lock support.
+ */
+import type { CachePluginOptions, LockOptions, LockResult, TTL } from './types.js';
+/**
+ * Cache manager interface.
+ */
+export interface CacheManager {
+    /**
+     * Get a value from the cache.
+     */
+    get<T>(key: string): Promise<T | null>;
+    /**
+     * Store a value in the cache.
+     */
+    put<T>(key: string, value: T, ttl?: TTL): Promise<void>;
+    /**
+     * Check if a key exists in the cache.
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * Remove a key from the cache.
+     */
+    forget(key: string): Promise<boolean>;
+    /**
+     * Increment a numeric value.
+     */
+    increment(key: string, value?: number): Promise<number>;
+    /**
+     * Decrement a numeric value.
+     */
+    decrement(key: string, value?: number): Promise<number>;
+    /**
+     * Clear all entries from the cache.
+     */
+    flush(): Promise<void>;
+    /**
+     * Get multiple values from the cache.
+     */
+    many<T>(keys: string[]): Promise<Map<string, T | null>>;
+    /**
+     * Store multiple values in the cache.
+     */
+    putMany<T>(entries: Map<string, T>, ttl?: TTL): Promise<void>;
+    /**
+     * Get a value or compute and cache it if not present.
+     */
+    remember<T>(key: string, ttl: TTL, callback: () => Promise<T>): Promise<T>;
+    /**
+     * Get a value or compute and cache it forever if not present.
+     */
+    rememberForever<T>(key: string, callback: () => Promise<T>): Promise<T>;
+    /**
+     * Delete a value and return it.
+     */
+    pull<T>(key: string): Promise<T | null>;
+    /**
+     * Store a value only if the key doesn't exist.
+     */
+    add<T>(key: string, value: T, ttl?: TTL): Promise<boolean>;
+    /**
+     * Create a tagged cache instance.
+     */
+    tags(tags: string[]): TaggedCache;
+    /**
+     * Acquire a distributed lock.
+     */
+    lock(key: string, options: LockOptions): Promise<LockResult>;
+    /**
+     * Execute a callback with a lock.
+     */
+    lockAndRun<T>(key: string, ttl: TTL, callback: () => Promise<T>): Promise<T>;
+    /**
+     * Close the cache connection.
+     */
+    close(): Promise<void>;
+}
+/**
+ * Tagged cache interface for grouped invalidation.
+ */
+export interface TaggedCache {
+    /**
+     * Get a value from the tagged cache.
+     */
+    get<T>(key: string): Promise<T | null>;
+    /**
+     * Store a value with the configured tags.
+     */
+    put<T>(key: string, value: T, ttl?: TTL): Promise<void>;
+    /**
+     * Get a value or compute and cache it with tags.
+     */
+    remember<T>(key: string, ttl: TTL, callback: () => Promise<T>): Promise<T>;
+    /**
+     * Flush all entries with the configured tags.
+     */
+    flush(): Promise<void>;
+}
+/**
+ * Create a cache manager.
+ *
+ * @param options - Cache plugin options
+ * @returns Cache manager instance
+ *
+ * @example
+ * ```typescript
+ * // Memory cache (development)
+ * const cache = await createCacheManager({ driver: 'memory' });
+ *
+ * // Redis cache (production)
+ * const cache = await createCacheManager({
+ *   driver: 'redis',
+ *   config: { url: process.env.REDIS_URL },
+ * });
+ *
+ * // Basic usage
+ * await cache.put('user:123', { name: 'John' }, '30m');
+ * const user = await cache.get('user:123');
+ *
+ * // Remember pattern
+ * const user = await cache.remember('user:123', '1h', async () => {
+ *   return await db.user.findUnique({ where: { id: '123' } });
+ * });
+ *
+ * // Tags for grouped invalidation
+ * await cache.tags(['users']).put('user:123', user);
+ * await cache.tags(['users']).flush(); // Invalidates all user entries
+ *
+ * // Distributed lock
+ * await cache.lockAndRun('process:payment', '30s', async () => {
+ *   // Only one process can run this at a time
+ * });
+ * ```
+ */
+export declare function createCacheManager(options?: CachePluginOptions): Promise<CacheManager>;
+/**
+ * Alias for createCacheManager.
+ */
+export declare const cache: typeof createCacheManager;

package/dist/utils.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Cache Utilities
+ *
+ * Helper functions for cache operations.
+ */
+import type { DurationString, TTL } from './types.js';
+/**
+ * Check if a value is a duration string.
+ */
+export declare function isDurationString(value: unknown): value is DurationString;
+/**
+ * Parse a TTL value to seconds.
+ *
+ * @param ttl - TTL as seconds (number) or duration string (e.g., '1h', '30m')
+ * @returns TTL in seconds
+ *
+ * @example
+ * ```typescript
+ * parseTtl(3600)      // 3600
+ * parseTtl('1h')      // 3600
+ * parseTtl('30m')     // 1800
+ * parseTtl('1d')      // 86400
+ * ```
+ */
+export declare function parseTtl(ttl: TTL): number;
+/**
+ * Parse a TTL value to milliseconds.
+ */
+export declare function parseTtlMs(ttl: TTL): number;
+/**
+ * Format a TTL in seconds to a human-readable string.
+ */
+export declare function formatTtl(seconds: number): string;
+/**
+ * Calculate expiration timestamp from TTL.
+ */
+export declare function calculateExpiration(ttl: TTL): number;
+/**
+ * Check if a timestamp has expired.
+ */
+export declare function isExpired(expiresAt: number | null): boolean;
+/**
+ * Generate a cache key with prefix.
+ */
+export declare function prefixKey(key: string, prefix: string): string;
+/**
+ * Generate a tag key for tag-based invalidation.
+ */
+export declare function tagKey(tag: string, prefix: string): string;
+/**
+ * Generate a unique lock token using cryptographically secure random values.
+ */
+export declare function generateLockToken(): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veloxts/cache",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "description": "Multi-driver caching layer for VeloxTS framework",
   "type": "module",
   "main": "dist/index.js",
@@ -35,7 +35,7 @@
     "fastify-plugin": "5.1.0",
     "lru-cache": "11.2.6",
     "superjson": "2.2.6",
-    "@veloxts/core": "0.7.1"
+    "@veloxts/core": "0.7.3"
   },
   "peerDependencies": {
     "ioredis": ">=5.0.0"
@@ -51,7 +51,7 @@
     "ioredis": "5.9.3",
     "typescript": "5.9.3",
     "vitest": "4.0.18",
-    "@veloxts/testing": "0.7.1"
+    "@veloxts/testing": "0.7.3"
   },
   "keywords": [
     "velox",