nvent 0.4.4 → 0.5.0

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

@@ -0,0 +1,6 @@
+/**
+ * Adapter base utilities
+ * Exported for use by external adapter packages
+ */
+export { StoreValidator, createStoreValidator } from './store-validator.js';
+export type { StoreValidatorOptions } from './store-validator.js';

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

@@ -0,0 +1 @@
+export { StoreValidator, createStoreValidator } from "./store-validator.js";

package/dist/runtime/adapters/base/store-validator.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Store Adapter Validation
+ *
+ * Centralized validation logic for index updates to ensure correct usage
+ * across all store adapter implementations.
+ */
+export interface StoreValidatorOptions {
+    /** Adapter name for error messages */
+    adapterName: string;
+    /** Enable counter misuse warnings (default: true in development) */
+    warnCounters?: boolean;
+    /** Throw errors on validation failures (default: true) */
+    throwOnError?: boolean;
+}
+export declare class StoreValidator {
+    private readonly adapterName;
+    private readonly warnCounters;
+    private readonly throwOnError;
+    constructor(options: StoreValidatorOptions);
+    /**
+     * Validate index update payload
+     * Throws error if dot notation keys are detected (except 'version')
+     * Recursively checks all nested objects
+     */
+    validateUpdatePayload(payload: Record<string, any>, method: string): void;
+    /**
+     * Recursively check for dot notation in object keys
+     */
+    private checkDotNotationKeys;
+    /**
+     * Build a nested object suggestion from a dot notation key
+     */
+    private buildNestedObjectSuggestion;
+    /**
+     * Detect potential counter misuse
+     * Logs warnings when numeric fields that look like counters are updated
+     * via update() instead of increment()
+     */
+    private detectCounterMisuse;
+    /**
+     * Check if a field looks like a counter that should use increment()
+     */
+    private isCounterField;
+}
+/**
+ * Factory function to create a validator for an adapter
+ */
+export declare function createStoreValidator(adapterName: string, options?: Partial<StoreValidatorOptions>): StoreValidator;

package/dist/runtime/adapters/base/store-validator.js

