alepha 0.19.3 → 0.19.5

package/src/orm/__tests__/enums.spec.ts

@@ -3,33 +3,33 @@ import { describe, expect, it } from "vitest";
 import { $entity, $repository, DrizzleKitProvider, db } from "../core/index.ts";
 import { AlephaOrmPostgres } from "../postgres/index.ts";
 
-// Test 1: Basic enum using t.enum (should map to TEXT column)
+// Test 1: t.enum with mode: "text" (should map to TEXT column)
 const textEnumEntity = $entity({
   name: "text_enum_test",
   schema: t.object({
     id: db.primaryKey(),
-    status: t.enum(["pending", "active", "archived"]),
-    role: t.enum(["user", "admin", "moderator"]),
+    status: t.enum(["pending", "active", "archived"], { mode: "text" }),
+    role: t.enum(["user", "admin", "moderator"], { mode: "text" }),
   }),
 });
 
-// Test 2: Basic enum using db.enum (should create real PG ENUM type)
+// Test 2: t.enum without mode (should create real PG ENUM type)
 const pgEnumEntity = $entity({
   name: "pg_enum_test",
   schema: t.object({
     id: db.primaryKey(),
-    status: db.enum(["draft", "published", "deleted"]),
-    priority: db.enum(["low", "medium", "high"]),
+    status: t.enum(["draft", "published", "deleted"]),
+    priority: t.enum(["low", "medium", "high"]),
   }),
 });
 
-// Test 3: Mixed t.enum and db.enum in the same table
+// Test 3: Mixed text and pg enum in the same table
 const mixedEnumEntity = $entity({
   name: "mixed_enum_test",
   schema: t.object({
     id: db.primaryKey(),
-    textStatus: t.enum(["open", "closed"]),
-    pgStatus: db.enum(["new", "in_progress", "done"]),
+    textStatus: t.enum(["open", "closed"], { mode: "text" }),
+    pgStatus: t.enum(["new", "in_progress", "done"]),
   }),
 });
 
@@ -38,7 +38,7 @@ const sharedEnumEntity1 = $entity({
   name: "shared_enum_test_1",
   schema: t.object({
     id: db.primaryKey(),
-    status: db.enum(["enabled", "disabled"], { name: "shared_status_enum" }),
+    status: t.enum(["enabled", "disabled"], { name: "shared_status_enum" }),
   }),
 });
 
@@ -46,7 +46,7 @@ const sharedEnumEntity2 = $entity({
   name: "shared_enum_test_2",
   schema: t.object({
     id: db.primaryKey(),
-    status: db.enum(["enabled", "disabled"], { name: "shared_status_enum" }),
+    status: t.enum(["enabled", "disabled"], { name: "shared_status_enum" }),
   }),
 });
 
@@ -55,7 +55,7 @@ const conflictEnumEntity1 = $entity({
   name: "conflict_enum_test_1",
   schema: t.object({
     id: db.primaryKey(),
-    status: db.enum(["a", "b", "c"], { name: "conflict_status_enum" }),
+    status: t.enum(["a", "b", "c"], { name: "conflict_status_enum" }),
   }),
 });
 
@@ -63,12 +63,12 @@ const conflictEnumEntity2 = $entity({
   name: "conflict_enum_test_2",
   schema: t.object({
     id: db.primaryKey(),
-    status: db.enum(["a", "b", "d"], { name: "conflict_status_enum" }), // Different value!
+    status: t.enum(["a", "b", "d"], { name: "conflict_status_enum" }), // Different value!
   }),
 });
 
