@fragno-dev/db 0.0.1 → 0.1.0

package/src/query/condition-builder.test.ts

@@ -0,0 +1,379 @@
+import { describe, expect, it } from "vitest";
+import { column, idColumn, schema } from "../schema/create";
+import { createBuilder, createIndexedBuilder } from "./condition-builder";
+
+describe("ConditionBuilder", () => {
+  const testSchema = schema((s) =>
+    s
+      .addTable("users", (t) =>
+        t
+          .addColumn("id", idColumn())
+          .addColumn("email", column("string"))
+          .addColumn("name", column("string"))
+          .addColumn("age", column("integer").nullable())
+          .createIndex("_primary", ["id"], { unique: true })
+          .createIndex("idx_email", ["email"], { unique: true })
+          .createIndex("idx_name_age", ["name", "age"]),
+      )
+      .addTable("posts", (t) =>
+        t
+          .addColumn("id", idColumn())
+          .addColumn("title", column("string"))
+          .addColumn("content", column("string"))
+          .addColumn("published", column("bool"))
+          .createIndex("_primary", ["id"], { unique: true })
+          .createIndex("idx_published", ["published"]),
+      ),
+  );
+
+  const usersTable = testSchema.tables.users;
+
+  describe("createBuilder", () => {
+    it("should create conditions with all columns", () => {
+      const builder = createBuilder(usersTable.columns);
+
+      const condition = builder("email", "=", "test@example.com");
+      expect(condition).toEqual({
+        type: "compare",
+        a: usersTable.columns.email,
+        operator: "=",
+        b: "test@example.com",
+      });
+    });
+
+    it("should support comparison operators", () => {
+      const builder = createBuilder(usersTable.columns);
+
+      expect(builder("age", ">", 18)).toEqual({
+        type: "compare",
+        a: usersTable.columns.age,
+        operator: ">",
+        b: 18,
+      });
+
+      expect(builder("age", "<=", 65)).toEqual({
+        type: "compare",
+        a: usersTable.columns.age,
+        operator: "<=",
+        b: 65,
+      });
+    });
+
+    it("should support array operators", () => {
+      const builder = createBuilder(usersTable.columns);
+
+      const condition = builder("name", "in", ["Alice", "Bob"]);
+      expect(condition).toEqual({
+        type: "compare",
+        a: usersTable.columns.name,
+        operator: "in",
+        b: ["Alice", "Bob"],
+      });
+    });
+
+    it("should support string operators", () => {
+      const builder = createBuilder(usersTable.columns);
+
+      const condition = builder("email", "contains", "example");
+      expect(condition).toEqual({
+        type: "compare",
+        a: usersTable.columns.email,
+        operator: "contains",
+        b: "example",
+      });
+    });
+
+    it("should support null checks", () => {
+      const builder = createBuilder(usersTable.columns);
+
+      expect(builder.isNull("age")).toEqual({
+        type: "compare",
+        a: usersTable.columns.age,
+        operator: "is",
+        b: null,
+      });
+
+      expect(builder.isNotNull("age")).toEqual({
+        type: "compare",
+        a: usersTable.columns.age,
+        operator: "is not",
+        b: null,
+      });
+    });
+
+    it("should support boolean columns", () => {
+      const postsTable = testSchema.tables.posts;
+      const builder = createBuilder(postsTable.columns);
+
+      expect(builder("published")).toEqual({
+        type: "compare",
+        a: postsTable.columns.published,
+        operator: "=",
+        b: true,
+      });
+    });
+
+    it("should support AND conditions", () => {
+      const builder = createBuilder(usersTable.columns);
+
+      const condition = builder.and(builder("age", ">", 18), builder("age", "<", 65));
+
+      expect(condition).toEqual({
+        type: "and",
+        items: [
+          {
+            type: "compare",
+            a: usersTable.columns.age,
+            operator: ">",
+            b: 18,
+          },
+          {
+            type: "compare",
+            a: usersTable.columns.age,
+            operator: "<",
+            b: 65,
+          },
+        ],
+      });
+    });
+
+    it("should support OR conditions", () => {
+      const builder = createBuilder(usersTable.columns);
+
+      const condition = builder.or(
+        builder("email", "contains", "gmail"),
+        builder("email", "contains", "yahoo"),
+      );
+
+      expect(condition).toEqual({
+        type: "or",
+        items: [
+          {
+            type: "compare",
+            a: usersTable.columns.email,
+            operator: "contains",
+            b: "gmail",
+          },
+          {
+            type: "compare",
+            a: usersTable.columns.email,
+            operator: "contains",
+            b: "yahoo",
+          },
+        ],
+      });
+    });
+
+    it("should support NOT conditions", () => {
+      const builder = createBuilder(usersTable.columns);
+
+      const condition = builder.not(builder("age", ">", 65));
+
+      expect(condition).toEqual({
+        type: "not",
+        item: {
+          type: "compare",
+          a: usersTable.columns.age,
+          operator: ">",
+          b: 65,
+        },
+      });
+    });
+
+    it("should handle boolean shortcuts in AND", () => {
+      const builder = createBuilder(usersTable.columns);
+
+      // true in AND should be ignored
+      expect(builder.and(true, builder("age", ">", 18))).toEqual({
+        type: "and",
+        items: [
+          {
+            type: "compare",
+            a: usersTable.columns.age,
+            operator: ">",
+            b: 18,
+          },
+        ],
+      });
+
+      // false in AND should short-circuit
+      expect(builder.and(false, builder("age", ">", 18))).toBe(false);
+
+      // all true should return true
+      expect(builder.and(true, true)).toBe(true);
+    });
+
+    it("should handle boolean shortcuts in OR", () => {
+      const builder = createBuilder(usersTable.columns);
+
+      // true in OR should short-circuit
+      expect(builder.or(true, builder("age", ">", 18))).toBe(true);
+
+      // false in OR should be ignored
+      expect(builder.or(false, builder("age", ">", 18))).toEqual({
+        type: "or",
+        items: [
+          {
+            type: "compare",
+            a: usersTable.columns.age,
+            operator: ">",
+            b: 18,
+          },
+        ],
+      });
+
+      // all false should return false
+      expect(builder.or(false, false)).toBe(false);
+    });
+
+    it("should throw on invalid column name", () => {
+      const builder = createBuilder(usersTable.columns);
+
+      expect(() => builder("nonexistent" as "email", "=", "test")).toThrow(
+        "Invalid column name nonexistent",
+      );
+    });
+
+    it("should throw on unsupported operator", () => {
+      const builder = createBuilder(usersTable.columns);
+
+      expect(() => builder("email", "invalid" as "=", "test")).toThrow(
+        "Unsupported operator: invalid",
+      );
+    });
+  });
+
+  describe("createIndexedBuilder", () => {
+    it("should allow comparisons on indexed columns", () => {
+      const indexedColumns = new Set(["id", "email", "name", "age"]);
+      const builder = createIndexedBuilder(usersTable.columns, indexedColumns);
+
+      const condition = builder("email", "=", "test@example.com");
+      expect(condition).toEqual({
+        type: "compare",
+        a: usersTable.columns.email,
+        operator: "=",
+        b: "test@example.com",
+      });
+    });
+
+    it("should allow comparisons on multiple indexed columns", () => {
+      const indexedColumns = new Set(["id", "email", "name", "age"]);
+      const builder = createIndexedBuilder(usersTable.columns, indexedColumns);
+
+      const condition = builder.and(builder("name", "=", "Alice"), builder("age", ">", 18));
+
+      expect(condition).toEqual({
+        type: "and",
+        items: [
+          {
+            type: "compare",
+            a: usersTable.columns.name,
+            operator: "=",
+            b: "Alice",
+          },
+          {
+            type: "compare",
+            a: usersTable.columns.age,
+            operator: ">",
+            b: 18,
+          },
+        ],
+      });
+    });
+
+    it("should throw error when using non-indexed column", () => {
+      // Only email is indexed
+      const indexedColumns = new Set(["email"]);
+      const builder = createIndexedBuilder(usersTable.columns, indexedColumns);
+
+      expect(() => builder("name", "=", "Alice")).toThrow(
+        'Column "name" is not indexed. Only indexed columns can be used in Unit of Work queries. Available indexed columns: email',
+      );
+    });
+
+    it("should throw error with helpful message listing available columns", () => {
+      const indexedColumns = new Set(["id", "email"]);
+      const builder = createIndexedBuilder(usersTable.columns, indexedColumns);
+
+      expect(() => builder("age", ">", 18)).toThrow(
+        'Column "age" is not indexed. Only indexed columns can be used in Unit of Work queries. Available indexed columns: id, email',
+      );
+    });
+
+    it("should support all builder methods with indexed columns", () => {
+      const indexedColumns = new Set(["id", "email", "name"]);
+      const builder = createIndexedBuilder(usersTable.columns, indexedColumns);
+
+      // Test various builder methods
+      expect(builder.isNull("email")).toEqual({
+        type: "compare",
+        a: usersTable.columns.email,
+        operator: "is",
+        b: null,
+      });
+
+      expect(builder.isNotNull("name")).toEqual({
+        type: "compare",
+        a: usersTable.columns.name,
+        operator: "is not",
+        b: null,
+      });
+
+      const orCondition = builder.or(
+        builder("email", "contains", "gmail"),
+        builder("email", "contains", "yahoo"),
+      );
+      expect(orCondition).toEqual({
+        type: "or",
+        items: [
+          {
+            type: "compare",
+            a: usersTable.columns.email,
+            operator: "contains",
+            b: "gmail",
+          },
+          {
+            type: "compare",
+            a: usersTable.columns.email,
+            operator: "contains",
+            b: "yahoo",
+          },
+        ],
+      });
+
+      const notCondition = builder.not(builder("name", "=", "Bob"));
+      expect(notCondition).toEqual({
+        type: "not",
+        item: {
+          type: "compare",
+          a: usersTable.columns.name,
+          operator: "=",
+          b: "Bob",
+        },
+      });
+    });
+
+    it("should support array operators on indexed columns", () => {
+      const indexedColumns = new Set(["name"]);
+      const builder = createIndexedBuilder(usersTable.columns, indexedColumns);
+
+      const condition = builder("name", "in", ["Alice", "Bob", "Charlie"]);
+      expect(condition).toEqual({
+        type: "compare",
+        a: usersTable.columns.name,
+        operator: "in",
+        b: ["Alice", "Bob", "Charlie"],
+      });
+    });
+
+    it("should allow empty indexed columns set to reject all comparisons", () => {
+      const indexedColumns = new Set<string>();
+      const builder = createIndexedBuilder(usersTable.columns, indexedColumns);
+
+      expect(() => builder("id", "=", "123")).toThrow(
+        'Column "id" is not indexed. Only indexed columns can be used in Unit of Work queries. Available indexed columns: ',
+      );
+    });
+  });
+});

