alepha 0.12.1 → 0.13.1

package/dist/lock/index.cjs

@@ -1,226 +0,0 @@
-let alepha = require("alepha");
-let alepha_topic = require("alepha/topic");
-let alepha_datetime = require("alepha/datetime");
-let alepha_logger = require("alepha/logger");
-
-//#region src/lock/providers/LockProvider.ts
-/**
-* Store Provider Interface
-*/
-var LockProvider = class {};
-
-//#endregion
-//#region src/lock/providers/LockTopicProvider.ts
-var LockTopicProvider = class extends alepha_topic.TopicProvider {};
-
-//#endregion
-//#region src/lock/descriptors/$lock.ts
-/**
-* Creates a distributed lock descriptor for ensuring single-instance execution across processes.
-*
-* Prevents multiple instances of the same operation from running simultaneously, essential for
-* maintaining data consistency and preventing race conditions in distributed applications.
-*
-* **Key Features**
-* - Distributed coordination across multiple processes, servers, and containers
-* - Automatic expiration to prevent deadlocks
-* - Configurable wait behavior (blocking vs. non-blocking)
-* - Optional grace periods for lock extension after completion
-* - Dynamic or static lock keys for fine-grained control
-*
-* **Common Use Cases**
-* - Database migrations and scheduled jobs
-* - File processing and batch operations
-* - Critical section protection and resource initialization
-*
-* @example
-* ```ts
-* class TaskService {
-*   // Basic scheduled task - only one server executes
-*   dailyReport = $lock({
-*     handler: async () => {
-*       const report = await this.generateDailyReport();
-*       await this.sendReportToManagement(report);
-*     }
-*   });
-*
-*   // Migration with wait - all instances wait for completion
-*   migration = $lock({
-*     wait: true,
-*     maxDuration: [10, "minutes"],
-*     handler: async (version: string) => {
-*       await this.runMigrationScripts(version);
-*     }
-*   });
-*
-*   // Dynamic lock keys for per-resource locking
-*   processFile = $lock({
-*     name: (fileId: string) => `file-processing:${fileId}`,
-*     gracePeriod: [5, "minutes"],
-*     handler: async (fileId: string) => {
-*       await this.processFileData(fileId);
-*     }
-*   });
-* }
-* ```
-*/
-const $lock = (options) => {
-	return (0, alepha.createDescriptor)(LockDescriptor, options);
-};
-const envSchema = alepha.t.object({ LOCK_PREFIX_KEY: alepha.t.text({ default: "lock" }) });
-var LockDescriptor = class extends alepha.Descriptor {
-	log = (0, alepha_logger.$logger)();
-	provider = (0, alepha.$inject)(LockProvider);
-	env = (0, alepha.$env)(envSchema);
-	dateTimeProvider = (0, alepha.$inject)(alepha_datetime.DateTimeProvider);
-	id = crypto.randomUUID();
-	maxDuration = this.dateTimeProvider.duration(this.options.maxDuration ?? [5, "minutes"]);
-	topicLockEnd = (0, alepha_topic.$topic)({
-		name: `${this.env.LOCK_PREFIX_KEY}:lock-end`,
-		provider: LockTopicProvider,
-		schema: { payload: alepha.t.object({ name: alepha.t.text() }) }
-	});
-	async run(...args) {
-		const key = this.key(...args);
-		const handler = this.options.handler;
-		const lock = await this.lock(key);
-		if (lock.endedAt) return;
-		if (lock.id !== this.id) {
-			if (this.options.wait) try {
-				await this.wait(key, this.maxDuration);
-			} catch (error) {
-				if (error instanceof alepha_topic.TopicTimeoutError) {
-					this.log.warn(`Lock timeout for '${key}' has been reached. Retry...`);
-					await this.run(...args);
-				} else throw error;
-			}
-			return;
-		}
-		this.log.debug(`Lock '${key}' ...`);
-		try {
-			await handler(...args);
-		} finally {
-			await this.topicLockEnd.publish({ name: key });
-			await this.setGracePeriod(key, lock, ...args);
-			this.log.debug(`Lock '${key}' OK`);
-		}
-	}
-	/**
-	* Set the lock for the given key.
-	*/
-	async lock(key) {
-		const value = await this.provider.set(key, `${this.id},${this.dateTimeProvider.nowISOString()}`, true, this.maxDuration.as("milliseconds"));
-		return this.parse(value);
-	}
-	async setGracePeriod(key, lock, ...args) {
-		const gracePeriod = this.options.gracePeriod ? this.dateTimeProvider.isDurationLike(this.options.gracePeriod) ? this.options.gracePeriod : this.options.gracePeriod(...args) : void 0;
-		if (gracePeriod) await this.provider.set(key, `${this.id},${lock.createdAt.toISOString()},${this.dateTimeProvider.nowISOString()}`, false, this.dateTimeProvider.duration(gracePeriod).as("milliseconds"));
-		else await this.provider.del(key);
-	}
-	async wait(key, maxDuration) {
-		this.log.debug(`Wait for lock '${key}' ...`);
-		await this.topicLockEnd.wait({
-			filter: (message) => message.payload.name === key,
-			timeout: maxDuration
-		});
-		this.log.debug(`Wait for lock '${key}' OK`);
-	}
-	key(...args) {
-		let base = "";
-		if (this.options.name) if (typeof this.options.name === "string") base = this.options.name;
-		else base = this.options.name(...args);
-		else base = `${this.config.service.name}:${this.config.propertyKey}`;
-		return `${this.env.LOCK_PREFIX_KEY}:${base}`;
-	}
-	parse(value) {
-		const [id, createdAtStr, endedAtStr] = value.split(",");
-		return {
-			id,
-			createdAt: this.dateTimeProvider.of(createdAtStr),
-			endedAt: endedAtStr ? this.dateTimeProvider.of(endedAtStr) : void 0
-		};
-	}
-};
-$lock[alepha.KIND] = LockDescriptor;
-
-//#endregion
-//#region src/lock/providers/MemoryLockProvider.ts
-/**
-* A simple in-memory store provider.
-*/
-var MemoryLockProvider = class {
-	dateTimeProvider = (0, alepha.$inject)(alepha_datetime.DateTimeProvider);
-	log = (0, alepha_logger.$logger)();
-	/**
-	* The in-memory store.
-	*/
-	store = {};
-	/**
-	* Timeouts used to expire keys.
-	*/
-	storeTimeout = {};
-	async set(key, value, nx, px) {
-		if (nx && this.store[key] != null) return this.store[key];
-		if (px) this.ttl(key, px);
-		this.store[key] = value;
-		return this.store[key];
-	}
-	async del(...keys) {
-		for (const key of keys) {
-			delete this.store[key];
-			if (this.storeTimeout[key] != null) {
-				this.storeTimeout[key].clear();
-				delete this.storeTimeout[key];
-			}
-		}
-	}
-	ttl(key, ms) {
-		if (this.storeTimeout[key] != null) {
-			this.storeTimeout[key].clear();
-			delete this.storeTimeout[key];
-		}
-		this.storeTimeout[key] = this.dateTimeProvider.createTimeout(() => {
-			delete this.store[key];
-			delete this.storeTimeout[key];
-		}, ms);
-	}
-};
-
-//#endregion
-//#region src/lock/index.ts
-/**
-* Lock a resource for a certain period of time.
-*
-* This module provides a memory implementation of the lock provider.
-* You probably want to use an implementation like RedisLockProvider for distributed systems.
-*
-* @see {@link $lock}
-* @module alepha.lock
-*/
-const AlephaLock = (0, alepha.$module)({
-	name: "alepha.lock",
-	descriptors: [$lock],
-	services: [
-		LockProvider,
-		MemoryLockProvider,
-		LockTopicProvider
-	],
-	register: (alepha$1) => alepha$1.with({
-		optional: true,
-		provide: LockTopicProvider,
-		use: alepha_topic.MemoryTopicProvider
-	}).with({
-		optional: true,
-		provide: LockProvider,
-		use: MemoryLockProvider
-	})
-});
-
-//#endregion
-exports.$lock = $lock;
-exports.AlephaLock = AlephaLock;
-exports.LockDescriptor = LockDescriptor;
-exports.LockProvider = LockProvider;
-exports.LockTopicProvider = LockTopicProvider;
-exports.MemoryLockProvider = MemoryLockProvider;
-//# sourceMappingURL=index.cjs.map

