alepha/dist/system/index.d.ts

Easy-to-use modern TypeScript framework for building many kind of applications.

import { FileLike, Json, StreamLike } from "alepha";
import { Readable } from "node:stream";
//#region ../../src/system/errors/FileError.d.ts
declare class FileError extends Error {
  constructor(message: string, cause?: Error);
}
//#endregion
//#region ../../src/system/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 {
  /**
   * Copy directories recursively.
   *
   * @default true
   */
  recursive?: boolean;
  /**
   * If true, overwrite existing destination
   */
  force?: boolean;
}
/**
 * Options for mkdir operation
 */
interface MkdirOptions {
  /**
   * If true, creates parent directories as needed
   *
   * @default true
   */
  recursive?: boolean;
  /**
   * If true, does not throw an error if the directory already exists
   *
   * @default true
   */
  force?: 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>;
  /**
   * Reads the content of a file as a string.
   *
   * @param path - The file path to read
   * @returns The file content as a string
   */
  abstract readTextFile(path: string): Promise<string>;
  /**
   * Reads the content of a file as JSON.
   *
   * @param path - The file path to read
   * @returns The parsed JSON content
   */
  abstract readJsonFile<T = unknown>(path: string): Promise<T>;
}
//#endregion
//#region ../../src/system/providers/ShellProvider.d.ts
interface ShellRunOptions {
  /**
   * Working directory for the command.
   */
  root?: string;
  /**
   * Additional environment variables.
   */
  env?: Record<string, string>;
  /**
   * Resolve the executable from node_modules/.bin.
   * Supports local project, pnpm nested, and monorepo structures.
   * @default false
   */
  resolve?: boolean;
  /**
   * Capture stdout instead of inheriting stdio.
   * When true, returns stdout as string.
   * When false, streams output to terminal.
   * @default false
   */
  capture?: boolean;
}
/**
 * Abstract provider for executing shell commands and binaries.
 *
 * Implementations:
 * - `NodeShellProvider` - Real shell execution using Node.js child_process
 * - `MemoryShellProvider` - In-memory mock for testing
 *
 * @example
 * ```typescript
 * class MyService {
 *   protected readonly shell = $inject(ShellProvider);
 *
 *   async build() {
 *     // Run shell command directly
 *     await this.shell.run("yarn install");
 *
 *     // Run local binary with resolution
 *     await this.shell.run("vite build", { resolve: true });
 *
 *     // Capture output
 *     const output = await this.shell.run("echo hello", { capture: true });
 *   }
 * }
 * ```
 */
declare abstract class ShellProvider {
  /**
   * Run a shell command or binary.
   *
   * @param command - The command to run
   * @param options - Execution options
   * @returns stdout if capture is true, empty string otherwise
   */
  abstract run(command: string, options?: ShellRunOptions): Promise<string>;
  /**
   * Check if a command is installed and available in the system PATH.
   *
   * @param command - The command name to check
   * @returns true if the command is available
   */
  abstract isInstalled(command: string): Promise<boolean>;
}
//#endregion
//#region ../../src/system/providers/NodeShellProvider.d.ts
/**
 * Node.js implementation of ShellProvider.
 *
 * Executes shell commands using Node.js child_process module.
 * Supports binary resolution from node_modules/.bin for local packages.
 */
declare class NodeShellProvider implements ShellProvider {
  protected readonly log: import("alepha/logger").Logger;
  protected readonly fs: FileSystemProvider;
  /**
   * Run a shell command or binary.
   */
  run(command: string, options?: ShellRunOptions): Promise<string>;
  /**
   * Execute command with inherited stdio (streams to terminal).
   */
  protected execInherit(executable: string, args: string[], options: {
    cwd: string;
    env?: Record<string, string>;
  }): Promise<string>;
  /**
   * Build a shell command string with proper escaping for Windows.
   * Quotes both executable and arguments that contain spaces or special characters.
   */
  protected buildShellCommand(executable: string, args: string[]): string;
  /**
   * Execute command and capture stdout.
   */
  protected execCapture(command: string, options: {
    cwd: string;
    env?: Record<string, string>;
  }): Promise<string>;
  /**
   * Resolve executable path from node_modules/.bin.
   *
   * Search order:
   * 1. Local: node_modules/.bin/
   * 2. Pnpm nested: node_modules/alepha/node_modules/.bin/
   * 3. Monorepo: Walk up to 3 parent directories
   */
  protected resolveExecutable(name: string, root: string): Promise<string>;
  /**
   * Check if executable exists at path.
   */
  protected findExecutable(root: string, relativePath: string): Promise<string | undefined>;
  /**
   * Check if a command is installed and available in the system PATH.
   */
  isInstalled(command: string): Promise<boolean>;
  /**
   * Parse a command string into executable and arguments.
   *
   * Handles quoted arguments properly for paths with spaces.
   * Supports both single and double quotes.
   */
  protected parseCommand(command: string): string[];
}
//#endregion
//#region ../../src/system/providers/BunShellProvider.d.ts
/**
 * Bun implementation of ShellProvider.
 *
 * Executes shell commands using Bun's native `Bun.spawn` and `Bun.which`,
 * skipping the `node:child_process` compatibility layer for better performance.
 *
 * Inherits executable resolution (`node_modules/.bin` walk) and command parsing
 * from `NodeShellProvider`.
 */
