alepha 0.21.2 → 0.22.0

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

@@ -1,11 +1,6 @@
-import * as _$alepha from "alepha";
 import { AsyncFn, Middleware, Primitive, Static } from "alepha";
-import * as _$alepha_topic0 from "alepha/topic";
 import { TopicProvider } from "alepha/topic";
-import * as _$alepha_datetime0 from "alepha/datetime";
 import { DateTime, DateTimeProvider, DurationLike, Timeout } from "alepha/datetime";
-import * as _$alepha_logger0 from "alepha/logger";
-import * as _$typebox from "typebox";
 
 //#region ../../src/lock/core/providers/LockProvider.d.ts
 /**
@@ -272,8 +267,8 @@ interface LockPrimitiveOptions<TFunc extends AsyncFn> {
 /**
  * Lock configuration atom.
  */
-declare const lockOptions: _$alepha.Atom<_$typebox.TObject<{
-  prefixKey: _$typebox.TString;
+declare const lockOptions: import("alepha").Atom<import("typebox").TObject<{
+  prefixKey: import("typebox").TString;
 }>, "alepha.lock.options">;
 type LockAtomOptions = Static<typeof lockOptions.schema>;
 declare module "alepha" {
@@ -282,7 +277,7 @@ declare module "alepha" {
   }
 }
 declare class LockPrimitive<TFunc extends AsyncFn> extends Primitive<LockPrimitiveOptions<TFunc>> {
-  protected readonly log: _$alepha_logger0.Logger;
+  protected readonly log: import("alepha/logger").Logger;
   protected readonly provider: LockProvider;
   protected readonly settings: Readonly<{
     prefixKey: string;
@@ -294,10 +289,10 @@ declare class LockPrimitive<TFunc extends AsyncFn> extends Primitive<LockPrimiti
    */
   protected _id?: string;
   protected get id(): string;
-  readonly maxDuration: _$alepha_datetime0.Duration;
-  protected readonly topicLockEnd: _$alepha_topic0.TopicPrimitive<{
-    payload: _$typebox.TObject<{
-      name: _$typebox.TString;
+  readonly maxDuration: import("alepha/datetime").Duration;
+  protected readonly topicLockEnd: import("alepha/topic").TopicPrimitive<{
+    payload: import("typebox").TObject<{
+      name: import("typebox").TString;
     }>;
   }>;
   run(...args: Parameters<TFunc>): Promise<void>;
@@ -326,7 +321,7 @@ declare abstract class LockTopicProvider extends TopicProvider {}
  */
 declare class MemoryLockProvider implements LockProvider {
   protected readonly dateTimeProvider: DateTimeProvider;
-  protected readonly log: _$alepha_logger0.Logger;
+  protected readonly log: import("alepha/logger").Logger;
   /**
    * The in-memory store.
    */
@@ -381,7 +376,7 @@ declare module "alepha" {
  *
  * @module alepha.lock
  */
-declare const AlephaLock: _$alepha.Service<_$alepha.Module>;
+declare const AlephaLock: import("alepha").Service<import("alepha").Module>;
 //#endregion
 export { $lock, AlephaLock, LockAtomOptions, LockMiddlewareOptions, LockPrimitive, LockPrimitiveOptions, LockProvider, LockResult, LockTopicProvider, MemoryLockProvider, lockOptions };
 //# sourceMappingURL=index.d.ts.map

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":"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"}

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/providers/MemoryLockProvider.ts","../../../src/lock/core/errors/LockAcquireError.ts","../../../src/lock/core/primitives/$lock.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 { $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  protected 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 { AlephaError } from \"alepha\";\n\nexport class LockAcquireError extends AlephaError {\n  constructor(name: string) {\n    super(`$lock: could not acquire lock '${name}'`);\n  }\n}\n","import {\n  $atom,\n  $context,\n  $inject,\n  $state,\n  AlephaError,\n  type AsyncFn,\n  createMiddleware,\n  type Middleware,\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 } from \"alepha/topic\";\nimport { LockAcquireError } from \"../errors/LockAcquireError.ts\";\nimport { LockProvider } from \"../providers/LockProvider.ts\";\nimport { LockTopicProvider } from \"../providers/LockTopicProvider.ts\";\n\n/**\n * Distributed lock middleware for `use` arrays in `$action`, `$job`, `$page`, `$pipeline`.\n *\n * Acquires a distributed lock before the handler runs and releases it after completion.\n * Throws `LockAcquireError` if the lock cannot be acquired (unless `wait: true`).\n *\n * ```ts\n * processOrder = $action({\n *   use: [$lock({ name: \"process-order\" })],\n *   handler: async ({ body }) => { ... },\n * });\n * ```\n */\nexport const $lock = (options: LockMiddlewareOptions): Middleware => {\n  const { alepha } = $context();\n  const lockProvider = alepha.inject(LockProvider);\n  const dateTimeProvider = alepha.inject(DateTimeProvider);\n\n  return createMiddleware({\n    name: \"$lock\",\n    options: options as unknown as Record<string, unknown>,\n    handler: ({ alepha, next }) => {\n      const id = crypto.randomUUID();\n      const maxDurationMs = dateTimeProvider\n        .duration(options.maxDuration ?? [5, \"minutes\"])\n        .asMilliseconds();\n\n      return async (...args: any[]) => {\n        const name =\n          typeof options.name === \"function\"\n            ? options.name(...args)\n            : options.name;\n        if (!name) {\n          throw new AlephaError(\n            \"$lock middleware requires a name option (no class context available)\",\n          );\n        }\n\n        const value = await lockProvider.set(\n          name,\n          `${id},${dateTimeProvider.nowISOString()}`,\n          true,\n          maxDurationMs,\n        );\n\n        const [lockId, _createdAtStr, endedAtStr] = value.split(\",\");\n\n        // Lock already ended (grace period active)\n        if (endedAtStr) {\n          await alepha.events.emit(\"lock:contended\", { name, id });\n          throw new LockAcquireError(name);\n        }\n\n        // Lock held by someone else\n        if (lockId !== id) {\n          await alepha.events.emit(\"lock:contended\", { name, id });\n          if (options.wait) {\n            // Poll until lock is released\n            const start = dateTimeProvider.nowMillis();\n            while (dateTimeProvider.nowMillis() - start < maxDurationMs) {\n              await dateTimeProvider.wait(500);\n              const current = await lockProvider.set(\n                name,\n                `${id},${dateTimeProvider.nowISOString()}`,\n                true,\n                maxDurationMs,\n              );\n              const [currentId] = current.split(\",\");\n              if (currentId === id) {\n                break;\n              }\n            }\n            // Check if we got the lock\n            const final = await lockProvider.set(\n              name,\n              `${id},${dateTimeProvider.nowISOString()}`,\n              true,\n              maxDurationMs,\n            );\n            const [finalId] = final.split(\",\");\n            if (finalId !== id) {\n              throw new LockAcquireError(name);\n            }\n          } else {\n            throw new LockAcquireError(name);\n          }\n        }\n\n        // We hold the lock — execute handler\n        const acquiredAt = dateTimeProvider.nowMillis();\n        await alepha.events.emit(\"lock:acquired\", {\n          name,\n          id,\n          maxDurationMs,\n        });\n        try {\n          return await next(...args);\n        } finally {\n          await lockProvider.del(name);\n          await alepha.events.emit(\"lock:released\", {\n            name,\n            id,\n            heldMs: dateTimeProvider.nowMillis() - acquiredAt,\n          });\n        }\n      };\n    },\n  });\n};\n\n// ---------------------------------------------------------------------------------------------------------------------\n\n/**\n * Options for $lock in middleware mode (no handler).\n */\nexport interface LockMiddlewareOptions {\n  /**\n   * Lock key name. Required in middleware mode (no class context available).\n   * Can be a static string or a function that derives the key from handler args.\n   */\n  name: string | ((...args: any[]) => string);\n\n  /**\n   * Whether to wait for the lock to become available.\n   *\n   * @default false\n   */\n  wait?: boolean;\n\n  /**\n   * Maximum duration the lock can be held before automatic expiration.\n   *\n   * @default [5, \"minutes\"]\n   */\n  maxDuration?: DurationLike;\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\n/**\n * Lock configuration atom.\n */\nexport const lockOptions = $atom({\n  name: \"alepha.lock.options\",\n  schema: t.object({\n    prefixKey: t.text({\n      default: \"\",\n      description: \"Prefix for all lock keys.\",\n    }),\n  }),\n  default: {\n    prefixKey: \"\",\n  },\n});\n\nexport type LockAtomOptions = Static<typeof lockOptions.schema>;\n\ndeclare module \"alepha\" {\n  interface State {\n    [lockOptions.key]: LockAtomOptions;\n  }\n}\n\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 settings = $state(lockOptions);\n  protected readonly dateTimeProvider = $inject(DateTimeProvider);\n\n  /**\n   * Lazy-initialized UUID to avoid calling crypto.randomUUID() in global scope.\n   * Cloudflare Workers doesn't allow random value generation during initialization.\n   */\n  protected _id?: string;\n  protected get id(): string {\n    if (!this._id) {\n      this._id = crypto.randomUUID();\n    }\n    return this._id;\n  }\n\n  public readonly maxDuration = this.dateTimeProvider.duration(\n    this.options.maxDuration ?? [5, \"minutes\"],\n  );\n\n  protected readonly topicLockEnd = $topic({\n    name: `${this.settings.prefixKey}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        // Poll until the lock is released, then re-attempt\n        const start = this.dateTimeProvider.nowMillis();\n        const maxMs = this.maxDuration.as(\"milliseconds\");\n        let acquired = false;\n        while (this.dateTimeProvider.nowMillis() - start < maxMs) {\n          await this.dateTimeProvider.wait(500);\n          const current = await this.lock(key);\n          if (current.id === this.id || !current.id || current.endedAt) {\n            acquired = true;\n            break;\n          }\n        }\n        if (acquired) {\n          return this.run(...args);\n        }\n        this.log.warn(`Lock wait timeout for '${key}', giving up`);\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.settings.prefixKey}${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\nexport interface LockResult {\n  id: string;\n  createdAt: DateTime;\n  endedAt?: DateTime;\n  response?: string;\n}\n","import { $module } from \"alepha\";\nimport { MemoryTopicProvider } from \"alepha/topic\";\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\ndeclare module \"alepha\" {\n  interface Hooks {\n    /**\n     * Fires when a lock is successfully acquired.\n     */\n    \"lock:acquired\": {\n      name: string;\n      id: string;\n      maxDurationMs: number;\n    };\n    /**\n     * Fires when a lock is released (handler completed or threw).\n     */\n    \"lock:released\": {\n      name: string;\n      id: string;\n      heldMs: number;\n    };\n    /**\n     * Fires when a lock acquisition contends with another holder.\n     * Emitted whether the caller eventually acquires (`wait: true`) or fails.\n     */\n    \"lock:contended\": {\n      name: string;\n      id: string;\n    };\n  }\n}\n\n// ---------------------------------------------------------------------------------------------------------------------\n\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  services: [LockProvider, LockTopicProvider],\n  variants: [MemoryLockProvider],\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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"}
+{"version":3,"file":"index.js","names":[],"sources":["../../../src/lock/core/providers/LockProvider.ts","../../../src/lock/core/providers/LockTopicProvider.ts","../../../src/lock/core/providers/MemoryLockProvider.ts","../../../src/lock/core/errors/LockAcquireError.ts","../../../src/lock/core/primitives/$lock.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 { $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  protected 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 { AlephaError } from \"alepha\";\n\nexport class LockAcquireError extends AlephaError {\n  constructor(name: string) {\n    super(`$lock: could not acquire lock '${name}'`);\n  }\n}\n","import {\n  $atom,\n  $context,\n  $inject,\n  $state,\n  AlephaError,\n  type AsyncFn,\n  createMiddleware,\n  type Middleware,\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 } from \"alepha/topic\";\nimport { LockAcquireError } from \"../errors/LockAcquireError.ts\";\nimport { LockProvider } from \"../providers/LockProvider.ts\";\nimport { LockTopicProvider } from \"../providers/LockTopicProvider.ts\";\n\n/**\n * Distributed lock middleware for `use` arrays in `$action`, `$job`, `$page`, `$pipeline`.\n *\n * Acquires a distributed lock before the handler runs and releases it after completion.\n * Throws `LockAcquireError` if the lock cannot be acquired (unless `wait: true`).\n *\n * ```ts\n * processOrder = $action({\n *   use: [$lock({ name: \"process-order\" })],\n *   handler: async ({ body }) => { ... },\n * });\n * ```\n */\nexport const $lock = (options: LockMiddlewareOptions): Middleware => {\n  const { alepha } = $context();\n  const lockProvider = alepha.inject(LockProvider);\n  const dateTimeProvider = alepha.inject(DateTimeProvider);\n\n  return createMiddleware({\n    name: \"$lock\",\n    options: options as unknown as Record<string, unknown>,\n    handler: ({ alepha, next }) => {\n      const id = crypto.randomUUID();\n      const maxDurationMs = dateTimeProvider\n        .duration(options.maxDuration ?? [5, \"minutes\"])\n        .asMilliseconds();\n\n      return async (...args: any[]) => {\n        const name =\n          typeof options.name === \"function\"\n            ? options.name(...args)\n            : options.name;\n        if (!name) {\n          throw new AlephaError(\n            \"$lock middleware requires a name option (no class context available)\",\n          );\n        }\n\n        const value = await lockProvider.set(\n          name,\n          `${id},${dateTimeProvider.nowISOString()}`,\n          true,\n          maxDurationMs,\n        );\n\n        const [lockId, _createdAtStr, endedAtStr] = value.split(\",\");\n\n        // Lock already ended (grace period active)\n        if (endedAtStr) {\n          await alepha.events.emit(\"lock:contended\", { name, id });\n          throw new LockAcquireError(name);\n        }\n\n        // Lock held by someone else\n        if (lockId !== id) {\n          await alepha.events.emit(\"lock:contended\", { name, id });\n          if (options.wait) {\n            // Poll until lock is released\n            const start = dateTimeProvider.nowMillis();\n            while (dateTimeProvider.nowMillis() - start < maxDurationMs) {\n              await dateTimeProvider.wait(500);\n              const current = await lockProvider.set(\n                name,\n                `${id},${dateTimeProvider.nowISOString()}`,\n                true,\n                maxDurationMs,\n              );\n              const [currentId] = current.split(\",\");\n              if (currentId === id) {\n                break;\n              }\n            }\n            // Check if we got the lock\n            const final = await lockProvider.set(\n              name,\n              `${id},${dateTimeProvider.nowISOString()}`,\n              true,\n              maxDurationMs,\n            );\n            const [finalId] = final.split(\",\");\n            if (finalId !== id) {\n              throw new LockAcquireError(name);\n            }\n          } else {\n            throw new LockAcquireError(name);\n          }\n        }\n\n        // We hold the lock — execute handler\n        const acquiredAt = dateTimeProvider.nowMillis();\n        await alepha.events.emit(\"lock:acquired\", {\n          name,\n          id,\n          maxDurationMs,\n        });\n        try {\n          return await next(...args);\n        } finally {\n          await lockProvider.del(name);\n          await alepha.events.emit(\"lock:released\", {\n            name,\n            id,\n            heldMs: dateTimeProvider.nowMillis() - acquiredAt,\n          });\n        }\n      };\n    },\n  });\n};\n\n// ---------------------------------------------------------------------------------------------------------------------\n\n/**\n * Options for $lock in middleware mode (no handler).\n */\nexport interface LockMiddlewareOptions {\n  /**\n   * Lock key name. Required in middleware mode (no class context available).\n   * Can be a static string or a function that derives the key from handler args.\n   */\n  name: string | ((...args: any[]) => string);\n\n  /**\n   * Whether to wait for the lock to become available.\n   *\n   * @default false\n   */\n  wait?: boolean;\n\n  /**\n   * Maximum duration the lock can be held before automatic expiration.\n   *\n   * @default [5, \"minutes\"]\n   */\n  maxDuration?: DurationLike;\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\n/**\n * Lock configuration atom.\n */\nexport const lockOptions = $atom({\n  name: \"alepha.lock.options\",\n  schema: t.object({\n    prefixKey: t.text({\n      default: \"\",\n      description: \"Prefix for all lock keys.\",\n    }),\n  }),\n  default: {\n    prefixKey: \"\",\n  },\n});\n\nexport type LockAtomOptions = Static<typeof lockOptions.schema>;\n\ndeclare module \"alepha\" {\n  interface State {\n    [lockOptions.key]: LockAtomOptions;\n  }\n}\n\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 settings = $state(lockOptions);\n  protected readonly dateTimeProvider = $inject(DateTimeProvider);\n\n  /**\n   * Lazy-initialized UUID to avoid calling crypto.randomUUID() in global scope.\n   * Cloudflare Workers doesn't allow random value generation during initialization.\n   */\n  protected _id?: string;\n  protected get id(): string {\n    if (!this._id) {\n      this._id = crypto.randomUUID();\n    }\n    return this._id;\n  }\n\n  public readonly maxDuration = this.dateTimeProvider.duration(\n    this.options.maxDuration ?? [5, \"minutes\"],\n  );\n\n  protected readonly topicLockEnd = $topic({\n    name: `${this.settings.prefixKey}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        // Poll until the lock is released, then re-attempt\n        const start = this.dateTimeProvider.nowMillis();\n        const maxMs = this.maxDuration.as(\"milliseconds\");\n        let acquired = false;\n        while (this.dateTimeProvider.nowMillis() - start < maxMs) {\n          await this.dateTimeProvider.wait(500);\n          const current = await this.lock(key);\n          if (current.id === this.id || !current.id || current.endedAt) {\n            acquired = true;\n            break;\n          }\n        }\n        if (acquired) {\n          return this.run(...args);\n        }\n        this.log.warn(`Lock wait timeout for '${key}', giving up`);\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.settings.prefixKey}${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\nexport interface LockResult {\n  id: string;\n  createdAt: DateTime;\n  endedAt?: DateTime;\n  response?: string;\n}\n","import { $module } from \"alepha\";\nimport { MemoryTopicProvider } from \"alepha/topic\";\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\ndeclare module \"alepha\" {\n  interface Hooks {\n    /**\n     * Fires when a lock is successfully acquired.\n     */\n    \"lock:acquired\": {\n      name: string;\n      id: string;\n      maxDurationMs: number;\n    };\n    /**\n     * Fires when a lock is released (handler completed or threw).\n     */\n    \"lock:released\": {\n      name: string;\n      id: string;\n      heldMs: number;\n    };\n    /**\n     * Fires when a lock acquisition contends with another holder.\n     * Emitted whether the caller eventually acquires (`wait: true`) or fails.\n     */\n    \"lock:contended\": {\n      name: string;\n      id: string;\n    };\n  }\n}\n\n// ---------------------------------------------------------------------------------------------------------------------\n\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  services: [LockProvider, LockTopicProvider],\n  variants: [MemoryLockProvider],\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/redis/index.d.ts

@@ -1,11 +1,9 @@
-import * as _$alepha from "alepha";
 import { LockProvider } from "alepha/lock";
-import * as _$alepha_logger0 from "alepha/logger";
 import { RedisProvider } from "alepha/redis";
 
 //#region ../../src/lock/redis/providers/RedisLockProvider.d.ts
 declare class RedisLockProvider implements LockProvider {
-  protected readonly log: _$alepha_logger0.Logger;
+  protected readonly log: import("alepha/logger").Logger;
   protected readonly redisProvider: RedisProvider;
   set(key: string, value: string, nx?: boolean, px?: number): Promise<string>;
   del(...keys: string[]): Promise<void>;
@@ -18,7 +16,7 @@ declare class RedisLockProvider implements LockProvider {
  * @see {@link RedisLockProvider}
  * @module alepha.lock.redis
  */
-declare const AlephaLockRedis: _$alepha.Service<_$alepha.Module>;
+declare const AlephaLockRedis: import("alepha").Service<import("alepha").Module>;
 //#endregion
 export { AlephaLockRedis, RedisLockProvider };
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../../../src/lock/redis/providers/RedisLockProvider.ts","../../../src/lock/redis/index.ts"],"mappings":";;;;;;cAKa,iBAAA,YAA6B,YAAA;EAAA,mBACrB,GAAA,EADU,gBAAA,CACP,MAAA;EAAA,mBACH,aAAA,EAAa,aAAA;EAEnB,GAAA,CACX,GAAA,UACA,KAAA,UACA,EAAA,YACA,EAAA,YACC,OAAA;EAqBU,GAAA,CAAA,GAAO,IAAA,aAAiB,OAAA;AAAA;;;;;;;;AA9BvC;cCYa,eAAA,EAAe,QAAA,CAAA,OAAA,CAgB1B,QAAA,CAhB0B,MAAA"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../../src/lock/redis/providers/RedisLockProvider.ts","../../../src/lock/redis/index.ts"],"mappings":";;;;cAKa,iBAAA,YAA6B,YAAA;EAAA,mBACrB,GAAA,0BAAG,MAAA;EAAA,mBACH,aAAA,EAAa,aAAA;EAEnB,GAAA,CACX,GAAA,UACA,KAAA,UACA,EAAA,YACA,EAAA,YACC,OAAA;EAqBU,GAAA,IAAO,IAAA,aAAiB,OAAA;AAAA;;;;;;AA9BvC;;;cCYa,eAAA,mBAAe,OAAA,kBAAA,MAAA"}

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../../src/lock/redis/providers/RedisLockProvider.ts","../../../src/lock/redis/index.ts"],"sourcesContent":["import { $inject } from \"alepha\";\nimport type { LockProvider } from \"alepha/lock\";\nimport { $logger } from \"alepha/logger\";\nimport { RedisProvider, type RedisSetOptions } from \"alepha/redis\";\n\nexport class RedisLockProvider implements LockProvider {\n  protected readonly log = $logger();\n  protected readonly redisProvider = $inject(RedisProvider);\n\n  public async set(\n    key: string,\n    value: string,\n    nx?: boolean,\n    px?: number,\n  ): Promise<string> {\n    const options: RedisSetOptions = {\n      GET: true, // all the secrets of $lock is based on this\n    };\n\n    if (px) {\n      options.expiration = {\n        type: \"PX\",\n        value: px,\n      };\n    }\n\n    if (nx) {\n      options.condition = \"NX\";\n    }\n\n    const resp = await this.redisProvider.set(key, value, options);\n\n    return resp.toString(\"utf-8\");\n  }\n\n  public async del(...keys: string[]): Promise<void> {\n    await this.redisProvider.del(keys);\n  }\n}\n","import { $module, type Alepha } from \"alepha\";\nimport { AlephaLock, LockProvider, LockTopicProvider } from \"alepha/lock\";\nimport { RedisTopicProvider } from \"alepha/topic/redis\";\nimport { RedisLockProvider } from \"./providers/RedisLockProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport * from \"./providers/RedisLockProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\n/**\n * Plugin for Alepha that provides a locking mechanism.\n *\n * @see {@link RedisLockProvider}\n * @module alepha.lock.redis\n */\nexport const AlephaLockRedis = $module({\n  name: \"alepha.lock.redis\",\n  services: [RedisLockProvider, RedisTopicProvider],\n  register: (alepha: Alepha) =>\n    alepha\n      .with({\n        optional: true,\n        provide: LockTopicProvider,\n        use: RedisTopicProvider,\n      })\n      .with({\n        optional: true,\n        provide: LockProvider,\n        use: RedisLockProvider,\n      })\n      .with(AlephaLock),\n});\n"],"mappings":";;;;;;AAKA,IAAa,oBAAb,MAAuD;CACrD,MAAyB,SAAS;CAClC,gBAAmC,QAAQ,cAAc;CAEzD,MAAa,IACX,KACA,OACA,IACA,IACiB;EACjB,MAAM,UAA2B,EAC/B,KAAK,MACN;EAED,IAAI,IACF,QAAQ,aAAa;GACnB,MAAM;GACN,OAAO;GACR;EAGH,IAAI,IACF,QAAQ,YAAY;EAKtB,QAAO,MAFY,KAAK,cAAc,IAAI,KAAK,OAAO,QAAQ,EAElD,SAAS,QAAQ;;CAG/B,MAAa,IAAI,GAAG,MAA+B;EACjD,MAAM,KAAK,cAAc,IAAI,KAAK;;;;;;;;;;;ACnBtC,MAAa,kBAAkB,QAAQ;CACrC,MAAM;CACN,UAAU,CAAC,mBAAmB,mBAAmB;CACjD,WAAW,WACT,OACG,KAAK;EACJ,UAAU;EACV,SAAS;EACT,KAAK;EACN,CAAC,CACD,KAAK;EACJ,UAAU;EACV,SAAS;EACT,KAAK;EACN,CAAC,CACD,KAAK,WAAW;CACtB,CAAC"}
+{"version":3,"file":"index.js","names":[],"sources":["../../../src/lock/redis/providers/RedisLockProvider.ts","../../../src/lock/redis/index.ts"],"sourcesContent":["import { $inject } from \"alepha\";\nimport type { LockProvider } from \"alepha/lock\";\nimport { $logger } from \"alepha/logger\";\nimport { RedisProvider, type RedisSetOptions } from \"alepha/redis\";\n\nexport class RedisLockProvider implements LockProvider {\n  protected readonly log = $logger();\n  protected readonly redisProvider = $inject(RedisProvider);\n\n  public async set(\n    key: string,\n    value: string,\n    nx?: boolean,\n    px?: number,\n  ): Promise<string> {\n    const options: RedisSetOptions = {\n      GET: true, // all the secrets of $lock is based on this\n    };\n\n    if (px) {\n      options.expiration = {\n        type: \"PX\",\n        value: px,\n      };\n    }\n\n    if (nx) {\n      options.condition = \"NX\";\n    }\n\n    const resp = await this.redisProvider.set(key, value, options);\n\n    return resp.toString(\"utf-8\");\n  }\n\n  public async del(...keys: string[]): Promise<void> {\n    await this.redisProvider.del(keys);\n  }\n}\n","import { $module, type Alepha } from \"alepha\";\nimport { AlephaLock, LockProvider, LockTopicProvider } from \"alepha/lock\";\nimport { RedisTopicProvider } from \"alepha/topic/redis\";\nimport { RedisLockProvider } from \"./providers/RedisLockProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport * from \"./providers/RedisLockProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\n/**\n * Plugin for Alepha that provides a locking mechanism.\n *\n * @see {@link RedisLockProvider}\n * @module alepha.lock.redis\n */\nexport const AlephaLockRedis = $module({\n  name: \"alepha.lock.redis\",\n  services: [RedisLockProvider, RedisTopicProvider],\n  register: (alepha: Alepha) =>\n    alepha\n      .with({\n        optional: true,\n        provide: LockTopicProvider,\n        use: RedisTopicProvider,\n      })\n      .with({\n        optional: true,\n        provide: LockProvider,\n        use: RedisLockProvider,\n      })\n      .with(AlephaLock),\n});\n"],"mappings":";;;;;;AAKA,IAAa,oBAAb,MAAuD;CACrD,MAAyB,QAAQ;CACjC,gBAAmC,QAAQ,aAAa;CAExD,MAAa,IACX,KACA,OACA,IACA,IACiB;EACjB,MAAM,UAA2B,EAC/B,KAAK,KACP;EAEA,IAAI,IACF,QAAQ,aAAa;GACnB,MAAM;GACN,OAAO;EACT;EAGF,IAAI,IACF,QAAQ,YAAY;EAKtB,QAAO,MAFY,KAAK,cAAc,IAAI,KAAK,OAAO,OAAO,GAEjD,SAAS,OAAO;CAC9B;CAEA,MAAa,IAAI,GAAG,MAA+B;EACjD,MAAM,KAAK,cAAc,IAAI,IAAI;CACnC;AACF;;;;;;;;;ACrBA,MAAa,kBAAkB,QAAQ;CACrC,MAAM;CACN,UAAU,CAAC,mBAAmB,kBAAkB;CAChD,WAAW,WACT,OACG,KAAK;EACJ,UAAU;EACV,SAAS;EACT,KAAK;CACP,CAAC,EACA,KAAK;EACJ,UAAU;EACV,SAAS;EACT,KAAK;CACP,CAAC,EACA,KAAK,UAAU;AACtB,CAAC"}

package/dist/logger/index.d.ts

@@ -1,35 +1,101 @@
-import * as _$alepha from "alepha";
 import { Alepha, KIND, LogLevel, LoggerInterface, Static } from "alepha";
 import { DateTimeProvider } from "alepha/datetime";
-import * as _$typebox from "typebox";
 
 //#region ../../src/logger/schemas/logEntrySchema.d.ts
-declare const logEntrySchema: _$typebox.TObject<{
-  level: _$typebox.TUnsafe<"DEBUG" | "SILENT" | "TRACE" | "INFO" | "WARN" | "ERROR">;
-  message: _$typebox.TString;
-  service: _$typebox.TString;
-  module: _$typebox.TString;
-  context: _$typebox.TOptional<_$typebox.TString>;
-  app: _$typebox.TOptional<_$typebox.TString>;
-  data: _$typebox.TOptional<_$typebox.TAny>;
-  timestamp: _$typebox.TNumber;
+declare const logEntrySchema: import("typebox").TObject<{
+  level: import("typebox").TUnsafe<"DEBUG" | "SILENT" | "TRACE" | "INFO" | "WARN" | "ERROR">;
+  message: import("typebox").TString;
+  service: import("typebox").TString;
+  module: import("typebox").TString;
+  context: import("typebox").TOptional<import("typebox").TString>;
+  app: import("typebox").TOptional<import("typebox").TString>;
+  data: import("typebox").TOptional<import("typebox").TAny>;
+  timestamp: import("typebox").TNumber;
 }>;
 type LogEntry = Static<typeof logEntrySchema>;
 //#endregion
+//#region ../../src/logger/providers/LogFormatterProvider.d.ts
+declare abstract class LogFormatterProvider {
+  abstract format(entry: LogEntry): string;
+}
+//#endregion
+//#region ../../src/logger/providers/JsonFormatterProvider.d.ts
+declare class JsonFormatterProvider extends LogFormatterProvider {
+  format(entry: LogEntry): string;
+  formatJsonError(error: Error): object;
+}
+//#endregion
 //#region ../../src/logger/providers/LogDestinationProvider.d.ts
 declare abstract class LogDestinationProvider {
   abstract write(message: string, entry: LogEntry): void;
 }
 //#endregion
-//#region ../../src/logger/providers/LogFormatterProvider.d.ts
-declare abstract class LogFormatterProvider {
-  abstract format(entry: LogEntry): string;
+//#region ../../src/logger/providers/ConsoleColorProvider.d.ts
+declare class ConsoleColorProvider {
+  static readonly COLORS: {
+    RESET: string;
+    BLACK: string;
+    RED: string;
+    GREEN: string;
+    ORANGE: string;
+    BLUE: string;
+    PURPLE: string;
+    CYAN: string;
+    GREY_LIGHT: string;
+    GREY_LIGHT_BOLD: string;
+    GREY_DARK: string;
+    GREY_DARK_BOLD: string;
+    WHITE: string;
+    WHITE_BOLD: string;
+    DIM: string;
+    BOLD: string;
+    INVERSE: string;
+    SILENT: string;
+    ERROR: string;
+    WARN: string;
+    INFO: string;
+    DEBUG: string;
+    TRACE: string;
+  };
+  protected readonly alepha: Alepha;
+  protected enabled: boolean;
+  constructor();
+  isEnabled(): boolean;
+  set(color: keyof typeof ConsoleColorProvider.COLORS, text: string, reset?: string): string;
+}
+//#endregion
+//#region ../../src/logger/providers/PrettyFormatterProvider.d.ts
+declare class PrettyFormatterProvider extends LogFormatterProvider {
+  protected color: ConsoleColorProvider;
+  protected alepha: Alepha;
+  format(entry: LogEntry): string;
+  formatTimestamp(timestamp: number): string;
+  protected pad2: (n: number) => string;
+  protected pad3: (n: number) => string;
+  /**
+   * Avoid to display the whole UUID in development mode
+   */
+  protected formatContext(context: string): string;
+  protected formatError(error: Error): string;
+}
+//#endregion
+//#region ../../src/logger/providers/RawFormatterProvider.d.ts
+declare class RawFormatterProvider extends LogFormatterProvider {
+  format(entry: LogEntry): string;
 }
 //#endregion
 //#region ../../src/logger/services/Logger.d.ts
 declare class Logger implements LoggerInterface {
   protected readonly alepha: Alepha;
-  protected readonly formatter: LogFormatterProvider;
+  /**
+   * Formatter chosen at register time (from `LOG_FORMAT`, honoring any
+   * custom `LogFormatterProvider` substitution). Used unless a runtime
+   * `alepha.logger.format` override is set — see {@link formatter}.
+   */
+  protected readonly defaultFormatter: LogFormatterProvider;
+  protected readonly jsonFormatter: JsonFormatterProvider;
+  protected readonly prettyFormatter: PrettyFormatterProvider;
+  protected readonly rawFormatter: RawFormatterProvider;
   protected readonly destination: LogDestinationProvider;
   protected readonly dateTimeProvider: DateTimeProvider;
   protected readonly levels: Record<string, number>;
@@ -41,6 +107,13 @@ declare class Logger implements LoggerInterface {
   constructor(service: string, module: string);
   get context(): string | undefined;
   get level(): string;
+  /**
+   * Active formatter. Honors a runtime `alepha.logger.format` override
+   * (read live, like {@link level}); otherwise falls back to the
+   * register-time {@link defaultFormatter} so custom substitutions and the
+   * `LOG_FORMAT` default keep working.
+   */
+  protected get formatter(): LogFormatterProvider;
   parseLevel(level: string, app: string): LogLevel;
   protected matchesPattern(moduleName: string, pattern: string): boolean;
   asLogLevel(something: string): LogLevel;
@@ -81,51 +154,11 @@ interface LoggerPrimitiveOptions {
   name?: string;
 }
 //#endregion
-//#region ../../src/logger/providers/ConsoleColorProvider.d.ts
-declare class ConsoleColorProvider {
-  static readonly COLORS: {
-    RESET: string;
-    BLACK: string;
-    RED: string;
-    GREEN: string;
-    ORANGE: string;
-    BLUE: string;
-    PURPLE: string;
-    CYAN: string;
-    GREY_LIGHT: string;
-    GREY_LIGHT_BOLD: string;
-    GREY_DARK: string;
-    GREY_DARK_BOLD: string;
-    WHITE: string;
-    WHITE_BOLD: string;
-    DIM: string;
-    BOLD: string;
-    INVERSE: string;
-    SILENT: string;
-    ERROR: string;
-    WARN: string;
-    INFO: string;
-    DEBUG: string;
-    TRACE: string;
-  };
-  protected readonly alepha: Alepha;
-  protected enabled: boolean;
-  constructor();
-  isEnabled(): boolean;
-  set(color: keyof typeof ConsoleColorProvider.COLORS, text: string, reset?: string): string;
-}
-//#endregion
 //#region ../../src/logger/providers/ConsoleDestinationProvider.d.ts
 declare class ConsoleDestinationProvider extends LogDestinationProvider {
   write(message: string): void;
 }
 //#endregion
-//#region ../../src/logger/providers/JsonFormatterProvider.d.ts
-declare class JsonFormatterProvider extends LogFormatterProvider {
-  format(entry: LogEntry): string;
-  formatJsonError(error: Error): object;
-}
-//#endregion
 //#region ../../src/logger/providers/MemoryDestinationProvider.d.ts
 declare class MemoryDestinationProvider extends LogDestinationProvider {
   protected entries: Array<LogEntry & {
@@ -150,21 +183,6 @@ declare class MemoryDestinationProvider extends LogDestinationProvider {
   clear(): void;
 }
 //#endregion
-//#region ../../src/logger/providers/PrettyFormatterProvider.d.ts
-declare class PrettyFormatterProvider extends LogFormatterProvider {
-  protected color: ConsoleColorProvider;
-  protected alepha: Alepha;
-  format(entry: LogEntry): string;
-  formatTimestamp(timestamp: number): string;
-  protected pad2: (n: number) => string;
-  protected pad3: (n: number) => string;
-  /**
-   * Avoid to display the whole UUID in development mode
-   */
-  protected formatContext(context: string): string;
-  protected formatError(error: Error): string;
-}
-//#endregion
 //#region ../../src/logger/index.d.ts
 /**
  * Configurable logging with multiple outputs.
@@ -181,8 +199,8 @@ declare class PrettyFormatterProvider extends LogFormatterProvider {
  *
  * @module alepha.logger
  */
-declare const AlephaLogger: _$alepha.Service<_$alepha.Module>;
-declare const envSchema: _$alepha.TObject<{
+declare const AlephaLogger: import("alepha").Service<import("alepha").Module>;
+declare const envSchema: import("alepha").TObject<{
   /**
    * Enable debug logging for specific modules using the `debug` package convention.
    *
@@ -192,7 +210,7 @@ declare const envSchema: _$alepha.TObject<{
    * DEBUG=alepha:orm:* # Enable debug logging for alepha.orm modules
    * DEBUG=* # Enable debug logging for all modules
    */
-  DEBUG: _$alepha.TOptional<_$alepha.TString>;
+  DEBUG: import("alepha").TOptional<import("alepha").TString>;
   /**
    * Default log level for the application.
    *
@@ -209,14 +227,14 @@ declare const envSchema: _$alepha.TObject<{
    * LOG_LEVEL=my.module.name:debug,info # Set debug level for my.module.name and info for all other modules
    * LOG_LEVEL=alepha:trace, info # Set trace level for all alepha modules and info for all other modules
    */
-  LOG_LEVEL: _$alepha.TOptional<_$alepha.TString>;
+  LOG_LEVEL: import("alepha").TOptional<import("alepha").TString>;
   /**
    * Built-in log formats.
    * - "json" - JSON format, useful for structured logging and log aggregation. {@link JsonFormatterProvider}
    * - "pretty" - Simple text format, human-readable, with colors. {@link PrettyFormatterProvider}
    * - "raw" - Raw format, no formatting, just the message. {@link RawFormatterProvider}
    */
-  LOG_FORMAT: _$alepha.TOptional<_$alepha.TUnsafe<"json" | "pretty" | "raw">>;
+  LOG_FORMAT: import("alepha").TOptional<import("alepha").TUnsafe<"json" | "pretty" | "raw">>;
 }>;
 declare module "alepha" {
   interface Env extends Partial<Static<typeof envSchema>> {}
@@ -225,6 +243,17 @@ declare module "alepha" {
      * Current log level for the application or specific modules.
      */
     "alepha.logger.level"?: string;
+    /**
+     * Runtime override for the log format (`json` | `pretty` | `raw`).
+     *
+     * Unset → the formatter chosen at register time from `LOG_FORMAT`
+     * (honoring any custom `LogFormatterProvider` substitution) is used.
+     * When set, it overrides both the active formatter and the CLI's
+     * dynamic/"stylish" task UI (which is enabled only for `raw`). Set it
+     * to flip output at runtime — e.g. the CLI `--verbose` flag forces
+     * `pretty`.
+     */
+    "alepha.logger.format"?: string;
   }
   interface Hooks {
     log: {
@@ -234,5 +263,5 @@ declare module "alepha" {
   }
 } //# sourceMappingURL=index.d.ts.map
 //#endregion
-export { $logger, AlephaLogger, ConsoleColorProvider, ConsoleDestinationProvider, JsonFormatterProvider, LogDestinationProvider, LogEntry, LogFormatterProvider, Logger, LoggerPrimitiveOptions, MemoryDestinationProvider, PrettyFormatterProvider, logEntrySchema };
+export { $logger, AlephaLogger, ConsoleColorProvider, ConsoleDestinationProvider, JsonFormatterProvider, LogDestinationProvider, LogEntry, LogFormatterProvider, Logger, LoggerPrimitiveOptions, MemoryDestinationProvider, PrettyFormatterProvider, RawFormatterProvider, logEntrySchema };
 //# sourceMappingURL=index.d.ts.map

package/dist/logger/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/logger/schemas/logEntrySchema.ts","../../src/logger/providers/LogDestinationProvider.ts","../../src/logger/providers/LogFormatterProvider.ts","../../src/logger/services/Logger.ts","../../src/logger/primitives/$logger.ts","../../src/logger/providers/ConsoleColorProvider.ts","../../src/logger/providers/ConsoleDestinationProvider.ts","../../src/logger/providers/JsonFormatterProvider.ts","../../src/logger/providers/MemoryDestinationProvider.ts","../../src/logger/providers/PrettyFormatterProvider.ts","../../src/logger/index.ts"],"mappings":"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"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/logger/schemas/logEntrySchema.ts","../../src/logger/providers/LogFormatterProvider.ts","../../src/logger/providers/JsonFormatterProvider.ts","../../src/logger/providers/LogDestinationProvider.ts","../../src/logger/providers/ConsoleColorProvider.ts","../../src/logger/providers/PrettyFormatterProvider.ts","../../src/logger/providers/RawFormatterProvider.ts","../../src/logger/services/Logger.ts","../../src/logger/primitives/$logger.ts","../../src/logger/providers/ConsoleDestinationProvider.ts","../../src/logger/providers/MemoryDestinationProvider.ts","../../src/logger/index.ts"],"mappings":"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"}