@tamyla/clodo-framework 4.3.4 → 4.4.0

package/dist/utilities/kv/storage.js

@@ -0,0 +1,268 @@
+/**
+ * KV Storage Utilities
+ * Convenient wrapper for Cloudflare Workers KV
+ * 
+ * @example
+ * import { KVStorage, KVCache } from '@tamyla/clodo-framework/utilities/kv';
+ * 
+ * const kv = new KVStorage(env.MY_KV);
+ * await kv.set('key', { data: 'value' }, { expirationTtl: 3600 });
+ * const data = await kv.get('key');
+ */
+
+/**
+ * KV Storage wrapper with convenience methods
+ */
+export class KVStorage {
+  /**
+   * @param {KVNamespace} namespace - KV namespace binding
+   */
+  constructor(namespace) {
+    if (!namespace) {
+      throw new Error('KV namespace binding is required');
+    }
+    this.kv = namespace;
+  }
+
+  /**
+   * Get a value from KV
+   * @param {string} key - Key to retrieve
+   * @param {Object} options - Get options
+   * @param {string} options.type - Return type: 'text', 'json', 'arrayBuffer', 'stream'
+   * @returns {Promise<*>}
+   */
+  async get(key, options = {}) {
+    const type = options.type || 'json';
+    return this.kv.get(key, {
+      type
+    });
+  }
+
+  /**
+   * Get value with metadata
+   * @param {string} key - Key to retrieve
+   * @param {Object} options - Get options
+   * @returns {Promise<{value: *, metadata: Object}>}
+   */
+  async getWithMetadata(key, options = {}) {
+    const type = options.type || 'json';
+    return this.kv.getWithMetadata(key, {
+      type
+    });
+  }
+
+  /**
+   * Set a value in KV
+   * @param {string} key - Key to set
+   * @param {*} value - Value to store (objects will be JSON serialized)
+   * @param {Object} options - Put options
+   * @param {number} options.expirationTtl - TTL in seconds
+   * @param {number} options.expiration - Unix timestamp for expiration
+   * @param {Object} options.metadata - Custom metadata
+   * @returns {Promise<void>}
+   */
+  async set(key, value, options = {}) {
+    const serialized = typeof value === 'object' ? JSON.stringify(value) : value;
+    const putOptions = {};
+    if (options.expirationTtl) putOptions.expirationTtl = options.expirationTtl;
+    if (options.expiration) putOptions.expiration = options.expiration;
+    if (options.metadata) putOptions.metadata = options.metadata;
+    await this.kv.put(key, serialized, putOptions);
+  }
+
+  /**
+   * Delete a key from KV
+   * @param {string} key - Key to delete
+   * @returns {Promise<void>}
+   */
+  async delete(key) {
+    await this.kv.delete(key);
+  }
+
+  /**
+   * List keys in KV
+   * @param {Object} options - List options
+   * @param {string} options.prefix - Key prefix to filter by
+   * @param {number} options.limit - Maximum keys to return
+   * @param {string} options.cursor - Pagination cursor
+   * @returns {Promise<{keys: Array, list_complete: boolean, cursor: string}>}
+   */
+  async list(options = {}) {
+    return this.kv.list({
+      prefix: options.prefix,
+      limit: options.limit || 1000,
+      cursor: options.cursor
+    });
+  }
+
+  /**
+   * List all keys (handles pagination)
+   * @param {string} prefix - Key prefix to filter by
+   * @returns {AsyncGenerator<{name: string, expiration?: number, metadata?: Object}>}
+   */
+  async *listAll(prefix = '') {
+    let cursor;
+    do {
+      const result = await this.list({
+        prefix,
+        cursor
+      });
+      for (const key of result.keys) {
+        yield key;
+      }
+      cursor = result.list_complete ? null : result.cursor;
+    } while (cursor);
+  }
+
+  /**
+   * Check if a key exists
+   * @param {string} key - Key to check
+   * @returns {Promise<boolean>}
+   */
+  async exists(key) {
+    const value = await this.kv.get(key);
+    return value !== null;
+  }
+
+  /**
+   * Get multiple keys at once
+   * @param {string[]} keys - Keys to retrieve
+   * @returns {Promise<Map<string, *>>}
+   */
+  async getMany(keys) {
+    const results = new Map();
+    await Promise.all(keys.map(async key => {
+      const value = await this.get(key);
+      results.set(key, value);
+    }));
+    return results;
+  }
+
+  /**
+   * Set multiple key-value pairs
+   * @param {Object} entries - Key-value pairs to set
+   * @param {Object} options - Put options (applied to all)
+   * @returns {Promise<void>}
+   */
+  async setMany(entries, options = {}) {
+    await Promise.all(Object.entries(entries).map(([key, value]) => this.set(key, value, options)));
+  }
+}
+
+/**
+ * KV-backed cache with TTL and stale-while-revalidate support
+ */
+export class KVCache {
+  constructor(namespace, options = {}) {
+    this.kv = new KVStorage(namespace);
+    this.prefix = options.prefix || 'cache:';
+    this.defaultTTL = options.defaultTTL || 3600;
+  }
+
+  /**
+   * Get a cached value
+   */
+  async get(key) {
+    return this.kv.get(this.prefix + key);
+  }
+
+  /**
+   * Set a cached value
+   */
+  async set(key, value, ttl = this.defaultTTL) {
+    await this.kv.set(this.prefix + key, value, {
+      expirationTtl: ttl
+    });
+  }
+
+  /**
+   * Delete a cached value
+   */
+  async delete(key) {
+    await this.kv.delete(this.prefix + key);
+  }
+
+  /**
+   * Get or set with loader function
+   */
+  async getOrSet(key, loader, ttl = this.defaultTTL) {
+    const cached = await this.get(key);
+    if (cached !== null) {
+      return cached;
+    }
+    const value = await loader();
+    await this.set(key, value, ttl);
+    return value;
+  }
+
+  /**
+   * Wrap a function with caching
+   */
+  wrap(fn, keyFn, ttl = this.defaultTTL) {
+    return async (...args) => {
+      const key = keyFn(...args);
+      return this.getOrSet(key, () => fn(...args), ttl);
+    };
+  }
+
+  /**
+   * Invalidate cache entries by prefix
+   */
+  async invalidatePrefix(prefix) {
+    const fullPrefix = this.prefix + prefix;
+    for await (const key of this.kv.listAll(fullPrefix)) {
+      await this.kv.delete(key.name);
+    }
+  }
+}
+
+/**
+ * KV with typed metadata for advanced use cases
+ */
+export class KVWithMetadata {
+  constructor(namespace) {
+    this.kv = new KVStorage(namespace);
+  }
+
+  /**
+   * Store value with metadata
+   */
+  async set(key, value, metadata, options = {}) {
+    await this.kv.set(key, value, {
+      ...options,
+      metadata
+    });
+  }
+
+  /**
+   * Get value and metadata
+   */
+  async get(key) {
+    const {
+      value,
+      metadata
+    } = await this.kv.getWithMetadata(key);
+    return {
+      value,
+      metadata: metadata || {}
+    };
+  }
+
+  /**
+   * Update only metadata (re-stores value)
+   */
+  async updateMetadata(key, metadataUpdater, options = {}) {
+    const {
+      value,
+      metadata
+    } = await this.get(key);
+    if (value === null) return false;
+    const newMetadata = typeof metadataUpdater === 'function' ? metadataUpdater(metadata) : {
+      ...metadata,
+      ...metadataUpdater
+    };
+    await this.set(key, value, newMetadata, options);
+    return true;
+  }
+}
+export default KVStorage;

