alepha 0.15.0 → 0.15.2

package/dist/file/index.d.ts

@@ -1,839 +0,0 @@
-import * as alepha0 from "alepha";
-import { FileLike, StreamLike } from "alepha";
-import { Readable } from "node:stream";
-
-//#region ../../src/file/errors/FileError.d.ts
-declare class FileError extends Error {
-  constructor(message: string, cause?: Error);
-}
-//#endregion
-//#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 {
-  /**
-       * Joins multiple path segments into a single path.
-       *
-       * @param paths - The path segments to join
-       * @returns The joined path
-       */
-  abstract join(...paths: string[]): string;
-  /**
-       * 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/providers/MemoryFileSystemProvider.d.ts
-interface MemoryFileSystemProviderOptions {
-  /**
-       * Error to throw on mkdir operations (for testing error handling)
-       */
-  mkdirError?: Error | null;
-  /**
-       * Error to throw on writeFile operations (for testing error handling)
-       */
-  writeFileError?: Error | null;
-  /**
-       * Error to throw on readFile operations (for testing error handling)
-       */
-  readFileError?: Error | null;
-}
-/**
- * In-memory implementation of FileSystemProvider for testing.
- *
- * This provider stores all files and directories in memory, making it ideal for
- * unit tests that need to verify file operations without touching the real file system.
- *
- * @example
- * ```typescript
- * // In tests, substitute the real FileSystemProvider with MemoryFileSystemProvider
- * const alepha = Alepha.create().with({
- *   provide: FileSystemProvider,
- *   use: MemoryFileSystemProvider,
- * });
- *
- * // Run code that uses FileSystemProvider
- * const service = alepha.inject(MyService);
- * await service.saveFile("test.txt", "Hello World");
- *
- * // Verify the file was written
- * const memoryFs = alepha.inject(MemoryFileSystemProvider);
- * expect(memoryFs.files.get("test.txt")?.toString()).toBe("Hello World");
- * ```
- */
-declare class MemoryFileSystemProvider implements FileSystemProvider {
-  /**
-       * In-memory storage for files (path -> content)
-       */
-  files: Map<string, Buffer<ArrayBufferLike>>;
-  /**
-       * In-memory storage for directories
-       */
-  directories: Set<string>;
-  /**
-       * Track mkdir calls for test assertions
-       */
-  mkdirCalls: Array<{
-    path: string;
-    options?: MkdirOptions;
-  }>;
-  /**
-       * Track writeFile calls for test assertions
-       */
-  writeFileCalls: Array<{
-    path: string;
-    data: string;
-  }>;
-  /**
-       * Track join calls for test assertions
-       */
-  joinCalls: Array<string[]>;
-  /**
-       * Error to throw on mkdir (for testing error handling)
-       */
-  mkdirError: Error | null;
-  /**
-       * Error to throw on writeFile (for testing error handling)
-       */
-  writeFileError: Error | null;
-  /**
-       * Error to throw on readFile (for testing error handling)
-       */
-  readFileError: Error | null;
-  constructor(options?: MemoryFileSystemProviderOptions);
-  /**
-       * Join path segments using forward slashes.
-       */
-  join(...paths: string[]): string;
-  /**
-       * Create a FileLike object from various sources.
-       */
-  createFile(options: CreateFileOptions): FileLike;
-  /**
-       * Remove a file or directory from memory.
-       */
-  rm(path: string, options?: RmOptions): Promise<void>;
-  /**
-       * Copy a file or directory in memory.
-       */
-  cp(src: string, dest: string, options?: CpOptions): Promise<void>;
-  /**
-       * Move/rename a file or directory in memory.
-       */
-  mv(src: string, dest: string): Promise<void>;
-  /**
-       * Create a directory in memory.
-       */
-  mkdir(path: string, options?: MkdirOptions): Promise<void>;
-  /**
-       * List files in a directory.
-       */
-  ls(path: string, options?: LsOptions): Promise<string[]>;
-  /**
-       * Check if a file or directory exists in memory.
-       */
-  exists(path: string): Promise<boolean>;
-  /**
-       * Read a file from memory.
-       */
-  readFile(path: string): Promise<Buffer>;
-  /**
-       * Write a file to memory.
-       */
-  writeFile(path: string, data: Uint8Array | Buffer | string | FileLike): Promise<void>;
-  /**
-       * Reset all in-memory state (useful between tests).
-       */
-  reset(): void;
-  /**
-       * Get the content of a file as a string (convenience method for testing).
-       */
-  getFileContent(path: string): string | undefined;
-}
-//#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;
-  join(...paths: string[]): string;
-  /**
-       * 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, FileError, FileSystemProvider, FileTypeResult, LsOptions, MemoryFileSystemProvider, MemoryFileSystemProviderOptions, MkdirOptions, NodeFileSystemProvider, RmOptions };
-//# sourceMappingURL=index.d.ts.map