alepha 0.15.0 → 0.15.2

package/dist/lock/core/index.d.ts

@@ -12,19 +12,19 @@ import * as dayjs_plugin_duration_js0 from "dayjs/plugin/duration.js";
  */
 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.
-       */
+   * 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.
-       */
+   * Remove the specified keys.
+   *
+   * @param keys The keys to delete.
+   */
   abstract del(...keys: string[]): Promise<void>;
 }
 //#endregion
@@ -84,205 +84,205 @@ declare const $lock: {
 };
 interface LockPrimitiveOptions<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`);
-       * }
-       * ```
-       */
+   * 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
-       * });
-       * ```
-       */
+   * 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
-       *   }
-       * });
-       * ```
-       */
+   * 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
-       * });
-       * ```
-       */
+   * 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);
-       *   }
-       * });
-       * ```
-       */
+   * 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<{
@@ -307,8 +307,8 @@ declare class LockPrimitive<TFunc extends AsyncFn> extends Primitive<LockPrimiti
   }>;
   run(...args: Parameters<TFunc>): Promise<void>;
   /**
-       * Set the lock for the given key.
-       */
+   * 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>;
@@ -333,12 +333,12 @@ declare class MemoryLockProvider implements LockProvider {
   protected readonly dateTimeProvider: DateTimeProvider;
   protected readonly log: alepha_logger0.Logger;
   /**
-       * The in-memory store.
-       */
+   * The in-memory store.
+   */
   protected store: Record<string, string>;
   /**
-       * Timeouts used to expire keys.
-       */
+   * 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>;
@@ -347,12 +347,19 @@ declare class MemoryLockProvider implements LockProvider {
 //#endregion
 //#region ../../src/lock/core/index.d.ts
 /**
- * Lock a resource for a certain period of time.
+ * | type | quality | stability |
+ * |------|---------|-----------|
+ * | backend | rare | stable |
  *
- * This module provides a memory implementation of the lock provider.
- * You probably want to use an implementation like RedisLockProvider for distributed systems.
+ * Resource locking for distributed systems.
+ *
+ * **Features:**
+ * - Distributed locks with timeout
+ * - Time-based lock expiration
+ * - Automatic release on scope exit
+ * - Distributed coordination via Redis
+ * - Providers: Memory (dev), Redis (production)
  *
- * @see {@link $lock}
  * @module alepha.lock
  */
 declare const AlephaLock: alepha1.Service<alepha1.Module>;

package/dist/lock/core/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../../../src/lock/core/providers/LockProvider.ts","../../../src/lock/core/primitives/$lock.ts","../../../src/lock/core/providers/LockTopicProvider.ts","../../../src/lock/core/providers/MemoryLockProvider.ts","../../../src/lock/core/index.ts"],"mappings":"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"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../../src/lock/core/providers/LockProvider.ts","../../../src/lock/core/primitives/$lock.ts","../../../src/lock/core/providers/LockTopicProvider.ts","../../../src/lock/core/providers/MemoryLockProvider.ts","../../../src/lock/core/index.ts"],"mappings":";;;;;;;;;;;;uBAGsB,YAAA;;;;;;AAAtB;;;WASkB,GAAA,CACd,GAAA,UACA,KAAA,UACA,EAAA,YACA,EAAA,YACC,OAAA;EALa;;;;;EAAA,SAYA,GAAA,CAAA,GAAO,IAAA,aAAiB,OAAA;AAAA;;;;;;;;;AArB1C;;;;;;;;;;;;;;;;;;ACkEA;;;;;;;;;;;;;;;;;;;;;;;AAQA;;cARa,KAAA;EAAA,eAAuB,OAAA,EAAO,OAAA,EAChC,oBAAA,CAAqB,KAAA,IAC7B,aAAA,CAAc,KAAA;EAAA;;UAMA,oBAAA,eAAmC,OAAA;EA6JpC;;;;;;;;;;;;;;;;;;;;;;;;;;AAmDf;;;;;;;;EA7KC,OAAA,EAAS,KAAA;;;;;;;;;;;;;;;;AAyLX;;;;;;;;;;;;;;;;;;;;;EAnJE,IAAA;EAyP+C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA7M/C,IAAA,iBAAqB,IAAA,EAAM,UAAA,CAAW,KAAA;EAyLjC;;;;;;;;;;;;;;;;;;AAgEP;;;;;;;;;;;;;;;ACzbA;;;;;EDwOE,WAAA,GAAc,YAAA;;;AElOhB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACwBA;;;;;;EH0PE,WAAA,QACS,IAAA,EAAM,UAAA,CAAW,KAAA,MAAW,YAAA,gBACjC,YAAA;AAAA;AAAA,cAKA,SAAA,EAEJ,OAAA,CAFa,OAAA;mBAEb,OAAA,CAAA,OAAA;AAAA;AAAA;EAAA,UAGU,GAAA,SAAY,OAAA,CAAQ,MAAA,QAAc,SAAA;AAAA;AAAA,cAGjC,aAAA,eAA4B,OAAA,UAAiB,SAAA,CACxD,oBAAA,CAAqB,KAAA;EAAA,mBAEF,GAAA,EAFC,cAAA,CAEE,MAAA;EAAA,mBACH,QAAA,EAAQ,YAAA;EAAA,mBACR,GAAA;;;qBACA,gBAAA,EAAgB,gBAAA;EAAA,mBAChB,EAAA;EAAA,SACH,WAAA,EAFmB,yBAAA,CAER,QAAA;EAAA,mBAIR,YAAA,gBAAY,cAAA;;YAJJ,OAAA,CAAA,OAAA;IAAA;EAAA;EAcd,GAAA,CAAA,GAAO,IAAA,EAAM,UAAA,CAAW,KAAA,IAAS,OAAA;;;;YA8C9B,IAAA,CAAK,GAAA,WAAc,OAAA,CAAQ,UAAA;EAAA,UAW3B,cAAA,CACd,GAAA,UACA,IAAA,EAAM,UAAA,KACH,IAAA,EAAM,UAAA,CAAW,KAAA,IACnB,OAAA;EAAA,UAmBa,IAAA,CAAK,GAAA,UAAa,WAAA,EAAa,YAAA,GAAe,OAAA;EAAA,UAWpD,GAAA,CAAA,GAAO,IAAA,EAAM,UAAA,CAAW,KAAA;EAAA,UAgBxB,KAAA,CAAM,KAAA,WAAgB,UAAA;AAAA;AAAA,UAiBjB,UAAA;EACf,EAAA;EACA,SAAA,EAAW,QAAA;EACX,OAAA,GAAU,QAAA;EACV,QAAA;AAAA;;;uBC7boB,iBAAA,SAA0B,aAAA;;;;;;cCMnC,kBAAA,YAA8B,YAAA;EAAA,mBACtB,gBAAA,EAAgB,gBAAA;EAAA,mBAChB,GAAA,EADgB,cAAA,CACb,MAAA;;AHPxB;;YGYY,KAAA,EAAO,MAAA;EHS8B;;;EAAA,UGJrC,YAAA,EAAc,MAAA,SAAe,OAAA;EAE1B,GAAA,CACX,GAAA,UACA,KAAA,UACA,EAAA,YACA,EAAA,YACC,OAAA;EAcU,GAAA,CAAA,GAAO,IAAA,aAAiB,OAAA;EAAA,QAU7B,GAAA;AAAA;;;;;;;;AHhDV;;;;;;;;;;;cI6Ba,UAAA,EAAU,OAAA,CAAA,OAAA,CAgBrB,OAAA,CAhBqB,MAAA"}

