@a0n/aeon 5.0.1

package/dist/persistence/index.js

@@ -0,0 +1,204 @@
+// src/persistence/DashStorageAdapter.ts
+var DEFAULT_RULE = {
+  urgency: "deferred",
+  debounce: 50,
+  maxBufferSize: 5e3,
+  readThrough: true
+};
+var DashStorageAdapter = class {
+  backend;
+  syncClient;
+  rules;
+  hooks;
+  pendingChanges = /* @__PURE__ */ new Map();
+  syncTimer = null;
+  syncInFlight = false;
+  syncPending = false;
+  constructor(backend, options = {}) {
+    this.backend = backend;
+    this.syncClient = options.syncClient ?? null;
+    this.hooks = options.hooks ?? {};
+    const defaultRule = {
+      ...DEFAULT_RULE,
+      ...options.rules?.default ?? {}
+    };
+    if (options.syncDebounceMs !== void 0)
+      defaultRule.debounce = options.syncDebounceMs;
+    if (options.maxPendingChanges !== void 0)
+      defaultRule.maxBufferSize = options.maxPendingChanges;
+    if (options.onSyncError && !this.hooks.onSyncError)
+      this.hooks.onSyncError = options.onSyncError;
+    this.rules = {
+      default: defaultRule,
+      prefixes: options.rules?.prefixes ?? {}
+    };
+  }
+  /**
+   * Get an item, checking the write pool (pending changes) first for consistency.
+   */
+  async getItem(key) {
+    const rule = this.getRuleForKey(key);
+    if (rule.readThrough !== false) {
+      const pending = this.pendingChanges.get(key);
+      if (pending) {
+        return pending.operation === "delete" ? null : pending.value ?? null;
+      }
+    }
+    return await this.backend.get(key);
+  }
+  async setItem(key, value) {
+    await this.backend.set(key, value);
+    this.trackChange({
+      key,
+      operation: "set",
+      value,
+      timestamp: Date.now()
+    });
+  }
+  async removeItem(key) {
+    await this.backend.delete(key);
+    this.trackChange({
+      key,
+      operation: "delete",
+      timestamp: Date.now()
+    });
+  }
+  getPendingSyncCount() {
+    return this.pendingChanges.size;
+  }
+  async flushSync() {
+    if (!this.syncClient || this.pendingChanges.size === 0) {
+      return;
+    }
+    if (this.syncTimer) {
+      clearTimeout(this.syncTimer);
+      this.syncTimer = null;
+    }
+    await this.performSync();
+  }
+  trackChange(change) {
+    this.pendingChanges.set(change.key, change);
+    const rule = this.getRuleForKey(change.key);
+    if (rule.urgency === "realtime") {
+      void this.performSync();
+      return;
+    }
+    const maxSize = rule.maxBufferSize ?? 5e3;
+    if (this.pendingChanges.size >= maxSize) {
+      this.hooks.onBufferOverflow?.(
+        this.getPrefixMatch(change.key) || "default",
+        this.pendingChanges.size,
+        maxSize
+      );
+      void this.performSync();
+      return;
+    }
+    this.scheduleSync(rule);
+  }
+  getRuleForKey(key) {
+    const prefix = this.getPrefixMatch(key);
+    return (prefix ? this.rules.prefixes?.[prefix] : this.rules.default) ?? this.rules.default;
+  }
+  getPrefixMatch(key) {
+    if (!this.rules.prefixes) {
+      return null;
+    }
+    const prefixes = Object.keys(this.rules.prefixes).sort(
+      (a, b) => b.length - a.length
+    );
+    return prefixes.find((p) => key.startsWith(p)) ?? null;
+  }
+  scheduleSync(rule) {
+    if (!this.syncClient || this.syncTimer) {
+      return;
+    }
+    const debounceMs = typeof rule.debounce === "string" ? this.parseInterval(rule.debounce) : rule.debounce ?? 50;
+    this.syncTimer = setTimeout(() => {
+      this.syncTimer = null;
+      void this.performSync();
+    }, debounceMs);
+  }
+  async performSync() {
+    if (!this.syncClient) {
+      return;
+    }
+    if (this.syncInFlight) {
+      this.syncPending = true;
+      return;
+    }
+    const changes = Array.from(this.pendingChanges.values()).sort(
+      (a, b) => a.timestamp - b.timestamp
+    );
+    if (changes.length === 0) {
+      return;
+    }
+    this.pendingChanges.clear();
+    this.syncInFlight = true;
+    try {
+      await this.syncClient.syncChanges(changes);
+      this.hooks.onSync?.(changes);
+      this.hooks.onFlush?.(changes.length);
+    } catch (error) {
+      for (const change of changes) {
+        const current = this.pendingChanges.get(change.key);
+        if (!current || change.timestamp > current.timestamp) {
+          this.pendingChanges.set(change.key, change);
+        }
+      }
+      if (this.hooks.onSyncError) {
+        const normalizedError = error instanceof Error ? error : new Error(String(error));
+        this.hooks.onSyncError(normalizedError, changes);
+      }
+    } finally {
+      this.syncInFlight = false;
+      const rerun = this.syncPending || this.pendingChanges.size > 0;
+      this.syncPending = false;
+      if (rerun) {
+        this.scheduleSync(this.rules.default);
+      }
+    }
+  }
+  parseInterval(input) {
+    const match = input.match(/^(\d+)(ms|s|m|h|d)$/);
+    if (!match) return 50;
+    const value = parseInt(match[1], 10);
+    const unit = match[2];
+    switch (unit) {
+      case "ms":
+        return value;
+      case "s":
+        return value * 1e3;
+      case "m":
+        return value * 60 * 1e3;
+      case "h":
+        return value * 60 * 60 * 1e3;
+      case "d":
+        return value * 24 * 60 * 60 * 1e3;
+      default:
+        return 50;
+    }
+  }
+};
+
+// src/persistence/InMemoryStorageAdapter.ts
+var InMemoryStorageAdapter = class {
+  store = /* @__PURE__ */ new Map();
+  getItem(key) {
+    return this.store.get(key) ?? null;
+  }
+  setItem(key, value) {
+    this.store.set(key, value);
+  }
+  removeItem(key) {
+    this.store.delete(key);
+  }
+  async flushSync() {
+  }
+  clear() {
+    this.store.clear();
+  }
+};
+
+export { DashStorageAdapter, InMemoryStorageAdapter };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/persistence/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/persistence/DashStorageAdapter.ts","../../src/persistence/InMemoryStorageAdapter.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import type { StorageAdapter } from './types';\n\nexport interface DashStorageBackend {\n  get(key: string): Promise<string | null> | string | null;\n  set(key: string, value: string): Promise<void> | void;\n  delete(key: string): Promise<void> | void;\n}\n\nexport interface DashStorageChange {\n  key: string;\n  operation: 'set' | 'delete';\n  value?: string;\n  timestamp: number;\n}\n\nexport interface DashSyncClient {\n  syncChanges(changes: DashStorageChange[]): Promise<void>;\n}\n\nexport type DashSyncUrgency = 'realtime' | 'deferred' | 'lazy';\n\nexport interface DashSyncRule {\n  /** How quickly to sync changes for keys matching this rule/prefix */\n  urgency: DashSyncUrgency;\n  /** Debounce/Interval for deferred/lazy sync (e.g. '1s', '1m', '1h') */\n  debounce?: string | number;\n  /** Maximum number of pending changes before forcing a sync */\n  maxBufferSize?: number;\n  /** Whether to return pending values from memory (default: true) */\n  readThrough?: boolean;\n}\n\nexport interface DashSyncRules {\n  default?: DashSyncRule;\n  /** Key prefix mapping to sync rules */\n  prefixes?: Record<string, DashSyncRule>;\n}\n\nexport interface DashStorageAdapterHooks {\n  onSync?: (changes: DashStorageChange[]) => void;\n  onSyncError?: (error: Error, changes: DashStorageChange[]) => void;\n  onBufferOverflow?: (prefix: string, size: number, max: number) => void;\n  onFlush?: (count: number) => void;\n}\n\nexport interface DashStorageAdapterOptions {\n  syncClient?: DashSyncClient;\n  rules?: DashSyncRules;\n  hooks?: DashStorageAdapterHooks;\n  /** @deprecated Use rules.default.debounce */\n  syncDebounceMs?: number;\n  /** @deprecated Use rules.default.maxBufferSize */\n  maxPendingChanges?: number;\n  /** @deprecated Use hooks.onSyncError */\n  onSyncError?: (error: Error, changes: DashStorageChange[]) => void;\n}\n\nconst DEFAULT_RULE: DashSyncRule = {\n  urgency: 'deferred',\n  debounce: 50,\n  maxBufferSize: 5000,\n  readThrough: true,\n};\n\n/**\n * Storage adapter boundary for dash-backed persistence.\n *\n * Provides a \"Write Pool\" layer that buffers local-first writes and flushes\n * them to D1/R2 via a sync client based on declarative rules.\n */\nexport class DashStorageAdapter implements StorageAdapter {\n  private readonly backend: DashStorageBackend;\n  private readonly syncClient: DashSyncClient | null;\n  private readonly rules: DashSyncRules;\n  private readonly hooks: DashStorageAdapterHooks;\n  private readonly pendingChanges = new Map<string, DashStorageChange>();\n  private syncTimer: ReturnType<typeof setTimeout> | null = null;\n  private syncInFlight = false;\n  private syncPending = false;\n\n  constructor(\n    backend: DashStorageBackend,\n    options: DashStorageAdapterOptions = {}\n  ) {\n    this.backend = backend;\n    this.syncClient = options.syncClient ?? null;\n    this.hooks = options.hooks ?? {};\n\n    // Migration/Fallback for deprecated options\n    const defaultRule: DashSyncRule = {\n      ...DEFAULT_RULE,\n      ...(options.rules?.default ?? {}),\n    };\n    if (options.syncDebounceMs !== undefined)\n      defaultRule.debounce = options.syncDebounceMs;\n    if (options.maxPendingChanges !== undefined)\n      defaultRule.maxBufferSize = options.maxPendingChanges;\n    if (options.onSyncError && !this.hooks.onSyncError)\n      this.hooks.onSyncError = options.onSyncError;\n\n    this.rules = {\n      default: defaultRule,\n      prefixes: options.rules?.prefixes ?? {},\n    };\n  }\n\n  /**\n   * Get an item, checking the write pool (pending changes) first for consistency.\n   */\n  async getItem(key: string): Promise<string | null> {\n    const rule = this.getRuleForKey(key);\n\n    // Read-through: check memory first if enabled\n    if (rule.readThrough !== false) {\n      const pending = this.pendingChanges.get(key);\n      if (pending) {\n        return pending.operation === 'delete' ? null : pending.value ?? null;\n      }\n    }\n\n    return await this.backend.get(key);\n  }\n\n  async setItem(key: string, value: string): Promise<void> {\n    await this.backend.set(key, value);\n    this.trackChange({\n      key,\n      operation: 'set',\n      value,\n      timestamp: Date.now(),\n    });\n  }\n\n  async removeItem(key: string): Promise<void> {\n    await this.backend.delete(key);\n    this.trackChange({\n      key,\n      operation: 'delete',\n      timestamp: Date.now(),\n    });\n  }\n\n  getPendingSyncCount(): number {\n    return this.pendingChanges.size;\n  }\n\n  async flushSync(): Promise<void> {\n    if (!this.syncClient || this.pendingChanges.size === 0) {\n      return;\n    }\n    if (this.syncTimer) {\n      clearTimeout(this.syncTimer);\n      this.syncTimer = null;\n    }\n    await this.performSync();\n  }\n\n  private trackChange(change: DashStorageChange): void {\n    this.pendingChanges.set(change.key, change);\n\n    const rule = this.getRuleForKey(change.key);\n\n    // Immediate flush for realtime\n    if (rule.urgency === 'realtime') {\n      void this.performSync();\n      return;\n    }\n\n    // Check for buffer overflow\n    const maxSize = rule.maxBufferSize ?? 5000;\n    if (this.pendingChanges.size >= maxSize) {\n      this.hooks.onBufferOverflow?.(\n        this.getPrefixMatch(change.key) || 'default',\n        this.pendingChanges.size,\n        maxSize\n      );\n      void this.performSync();\n      return;\n    }\n\n    this.scheduleSync(rule);\n  }\n\n  private getRuleForKey(key: string): DashSyncRule {\n    const prefix = this.getPrefixMatch(key);\n    return (\n      (prefix ? this.rules.prefixes?.[prefix] : this.rules.default) ??\n      this.rules.default!\n    );\n  }\n\n  private getPrefixMatch(key: string): string | null {\n    if (!this.rules.prefixes) {\n      return null;\n    }\n    // Match longest prefix first\n    const prefixes = Object.keys(this.rules.prefixes).sort(\n      (a, b) => b.length - a.length\n    );\n    return prefixes.find((p) => key.startsWith(p)) ?? null;\n  }\n\n  private scheduleSync(rule: DashSyncRule): void {\n    if (!this.syncClient || this.syncTimer) {\n      return;\n    }\n\n    const debounceMs =\n      typeof rule.debounce === 'string'\n        ? this.parseInterval(rule.debounce)\n        : rule.debounce ?? 50;\n\n    this.syncTimer = setTimeout(() => {\n      this.syncTimer = null;\n      void this.performSync();\n    }, debounceMs);\n  }\n\n  private async performSync(): Promise<void> {\n    if (!this.syncClient) {\n      return;\n    }\n\n    if (this.syncInFlight) {\n      this.syncPending = true;\n      return;\n    }\n\n    const changes = Array.from(this.pendingChanges.values()).sort(\n      (a, b) => a.timestamp - b.timestamp\n    );\n    if (changes.length === 0) {\n      return;\n    }\n\n    this.pendingChanges.clear();\n    this.syncInFlight = true;\n    try {\n      await this.syncClient.syncChanges(changes);\n      this.hooks.onSync?.(changes);\n      this.hooks.onFlush?.(changes.length);\n    } catch (error) {\n      // Re-queue changes if they haven't been overwritten by newer local writes\n      for (const change of changes) {\n        const current = this.pendingChanges.get(change.key);\n        if (!current || change.timestamp > current.timestamp) {\n          this.pendingChanges.set(change.key, change);\n        }\n      }\n\n      if (this.hooks.onSyncError) {\n        const normalizedError =\n          error instanceof Error ? error : new Error(String(error));\n        this.hooks.onSyncError(normalizedError, changes);\n      }\n    } finally {\n      this.syncInFlight = false;\n      const rerun = this.syncPending || this.pendingChanges.size > 0;\n      this.syncPending = false;\n      if (rerun) {\n        // Use default rule for re-run or wait for next trackChange\n        this.scheduleSync(this.rules.default!);\n      }\n    }\n  }\n\n  private parseInterval(input: string): number {\n    const match = input.match(/^(\\d+)(ms|s|m|h|d)$/);\n    if (!match) return 50;\n    const value = parseInt(match[1], 10);\n    const unit = match[2];\n    switch (unit) {\n      case 'ms':\n        return value;\n      case 's':\n        return value * 1000;\n      case 'm':\n        return value * 60 * 1000;\n      case 'h':\n        return value * 60 * 60 * 1000;\n      case 'd':\n        return value * 24 * 60 * 60 * 1000;\n      default:\n        return 50;\n    }\n  }\n}\n","import type { StorageAdapter } from './types';\n\n/**\n * In-memory adapter for tests and ephemeral runtimes.\n */\nexport class InMemoryStorageAdapter implements StorageAdapter {\n  private readonly store = new Map<string, string>();\n\n  getItem(key: string): string | null {\n    return this.store.get(key) ?? null;\n  }\n\n  setItem(key: string, value: string): void {\n    this.store.set(key, value);\n  }\n\n  removeItem(key: string): void {\n    this.store.delete(key);\n  }\n\n  async flushSync(): Promise<void> {\n    /* noop */\n  }\n\n  clear(): void {\n    this.store.clear();\n  }\n}\n"]}