nvent 0.4.4 → 0.5.0

package/dist/runtime/adapters/builtin/file-store.js

@@ -0,0 +1,206 @@
+import { promises as fs } from "node:fs";
+import { join, dirname } from "node:path";
+import { MemoryStoreAdapter } from "./memory-store.js";
+function sanitize(name) {
+  return name.replace(/[^\w.-]/g, "_");
+}
+async function ensureDir(path) {
+  try {
+    await fs.mkdir(path, { recursive: true });
+  } catch {
+  }
+}
+export class FileStoreAdapter extends MemoryStoreAdapter {
+  options;
+  constructor(options) {
+    super();
+    this.options = options;
+    const parentKv = this.kv;
+    const parentStream = this.stream;
+    const parentIndex = this.index;
+    this.kv = {
+      get: parentKv.get,
+      set: async (key, value, ttl) => {
+        await parentKv.set(key, value, ttl);
+        const path = this.kvPath(key);
+        await ensureDir(dirname(path));
+        await fs.writeFile(path, JSON.stringify(value), "utf-8");
+      },
+      delete: async (key) => {
+        await parentKv.delete(key);
+        const path = this.kvPath(key);
+        try {
+          await fs.unlink(path);
+        } catch {
+        }
+      },
+      clear: async (pattern) => {
+        const count = await parentKv.clear(pattern);
+        try {
+          const kvDir = join(this.options.dataDir, "kv");
+          const files = await fs.readdir(kvDir);
+          const regex = new RegExp(`^${pattern.replace(/\*/g, ".*")}$`);
+          for (const file of files) {
+            if (!file.endsWith(".json")) continue;
+            const key = file.replace(".json", "").replace(/_/g, ":");
+            if (regex.test(key)) {
+              await fs.unlink(join(kvDir, file));
+            }
+          }
+        } catch {
+        }
+        return count;
+      },
+      increment: async (key, by = 1) => {
+        const result = await parentKv.increment(key, by);
+        const path = this.kvPath(key);
+        await ensureDir(dirname(path));
+        await fs.writeFile(path, JSON.stringify(result), "utf-8");
+        return result;
+      }
+    };
+    this.stream = {
+      append: async (subject, event) => {
+        const result = await parentStream.append(subject, event);
+        const path = this.streamPath(subject);
+        await ensureDir(dirname(path));
+        await fs.appendFile(path, JSON.stringify(result) + "\n", "utf-8");
+        return result;
+      },
+      read: parentStream.read,
+      subscribe: parentStream.subscribe,
+      delete: async (subject) => {
+        const deleted = parentStream.delete ? await parentStream.delete(subject) : false;
+        if (deleted) {
+          const path = this.streamPath(subject);
+          try {
+            await fs.unlink(path);
+          } catch {
+          }
+        }
+        return deleted;
+      }
+    };
+    this.index = {
+      add: async (key, id, score, metadata) => {
+        await parentIndex.add(key, id, score, metadata);
+        const self = this;
+        const index = self.sortedIndices?.get(key);
+        if (index) {
+          const path = this.indexPath(key);
+          await ensureDir(dirname(path));
+          await fs.writeFile(path, JSON.stringify(index, null, 2), "utf-8");
+        }
+      },
+      get: parentIndex.get,
+      read: parentIndex.read,
+      update: async (key, id, metadata) => {
+        const result = await parentIndex.update(key, id, metadata);
+        const self = this;
+        const index = self.sortedIndices?.get(key);
+        if (index) {
+          const path = this.indexPath(key);
+          await ensureDir(dirname(path));
+          await fs.writeFile(path, JSON.stringify(index, null, 2), "utf-8");
+        }
+        return result;
+      },
+      updateWithRetry: async (key, id, metadata, maxRetries) => {
+        await parentIndex.updateWithRetry(key, id, metadata, maxRetries);
+        const self = this;
+        const index = self.sortedIndices?.get(key);
+        if (index) {
+          const path = this.indexPath(key);
+          await ensureDir(dirname(path));
+          await fs.writeFile(path, JSON.stringify(index, null, 2), "utf-8");
+        }
+      },
+      increment: async (key, id, field, increment) => {
+        const result = await parentIndex.increment(key, id, field, increment);
+        const self = this;
+        const index = self.sortedIndices?.get(key);
+        if (index) {
+          const path = this.indexPath(key);
+          await ensureDir(dirname(path));
+          await fs.writeFile(path, JSON.stringify(index, null, 2), "utf-8");
+        }
+        return result;
+      },
+      delete: async (key, id) => {
+        const deleted = await parentIndex.delete(key, id);
+        if (deleted) {
+          const self = this;
+          const index = self.sortedIndices?.get(key);
+          if (index) {
+            const path = this.indexPath(key);
+            await ensureDir(dirname(path));
+            await fs.writeFile(path, JSON.stringify(index, null, 2), "utf-8");
+          }
+        }
+        return deleted;
+      }
+    };
+  }
+  streamPath(subject) {
+    return join(this.options.dataDir, "streams", sanitize(subject) + ".ndjson");
+  }
+  indexPath(key) {
+    return join(this.options.dataDir, "indices", sanitize(key) + ".json");
+  }
+  kvPath(key) {
+    return join(this.options.dataDir, "kv", `${sanitize(key)}.json`);
+  }
+  async init() {
+    await ensureDir(this.options.dataDir);
+    await ensureDir(join(this.options.dataDir, "streams"));
+    await ensureDir(join(this.options.dataDir, "indices"));
+    await ensureDir(join(this.options.dataDir, "kv"));
+    await this.loadFromDisk();
+  }
+  async loadFromDisk() {
+    const self = this;
+    try {
+      const streamsDir = join(this.options.dataDir, "streams");
+      const files = await fs.readdir(streamsDir);
+      for (const file of files) {
+        if (!file.endsWith(".ndjson")) continue;
+        const subject = file.replace(".ndjson", "").replace(/_/g, ":");
+        const content = await fs.readFile(join(streamsDir, file), "utf-8");
+        const lines = content.trim().split("\n").filter((l) => l.length > 0);
+        const events = lines.map((line) => JSON.parse(line));
+        if (!self.eventStreams) self.eventStreams = /* @__PURE__ */ new Map();
+        self.eventStreams.set(subject, events);
+      }
+    } catch {
+    }
+    try {
+      const indicesDir = join(this.options.dataDir, "indices");
+      const indexFiles = await fs.readdir(indicesDir);
+      for (const file of indexFiles) {
+        if (!file.endsWith(".json")) continue;
+        const key = file.replace(".json", "").replace(/_/g, ":");
+        const content = await fs.readFile(join(indicesDir, file), "utf-8");
+        const entries = JSON.parse(content);
+        if (!self.sortedIndices) self.sortedIndices = /* @__PURE__ */ new Map();
+        self.sortedIndices.set(key, entries);
+      }
+    } catch {
+    }
+    try {
+      const kvDir = join(this.options.dataDir, "kv");
+      const kvFiles = await fs.readdir(kvDir);
+      for (const file of kvFiles) {
+        if (!file.endsWith(".json")) continue;
+        const key = file.replace(".json", "").replace(/_/g, ":");
+        const content = await fs.readFile(join(kvDir, file), "utf-8");
+        const value = JSON.parse(content);
+        if (!self.kvStore) self.kvStore = /* @__PURE__ */ new Map();
+        self.kvStore.set(key, value);
+      }
+    } catch {
+    }
+  }
+  async close() {
+    await super.close();
+  }
+}

