alepha 0.19.3 → 0.19.5

package/src/orm/__tests__/orm-showcase.spec.ts

@@ -0,0 +1,167 @@
+import { Alepha } from "alepha";
+import { describe, it } from "vitest";
+import { AlephaOrmPostgres } from "../postgres/index.ts";
+import {
+  testCombinedFilters,
+  testEmptyResultWithJoins,
+  testFilterOnJoinedTable,
+  testFindOneWithJoinReturnsUndefined,
+  testGetOneWithJoinThrowsWhenNotFound,
+  testInnerJoinExcludesNulls,
+  testJoinWithOffset,
+  testJoinWithOrderByAndLimit,
+  testLeftJoinPlayerWithTeam,
+  testLeftJoinReturnsUndefinedWhenFkNull,
+  testMultipleOperatorsOnJoinedFilter,
+  testOrFilterAcrossTables,
+  testPaginationWithJoins,
+} from "./orm-showcase-tests.ts";
+
+describe("orm showcase: entities + joins", () => {
+  describe("basic left join", () => {
+    it("should join player with team (sqlite)", async () => {
+      await testLeftJoinPlayerWithTeam(
+        Alepha.create({ env: { DATABASE_URL: "sqlite://:memory:" } }),
+      );
+    });
+    it("should join player with team (postgres)", async () => {
+      await testLeftJoinPlayerWithTeam(Alepha.create().with(AlephaOrmPostgres));
+    });
+  });
+
+  describe("left join with null FK", () => {
+    it("should return undefined when FK is null (sqlite)", async () => {
+      await testLeftJoinReturnsUndefinedWhenFkNull(
+        Alepha.create({ env: { DATABASE_URL: "sqlite://:memory:" } }),
+      );
+    });
+    it("should return undefined when FK is null (postgres)", async () => {
+      await testLeftJoinReturnsUndefinedWhenFkNull(
+        Alepha.create().with(AlephaOrmPostgres),
+      );
+    });
+  });
+
+  describe("inner join", () => {
+    it("should exclude rows without match (sqlite)", async () => {
+      await testInnerJoinExcludesNulls(
+        Alepha.create({ env: { DATABASE_URL: "sqlite://:memory:" } }),
+      );
+    });
+    it("should exclude rows without match (postgres)", async () => {
+      await testInnerJoinExcludesNulls(Alepha.create().with(AlephaOrmPostgres));
+    });
+  });
+
+  describe("filter on joined table", () => {
+    it("should filter by joined table column (sqlite)", async () => {
+      await testFilterOnJoinedTable(
+        Alepha.create({ env: { DATABASE_URL: "sqlite://:memory:" } }),
+      );
+    });
+    it("should filter by joined table column (postgres)", async () => {
+      await testFilterOnJoinedTable(Alepha.create().with(AlephaOrmPostgres));
+    });
+  });
+
+  describe("combined base + join filters", () => {
+    it("should combine base and join table filters (sqlite)", async () => {
+      await testCombinedFilters(
+        Alepha.create({ env: { DATABASE_URL: "sqlite://:memory:" } }),
+      );
+    });
+    it("should combine base and join table filters (postgres)", async () => {
+      await testCombinedFilters(Alepha.create().with(AlephaOrmPostgres));
+    });
+  });
+
+  describe("orderBy + limit with joins", () => {
+    it("should order and limit with joins (sqlite)", async () => {
+      await testJoinWithOrderByAndLimit(
+        Alepha.create({ env: { DATABASE_URL: "sqlite://:memory:" } }),
+      );
+    });
+    it("should order and limit with joins (postgres)", async () => {
+      await testJoinWithOrderByAndLimit(
+        Alepha.create().with(AlephaOrmPostgres),
+      );
+    });
+  });
+
+  describe("pagination with joins", () => {
+    it("should paginate with joins (sqlite)", async () => {
+      await testPaginationWithJoins(
+        Alepha.create({ env: { DATABASE_URL: "sqlite://:memory:" } }),
+      );
+    });
+    it("should paginate with joins (postgres)", async () => {
+      await testPaginationWithJoins(Alepha.create().with(AlephaOrmPostgres));
+    });
+  });
+
+  describe("OR filter across tables", () => {
+    it("should OR across base and joined table (sqlite)", async () => {
+      await testOrFilterAcrossTables(
+        Alepha.create({ env: { DATABASE_URL: "sqlite://:memory:" } }),
+      );
+    });
+    it("should OR across base and joined table (postgres)", async () => {
+      await testOrFilterAcrossTables(Alepha.create().with(AlephaOrmPostgres));
+    });
+  });
+
+  describe("getOne / findOne with joins", () => {
+    it("should throw when not found via getOne (sqlite)", async () => {
+      await testGetOneWithJoinThrowsWhenNotFound(
+        Alepha.create({ env: { DATABASE_URL: "sqlite://:memory:" } }),
+      );
+    });
+    it("should throw when not found via getOne (postgres)", async () => {
+      await testGetOneWithJoinThrowsWhenNotFound(
+        Alepha.create().with(AlephaOrmPostgres),
+      );
+    });
+
+    it("should return undefined via findOne (sqlite)", async () => {
+      await testFindOneWithJoinReturnsUndefined(
+        Alepha.create({ env: { DATABASE_URL: "sqlite://:memory:" } }),
+      );
+    });
+    it("should return undefined via findOne (postgres)", async () => {
+      await testFindOneWithJoinReturnsUndefined(
+        Alepha.create().with(AlephaOrmPostgres),
+      );
+    });
+  });
+
+  describe("edge cases", () => {
+    it("should return empty array when no matches (sqlite)", async () => {
+      await testEmptyResultWithJoins(
+        Alepha.create({ env: { DATABASE_URL: "sqlite://:memory:" } }),
+      );
+    });
+    it("should return empty array when no matches (postgres)", async () => {
+      await testEmptyResultWithJoins(Alepha.create().with(AlephaOrmPostgres));
+    });
+
+    it("should filter with operators on joined table (sqlite)", async () => {
+      await testMultipleOperatorsOnJoinedFilter(
+        Alepha.create({ env: { DATABASE_URL: "sqlite://:memory:" } }),
+      );
+    });
+    it("should filter with operators on joined table (postgres)", async () => {
+      await testMultipleOperatorsOnJoinedFilter(
+        Alepha.create().with(AlephaOrmPostgres),
+      );
+    });
+
+    it("should handle offset with inner join (sqlite)", async () => {
+      await testJoinWithOffset(
+        Alepha.create({ env: { DATABASE_URL: "sqlite://:memory:" } }),
+      );
+    });
+    it("should handle offset with inner join (postgres)", async () => {
+      await testJoinWithOffset(Alepha.create().with(AlephaOrmPostgres));
+    });
+  });
+});