declare class BunShellProvider extends NodeShellProvider {
  /**
   * Execute command with inherited stdio (streams to terminal).
   */
  protected execInherit(executable: string, args: string[], options: {
    cwd: string;
    env?: Record<string, string>;
  }): Promise<string>;
  /**
   * Execute command and capture stdout.
   */
  protected execCapture(command: string, options: {
    cwd: string;
    env?: Record<string, string>;
  }): Promise<string>;
  /**
   * Check if a command is installed and available in the system PATH.
   */
  isInstalled(command: string): Promise<boolean>;
}
//#endregion
//#region ../../src/system/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 {
  protected json: Json;
  /**
   * 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 readFile calls for test assertions
   */
  readFileCalls: Array<string>;
  /**
   * Track rm calls for test assertions
   */
  rmCalls: Array<{
    path: string;
    options?: RmOptions;
  }>;
  /**
   * 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.
   * Uses Node's path.join for proper normalization (handles .. and .)
   */
  join(...paths: string[]): string;
  /**
   * Normalize path separators to forward slashes for consistent internal storage.
   * This ensures Windows paths work correctly in the in-memory file system.
   */
  protected normalizePath(path: 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>;
  /**
   * Read a file from memory as text.
   */
  readTextFile(path: string): Promise<string>;
  /**
   * Read a file from memory as JSON.
   */
  readJsonFile<T = unknown>(path: string): Promise<T>;
  /**
   * 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;
  /**
   * Check if a file was written during the test.
   *
   * @example
   * ```typescript
   * expect(fs.wasWritten("/project/tsconfig.json")).toBe(true);
   * ```
   */
  wasWritten(path: string): boolean;
  /**
   * Check if a file was written with content matching a pattern.
   *
   * @example
   * ```typescript
   * expect(fs.wasWrittenMatching("/project/tsconfig.json", /extends/)).toBe(true);
   * ```
   */
  wasWrittenMatching(path: string, pattern: RegExp): boolean;
  /**
   * Check if a file was read during the test.
   *
   * @example
   * ```typescript
   * expect(fs.wasRead("/project/package.json")).toBe(true);
   * ```
   */
  wasRead(path: string): boolean;
  /**
   * Check if a file was deleted during the test.
   *
   * @example
   * ```typescript
   * expect(fs.wasDeleted("/project/old-file.txt")).toBe(true);
   * ```
   */
  wasDeleted(path: string): boolean;
  /**
   * Get the content of a file as a string (convenience method for testing).
   */
  getFileContent(path: string): string | undefined;
}
//#endregion
//#region ../../src/system/providers/MemoryShellProvider.d.ts
interface MemoryShellCall {
  command: string;
  options: ShellRunOptions;
}
interface MemoryShellProviderOptions {
  /**
   * Simulated outputs for specific commands.
   * Key is the command string, value is the stdout to return.
   */
  outputs?: Record<string, string>;
  /**
   * Commands that should throw an error.
   * Key is the command string, value is the error message.
   */
  errors?: Record<string, string>;
  /**
   * Commands that are considered "installed" in the system PATH.
   */
  installedCommands?: string[];
}
/**
 * In-memory implementation of ShellProvider for testing.
 *
 * Records all commands that would be executed without actually running them.
 * Can be configured to return specific outputs or throw errors for testing.
 *
 * @example
 * ```typescript
 * // In tests, substitute the real ShellProvider with MemoryShellProvider
 * const alepha = Alepha.create().with({
 *   provide: ShellProvider,
 *   use: MemoryShellProvider,
 * });
 *
 * // Configure mock behavior
 * const shell = alepha.inject(MemoryShellProvider);
 * shell.configure({
 *   outputs: { "echo hello": "hello\n" },
 *   errors: { "failing-cmd": "Command failed" },
 * });
 *
 * // Or use the fluent API
 * shell.outputs.set("another-cmd", "output");
 * shell.errors.set("another-error", "Error message");
 *
 * // Run code that uses ShellProvider
 * const service = alepha.inject(MyService);
 * await service.doSomething();
 *
 * // Verify commands were called
 * expect(shell.calls).toHaveLength(2);
 * expect(shell.calls[0].command).toBe("yarn install");
 * ```
 */
