@orkify/cli 1.0.0-beta.5 → 1.0.0-beta.6

package/packages/cache/src/CachePrimary.ts

@@ -1,172 +0,0 @@
-import type { Worker } from 'node:cluster';
-import type { CacheConfig, CacheWorkerMessage, ICacheStore } from './types.js';
-import { CacheFileStore } from './CacheFileStore.js';
-import { CachePersistence } from './CachePersistence.js';
-import { CacheStore } from './CacheStore.js';
-
-interface WorkerState {
-  worker: Worker;
-}
-
-export class CachePrimary {
-  private fileBacked: boolean;
-  private persistence: CachePersistence;
-  private processName: string;
-  private store: ICacheStore;
-
-  constructor(processName: string, config?: CacheConfig) {
-    this.processName = processName;
-    this.fileBacked = config?.fileBacked === true;
-    this.store = this.fileBacked ? new CacheFileStore(processName, config) : new CacheStore(config);
-    this.persistence = new CachePersistence(processName);
-  }
-
-  handleMessage(
-    _worker: Worker,
-    msg: CacheWorkerMessage,
-    allWorkers: Map<number, WorkerState>
-  ): void {
-    switch (msg.type) {
-      case 'cache:set': {
-        const expiresAt = msg.ttl ? Date.now() + msg.ttl * 1000 : undefined;
-        this.store.set(msg.key, msg.value, expiresAt, msg.tags);
-        // Broadcast to ALL workers (including sender) for consistency
-        for (const [, state] of allWorkers) {
-          if (state.worker.isConnected()) {
-            state.worker.send({
-              __orkify: true,
-              type: 'cache:set',
-              key: msg.key,
-              value: msg.value,
-              expiresAt,
-              tags: msg.tags,
-            });
-          }
-        }
-        break;
-      }
-      case 'cache:delete': {
-        this.store.delete(msg.key);
-        for (const [, state] of allWorkers) {
-          if (state.worker.isConnected()) {
-            state.worker.send({
-              __orkify: true,
-              type: 'cache:delete',
-              key: msg.key,
-            });
-          }
-        }
-        break;
-      }
-      case 'cache:clear': {
-        this.store.clear();
-        for (const [, state] of allWorkers) {
-          if (state.worker.isConnected()) {
-            state.worker.send({ __orkify: true, type: 'cache:clear' });
-          }
-        }
-        break;
-      }
-      case 'cache:invalidate-tag': {
-        this.store.invalidateTag(msg.tag);
-        const tagTimestamp = this.store.getTagExpiration([msg.tag]);
-        for (const [, state] of allWorkers) {
-          if (state.worker.isConnected()) {
-            state.worker.send({
-              __orkify: true,
-              type: 'cache:invalidate-tag',
-              tag: msg.tag,
-              tagTimestamp,
-            });
-          }
-        }
-        break;
-      }
-      case 'cache:update-tag-timestamp': {
-        this.store.applyTagTimestamp(msg.tag, msg.tagTimestamp);
-        for (const [, state] of allWorkers) {
-          if (state.worker.isConnected()) {
-            state.worker.send({
-              __orkify: true,
-              type: 'cache:update-tag-timestamp',
-              tag: msg.tag,
-              tagTimestamp: msg.tagTimestamp,
-            });
-          }
-        }
-        break;
-      }
-      case 'cache:configure': {
-        this.applyConfig(msg.config);
-        break;
-      }
-    }
-  }
-
-  /**
-   * Upgrade from CacheStore to CacheFileStore when a worker reports fileBacked config.
-   * Migrates existing in-memory entries and loads the disk index from any previous session.
-   */
-  private applyConfig(config: CacheConfig): void {
-    if (!config.fileBacked || this.fileBacked) return;
-
-    const snapshot = this.store.serialize();
-    const newStore = new CacheFileStore(this.processName, config);
-    this.store.destroy();
-    this.store = newStore;
-
-    // Migrate existing in-memory entries (from CachePersistence restore or earlier sets)
-    for (const [key, entry] of snapshot.entries) {
-      this.store.set(key, entry.value, entry.expiresAt, entry.tags);
-    }
-    for (const [tag, ts] of snapshot.tagTimestamps) {
-      this.store.applyTagTimestamp(tag, ts);
-    }
-    this.fileBacked = true;
-
-    // Load disk index from previous file-backed sessions (async, entries promoted lazily)
-    void (this.store as CacheFileStore).loadIndex();
-  }
-
-  sendSnapshot(worker: Worker): void {
-    const snapshot = this.store.serialize();
-    if (snapshot.entries.length === 0 && snapshot.tagTimestamps.length === 0) return;
-    worker.send({
-      __orkify: true,
-      type: 'cache:snapshot',
-      entries: snapshot.entries,
-      tagTimestamps: snapshot.tagTimestamps,
-    });
-  }
-
-  async persist(): Promise<void> {
-    if (this.fileBacked) {
-      await (this.store as CacheFileStore).flush();
-      // Clear CachePersistence so stale snapshot data isn't loaded on next restart
-      await this.persistence.clear();
-    } else {
-      const snapshot = this.store.serialize();
-      await this.persistence.save(snapshot);
-    }
-  }
-
-  async restore(): Promise<void> {
-    if (this.fileBacked) {
-      await (this.store as CacheFileStore).loadIndex();
-    } else {
-      const snapshot = await this.persistence.load();
-      if (snapshot.entries.length > 0 || snapshot.tagTimestamps.length > 0) {
-        this.store.applySnapshot(snapshot);
-      }
-    }
-  }
-
-  destroy(): void {
-    this.store.destroy();
-  }
-
-  async shutdown(): Promise<void> {
-    await this.persist();
-    this.store.destroy();
-  }
-}