package/src/query/condition-builder.ts

@@ -0,0 +1,294 @@
+import type { AnyColumn, FragnoId, IdColumn } from "../schema/create";
+
+export type ConditionType = "compare" | "and" | "or" | "not";
+
+export type Condition =
+  | {
+      type: "compare";
+      a: AnyColumn;
+      operator: Operator;
+      b: AnyColumn | unknown | null;
+    }
+  | {
+      type: "or" | "and";
+      items: Condition[];
+    }
+  | {
+      type: "not";
+      item: Condition;
+    };
+
+// TODO: we temporarily dropped support for comparing against another column, because Prisma ORM still have problems with it.
+
+/**
+ * Helper type that allows FragnoId for ID columns and reference columns (bigint).
+ * Used in ConditionBuilder to accept FragnoId values in where conditions.
+ */
+type AcceptsFragnoId<T extends AnyColumn> = T extends IdColumn
+  ? T["$in"] | FragnoId
+  : T["$in"] extends bigint
+    ? T["$in"] | FragnoId
+    : T["$in"];
+
+export type ConditionBuilder<Columns extends Record<string, AnyColumn>> = {
+  <ColName extends keyof Columns>(
+    a: ColName,
+    operator: (typeof valueOperators)[number] | (typeof stringOperators)[number],
+    b: AcceptsFragnoId<Columns[ColName]> | null,
+  ): Condition;
+
+  <ColName extends keyof Columns>(
+    a: ColName,
+    operator: (typeof arrayOperators)[number],
+    b: AcceptsFragnoId<Columns[ColName]>[],
+  ): Condition;
+
+  /**
+   * Boolean values
+   */
+  <ColName extends keyof Columns>(a: ColName): Condition;
+
+  and: (...v: (Condition | boolean)[]) => Condition | boolean;
+  or: (...v: (Condition | boolean)[]) => Condition | boolean;
+  not: (v: Condition | boolean) => Condition | boolean;
+
+  isNull: (a: keyof Columns) => Condition;
+  isNotNull: (a: keyof Columns) => Condition;
+};
+
+// replacement for `like` (Prisma doesn't support `like`)
+const stringOperators = [
+  "contains",
+  "starts with",
+  "ends with",
+
+  "not contains",
+  "not starts with",
+  "not ends with",
+  // excluded `regexp` since MSSQL doesn't support it, may re-consider
+] as const;
+
+const arrayOperators = ["in", "not in"] as const;
+
+const valueOperators = ["=", "!=", ">", ">=", "<", "<=", "is", "is not"] as const;
+
+// JSON specific operators are not included, some databases don't support them
+// `match` requires additional extensions & configurations on SQLite and PostgreSQL
+// MySQL & SQLite requires workarounds to support `ilike`
+export const operators = [...valueOperators, ...arrayOperators, ...stringOperators] as const;
+
+export type Operator = (typeof operators)[number];
+
+export function createBuilder<Columns extends Record<string, AnyColumn>>(
+  columns: Columns,
+): ConditionBuilder<Columns> {
+  function col(name: keyof Columns) {
+    const out = columns[name];
+    if (!out) {
+      throw new Error(`Invalid column name ${String(name)}`);
+    }
+
+    return out;
+  }
+
+  const builder: ConditionBuilder<Columns> = (...args: [string, Operator, unknown] | [string]) => {
+    if (args.length === 3) {
+      const [a, operator, b] = args;
+
+      if (!operators.includes(operator)) throw new Error(`Unsupported operator: ${operator}`);
+
+      return {
+        type: "compare",
+        a: col(a),
+        b,
+        operator,
+      };
+    }
+
+    return {
+      type: "compare",
+      a: col(args[0]),
+      operator: "=",
+      b: true,
+    };
+  };
+
+  builder.isNull = (a) => builder(a, "is", null);
+  builder.isNotNull = (a) => builder(a, "is not", null);
+  builder.not = (condition) => {
+    if (typeof condition === "boolean") return !condition;
+
+    return {
+      type: "not",
+      item: condition,
+    };
+  };
+
+  builder.or = (...conditions) => {
+    const out = {
+      type: "or",
+      items: [] as Condition[],
+    } as const;
+
+    for (const item of conditions) {
+      if (item === true) return true;
+      if (item === false) continue;
+
+      out.items.push(item);
+    }
+
+    if (out.items.length === 0) return false;
+    return out;
+  };
+
+  builder.and = (...conditions) => {
+    const out = {
+      type: "and",
+      items: [] as Condition[],
+    } as const;
+
+    for (const item of conditions) {
+      if (item === true) continue;
+      if (item === false) return false;
+
+      out.items.push(item);
+    }
+
+    if (out.items.length === 0) return true;
+    return out;
+  };
+
+  return builder;
+}
+
+export function buildCondition<T, Columns extends Record<string, AnyColumn>>(
+  columns: Columns,
+  input: (builder: ConditionBuilder<Columns>) => T,
+): T {
+  return input(createBuilder(columns));
+}
+
+/**
+ * Create a ConditionBuilder that only allows comparisons on indexed columns.
+ * Used in Unit of Work to ensure queries can leverage indexes for optimal performance.
+ *
+ * @param columns - The full set of columns from the table
+ * @param indexedColumnNames - Set of column names that are part of indexes
+ * @returns A ConditionBuilder restricted to indexed columns only
+ *
+ * @example
+ * ```ts
+ * const builder = createIndexedBuilder(
+ *   table.columns,
+ *   new Set(["id", "userId", "createdAt"])
+ * );
+ * const condition = builder("userId", "=", "123");
+ * ```
+ */
+export function createIndexedBuilder<Columns extends Record<string, AnyColumn>>(
+  columns: Columns,
+  indexedColumnNames: Set<string>,
+): ConditionBuilder<Columns> {
+  function col(name: keyof Columns) {
+    const columnName = String(name);
+
+    if (!indexedColumnNames.has(columnName)) {
+      throw new Error(
+        `Column "${columnName}" is not indexed. Only indexed columns can be used in Unit of Work queries. ` +
+          `Available indexed columns: ${Array.from(indexedColumnNames).join(", ")}`,
+      );
+    }
+
+    const out = columns[name];
+    if (!out) {
+      throw new Error(`Invalid column name ${columnName}`);
+    }
+
+    return out;
+  }
+
+  const builder: ConditionBuilder<Columns> = (...args: [string, Operator, unknown] | [string]) => {
+    if (args.length === 3) {
+      const [a, operator, b] = args;
+
+      if (!operators.includes(operator)) {
+        throw new Error(`Unsupported operator: ${operator}`);
+      }
+
+      return {
+        type: "compare",
+        a: col(a),
+        b,
+        operator,
+      };
+    }
+
+    return {
+      type: "compare",
+      a: col(args[0]),
+      operator: "=",
+      b: true,
+    };
+  };
+
+  builder.isNull = (a) => builder(a, "is", null);
+  builder.isNotNull = (a) => builder(a, "is not", null);
+  builder.not = (condition) => {
+    if (typeof condition === "boolean") {
+      return !condition;
+    }
+
+    return {
+      type: "not",
+      item: condition,
+    };
+  };
+
+  builder.or = (...conditions) => {
+    const out = {
+      type: "or",
+      items: [] as Condition[],
+    } as const;
+
+    for (const item of conditions) {
+      if (item === true) {
+        return true;
+      }
+      if (item === false) {
+        continue;
+      }
+
+      out.items.push(item);
+    }
+
+    if (out.items.length === 0) {
+      return false;
+    }
+    return out;
+  };
+
+  builder.and = (...conditions) => {
+    const out = {
+      type: "and",
+      items: [] as Condition[],
+    } as const;
+
+    for (const item of conditions) {
+      if (item === true) {
+        continue;
+      }
+      if (item === false) {
+        return false;
+      }
+
+      out.items.push(item);
+    }
+
+    if (out.items.length === 0) {
+      return true;
+    }
+    return out;
+  };
+
+  return builder;
+}