alepha 0.14.3 → 0.15.0

package/src/file/index.ts

@@ -1,11 +1,14 @@
 import { $module } from "alepha";
 import { FileSystemProvider } from "./providers/FileSystemProvider.ts";
+import { MemoryFileSystemProvider } from "./providers/MemoryFileSystemProvider.ts";
 import { NodeFileSystemProvider } from "./providers/NodeFileSystemProvider.ts";
 import { FileDetector } from "./services/FileDetector.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
+export * from "./errors/FileError.ts";
 export * from "./providers/FileSystemProvider.ts";
+export * from "./providers/MemoryFileSystemProvider.ts";
 export * from "./providers/NodeFileSystemProvider.ts";
 export * from "./services/FileDetector.ts";
 
@@ -25,7 +28,12 @@ export * from "./services/FileDetector.ts";
 export const AlephaFile = $module({
   name: "alepha.file",
   primitives: [],
-  services: [FileDetector, FileSystemProvider, NodeFileSystemProvider],
+  services: [
+    FileDetector,
+    FileSystemProvider,
+    MemoryFileSystemProvider,
+    NodeFileSystemProvider,
+  ],
   register: (alepha) =>
     alepha.with({
       optional: true,

package/src/file/providers/MemoryFileSystemProvider.ts

@@ -0,0 +1,393 @@
+import type { FileLike } from "alepha";
+import type {
+  CpOptions,
+  CreateFileOptions,
+  FileSystemProvider,
+  LsOptions,
+  MkdirOptions,
+  RmOptions,
+} from "./FileSystemProvider.ts";
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+export 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");
+ * ```
+ */
+export class MemoryFileSystemProvider implements FileSystemProvider {
+  /**
+   * In-memory storage for files (path -> content)
+   */
+  public files = new Map<string, Buffer>();
+
+  /**
+   * In-memory storage for directories
+   */
+  public directories = new Set<string>();
+
+  /**
+   * Track mkdir calls for test assertions
+   */
+  public mkdirCalls: Array<{ path: string; options?: MkdirOptions }> = [];
+
+  /**
+   * Track writeFile calls for test assertions
+   */
+  public writeFileCalls: Array<{ path: string; data: string }> = [];
+
+  /**
+   * Track join calls for test assertions
+   */
+  public joinCalls: Array<string[]> = [];
+
+  /**
+   * Error to throw on mkdir (for testing error handling)
+   */
+  public mkdirError: Error | null = null;
+
+  /**
+   * Error to throw on writeFile (for testing error handling)
+   */
+  public writeFileError: Error | null = null;
+
+  /**
+   * Error to throw on readFile (for testing error handling)
+   */
+  public readFileError: Error | null = null;
+
+  constructor(options: MemoryFileSystemProviderOptions = {}) {
+    this.mkdirError = options.mkdirError ?? null;
+    this.writeFileError = options.writeFileError ?? null;
+    this.readFileError = options.readFileError ?? null;
+  }
+
+  /**
+   * Join path segments using forward slashes.
+   */
+  public join(...paths: string[]): string {
+    this.joinCalls.push(paths);
+    // Simple path join - normalize and join with /
+    return paths.filter(Boolean).join("/").replace(/\/+/g, "/");
+  }
+
+  /**
+   * Create a FileLike object from various sources.
+   */
+  public createFile(options: CreateFileOptions): FileLike {
+    if ("buffer" in options) {
+      const buffer = options.buffer;
+      return {
+        name: options.name ?? "file",
+        type: options.type ?? "application/octet-stream",
+        size: buffer.byteLength,
+        lastModified: Date.now(),
+        stream: () => {
+          throw new Error("Stream not implemented in MemoryFileSystemProvider");
+        },
+        arrayBuffer: async (): Promise<ArrayBuffer> =>
+          buffer.buffer.slice(
+            buffer.byteOffset,
+            buffer.byteOffset + buffer.byteLength,
+          ) as ArrayBuffer,
+        text: async () => buffer.toString("utf-8"),
+      };
+    }
+
+    if ("text" in options) {
+      const buffer = Buffer.from(options.text, "utf-8");
+      return {
+        name: options.name ?? "file.txt",
+        type: options.type ?? "text/plain",
+        size: buffer.byteLength,
+        lastModified: Date.now(),
+        stream: () => {
+          throw new Error("Stream not implemented in MemoryFileSystemProvider");
+        },
+        arrayBuffer: async (): Promise<ArrayBuffer> =>
+          buffer.buffer.slice(
+            buffer.byteOffset,
+            buffer.byteOffset + buffer.byteLength,
+          ) as ArrayBuffer,
+        text: async () => options.text,
+      };
+    }
+
+    throw new Error(
+      "MemoryFileSystemProvider.createFile: unsupported options. Only buffer and text are supported.",
+    );
+  }
+
+  /**
+   * Remove a file or directory from memory.
+   */
+  public async rm(path: string, options?: RmOptions): Promise<void> {
+    const exists = this.files.has(path) || this.directories.has(path);
+
+    if (!exists && !options?.force) {
+      throw new Error(`ENOENT: no such file or directory, rm '${path}'`);
+    }
+
+    if (this.directories.has(path)) {
+      if (options?.recursive) {
+        // Remove directory and all contents
+        this.directories.delete(path);
+        for (const filePath of this.files.keys()) {
+          if (filePath.startsWith(`${path}/`)) {
+            this.files.delete(filePath);
+          }
+        }
+        for (const dirPath of this.directories) {
+          if (dirPath.startsWith(`${path}/`)) {
+            this.directories.delete(dirPath);
+          }
+        }
+      } else {
+        throw new Error(
+          `EISDIR: illegal operation on a directory, rm '${path}'`,
+        );
+      }
+    } else {
+      this.files.delete(path);
+    }
+  }
+
+  /**
+   * Copy a file or directory in memory.
+   */
+  public async cp(
+    src: string,
+    dest: string,
+    options?: CpOptions,
+  ): Promise<void> {
+    if (this.directories.has(src)) {
+      if (!options?.recursive) {
+        throw new Error(
+          `Cannot copy directory without recursive option: ${src}`,
+        );
+      }
+      // Copy directory and contents
+      this.directories.add(dest);
+      for (const [filePath, content] of this.files) {
+        if (filePath.startsWith(`${src}/`)) {
+          const newPath = filePath.replace(src, dest);
+          this.files.set(newPath, Buffer.from(content));
+        }
+      }
+    } else if (this.files.has(src)) {
+      const content = this.files.get(src)!;
+      this.files.set(dest, Buffer.from(content));
+    } else {
+      throw new Error(`ENOENT: no such file or directory, cp '${src}'`);
+    }
+  }
+
+  /**
+   * Move/rename a file or directory in memory.
+   */
+  public async mv(src: string, dest: string): Promise<void> {
+    if (this.directories.has(src)) {
+      // Move directory and contents
+      this.directories.delete(src);
+      this.directories.add(dest);
+      for (const [filePath, content] of this.files) {
+        if (filePath.startsWith(`${src}/`)) {
+          const newPath = filePath.replace(src, dest);
+          this.files.delete(filePath);
+          this.files.set(newPath, content);
+        }
+      }
+    } else if (this.files.has(src)) {
+      const content = this.files.get(src)!;
+      this.files.delete(src);
+      this.files.set(dest, content);
+    } else {
+      throw new Error(`ENOENT: no such file or directory, mv '${src}'`);
+    }
+  }
+
+  /**
+   * Create a directory in memory.
+   */
+  public async mkdir(path: string, options?: MkdirOptions): Promise<void> {
+    this.mkdirCalls.push({ path, options });
+
+    if (this.mkdirError) {
+      throw this.mkdirError;
+    }
+
+    if (this.directories.has(path) && !options?.recursive) {
+      throw new Error(`EEXIST: file already exists, mkdir '${path}'`);
+    }
+
+    this.directories.add(path);
+
+    // If recursive, create parent directories
+    if (options?.recursive) {
+      const parts = path.split("/").filter(Boolean);
+      let current = "";
+      for (const part of parts) {
+        current = current ? `${current}/${part}` : part;
+        this.directories.add(current);
+      }
+    }
+  }
+
+  /**
+   * List files in a directory.
+   */
+  public async ls(path: string, options?: LsOptions): Promise<string[]> {
+    const normalizedPath = path.replace(/\/$/, "");
+    const entries = new Set<string>();
+
+    // Find files in the directory
+    for (const filePath of this.files.keys()) {
+      if (filePath.startsWith(`${normalizedPath}/`)) {
+        const relativePath = filePath.slice(normalizedPath.length + 1);
+        const parts = relativePath.split("/");
+
+        if (options?.recursive) {
+          entries.add(relativePath);
+        } else {
+          entries.add(parts[0]);
+        }
+      }
+    }
+
+    // Find subdirectories
+    for (const dirPath of this.directories) {
+      if (
+        dirPath.startsWith(`${normalizedPath}/`) &&
+        dirPath !== normalizedPath
+      ) {
+        const relativePath = dirPath.slice(normalizedPath.length + 1);
+        const parts = relativePath.split("/");
+
+        if (options?.recursive) {
+          entries.add(relativePath);
+        } else if (parts.length === 1) {
+          entries.add(parts[0]);
+        }
+      }
+    }
+
+    let result = Array.from(entries);
+
+    // Filter hidden files unless requested
+    if (!options?.hidden) {
+      result = result.filter((entry) => !entry.startsWith("."));
+    }
+
+    return result.sort();
+  }
+
+  /**
+   * Check if a file or directory exists in memory.
+   */
+  public async exists(path: string): Promise<boolean> {
+    return this.files.has(path) || this.directories.has(path);
+  }
+
+  /**
+   * Read a file from memory.
+   */
+  public async readFile(path: string): Promise<Buffer> {
+    if (this.readFileError) {
+      throw this.readFileError;
+    }
+
+    const content = this.files.get(path);
+    if (!content) {
+      throw new Error(`ENOENT: no such file or directory, open '${path}'`);
+    }
+    return content;
+  }
+
+  /**
+   * Write a file to memory.
+   */
+  public async writeFile(
+    path: string,
+    data: Uint8Array | Buffer | string | FileLike,
+  ): Promise<void> {
+    const dataStr =
+      typeof data === "string"
+        ? data
+        : data instanceof Buffer || data instanceof Uint8Array
+          ? data.toString("utf-8")
+          : await data.text();
+
+    this.writeFileCalls.push({ path, data: dataStr });
+
+    if (this.writeFileError) {
+      throw this.writeFileError;
+    }
+
+    const buffer =
+      typeof data === "string"
+        ? Buffer.from(data, "utf-8")
+        : data instanceof Buffer
+          ? data
+          : data instanceof Uint8Array
+            ? Buffer.from(data)
+            : Buffer.from(await data.text(), "utf-8");
+
+    this.files.set(path, buffer);
+  }
+
+  /**
+   * Reset all in-memory state (useful between tests).
+   */
+  public reset(): void {
+    this.files.clear();
+    this.directories.clear();
+    this.mkdirCalls = [];
+    this.writeFileCalls = [];
+    this.joinCalls = [];
+    this.mkdirError = null;
+    this.writeFileError = null;
+    this.readFileError = null;
+  }
+
+  /**
+   * Get the content of a file as a string (convenience method for testing).
+   */
+  public getFileContent(path: string): string | undefined {
+    return this.files.get(path)?.toString("utf-8");
+  }
+}

package/src/logger/index.ts

@@ -199,16 +199,28 @@ const envSchema = t.object({
    * LOG_LEVEL=my.module.name:debug,info # Set debug level for my.module.name and info for all other modules
    * LOG_LEVEL=alepha:trace, info # Set trace level for all alepha modules and info for all other modules
    */
-  LOG_LEVEL: t.optional(t.text({ lowercase: true })),
+  LOG_LEVEL: t.optional(
+    t.text({
+      description: `Application log level on startup.
+Levels are: trace, debug, info, warn, error, silent
+Level can be set for a specific module:
+"my.module.name:debug,info" -> Set debug level for my.module.name and info for all other modules
+"alepha:trace,info" -> Set trace level for all alepha modules and info for all other modules`,
+      lowercase: true,
+    }),
+  ),
 
   /**
    * Built-in log formats.
    * - "json" - JSON format, useful for structured logging and log aggregation. {@link JsonFormatterProvider}
    * - "pretty" - Simple text format, human-readable, with colors. {@link PrettyFormatterProvider}
-   * - "raw" - Raw format, no formatting, just the message.  {@link RawFormatterProvider}
+   * - "raw" - Raw format, no formatting, just the message. {@link RawFormatterProvider}
    */
   LOG_FORMAT: t.optional(
-    t.enum(["json", "pretty", "raw"], { lowercase: true }),
+    t.enum(["json", "pretty", "raw"], {
+      description: "Default log format for the application.",
+      lowercase: true,
+    }),
   ),
 });
 

package/src/mcp/transports/StdioMcpTransport.ts

@@ -121,6 +121,6 @@ export class StdioMcpTransport {
    */
   protected send(message: object): void {
     const json = JSON.stringify(message);
-    process.stdout.write(json + "\n");
+    process.stdout.write(`${json}\n`);
   }
 }

package/src/orm/index.browser.ts

@@ -1,25 +1,7 @@
 import { $module } from "alepha";
 import { AlephaDateTime } from "alepha/datetime";
 
-// ---------------------------------------------------------------------------------------------------------------------
-
-export {
-  type Page,
-  type PageQuery,
-  pageQuerySchema,
-  pageSchema,
-} from "alepha";
-export * from "./errors/DbEntityNotFoundError.ts";
-export * from "./helpers/parseQueryString.ts";
-export * from "./helpers/pgAttr.ts";
-export * from "./interfaces/FilterOperators.ts";
-export * from "./interfaces/PgQuery.ts";
-export * from "./interfaces/PgQueryWhere.ts";
-export * from "./primitives/$entity.ts";
-export * from "./providers/DatabaseTypeProvider.ts";
-export * from "./schemas/legacyIdSchema.ts";
-
-// ---------------------------------------------------------------------------------------------------------------------
+export * from "./index.shared.ts";
 
 export const AlephaPostgres = $module({
   name: "alepha.postgres",

package/src/orm/index.bun.ts

@@ -0,0 +1,77 @@
+import { $module, type Alepha, t } from "alepha";
+import { AlephaDateTime } from "alepha/datetime";
+import { $entity } from "./primitives/$entity.ts";
+import { $sequence } from "./primitives/$sequence.ts";
+import { DrizzleKitProvider } from "./providers/DrizzleKitProvider.ts";
+import { BunPostgresProvider } from "./providers/drivers/BunPostgresProvider.ts";
+import { BunSqliteProvider } from "./providers/drivers/BunSqliteProvider.ts";
+import { CloudflareD1Provider } from "./providers/drivers/CloudflareD1Provider.ts";
+import { DatabaseProvider } from "./providers/drivers/DatabaseProvider.ts";
+import { PglitePostgresProvider } from "./providers/drivers/PglitePostgresProvider.ts";
+import { RepositoryProvider } from "./providers/RepositoryProvider.ts";
+import { PgRelationManager } from "./services/PgRelationManager.ts";
+import { PostgresModelBuilder } from "./services/PostgresModelBuilder.ts";
+import { QueryManager } from "./services/QueryManager.ts";
+import { Repository } from "./services/Repository.ts";
+import { SqliteModelBuilder } from "./services/SqliteModelBuilder.ts";
+
+export * from "./index.shared-server.ts";
+export * from "./providers/drivers/BunPostgresProvider.ts";
+export * from "./providers/drivers/BunSqliteProvider.ts";
+
+export const AlephaPostgres = $module({
+  name: "alepha.postgres",
+  primitives: [$sequence, $entity],
+  services: [
+    AlephaDateTime,
+    DatabaseProvider,
+    BunPostgresProvider,
+    BunSqliteProvider,
+    PglitePostgresProvider,
+    CloudflareD1Provider,
+    SqliteModelBuilder,
+    PostgresModelBuilder,
+    DrizzleKitProvider,
+    RepositoryProvider,
+    Repository,
+    PgRelationManager,
+    QueryManager,
+  ],
+  register: (alepha: Alepha) => {
+    const env = alepha.parseEnv(
+      t.object({
+        DATABASE_URL: t.optional(t.text()),
+      }),
+    );
+
+    alepha.with(DrizzleKitProvider);
+    alepha.with(RepositoryProvider);
+
+    const url = env.DATABASE_URL;
+    const isPostgres = url?.startsWith("postgres:");
+
+    if (url?.startsWith("cloudflare-d1:")) {
+      alepha.with({
+        optional: true,
+        provide: DatabaseProvider,
+        use: CloudflareD1Provider,
+      });
+      return;
+    }
+
+    if (isPostgres) {
+      alepha.with({
+        optional: true,
+        provide: DatabaseProvider,
+        use: BunPostgresProvider,
+      });
+      return;
+    }
+
+    alepha.with({
+      optional: true,
+      provide: DatabaseProvider,
+      use: BunSqliteProvider,
+    });
+  },
+});

package/src/orm/index.shared-server.ts

@@ -0,0 +1,22 @@
+import * as drizzle from "drizzle-orm";
+
+export { drizzle };
+export { sql } from "drizzle-orm";
+export * from "drizzle-orm/pg-core";
+export * from "./constants/PG_SYMBOLS.ts";
+export * from "./errors/DbConflictError.ts";
+export * from "./errors/DbError.ts";
+export * from "./errors/DbMigrationError.ts";
+export * from "./errors/DbVersionMismatchError.ts";
+export * from "./index.shared.ts";
+export * from "./primitives/$repository.ts";
+export * from "./primitives/$sequence.ts";
+export * from "./primitives/$transaction.ts";
+export * from "./providers/DrizzleKitProvider.ts";
+export * from "./providers/drivers/CloudflareD1Provider.ts";
+export * from "./providers/drivers/DatabaseProvider.ts";
+export * from "./providers/RepositoryProvider.ts";
+export * from "./schemas/insertSchema.ts";
+export * from "./schemas/updateSchema.ts";
+export * from "./services/Repository.ts";
+export * from "./types/schema.ts";

package/src/orm/index.shared.ts

@@ -0,0 +1,15 @@
+export {
+  type Page,
+  type PageQuery,
+  pageQuerySchema,
+  pageSchema,
+} from "alepha";
+export * from "./errors/DbEntityNotFoundError.ts";
+export * from "./helpers/parseQueryString.ts";
+export * from "./helpers/pgAttr.ts";
+export * from "./interfaces/FilterOperators.ts";
+export * from "./interfaces/PgQuery.ts";
+export * from "./interfaces/PgQueryWhere.ts";
+export * from "./primitives/$entity.ts";
+export * from "./providers/DatabaseTypeProvider.ts";
+export * from "./schemas/legacyIdSchema.ts";