package/packages/cache/src/CacheStore.ts

@@ -1,308 +0,0 @@
-import type {
-  CacheConfig,
-  CacheEntry,
-  CacheSnapshot,
-  CacheStats,
-  EvictReason,
-  ICacheStore,
-  SerializedCacheEntry,
-} from './types.js';
-import {
-  CACHE_CLEANUP_INTERVAL,
-  CACHE_DEFAULT_MAX_ENTRIES,
-  CACHE_DEFAULT_MAX_MEMORY_SIZE,
-} from './constants.js';
-import { serialize, serializedByteLength } from './serialize.js';
-
-export type OnEvictCallback = (key: string, entry: CacheEntry, reason: EvictReason) => void;
-
-export class CacheStore implements ICacheStore {
-  private entries = new Map<string, CacheEntry>();
-  private hits = 0;
-  private maxEntries: number;
-  private maxMemorySize: number;
-  private misses = 0;
-  private onEvict: OnEvictCallback | undefined;
-  private sweepTimer: ReturnType<typeof setInterval> | undefined;
-  private tagIndex = new Map<string, Set<string>>(); // tag → keys
-  private tagTimestamps = new Map<string, number>(); // tag → epoch ms of last invalidation
-  totalBytes = 0;
-
-  constructor(config?: CacheConfig, onEvict?: OnEvictCallback) {
-    this.maxEntries = config?.maxEntries ?? CACHE_DEFAULT_MAX_ENTRIES;
-    this.maxMemorySize = config?.maxMemorySize ?? CACHE_DEFAULT_MAX_MEMORY_SIZE;
-    this.onEvict = onEvict;
-
-    this.sweepTimer = setInterval(() => this.sweep(), CACHE_CLEANUP_INTERVAL);
-    this.sweepTimer.unref();
-  }
-
-  get<T>(key: string): T | undefined {
-    const entry = this.entries.get(key);
-    if (!entry) {
-      this.misses++;
-      return undefined;
-    }
-    if (entry.expiresAt !== undefined && entry.expiresAt < Date.now()) {
-      this.removeEntry(key, entry);
-      this.misses++;
-      return undefined;
-    }
-    entry.lastAccessedAt = Date.now();
-    this.hits++;
-    return entry.value as T;
-  }
-
-  set(
-    key: string,
-    value: unknown,
-    expiresAt?: number,
-    tags?: string[],
-    precomputedByteSize?: number
-  ): void {
-    const byteSize = precomputedByteSize ?? serializedByteLength(serialize(value));
-    const existing = this.entries.get(key);
-    if (existing) {
-      // Remove old tag associations and byte count before overwriting
-      this.removeFromTagIndex(key, existing.tags);
-      this.totalBytes -= existing.byteSize;
-    }
-
-    // Evict until we're under both limits (entry count for new keys, byte limit always)
-    while (this.overLimit(existing ? 0 : 1, byteSize)) {
-      if (!this.evictLru()) break; // nothing left to evict
-    }
-
-    this.entries.set(key, {
-      byteSize,
-      value,
-      expiresAt,
-      lastAccessedAt: Date.now(),
-      tags,
-    });
-    this.totalBytes += byteSize;
-    if (tags) {
-      this.addToTagIndex(key, tags);
-    }
-  }
-
-  delete(key: string): boolean {
-    const entry = this.entries.get(key);
-    if (!entry) return false;
-    this.removeFromTagIndex(key, entry.tags);
-    this.totalBytes -= entry.byteSize;
-    this.entries.delete(key);
-    return true;
-  }
-
-  clear(): void {
-    this.entries.clear();
-    this.tagIndex.clear();
-    this.tagTimestamps.clear();
-    this.totalBytes = 0;
-  }
-
-  has(key: string): boolean {
-    const entry = this.entries.get(key);
-    if (!entry) return false;
-    if (entry.expiresAt !== undefined && entry.expiresAt < Date.now()) {
-      this.removeEntry(key, entry);
-      return false;
-    }
-    return true;
-  }
-
-  stats(): CacheStats {
-    const total = this.hits + this.misses;
-    return {
-      size: this.entries.size,
-      hits: this.hits,
-      misses: this.misses,
-      hitRate: total === 0 ? 0 : this.hits / total,
-      totalBytes: this.totalBytes,
-    };
-  }
-
-  /** Invalidate all entries with the given tag. Returns deleted keys. */
-  invalidateTag(tag: string): string[] {
-    this.tagTimestamps.set(tag, Date.now());
-
-    const keys = this.tagIndex.get(tag);
-    if (!keys || keys.size === 0) return [];
-
-    const deleted: string[] = [];
-    for (const key of keys) {
-      const entry = this.entries.get(key);
-      if (entry) {
-        // Remove this key from all its other tag sets
-        this.removeFromTagIndex(key, entry.tags, tag);
-        this.totalBytes -= entry.byteSize;
-        this.entries.delete(key);
-        deleted.push(key);
-      }
-    }
-    // Remove the tag itself from the index
-    this.tagIndex.delete(tag);
-    return deleted;
-  }
-
-  /** Returns the most recent invalidation timestamp across the given tags (0 if none). */
-  getTagExpiration(tags: string[]): number {
-    let max = 0;
-    for (const tag of tags) {
-      const ts = this.tagTimestamps.get(tag);
-      if (ts !== undefined && ts > max) {
-        max = ts;
-      }
-    }
-    return max;
-  }
-
-  /** Set a tag invalidation timestamp without deleting entries (for IPC replay). */
-  applyTagTimestamp(tag: string, timestamp: number): void {
-    this.tagTimestamps.set(tag, timestamp);
-  }
-
-  async getAsync<T>(key: string): Promise<T | undefined> {
-    return this.get<T>(key);
-  }
-
-  /** Apply a set from IPC — no broadcast triggered */
-  applySet(key: string, value: unknown, expiresAt?: number, tags?: string[]): void {
-    this.set(key, value, expiresAt, tags);
-  }
-
-  /** Apply a delete from IPC — no broadcast triggered */
-  applyDelete(key: string): void {
-    this.delete(key);
-  }
-
-  /** Apply a full snapshot from primary — replaces all entries and tag timestamps */
-  applySnapshot(snapshot: CacheSnapshot): void {
-    this.entries.clear();
-    this.tagIndex.clear();
-    this.tagTimestamps.clear();
-    this.totalBytes = 0;
-    const now = Date.now();
-    for (const [key, serialized] of snapshot.entries) {
-      // Skip expired entries
-      if (serialized.expiresAt !== undefined && serialized.expiresAt < now) continue;
-      const tags = serialized.tags;
-      const byteSize = serializedByteLength(serialize(serialized.value));
-      this.entries.set(key, {
-        byteSize,
-        value: serialized.value,
-        expiresAt: serialized.expiresAt,
-        lastAccessedAt: now,
-        tags,
-      });
-      this.totalBytes += byteSize;
-      if (tags) {
-        this.addToTagIndex(key, tags);
-      }
-    }
-    for (const [tag, ts] of snapshot.tagTimestamps) {
-      this.tagTimestamps.set(tag, ts);
-    }
-  }
-
-  /** Export for snapshots and persistence */
-  serialize(): CacheSnapshot {
-    const now = Date.now();
-    const entries: Array<[string, SerializedCacheEntry]> = [];
-    for (const [key, entry] of this.entries) {
-      // Skip expired entries
-      if (entry.expiresAt !== undefined && entry.expiresAt < now) continue;
-      const serialized: SerializedCacheEntry = { value: entry.value, expiresAt: entry.expiresAt };
-      if (entry.tags && entry.tags.length > 0) {
-        serialized.tags = entry.tags;
-      }
-      entries.push([key, serialized]);
-    }
-    return { entries, tagTimestamps: [...this.tagTimestamps] };
-  }
-
-  destroy(): void {
-    if (this.sweepTimer) {
-      clearInterval(this.sweepTimer);
-      this.sweepTimer = undefined;
-    }
-    this.entries.clear();
-    this.tagIndex.clear();
-    this.tagTimestamps.clear();
-    this.totalBytes = 0;
-  }
-
-  /** Remove all expired entries */
-  private sweep(): void {
-    const now = Date.now();
-    for (const [key, entry] of this.entries) {
-      if (entry.expiresAt !== undefined && entry.expiresAt < now) {
-        this.onEvict?.(key, entry, 'expired');
-        this.removeEntry(key, entry);
-      }
-    }
-  }
-
-  /** Check if adding pendingEntries + pendingBytes would exceed limits */
-  private overLimit(pendingEntries: number, pendingBytes: number): boolean {
-    if (this.entries.size + pendingEntries > this.maxEntries) return true;
-    if (this.totalBytes + pendingBytes > this.maxMemorySize) return true;
-    return false;
-  }
-
-  /** Evict the entry with the oldest lastAccessedAt. Returns false if nothing to evict. */
-  private evictLru(): boolean {
-    let oldestKey: string | undefined;
-    let oldestTime = Infinity;
-    for (const [key, entry] of this.entries) {
-      if (entry.lastAccessedAt < oldestTime) {
-        oldestTime = entry.lastAccessedAt;
-        oldestKey = key;
-      }
-    }
-    if (oldestKey === undefined) return false;
-    const entry = this.entries.get(oldestKey);
-    if (entry) {
-      this.onEvict?.(oldestKey, entry, 'lru');
-      this.removeFromTagIndex(oldestKey, entry.tags);
-      this.totalBytes -= entry.byteSize;
-    }
-    this.entries.delete(oldestKey);
-    return true;
-  }
-
-  /** Remove a key from the entries map and clean up its tag index entries */
-  private removeEntry(key: string, entry: CacheEntry): void {
-    this.removeFromTagIndex(key, entry.tags);
-    this.totalBytes -= entry.byteSize;
-    this.entries.delete(key);
-  }
-
-  /** Add a key to the tag index for each of its tags */
-  private addToTagIndex(key: string, tags: string[]): void {
-    for (const tag of tags) {
-      let keys = this.tagIndex.get(tag);
-      if (!keys) {
-        keys = new Set();
-        this.tagIndex.set(tag, keys);
-      }
-      keys.add(key);
-    }
-  }
-
-  /** Remove a key from the tag index. Optionally skip a specific tag (already being deleted). */
-  private removeFromTagIndex(key: string, tags?: string[], skipTag?: string): void {
-    if (!tags) return;
-    for (const tag of tags) {
-      if (tag === skipTag) continue;
-      const keys = this.tagIndex.get(tag);
-      if (keys) {
-        keys.delete(key);
-        if (keys.size === 0) {
-          this.tagIndex.delete(tag);
-        }
-      }
-    }
-  }
-}

