@fragno-dev/db 0.0.1 → 0.1.0

package/src/query/query-type.test.ts

@@ -0,0 +1,429 @@
+import { describe, expectTypeOf, it } from "vitest";
+import { column, FragnoId, idColumn, referenceColumn, schema } from "../schema/create";
+import type {
+  AbstractQuery,
+  FindFirstOptions,
+  FindManyOptions,
+  JoinBuilder,
+  OrderBy,
+  SelectClause,
+  TableToInsertValues,
+} from "./query";
+import type { ConditionBuilder } from "./condition-builder";
+
+describe("query type tests", () => {
+  // Create test schema
+  const _testSchema = schema((s) => {
+    return s
+      .addTable("users", (t) => {
+        return t
+          .addColumn("_id", idColumn())
+          .addColumn("name", column("string"))
+          .addColumn("email", column("string"))
+          .addColumn("age", column("integer").nullable())
+          .addColumn("isActive", column("bool"));
+      })
+      .addTable("posts", (t) => {
+        return t
+          .addColumn("_id", idColumn())
+          .addColumn("title", column("string"))
+          .addColumn("content", column("string"))
+          .addColumn("userId", column("string"))
+          .addColumn("publishedAt", column("timestamp").nullable())
+          .addColumn("viewCount", column("integer"));
+      })
+      .addTable("comments", (t) => {
+        return t
+          .addColumn("_id", idColumn())
+          .addColumn("postId", column("string"))
+          .addColumn("authorId", column("string"))
+          .addColumn("text", column("string"))
+          .addColumn("likes", column("integer").nullable());
+      });
+  });
+
+  type TestSchema = typeof _testSchema;
+
+  describe("SelectClause", () => {
+    it("should allow true for selecting all columns", () => {
+      expectTypeOf<true>().toExtend<SelectClause<TestSchema["tables"]["users"]>>();
+    });
+
+    it("should allow array of column names", () => {
+      expectTypeOf<["name", "email"]>().toExtend<SelectClause<TestSchema["tables"]["users"]>>();
+    });
+
+    it("should not allow invalid column names", () => {
+      expectTypeOf<["invalid"]>().not.toEqualTypeOf<SelectClause<TestSchema["tables"]["users"]>>();
+    });
+  });
+
+  describe("OrderBy", () => {
+    it("should allow column name with direction", () => {
+      expectTypeOf<["name", "asc"]>().toExtend<
+        OrderBy<keyof TestSchema["tables"]["users"]["columns"]>
+      >();
+      expectTypeOf<["age", "desc"]>().toExtend<
+        OrderBy<keyof TestSchema["tables"]["users"]["columns"]>
+      >();
+    });
+  });
+
+  describe("FindManyOptions", () => {
+    it("should not allow offset when IsRoot is false", () => {
+      type _NonRootOptions = FindManyOptions<TestSchema["tables"]["users"], true, object, false>;
+
+      expectTypeOf<_NonRootOptions>().not.toHaveProperty("offset");
+    });
+  });
+
+  describe("FindFirstOptions", () => {
+    it("should omit limit from FindManyOptions", () => {
+      expectTypeOf<FindFirstOptions<TestSchema["tables"]["users"]>>().not.toHaveProperty("limit");
+    });
+
+    it("should omit orderBy and offset when IsRoot is false", () => {
+      type _NonRootOptions = FindFirstOptions<TestSchema["tables"]["users"], true, object, false>;
+
+      expectTypeOf<_NonRootOptions>().not.toHaveProperty("limit");
+      expectTypeOf<_NonRootOptions>().not.toHaveProperty("orderBy");
+      expectTypeOf<_NonRootOptions>().not.toHaveProperty("offset");
+    });
+  });
+
+  describe("AbstractQuery methods", () => {
+    type Query = AbstractQuery<TestSchema>;
+
+    describe("findFirst", () => {
+      it("should return all columns when select is true or undefined", () => {
+        const _query = {} as Query;
+        type Result = Awaited<ReturnType<typeof _query.findFirst<"users">>>;
+
+        expectTypeOf<Result>().toExtend<{
+          _id: FragnoId;
+          name: string;
+          email: string;
+          age: number | null;
+          isActive: boolean;
+        } | null>();
+      });
+
+      it("should return selected columns only", () => {
+        const _query = {} as Query;
+
+        type Result = Awaited<ReturnType<typeof _query.findFirst<"users", ["name", "email"]>>>;
+
+        expectTypeOf<Result>().toExtend<{
+          name: string;
+          email: string;
+        } | null>();
+      });
+
+      it("should handle nullable columns correctly", () => {
+        const _query = {} as Query;
+
+        type Result = Awaited<ReturnType<typeof _query.findFirst<"users", ["age"]>>>;
+        type NonNullResult = Exclude<Result, null>;
+
+        expectTypeOf<NonNullResult>().toMatchTypeOf<{ age: number | null }>();
+      });
+    });
+
+    describe("find", () => {
+      it("should return array of all columns when select is true or undefined", () => {
+        const _query = {} as Query;
+        type Result = Awaited<ReturnType<typeof _query.find<"users">>>;
+
+        expectTypeOf<Result>().toExtend<
+          {
+            _id: FragnoId;
+            name: string;
+            email: string;
+            age: number | null;
+            isActive: boolean;
+          }[]
+        >();
+      });
+
+      it("should return array of selected columns only", () => {
+        const _query = {} as Query;
+
+        type Result = Awaited<ReturnType<typeof _query.find<"users", ["name", "email"], object>>>;
+
+        expectTypeOf<Result>().toExtend<
+          {
+            name: string;
+            email: string;
+          }[]
+        >();
+      });
+    });
+
+    describe("create", () => {
+      it("should require non-nullable columns and allow omitting nullable columns", () => {
+        const _query = {} as Query;
+
+        type Params = Parameters<typeof _query.create<"users">>[1];
+
+        // TODO: This could be better
+        expectTypeOf<{
+          [x: string]: unknown;
+          age?: number | null | undefined;
+          _id: FragnoId;
+          name: string;
+          email: string;
+          isActive: boolean;
+        }>().toExtend<Params>();
+      });
+
+      it("should return the created ID", () => {
+        const _query = {} as Query;
+        type Result = Awaited<ReturnType<typeof _query.create<"users">>>;
+
+        expectTypeOf<Result>().toEqualTypeOf<FragnoId>();
+      });
+
+      it("should handle posts table correctly", () => {
+        const _query = {} as Query;
+
+        type Params = Parameters<typeof _query.create<"posts">>[1];
+
+        expectTypeOf<{
+          publishedAt?: Date | null | undefined;
+          likes?: number | null | undefined;
+          _id: FragnoId;
+          title: string;
+          content: string;
+          userId: string;
+          viewCount: number;
+        }>().toExtend<Params>();
+      });
+    });
+
+    describe("createMany", () => {
+      it("should accept array of insert values", () => {
+        const _query = {} as Query;
+
+        type Params = Parameters<typeof _query.createMany<"users">>[1];
+
+        expectTypeOf<
+          {
+            name: string;
+            age?: number | null | undefined;
+            _id: FragnoId;
+            email: string;
+            isActive: boolean;
+          }[]
+        >().toExtend<Params>();
+
+        type Result = Awaited<ReturnType<typeof _query.createMany<"users">>>;
+        // createMany returns array of IDs
+        expectTypeOf<Result>().toEqualTypeOf<FragnoId[]>();
+      });
+    });
+
+    describe("updateMany", () => {
+      it("should accept a builder function", () => {
+        const _query = {} as Query;
+
+        // updateMany accepts a builder function, not an options object
+        type Params = Parameters<typeof _query.updateMany<"users">>;
+
+        // Check that updateMany takes correct parameters
+        expectTypeOf<Params[0]>().toEqualTypeOf<"users">();
+        expectTypeOf<Params[1]>().toBeFunction();
+      });
+    });
+  });
+
+  describe("table name type checking", () => {
+    it("should only allow valid table names", () => {
+      const _query = {} as AbstractQuery<TestSchema>;
+
+      // Valid table names
+      type UsersParam = Parameters<typeof _query.find<"users">>;
+      type PostsParam = Parameters<typeof _query.find<"posts">>;
+      type CommentsParam = Parameters<typeof _query.find<"comments">>;
+
+      expectTypeOf<UsersParam>().not.toEqualTypeOf<never>();
+      expectTypeOf<PostsParam>().not.toEqualTypeOf<never>();
+      expectTypeOf<CommentsParam>().not.toEqualTypeOf<never>();
+    });
+  });
+
+  describe("column type inference", () => {
+    it("should correctly infer column types for users table", () => {
+      const _query = {} as AbstractQuery<TestSchema>;
+      type Result = Awaited<ReturnType<typeof _query.findFirst<"users">>>;
+      type User = Exclude<Result, null>;
+
+      expectTypeOf<User["_id"]>().toEqualTypeOf<FragnoId>();
+      expectTypeOf<User["name"]>().toEqualTypeOf<string>();
+      expectTypeOf<User["email"]>().toEqualTypeOf<string>();
+      expectTypeOf<User["age"]>().toEqualTypeOf<number | null>();
+      expectTypeOf<User["isActive"]>().toEqualTypeOf<boolean>();
+    });
+
+    it("should correctly infer column types for posts table", () => {
+      const _query = {} as AbstractQuery<TestSchema>;
+      type Result = Awaited<ReturnType<typeof _query.findFirst<"posts">>>;
+      type Post = Exclude<Result, null>;
+
+      expectTypeOf<Post["_id"]>().toEqualTypeOf<FragnoId>();
+      expectTypeOf<Post["title"]>().toEqualTypeOf<string>();
+      expectTypeOf<Post["content"]>().toEqualTypeOf<string>();
+      expectTypeOf<Post["userId"]>().toEqualTypeOf<string>();
+      expectTypeOf<Post["publishedAt"]>().toEqualTypeOf<Date | null>();
+      expectTypeOf<Post["viewCount"]>().toEqualTypeOf<number>();
+    });
+
+    it("should correctly infer column types for comments table", () => {
+      const _query = {} as AbstractQuery<TestSchema>;
+      type Result = Awaited<ReturnType<typeof _query.findFirst<"comments">>>;
+      type Comment = Exclude<Result, null>;
+
+      expectTypeOf<Comment["_id"]>().toEqualTypeOf<FragnoId>();
+      expectTypeOf<Comment["postId"]>().toEqualTypeOf<string>();
+      expectTypeOf<Comment["authorId"]>().toEqualTypeOf<string>();
+      expectTypeOf<Comment["text"]>().toEqualTypeOf<string>();
+      expectTypeOf<Comment["likes"]>().toEqualTypeOf<number | null>();
+    });
+  });
+
+  describe("complex scenarios", () => {
+    it("should handle multiple table operations with correct types", () => {
+      const _query = {} as AbstractQuery<TestSchema>;
+
+      // Create user return type
+      type UserResult = Awaited<ReturnType<typeof _query.create<"users">>>;
+      expectTypeOf<UserResult>().toEqualTypeOf<FragnoId>();
+
+      // Create post return type
+      type PostResult = Awaited<ReturnType<typeof _query.create<"posts">>>;
+      expectTypeOf<PostResult>().toEqualTypeOf<FragnoId>();
+
+      // Find posts by user return type
+      type UserPostsResult = Awaited<
+        ReturnType<typeof _query.find<"posts", ["title", "viewCount"], object>>
+      >;
+
+      expectTypeOf<UserPostsResult>().toExtend<
+        {
+          title: string;
+          viewCount: number;
+        }[]
+      >();
+    });
+  });
+
+  describe("join", () => {
+    const userSchema = schema((s) => {
+      return s
+        .addTable("users", (t) => {
+          return t.addColumn("id", idColumn()).addColumn("name", column("string"));
+        })
+        .addTable("posts", (t) => {
+          return t
+            .addColumn("id", idColumn())
+            .addColumn("title", column("string"))
+            .addColumn("userId", referenceColumn());
+        })
+        .addTable("tags", (t) => {
+          return t.addColumn("id", idColumn()).addColumn("name", column("string"));
+        })
+        .addReference("author", {
+          type: "one",
+          from: { table: "posts", column: "userId" },
+          to: { table: "users", column: "id" },
+        });
+    });
+
+    it("should handle join correctly", () => {
+      const _table = userSchema.tables.posts;
+      const _relations = _table.relations;
+
+      type _Relations = typeof _table.relations;
+      type Builder1 = JoinBuilder<typeof _table>;
+
+      expectTypeOf<Builder1>().toExtend<{
+        author: () => void;
+      }>();
+    });
+  });
+
+  describe("FragnoId support", () => {
+    it("should accept FragnoId in insert values for id column", () => {
+      const fragnoId = FragnoId.fromExternal("user123", 0);
+      const _values: TableToInsertValues<typeof _testSchema.tables.users> = {
+        _id: fragnoId,
+        name: "John",
+        email: "john@example.com",
+        isActive: true,
+      };
+      // Verify the type accepts both string and FragnoId
+      type IdType = TableToInsertValues<typeof _testSchema.tables.users>["_id"];
+      expectTypeOf<string>().toExtend<IdType>();
+      expectTypeOf<FragnoId>().toExtend<IdType>();
+    });
+
+    it("should accept string in insert values for id column", () => {
+      const _values: TableToInsertValues<typeof _testSchema.tables.users> = {
+        _id: "user123",
+        name: "John",
+        email: "john@example.com",
+        isActive: true,
+      };
+      // Verify string is accepted
+      type IdType = TableToInsertValues<typeof _testSchema.tables.users>["_id"];
+      expectTypeOf<string>().toExtend<IdType>();
+    });
+
+    it("should accept FragnoId in where conditions", () => {
+      const fragnoId = FragnoId.fromExternal("user123", 0);
+      // This should compile without errors
+      const condition = (eb: ConditionBuilder<typeof _testSchema.tables.users.columns>) =>
+        eb("_id", "=", fragnoId);
+      expectTypeOf(condition).toBeFunction();
+    });
+
+    it("should accept FragnoId in array where conditions", () => {
+      const fragnoId1 = FragnoId.fromExternal("user123", 0);
+      const fragnoId2 = FragnoId.fromExternal("user456", 0);
+      // This should compile without errors
+      const condition = (eb: ConditionBuilder<typeof _testSchema.tables.users.columns>) =>
+        eb("_id", "in", [fragnoId1, fragnoId2, "user789"]);
+      expectTypeOf(condition).toBeFunction();
+    });
+
+    it("should accept FragnoId with both external and internal IDs", () => {
+      const fragnoId = new FragnoId({
+        externalId: "user123",
+        internalId: 1n,
+        version: 1,
+      });
+      const _values: TableToInsertValues<typeof _testSchema.tables.posts> = {
+        _id: fragnoId,
+        title: "Test Post",
+        content: "Content",
+        userId: "user123",
+        viewCount: 0,
+      };
+      // Verify FragnoId is accepted for id columns
+      type IdType = TableToInsertValues<typeof _testSchema.tables.posts>["_id"];
+      expectTypeOf<FragnoId>().toExtend<IdType>();
+    });
+
+    it("should not accept FragnoId for non-id columns", () => {
+      const _values: TableToInsertValues<typeof _testSchema.tables.users> = {
+        _id: "user123",
+        name: "John",
+        email: "john@example.com",
+        isActive: true,
+      };
+      // This should be a type error if we try to use FragnoId for name
+      type NameType = TableToInsertValues<typeof _testSchema.tables.users>["name"];
+      expectTypeOf<NameType>().toExtend<string>();
+      expectTypeOf<NameType>().not.toExtend<FragnoId>();
+    });
+  });
+});

