alepha 0.11.3 → 0.11.5

package/fake.d.ts

@@ -0,0 +1,73 @@
+import * as _alepha_core0 from "alepha";
+import { StaticDecode, TSchema } from "alepha";
+
+//#region src/providers/FakeProvider.d.ts
+interface FakeOptions {
+  /**
+   * Faker locale to use for generating fake data.
+   * @default "en"
+   */
+  locale?: string;
+  /**
+   * Seed for deterministic fake data generation.
+   */
+  seed?: number;
+}
+/**
+ * Generate fake data from TypeBox schemas using faker.js.
+ *
+ * @example
+ * ```ts
+ * const fake = new FakeProvider();
+ * const userSchema = t.object({
+ *   id: t.uuid(),
+ *   name: t.text(),
+ *   email: t.email(),
+ * });
+ * const fakeUser = fake.generate(userSchema);
+ * ```
+ */
+declare class FakeProvider {
+  private readonly faker;
+  private readonly guard;
+  constructor(options?: FakeOptions);
+  /**
+   * Generate fake data matching the given TypeBox schema.
+   */
+  generate<T extends TSchema>(schema: T): StaticDecode<T>;
+  /**
+   * Generate multiple fake data items.
+   */
+  generateMany<T extends TSchema>(schema: T, count: number): StaticDecode<T>[];
+  private generateValue;
+  private generateString;
+  private generateNumber;
+  private generateInteger;
+  private generateBigInt;
+  private generateBoolean;
+  private generateArray;
+  private generateObject;
+  /**
+   * Generate a value with context from the property key name.
+   * This helps generate more realistic fake data based on field names.
+   */
+  private generateValueWithContext;
+  private generateRecord;
+}
+//#endregion
+//#region src/index.d.ts
+/**
+ * Provides fake data generation capabilities for Alepha applications using faker.js and TypeBox schemas.
+ *
+ * The fake module enables declarative fake data generation from TypeBox schemas, making it easy to create
+ * realistic test data, seed databases, or generate mock responses. It intelligently uses property key names
+ * to generate contextually appropriate data (e.g., "email" generates an email address, "firstName" generates
+ * a first name).
+ *
+ * @see {@link FakeProvider}
+ * @module alepha.fake
+ */
+declare const AlephaFake: _alepha_core0.Service<_alepha_core0.Module<{}>>;
+//#endregion
+export { AlephaFake, FakeOptions, FakeProvider };
+//# sourceMappingURL=index.d.ts.map

package/fake.js

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

package/file.d.ts

@@ -1,5 +1,275 @@
+import * as _alepha_core0 from "alepha";
 import { FileLike, StreamLike } from "alepha";
+import { Readable } from "node:stream";
 
+//#region src/helpers/detectFileType.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;
+}
+/**
+ * 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 stream = fs.createReadStream('image.png');
+ * const result = await detectFileType(stream, 'image.png');
+ * console.log(result.mimeType); // 'image/png'
+ * console.log(result.verified); // true if magic bytes match
+ * ```
+ */
+declare function detectFileType(stream: Readable, filename: string): Promise<FileTypeResult>;
+//#endregion
+//#region src/FileSystem.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 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;
+}
+/**
+ * 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 | CreateFileFromBufferOptions | CreateFileFromStreamOptions | CreateFileFromTextOptions | CreateFileFromWebFileOptions | 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 FileSystem {
+  /**
+   * Creates a FileLike object from various sources.
+   *
+   * @param options - Options for creating the file
+   * @returns A FileLike object
+   */
+  abstract createFile(options: CreateFileOptions): FileLike;
+  /**
+   * Detects the file type by checking magic bytes in a stream.
+   *
+   * @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
+   */
+  abstract detectFileType(stream: Readable, filename: string): Promise<FileTypeResult>;
+  /**
+   * Gets the content type (MIME type) based on a filename.
+   *
+   * @param filename - The filename to check
+   * @returns The MIME type
+   */
+  abstract getContentType(filename: string): string;
+  /**
+   * 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[]>;
+}
+//#endregion
 //#region src/helpers/createFile.d.ts
 declare const createFile: (source: string | Buffer | ArrayBuffer | StreamLike | File, options?: {
   type?: string;
@@ -49,5 +319,210 @@ declare const mimeMap: Record<string, string>;
  */
 declare const getContentType: (filename: string) => string;
 //#endregion
-export { bufferToArrayBuffer, createFile, createFileFromBuffer, createFileFromStream, createFileFromUrl, createFileFromWebFile, getContentType, isReadableStream, mimeMap, streamToBuffer };
+//#region src/NodeFileSystem.d.ts
+/**
+ * Node.js implementation of FileSystem interface.
+ *
+ * @example
+ * ```typescript
+ * const fs = new NodeFileSystem();
+ *
+ * // 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 NodeFileSystem implements FileSystem {
+  /**
+   * Creates a FileLike object from various sources.
+   *
+   * @param options - Options for creating the file
+   * @returns A FileLike object
+   *
+   * @example
+   * ```typescript
+   * const fs = new NodeFileSystem();
+   *
+   * // 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;
+  /**
+   * Detects the file type by checking magic bytes in a stream.
+   *
+   * @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 fs = new NodeFileSystem();
+   * const stream = createReadStream('image.png');
+   * const result = await fs.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>;
+  /**
+   * Gets the content type (MIME type) based on a filename.
+   *
+   * @param filename - The filename to check
+   * @returns The MIME type
+   *
+   * @example
+   * ```typescript
+   * const fs = new NodeFileSystem();
+   * const mimeType = fs.getContentType("image.png"); // "image/png"
+   * ```
+   */
+  getContentType(filename: string): string;
+  /**
+   * Removes a file or directory.
+   *
+   * @param path - The path to remove
+   * @param options - Remove options
+   *
+   * @example
+   * ```typescript
+   * const fs = new NodeFileSystem();
+   *
+   * // 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 = new NodeFileSystem();
+   *
+   * // 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 = new NodeFileSystem();
+   *
+   * // 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 = new NodeFileSystem();
+   *
+   * // 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 = new NodeFileSystem();
+   *
+   * // 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[]>;
+}
+//#endregion
+//#region src/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 FileSystem}
+ * @see {@link NodeFileSystem}
+ * @module alepha.file
+ */
+declare const AlephaFile: _alepha_core0.Service<_alepha_core0.Module<{}>>;
+//#endregion
+export { AlephaFile, CpOptions, CreateFileFromArrayBufferOptions, CreateFileFromBufferOptions, CreateFileFromStreamOptions, CreateFileFromTextOptions, CreateFileFromUrlOptions, CreateFileFromWebFileOptions, CreateFileOptions, FileSystem, FileTypeResult, LsOptions, MkdirOptions, NodeFileSystem, RmOptions, bufferToArrayBuffer, createFile, createFileFromBuffer, createFileFromStream, createFileFromUrl, createFileFromWebFile, detectFileType, getContentType, isReadableStream, mimeMap, streamToBuffer };
 //# sourceMappingURL=index.d.ts.map

package/logger.d.ts

@@ -51,6 +51,7 @@ declare class Logger implements LoggerInterface {
   debug(message: string, data?: unknown): void;
   trace(message: string, data?: unknown): void;
   protected log(level: LogLevel, message: string, data?: unknown): void;
+  protected emit(entry: LogEntry, message?: string): void;
 }
 //#endregion
 //#region src/descriptors/$logger.d.ts
@@ -273,7 +274,7 @@ declare module "alepha" {
   }
   interface Hooks {
     log: {
-      message: string;
+      message?: string;
       entry: LogEntry;
     };
   }