package/dist/runtime/adapters/builtin/file-stream.d.ts

@@ -0,0 +1,39 @@
+/**
+ * File Stream Adapter
+ *
+ * DEPRECATED: This adapter is identical to MemoryStreamAdapter
+ *
+ * For file-based deployments (single instance):
+ * - StreamAdapter is NOT needed for cross-instance pub/sub
+ * - StoreAdapter.subscribe() handles in-process subscriptions
+ * - StoreAdapter handles ALL persistence (events, documents, KV)
+ *
+ * This adapter exists only for API compatibility.
+ * Use MemoryStreamAdapter instead - it's the same implementation.
+ */
+import type { StreamAdapter, StreamEvent, SubscribeOptions, SubscriptionHandle } from '../interfaces/stream.js';
+/**
+ * @deprecated Use MemoryStreamAdapter instead. FileStreamAdapter is identical.
+ */
+export interface FileStreamAdapterOptions {
+    dataDir?: string;
+}
+/**
+ * @deprecated Use MemoryStreamAdapter instead
+ *
+ * Pure in-memory pub/sub (same as MemoryStreamAdapter)
+ * - No persistence (StoreAdapter handles that)
+ * - Single instance only
+ * - Events lost if no subscribers
+ */
+export declare class FileStreamAdapter implements StreamAdapter {
+    private subscriptions;
+    private subscriptionCounter;
+    init(): Promise<void>;
+    publish(topic: string, event: StreamEvent): Promise<void>;
+    subscribe(topic: string, handler: (event: StreamEvent) => void | Promise<void>, _opts?: SubscribeOptions): Promise<SubscriptionHandle>;
+    unsubscribe(handle: SubscriptionHandle): Promise<void>;
+    listTopics(): Promise<string[]>;
+    getSubscriptionCount(topic: string): Promise<number>;
+    shutdown(): Promise<void>;
+}

