alepha 0.14.2 → 0.14.4

package/src/vite/plugins/viteAlephaSsrPreload.ts

@@ -0,0 +1,222 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import type { Plugin } from "vite";
+
+/**
+ * Preload manifest mapping short keys to source paths.
+ * Generated at build time, consumed by SSRManifestProvider at runtime.
+ */
+export interface PreloadManifest {
+  [key: string]: string;
+}
+
+/**
+ * Vite plugin that generates a preload manifest for SSR module preloading.
+ *
+ * Instead of injecting source paths directly into $page definitions (which would
+ * leak component paths in the browser bundle), this plugin:
+ *
+ * 1. Collects all lazy import paths from $page definitions during transform
+ * 2. Generates a manifest file mapping short keys to resolved source paths
+ * 3. Injects only the short key into $page definitions
+ *
+ * The manifest is written to `.vite/preload-manifest.json` alongside Vite's
+ * other manifests. The CLI build command moves all manifests to
+ * `dist/server/.ssr/` where SSRManifestProvider loads them at runtime.
+ *
+ * Before:
+ * ```typescript
+ * $page({
+ *   path: '/users/:id',
+ *   lazy: () => import('./UserDetail.tsx'),
+ * })
+ * ```
+ *
+ * After:
+ * ```typescript
+ * $page({
+ *   path: '/users/:id',
+ *   lazy: () => import('./UserDetail.tsx'),
+ *   [Symbol.for("alepha.page.preload")]: "a1b2c3",
+ * })
+ * ```
+ *
+ * Manifest (.alepha/preload-manifest.json):
+ * ```json
+ * {
+ *   "a1b2c3": "src/pages/UserDetail.tsx"
+ * }
+ * ```
+ */
+export function viteAlephaSsrPreload(): Plugin {
+  let root = "";
+  const preloadMap = new Map<string, string>(); // key -> sourcePath
+
+  /**
+   * Generate a short hash key for a source path.
+   * Uses first 8 chars of MD5 hash for brevity while avoiding collisions.
+   */
+  function generateKey(sourcePath: string): string {
+    return createHash("md5").update(sourcePath).digest("hex").slice(0, 8);
+  }
+
+  return {
+    name: "alepha-preload",
+    configResolved(config) {
+      root = config.root;
+    },
+    transform(code, id) {
+      // Only process TypeScript/JavaScript files
+      if (!id.match(/\.[tj]sx?$/)) {
+        return null;
+      }
+
+      // Skip node_modules
+      if (id.includes("node_modules")) {
+        return null;
+      }
+
+      // Quick check if file contains $page with lazy
+      if (!code.includes("$page") || !code.includes("lazy")) {
+        return null;
+      }
+
+      // Collect all insertions first, then apply in reverse order
+      const insertions: Array<{ position: number; text: string }> = [];
+
+      // Find all $page({ occurrences
+      const pageStartRegex = /\$page\s*\(\s*\{/g;
+      let pageMatch: RegExpExecArray | null = pageStartRegex.exec(code);
+
+      while (pageMatch !== null) {
+        const startIndex = pageMatch.index;
+        const objectStartIndex = startIndex + pageMatch[0].length - 1; // Position of '{'
+
+        // Find the matching closing brace using brace counting
+        let braceCount = 1;
+        let i = objectStartIndex + 1;
+        while (i < code.length && braceCount > 0) {
+          if (code[i] === "{") braceCount++;
+          else if (code[i] === "}") braceCount--;
+          i++;
+        }
+
+        // Malformed, skip
+        if (braceCount !== 0) {
+          pageMatch = pageStartRegex.exec(code);
+          continue;
+        }
+
+        const objectEndIndex = i - 1; // Position of matching '}'
+        const pageContent = code.slice(objectStartIndex, objectEndIndex + 1);
+
+        // Skip if already has preload symbol
+        if (pageContent.includes("alepha.page.preload")) {
+          pageMatch = pageStartRegex.exec(code);
+          continue;
+        }
+
+        // Find lazy: () => import('...') within this $page block
+        const lazyRegex =
+          /lazy\s*:\s*\(\s*\)\s*=>\s*import\s*\(\s*['"]([^'"]+)['"]\s*\)/;
+        const lazyMatch = lazyRegex.exec(pageContent);
+
+        if (!lazyMatch) {
+          pageMatch = pageStartRegex.exec(code);
+          continue;
+        }
+
+        const importPath = lazyMatch[1];
+
+        // Resolve the import path relative to the current file
+        const currentDir = dirname(id);
+        let resolvedPath: string;
+
+        if (importPath.startsWith(".")) {
+          // Relative import
+          resolvedPath = resolve(currentDir, importPath);
+        } else if (importPath.startsWith("/")) {
+          // Absolute import from root
+          resolvedPath = resolve(root, importPath.slice(1));
+        } else {
+          // Package import - skip preloading for external packages
+          pageMatch = pageStartRegex.exec(code);
+          continue;
+        }
+
+        // Make path relative to root for SSR manifest lookup
+        let relativePath = relative(root, resolvedPath);
+
+        // Normalize path separators for cross-platform compatibility
+        relativePath = relativePath.replace(/\\/g, "/");
+
+        // Handle extension - Vite resolves .jsx imports to .tsx files
+        // Try to use .tsx when the source has .jsx since TypeScript is more common
+        if (!relativePath.match(/\.[tj]sx?$/)) {
+          relativePath = `${relativePath}.tsx`;
+        } else if (relativePath.endsWith(".jsx")) {
+          // Import said .jsx but actual file is likely .tsx
+          relativePath = relativePath.replace(/\.jsx$/, ".tsx");
+        } else if (relativePath.endsWith(".js")) {
+          // Import said .js but actual file is likely .ts
+          relativePath = relativePath.replace(/\.js$/, ".ts");
+        }
+
+        // Generate short key and store mapping
+        const key = generateKey(relativePath);
+        preloadMap.set(key, relativePath);
+
+        // Check if we need a comma (look at character before closing brace)
+        const beforeBrace = code.slice(0, objectEndIndex).trimEnd();
+        const needsComma = !beforeBrace.endsWith(",");
+        // Use Symbol.for() so it can be looked up at runtime without importing
+        // Only inject the short key, not the full path
+        const preloadProperty = `${needsComma ? "," : ""} [Symbol.for("alepha.page.preload")]: "${key}"`;
+
+        insertions.push({ position: objectEndIndex, text: preloadProperty });
+
+        pageMatch = pageStartRegex.exec(code);
+      }
+
+      if (insertions.length === 0) {
+        return null;
+      }
+
+      // Apply insertions in reverse order to preserve positions
+      let result = code;
+      for (let j = insertions.length - 1; j >= 0; j--) {
+        const { position, text } = insertions[j];
+        result = result.slice(0, position) + text + result.slice(position);
+      }
+
+      return {
+        code: result,
+        map: null,
+      };
+    },
+    writeBundle(options) {
+      // Only process client build (outputs to dist/public or similar)
+      // Skip server build which outputs to dist/server
+      const outDir = options.dir || "";
+      if (outDir.includes("server")) {
+        return;
+      }
+
+      // Write the preload manifest to the same .vite directory Vite uses
+      // The CLI build command will move all manifests to dist/server/.ssr/
+      if (preloadMap.size > 0) {
+        const viteDir = join(outDir, ".vite");
+
+        // Ensure .vite directory exists
+        if (!existsSync(viteDir)) {
+          mkdirSync(viteDir, { recursive: true });
+        }
+
+        const manifest: PreloadManifest = Object.fromEntries(preloadMap);
+        const manifestPath = join(viteDir, "preload-manifest.json");
+        writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+      }
+    },
+  };
+}

package/src/vite/tasks/buildClient.ts

@@ -2,6 +2,8 @@ import type { UserConfig } from "vite";
 import { analyzer as viteAnalyzer } from "vite-bundle-analyzer";
 import { createBufferedLogger } from "../helpers/createBufferedLogger.ts";
 import { importVite } from "../helpers/importVite.ts";
+import { importViteReact } from "../helpers/importViteReact.ts";
+import { viteAlephaSsrPreload } from "../plugins/viteAlephaSsrPreload.ts";
 import {
   type ViteCompressOptions,
   viteCompress,
@@ -62,6 +64,12 @@ export async function buildClient(opts: BuildClientOptions): Promise<void> {
   const { build: viteBuild, mergeConfig } = await importVite();
   const plugins: any[] = [];
 
+  const viteReact = await importViteReact();
+  if (viteReact) plugins.push(viteReact());
+
+  // Add preload plugin for SSR module preloading
+  plugins.push(viteAlephaSsrPreload());
+
   const compress: ViteCompressOptions | undefined = opts.precompress
     ? typeof opts.precompress === "object"
       ? opts.precompress
@@ -93,6 +101,9 @@ export async function buildClient(opts: BuildClientOptions): Promise<void> {
     build: {
       chunkSizeWarningLimit: 1000,
       outDir: opts.dist,
+      // Generate manifest for SSR module preloading
+      manifest: true,
+      ssrManifest: true,
       rollupOptions: {
         output: {
           entryFileNames: "entry.[hash].js",

package/src/vite/tasks/buildServer.ts

@@ -1,4 +1,4 @@
-import { readFile, writeFile } from "node:fs/promises";
+import { readFile, rm, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { AlephaError } from "alepha";
 import type * as vite from "vite";
@@ -6,6 +6,8 @@ import type { UserConfig } from "vite";
 import { analyzer as viteAnalyzer } from "vite-bundle-analyzer";
 import { createBufferedLogger } from "../helpers/createBufferedLogger.ts";
 import { importVite } from "../helpers/importVite.ts";
+import { importViteReact } from "../helpers/importViteReact.ts";
+import { viteAlephaSsrPreload } from "../plugins/viteAlephaSsrPreload.ts";
 import { generateExternals } from "./generateExternals.ts";
 
 export interface BuildServerOptions {
@@ -63,6 +65,13 @@ export async function buildServer(
   const { build: viteBuild, mergeConfig } = await importVite();
   const plugins: any[] = [];
 
+  const viteReact = await importViteReact();
+  if (viteReact && opts.clientDir) {
+    plugins.push(viteReact());
+  }
+
+  plugins.push(viteAlephaSsrPreload());
+
   if (opts.stats) {
     plugins.push(
       viteAnalyzer({
@@ -85,7 +94,7 @@ export async function buildServer(
       noExternal: true,
     },
     build: {
-      sourcemap: true, // or "hidden" if you don't want to expose source maps
+      sourcemap: true,
       ssr: opts.entry,
       outDir: `${opts.distDir}/server`,
       minify: true,
@@ -138,6 +147,29 @@ export async function buildServer(
     template = `__alepha.set("alepha.react.server.template", \`${index.replace(/>\s*</g, "><").trim()}\`);\n`;
   }
 
+  // Embed SSR manifests if client was built
+  // This bundles all manifest data into index.js for serverless deployments
+  let manifest = "";
+  if (opts.clientDir) {
+    const viteDir = `${opts.distDir}/${opts.clientDir}/.vite`;
+    const ssrManifest = await loadJsonFile(`${viteDir}/ssr-manifest.json`);
+    const clientManifest = await loadJsonFile(`${viteDir}/manifest.json`);
+    const preloadManifest = await loadJsonFile(
+      `${viteDir}/preload-manifest.json`,
+    );
+
+    const combined = {
+      ssr: ssrManifest,
+      client: clientManifest,
+      preload: preloadManifest,
+    };
+
+    manifest = `__alepha.set("alepha.react.ssr.manifest", ${JSON.stringify(combined)});\n`;
+
+    // Remove .vite directory - no longer needed at runtime
+    await rm(viteDir, { recursive: true, force: true });
+  }
+
   const warning =
     "// This file was automatically generated. DO NOT MODIFY." +
     "\n" +
@@ -145,12 +177,24 @@ export async function buildServer(
 
   await writeFile(
     `${opts.distDir}/index.js`,
-    `${warning}\nimport './server/${entryFile}';\n\n${template}`.trim(),
+    `${warning}\n${template}${manifest}import './server/${entryFile}';\n`.trim(),
   );
 
   return { entryFile };
 }
 
+/**
+ * Load a JSON file, returning undefined if it doesn't exist.
+ */
+async function loadJsonFile(path: string): Promise<any> {
+  try {
+    const content = await readFile(path, "utf-8");
+    return JSON.parse(content);
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * Extract entry filename from Vite build result.
  */

package/src/vite/tasks/devServer.ts

@@ -0,0 +1,69 @@
+import type { InlineConfig } from "vite";
+import { importVite } from "../helpers/importVite.ts";
+import { importViteReact } from "../helpers/importViteReact.ts";
+import { viteAlephaDev } from "../plugins/viteAlephaDev.ts";
+import { viteAlephaSsrPreload } from "../plugins/viteAlephaSsrPreload.ts";
+
+export interface DevServerOptions {
+  /**
+   * Path to the server entry file.
+   * If not provided, will auto-detect.
+   */
+  entry?: string;
+
+  /**
+   * Port to run the dev server on.
+   */
+  port?: number;
+
+  /**
+   * Host to bind the dev server to.
+   */
+  host?: string | boolean;
+
+  /**
+   * Enable debug logging.
+   */
+  debug?: boolean;
+}
+
+/**
+ * Start Vite development server with Alepha plugins.
+ *
+ * This task starts the Vite dev server with all required plugins:
+ * - @vitejs/plugin-react (JSX/TSX compilation)
+ * - viteAlephaDev (Alepha server integration)
+ * - viteAlephaSsrPreload (SSR module preloading)
+ */
+export async function devServer(opts: DevServerOptions = {}): Promise<void> {
+  const { createServer, mergeConfig } = await importVite();
+  const plugins: any[] = [];
+
+  // Add React plugin for JSX/TSX compilation
+  const viteReact = await importViteReact();
+  if (viteReact) plugins.push(viteReact());
+
+  // Add SSR preload plugin
+  plugins.push(viteAlephaSsrPreload());
+
+  // Add Alepha dev plugin
+  plugins.push(
+    await viteAlephaDev({
+      serverEntry: opts.entry,
+      debug: opts.debug,
+    }),
+  );
+
+  const config: InlineConfig = {
+    plugins,
+    server: {
+      port: opts.port,
+      host: opts.host,
+    },
+  };
+
+  const server = await createServer(mergeConfig(config, {}));
+  await server.listen();
+
+  // server.printUrls();
+}

package/src/vite/tasks/index.ts

@@ -2,7 +2,7 @@
  * Build tasks for Alepha applications.
  *
  * These tasks can be used by:
- * - Vite plugins (viteAlephaDev, viteAlephaBuild)
+ * - Vite plugins (viteAlephaDev, viteAlephaSsrPreload)
  * - CLI commands (alepha build, alepha dev)
  *
  * Each task is a standalone async function with explicit inputs and outputs.
@@ -13,6 +13,7 @@
 export * from "./buildClient.ts";
 export * from "./buildServer.ts";
 export * from "./copyAssets.ts";
+export * from "./devServer.ts";
 export * from "./generateCloudflare.ts";
 export * from "./generateDocker.ts";
 export * from "./generateExternals.ts";

package/src/vite/tasks/runAlepha.ts

@@ -132,13 +132,19 @@ export class AlephaRunner {
       process.env[key] = env[key];
     }
 
+    let port = 5173;
+    const address = server.httpServer?.address();
+    if (typeof address === "object" && address?.port) {
+      port = address.port;
+    }
+
     process.env.NODE_ENV ??= "development";
     process.env.VITE_ALEPHA_DEV = "true";
     process.env.SERVER_HOST ??=
       typeof server.config.server.host === "string"
         ? server.config.server.host
         : "localhost";
-    process.env.SERVER_PORT ??= String(server.config.server.port || "5173");
+    process.env.SERVER_PORT ??= String(port);
 
     try {
       const now = Date.now();

package/src/websocket/__tests__/$websocket-new.spec.ts

@@ -0,0 +1,195 @@
+import { Alepha, t } from "alepha";
+import { NodeHttpServerProvider } from "alepha/server";
+import { test } from "vitest";
+import WebSocket from "ws";
+import { AlephaWebSocket } from "../index.ts";
+import { $channel } from "../primitives/$channel.ts";
+import { $websocket } from "../primitives/$websocket.ts";
+
+test("$websocket with channel-based architecture", async ({ expect }) => {
+  const alepha = Alepha.create().with(AlephaWebSocket);
+
+  const messages: any[] = [];
+
+  class ChatController {
+    // Define channel inside the class
+    chatChannel = $channel({
+      path: "/ws/chat",
+      schema: {
+        // Server → Client messages
+        in: t.union([
+          t.object({
+            type: t.const("append"),
+            content: t.text(),
+            username: t.text(),
+          }),
+          t.object({
+            type: t.const("system"),
+            message: t.text(),
+          }),
+        ]),
+        // Client → Server messages
+        out: t.object({
+          content: t.text(),
+        }),
+      },
+    });
+
+    chat = $websocket({
+      channel: this.chatChannel,
+      handler: async ({ connectionId, roomId, message, reply }) => {
+        // Broadcast to all in room except sender
+        await reply({
+          message: {
+            type: "append",
+            content: message.content,
+            username: connectionId,
+          },
+          exceptSelf: true,
+        });
+      },
+    });
+  }
+
+  const controller = alepha.inject(ChatController);
+  await alepha.start();
+
+  const httpServer = alepha.inject(NodeHttpServerProvider);
+  const hostname = httpServer.hostname.replace("http://", "ws://");
+
+  // Connect two clients to the same room
+  const ws1 = new WebSocket(`${hostname}/ws/chat?roomId=room-1`);
+  const ws2 = new WebSocket(`${hostname}/ws/chat?roomId=room-1`);
+
+  await Promise.all([
+    new Promise((resolve) => ws1.on("open", resolve)),
+    new Promise((resolve) => ws2.on("open", resolve)),
+  ]);
+
+  // Listen for messages on ws2
+  ws2.on("message", (data) => {
+    const message = JSON.parse(data.toString());
+    messages.push(message);
+  });
+
+  // Wait a bit for connections to be established
+  await new Promise((resolve) => setTimeout(resolve, 100));
+
+  // Send message from ws1
+  ws1.send(
+    JSON.stringify({
+      roomId: "room-1",
+      message: {
+        content: "Hello from client 1!",
+      },
+    }),
+  );
+
+  // Wait for message to be received
+  await new Promise((resolve) => setTimeout(resolve, 200));
+
+  // ws2 should receive the message, but not ws1 (exceptSelf)
+  expect(messages.length).toBe(1);
+  expect(messages[0].type).toBe("append");
+  expect(messages[0].content).toBe("Hello from client 1!");
+  expect(messages[0].username).toContain("ws-");
+
+  // Test emit API from server
+  await controller.chat.emit({
+    roomId: "room-1",
+    message: {
+      type: "system",
+      message: "Server announcement",
+    },
+  });
+
+  await new Promise((resolve) => setTimeout(resolve, 200));
+
+  // Both clients should receive the system message
+  expect(messages.length).toBe(2);
+  expect(messages[1].type).toBe("system");
+  expect(messages[1].message).toBe("Server announcement");
+
+  ws1.close();
+  ws2.close();
+  await alepha.stop();
+});
+
+test("$websocket room isolation", async ({ expect }) => {
+  const alepha = Alepha.create().with(AlephaWebSocket);
+
+  class ChatController {
+    chatChannel = $channel({
+      path: "/ws/chat",
+      schema: {
+        in: t.object({
+          type: t.const("message"),
+          content: t.text(),
+        }),
+        out: t.object({
+          content: t.text(),
+        }),
+      },
+    });
+
+    chat = $websocket({
+      channel: this.chatChannel,
+      handler: async ({ roomId, message, reply }) => {
+        await reply({
+          message: {
+            type: "message",
+            content: message.content,
+          },
+        });
+      },
+    });
+  }
+
+  const controller = alepha.inject(ChatController);
+  await alepha.start();
+
+  const httpServer = alepha.inject(NodeHttpServerProvider);
+  const hostname = httpServer.hostname.replace("http://", "ws://");
+
+  // Connect clients to different rooms
+  const room1Client = new WebSocket(`${hostname}/ws/chat?roomId=room-1`);
+  const room2Client = new WebSocket(`${hostname}/ws/chat?roomId=room-2`);
+
+  await Promise.all([
+    new Promise((resolve) => room1Client.on("open", resolve)),
+    new Promise((resolve) => room2Client.on("open", resolve)),
+  ]);
+
+  const room1Messages: any[] = [];
+  const room2Messages: any[] = [];
+
+  room1Client.on("message", (data) => {
+    room1Messages.push(JSON.parse(data.toString()));
+  });
+
+  room2Client.on("message", (data) => {
+    room2Messages.push(JSON.parse(data.toString()));
+  });
+
+  await new Promise((resolve) => setTimeout(resolve, 100));
+
+  // Send to room-1 only
+  await controller.chat.emit({
+    roomId: "room-1",
+    message: {
+      type: "message",
+      content: "Message for room 1",
+    },
+  });
+
+  await new Promise((resolve) => setTimeout(resolve, 200));
+
+  // Only room1Client should receive the message
+  expect(room1Messages.length).toBe(1);
+  expect(room1Messages[0].content).toBe("Message for room 1");
+  expect(room2Messages.length).toBe(0);
+
+  room1Client.close();
+  room2Client.close();
+  await alepha.stop();
+});

package/src/websocket/primitives/$channel.spec.ts

@@ -0,0 +1,30 @@
+import { Alepha, t } from "alepha";
+import { test } from "vitest";
+import { $channel } from "../primitives/$channel.ts";
+
+test("$channel should create a channel primitive", async ({ expect }) => {
+  const alepha = Alepha.create();
+
+  class TestApp {
+    chat = $channel({
+      path: "/ws/chat",
+      description: "Chat channel",
+      schema: {
+        in: t.object({
+          type: t.const("message"),
+          content: t.text(),
+        }),
+        out: t.object({
+          content: t.text(),
+        }),
+      },
+    });
+  }
+
+  const app = alepha.inject(TestApp);
+
+  expect(app.chat).toBeDefined();
+  expect(app.chat.options.path).toBe("/ws/chat");
+  expect(app.chat.options.schema.in).toBeDefined();
+  expect(app.chat.options.schema.out).toBeDefined();
+});

package/src/cli/assets/viteConfigTs.ts

@@ -1,14 +0,0 @@
-export const viteConfigTs = (
-  serverEntry?: string,
-) => `
-import { viteAlepha } from "alepha/vite";
-
-export default {
-  plugins: [
-    viteAlepha(${serverEntry ? `{ serverEntry: "${serverEntry}" }` : ""}),
-  ],
-  test: {
-    globals: true,
-  },
-};
-`.trim();