@@ -0,0 +1,147 @@
+export class StoreValidator {
+  adapterName;
+  warnCounters;
+  throwOnError;
+  constructor(options) {
+    this.adapterName = options.adapterName;
+    this.warnCounters = options.warnCounters ?? process.env.NODE_ENV === "development";
+    this.throwOnError = options.throwOnError ?? true;
+  }
+  /**
+   * Validate index update payload
+   * Throws error if dot notation keys are detected (except 'version')
+   * Recursively checks all nested objects
+   */
+  validateUpdatePayload(payload, method) {
+    this.checkDotNotationKeys(payload, method, []);
+    if (this.warnCounters) {
+      this.detectCounterMisuse(payload, method);
+    }
+  }
+  /**
+   * Recursively check for dot notation in object keys
+   */
+  checkDotNotationKeys(obj, method, path) {
+    for (const key of Object.keys(obj)) {
+      const currentPath = [...path, key];
+      if (key.includes(".") && key !== "version") {
+        const fullPath = currentPath.join(".");
+        const suggestion = this.buildNestedObjectSuggestion(key);
+        const message = [
+          `[${this.adapterName}] Invalid update payload in ${method}:`,
+          `Dot notation key "${key}" detected at path "${fullPath}".`,
+          `Keys should not contain dots. Split "${key}" into nested objects: ${suggestion}`
+        ].join("\n");
+        console.error(message);
+        if (this.throwOnError) {
+          throw new Error(
+            `Invalid index update: dot notation keys not supported. Key "${key}" at path "${fullPath}" contains dots.`
+          );
+        }
+      }
+      const value = obj[key];
+      if (value && typeof value === "object" && !Array.isArray(value)) {
+        this.checkDotNotationKeys(value, method, currentPath);
+      }
+    }
+  }
+  /**
+   * Build a nested object suggestion from a dot notation key
+   */
+  buildNestedObjectSuggestion(dotKey) {
+    const parts = dotKey.split(".");
+    let suggestion = "{ ";
+    for (let i = 0; i < parts.length - 1; i++) {
+      suggestion += `${parts[i]}: { `;
+    }
+    suggestion += `${parts[parts.length - 1]}: value `;
+    for (let i = 0; i < parts.length - 1; i++) {
+      suggestion += "}";
+    }
+    suggestion += " }";
+    return suggestion;
+  }
+  /**
+   * Detect potential counter misuse
+   * Logs warnings when numeric fields that look like counters are updated
+   * via update() instead of increment()
+   */
+  detectCounterMisuse(payload, method) {
+    const checkNested = (obj, path = []) => {
+      for (const [key, value] of Object.entries(obj)) {
+        const currentPath = [...path, key];
+        if (this.isCounterField(key, value, currentPath)) {
+          console.warn(
+            `[${this.adapterName}] Potential counter misuse in ${method}:`,
+            `Field "${currentPath.join(".")}" is numeric.`,
+            `Consider using index.increment() for atomic updates instead of ${method}.`
+          );
+        }
+        if (value && typeof value === "object" && !Array.isArray(value)) {
+          checkNested(value, currentPath);
+        }
+      }
+    };
+    checkNested(payload);
+  }
+  /**
+   * Check if a field looks like a counter that should use increment()
+   */
+  isCounterField(key, value, path) {
+    if (typeof value !== "number") {
+      return false;
+    }
+    if (path.includes("emittedEvents")) {
+      return false;
+    }
+    const metadataFields = [
+      "stepCount",
+      // Total steps in flow (constant)
+      "timeout",
+      // Timeout duration
+      "delay",
+      // Delay duration
+      "timestamp",
+      // Timestamp values
+      "score",
+      // Score values
+      "priority",
+      // Priority values
+      "version"
+      // Version field
+    ];
+    if (metadataFields.includes(key)) {
+      return false;
+    }
+    if (key.endsWith("At")) {
+      return false;
+    }
+    const counterKeywords = [
+      "count",
+      "total",
+      "running",
+      "awaiting",
+      "success",
+      "failure",
+      "cancel",
+      "pending",
+      "completed",
+      "failed",
+      "retries",
+      "attempts"
+    ];
+    if (counterKeywords.some((keyword) => key.toLowerCase().includes(keyword))) {
+      return true;
+    }
+    if (path.includes("stats")) {
+      return true;
+    }
+    return false;
+  }
+}
+export function createStoreValidator(adapterName, options) {
+  return new StoreValidator({
+    adapterName,
+    ...options
+  });
+}

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

@@ -0,0 +1,67 @@
+/**
+ * File Queue Adapter
+ *
+ * File-based queue implementation for development/small deployments
+ * - Uses fastq for job processing (same as memory adapter)
+ * - Persists jobs to file system
+ * - Survives restarts
+ * - Single instance only (no distributed lock)
+ *
+ * Storage format:
+ * - {dataDir}/{queueName}/jobs/{jobId}.json - Individual job files
+ * - Jobs are loaded on init and kept in memory with fastq
+ */
+import type { QueueAdapter, JobInput, Job, JobsQuery, ScheduleOptions, JobCounts, QueueEvent, WorkerHandler, WorkerOptions } from '../interfaces/queue.js';
+export interface FileQueueAdapterOptions {
+    dataDir: string;
+    maxQueueSize?: number;
+}
+export declare class FileQueueAdapter implements QueueAdapter {
+    private jobs;
+    private eventListeners;
+    private workers;
+    private scheduledJobs;
+    private options;
+    private initialized;
+    constructor(options: FileQueueAdapterOptions);
+    init(): Promise<void>;
+    private loadJobsFromDisk;
+    private persistJob;
+    private deleteJobFile;
+    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>;
+    getScheduledJobs(queueName: string): Promise<Array<any>>;
+    removeScheduledJob(scheduleId: string): Promise<boolean>;
+    pause(queueName: string): Promise<void>;
+    resume(queueName: string): Promise<void>;
+    close(): Promise<void>;
+    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;
+    private updateJobState;
+    private emitEvent;
+    /**
+     * Clean up completed jobs based on removeOnComplete option
+     * - true: delete immediately
+     * - false/undefined: keep forever
+     * - number: keep last N jobs, delete older ones
+     */
+    private cleanupCompletedJobs;
+    /**
+     * Clean up failed jobs based on removeOnFail option
+     * - true: delete immediately
+     * - false/undefined: keep forever
+     * - number: keep last N jobs, delete older ones
+     */
+    private cleanupFailedJobs;
+    private generateId;
+    private scheduleCronJob;
+}