package/dist/runtime/adapters/builtin/file-stream.js

@@ -0,0 +1,56 @@
+export class FileStreamAdapter {
+  subscriptions = /* @__PURE__ */ new Map();
+  subscriptionCounter = 0;
+  async init() {
+  }
+  async publish(topic, event) {
+    const topicSubscriptions = this.subscriptions.get(topic);
+    if (!topicSubscriptions || topicSubscriptions.size === 0) {
+      return;
+    }
+    const eventWithTs = {
+      ...event,
+      timestamp: event.timestamp || Date.now()
+    };
+    const promises = [];
+    Array.from(topicSubscriptions.values()).forEach((handler) => {
+      promises.push(handler(eventWithTs));
+    });
+    await Promise.all(promises);
+  }
+  async subscribe(topic, handler, _opts) {
+    const subscriptionId = `sub-${++this.subscriptionCounter}`;
+    if (!this.subscriptions.has(topic)) {
+      this.subscriptions.set(topic, /* @__PURE__ */ new Map());
+    }
+    const topicSubscriptions = this.subscriptions.get(topic);
+    topicSubscriptions.set(subscriptionId, handler);
+    return {
+      id: subscriptionId,
+      topic,
+      unsubscribe: async () => {
+        await this.unsubscribe({ id: subscriptionId, topic, unsubscribe: async () => {
+        } });
+      }
+    };
+  }
+  async unsubscribe(handle) {
+    const topicSubscriptions = this.subscriptions.get(handle.topic);
+    if (topicSubscriptions) {
+      topicSubscriptions.delete(handle.id);
+      if (topicSubscriptions.size === 0) {
+        this.subscriptions.delete(handle.topic);
+      }
+    }
+  }
+  async listTopics() {
+    return Array.from(this.subscriptions.keys());
+  }
+  async getSubscriptionCount(topic) {
+    const topicSubscriptions = this.subscriptions.get(topic);
+    return topicSubscriptions ? topicSubscriptions.size : 0;
+  }
+  async shutdown() {
+    this.subscriptions.clear();
+  }
+}

package/dist/runtime/adapters/builtin/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Built-in Adapters
+ *
+ * In-memory and file-based adapters for development (no external dependencies)
+ */
+export { MemoryQueueAdapter } from './memory-queue.js';
+export { MemoryStreamAdapter } from './memory-stream.js';
+export { MemoryStoreAdapter } from './memory-store.js';
+export { FileQueueAdapter } from './file-queue.js';
+export { FileStoreAdapter } from './file-store.js';

package/dist/runtime/adapters/builtin/index.js

@@ -0,0 +1,5 @@
+export { MemoryQueueAdapter } from "./memory-queue.js";
+export { MemoryStreamAdapter } from "./memory-stream.js";
+export { MemoryStoreAdapter } from "./memory-store.js";
+export { FileQueueAdapter } from "./file-queue.js";
+export { FileStoreAdapter } from "./file-store.js";

