alepha 0.13.0 → 0.13.1

package/dist/file/index.d.cts

@@ -1,698 +0,0 @@
-import * as alepha0 from "alepha";
-import { FileLike, StreamLike } from "alepha";
-import { Readable } from "node:stream";
-
-//#region src/file/providers/FileSystemProvider.d.ts
-/**
- * Options for creating a file from a URL
- */
-interface CreateFileFromUrlOptions {
-  /**
-   * The URL to load the file from (file://, http://, or https://)
-   */
-  url: string;
-  /**
-   * The MIME type of the file (optional, will be detected from filename if not provided)
-   */
-  type?: string;
-  /**
-   * The name of the file (optional, will be extracted from URL if not provided)
-   */
-  name?: string;
-}
-/**
- * Options for creating a file from a path (URL with file:// scheme)
- */
-interface CreateFileFromPathOptions {
-  /**
-   * The path to the file on the local filesystem
-   */
-  path: string;
-  /**
-   * The MIME type of the file (optional, will be detected from filename if not provided)
-   */
-  type?: string;
-  /**
-   * The name of the file (optional, will be extracted from URL if not provided)
-   */
-  name?: string;
-}
-/**
- * Options for creating a file from a Buffer
- */
-interface CreateFileFromBufferOptions {
-  /**
-   * The Buffer containing the file data
-   */
-  buffer: Buffer;
-  /**
-   * The MIME type of the file (optional, will be detected from name if not provided)
-   */
-  type?: string;
-  /**
-   * The name of the file (required for proper content type detection)
-   */
-  name?: string;
-}
-/**
- * Options for creating a file from a stream
- */
-interface CreateFileFromStreamOptions {
-  /**
-   * The readable stream containing the file data
-   */
-  stream: StreamLike;
-  /**
-   * The MIME type of the file (optional, will be detected from name if not provided)
-   */
-  type?: string;
-  /**
-   * The name of the file (required for proper content type detection)
-   */
-  name?: string;
-  /**
-   * The size of the file in bytes (optional)
-   */
-  size?: number;
-}
-/**
- * Options for creating a file from text content
- */
-interface CreateFileFromTextOptions {
-  /**
-   * The text content to create the file from
-   */
-  text: string;
-  /**
-   * The MIME type of the file (default: text/plain)
-   */
-  type?: string;
-  /**
-   * The name of the file (default: "file.txt")
-   */
-  name?: string;
-}
-interface CreateFileFromResponseOptions {
-  /**
-   * The Response object containing the file data
-   */
-  response: Response;
-  /**
-   * Override the name (optional, uses filename from Content-Disposition header if not provided)
-   */
-  name?: string;
-  /**
-   * Override the MIME type (optional, uses file.type if not provided)
-   */
-  type?: string;
-}
-/**
- * Options for creating a file from a Web File object
- */
-interface CreateFileFromWebFileOptions {
-  /**
-   * The Web File object
-   */
-  file: File;
-  /**
-   * Override the MIME type (optional, uses file.type if not provided)
-   */
-  type?: string;
-  /**
-   * Override the name (optional, uses file.name if not provided)
-   */
-  name?: string;
-  /**
-   * Override the size (optional, uses file.size if not provided)
-   */
-  size?: number;
-}
-/**
- * Options for creating a file from an ArrayBuffer
- */
-interface CreateFileFromArrayBufferOptions {
-  /**
-   * The ArrayBuffer containing the file data
-   */
-  arrayBuffer: ArrayBuffer;
-  /**
-   * The MIME type of the file (optional, will be detected from name if not provided)
-   */
-  type?: string;
-  /**
-   * The name of the file (required for proper content type detection)
-   */
-  name?: string;
-}
-/**
- * Union type for all createFile options
- */
-type CreateFileOptions = CreateFileFromUrlOptions | CreateFileFromPathOptions | CreateFileFromBufferOptions | CreateFileFromStreamOptions | CreateFileFromTextOptions | CreateFileFromWebFileOptions | CreateFileFromResponseOptions | CreateFileFromArrayBufferOptions;
-/**
- * Options for rm (remove) operation
- */
-interface RmOptions {
-  /**
-   * If true, removes directories and their contents recursively
-   */
-  recursive?: boolean;
-  /**
-   * If true, no error will be thrown if the path does not exist
-   */
-  force?: boolean;
-}
-/**
- * Options for cp (copy) operation
- */
-interface CpOptions {
-  /**
-   * If true, copy directories recursively
-   */
-  recursive?: boolean;
-  /**
-   * If true, overwrite existing destination
-   */
-  force?: boolean;
-}
-/**
- * Options for mkdir operation
- */
-interface MkdirOptions {
-  /**
-   * If true, creates parent directories as needed
-   */
-  recursive?: boolean;
-  /**
-   * File mode (permission and sticky bits)
-   */
-  mode?: number;
-}
-/**
- * Options for ls (list) operation
- */
-interface LsOptions {
-  /**
-   * If true, list contents of directories recursively
-   */
-  recursive?: boolean;
-  /**
-   * If true, include hidden files (starting with .)
-   */
-  hidden?: boolean;
-}
-/**
- * FileSystem interface providing utilities for working with files.
- */
-declare abstract class FileSystemProvider {
-  /**
-   * Creates a FileLike object from various sources.
-   *
-   * @param options - Options for creating the file
-   * @returns A FileLike object
-   */
-  abstract createFile(options: CreateFileOptions): FileLike;
-  /**
-   * Removes a file or directory.
-   *
-   * @param path - The path to remove
-   * @param options - Remove options
-   */
-  abstract rm(path: string, options?: RmOptions): Promise<void>;
-  /**
-   * Copies a file or directory.
-   *
-   * @param src - Source path
-   * @param dest - Destination path
-   * @param options - Copy options
-   */
-  abstract cp(src: string, dest: string, options?: CpOptions): Promise<void>;
-  /**
-   * Moves/renames a file or directory.
-   *
-   * @param src - Source path
-   * @param dest - Destination path
-   */
-  abstract mv(src: string, dest: string): Promise<void>;
-  /**
-   * Creates a directory.
-   *
-   * @param path - The directory path to create
-   * @param options - Mkdir options
-   */
-  abstract mkdir(path: string, options?: MkdirOptions): Promise<void>;
-  /**
-   * Lists files in a directory.
-   *
-   * @param path - The directory path to list
-   * @param options - List options
-   * @returns Array of filenames
-   */
-  abstract ls(path: string, options?: LsOptions): Promise<string[]>;
-  /**
-   * Checks if a file or directory exists.
-   *
-   * @param path - The path to check
-   * @returns True if the path exists, false otherwise
-   */
-  abstract exists(path: string): Promise<boolean>;
-  /**
-   * Reads the content of a file.
-   *
-   * @param path - The file path to read
-   * @returns The file content as a Buffer
-   */
-  abstract readFile(path: string): Promise<Buffer>;
-  /**
-   * Writes data to a file.
-   *
-   * @param path - The file path to write to
-   * @param data - The data to write (Buffer or string)
-   */
-  abstract writeFile(path: string, data: Uint8Array | Buffer | string | FileLike): Promise<void>;
-}
-//#endregion
-//#region src/file/services/FileDetector.d.ts
-interface FileTypeResult {
-  /**
-   * The detected MIME type
-   */
-  mimeType: string;
-  /**
-   * The detected file extension
-   */
-  extension: string;
-  /**
-   * Whether the file type was verified by magic bytes
-   */
-  verified: boolean;
-  /**
-   * The stream (potentially wrapped to allow re-reading)
-   */
-  stream: Readable;
-}
-/**
- * Service for detecting file types and getting content types.
- *
- * @example
- * ```typescript
- * const detector = alepha.inject(FileDetector);
- *
- * // Get content type from filename
- * const mimeType = detector.getContentType("image.png"); // "image/png"
- *
- * // Detect file type by magic bytes
- * const stream = createReadStream('image.png');
- * const result = await detector.detectFileType(stream, 'image.png');
- * console.log(result.mimeType); // 'image/png'
- * console.log(result.verified); // true if magic bytes match
- * ```
- */
-declare class FileDetector {
-  /**
-   * Magic byte signatures for common file formats.
-   * Each signature is represented as an array of bytes or null (wildcard).
-   */
-  protected static readonly MAGIC_BYTES: Record<string, {
-    signature: (number | null)[];
-    mimeType: string;
-  }[]>;
-  /**
-   * All possible format signatures for checking against actual file content
-   */
-  protected static readonly ALL_SIGNATURES: {
-    signature: (number | null)[];
-    mimeType: string;
-    ext: string;
-  }[];
-  /**
-   * MIME type map for file extensions.
-   *
-   * Can be used to get the content type of file based on its extension.
-   * Feel free to add more mime types in your project!
-   */
-  static readonly mimeMap: Record<string, string>;
-  /**
-   * Reverse MIME type map for looking up extensions from MIME types.
-   * Prefers shorter, more common extensions when multiple exist.
-   */
-  protected static readonly reverseMimeMap: Record<string, string>;
-  /**
-   * Returns the file extension for a given MIME type.
-   *
-   * @param mimeType - The MIME type to look up
-   * @returns The file extension (without dot), or "bin" if not found
-   *
-   * @example
-   * ```typescript
-   * const detector = alepha.inject(FileDetector);
-   * const ext = detector.getExtensionFromMimeType("image/png"); // "png"
-   * const ext2 = detector.getExtensionFromMimeType("application/octet-stream"); // "bin"
-   * ```
-   */
-  getExtensionFromMimeType(mimeType: string): string;
-  /**
-   * Returns the content type of file based on its filename.
-   *
-   * @param filename - The filename to check
-   * @returns The MIME type
-   *
-   * @example
-   * ```typescript
-   * const detector = alepha.inject(FileDetector);
-   * const mimeType = detector.getContentType("image.png"); // "image/png"
-   * ```
-   */
-  getContentType(filename: string): string;
-  /**
-   * Detects the file type by checking magic bytes against the stream content.
-   *
-   * @param stream - The readable stream to check
-   * @param filename - The filename (used to get the extension)
-   * @returns File type information including MIME type, extension, and verification status
-   *
-   * @example
-   * ```typescript
-   * const detector = alepha.inject(FileDetector);
-   * const stream = createReadStream('image.png');
-   * const result = await detector.detectFileType(stream, 'image.png');
-   * console.log(result.mimeType); // 'image/png'
-   * console.log(result.verified); // true if magic bytes match
-   * ```
-   */
-  detectFileType(stream: Readable, filename: string): Promise<FileTypeResult>;
-  /**
-   * Reads all bytes from a stream and returns the first N bytes along with a new stream containing all data.
-   * This approach reads the entire stream upfront to avoid complex async handling issues.
-   *
-   * @protected
-   */
-  protected peekBytes(stream: Readable, numBytes: number): Promise<{
-    buffer: Buffer;
-    stream: Readable;
-  }>;
-  /**
-   * Checks if a buffer matches a magic byte signature.
-   *
-   * @protected
-   */
-  protected matchesSignature(buffer: Buffer, signature: (number | null)[]): boolean;
-}
-//#endregion
-//#region src/file/providers/NodeFileSystemProvider.d.ts
-/**
- * Node.js implementation of FileSystem interface.
- *
- * @example
- * ```typescript
- * const fs = alepha.inject(NodeFileSystemProvider);
- *
- * // Create from URL
- * const file1 = fs.createFile({ url: "file:///path/to/file.png" });
- *
- * // Create from Buffer
- * const file2 = fs.createFile({ buffer: Buffer.from("hello"), name: "hello.txt" });
- *
- * // Create from text
- * const file3 = fs.createFile({ text: "Hello, world!", name: "greeting.txt" });
- *
- * // File operations
- * await fs.mkdir("/tmp/mydir", { recursive: true });
- * await fs.cp("/src/file.txt", "/dest/file.txt");
- * await fs.mv("/old/path.txt", "/new/path.txt");
- * const files = await fs.ls("/tmp");
- * await fs.rm("/tmp/file.txt");
- * ```
- */
-declare class NodeFileSystemProvider implements FileSystemProvider {
-  protected detector: FileDetector;
-  /**
-   * Creates a FileLike object from various sources.
-   *
-   * @param options - Options for creating the file
-   * @returns A FileLike object
-   *
-   * @example
-   * ```typescript
-   * const fs = alepha.inject(NodeFileSystemProvider);
-   *
-   * // From URL
-   * const file1 = fs.createFile({ url: "https://example.com/image.png" });
-   *
-   * // From Buffer
-   * const file2 = fs.createFile({
-   *   buffer: Buffer.from("hello"),
-   *   name: "hello.txt",
-   *   type: "text/plain"
-   * });
-   *
-   * // From text
-   * const file3 = fs.createFile({ text: "Hello!", name: "greeting.txt" });
-   *
-   * // From stream with detection
-   * const stream = createReadStream("/path/to/file.png");
-   * const file4 = fs.createFile({ stream, name: "image.png" });
-   * ```
-   */
-  createFile(options: CreateFileOptions): FileLike;
-  /**
-   * Removes a file or directory.
-   *
-   * @param path - The path to remove
-   * @param options - Remove options
-   *
-   * @example
-   * ```typescript
-   * const fs = alepha.inject(NodeFileSystemProvider);
-   *
-   * // Remove a file
-   * await fs.rm("/tmp/file.txt");
-   *
-   * // Remove a directory recursively
-   * await fs.rm("/tmp/mydir", { recursive: true });
-   *
-   * // Remove with force (no error if doesn't exist)
-   * await fs.rm("/tmp/maybe-exists.txt", { force: true });
-   * ```
-   */
-  rm(path: string, options?: RmOptions): Promise<void>;
-  /**
-   * Copies a file or directory.
-   *
-   * @param src - Source path
-   * @param dest - Destination path
-   * @param options - Copy options
-   *
-   * @example
-   * ```typescript
-   * const fs = alepha.inject(NodeFileSystemProvider);
-   *
-   * // Copy a file
-   * await fs.cp("/src/file.txt", "/dest/file.txt");
-   *
-   * // Copy a directory recursively
-   * await fs.cp("/src/dir", "/dest/dir", { recursive: true });
-   *
-   * // Copy with force (overwrite existing)
-   * await fs.cp("/src/file.txt", "/dest/file.txt", { force: true });
-   * ```
-   */
-  cp(src: string, dest: string, options?: CpOptions): Promise<void>;
-  /**
-   * Moves/renames a file or directory.
-   *
-   * @param src - Source path
-   * @param dest - Destination path
-   *
-   * @example
-   * ```typescript
-   * const fs = alepha.inject(NodeFileSystemProvider);
-   *
-   * // Move/rename a file
-   * await fs.mv("/old/path.txt", "/new/path.txt");
-   *
-   * // Move a directory
-   * await fs.mv("/old/dir", "/new/dir");
-   * ```
-   */
-  mv(src: string, dest: string): Promise<void>;
-  /**
-   * Creates a directory.
-   *
-   * @param path - The directory path to create
-   * @param options - Mkdir options
-   *
-   * @example
-   * ```typescript
-   * const fs = alepha.inject(NodeFileSystemProvider);
-   *
-   * // Create a directory
-   * await fs.mkdir("/tmp/mydir");
-   *
-   * // Create nested directories
-   * await fs.mkdir("/tmp/path/to/dir", { recursive: true });
-   *
-   * // Create with specific permissions
-   * await fs.mkdir("/tmp/mydir", { mode: 0o755 });
-   * ```
-   */
-  mkdir(path: string, options?: MkdirOptions): Promise<void>;
-  /**
-   * Lists files in a directory.
-   *
-   * @param path - The directory path to list
-   * @param options - List options
-   * @returns Array of filenames
-   *
-   * @example
-   * ```typescript
-   * const fs = alepha.inject(NodeFileSystemProvider);
-   *
-   * // List files in a directory
-   * const files = await fs.ls("/tmp");
-   * console.log(files); // ["file1.txt", "file2.txt", "subdir"]
-   *
-   * // List with hidden files
-   * const allFiles = await fs.ls("/tmp", { hidden: true });
-   *
-   * // List recursively
-   * const allFilesRecursive = await fs.ls("/tmp", { recursive: true });
-   * ```
-   */
-  ls(path: string, options?: LsOptions): Promise<string[]>;
-  /**
-   * Checks if a file or directory exists.
-   *
-   * @param path - The path to check
-   * @returns True if the path exists, false otherwise
-   *
-   * @example
-   * ```typescript
-   * const fs = alepha.inject(NodeFileSystemProvider);
-   *
-   * if (await fs.exists("/tmp/file.txt")) {
-   *   console.log("File exists");
-   * }
-   * ```
-   */
-  exists(path: string): Promise<boolean>;
-  /**
-   * Reads the content of a file.
-   *
-   * @param path - The file path to read
-   * @returns The file content as a Buffer
-   *
-   * @example
-   * ```typescript
-   * const fs = alepha.inject(NodeFileSystemProvider);
-   *
-   * const buffer = await fs.readFile("/tmp/file.txt");
-   * console.log(buffer.toString("utf-8"));
-   * ```
-   */
-  readFile(path: string): Promise<Buffer>;
-  /**
-   * Writes data to a file.
-   *
-   * @param path - The file path to write to
-   * @param data - The data to write (Buffer or string)
-   *
-   * @example
-   * ```typescript
-   * const fs = alepha.inject(NodeFileSystemProvider);
-   *
-   * // Write string
-   * await fs.writeFile("/tmp/file.txt", "Hello, world!");
-   *
-   * // Write Buffer
-   * await fs.writeFile("/tmp/file.bin", Buffer.from([0x01, 0x02, 0x03]));
-   * ```
-   */
-  writeFile(path: string, data: Uint8Array | Buffer | string | FileLike): Promise<void>;
-  /**
-   * Creates a FileLike object from a Web File.
-   *
-   * @protected
-   */
-  protected createFileFromWebFile(source: File, options?: {
-    type?: string;
-    name?: string;
-    size?: number;
-  }): FileLike;
-  /**
-   * Creates a FileLike object from a Buffer.
-   *
-   * @protected
-   */
-  protected createFileFromBuffer(source: Buffer, options?: {
-    type?: string;
-    name?: string;
-  }): FileLike;
-  /**
-   * Creates a FileLike object from a stream.
-   *
-   * @protected
-   */
-  protected createFileFromStream(source: StreamLike, options?: {
-    type?: string;
-    name?: string;
-    size?: number;
-  }): FileLike & {
-    _buffer: null | Buffer;
-  };
-  /**
-   * Creates a FileLike object from a URL.
-   *
-   * @protected
-   */
-  protected createFileFromUrl(url: string, options?: {
-    type?: string;
-    name?: string;
-  }): FileLike;
-  /**
-   * Gets a streaming response from a URL.
-   *
-   * @protected
-   */
-  protected getStreamingResponse(url: string): Readable;
-  /**
-   * Loads data from a URL.
-   *
-   * @protected
-   */
-  protected loadFromUrl(url: string): Promise<Buffer>;
-  /**
-   * Creates a stream from a URL.
-   *
-   * @protected
-   */
-  protected createStreamFromUrl(url: string): Readable;
-  /**
-   * Converts a stream-like object to a Buffer.
-   *
-   * @protected
-   */
-  protected streamToBuffer(streamLike: StreamLike): Promise<Buffer>;
-  /**
-   * Converts a Node.js Buffer to an ArrayBuffer.
-   *
-   * @protected
-   */
-  protected bufferToArrayBuffer(buffer: Buffer): ArrayBuffer;
-}
-//#endregion
-//#region src/file/index.d.ts
-/**
- * Provides file system capabilities for Alepha applications with support for multiple file sources and operations.
- *
- * The file module enables working with files from various sources (URLs, buffers, streams) and provides
- * utilities for file type detection, content type determination, and common file system operations.
- *
- * @see {@link FileDetector}
- * @see {@link FileSystemProvider}
- * @see {@link NodeFileSystemProvider}
- * @module alepha.file
- */
-declare const AlephaFile: alepha0.Service<alepha0.Module>;
-//#endregion
-export { AlephaFile, CpOptions, CreateFileFromArrayBufferOptions, CreateFileFromBufferOptions, CreateFileFromPathOptions, CreateFileFromResponseOptions, CreateFileFromStreamOptions, CreateFileFromTextOptions, CreateFileFromUrlOptions, CreateFileFromWebFileOptions, CreateFileOptions, FileDetector, FileSystemProvider, FileTypeResult, LsOptions, MkdirOptions, NodeFileSystemProvider, RmOptions };
-//# sourceMappingURL=index.d.cts.map