package/dist/utilities/queues/consumer.js

@@ -0,0 +1,188 @@
+/**
+ * Queue Consumer
+ * Process messages from Cloudflare Queues
+ * 
+ * @example
+ * import { QueueConsumer } from '@tamyla/clodo-framework/utilities/queues';
+ * 
+ * export default {
+ *   async queue(batch, env) {
+ *     const consumer = new QueueConsumer(batch, env);
+ *     await consumer.process(async (message) => {
+ *       console.log('Processing:', message.body);
+ *     });
+ *   }
+ * }
+ */
+
+export class QueueConsumer {
+  /**
+   * @param {MessageBatch} batch - The message batch from queue handler
+   * @param {Object} env - Environment bindings
+   */
+  constructor(batch, env) {
+    this.batch = batch;
+    this.env = env;
+    this.results = new Map();
+  }
+
+  /**
+   * Process all messages in the batch
+   * @param {Function} handler - Async function to handle each message
+   * @param {Object} options - Processing options
+   */
+  async process(handler, options = {}) {
+    const {
+      continueOnError = true,
+      maxRetries = 3,
+      deadLetterQueue = null
+    } = options;
+    for (const message of this.batch.messages) {
+      try {
+        await handler(message.body, {
+          id: message.id,
+          timestamp: message.timestamp,
+          attempts: message.attempts
+        });
+        message.ack();
+        this.results.set(message.id, {
+          status: 'success'
+        });
+      } catch (error) {
+        console.error(`Error processing message ${message.id}:`, error);
+        if (message.attempts >= maxRetries) {
+          // Max retries exceeded
+          if (deadLetterQueue) {
+            // Send to dead letter queue
+            await deadLetterQueue.send({
+              originalMessage: message.body,
+              error: error.message,
+              attempts: message.attempts,
+              failedAt: Date.now()
+            });
+          }
+          message.ack(); // Acknowledge to prevent infinite retry
+          this.results.set(message.id, {
+            status: 'dead_lettered',
+            error: error.message
+          });
+        } else {
+          // Retry
+          message.retry();
+          this.results.set(message.id, {
+            status: 'retrying',
+            error: error.message
+          });
+        }
+        if (!continueOnError) {
+          throw error;
+        }
+      }
+    }
+    return this.results;
+  }
+
+  /**
+   * Process messages with typed handlers
+   * @param {Object} handlers - Map of message types to handlers
+   * @param {Object} options - Processing options
+   */
+  async processTyped(handlers, options = {}) {
+    const defaultHandler = handlers.default || (async () => {
+      console.warn('No handler for message type');
+    });
+    return this.process(async (body, meta) => {
+      const type = body.type || body._type || 'default';
+      const handler = handlers[type] || defaultHandler;
+      return handler(body, meta, this.env);
+    }, options);
+  }
+
+  /**
+   * Acknowledge all messages (use with caution)
+   */
+  ackAll() {
+    this.batch.ackAll();
+  }
+
+  /**
+   * Retry all messages (use with caution)
+   */
+  retryAll() {
+    this.batch.retryAll();
+  }
+
+  /**
+   * Get batch statistics
+   */
+  getStats() {
+    return {
+      total: this.batch.messages.length,
+      queue: this.batch.queue,
+      results: Object.fromEntries(this.results)
+    };
+  }
+}
+
+/**
+ * Typed message builder for type-safe queue messages
+ */
+export class MessageBuilder {
+  constructor(type) {
+    this.message = {
+      type
+    };
+  }
+  data(data) {
+    this.message = {
+      ...this.message,
+      ...data
+    };
+    return this;
+  }
+  meta(meta) {
+    this.message._meta = {
+      ...this.message._meta,
+      ...meta
+    };
+    return this;
+  }
+  priority(priority) {
+    this.message._priority = priority;
+    return this;
+  }
+  build() {
+    return {
+      ...this.message,
+      _meta: {
+        ...this.message._meta,
+        createdAt: Date.now()
+      }
+    };
+  }
+}
+
+/**
+ * Create a typed message
+ */
+export function createMessage(type) {
+  return new MessageBuilder(type);
+}
+
+/**
+ * Common message type definitions
+ */
+export const MessageTypes = {
+  EMAIL_SEND: 'email:send',
+  EMAIL_BULK: 'email:bulk',
+  NOTIFICATION_PUSH: 'notification:push',
+  NOTIFICATION_SMS: 'notification:sms',
+  TASK_PROCESS: 'task:process',
+  TASK_CLEANUP: 'task:cleanup',
+  DATA_IMPORT: 'data:import',
+  DATA_EXPORT: 'data:export',
+  DATA_SYNC: 'data:sync',
+  WEBHOOK_DELIVER: 'webhook:deliver',
+  WEBHOOK_RETRY: 'webhook:retry'
+};
+export default QueueConsumer;