package/dist/runtime/adapters/builtin/memory-queue.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Memory Queue Adapter
+ *
+ * In-memory queue implementation using fastq for development
+ * - Fast and simple
+ * - No external dependencies beyond fastq
+ * - Data lost on restart
+ * - Single instance only
+ *
+ * Architecture:
+ * - QueueAdapter: Manages job storage and queue events
+ * - WorkerManager: Executes jobs using fastq
+ * - Dispatcher pattern: Routes jobs to handlers by job.name
+ */
+import type { QueueAdapter, JobInput, Job, JobsQuery, ScheduleOptions, JobCounts, QueueEvent, WorkerHandler, WorkerOptions } from '../interfaces/queue.js';
+export interface MemoryQueueAdapterOptions {
+    maxQueueSize?: number;
+}
+export declare class MemoryQueueAdapter implements QueueAdapter {
+    private jobs;
+    private eventListeners;
+    private workers;
+    private options;
+    constructor(options?: MemoryQueueAdapterOptions);
+    init(): Promise<void>;
+    enqueue(queueName: string, job: JobInput): Promise<string>;
+    schedule(queueName: string, job: JobInput, opts?: ScheduleOptions): Promise<string>;
+    getJob(_queueName: string, id: string): Promise<Job | null>;
+    getJobs(queueName: string, query?: JobsQuery): Promise<Job[]>;
+    on(queueName: string, event: QueueEvent, callback: (payload: any) => void): () => void;
+    isPaused(queueName: string): Promise<boolean>;
+    getJobCounts(queueName: string): Promise<JobCounts>;
+    pause(queueName: string): Promise<void>;
+    resume(queueName: string): Promise<void>;
+    close(): Promise<void>;
+    /**
+     * Register a worker handler for a queue
+     * This is called by the worker registration system
+     */
+    registerWorker(queueName: string, jobName: string, handler: WorkerHandler, opts?: WorkerOptions): void;
+    /**
+     * Start processing waiting jobs for a queue
+     * Should be called after all handlers are registered
+     */
+    startProcessingQueue(queueName: string): void;
+    /**
+     * Update job state (called internally and by worker manager)
+     */
+    updateJobState(jobId: string, state: Job['state'], extra?: Partial<Job>): void;
+    private emitEvent;
+    private generateId;
+}

package/dist/runtime/adapters/builtin/memory-queue.js

