alepha 0.15.2 → 0.15.4

package/src/email/providers/WorkermailerEmailProvider.ts

@@ -0,0 +1,221 @@
+import { $atom, $env, $use, type Static, t } from "alepha";
+import { $logger } from "alepha/logger";
+import { WorkerMailer } from "worker-mailer";
+import { EmailError } from "../errors/EmailError.ts";
+import type { EmailProvider, EmailSendOptions } from "./EmailProvider.ts";
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+/**
+ * Environment variables for worker-mailer configuration
+ */
+const envSchema = t.object({
+  EMAIL_HOST: t.optional(
+    t.text({
+      description: "SMTP server host",
+    }),
+  ),
+  EMAIL_PORT: t.number({
+    default: 587,
+    description: "SMTP server port (465 or 587, not 25)",
+  }),
+  EMAIL_USER: t.optional(
+    t.text({
+      description: "SMTP authentication username",
+    }),
+  ),
+  EMAIL_PASS: t.optional(
+    t.text({
+      description: "SMTP authentication password",
+    }),
+  ),
+  EMAIL_FROM: t.optional(
+    t.text({
+      description: "Default from email address",
+    }),
+  ),
+  EMAIL_FROM_NAME: t.optional(
+    t.text({
+      description: "Default from name",
+    }),
+  ),
+  EMAIL_SECURE: t.boolean({
+    default: true,
+    description: "Use secure connection (TLS/STARTTLS)",
+  }),
+  EMAIL_AUTH_TYPE: t.optional(
+    t.enum(["plain", "login", "cram-md5"], {
+      default: "plain",
+      description: "SMTP authentication type",
+    }),
+  ),
+});
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+/**
+ * Worker-mailer specific options
+ */
+export const workermailerEmailOptions = $atom({
+  name: "alepha.email.workermailer.options",
+  schema: t.object({
+    authType: t.optional(
+      t.enum(["plain", "login", "cram-md5"], {
+        description: "SMTP authentication type (default: plain)",
+      }),
+    ),
+  }),
+  default: {},
+});
+
+export type WorkermailerEmailProviderOptions = Static<
+  typeof workermailerEmailOptions.schema
+>;
+
+declare module "alepha" {
+  interface State {
+    [workermailerEmailOptions.key]: WorkermailerEmailProviderOptions;
+  }
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+/**
+ * Email provider using worker-mailer for Cloudflare Workers.
+ *
+ * This provider uses Cloudflare's TCP Sockets API to send emails via SMTP,
+ * making it suitable for edge runtime environments.
+ *
+ * Configuration is provided via environment variables:
+ * - EMAIL_HOST: SMTP server host
+ * - EMAIL_PORT: SMTP server port (default: 587, note: port 25 is blocked)
+ * - EMAIL_USER: SMTP authentication username
+ * - EMAIL_PASS: SMTP authentication password
+ * - EMAIL_FROM: Default from email address
+ * - EMAIL_FROM_NAME: Default from name (optional)
+ * - EMAIL_SECURE: Use secure connection (default: true)
+ * - EMAIL_AUTH_TYPE: Authentication type - plain, login, or cram-md5 (default: plain)
+ *
+ * @example
+ * ```typescript
+ * // Configure via environment variables
+ * // EMAIL_HOST=smtp.example.com
+ * // EMAIL_PORT=587
+ * // EMAIL_USER=user@example.com
+ * // EMAIL_PASS=secret
+ * // EMAIL_FROM=noreply@example.com
+ * // EMAIL_FROM_NAME=My App
+ * // EMAIL_SECURE=true
+ * // EMAIL_AUTH_TYPE=plain
+ * ```
+ *
+ * @see https://github.com/zou-yu/worker-mailer
+ */
+export class WorkermailerEmailProvider implements EmailProvider {
+  protected readonly env = $env(envSchema);
+  protected readonly log = $logger();
+  protected readonly options = $use(workermailerEmailOptions);
+
+  protected get host(): string {
+    const host = this.env.EMAIL_HOST;
+    if (!host) {
+      throw new EmailError(
+        "Email host not configured. Set EMAIL_HOST env var.",
+      );
+    }
+    return host;
+  }
+
+  protected get port(): number {
+    return this.env.EMAIL_PORT;
+  }
+
+  protected get secure(): boolean {
+    return this.env.EMAIL_SECURE;
+  }
+
+  protected get user(): string | undefined {
+    return this.env.EMAIL_USER;
+  }
+
+  protected get pass(): string | undefined {
+    return this.env.EMAIL_PASS;
+  }
+
+  protected get fromAddress(): string {
+    const from = this.env.EMAIL_FROM;
+    if (!from) {
+      throw new EmailError(
+        "Email from address not configured. Set EMAIL_FROM env var.",
+      );
+    }
+    return from;
+  }
+
+  protected get fromName(): string | undefined {
+    return this.env.EMAIL_FROM_NAME;
+  }
+
+  protected get authType(): "plain" | "login" | "cram-md5" {
+    return this.options.authType ?? this.env.EMAIL_AUTH_TYPE ?? "plain";
+  }
+
+  public async send(options: EmailSendOptions): Promise<void> {
+    const { to, subject, body } = options;
+    this.log.debug("Sending email via worker-mailer", { to, subject });
+
+    const user = this.user;
+    const pass = this.pass;
+
+    if (!user || !pass) {
+      throw new EmailError(
+        "Email credentials not configured. Set EMAIL_USER and EMAIL_PASS env vars.",
+      );
+    }
+
+    let mailer: WorkerMailer | undefined;
+
+    try {
+      mailer = await WorkerMailer.connect({
+        credentials: {
+          username: user,
+          password: pass,
+        },
+        authType: this.authType,
+        host: this.host,
+        port: this.port,
+        secure: this.secure,
+      });
+
+      const recipients = Array.isArray(to) ? to : [to];
+
+      for (const recipient of recipients) {
+        await mailer.send({
+          from: this.fromName
+            ? { name: this.fromName, email: this.fromAddress }
+            : { email: this.fromAddress },
+          to: { email: recipient },
+          subject,
+          html: body,
+        });
+
+        this.log.info("Email sent successfully", {
+          to: recipient,
+          subject,
+        });
+      }
+    } catch (error) {
+      const message = `Failed to send email via worker-mailer: ${error instanceof Error ? error.message : String(error)}`;
+      this.log.error(message, { to, subject });
+      throw new EmailError(message, error instanceof Error ? error : undefined);
+    } finally {
+      if (mailer) {
+        try {
+          await mailer.close();
+        } catch {
+          // Ignore close errors
+        }
+      }
+    }
+  }
+}

package/src/lock/core/primitives/$lock.ts

@@ -302,7 +302,19 @@ export class LockPrimitive<TFunc extends AsyncFn> extends Primitive<
   protected readonly provider = $inject(LockProvider);
   protected readonly env = $env(envSchema);
   protected readonly dateTimeProvider = $inject(DateTimeProvider);
-  protected readonly id = crypto.randomUUID();
+
+  /**
+   * Lazy-initialized UUID to avoid calling crypto.randomUUID() in global scope.
+   * Cloudflare Workers doesn't allow random value generation during initialization.
+   */
+  protected _id?: string;
+  protected get id(): string {
+    if (!this._id) {
+      this._id = crypto.randomUUID();
+    }
+    return this._id;
+  }
+
   public readonly maxDuration = this.dateTimeProvider.duration(
     this.options.maxDuration ?? [5, "minutes"],
   );

package/src/orm/index.bun.ts

@@ -52,7 +52,7 @@ export const AlephaOrm = $module({
     const url = env.DATABASE_URL;
     const isPostgres = url?.startsWith("postgres:");
 
-    if (url?.startsWith("cloudflare-d1:")) {
+    if (url?.startsWith("d1:")) {
       alepha.with({
         optional: true,
         provide: DatabaseProvider,

package/src/orm/index.ts

@@ -152,14 +152,10 @@ export const AlephaOrm = $module({
     alepha.with(RepositoryProvider);
 
     const url = env.DATABASE_URL;
-    const hasPGlite = !!PglitePostgresProvider.importPglite();
     const isPostgres = url?.startsWith("postgres:");
-    const isSqlite = url?.startsWith("sqlite:");
-    const isMemory = url?.includes(":memory:");
-    const isFile = !!url && !isPostgres && !isMemory;
     const isBun = alepha.isBun();
 
-    if (url?.startsWith("cloudflare-d1:")) {
+    if (url?.startsWith("d1:")) {
       alepha.with({
         optional: true,
         provide: DatabaseProvider,
@@ -168,7 +164,7 @@ export const AlephaOrm = $module({
       return;
     }
 
-    if (hasPGlite && (isMemory || isFile || !url) && !isSqlite) {
+    if (url?.startsWith("pglite:")) {
       alepha.with({
         optional: true,
         provide: DatabaseProvider,

package/src/orm/providers/drivers/BunSqliteProvider.ts

@@ -154,7 +154,10 @@ export class BunSqliteProvider extends DatabaseProvider {
         },
       });
 
-      await this.migrate();
+      // Never migrate in serverless mode - migrations should be applied during deployment
+      if (!this.alepha.isServerless()) {
+        await this.migrate();
+      }
 
       this.log.info(`Using Bun SQLite database at ${filepath}`);
     },

package/src/orm/providers/drivers/CloudflareD1Provider.ts

@@ -64,7 +64,7 @@ export class CloudflareD1Provider extends DatabaseProvider {
   protected readonly env = $env(
     t.object({
       DATABASE_URL: t.string({
-        description: "Expect to be 'cloudflare-d1://name:id'",
+        description: "Expect to be 'd1://name:id'",
       }),
     }),
   );
@@ -104,41 +104,68 @@ export class CloudflareD1Provider extends DatabaseProvider {
   protected readonly onStart = $hook({
     on: "start",
     handler: async () => {
-      const [bindingName] = this.env.DATABASE_URL.replace(
-        "cloudflare-d1://",
-        "",
-      ).split(":");
-      const cloudflareEnv = this.alepha.store.get("cloudflare.env" as any);
-      if (!cloudflareEnv) {
-        throw new AlephaError(
-          "Cloudflare Workers environment not found in Alepha store under 'cloudflare.env'.",
+      try {
+        const [bindingName] = this.env.DATABASE_URL.replace("d1://", "").split(
+          ":",
         );
+        const cloudflareEnv = this.alepha.store.get("cloudflare.env" as any);
+        if (!cloudflareEnv) {
+          throw new AlephaError(
+            "Cloudflare Workers environment not found in Alepha store under 'cloudflare.env'.",
+          );
+        }
+
+        const binding = cloudflareEnv[bindingName] as D1Database;
+        if (!binding) {
+          throw new AlephaError(
+            `D1 binding '${bindingName}' not found in Cloudflare Workers environment.`,
+          );
+        }
+
+        this.d1 = binding;
+
+        // Dynamic import to avoid crashes when not on Cloudflare
+        const { drizzle } = await import("drizzle-orm/d1");
+
+        this.drizzleDb = drizzle(this.d1) as DrizzleD1Database;
+
+        // Never migrate in serverless mode - D1 migrations must be applied
+        // via `wrangler d1 migrations apply` before deployment
+        if (!this.alepha.isServerless()) {
+          await this.migrate();
+        }
+
+        this.log.info("Using Cloudflare D1 database");
+      } catch (error) {
+        // Log the full error for debugging since Cloudflare Workers
+        // doesn't properly display error causes
+        const errorMessage =
+          error instanceof Error
+            ? `${error.message}${error.stack ? `\n${error.stack}` : ""}`
+            : String(error);
+        this.log.error(`D1 initialization failed: ${errorMessage}`);
+        throw error;
       }
-
-      const binding = cloudflareEnv[bindingName] as D1Database;
-      if (!binding) {
-        throw new AlephaError(
-          `D1 binding '${bindingName}' not found in Cloudflare Workers environment.`,
-        );
-      }
-
-      this.d1 = binding;
-
-      // Dynamic import to avoid crashes when not on Cloudflare
-      const { drizzle } = await import("drizzle-orm/d1");
-
-      this.drizzleDb = drizzle(this.d1) as DrizzleD1Database;
-
-      await this.migrate();
-
-      this.log.info("Using Cloudflare D1 database");
     },
   });
 
   protected async executeMigrations(migrationsFolder: string): Promise<void> {
-    // Dynamic import for D1 migrator
-    const { migrate } = await import("drizzle-orm/d1/migrator");
-    await migrate(this.db as any, { migrationsFolder });
+    this.log.debug(`Running D1 migrations from '${migrationsFolder}'...`);
+    try {
+      // Dynamic import for D1 migrator
+      const { migrate } = await import("drizzle-orm/d1/migrator");
+      await migrate(this.db as any, { migrationsFolder });
+      this.log.debug("D1 migrations completed successfully");
+    } catch (error) {
+      const errorMessage =
+        error instanceof Error
+          ? `${error.name}: ${error.message}`
+          : String(error);
+      throw new AlephaError(
+        `D1 migration failed from '${migrationsFolder}': ${errorMessage}`,
+        { cause: error },
+      );
+    }
   }
 
   /**

package/src/orm/providers/drivers/DatabaseProvider.ts

@@ -97,9 +97,17 @@ export abstract class DatabaseProvider {
   }
 
   /**
-   * Base migration orchestration - handles environment logic
+   * Base migration orchestration - handles environment logic.
+   *
+   * Never runs in serverless mode - migrations should be applied during
+   * deployment, not at runtime (to avoid race conditions and timeouts).
    */
   public async migrate(): Promise<void> {
+    // Never migrate in serverless mode - migrations should be applied during deployment
+    if (this.alepha.isServerless()) {
+      return;
+    }
+
     const migrationsFolder = this.getMigrationsFolder();
 
     // Handle different environments

package/src/orm/providers/drivers/NodeSqliteProvider.ts

@@ -157,7 +157,10 @@ export class NodeSqliteProvider extends DatabaseProvider {
 
       this.sqlite = new DatabaseSync(filepath);
 
-      await this.migrate();
+      // Never migrate in serverless mode - migrations should be applied during deployment
+      if (!this.alepha.isServerless()) {
+        await this.migrate();
+      }
 
       this.log.info(`Using SQLite database at ${filepath}`);
     },

package/src/react/auth/services/ReactAuth.ts

@@ -130,6 +130,8 @@ export class ReactAuth {
   }
 
   public logout() {
-    window.location.href = `${alephaServerAuthRoutes.logout}?post_logout_redirect_uri=${encodeURIComponent(window.location.origin)}`;
+    // Add cache-busting parameter to prevent browser from using cached redirect
+    const cacheBuster = Date.now();
+    window.location.href = `${alephaServerAuthRoutes.logout}?post_logout_redirect_uri=${encodeURIComponent(window.location.origin)}&_=${cacheBuster}`;
   }
 }

package/src/react/router/atoms/ssrManifestAtom.ts

@@ -32,6 +32,13 @@ export const ssrManifestAtomSchema = t.object({
       }),
     ),
   ),
+
+  /**
+   * Dev mode head content.
+   * Contains pre-transformed scripts injected by Vite and plugins (React, etc.).
+   * Only set in dev mode via ViteDevServerProvider.
+   */
+  devHead: t.optional(t.string()),
 });
 
 /**

package/src/react/router/hooks/useActive.ts

@@ -36,7 +36,7 @@ export const useActive = (args: string | UseActiveOptions): UseActiveHook => {
 
         setPending(true);
         try {
-          await router.go(href);
+          await router.push(href);
         } finally {
           setPending(false);
         }

package/src/react/router/hooks/useRouter.ts

@@ -13,7 +13,7 @@ import { ReactRouter } from "../services/ReactRouter.ts";
  * }
  *
  * const router = useRouter<App>();
- * router.go("home"); // typesafe
+ * router.push("home"); // typesafe
  */
 export const useRouter = <T extends object = any>(): ReactRouter<T> => {
   return useInject(ReactRouter<T>);

package/src/react/router/index.ts

@@ -11,6 +11,7 @@ import {
   ReactPageProvider,
   type ReactRouterState,
 } from "./providers/ReactPageProvider.ts";
+import { ReactPreloadProvider } from "./providers/ReactPreloadProvider.ts";
 import { ReactServerProvider } from "./providers/ReactServerProvider.ts";
 import { ReactServerTemplateProvider } from "./providers/ReactServerTemplateProvider.ts";
 import { SSRManifestProvider } from "./providers/SSRManifestProvider.ts";
@@ -23,6 +24,7 @@ import { ReactRouter } from "./services/ReactRouter.ts";
 export * from "./index.shared.ts";
 export * from "./providers/ReactBrowserProvider.ts";
 export * from "./providers/ReactPageProvider.ts";
+export * from "./providers/ReactPreloadProvider.ts";
 export * from "./providers/ReactServerProvider.ts";
 export * from "./providers/ReactServerTemplateProvider.ts";
 export * from "./providers/SSRManifestProvider.ts";
@@ -117,6 +119,7 @@ export const AlephaReactRouter = $module({
   services: [
     ReactPageProvider,
     ReactPageService,
+    ReactPreloadProvider,
     ReactRouter,
     ReactServerProvider,
     ReactServerTemplateProvider,
@@ -136,6 +139,7 @@ export const AlephaReactRouter = $module({
       })
       .with(SSRManifestProvider)
       .with(ReactServerTemplateProvider)
+      .with(ReactPreloadProvider)
       .with(ReactServerProvider)
       .with(ReactPageProvider)
       .with(ReactRouter),