package/dist/lock/core/index.js

@@ -189,12 +189,19 @@ var MemoryLockProvider = class {
 //#endregion
 //#region ../../src/lock/core/index.ts
 /**
-* Lock a resource for a certain period of time.
+* | type | quality | stability |
+* |------|---------|-----------|
+* | backend | rare | stable |
 *
-* This module provides a memory implementation of the lock provider.
-* You probably want to use an implementation like RedisLockProvider for distributed systems.
+* Resource locking for distributed systems.
+*
+* **Features:**
+* - Distributed locks with timeout
+* - Time-based lock expiration
+* - Automatic release on scope exit
+* - Distributed coordination via Redis
+* - Providers: Memory (dev), Redis (production)
 *
-* @see {@link $lock}
 * @module alepha.lock
 */
 const AlephaLock = $module({

package/dist/lock/core/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../../src/lock/core/providers/LockProvider.ts","../../../src/lock/core/providers/LockTopicProvider.ts","../../../src/lock/core/primitives/$lock.ts","../../../src/lock/core/providers/MemoryLockProvider.ts","../../../src/lock/core/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  createPrimitive,\n  KIND,\n  Primitive,\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 primitive 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: LockPrimitiveOptions<TFunc>,\n): LockPrimitive<TFunc> => {\n  return createPrimitive(LockPrimitive<TFunc>, options);\n};\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport interface LockPrimitiveOptions<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 LockPrimitive<TFunc extends AsyncFn> extends Primitive<\n  LockPrimitiveOptions<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] = LockPrimitive;\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 \"./primitives/$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 \"./primitives/$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  primitives: [$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":";;;;;;;;;AAGA,IAAsB,eAAtB,MAAmC;;;;ACDnC,IAAsB,oBAAtB,cAAgD,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACmE9D,MAAa,SACX,YACyB;AACzB,QAAO,gBAAgB,eAAsB,QAAQ;;AAyNvD,MAAM,YAAY,EAAE,OAAO,EACzB,iBAAiB,EAAE,KAAK,EAAE,SAAS,QAAQ,CAAC,EAC7C,CAAC;AAMF,IAAa,gBAAb,cAA0D,UAExD;CACA,AAAmB,MAAM,SAAS;CAClC,AAAmB,WAAW,QAAQ,aAAa;CACnD,AAAmB,MAAM,KAAK,UAAU;CACxC,AAAmB,mBAAmB,QAAQ,iBAAiB;CAC/D,AAAmB,KAAK,OAAO,YAAY;CAC3C,AAAgB,cAAc,KAAK,iBAAiB,SAClD,KAAK,QAAQ,eAAe,CAAC,GAAG,UAAU,CAC3C;CAED,AAAmB,eAAe,OAAO;EACvC,MAAM,GAAG,KAAK,IAAI,gBAAgB;EAClC,UAAU;EACV,QAAQ,EACN,SAAS,EAAE,OAAO,EAChB,MAAM,EAAE,MAAM,EACf,CAAC,EACH;EACF,CAAC;CAEF,MAAa,IAAI,GAAG,MAAwC;EAC1D,MAAM,MAAM,KAAK,IAAI,GAAG,KAAK;EAC7B,MAAM,UAAU,KAAK,QAAQ;EAE7B,MAAM,OAAO,MAAM,KAAK,KAAK,IAAI;AACjC,MAAI,KAAK,QACP;AAGF,MAAI,KAAK,OAAO,KAAK,IAAI;AACvB,OAAI,KAAK,QAAQ,KACf,KAAI;AACF,UAAM,KAAK,KAAK,KAAK,KAAK,YAAY;YAC/B,OAAO;AACd,QAAI,iBAAiB,mBAAmB;AACtC,UAAK,IAAI,KACP,qBAAqB,IAAI,8BAC1B;AACD,WAAM,KAAK,IAAI,GAAG,KAAK;UAEvB,OAAM;;AAKZ;;AAGF,OAAK,IAAI,MAAM,SAAS,IAAI,OAAO;AAEnC,MAAI;AACF,SAAM,QAAQ,GAAG,KAAK;YACd;AACR,SAAM,KAAK,aAAa,QAAQ,EAC9B,MAAM,KACP,CAAC;AAEF,SAAM,KAAK,eAAe,KAAK,MAAM,GAAG,KAAK;AAE7C,QAAK,IAAI,MAAM,SAAS,IAAI,MAAM;;;;;;CAOtC,MAAgB,KAAK,KAAkC;EACrD,MAAM,QAAQ,MAAM,KAAK,SAAS,IAChC,KACA,GAAG,KAAK,GAAG,GAAG,KAAK,iBAAiB,cAAc,IAClD,MACA,KAAK,YAAY,GAAG,eAAe,CACpC;AAED,SAAO,KAAK,MAAM,MAAM;;CAG1B,MAAgB,eACd,KACA,MACA,GAAG,MACY;EACf,MAAM,cAAc,KAAK,QAAQ,cAC7B,KAAK,iBAAiB,eAAe,KAAK,QAAQ,YAAY,GAC5D,KAAK,QAAQ,cACb,KAAK,QAAQ,YAAY,GAAG,KAAK,GACnC;AAEJ,MAAI,YACF,OAAM,KAAK,SAAS,IAClB,KACA,GAAG,KAAK,GAAG,GAAG,KAAK,UAAU,aAAa,CAAC,GAAG,KAAK,iBAAiB,cAAc,IAClF,OACA,KAAK,iBAAiB,SAAS,YAAY,CAAC,GAAG,eAAe,CAC/D;MAED,OAAM,KAAK,SAAS,IAAI,IAAI;;CAIhC,MAAgB,KAAK,KAAa,aAA0C;AAC1E,OAAK,IAAI,MAAM,kBAAkB,IAAI,OAAO;AAE5C,QAAM,KAAK,aAAa,KAAK;GAC3B,SAAS,YAAY,QAAQ,QAAQ,SAAS;GAC9C,SAAS;GACV,CAAC;AAEF,OAAK,IAAI,MAAM,kBAAkB,IAAI,MAAM;;CAG7C,AAAU,IAAI,GAAG,MAAyB;EACxC,IAAI,OAAO;AAEX,MAAI,KAAK,QAAQ,KACf,KAAI,OAAO,KAAK,QAAQ,SAAS,SAC/B,QAAO,KAAK,QAAQ;MAEpB,QAAO,KAAK,QAAQ,KAAK,GAAG,KAAK;MAGnC,QAAO,GAAG,KAAK,OAAO,QAAQ,KAAK,GAAG,KAAK,OAAO;AAGpD,SAAO,GAAG,KAAK,IAAI,gBAAgB,GAAG;;CAGxC,AAAU,MAAM,OAA2B;EACzC,MAAM,CAAC,IAAI,cAAc,cAAc,MAAM,MAAM,IAAI;AAMvD,SAAO;GACL;GACA,WAPgB,KAAK,iBAAiB,GAAG,aAAa;GAQtD,SAPc,aACZ,KAAK,iBAAiB,GAAG,WAAW,GACpC;GAMH;;;AAIL,MAAM,QAAQ;;;;;;;ACjbd,IAAa,qBAAb,MAAwD;CACtD,AAAmB,mBAAmB,QAAQ,iBAAiB;CAC/D,AAAmB,MAAM,SAAS;;;;CAKlC,AAAU,QAAgC,EAAE;;;;CAK5C,AAAU,eAAwC,EAAE;CAEpD,MAAa,IACX,KACA,OACA,IACA,IACiB;AACjB,MAAI,MAAM,KAAK,MAAM,QAAQ,KAC3B,QAAO,KAAK,MAAM;AAGpB,MAAI,GACF,MAAK,IAAI,KAAK,GAAG;AAGnB,OAAK,MAAM,OAAO;AAElB,SAAO,KAAK,MAAM;;CAGpB,MAAa,IAAI,GAAG,MAA+B;AACjD,OAAK,MAAM,OAAO,MAAM;AACtB,UAAO,KAAK,MAAM;AAClB,OAAI,KAAK,aAAa,QAAQ,MAAM;AAClC,SAAK,aAAa,KAAK,OAAO;AAC9B,WAAO,KAAK,aAAa;;;;CAK/B,AAAQ,IAAI,KAAa,IAAkB;AACzC,MAAI,KAAK,aAAa,QAAQ,MAAM;AAClC,QAAK,aAAa,KAAK,OAAO;AAC9B,UAAO,KAAK,aAAa;;AAG3B,OAAK,aAAa,OAAO,KAAK,iBAAiB,oBAAoB;AACjE,UAAO,KAAK,MAAM;AAClB,UAAO,KAAK,aAAa;KACxB,GAAG;;;;;;;;;;;;;;;ACnCV,MAAa,aAAa,QAAQ;CAChC,MAAM;CACN,YAAY,CAAC,MAAM;CACnB,UAAU;EAAC;EAAc;EAAoB;EAAkB;CAC/D,WAAW,WACT,OACG,KAAK;EACJ,UAAU;EACV,SAAS;EACT,KAAK;EACN,CAAC,CACD,KAAK;EACJ,UAAU;EACV,SAAS;EACT,KAAK;EACN,CAAC;CACP,CAAC"}
+{"version":3,"file":"index.js","names":[],"sources":["../../../src/lock/core/providers/LockProvider.ts","../../../src/lock/core/providers/LockTopicProvider.ts","../../../src/lock/core/primitives/$lock.ts","../../../src/lock/core/providers/MemoryLockProvider.ts","../../../src/lock/core/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  createPrimitive,\n  KIND,\n  Primitive,\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 primitive 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: LockPrimitiveOptions<TFunc>,\n): LockPrimitive<TFunc> => {\n  return createPrimitive(LockPrimitive<TFunc>, options);\n};\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport interface LockPrimitiveOptions<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 LockPrimitive<TFunc extends AsyncFn> extends Primitive<\n  LockPrimitiveOptions<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] = LockPrimitive;\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 \"./primitives/$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 \"./primitives/$lock.ts\";\nexport * from \"./providers/LockProvider.ts\";\nexport * from \"./providers/LockTopicProvider.ts\";\nexport * from \"./providers/MemoryLockProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\n/**\n * | type | quality | stability |\n * |------|---------|-----------|\n * | backend | rare | stable |\n *\n * Resource locking for distributed systems.\n *\n * **Features:**\n * - Distributed locks with timeout\n * - Time-based lock expiration\n * - Automatic release on scope exit\n * - Distributed coordination via Redis\n * - Providers: Memory (dev), Redis (production)\n *\n * @module alepha.lock\n */\nexport const AlephaLock = $module({\n  name: \"alepha.lock\",\n  primitives: [$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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"}