@dotdo/do 0.1.0

package/dist/db/storage/warm.js

@@ -0,0 +1,339 @@
+/**
+ * Warm Storage - Edge Cache API
+ *
+ * Caching tier using Cloudflare's Cache API for frequently accessed data.
+ * Provides ~10ms latency with zero additional cost.
+ *
+ * Features:
+ * - Automatic cache key generation
+ * - TTL management
+ * - Pattern-based invalidation
+ * - Cache-aside pattern support
+ *
+ * @module @do/core/storage/warm
+ */
+/**
+ * Warm storage implementation using Edge Cache API
+ *
+ * @example
+ * ```typescript
+ * const warm = new WarmStorage(caches.default)
+ *
+ * // Cache a value
+ * await warm.set('users:123', user, { ttl: 300 })
+ *
+ * // Get cached value
+ * const cached = await warm.get<User>('users:123')
+ *
+ * // Cache-aside pattern
+ * const user = await warm.getOrSet('users:123', async () => {
+ *   return await hot.get('users', '123')
+ * }, { ttl: 300 })
+ *
+ * // Invalidate by pattern
+ * await warm.invalidate('users:*')
+ * ```
+ */
+export class WarmStorage {
+    cache;
+    config;
+    stats;
+    /**
+     * Create a new warm storage instance
+     *
+     * @param cache - Cloudflare Cache API instance
+     * @param config - Cache configuration
+     */
+    constructor(cache, config) {
+        this.cache = cache;
+        this.config = {
+            defaultTTL: config?.defaultTTL ?? 300,
+            keyPrefix: config?.keyPrefix ?? 'do-cache:',
+            maxValueSize: config?.maxValueSize ?? 1024 * 1024, // 1MB
+            compression: config?.compression ?? true,
+        };
+        this.stats = {
+            hits: 0,
+            misses: 0,
+            hitRate: 0,
+            invalidations: 0,
+            entries: 0,
+        };
+    }
+    /**
+     * Get a value from cache
+     *
+     * @param key - Cache key
+     * @returns Cached value or null if not found/expired
+     *
+     * @example
+     * ```typescript
+     * const user = await warm.get<User>('users:123')
+     * if (user) {
+     *   console.log('Cache hit:', user.name)
+     * } else {
+     *   console.log('Cache miss')
+     * }
+     * ```
+     */
+    async get(key) {
+        // TODO: Implement cache get
+        throw new Error('Not implemented');
+    }
+    /**
+     * Get a value with metadata
+     *
+     * @param key - Cache key
+     * @returns Cache entry with metadata or null
+     */
+    async getEntry(key) {
+        // TODO: Implement cache get with metadata
+        throw new Error('Not implemented');
+    }
+    /**
+     * Set a value in cache
+     *
+     * @param key - Cache key
+     * @param value - Value to cache
+     * @param options - Cache options
+     *
+     * @example
+     * ```typescript
+     * await warm.set('users:123', user, {
+     *   ttl: 600, // 10 minutes
+     *   tags: ['users', 'user:123'],
+     * })
+     * ```
+     */
+    async set(key, value, options) {
+        // TODO: Implement cache set
+        throw new Error('Not implemented');
+    }
+    /**
+     * Get or set a cached value (cache-aside pattern)
+     *
+     * If the key exists in cache, returns cached value.
+     * Otherwise, calls the factory function, caches the result, and returns it.
+     *
+     * @param key - Cache key
+     * @param factory - Function to generate value on cache miss
+     * @param options - Cache options
+     * @returns Cached or generated value
+     *
+     * @example
+     * ```typescript
+     * const user = await warm.getOrSet('users:123', async () => {
+     *   return await db.query('SELECT * FROM users WHERE id = ?', [123])
+     * }, { ttl: 300 })
+     * ```
+     */
+    async getOrSet(key, factory, options) {
+        // TODO: Implement cache-aside pattern
+        throw new Error('Not implemented');
+    }
+    /**
+     * Delete a specific key from cache
+     *
+     * @param key - Cache key
+     * @returns True if key was deleted
+     *
+     * @example
+     * ```typescript
+     * await warm.delete('users:123')
+     * ```
+     */
+    async delete(key) {
+        // TODO: Implement cache delete
+        throw new Error('Not implemented');
+    }
+    /**
+     * Invalidate cache entries by pattern
+     *
+     * Supports glob-style patterns:
+     * - `users:*` - All keys starting with "users:"
+     * - `*:123` - All keys ending with ":123"
+     * - `users:*:orders` - Keys matching pattern
+     *
+     * @param pattern - Glob pattern for keys to invalidate
+     * @returns Number of entries invalidated
+     *
+     * @example
+     * ```typescript
+     * // Invalidate all user cache entries
+     * await warm.invalidate('users:*')
+     *
+     * // Invalidate specific user's related caches
+     * await warm.invalidate('*:user:123:*')
+     * ```
+     */
+    async invalidate(pattern) {
+        // TODO: Implement pattern-based invalidation
+        // Note: Cache API doesn't support listing, so this requires
+        // maintaining a key registry or using cache tags
+        throw new Error('Not implemented');
+    }
+    /**
+     * Invalidate cache entries by tag
+     *
+     * @param tag - Tag to invalidate
+     * @returns Number of entries invalidated
+     *
+     * @example
+     * ```typescript
+     * // Invalidate all entries tagged with 'user:123'
+     * await warm.invalidateByTag('user:123')
+     * ```
+     */
+    async invalidateByTag(tag) {
+        // TODO: Implement tag-based invalidation
+        throw new Error('Not implemented');
+    }
+    /**
+     * Check if a key exists in cache
+     *
+     * @param key - Cache key
+     * @returns True if key exists and is not expired
+     */
+    async has(key) {
+        // TODO: Implement existence check
+        throw new Error('Not implemented');
+    }
+    /**
+     * Get multiple values from cache
+     *
+     * @param keys - Array of cache keys
+     * @returns Map of key to value (missing keys omitted)
+     *
+     * @example
+     * ```typescript
+     * const users = await warm.getMany(['users:1', 'users:2', 'users:3'])
+     * for (const [key, user] of users) {
+     *   console.log(key, user.name)
+     * }
+     * ```
+     */
+    async getMany(keys) {
+        // TODO: Implement batch get
+        throw new Error('Not implemented');
+    }
+    /**
+     * Set multiple values in cache
+     *
+     * @param entries - Map of key to value
+     * @param options - Cache options (applied to all entries)
+     *
+     * @example
+     * ```typescript
+     * await warm.setMany(new Map([
+     *   ['users:1', user1],
+     *   ['users:2', user2],
+     * ]), { ttl: 300 })
+     * ```
+     */
+    async setMany(entries, options) {
+        // TODO: Implement batch set
+        throw new Error('Not implemented');
+    }
+    /**
+     * Get cache statistics
+     *
+     * @returns Cache statistics
+     */
+    getStats() {
+        return { ...this.stats };
+    }
+    /**
+     * Reset cache statistics
+     */
+    resetStats() {
+        this.stats = {
+            hits: 0,
+            misses: 0,
+            hitRate: 0,
+            invalidations: 0,
+            entries: 0,
+        };
+    }
+    /**
+     * Build full cache key with prefix
+     *
+     * @param key - User-provided key
+     * @returns Full cache key
+     */
+    buildKey(key) {
+        return `${this.config.keyPrefix}${key}`;
+    }
+    /**
+     * Convert cache key to Request object
+     *
+     * Cache API requires Request objects as keys.
+     *
+     * @param key - Cache key
+     * @returns Request object for cache operations
+     */
+    toRequest(key) {
+        return new Request(`https://cache.internal/${this.buildKey(key)}`);
+    }
+    /**
+     * Create Response object for caching
+     *
+     * @param value - Value to cache
+     * @param options - Cache options
+     * @returns Response object with proper headers
+     */
+    toResponse(value, options) {
+        const ttl = options?.ttl ?? this.config.defaultTTL;
+        const body = JSON.stringify({
+            value,
+            cachedAt: Date.now(),
+            expiresAt: Date.now() + ttl * 1000,
+            tags: options?.tags ?? [],
+        });
+        return new Response(body, {
+            headers: {
+                'Content-Type': 'application/json',
+                'Cache-Control': `max-age=${ttl}`,
+            },
+        });
+    }
+}
+/**
+ * Cache key builder utility
+ *
+ * Builds consistent cache keys from components.
+ *
+ * @example
+ * ```typescript
+ * const key = cacheKey('users', userId, 'orders')
+ * // Returns: 'users:abc123:orders'
+ * ```
+ */
+export function cacheKey(...parts) {
+    return parts.join(':');
+}
+/**
+ * Parse cache key into components
+ *
+ * @param key - Cache key
+ * @returns Array of key components
+ */
+export function parseCacheKey(key) {
+    return key.split(':');
+}
+/**
+ * Check if a key matches a glob pattern
+ *
+ * @param key - Cache key to check
+ * @param pattern - Glob pattern
+ * @returns True if key matches pattern
+ */
+export function matchesCachePattern(key, pattern) {
+    const regex = new RegExp('^' +
+        pattern
+            .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+            .replace(/\*/g, '.*')
+            .replace(/\?/g, '.') +
+        '$');
+    return regex.test(key);
+}
+//# sourceMappingURL=warm.js.map

package/dist/db/storage/warm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"warm.js","sourceRoot":"","sources":["../../../db/storage/warm.ts"],"names":[],"mappings":"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"}