-describe("enums - t.enum (TEXT column)", () => {
-  it("should create TEXT columns for t.enum fields", async () => {
+describe("enums - t.enum with mode: 'text' (TEXT column)", () => {
+  it("should create TEXT columns for t.enum fields with mode: 'text'", async () => {
     const alepha = Alepha.create().with(AlephaOrmPostgres);
 
     class App {
@@ -87,12 +87,12 @@ describe("enums - t.enum (TEXT column)", () => {
 
     expect(sql).toContainEqual(expect.stringContaining("CREATE TABLE"));
     expect(sql).toContainEqual(expect.stringContaining("text_enum_test"));
-    // t.enum should map to TEXT, not a real ENUM type
+    // mode: "text" should map to TEXT, not a real ENUM type
     expect(sql.some((s) => s.includes('"status" text'))).toBe(true);
     expect(sql.some((s) => s.includes('"role" text'))).toBe(true);
   });
 
-  it("should allow inserting and querying with t.enum values", async () => {
+  it("should allow inserting and querying with text enum values", async () => {
     const alepha = Alepha.create().with(AlephaOrmPostgres);
 
     class App {
@@ -117,8 +117,8 @@ describe("enums - t.enum (TEXT column)", () => {
   });
 });
 
-describe("enums - db.enum (real PG ENUM type)", () => {
-  it("should create real PostgreSQL ENUM types for db.enum fields", async () => {
+describe("enums - t.enum (real PG ENUM type)", () => {
+  it("should create real PostgreSQL ENUM types for t.enum fields", async () => {
     const alepha = Alepha.create().with(AlephaOrmPostgres);
 
     class App {
@@ -137,13 +137,13 @@ describe("enums - db.enum (real PG ENUM type)", () => {
 
     expect(sql).toContainEqual(expect.stringContaining("CREATE TABLE"));
     expect(sql).toContainEqual(expect.stringContaining("pg_enum_test"));
-    // db.enum should create real ENUM types
+    // t.enum without mode should create real ENUM types
     expect(
       sql.some((s) => s.includes("CREATE TYPE") || s.includes("DO $$ BEGIN")),
     ).toBe(true);
   });
 
-  it("should allow inserting and querying with db.enum values", async () => {
+  it("should allow inserting and querying with pg enum values", async () => {
     const alepha = Alepha.create().with(AlephaOrmPostgres);
 
     class App {
@@ -168,7 +168,7 @@ describe("enums - db.enum (real PG ENUM type)", () => {
   });
 });
 
-describe("enums - mixed t.enum and db.enum in same table", () => {
+describe("enums - mixed text and pg enum in same table", () => {
   it("should handle both TEXT and PG ENUM types in the same table", async () => {
     const alepha = Alepha.create().with(AlephaOrmPostgres);
 
@@ -299,13 +299,6 @@ describe("enums - conflict detection with different values", () => {
   it("should throw error when same enum name has different values", async () => {
     const alepha = Alepha.create().with(AlephaOrmPostgres);
 
-    const load = async () => {
-      return alepha.with(() => ({
-        r1: $repository(conflictEnumEntity1),
-        r2: $repository(conflictEnumEntity2),
-      }));
-    };
-
     expect(() =>
       alepha.with(() => ({
         r1: $repository(conflictEnumEntity1),

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

@@ -0,0 +1,430 @@
+import type { Alepha } from "alepha";
+import { t } from "alepha";
+import { expect } from "vitest";
+import { $entity, $repository, db } from "../core/index.ts";
+
+// ============================================================================
+// Entity definitions — two entities with a foreign key relationship
+// ============================================================================
+
+const teams = $entity({
+  name: "teams",
+  schema: t.object({
+    id: db.primaryKey(),
+    name: t.text(),
+    country: t.text(),
+  }),
+});
+
+const players = $entity({
+  name: "players",
+  schema: t.object({
+    id: db.primaryKey(),
+    teamId: db.ref(t.optional(t.integer()), () => teams.cols.id),
+    name: t.text(),
+    position: t.text(),
+    goals: db.default(t.integer(), 0),
+  }),
+});
+
+class App {
+  teams = $repository(teams);
+  players = $repository(players);
+}
+
+// ============================================================================
+// Shared setup
+// ============================================================================
+
+async function seed(app: App) {
+  const barca = await app.teams.create({
+    name: "FC Barcelona",
+    country: "Spain",
+  });
+  const psg = await app.teams.create({
+    name: "Paris Saint-Germain",
+    country: "France",
+  });
+  const real = await app.teams.create({
+    name: "Real Madrid",
+    country: "Spain",
+  });
+
+  const messi = await app.players.create({
+    teamId: barca.id,
+    name: "Messi",
+    position: "Forward",
+    goals: 672,
+  });
+  const pedri = await app.players.create({
+    teamId: barca.id,
+    name: "Pedri",
+    position: "Midfielder",
+    goals: 18,
+  });
+  const mbappe = await app.players.create({
+    teamId: psg.id,
+    name: "Mbappé",
+    position: "Forward",
+    goals: 256,
+  });
+  const modric = await app.players.create({
+    teamId: real.id,
+    name: "Modrić",
+    position: "Midfielder",
+    goals: 39,
+  });
+  const freeAgent = await app.players.create({
+    name: "Free Agent",
+    position: "Goalkeeper",
+    goals: 0,
+  });
+
+  return {
+    teams: { barca, psg, real },
+    players: { messi, pedri, mbappe, modric, freeAgent },
+  };
+}
+
+// ============================================================================
+// 1. Basic left join — player with their team
+// ============================================================================
+
+export const testLeftJoinPlayerWithTeam = async (alepha: Alepha) => {
+  const app = alepha.inject(App);
+  await alepha.start();
+  const { players: p } = await seed(app);
+
+  const result = await app.players.getOne({
+    where: { id: { eq: p.messi.id } },
+    with: {
+      team: {
+        join: teams,
+        on: ["teamId", teams.cols.id],
+      },
+    },
+  });
+
+  expect(result.name).toBe("Messi");
+  expect(result.team).toBeDefined();
+  expect(result.team.name).toBe("FC Barcelona");
+  expect(result.team.country).toBe("Spain");
+};
+
+// ============================================================================
+// 2. Left join returns undefined when FK is null
+// ============================================================================
+
+export const testLeftJoinReturnsUndefinedWhenFkNull = async (
+  alepha: Alepha,
+) => {
+  const app = alepha.inject(App);
+  await alepha.start();
+  const { players: p } = await seed(app);
+
+  const result = await app.players.getOne({
+    where: { id: { eq: p.freeAgent.id } },
+    with: {
+      team: {
+        join: teams,
+        on: ["teamId", teams.cols.id],
+      },
+    },
+  });
+
+  expect(result.name).toBe("Free Agent");
+  expect(result.team).toBeUndefined();
+};
+
+// ============================================================================
+// 3. Inner join excludes rows without match
+// ============================================================================
+
+export const testInnerJoinExcludesNulls = async (alepha: Alepha) => {
+  const app = alepha.inject(App);
+  await alepha.start();
+  await seed(app);
+
+  const results = await app.players.findMany({
+    with: {
+      team: {
+        type: "inner",
+        join: teams,
+        on: ["teamId", teams.cols.id],
+      },
+    },
+  });
+
+  // Free Agent has no team → excluded by inner join
+  expect(results.length).toBe(4);
+  expect(results.every((r) => r.team !== null && r.team !== undefined)).toBe(
+    true,
+  );
+  expect(results.find((r) => r.name === "Free Agent")).toBeUndefined();
+};
+
+// ============================================================================
+// 4. findMany with join + filter on joined table
+// ============================================================================
+
+export const testFilterOnJoinedTable = async (alepha: Alepha) => {
+  const app = alepha.inject(App);
+  await alepha.start();
+  await seed(app);
+
+  const spanishPlayers = await app.players.findMany({
+    with: {
+      team: {
+        join: teams,
+        on: ["teamId", teams.cols.id],
+      },
+    },
+    where: {
+      team: {
+        country: { eq: "Spain" },
+      },
+    },
+  });
+
+  expect(spanishPlayers.length).toBe(3); // Messi, Pedri (Barça), Modrić (Real)
+  expect(spanishPlayers.every((p) => p.team.country === "Spain")).toBe(true);
+};
+
+// ============================================================================
+// 5. Combined filters — base table + joined table
+// ============================================================================
+
+export const testCombinedFilters = async (alepha: Alepha) => {
+  const app = alepha.inject(App);
+  await alepha.start();
+  await seed(app);
+
+  const results = await app.players.findMany({
+    with: {
+      team: {
+        join: teams,
+        on: ["teamId", teams.cols.id],
+      },
+    },
+    where: {
+      and: [
+        { position: { eq: "Forward" } },
+        { team: { country: { eq: "Spain" } } },
+      ],
+    },
+  });
+
+  expect(results.length).toBe(1);
+  expect(results[0].name).toBe("Messi");
+};
+
+// ============================================================================
+// 6. findMany with join + orderBy + limit
+// ============================================================================
+
+export const testJoinWithOrderByAndLimit = async (alepha: Alepha) => {
+  const app = alepha.inject(App);
+  await alepha.start();
+  await seed(app);
+
+  const topScorers = await app.players.findMany({
+    with: {
+      team: {
+        join: teams,
+        on: ["teamId", teams.cols.id],
+      },
+    },
+    orderBy: { column: "goals", direction: "desc" },
+    limit: 2,
+  });
+
+  expect(topScorers.length).toBe(2);
+  expect(topScorers[0].name).toBe("Messi");
+  expect(topScorers[1].name).toBe("Mbappé");
+  expect(topScorers[0].team).toBeDefined();
+  expect(topScorers[1].team).toBeDefined();
+};
+
+// ============================================================================
+// 7. Pagination with joins
+// ============================================================================
+
+export const testPaginationWithJoins = async (alepha: Alepha) => {
+  const app = alepha.inject(App);
+  await alepha.start();
+  await seed(app);
+
+  const page = await app.players.paginate(
+    { page: 0, size: 2 },
+    {
+      with: {
+        team: {
+          join: teams,
+          on: ["teamId", teams.cols.id],
+        },
+      },
+      orderBy: { column: "name", direction: "asc" },
+    },
+  );
+
+  expect(page.content.length).toBe(2);
+  expect(page.page.isFirst).toBe(true);
+  expect(page.page.isLast).toBe(false);
+  // Each result should include the joined team
+  for (const player of page.content) {
+    // Some players may have no team (left join)
+    if (player.teamId) {
+      expect(player.team).toBeDefined();
+    }
+  }
+};
+
+// ============================================================================
+// 8. OR filter across base + joined table
+// ============================================================================
+
+export const testOrFilterAcrossTables = async (alepha: Alepha) => {
+  const app = alepha.inject(App);
+  await alepha.start();
+  await seed(app);
+
+  const results = await app.players.findMany({
+    with: {
+      team: {
+        join: teams,
+        on: ["teamId", teams.cols.id],
+      },
+    },
+    where: {
+      or: [{ goals: { gte: 200 } }, { team: { country: { eq: "France" } } }],
+    },
+    orderBy: { column: "goals", direction: "desc" },
+  });
+
+  // Messi (672), Mbappé (256 + France) — Mbappé matches both conditions
+  expect(results.length).toBe(2);
+  expect(results.map((r) => r.name)).toEqual(["Messi", "Mbappé"]);
+};
+
+// ============================================================================
+// 9. getOne with join throws when not found
+// ============================================================================
+
+export const testGetOneWithJoinThrowsWhenNotFound = async (alepha: Alepha) => {
+  const app = alepha.inject(App);
+  await alepha.start();
+  await seed(app);
+
+  await expect(
+    app.players.getOne({
+      where: { name: { eq: "Neymar" } },
+      with: {
+        team: {
+          join: teams,
+          on: ["teamId", teams.cols.id],
+        },
+      },
+    }),
+  ).rejects.toThrow();
+};
+
+// ============================================================================
+// 10. findOne with join — returns undefined instead of throwing
+// ============================================================================
+
+export const testFindOneWithJoinReturnsUndefined = async (alepha: Alepha) => {
+  const app = alepha.inject(App);
+  await alepha.start();
+  await seed(app);
+
+  const result = await app.players.findOne({
+    where: { name: { eq: "Neymar" } },
+    with: {
+      team: {
+        join: teams,
+        on: ["teamId", teams.cols.id],
+      },
+    },
+  });
+
+  expect(result).toBeUndefined();
+};
+
+// ============================================================================
+// 11. Empty result set with joins
+// ============================================================================
+
+export const testEmptyResultWithJoins = async (alepha: Alepha) => {
+  const app = alepha.inject(App);
+  await alepha.start();
+  await seed(app);
+
+  const results = await app.players.findMany({
+    where: { position: { eq: "Defender" } },
+    with: {
+      team: {
+        join: teams,
+        on: ["teamId", teams.cols.id],
+      },
+    },
+  });
+
+  expect(results.length).toBe(0);
+};
+
+// ============================================================================
+// 12. Multiple operators on joined table filter
+// ============================================================================
+
+export const testMultipleOperatorsOnJoinedFilter = async (alepha: Alepha) => {
+  const app = alepha.inject(App);
+  await alepha.start();
+  await seed(app);
+
+  const results = await app.players.findMany({
+    with: {
+      team: {
+        join: teams,
+        on: ["teamId", teams.cols.id],
+      },
+    },
+    where: {
+      team: {
+        name: { contains: "paris" }, // case-insensitive
+      },
+    },
+  });
+
+  expect(results.length).toBe(1);
+  expect(results[0].name).toBe("Mbappé");
+  expect(results[0].team.name).toBe("Paris Saint-Germain");
+};
+
+// ============================================================================
+// 13. Join with offset (pagination without paginate)
+// ============================================================================
+
+export const testJoinWithOffset = async (alepha: Alepha) => {
+  const app = alepha.inject(App);
+  await alepha.start();
+  await seed(app);
+
+  const results = await app.players.findMany({
+    with: {
+      team: {
+        type: "inner",
+        join: teams,
+        on: ["teamId", teams.cols.id],
+      },
+    },
+    orderBy: { column: "name", direction: "asc" },
+    offset: 1,
+    limit: 2,
+  });
+
+  // Inner join excludes Free Agent → sorted: Mbappé, Messi, Modrić, Pedri
+  // offset 1 + limit 2 → Messi, Modrić
+  expect(results.length).toBe(2);
+  expect(results[0].name).toBe("Messi");
+  expect(results[1].name).toBe("Modrić");
+};