package/src/query/query.ts

@@ -0,0 +1,200 @@
+import type { IdColumn, AnySchema, AnyTable, Relation, FragnoId } from "../schema/create";
+import type { Condition, ConditionBuilder } from "./condition-builder";
+import type {
+  UnitOfWork,
+  FindBuilder,
+  UpdateBuilder,
+  DeleteBuilder,
+  UpdateManyBuilder,
+} from "./unit-of-work";
+import type { Prettify } from "../util/types";
+
+export type AnySelectClause = SelectClause<AnyTable>;
+
+export type SelectClause<T extends AnyTable> = true | (keyof T["columns"])[];
+
+export type RawColumnValues<T extends AnyTable> = {
+  [K in keyof T["columns"] as string extends K ? never : K]: T["columns"][K]["$out"];
+};
+
+export type TableToColumnValues<T extends AnyTable> = RawColumnValues<T>;
+
+type PickNullable<T> = {
+  [P in keyof T as null extends T[P] ? P : never]: T[P];
+};
+
+type PickNotNullable<T> = {
+  [P in keyof T as null extends T[P] ? never : P]: T[P];
+};
+
+type RawInsertValues<T extends AnyTable> = {
+  [K in keyof T["columns"] as string extends K ? never : K]: T["columns"][K]["$in"];
+};
+
+export type TableToInsertValues<T extends AnyTable> = Prettify<
+  Partial<PickNullable<RawInsertValues<T>>> & PickNotNullable<RawInsertValues<T>>
+>;
+
+export type TableToUpdateValues<T extends AnyTable> = {
+  [K in keyof T["columns"] as string extends K ? never : K]?: T["columns"][K] extends IdColumn
+    ? never
+    : T["columns"][K]["$in"];
+};
+
+type MainSelectResult<S extends SelectClause<T>, T extends AnyTable> = S extends true
+  ? TableToColumnValues<T>
+  : S extends (keyof T["columns"])[]
+    ? {
+        [K in S[number] as string extends K ? never : K]: K extends keyof T["columns"]
+          ? T["columns"][K]["$out"]
+          : never;
+      }
+    : never;
+
+export type SelectResult<
+  T extends AnyTable,
+  JoinOut,
+  Select extends SelectClause<T>,
+> = MainSelectResult<Select, T> & JoinOut;
+
+interface MapRelationType<Type> {
+  one: Type | null;
+  many: Type[];
+}
+
+export type JoinBuilder<T extends AnyTable, Out = {}> = {
+  [K in keyof T["relations"]]: T["relations"][K] extends Relation<infer Type, infer Target>
+    ? <Select extends SelectClause<Target> = true, JoinOut = {}>(
+        options?: FindManyOptions<Target, Select, JoinOut, false>,
+      ) => JoinBuilder<
+        T,
+        Out & {
+          [$K in K]: MapRelationType<SelectResult<Target, JoinOut, Select>>[Type];
+        }
+      >
+    : never;
+};
+
+export type OrderBy<Column = string> = [columnName: Column, "asc" | "desc"];
+
+export type FindFirstOptions<
+  T extends AnyTable = AnyTable,
+  Select extends SelectClause<T> = SelectClause<T>,
+  JoinOut = {},
+  IsRoot extends boolean = true,
+> = Omit<
+  FindManyOptions<T, Select, JoinOut, IsRoot>,
+  IsRoot extends true ? "limit" : "limit" | "offset" | "orderBy"
+>;
+
+export type FindManyOptions<
+  T extends AnyTable = AnyTable,
+  Select extends SelectClause<T> = SelectClause<T>,
+  _JoinOut = {},
+  IsRoot extends boolean = true,
+> = {
+  select?: Select;
+  where?: (eb: ConditionBuilder<T["columns"]>) => Condition | boolean;
+  limit?: number;
+  orderBy?: OrderBy<keyof T["columns"]> | OrderBy<keyof T["columns"]>[];
+  join?: (jb: JoinBuilder<T>) => void;
+} & (IsRoot extends true
+  ? {
+      // drizzle doesn't support `offset` in join queries (this may be changed in future, we can add it back)
+      offset?: number;
+    }
+  : {});
+
+export interface AbstractQuery<TSchema extends AnySchema, TUOWConfig = void> {
+  /**
+   * Find multiple records using a builder pattern
+   */
+  find: <
+    TableName extends keyof TSchema["tables"] & string,
+    Select extends SelectClause<TSchema["tables"][TableName]> = true,
+    JoinOut = {},
+  >(
+    table: TableName,
+    builderFn?: (
+      builder: Omit<FindBuilder<TSchema["tables"][TableName]>, "build">,
+    ) => Omit<FindBuilder<TSchema["tables"][TableName], Select, JoinOut>, "build">,
+  ) => Promise<SelectResult<TSchema["tables"][TableName], JoinOut, Select>[]>;
+
+  /**
+   * Find the first record matching the criteria
+   * Implemented as a wrapper around find() with pageSize(1)
+   */
+  findFirst: <
+    TableName extends keyof TSchema["tables"] & string,
+    Select extends SelectClause<TSchema["tables"][TableName]> = true,
+    JoinOut = {},
+  >(
+    table: TableName,
+    builderFn?: (
+      builder: Omit<FindBuilder<TSchema["tables"][TableName]>, "build">,
+    ) => Omit<FindBuilder<TSchema["tables"][TableName], Select, JoinOut>, "build">,
+  ) => Promise<SelectResult<TSchema["tables"][TableName], JoinOut, Select> | null>;
+
+  /**
+   * Create a single record
+   * @returns The ID of the created record
+   */
+  create: <TableName extends keyof TSchema["tables"] & string>(
+    table: TableName,
+    values: TableToInsertValues<TSchema["tables"][TableName]>,
+  ) => Promise<FragnoId>;
+
+  /**
+   * Create multiple records
+   * @returns Array of IDs of the created records
+   */
+  createMany: <TableName extends keyof TSchema["tables"] & string>(
+    table: TableName,
+    values: TableToInsertValues<TSchema["tables"][TableName]>[],
+  ) => Promise<FragnoId[]>;
+
+  /**
+   * Update a single record by ID
+   * Note: you cannot update the id of a row, some databases don't support that (including MongoDB).
+   */
+  update: <TableName extends keyof TSchema["tables"] & string>(
+    table: TableName,
+    id: FragnoId | string,
+    builderFn: (
+      builder: Omit<UpdateBuilder<TSchema["tables"][TableName]>, "build" | "check">,
+    ) => Omit<UpdateBuilder<TSchema["tables"][TableName]>, "build">,
+  ) => Promise<void>;
+
+  /**
+   * Update multiple records matching a where clause
+   * Note: you cannot update the id of a row, some databases don't support that (including MongoDB).
+   */
+  updateMany: <TableName extends keyof TSchema["tables"] & string>(
+    table: TableName,
+    builderFn: (builder: UpdateManyBuilder<TSchema["tables"][TableName]>) => void,
+  ) => Promise<void>;
+
+  /**
+   * Delete a single record by ID
+   */
+  delete: <TableName extends keyof TSchema["tables"] & string>(
+    table: TableName,
+    id: FragnoId | string,
+    builderFn?: (builder: Omit<DeleteBuilder, "build">) => Omit<DeleteBuilder, "build" | "check">,
+  ) => Promise<void>;
+
+  /**
+   * Delete multiple records matching a where clause
+   */
+  deleteMany: <TableName extends keyof TSchema["tables"] & string>(
+    table: TableName,
+    builderFn: (
+      builder: Omit<FindBuilder<TSchema["tables"][TableName]>, "build" | "check">,
+    ) => void,
+  ) => Promise<void>;
+
+  /**
+   * Create a Unit of Work bound to this query engine
+   */
+  createUnitOfWork: (name?: string, config?: TUOWConfig) => UnitOfWork<TSchema, []>;
+}