@donkeylabs/server 0.2.6 → 0.2.9

package/examples/starter/node_modules/@donkeylabs/server/src/core/cache.ts

@@ -0,0 +1,183 @@
+// Core Cache Service
+// Key-value store with TTL, in-memory by default
+
+export interface CacheAdapter {
+  get<T>(key: string): Promise<T | null>;
+  set<T>(key: string, value: T, ttlMs?: number): Promise<void>;
+  delete(key: string): Promise<boolean>;
+  has(key: string): Promise<boolean>;
+  clear(): Promise<void>;
+  keys(pattern?: string): Promise<string[]>;
+}
+
+export interface CacheConfig {
+  adapter?: CacheAdapter;
+  defaultTtlMs?: number; // Default: 5 minutes
+  maxSize?: number; // Default: 1000 items (LRU eviction)
+}
+
+export interface Cache {
+  get<T>(key: string): Promise<T | null>;
+  set<T>(key: string, value: T, ttlMs?: number): Promise<void>;
+  delete(key: string): Promise<boolean>;
+  has(key: string): Promise<boolean>;
+  clear(): Promise<void>;
+  keys(pattern?: string): Promise<string[]>;
+  getOrSet<T>(key: string, factory: () => Promise<T>, ttlMs?: number): Promise<T>;
+}
+
+interface CacheEntry<T> {
+  value: T;
+  expiresAt: number | null;
+}
+
+// In-memory cache adapter with LRU eviction
+export class MemoryCacheAdapter implements CacheAdapter {
+  private cache = new Map<string, CacheEntry<any>>();
+  private accessOrder: string[] = [];
+  private maxSize: number;
+
+  constructor(maxSize: number = 1000) {
+    this.maxSize = maxSize;
+  }
+
+  private isExpired(entry: CacheEntry<any>): boolean {
+    return entry.expiresAt !== null && Date.now() > entry.expiresAt;
+  }
+
+  private updateAccessOrder(key: string): void {
+    const index = this.accessOrder.indexOf(key);
+    if (index > -1) {
+      this.accessOrder.splice(index, 1);
+    }
+    this.accessOrder.push(key);
+  }
+
+  private evictIfNeeded(): void {
+    while (this.cache.size >= this.maxSize && this.accessOrder.length > 0) {
+      const oldest = this.accessOrder.shift();
+      if (oldest) {
+        this.cache.delete(oldest);
+      }
+    }
+  }
+
+  async get<T>(key: string): Promise<T | null> {
+    const entry = this.cache.get(key);
+    if (!entry) return null;
+
+    if (this.isExpired(entry)) {
+      this.cache.delete(key);
+      const index = this.accessOrder.indexOf(key);
+      if (index > -1) this.accessOrder.splice(index, 1);
+      return null;
+    }
+
+    this.updateAccessOrder(key);
+    return entry.value as T;
+  }
+
+  async set<T>(key: string, value: T, ttlMs?: number): Promise<void> {
+    this.evictIfNeeded();
+
+    const entry: CacheEntry<T> = {
+      value,
+      expiresAt: ttlMs ? Date.now() + ttlMs : null,
+    };
+
+    this.cache.set(key, entry);
+    this.updateAccessOrder(key);
+  }
+
+  async delete(key: string): Promise<boolean> {
+    const existed = this.cache.has(key);
+    this.cache.delete(key);
+    const index = this.accessOrder.indexOf(key);
+    if (index > -1) this.accessOrder.splice(index, 1);
+    return existed;
+  }
+
+  async has(key: string): Promise<boolean> {
+    const entry = this.cache.get(key);
+    if (!entry) return false;
+
+    if (this.isExpired(entry)) {
+      this.cache.delete(key);
+      return false;
+    }
+
+    return true;
+  }
+
+  async clear(): Promise<void> {
+    this.cache.clear();
+    this.accessOrder = [];
+  }
+
+  async keys(pattern?: string): Promise<string[]> {
+    const allKeys: string[] = [];
+
+    for (const [key, entry] of this.cache.entries()) {
+      if (!this.isExpired(entry)) {
+        if (!pattern || this.matchPattern(key, pattern)) {
+          allKeys.push(key);
+        }
+      }
+    }
+
+    return allKeys;
+  }
+
+  private matchPattern(key: string, pattern: string): boolean {
+    // Simple glob pattern matching (* as wildcard)
+    const regex = new RegExp("^" + pattern.replace(/\*/g, ".*") + "$");
+    return regex.test(key);
+  }
+}
+
+class CacheImpl implements Cache {
+  private adapter: CacheAdapter;
+  private defaultTtlMs: number;
+
+  constructor(config: CacheConfig = {}) {
+    this.adapter = config.adapter ?? new MemoryCacheAdapter(config.maxSize);
+    this.defaultTtlMs = config.defaultTtlMs ?? 5 * 60 * 1000; // 5 minutes
+  }
+
+  async get<T>(key: string): Promise<T | null> {
+    return this.adapter.get<T>(key);
+  }
+
+  async set<T>(key: string, value: T, ttlMs?: number): Promise<void> {
+    return this.adapter.set(key, value, ttlMs ?? this.defaultTtlMs);
+  }
+
+  async delete(key: string): Promise<boolean> {
+    return this.adapter.delete(key);
+  }
+
+  async has(key: string): Promise<boolean> {
+    return this.adapter.has(key);
+  }
+
+  async clear(): Promise<void> {
+    return this.adapter.clear();
+  }
+
+  async keys(pattern?: string): Promise<string[]> {
+    return this.adapter.keys(pattern);
+  }
+
+  async getOrSet<T>(key: string, factory: () => Promise<T>, ttlMs?: number): Promise<T> {
+    const existing = await this.get<T>(key);
+    if (existing !== null) return existing;
+
+    const value = await factory();
+    await this.set(key, value, ttlMs);
+    return value;
+  }
+}
+
+export function createCache(config?: CacheConfig): Cache {
+  return new CacheImpl(config);
+}

