@tamyla/clodo-framework 4.3.4 → 4.4.0

package/dist/utilities/scheduled/handler.js

@@ -0,0 +1,276 @@
+/**
+ * Scheduled/Cron Job Utilities
+ * Helpers for Cloudflare Workers Cron Triggers
+ * 
+ * @example
+ * import { ScheduledHandler, CronJob } from '@tamyla/clodo-framework/utilities/scheduled';
+ * 
+ * const handler = new ScheduledHandler()
+ *   .register('0 * * * *', new CleanupJob())
+ *   .register('0 0 * * *', new DailyReportJob())
+ *   .register('* /5 * * * *', async (event, env) => {
+ *     // Run every 5 minutes
+ *   });
+ * 
+ * export default {
+ *   scheduled: (event, env, ctx) => handler.handle(event, env, ctx)
+ * }
+ */
+
+/**
+ * Base class for cron jobs
+ */
+export class CronJob {
+  /**
+   * Execute the job
+   * @param {ScheduledEvent} event - Scheduled event
+   * @param {Object} env - Environment bindings
+   * @param {ExecutionContext} ctx - Execution context
+   */
+  async execute(event, env, ctx) {
+    throw new Error('execute() must be implemented');
+  }
+
+  /**
+   * Check if job should run
+   * @param {ScheduledEvent} event
+   * @returns {boolean}
+   */
+  shouldRun(event) {
+    return true;
+  }
+
+  /**
+   * Called before execution
+   */
+  async beforeExecute(event, env) {}
+
+  /**
+   * Called after successful execution
+   */
+  async afterExecute(event, env, result) {}
+
+  /**
+   * Called on error
+   */
+  async onError(event, env, error) {
+    console.error(`Job error: ${error.message}`);
+    throw error;
+  }
+}
+
+/**
+ * Scheduled event handler with job registration
+ */
+export class ScheduledHandler {
+  constructor() {
+    this.jobs = new Map();
+    this.defaultJob = null;
+    this.middleware = [];
+  }
+
+  /**
+   * Register a job for a cron pattern
+   * @param {string} cron - Cron pattern (e.g., '0 * * * *')
+   * @param {CronJob|Function} job - Job instance or function
+   */
+  register(cron, job) {
+    if (typeof job === 'function') {
+      // Wrap function in CronJob
+      const fn = job;
+      job = new class extends CronJob {
+        async execute(event, env, ctx) {
+          return fn(event, env, ctx);
+        }
+      }();
+    }
+    this.jobs.set(cron, job);
+    return this;
+  }
+
+  /**
+   * Set default job for unmatched cron patterns
+   */
+  setDefault(job) {
+    if (typeof job === 'function') {
+      const fn = job;
+      job = new class extends CronJob {
+        async execute(event, env, ctx) {
+          return fn(event, env, ctx);
+        }
+      }();
+    }
+    this.defaultJob = job;
+    return this;
+  }
+
+  /**
+   * Add middleware
+   * @param {Function} fn - Middleware function (event, env, next) => Promise
+   */
+  use(fn) {
+    this.middleware.push(fn);
+    return this;
+  }
+
+  /**
+   * Handle scheduled event
+   * @param {ScheduledEvent} event
+   * @param {Object} env
+   * @param {ExecutionContext} ctx
+   */
+  async handle(event, env, ctx) {
+    const job = this.jobs.get(event.cron) || this.defaultJob;
+    if (!job) {
+      console.warn(`No job registered for cron: ${event.cron}`);
+      return;
+    }
+    if (!job.shouldRun(event)) {
+      console.log(`Job skipped for cron: ${event.cron}`);
+      return;
+    }
+
+    // Run middleware chain
+    const runWithMiddleware = async () => {
+      let index = 0;
+      const next = async () => {
+        if (index < this.middleware.length) {
+          const middleware = this.middleware[index++];
+          return middleware(event, env, next);
+        }
+        return this._executeJob(job, event, env, ctx);
+      };
+      return next();
+    };
+    return runWithMiddleware();
+  }
+  async _executeJob(job, event, env, ctx) {
+    try {
+      await job.beforeExecute(event, env);
+      const result = await job.execute(event, env, ctx);
+      await job.afterExecute(event, env, result);
+      return result;
+    } catch (error) {
+      return job.onError(event, env, error);
+    }
+  }
+}
+
+/**
+ * Job scheduler for dynamic job management
+ */
+export class JobScheduler {
+  constructor(kvNamespace) {
+    this.kv = kvNamespace;
+    this.prefix = 'jobs:';
+  }
+
+  /**
+   * Schedule a job for future execution
+   * @param {string} jobId - Unique job ID
+   * @param {Object} jobData - Job data
+   * @param {Date|number} runAt - When to run (Date or timestamp)
+   */
+  async schedule(jobId, jobData, runAt) {
+    const timestamp = runAt instanceof Date ? runAt.getTime() : runAt;
+    await this.kv.put(`${this.prefix}${timestamp}:${jobId}`, JSON.stringify({
+      id: jobId,
+      data: jobData,
+      scheduledAt: Date.now(),
+      runAt: timestamp
+    }), {
+      expirationTtl: Math.ceil((timestamp - Date.now()) / 1000) + 86400
+    });
+  }
+
+  /**
+   * Get jobs ready to run
+   * @returns {Promise<Array>}
+   */
+  async getReadyJobs() {
+    const now = Date.now();
+    const jobs = [];
+    const {
+      keys
+    } = await this.kv.list({
+      prefix: this.prefix
+    });
+    for (const key of keys) {
+      const [, timestampAndId] = key.name.split(this.prefix);
+      const [timestamp] = timestampAndId.split(':');
+      if (parseInt(timestamp) <= now) {
+        const jobData = await this.kv.get(key.name, {
+          type: 'json'
+        });
+        if (jobData) {
+          jobs.push(jobData);
+        }
+      }
+    }
+    return jobs;
+  }
+
+  /**
+   * Mark job as completed
+   */
+  async complete(jobId, timestamp) {
+    await this.kv.delete(`${this.prefix}${timestamp}:${jobId}`);
+  }
+
+  /**
+   * Reschedule a job
+   */
+  async reschedule(jobId, currentTimestamp, newRunAt) {
+    const key = `${this.prefix}${currentTimestamp}:${jobId}`;
+    const jobData = await this.kv.get(key, {
+      type: 'json'
+    });
+    if (jobData) {
+      await this.kv.delete(key);
+      await this.schedule(jobId, jobData.data, newRunAt);
+    }
+  }
+}
+
+/**
+ * Registry for tracking scheduled jobs
+ */
+export class ScheduledJobRegistry {
+  constructor() {
+    this.jobs = new Map();
+  }
+
+  /**
+   * Define a named job
+   */
+  define(name, JobClass) {
+    this.jobs.set(name, JobClass);
+    return this;
+  }
+
+  /**
+   * Get a job class by name
+   */
+  get(name) {
+    return this.jobs.get(name);
+  }
+
+  /**
+   * Create a job instance
+   */
+  create(name, ...args) {
+    const JobClass = this.get(name);
+    if (!JobClass) {
+      throw new Error(`Unknown job: ${name}`);
+    }
+    return new JobClass(...args);
+  }
+
+  /**
+   * List all registered jobs
+   */
+  list() {
+    return Array.from(this.jobs.keys());
+  }
+}
+export default ScheduledHandler;