package/packages/cache/src/constants.ts

@@ -1,10 +0,0 @@
-import { homedir } from 'node:os';
-import { join } from 'node:path';
-
-const ORKIFY_HOME = join(homedir(), '.orkify');
-
-export const CACHE_DIR = join(ORKIFY_HOME, 'cache');
-export const CACHE_DEFAULT_MAX_ENTRIES = 10_000;
-export const CACHE_DEFAULT_MAX_MEMORY_SIZE = 64 * 1024 * 1024; // 64 MB
-export const CACHE_DEFAULT_MAX_VALUE_SIZE = 1024 * 1024; // 1 MB
-export const CACHE_CLEANUP_INTERVAL = 60_000; // 60s

package/packages/cache/src/index.ts

@@ -1,100 +0,0 @@
-import type { CacheConfig } from './types.js';
-import { CacheClient } from './CacheClient.js';
-
-let instance: CacheClient | undefined;
-let pendingConfig: CacheConfig | undefined;
-
-// In cluster mode, IPC cache messages (including snapshots) can arrive before
-// this module loads.  The metrics probe registers a global buffer on
-// `globalThis.__orkifyCacheBuffer` synchronously before any `await`, so those
-// early messages are captured even when this module loads late.
-//
-// Messages that arrive *after* this module loads but *before* the proxy is first
-// accessed are captured by the local early listener below.  Both sources are
-// merged and drained when the CacheClient is created.
-const g = globalThis as Record<string, unknown>;
-const probeBuffer: unknown[] = Array.isArray(g.__orkifyCacheBuffer)
-  ? (g.__orkifyCacheBuffer as unknown[])
-  : [];
-
-const localBuffer: unknown[] = [];
-let earlyListener: ((msg: unknown) => void) | undefined;
-
-if (process.env.ORKIFY_CLUSTER_MODE === 'true' && typeof process.send === 'function') {
-  earlyListener = (msg: unknown) => {
-    const m = msg as { __orkify?: boolean; type?: string };
-    if (m?.__orkify && m.type?.startsWith('cache:')) {
-      localBuffer.push(msg);
-    }
-  };
-  process.on('message', earlyListener);
-}
-
-function createInstance(): void {
-  // Stop the local early listener — CacheClient registers its own
-  if (earlyListener) {
-    process.removeListener('message', earlyListener);
-    earlyListener = undefined;
-  }
-
-  // Stop the probe's global buffer listener
-  if (typeof g.__orkifyCacheBufferCleanup === 'function') {
-    (g.__orkifyCacheBufferCleanup as () => void)();
-    delete g.__orkifyCacheBufferCleanup;
-    delete g.__orkifyCacheBuffer;
-  }
-
-  // Merge probe buffer + local buffer — probe messages arrived first
-  const merged = [...probeBuffer, ...localBuffer];
-  probeBuffer.length = 0;
-  localBuffer.length = 0;
-
-  // Default to fileBacked: true unless explicitly disabled
-  const config: CacheConfig | undefined =
-    pendingConfig?.fileBacked === false ? pendingConfig : { fileBacked: true, ...pendingConfig };
-
-  instance = new CacheClient(config, merged);
-  const client = instance;
-  (g as Record<string, unknown>).__orkifyCacheStats = () => client.stats();
-}
-
-/**
- * @deprecated Use `cache.configure()` instead. Will be removed in a future version.
- */
-export function configure(config: CacheConfig): void {
-  if (instance) {
-    throw new Error('orkify/cache: configure() must be called before the first use of cache');
-  }
-  pendingConfig = config;
-}
-
-/**
- * Shared cache singleton. Reads are always synchronous local Map lookups.
- * In cluster mode, writes broadcast via IPC so all workers converge.
- * In standalone/fork mode, behaves as a local in-memory cache.
- *
- * Call `cache.configure()` before any other method to set options.
- */
-export const cache: CacheClient = new Proxy({} as CacheClient, {
-  get(_target, prop, receiver) {
-    // configure() must run before the instance is created
-    if (prop === 'configure') {
-      return (config: CacheConfig) => {
-        if (instance) {
-          throw new Error('orkify/cache: configure() must be called before the first use of cache');
-        }
-        pendingConfig = config;
-      };
-    }
-
-    if (!instance) createInstance();
-    const inst = instance as CacheClient;
-    const value = Reflect.get(inst, prop, receiver);
-    if (typeof value === 'function') {
-      return value.bind(inst);
-    }
-    return value;
-  },
-});
-
-export type { CacheConfig, CacheSetOptions, CacheStats } from './types.js';

