alepha 0.14.3 → 0.14.4

package/src/core/Alepha.ts

@@ -165,6 +165,13 @@ export class Alepha {
         ...state.env,
         ...process.env,
       };
+
+      // remove empty env variables
+      for (const key in state.env) {
+        if (state.env[key] === "") {
+          delete (state.env as any)[key];
+        }
+      }
     }
 
     // force production mode when building with vite
@@ -908,6 +915,27 @@ export class Alepha {
     return graph;
   }
 
+  public dump(): AlephaDump {
+    const env: Record<string, AlephaDumpEnvVariable> = {};
+    for (const [schema] of this.cacheEnv.entries()) {
+      const ref = schema as any;
+      for (const [key, value] of Object.entries(ref.properties)) {
+        const prop = value as any;
+        env[key] = {
+          description: prop.description,
+          default: prop.default,
+          required: ref.required?.includes(key) ?? undefined,
+          enum: prop.enum ? ([...prop.enum] as Array<string>) : undefined,
+        };
+      }
+    }
+
+    return {
+      env,
+      providers: this.graph(),
+    };
+  }
+
   public services<T extends object>(base: Service<T>): Array<T> {
     const list: Array<T> = [];
     for (const [key, value] of this.registry.entries()) {
@@ -1012,6 +1040,20 @@ export interface Hook<T extends keyof Hooks = any> {
 
 // ---------------------------------------------------------------------------------------------------------------------
 
+export interface AlephaDump {
+  env: Record<string, AlephaDumpEnvVariable>;
+  providers: Record<string, { from: string[]; as?: string[]; module?: string }>;
+}
+
+export interface AlephaDumpEnvVariable {
+  description: string;
+  default?: string;
+  required?: boolean;
+  enum?: Array<string>;
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+
 /**
  * This is how we store services in the Alepha container.
  */

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.ts

@@ -5,8 +5,6 @@ import { $entity } from "./primitives/$entity.ts";
 import { $repository } from "./primitives/$repository.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 { NodePostgresProvider } from "./providers/drivers/NodePostgresProvider.ts";
@@ -116,8 +114,6 @@ export * from "./primitives/$sequence.ts";
 export * from "./primitives/$transaction.ts";
 export * from "./providers/DatabaseTypeProvider.ts";
 export * from "./providers/DrizzleKitProvider.ts";
-export * from "./providers/drivers/BunPostgresProvider.ts";
-export * from "./providers/drivers/BunSqliteProvider.ts";
 export * from "./providers/drivers/CloudflareD1Provider.ts";
 export * from "./providers/drivers/DatabaseProvider.ts";
 export * from "./providers/drivers/NodePostgresProvider.ts";
@@ -183,8 +179,6 @@ export const AlephaPostgres = $module({
     NodePostgresProvider,
     PglitePostgresProvider,
     NodeSqliteProvider,
-    BunPostgresProvider,
-    BunSqliteProvider,
     CloudflareD1Provider,
     SqliteModelBuilder,
     PostgresModelBuilder,
@@ -233,7 +227,7 @@ export const AlephaPostgres = $module({
       alepha.with({
         optional: true,
         provide: DatabaseProvider,
-        use: alepha.isBun() ? BunPostgresProvider : NodePostgresProvider,
+        use: NodePostgresProvider,
       });
       return;
     }
@@ -241,7 +235,7 @@ export const AlephaPostgres = $module({
     alepha.with({
       optional: true,
       provide: DatabaseProvider,
-      use: alepha.isBun() ? BunSqliteProvider : NodeSqliteProvider,
+      use: NodeSqliteProvider,
     });
   },
 });

package/src/queue/core/providers/WorkerProvider.spec.ts

@@ -1,4 +1,5 @@
 import { Alepha, t } from "alepha";
+import { $logger } from "alepha/logger";
 import { describe, expect, test, vi } from "vitest";
 import {
   $consumer,
@@ -13,6 +14,16 @@ const payloadSchema = t.object({
   count: t.integer(),
 });
 
+class TestWorkerProvider extends WorkerProvider {
+  public readonly log = $logger();
+  public workersRunning = 0;
+  public workerIntervals: Record<number, number> = {};
+  public abortController = new AbortController();
+  public waitForNextMessage(n: number): Promise<void> {
+    return super.waitForNextMessage(n);
+  }
+}
+
 describe("WorkerProvider", () => {
   const createTestApp = async (
     options: {
@@ -29,6 +40,11 @@ describe("WorkerProvider", () => {
       },
     });
 
+    app.with({
+      provide: WorkerProvider,
+      use: TestWorkerProvider,
+    });
+
     app.with({
       provide: QueueProvider,
       use: MemoryQueueProvider,
@@ -52,16 +68,16 @@ describe("WorkerProvider", () => {
       const app = await createTestApp();
       app.with(TestService);
 
-      const workerProvider = app.inject(WorkerProvider);
-      const logSpy = vi.spyOn(workerProvider["log"], "debug");
+      const workerProvider = app.inject(TestWorkerProvider);
+      const logSpy = vi.spyOn(workerProvider.log, "debug");
 
       await app.start();
 
       expect(logSpy).toHaveBeenCalledWith("Starting worker n-0");
-      expect(workerProvider["workersRunning"]).toBe(1);
+      expect(workerProvider.workersRunning).toBe(1);
 
       await app.stop();
-      expect(workerProvider["workersRunning"]).toBe(0);
+      expect(workerProvider.workersRunning).toBe(0);
     });
 
     test("should start multiple workers with concurrency", async () => {
@@ -76,32 +92,32 @@ describe("WorkerProvider", () => {
       const app = await createTestApp({ workerConcurrency: 3 });
       app.with(TestService);
 
-      const workerProvider = app.inject(WorkerProvider);
-      const logSpy = vi.spyOn(workerProvider["log"], "debug");
+      const workerProvider = app.inject(TestWorkerProvider);
+      const logSpy = vi.spyOn(workerProvider.log, "debug");
 
       await app.start();
 
       expect(logSpy).toHaveBeenCalledWith("Starting worker n-0");
       expect(logSpy).toHaveBeenCalledWith("Starting worker n-1");
       expect(logSpy).toHaveBeenCalledWith("Starting worker n-2");
-      expect(workerProvider["workersRunning"]).toBe(3);
+      expect(workerProvider.workersRunning).toBe(3);
 
       await app.stop();
-      expect(workerProvider["workersRunning"]).toBe(0);
+      expect(workerProvider.workersRunning).toBe(0);
     });
 
     test("should not start workers when no consumers", async () => {
       const app = await createTestApp();
 
-      const workerProvider = app.inject(WorkerProvider);
-      const logSpy = vi.spyOn(workerProvider["log"], "debug");
+      const workerProvider = app.inject(TestWorkerProvider);
+      const logSpy = vi.spyOn(workerProvider.log, "debug");
 
       await app.start();
 
       expect(logSpy).not.toHaveBeenCalledWith(
         expect.stringMatching(/Starting worker/),
       );
-      expect(workerProvider["workersRunning"]).toBe(0);
+      expect(workerProvider.workersRunning).toBe(0);
 
       await app.stop();
     });
@@ -120,20 +136,20 @@ describe("WorkerProvider", () => {
       const app = await createTestApp({ workerConcurrency: 2 });
       app.with(TestService);
 
-      const workerProvider = app.inject(WorkerProvider);
-      const debugSpy = vi.spyOn(workerProvider["log"], "debug");
+      const workerProvider = app.inject(TestWorkerProvider);
+      const debugSpy = vi.spyOn(workerProvider.log, "debug");
 
       await app.start();
-      expect(workerProvider["workersRunning"]).toBe(2);
+      expect(workerProvider.workersRunning).toBe(2);
 
       // Simulate worker crash by manually decrementing counter
-      workerProvider["workersRunning"] = 1;
+      workerProvider.workersRunning = 1;
 
       // Call wakeUp - should detect missing worker and restart it
       workerProvider.wakeUp();
 
       expect(debugSpy).toHaveBeenCalledWith("Waking up workers...");
-      expect(workerProvider["workersRunning"]).toBe(2);
+      expect(workerProvider.workersRunning).toBe(2);
 
       await app.stop();
     });
@@ -150,16 +166,16 @@ describe("WorkerProvider", () => {
       const app = await createTestApp();
       app.with(TestService);
 
-      const workerProvider = app.inject(WorkerProvider);
+      const workerProvider = app.inject(TestWorkerProvider);
 
       await app.start();
 
-      const oldController = workerProvider["abortController"];
+      const oldController = workerProvider.abortController;
       expect(oldController.signal.aborted).toBe(false);
 
       workerProvider.wakeUp();
 
-      const newController = workerProvider["abortController"];
+      const newController = workerProvider.abortController;
       expect(oldController.signal.aborted).toBe(true);
       expect(newController.signal.aborted).toBe(false);
       expect(newController).not.toBe(oldController);
@@ -217,8 +233,8 @@ describe("WorkerProvider", () => {
       const app = await createTestApp();
       app.with(TestService);
 
-      const workerProvider = app.inject(WorkerProvider);
-      const errorSpy = vi.spyOn(workerProvider["log"], "error");
+      const workerProvider = app.inject(TestWorkerProvider);
+      const errorSpy = vi.spyOn(workerProvider.log, "error");
 
       await app.start();
 
@@ -230,7 +246,7 @@ describe("WorkerProvider", () => {
         .toBeTruthy();
 
       // Worker should still be running after processing error
-      expect(workerProvider["workersRunning"]).toBe(1);
+      expect(workerProvider.workersRunning).toBe(1);
 
       await app.stop();
     });
@@ -282,9 +298,9 @@ describe("WorkerProvider", () => {
       const app = await createTestApp();
       app.with(TestService);
 
-      const workerProvider = app.inject(WorkerProvider);
+      const workerProvider = app.inject(TestWorkerProvider);
       const queueProvider = app.inject(QueueProvider);
-      const errorSpy = vi.spyOn(workerProvider["log"], "error");
+      const errorSpy = vi.spyOn(workerProvider.log, "error");
 
       await app.start();
 
@@ -301,7 +317,7 @@ describe("WorkerProvider", () => {
       );
 
       // Worker should still be running
-      expect(workerProvider["workersRunning"]).toBe(1);
+      expect(workerProvider.workersRunning).toBe(1);
 
       await app.stop();
     });
@@ -318,9 +334,9 @@ describe("WorkerProvider", () => {
       const app = await createTestApp();
       app.with(TestService);
 
-      const workerProvider = app.inject(WorkerProvider);
+      const workerProvider = app.inject(TestWorkerProvider);
       const queueProvider = app.inject(QueueProvider);
-      const errorSpy = vi.spyOn(workerProvider["log"], "error");
+      const errorSpy = vi.spyOn(workerProvider.log, "error");
 
       await app.start();
 
@@ -342,7 +358,7 @@ describe("WorkerProvider", () => {
       );
 
       // Worker should still be running
-      expect(workerProvider["workersRunning"]).toBe(1);
+      expect(workerProvider.workersRunning).toBe(1);
 
       await app.stop();
     });
@@ -359,16 +375,16 @@ describe("WorkerProvider", () => {
       const app = await createTestApp({ workerInterval: 5000 });
       app.with(TestService);
 
-      const workerProvider = app.inject(WorkerProvider);
-      const warnSpy = vi.spyOn(workerProvider["log"], "warn");
+      const workerProvider = app.inject(TestWorkerProvider);
+      const warnSpy = vi.spyOn(workerProvider.log, "warn");
 
       await app.start();
 
       // Abort the controller to simulate abort during wait
-      workerProvider["abortController"].abort();
+      workerProvider.abortController.abort();
 
       // This should detect the abort and return early
-      await workerProvider["waitForNextMessage"](0);
+      await workerProvider.waitForNextMessage(0);
 
       expect(warnSpy).toHaveBeenCalledWith("Worker n-0 aborted.");
 

package/src/server/cache/providers/ServerCacheProvider.spec.ts

@@ -865,6 +865,189 @@ describe("ServerCacheProvider", () => {
     });
   });
 
+  describe("Stream caching support", () => {
+    test("should cache ReadableStream responses via tee", async ({
+      expect,
+    }) => {
+      // Create a simple ReadableStream that emits chunks
+      const chunks = ["Hello", " ", "World"];
+      const stream = new ReadableStream<Uint8Array>({
+        start(controller) {
+          const encoder = new TextEncoder();
+          for (const chunk of chunks) {
+            controller.enqueue(encoder.encode(chunk));
+          }
+          controller.close();
+        },
+      });
+
+      // Access the protected method via type assertion
+      const provider = cacheProvider as any;
+      const key = "test-stream-key";
+
+      // Collect the stream for cache
+      const hash = await provider.collectStreamForCache(
+        stream,
+        key,
+        200,
+        "text/html",
+        true,
+      );
+
+      expect(hash).toBeDefined();
+      expect(hash).toMatch(/^"[a-f0-9]+"$/); // ETag format
+
+      // Verify the cache contains the collected content
+      const cached = await provider.cache.get(key);
+      expect(cached).toBeDefined();
+      expect(cached.body).toBe("Hello World");
+      expect(cached.status).toBe(200);
+      expect(cached.contentType).toBe("text/html");
+    });
+
+    test("should tee stream so client and cache both receive data", async ({
+      expect,
+    }) => {
+      const encoder = new TextEncoder();
+      const chunks = ["<html>", "<body>", "Content", "</body>", "</html>"];
+
+      const originalStream = new ReadableStream<Uint8Array>({
+        start(controller) {
+          for (const chunk of chunks) {
+            controller.enqueue(encoder.encode(chunk));
+          }
+          controller.close();
+        },
+      });
+
+      // Tee the stream like ServerCacheProvider does
+      const [clientStream, cacheStream] = originalStream.tee();
+
+      // Read from client stream (simulates client receiving data)
+      const clientReader = clientStream.getReader();
+      const clientChunks: string[] = [];
+      const decoder = new TextDecoder();
+
+      while (true) {
+        const { done, value } = await clientReader.read();
+        if (done) break;
+        clientChunks.push(decoder.decode(value, { stream: true }));
+      }
+      clientChunks.push(decoder.decode()); // flush
+
+      // Read from cache stream (simulates cache collection)
+      const cacheReader = cacheStream.getReader();
+      const cacheChunks: string[] = [];
+      const cacheDecoder = new TextDecoder();
+
+      while (true) {
+        const { done, value } = await cacheReader.read();
+        if (done) break;
+        cacheChunks.push(cacheDecoder.decode(value, { stream: true }));
+      }
+      cacheChunks.push(cacheDecoder.decode()); // flush
+
+      // Both should receive the same data
+      const clientData = clientChunks.join("");
+      const cacheData = cacheChunks.join("");
+
+      expect(clientData).toBe("<html><body>Content</body></html>");
+      expect(cacheData).toBe("<html><body>Content</body></html>");
+      expect(clientData).toBe(cacheData);
+    });
+
+    test("should handle empty stream gracefully", async ({ expect }) => {
+      const stream = new ReadableStream<Uint8Array>({
+        start(controller) {
+          controller.close();
+        },
+      });
+
+      const provider = cacheProvider as any;
+      const key = "empty-stream-key";
+
+      const hash = await provider.collectStreamForCache(
+        stream,
+        key,
+        200,
+        "text/html",
+        true,
+      );
+
+      expect(hash).toBeDefined();
+
+      const cached = await provider.cache.get(key);
+      expect(cached).toBeDefined();
+      expect(cached.body).toBe("");
+    });
+
+    test("should handle large stream with multiple chunks", async ({
+      expect,
+    }) => {
+      const encoder = new TextEncoder();
+      const chunkCount = 100;
+      const chunkContent = "x".repeat(1000);
+
+      const stream = new ReadableStream<Uint8Array>({
+        start(controller) {
+          for (let i = 0; i < chunkCount; i++) {
+            controller.enqueue(encoder.encode(chunkContent));
+          }
+          controller.close();
+        },
+      });
+
+      const provider = cacheProvider as any;
+      const key = "large-stream-key";
+
+      const hash = await provider.collectStreamForCache(
+        stream,
+        key,
+        200,
+        "text/html",
+        false,
+      );
+
+      // hash should be undefined when generateEtag is false
+      expect(hash).toBeUndefined();
+
+      const cached = await provider.cache.get(key);
+      expect(cached).toBeDefined();
+      expect(cached.body.length).toBe(chunkCount * chunkContent.length);
+    });
+
+    test("should generate correct ETag for streamed content", async ({
+      expect,
+    }) => {
+      const content = "Test content for ETag";
+      const encoder = new TextEncoder();
+
+      const stream = new ReadableStream<Uint8Array>({
+        start(controller) {
+          controller.enqueue(encoder.encode(content));
+          controller.close();
+        },
+      });
+
+      const provider = cacheProvider as any;
+
+      // Generate ETag from stream
+      const streamHash = await provider.collectStreamForCache(
+        stream,
+        "etag-test-key",
+        200,
+        "text/html",
+        true,
+      );
+
+      // Generate ETag from string directly
+      const stringHash = cacheProvider.generateETag(content);
+
+      // Both should produce the same ETag
+      expect(streamHash).toBe(stringHash);
+    });
+  });
+
   describe("Error response caching", () => {
     test("should NOT cache 500 error responses", async ({ expect }) => {
       const response1 = await app.errorAction.fetch();

package/src/server/cache/providers/ServerCacheProvider.ts

@@ -261,24 +261,55 @@ export class ServerCacheProvider {
         return;
       }
 
-      // Only process string responses (text, html, json, etc.)
-      // Buffer is not supported by alepha/cache for now
-      if (typeof response.body !== "string") {
-        return;
-      }
-
       // Don't cache error responses (status >= 400)
       if (response.status && response.status >= 400) {
         return;
       }
 
+      // Initialize headers if not present
+      response.headers ??= {};
+
       const key = this.createCacheKey(route, request);
+
+      // Handle ReadableStream responses (e.g., SSR streaming)
+      if (response.body instanceof ReadableStream && shouldStore) {
+        // Tee the stream: one for client, one for cache collection
+        const [clientStream, cacheStream] = (
+          response.body as ReadableStream<Uint8Array>
+        ).tee();
+
+        // Replace response body with client stream (continues streaming to client)
+        response.body = clientStream as typeof response.body;
+
+        // Collect cache stream in background (non-blocking)
+        this.collectStreamForCache(
+          cacheStream,
+          key,
+          response.status,
+          response.headers?.["content-type"],
+          shouldUseEtag,
+        )
+          .then((hash) => {
+            if (shouldUseEtag && hash) {
+              // Note: headers already sent for streaming, etag only useful for future requests
+              this.log.trace("Stream cached with hash", { key, hash });
+            }
+          })
+          .catch((err) => {
+            this.log.warn("Failed to cache stream", { key, error: err });
+          });
+
+        return;
+      }
+
+      // Only process string responses (text, html, json, etc.)
+      if (typeof response.body !== "string") {
+        return;
+      }
+
       const generatedEtag = this.generateETag(response.body);
       const lastModified = this.time.toISOString();
 
-      // Initialize headers if not present
-      response.headers ??= {};
-
       // Store response if storing is enabled
       if (shouldStore) {
         this.log.trace("Storing response", {
@@ -404,6 +435,60 @@ export class ServerCacheProvider {
 
     return `${route.method}:${route.path.replaceAll(":", "")}:${params.join(",").replaceAll(":", "")}`;
   }
+
+  /**
+   * Collect a ReadableStream into a string and store it in the cache.
+   * This runs in the background while the original stream is sent to the client.
+   *
+   * @param stream - The stream to collect
+   * @param key - Cache key
+   * @param status - HTTP status code
+   * @param contentType - Content-Type header
+   * @param generateEtag - Whether to generate and return an ETag
+   * @returns The generated ETag hash, or undefined
+   */
+  protected async collectStreamForCache(
+    stream: ReadableStream<Uint8Array>,
+    key: string,
+    status: number | undefined,
+    contentType: string | undefined,
+    generateEtag: boolean,
+  ): Promise<string | undefined> {
+    const chunks: Uint8Array[] = [];
+    const reader = stream.getReader();
+
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        chunks.push(value);
+      }
+
+      // Combine chunks into a single string
+      const decoder = new TextDecoder();
+      const body =
+        chunks
+          .map((chunk) => decoder.decode(chunk, { stream: true }))
+          .join("") + decoder.decode(); // Flush remaining
+
+      const hash = this.generateETag(body);
+      const lastModified = this.time.toISOString();
+
+      this.log.trace("Storing streamed response", { key });
+
+      await this.cache.set(key, {
+        body,
+        status,
+        contentType,
+        lastModified,
+        hash,
+      });
+
+      return generateEtag ? hash : undefined;
+    } finally {
+      reader.releaseLock();
+    }
+  }
 }
 
 export type ServerRouteCache =