package/examples/starter/node_modules/@donkeylabs/server/src/core/cron.ts

@@ -0,0 +1,255 @@
+// Core Cron Service
+// Schedule recurring tasks with cron expressions
+
+export interface CronTask {
+  id: string;
+  name: string;
+  expression: string;
+  handler: () => void | Promise<void>;
+  enabled: boolean;
+  lastRun?: Date;
+  nextRun?: Date;
+}
+
+export interface CronConfig {
+  timezone?: string; // For future use
+}
+
+export interface Cron {
+  schedule(
+    expression: string,
+    handler: () => void | Promise<void>,
+    options?: { name?: string; enabled?: boolean }
+  ): string;
+  unschedule(taskId: string): boolean;
+  pause(taskId: string): void;
+  resume(taskId: string): void;
+  list(): CronTask[];
+  get(taskId: string): CronTask | undefined;
+  trigger(taskId: string): Promise<void>;
+  start(): void;
+  stop(): Promise<void>;
+}
+
+// Simple cron expression parser
+// Supports: * (any), specific values, ranges (1-5), steps (*/5)
+// Format: second minute hour dayOfMonth month dayOfWeek
+// Also supports 5-field format (minute hour dayOfMonth month dayOfWeek)
+class CronExpression {
+  private fields: [number[], number[], number[], number[], number[], number[]];
+
+  constructor(expression: string) {
+    const parts = expression.trim().split(/\s+/);
+
+    // Support both 5-field and 6-field cron
+    if (parts.length === 5) {
+      // minute hour dayOfMonth month dayOfWeek
+      this.fields = [
+        [0], // seconds (always 0)
+        this.parseField(parts[0]!, 0, 59),  // minutes
+        this.parseField(parts[1]!, 0, 23),  // hours
+        this.parseField(parts[2]!, 1, 31),  // day of month
+        this.parseField(parts[3]!, 1, 12),  // month
+        this.parseField(parts[4]!, 0, 6),   // day of week
+      ];
+    } else if (parts.length === 6) {
+      // second minute hour dayOfMonth month dayOfWeek
+      this.fields = [
+        this.parseField(parts[0]!, 0, 59),  // seconds
+        this.parseField(parts[1]!, 0, 59),  // minutes
+        this.parseField(parts[2]!, 0, 23),  // hours
+        this.parseField(parts[3]!, 1, 31),  // day of month
+        this.parseField(parts[4]!, 1, 12),  // month
+        this.parseField(parts[5]!, 0, 6),   // day of week
+      ];
+    } else {
+      throw new Error(`Invalid cron expression: ${expression}`);
+    }
+  }
+
+  private parseField(field: string, min: number, max: number): number[] {
+    const values: Set<number> = new Set();
+
+    for (const part of field.split(",")) {
+      if (part === "*") {
+        for (let i = min; i <= max; i++) values.add(i);
+      } else if (part.includes("/")) {
+        const [range, stepStr] = part.split("/");
+        const step = parseInt(stepStr!, 10);
+        const start = range === "*" ? min : parseInt(range!, 10);
+        for (let i = start; i <= max; i += step) values.add(i);
+      } else if (part.includes("-")) {
+        const [startStr, endStr] = part.split("-");
+        const start = parseInt(startStr!, 10);
+        const end = parseInt(endStr!, 10);
+        for (let i = start; i <= end; i++) values.add(i);
+      } else {
+        values.add(parseInt(part, 10));
+      }
+    }
+
+    return Array.from(values).sort((a, b) => a - b);
+  }
+
+  matches(date: Date): boolean {
+    const second = date.getSeconds();
+    const minute = date.getMinutes();
+    const hour = date.getHours();
+    const dayOfMonth = date.getDate();
+    const month = date.getMonth() + 1;
+    const dayOfWeek = date.getDay();
+
+    return (
+      this.fields[0].includes(second) &&
+      this.fields[1].includes(minute) &&
+      this.fields[2].includes(hour) &&
+      this.fields[3].includes(dayOfMonth) &&
+      this.fields[4].includes(month) &&
+      this.fields[5].includes(dayOfWeek)
+    );
+  }
+
+  getNextRun(from: Date = new Date()): Date {
+    const next = new Date(from);
+    next.setMilliseconds(0);
+    next.setSeconds(next.getSeconds() + 1);
+
+    // Search up to 1 year ahead
+    const maxIterations = 366 * 24 * 60 * 60;
+    for (let i = 0; i < maxIterations; i++) {
+      if (this.matches(next)) {
+        return next;
+      }
+      next.setSeconds(next.getSeconds() + 1);
+    }
+
+    throw new Error("Could not find next run time within 1 year");
+  }
+}
+
+interface InternalCronTask extends CronTask {
+  _cronExpr: CronExpression;
+}
+
+class CronImpl implements Cron {
+  private tasks = new Map<string, InternalCronTask>();
+  private running = false;
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private taskCounter = 0;
+
+  constructor(_config: CronConfig = {}) {
+    // timezone handling for future use
+  }
+
+  schedule(
+    expression: string,
+    handler: () => void | Promise<void>,
+    options: { name?: string; enabled?: boolean } = {}
+  ): string {
+    const id = `cron_${++this.taskCounter}_${Date.now()}`;
+    const cronExpr = new CronExpression(expression);
+
+    const task: InternalCronTask = {
+      id,
+      name: options.name ?? id,
+      expression,
+      handler,
+      enabled: options.enabled ?? true,
+      nextRun: cronExpr.getNextRun(),
+      _cronExpr: cronExpr,
+    };
+
+    this.tasks.set(id, task);
+
+    return id;
+  }
+
+  unschedule(taskId: string): boolean {
+    return this.tasks.delete(taskId);
+  }
+
+  pause(taskId: string): void {
+    const task = this.tasks.get(taskId);
+    if (task) task.enabled = false;
+  }
+
+  resume(taskId: string): void {
+    const task = this.tasks.get(taskId);
+    if (task) {
+      task.enabled = true;
+      const cronExpr = new CronExpression(task.expression);
+      task.nextRun = cronExpr.getNextRun();
+    }
+  }
+
+  list(): CronTask[] {
+    return Array.from(this.tasks.values()).map(t => ({
+      id: t.id,
+      name: t.name,
+      expression: t.expression,
+      handler: t.handler,
+      enabled: t.enabled,
+      lastRun: t.lastRun,
+      nextRun: t.nextRun,
+    }));
+  }
+
+  get(taskId: string): CronTask | undefined {
+    const task = this.tasks.get(taskId);
+    if (!task) return undefined;
+    return {
+      id: task.id,
+      name: task.name,
+      expression: task.expression,
+      handler: task.handler,
+      enabled: task.enabled,
+      lastRun: task.lastRun,
+      nextRun: task.nextRun,
+    };
+  }
+
+  async trigger(taskId: string): Promise<void> {
+    const task = this.tasks.get(taskId);
+    if (!task) throw new Error(`Task ${taskId} not found`);
+
+    task.lastRun = new Date();
+    await task.handler();
+  }
+
+  start(): void {
+    if (this.running) return;
+    this.running = true;
+
+    // Check every second
+    this.timer = setInterval(() => {
+      const now = new Date();
+
+      for (const task of this.tasks.values()) {
+        if (!task.enabled) continue;
+
+        const cronExpr = new CronExpression(task.expression);
+        if (cronExpr.matches(now)) {
+          task.lastRun = now;
+          task.nextRun = cronExpr.getNextRun(now);
+
+          // Execute handler (fire and forget, but log errors)
+          Promise.resolve(task.handler()).catch(err => {
+            console.error(`[Cron] Task "${task.name}" failed:`, err);
+          });
+        }
+      }
+    }, 1000);
+  }
+
+  async stop(): Promise<void> {
+    this.running = false;
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+}
+
+export function createCron(config?: CronConfig): Cron {
+  return new CronImpl(config);
+}