package/dist/lock/index.cjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.cjs","names":["TopicProvider","t","Descriptor","DateTimeProvider","TopicTimeoutError","KIND","DateTimeProvider","alepha","MemoryTopicProvider"],"sources":["../../src/lock/providers/LockProvider.ts","../../src/lock/providers/LockTopicProvider.ts","../../src/lock/descriptors/$lock.ts","../../src/lock/providers/MemoryLockProvider.ts","../../src/lock/index.ts"],"sourcesContent":["/**\n * Store Provider Interface\n */\nexport abstract class LockProvider {\n  /**\n   * Set the string value of a key.\n   *\n   * @param key The key of the value to set.\n   * @param value The value to set.\n   * @param nx If set to true, the key will only be set if it does not already exist.\n   * @param px Set the specified expire time, in milliseconds.\n   */\n  public abstract set(\n    key: string,\n    value: string,\n    nx?: boolean,\n    px?: number,\n  ): Promise<string>;\n\n  /**\n   * Remove the specified keys.\n   *\n   * @param keys The keys to delete.\n   */\n  public abstract del(...keys: string[]): Promise<void>;\n}\n","import { TopicProvider } from \"alepha/topic\";\n\nexport abstract class LockTopicProvider extends TopicProvider {}\n","import {\n  $env,\n  $inject,\n  type AsyncFn,\n  createDescriptor,\n  Descriptor,\n  KIND,\n  type Static,\n  t,\n} from \"alepha\";\nimport {\n  type DateTime,\n  DateTimeProvider,\n  type DurationLike,\n} from \"alepha/datetime\";\nimport { $logger } from \"alepha/logger\";\nimport { $topic, TopicTimeoutError } from \"alepha/topic\";\nimport { LockProvider } from \"../providers/LockProvider.ts\";\nimport { LockTopicProvider } from \"../providers/LockTopicProvider.ts\";\n\n/**\n * Creates a distributed lock descriptor for ensuring single-instance execution across processes.\n *\n * Prevents multiple instances of the same operation from running simultaneously, essential for\n * maintaining data consistency and preventing race conditions in distributed applications.\n *\n * **Key Features**\n * - Distributed coordination across multiple processes, servers, and containers\n * - Automatic expiration to prevent deadlocks\n * - Configurable wait behavior (blocking vs. non-blocking)\n * - Optional grace periods for lock extension after completion\n * - Dynamic or static lock keys for fine-grained control\n *\n * **Common Use Cases**\n * - Database migrations and scheduled jobs\n * - File processing and batch operations\n * - Critical section protection and resource initialization\n *\n * @example\n * ```ts\n * class TaskService {\n *   // Basic scheduled task - only one server executes\n *   dailyReport = $lock({\n *     handler: async () => {\n *       const report = await this.generateDailyReport();\n *       await this.sendReportToManagement(report);\n *     }\n *   });\n *\n *   // Migration with wait - all instances wait for completion\n *   migration = $lock({\n *     wait: true,\n *     maxDuration: [10, \"minutes\"],\n *     handler: async (version: string) => {\n *       await this.runMigrationScripts(version);\n *     }\n *   });\n *\n *   // Dynamic lock keys for per-resource locking\n *   processFile = $lock({\n *     name: (fileId: string) => `file-processing:${fileId}`,\n *     gracePeriod: [5, \"minutes\"],\n *     handler: async (fileId: string) => {\n *       await this.processFileData(fileId);\n *     }\n *   });\n * }\n * ```\n */\nexport const $lock = <TFunc extends AsyncFn>(\n  options: LockDescriptorOptions<TFunc>,\n): LockDescriptor<TFunc> => {\n  return createDescriptor(LockDescriptor<TFunc>, options);\n};\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport interface LockDescriptorOptions<TFunc extends AsyncFn> {\n  /**\n   * The function to execute when the lock is successfully acquired.\n   *\n   * This function:\n   * - Only executes on the instance that successfully acquires the lock\n   * - Has exclusive access to the protected resource during execution\n   * - Should contain the critical section logic that must not run concurrently\n   * - Can be async and perform any operations needed\n   * - Will automatically release the lock upon completion or error\n   * - Has access to the full Alepha dependency injection container\n   *\n   * **Handler Design Guidelines**:\n   * - Keep critical sections as short as possible to minimize lock contention\n   * - Include proper error handling to ensure locks are released\n   * - Use timeouts for external operations to prevent deadlocks\n   * - Log important operations for debugging and monitoring\n   * - Consider idempotency for handlers that might be retried\n   *\n   * @param ...args - The arguments passed to the lock execution\n   * @returns Promise that resolves when the protected operation is complete\n   *\n   * @example\n   * ```ts\n   * handler: async (batchId: string) => {\n   *   console.log(`Processing batch ${batchId} - only one instance will run this`);\n   *\n   *   const batch = await this.getBatchData(batchId);\n   *   const results = await this.processBatchItems(batch.items);\n   *   await this.saveBatchResults(batchId, results);\n   *\n   *   console.log(`Batch ${batchId} completed successfully`);\n   * }\n   * ```\n   */\n  handler: TFunc;\n\n  /**\n   * Whether the lock should wait for other instances to complete before giving up.\n   *\n   * **wait = false (default)**:\n   * - Non-blocking behavior - if lock is held, immediately return without executing\n   * - Perfect for scheduled tasks where you only want one execution per trigger\n   * - Use when multiple triggers are acceptable but concurrent execution is not\n   * - Examples: periodic cleanup, cron jobs, background maintenance\n   *\n   * **wait = true**:\n   * - Blocking behavior - wait for the current lock holder to finish\n   * - All instances will eventually execute (one after another)\n   * - Perfect for initialization tasks where all instances need the work completed\n   * - Examples: database migrations, cache warming, resource initialization\n   *\n   * **Trade-offs**:\n   * - Non-waiting: Better performance, may miss executions if timing is off\n   * - Waiting: Guaranteed execution order, slower overall throughput\n   *\n   * @default false\n   *\n   * @example\n   * ```ts\n   * // Scheduled task - don't wait, just skip if already running\n   * scheduledCleanup = $lock({\n   *   wait: false,  // Skip if cleanup already running\n   *   handler: async () => { } // perform cleanup\n   * });\n   *\n   * // Migration - wait for completion before proceeding\n   * migration = $lock({\n   *   wait: true,   // All instances wait for migration to complete\n   *   handler: async () => { } // perform migration\n   * });\n   * ```\n   */\n  wait?: boolean;\n\n  /**\n   * The unique identifier for the lock.\n   *\n   * Can be either:\n   * - **Static string**: A fixed identifier for the lock\n   * - **Dynamic function**: A function that generates the lock key based on arguments\n   *\n   * **Dynamic Lock Keys**:\n   * - Enable per-resource locking (e.g., per-user, per-file, per-product)\n   * - Allow fine-grained concurrency control\n   * - Prevent unnecessary blocking between unrelated operations\n   *\n   * **Key Design Guidelines**:\n   * - Use descriptive names that indicate the protected resource\n   * - Include relevant identifiers for dynamic keys\n   * - Keep keys reasonably short but unique\n   * - Consider using hierarchical naming (e.g., \"service:operation:resource\")\n   *\n   * If not provided, defaults to `{serviceName}:{propertyKey}`.\n   *\n   * @example \"user-migration\"\n   * @example \"daily-report-generation\"\n   * @example (userId: string) => `user-profile-update:${userId}`\n   * @example (fileId: string, operation: string) => `file-${operation}:${fileId}`\n   *\n   * @example\n   * ```ts\n   * // Static lock key - all instances compete for the same lock\n   * globalCleanup = $lock({\n   *   name: \"system-cleanup\",\n   *   handler: async () => { } // perform cleanup\n   * });\n   *\n   * // Dynamic lock key - per-user locks, users don't block each other\n   * updateUserProfile = $lock({\n   *   name: (userId: string) => `user-update:${userId}`,\n   *   handler: async (userId: string, data: UserData) => {\n   *     // Only one update per user at a time, but different users can update concurrently\n   *   }\n   * });\n   * ```\n   */\n  name?: string | ((...args: Parameters<TFunc>) => string);\n\n  /**\n   * Maximum duration the lock can be held before it expires automatically.\n   *\n   * This prevents deadlocks when a process dies while holding a lock or when\n   * operations take longer than expected. The lock will be automatically released\n   * after this duration, allowing other instances to proceed.\n   *\n   * **Duration Guidelines**:\n   * - Set based on expected operation duration plus safety margin\n   * - Too short: Operations may be interrupted by early expiration\n   * - Too long: Failed processes block others for extended periods\n   * - Consider worst-case scenarios and external dependency timeouts\n   *\n   * **Typical Values**:\n   * - Quick operations: 30 seconds - 2 minutes\n   * - Database operations: 5 - 15 minutes\n   * - File processing: 10 - 30 minutes\n   * - Large migrations: 30 minutes - 2 hours\n   *\n   * @default [5, \"minutes\"]\n   *\n   * @example [30, \"seconds\"]    // Quick operations\n   * @example [10, \"minutes\"]    // Database migrations\n   * @example [1, \"hour\"]        // Long-running batch jobs\n   *\n   * @example\n   * ```ts\n   * quickTask = $lock({\n   *   maxDuration: [2, \"minutes\"],  // Quick timeout for fast operations\n   *   handler: async () => { } // perform quick task\n   * });\n   *\n   * heavyProcessing = $lock({\n   *   maxDuration: [30, \"minutes\"], // Longer timeout for heavy work\n   *   handler: async () => { } // perform heavy processing\n   * });\n   * ```\n   */\n  maxDuration?: DurationLike;\n\n  /**\n   * Additional time to keep the lock active after the handler completes successfully.\n   *\n   * This provides a \"cooling off\" period that can be useful for:\n   * - Preventing immediate re-execution of the same operation\n   * - Giving time for related systems to process the results\n   * - Avoiding race conditions with dependent operations\n   * - Providing a buffer for cleanup operations\n   *\n   * Can be either:\n   * - **Static duration**: Fixed grace period for all executions\n   * - **Dynamic function**: Grace period determined by execution arguments\n   * - **undefined**: No grace period, lock released immediately after completion\n   *\n   * **Grace Period Use Cases**:\n   * - File processing: Prevent immediate reprocessing of uploaded files\n   * - Cache updates: Allow time for cache propagation\n   * - Batch operations: Prevent overlapping batch processing\n   * - External API calls: Respect rate limiting requirements\n   *\n   * @default undefined (no grace period)\n   *\n   * @example [5, \"minutes\"]     // Fixed 5-minute grace period\n   * @example [30, \"seconds\"]    // Short grace for quick operations\n   * @example (userId: string) => userId.startsWith(\"premium\") ? [10, \"minutes\"] : [2, \"minutes\"]\n   *\n   * @example\n   * ```ts\n   * fileProcessor = $lock({\n   *   gracePeriod: [10, \"minutes\"],  // Prevent reprocessing same file immediately\n   *   handler: async (filePath: string) => {\n   *     await this.processFile(filePath);\n   *   }\n   * });\n   *\n   * userOperation = $lock({\n   *   gracePeriod: (userId: string, operation: string) => {\n   *     // Dynamic grace based on operation type\n   *     return operation === 'migration' ? [30, \"minutes\"] : [5, \"minutes\"];\n   *   },\n   *   handler: async (userId: string, operation: string) => {\n   *     await this.performUserOperation(userId, operation);\n   *   }\n   * });\n   * ```\n   */\n  gracePeriod?:\n    | ((...args: Parameters<TFunc>) => DurationLike | undefined)\n    | DurationLike;\n}\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nconst envSchema = t.object({\n  LOCK_PREFIX_KEY: t.text({ default: \"lock\" }),\n});\n\ndeclare module \"alepha\" {\n  interface Env extends Partial<Static<typeof envSchema>> {}\n}\n\nexport class LockDescriptor<TFunc extends AsyncFn> extends Descriptor<\n  LockDescriptorOptions<TFunc>\n> {\n  protected readonly log = $logger();\n  protected readonly provider = $inject(LockProvider);\n  protected readonly env = $env(envSchema);\n  protected readonly dateTimeProvider = $inject(DateTimeProvider);\n  protected readonly id = crypto.randomUUID();\n  public readonly maxDuration = this.dateTimeProvider.duration(\n    this.options.maxDuration ?? [5, \"minutes\"],\n  );\n\n  protected readonly topicLockEnd = $topic({\n    name: `${this.env.LOCK_PREFIX_KEY}:lock-end`,\n    provider: LockTopicProvider,\n    schema: {\n      payload: t.object({\n        name: t.text(),\n      }),\n    },\n  });\n\n  public async run(...args: Parameters<TFunc>): Promise<void> {\n    const key = this.key(...args);\n    const handler = this.options.handler;\n\n    const lock = await this.lock(key);\n    if (lock.endedAt) {\n      return;\n    }\n\n    if (lock.id !== this.id) {\n      if (this.options.wait) {\n        try {\n          await this.wait(key, this.maxDuration);\n        } catch (error) {\n          if (error instanceof TopicTimeoutError) {\n            this.log.warn(\n              `Lock timeout for '${key}' has been reached. Retry...`,\n            );\n            await this.run(...args);\n          } else {\n            throw error;\n          }\n        }\n      }\n\n      return;\n    }\n\n    this.log.debug(`Lock '${key}' ...`);\n\n    try {\n      await handler(...args);\n    } finally {\n      await this.topicLockEnd.publish({\n        name: key,\n      });\n\n      await this.setGracePeriod(key, lock, ...args);\n\n      this.log.debug(`Lock '${key}' OK`);\n    }\n  }\n\n  /**\n   * Set the lock for the given key.\n   */\n  protected async lock(key: string): Promise<LockResult> {\n    const value = await this.provider.set(\n      key,\n      `${this.id},${this.dateTimeProvider.nowISOString()}`,\n      true,\n      this.maxDuration.as(\"milliseconds\"),\n    );\n\n    return this.parse(value);\n  }\n\n  protected async setGracePeriod(\n    key: string,\n    lock: LockResult,\n    ...args: Parameters<TFunc>\n  ): Promise<void> {\n    const gracePeriod = this.options.gracePeriod\n      ? this.dateTimeProvider.isDurationLike(this.options.gracePeriod)\n        ? this.options.gracePeriod\n        : this.options.gracePeriod(...args)\n      : undefined;\n\n    if (gracePeriod) {\n      await this.provider.set(\n        key,\n        `${this.id},${lock.createdAt.toISOString()},${this.dateTimeProvider.nowISOString()}`,\n        false,\n        this.dateTimeProvider.duration(gracePeriod).as(\"milliseconds\"),\n      );\n    } else {\n      await this.provider.del(key);\n    }\n  }\n\n  protected async wait(key: string, maxDuration: DurationLike): Promise<void> {\n    this.log.debug(`Wait for lock '${key}' ...`);\n\n    await this.topicLockEnd.wait({\n      filter: (message) => message.payload.name === key,\n      timeout: maxDuration,\n    });\n\n    this.log.debug(`Wait for lock '${key}' OK`);\n  }\n\n  protected key(...args: Parameters<TFunc>) {\n    let base = \"\";\n\n    if (this.options.name) {\n      if (typeof this.options.name === \"string\") {\n        base = this.options.name;\n      } else {\n        base = this.options.name(...args);\n      }\n    } else {\n      base = `${this.config.service.name}:${this.config.propertyKey}`;\n    }\n\n    return `${this.env.LOCK_PREFIX_KEY}:${base}`;\n  }\n\n  protected parse(value: string): LockResult {\n    const [id, createdAtStr, endedAtStr] = value.split(\",\");\n    const createdAt = this.dateTimeProvider.of(createdAtStr);\n    const endedAt = endedAtStr\n      ? this.dateTimeProvider.of(endedAtStr)\n      : undefined;\n\n    return {\n      id,\n      createdAt,\n      endedAt,\n    };\n  }\n}\n\n$lock[KIND] = LockDescriptor;\n\nexport interface LockResult {\n  id: string;\n  createdAt: DateTime;\n  endedAt?: DateTime;\n  response?: string;\n}\n","import { $inject } from \"alepha\";\nimport { DateTimeProvider, type Timeout } from \"alepha/datetime\";\nimport { $logger } from \"alepha/logger\";\nimport type { LockProvider } from \"./LockProvider.ts\";\n\n/**\n * A simple in-memory store provider.\n */\nexport class MemoryLockProvider implements LockProvider {\n  protected readonly dateTimeProvider = $inject(DateTimeProvider);\n  protected readonly log = $logger();\n\n  /**\n   * The in-memory store.\n   */\n  protected store: Record<string, string> = {};\n\n  /**\n   * Timeouts used to expire keys.\n   */\n  protected storeTimeout: Record<string, Timeout> = {};\n\n  public async set(\n    key: string,\n    value: string,\n    nx?: boolean,\n    px?: number,\n  ): Promise<string> {\n    if (nx && this.store[key] != null) {\n      return this.store[key];\n    }\n\n    if (px) {\n      this.ttl(key, px);\n    }\n\n    this.store[key] = value;\n\n    return this.store[key];\n  }\n\n  public async del(...keys: string[]): Promise<void> {\n    for (const key of keys) {\n      delete this.store[key];\n      if (this.storeTimeout[key] != null) {\n        this.storeTimeout[key].clear();\n        delete this.storeTimeout[key];\n      }\n    }\n  }\n\n  private ttl(key: string, ms: number): void {\n    if (this.storeTimeout[key] != null) {\n      this.storeTimeout[key].clear();\n      delete this.storeTimeout[key];\n    }\n\n    this.storeTimeout[key] = this.dateTimeProvider.createTimeout(() => {\n      delete this.store[key];\n      delete this.storeTimeout[key];\n    }, ms);\n  }\n}\n","import { $module } from \"alepha\";\nimport { MemoryTopicProvider } from \"alepha/topic\";\nimport { $lock } from \"./descriptors/$lock.ts\";\nimport { LockProvider } from \"./providers/LockProvider.ts\";\nimport { LockTopicProvider } from \"./providers/LockTopicProvider.ts\";\nimport { MemoryLockProvider } from \"./providers/MemoryLockProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport * from \"./descriptors/$lock.ts\";\nexport * from \"./providers/LockProvider.ts\";\nexport * from \"./providers/LockTopicProvider.ts\";\nexport * from \"./providers/MemoryLockProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\n/**\n * Lock a resource for a certain period of time.\n *\n * This module provides a memory implementation of the lock provider.\n * You probably want to use an implementation like RedisLockProvider for distributed systems.\n *\n * @see {@link $lock}\n * @module alepha.lock\n */\nexport const AlephaLock = $module({\n  name: \"alepha.lock\",\n  descriptors: [$lock],\n  services: [LockProvider, MemoryLockProvider, LockTopicProvider],\n  register: (alepha) =>\n    alepha\n      .with({\n        optional: true,\n        provide: LockTopicProvider,\n        use: MemoryTopicProvider,\n      })\n      .with({\n        optional: true,\n        provide: LockProvider,\n        use: MemoryLockProvider,\n      }),\n});\n"],"mappings":"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"}