declare class MemoryShellProvider implements ShellProvider {
  /**
   * All recorded shell calls.
   */
  calls: MemoryShellCall[];
  /**
   * Simulated outputs for specific commands.
   */
  outputs: Map<string, string>;
  /**
   * Commands that should throw an error.
   */
  errors: Map<string, string>;
  /**
   * Commands considered installed in the system PATH.
   */
  installedCommands: Set<string>;
  /**
   * Configure the mock with predefined outputs, errors, and installed commands.
   */
  configure(options: MemoryShellProviderOptions): this;
  /**
   * Record command and return simulated output.
   */
  run(command: string, options?: ShellRunOptions): Promise<string>;
  /**
   * Check if a specific command was called.
   */
  wasCalled(command: string): boolean;
  /**
   * Check if a command matching a pattern was called.
   */
  wasCalledMatching(pattern: RegExp): boolean;
  /**
   * Get all calls matching a pattern.
   */
  getCallsMatching(pattern: RegExp): MemoryShellCall[];
  /**
   * Check if a command is installed.
   */
  isInstalled(command: string): Promise<boolean>;
  /**
   * Reset all recorded state.
   */
  reset(): void;
}
//#endregion
//#region ../../src/system/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/system/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;
  protected json: Json;
  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 (recursive by default)
   * await fs.cp("/src/dir", "/dest/dir");
   *
   * // 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>;
  /**
   * Reads the content of a file as a string.
   *
   * @param path - The file path to read
   * @returns The file content as a string
   *
   * @example
   * ```typescript
   * const fs = alepha.inject(NodeFileSystemProvider);
   * const content = await fs.readTextFile("/tmp/file.txt");
   * ```
   */
  readTextFile(path: string): Promise<string>;
  /**
   * Reads the content of a file as JSON.
   *
   * @param path - The file path to read
   * @returns The parsed JSON content
   *
   * @example
   * ```typescript
   * const fs = alepha.inject(NodeFileSystemProvider);
   * const config = await fs.readJsonFile<{ name: string }>("/tmp/config.json");
   * ```
   */
  readJsonFile<T = unknown>(path: string): Promise<T>;
  /**
   * 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/system/providers/WorkerdFileSystemProvider.d.ts
/**
 * Web-standard implementation of FileSystemProvider for Cloudflare Workers and other edge runtimes.
 *
 * Uses only Web APIs (ReadableStream, TextEncoder, etc.) — no Node.js-specific APIs.
 * Provides working `createFile` with proper streaming support.
 * Filesystem operations (rm, cp, mv, etc.) are not available in edge runtimes and will throw.
 *
 * @example
 * ```typescript
 * const fs = alepha.inject(WorkerdFileSystemProvider);
 *
 * // Create from text (returns FileLike with web ReadableStream)
 * const file = fs.createFile({ text: "Hello!", name: "greeting.txt" });
 * const stream = file.stream(); // ReadableStream (web standard)
 * ```
 */
declare class WorkerdFileSystemProvider implements FileSystemProvider {
  protected detector: FileDetector;
  protected json: Json;
  protected encoder: TextEncoder;
  protected decoder: TextDecoder;
  join(...paths: string[]): string;
  createFile(options: CreateFileOptions): FileLike;
  protected createFileFromText(text: string, options?: {
    type?: string;
    name?: string;
  }): FileLike;
  protected createFileFromArrayBuffer(source: ArrayBuffer, options?: {
    type?: string;
    name?: string;
  }): FileLike;
  protected createFileFromWebFile(source: File, options?: {
    type?: string;
    name?: string;
    size?: number;
  }): FileLike;
  protected createFileFromResponse(response: Response, options?: {
    type?: string;
    name?: string;
  }): FileLike;
  protected createFileFromStream(source: ReadableStream, options?: {
    type?: string;
    name?: string;
    size?: number;
  }): FileLike;
  protected createFileFromUrl(url: string, options?: {
    type?: string;
    name?: string;
  }): FileLike;
  rm(_path: string, _options?: RmOptions): Promise<void>;
  cp(_src: string, _dest: string, _options?: CpOptions): Promise<void>;
  mv(_src: string, _dest: string): Promise<void>;
  mkdir(_path: string, _options?: MkdirOptions): Promise<void>;
  ls(_path: string, _options?: LsOptions): Promise<string[]>;
  exists(_path: string): Promise<boolean>;
  readFile(_path: string): Promise<Buffer>;
  writeFile(_path: string, _data: Uint8Array | Buffer | string | FileLike): Promise<void>;
  readTextFile(_path: string): Promise<string>;
  readJsonFile<T = unknown>(_path: string): Promise<T>;
}
//#endregion
//#region ../../src/system/index.d.ts
/**
 * System-level abstractions for portable code across runtimes.
 *
 * **Features:**
 * - File system operations (read, write, exists, etc.)
 * - Shell command execution
 * - File type detection and MIME utilities
 * - Memory implementations for testing
 *
 * @module alepha.system
 */
declare const AlephaSystem: import("alepha").Service<import("alepha").Module>;
//#endregion
export { AlephaSystem, BunShellProvider, CpOptions, CreateFileFromArrayBufferOptions, CreateFileFromBufferOptions, CreateFileFromPathOptions, CreateFileFromResponseOptions, CreateFileFromStreamOptions, CreateFileFromTextOptions, CreateFileFromUrlOptions, CreateFileFromWebFileOptions, CreateFileOptions, FileDetector, FileError, FileSystemProvider, FileTypeResult, LsOptions, MemoryFileSystemProvider, MemoryFileSystemProviderOptions, MemoryShellCall, MemoryShellProvider, MemoryShellProviderOptions, MkdirOptions, NodeFileSystemProvider, NodeShellProvider, RmOptions, ShellProvider, ShellRunOptions, WorkerdFileSystemProvider };
//# sourceMappingURL=index.d.ts.map