alepha 0.13.0 → 0.13.2

package/dist/file/index.js

@@ -1191,7 +1191,7 @@ var NodeFileSystemProvider = class {
 */
 const AlephaFile = $module({
 	name: "alepha.file",
-	descriptors: [],
+	primitives: [],
 	services: [
 		FileDetector,
 		FileSystemProvider,

package/dist/file/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["reverse: Record<string, string>","chunks: Buffer[]","fsRm","fsCp","fsMkdir","allFiles: string[]","fsReadFile","fsWriteFile","name: string","buffer: Buffer | null","buffer: any[]"],"sources":["../../src/file/providers/FileSystemProvider.ts","../../src/file/services/FileDetector.ts","../../src/file/providers/NodeFileSystemProvider.ts","../../src/file/index.ts"],"sourcesContent":["import type { FileLike, StreamLike } from \"alepha\";\n\n/**\n * Options for creating a file from a URL\n */\nexport interface CreateFileFromUrlOptions {\n  /**\n   * The URL to load the file from (file://, http://, or https://)\n   */\n  url: string;\n  /**\n   * The MIME type of the file (optional, will be detected from filename if not provided)\n   */\n  type?: string;\n  /**\n   * The name of the file (optional, will be extracted from URL if not provided)\n   */\n  name?: string;\n}\n\n/**\n * Options for creating a file from a path (URL with file:// scheme)\n */\nexport interface CreateFileFromPathOptions {\n  /**\n   * The path to the file on the local filesystem\n   */\n  path: string;\n  /**\n   * The MIME type of the file (optional, will be detected from filename if not provided)\n   */\n  type?: string;\n  /**\n   * The name of the file (optional, will be extracted from URL if not provided)\n   */\n  name?: string;\n}\n\n/**\n * Options for creating a file from a Buffer\n */\nexport interface CreateFileFromBufferOptions {\n  /**\n   * The Buffer containing the file data\n   */\n  buffer: Buffer;\n  /**\n   * The MIME type of the file (optional, will be detected from name if not provided)\n   */\n  type?: string;\n  /**\n   * The name of the file (required for proper content type detection)\n   */\n  name?: string;\n}\n\n/**\n * Options for creating a file from a stream\n */\nexport interface CreateFileFromStreamOptions {\n  /**\n   * The readable stream containing the file data\n   */\n  stream: StreamLike;\n  /**\n   * The MIME type of the file (optional, will be detected from name if not provided)\n   */\n  type?: string;\n  /**\n   * The name of the file (required for proper content type detection)\n   */\n  name?: string;\n  /**\n   * The size of the file in bytes (optional)\n   */\n  size?: number;\n}\n\n/**\n * Options for creating a file from text content\n */\nexport interface CreateFileFromTextOptions {\n  /**\n   * The text content to create the file from\n   */\n  text: string;\n  /**\n   * The MIME type of the file (default: text/plain)\n   */\n  type?: string;\n  /**\n   * The name of the file (default: \"file.txt\")\n   */\n  name?: string;\n}\n\nexport interface CreateFileFromResponseOptions {\n  /**\n   * The Response object containing the file data\n   */\n  response: Response;\n  /**\n   * Override the name (optional, uses filename from Content-Disposition header if not provided)\n   */\n  name?: string;\n  /**\n   * Override the MIME type (optional, uses file.type if not provided)\n   */\n  type?: string;\n}\n\n/**\n * Options for creating a file from a Web File object\n */\nexport interface CreateFileFromWebFileOptions {\n  /**\n   * The Web File object\n   */\n  file: File;\n  /**\n   * Override the MIME type (optional, uses file.type if not provided)\n   */\n  type?: string;\n  /**\n   * Override the name (optional, uses file.name if not provided)\n   */\n  name?: string;\n  /**\n   * Override the size (optional, uses file.size if not provided)\n   */\n  size?: number;\n}\n\n/**\n * Options for creating a file from an ArrayBuffer\n */\nexport interface CreateFileFromArrayBufferOptions {\n  /**\n   * The ArrayBuffer containing the file data\n   */\n  arrayBuffer: ArrayBuffer;\n  /**\n   * The MIME type of the file (optional, will be detected from name if not provided)\n   */\n  type?: string;\n  /**\n   * The name of the file (required for proper content type detection)\n   */\n  name?: string;\n}\n\n/**\n * Union type for all createFile options\n */\nexport type CreateFileOptions =\n  | CreateFileFromUrlOptions\n  | CreateFileFromPathOptions\n  | CreateFileFromBufferOptions\n  | CreateFileFromStreamOptions\n  | CreateFileFromTextOptions\n  | CreateFileFromWebFileOptions\n  | CreateFileFromResponseOptions\n  | CreateFileFromArrayBufferOptions;\n\n/**\n * Options for rm (remove) operation\n */\nexport interface RmOptions {\n  /**\n   * If true, removes directories and their contents recursively\n   */\n  recursive?: boolean;\n  /**\n   * If true, no error will be thrown if the path does not exist\n   */\n  force?: boolean;\n}\n\n/**\n * Options for cp (copy) operation\n */\nexport interface CpOptions {\n  /**\n   * If true, copy directories recursively\n   */\n  recursive?: boolean;\n  /**\n   * If true, overwrite existing destination\n   */\n  force?: boolean;\n}\n\n/**\n * Options for mkdir operation\n */\nexport interface MkdirOptions {\n  /**\n   * If true, creates parent directories as needed\n   */\n  recursive?: boolean;\n  /**\n   * File mode (permission and sticky bits)\n   */\n  mode?: number;\n}\n\n/**\n * Options for ls (list) operation\n */\nexport interface LsOptions {\n  /**\n   * If true, list contents of directories recursively\n   */\n  recursive?: boolean;\n  /**\n   * If true, include hidden files (starting with .)\n   */\n  hidden?: boolean;\n}\n\n/**\n * FileSystem interface providing utilities for working with files.\n */\nexport abstract class FileSystemProvider {\n  /**\n   * Creates a FileLike object from various sources.\n   *\n   * @param options - Options for creating the file\n   * @returns A FileLike object\n   */\n  abstract createFile(options: CreateFileOptions): FileLike;\n\n  /**\n   * Removes a file or directory.\n   *\n   * @param path - The path to remove\n   * @param options - Remove options\n   */\n  abstract rm(path: string, options?: RmOptions): Promise<void>;\n\n  /**\n   * Copies a file or directory.\n   *\n   * @param src - Source path\n   * @param dest - Destination path\n   * @param options - Copy options\n   */\n  abstract cp(src: string, dest: string, options?: CpOptions): Promise<void>;\n\n  /**\n   * Moves/renames a file or directory.\n   *\n   * @param src - Source path\n   * @param dest - Destination path\n   */\n  abstract mv(src: string, dest: string): Promise<void>;\n\n  /**\n   * Creates a directory.\n   *\n   * @param path - The directory path to create\n   * @param options - Mkdir options\n   */\n  abstract mkdir(path: string, options?: MkdirOptions): Promise<void>;\n\n  /**\n   * Lists files in a directory.\n   *\n   * @param path - The directory path to list\n   * @param options - List options\n   * @returns Array of filenames\n   */\n  abstract ls(path: string, options?: LsOptions): Promise<string[]>;\n\n  /**\n   * Checks if a file or directory exists.\n   *\n   * @param path - The path to check\n   * @returns True if the path exists, false otherwise\n   */\n  abstract exists(path: string): Promise<boolean>;\n\n  /**\n   * Reads the content of a file.\n   *\n   * @param path - The file path to read\n   * @returns The file content as a Buffer\n   */\n  abstract readFile(path: string): Promise<Buffer>;\n\n  /**\n   * Writes data to a file.\n   *\n   * @param path - The file path to write to\n   * @param data - The data to write (Buffer or string)\n   */\n  abstract writeFile(\n    path: string,\n    data: Uint8Array | Buffer | string | FileLike,\n  ): Promise<void>;\n}\n","import { Readable } from \"node:stream\";\n\nexport interface FileTypeResult {\n  /**\n   * The detected MIME type\n   */\n  mimeType: string;\n  /**\n   * The detected file extension\n   */\n  extension: string;\n  /**\n   * Whether the file type was verified by magic bytes\n   */\n  verified: boolean;\n  /**\n   * The stream (potentially wrapped to allow re-reading)\n   */\n  stream: Readable;\n}\n\n/**\n * Service for detecting file types and getting content types.\n *\n * @example\n * ```typescript\n * const detector = alepha.inject(FileDetector);\n *\n * // Get content type from filename\n * const mimeType = detector.getContentType(\"image.png\"); // \"image/png\"\n *\n * // Detect file type by magic bytes\n * const stream = createReadStream('image.png');\n * const result = await detector.detectFileType(stream, 'image.png');\n * console.log(result.mimeType); // 'image/png'\n * console.log(result.verified); // true if magic bytes match\n * ```\n */\nexport class FileDetector {\n  /**\n   * Magic byte signatures for common file formats.\n   * Each signature is represented as an array of bytes or null (wildcard).\n   */\n  protected static readonly MAGIC_BYTES: Record<\n    string,\n    { signature: (number | null)[]; mimeType: string }[]\n  > = {\n    // Images\n    png: [\n      {\n        signature: [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a],\n        mimeType: \"image/png\",\n      },\n    ],\n    jpg: [\n      { signature: [0xff, 0xd8, 0xff, 0xe0], mimeType: \"image/jpeg\" },\n      { signature: [0xff, 0xd8, 0xff, 0xe1], mimeType: \"image/jpeg\" },\n      { signature: [0xff, 0xd8, 0xff, 0xe2], mimeType: \"image/jpeg\" },\n      { signature: [0xff, 0xd8, 0xff, 0xe3], mimeType: \"image/jpeg\" },\n      { signature: [0xff, 0xd8, 0xff, 0xe8], mimeType: \"image/jpeg\" },\n    ],\n    jpeg: [\n      { signature: [0xff, 0xd8, 0xff, 0xe0], mimeType: \"image/jpeg\" },\n      { signature: [0xff, 0xd8, 0xff, 0xe1], mimeType: \"image/jpeg\" },\n      { signature: [0xff, 0xd8, 0xff, 0xe2], mimeType: \"image/jpeg\" },\n      { signature: [0xff, 0xd8, 0xff, 0xe3], mimeType: \"image/jpeg\" },\n      { signature: [0xff, 0xd8, 0xff, 0xe8], mimeType: \"image/jpeg\" },\n    ],\n    gif: [\n      {\n        signature: [0x47, 0x49, 0x46, 0x38, 0x37, 0x61],\n        mimeType: \"image/gif\",\n      }, // GIF87a\n      {\n        signature: [0x47, 0x49, 0x46, 0x38, 0x39, 0x61],\n        mimeType: \"image/gif\",\n      }, // GIF89a\n    ],\n    webp: [\n      {\n        signature: [\n          0x52,\n          0x49,\n          0x46,\n          0x46,\n          null,\n          null,\n          null,\n          null,\n          0x57,\n          0x45,\n          0x42,\n          0x50,\n        ],\n        mimeType: \"image/webp\",\n      },\n    ],\n    bmp: [{ signature: [0x42, 0x4d], mimeType: \"image/bmp\" }],\n    ico: [{ signature: [0x00, 0x00, 0x01, 0x00], mimeType: \"image/x-icon\" }],\n    tiff: [\n      { signature: [0x49, 0x49, 0x2a, 0x00], mimeType: \"image/tiff\" }, // Little-endian\n      { signature: [0x4d, 0x4d, 0x00, 0x2a], mimeType: \"image/tiff\" }, // Big-endian\n    ],\n    tif: [\n      { signature: [0x49, 0x49, 0x2a, 0x00], mimeType: \"image/tiff\" },\n      { signature: [0x4d, 0x4d, 0x00, 0x2a], mimeType: \"image/tiff\" },\n    ],\n\n    // Documents\n    pdf: [\n      {\n        signature: [0x25, 0x50, 0x44, 0x46, 0x2d],\n        mimeType: \"application/pdf\",\n      },\n    ], // %PDF-\n    zip: [\n      { signature: [0x50, 0x4b, 0x03, 0x04], mimeType: \"application/zip\" },\n      { signature: [0x50, 0x4b, 0x05, 0x06], mimeType: \"application/zip\" },\n      { signature: [0x50, 0x4b, 0x07, 0x08], mimeType: \"application/zip\" },\n    ],\n\n    // Archives\n    rar: [\n      {\n        signature: [0x52, 0x61, 0x72, 0x21, 0x1a, 0x07],\n        mimeType: \"application/vnd.rar\",\n      },\n    ],\n    \"7z\": [\n      {\n        signature: [0x37, 0x7a, 0xbc, 0xaf, 0x27, 0x1c],\n        mimeType: \"application/x-7z-compressed\",\n      },\n    ],\n    tar: [\n      {\n        signature: [0x75, 0x73, 0x74, 0x61, 0x72],\n        mimeType: \"application/x-tar\",\n      },\n    ],\n    gz: [{ signature: [0x1f, 0x8b], mimeType: \"application/gzip\" }],\n    tgz: [{ signature: [0x1f, 0x8b], mimeType: \"application/gzip\" }],\n\n    // Audio\n    mp3: [\n      { signature: [0xff, 0xfb], mimeType: \"audio/mpeg\" },\n      { signature: [0xff, 0xf3], mimeType: \"audio/mpeg\" },\n      { signature: [0xff, 0xf2], mimeType: \"audio/mpeg\" },\n      { signature: [0x49, 0x44, 0x33], mimeType: \"audio/mpeg\" }, // ID3\n    ],\n    wav: [\n      {\n        signature: [\n          0x52,\n          0x49,\n          0x46,\n          0x46,\n          null,\n          null,\n          null,\n          null,\n          0x57,\n          0x41,\n          0x56,\n          0x45,\n        ],\n        mimeType: \"audio/wav\",\n      },\n    ],\n    ogg: [{ signature: [0x4f, 0x67, 0x67, 0x53], mimeType: \"audio/ogg\" }],\n    flac: [{ signature: [0x66, 0x4c, 0x61, 0x43], mimeType: \"audio/flac\" }], // fLaC\n\n    // Video\n    mp4: [\n      {\n        signature: [null, null, null, null, 0x66, 0x74, 0x79, 0x70],\n        mimeType: \"video/mp4\",\n      }, // ftyp\n      {\n        signature: [\n          null,\n          null,\n          null,\n          null,\n          0x66,\n          0x74,\n          0x79,\n          0x70,\n          0x69,\n          0x73,\n          0x6f,\n          0x6d,\n        ],\n        mimeType: \"video/mp4\",\n      }, // ftypisom\n      {\n        signature: [\n          null,\n          null,\n          null,\n          null,\n          0x66,\n          0x74,\n          0x79,\n          0x70,\n          0x6d,\n          0x70,\n          0x34,\n          0x32,\n        ],\n        mimeType: \"video/mp4\",\n      }, // ftypmp42\n    ],\n    webm: [{ signature: [0x1a, 0x45, 0xdf, 0xa3], mimeType: \"video/webm\" }],\n    avi: [\n      {\n        signature: [\n          0x52,\n          0x49,\n          0x46,\n          0x46,\n          null,\n          null,\n          null,\n          null,\n          0x41,\n          0x56,\n          0x49,\n          0x20,\n        ],\n        mimeType: \"video/x-msvideo\",\n      },\n    ],\n    mov: [\n      {\n        signature: [\n          null,\n          null,\n          null,\n          null,\n          0x66,\n          0x74,\n          0x79,\n          0x70,\n          0x71,\n          0x74,\n          0x20,\n          0x20,\n        ],\n        mimeType: \"video/quicktime\",\n      },\n    ],\n    mkv: [\n      { signature: [0x1a, 0x45, 0xdf, 0xa3], mimeType: \"video/x-matroska\" },\n    ],\n\n    // Office (DOCX, XLSX, PPTX are all ZIP-based)\n    docx: [\n      {\n        signature: [0x50, 0x4b, 0x03, 0x04],\n        mimeType:\n          \"application/vnd.openxmlformats-officedocument.wordprocessingml.document\",\n      },\n    ],\n    xlsx: [\n      {\n        signature: [0x50, 0x4b, 0x03, 0x04],\n        mimeType:\n          \"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet\",\n      },\n    ],\n    pptx: [\n      {\n        signature: [0x50, 0x4b, 0x03, 0x04],\n        mimeType:\n          \"application/vnd.openxmlformats-officedocument.presentationml.presentation\",\n      },\n    ],\n    doc: [\n      {\n        signature: [0xd0, 0xcf, 0x11, 0xe0, 0xa1, 0xb1, 0x1a, 0xe1],\n        mimeType: \"application/msword\",\n      },\n    ],\n    xls: [\n      {\n        signature: [0xd0, 0xcf, 0x11, 0xe0, 0xa1, 0xb1, 0x1a, 0xe1],\n        mimeType: \"application/vnd.ms-excel\",\n      },\n    ],\n    ppt: [\n      {\n        signature: [0xd0, 0xcf, 0x11, 0xe0, 0xa1, 0xb1, 0x1a, 0xe1],\n        mimeType: \"application/vnd.ms-powerpoint\",\n      },\n    ],\n  };\n\n  /**\n   * All possible format signatures for checking against actual file content\n   */\n  protected static readonly ALL_SIGNATURES = Object.entries(\n    FileDetector.MAGIC_BYTES,\n  ).flatMap(([ext, signatures]) => signatures.map((sig) => ({ ext, ...sig })));\n\n  /**\n   * MIME type map for file extensions.\n   *\n   * Can be used to get the content type of file based on its extension.\n   * Feel free to add more mime types in your project!\n   */\n  public static readonly mimeMap: Record<string, string> = {\n    // Documents\n    json: \"application/json\",\n    txt: \"text/plain\",\n    html: \"text/html\",\n    htm: \"text/html\",\n    xml: \"application/xml\",\n    csv: \"text/csv\",\n    pdf: \"application/pdf\",\n    md: \"text/markdown\",\n    markdown: \"text/markdown\",\n    rtf: \"application/rtf\",\n\n    // Styles and scripts\n    css: \"text/css\",\n    js: \"application/javascript\",\n    mjs: \"application/javascript\",\n    ts: \"application/typescript\",\n    jsx: \"text/jsx\",\n    tsx: \"text/tsx\",\n\n    // Archives\n    zip: \"application/zip\",\n    rar: \"application/vnd.rar\",\n    \"7z\": \"application/x-7z-compressed\",\n    tar: \"application/x-tar\",\n    gz: \"application/gzip\",\n    tgz: \"application/gzip\",\n\n    // Images\n    png: \"image/png\",\n    jpg: \"image/jpeg\",\n    jpeg: \"image/jpeg\",\n    gif: \"image/gif\",\n    webp: \"image/webp\",\n    svg: \"image/svg+xml\",\n    bmp: \"image/bmp\",\n    ico: \"image/x-icon\",\n    tiff: \"image/tiff\",\n    tif: \"image/tiff\",\n\n    // Audio\n    mp3: \"audio/mpeg\",\n    wav: \"audio/wav\",\n    ogg: \"audio/ogg\",\n    m4a: \"audio/mp4\",\n    aac: \"audio/aac\",\n    flac: \"audio/flac\",\n\n    // Video\n    mp4: \"video/mp4\",\n    webm: \"video/webm\",\n    avi: \"video/x-msvideo\",\n    mov: \"video/quicktime\",\n    wmv: \"video/x-ms-wmv\",\n    flv: \"video/x-flv\",\n    mkv: \"video/x-matroska\",\n\n    // Office\n    doc: \"application/msword\",\n    docx: \"application/vnd.openxmlformats-officedocument.wordprocessingml.document\",\n    xls: \"application/vnd.ms-excel\",\n    xlsx: \"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet\",\n    ppt: \"application/vnd.ms-powerpoint\",\n    pptx: \"application/vnd.openxmlformats-officedocument.presentationml.presentation\",\n\n    // Fonts\n    woff: \"font/woff\",\n    woff2: \"font/woff2\",\n    ttf: \"font/ttf\",\n    otf: \"font/otf\",\n    eot: \"application/vnd.ms-fontobject\",\n  };\n\n  /**\n   * Reverse MIME type map for looking up extensions from MIME types.\n   * Prefers shorter, more common extensions when multiple exist.\n   */\n  protected static readonly reverseMimeMap: Record<string, string> = (() => {\n    const reverse: Record<string, string> = {};\n    // Process in order so common extensions come first\n    for (const [ext, mimeType] of Object.entries(FileDetector.mimeMap)) {\n      // Only set if not already set (prefer first/shorter extension)\n      if (!reverse[mimeType]) {\n        reverse[mimeType] = ext;\n      }\n    }\n    return reverse;\n  })();\n\n  /**\n   * Returns the file extension for a given MIME type.\n   *\n   * @param mimeType - The MIME type to look up\n   * @returns The file extension (without dot), or \"bin\" if not found\n   *\n   * @example\n   * ```typescript\n   * const detector = alepha.inject(FileDetector);\n   * const ext = detector.getExtensionFromMimeType(\"image/png\"); // \"png\"\n   * const ext2 = detector.getExtensionFromMimeType(\"application/octet-stream\"); // \"bin\"\n   * ```\n   */\n  getExtensionFromMimeType(mimeType: string): string {\n    return FileDetector.reverseMimeMap[mimeType] || \"bin\";\n  }\n  /**\n   * Returns the content type of file based on its filename.\n   *\n   * @param filename - The filename to check\n   * @returns The MIME type\n   *\n   * @example\n   * ```typescript\n   * const detector = alepha.inject(FileDetector);\n   * const mimeType = detector.getContentType(\"image.png\"); // \"image/png\"\n   * ```\n   */\n  getContentType(filename: string): string {\n    const ext = filename.toLowerCase().split(\".\").pop() || \"\";\n    return FileDetector.mimeMap[ext] || \"application/octet-stream\";\n  }\n\n  /**\n   * Detects the file type by checking magic bytes against the stream content.\n   *\n   * @param stream - The readable stream to check\n   * @param filename - The filename (used to get the extension)\n   * @returns File type information including MIME type, extension, and verification status\n   *\n   * @example\n   * ```typescript\n   * const detector = alepha.inject(FileDetector);\n   * const stream = createReadStream('image.png');\n   * const result = await detector.detectFileType(stream, 'image.png');\n   * console.log(result.mimeType); // 'image/png'\n   * console.log(result.verified); // true if magic bytes match\n   * ```\n   */\n  async detectFileType(\n    stream: Readable,\n    filename: string,\n  ): Promise<FileTypeResult> {\n    // Get the expected MIME type from the filename extension\n    const expectedMimeType = this.getContentType(filename);\n\n    // Extract extension - only if filename contains a dot\n    const lastDotIndex = filename.lastIndexOf(\".\");\n    const ext =\n      lastDotIndex > 0\n        ? filename.substring(lastDotIndex + 1).toLowerCase()\n        : \"\";\n\n    // Read the first 16 bytes (enough for most magic byte checks)\n    const { buffer, stream: newStream } = await this.peekBytes(stream, 16);\n\n    // First, check if the extension's expected signature matches\n    const expectedSignatures = FileDetector.MAGIC_BYTES[ext];\n    if (expectedSignatures) {\n      for (const { signature, mimeType } of expectedSignatures) {\n        if (this.matchesSignature(buffer, signature)) {\n          return {\n            mimeType,\n            extension: ext,\n            verified: true,\n            stream: newStream,\n          };\n        }\n      }\n    }\n\n    // If the expected signature didn't match, try all other signatures\n    for (const {\n      ext: detectedExt,\n      signature,\n      mimeType,\n    } of FileDetector.ALL_SIGNATURES) {\n      if (detectedExt !== ext && this.matchesSignature(buffer, signature)) {\n        return {\n          mimeType,\n          extension: detectedExt,\n          verified: true,\n          stream: newStream,\n        };\n      }\n    }\n\n    // If no magic bytes matched, fall back to extension-based detection\n    // or return binary if extension is not recognized\n    return {\n      mimeType: expectedMimeType,\n      extension: ext,\n      verified: false,\n      stream: newStream,\n    };\n  }\n\n  /**\n   * Reads all bytes from a stream and returns the first N bytes along with a new stream containing all data.\n   * This approach reads the entire stream upfront to avoid complex async handling issues.\n   *\n   * @protected\n   */\n  protected async peekBytes(\n    stream: Readable,\n    numBytes: number,\n  ): Promise<{ buffer: Buffer; stream: Readable }> {\n    const chunks: Buffer[] = [];\n\n    // Read the entire stream\n    for await (const chunk of stream) {\n      chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));\n    }\n\n    const allData = Buffer.concat(chunks);\n    const buffer = allData.subarray(0, numBytes);\n\n    // Create a new stream with all the data\n    const newStream = Readable.from(allData);\n\n    return { buffer, stream: newStream };\n  }\n\n  /**\n   * Checks if a buffer matches a magic byte signature.\n   *\n   * @protected\n   */\n  protected matchesSignature(\n    buffer: Buffer,\n    signature: (number | null)[],\n  ): boolean {\n    if (buffer.length < signature.length) {\n      return false;\n    }\n\n    for (let i = 0; i < signature.length; i++) {\n      if (signature[i] !== null && buffer[i] !== signature[i]) {\n        return false;\n      }\n    }\n\n    return true;\n  }\n}\n","import { createReadStream } from \"node:fs\";\nimport {\n  access,\n  copyFile,\n  cp as fsCp,\n  mkdir as fsMkdir,\n  readFile as fsReadFile,\n  rm as fsRm,\n  writeFile as fsWriteFile,\n  readdir,\n  rename,\n  stat,\n} from \"node:fs/promises\";\nimport { join } from \"node:path\";\nimport { PassThrough, Readable } from \"node:stream\";\nimport type { ReadableStream as NodeWebStream } from \"node:stream/web\";\nimport { fileURLToPath } from \"node:url\";\nimport {\n  $inject,\n  AlephaError,\n  type FileLike,\n  isFileLike,\n  type StreamLike,\n} from \"alepha\";\nimport { FileDetector } from \"../services/FileDetector.ts\";\nimport type {\n  CpOptions,\n  CreateFileOptions,\n  FileSystemProvider,\n  LsOptions,\n  MkdirOptions,\n  RmOptions,\n} from \"./FileSystemProvider.ts\";\n\n/**\n * Node.js implementation of FileSystem interface.\n *\n * @example\n * ```typescript\n * const fs = alepha.inject(NodeFileSystemProvider);\n *\n * // Create from URL\n * const file1 = fs.createFile({ url: \"file:///path/to/file.png\" });\n *\n * // Create from Buffer\n * const file2 = fs.createFile({ buffer: Buffer.from(\"hello\"), name: \"hello.txt\" });\n *\n * // Create from text\n * const file3 = fs.createFile({ text: \"Hello, world!\", name: \"greeting.txt\" });\n *\n * // File operations\n * await fs.mkdir(\"/tmp/mydir\", { recursive: true });\n * await fs.cp(\"/src/file.txt\", \"/dest/file.txt\");\n * await fs.mv(\"/old/path.txt\", \"/new/path.txt\");\n * const files = await fs.ls(\"/tmp\");\n * await fs.rm(\"/tmp/file.txt\");\n * ```\n */\nexport class NodeFileSystemProvider implements FileSystemProvider {\n  protected detector = $inject(FileDetector);\n  /**\n   * Creates a FileLike object from various sources.\n   *\n   * @param options - Options for creating the file\n   * @returns A FileLike object\n   *\n   * @example\n   * ```typescript\n   * const fs = alepha.inject(NodeFileSystemProvider);\n   *\n   * // From URL\n   * const file1 = fs.createFile({ url: \"https://example.com/image.png\" });\n   *\n   * // From Buffer\n   * const file2 = fs.createFile({\n   *   buffer: Buffer.from(\"hello\"),\n   *   name: \"hello.txt\",\n   *   type: \"text/plain\"\n   * });\n   *\n   * // From text\n   * const file3 = fs.createFile({ text: \"Hello!\", name: \"greeting.txt\" });\n   *\n   * // From stream with detection\n   * const stream = createReadStream(\"/path/to/file.png\");\n   * const file4 = fs.createFile({ stream, name: \"image.png\" });\n   * ```\n   */\n  createFile(options: CreateFileOptions): FileLike {\n    if (\"path\" in options) {\n      const path = options.path;\n      const filename = path.split(\"/\").pop() || \"file\";\n      return this.createFileFromUrl(`file://${path}`, {\n        type: options.type,\n        name: options.name || filename,\n      });\n    }\n\n    // Handle URL\n    if (\"url\" in options) {\n      return this.createFileFromUrl(options.url, {\n        type: options.type,\n        name: options.name,\n      });\n    }\n\n    if (\"response\" in options) {\n      if (!options.response.body) {\n        throw new AlephaError(\"Response has no body stream\");\n      }\n      const res = options.response;\n      // guess size from content-length header if available\n      const sizeHeader = res.headers.get(\"content-length\");\n      const size = sizeHeader ? parseInt(sizeHeader, 10) : undefined;\n      // guess name from content-disposition header if available\n      let name = options.name;\n      const contentDisposition = res.headers.get(\"content-disposition\");\n      if (contentDisposition && !name) {\n        const match = contentDisposition.match(/filename=\"?([^\"]+)\"?/);\n        if (match) {\n          name = match[1];\n        }\n      }\n      // guess type from content-type header if available\n      const type = options.type || res.headers.get(\"content-type\") || undefined;\n      return this.createFileFromStream(options.response.body, {\n        type,\n        name,\n        size,\n      });\n    }\n\n    // Handle Web File\n    if (\"file\" in options) {\n      return this.createFileFromWebFile(options.file, {\n        type: options.type,\n        name: options.name,\n        size: options.size,\n      });\n    }\n\n    // Handle Buffer\n    if (\"buffer\" in options) {\n      return this.createFileFromBuffer(options.buffer, {\n        type: options.type,\n        name: options.name,\n      });\n    }\n\n    // Handle ArrayBuffer\n    if (\"arrayBuffer\" in options) {\n      return this.createFileFromBuffer(Buffer.from(options.arrayBuffer), {\n        type: options.type,\n        name: options.name,\n      });\n    }\n\n    // Handle text\n    if (\"text\" in options) {\n      return this.createFileFromBuffer(Buffer.from(options.text, \"utf-8\"), {\n        type: options.type || \"text/plain\",\n        name: options.name || \"file.txt\",\n      });\n    }\n\n    // Handle stream\n    if (\"stream\" in options) {\n      return this.createFileFromStream(options.stream, {\n        type: options.type,\n        name: options.name,\n        size: options.size,\n      });\n    }\n\n    throw new AlephaError(\n      \"Invalid createFile options: no valid source provided\",\n    );\n  }\n\n  /**\n   * Removes a file or directory.\n   *\n   * @param path - The path to remove\n   * @param options - Remove options\n   *\n   * @example\n   * ```typescript\n   * const fs = alepha.inject(NodeFileSystemProvider);\n   *\n   * // Remove a file\n   * await fs.rm(\"/tmp/file.txt\");\n   *\n   * // Remove a directory recursively\n   * await fs.rm(\"/tmp/mydir\", { recursive: true });\n   *\n   * // Remove with force (no error if doesn't exist)\n   * await fs.rm(\"/tmp/maybe-exists.txt\", { force: true });\n   * ```\n   */\n  async rm(path: string, options?: RmOptions): Promise<void> {\n    await fsRm(path, options);\n  }\n\n  /**\n   * Copies a file or directory.\n   *\n   * @param src - Source path\n   * @param dest - Destination path\n   * @param options - Copy options\n   *\n   * @example\n   * ```typescript\n   * const fs = alepha.inject(NodeFileSystemProvider);\n   *\n   * // Copy a file\n   * await fs.cp(\"/src/file.txt\", \"/dest/file.txt\");\n   *\n   * // Copy a directory recursively\n   * await fs.cp(\"/src/dir\", \"/dest/dir\", { recursive: true });\n   *\n   * // Copy with force (overwrite existing)\n   * await fs.cp(\"/src/file.txt\", \"/dest/file.txt\", { force: true });\n   * ```\n   */\n  async cp(src: string, dest: string, options?: CpOptions): Promise<void> {\n    // Check if source is a directory\n    const srcStat = await stat(src);\n\n    if (srcStat.isDirectory()) {\n      if (!options?.recursive) {\n        throw new Error(\n          `Cannot copy directory without recursive option: ${src}`,\n        );\n      }\n      // Use Node.js cp function for recursive directory copy\n      await fsCp(src, dest, {\n        recursive: true,\n        force: options?.force ?? false,\n      });\n    } else {\n      // For files, use copyFile\n      await copyFile(src, dest);\n    }\n  }\n\n  /**\n   * Moves/renames a file or directory.\n   *\n   * @param src - Source path\n   * @param dest - Destination path\n   *\n   * @example\n   * ```typescript\n   * const fs = alepha.inject(NodeFileSystemProvider);\n   *\n   * // Move/rename a file\n   * await fs.mv(\"/old/path.txt\", \"/new/path.txt\");\n   *\n   * // Move a directory\n   * await fs.mv(\"/old/dir\", \"/new/dir\");\n   * ```\n   */\n  async mv(src: string, dest: string): Promise<void> {\n    await rename(src, dest);\n  }\n\n  /**\n   * Creates a directory.\n   *\n   * @param path - The directory path to create\n   * @param options - Mkdir options\n   *\n   * @example\n   * ```typescript\n   * const fs = alepha.inject(NodeFileSystemProvider);\n   *\n   * // Create a directory\n   * await fs.mkdir(\"/tmp/mydir\");\n   *\n   * // Create nested directories\n   * await fs.mkdir(\"/tmp/path/to/dir\", { recursive: true });\n   *\n   * // Create with specific permissions\n   * await fs.mkdir(\"/tmp/mydir\", { mode: 0o755 });\n   * ```\n   */\n  async mkdir(path: string, options?: MkdirOptions): Promise<void> {\n    await fsMkdir(path, options);\n  }\n\n  /**\n   * Lists files in a directory.\n   *\n   * @param path - The directory path to list\n   * @param options - List options\n   * @returns Array of filenames\n   *\n   * @example\n   * ```typescript\n   * const fs = alepha.inject(NodeFileSystemProvider);\n   *\n   * // List files in a directory\n   * const files = await fs.ls(\"/tmp\");\n   * console.log(files); // [\"file1.txt\", \"file2.txt\", \"subdir\"]\n   *\n   * // List with hidden files\n   * const allFiles = await fs.ls(\"/tmp\", { hidden: true });\n   *\n   * // List recursively\n   * const allFilesRecursive = await fs.ls(\"/tmp\", { recursive: true });\n   * ```\n   */\n  async ls(path: string, options?: LsOptions): Promise<string[]> {\n    const entries = await readdir(path);\n\n    // Filter out hidden files if not requested\n    const filteredEntries = options?.hidden\n      ? entries\n      : entries.filter((e) => !e.startsWith(\".\"));\n\n    // If recursive, get all nested files\n    if (options?.recursive) {\n      const allFiles: string[] = [];\n\n      for (const entry of filteredEntries) {\n        const fullPath = join(path, entry);\n        const entryStat = await stat(fullPath);\n\n        if (entryStat.isDirectory()) {\n          // Add directory entry\n          allFiles.push(entry);\n          // Recursively get files from subdirectory\n          const subFiles = await this.ls(fullPath, options);\n          allFiles.push(...subFiles.map((f) => join(entry, f)));\n        } else {\n          allFiles.push(entry);\n        }\n      }\n\n      return allFiles;\n    }\n\n    return filteredEntries;\n  }\n\n  /**\n   * Checks if a file or directory exists.\n   *\n   * @param path - The path to check\n   * @returns True if the path exists, false otherwise\n   *\n   * @example\n   * ```typescript\n   * const fs = alepha.inject(NodeFileSystemProvider);\n   *\n   * if (await fs.exists(\"/tmp/file.txt\")) {\n   *   console.log(\"File exists\");\n   * }\n   * ```\n   */\n  async exists(path: string): Promise<boolean> {\n    try {\n      await access(path);\n      return true;\n    } catch {\n      return false;\n    }\n  }\n\n  /**\n   * Reads the content of a file.\n   *\n   * @param path - The file path to read\n   * @returns The file content as a Buffer\n   *\n   * @example\n   * ```typescript\n   * const fs = alepha.inject(NodeFileSystemProvider);\n   *\n   * const buffer = await fs.readFile(\"/tmp/file.txt\");\n   * console.log(buffer.toString(\"utf-8\"));\n   * ```\n   */\n  async readFile(path: string): Promise<Buffer> {\n    return await fsReadFile(path);\n  }\n\n  /**\n   * Writes data to a file.\n   *\n   * @param path - The file path to write to\n   * @param data - The data to write (Buffer or string)\n   *\n   * @example\n   * ```typescript\n   * const fs = alepha.inject(NodeFileSystemProvider);\n   *\n   * // Write string\n   * await fs.writeFile(\"/tmp/file.txt\", \"Hello, world!\");\n   *\n   * // Write Buffer\n   * await fs.writeFile(\"/tmp/file.bin\", Buffer.from([0x01, 0x02, 0x03]));\n   * ```\n   */\n  async writeFile(\n    path: string,\n    data: Uint8Array | Buffer | string | FileLike,\n  ): Promise<void> {\n    if (isFileLike(data)) {\n      await fsWriteFile(path, Readable.from(data.stream()));\n      return;\n    }\n    await fsWriteFile(path, data);\n  }\n\n  /**\n   * Creates a FileLike object from a Web File.\n   *\n   * @protected\n   */\n  protected createFileFromWebFile(\n    source: File,\n    options: {\n      type?: string;\n      name?: string;\n      size?: number;\n    } = {},\n  ): FileLike {\n    const name = options.name ?? source.name;\n    return {\n      name,\n      type: options.type ?? (source.type || this.detector.getContentType(name)),\n      size: options.size ?? source.size ?? 0,\n      lastModified: source.lastModified || Date.now(),\n      stream: () => source.stream(),\n      arrayBuffer: async (): Promise<ArrayBuffer> => {\n        return await source.arrayBuffer();\n      },\n      text: async (): Promise<string> => {\n        return await source.text();\n      },\n    };\n  }\n\n  /**\n   * Creates a FileLike object from a Buffer.\n   *\n   * @protected\n   */\n  protected createFileFromBuffer(\n    source: Buffer,\n    options: {\n      type?: string;\n      name?: string;\n    } = {},\n  ): FileLike {\n    const name: string = options.name ?? \"file\";\n    return {\n      name,\n      type: options.type ?? this.detector.getContentType(options.name ?? name),\n      size: source.byteLength,\n      lastModified: Date.now(),\n      stream: (): Readable => Readable.from(source),\n      arrayBuffer: async (): Promise<ArrayBuffer> => {\n        return this.bufferToArrayBuffer(source);\n      },\n      text: async (): Promise<string> => {\n        return source.toString(\"utf-8\");\n      },\n    };\n  }\n\n  /**\n   * Creates a FileLike object from a stream.\n   *\n   * @protected\n   */\n  protected createFileFromStream(\n    source: StreamLike,\n    options: {\n      type?: string;\n      name?: string;\n      size?: number;\n    } = {},\n  ): FileLike & { _buffer: null | Buffer } {\n    let buffer: Buffer | null = null;\n\n    return {\n      name: options.name ?? \"file\",\n      type:\n        options.type ?? this.detector.getContentType(options.name ?? \"file\"),\n      size: options.size ?? 0,\n      lastModified: Date.now(),\n      stream: () => source,\n      _buffer: null as Buffer | null,\n      arrayBuffer: async () => {\n        buffer ??= await this.streamToBuffer(source);\n        return this.bufferToArrayBuffer(buffer);\n      },\n      text: async () => {\n        buffer ??= await this.streamToBuffer(source);\n        return buffer.toString(\"utf-8\");\n      },\n    };\n  }\n\n  /**\n   * Creates a FileLike object from a URL.\n   *\n   * @protected\n   */\n  protected createFileFromUrl(\n    url: string,\n    options: {\n      type?: string;\n      name?: string;\n    } = {},\n  ): FileLike {\n    const parsedUrl = new URL(url);\n    const filename =\n      options.name || parsedUrl.pathname.split(\"/\").pop() || \"file\";\n    let buffer: Buffer | null = null;\n\n    return {\n      name: filename,\n      type: options.type ?? this.detector.getContentType(filename),\n      size: 0, // Unknown size until loaded\n      lastModified: Date.now(),\n      stream: () => this.createStreamFromUrl(url),\n      arrayBuffer: async () => {\n        buffer ??= await this.loadFromUrl(url);\n        return this.bufferToArrayBuffer(buffer);\n      },\n      text: async () => {\n        buffer ??= await this.loadFromUrl(url);\n        return buffer.toString(\"utf-8\");\n      },\n      filepath: url,\n    };\n  }\n\n  /**\n   * Gets a streaming response from a URL.\n   *\n   * @protected\n   */\n  protected getStreamingResponse(url: string): Readable {\n    const stream = new PassThrough();\n\n    fetch(url)\n      .then((res) => Readable.fromWeb(res.body as NodeWebStream).pipe(stream))\n      .catch((err) => stream.destroy(err));\n\n    return stream;\n  }\n\n  /**\n   * Loads data from a URL.\n   *\n   * @protected\n   */\n  protected async loadFromUrl(url: string): Promise<Buffer> {\n    const parsedUrl = new URL(url);\n\n    if (parsedUrl.protocol === \"file:\") {\n      // Handle file:// URLs\n      const filePath = fileURLToPath(url);\n      return await fsReadFile(filePath);\n    } else if (\n      parsedUrl.protocol === \"http:\" ||\n      parsedUrl.protocol === \"https:\"\n    ) {\n      // Handle HTTP/HTTPS URLs\n      const response = await fetch(url);\n      if (!response.ok) {\n        throw new Error(\n          `Failed to fetch ${url}: ${response.status} ${response.statusText}`,\n        );\n      }\n      const arrayBuffer = await response.arrayBuffer();\n      return Buffer.from(arrayBuffer);\n    } else {\n      throw new Error(`Unsupported protocol: ${parsedUrl.protocol}`);\n    }\n  }\n\n  /**\n   * Creates a stream from a URL.\n   *\n   * @protected\n   */\n  protected createStreamFromUrl(url: string): Readable {\n    const parsedUrl = new URL(url);\n\n    if (parsedUrl.protocol === \"file:\") {\n      // For file:// URLs, create a stream that reads the file\n      return createReadStream(fileURLToPath(url));\n    } else if (\n      parsedUrl.protocol === \"http:\" ||\n      parsedUrl.protocol === \"https:\"\n    ) {\n      // For HTTP/HTTPS URLs, create a stream that fetches the content\n      return this.getStreamingResponse(url);\n    } else {\n      throw new AlephaError(`Unsupported protocol: ${parsedUrl.protocol}`);\n    }\n  }\n\n  /**\n   * Converts a stream-like object to a Buffer.\n   *\n   * @protected\n   */\n  protected async streamToBuffer(streamLike: StreamLike): Promise<Buffer> {\n    const stream =\n      streamLike instanceof Readable\n        ? streamLike\n        : Readable.fromWeb(streamLike as NodeWebStream);\n\n    return new Promise<Buffer>((resolve, reject) => {\n      const buffer: any[] = [];\n      stream.on(\"data\", (chunk) => buffer.push(Buffer.from(chunk)));\n      stream.on(\"end\", () => resolve(Buffer.concat(buffer)));\n      stream.on(\"error\", (err) =>\n        reject(new AlephaError(\"Error converting stream\", { cause: err })),\n      );\n    });\n  }\n\n  /**\n   * Converts a Node.js Buffer to an ArrayBuffer.\n   *\n   * @protected\n   */\n  protected bufferToArrayBuffer(buffer: Buffer): ArrayBuffer {\n    return buffer.buffer.slice(\n      buffer.byteOffset,\n      buffer.byteOffset + buffer.byteLength,\n    ) as ArrayBuffer;\n  }\n}\n","import { $module } from \"alepha\";\nimport { FileSystemProvider } from \"./providers/FileSystemProvider.ts\";\nimport { NodeFileSystemProvider } from \"./providers/NodeFileSystemProvider.ts\";\nimport { FileDetector } from \"./services/FileDetector.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport * from \"./providers/FileSystemProvider.ts\";\nexport * from \"./providers/NodeFileSystemProvider.ts\";\nexport * from \"./services/FileDetector.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\n/**\n * Provides file system capabilities for Alepha applications with support for multiple file sources and operations.\n *\n * The file module enables working with files from various sources (URLs, buffers, streams) and provides\n * utilities for file type detection, content type determination, and common file system operations.\n *\n * @see {@link FileDetector}\n * @see {@link FileSystemProvider}\n * @see {@link NodeFileSystemProvider}\n * @module alepha.file\n */\nexport const AlephaFile = $module({\n  name: \"alepha.file\",\n  descriptors: [],\n  services: [FileDetector, FileSystemProvider, NodeFileSystemProvider],\n  register: (alepha) =>\n    alepha.with({\n      optional: true,\n      provide: FileSystemProvider,\n      use: NodeFileSystemProvider,\n    }),\n});\n"],"mappings":"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AM;IAAM;IAAM;IAAK;GAAE,UAAU;GAAa,CAAC;EACrE,MAAM,CAAC;GAAE,WAAW;IAAC;IAAM;IAAM;IAAM;IAAK;GAAE,UAAU;GAAc,CAAC;EAGvE,KAAK;GACH;IACE,WAAW;KAAC;KAAM;KAAM;KAAM;KAAM;KAAM;KAAM;KAAM;KAAK;IAC3D,UAAU;IACX;GACD;IACE,WAAW;KACT;KACA;KACA;KACA;KACA;KACA;KACA;KACA;KACA;KACA;KACA;KACA;KACD;IACD,UAAU;IACX;GACD;IACE,WAAW;KACT;KACA;KACA;KACA;KACA;KACA;KACA;KACA;KACA;KACA;KACA;KACA;KACD;IACD,UAAU;IACX;GACF;EACD,MAAM,CAAC;GAAE,WAAW;IAAC;IAAM;IAAM;IAAM;IAAK;GAAE,UAAU;GAAc,CAAC;EACvE,KAAK,CACH;GACE,WAAW;IACT;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACD;GACD,UAAU;GACX,CACF;EACD,KAAK,CACH;GACE,WAAW;IACT;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACD;GACD,UAAU;GACX,CACF;EACD,KAAK,CACH;GAAE,WAAW;IAAC;IAAM;IAAM;IAAM;IAAK;GAAE,UAAU;GAAoB,CACtE;EAGD,MAAM,CACJ;GACE,WAAW;IAAC;IAAM;IAAM;IAAM;IAAK;GACnC,UACE;GACH,CACF;EACD,MAAM,CACJ;GACE,WAAW;IAAC;IAAM;IAAM;IAAM;IAAK;GACnC,UACE;GACH,CACF;EACD,MAAM,CACJ;GACE,WAAW;IAAC;IAAM;IAAM;IAAM;IAAK;GACnC,UACE;GACH,CACF;EACD,KAAK,CACH;GACE,WAAW;IAAC;IAAM;IAAM;IAAM;IAAM;IAAM;IAAM;IAAM;IAAK;GAC3D,UAAU;GACX,CACF;EACD,KAAK,CACH;GACE,WAAW;IAAC;IAAM;IAAM;IAAM;IAAM;IAAM;IAAM;IAAM;IAAK;GAC3D,UAAU;GACX,CACF;EACD,KAAK,CACH;GACE,WAAW;IAAC;IAAM;IAAM;IAAM;IAAM;I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"}
+{"version":3,"file":"index.js","names":["reverse: Record<string, string>","chunks: Buffer[]","fsRm","fsCp","fsMkdir","allFiles: string[]","fsReadFile","fsWriteFile","name: string","buffer: Buffer | null","buffer: any[]"],"sources":["../../src/file/providers/FileSystemProvider.ts","../../src/file/services/FileDetector.ts","../../src/file/providers/NodeFileSystemProvider.ts","../../src/file/index.ts"],"sourcesContent":["import type { FileLike, StreamLike } from \"alepha\";\n\n/**\n * Options for creating a file from a URL\n */\nexport interface CreateFileFromUrlOptions {\n  /**\n   * The URL to load the file from (file://, http://, or https://)\n   */\n  url: string;\n  /**\n   * The MIME type of the file (optional, will be detected from filename if not provided)\n   */\n  type?: string;\n  /**\n   * The name of the file (optional, will be extracted from URL if not provided)\n   */\n  name?: string;\n}\n\n/**\n * Options for creating a file from a path (URL with file:// scheme)\n */\nexport interface CreateFileFromPathOptions {\n  /**\n   * The path to the file on the local filesystem\n   */\n  path: string;\n  /**\n   * The MIME type of the file (optional, will be detected from filename if not provided)\n   */\n  type?: string;\n  /**\n   * The name of the file (optional, will be extracted from URL if not provided)\n   */\n  name?: string;\n}\n\n/**\n * Options for creating a file from a Buffer\n */\nexport interface CreateFileFromBufferOptions {\n  /**\n   * The Buffer containing the file data\n   */\n  buffer: Buffer;\n  /**\n   * The MIME type of the file (optional, will be detected from name if not provided)\n   */\n  type?: string;\n  /**\n   * The name of the file (required for proper content type detection)\n   */\n  name?: string;\n}\n\n/**\n * Options for creating a file from a stream\n */\nexport interface CreateFileFromStreamOptions {\n  /**\n   * The readable stream containing the file data\n   */\n  stream: StreamLike;\n  /**\n   * The MIME type of the file (optional, will be detected from name if not provided)\n   */\n  type?: string;\n  /**\n   * The name of the file (required for proper content type detection)\n   */\n  name?: string;\n  /**\n   * The size of the file in bytes (optional)\n   */\n  size?: number;\n}\n\n/**\n * Options for creating a file from text content\n */\nexport interface CreateFileFromTextOptions {\n  /**\n   * The text content to create the file from\n   */\n  text: string;\n  /**\n   * The MIME type of the file (default: text/plain)\n   */\n  type?: string;\n  /**\n   * The name of the file (default: \"file.txt\")\n   */\n  name?: string;\n}\n\nexport interface CreateFileFromResponseOptions {\n  /**\n   * The Response object containing the file data\n   */\n  response: Response;\n  /**\n   * Override the name (optional, uses filename from Content-Disposition header if not provided)\n   */\n  name?: string;\n  /**\n   * Override the MIME type (optional, uses file.type if not provided)\n   */\n  type?: string;\n}\n\n/**\n * Options for creating a file from a Web File object\n */\nexport interface CreateFileFromWebFileOptions {\n  /**\n   * The Web File object\n   */\n  file: File;\n  /**\n   * Override the MIME type (optional, uses file.type if not provided)\n   */\n  type?: string;\n  /**\n   * Override the name (optional, uses file.name if not provided)\n   */\n  name?: string;\n  /**\n   * Override the size (optional, uses file.size if not provided)\n   */\n  size?: number;\n}\n\n/**\n * Options for creating a file from an ArrayBuffer\n */\nexport interface CreateFileFromArrayBufferOptions {\n  /**\n   * The ArrayBuffer containing the file data\n   */\n  arrayBuffer: ArrayBuffer;\n  /**\n   * The MIME type of the file (optional, will be detected from name if not provided)\n   */\n  type?: string;\n  /**\n   * The name of the file (required for proper content type detection)\n   */\n  name?: string;\n}\n\n/**\n * Union type for all createFile options\n */\nexport type CreateFileOptions =\n  | CreateFileFromUrlOptions\n  | CreateFileFromPathOptions\n  | CreateFileFromBufferOptions\n  | CreateFileFromStreamOptions\n  | CreateFileFromTextOptions\n  | CreateFileFromWebFileOptions\n  | CreateFileFromResponseOptions\n  | CreateFileFromArrayBufferOptions;\n\n/**\n * Options for rm (remove) operation\n */\nexport interface RmOptions {\n  /**\n   * If true, removes directories and their contents recursively\n   */\n  recursive?: boolean;\n  /**\n   * If true, no error will be thrown if the path does not exist\n   */\n  force?: boolean;\n}\n\n/**\n * Options for cp (copy) operation\n */\nexport interface CpOptions {\n  /**\n   * If true, copy directories recursively\n   */\n  recursive?: boolean;\n  /**\n   * If true, overwrite existing destination\n   */\n  force?: boolean;\n}\n\n/**\n * Options for mkdir operation\n */\nexport interface MkdirOptions {\n  /**\n   * If true, creates parent directories as needed\n   */\n  recursive?: boolean;\n  /**\n   * File mode (permission and sticky bits)\n   */\n  mode?: number;\n}\n\n/**\n * Options for ls (list) operation\n */\nexport interface LsOptions {\n  /**\n   * If true, list contents of directories recursively\n   */\n  recursive?: boolean;\n  /**\n   * If true, include hidden files (starting with .)\n   */\n  hidden?: boolean;\n}\n\n/**\n * FileSystem interface providing utilities for working with files.\n */\nexport abstract class FileSystemProvider {\n  /**\n   * Creates a FileLike object from various sources.\n   *\n   * @param options - Options for creating the file\n   * @returns A FileLike object\n   */\n  abstract createFile(options: CreateFileOptions): FileLike;\n\n  /**\n   * Removes a file or directory.\n   *\n   * @param path - The path to remove\n   * @param options - Remove options\n   */\n  abstract rm(path: string, options?: RmOptions): Promise<void>;\n\n  /**\n   * Copies a file or directory.\n   *\n   * @param src - Source path\n   * @param dest - Destination path\n   * @param options - Copy options\n   */\n  abstract cp(src: string, dest: string, options?: CpOptions): Promise<void>;\n\n  /**\n   * Moves/renames a file or directory.\n   *\n   * @param src - Source path\n   * @param dest - Destination path\n   */\n  abstract mv(src: string, dest: string): Promise<void>;\n\n  /**\n   * Creates a directory.\n   *\n   * @param path - The directory path to create\n   * @param options - Mkdir options\n   */\n  abstract mkdir(path: string, options?: MkdirOptions): Promise<void>;\n\n  /**\n   * Lists files in a directory.\n   *\n   * @param path - The directory path to list\n   * @param options - List options\n   * @returns Array of filenames\n   */\n  abstract ls(path: string, options?: LsOptions): Promise<string[]>;\n\n  /**\n   * Checks if a file or directory exists.\n   *\n   * @param path - The path to check\n   * @returns True if the path exists, false otherwise\n   */\n  abstract exists(path: string): Promise<boolean>;\n\n  /**\n   * Reads the content of a file.\n   *\n   * @param path - The file path to read\n   * @returns The file content as a Buffer\n   */\n  abstract readFile(path: string): Promise<Buffer>;\n\n  /**\n   * Writes data to a file.\n   *\n   * @param path - The file path to write to\n   * @param data - The data to write (Buffer or string)\n   */\n  abstract writeFile(\n    path: string,\n    data: Uint8Array | Buffer | string | FileLike,\n  ): Promise<void>;\n}\n","import { Readable } from \"node:stream\";\n\nexport interface FileTypeResult {\n  /**\n   * The detected MIME type\n   */\n  mimeType: string;\n  /**\n   * The detected file extension\n   */\n  extension: string;\n  /**\n   * Whether the file type was verified by magic bytes\n   */\n  verified: boolean;\n  /**\n   * The stream (potentially wrapped to allow re-reading)\n   */\n  stream: Readable;\n}\n\n/**\n * Service for detecting file types and getting content types.\n *\n * @example\n * ```typescript\n * const detector = alepha.inject(FileDetector);\n *\n * // Get content type from filename\n * const mimeType = detector.getContentType(\"image.png\"); // \"image/png\"\n *\n * // Detect file type by magic bytes\n * const stream = createReadStream('image.png');\n * const result = await detector.detectFileType(stream, 'image.png');\n * console.log(result.mimeType); // 'image/png'\n * console.log(result.verified); // true if magic bytes match\n * ```\n */\nexport class FileDetector {\n  /**\n   * Magic byte signatures for common file formats.\n   * Each signature is represented as an array of bytes or null (wildcard).\n   */\n  protected static readonly MAGIC_BYTES: Record<\n    string,\n    { signature: (number | null)[]; mimeType: string }[]\n  > = {\n    // Images\n    png: [\n      {\n        signature: [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a],\n        mimeType: \"image/png\",\n      },\n    ],\n    jpg: [\n      { signature: [0xff, 0xd8, 0xff, 0xe0], mimeType: \"image/jpeg\" },\n      { signature: [0xff, 0xd8, 0xff, 0xe1], mimeType: \"image/jpeg\" },\n      { signature: [0xff, 0xd8, 0xff, 0xe2], mimeType: \"image/jpeg\" },\n      { signature: [0xff, 0xd8, 0xff, 0xe3], mimeType: \"image/jpeg\" },\n      { signature: [0xff, 0xd8, 0xff, 0xe8], mimeType: \"image/jpeg\" },\n    ],\n    jpeg: [\n      { signature: [0xff, 0xd8, 0xff, 0xe0], mimeType: \"image/jpeg\" },\n      { signature: [0xff, 0xd8, 0xff, 0xe1], mimeType: \"image/jpeg\" },\n      { signature: [0xff, 0xd8, 0xff, 0xe2], mimeType: \"image/jpeg\" },\n      { signature: [0xff, 0xd8, 0xff, 0xe3], mimeType: \"image/jpeg\" },\n      { signature: [0xff, 0xd8, 0xff, 0xe8], mimeType: \"image/jpeg\" },\n    ],\n    gif: [\n      {\n        signature: [0x47, 0x49, 0x46, 0x38, 0x37, 0x61],\n        mimeType: \"image/gif\",\n      }, // GIF87a\n      {\n        signature: [0x47, 0x49, 0x46, 0x38, 0x39, 0x61],\n        mimeType: \"image/gif\",\n      }, // GIF89a\n    ],\n    webp: [\n      {\n        signature: [\n          0x52,\n          0x49,\n          0x46,\n          0x46,\n          null,\n          null,\n          null,\n          null,\n          0x57,\n          0x45,\n          0x42,\n          0x50,\n        ],\n        mimeType: \"image/webp\",\n      },\n    ],\n    bmp: [{ signature: [0x42, 0x4d], mimeType: \"image/bmp\" }],\n    ico: [{ signature: [0x00, 0x00, 0x01, 0x00], mimeType: \"image/x-icon\" }],\n    tiff: [\n      { signature: [0x49, 0x49, 0x2a, 0x00], mimeType: \"image/tiff\" }, // Little-endian\n      { signature: [0x4d, 0x4d, 0x00, 0x2a], mimeType: \"image/tiff\" }, // Big-endian\n    ],\n    tif: [\n      { signature: [0x49, 0x49, 0x2a, 0x00], mimeType: \"image/tiff\" },\n      { signature: [0x4d, 0x4d, 0x00, 0x2a], mimeType: \"image/tiff\" },\n    ],\n\n    // Documents\n    pdf: [\n      {\n        signature: [0x25, 0x50, 0x44, 0x46, 0x2d],\n        mimeType: \"application/pdf\",\n      },\n    ], // %PDF-\n    zip: [\n      { signature: [0x50, 0x4b, 0x03, 0x04], mimeType: \"application/zip\" },\n      { signature: [0x50, 0x4b, 0x05, 0x06], mimeType: \"application/zip\" },\n      { signature: [0x50, 0x4b, 0x07, 0x08], mimeType: \"application/zip\" },\n    ],\n\n    // Archives\n    rar: [\n      {\n        signature: [0x52, 0x61, 0x72, 0x21, 0x1a, 0x07],\n        mimeType: \"application/vnd.rar\",\n      },\n    ],\n    \"7z\": [\n      {\n        signature: [0x37, 0x7a, 0xbc, 0xaf, 0x27, 0x1c],\n        mimeType: \"application/x-7z-compressed\",\n      },\n    ],\n    tar: [\n      {\n        signature: [0x75, 0x73, 0x74, 0x61, 0x72],\n        mimeType: \"application/x-tar\",\n      },\n    ],\n    gz: [{ signature: [0x1f, 0x8b], mimeType: \"application/gzip\" }],\n    tgz: [{ signature: [0x1f, 0x8b], mimeType: \"application/gzip\" }],\n\n    // Audio\n    mp3: [\n      { signature: [0xff, 0xfb], mimeType: \"audio/mpeg\" },\n      { signature: [0xff, 0xf3], mimeType: \"audio/mpeg\" },\n      { signature: [0xff, 0xf2], mimeType: \"audio/mpeg\" },\n      { signature: [0x49, 0x44, 0x33], mimeType: \"audio/mpeg\" }, // ID3\n    ],\n    wav: [\n      {\n        signature: [\n          0x52,\n          0x49,\n          0x46,\n          0x46,\n          null,\n          null,\n          null,\n          null,\n          0x57,\n          0x41,\n          0x56,\n          0x45,\n        ],\n        mimeType: \"audio/wav\",\n      },\n    ],\n    ogg: [{ signature: [0x4f, 0x67, 0x67, 0x53], mimeType: \"audio/ogg\" }],\n    flac: [{ signature: [0x66, 0x4c, 0x61, 0x43], mimeType: \"audio/flac\" }], // fLaC\n\n    // Video\n    mp4: [\n      {\n        signature: [null, null, null, null, 0x66, 0x74, 0x79, 0x70],\n        mimeType: \"video/mp4\",\n      }, // ftyp\n      {\n        signature: [\n          null,\n          null,\n          null,\n          null,\n          0x66,\n          0x74,\n          0x79,\n          0x70,\n          0x69,\n          0x73,\n          0x6f,\n          0x6d,\n        ],\n        mimeType: \"video/mp4\",\n      }, // ftypisom\n      {\n        signature: [\n          null,\n          null,\n          null,\n          null,\n          0x66,\n          0x74,\n          0x79,\n          0x70,\n          0x6d,\n          0x70,\n          0x34,\n          0x32,\n        ],\n        mimeType: \"video/mp4\",\n      }, // ftypmp42\n    ],\n    webm: [{ signature: [0x1a, 0x45, 0xdf, 0xa3], mimeType: \"video/webm\" }],\n    avi: [\n      {\n        signature: [\n          0x52,\n          0x49,\n          0x46,\n          0x46,\n          null,\n          null,\n          null,\n          null,\n          0x41,\n          0x56,\n          0x49,\n          0x20,\n        ],\n        mimeType: \"video/x-msvideo\",\n      },\n    ],\n    mov: [\n      {\n        signature: [\n          null,\n          null,\n          null,\n          null,\n          0x66,\n          0x74,\n          0x79,\n          0x70,\n          0x71,\n          0x74,\n          0x20,\n          0x20,\n        ],\n        mimeType: \"video/quicktime\",\n      },\n    ],\n    mkv: [\n      { signature: [0x1a, 0x45, 0xdf, 0xa3], mimeType: \"video/x-matroska\" },\n    ],\n\n    // Office (DOCX, XLSX, PPTX are all ZIP-based)\n    docx: [\n      {\n        signature: [0x50, 0x4b, 0x03, 0x04],\n        mimeType:\n          \"application/vnd.openxmlformats-officedocument.wordprocessingml.document\",\n      },\n    ],\n    xlsx: [\n      {\n        signature: [0x50, 0x4b, 0x03, 0x04],\n        mimeType:\n          \"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet\",\n      },\n    ],\n    pptx: [\n      {\n        signature: [0x50, 0x4b, 0x03, 0x04],\n        mimeType:\n          \"application/vnd.openxmlformats-officedocument.presentationml.presentation\",\n      },\n    ],\n    doc: [\n      {\n        signature: [0xd0, 0xcf, 0x11, 0xe0, 0xa1, 0xb1, 0x1a, 0xe1],\n        mimeType: \"application/msword\",\n      },\n    ],\n    xls: [\n      {\n        signature: [0xd0, 0xcf, 0x11, 0xe0, 0xa1, 0xb1, 0x1a, 0xe1],\n        mimeType: \"application/vnd.ms-excel\",\n      },\n    ],\n    ppt: [\n      {\n        signature: [0xd0, 0xcf, 0x11, 0xe0, 0xa1, 0xb1, 0x1a, 0xe1],\n        mimeType: \"application/vnd.ms-powerpoint\",\n      },\n    ],\n  };\n\n  /**\n   * All possible format signatures for checking against actual file content\n   */\n  protected static readonly ALL_SIGNATURES = Object.entries(\n    FileDetector.MAGIC_BYTES,\n  ).flatMap(([ext, signatures]) => signatures.map((sig) => ({ ext, ...sig })));\n\n  /**\n   * MIME type map for file extensions.\n   *\n   * Can be used to get the content type of file based on its extension.\n   * Feel free to add more mime types in your project!\n   */\n  public static readonly mimeMap: Record<string, string> = {\n    // Documents\n    json: \"application/json\",\n    txt: \"text/plain\",\n    html: \"text/html\",\n    htm: \"text/html\",\n    xml: \"application/xml\",\n    csv: \"text/csv\",\n    pdf: \"application/pdf\",\n    md: \"text/markdown\",\n    markdown: \"text/markdown\",\n    rtf: \"application/rtf\",\n\n    // Styles and scripts\n    css: \"text/css\",\n    js: \"application/javascript\",\n    mjs: \"application/javascript\",\n    ts: \"application/typescript\",\n    jsx: \"text/jsx\",\n    tsx: \"text/tsx\",\n\n    // Archives\n    zip: \"application/zip\",\n    rar: \"application/vnd.rar\",\n    \"7z\": \"application/x-7z-compressed\",\n    tar: \"application/x-tar\",\n    gz: \"application/gzip\",\n    tgz: \"application/gzip\",\n\n    // Images\n    png: \"image/png\",\n    jpg: \"image/jpeg\",\n    jpeg: \"image/jpeg\",\n    gif: \"image/gif\",\n    webp: \"image/webp\",\n    svg: \"image/svg+xml\",\n    bmp: \"image/bmp\",\n    ico: \"image/x-icon\",\n    tiff: \"image/tiff\",\n    tif: \"image/tiff\",\n\n    // Audio\n    mp3: \"audio/mpeg\",\n    wav: \"audio/wav\",\n    ogg: \"audio/ogg\",\n    m4a: \"audio/mp4\",\n    aac: \"audio/aac\",\n    flac: \"audio/flac\",\n\n    // Video\n    mp4: \"video/mp4\",\n    webm: \"video/webm\",\n    avi: \"video/x-msvideo\",\n    mov: \"video/quicktime\",\n    wmv: \"video/x-ms-wmv\",\n    flv: \"video/x-flv\",\n    mkv: \"video/x-matroska\",\n\n    // Office\n    doc: \"application/msword\",\n    docx: \"application/vnd.openxmlformats-officedocument.wordprocessingml.document\",\n    xls: \"application/vnd.ms-excel\",\n    xlsx: \"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet\",\n    ppt: \"application/vnd.ms-powerpoint\",\n    pptx: \"application/vnd.openxmlformats-officedocument.presentationml.presentation\",\n\n    // Fonts\n    woff: \"font/woff\",\n    woff2: \"font/woff2\",\n    ttf: \"font/ttf\",\n    otf: \"font/otf\",\n    eot: \"application/vnd.ms-fontobject\",\n  };\n\n  /**\n   * Reverse MIME type map for looking up extensions from MIME types.\n   * Prefers shorter, more common extensions when multiple exist.\n   */\n  protected static readonly reverseMimeMap: Record<string, string> = (() => {\n    const reverse: Record<string, string> = {};\n    // Process in order so common extensions come first\n    for (const [ext, mimeType] of Object.entries(FileDetector.mimeMap)) {\n      // Only set if not already set (prefer first/shorter extension)\n      if (!reverse[mimeType]) {\n        reverse[mimeType] = ext;\n      }\n    }\n    return reverse;\n  })();\n\n  /**\n   * Returns the file extension for a given MIME type.\n   *\n   * @param mimeType - The MIME type to look up\n   * @returns The file extension (without dot), or \"bin\" if not found\n   *\n   * @example\n   * ```typescript\n   * const detector = alepha.inject(FileDetector);\n   * const ext = detector.getExtensionFromMimeType(\"image/png\"); // \"png\"\n   * const ext2 = detector.getExtensionFromMimeType(\"application/octet-stream\"); // \"bin\"\n   * ```\n   */\n  getExtensionFromMimeType(mimeType: string): string {\n    return FileDetector.reverseMimeMap[mimeType] || \"bin\";\n  }\n  /**\n   * Returns the content type of file based on its filename.\n   *\n   * @param filename - The filename to check\n   * @returns The MIME type\n   *\n   * @example\n   * ```typescript\n   * const detector = alepha.inject(FileDetector);\n   * const mimeType = detector.getContentType(\"image.png\"); // \"image/png\"\n   * ```\n   */\n  getContentType(filename: string): string {\n    const ext = filename.toLowerCase().split(\".\").pop() || \"\";\n    return FileDetector.mimeMap[ext] || \"application/octet-stream\";\n  }\n\n  /**\n   * Detects the file type by checking magic bytes against the stream content.\n   *\n   * @param stream - The readable stream to check\n   * @param filename - The filename (used to get the extension)\n   * @returns File type information including MIME type, extension, and verification status\n   *\n   * @example\n   * ```typescript\n   * const detector = alepha.inject(FileDetector);\n   * const stream = createReadStream('image.png');\n   * const result = await detector.detectFileType(stream, 'image.png');\n   * console.log(result.mimeType); // 'image/png'\n   * console.log(result.verified); // true if magic bytes match\n   * ```\n   */\n  async detectFileType(\n    stream: Readable,\n    filename: string,\n  ): Promise<FileTypeResult> {\n    // Get the expected MIME type from the filename extension\n    const expectedMimeType = this.getContentType(filename);\n\n    // Extract extension - only if filename contains a dot\n    const lastDotIndex = filename.lastIndexOf(\".\");\n    const ext =\n      lastDotIndex > 0\n        ? filename.substring(lastDotIndex + 1).toLowerCase()\n        : \"\";\n\n    // Read the first 16 bytes (enough for most magic byte checks)\n    const { buffer, stream: newStream } = await this.peekBytes(stream, 16);\n\n    // First, check if the extension's expected signature matches\n    const expectedSignatures = FileDetector.MAGIC_BYTES[ext];\n    if (expectedSignatures) {\n      for (const { signature, mimeType } of expectedSignatures) {\n        if (this.matchesSignature(buffer, signature)) {\n          return {\n            mimeType,\n            extension: ext,\n            verified: true,\n            stream: newStream,\n          };\n        }\n      }\n    }\n\n    // If the expected signature didn't match, try all other signatures\n    for (const {\n      ext: detectedExt,\n      signature,\n      mimeType,\n    } of FileDetector.ALL_SIGNATURES) {\n      if (detectedExt !== ext && this.matchesSignature(buffer, signature)) {\n        return {\n          mimeType,\n          extension: detectedExt,\n          verified: true,\n          stream: newStream,\n        };\n      }\n    }\n\n    // If no magic bytes matched, fall back to extension-based detection\n    // or return binary if extension is not recognized\n    return {\n      mimeType: expectedMimeType,\n      extension: ext,\n      verified: false,\n      stream: newStream,\n    };\n  }\n\n  /**\n   * Reads all bytes from a stream and returns the first N bytes along with a new stream containing all data.\n   * This approach reads the entire stream upfront to avoid complex async handling issues.\n   *\n   * @protected\n   */\n  protected async peekBytes(\n    stream: Readable,\n    numBytes: number,\n  ): Promise<{ buffer: Buffer; stream: Readable }> {\n    const chunks: Buffer[] = [];\n\n    // Read the entire stream\n    for await (const chunk of stream) {\n      chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));\n    }\n\n    const allData = Buffer.concat(chunks);\n    const buffer = allData.subarray(0, numBytes);\n\n    // Create a new stream with all the data\n    const newStream = Readable.from(allData);\n\n    return { buffer, stream: newStream };\n  }\n\n  /**\n   * Checks if a buffer matches a magic byte signature.\n   *\n   * @protected\n   */\n  protected matchesSignature(\n    buffer: Buffer,\n    signature: (number | null)[],\n  ): boolean {\n    if (buffer.length < signature.length) {\n      return false;\n    }\n\n    for (let i = 0; i < signature.length; i++) {\n      if (signature[i] !== null && buffer[i] !== signature[i]) {\n        return false;\n      }\n    }\n\n    return true;\n  }\n}\n","import { createReadStream } from \"node:fs\";\nimport {\n  access,\n  copyFile,\n  cp as fsCp,\n  mkdir as fsMkdir,\n  readFile as fsReadFile,\n  rm as fsRm,\n  writeFile as fsWriteFile,\n  readdir,\n  rename,\n  stat,\n} from \"node:fs/promises\";\nimport { join } from \"node:path\";\nimport { PassThrough, Readable } from \"node:stream\";\nimport type { ReadableStream as NodeWebStream } from \"node:stream/web\";\nimport { fileURLToPath } from \"node:url\";\nimport {\n  $inject,\n  AlephaError,\n  type FileLike,\n  isFileLike,\n  type StreamLike,\n} from \"alepha\";\nimport { FileDetector } from \"../services/FileDetector.ts\";\nimport type {\n  CpOptions,\n  CreateFileOptions,\n  FileSystemProvider,\n  LsOptions,\n  MkdirOptions,\n  RmOptions,\n} from \"./FileSystemProvider.ts\";\n\n/**\n * Node.js implementation of FileSystem interface.\n *\n * @example\n * ```typescript\n * const fs = alepha.inject(NodeFileSystemProvider);\n *\n * // Create from URL\n * const file1 = fs.createFile({ url: \"file:///path/to/file.png\" });\n *\n * // Create from Buffer\n * const file2 = fs.createFile({ buffer: Buffer.from(\"hello\"), name: \"hello.txt\" });\n *\n * // Create from text\n * const file3 = fs.createFile({ text: \"Hello, world!\", name: \"greeting.txt\" });\n *\n * // File operations\n * await fs.mkdir(\"/tmp/mydir\", { recursive: true });\n * await fs.cp(\"/src/file.txt\", \"/dest/file.txt\");\n * await fs.mv(\"/old/path.txt\", \"/new/path.txt\");\n * const files = await fs.ls(\"/tmp\");\n * await fs.rm(\"/tmp/file.txt\");\n * ```\n */\nexport class NodeFileSystemProvider implements FileSystemProvider {\n  protected detector = $inject(FileDetector);\n  /**\n   * Creates a FileLike object from various sources.\n   *\n   * @param options - Options for creating the file\n   * @returns A FileLike object\n   *\n   * @example\n   * ```typescript\n   * const fs = alepha.inject(NodeFileSystemProvider);\n   *\n   * // From URL\n   * const file1 = fs.createFile({ url: \"https://example.com/image.png\" });\n   *\n   * // From Buffer\n   * const file2 = fs.createFile({\n   *   buffer: Buffer.from(\"hello\"),\n   *   name: \"hello.txt\",\n   *   type: \"text/plain\"\n   * });\n   *\n   * // From text\n   * const file3 = fs.createFile({ text: \"Hello!\", name: \"greeting.txt\" });\n   *\n   * // From stream with detection\n   * const stream = createReadStream(\"/path/to/file.png\");\n   * const file4 = fs.createFile({ stream, name: \"image.png\" });\n   * ```\n   */\n  createFile(options: CreateFileOptions): FileLike {\n    if (\"path\" in options) {\n      const path = options.path;\n      const filename = path.split(\"/\").pop() || \"file\";\n      return this.createFileFromUrl(`file://${path}`, {\n        type: options.type,\n        name: options.name || filename,\n      });\n    }\n\n    // Handle URL\n    if (\"url\" in options) {\n      return this.createFileFromUrl(options.url, {\n        type: options.type,\n        name: options.name,\n      });\n    }\n\n    if (\"response\" in options) {\n      if (!options.response.body) {\n        throw new AlephaError(\"Response has no body stream\");\n      }\n      const res = options.response;\n      // guess size from content-length header if available\n      const sizeHeader = res.headers.get(\"content-length\");\n      const size = sizeHeader ? parseInt(sizeHeader, 10) : undefined;\n      // guess name from content-disposition header if available\n      let name = options.name;\n      const contentDisposition = res.headers.get(\"content-disposition\");\n      if (contentDisposition && !name) {\n        const match = contentDisposition.match(/filename=\"?([^\"]+)\"?/);\n        if (match) {\n          name = match[1];\n        }\n      }\n      // guess type from content-type header if available\n      const type = options.type || res.headers.get(\"content-type\") || undefined;\n      return this.createFileFromStream(options.response.body, {\n        type,\n        name,\n        size,\n      });\n    }\n\n    // Handle Web File\n    if (\"file\" in options) {\n      return this.createFileFromWebFile(options.file, {\n        type: options.type,\n        name: options.name,\n        size: options.size,\n      });\n    }\n\n    // Handle Buffer\n    if (\"buffer\" in options) {\n      return this.createFileFromBuffer(options.buffer, {\n        type: options.type,\n        name: options.name,\n      });\n    }\n\n    // Handle ArrayBuffer\n    if (\"arrayBuffer\" in options) {\n      return this.createFileFromBuffer(Buffer.from(options.arrayBuffer), {\n        type: options.type,\n        name: options.name,\n      });\n    }\n\n    // Handle text\n    if (\"text\" in options) {\n      return this.createFileFromBuffer(Buffer.from(options.text, \"utf-8\"), {\n        type: options.type || \"text/plain\",\n        name: options.name || \"file.txt\",\n      });\n    }\n\n    // Handle stream\n    if (\"stream\" in options) {\n      return this.createFileFromStream(options.stream, {\n        type: options.type,\n        name: options.name,\n        size: options.size,\n      });\n    }\n\n    throw new AlephaError(\n      \"Invalid createFile options: no valid source provided\",\n    );\n  }\n\n  /**\n   * Removes a file or directory.\n   *\n   * @param path - The path to remove\n   * @param options - Remove options\n   *\n   * @example\n   * ```typescript\n   * const fs = alepha.inject(NodeFileSystemProvider);\n   *\n   * // Remove a file\n   * await fs.rm(\"/tmp/file.txt\");\n   *\n   * // Remove a directory recursively\n   * await fs.rm(\"/tmp/mydir\", { recursive: true });\n   *\n   * // Remove with force (no error if doesn't exist)\n   * await fs.rm(\"/tmp/maybe-exists.txt\", { force: true });\n   * ```\n   */\n  async rm(path: string, options?: RmOptions): Promise<void> {\n    await fsRm(path, options);\n  }\n\n  /**\n   * Copies a file or directory.\n   *\n   * @param src - Source path\n   * @param dest - Destination path\n   * @param options - Copy options\n   *\n   * @example\n   * ```typescript\n   * const fs = alepha.inject(NodeFileSystemProvider);\n   *\n   * // Copy a file\n   * await fs.cp(\"/src/file.txt\", \"/dest/file.txt\");\n   *\n   * // Copy a directory recursively\n   * await fs.cp(\"/src/dir\", \"/dest/dir\", { recursive: true });\n   *\n   * // Copy with force (overwrite existing)\n   * await fs.cp(\"/src/file.txt\", \"/dest/file.txt\", { force: true });\n   * ```\n   */\n  async cp(src: string, dest: string, options?: CpOptions): Promise<void> {\n    // Check if source is a directory\n    const srcStat = await stat(src);\n\n    if (srcStat.isDirectory()) {\n      if (!options?.recursive) {\n        throw new Error(\n          `Cannot copy directory without recursive option: ${src}`,\n        );\n      }\n      // Use Node.js cp function for recursive directory copy\n      await fsCp(src, dest, {\n        recursive: true,\n        force: options?.force ?? false,\n      });\n    } else {\n      // For files, use copyFile\n      await copyFile(src, dest);\n    }\n  }\n\n  /**\n   * Moves/renames a file or directory.\n   *\n   * @param src - Source path\n   * @param dest - Destination path\n   *\n   * @example\n   * ```typescript\n   * const fs = alepha.inject(NodeFileSystemProvider);\n   *\n   * // Move/rename a file\n   * await fs.mv(\"/old/path.txt\", \"/new/path.txt\");\n   *\n   * // Move a directory\n   * await fs.mv(\"/old/dir\", \"/new/dir\");\n   * ```\n   */\n  async mv(src: string, dest: string): Promise<void> {\n    await rename(src, dest);\n  }\n\n  /**\n   * Creates a directory.\n   *\n   * @param path - The directory path to create\n   * @param options - Mkdir options\n   *\n   * @example\n   * ```typescript\n   * const fs = alepha.inject(NodeFileSystemProvider);\n   *\n   * // Create a directory\n   * await fs.mkdir(\"/tmp/mydir\");\n   *\n   * // Create nested directories\n   * await fs.mkdir(\"/tmp/path/to/dir\", { recursive: true });\n   *\n   * // Create with specific permissions\n   * await fs.mkdir(\"/tmp/mydir\", { mode: 0o755 });\n   * ```\n   */\n  async mkdir(path: string, options?: MkdirOptions): Promise<void> {\n    await fsMkdir(path, options);\n  }\n\n  /**\n   * Lists files in a directory.\n   *\n   * @param path - The directory path to list\n   * @param options - List options\n   * @returns Array of filenames\n   *\n   * @example\n   * ```typescript\n   * const fs = alepha.inject(NodeFileSystemProvider);\n   *\n   * // List files in a directory\n   * const files = await fs.ls(\"/tmp\");\n   * console.log(files); // [\"file1.txt\", \"file2.txt\", \"subdir\"]\n   *\n   * // List with hidden files\n   * const allFiles = await fs.ls(\"/tmp\", { hidden: true });\n   *\n   * // List recursively\n   * const allFilesRecursive = await fs.ls(\"/tmp\", { recursive: true });\n   * ```\n   */\n  async ls(path: string, options?: LsOptions): Promise<string[]> {\n    const entries = await readdir(path);\n\n    // Filter out hidden files if not requested\n    const filteredEntries = options?.hidden\n      ? entries\n      : entries.filter((e) => !e.startsWith(\".\"));\n\n    // If recursive, get all nested files\n    if (options?.recursive) {\n      const allFiles: string[] = [];\n\n      for (const entry of filteredEntries) {\n        const fullPath = join(path, entry);\n        const entryStat = await stat(fullPath);\n\n        if (entryStat.isDirectory()) {\n          // Add directory entry\n          allFiles.push(entry);\n          // Recursively get files from subdirectory\n          const subFiles = await this.ls(fullPath, options);\n          allFiles.push(...subFiles.map((f) => join(entry, f)));\n        } else {\n          allFiles.push(entry);\n        }\n      }\n\n      return allFiles;\n    }\n\n    return filteredEntries;\n  }\n\n  /**\n   * Checks if a file or directory exists.\n   *\n   * @param path - The path to check\n   * @returns True if the path exists, false otherwise\n   *\n   * @example\n   * ```typescript\n   * const fs = alepha.inject(NodeFileSystemProvider);\n   *\n   * if (await fs.exists(\"/tmp/file.txt\")) {\n   *   console.log(\"File exists\");\n   * }\n   * ```\n   */\n  async exists(path: string): Promise<boolean> {\n    try {\n      await access(path);\n      return true;\n    } catch {\n      return false;\n    }\n  }\n\n  /**\n   * Reads the content of a file.\n   *\n   * @param path - The file path to read\n   * @returns The file content as a Buffer\n   *\n   * @example\n   * ```typescript\n   * const fs = alepha.inject(NodeFileSystemProvider);\n   *\n   * const buffer = await fs.readFile(\"/tmp/file.txt\");\n   * console.log(buffer.toString(\"utf-8\"));\n   * ```\n   */\n  async readFile(path: string): Promise<Buffer> {\n    return await fsReadFile(path);\n  }\n\n  /**\n   * Writes data to a file.\n   *\n   * @param path - The file path to write to\n   * @param data - The data to write (Buffer or string)\n   *\n   * @example\n   * ```typescript\n   * const fs = alepha.inject(NodeFileSystemProvider);\n   *\n   * // Write string\n   * await fs.writeFile(\"/tmp/file.txt\", \"Hello, world!\");\n   *\n   * // Write Buffer\n   * await fs.writeFile(\"/tmp/file.bin\", Buffer.from([0x01, 0x02, 0x03]));\n   * ```\n   */\n  async writeFile(\n    path: string,\n    data: Uint8Array | Buffer | string | FileLike,\n  ): Promise<void> {\n    if (isFileLike(data)) {\n      await fsWriteFile(path, Readable.from(data.stream()));\n      return;\n    }\n    await fsWriteFile(path, data);\n  }\n\n  /**\n   * Creates a FileLike object from a Web File.\n   *\n   * @protected\n   */\n  protected createFileFromWebFile(\n    source: File,\n    options: {\n      type?: string;\n      name?: string;\n      size?: number;\n    } = {},\n  ): FileLike {\n    const name = options.name ?? source.name;\n    return {\n      name,\n      type: options.type ?? (source.type || this.detector.getContentType(name)),\n      size: options.size ?? source.size ?? 0,\n      lastModified: source.lastModified || Date.now(),\n      stream: () => source.stream(),\n      arrayBuffer: async (): Promise<ArrayBuffer> => {\n        return await source.arrayBuffer();\n      },\n      text: async (): Promise<string> => {\n        return await source.text();\n      },\n    };\n  }\n\n  /**\n   * Creates a FileLike object from a Buffer.\n   *\n   * @protected\n   */\n  protected createFileFromBuffer(\n    source: Buffer,\n    options: {\n      type?: string;\n      name?: string;\n    } = {},\n  ): FileLike {\n    const name: string = options.name ?? \"file\";\n    return {\n      name,\n      type: options.type ?? this.detector.getContentType(options.name ?? name),\n      size: source.byteLength,\n      lastModified: Date.now(),\n      stream: (): Readable => Readable.from(source),\n      arrayBuffer: async (): Promise<ArrayBuffer> => {\n        return this.bufferToArrayBuffer(source);\n      },\n      text: async (): Promise<string> => {\n        return source.toString(\"utf-8\");\n      },\n    };\n  }\n\n  /**\n   * Creates a FileLike object from a stream.\n   *\n   * @protected\n   */\n  protected createFileFromStream(\n    source: StreamLike,\n    options: {\n      type?: string;\n      name?: string;\n      size?: number;\n    } = {},\n  ): FileLike & { _buffer: null | Buffer } {\n    let buffer: Buffer | null = null;\n\n    return {\n      name: options.name ?? \"file\",\n      type:\n        options.type ?? this.detector.getContentType(options.name ?? \"file\"),\n      size: options.size ?? 0,\n      lastModified: Date.now(),\n      stream: () => source,\n      _buffer: null as Buffer | null,\n      arrayBuffer: async () => {\n        buffer ??= await this.streamToBuffer(source);\n        return this.bufferToArrayBuffer(buffer);\n      },\n      text: async () => {\n        buffer ??= await this.streamToBuffer(source);\n        return buffer.toString(\"utf-8\");\n      },\n    };\n  }\n\n  /**\n   * Creates a FileLike object from a URL.\n   *\n   * @protected\n   */\n  protected createFileFromUrl(\n    url: string,\n    options: {\n      type?: string;\n      name?: string;\n    } = {},\n  ): FileLike {\n    const parsedUrl = new URL(url);\n    const filename =\n      options.name || parsedUrl.pathname.split(\"/\").pop() || \"file\";\n    let buffer: Buffer | null = null;\n\n    return {\n      name: filename,\n      type: options.type ?? this.detector.getContentType(filename),\n      size: 0, // Unknown size until loaded\n      lastModified: Date.now(),\n      stream: () => this.createStreamFromUrl(url),\n      arrayBuffer: async () => {\n        buffer ??= await this.loadFromUrl(url);\n        return this.bufferToArrayBuffer(buffer);\n      },\n      text: async () => {\n        buffer ??= await this.loadFromUrl(url);\n        return buffer.toString(\"utf-8\");\n      },\n      filepath: url,\n    };\n  }\n\n  /**\n   * Gets a streaming response from a URL.\n   *\n   * @protected\n   */\n  protected getStreamingResponse(url: string): Readable {\n    const stream = new PassThrough();\n\n    fetch(url)\n      .then((res) => Readable.fromWeb(res.body as NodeWebStream).pipe(stream))\n      .catch((err) => stream.destroy(err));\n\n    return stream;\n  }\n\n  /**\n   * Loads data from a URL.\n   *\n   * @protected\n   */\n  protected async loadFromUrl(url: string): Promise<Buffer> {\n    const parsedUrl = new URL(url);\n\n    if (parsedUrl.protocol === \"file:\") {\n      // Handle file:// URLs\n      const filePath = fileURLToPath(url);\n      return await fsReadFile(filePath);\n    } else if (\n      parsedUrl.protocol === \"http:\" ||\n      parsedUrl.protocol === \"https:\"\n    ) {\n      // Handle HTTP/HTTPS URLs\n      const response = await fetch(url);\n      if (!response.ok) {\n        throw new Error(\n          `Failed to fetch ${url}: ${response.status} ${response.statusText}`,\n        );\n      }\n      const arrayBuffer = await response.arrayBuffer();\n      return Buffer.from(arrayBuffer);\n    } else {\n      throw new Error(`Unsupported protocol: ${parsedUrl.protocol}`);\n    }\n  }\n\n  /**\n   * Creates a stream from a URL.\n   *\n   * @protected\n   */\n  protected createStreamFromUrl(url: string): Readable {\n    const parsedUrl = new URL(url);\n\n    if (parsedUrl.protocol === \"file:\") {\n      // For file:// URLs, create a stream that reads the file\n      return createReadStream(fileURLToPath(url));\n    } else if (\n      parsedUrl.protocol === \"http:\" ||\n      parsedUrl.protocol === \"https:\"\n    ) {\n      // For HTTP/HTTPS URLs, create a stream that fetches the content\n      return this.getStreamingResponse(url);\n    } else {\n      throw new AlephaError(`Unsupported protocol: ${parsedUrl.protocol}`);\n    }\n  }\n\n  /**\n   * Converts a stream-like object to a Buffer.\n   *\n   * @protected\n   */\n  protected async streamToBuffer(streamLike: StreamLike): Promise<Buffer> {\n    const stream =\n      streamLike instanceof Readable\n        ? streamLike\n        : Readable.fromWeb(streamLike as NodeWebStream);\n\n    return new Promise<Buffer>((resolve, reject) => {\n      const buffer: any[] = [];\n      stream.on(\"data\", (chunk) => buffer.push(Buffer.from(chunk)));\n      stream.on(\"end\", () => resolve(Buffer.concat(buffer)));\n      stream.on(\"error\", (err) =>\n        reject(new AlephaError(\"Error converting stream\", { cause: err })),\n      );\n    });\n  }\n\n  /**\n   * Converts a Node.js Buffer to an ArrayBuffer.\n   *\n   * @protected\n   */\n  protected bufferToArrayBuffer(buffer: Buffer): ArrayBuffer {\n    return buffer.buffer.slice(\n      buffer.byteOffset,\n      buffer.byteOffset + buffer.byteLength,\n    ) as ArrayBuffer;\n  }\n}\n","import { $module } from \"alepha\";\nimport { FileSystemProvider } from \"./providers/FileSystemProvider.ts\";\nimport { NodeFileSystemProvider } from \"./providers/NodeFileSystemProvider.ts\";\nimport { FileDetector } from \"./services/FileDetector.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport * from \"./providers/FileSystemProvider.ts\";\nexport * from \"./providers/NodeFileSystemProvider.ts\";\nexport * from \"./services/FileDetector.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\n/**\n * Provides file system capabilities for Alepha applications with support for multiple file sources and operations.\n *\n * The file module enables working with files from various sources (URLs, buffers, streams) and provides\n * utilities for file type detection, content type determination, and common file system operations.\n *\n * @see {@link FileDetector}\n * @see {@link FileSystemProvider}\n * @see {@link NodeFileSystemProvider}\n * @module alepha.file\n */\nexport const AlephaFile = $module({\n  name: \"alepha.file\",\n  primitives: [],\n  services: [FileDetector, FileSystemProvider, NodeFileSystemProvider],\n  register: (alepha) =>\n    alepha.with({\n      optional: true,\n      provide: FileSystemProvider,\n      use: NodeFileSystemProvider,\n    }),\n});\n"],"mappings":"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AM;IAAM;IAAM;IAAK;GAAE,UAAU;GAAa,CAAC;EACrE,MAAM,CAAC;GAAE,WAAW;IAAC;IAAM;IAAM;IAAM;IAAK;GAAE,UAAU;GAAc,CAAC;EAGvE,KAAK;GACH;IACE,WAAW;KAAC;KAAM;KAAM;KAAM;KAAM;KAAM;KAAM;KAAM;KAAK;IAC3D,UAAU;IACX;GACD;IACE,WAAW;KACT;KACA;KACA;KACA;KACA;KACA;KACA;KACA;KACA;KACA;KACA;KACA;KACD;IACD,UAAU;IACX;GACD;IACE,WAAW;KACT;KACA;KACA;KACA;KACA;KACA;KACA;KACA;KACA;KACA;KACA;KACA;KACD;IACD,UAAU;IACX;GACF;EACD,MAAM,CAAC;GAAE,WAAW;IAAC;IAAM;IAAM;IAAM;IAAK;GAAE,UAAU;GAAc,CAAC;EACvE,KAAK,CACH;GACE,WAAW;IACT;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACD;GACD,UAAU;GACX,CACF;EACD,KAAK,CACH;GACE,WAAW;IACT;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACD;GACD,UAAU;GACX,CACF;EACD,KAAK,CACH;GAAE,WAAW;IAAC;IAAM;IAAM;IAAM;IAAK;GAAE,UAAU;GAAoB,CACtE;EAGD,MAAM,CACJ;GACE,WAAW;IAAC;IAAM;IAAM;IAAM;IAAK;GACnC,UACE;GACH,CACF;EACD,MAAM,CACJ;GACE,WAAW;IAAC;IAAM;IAAM;IAAM;IAAK;GACnC,UACE;GACH,CACF;EACD,MAAM,CACJ;GACE,WAAW;IAAC;IAAM;IAAM;IAAM;IAAK;GACnC,UACE;GACH,CACF;EACD,KAAK,CACH;GACE,WAAW;IAAC;IAAM;IAAM;IAAM;IAAM;IAAM;IAAM;IAAM;IAAK;GAC3D,UAAU;GACX,CACF;EACD,KAAK,CACH;GACE,WAAW;IAAC;IAAM;IAAM;IAAM;IAAM;IAAM;IAAM;IAAM;IAAK;GAC3D,UAAU;GACX,CACF;EACD,KAAK,CACH;GACE,WAAW;IAAC;IAAM;IAAM;IAAM;IAAM;I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"}

package/dist/lock/index.d.ts

@@ -1,5 +1,5 @@
 import * as alepha1 from "alepha";
-import { AsyncFn, Descriptor, KIND, Static } from "alepha";
+import { AsyncFn, KIND, Primitive, Static } from "alepha";
 import * as alepha_topic0 from "alepha/topic";
 import { TopicProvider } from "alepha/topic";
 import { DateTime, DateTimeProvider, DurationLike, Timeout } from "alepha/datetime";
@@ -28,9 +28,9 @@ declare abstract class LockProvider {
   abstract del(...keys: string[]): Promise<void>;
 }
 //#endregion
-//#region src/lock/descriptors/$lock.d.ts
+//#region src/lock/primitives/$lock.d.ts
 /**
- * Creates a distributed lock descriptor for ensuring single-instance execution across processes.
+ * Creates a distributed lock primitive for ensuring single-instance execution across processes.
  *
  * Prevents multiple instances of the same operation from running simultaneously, essential for
  * maintaining data consistency and preventing race conditions in distributed applications.
@@ -79,10 +79,10 @@ declare abstract class LockProvider {
  * ```
  */
 declare const $lock: {
-  <TFunc extends AsyncFn>(options: LockDescriptorOptions<TFunc>): LockDescriptor<TFunc>;
-  [KIND]: typeof LockDescriptor;
+  <TFunc extends AsyncFn>(options: LockPrimitiveOptions<TFunc>): LockPrimitive<TFunc>;
+  [KIND]: typeof LockPrimitive;
 };
-interface LockDescriptorOptions<TFunc extends AsyncFn> {
+interface LockPrimitiveOptions<TFunc extends AsyncFn> {
   /**
    * The function to execute when the lock is successfully acquired.
    *
@@ -291,7 +291,7 @@ declare const envSchema: alepha1.TObject<{
 declare module "alepha" {
   interface Env extends Partial<Static<typeof envSchema>> {}
 }
-declare class LockDescriptor<TFunc extends AsyncFn> extends Descriptor<LockDescriptorOptions<TFunc>> {
+declare class LockPrimitive<TFunc extends AsyncFn> extends Primitive<LockPrimitiveOptions<TFunc>> {
   protected readonly log: alepha_logger0.Logger;
   protected readonly provider: LockProvider;
   protected readonly env: {
@@ -300,7 +300,7 @@ declare class LockDescriptor<TFunc extends AsyncFn> extends Descriptor<LockDescr
   protected readonly dateTimeProvider: DateTimeProvider;
   protected readonly id: `${string}-${string}-${string}-${string}-${string}`;
   readonly maxDuration: dayjs_plugin_duration_js0.Duration;
-  protected readonly topicLockEnd: alepha_topic0.TopicDescriptor<{
+  protected readonly topicLockEnd: alepha_topic0.TopicPrimitive<{
     payload: alepha1.TObject<{
       name: alepha1.TString;
     }>;
@@ -357,5 +357,5 @@ declare class MemoryLockProvider implements LockProvider {
  */
 declare const AlephaLock: alepha1.Service<alepha1.Module>;
 //#endregion
-export { $lock, AlephaLock, LockDescriptor, LockDescriptorOptions, LockProvider, LockResult, LockTopicProvider, MemoryLockProvider };
+export { $lock, AlephaLock, LockPrimitive, LockPrimitiveOptions, LockProvider, LockResult, LockTopicProvider, MemoryLockProvider };
 //# sourceMappingURL=index.d.ts.map

package/dist/lock/index.js

@@ -1,4 +1,4 @@
-import { $env, $inject, $module, Descriptor, KIND, createDescriptor, t } from "alepha";
+import { $env, $inject, $module, KIND, Primitive, createPrimitive, t } from "alepha";
 import { $topic, MemoryTopicProvider, TopicProvider, TopicTimeoutError } from "alepha/topic";
 import { DateTimeProvider } from "alepha/datetime";
 import { $logger } from "alepha/logger";
@@ -14,9 +14,9 @@ var LockProvider = class {};
 var LockTopicProvider = class extends TopicProvider {};
 
 //#endregion
-//#region src/lock/descriptors/$lock.ts
+//#region src/lock/primitives/$lock.ts
 /**
-* Creates a distributed lock descriptor for ensuring single-instance execution across processes.
+* Creates a distributed lock primitive for ensuring single-instance execution across processes.
 *
 * Prevents multiple instances of the same operation from running simultaneously, essential for
 * maintaining data consistency and preventing race conditions in distributed applications.
@@ -65,10 +65,10 @@ var LockTopicProvider = class extends TopicProvider {};
 * ```
 */
 const $lock = (options) => {
-	return createDescriptor(LockDescriptor, options);
+	return createPrimitive(LockPrimitive, options);
 };
 const envSchema = t.object({ LOCK_PREFIX_KEY: t.text({ default: "lock" }) });
-var LockDescriptor = class extends Descriptor {
+var LockPrimitive = class extends Primitive {
 	log = $logger();
 	provider = $inject(LockProvider);
 	env = $env(envSchema);
@@ -141,7 +141,7 @@ var LockDescriptor = class extends Descriptor {
 		};
 	}
 };
-$lock[KIND] = LockDescriptor;
+$lock[KIND] = LockPrimitive;
 
 //#endregion
 //#region src/lock/providers/MemoryLockProvider.ts
@@ -199,7 +199,7 @@ var MemoryLockProvider = class {
 */
 const AlephaLock = $module({
 	name: "alepha.lock",
-	descriptors: [$lock],
+	primitives: [$lock],
 	services: [
 		LockProvider,
 		MemoryLockProvider,
@@ -217,5 +217,5 @@ const AlephaLock = $module({
 });
 
 //#endregion
-export { $lock, AlephaLock, LockDescriptor, LockProvider, LockTopicProvider, MemoryLockProvider };
+export { $lock, AlephaLock, LockPrimitive, LockProvider, LockTopicProvider, MemoryLockProvider };
 //# sourceMappingURL=index.js.map

package/dist/lock/index.js.map

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

package/dist/lock-redis/index.js

@@ -1,72 +1,9 @@
-import { $env, $hook, $inject, $module, Alepha, t } from "alepha";
+import { $inject, $module } from "alepha";
 import { AlephaLock, LockProvider, LockTopicProvider } from "alepha/lock";
-import { AlephaTopic, TopicProvider } from "alepha/topic";
+import { RedisTopicProvider } from "alepha/topic/redis";
 import { $logger } from "alepha/logger";
-import { RedisProvider, RedisSubscriberProvider } from "alepha/redis";
+import { RedisProvider } from "alepha/redis";
 
-//#region src/topic-redis/providers/RedisTopicProvider.ts
-const envSchema = t.object({ REDIS_TOPIC_PREFIX: t.text({ default: "topic" }) });
-var RedisTopicProvider = class extends TopicProvider {
-	env = $env(envSchema);
-	alepha = $inject(Alepha);
-	redisProvider = $inject(RedisProvider);
-	redisSubscriberProvider = $inject(RedisSubscriberProvider);
-	log = $logger();
-	start = $hook({
-		on: "start",
-		handler: async () => {
-			const subscribers = this.subscribers();
-			if (subscribers.length) {
-				await Promise.all(subscribers.map((fn) => fn()));
-				for (const subscriber of subscribers) this.log.debug(`Subscribed to topic '${subscriber.name}'`);
-			}
-		}
-	});
-	prefix(queue) {
-		return `${this.env.REDIS_TOPIC_PREFIX}:${queue}`;
-	}
-	/**
-	* Publish a message to a topic.
-	*/
-	async publish(topic, message) {
-		await this.redisProvider.publisher.publish(this.prefix(topic), message);
-	}
-	/**
-	* Subscribe to a topic.
-	*/
-	async subscribe(name, callback) {
-		const topic = this.prefix(name);
-		await this.redisSubscriberProvider.subscriber.subscribe(topic, callback);
-		return () => this.unsubscribe(name, callback);
-	}
-	/**
-	* Unsubscribe from a topic.
-	*/
-	async unsubscribe(name, callback) {
-		const topic = this.prefix(name);
-		await this.redisSubscriberProvider.subscriber.unsubscribe(topic, callback);
-	}
-};
-
-//#endregion
-//#region src/topic-redis/index.ts
-/**
-* Plugin for Alepha Topic that provides Redis pub/sub capabilities.
-*
-* @see {@link RedisTopicProvider}
-* @module alepha.topic.redis
-*/
-const AlephaTopicRedis = $module({
-	name: "alepha.topic.redis",
-	services: [RedisTopicProvider],
-	register: (alepha) => alepha.with({
-		optional: true,
-		provide: TopicProvider,
-		use: RedisTopicProvider
-	}).with(AlephaTopic)
-});
-
-//#endregion
 //#region src/lock-redis/providers/RedisLockProvider.ts
 var RedisLockProvider = class {
 	log = $logger();

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["options: RedisSetOptions"],"sources":["../../src/topic-redis/providers/RedisTopicProvider.ts","../../src/topic-redis/index.ts","../../src/lock-redis/providers/RedisLockProvider.ts","../../src/lock-redis/index.ts"],"sourcesContent":["import { $env, $hook, $inject, Alepha, t } from \"alepha\";\nimport { $logger } from \"alepha/logger\";\nimport { RedisProvider, RedisSubscriberProvider } from \"alepha/redis\";\nimport {\n  type SubscribeCallback,\n  TopicProvider,\n  type UnSubscribeFn,\n} from \"alepha/topic\";\n\nconst envSchema = t.object({\n  REDIS_TOPIC_PREFIX: t.text({\n    default: \"topic\",\n  }),\n});\n\nexport class RedisTopicProvider extends TopicProvider {\n  protected readonly env = $env(envSchema);\n  protected readonly alepha = $inject(Alepha);\n  protected readonly redisProvider = $inject(RedisProvider);\n  protected readonly redisSubscriberProvider = $inject(RedisSubscriberProvider);\n\n  protected readonly log = $logger();\n\n  protected readonly start = $hook({\n    on: \"start\",\n    handler: async () => {\n      const subscribers = this.subscribers();\n      if (subscribers.length) {\n        await Promise.all(subscribers.map((fn) => fn()));\n        for (const subscriber of subscribers) {\n          this.log.debug(`Subscribed to topic '${subscriber.name}'`);\n        }\n      }\n    },\n  });\n\n  public prefix(queue: string): string {\n    return `${this.env.REDIS_TOPIC_PREFIX}:${queue}`;\n  }\n\n  /**\n   * Publish a message to a topic.\n   */\n  public async publish(topic: string, message: string): Promise<void> {\n    await this.redisProvider.publisher.publish(this.prefix(topic), message);\n  }\n\n  /**\n   * Subscribe to a topic.\n   */\n  public async subscribe(\n    name: string,\n    callback: SubscribeCallback,\n  ): Promise<UnSubscribeFn> {\n    const topic = this.prefix(name);\n    await this.redisSubscriberProvider.subscriber.subscribe(topic, callback);\n\n    return () => this.unsubscribe(name, callback);\n  }\n\n  /**\n   * Unsubscribe from a topic.\n   */\n  public async unsubscribe(\n    name: string,\n    callback?: SubscribeCallback,\n  ): Promise<void> {\n    const topic = this.prefix(name);\n\n    await this.redisSubscriberProvider.subscriber.unsubscribe(topic, callback);\n  }\n}\n","import { $module, type Alepha } from \"alepha\";\nimport { AlephaTopic, TopicProvider } from \"alepha/topic\";\nimport { RedisTopicProvider } from \"./providers/RedisTopicProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport * from \"./providers/RedisTopicProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\n/**\n * Plugin for Alepha Topic that provides Redis pub/sub capabilities.\n *\n * @see {@link RedisTopicProvider}\n * @module alepha.topic.redis\n */\nexport const AlephaTopicRedis = $module({\n  name: \"alepha.topic.redis\",\n  services: [RedisTopicProvider],\n  register: (alepha: Alepha): Alepha =>\n    alepha\n      .with({\n        optional: true,\n        provide: TopicProvider,\n        use: RedisTopicProvider,\n      })\n      .with(AlephaTopic),\n});\n","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":";;;;;;;AASA,MAAM,YAAY,EAAE,OAAO,EACzB,oBAAoB,EAAE,KAAK,EACzB,SAAS,SACV,CAAC,EACH,CAAC;AAEF,IAAa,qBAAb,cAAwC,cAAc;CACpD,AAAmB,MAAM,KAAK,UAAU;CACxC,AAAmB,SAAS,QAAQ,OAAO;CAC3C,AAAmB,gBAAgB,QAAQ,cAAc;CACzD,AAAmB,0BAA0B,QAAQ,wBAAwB;CAE7E,AAAmB,MAAM,SAAS;CAElC,AAAmB,QAAQ,MAAM;EAC/B,IAAI;EACJ,SAAS,YAAY;GACnB,MAAM,cAAc,KAAK,aAAa;AACtC,OAAI,YAAY,QAAQ;AACtB,UAAM,QAAQ,IAAI,YAAY,KAAK,OAAO,IAAI,CAAC,CAAC;AAChD,SAAK,MAAM,cAAc,YACvB,MAAK,IAAI,MAAM,wBAAwB,WAAW,KAAK,GAAG;;;EAIjE,CAAC;CAEF,AAAO,OAAO,OAAuB;AACnC,SAAO,GAAG,KAAK,IAAI,mBAAmB,GAAG;;;;;CAM3C,MAAa,QAAQ,OAAe,SAAgC;AAClE,QAAM,KAAK,cAAc,UAAU,QAAQ,KAAK,OAAO,MAAM,EAAE,QAAQ;;;;;CAMzE,MAAa,UACX,MACA,UACwB;EACxB,MAAM,QAAQ,KAAK,OAAO,KAAK;AAC/B,QAAM,KAAK,wBAAwB,WAAW,UAAU,OAAO,SAAS;AAExE,eAAa,KAAK,YAAY,MAAM,SAAS;;;;;CAM/C,MAAa,YACX,MACA,UACe;EACf,MAAM,QAAQ,KAAK,OAAO,KAAK;AAE/B,QAAM,KAAK,wBAAwB,WAAW,YAAY,OAAO,SAAS;;;;;;;;;;;;ACrD9E,MAAa,mBAAmB,QAAQ;CACtC,MAAM;CACN,UAAU,CAAC,mBAAmB;CAC9B,WAAW,WACT,OACG,KAAK;EACJ,UAAU;EACV,SAAS;EACT,KAAK;EACN,CAAC,CACD,KAAK,YAAY;CACvB,CAAC;;;;ACtBF,IAAa,oBAAb,MAAuD;CACrD,AAAmB,MAAM,SAAS;CAClC,AAAmB,gBAAgB,QAAQ,cAAc;CAEzD,MAAa,IACX,KACA,OACA,IACA,IACiB;EACjB,MAAMA,UAA2B,EAC/B,KAAK,MACN;AAED,MAAI,GACF,SAAQ,aAAa;GACnB,MAAM;GACN,OAAO;GACR;AAGH,MAAI,GACF,SAAQ,YAAY;AAKtB,UAFa,MAAM,KAAK,cAAc,IAAI,KAAK,OAAO,QAAQ,EAElD,SAAS,QAAQ;;CAG/B,MAAa,IAAI,GAAG,MAA+B;AACjD,QAAM,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":["options: RedisSetOptions"],"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,AAAmB,MAAM,SAAS;CAClC,AAAmB,gBAAgB,QAAQ,cAAc;CAEzD,MAAa,IACX,KACA,OACA,IACA,IACiB;EACjB,MAAMA,UAA2B,EAC/B,KAAK,MACN;AAED,MAAI,GACF,SAAQ,aAAa;GACnB,MAAM;GACN,OAAO;GACR;AAGH,MAAI,GACF,SAAQ,YAAY;AAKtB,UAFa,MAAM,KAAK,cAAc,IAAI,KAAK,OAAO,QAAQ,EAElD,SAAS,QAAQ;;CAG/B,MAAa,IAAI,GAAG,MAA+B;AACjD,QAAM,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"}