alepha 0.15.1 → 0.15.3

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/orm/services/Repository.ts

@@ -616,7 +616,7 @@ export abstract class Repository<T extends TObject> {
    */
   public async updateOne(
     where: PgQueryWhereOrSQL<T>,
-    data: Partial<Static<TObjectUpdate<T>>>,
+    data: WithSQL<Static<TObjectUpdate<T>>>,
     opts: StatementOptions = {},
   ): Promise<Static<T>> {
     await this.alepha.events.emit("repository:update:before", {
@@ -767,7 +767,7 @@ export abstract class Repository<T extends TObject> {
    */
   public async updateById(
     id: string | number,
-    data: Partial<Static<TObjectUpdate<T>>>,
+    data: WithSQL<Static<TObjectUpdate<T>>>,
     opts: StatementOptions = {},
   ): Promise<Static<T>> {
     return await this.updateOne(this.getWhereId(id), data, opts);
@@ -778,7 +778,7 @@ export abstract class Repository<T extends TObject> {
    */
   public async updateMany(
     where: PgQueryWhereOrSQL<T>,
-    data: Partial<Static<TObjectUpdate<T>>>,
+    data: WithSQL<Static<TObjectUpdate<T>>>,
     opts: StatementOptions = {},
   ): Promise<Array<number | string>> {
     await this.alepha.events.emit("repository:update:before", {
@@ -1177,3 +1177,7 @@ export interface StatementOptions {
    */
   now?: DateTime | string;
 }
+
+type WithSQL<T> = {
+  [P in keyof T]?: T[P] | SQL;
+};

package/src/queue/core/index.ts

@@ -16,14 +16,22 @@ export * from "./providers/WorkerProvider.ts";
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * Provides asynchronous message queuing and processing capabilities through declarative queue descriptors.
+ * | type | quality | stability |
+ * |------|---------|-----------|
+ * | backend | epic | stable |
  *
- * The queue module enables reliable background job processing and message passing using the `$queue` descriptor
- * on class properties. It supports schema validation, automatic retries, and multiple queue backends for
- * building scalable, decoupled applications with robust error handling.
+ * Asynchronous message processing with automatic worker management.
+ *
+ * **Features:**
+ * - Background job queues with type-safe payloads
+ * - Queue consumer handlers
+ * - Automatic worker threads for non-blocking processing
+ * - Retry mechanisms with exponential backoff
+ * - Dead letter queues for failed messages
+ * - Batch processing support
+ * - Configurable concurrency and worker pools
+ * - Providers: Memory (dev), Redis (production)
  *
- * @see {@link $queue}
- * @see {@link $consumer}
  * @module alepha.queue
  */
 export const AlephaQueue = $module({

package/src/react/auth/__tests__/$auth.spec.ts

@@ -0,0 +1,202 @@
+import { randomUUID } from "node:crypto";
+import { Alepha } from "alepha";
+import { DateTimeProvider } from "alepha/datetime";
+import { $issuer, AlephaSecurity } from "alepha/security";
+import { AlephaServer, HttpClient, ServerProvider } from "alepha/server";
+import {
+  $auth,
+  alephaServerAuthRoutes,
+  type TokenResponse,
+  tokenResponseSchema,
+  tokensSchema,
+} from "alepha/server/auth";
+import { $client } from "alepha/server/links";
+import { describe, test } from "vitest";
+import { ReactAuth, type ReactAuthProvider } from "../index.ts";
+
+describe("$auth", () => {
+  const user = {
+    id: randomUUID(),
+    name: "John Doe",
+    username: "john",
+    password: "***",
+    roles: ["admin"],
+  };
+
+  class App {
+    issuer = $issuer({
+      secret: "my-secret-key",
+      roles: [
+        {
+          name: "admin",
+          permissions: [{ name: "*" }],
+        },
+      ],
+    });
+
+    auth = $auth({
+      issuer: this.issuer,
+      credentials: {
+        account: () => user,
+      },
+    });
+
+    api = $client<ReactAuthProvider>();
+  }
+
+  const userinfo = (alepha: Alepha, token?: string) =>
+    alepha
+      .inject(HttpClient)
+      .fetch(
+        `${alepha.inject(ServerProvider).hostname}${alephaServerAuthRoutes.userinfo}`,
+        {
+          method: "GET",
+          headers: {
+            authorization: `Bearer ${token}`,
+          },
+        },
+      )
+      .then((it) => it.data);
+
+  const login = (alepha: Alepha) =>
+    alepha
+      .inject(HttpClient)
+      .fetch(
+        `${alepha.inject(ServerProvider).hostname}${alephaServerAuthRoutes.token}?provider=auth`,
+        {
+          method: "POST",
+          body: JSON.stringify({
+            username: user.username,
+            password: user.password,
+          }),
+          schema: {
+            response: tokenResponseSchema,
+          },
+        },
+      );
+
+  const refresh = (alepha: Alepha, tokens: TokenResponse) =>
+    alepha
+      .inject(HttpClient)
+      .fetch(
+        `${alepha.inject(ServerProvider).hostname}${alephaServerAuthRoutes.refresh}?provider=auth`,
+        {
+          method: "POST",
+          body: JSON.stringify({
+            refresh_token: tokens.refresh_token!,
+            access_token: tokens.access_token,
+          }),
+          schema: {
+            response: tokensSchema,
+          },
+        },
+      );
+
+  test("should login with credentials", async ({ expect }) => {
+    const alepha = Alepha.create()
+      .with(AlephaServer)
+      .with(AlephaSecurity)
+      .with(App);
+    const auth = alepha.inject(ReactAuth);
+    await alepha.start();
+
+    expect(auth.user).toBeUndefined();
+    await auth.login("auth", {
+      username: user.username,
+      password: user.password,
+      hostname: alepha.inject(ServerProvider).hostname,
+    });
+    expect(auth.user).toEqual({
+      id: user.id,
+      name: user.name,
+      roles: user.roles,
+      username: user.username,
+    });
+  });
+
+  test("should get userinfo", async ({ expect }) => {
+    const alepha = Alepha.create()
+      .with(AlephaServer)
+      .with(AlephaSecurity)
+      .with(App);
+    await alepha.start();
+
+    const { data: tokens } = await login(alepha);
+
+    expect(await userinfo(alepha, tokens.access_token)).toEqual({
+      user: {
+        id: user.id,
+        name: user.name,
+        roles: user.roles,
+        username: user.username,
+        sessionId: expect.any(String),
+      },
+      api: {
+        prefix: "/api",
+        links: [],
+      },
+    });
+  });
+
+  test("should reject expired token", async ({ expect }) => {
+    const alepha = Alepha.create()
+      .with(AlephaServer)
+      .with(AlephaSecurity)
+      .with(App);
+    await alepha.start();
+
+    const { data: tokens } = await login(alepha);
+
+    await alepha.inject(DateTimeProvider).travel(1, "hour");
+
+    expect(await userinfo(alepha, tokens.access_token)).toEqual({
+      api: {
+        prefix: "/api",
+        links: [],
+      },
+    });
+  });
+
+  test("should refresh expired token", async ({ expect }) => {
+    const alepha = Alepha.create()
+      .with(AlephaServer)
+      .with(AlephaSecurity)
+      .with(App);
+    await alepha.start();
+
+    const { data: tokens } = await login(alepha);
+
+    await alepha.inject(DateTimeProvider).travel(1, "hour");
+
+    const { data: tokens2 } = await refresh(alepha, tokens);
+
+    expect(await userinfo(alepha, tokens2.access_token)).toEqual({
+      user: {
+        id: user.id,
+        name: user.name,
+        roles: user.roles,
+        username: user.username,
+      },
+      api: {
+        prefix: "/api",
+        links: [],
+      },
+    });
+  });
+
+  test("should reject expired refresh token", async ({ expect }) => {
+    const alepha = Alepha.create()
+      .with(AlephaServer)
+      .with(AlephaSecurity)
+      .with(App);
+    await alepha.start();
+
+    const { data: tokens } = await login(alepha);
+
+    await alepha.inject(DateTimeProvider).travel(40, "days");
+
+    await expect(refresh(alepha, tokens)).rejects.toThrowError(
+      "Failed to refresh access token using the refresh token (issuer)",
+    );
+  });
+});

package/src/react/auth/hooks/useAuth.ts

@@ -0,0 +1,32 @@
+import { useAlepha, useStore } from "alepha/react";
+import { type HttpVirtualClient, LinkProvider } from "alepha/server/links";
+import { ReactAuth } from "../services/ReactAuth.ts";
+
+export const useAuth = <T extends object = any>() => {
+  const alepha = useAlepha();
+  const [user] = useStore("alepha.server.request.user");
+
+  return {
+    user,
+    logout: () => {
+      alepha.inject(ReactAuth).logout();
+    },
+    login: async (
+      provider: keyof T,
+      options: {
+        username?: string;
+        password?: string;
+        redirect?: string;
+        realm?: string;
+        [extra: string]: any;
+      } = {},
+    ) => {
+      await alepha.inject(ReactAuth).login(provider as string, options);
+    },
+    can: <Api extends object = any>(
+      name: keyof HttpVirtualClient<Api>,
+    ): boolean => {
+      return alepha.inject(LinkProvider).can(name as string);
+    },
+  };
+};

package/src/react/auth/index.browser.ts

@@ -0,0 +1,13 @@
+import { $module } from "alepha";
+import { ReactAuth } from "./services/ReactAuth.ts";
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+export * from "./index.shared.ts";
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+export const AlephaReactAuth = $module({
+  name: "alepha.react.auth",
+  services: [ReactAuth],
+});

package/src/react/auth/index.shared.ts

@@ -0,0 +1,2 @@
+export * from "./hooks/useAuth.ts";
+export * from "./services/ReactAuth.ts";

package/src/react/auth/index.ts

@@ -0,0 +1,48 @@
+import { $module } from "alepha";
+import { AlephaReact } from "alepha/react";
+import type { UserAccount } from "alepha/security";
+import { $auth, AlephaServerAuth } from "alepha/server/auth";
+import { AlephaServerLinks } from "alepha/server/links";
+import { ReactAuthProvider } from "./providers/ReactAuthProvider.ts";
+import { ReactAuth } from "./services/ReactAuth.ts";
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+export * from "./index.shared.ts";
+export * from "./providers/ReactAuthProvider.ts";
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+declare module "alepha/react/router" {
+  interface ReactRouterState {
+    user?: UserAccount;
+  }
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+/**
+ * | type | quality | stability |
+ * |------|---------|-----------|
+ * | frontend | rare | stable |
+ *
+ * Auth-related React components and hooks.
+ *
+ * **Features:**
+ * - Login/logout components
+ * - Protected route wrappers
+ * - Auth state hooks
+ *
+ * @module alepha.react.auth
+ */
+export const AlephaReactAuth = $module({
+  name: "alepha.react.auth",
+  primitives: [$auth],
+  services: [
+    AlephaReact,
+    AlephaServerLinks,
+    AlephaServerAuth,
+    ReactAuthProvider,
+    ReactAuth,
+  ],
+});

package/src/react/auth/providers/ReactAuthProvider.ts

@@ -0,0 +1,16 @@
+import { $hook, $inject, Alepha } from "alepha";
+
+export class ReactAuthProvider {
+  protected readonly alepha = $inject(Alepha);
+
+  public readonly onRender = $hook({
+    on: "react:server:render:begin",
+    handler: async ({ request, state }) => {
+      if (request?.user) {
+        const { token, realm, ...user } = request.user; // do not send token and realm to the client
+        this.alepha.store.set("alepha.server.request.user", user); // for hydration, browser, etc...
+        state.user = user;
+      }
+    },
+  });
+}

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

@@ -0,0 +1,135 @@
+import { $hook, $inject, Alepha } from "alepha";
+import { $logger } from "alepha/logger";
+import { ReactBrowserProvider, Redirection } from "alepha/react/router";
+import type { UserAccountToken } from "alepha/security";
+import { HttpClient } from "alepha/server";
+import {
+  alephaServerAuthRoutes,
+  type Tokens,
+  tokenResponseSchema,
+  userinfoResponseSchema,
+} from "alepha/server/auth";
+import { LinkProvider } from "alepha/server/links";
+
+/**
+ * Browser, SSR friendly, service to handle authentication.
+ */
+export class ReactAuth {
+  protected readonly log = $logger();
+  protected readonly alepha = $inject(Alepha);
+  protected readonly httpClient = $inject(HttpClient);
+  protected readonly linkProvider = $inject(LinkProvider);
+
+  protected readonly onBeginTransition = $hook({
+    on: "react:transition:begin",
+    handler: async (event) => {
+      if (this.alepha.isBrowser()) {
+        Object.defineProperty(event.state, "user", {
+          get: () => this.user,
+        });
+      }
+    },
+  });
+
+  protected readonly onFetchRequest = $hook({
+    on: "client:onRequest",
+    handler: async ({ request }) => {
+      if (this.alepha.isBrowser() && this.user) {
+        // ensure cookies are sent with requests and refresh-able
+        request.credentials ??= "include";
+      }
+    },
+  });
+
+  /**
+   * Get the current authenticated user.
+   *
+   * Alias for `alepha.state.get("user")`
+   */
+  public get user(): UserAccountToken | undefined {
+    return this.alepha.store.get("alepha.server.request.user");
+  }
+
+  public async ping() {
+    const { data } = await this.httpClient.fetch(
+      alephaServerAuthRoutes.userinfo,
+      {
+        schema: { response: userinfoResponseSchema },
+      },
+    );
+
+    this.alepha.store.set("alepha.server.request.apiLinks", data.api);
+    this.alepha.store.set("alepha.server.request.user", data.user);
+
+    return data.user;
+  }
+
+  public can(action: string): boolean {
+    if (!this.user) {
+      return false;
+    }
+
+    return this.linkProvider.can(action);
+  }
+
+  public async login(
+    provider: string,
+    options: {
+      hostname?: string;
+      username?: string;
+      password?: string;
+      redirect?: string;
+      realm?: string;
+      [extra: string]: any;
+    },
+  ): Promise<Tokens> {
+    const realmParam = options.realm
+      ? `&realm=${encodeURIComponent(options.realm)}`
+      : "";
+
+    if (options.username || options.password) {
+      const { data } = await this.httpClient.fetch(
+        `${options.hostname || ""}${alephaServerAuthRoutes.token}?provider=${provider}${realmParam}`,
+        {
+          method: "POST",
+          body: JSON.stringify({
+            username: options.username,
+            password: options.password,
+          }),
+          schema: { response: tokenResponseSchema },
+        },
+      );
+
+      this.alepha.store.set("alepha.server.request.apiLinks", data.api);
+      this.alepha.store.set("alepha.server.request.user", data.user);
+
+      return data;
+    }
+
+    if (this.alepha.isBrowser()) {
+      const browser = this.alepha.inject(ReactBrowserProvider);
+      const redirect =
+        options.redirect ||
+        (browser.transitioning
+          ? window.location.origin + browser.transitioning.to
+          : window.location.href);
+
+      const href = `${window.location.origin}${alephaServerAuthRoutes.login}?provider=${provider}${realmParam}&redirect_uri=${encodeURIComponent(redirect)}`;
+
+      if (browser.transitioning) {
+        throw new Redirection(href);
+      } else {
+        window.location.href = href;
+        return {} as Tokens;
+      }
+    }
+
+    throw new Redirection(
+      `${alephaServerAuthRoutes.login}?provider=${provider}${realmParam}&redirect_uri=${options.redirect || "/"}`,
+    );
+  }
+
+  public logout() {
+    window.location.href = `${alephaServerAuthRoutes.logout}?post_logout_redirect_uri=${encodeURIComponent(window.location.origin)}`;
+  }
+}