package/dist/utilities/queues/index.js

@@ -0,0 +1,7 @@
+/**
+ * Queue Utilities
+ * @module @tamyla/clodo-framework/utilities/queues
+ */
+
+export { QueueProducer } from './producer.js';
+export { QueueConsumer, MessageBuilder, createMessage, MessageTypes } from './consumer.js';

package/dist/utilities/queues/producer.js

@@ -0,0 +1,74 @@
+/**
+ * Queue Producer
+ * Send messages to Cloudflare Queues
+ * 
+ * @example
+ * import { QueueProducer } from '@tamyla/clodo-framework/utilities/queues';
+ * 
+ * const producer = new QueueProducer(env.MY_QUEUE);
+ * await producer.send({ type: 'email', to: 'user@example.com' });
+ * await producer.sendBatch([msg1, msg2, msg3]);
+ */
+
+export class QueueProducer {
+  /**
+   * @param {Queue} queue - Queue binding
+   */
+  constructor(queue) {
+    if (!queue) {
+      throw new Error('Queue binding is required');
+    }
+    this.queue = queue;
+  }
+
+  /**
+   * Send a single message to the queue
+   * @param {*} body - Message body (will be JSON serialized)
+   * @param {Object} options - Send options
+   * @param {number} options.delaySeconds - Delay before processing (max 12 hours)
+   * @returns {Promise<void>}
+   */
+  async send(body, options = {}) {
+    const message = {
+      body,
+      ...(options.delaySeconds && {
+        delaySeconds: options.delaySeconds
+      })
+    };
+    await this.queue.send(message);
+  }
+
+  /**
+   * Send multiple messages in a batch
+   * @param {Array<*>} bodies - Array of message bodies
+   * @param {Object} options - Batch options
+   * @returns {Promise<void>}
+   */
+  async sendBatch(bodies, options = {}) {
+    const messages = bodies.map(body => ({
+      body,
+      ...(options.delaySeconds && {
+        delaySeconds: options.delaySeconds
+      })
+    }));
+    await this.queue.sendBatch(messages);
+  }
+
+  /**
+   * Send a message with automatic retry info
+   * @param {*} body - Message body
+   * @param {Object} options - Options including retry tracking
+   */
+  async sendWithRetry(body, options = {}) {
+    const enhancedBody = {
+      ...body,
+      _meta: {
+        attempt: (body._meta?.attempt || 0) + 1,
+        firstAttemptAt: body._meta?.firstAttemptAt || Date.now(),
+        lastAttemptAt: Date.now()
+      }
+    };
+    await this.send(enhancedBody, options);
+  }
+}
+export default QueueProducer;