package/dist/utilities/scheduled/index.js

@@ -0,0 +1,6 @@
+/**
+ * Scheduled/Cron Utilities
+ * @module @tamyla/clodo-framework/utilities/scheduled
+ */
+
+export { ScheduledHandler, CronJob, JobScheduler, ScheduledJobRegistry } from './handler.js';

package/dist/utilities/storage/index.js

@@ -0,0 +1,6 @@
+/**
+ * Storage Utilities
+ * @module @tamyla/clodo-framework/utilities/storage
+ */
+
+export { R2Storage, handleFileUpload, serveFile } from './r2.js';

package/dist/utilities/storage/r2.js

@@ -0,0 +1,314 @@
+/**
+ * R2 Storage Utilities
+ * Provides convenient methods for working with Cloudflare R2 buckets
+ * 
+ * @example
+ * import { R2Storage } from '@tamyla/clodo-framework/utilities/storage';
+ * 
+ * export default {
+ *   async fetch(request, env) {
+ *     const storage = new R2Storage(env.BUCKET);
+ *     
+ *     // Upload a file
+ *     await storage.upload('images/photo.jpg', imageData, {
+ *       contentType: 'image/jpeg',
+ *       metadata: { uploadedBy: 'user-123' }
+ *     });
+ *     
+ *     // Get a file
+ *     const file = await storage.get('images/photo.jpg');
+ *     
+ *     // List files
+ *     const files = await storage.list('images/', { limit: 100 });
+ *   }
+ * }
+ */
+
+/**
+ * R2 Storage wrapper class
+ */
+export class R2Storage {
+  /**
+   * @param {R2Bucket} bucket - The R2 bucket binding
+   */
+  constructor(bucket) {
+    if (!bucket) {
+      throw new Error('R2 bucket binding is required');
+    }
+    this.bucket = bucket;
+  }
+
+  /**
+   * Upload a file to R2
+   * @param {string} key - Object key (path)
+   * @param {ReadableStream|ArrayBuffer|string|Blob} data - File data
+   * @param {Object} options - Upload options
+   * @param {string} options.contentType - MIME type
+   * @param {Object} options.metadata - Custom metadata
+   * @param {string} options.cacheControl - Cache-Control header
+   * @returns {Promise<R2Object>}
+   */
+  async upload(key, data, options = {}) {
+    const httpMetadata = {};
+    if (options.contentType) {
+      httpMetadata.contentType = options.contentType;
+    }
+    if (options.cacheControl) {
+      httpMetadata.cacheControl = options.cacheControl;
+    }
+    if (options.contentDisposition) {
+      httpMetadata.contentDisposition = options.contentDisposition;
+    }
+    if (options.contentEncoding) {
+      httpMetadata.contentEncoding = options.contentEncoding;
+    }
+    if (options.contentLanguage) {
+      httpMetadata.contentLanguage = options.contentLanguage;
+    }
+    return this.bucket.put(key, data, {
+      httpMetadata,
+      customMetadata: options.metadata || {}
+    });
+  }
+
+  /**
+   * Get a file from R2
+   * @param {string} key - Object key
+   * @returns {Promise<R2ObjectBody|null>}
+   */
+  async get(key) {
+    return this.bucket.get(key);
+  }
+
+  /**
+   * Get only object metadata (head)
+   * @param {string} key - Object key
+   * @returns {Promise<R2Object|null>}
+   */
+  async head(key) {
+    return this.bucket.head(key);
+  }
+
+  /**
+   * Delete a file from R2
+   * @param {string} key - Object key
+   * @returns {Promise<void>}
+   */
+  async delete(key) {
+    return this.bucket.delete(key);
+  }
+
+  /**
+   * Delete multiple files
+   * @param {string[]} keys - Array of object keys
+   * @returns {Promise<void>}
+   */
+  async deleteMany(keys) {
+    return this.bucket.delete(keys);
+  }
+
+  /**
+   * List objects in the bucket
+   * @param {string} prefix - Key prefix to filter by
+   * @param {Object} options - List options
+   * @param {number} options.limit - Maximum number of results
+   * @param {string} options.cursor - Pagination cursor
+   * @param {string} options.delimiter - Delimiter for hierarchy
+   * @returns {Promise<R2Objects>}
+   */
+  async list(prefix = '', options = {}) {
+    return this.bucket.list({
+      prefix,
+      limit: options.limit || 1000,
+      cursor: options.cursor,
+      delimiter: options.delimiter,
+      include: options.include || ['httpMetadata', 'customMetadata']
+    });
+  }
+
+  /**
+   * List all objects (handles pagination automatically)
+   * @param {string} prefix - Key prefix to filter by
+   * @returns {AsyncGenerator<R2Object>}
+   */
+  async *listAll(prefix = '') {
+    let cursor;
+    do {
+      const result = await this.list(prefix, {
+        cursor
+      });
+      for (const object of result.objects) {
+        yield object;
+      }
+      cursor = result.truncated ? result.cursor : null;
+    } while (cursor);
+  }
+
+  /**
+   * Check if an object exists
+   * @param {string} key - Object key
+   * @returns {Promise<boolean>}
+   */
+  async exists(key) {
+    const head = await this.head(key);
+    return head !== null;
+  }
+
+  /**
+   * Copy an object within the bucket
+   * @param {string} sourceKey - Source object key
+   * @param {string} destKey - Destination object key
+   * @returns {Promise<R2Object>}
+   */
+  async copy(sourceKey, destKey) {
+    const source = await this.get(sourceKey);
+    if (!source) {
+      throw new Error(`Source object not found: ${sourceKey}`);
+    }
+    return this.upload(destKey, source.body, {
+      contentType: source.httpMetadata?.contentType,
+      metadata: source.customMetadata
+    });
+  }
+
+  /**
+   * Move an object within the bucket
+   * @param {string} sourceKey - Source object key
+   * @param {string} destKey - Destination object key
+   * @returns {Promise<R2Object>}
+   */
+  async move(sourceKey, destKey) {
+    const result = await this.copy(sourceKey, destKey);
+    await this.delete(sourceKey);
+    return result;
+  }
+
+  /**
+   * Get a signed URL info for temporary access
+   * Note: R2 doesn't have built-in signed URLs, this returns info for custom implementation
+   * @param {string} key - Object key
+   * @param {Object} options - Signing options
+   * @returns {Object} URL info object
+   */
+  createSignedUrlInfo(key, options = {}) {
+    const expiresIn = options.expiresIn || 3600;
+    const expiresAt = Date.now() + expiresIn * 1000;
+    return {
+      key,
+      bucket: this.bucket,
+      expiresAt,
+      expiresIn,
+      // Implement custom signing logic in your application
+      // This is a placeholder for the signing parameters
+      signatureParams: {
+        key,
+        expires: expiresAt,
+        ...options
+      }
+    };
+  }
+}
+
+/**
+ * Handle file upload from multipart form data
+ * @param {Request} request - Incoming request
+ * @param {R2Storage} storage - R2Storage instance
+ * @param {Object} options - Upload options
+ * @returns {Promise<Object>} Upload result
+ */
+export async function handleFileUpload(request, storage, options = {}) {
+  const {
+    fieldName = 'file',
+    keyPrefix = '',
+    maxSize = 10 * 1024 * 1024,
+    // 10MB default
+    allowedTypes = null,
+    generateKey = null
+  } = options;
+  const formData = await request.formData();
+  const file = formData.get(fieldName);
+  if (!file || !(file instanceof File)) {
+    throw new Error('No file provided');
+  }
+
+  // Check file size
+  if (file.size > maxSize) {
+    throw new Error(`File too large. Maximum size is ${maxSize} bytes`);
+  }
+
+  // Check content type
+  if (allowedTypes && !allowedTypes.includes(file.type)) {
+    throw new Error(`File type not allowed: ${file.type}`);
+  }
+
+  // Generate key
+  const key = generateKey ? generateKey(file) : `${keyPrefix}${Date.now()}-${file.name}`;
+
+  // Upload
+  const result = await storage.upload(key, file, {
+    contentType: file.type,
+    metadata: {
+      originalName: file.name,
+      uploadedAt: new Date().toISOString()
+    }
+  });
+  return {
+    key,
+    size: file.size,
+    type: file.type,
+    name: file.name,
+    etag: result.etag
+  };
+}
+
+/**
+ * Serve a file from R2 with proper headers
+ * @param {R2Storage} storage - R2Storage instance
+ * @param {string} key - Object key
+ * @param {Request} request - Original request (for range headers)
+ * @returns {Promise<Response>}
+ */
+export async function serveFile(storage, key, request) {
+  const object = await storage.get(key);
+  if (!object) {
+    return new Response('Not Found', {
+      status: 404
+    });
+  }
+  const headers = new Headers();
+
+  // Set content type
+  if (object.httpMetadata?.contentType) {
+    headers.set('Content-Type', object.httpMetadata.contentType);
+  }
+
+  // Set cache control
+  if (object.httpMetadata?.cacheControl) {
+    headers.set('Cache-Control', object.httpMetadata.cacheControl);
+  } else {
+    headers.set('Cache-Control', 'public, max-age=31536000');
+  }
+
+  // Set ETag
+  headers.set('ETag', object.etag);
+
+  // Set content length
+  headers.set('Content-Length', object.size.toString());
+
+  // Handle range requests
+  const range = request.headers.get('Range');
+  if (range) {
+    const [start, end] = range.replace('bytes=', '').split('-').map(Number);
+    const actualEnd = end || object.size - 1;
+    headers.set('Content-Range', `bytes ${start}-${actualEnd}/${object.size}`);
+    headers.set('Content-Length', (actualEnd - start + 1).toString());
+    return new Response(object.body, {
+      status: 206,
+      headers
+    });
+  }
+  return new Response(object.body, {
+    headers
+  });
+}
+export default R2Storage;

package/dist/utilities/vectorize/index.js

@@ -0,0 +1,6 @@
+/**
+ * Vectorize Utilities
+ * @module @tamyla/clodo-framework/utilities/vectorize
+ */
+
+export { VectorStore, VectorSearch, EmbeddingHelper } from './store.js';