package/src/orm/core/providers/DatabaseTypeProvider.ts

@@ -12,7 +12,6 @@ import {
   type TSchema,
   type TString,
   type TStringOptions,
-  type TUnsafe,
   t,
 } from "alepha";
 import type { UpdateDeleteAction } from "drizzle-orm/pg-core/foreign-keys";
@@ -20,7 +19,6 @@ import {
   PG_CREATED_AT,
   PG_DEFAULT,
   PG_DELETED_AT,
-  PG_ENUM,
   PG_IDENTITY,
   PG_ORGANIZATION,
   PG_PRIMARY_KEY,
@@ -28,7 +26,6 @@ import {
   PG_UPDATED_AT,
   PG_VERSION,
   type PgDefault,
-  type PgEnumOptions,
   type PgIdentityOptions,
   type PgPrimaryKey,
   type PgRef,
@@ -198,32 +195,6 @@ export class DatabaseTypeProvider {
   public readonly organization = () =>
     pgAttr(t.optional(t.uuid()), PG_ORGANIZATION);
 
-  /**
-   * Creates a Postgres ENUM type.
-   *
-   * > By default, `t.enum()` is mapped to a TEXT column in Postgres.
-   * > Using this method, you can create a real ENUM type in the database.
-   *
-   * @example
-   * ```ts
-   * const statusEnum = pg.enum(["pending", "active", "archived"], { name: "status_enum" });
-   * ```
-   */
-  public readonly enum = <T extends string[]>(
-    values: [...T],
-    pgEnumOptions?: PgEnumOptions,
-    typeOptions?: TStringOptions,
-  ): PgAttr<TUnsafe<T[number]>, typeof PG_ENUM> => {
-    return pgAttr(
-      t.enum(values, {
-        description: pgEnumOptions?.description,
-        ...typeOptions,
-      }),
-      PG_ENUM,
-      pgEnumOptions,
-    );
-  };
-
   /**
    * Creates a reference to another table or schema. Basically a foreign key.
    */

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

@@ -533,6 +533,8 @@ export abstract class Repository<T extends TObject> {
     } = {},
     opts: StatementOptions & { count?: boolean } = {},
   ): Promise<Page<PgStatic<T, R>>> {
+    // Overflow-safe: pageQuerySchema constrains size to [1, 100] and page to >= 0.
+    // With max size=100, page would need to exceed 2^45 to overflow Number.MAX_SAFE_INTEGER.
     const limit = query.limit ?? pagination.size ?? 10;
     const page = pagination.page ?? 0;
     const offset = query.offset ?? page * limit;
@@ -674,7 +676,9 @@ export abstract class Repository<T extends TObject> {
         .returning(this.table)
         .then(([it]) => this.clean(it, this.entity.schema));
 
-      this.dbCache.invalidateTable(this.tableName).catch(() => {});
+      this.dbCache
+        .invalidateTable(this.tableName)
+        .catch((err) => this.log.warn("Cache invalidation failed", err));
 
       await this.alepha.events.emit("repository:create:after", {
         tableName: this.tableName,
@@ -728,7 +732,9 @@ export abstract class Repository<T extends TObject> {
         allEntities.push(...entities);
       }
 
-      this.dbCache.invalidateTable(this.tableName).catch(() => {});
+      this.dbCache
+        .invalidateTable(this.tableName)
+        .catch((err) => this.log.warn("Cache invalidation failed", err));
 
       await this.alepha.events.emit("repository:create:after", {
         tableName: this.tableName,
@@ -825,7 +831,9 @@ export abstract class Repository<T extends TObject> {
         .returning(this.table)
         .then(([it]) => this.clean(it, this.entity.schema));
 
-      this.dbCache.invalidateTable(this.tableName).catch(() => {});
+      this.dbCache
+        .invalidateTable(this.tableName)
+        .catch((err) => this.log.warn("Cache invalidation failed", err));
 
       await this.alepha.events.emit("repository:create:after", {
         tableName: this.tableName,
@@ -889,7 +897,9 @@ export abstract class Repository<T extends TObject> {
     try {
       const entity = this.clean(response[0], this.entity.schema);
 
-      this.dbCache.invalidateTable(this.tableName).catch(() => {});
+      this.dbCache
+        .invalidateTable(this.tableName)
+        .catch((err) => this.log.warn("Cache invalidation failed", err));
 
       await this.alepha.events.emit("repository:update:after", {
         tableName: this.tableName,
@@ -1041,7 +1051,9 @@ export abstract class Repository<T extends TObject> {
         .where(this.toSQL(where))
         .returning();
 
-      this.dbCache.invalidateTable(this.tableName).catch(() => {});
+      this.dbCache
+        .invalidateTable(this.tableName)
+        .catch((err) => this.log.warn("Cache invalidation failed", err));
 
       await this.alepha.events.emit("repository:update:after", {
         tableName: this.tableName,
@@ -1089,7 +1101,9 @@ export abstract class Repository<T extends TObject> {
         .returning({ id: (this.table as any)[this.id.key] });
       const ids = result.map((row) => row.id);
 
-      this.dbCache.invalidateTable(this.tableName).catch(() => {});
+      this.dbCache
+        .invalidateTable(this.tableName)
+        .catch((err) => this.log.warn("Cache invalidation failed", err));
 
       await this.alepha.events.emit("repository:delete:after", {
         tableName: this.tableName,

package/src/orm/postgres/services/PostgresModelBuilder.ts

@@ -4,14 +4,12 @@ import {
   type FromSchema,
   ModelBuilder,
   PG_CREATED_AT,
-  PG_ENUM,
   PG_GENERATED,
   PG_IDENTITY,
   PG_PRIMARY_KEY,
   PG_REF,
   PG_SERIAL,
   PG_UPDATED_AT,
-  type PgEnumOptions,
   type PgGeneratedOptions,
   type PgIdentityOptions,
   type PgRefOptions,
@@ -384,10 +382,9 @@ export class PostgresModelBuilder extends ModelBuilder {
         );
       }
 
-      // SQL Enum
-      if (PG_ENUM in value && value[PG_ENUM]) {
-        const options = value[PG_ENUM] as PgEnumOptions;
-        const enumName = options.name ?? `${tableName}_${key}_enum`;
+      // SQL Enum (default for t.enum unless mode: "text")
+      if ((value as any).mode !== "text") {
+        const enumName = (value as any).enumName ?? `${tableName}_${key}_enum`;
 
         if (enums.has(enumName)) {
           const values = (

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

@@ -366,6 +366,89 @@ describe("I18nProvider", () => {
     );
   });
 
+  describe("when only non-English dictionaries are registered", () => {
+    test("should default to the first registered language", async ({
+      expect,
+    }) => {
+      class App {
+        fr = $dictionary({
+          lazy: async () => ({ default: { hello: "Bonjour" } }),
+        });
+      }
+
+      const alepha = Alepha.create().with(AlephaReactI18n);
+      const app = alepha.inject(App);
+      const i18n = alepha.inject(I18nProvider);
+
+      expect(i18n.lang).toBe("fr");
+    });
+
+    test("should translate using the first registered language", async ({
+      expect,
+    }) => {
+      class App {
+        fr = $dictionary({
+          lazy: async () => ({
+            default: { greeting: "Bonjour!", settings: "Paramètres" },
+          }),
+        });
+      }
+
+      const alepha = Alepha.create().with(AlephaReactI18n);
+      const app = alepha.inject(App);
+      const i18n = alepha.inject(I18nProvider);
+
+      await alepha.start();
+
+      expect(i18n.tr("greeting")).toBe("Bonjour!");
+      expect(i18n.tr("settings")).toBe("Paramètres");
+    });
+
+    test("should not include 'en' in languages list", async ({ expect }) => {
+      class App {
+        fr = $dictionary({
+          lazy: async () => ({ default: { hello: "Bonjour" } }),
+        });
+
+        de = $dictionary({
+          lazy: async () => ({ default: { hello: "Hallo" } }),
+        });
+      }
+
+      const alepha = Alepha.create().with(AlephaReactI18n);
+      const app = alepha.inject(App);
+      const i18n = alepha.inject(I18nProvider);
+
+      expect(i18n.languages).toEqual(["fr", "de"]);
+    });
+
+    test("should fallback to the first registered language for missing keys", async ({
+      expect,
+    }) => {
+      class App {
+        fr = $dictionary({
+          lazy: async () => ({
+            default: { hello: "Bonjour", world: "Monde" },
+          }),
+        });
+
+        de = $dictionary({
+          lazy: async () => ({ default: { hello: "Hallo" } }),
+        });
+      }
+
+      const alepha = Alepha.create().with(AlephaReactI18n);
+      const app = alepha.inject(App);
+      const i18n = alepha.inject(I18nProvider);
+
+      await alepha.start();
+      await i18n.setLang("de");
+
+      expect(i18n.tr("hello")).toBe("Hallo");
+      expect(i18n.tr("world")).toBe("Monde"); // Falls back to FR
+    });
+  });
+
   test("should handle partial interpolation args", async ({ expect }) => {
     class App {
       en = $dictionary({

package/src/react/i18n/providers/I18nProvider.ts

@@ -42,7 +42,6 @@ export class I18nProvider<
     for (const item of this.registry) {
       languages.add(item.lang);
     }
-    languages.add(this.options.fallbackLang);
 
     return Array.from(languages);
   }
@@ -70,10 +69,7 @@ export class I18nProvider<
         }
 
         for (const item of this.registry) {
-          if (
-            item.lang === this.lang ||
-            item.lang === this.options.fallbackLang
-          ) {
+          if (item.lang === this.lang || item.lang === this.fallbackLang) {
             this.log.trace("Loading language", {
               lang: item.lang,
               name: item.name,
@@ -139,11 +135,17 @@ export class I18nProvider<
     },
   });
 
+  public get fallbackLang(): string {
+    const configured = this.options.fallbackLang;
+    const hasDict = this.registry.some((item) => item.lang === configured);
+    if (hasDict) {
+      return configured;
+    }
+    return this.registry[0]?.lang ?? configured;
+  }
+
   public get lang(): string {
-    return (
-      this.alepha.store.get("alepha.react.i18n.lang") ||
-      this.options.fallbackLang
-    );
+    return this.alepha.store.get("alepha.react.i18n.lang") || this.fallbackLang;
   }
 
   public translate = (key: string, args: string[] = []) => {
@@ -156,7 +158,7 @@ export class I18nProvider<
     }
 
     for (const item of this.registry) {
-      if (item.lang === this.options.fallbackLang) {
+      if (item.lang === this.fallbackLang) {
         if (item.translations[key]) {
           return this.render(item.translations[key], args); // append lang for fallback
         }

package/src/react/router/__tests__/$page.browser.spec.tsx

@@ -882,4 +882,161 @@ describe("$page browser tests", () => {
       });
     });
   });
+
+  describe("transition supersession", () => {
+    it("should not commit a stale slow transition when a newer navigation already won", async () => {
+      let resolvePageA: ((value: { data: string }) => void) | undefined;
+      const pageARendered = vi.fn();
+      const pageBRendered = vi.fn();
+
+      class App {
+        pageA = $page({
+          path: "/page-a",
+          loader: () =>
+            new Promise<{ data: string }>((resolve) => {
+              resolvePageA = resolve;
+            }),
+          component: ({ data }: { data: string }) => {
+            pageARendered();
+            return <div data-testid="page-a">A: {data}</div>;
+          },
+        });
+
+        pageB = $page({
+          path: "/page-b",
+          component: () => {
+            pageBRendered();
+            return <div data-testid="page-b">B</div>;
+          },
+        });
+      }
+
+      alepha = Alepha.create().with(AlephaReact).with(App);
+      await alepha.start();
+
+      const router = alepha.inject(ReactRouter);
+
+      // Start navigating to /page-a — its loader hangs, push() will not
+      // resolve until we manually resolve the loader below.
+      const pushAPromise = router.push("/page-a");
+
+      // Yield so the in-flight transition for /page-a actually starts and
+      // reaches the awaited loader before pushB enters the race.
+      await new Promise((r) => setTimeout(r, 0));
+
+      // Navigate to /page-b before /page-a finishes loading. This should
+      // supersede the in-flight /page-a transition.
+      await act(async () => {
+        await router.push("/page-b");
+      });
+
+      // /page-b should now be the committed router state.
+      expect(router.state.name).toBe("pageB");
+      expect(router.state.url.pathname).toBe("/page-b");
+
+      // Now resolve /page-a's loader: this is the race window where the
+      // stale /page-a transition could overwrite /page-b.
+      resolvePageA?.({ data: "loaded" });
+      await act(async () => {
+        await pushAPromise;
+      });
+
+      // Stale /page-a must NOT have committed.
+      expect(router.state.name).toBe("pageB");
+      expect(router.state.url.pathname).toBe("/page-b");
+      // /page-a's component must never have been instantiated.
+      expect(pageARendered).not.toHaveBeenCalled();
+    });
+
+    it("should not fire onEnter for a stale superseded page", async () => {
+      let resolvePageA: (() => void) | undefined;
+      const pageAOnEnter = vi.fn();
+      const pageBOnEnter = vi.fn();
+
+      class App {
+        pageA = $page({
+          path: "/page-a",
+          loader: () =>
+            new Promise<void>((resolve) => {
+              resolvePageA = resolve;
+            }),
+          onEnter: pageAOnEnter,
+          component: () => <div data-testid="page-a">A</div>,
+        });
+
+        pageB = $page({
+          path: "/page-b",
+          onEnter: pageBOnEnter,
+          component: () => <div data-testid="page-b">B</div>,
+        });
+      }
+
+      alepha = Alepha.create().with(AlephaReact).with(App);
+      await alepha.start();
+
+      const router = alepha.inject(ReactRouter);
+
+      const pushAPromise = router.push("/page-a");
+      await new Promise((r) => setTimeout(r, 0));
+
+      await act(async () => {
+        await router.push("/page-b");
+      });
+
+      expect(router.state.name).toBe("pageB");
+      expect(pageBOnEnter).toHaveBeenCalledTimes(1);
+      expect(pageAOnEnter).not.toHaveBeenCalled();
+
+      // Resolve the stale loader: it must remain a no-op.
+      resolvePageA?.();
+      await act(async () => {
+        await pushAPromise;
+      });
+
+      expect(router.state.name).toBe("pageB");
+      expect(pageAOnEnter).not.toHaveBeenCalled();
+      expect(pageBOnEnter).toHaveBeenCalledTimes(1);
+    });
+
+    it("should not call pushState for a stale superseded transition", async () => {
+      let resolvePageA: (() => void) | undefined;
+
+      class App {
+        pageA = $page({
+          path: "/page-a",
+          loader: () =>
+            new Promise<void>((resolve) => {
+              resolvePageA = resolve;
+            }),
+          component: () => <div data-testid="page-a">A</div>,
+        });
+
+        pageB = $page({
+          path: "/page-b",
+          component: () => <div data-testid="page-b">B</div>,
+        });
+      }
+
+      alepha = Alepha.create().with(AlephaReact).with(App);
+      await alepha.start();
+
+      const router = alepha.inject(ReactRouter);
+
+      const pushAPromise = router.push("/page-a");
+      await new Promise((r) => setTimeout(r, 0));
+
+      await act(async () => {
+        await router.push("/page-b");
+      });
+      expect(window.location.pathname).toBe("/page-b");
+
+      resolvePageA?.();
+      await act(async () => {
+        await pushAPromise;
+      });
+
+      // The stale /page-a transition must not have rewritten the URL bar.
+      expect(window.location.pathname).toBe("/page-b");
+    });
+  });
 });