alepha 0.21.2 → 0.23.0

package/src/orm/core/interfaces/PgQuery.ts

@@ -67,9 +67,12 @@ export type PgRelation<Base extends TObject> = {
     schema: TObject;
     name: string;
   };
+  // `readonly` so a literal tuple written with `as const` (the natural
+  // shape for `["userId", users.cols.id]`) satisfies the type without an
+  // explicit cast. The relation manager only reads the indices.
   on:
     | SQLWrapper
-    | [
+    | readonly [
         keyof Static<Base>,
         {
           name: string;

package/src/orm/core/services/Repository.ts

@@ -597,27 +597,43 @@ export abstract class Repository<T extends TObject> {
 
   /**
    * Find an entity by ID. Returns `undefined` if not found.
+   *
+   * Pass `with` to eager-load relations on the result — same `with` map
+   * shape as `findOne` / `paginate`. Without `with`, returns the plain
+   * row.
+   *
+   * @example
+   * ```ts
+   * const session = await sessions.findById(id, {
+   *   with: { user: { join: users, on: ["userId", users.cols.id] as const } },
+   * });
+   * session?.user?.email;
+   * ```
    */
-  public async findById(
+  public async findById<R extends PgRelationMap<T>>(
     id: string | number,
-    opts: StatementOptions = {},
-  ): Promise<Static<T> | undefined> {
-    return await this.findOne(
+    opts: StatementOptions & { with?: R } = {},
+  ): Promise<PgStatic<T, R> | undefined> {
+    const { with: withRelations, ...rest } = opts;
+    return (await this.findOne<R>(
       {
         where: this.getWhereId(id),
-      },
-      opts,
-    );
+        ...(withRelations ? { with: withRelations } : {}),
+      } as Pick<PgQueryRelations<T, R>, "with" | "where">,
+      rest,
+    )) as PgStatic<T, R> | undefined;
   }
 
   /**
    * Find an entity by ID. Throws `DbEntityNotFoundError` if not found.
+   *
+   * Pass `with` to eager-load relations — see {@link findById}.
    */
-  public async getById(
+  public async getById<R extends PgRelationMap<T>>(
     id: string | number,
-    opts: StatementOptions = {},
-  ): Promise<Static<T>> {
-    const entity = await this.findById(id, opts);
+    opts: StatementOptions & { with?: R } = {},
+  ): Promise<PgStatic<T, R>> {
+    const entity = await this.findById<R>(id, opts);
 
     if (!entity) {
       throw new DbEntityNotFoundError(this.tableName);

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

@@ -1,6 +1,6 @@
 import { useAlepha, useStore } from "alepha/react";
 import { currentUserAtom } from "alepha/security";
-import { type HttpVirtualClient, LinkProvider } from "alepha/server/links";
+import { LinkProvider } from "alepha/server/links";
 import { ReactAuth } from "../services/ReactAuth.ts";
 
 export const useAuth = <T extends object = any>() => {
@@ -24,10 +24,15 @@ export const useAuth = <T extends object = 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);
+    /**
+     * UI permission check — does the current user hold this permission?
+     * Supports exact and wildcard names (e.g. `"admin:*"`, `"admin:user:read"`).
+     *
+     * UI affordance only (show/hide/disable). Real access control is enforced
+     * server-side via `$secure` on the route/action.
+     */
+    has: (permission: string): boolean => {
+      return alepha.inject(LinkProvider).can(permission);
     },
   };
 };

package/src/react/core/__tests__/useQuery.browser.spec.tsx

@@ -41,6 +41,31 @@ describe("useQuery", () => {
     expect(handler).toHaveBeenCalledTimes(2);
   });
 
+  test("reports loading on the first render, before the fetch settles", async ({
+    expect,
+  }) => {
+    const alepha = Alepha.create().with(AlephaDateTime);
+    await alepha.start();
+
+    const handler = vi.fn(async () => "value");
+
+    const wrapper = ({ children }: { children: React.ReactNode }) => (
+      <AlephaContext.Provider value={alepha}>{children}</AlephaContext.Provider>
+    );
+
+    const { result } = renderHook(() => useQuery({ handler }, []), { wrapper });
+
+    // No data yet, but loading must already be true so callers can render a
+    // skeleton instead of an empty/not-found flash.
+    expect(result.current.data).toBe(undefined);
+    expect(result.current.loading).toBe(true);
+
+    await waitFor(() => {
+      expect(result.current.data).toBe("value");
+    });
+    expect(result.current.loading).toBe(false);
+  });
+
   test("does not run when enabled is false", async ({ expect }) => {
     const alepha = Alepha.create().with(AlephaDateTime);
     await alepha.start();

package/src/react/core/hooks/useAction.ts

@@ -158,6 +158,15 @@ export function useAction<Args extends any[], Result = void>(
         abortControllerRef.current.abort();
         abortControllerRef.current = undefined;
       }
+
+      // Release the concurrency guard: we've just abandoned the in-flight run
+      // (its result is discarded by the aborted-signal check), so the *next*
+      // lifecycle must be free to start. Without this, a remount that reuses
+      // the same refs — React StrictMode's double-invoke, or a Suspense/router
+      // remount on client-side navigation — would hit `if (isExecutingRef
+      // .current) return` and never re-run, leaving a `useQuery` stuck on its
+      // loading skeleton forever (the original request 200s but is dropped).
+      isExecutingRef.current = false;
     };
   }, []);
 
@@ -230,10 +239,12 @@ export function useAction<Args extends any[], Result = void>(
 
         if (options.onError) {
           await options.onError(error);
-        } else {
-          // Re-throw if no custom error handler
-          throw error;
         }
+        // Without a custom `onError`, the error is NOT re-thrown: it is captured
+        // in `error` state and emitted as `react:action:error` (a mounted
+        // <ActionErrorToaster /> surfaces it as a toast). This keeps
+        // fire-and-forget `action.run()` calls from producing unhandled
+        // promise rejections.
       } finally {
         isExecutingRef.current = false;
         if (isMountedRef.current) {

package/src/react/core/hooks/useQuery.ts

@@ -1,6 +1,6 @@
 import type { Async } from "alepha";
 import type { DurationLike } from "alepha/datetime";
-import { type DependencyList, useCallback, useState } from "react";
+import { type DependencyList, useCallback, useRef, useState } from "react";
 import type { ActionContext } from "./useAction.ts";
 import { useAction } from "./useAction.ts";
 
@@ -47,17 +47,23 @@ export function useQuery<Result>(
   options: UseQueryOptions<Result>,
   deps: DependencyList,
 ): UseQueryReturn<Result> {
+  const enabled = options.enabled !== false;
   const [data, setData] = useState<Result | undefined>(options.initialData);
+  // Tracks whether the auto-run has completed at least once, so we can keep
+  // `loading` true on the very first render — before `runOnInit`'s effect
+  // fires — instead of briefly reporting `loading: false` with no data.
+  const settledRef = useRef(false);
 
   const action = useAction<[], Result>(
     {
       id: options.id,
       handler: options.handler,
-      runOnInit: options.enabled !== false,
+      runOnInit: enabled,
       runEvery: options.runEvery,
       debounce: options.debounce,
       onError: options.onError,
       onSuccess: async (result) => {
+        settledRef.current = true;
         setData(result);
         if (options.onSuccess) {
           await options.onSuccess(result);
@@ -69,9 +75,21 @@ export function useQuery<Result>(
 
   const refetch = useCallback(() => action.run(), [action.run]);
 
+  // `loading` is true while a fetch is in flight, AND during the initial gap
+  // between first render and the auto-run effect — so consumers can render a
+  // skeleton immediately instead of flashing an empty/not-found state. Only
+  // applies to enabled queries with no `initialData` seed; an error settles
+  // it (the error path keeps the caller's `onError` re-throw semantics).
+  const loading =
+    action.loading ||
+    (enabled &&
+      options.initialData === undefined &&
+      !settledRef.current &&
+      action.error === undefined);
+
   return {
     data,
-    loading: action.loading,
+    loading,
     error: action.error,
     refetch,
     cancel: action.cancel,
@@ -132,7 +150,9 @@ export interface UseQueryReturn<Result> {
   data: Result | undefined;
 
   /**
-   * Loading state — `true` while a fetch is in flight.
+   * Loading state — `true` while a fetch is in flight, and also from the
+   * first render until the initial auto-run settles (for enabled queries
+   * with no `initialData`), so a skeleton can render without a flash.
    */
   loading: boolean;
 

package/src/react/form/__tests__/FormModel-submit-loading.spec.ts

@@ -0,0 +1,71 @@
+import { Alepha, t } from "alepha";
+import { AlephaLogger } from "alepha/logger";
+import { describe, it } from "vitest";
+import { FormModel } from "../services/FormModel.ts";
+
+/**
+ * Repro for: a form whose submit fails TypeBox validation (missing field)
+ * leaves the submit button stuck in its loading state forever.
+ *
+ * The button's loading is driven by the `form:submit:begin` / `form:submit:end`
+ * event pair (see useFormState). So the invariant that matters is: every
+ * `form:submit:begin` is followed by a `form:submit:end`, even when validation
+ * throws AND even when a downstream error listener (e.g. the action-error
+ * toaster) itself throws.
+ */
+describe("FormModel.submit loading pairing", () => {
+  const makeForm = (alepha: Alepha) =>
+    alepha.inject(FormModel as any, {
+      lifetime: "transient",
+      args: [
+        "f1",
+        {
+          id: "f1",
+          schema: t.object({ email: t.text(), password: t.text() }),
+          handler: () => {},
+          initialValues: {}, // both required fields missing → decode throws
+        },
+      ],
+    }) as FormModel<any>;
+
+  it("emits form:submit:end on a validation error (intrinsic)", async ({
+    expect,
+  }) => {
+    const alepha = Alepha.create().with(AlephaLogger);
+    await alepha.start();
+    const form = makeForm(alepha);
+    let begun = false;
+    let ended = false;
+    alepha.events.on("form:submit:begin", () => {
+      begun = true;
+    });
+    alepha.events.on("form:submit:end", () => {
+      ended = true;
+    });
+
+    await form.submit().catch(() => {});
+
+    expect(begun).toBe(true);
+    expect(ended).toBe(true); // pairing must hold
+  });
+
+  it("emits form:submit:end even when a react:action:error listener throws", async ({
+    expect,
+  }) => {
+    const alepha = Alepha.create().with(AlephaLogger);
+    await alepha.start();
+    const form = makeForm(alepha);
+    let ended = false;
+    alepha.events.on("form:submit:end", () => {
+      ended = true;
+    });
+    // Simulates a globally-mounted listener (e.g. ActionErrorToaster) throwing.
+    alepha.events.on("react:action:error", () => {
+      throw new Error("toaster boom");
+    });
+
+    await form.submit().catch(() => {});
+
+    expect(ended).toBe(true); // currently FAILS: end is skipped → button stuck
+  });
+});

package/src/react/form/__tests__/form-submitting-reactive.browser.spec.tsx

@@ -0,0 +1,96 @@
+import { fireEvent, render, waitFor } from "@testing-library/react";
+import { Alepha, t } from "alepha";
+import { AlephaLogger } from "alepha/logger";
+import { AlephaContext } from "alepha/react";
+import { describe, it } from "vitest";
+import { useForm, useFormState } from "../index.ts";
+
+/**
+ * Submit buttons bind their loading state to `useFormState(form, ["loading"])`
+ * (the reactive form-state API; the non-reactive `form.submitting` getter was
+ * removed). This loading must:
+ *  - turn ON while an async submit is in flight, and
+ *  - turn OFF again afterwards — including after a TypeBox validation error.
+ *
+ * The OFF guarantee relies on `FormModel.submit` always emitting
+ * `form:submit:end` (see FormModel-submit-loading.spec.ts).
+ */
+describe("useFormState loading drives the submit button", () => {
+  const mount = (alepha: Alepha, ui: React.ReactNode) =>
+    render(
+      <AlephaContext.Provider value={alepha}>{ui}</AlephaContext.Provider>,
+    );
+
+  it("turns loading on during an async submit and off after", async ({
+    expect,
+  }) => {
+    const alepha = Alepha.create().with(AlephaLogger);
+    let release!: () => void;
+
+    const Form = () => {
+      const form = useForm({
+        id: "async",
+        schema: t.object({ name: t.string({ minLength: 1 }) }),
+        initialValues: { name: "ok" },
+        handler: () => new Promise<void>((r) => (release = r)),
+      });
+      const { loading } = useFormState(form, ["loading"]);
+      return (
+        <form {...form.props} data-testid="form">
+          <button
+            type="submit"
+            data-testid="submit"
+            data-loading={loading ? "true" : "false"}
+          >
+            go
+          </button>
+        </form>
+      );
+    };
+
+    const { getByTestId } = mount(alepha, <Form />);
+    fireEvent.submit(getByTestId("form"));
+
+    await waitFor(() =>
+      expect(getByTestId("submit").getAttribute("data-loading")).toBe("true"),
+    );
+    release();
+    await waitFor(() =>
+      expect(getByTestId("submit").getAttribute("data-loading")).toBe("false"),
+    );
+  });
+
+  it("clears loading after a TypeBox validation error", async ({ expect }) => {
+    const alepha = Alepha.create().with(AlephaLogger);
+
+    const Form = () => {
+      const form = useForm({
+        id: "login",
+        schema: t.object({
+          identifier: t.string({ minLength: 1 }),
+          password: t.string({ minLength: 6 }),
+        }),
+        handler: async () => {},
+      });
+      const { loading } = useFormState(form, ["loading"]);
+      return (
+        <form {...form.props} data-testid="form">
+          <button
+            type="submit"
+            data-testid="submit"
+            data-loading={loading ? "true" : "false"}
+          >
+            Sign in
+          </button>
+        </form>
+      );
+    };
+
+    const { getByTestId } = mount(alepha, <Form />);
+    fireEvent.submit(getByTestId("form")); // empty → validation error
+
+    await waitFor(() =>
+      expect(getByTestId("submit").getAttribute("data-loading")).toBe("false"),
+    );
+  });
+});

package/src/react/form/services/FormModel.ts

@@ -27,10 +27,6 @@ export class FormModel<T extends TObject> {
 
   public input: SchemaToInput<T>;
 
-  public get submitting(): boolean {
-    return this.submitInProgress;
-  }
-
   constructor(
     public readonly id: string,
     public readonly options: FormCtrlOptions<T>,
@@ -185,14 +181,22 @@ export class FormModel<T extends TObject> {
       return;
     }
 
-    // emit both action and form events
-    await this.alepha.events.emit("react:action:begin", {
-      type: "form",
-      id: this.id,
-    });
-    await this.alepha.events.emit("form:submit:begin", {
-      id: this.id,
-    });
+    // Lifecycle events are best-effort NOTIFICATIONS (loading spinners, toasts,
+    // analytics). A misbehaving listener must never break form state or reject
+    // submit() — hence `{ catch: true }` on every emit below. Without it, a
+    // throwing `react:action:error`/`form:submit:error` listener would skip the
+    // `form:submit:end` "loading off" signal and leave submit buttons stuck in
+    // their loading state forever.
+    await this.alepha.events.emit(
+      "react:action:begin",
+      { type: "form", id: this.id },
+      { catch: true },
+    );
+    await this.alepha.events.emit(
+      "form:submit:begin",
+      { id: this.id },
+      { catch: true },
+    );
 
     this.submitInProgress = true;
 
@@ -210,39 +214,53 @@ export class FormModel<T extends TObject> {
 
       await options.handler(values as any);
 
-      await this.alepha.events.emit("react:action:success", {
-        type: "form",
-        id: this.id,
-      });
-      await this.alepha.events.emit("form:submit:success", {
-        id: this.id,
-        values,
-      });
+      await this.alepha.events.emit(
+        "react:action:success",
+        { type: "form", id: this.id },
+        { catch: true },
+      );
+      await this.alepha.events.emit(
+        "form:submit:success",
+        { id: this.id, values },
+        { catch: true },
+      );
     } catch (error) {
       this.log.error("Form submission error:", error);
 
-      options.onError?.(error as Error);
-
-      await this.alepha.events.emit("react:action:error", {
-        type: "form",
-        id: this.id,
-        error: error as Error,
-      });
-      await this.alepha.events.emit("form:submit:error", {
-        error: error as Error,
-        id: this.id,
-      });
+      // A throwing onError callback must not abort the lifecycle either.
+      try {
+        options.onError?.(error as Error);
+      } catch (handlerError) {
+        this.log.error("Form onError handler threw:", handlerError);
+      }
+
+      await this.alepha.events.emit(
+        "react:action:error",
+        { type: "form", id: this.id, error: error as Error },
+        { catch: true },
+      );
+      await this.alepha.events.emit(
+        "form:submit:error",
+        { error: error as Error, id: this.id },
+        { catch: true },
+      );
     } finally {
       this.submitInProgress = false;
-    }
 
-    await this.alepha.events.emit("react:action:end", {
-      type: "form",
-      id: this.id,
-    });
-    await this.alepha.events.emit("form:submit:end", {
-      id: this.id,
-    });
+      // The "loading off" signals live in `finally` so they ALWAYS fire,
+      // even if something above threw — guaranteeing the begin/end pairing
+      // that drives submit-button loading state.
+      await this.alepha.events.emit(
+        "react:action:end",
+        { type: "form", id: this.id },
+        { catch: true },
+      );
+      await this.alepha.events.emit(
+        "form:submit:end",
+        { id: this.id },
+        { catch: true },
+      );
+    }
   };
 
   /**

package/src/react/i18n/__tests__/I18nProvider.spec.ts

@@ -449,6 +449,95 @@ describe("I18nProvider", () => {
     });
   });
 
+  describe("server-side language autodetect (Accept-Language)", () => {
+    /**
+     * Injects a real, dictionary-populated `I18nProvider` and exposes the
+     * protected resolution used by the `server:onRequest` hook, so the priority
+     * (cookie → header → fallback) can be unit-tested against a true registry.
+     */
+    const setup = (AppClass: new () => unknown) => {
+      const alepha = Alepha.create().with(AlephaReactI18n);
+      alepha.inject(AppClass as any);
+      const i18n = alepha.inject(I18nProvider);
+      return {
+        i18n,
+        resolve: (cookieLang?: string, headerLang?: string): string =>
+          (i18n as any).resolveRequestLang(cookieLang, headerLang),
+      };
+    };
+
+    class App {
+      en = $dictionary({
+        lazy: async () => ({ default: { hello: "Hello" } }),
+      });
+
+      fr = $dictionary({
+        lazy: async () => ({ default: { hello: "Bonjour" } }),
+      });
+    }
+
+    test("uses the Accept-Language header when no cookie is set", ({
+      expect,
+    }) => {
+      expect(setup(App).resolve(undefined, "fr")).toBe("fr");
+    });
+
+    test("lets a manually-selected cookie win over the header", ({
+      expect,
+    }) => {
+      expect(setup(App).resolve("en", "fr")).toBe("en");
+    });
+
+    test("falls back when the header language is not registered", ({
+      expect,
+    }) => {
+      expect(setup(App).resolve(undefined, "de")).toBe("en");
+    });
+
+    test("falls back when neither cookie nor header is present", ({
+      expect,
+    }) => {
+      expect(setup(App).resolve(undefined, undefined)).toBe("en");
+    });
+
+    test("normalizes a region-qualified header to a registered base language", ({
+      expect,
+    }) => {
+      expect(setup(App).resolve(undefined, "fr-FR")).toBe("fr");
+    });
+
+    test("prefers an exact region match when one is registered", ({
+      expect,
+    }) => {
+      class RegionApp {
+        enUS = $dictionary({
+          lang: "en-US",
+          lazy: async () => ({ default: { color: "color" } }),
+        });
+
+        fr = $dictionary({
+          lazy: async () => ({ default: { color: "couleur" } }),
+        });
+      }
+
+      expect(setup(RegionApp).resolve(undefined, "en-US")).toBe("en-US");
+    });
+
+    test("ignores the header when autoDetect is disabled", ({ expect }) => {
+      const { i18n, resolve } = setup(App);
+      i18n.options.autoDetect = false;
+      expect(resolve(undefined, "fr")).toBe("en");
+    });
+
+    test("still honours a manual cookie when autoDetect is disabled", ({
+      expect,
+    }) => {
+      const { i18n, resolve } = setup(App);
+      i18n.options.autoDetect = false;
+      expect(resolve("fr", "en")).toBe("fr");
+    });
+  });
+
   test("should handle partial interpolation args", async ({ expect }) => {
     class App {
       en = $dictionary({