kysely-hydrate 0.8.0 → 0.9.0

package/README.md

@@ -130,6 +130,7 @@ type Result = Array<{
   - [Sorting with `.orderBy()`](#sorting-with-orderby)
   - [Pagination and aggregation](#pagination-and-aggregation)
   - [Inspect the SQL](#inspecting-the-sql)
+  - [Hydrating pre-fetched rows with `.hydrate()`](#hydrating-pre-fetched-rows-with-hydrate)
   - [Mapped properties with `.mapFields()`](#mapped-properties-with-mapfields)
   - [Computed properties with `.extras()`](#computed-properties-with-extras)
   - [Computed properties with `.extend()`](#computed-properties-with-extend)
@@ -799,6 +800,53 @@ You can inspect the generated SQL using `.toQuery()`, `.toJoinedQuery()`, or `.t
 - `toJoinedQuery()`: Returns the query with all joins applied (subject to row explosion).
 - `toBaseQuery()`: Returns the base query without any joins (but with modifications).
 
+### Hydrating pre-fetched rows with `.hydrate()`
+
+Sometimes you already have the flat rows—from a separate query, a cache, a
+transaction, or from calling `.toQuery().execute()` directly—and want to hydrate
+them without re-executing the query.
+
+The `.hydrate()` method applies the same hydration logic that `.execute()` uses,
+including nested joins, `mapFields`, `extras`, `omit`, and `map`.
+
+```ts
+const qs = querySet(db)
+	.selectAs("user", db.selectFrom("users").select(["id", "username"]))
+	.leftJoinMany(
+		"posts",
+		({ eb, qs }) => qs(eb.selectFrom("posts").select(["id", "title", "userId"])),
+		"posts.userId",
+		"user.id",
+	);
+
+// Fetch the flat rows yourself
+const rows = await qs.toQuery().execute();
+
+// Hydrate them
+const users = await qs.hydrate(rows);
+// ⬇
+type Result = Array<{
+	id: number;
+	username: string;
+	posts: Array<{ id: number; title: string; userId: number }>;
+}>;
+```
+
+It also accepts a single row and returns a single hydrated result:
+
+```ts
+const [row] = await qs.toQuery().execute();
+const user = await qs.hydrate(row);
+// ⬇ { id: number; username: string; posts: Array<...> }
+```
+
+For convenience, `.hydrate()` accepts a `Promise` as input, so you can skip
+the intermediate `await`:
+
+```ts
+const users = await qs.hydrate(qs.toQuery().execute());
+```
+
 ### Mapped properties with `.mapFields()`
 
 Transform individual fields in the result set. This changes the output type for

package/dist/index.d.mts

@@ -613,7 +613,7 @@ 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 THydrationInput<T extends TQuerySet> = T["JoinedQuery"]["O"];
 type TOutput<T extends TQuerySet> = T["HydratedOutput"];
 interface TMapped<in out T extends TQuerySet, in out Output> {
   DB: T["DB"];
@@ -868,6 +868,37 @@ interface MappedQuerySet<in out T extends TQuerySet> extends k.Compilable, k.Ope
    * ```
    */
   toExistsQuery(): OpaqueExistsQueryBuilder;
+  /**
+   * Hydrates pre-fetched raw joined rows into nested output objects without
+   * executing a query.
+   *
+   * This is useful when you already have the flat SQL result (e.g. from a
+   * separate query, a cache, or a transaction) and want to apply the same
+   * hydration logic that `.execute()` uses.
+   *
+   * **Example - single row:**
+   * ```ts
+   * const qs = querySet(db)
+   *   .selectAs("user", db.selectFrom("users").select(["id", "username"]))
+   *   .leftJoinMany("posts", ...);
+   *
+   * const row = await qs.toQuery().executeTakeFirstOrThrow();
+   * const user = await qs.hydrate(row);
+   * ```
+   *
+   * **Example - multiple rows:**
+   * ```ts
+   * const rows = await qs.toQuery().execute();
+   * const users = await qs.hydrate(rows);
+   * ```
+   *
+   * @param input - A single flat row or an iterable of flat rows matching the
+   *   joined query output shape.
+   * @returns The hydrated output(s).
+   */
+  hydrate(input: THydrationInput<T> | Promise<THydrationInput<T>>): Promise<TOutput<T>>;
+  hydrate(input: Iterable<THydrationInput<T>> | Promise<Iterable<THydrationInput<T>>>): Promise<TOutput<T>[]>;
+  hydrate(input: THydrationInput<T> | Iterable<THydrationInput<T>> | Promise<THydrationInput<T>> | Promise<Iterable<THydrationInput<T>>>): Promise<TOutput<T> | TOutput<T>[]>;
   /**
    * Executes the query and returns an array of hydrated rows.
    *
@@ -1378,7 +1409,7 @@ interface QuerySet<in out T extends TQuerySet> extends MappedQuerySet<T> {
    *   the field value from the entire row.
    * @returns A new HydratedQueryBuilder with the extras applied.
    */
-  extras<E extends Extras<TInput<T>>>(extras: E): QuerySet<TWithExtendedOutput<T, InferExtras<TInput<T>, E>>>;
+  extras<E extends Extras<THydrationInput<T>>>(extras: E): QuerySet<TWithExtendedOutput<T, InferExtras<THydrationInput<T>, E>>>;
   /**
    * Adds computed fields to the hydrated output by spreading the return value
    * of a function.  Unlike `.extras()` which defines one field at a time,
@@ -1409,7 +1440,7 @@ interface QuerySet<in out T extends TQuerySet> extends MappedQuerySet<T> {
    *   computed properties.
    * @returns A new HydratedQueryBuilder with the extender applied.
    */
-  extend<F extends Extender<TInput<T>>>(fn: F): QuerySet<TWithExtendedOutput<T, InferExtender<TInput<T>, F>>>;
+  extend<F extends Extender<THydrationInput<T>>>(fn: F): QuerySet<TWithExtendedOutput<T, InferExtender<THydrationInput<T>, F>>>;
   /**
    * Transforms already-selected field values in the hydrated output.  Fields
    * not mentioned in the mappings will still be included as-is.
@@ -1431,7 +1462,7 @@ interface QuerySet<in out T extends TQuerySet> extends MappedQuerySet<T> {
    * functions.
    * @returns A new HydratedQueryBuilder with the field transformations applied.
    */
-  mapFields<M extends FieldMappings<TInput<T>>>(mappings: M): QuerySet<TWithExtendedOutput<T, InferFields<TInput<T>, M>>>;
+  mapFields<M extends FieldMappings<THydrationInput<T>>>(mappings: M): QuerySet<TWithExtendedOutput<T, InferFields<THydrationInput<T>, M>>>;
   /**
    * Omits specified fields from the hydrated output.  Useful for excluding
    * fields that were selected for internal use (e.g., for extras).
@@ -1453,7 +1484,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<TWithOmit<T, K$1>>;
+  omit<K$1 extends keyof THydrationInput<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.
@@ -1485,8 +1516,8 @@ interface QuerySet<in out T extends TQuerySet> extends MappedQuerySet<T> {
    * @param hydrator - The Hydrator to extend with.
    * @returns A new HydratedQueryBuilder with merged hydration configuration.
    */
-  with<OtherInput extends StrictSubset<TInput<T>, OtherInput>, OtherOutput>(hydrator: FullHydrator<OtherInput, OtherOutput>): QuerySet<TWithExtendedOutput<T, OtherOutput>>;
-  with<OtherInput extends StrictSubset<TInput<T>, OtherInput>, OtherOutput>(hydrator: MappedHydrator<OtherInput, OtherOutput>): QuerySet<TWithExtendedOutput<T, OtherOutput>>;
+  with<OtherInput extends StrictSubset<THydrationInput<T>, OtherInput>, OtherOutput>(hydrator: FullHydrator<OtherInput, OtherOutput>): QuerySet<TWithExtendedOutput<T, OtherOutput>>;
+  with<OtherInput extends StrictSubset<THydrationInput<T>, OtherInput>, OtherOutput>(hydrator: MappedHydrator<OtherInput, OtherOutput>): QuerySet<TWithExtendedOutput<T, OtherOutput>>;
   /**
    * Attaches data from an external source (not via SQL joins) as a nested
    * array. The `fetchFn` is called exactly once per query execution with all
@@ -2334,8 +2365,8 @@ interface ModifyCollectionReturnMap<T extends TQuerySet, Key extends string, TNe
   AttachOneOrThrow: QuerySetWithAttach<T, Key, "AttachOneOrThrow", NewValue>;
   AttachMany: QuerySetWithAttach<T, Key, "AttachMany", NewValue>;
 }
-type ToFetchFn<T extends TQuerySet, FetchFnReturn extends SomeFetchFnReturn> = SomeFetchFn<TInput<T>, FetchFnReturn>;
-type ToAttachedKeysArg<T extends TQuerySet, FetchFnReturn extends SomeFetchFnReturn> = AttachedKeysArg<TInput<T>, AttachedOutputFromFetchFnReturn<NoInfer<FetchFnReturn>>>;
+type ToFetchFn<T extends TQuerySet, FetchFnReturn extends SomeFetchFnReturn> = SomeFetchFn<THydrationInput<T>, FetchFnReturn>;
+type ToAttachedKeysArg<T extends TQuerySet, FetchFnReturn extends SomeFetchFnReturn> = AttachedKeysArg<THydrationInput<T>, AttachedOutputFromFetchFnReturn<NoInfer<FetchFnReturn>>>;
 interface AttachedOutputMap<in out FetchFnReturn extends SomeFetchFnReturn> {
   AttachOne: AttachedOutputFromFetchFnReturn<FetchFnReturn> | null;
   AttachOneOrThrow: AttachedOutputFromFetchFnReturn<FetchFnReturn>;

package/dist/index.mjs

@@ -856,13 +856,16 @@ var QuerySetImpl = class QuerySetImpl {
 	toOperationNode() {
 		return this.toQuery().toOperationNode();
 	}
-	async execute() {
-		const rows = await this.toQuery().execute();
-		return this.#props.hydrator.hydrate(rows, {
+	async hydrate(input) {
+		return this.#props.hydrator.hydrate(await input, {
 			[EnableAutoInclusion]: true,
 			sort: "nested"
 		});
 	}
+	async execute() {
+		const rows = await this.toQuery().execute();
+		return this.hydrate(rows);
+	}
 	async executeTakeFirst() {
 		const [result] = await this.execute();
 		return result;

package/package.json

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