package/dist/lock/index.d.cts

@@ -1,361 +0,0 @@
-import * as alepha1 from "alepha";
-import { AsyncFn, Descriptor, KIND, Static } from "alepha";
-import * as alepha_logger0 from "alepha/logger";
-import * as dayjs_plugin_duration_js0 from "dayjs/plugin/duration.js";
-import * as alepha_topic0 from "alepha/topic";
-import { TopicProvider } from "alepha/topic";
-import { DateTime, DateTimeProvider, DurationLike, Timeout } from "alepha/datetime";
-
-//#region src/lock/providers/LockProvider.d.ts
-/**
- * Store Provider Interface
- */
-declare abstract class LockProvider {
-  /**
-   * Set the string value of a key.
-   *
-   * @param key The key of the value to set.
-   * @param value The value to set.
-   * @param nx If set to true, the key will only be set if it does not already exist.
-   * @param px Set the specified expire time, in milliseconds.
-   */
-  abstract set(key: string, value: string, nx?: boolean, px?: number): Promise<string>;
-  /**
-   * Remove the specified keys.
-   *
-   * @param keys The keys to delete.
-   */
-  abstract del(...keys: string[]): Promise<void>;
-}
-//#endregion
-//#region src/lock/descriptors/$lock.d.ts
-/**
- * Creates a distributed lock descriptor for ensuring single-instance execution across processes.
- *
- * Prevents multiple instances of the same operation from running simultaneously, essential for
- * maintaining data consistency and preventing race conditions in distributed applications.
- *
- * **Key Features**
- * - Distributed coordination across multiple processes, servers, and containers
- * - Automatic expiration to prevent deadlocks
- * - Configurable wait behavior (blocking vs. non-blocking)
- * - Optional grace periods for lock extension after completion
- * - Dynamic or static lock keys for fine-grained control
- *
- * **Common Use Cases**
- * - Database migrations and scheduled jobs
- * - File processing and batch operations
- * - Critical section protection and resource initialization
- *
- * @example
- * ```ts
- * class TaskService {
- *   // Basic scheduled task - only one server executes
- *   dailyReport = $lock({
- *     handler: async () => {
- *       const report = await this.generateDailyReport();
- *       await this.sendReportToManagement(report);
- *     }
- *   });
- *
- *   // Migration with wait - all instances wait for completion
- *   migration = $lock({
- *     wait: true,
- *     maxDuration: [10, "minutes"],
- *     handler: async (version: string) => {
- *       await this.runMigrationScripts(version);
- *     }
- *   });
- *
- *   // Dynamic lock keys for per-resource locking
- *   processFile = $lock({
- *     name: (fileId: string) => `file-processing:${fileId}`,
- *     gracePeriod: [5, "minutes"],
- *     handler: async (fileId: string) => {
- *       await this.processFileData(fileId);
- *     }
- *   });
- * }
- * ```
- */
-declare const $lock: {
-  <TFunc extends AsyncFn>(options: LockDescriptorOptions<TFunc>): LockDescriptor<TFunc>;
-  [KIND]: typeof LockDescriptor;
-};
-interface LockDescriptorOptions<TFunc extends AsyncFn> {
-  /**
-   * The function to execute when the lock is successfully acquired.
-   *
-   * This function:
-   * - Only executes on the instance that successfully acquires the lock
-   * - Has exclusive access to the protected resource during execution
-   * - Should contain the critical section logic that must not run concurrently
-   * - Can be async and perform any operations needed
-   * - Will automatically release the lock upon completion or error
-   * - Has access to the full Alepha dependency injection container
-   *
-   * **Handler Design Guidelines**:
-   * - Keep critical sections as short as possible to minimize lock contention
-   * - Include proper error handling to ensure locks are released
-   * - Use timeouts for external operations to prevent deadlocks
-   * - Log important operations for debugging and monitoring
-   * - Consider idempotency for handlers that might be retried
-   *
-   * @param ...args - The arguments passed to the lock execution
-   * @returns Promise that resolves when the protected operation is complete
-   *
-   * @example
-   * ```ts
-   * handler: async (batchId: string) => {
-   *   console.log(`Processing batch ${batchId} - only one instance will run this`);
-   *
-   *   const batch = await this.getBatchData(batchId);
-   *   const results = await this.processBatchItems(batch.items);
-   *   await this.saveBatchResults(batchId, results);
-   *
-   *   console.log(`Batch ${batchId} completed successfully`);
-   * }
-   * ```
-   */
-  handler: TFunc;
-  /**
-   * Whether the lock should wait for other instances to complete before giving up.
-   *
-   * **wait = false (default)**:
-   * - Non-blocking behavior - if lock is held, immediately return without executing
-   * - Perfect for scheduled tasks where you only want one execution per trigger
-   * - Use when multiple triggers are acceptable but concurrent execution is not
-   * - Examples: periodic cleanup, cron jobs, background maintenance
-   *
-   * **wait = true**:
-   * - Blocking behavior - wait for the current lock holder to finish
-   * - All instances will eventually execute (one after another)
-   * - Perfect for initialization tasks where all instances need the work completed
-   * - Examples: database migrations, cache warming, resource initialization
-   *
-   * **Trade-offs**:
-   * - Non-waiting: Better performance, may miss executions if timing is off
-   * - Waiting: Guaranteed execution order, slower overall throughput
-   *
-   * @default false
-   *
-   * @example
-   * ```ts
-   * // Scheduled task - don't wait, just skip if already running
-   * scheduledCleanup = $lock({
-   *   wait: false,  // Skip if cleanup already running
-   *   handler: async () => { } // perform cleanup
-   * });
-   *
-   * // Migration - wait for completion before proceeding
-   * migration = $lock({
-   *   wait: true,   // All instances wait for migration to complete
-   *   handler: async () => { } // perform migration
-   * });
-   * ```
-   */
-  wait?: boolean;
-  /**
-   * The unique identifier for the lock.
-   *
-   * Can be either:
-   * - **Static string**: A fixed identifier for the lock
-   * - **Dynamic function**: A function that generates the lock key based on arguments
-   *
-   * **Dynamic Lock Keys**:
-   * - Enable per-resource locking (e.g., per-user, per-file, per-product)
-   * - Allow fine-grained concurrency control
-   * - Prevent unnecessary blocking between unrelated operations
-   *
-   * **Key Design Guidelines**:
-   * - Use descriptive names that indicate the protected resource
-   * - Include relevant identifiers for dynamic keys
-   * - Keep keys reasonably short but unique
-   * - Consider using hierarchical naming (e.g., "service:operation:resource")
-   *
-   * If not provided, defaults to `{serviceName}:{propertyKey}`.
-   *
-   * @example "user-migration"
-   * @example "daily-report-generation"
-   * @example (userId: string) => `user-profile-update:${userId}`
-   * @example (fileId: string, operation: string) => `file-${operation}:${fileId}`
-   *
-   * @example
-   * ```ts
-   * // Static lock key - all instances compete for the same lock
-   * globalCleanup = $lock({
-   *   name: "system-cleanup",
-   *   handler: async () => { } // perform cleanup
-   * });
-   *
-   * // Dynamic lock key - per-user locks, users don't block each other
-   * updateUserProfile = $lock({
-   *   name: (userId: string) => `user-update:${userId}`,
-   *   handler: async (userId: string, data: UserData) => {
-   *     // Only one update per user at a time, but different users can update concurrently
-   *   }
-   * });
-   * ```
-   */
-  name?: string | ((...args: Parameters<TFunc>) => string);
-  /**
-   * Maximum duration the lock can be held before it expires automatically.
-   *
-   * This prevents deadlocks when a process dies while holding a lock or when
-   * operations take longer than expected. The lock will be automatically released
-   * after this duration, allowing other instances to proceed.
-   *
-   * **Duration Guidelines**:
-   * - Set based on expected operation duration plus safety margin
-   * - Too short: Operations may be interrupted by early expiration
-   * - Too long: Failed processes block others for extended periods
-   * - Consider worst-case scenarios and external dependency timeouts
-   *
-   * **Typical Values**:
-   * - Quick operations: 30 seconds - 2 minutes
-   * - Database operations: 5 - 15 minutes
-   * - File processing: 10 - 30 minutes
-   * - Large migrations: 30 minutes - 2 hours
-   *
-   * @default [5, "minutes"]
-   *
-   * @example [30, "seconds"]    // Quick operations
-   * @example [10, "minutes"]    // Database migrations
-   * @example [1, "hour"]        // Long-running batch jobs
-   *
-   * @example
-   * ```ts
-   * quickTask = $lock({
-   *   maxDuration: [2, "minutes"],  // Quick timeout for fast operations
-   *   handler: async () => { } // perform quick task
-   * });
-   *
-   * heavyProcessing = $lock({
-   *   maxDuration: [30, "minutes"], // Longer timeout for heavy work
-   *   handler: async () => { } // perform heavy processing
-   * });
-   * ```
-   */
-  maxDuration?: DurationLike;
-  /**
-   * Additional time to keep the lock active after the handler completes successfully.
-   *
-   * This provides a "cooling off" period that can be useful for:
-   * - Preventing immediate re-execution of the same operation
-   * - Giving time for related systems to process the results
-   * - Avoiding race conditions with dependent operations
-   * - Providing a buffer for cleanup operations
-   *
-   * Can be either:
-   * - **Static duration**: Fixed grace period for all executions
-   * - **Dynamic function**: Grace period determined by execution arguments
-   * - **undefined**: No grace period, lock released immediately after completion
-   *
-   * **Grace Period Use Cases**:
-   * - File processing: Prevent immediate reprocessing of uploaded files
-   * - Cache updates: Allow time for cache propagation
-   * - Batch operations: Prevent overlapping batch processing
-   * - External API calls: Respect rate limiting requirements
-   *
-   * @default undefined (no grace period)
-   *
-   * @example [5, "minutes"]     // Fixed 5-minute grace period
-   * @example [30, "seconds"]    // Short grace for quick operations
-   * @example (userId: string) => userId.startsWith("premium") ? [10, "minutes"] : [2, "minutes"]
-   *
-   * @example
-   * ```ts
-   * fileProcessor = $lock({
-   *   gracePeriod: [10, "minutes"],  // Prevent reprocessing same file immediately
-   *   handler: async (filePath: string) => {
-   *     await this.processFile(filePath);
-   *   }
-   * });
-   *
-   * userOperation = $lock({
-   *   gracePeriod: (userId: string, operation: string) => {
-   *     // Dynamic grace based on operation type
-   *     return operation === 'migration' ? [30, "minutes"] : [5, "minutes"];
-   *   },
-   *   handler: async (userId: string, operation: string) => {
-   *     await this.performUserOperation(userId, operation);
-   *   }
-   * });
-   * ```
-   */
-  gracePeriod?: ((...args: Parameters<TFunc>) => DurationLike | undefined) | DurationLike;
-}
-declare const envSchema: alepha1.TObject<{
-  LOCK_PREFIX_KEY: alepha1.TString;
-}>;
-declare module "alepha" {
-  interface Env extends Partial<Static<typeof envSchema>> {}
-}
-declare class LockDescriptor<TFunc extends AsyncFn> extends Descriptor<LockDescriptorOptions<TFunc>> {
-  protected readonly log: alepha_logger0.Logger;
-  protected readonly provider: LockProvider;
-  protected readonly env: {
-    LOCK_PREFIX_KEY: string;
-  };
-  protected readonly dateTimeProvider: DateTimeProvider;
-  protected readonly id: `${string}-${string}-${string}-${string}-${string}`;
-  readonly maxDuration: dayjs_plugin_duration_js0.Duration;
-  protected readonly topicLockEnd: alepha_topic0.TopicDescriptor<{
-    payload: alepha1.TObject<{
-      name: alepha1.TString;
-    }>;
-  }>;
-  run(...args: Parameters<TFunc>): Promise<void>;
-  /**
-   * Set the lock for the given key.
-   */
-  protected lock(key: string): Promise<LockResult>;
-  protected setGracePeriod(key: string, lock: LockResult, ...args: Parameters<TFunc>): Promise<void>;
-  protected wait(key: string, maxDuration: DurationLike): Promise<void>;
-  protected key(...args: Parameters<TFunc>): string;
-  protected parse(value: string): LockResult;
-}
-interface LockResult {
-  id: string;
-  createdAt: DateTime;
-  endedAt?: DateTime;
-  response?: string;
-}
-//#endregion
-//#region src/lock/providers/LockTopicProvider.d.ts
-declare abstract class LockTopicProvider extends TopicProvider {}
-//#endregion
-//#region src/lock/providers/MemoryLockProvider.d.ts
-/**
- * A simple in-memory store provider.
- */
-declare class MemoryLockProvider implements LockProvider {
-  protected readonly dateTimeProvider: DateTimeProvider;
-  protected readonly log: alepha_logger0.Logger;
-  /**
-   * The in-memory store.
-   */
-  protected store: Record<string, string>;
-  /**
-   * Timeouts used to expire keys.
-   */
-  protected storeTimeout: Record<string, Timeout>;
-  set(key: string, value: string, nx?: boolean, px?: number): Promise<string>;
-  del(...keys: string[]): Promise<void>;
-  private ttl;
-}
-//#endregion
-//#region src/lock/index.d.ts
-/**
- * Lock a resource for a certain period of time.
- *
- * This module provides a memory implementation of the lock provider.
- * You probably want to use an implementation like RedisLockProvider for distributed systems.
- *
- * @see {@link $lock}
- * @module alepha.lock
- */
-declare const AlephaLock: alepha1.Service<alepha1.Module>;
-//#endregion
-export { $lock, AlephaLock, LockDescriptor, LockDescriptorOptions, LockProvider, LockResult, LockTopicProvider, MemoryLockProvider };
-//# sourceMappingURL=index.d.cts.map