kysely-hydrate 0.6.0 → 0.7.2

package/README.md

@@ -136,6 +136,7 @@ type Result = Array<{
   - [Output transformations with `.map()`](#output-transformations-with-map)
   - [Composable mappings with `.with()`](#composable-mappings-with-with)
   - [Hydrated writes](#hydrated-writes)
+  - [Type helpers](#type-helpers)
 - [Hydrators](#hydrators)
   - [Creating hydrators with `createHydrator()`](#creating-hydrators-with-createhydrator)
   - [Manual hydration with `hydrate()`](#manual-hydration-with-hydrate)
@@ -388,11 +389,12 @@ const result = await querySet(db)
 
 ###### Generated SQL strategy:
 
-1 **Inner Query**: Selects the parent rows, applying the `LIMIT 10` here. This
-inner query will include "cardinality-one" joins (`*One()`), so you can use them
-in filtering. "Cardinality-many" filtering joins (`innerJoinMany` or
-`crossJoinMany`) will be converted to a WHERE EXISTS to filter without causing
-row explosion. 2. **Outer Query**: Joins the "many" relations to the limited set of parents.
+1. **Inner Query**: Selects the parent rows, applying the `LIMIT 10` here. This
+   inner query will include "cardinality-one" joins (`*One()`), so you can use them
+   in filtering. "Cardinality-many" filtering joins (`innerJoinMany` or
+   `crossJoinMany`) will be converted to a `WHERE EXISTS` to filter without causing
+   row explosion.
+2. **Outer Query**: Joins the "many" relations to the limited set of parents.
 
 For example, a query for "users who have posted" looks something like this:
 
@@ -544,7 +546,7 @@ Kysely Hydrate how to match the attached rows back to their parents:
 - `matchChild`: the key (or keys) on the attached rows
 - `toParent` (optional): the key (or keys) on the parent rows
 
-If you omit `toParent`, it defaults to the parent collection’s `keyBy` (which
+If you omit `toParent`, it defaults to the parent collection's `keyBy` (which
 itself defaults to `"id"` when available).
 
 ```ts
@@ -596,7 +598,7 @@ type Result = Array<{
 ```
 
 Because the `fetchFn` can be any async function, `.attachMany()` is also useful
-for things that _aren’t_ database rows: HTTP calls, caches, etc.
+for things that _aren't_ database rows: HTTP calls, caches, etc.
 
 ```ts
 // Example: Attach feature flags from a cached HTTP endpoint
@@ -1090,9 +1092,105 @@ type Result = {
 };
 ```
 
+### Type Helpers
+
+Kysely Hydrate provides type helpers that mirror
+[Kysely's type manipulation methods](https://kysely-org.github.io/kysely-apidoc/interfaces/SelectQueryBuilder.html).
+These methods don't change the SQL or have any runtime effect—they only affect TypeScript types.
+
+#### `$castTo<T>()`
+
+Changes the output type of the query. Use this when you know the actual output type better than
+TypeScript can infer. This is unsafe! You can change the type to anything.
+
+```ts
+const users = await querySet(db)
+	.selectAs("user", db.selectFrom("users").select(["id", "name"]))
+	.$castTo<{ id: number; name: string; extra: boolean }>()
+	.execute();
+// ⬇
+type Result = Array<{
+	id: number;
+	name: string;
+	extra: boolean; // You better be sure this is there!
+}>;
+```
+
+See [Kysely's version](https://kysely-org.github.io/kysely-apidoc/interfaces/SelectQueryBuilder.html#castto).
+
+#### `$narrowType<T>()`
+
+Narrows parts of the output type. Useful after `WHERE` clauses that guarantee a
+nullable column is not null.
+
+```ts
+const users = await querySet(db)
+	.selectAs("user", db.selectFrom("users").select(["id", "avatar_url"]))
+	.where("avatar_url", "is not", null)
+	.$narrowType<{ avatar_url: string }>(); // Remove null from the type
+	.execute()
+// ⬇
+type Result = Array<{
+	id: string;
+	avatar_url: string; // No `| null`!
+}>
+```
+
+You can also use Kysely's `NotNull` type:
+
+```ts
+import type { NotNull } from "kysely";
+
+const users = await querySet(db)
+	.selectAs("user", db.selectFrom("users").select(["id", "avatar_url"]))
+	.where("avatar_url", "is not", null)
+	.$narrowType<{ avatar_url: NotNull }>();
+	.execute()
+// ⬇
+type Result = Array<{
+	id: string;
+	avatar_url: string; // No `| null`!
+}>
+```
+
+See [Kysely's version](https://kysely-org.github.io/kysely-apidoc/interfaces/SelectQueryBuilder.html#narrowtype).
+
+#### `$assertType<T>()`
+
+Asserts that the query's output type equals a given type. Unlike `$castTo`, this
+validates structural equality—if the types don't match, you get a compile error. Useful as a strategy for annotating your query sets with their expected return type, and also useful if you run into a dreaded "excessively deep" type instantiation error.
+
+```ts
+type UserDto = { id: number; name: string };
+
+const users = await querySet(db)
+	.selectAs("user", db.selectFrom("users").select(["id", "name"]))
+	.$assertType<UserDto>(); // Compile error if output doesn't match UserDto
+	.execute();
+// ⬇
+type Result = Array<UserDto>
+```
+
+See [Kysely's version](https://kysely-org.github.io/kysely-apidoc/interfaces/SelectQueryBuilder.html#asserttype).
+
+#### `InferOutput<T>`
+
+A type-level helper to extract the output type of a query set.
+
+```ts
+import type { InferOutput } from "kysely-hydrate";
+
+const usersQuery = querySet(db)
+	.selectAs("user", db.selectFrom("users").select(["id", "name"]))
+	.extras({ upperName: (u) => u.name.toUpperCase() });
+
+type User = InferOutput<typeof usersQuery>;
+// type User = { id: number; name: string; upperName: string }
+```
+
 ## Hydrators
 
-The `querySet()` API described above is the happy path when you’re building a
+The `querySet()` API described above is the happy path when you're building a
 query in Kysely and want nested results.
 
 Hydrators are the lower-level API: they let you take _already-fetched_ rows
@@ -1105,7 +1203,7 @@ Use hydrators when:
 - You want to define reusable hydration logic independent of any particular query.
 
 > [!NOTE]
-> Hydrators don’t “know” what you selected. Unlike `querySet()`, you need to
+> Hydrators don't "know" what you selected. Unlike `querySet()`, you need to
 > specify what you want in the output using `.fields()` (and/or `.extras()`).
 
 ### Creating hydrators with `createHydrator()`
@@ -1276,7 +1374,7 @@ mapped.extend(...);       // Error: Property 'extend' does not exist
 ### Attached collections with `.attach*()`
 
 These work the same as in the `querySet()` API (see the `.attach*()` section above).
-They’re useful when your “rows” come from somewhere other than SQL, but you still
+They're useful when your "rows" come from somewhere other than SQL, but you still
 want to batch-fetch and attach related data.
 
 ### Prefixed collections with `.has*()`
@@ -1329,11 +1427,11 @@ know the difference, and so does not suffer from this problem.
 
 Merges two hydrators. The second hydrator's configuration takes precedence.
 
-This is a good way to build small, reusable hydrators (for a “user preview”, a
-“user display name”, etc.) and compose them.
+This is a good way to build small, reusable hydrators (for a "user preview", a
+"user display name", etc.) and compose them.
 
 > [!NOTE]
-> Hydrators must have the same `keyBy`. If they don’t, `.extend()` throws.
+> Hydrators must have the same `keyBy`. If they don't, `.extend()` throws.
 
 ```ts
 type UserRow = { id: number; username: string; email: string };

package/dist/index.d.mts

@@ -22,7 +22,24 @@ type SelectAndStripPrefix<P extends string, T> = { [K in keyof T as K extends `$
 type DrainOuterGeneric<T> = [T] extends [unknown] ? T : never;
 type Identity<T> = T;
 type Flatten<T> = Identity<{ [k in keyof T]: T[k] }>;
-type Extend<A, B> = Flatten<keyof A & keyof B extends never ? A & B : { [K in keyof A | keyof B]: K extends keyof B ? B[K] : K extends keyof A ? A[K] : never }>;
+/**
+ * Type-level error message. Cloned from Kysely since it's not exported.
+ */
+interface TypeErrorMessage<E extends string> {
+  readonly __typeError__: E;
+}
+/**
+ * Narrows a type by intersecting with another type, with validation.
+ * Cloned from Kysely's NarrowPartial since it's not exported.
+ *
+ * Unlike a simple intersection, this:
+ * - Validates that narrowing types are subsets of original types
+ * - Supports `k.NotNull` to exclude null from nullable fields
+ * - Produces readable error messages for invalid narrowing
+ */
+type NarrowPartial<O$1, T> = DrainOuterGeneric<T extends object ? { [K in keyof O$1 & string]: K extends keyof T ? T[K] extends k.NotNull ? Exclude<O$1[K], null> : T[K] extends O$1[K] ? T[K] : TypeErrorMessage<`$narrowType() call failed: passed type does not exist in '${K}'s type union`> : O$1[K] } : never>;
+type Extend<A, B> = Flatten<RawExtend<A, B>>;
+type RawExtend<A, B> = keyof A & keyof B extends never ? A & B : { [K in keyof A | keyof B]: K extends keyof B ? B[K] : K extends keyof A ? A[K] : never };
 type ExtendWith<T, K$1 extends PropertyKey, V> = Flatten<K$1 & keyof T extends never ? T & { [_ in K$1]: V } : Omit<T, K$1> & { [_ in K$1]: V }>;
 /**
  * Ensures that U is a strict subset of T - all keys in U must exist in T
@@ -566,13 +583,18 @@ interface TQuerySet {
    * The final shape of the hydrated output row.
    */
   HydratedOutput: any;
+  /**
+   * Keys that have been omitted from the output. Tracked separately so they
+   * can be preserved through base query changes (e.g., .insert(), .update()).
+   */
+  OmittedKeys: PropertyKey;
 }
 interface TSelectQuerySet extends TQuerySet {
   BaseQuery: TSelectQuery;
 }
 type QuerySetFor<T extends TQuerySet> = T["IsMapped"] extends true ? MappedQuerySet<T> : QuerySet<T>;
 type TInput<T extends TQuerySet> = T["JoinedQuery"]["O"];
-type TOutput<T extends TQuerySet> = Flatten<T["HydratedOutput"]>;
+type TOutput<T extends TQuerySet> = T["HydratedOutput"];
 interface TMapped<in out T extends TQuerySet, in out Output> {
   DB: T["DB"];
   IsMapped: true;
@@ -582,6 +604,7 @@ interface TMapped<in out T extends TQuerySet, in out Output> {
   JoinedQuery: T["JoinedQuery"];
   OrderableColumns: T["OrderableColumns"];
   HydratedOutput: Output;
+  OmittedKeys: T["OmittedKeys"];
 }
 interface TJoinedQueryWithBaseQuery<in out BaseAlias extends string, in out JoinedQuery extends TQuery, in out BaseQuery extends TQuery> {
   Type: "Select";
@@ -598,7 +621,8 @@ interface TWithBaseQuery<in out T extends TQuerySet, in out BaseQuery extends TQ
   Collections: T["Collections"];
   JoinedQuery: TJoinedQueryWithBaseQuery<T["BaseAlias"], T["JoinedQuery"], BaseQuery>;
   OrderableColumns: T["OrderableColumns"] | (keyof BaseQuery["O"] & string);
-  HydratedOutput: Extend<BaseQuery["O"], TOutput<T>>;
+  HydratedOutput: Flatten<Omit<RawExtend<BaseQuery["O"], T["HydratedOutput"]>, T["OmittedKeys"]>>;
+  OmittedKeys: T["OmittedKeys"];
 }
 interface TWithOutput<in out T extends TQuerySet, in out Output> {
   DB: T["DB"];
@@ -609,6 +633,7 @@ interface TWithOutput<in out T extends TQuerySet, in out Output> {
   JoinedQuery: T["JoinedQuery"];
   OrderableColumns: T["OrderableColumns"];
   HydratedOutput: Output;
+  OmittedKeys: T["OmittedKeys"];
 }
 interface TWithExtendedOutput<in out T extends TQuerySet, in out Output> {
   DB: T["DB"];
@@ -619,7 +644,20 @@ interface TWithExtendedOutput<in out T extends TQuerySet, in out Output> {
   JoinedQuery: T["JoinedQuery"];
   OrderableColumns: T["OrderableColumns"];
   HydratedOutput: Extend<T["HydratedOutput"], Output>;
+  OmittedKeys: T["OmittedKeys"];
+}
+interface TWithOmit<in out T extends TQuerySet, in out K$1 extends PropertyKey> {
+  DB: T["DB"];
+  IsMapped: T["IsMapped"];
+  BaseAlias: T["BaseAlias"];
+  BaseQuery: T["BaseQuery"];
+  Collections: T["Collections"];
+  JoinedQuery: T["JoinedQuery"];
+  OrderableColumns: T["OrderableColumns"];
+  HydratedOutput: Flatten<Omit<T["HydratedOutput"], K$1>>;
+  OmittedKeys: T["OmittedKeys"] | K$1;
 }
+type NarrowOutput<T extends TQuerySet, Narrow> = NarrowPartial<T["HydratedOutput"], Narrow>;
 interface InitialJoinedQuery<in out DB$1, in out BaseAlias extends string, in out BaseO> {
   Type: "Select";
   DB: DB$1 & { [K in BaseAlias]: BaseO };
@@ -649,6 +687,32 @@ type OpaqueExistsQueryBuilder = OpaqueSelectQueryBuilder<{
  * A limit or offset value, passable to `.limit()` and `.offset()`.
  */
 type LimitOrOffset = number | bigint | null;
+/**
+ * Infer the output type of a query set.  This is the type of one hydrated row.  It's the same as
+ * the type returned by `.executeTakeFirstOrThrow()`.
+ *
+ * **Example:**
+ * ```ts
+ * const usersQuerySet = querySet(db)
+ *   .selectAs("user", db.selectFrom("users").select(["id", "username"]))
+ *
+ * type User = InferOutput<typeof usersQuerySet>;
+ * // ⬇
+ * type User = { id: number; username: string };
+ * ```
+ */
+type InferOutput<Q extends {
+  _generics: TQuerySet | undefined;
+}> = Q extends {
+  _generics: {
+    HydratedOutput: infer O;
+  } | undefined;
+} ? O : never;
+/**
+ * Given a TQuerySet, return a QuerySet or MappedQuerySet depending on whether the query set has
+ * been mapped (indicated by T["IsMapped"]).
+ */
+type MaybeMappedQuerySet<T extends TQuerySet> = T["IsMapped"] extends true ? MappedQuerySet<T> : QuerySet<T>;
 /**
  * A query set that has been mapped with a transformation function.
  *
@@ -1176,6 +1240,39 @@ interface MappedQuerySet<in out T extends TQuerySet> extends k.Compilable, k.Ope
    * Calls a callback with the query set and returns the result.  Like {@link k.SelectQueryBuilder.$call}.
    */
   $call<R>(callback: (qs: this) => R): R;
+  /**
+   * Changes the output type of the query.
+   *
+   * This method call doesn't change the SQL in any way. This method simply
+   * returns a copy of this query set with a new output type.
+   */
+  $castTo<NewOutput>(): MaybeMappedQuerySet<TWithOutput<T, NewOutput>>;
+  /**
+   * Narrows (parts of) the output type of the query.
+   *
+   * This method call doesn't change the SQL in any way. This method simply
+   * returns a copy of this query set with a narrowed output type.
+   *
+   * See {@link k.SelectQueryBuilder.$narrowType} for more information.
+   */
+  $narrowType<Narrow>(): MaybeMappedQuerySet<TWithOutput<T, NarrowOutput<T, Narrow>>>;
+  /**
+   * Asserts that query's output row type equals the given type `T`.
+   *
+   * This method can be used to simplify excessively complex types to make
+   * TypeScript happy and faster.
+   *
+   * It's also useful as a type guard to ensure a query set matches an expected
+   * shape, similar to annotating a function's return type. For example,
+   * `.$assertType<UserDto>()` will produce a type error if the query's output
+   * doesn't match `UserDto`.
+   *
+   * Using this method doesn't reduce type safety at all. You have to pass in
+   * a type that is structurally equal to the current type.
+   *
+   * See {@link k.SelectQueryBuilder.$assertType} for more information.
+   */
+  $assertType<NewOutput extends TOutput<T>>(): TOutput<T> extends NewOutput ? MaybeMappedQuerySet<TWithOutput<T, NewOutput>> : TypeErrorMessage<"$assertType() call failed: The type passed in is not equal to the output type of the query.">;
   /**
    * Switches the base query to an `INSERT` statement.
    *
@@ -1209,15 +1306,15 @@ interface MappedQuerySet<in out T extends TQuerySet> extends k.Compilable, k.Ope
    * @param iqb - An insert query builder or factory function.
    * @returns A new QuerySet with the insert query as the base.
    */
-  insert<IQB extends k.InsertQueryBuilder<any, any, T["BaseQuery"]["O"]>>(iqb: InsertQueryBuilderOrFactory<T["DB"], IQB>): QuerySet<TWithBaseQuery<T, InferTInsertQuery<IQB>>>;
+  insert<IQB extends k.InsertQueryBuilder<any, any, T["BaseQuery"]["O"]>>(iqb: InsertQueryBuilderOrFactory<T["DB"], IQB>): MaybeMappedQuerySet<TWithBaseQuery<T, InferTInsertQuery<IQB>>>;
   /**
    * Like {@link insert}, but switches to an `UPDATE` statement.
    */
-  update<IQB extends k.UpdateQueryBuilder<any, any, any, T["BaseQuery"]["O"]>>(iqb: UpdateQueryBuilderOrFactory<T["DB"], IQB>): QuerySet<TWithBaseQuery<T, InferTUpdateQuery<IQB>>>;
+  update<IQB extends k.UpdateQueryBuilder<any, any, any, T["BaseQuery"]["O"]>>(uqb: UpdateQueryBuilderOrFactory<T["DB"], IQB>): MaybeMappedQuerySet<TWithBaseQuery<T, InferTUpdateQuery<IQB>>>;
   /**
    * Like {@link insert}, but switches to a `DELETE` statement.
    */
-  delete<IQB extends k.DeleteQueryBuilder<any, any, T["BaseQuery"]["O"]>>(iqb: DeleteQueryBuilderOrFactory<T["DB"], IQB>): QuerySet<TWithBaseQuery<T, InferTDeleteQuery<IQB>>>;
+  delete<IQB extends k.DeleteQueryBuilder<any, any, T["BaseQuery"]["O"]>>(dqb: DeleteQueryBuilderOrFactory<T["DB"], IQB>): MaybeMappedQuerySet<TWithBaseQuery<T, InferTDeleteQuery<IQB>>>;
 }
 /**
  * A query set that supports nested joins and automatic hydration.
@@ -1305,7 +1402,7 @@ interface QuerySet<in out T extends TQuerySet> extends MappedQuerySet<T> {
    * @param keys - Field names to omit from the output.
    * @returns A new HydratedQueryBuilder with the fields omitted.
    */
-  omit<K$1 extends keyof TInput<T>>(keys: readonly K$1[]): QuerySet<TWithOutput<T, Omit<TOutput<T>, K$1>>>;
+  omit<K$1 extends keyof TInput<T>>(keys: readonly K$1[]): QuerySet<TWithOmit<T, K$1>>;
   /**
    * Extends this query builder's hydration configuration with another Hydrator.
    * The other Hydrator's configuration takes precedence in case of conflicts.
@@ -2206,6 +2303,7 @@ interface TQuerySetWithAttach<in out T extends TQuerySet, in out Key extends str
   }>;
   OrderableColumns: T["OrderableColumns"];
   HydratedOutput: ExtendWith<T["HydratedOutput"], Key, AttachedOutputMap<FetchFnReturn>[Type]>;
+  OmittedKeys: T["OmittedKeys"];
 }
 interface QuerySetWithAttach<in out T extends TQuerySet, in out Key extends string, in out Type extends TAttachType, in out FetchFnReturn extends SomeFetchFnReturn> extends QuerySet<TQuerySetWithAttach<T, Key, Type, FetchFnReturn>> {}
 type NestedQuerySetOrFactory<T extends TQuerySet, Alias extends string, TNested extends TSelectQuerySet> = MappedQuerySet<TNested> | JoinBuilderCallback<T, Alias, TNested>;
@@ -2251,6 +2349,7 @@ type TQuerySetWithJoin<T extends TQuerySet, Key extends string, Type extends TJo
   JoinedQuery: JoinedQueryMap<T, Key, TNested>[Type];
   OrderableColumns: TOrderableColumnsWithJoin<T, Key, Type, TNested>;
   HydratedOutput: ExtendWith<T["HydratedOutput"], Key, JoinHydratedRowMap<TNested>[Type]>;
+  OmittedKeys: T["OmittedKeys"];
 }>;
 interface QuerySetWithJoin<in out T extends TQuerySet, in out Key extends string, in out Type extends TJoinType, in out TNested extends TSelectQuerySet> extends QuerySet<TQuerySetWithJoin<T, Key, Type, TNested>> {}
 interface InitialQuerySet<in out DB$1, in out BaseAlias extends string, in out BaseQuery extends TQuery> extends QuerySet<{
@@ -2261,7 +2360,8 @@ interface InitialQuerySet<in out DB$1, in out BaseAlias extends string, in out B
   Collections: {};
   JoinedQuery: InitialJoinedQuery<BaseQuery["DB"], BaseAlias, BaseQuery["O"]>;
   OrderableColumns: keyof BaseQuery["O"] & string;
-  HydratedOutput: BaseQuery["O"];
+  HydratedOutput: Flatten<BaseQuery["O"]>;
+  OmittedKeys: never;
 }> {}
 interface SelectCreator<DB$1> {
   selectFrom: k.QueryCreator<DB$1>["selectFrom"];
@@ -2495,4 +2595,4 @@ declare class InvalidJoinedQuerySetError extends KyselyHydrateError {
   constructor(baseAlias: string);
 }
 //#endregion
-export { AmbiguousColumnReferenceError, CardinalityViolationError, ExpectedOneItemError, type Hydrator, InvalidJoinedQuerySetError, KeyByMismatchError, KyselyHydrateError, UnexpectedCaseError, UnexpectedComplexAliasError, UnexpectedSelectAllError, UnexpectedSelectionTypeError, UnsupportedAliasNodeTypeError, UnsupportedNodeTypeError, UnsupportedTableAliasNodeTypeError, WildcardSelectionError, createHydrator, hydrate, isFullHydrator, querySet };
+export { AmbiguousColumnReferenceError, CardinalityViolationError, ExpectedOneItemError, type Hydrator, type InferOutput, InvalidJoinedQuerySetError, KeyByMismatchError, KyselyHydrateError, UnexpectedCaseError, UnexpectedComplexAliasError, UnexpectedSelectAllError, UnexpectedSelectionTypeError, UnsupportedAliasNodeTypeError, UnsupportedNodeTypeError, UnsupportedTableAliasNodeTypeError, WildcardSelectionError, createHydrator, hydrate, isFullHydrator, querySet };

package/dist/index.mjs

@@ -1017,6 +1017,15 @@ var QuerySetImpl = class QuerySetImpl {
 	$call(callback) {
 		return callback(this);
 	}
+	$castTo() {
+		return this;
+	}
+	$narrowType() {
+		return this;
+	}
+	$assertType() {
+		return this;
+	}
 	#asWrite(query) {
 		return this.#clone({ baseQuery: typeof query === "function" ? query(this.#props.db) : query });
 	}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "kysely-hydrate",
-	"version": "0.6.0",
+	"version": "0.7.2",
 	"description": "Explicit ORM-style queries with Kysely",
 	"homepage": "https://github.com/GiacoCorsiglia/kysely-hydrate#readme",
 	"bugs": {