@@ -0,0 +1,243 @@
+import * as fastq from "fastq";
+export class MemoryQueueAdapter {
+  jobs = /* @__PURE__ */ new Map();
+  eventListeners = /* @__PURE__ */ new Map();
+  workers = /* @__PURE__ */ new Map();
+  options;
+  constructor(options = {}) {
+    this.options = {
+      maxQueueSize: options.maxQueueSize || 1e3
+    };
+  }
+  async init() {
+  }
+  async enqueue(queueName, job) {
+    const jobId = job.opts?.jobId || this.generateId();
+    if (this.jobs.has(jobId)) {
+      return jobId;
+    }
+    if (this.jobs.size >= this.options.maxQueueSize) {
+      throw new Error(`Queue ${queueName} is full (max: ${this.options.maxQueueSize})`);
+    }
+    const internalJob = {
+      id: jobId,
+      name: job.name,
+      data: { ...job.data, __queueName: queueName },
+      state: "waiting",
+      timestamp: Date.now()
+    };
+    this.jobs.set(jobId, internalJob);
+    this.emitEvent(queueName, "waiting", { jobId, job: internalJob });
+    const workerInfo = this.workers.get(queueName);
+    if (workerInfo && !workerInfo.paused) {
+      workerInfo.queue.push({ jobId, jobName: job.name, data: job.data }).catch((error) => {
+        console.error(`[MemoryQueueAdapter] Error processing job ${jobId}:`, error);
+      });
+    }
+    return jobId;
+  }
+  async schedule(queueName, job, opts) {
+    if (opts?.delay) {
+      const jobId = this.generateId();
+      const internalJob = {
+        id: jobId,
+        name: job.name,
+        data: { ...job.data, __queueName: queueName },
+        state: "delayed",
+        timestamp: Date.now()
+      };
+      this.jobs.set(jobId, internalJob);
+      this.emitEvent(queueName, "delayed", { jobId, job: internalJob, delay: opts.delay });
+      setTimeout(() => {
+        this.enqueue(queueName, job);
+      }, opts.delay);
+      return jobId;
+    }
+    if (opts?.cron || opts?.repeat) {
+      throw new Error("Cron/repeat scheduling not supported in memory adapter");
+    }
+    return this.enqueue(queueName, job);
+  }
+  async getJob(_queueName, id) {
+    return this.jobs.get(id) || null;
+  }
+  async getJobs(queueName, query) {
+    let jobs = Array.from(this.jobs.values()).filter((j) => j.data?.__queueName === queueName);
+    if (query?.state && query.state.length > 0) {
+      jobs = jobs.filter((j) => query.state.includes(j.state));
+    }
+    if (query?.offset) {
+      jobs = jobs.slice(query.offset);
+    }
+    if (query?.limit) {
+      jobs = jobs.slice(0, query.limit);
+    }
+    return jobs;
+  }
+  on(queueName, event, callback) {
+    const key = `${queueName}:${event}`;
+    if (!this.eventListeners.has(key)) {
+      this.eventListeners.set(key, []);
+    }
+    this.eventListeners.get(key).push(callback);
+    return () => {
+      const listeners = this.eventListeners.get(key);
+      if (listeners) {
+        const index = listeners.indexOf(callback);
+        if (index > -1) {
+          listeners.splice(index, 1);
+        }
+      }
+    };
+  }
+  async isPaused(queueName) {
+    const workerInfo = this.workers.get(queueName);
+    return workerInfo?.paused || false;
+  }
+  async getJobCounts(queueName) {
+    const jobs = Array.from(this.jobs.values()).filter((j) => j.data?.__queueName === queueName);
+    return {
+      active: jobs.filter((j) => j.state === "active").length,
+      completed: jobs.filter((j) => j.state === "completed").length,
+      failed: jobs.filter((j) => j.state === "failed").length,
+      delayed: jobs.filter((j) => j.state === "delayed").length,
+      waiting: jobs.filter((j) => j.state === "waiting").length,
+      paused: jobs.filter((j) => j.state === "paused").length
+    };
+  }
+  async pause(queueName) {
+    const workerInfo = this.workers.get(queueName);
+    if (workerInfo) {
+      workerInfo.paused = true;
+      workerInfo.queue.pause();
+    }
+  }
+  async resume(queueName) {
+    const workerInfo = this.workers.get(queueName);
+    if (workerInfo) {
+      workerInfo.paused = false;
+      workerInfo.queue.resume();
+    }
+  }
+  async close() {
+    const drainPromises = Array.from(this.workers.values()).map((w) => w.queue.drained());
+    await Promise.all(drainPromises);
+    this.jobs.clear();
+    this.eventListeners.clear();
+    this.workers.clear();
+  }
+  // ============================================================
+  // Worker Management (used by worker registration system)
+  // ============================================================
+  /**
+   * Register a worker handler for a queue
+   * This is called by the worker registration system
+   */
+  registerWorker(queueName, jobName, handler, opts) {
+    let workerInfo = this.workers.get(queueName);
+    if (workerInfo) {
+      console.info(`[MemoryQueue] Adding handler for job "${jobName}" to queue "${queueName}"`);
+      workerInfo.handlers.set(jobName, handler);
+      return;
+    }
+    console.info(`[MemoryQueue] Creating new worker for queue: ${queueName}`);
+    const handlers = /* @__PURE__ */ new Map();
+    handlers.set(jobName, handler);
+    const dispatcher = async (task) => {
+      const handler2 = handlers.get(task.jobName);
+      if (!handler2) {
+        const error = `No handler for job "${task.jobName}" on queue "${queueName}". Available: ${Array.from(handlers.keys()).join(", ")}`;
+        console.error(error);
+        throw new Error(error);
+      }
+      this.updateJobState(task.jobId, "active", { processedOn: Date.now() });
+      this.emitEvent(queueName, "active", { jobId: task.jobId });
+      try {
+        const result = await handler2(task.data, {
+          jobId: task.jobId,
+          queueName
+          // Add more context as needed
+        });
+        if (result && typeof result === "object" && result.awaiting === true) {
+          this.jobs.delete(task.jobId);
+          return result;
+        }
+        this.updateJobState(task.jobId, "completed", {
+          returnvalue: result,
+          finishedOn: Date.now()
+        });
+        this.emitEvent(queueName, "completed", { jobId: task.jobId, returnvalue: result });
+        return result;
+      } catch (err) {
+        this.updateJobState(task.jobId, "failed", {
+          failedReason: err.message,
+          finishedOn: Date.now()
+        });
+        this.emitEvent(queueName, "failed", {
+          jobId: task.jobId,
+          failedReason: err.message
+        });
+        throw err;
+      }
+    };
+    const concurrency = opts?.concurrency || 1;
+    const queue = fastq.promise(dispatcher, concurrency);
+    const shouldPause = opts?.autorun === false;
+    workerInfo = {
+      queue,
+      handlers,
+      paused: shouldPause || false,
+      concurrency
+    };
+    if (shouldPause) {
+      queue.pause();
+      console.info(`[MemoryQueue] Worker for "${queueName}" created but paused`);
+    }
+    this.workers.set(queueName, workerInfo);
+  }
+  /**
+   * Start processing waiting jobs for a queue
+   * Should be called after all handlers are registered
+   */
+  startProcessingQueue(queueName) {
+    const workerInfo = this.workers.get(queueName);
+    if (!workerInfo || workerInfo.paused) return;
+    const waitingJobs = Array.from(this.jobs.values()).filter(
+      (j) => j.state === "waiting" && j.data?.__queueName === queueName
+    );
+    for (const job of waitingJobs) {
+      workerInfo.queue.push({ jobId: job.id, jobName: job.name, data: job.data }).catch((error) => {
+        console.error(`[MemoryQueueAdapter] Error processing queued job ${job.id}:`, error);
+      });
+    }
+  }
+  // ============================================================
+  // Helper Methods
+  // ============================================================
+  /**
+   * Update job state (called internally and by worker manager)
+   */
+  updateJobState(jobId, state, extra) {
+    const job = this.jobs.get(jobId);
+    if (job) {
+      job.state = state;
+      if (extra) {
+        Object.assign(job, extra);
+      }
+    }
+  }
+  emitEvent(queueName, event, payload) {
+    const key = `${queueName}:${event}`;
+    const listeners = this.eventListeners.get(key) || [];
+    for (const callback of listeners) {
+      try {
+        callback(payload);
+      } catch (error) {
+        console.error(`[MemoryQueueAdapter] Error in event listener for ${key}:`, error);
+      }
+    }
+  }
+  generateId() {
+    return `${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+  }
+}

package/dist/runtime/adapters/builtin/memory-store.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Memory Store Adapter
+ *
+ * In-memory storage implementation for development
+ * Three-tier storage:
+ * 1. Event Stream - Append-only event log
+ * 2. Sorted Index - Time-ordered metadata storage
+ * 3. Key-Value Store - Fast lookups
+ *
+ * All data is lost on restart (ephemeral)
+ */
+import type { StoreAdapter, EventRecord, EventReadOptions, EventSubscription } from '../interfaces/store.js';
+export declare class MemoryStoreAdapter implements StoreAdapter {
+    private eventStreams;
+    private eventSubscriptions;
+    private subscriptionCounter;
+    private kvStore;
+    private sortedIndices;
+    protected validator: import("../base/index.js").StoreValidator;
+    private indexLocks;
+    close(): Promise<void>;
+    stream: {
+        append: (subject: string, event: Omit<EventRecord, "id" | "ts">) => Promise<EventRecord>;
+        read: (subject: string, opts?: EventReadOptions) => Promise<EventRecord[]>;
+        subscribe: (subject: string, onEvent: (event: EventRecord) => void) => Promise<EventSubscription>;
+        delete: (subject: string) => Promise<boolean>;
+    };
+    private notifySubscribers;
+    kv: {
+        get: <T = any>(key: string) => Promise<T | null>;
+        set: <T = any>(key: string, value: T, _ttl?: number) => Promise<void>;
+        delete: (key: string) => Promise<void>;
+        clear: (pattern: string) => Promise<number>;
+        increment: (key: string, by?: number) => Promise<number>;
+    };
+    index: {
+        add: (key: string, id: string, score: number, metadata?: Record<string, any>) => Promise<void>;
+        get: (key: string, id: string) => Promise<{
+            id: string;
+            score: number;
+            metadata?: any;
+        } | null>;
+        read: (key: string, opts?: {
+            offset?: number;
+            limit?: number;
+        }) => Promise<Array<{
+            id: string;
+            score: number;
+            metadata?: any;
+        }>>;
+        update: (key: string, id: string, metadata: Record<string, any>) => Promise<boolean>;
+        updateWithRetry: (key: string, id: string, metadata: Record<string, any>, maxRetries?: number) => Promise<void>;
+        increment: (key: string, id: string, field: string, increment?: number) => Promise<number>;
+        delete: (key: string, id: string) => Promise<boolean>;
+    };
+    /**
+     * Acquire a lock for atomic index operations
+     * Protected to allow access from FileStoreAdapter
+     */
+    protected acquireIndexLock(key: string): Promise<() => void>;
+    /**
+     * Convert dot notation keys to nested objects
+     * e.g., { 'stats.totalFires': 5 } -> { stats: { totalFires: 5 } }
+     * null values are preserved for deletion
+     */
+    private expandDotNotation;
+    private generateId;
+}