alepha 0.11.9 → 0.11.11

package/lock.d.ts

@@ -1,552 +0,0 @@
-import * as _alepha_core1 from "alepha";
-import { AsyncFn, Descriptor, KIND, Static } from "alepha";
-import * as _alepha_topic0 from "alepha/topic";
-import { TopicProvider } from "alepha/topic";
-import { DateTime, DateTimeProvider, DurationLike, Timeout } from "alepha/datetime";
-import * as _alepha_logger0 from "alepha/logger";
-import * as dayjs_plugin_duration0 from "dayjs/plugin/duration";
-
-//#region src/providers/LockProvider.d.ts
-/**
- * Store Provider Interface
- */
-declare abstract class LockProvider {
-  /**
-   * Set the string value of a key.
-   *
-   * @param key The key of the value to set.
-   * @param value The value to set.
-   * @param nx If set to true, the key will only be set if it does not already exist.
-   * @param px Set the specified expire time, in milliseconds.
-   */
-  abstract set(key: string, value: string, nx?: boolean, px?: number): Promise<string>;
-  /**
-   * Remove the specified keys.
-   *
-   * @param keys The keys to delete.
-   */
-  abstract del(...keys: string[]): Promise<void>;
-}
-//#endregion
-//#region src/descriptors/$lock.d.ts
-/**
- * Creates a distributed lock descriptor for ensuring single-instance execution across processes.
- *
- * This descriptor provides a powerful distributed locking mechanism that prevents multiple instances
- * of the same operation from running simultaneously. It's essential for maintaining data consistency
- * and preventing race conditions in distributed applications, scheduled tasks, and critical sections
- * that must execute atomically.
- *
- * **Key Features**
- *
- * - **Distributed Coordination**: Works across multiple processes, servers, and containers
- * - **Automatic Expiration**: Locks expire automatically to prevent deadlocks
- * - **Graceful Handling**: Configurable wait behavior for different use cases
- * - **Grace Periods**: Optional lock extension after completion for additional safety
- * - **Topic Integration**: Uses pub/sub for efficient lock release notifications
- * - **Unique Instance IDs**: Prevents lock conflicts between different instances
- * - **Timeout Management**: Configurable durations with intelligent retry logic
- *
- * **Use Cases**
- *
- * Perfect for ensuring single execution in distributed environments:
- * - Database migrations and schema updates
- * - Scheduled job execution (cron-like tasks)
- * - File processing and batch operations
- * - Critical section protection
- * - Resource initialization and cleanup
- * - Singleton service operations
- * - Cache warming and maintenance tasks
- *
- * @example
- * **Basic lock for scheduled tasks:**
- * ```ts
- * import { $lock } from "alepha/lock";
- *
- * class ScheduledTaskService {
- *   dailyReport = $lock({
- *     handler: async () => {
- *       // This will only run on one server even if multiple servers
- *       // trigger the task simultaneously
- *       console.log('Generating daily report...');
- *
- *       const report = await this.generateDailyReport();
- *       await this.sendReportToManagement(report);
- *
- *       console.log('Daily report completed');
- *     }
- *   });
- *
- *   async runDailyReport() {
- *     // Multiple servers can call this, but only one will execute
- *     await this.dailyReport.run();
- *   }
- * }
- * ```
- *
- * @example
- * **Migration lock with wait behavior:**
- * ```ts
- * class DatabaseService {
- *   migration = $lock({
- *     wait: true,  // Wait for other instances to complete migration
- *     maxDuration: [10, "minutes"],  // Migration timeout
- *     handler: async (version: string) => {
- *       console.log(`Running migration to version ${version}`);
- *
- *       const currentVersion = await this.getCurrentSchemaVersion();
- *       if (currentVersion >= version) {
- *         console.log(`Already at version ${version}, skipping`);
- *         return;
- *       }
- *
- *       await this.runMigrationScripts(version);
- *       await this.updateSchemaVersion(version);
- *
- *       console.log(`Migration to ${version} completed`);
- *     }
- *   });
- *
- *   async migrateToVersion(version: string) {
- *     // All instances will wait for the first one to complete
- *     // before continuing with their startup process
- *     await this.migration.run(version);
- *   }
- * }
- * ```
- *
- * @example
- * **Dynamic lock keys with grace periods:**
- * ```ts
- * class FileProcessor {
- *   processFile = $lock({
- *     name: (filePath: string) => `file-processing:${filePath}`,
- *     wait: false,  // Don't wait, skip if already processing
- *     maxDuration: [30, "minutes"],
- *     gracePeriod: [5, "minutes"],  // Keep lock for 5min after completion
- *     handler: async (filePath: string) => {
- *       console.log(`Processing file: ${filePath}`);
- *
- *       try {
- *         const fileData = await this.readFile(filePath);
- *         const processedData = await this.processData(fileData);
- *         await this.saveProcessedData(filePath, processedData);
- *         await this.moveToCompleted(filePath);
- *
- *         console.log(`File processing completed: ${filePath}`);
- *       } catch (error) {
- *         console.error(`File processing failed: ${filePath}`, error);
- *         await this.moveToError(filePath, error.message);
- *         throw error;
- *       }
- *     }
- *   });
- *
- *   async processUploadedFile(filePath: string) {
- *     // Each file gets its own lock, preventing duplicate processing
- *     // Grace period prevents immediate reprocessing of the same file
- *     await this.processFile.run(filePath);
- *   }
- * }
- * ```
- *
- * @example
- * **Resource initialization with conditional grace periods:**
- * ```ts
- * class CacheService {
- *   warmCache = $lock({
- *     name: (cacheKey: string) => `cache-warming:${cacheKey}`,
- *     wait: true,  // Wait for cache to be warmed before continuing
- *     maxDuration: [15, "minutes"],
- *     gracePeriod: (cacheKey: string) => {
- *       // Dynamic grace period based on cache importance
- *       const criticalCaches = ['user-sessions', 'product-catalog'];
- *       return criticalCaches.includes(cacheKey)
- *         ? [30, "minutes"]  // Longer grace for critical caches
- *         : [5, "minutes"];   // Shorter grace for regular caches
- *     },
- *     handler: async (cacheKey: string, force: boolean = false) => {
- *       console.log(`Warming cache: ${cacheKey}`);
- *
- *       if (!force && await this.isCacheWarm(cacheKey)) {
- *         console.log(`Cache ${cacheKey} is already warm`);
- *         return;
- *       }
- *
- *       const startTime = Date.now();
- *
- *       switch (cacheKey) {
- *         case 'user-sessions':
- *           await this.warmUserSessionsCache();
- *           break;
- *         case 'product-catalog':
- *           await this.warmProductCatalogCache();
- *           break;
- *         case 'configuration':
- *           await this.warmConfigurationCache();
- *           break;
- *         default:
- *           throw new Error(`Unknown cache key: ${cacheKey}`);
- *       }
- *
- *       const duration = Date.now() - startTime;
- *       console.log(`Cache warming completed for ${cacheKey} in ${duration}ms`);
- *
- *       await this.markCacheAsWarm(cacheKey);
- *     }
- *   });
- *
- *   async ensureCacheWarmed(cacheKey: string, force: boolean = false) {
- *     // Multiple instances can call this, but cache warming happens only once
- *     // All instances wait for completion before proceeding
- *     await this.warmCache.run(cacheKey, force);
- *   }
- * }
- * ```
- *
- * @example
- * **Critical section protection with custom timeout handling:**
- * ```ts
- * class InventoryService {
- *   updateInventory = $lock({
- *     name: (productId: string) => `inventory-update:${productId}`,
- *     wait: true,  // Ensure all inventory updates are sequential
- *     maxDuration: [2, "minutes"],
- *     gracePeriod: [30, "seconds"],  // Brief grace to prevent immediate conflicts
- *     handler: async (productId: string, quantity: number, operation: 'add' | 'subtract') => {
- *       console.log(`Updating inventory for product ${productId}: ${operation} ${quantity}`);
- *
- *       try {
- *         // Start transaction for inventory update
- *         await this.db.transaction(async (tx) => {
- *           const currentInventory = await tx.getInventory(productId);
- *
- *           if (operation === 'subtract' && currentInventory.quantity < quantity) {
- *             throw new Error(`Insufficient inventory for product ${productId}. Available: ${currentInventory.quantity}, Requested: ${quantity}`);
- *           }
- *
- *           const newQuantity = operation === 'add'
- *             ? currentInventory.quantity + quantity
- *             : currentInventory.quantity - quantity;
- *
- *           await tx.updateInventory(productId, newQuantity);
- *
- *           // Log inventory change for audit
- *           await tx.logInventoryChange({
- *             productId,
- *             operation,
- *             quantity,
- *             previousQuantity: currentInventory.quantity,
- *             newQuantity,
- *             timestamp: new Date()
- *           });
- *
- *           console.log(`Inventory updated for product ${productId}: ${currentInventory.quantity} -> ${newQuantity}`);
- *         });
- *
- *         // Notify other services about inventory change
- *         await this.inventoryChangeNotifier.notify({
- *           productId,
- *           operation,
- *           quantity,
- *           timestamp: new Date()
- *         });
- *
- *       } catch (error) {
- *         console.error(`Inventory update failed for product ${productId}`, error);
- *         throw error;
- *       }
- *     }
- *   });
- *
- *   async addInventory(productId: string, quantity: number) {
- *     await this.updateInventory.run(productId, quantity, 'add');
- *   }
- *
- *   async subtractInventory(productId: string, quantity: number) {
- *     await this.updateInventory.run(productId, quantity, 'subtract');
- *   }
- * }
- * ```
- */
-declare const $lock: {
-  <TFunc extends AsyncFn>(options: LockDescriptorOptions<TFunc>): LockDescriptor<TFunc>;
-  [KIND]: typeof LockDescriptor;
-};
-interface LockDescriptorOptions<TFunc extends AsyncFn> {
-  /**
-   * The function to execute when the lock is successfully acquired.
-   *
-   * This function:
-   * - Only executes on the instance that successfully acquires the lock
-   * - Has exclusive access to the protected resource during execution
-   * - Should contain the critical section logic that must not run concurrently
-   * - Can be async and perform any operations needed
-   * - Will automatically release the lock upon completion or error
-   * - Has access to the full Alepha dependency injection container
-   *
-   * **Handler Design Guidelines**:
-   * - Keep critical sections as short as possible to minimize lock contention
-   * - Include proper error handling to ensure locks are released
-   * - Use timeouts for external operations to prevent deadlocks
-   * - Log important operations for debugging and monitoring
-   * - Consider idempotency for handlers that might be retried
-   *
-   * @param ...args - The arguments passed to the lock execution
-   * @returns Promise that resolves when the protected operation is complete
-   *
-   * @example
-   * ```ts
-   * handler: async (batchId: string) => {
-   *   console.log(`Processing batch ${batchId} - only one instance will run this`);
-   *
-   *   const batch = await this.getBatchData(batchId);
-   *   const results = await this.processBatchItems(batch.items);
-   *   await this.saveBatchResults(batchId, results);
-   *
-   *   console.log(`Batch ${batchId} completed successfully`);
-   * }
-   * ```
-   */
-  handler: TFunc;
-  /**
-   * Whether the lock should wait for other instances to complete before giving up.
-   *
-   * **wait = false (default)**:
-   * - Non-blocking behavior - if lock is held, immediately return without executing
-   * - Perfect for scheduled tasks where you only want one execution per trigger
-   * - Use when multiple triggers are acceptable but concurrent execution is not
-   * - Examples: periodic cleanup, cron jobs, background maintenance
-   *
-   * **wait = true**:
-   * - Blocking behavior - wait for the current lock holder to finish
-   * - All instances will eventually execute (one after another)
-   * - Perfect for initialization tasks where all instances need the work completed
-   * - Examples: database migrations, cache warming, resource initialization
-   *
-   * **Trade-offs**:
-   * - Non-waiting: Better performance, may miss executions if timing is off
-   * - Waiting: Guaranteed execution order, slower overall throughput
-   *
-   * @default false
-   *
-   * @example
-   * ```ts
-   * // Scheduled task - don't wait, just skip if already running
-   * scheduledCleanup = $lock({
-   *   wait: false,  // Skip if cleanup already running
-   *   handler: async () => { } // perform cleanup
-   * });
-   *
-   * // Migration - wait for completion before proceeding
-   * migration = $lock({
-   *   wait: true,   // All instances wait for migration to complete
-   *   handler: async () => { } // perform migration
-   * });
-   * ```
-   */
-  wait?: boolean;
-  /**
-   * The unique identifier for the lock.
-   *
-   * Can be either:
-   * - **Static string**: A fixed identifier for the lock
-   * - **Dynamic function**: A function that generates the lock key based on arguments
-   *
-   * **Dynamic Lock Keys**:
-   * - Enable per-resource locking (e.g., per-user, per-file, per-product)
-   * - Allow fine-grained concurrency control
-   * - Prevent unnecessary blocking between unrelated operations
-   *
-   * **Key Design Guidelines**:
-   * - Use descriptive names that indicate the protected resource
-   * - Include relevant identifiers for dynamic keys
-   * - Keep keys reasonably short but unique
-   * - Consider using hierarchical naming (e.g., "service:operation:resource")
-   *
-   * If not provided, defaults to `{serviceName}:{propertyKey}`.
-   *
-   * @example "user-migration"
-   * @example "daily-report-generation"
-   * @example (userId: string) => `user-profile-update:${userId}`
-   * @example (fileId: string, operation: string) => `file-${operation}:${fileId}`
-   *
-   * @example
-   * ```ts
-   * // Static lock key - all instances compete for the same lock
-   * globalCleanup = $lock({
-   *   name: "system-cleanup",
-   *   handler: async () => { } // perform cleanup
-   * });
-   *
-   * // Dynamic lock key - per-user locks, users don't block each other
-   * updateUserProfile = $lock({
-   *   name: (userId: string) => `user-update:${userId}`,
-   *   handler: async (userId: string, data: UserData) => {
-   *     // Only one update per user at a time, but different users can update concurrently
-   *   }
-   * });
-   * ```
-   */
-  name?: string | ((...args: Parameters<TFunc>) => string);
-  /**
-   * Maximum duration the lock can be held before it expires automatically.
-   *
-   * This prevents deadlocks when a process dies while holding a lock or when
-   * operations take longer than expected. The lock will be automatically released
-   * after this duration, allowing other instances to proceed.
-   *
-   * **Duration Guidelines**:
-   * - Set based on expected operation duration plus safety margin
-   * - Too short: Operations may be interrupted by early expiration
-   * - Too long: Failed processes block others for extended periods
-   * - Consider worst-case scenarios and external dependency timeouts
-   *
-   * **Typical Values**:
-   * - Quick operations: 30 seconds - 2 minutes
-   * - Database operations: 5 - 15 minutes
-   * - File processing: 10 - 30 minutes
-   * - Large migrations: 30 minutes - 2 hours
-   *
-   * @default [5, "minutes"]
-   *
-   * @example [30, "seconds"]    // Quick operations
-   * @example [10, "minutes"]    // Database migrations
-   * @example [1, "hour"]        // Long-running batch jobs
-   *
-   * @example
-   * ```ts
-   * quickTask = $lock({
-   *   maxDuration: [2, "minutes"],  // Quick timeout for fast operations
-   *   handler: async () => { } // perform quick task
-   * });
-   *
-   * heavyProcessing = $lock({
-   *   maxDuration: [30, "minutes"], // Longer timeout for heavy work
-   *   handler: async () => { } // perform heavy processing
-   * });
-   * ```
-   */
-  maxDuration?: DurationLike;
-  /**
-   * Additional time to keep the lock active after the handler completes successfully.
-   *
-   * This provides a "cooling off" period that can be useful for:
-   * - Preventing immediate re-execution of the same operation
-   * - Giving time for related systems to process the results
-   * - Avoiding race conditions with dependent operations
-   * - Providing a buffer for cleanup operations
-   *
-   * Can be either:
-   * - **Static duration**: Fixed grace period for all executions
-   * - **Dynamic function**: Grace period determined by execution arguments
-   * - **undefined**: No grace period, lock released immediately after completion
-   *
-   * **Grace Period Use Cases**:
-   * - File processing: Prevent immediate reprocessing of uploaded files
-   * - Cache updates: Allow time for cache propagation
-   * - Batch operations: Prevent overlapping batch processing
-   * - External API calls: Respect rate limiting requirements
-   *
-   * @default undefined (no grace period)
-   *
-   * @example [5, "minutes"]     // Fixed 5-minute grace period
-   * @example [30, "seconds"]    // Short grace for quick operations
-   * @example (userId: string) => userId.startsWith("premium") ? [10, "minutes"] : [2, "minutes"]
-   *
-   * @example
-   * ```ts
-   * fileProcessor = $lock({
-   *   gracePeriod: [10, "minutes"],  // Prevent reprocessing same file immediately
-   *   handler: async (filePath: string) => {
-   *     await this.processFile(filePath);
-   *   }
-   * });
-   *
-   * userOperation = $lock({
-   *   gracePeriod: (userId: string, operation: string) => {
-   *     // Dynamic grace based on operation type
-   *     return operation === 'migration' ? [30, "minutes"] : [5, "minutes"];
-   *   },
-   *   handler: async (userId: string, operation: string) => {
-   *     await this.performUserOperation(userId, operation);
-   *   }
-   * });
-   * ```
-   */
-  gracePeriod?: ((...args: Parameters<TFunc>) => DurationLike | undefined) | DurationLike;
-}
-declare const envSchema: _alepha_core1.TObject<{
-  LOCK_PREFIX_KEY: _alepha_core1.TString;
-}>;
-declare module "alepha" {
-  interface Env extends Partial<Static<typeof envSchema>> {}
-}
-declare class LockDescriptor<TFunc extends AsyncFn> extends Descriptor<LockDescriptorOptions<TFunc>> {
-  protected readonly log: _alepha_logger0.Logger;
-  protected readonly provider: LockProvider;
-  protected readonly env: {
-    LOCK_PREFIX_KEY: string;
-  };
-  protected readonly dateTimeProvider: DateTimeProvider;
-  protected readonly id: `${string}-${string}-${string}-${string}-${string}`;
-  readonly maxDuration: dayjs_plugin_duration0.Duration;
-  protected readonly topicLockEnd: _alepha_topic0.TopicDescriptor<{
-    payload: _alepha_core1.TObject<{
-      name: _alepha_core1.TString;
-    }>;
-  }>;
-  run(...args: Parameters<TFunc>): Promise<void>;
-  /**
-   * Set the lock for the given key.
-   */
-  protected lock(key: string): Promise<LockResult>;
-  protected setGracePeriod(key: string, lock: LockResult, ...args: Parameters<TFunc>): Promise<void>;
-  protected wait(key: string, maxDuration: DurationLike): Promise<void>;
-  protected key(...args: Parameters<TFunc>): string;
-  protected parse(value: string): LockResult;
-}
-interface LockResult {
-  id: string;
-  createdAt: DateTime;
-  endedAt?: DateTime;
-  response?: string;
-}
-//#endregion
-//#region src/providers/LockTopicProvider.d.ts
-declare abstract class LockTopicProvider extends TopicProvider {}
-//#endregion
-//#region src/providers/MemoryLockProvider.d.ts
-/**
- * A simple in-memory store provider.
- */
-declare class MemoryLockProvider implements LockProvider {
-  protected readonly dateTimeProvider: DateTimeProvider;
-  protected readonly log: _alepha_logger0.Logger;
-  /**
-   * The in-memory store.
-   */
-  protected store: Record<string, string>;
-  /**
-   * Timeouts used to expire keys.
-   */
-  protected storeTimeout: Record<string, Timeout>;
-  set(key: string, value: string, nx?: boolean, px?: number): Promise<string>;
-  del(...keys: string[]): Promise<void>;
-  private ttl;
-}
-//#endregion
-//#region src/index.d.ts
-/**
- * Lock a resource for a certain period of time.
- *
- * This module provides a memory implementation of the lock provider.
- * You probably want to use an implementation like RedisLockProvider for distributed systems.
- *
- * @see {@link $lock}
- * @module alepha.lock
- */
-declare const AlephaLock: _alepha_core1.Service<_alepha_core1.Module>;
-//#endregion
-export { $lock, AlephaLock, LockDescriptor, LockDescriptorOptions, LockProvider, LockResult, LockTopicProvider, MemoryLockProvider };
-//# sourceMappingURL=index.d.ts.map

package/lock.js

@@ -1 +0,0 @@
-export * from '@alepha/lock'

package/logger.cjs

@@ -1,8 +0,0 @@
-'use strict';
-var m = require('@alepha/logger');
-Object.keys(m).forEach(function (k) {
-	if (k !== 'default' && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {
-		enumerable: true,
-		get: function () { return m[k]; }
-	});
-});