package/packages/cache/src/serialize.ts

@@ -1,49 +0,0 @@
-import v8 from 'node:v8';
-
-export type Encoding = 'json' | 'v8';
-
-export interface Serialized {
-  data: string;
-  encoding: Encoding;
-}
-
-function needsV8(value: unknown): boolean {
-  if (
-    value instanceof Map ||
-    value instanceof Set ||
-    value instanceof Date ||
-    value instanceof RegExp ||
-    value instanceof Error
-  )
-    return true;
-  if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer) return true;
-  if (Array.isArray(value)) return value.some(needsV8);
-  if (value !== null && typeof value === 'object') {
-    return Object.values(value).some(needsV8);
-  }
-  return false;
-}
-
-export function serialize(value: unknown): Serialized {
-  if (typeof value === 'function') {
-    throw new Error('cache: functions are not serializable');
-  }
-  if (typeof value === 'symbol') {
-    throw new Error('cache: symbols are not serializable');
-  }
-  if (needsV8(value)) {
-    return { data: v8.serialize(value).toString('base64'), encoding: 'v8' };
-  }
-  return { data: JSON.stringify(value), encoding: 'json' };
-}
-
-export function deserialize({ data, encoding }: Serialized): unknown {
-  if (encoding === 'v8') return v8.deserialize(Buffer.from(data, 'base64'));
-  return JSON.parse(data);
-}
-
-export function serializedByteLength(s: Serialized): number {
-  return s.encoding === 'v8'
-    ? Math.ceil((s.data.length * 3) / 4) // base64 → raw bytes
-    : Buffer.byteLength(s.data, 'utf-8');
-}