@fragno-dev/db 0.1.11 → 0.1.12

package/src/query/query.ts

@@ -17,7 +17,7 @@ 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>;
+export type TableToColumnValues<T extends AnyTable> = Prettify<RawColumnValues<T>>;
 
 type PickNullable<T> = {
   [P in keyof T as null extends T[P] ? P : never]: T[P];
@@ -44,18 +44,16 @@ export type TableToUpdateValues<T extends AnyTable> = {
 type MainSelectResult<S extends SelectClause<T>, T extends AnyTable> = S extends true
   ? TableToColumnValues<T>
   : S extends (keyof T["columns"])[]
-    ? {
+    ? Prettify<{
         [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;
+export type SelectResult<T extends AnyTable, JoinOut, Select extends SelectClause<T>> = Prettify<
+  MainSelectResult<Select, T> & JoinOut
+>;
 
 interface MapRelationType<Type> {
   one: Type | null;
@@ -68,15 +66,43 @@ export type JoinBuilder<T extends AnyTable, Out = {}> = {
         options?: FindManyOptions<Target, Select, JoinOut, false>,
       ) => JoinBuilder<
         T,
-        Out & {
-          [$K in K]: MapRelationType<SelectResult<Target, JoinOut, Select>>[Type];
-        }
+        Prettify<
+          Out & {
+            [$K in K]: MapRelationType<SelectResult<Target, JoinOut, Select>>[Type];
+          }
+        >
       >
     : never;
 };
 
 export type OrderBy<Column = string> = [columnName: Column, "asc" | "desc"];
 
+/**
+ * Extract Select type parameter from a FindBuilder type (handles Omit wrapper)
+ * @internal
+ */
+type ExtractSelect<T> =
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  T extends FindBuilder<any, infer TSelect, any>
+    ? TSelect
+    : // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      T extends Omit<FindBuilder<any, infer TSelect, any>, any>
+      ? TSelect
+      : true;
+
+/**
+ * Extract JoinOut type parameter from a FindBuilder type (handles Omit wrapper)
+ * @internal
+ */
+type ExtractJoinOut<T> =
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  T extends FindBuilder<any, any, infer TJoinOut>
+    ? TJoinOut
+    : // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      T extends Omit<FindBuilder<any, any, infer TJoinOut>, any>
+      ? TJoinOut
+      : {};
+
 export type FindFirstOptions<
   T extends AnyTable = AnyTable,
   Select extends SelectClause<T> = SelectClause<T>,
@@ -109,31 +135,48 @@ 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: {
+    // Overload when builder function is provided - infer Select and JoinOut from builder
+    <TableName extends keyof TSchema["tables"] & string, const TBuilderResult>(
+      table: TableName,
+      builderFn: (
+        builder: Omit<FindBuilder<TSchema["tables"][TableName]>, "build">,
+      ) => TBuilderResult,
+    ): Promise<
+      SelectResult<
+        TSchema["tables"][TableName],
+        ExtractJoinOut<TBuilderResult>,
+        Extract<ExtractSelect<TBuilderResult>, SelectClause<TSchema["tables"][TableName]>>
+      >[]
+    >;
+    // Overload when no builder function - return all columns
+    <TableName extends keyof TSchema["tables"] & string>(
+      table: TableName,
+    ): Promise<SelectResult<TSchema["tables"][TableName], {}, true>[]>;
+  };
 
   /**
    * 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>;
+  findFirst: {
+    // Overload when builder function is provided - infer Select and JoinOut from builder
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    <TableName extends keyof TSchema["tables"] & string, const TBuilderResult>(
+      table: TableName,
+      builderFn: (
+        builder: Omit<FindBuilder<TSchema["tables"][TableName]>, "build">,
+      ) => TBuilderResult,
+    ): Promise<SelectResult<
+      TSchema["tables"][TableName],
+      ExtractJoinOut<TBuilderResult>,
+      Extract<ExtractSelect<TBuilderResult>, SelectClause<TSchema["tables"][TableName]>>
+    > | null>;
+    // Overload when no builder function - return all columns
+    <TableName extends keyof TSchema["tables"] & string>(
+      table: TableName,
+    ): Promise<SelectResult<TSchema["tables"][TableName], {}, true> | null>;
+  };
 
   /**
    * Create a single record
@@ -161,8 +204,8 @@ export interface AbstractQuery<TSchema extends AnySchema, TUOWConfig = void> {
     table: TableName,
     id: FragnoId | string,
     builderFn: (
-      builder: Omit<UpdateBuilder<TSchema["tables"][TableName]>, "build" | "check">,
-    ) => Omit<UpdateBuilder<TSchema["tables"][TableName]>, "build" | "check">,
+      builder: Omit<UpdateBuilder<TSchema["tables"][TableName]>, "build">,
+    ) => Omit<UpdateBuilder<TSchema["tables"][TableName]>, "build">,
   ) => Promise<void>;
 
   /**
@@ -180,9 +223,7 @@ export interface AbstractQuery<TSchema extends AnySchema, TUOWConfig = void> {
   delete: <TableName extends keyof TSchema["tables"] & string>(
     table: TableName,
     id: FragnoId | string,
-    builderFn?: (
-      builder: Omit<DeleteBuilder, "build" | "check">,
-    ) => Omit<DeleteBuilder, "build" | "check">,
+    builderFn?: (builder: Omit<DeleteBuilder, "build">) => Omit<DeleteBuilder, "build">,
   ) => Promise<void>;
 
   /**

package/src/query/result-transform.test.ts

@@ -226,7 +226,7 @@ describe("encodeValues", () => {
       });
     });
 
-    it("should fallback to external ID for reference when internal ID unavailable", () => {
+    it("should convert FragnoId without internalId to ReferenceSubquery for reference columns", () => {
       const fragnoId = new FragnoId({
         externalId: "user123",
         version: 1,
@@ -238,10 +238,10 @@ describe("encodeValues", () => {
         "postgresql",
       );
 
-      expect(result).toEqual({
-        title: "Test Post",
-        userId: "user123",
-      });
+      // FragnoId without internalId should be converted to ReferenceSubquery for database lookup
+      expect(result["title"]).toBe("Test Post");
+      expect(result["userId"]).toBeInstanceOf(ReferenceSubquery);
+      expect((result["userId"] as ReferenceSubquery).externalIdValue).toBe("user123");
     });
 
     it("should handle FragnoId across different providers", () => {

package/src/query/result-transform.ts

@@ -123,18 +123,36 @@ export function encodeValues(
     }
 
     if (value !== undefined) {
-      // Handle string references - convert external ID to internal ID via subquery
-      if (col.role === "reference" && typeof value === "string") {
-        // Find relation that uses this column
-        const relation = Object.values(table.relations).find((rel) =>
-          rel.on.some(([localCol]) => localCol === k),
-        );
-        if (relation) {
-          result[col.name] = new ReferenceSubquery(relation.table, value);
-          continue;
+      // Handle string references and FragnoId objects
+      if (col.role === "reference") {
+        if (typeof value === "string") {
+          // String external ID - generate subquery
+          const relation = Object.values(table.relations).find((rel) =>
+            rel.on.some(([localCol]) => localCol === k),
+          );
+          if (relation) {
+            result[col.name] = new ReferenceSubquery(relation.table, value);
+            continue;
+          }
+          throw new Error(`Reference column ${k} not found in table ${table.name}`);
+        } else if (value instanceof FragnoId) {
+          // FragnoId object
+          if (value.internalId !== undefined) {
+            // If internal ID is populated, use it directly (no subquery needed)
+            result[col.name] = value.internalId;
+            continue;
+          } else {
+            // If internal ID is not populated, use external ID via subquery
+            const relation = Object.values(table.relations).find((rel) =>
+              rel.on.some(([localCol]) => localCol === k),
+            );
+            if (relation) {
+              result[col.name] = new ReferenceSubquery(relation.table, value.externalId);
+              continue;
+            }
+            throw new Error(`Reference column ${k} not found in table ${table.name}`);
+          }
         }
-
-        throw new Error(`Reference column ${k} not found in table ${table.name}`);
       }
 
       result[col.name] = serialize(value, col, provider);

package/src/query/unit-of-work.ts

@@ -939,7 +939,7 @@ export class UnitOfWork<
     builderFn?: (
       // We omit "build" because we don't want to expose it to the user
       builder: Omit<FindBuilder<TSchema["tables"][TTableName]>, "build">,
-    ) => Omit<FindBuilder<TSchema["tables"][TTableName], TSelect, TJoinOut>, "build">,
+    ) => Omit<FindBuilder<TSchema["tables"][TTableName], TSelect, TJoinOut>, "build"> | void,
   ): UnitOfWork<
     TSchema,
     [...TRetrievalResults, SelectResult<TSchema["tables"][TTableName], TJoinOut, TSelect>[]],
@@ -985,11 +985,12 @@ export class UnitOfWork<
 
   /**
    * Add a create operation (mutation phase only)
+   * Returns a FragnoId with the external ID that can be used immediately in subsequent operations
    */
   create<TableName extends keyof TSchema["tables"] & string>(
     table: TableName,
     values: TableToInsertValues<TSchema["tables"][TableName]>,
-  ): this {
+  ): FragnoId {
     if (this.#state === "executed") {
       throw new Error(`create() can only be called during mutation phase.`);
     }
@@ -1041,7 +1042,7 @@ export class UnitOfWork<
       generatedExternalId: externalId,
     });
 
-    return this;
+    return FragnoId.fromExternal(externalId, 0);
   }
 
   /**
@@ -1053,8 +1054,8 @@ export class UnitOfWork<
     builderFn: (
       // We omit "build" because we don't want to expose it to the user
       builder: Omit<UpdateBuilder<TSchema["tables"][TableName]>, "build">,
-    ) => Omit<UpdateBuilder<TSchema["tables"][TableName]>, "build">,
-  ): this {
+    ) => Omit<UpdateBuilder<TSchema["tables"][TableName]>, "build"> | void,
+  ): void {
     if (this.#state === "executed") {
       throw new Error(`update() can only be called during mutation phase.`);
     }
@@ -1071,8 +1072,6 @@ export class UnitOfWork<
       checkVersion,
       set,
     });
-
-    return this;
   }
 
   /**
@@ -1084,8 +1083,8 @@ export class UnitOfWork<
     builderFn?: (
       // We omit "build" because we don't want to expose it to the user
       builder: Omit<DeleteBuilder, "build">,
-    ) => Omit<DeleteBuilder, "build">,
-  ): this {
+    ) => Omit<DeleteBuilder, "build"> | void,
+  ): void {
     if (this.#state === "executed") {
       throw new Error(`delete() can only be called during mutation phase.`);
     }
@@ -1101,8 +1100,6 @@ export class UnitOfWork<
       id: opId,
       checkVersion,
     });
-
-    return this;
   }
 
   /**

package/src/schema/serialize.test.ts

@@ -342,6 +342,229 @@ describe("serialize", () => {
         const time = Date.now();
         expect(deserialize(time, dateCol, "sqlite")).toEqual(new Date(time));
       });
+
+      it("should handle ISO string timestamps with positive timezone offset", () => {
+        const timestampCol = column("timestamp");
+        const time = "2024-06-15T14:30:00+05:30"; // India Standard Time
+        const result = deserialize(time, timestampCol, "sqlite");
+        expect(result).toBeInstanceOf(Date);
+        expect(result.toISOString()).toBe("2024-06-15T09:00:00.000Z");
+      });
+
+      it("should handle ISO string timestamps with negative timezone offset", () => {
+        const timestampCol = column("timestamp");
+        const time = "2024-06-15T14:30:00-08:00"; // Pacific Time
+        const result = deserialize(time, timestampCol, "sqlite");
+        expect(result).toBeInstanceOf(Date);
+        expect(result.toISOString()).toBe("2024-06-15T22:30:00.000Z");
+      });
+
+      it("should preserve absolute time when deserializing numeric timestamps", () => {
+        const timestampCol = column("timestamp");
+        // Create a specific date and get its numeric representation
+        const specificDate = new Date("2024-06-15T12:00:00Z");
+        const numericTimestamp = specificDate.getTime();
+
+        const result = deserialize(numericTimestamp, timestampCol, "sqlite");
+        expect(result).toBeInstanceOf(Date);
+        expect(result.getTime()).toBe(numericTimestamp);
+        expect(result.toISOString()).toBe("2024-06-15T12:00:00.000Z");
+      });
+
+      it("should handle round-trip serialization/deserialization with timezones", () => {
+        const timestampCol = column("timestamp");
+        // Start with a date with timezone info
+        const originalTime = "2024-06-15T14:30:00+02:00";
+        const deserialized = deserialize(originalTime, timestampCol, "sqlite");
+
+        // SQLite would store this as a number
+        const numericValue = deserialized.getTime();
+
+        // Deserialize the numeric value back
+        const roundTrip = deserialize(numericValue, timestampCol, "sqlite");
+
+        expect(roundTrip).toBeInstanceOf(Date);
+        expect(roundTrip.getTime()).toBe(deserialized.getTime());
+        expect(roundTrip.toISOString()).toBe(deserialized.toISOString());
+      });
+    });
+
+    describe("postgresql date handling", () => {
+      it("should convert string timestamps to Date", () => {
+        const timestampCol = column("timestamp");
+        const time = "2024-01-01 12:30:45.123";
+        expect(deserialize(time, timestampCol, "postgresql")).toEqual(new Date(time));
+      });
+
+      it("should convert ISO string timestamps to Date", () => {
+        const timestampCol = column("timestamp");
+        const time = "2024-01-01T00:00:00.000Z";
+        expect(deserialize(time, timestampCol, "postgresql")).toEqual(new Date(time));
+      });
+
+      it("should convert date strings to Date", () => {
+        const dateCol = column("date");
+        const time = "2024-01-01";
+        expect(deserialize(time, dateCol, "postgresql")).toEqual(new Date(time));
+      });
+
+      it("should handle timestamps with positive timezone offset", () => {
+        const timestampCol = column("timestamp");
+        const time = "2024-06-15T14:30:00+05:30"; // India Standard Time
+        const result = deserialize(time, timestampCol, "postgresql");
+        expect(result).toBeInstanceOf(Date);
+        expect(result.toISOString()).toBe("2024-06-15T09:00:00.000Z");
+      });
+
+      it("should handle timestamps with negative timezone offset", () => {
+        const timestampCol = column("timestamp");
+        const time = "2024-06-15T14:30:00-08:00"; // Pacific Time
+        const result = deserialize(time, timestampCol, "postgresql");
+        expect(result).toBeInstanceOf(Date);
+        expect(result.toISOString()).toBe("2024-06-15T22:30:00.000Z");
+      });
+
+      it("should handle timestamps with fractional seconds and timezone", () => {
+        const timestampCol = column("timestamp");
+        const time = "2024-06-15T14:30:45.123+01:00"; // Central European Time
+        const result = deserialize(time, timestampCol, "postgresql");
+        expect(result).toBeInstanceOf(Date);
+        expect(result.toISOString()).toBe("2024-06-15T13:30:45.123Z");
+        expect(result.getTime()).toBe(new Date("2024-06-15T13:30:45.123Z").getTime());
+      });
+
+      it("should preserve absolute time across timezone conversions", () => {
+        const timestampCol = column("timestamp");
+        // Same absolute time in different timezones
+        const utcTime = "2024-06-15T12:00:00Z";
+        const estTime = "2024-06-15T08:00:00-04:00";
+        const jstTime = "2024-06-15T21:00:00+09:00";
+
+        const utcResult = deserialize(utcTime, timestampCol, "postgresql");
+        const estResult = deserialize(estTime, timestampCol, "postgresql");
+        const jstResult = deserialize(jstTime, timestampCol, "postgresql");
+
+        // All should represent the same absolute time
+        expect(utcResult.getTime()).toBe(estResult.getTime());
+        expect(utcResult.getTime()).toBe(jstResult.getTime());
+        expect(estResult.getTime()).toBe(jstResult.getTime());
+      });
+    });
+
+    describe("mysql date handling", () => {
+      it("should convert string timestamps to Date", () => {
+        const timestampCol = column("timestamp");
+        const time = "2024-01-01 12:30:45";
+        expect(deserialize(time, timestampCol, "mysql")).toEqual(new Date(time));
+      });
+
+      it("should convert ISO string timestamps to Date", () => {
+        const timestampCol = column("timestamp");
+        const time = "2024-01-01T00:00:00.000Z";
+        expect(deserialize(time, timestampCol, "mysql")).toEqual(new Date(time));
+      });
+
+      it("should convert date strings to Date", () => {
+        const dateCol = column("date");
+        const time = "2024-01-01";
+        expect(deserialize(time, dateCol, "mysql")).toEqual(new Date(time));
+      });
+
+      it("should handle timestamps with positive timezone offset", () => {
+        const timestampCol = column("timestamp");
+        const time = "2024-06-15T14:30:00+05:30"; // India Standard Time
+        const result = deserialize(time, timestampCol, "mysql");
+        expect(result).toBeInstanceOf(Date);
+        expect(result.toISOString()).toBe("2024-06-15T09:00:00.000Z");
+      });
+
+      it("should handle timestamps with negative timezone offset", () => {
+        const timestampCol = column("timestamp");
+        const time = "2024-06-15T14:30:00-08:00"; // Pacific Time
+        const result = deserialize(time, timestampCol, "mysql");
+        expect(result).toBeInstanceOf(Date);
+        expect(result.toISOString()).toBe("2024-06-15T22:30:00.000Z");
+      });
+
+      it("should handle timestamps with fractional seconds and timezone", () => {
+        const timestampCol = column("timestamp");
+        const time = "2024-06-15T14:30:45.123+01:00"; // Central European Time
+        const result = deserialize(time, timestampCol, "mysql");
+        expect(result).toBeInstanceOf(Date);
+        expect(result.toISOString()).toBe("2024-06-15T13:30:45.123Z");
+      });
+
+      it("should preserve absolute time across timezone conversions", () => {
+        const timestampCol = column("timestamp");
+        // Same absolute time in different timezones
+        const utcTime = "2024-06-15T12:00:00Z";
+        const cstTime = "2024-06-15T20:00:00+08:00"; // China Standard Time
+        const pstTime = "2024-06-15T04:00:00-08:00"; // Pacific Time
+
+        const utcResult = deserialize(utcTime, timestampCol, "mysql");
+        const cstResult = deserialize(cstTime, timestampCol, "mysql");
+        const pstResult = deserialize(pstTime, timestampCol, "mysql");
+
+        // All should represent the same absolute time
+        expect(utcResult.getTime()).toBe(cstResult.getTime());
+        expect(utcResult.getTime()).toBe(pstResult.getTime());
+        expect(cstResult.getTime()).toBe(pstResult.getTime());
+      });
+    });
+
+    describe("cockroachdb date handling", () => {
+      it("should convert string timestamps to Date", () => {
+        const timestampCol = column("timestamp");
+        const time = "2024-01-01 12:30:45.123";
+        expect(deserialize(time, timestampCol, "cockroachdb")).toEqual(new Date(time));
+      });
+
+      it("should convert date strings to Date", () => {
+        const dateCol = column("date");
+        const time = "2024-01-01";
+        expect(deserialize(time, dateCol, "cockroachdb")).toEqual(new Date(time));
+      });
+
+      it("should handle timestamps with positive timezone offset", () => {
+        const timestampCol = column("timestamp");
+        const time = "2024-06-15T14:30:00+05:30"; // India Standard Time
+        const result = deserialize(time, timestampCol, "cockroachdb");
+        expect(result).toBeInstanceOf(Date);
+        expect(result.toISOString()).toBe("2024-06-15T09:00:00.000Z");
+      });
+
+      it("should handle timestamps with negative timezone offset", () => {
+        const timestampCol = column("timestamp");
+        const time = "2024-06-15T14:30:00-08:00"; // Pacific Time
+        const result = deserialize(time, timestampCol, "cockroachdb");
+        expect(result).toBeInstanceOf(Date);
+        expect(result.toISOString()).toBe("2024-06-15T22:30:00.000Z");
+      });
+
+      it("should handle timestamps with fractional seconds and timezone", () => {
+        const timestampCol = column("timestamp");
+        const time = "2024-06-15T14:30:45.123+01:00"; // Central European Time
+        const result = deserialize(time, timestampCol, "cockroachdb");
+        expect(result).toBeInstanceOf(Date);
+        expect(result.toISOString()).toBe("2024-06-15T13:30:45.123Z");
+      });
+
+      it("should preserve absolute time across timezone conversions", () => {
+        const timestampCol = column("timestamp");
+        // Same absolute time in different timezones
+        const utcTime = "2024-06-15T12:00:00Z";
+        const aestTime = "2024-06-15T22:00:00+10:00"; // Australian Eastern Standard Time
+        const brtTime = "2024-06-15T09:00:00-03:00"; // Brasilia Time
+
+        const utcResult = deserialize(utcTime, timestampCol, "cockroachdb");
+        const aestResult = deserialize(aestTime, timestampCol, "cockroachdb");
+        const brtResult = deserialize(brtTime, timestampCol, "cockroachdb");
+
+        // All should represent the same absolute time
+        expect(utcResult.getTime()).toBe(aestResult.getTime());
+        expect(utcResult.getTime()).toBe(brtResult.getTime());
+        expect(aestResult.getTime()).toBe(brtResult.getTime());
+      });
     });
 
     describe("boolean handling", () => {

package/src/schema/serialize.ts

@@ -300,6 +300,22 @@ export function deserialize(value: unknown, col: AnyColumn, provider: SQLProvide
     return new Date(value);
   }
 
+  if (
+    (provider === "postgresql" || provider === "cockroachdb") &&
+    (col.type === "timestamp" || col.type === "date") &&
+    typeof value === "string"
+  ) {
+    return new Date(value);
+  }
+
+  if (
+    provider === "mysql" &&
+    (col.type === "timestamp" || col.type === "date") &&
+    typeof value === "string"
+  ) {
+    return new Date(value);
+  }
+
   if (col.type === "bool" && typeof value === "number") {
     return value === 1;
   }