kysely-hydrate 0.2.1 → 0.3.0

package/README.md

@@ -138,6 +138,7 @@ By design, Kysely has the following constraints:
   - [Mapped properties with `.mapFields()`](#mapped-properties-with-mapfields)
   - [Computed properties with `.extras()`](#computed-properties-with-extras)
   - [Excluded properties with `.omit()`](#excluded-properties-with-omit)
+  - [Output transformations with `.map()`](#output-transformations-with-map)
   - [Composable mappings with `.with()`](#composable-mappings-with-with)
   - [Execution](#execution)
 - [Hydrators](#hydrators)
@@ -146,6 +147,7 @@ By design, Kysely has the following constraints:
   - [Selecting and mapping fields with `.fields()`](#selecting-and-mapping-fields-with-fields)
   - [Computed properties with `.extras()`](#computed-properties-with-extras-1)
   - [Excluding fields with `.omit()`](#excluding-fields-with-omit)
+  - [Output transformations with `.map()`](#output-transformations-with-map-1)
   - [Attached collections with `.attach*()`](#attached-collections-with-attach)
   - [Prefixed collections with `.has*()`](#prefixed-collections-with-has)
   - [Composing hydrators with `.extend()`](#composing-hydrators-with-extend)
@@ -779,6 +781,134 @@ const users = await hydrate(
 type Result = Array<{ id: number; fullName: string }>;
 ```
 
+### Output transformations with `.map()`
+
+The `.map()` method transforms the hydrated output into a different shape.  Use
+it for complex transformations like:
+
+- Converting plain objects into class instances
+- Asserting discriminated union types
+- Restructuring or reshaping data
+
+Unlike `.mapFields()` and `.extras()`, which operate on individual fields,
+`.map()` receives the complete hydrated result and can transform it however you
+want.
+
+```ts
+// Transform into class instances
+class UserModel {
+  constructor(
+    public id: number,
+    public name: string,
+  ) {}
+
+  getDisplayName() {
+    return `User: ${this.name}`;
+  }
+}
+
+const users = await hydrate(
+  db.selectFrom("users").select(["users.id", "users.name"]),
+)
+  .map((user) => new UserModel(user.id, user.name))
+  .execute();
+// ⬇
+type Result = UserModel[];
+```
+
+#### Chaining transformations
+
+You can chain multiple `.map()` calls to compose transformations.  Each function
+receives the output of the previous transformation.
+
+```ts
+const users = await hydrate(
+  db.selectFrom("users").select(["users.id", "users.name"]),
+)
+  .map((user) => ({ ...user, nameUpper: user.name.toUpperCase() }))
+  .map((user) => ({ id: user.id, display: user.nameUpper }))
+  .execute();
+// ⬇
+type Result = Array<{ id: number; display: string }>;
+```
+
+#### Transforming nested collections
+
+`.map()` works with nested collections too. You can apply transformations to
+child entities and then to parents:
+
+```ts
+const users = await hydrate(db.selectFrom("users").select(["users.id"]))
+  .hasMany("posts", ({ leftJoin }) =>
+    leftJoin("posts", "posts.userId", "users.id")
+      .select(["posts.id", "posts.title"])
+      // Transform child:
+      .map((post) => ({ postId: post.id, postTitle: post.title })),
+  )
+  // Transform parent:
+  .map((user) => ({
+    userId: user.id,
+    postCount: user.posts.length,
+    posts: user.posts,
+  }))
+  .execute();
+// ⬇
+type Result = Array<{
+  userId: number;
+  postCount: number;
+  posts: {
+    postId: number;
+    postTitle: string;
+  };
+}>;
+```
+
+#### Terminal operation
+
+`.map()` is a **terminal operation**. After you call `.map()`, you can only:
+
+- Call `.map()` again to chain another transformation
+- Call `.modify()` to adjust the underlying SQL query
+- Call execution methods (`.execute()`, `.executeTakeFirst()`, etc.)
+
+You **cannot** call configuration methods like `.mapFields()`, `.extras()`,
+`.hasMany()`, or `.with()` after `.map()`.
+
+This is intentional: those methods would affect the *input* type expected by
+your transformation function, which would break your mapping logic. By
+preventing further configuration, the type system protects you from this class
+of bugs.
+
+```ts
+const mapped = hydrate(db.selectFrom("users").select(["users.id"]))
+  .map((user) => ({ userId: user.id }));
+
+// ✅ These work:
+mapped.map((data) => ({ transformed: data.userId }));
+mapped.execute();
+
+// ❌ These don't compile:
+mapped.mapFields({ ... });  // Error: Property 'mapFields' does not exist
+mapped.hasMany(...);        // Error: Property 'hasMany' does not exist
+```
+
+#### `.map()` vs `.mapFields()` and `.extras()`
+
+When should you use `.map()` vs the more targeted methods?
+
+- **Use `.mapFields()`** when you want to transform individual fields by name
+  (e.g., normalizing strings)
+- **Use `.extras()`** when you want to add computed fields while keeping the
+  existing structure
+- **Use `.map()`** when you need to:
+  - Convert to class instances
+  - Completely reshape the output
+  - Apply transformations that depend on the full hydrated result
+  - Assert or narrow types on the entire output shape
+
+The targeted methods are more composable, because they can be interleaved with
+joins, unlike `.map()`.
+
 ### Composable mappings with `.with()`
 
 Re-use hydration logic by importing it from another `Hydrator`.  This is great for
@@ -948,20 +1078,16 @@ Computes new fields from the input row.
 type UserRow = { id: number; username: string; email: string };
 
 const hydrator = createHydrator<UserRow>()
-  .fields({ id: true, username: true, email: true })
   .extras({
     displayName: (u) => `${u.username} <${u.email}>`,
   })
-  .omit(["email"]);
 // ⬇
-type Result = Array<{ id: number; username: string; displayName: string }>;
+type Result = Array<{ displayName: string }>;
 ```
 
 ### Excluding fields with `.omit()`
 
-Excludes fields from the output that were already included.  This method
-primarily exists for use by the `HydratedQueryBuilder`, which includes all
-fields by default.
+Excludes fields from the output that were already included.
 
 ```ts
 type UserRow = { id: number; passwordHash: string };
@@ -973,6 +1099,53 @@ const hydrator = createHydrator<UserRow>()
 type Result = Array<{ id: number }>;
 ```
 
+This method primarily exists for use by the `HydratedQueryBuilder`, which
+includes all fields by default.  It's not so useful in standalone Hydrators, in
+which you must explicitly name the fields to include.  The example above is
+equivalent to `createHydrator<UserRow>().fields({ id: true })`.
+
+### Output transformations with `.map()`
+
+The `.map()` method works the same way as described in the
+[`hydrate()` API section](#output-transformations-with-map) above: it
+transforms the hydrated output into a different shape, such as class instances
+or discriminated union types.
+
+```ts
+class UserModel {
+  constructor(
+    public id: number,
+    public name: string,
+  ) {}
+}
+
+const hydrator = createHydrator<{ id: number; name: string }>()
+  .fields({ id: true, name: true })
+  .map((user) => new UserModel(user.id, user.name));
+
+const users = await hydrateData(rows, hydrator);
+// ⬇
+type Result = UserModel[];
+```
+
+Like with `HydratedQueryBuilder`, `.map()` is a terminal operation—after
+calling it, you can only call `.map()` again or `.hydrate()`. You cannot call
+configuration methods like `.fields()`, `.extras()`, `.has*()`, or `.extend()`.
+
+```ts
+const mapped = createHydrator<User>()
+  .fields({ id: true })
+  .map((u) => ({ userId: u.id }));
+
+// ✅ These work:
+mapped.map((data) => ({ transformed: data.userId }));
+mapped.hydrate(rows);
+
+// ❌ These don't compile:
+mapped.fields({ ... });   // Error: Property 'fields' does not exist
+mapped.extend(...);       // Error: Property 'extend' does not exist
+```
+
 ### Attached collections with `.attach*()`
 
 These work the same as in the `hydrate()` API (see the `.attach*()` section above).
@@ -1041,9 +1214,7 @@ type UserRow = { id: number; username: string; email: string };
 const base = createHydrator<UserRow>().fields({ id: true, username: true });
 
 const withDisplayName = createHydrator<UserRow>()
-  .fields({ email: true })
-  .extras({ displayName: (u) => `${u.username} <${u.email}>` })
-  .omit(["email"]);
+  .extras({ displayName: (u) => `${u.username} <${u.email}>` });
 
 const combined = base.extend(withDisplayName);
 // ⬇

package/dist/index.d.mts

@@ -80,24 +80,6 @@ type InferExtras<Input, E extends Extras<Input>> = { [K in keyof E]: ReturnType<
  *   is thrown if the object is null when hydrating.
  */
 type CollectionMode = "many" | "one" | "oneOrThrow";
-/**
- * Configuration for a nested collection.
- */
-interface Collection<ChildInput, ChildOutput> {
-  /**
-   * The mode of the nested entity: "one" (or "oneOrThrow") for a single
-   * object, "many" for an array.
-   */
-  readonly mode: CollectionMode;
-  /**
-   * The prefix to use for the nested collection.
-   */
-  readonly prefix: string;
-  /**
-   * The Hydrator to use when hydrating the objects in the nested collection.
-   */
-  readonly hydrator: Hydrator<ChildInput, ChildOutput>;
-}
 /**
  * Async function that fetches and hydrates data to attach. Called exactly once with
  * all parent inputs to avoid N+1 queries. Should return already-hydrated data.
@@ -117,81 +99,15 @@ interface AttachedKeysArg<ParentInput, AttachedOutput> {
    */
   readonly toParent?: KeyBy<ParentInput> | undefined;
 }
-/**
- * Configuration for an attached collection.
- */
-interface AttachedCollection<ParentInput, AttachedOutput> {
-  /**
-   * The mode of the attached collection: "one" (or "oneOrThrow") for a single
-   * object, "many" for an array.
-   */
-  readonly mode: CollectionMode;
-  /**
-   * Async function that fetches and hydrates the data to attach. Called exactly once with
-   * all parent inputs to avoid N+1 queries. Should return already-hydrated data.
-   */
-  readonly fetchFn: FetchFn<ParentInput, AttachedOutput>;
-  /**
-   * The key(s) on the attached child output to use for matching to parents.
-   */
-  readonly matchChild: KeyBy<AttachedOutput>;
-  /**
-   * The key(s) on the parent input to compare with the attached child output's key.
-   */
-  readonly toParent: KeyBy<ParentInput>;
-}
-/**
- * Internal map type for fields configuration.
- */
-type FieldsMap = Map<string, true | false | ((value: any) => unknown)>;
-/**
- * Internal map type for extras configuration.
- */
-type ExtrasMap = Map<string, (input: any) => unknown>;
-/**
- * Internal map type for nested collections configuration.
- */
-type CollectionsMap = Map<string, Collection<any, any>>;
-/**
- * Internal map type for attached collections configuration.
- */
-type AttachedCollectionsMap = Map<string, AttachedCollection<any, any>>;
-/**
- * Internal configuration for a Hydrator.
- */
-interface HydratorProps<Input> {
-  /**
-   * The key(s) to group by for this entity.
-   * Can be a single key or an array of keys for composite keys.
-   */
-  readonly keyBy: KeyBy<Input>;
-  /**
-   * The fields to include in the final denormalized entity.  You can either specify `true` to
-   * include a field as-is, or provide a transformation function to modify the field's value.
-   */
-  readonly fields?: FieldsMap | undefined;
-  /**
-   * Extra fields generated from the entire input.
-   */
-  readonly extras?: ExtrasMap | undefined;
-  /**
-   * An optional map of nested collections.
-   */
-  readonly collections?: CollectionsMap | undefined;
-  /**
-   * An optional map of attached collections (for application-level joins).
-   */
-  readonly attachedCollections?: AttachedCollectionsMap | undefined;
-}
 /**
  * Type for createHydrator when Input extends InputWithDefaultKey or not.
  * Allows optional keyBy only if Input extends InputWithDefaultKey.
  */
 interface CreateHydratorWithoutDefaultKey<Input> {
-  (keyBy: KeyBy<Input>): Hydrator<Input, {}>;
+  (keyBy: KeyBy<Input>): FullHydrator<Input, {}>;
 }
 interface CreateHydratorWithDefaultKey<Input> extends CreateHydratorWithoutDefaultKey<Input> {
-  (): Hydrator<Input, {}>;
+  (): FullHydrator<Input, {}>;
 }
 /**
  * Type for a createHydrator function scoped to a specific Input type.
@@ -200,17 +116,17 @@ type CreateHydratorFn<Input> = Input extends InputWithDefaultKey ? CreateHydrato
 /**
  * A function that creates a Hydrator.
  */
-type HydratorFactory<Input, Output> = (create: CreateHydratorFn<Input>) => Hydrator<Input, Output>;
+type HydratorFactory<Input, Output> = (create: CreateHydratorFn<Input>) => MappedHydrator<Input, Output>;
 /**
  * A Hydrator instance or a function that creates one.
  * Used to allow inline Hydrator creation in method calls.
  */
-type HydratorArg<Input, Output> = Hydrator<Input, Output> | HydratorFactory<Input, Output>;
+type HydratorArg<Input, Output> = MappedHydrator<Input, Output> | HydratorFactory<Input, Output>;
 /**
  * A Hydrator instance for a child collection or a function that creates one.
  * The input type is automatically prefixed based on the parent's prefix.
  */
-type ChildHydratorArg<P extends string, ParentInput, ChildOutput> = Hydrator<SelectAndStripPrefix<P, ParentInput>, ChildOutput> | ((create: CreateHydratorFn<SelectAndStripPrefix<P, ParentInput>>) => Hydrator<SelectAndStripPrefix<P, ParentInput>, ChildOutput>);
+type ChildHydratorArg<P extends string, ParentInput, ChildOutput> = MappedHydrator<SelectAndStripPrefix<P, ParentInput>, ChildOutput> | ((create: CreateHydratorFn<SelectAndStripPrefix<P, ParentInput>>) => MappedHydrator<SelectAndStripPrefix<P, ParentInput>, ChildOutput>);
 /**
  * Ensures fields are included in the Hydrator's output if they don't already
  * have an explicit configuration (including explicit omission).
@@ -225,6 +141,7 @@ type ChildHydratorArg<P extends string, ParentInput, ChildOutput> = Hydrator<Sel
  * @internal
  */
 
+declare const IsFullHydrator: unique symbol;
 /**
  * A configuration for how to hydrate flat database rows into a denormalized structure.
  *
@@ -233,15 +150,64 @@ type ChildHydratorArg<P extends string, ParentInput, ChildOutput> = Hydrator<Sel
  * - Extra computed fields
  * - Nested collections (using `has()` methods)
  * - Attached collections (using `attach()` methods)
+ * - Map functions to apply to the hydrated output
  *
  * Once configured, call `hydrate()` to transform input data into the denormalized output.
  *
  * @template Input - The type of the input data (typically from a database query)
  * @template Output - The type of the hydrated output structure
  */
-declare class Hydrator<Input, Output> {
-  #private;
-  constructor(props: HydratorProps<Input>);
+type Hydrator<Input, Output> = MappedHydrator<Input, Output> | FullHydrator<Input, Output>;
+/**
+ * Determines if a hydrator is a full hydrator, meaning it has not had a .map()
+ * applied to it yet.
+ *
+ * @param hydrator - The hydrator to check
+ * @returns True if the hydrator is a full hydrator, false otherwise
+ */
+declare const isFullHydrator: <Input, Output>(hydrator: Hydrator<Input, Output>) => hydrator is FullHydrator<Input, Output>;
+/**
+ * Base interface for a mapped hydrator that only allows hydration and further mapping.
+ * This is returned after calling `.map()` to prevent further configuration.
+ */
+interface MappedHydrator<Input, Output> {
+  [IsFullHydrator]: boolean;
+  /**
+   * Applies a transformation function to the hydrated output.
+   *
+   * This is a terminal operation: after calling `.map()`, only `.map()` and
+   * `.hydrate()` are available.
+   *
+   * Use this for more complex transformations, such as:
+   * - Hydrating into class instances
+   * - Asserting discriminated union types
+   * - Complex data reshaping
+   *
+   * For simple field transformations, prefer `.fields()` or `.extras()`.
+   *
+   * @param fn - A function that transforms the hydrated output
+   * @returns A MappedHydrator with the transformation added
+   */
+  map<NewOutput>(fn: (output: Output) => NewOutput): MappedHydrator<Input, NewOutput>;
+  /**
+   * Hydrates the input data into a denormalized structure according to this configuration.
+   *
+   * If attached collections are configured, this method will fetch them asynchronously
+   * before performing the hydration. The method always returns a Promise for consistency.
+   *
+   * @param input - A single input entity or an iterable of input entities
+   * @returns A Promise that resolves to the hydrated output(s)
+   */
+  hydrate(input: Iterable<Input>): Promise<Output[]>;
+  hydrate(input: Input | Iterable<Input>): Promise<Output | Output[]>;
+  hydrate(input: Input): Promise<Output>;
+}
+/**
+ * Full hydrator interface with all configuration methods.
+ * Extends MappedHydrator but `.map()` returns MappedHydrator to make it terminal.
+ */
+interface FullHydrator<Input, Output> extends MappedHydrator<Input, Output> {
+  [IsFullHydrator]: true;
   /**
    * Configures which fields to include in the hydrated output.
    *
@@ -249,14 +215,14 @@ declare class Hydrator<Input, Output> {
    *   or a transformation function
    * @returns A new Hydrator with the fields configuration merged
    */
-  fields<F extends Fields<Input>>(fields: F): Hydrator<Input, Extend<Output, InferFields<Input, F>>>;
+  fields<F extends Fields<Input>>(fields: F): FullHydrator<Input, Extend<Output, InferFields<Input, F>>>;
   /**
    * Omits specified fields from the hydrated output.
    *
    * @param keys - Field names to omit from the output
    * @returns A new Hydrator with the fields omitted
    */
-  omit<K$1 extends keyof Input>(keys: readonly K$1[]): Hydrator<Input, Omit<Output, K$1>>;
+  omit<K$1 extends keyof Input>(keys: readonly K$1[]): FullHydrator<Input, Omit<Output, K$1>>;
   /**
    * Configures extra computed fields to add to the hydrated output.
    *
@@ -264,7 +230,7 @@ declare class Hydrator<Input, Output> {
    *   the field value from the entire input
    * @returns A new Hydrator with the extras configuration merged
    */
-  extras<E extends Extras<Input>>(extras: E): Hydrator<Input, Extend<Output, InferExtras<Input, E>>>;
+  extras<E extends Extras<Input>>(extras: E): FullHydrator<Input, Extend<Output, InferExtras<Input, E>>>;
   /**
    * Extends this Hydrator with the configuration from another Hydrator.  The
    * other Hydrator's configuration takes precedence in case of conflicts.
@@ -276,7 +242,8 @@ declare class Hydrator<Input, Output> {
    * @returns A new Hydrator with merged configuration
    * @throws {KeyByMismatchError} If the keyBy configurations don't match
    */
-  extend<OtherInput extends Partial<Input>, OtherOutput>(other: Hydrator<OtherInput, OtherOutput>): Hydrator<Input & OtherInput, Extend<Output, OtherOutput>>;
+  extend<OtherInput extends Partial<Input>, OtherOutput>(other: FullHydrator<OtherInput, OtherOutput>): FullHydrator<Input & OtherInput, Extend<Output, OtherOutput>>;
+  extend<OtherInput extends Partial<Input>, OtherOutput>(other: MappedHydrator<OtherInput, OtherOutput>): MappedHydrator<Input & OtherInput, Extend<Output, OtherOutput>>;
   /**
    * Configures a nested collection that exists in the same query result. The
    * child data is expected to be prefixed in the input (e.g., `posts$$id`,
@@ -293,10 +260,10 @@ declare class Hydrator<Input, Output> {
    *   a function that creates one.
    * @returns A new Hydrator with the nested collection added.
    */
-  has<K$1 extends string, P extends string, ChildOutput>(mode: "many", key: K$1, prefix: P, hydrator: ChildHydratorArg<P, Input, ChildOutput>): Hydrator<Input, Extend<Output, { [_ in K$1]: ChildOutput[] }>>;
-  has<K$1 extends string, P extends string, ChildOutput>(mode: "one", key: K$1, prefix: P, hydrator: ChildHydratorArg<P, Input, ChildOutput>): Hydrator<Input, Extend<Output, { [_ in K$1]: ChildOutput | null }>>;
-  has<K$1 extends string, P extends string, ChildOutput>(mode: "oneOrThrow", key: K$1, prefix: P, hydrator: ChildHydratorArg<P, Input, ChildOutput>): Hydrator<Input, Extend<Output, { [_ in K$1]: ChildOutput }>>;
-  has<K$1 extends string, P extends string, ChildOutput>(mode: CollectionMode, key: K$1, prefix: P, hydrator: ChildHydratorArg<P, Input, ChildOutput>): Hydrator<Input, Extend<Output, { [_ in K$1]: ChildOutput[] | ChildOutput | null }>>;
+  has<K$1 extends string, P extends string, ChildOutput>(mode: "many", key: K$1, prefix: P, hydrator: ChildHydratorArg<P, Input, ChildOutput>): FullHydrator<Input, Extend<Output, { [_ in K$1]: ChildOutput[] }>>;
+  has<K$1 extends string, P extends string, ChildOutput>(mode: "one", key: K$1, prefix: P, hydrator: ChildHydratorArg<P, Input, ChildOutput>): FullHydrator<Input, Extend<Output, { [_ in K$1]: ChildOutput | null }>>;
+  has<K$1 extends string, P extends string, ChildOutput>(mode: "oneOrThrow", key: K$1, prefix: P, hydrator: ChildHydratorArg<P, Input, ChildOutput>): FullHydrator<Input, Extend<Output, { [_ in K$1]: ChildOutput }>>;
+  has<K$1 extends string, P extends string, ChildOutput>(mode: CollectionMode, key: K$1, prefix: P, hydrator: ChildHydratorArg<P, Input, ChildOutput>): FullHydrator<Input, Extend<Output, { [_ in K$1]: ChildOutput[] | ChildOutput | null }>>;
   /**
    * Shorthand for `has("many", ...)` - configures a nested array collection.
    *
@@ -305,7 +272,7 @@ declare class Hydrator<Input, Output> {
    * @param hydrator - The Hydrator configuration for the child entities
    * @returns A new Hydrator with the nested collection added
    */
-  hasMany<K$1 extends string, P extends string, ChildOutput>(key: K$1, prefix: P, hydrator: ChildHydratorArg<P, Input, ChildOutput>): Hydrator<Input, Extend<Output, { [_ in K$1]: ChildOutput[] }>>;
+  hasMany<K$1 extends string, P extends string, ChildOutput>(key: K$1, prefix: P, hydrator: ChildHydratorArg<P, Input, ChildOutput>): FullHydrator<Input, Extend<Output, { [_ in K$1]: ChildOutput[] }>>;
   /**
    * Shorthand for `has("one", ...)` - configures a nested nullable single entity.
    *
@@ -314,7 +281,7 @@ declare class Hydrator<Input, Output> {
    * @param hydrator - The Hydrator configuration for the child entity
    * @returns A new Hydrator with the nested entity added
    */
-  hasOne<K$1 extends string, P extends string, ChildOutput>(key: K$1, prefix: P, hydrator: ChildHydratorArg<P, Input, ChildOutput>): Hydrator<Input, Extend<Output, { [_ in K$1]: ChildOutput | null }>>;
+  hasOne<K$1 extends string, P extends string, ChildOutput>(key: K$1, prefix: P, hydrator: ChildHydratorArg<P, Input, ChildOutput>): FullHydrator<Input, Extend<Output, { [_ in K$1]: ChildOutput | null }>>;
   /**
    * Shorthand for `has("oneOrThrow", ...)` - configures a nested non-nullable single entity.
    * Throws an error if the entity is not found during hydration.
@@ -324,7 +291,7 @@ declare class Hydrator<Input, Output> {
    * @param hydrator - The Hydrator configuration for the child entity.
    * @returns A new Hydrator with the nested entity added.
    */
-  hasOneOrThrow<K$1 extends string, P extends string, ChildOutput>(key: K$1, prefix: P, hydrator: ChildHydratorArg<P, Input, ChildOutput>): Hydrator<Input, Extend<Output, { [_ in K$1]: ChildOutput }>>;
+  hasOneOrThrow<K$1 extends string, P extends string, ChildOutput>(key: K$1, prefix: P, hydrator: ChildHydratorArg<P, Input, ChildOutput>): FullHydrator<Input, Extend<Output, { [_ in K$1]: ChildOutput }>>;
   /**
    * Configures an attached collection that is fetched from an external source.
    * The `fetchFn` is called exactly once per hydration with all parent inputs
@@ -344,10 +311,10 @@ declare class Hydrator<Input, Output> {
    *   attached child's key.
    * @returns A new Hydrator with the attached collection added.
    */
-  attach<K$1 extends string, AttachedOutput>(mode: "many", key: K$1, fetchFn: FetchFn<Input, AttachedOutput>, keys: AttachedKeysArg<Input, AttachedOutput>): Hydrator<Input, Extend<Output, { [_ in K$1]: AttachedOutput[] }>>;
-  attach<K$1 extends string, AttachedOutput>(mode: "one", key: K$1, fetchFn: FetchFn<Input, AttachedOutput>, keys: AttachedKeysArg<Input, AttachedOutput>): Hydrator<Input, Extend<Output, { [_ in K$1]: AttachedOutput | null }>>;
-  attach<K$1 extends string, AttachedOutput>(mode: "oneOrThrow", key: K$1, fetchFn: FetchFn<Input, AttachedOutput>, keys: AttachedKeysArg<Input, AttachedOutput>): Hydrator<Input, Extend<Output, { [_ in K$1]: AttachedOutput }>>;
-  attach<K$1 extends string, AttachedOutput>(mode: CollectionMode, key: K$1, fetchFn: FetchFn<Input, AttachedOutput>, keys: AttachedKeysArg<Input, AttachedOutput>): Hydrator<Input, Extend<Output, { [_ in K$1]: AttachedOutput[] | AttachedOutput | null }>>;
+  attach<K$1 extends string, AttachedOutput>(mode: "many", key: K$1, fetchFn: FetchFn<Input, AttachedOutput>, keys: AttachedKeysArg<Input, AttachedOutput>): FullHydrator<Input, Extend<Output, { [_ in K$1]: AttachedOutput[] }>>;
+  attach<K$1 extends string, AttachedOutput>(mode: "one", key: K$1, fetchFn: FetchFn<Input, AttachedOutput>, keys: AttachedKeysArg<Input, AttachedOutput>): FullHydrator<Input, Extend<Output, { [_ in K$1]: AttachedOutput | null }>>;
+  attach<K$1 extends string, AttachedOutput>(mode: "oneOrThrow", key: K$1, fetchFn: FetchFn<Input, AttachedOutput>, keys: AttachedKeysArg<Input, AttachedOutput>): FullHydrator<Input, Extend<Output, { [_ in K$1]: AttachedOutput }>>;
+  attach<K$1 extends string, AttachedOutput>(mode: CollectionMode, key: K$1, fetchFn: FetchFn<Input, AttachedOutput>, keys: AttachedKeysArg<Input, AttachedOutput>): FullHydrator<Input, Extend<Output, { [_ in K$1]: AttachedOutput[] | AttachedOutput | null }>>;
   /**
    * Shorthand for `attach("many", ...)` - configures an attached array collection.
    *
@@ -357,7 +324,7 @@ declare class Hydrator<Input, Output> {
    * @param keys.toParent - The key(s) on the parent input to compare with the child's key.
    * @returns A new Hydrator with the attached collection added.
    */
-  attachMany<K$1 extends string, AttachedOutput>(key: K$1, fetchFn: FetchFn<Input, AttachedOutput>, keys: AttachedKeysArg<Input, AttachedOutput>): Hydrator<Input, Extend<Output, { [_ in K$1]: AttachedOutput[] }>>;
+  attachMany<K$1 extends string, AttachedOutput>(key: K$1, fetchFn: FetchFn<Input, AttachedOutput>, keys: AttachedKeysArg<Input, AttachedOutput>): FullHydrator<Input, Extend<Output, { [_ in K$1]: AttachedOutput[] }>>;
   /**
    * Shorthand for `attach("one", ...)` - configures an attached nullable single entity.
    *
@@ -367,7 +334,7 @@ declare class Hydrator<Input, Output> {
    * @param keys.toParent - The key(s) on the parent input to compare with the child's key.
    * @returns A new Hydrator with the attached entity added.
    */
-  attachOne<K$1 extends string, AttachedOutput>(key: K$1, fetchFn: FetchFn<Input, AttachedOutput>, keys: AttachedKeysArg<Input, AttachedOutput>): Hydrator<Input, Extend<Output, { [_ in K$1]: AttachedOutput | null }>>;
+  attachOne<K$1 extends string, AttachedOutput>(key: K$1, fetchFn: FetchFn<Input, AttachedOutput>, keys: AttachedKeysArg<Input, AttachedOutput>): FullHydrator<Input, Extend<Output, { [_ in K$1]: AttachedOutput | null }>>;
   /**
    * Shorthand for `attach("oneOrThrow", ...)` - configures an attached non-nullable single entity.
    * Throws an error if the entity is not found during hydration.
@@ -378,19 +345,7 @@ declare class Hydrator<Input, Output> {
    * @param keys.toParent - The key(s) on the parent input to compare with the child's key.
    * @returns A new Hydrator with the attached entity added
    */
-  attachOneOrThrow<K$1 extends string, AttachedOutput>(key: K$1, fetchFn: FetchFn<Input, AttachedOutput>, keys: AttachedKeysArg<Input, AttachedOutput>): Hydrator<Input, Extend<Output, { [_ in K$1]: AttachedOutput }>>;
-  /**
-   * Hydrates the input data into a denormalized structure according to this configuration.
-   *
-   * If attached collections are configured, this method will fetch them asynchronously
-   * before performing the hydration. The method always returns a Promise for consistency.
-   *
-   * @param input - A single input entity or an iterable of input entities
-   * @returns A Promise that resolves to the hydrated output(s)
-   */
-  hydrate(input: Iterable<Input>): Promise<Output[]>;
-  hydrate(input: Input | Iterable<Input>): Promise<Output | Output[]>;
-  hydrate(input: Input): Promise<Output>;
+  attachOneOrThrow<K$1 extends string, AttachedOutput>(key: K$1, fetchFn: FetchFn<Input, AttachedOutput>, keys: AttachedKeysArg<Input, AttachedOutput>): FullHydrator<Input, Extend<Output, { [_ in K$1]: AttachedOutput }>>;
 }
 /**
  * Creates a new Hydrator---a configuration for how to hydrate an entity into
@@ -399,8 +354,8 @@ declare class Hydrator<Input, Output> {
  * @param keyBy - The key(s) to group by for this entity.
  *   Defaults to "id" if the input type has an "id" property.
  */
-declare function createHydrator<T>(keyBy: KeyBy<NoInfer<T>>): Hydrator<T, {}>;
-declare function createHydrator<T extends InputWithDefaultKey>(): Hydrator<T, {}>;
+declare function createHydrator<T>(keyBy: KeyBy<NoInfer<T>>): FullHydrator<T, {}>;
+declare function createHydrator<T extends InputWithDefaultKey>(): FullHydrator<T, {}>;
 /**
  * Hydrates an entity or collection of entities into a denormalized structure
  * per the given Hydrator configuration.
@@ -414,6 +369,85 @@ declare function hydrateData<Input, Output>(input: Input | readonly Input[], hyd
 declare function hydrateData<Input, Output>(input: Input, hydrator: HydratorArg<NoInfer<Input>, Output>): Promise<Output>;
 //#endregion
 //#region src/query-builder.d.ts
+/**
+ * Super type to HydratedQueryBuilder, that has already had a .map() added,
+ * meaning it's no longer safe to continue to chain methods like .mapFields() or
+ * .hasMany(), because those will affect the input type expected by the
+ * transformation function applied to .map().
+ *
+ * The generic parameters are the same as HydratedQueryBuilder.
+ */
+interface MappedHydratedQueryBuilder<Prefix extends string, QueryDB, QueryTB extends keyof QueryDB, QueryRow, LocalDB, LocalRow, HydratedRow, IsNullable extends boolean, HasJoin extends boolean> {
+  /**
+   * This property exists for complex type reasons and will never be set.
+   *
+   * @internal
+   */
+  readonly _generics: {
+    Prefix: Prefix;
+    QueryDB: QueryDB;
+    QueryTB: QueryTB;
+    QueryRow: QueryRow;
+    LocalRow: LocalRow;
+    HydratedRow: HydratedRow;
+    IsNullable: IsNullable;
+    NestedDB: LocalDB;
+    HasJoin: HasJoin;
+  } | undefined;
+  /**
+   * Allows you to modify the underlying select query.  Useful for adding
+   * `where` clauses.  Adding additional SELECTs here is forbidden.
+   *
+   * For example:
+   *
+   * ```ts
+   * hydrate(...).modify((qb) => qb.where("isActive", "=", "true"))
+   * ```
+   */
+  modify(modifier: (qb: k$1.SelectQueryBuilder<QueryDB, QueryTB, QueryRow>) => k$1.SelectQueryBuilder<QueryDB, QueryTB, QueryRow>): MappedHydratedQueryBuilder<Prefix, QueryDB, QueryTB, QueryRow, LocalDB, LocalRow, HydratedRow, IsNullable, HasJoin>;
+  /**
+   * Returns the raw underlying Kysely select query builder.
+   * Useful for debugging or when you need direct access to the query.
+   */
+  toQuery(): k$1.SelectQueryBuilder<QueryDB, QueryTB, QueryRow>;
+  /**
+   * Executes the query and returns an array of rows.
+   *
+   * Also see the {@link executeTakeFirst} and {@link executeTakeFirstOrThrow} methods.
+   */
+  execute(): Promise<k$1.Simplify<HydratedRow>[]>;
+  /**
+   * Executes the query and returns the first result or undefined if the query
+   * returned no result.
+   */
+  executeTakeFirst(): Promise<k$1.Simplify<HydratedRow> | undefined>;
+  /**
+   * Executes the query and returns the first result or throws if the query
+   * returned no result.
+   *
+   * By default an instance of {@link k.NoResultError} is thrown, but you can
+   * provide a custom error class, or callback to throw a different error.
+   */
+  executeTakeFirstOrThrow(errorConstructor?: k$1.NoResultErrorConstructor | ((node: k$1.QueryNode) => Error)): Promise<k$1.Simplify<HydratedRow>>;
+  /**
+   * Applies a transformation function to the hydrated output.
+   *
+   * This is a terminal operation: after calling `.map()`, only `.map()` and
+   * `.execute()` are available; you cannot continue to chain methods that
+   * affect the input type expected by the transformation function.
+   *
+   * Use this for more complex transformations, such as:
+   * - Hydrating into class instances
+   * - Asserting discriminated union types
+   * - Complex data reshaping
+   *
+   * For simple field transformations, prefer `.fields()` or `.extras()`.
+   *
+   * @param transform - A function that transforms the hydrated output
+   * @returns A MappedHydratedQueryBuilder with the transformation added
+   */
+  map<NewHydratedRow>(transform: (row: k$1.Simplify<HydratedRow>) => NewHydratedRow): MappedHydratedQueryBuilder<Prefix, QueryDB, QueryTB, QueryRow, LocalDB, LocalRow, NewHydratedRow, IsNullable, HasJoin>;
+}
 /**
  * A query builder that supports both mapping and nested joins.
  *
@@ -437,33 +471,8 @@ declare function hydrateData<Input, Output>(input: Input, hydrator: HydratorArg<
  * @template HasJoin Preserves whether this join builder has already had a join
  * added, which affects the nullability of this relation when adding more joins.
  */
-interface HydratedQueryBuilder<Prefix extends string, QueryDB, QueryTB extends keyof QueryDB, QueryRow, LocalDB, LocalRow, HydratedRow, IsNullable extends boolean, HasJoin extends boolean> {
-  /**
-   * @internal This is is a fake method that does nothing and is only for
-   * testing types.  The callback will never actually be called.
-   */
-  _generics(cb: (args: {
-    Prefix: Prefix;
-    QueryDB: QueryDB;
-    QueryTB: QueryTB;
-    QueryRow: QueryRow;
-    LocalRow: LocalRow;
-    HydratedRow: HydratedRow;
-    IsNullable: IsNullable;
-    NestedDB: LocalDB;
-    HasJoin: HasJoin;
-  }) => void): this;
-  /**
-   * Allows you to modify the underlying select query.  Useful for adding
-   * `where` clauses.  Adding additional SELECTs here is discouraged.
-   *
-   * ### Examples
-   *
-   * ```ts
-   * nestableQuery.modify((qb) => qb.where("isActive", "=", "true"))
-   * ```
-   */
-  modify<NewQueryDB, NewQueryTB extends keyof NewQueryDB, NewQueryRow extends QueryRow>(modifier: (qb: k$1.SelectQueryBuilder<QueryDB, QueryTB, QueryRow>) => k$1.SelectQueryBuilder<NewQueryDB, NewQueryTB, NewQueryRow>): HydratedQueryBuilder<Prefix, NewQueryDB, NewQueryTB, NewQueryRow, LocalDB, LocalRow, Extend<NewQueryRow, HydratedRow>, IsNullable, HasJoin>;
+interface HydratedQueryBuilder<Prefix extends string, QueryDB, QueryTB extends keyof QueryDB, QueryRow, LocalDB, LocalRow, HydratedRow, IsNullable extends boolean, HasJoin extends boolean> extends MappedHydratedQueryBuilder<Prefix, QueryDB, QueryTB, QueryRow, LocalDB, LocalRow, HydratedRow, IsNullable, HasJoin> {
+  modify(modifier: (qb: k$1.SelectQueryBuilder<QueryDB, QueryTB, QueryRow>) => k$1.SelectQueryBuilder<QueryDB, QueryTB, QueryRow>): HydratedQueryBuilder<Prefix, QueryDB, QueryTB, QueryRow, LocalDB, LocalRow, HydratedRow, IsNullable, HasJoin>;
   /**
    * Configures extra computed fields to add to the hydrated output.
    * Each extra is a function that receives the full row (with prefixed columns
@@ -561,31 +570,8 @@ interface HydratedQueryBuilder<Prefix extends string, QueryDB, QueryTB extends k
    * @param hydrator - The Hydrator to extend with.
    * @returns A new HydratedQueryBuilder with merged hydration configuration.
    */
-  with<OtherInput extends StrictSubset<LocalRow, OtherInput>, OtherOutput>(hydrator: Hydrator<OtherInput, OtherOutput>): HydratedQueryBuilder<Prefix, QueryDB, QueryTB, QueryRow, LocalDB, LocalRow, Extend<HydratedRow, OtherOutput>, IsNullable, HasJoin>;
-  /**
-   * Returns the raw underlying Kysely select query builder.
-   * Useful for debugging or when you need direct access to the query.
-   */
-  toQuery(): k$1.SelectQueryBuilder<QueryDB, QueryTB, QueryRow>;
-  /**
-   * Executes the query and returns an array of rows.
-   *
-   * Also see the {@link executeTakeFirst} and {@link executeTakeFirstOrThrow} methods.
-   */
-  execute(): Promise<k$1.Simplify<HydratedRow>[]>;
-  /**
-   * Executes the query and returns the first result or undefined if the query
-   * returned no result.
-   */
-  executeTakeFirst(): Promise<k$1.Simplify<HydratedRow> | undefined>;
-  /**
-   * Executes the query and returns the first result or throws if the query
-   * returned no result.
-   *
-   * By default an instance of {@link k.NoResultError} is thrown, but you can
-   * provide a custom error class, or callback to throw a different error.
-   */
-  executeTakeFirstOrThrow(errorConstructor?: k$1.NoResultErrorConstructor | ((node: k$1.QueryNode) => Error)): Promise<k$1.Simplify<HydratedRow>>;
+  with<OtherInput extends StrictSubset<LocalRow, OtherInput>, OtherOutput>(hydrator: FullHydrator<OtherInput, OtherOutput>): HydratedQueryBuilder<Prefix, QueryDB, QueryTB, QueryRow, LocalDB, LocalRow, Extend<HydratedRow, OtherOutput>, IsNullable, HasJoin>;
+  with<OtherInput extends StrictSubset<LocalRow, OtherInput>, OtherOutput>(hydrator: MappedHydrator<OtherInput, OtherOutput>): MappedHydratedQueryBuilder<Prefix, QueryDB, QueryTB, QueryRow, LocalDB, LocalRow, Extend<HydratedRow, OtherOutput>, IsNullable, HasJoin>;
   /**
    * Adds a join to the query that will hydrate into a nested collection.
    *
@@ -624,12 +610,12 @@ interface HydratedQueryBuilder<Prefix extends string, QueryDB, QueryTB extends k
   // LocalRow is empty within the nesting.
   {},
   // HydratedRow is empty within the nesting.
-  false, false>) => HydratedQueryBuilder<MakePrefix<Prefix, NoInfer<K$1>>, JoinedQueryDB, JoinedQueryTB, JoinedQueryRow, NestedLocalDB, NestedLocalRow, NestedHydratedRow, any, any>, keyBy: KeyBy<NestedLocalRow>): HydratedQueryBuilder<Prefix, JoinedQueryDB, JoinedQueryTB, JoinedQueryRow, NestedLocalDB, LocalRow & ApplyPrefixes<MakePrefix<"", K$1>, NestedLocalRow>, Extend<HydratedRow, { [_ in K$1]: NestedHydratedRow[] }>, IsNullable, HasJoin>;
+  false, false>) => MappedHydratedQueryBuilder<MakePrefix<Prefix, NoInfer<K$1>>, JoinedQueryDB, JoinedQueryTB, JoinedQueryRow, NestedLocalDB, NestedLocalRow, NestedHydratedRow, any, any>, keyBy: KeyBy<NestedLocalRow>): HydratedQueryBuilder<Prefix, JoinedQueryDB, JoinedQueryTB, JoinedQueryRow, NestedLocalDB, LocalRow & ApplyPrefixes<MakePrefix<"", K$1>, NestedLocalRow>, Extend<HydratedRow, { [_ in K$1]: NestedHydratedRow[] }>, IsNullable, HasJoin>;
   hasMany<K$1 extends string, JoinedQueryDB, JoinedQueryTB extends keyof JoinedQueryDB, JoinedQueryRow, NestedLocalDB, NestedLocalRow extends InputWithDefaultKey, NestedHydratedRow>(key: K$1, jb: (nb: HydratedQueryBuilder<MakePrefix<Prefix, NoInfer<K$1>>, QueryDB, QueryTB, QueryRow, LocalDB, {},
   // LocalRow is empty within the nesting.
   {},
   // HydratedRow is empty within the nesting.
-  false, false>) => HydratedQueryBuilder<MakePrefix<Prefix, NoInfer<K$1>>, JoinedQueryDB, JoinedQueryTB, JoinedQueryRow, NestedLocalDB, NestedLocalRow, NestedHydratedRow, any, any>): HydratedQueryBuilder<Prefix, JoinedQueryDB, JoinedQueryTB, JoinedQueryRow, NestedLocalDB, LocalRow & ApplyPrefixes<MakePrefix<"", K$1>, NestedLocalRow>, Extend<HydratedRow, { [_ in K$1]: NestedHydratedRow[] }>, IsNullable, HasJoin>;
+  false, false>) => MappedHydratedQueryBuilder<MakePrefix<Prefix, NoInfer<K$1>>, JoinedQueryDB, JoinedQueryTB, JoinedQueryRow, NestedLocalDB, NestedLocalRow, NestedHydratedRow, any, any>): HydratedQueryBuilder<Prefix, JoinedQueryDB, JoinedQueryTB, JoinedQueryRow, NestedLocalDB, LocalRow & ApplyPrefixes<MakePrefix<"", K$1>, NestedLocalRow>, Extend<HydratedRow, { [_ in K$1]: NestedHydratedRow[] }>, IsNullable, HasJoin>;
   /**
    * Adds a join to the query that will hydrate into a single nested object.
    * The object will be nullable if you use a left join, and non-nullable if you
@@ -670,12 +656,12 @@ interface HydratedQueryBuilder<Prefix extends string, QueryDB, QueryTB extends k
   // LocalRow is empty within the nesting.
   {},
   // HydratedRow is empty within the nesting.
-  false, false>) => HydratedQueryBuilder<MakePrefix<Prefix, NoInfer<K$1>>, JoinedQueryDB, JoinedQueryTB, JoinedQueryRow, NestedLocalDB, NestedLocalRow, NestedHydratedRow, IsChildNullable, any>, keyBy: KeyBy<NestedLocalRow>): HydratedQueryBuilder<Prefix, JoinedQueryDB, JoinedQueryTB, JoinedQueryRow, NestedLocalDB, LocalRow & ApplyPrefixes<MakePrefix<"", K$1>, NestedLocalRow>, Extend<HydratedRow, { [_ in K$1]: IsChildNullable extends true ? NestedHydratedRow | null : NestedHydratedRow }>, IsNullable, HasJoin>;
+  false, false>) => MappedHydratedQueryBuilder<MakePrefix<Prefix, NoInfer<K$1>>, JoinedQueryDB, JoinedQueryTB, JoinedQueryRow, NestedLocalDB, NestedLocalRow, NestedHydratedRow, IsChildNullable, any>, keyBy: KeyBy<NestedLocalRow>): HydratedQueryBuilder<Prefix, JoinedQueryDB, JoinedQueryTB, JoinedQueryRow, NestedLocalDB, LocalRow & ApplyPrefixes<MakePrefix<"", K$1>, NestedLocalRow>, Extend<HydratedRow, { [_ in K$1]: IsChildNullable extends true ? NestedHydratedRow | null : NestedHydratedRow }>, IsNullable, HasJoin>;
   hasOne<K$1 extends string, JoinedQueryDB, JoinedQueryTB extends keyof JoinedQueryDB, JoinedQueryRow, NestedLocalDB, NestedLocalRow extends InputWithDefaultKey, NestedHydratedRow, IsChildNullable extends boolean>(key: K$1, jb: (nb: HydratedQueryBuilder<MakePrefix<Prefix, NoInfer<K$1>>, QueryDB, QueryTB, QueryRow, LocalDB, {},
   // LocalRow is empty within the nesting.
   {},
   // HydratedRow is empty within the nesting.
-  false, false>) => HydratedQueryBuilder<MakePrefix<Prefix, NoInfer<K$1>>, JoinedQueryDB, JoinedQueryTB, JoinedQueryRow, NestedLocalDB, NestedLocalRow, NestedHydratedRow, IsChildNullable, any>): HydratedQueryBuilder<Prefix, JoinedQueryDB, JoinedQueryTB, JoinedQueryRow, NestedLocalDB, LocalRow & ApplyPrefixes<MakePrefix<"", K$1>, NestedLocalRow>, Extend<HydratedRow, { [_ in K$1]: IsChildNullable extends true ? NestedHydratedRow | null : NestedHydratedRow }>, IsNullable, HasJoin>;
+  false, false>) => MappedHydratedQueryBuilder<MakePrefix<Prefix, NoInfer<K$1>>, JoinedQueryDB, JoinedQueryTB, JoinedQueryRow, NestedLocalDB, NestedLocalRow, NestedHydratedRow, IsChildNullable, any>): HydratedQueryBuilder<Prefix, JoinedQueryDB, JoinedQueryTB, JoinedQueryRow, NestedLocalDB, LocalRow & ApplyPrefixes<MakePrefix<"", K$1>, NestedLocalRow>, Extend<HydratedRow, { [_ in K$1]: IsChildNullable extends true ? NestedHydratedRow | null : NestedHydratedRow }>, IsNullable, HasJoin>;
   /**
    * Exactly like {@link hasOne}, but throws an error if the nested object is not found.
    *
@@ -689,12 +675,12 @@ interface HydratedQueryBuilder<Prefix extends string, QueryDB, QueryTB extends k
   // LocalRow is empty within the nesting.
   {},
   // HydratedRow is empty within the nesting.
-  false, false>) => HydratedQueryBuilder<MakePrefix<Prefix, NoInfer<K$1>>, JoinedQueryDB, JoinedQueryTB, JoinedQueryRow, NestedLocalDB, NestedLocalRow, NestedHydratedRow, any, any>, keyBy: KeyBy<NestedLocalRow>): HydratedQueryBuilder<Prefix, JoinedQueryDB, JoinedQueryTB, JoinedQueryRow, NestedLocalDB, LocalRow & ApplyPrefixes<MakePrefix<"", K$1>, NestedLocalRow>, Extend<HydratedRow, { [_ in K$1]: NestedHydratedRow }>, IsNullable, HasJoin>;
+  false, false>) => MappedHydratedQueryBuilder<MakePrefix<Prefix, NoInfer<K$1>>, JoinedQueryDB, JoinedQueryTB, JoinedQueryRow, NestedLocalDB, NestedLocalRow, NestedHydratedRow, any, any>, keyBy: KeyBy<NestedLocalRow>): HydratedQueryBuilder<Prefix, JoinedQueryDB, JoinedQueryTB, JoinedQueryRow, NestedLocalDB, LocalRow & ApplyPrefixes<MakePrefix<"", K$1>, NestedLocalRow>, Extend<HydratedRow, { [_ in K$1]: NestedHydratedRow }>, IsNullable, HasJoin>;
   hasOneOrThrow<K$1 extends string, JoinedQueryDB, JoinedQueryTB extends keyof JoinedQueryDB, JoinedQueryRow, NestedLocalDB, NestedLocalRow extends InputWithDefaultKey, NestedHydratedRow>(key: K$1, jb: (nb: HydratedQueryBuilder<MakePrefix<Prefix, NoInfer<K$1>>, QueryDB, QueryTB, QueryRow, LocalDB, {},
   // LocalRow is empty within the nesting.
   {},
   // HydratedRow is empty within the nesting.
-  false, false>) => HydratedQueryBuilder<MakePrefix<Prefix, NoInfer<K$1>>, JoinedQueryDB, JoinedQueryTB, JoinedQueryRow, NestedLocalDB, NestedLocalRow, NestedHydratedRow, any, any>): HydratedQueryBuilder<Prefix, JoinedQueryDB, JoinedQueryTB, JoinedQueryRow, NestedLocalDB, LocalRow & ApplyPrefixes<MakePrefix<"", K$1>, NestedLocalRow>, Extend<HydratedRow, { [_ in K$1]: NestedHydratedRow }>, IsNullable, HasJoin>;
+  false, false>) => MappedHydratedQueryBuilder<MakePrefix<Prefix, NoInfer<K$1>>, JoinedQueryDB, JoinedQueryTB, JoinedQueryRow, NestedLocalDB, NestedLocalRow, NestedHydratedRow, any, any>): HydratedQueryBuilder<Prefix, JoinedQueryDB, JoinedQueryTB, JoinedQueryRow, NestedLocalDB, LocalRow & ApplyPrefixes<MakePrefix<"", K$1>, NestedLocalRow>, Extend<HydratedRow, { [_ in K$1]: NestedHydratedRow }>, IsNullable, HasJoin>;
   /**
    * 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 parent rows
@@ -993,4 +979,4 @@ declare class KeyByMismatchError extends KyselyHydrateError {
   constructor(thisKeyBy: string, otherKeyBy: string);
 }
 //#endregion
-export { AmbiguousColumnReferenceError, ExpectedOneItemError, HydratePlugin, type Hydrator, InvalidInstanceError, KeyByMismatchError, KyselyHydrateError, UnexpectedCaseError, UnexpectedComplexAliasError, UnexpectedSelectAllError, UnexpectedSelectionTypeError, UnsupportedAliasNodeTypeError, UnsupportedNodeTypeError, UnsupportedTableAliasNodeTypeError, WildcardSelectionError, createHydrator, hydrate, hydrateData, map };
+export { AmbiguousColumnReferenceError, ExpectedOneItemError, HydratePlugin, type Hydrator, InvalidInstanceError, KeyByMismatchError, KyselyHydrateError, UnexpectedCaseError, UnexpectedComplexAliasError, UnexpectedSelectAllError, UnexpectedSelectionTypeError, UnsupportedAliasNodeTypeError, UnsupportedNodeTypeError, UnsupportedTableAliasNodeTypeError, WildcardSelectionError, createHydrator, hydrate, hydrateData, isFullHydrator, map };

package/dist/index.mjs

@@ -240,105 +240,89 @@ const ensureFieldsAccessor = createPrivateAccessor();
 * @internal
 */
 const ensureFields = ensureFieldsAccessor.call;
+const IsFullHydrator = Symbol("HydratorType");
 /**
-* A configuration for how to hydrate flat database rows into a denormalized structure.
+* Determines if a hydrator is a full hydrator, meaning it has not had a .map()
+* applied to it yet.
 *
-* The Hydrator class provides a fluent API for configuring:
-* - Fields to include (with optional transformations)
-* - Extra computed fields
-* - Nested collections (using `has()` methods)
-* - Attached collections (using `attach()` methods)
-*
-* Once configured, call `hydrate()` to transform input data into the denormalized output.
+* @param hydrator - The hydrator to check
+* @returns True if the hydrator is a full hydrator, false otherwise
+*/
+const isFullHydrator = (hydrator) => {
+	return hydrator[IsFullHydrator];
+};
+/**
+* Asserts that a hydrator is a full hydrator and returns it.
 *
-* @template Input - The type of the input data (typically from a database query)
-* @template Output - The type of the hydrated output structure
+* @internal
 */
-var Hydrator = class Hydrator {
+const asFullHydrator = (hydrator) => {
+	if (isFullHydrator(hydrator)) return hydrator;
+	throw new Error("Hydrator is not a full hydrator");
+};
+/**
+* Implements the entire inheritance chain of Hydrators.
+*/
+var HydratorImpl = class HydratorImpl {
 	#props;
 	constructor(props) {
 		this.#props = props;
 		ensureFieldsAccessor.register(this, this.#ensureFields.bind(this));
 	}
-	/**
-	* Configures which fields to include in the hydrated output.
-	*
-	* @param fields - An object mapping field names to either `true` (include as-is)
-	*   or a transformation function
-	* @returns A new Hydrator with the fields configuration merged
-	*/
+	get [IsFullHydrator]() {
+		return !this.#props.mapFns?.length;
+	}
 	fields(fields) {
-		return new Hydrator({
+		return new HydratorImpl({
 			...this.#props,
 			fields: addObjectToMap(this.#props.fields, fields)
 		});
 	}
-	/**
-	* Omits specified fields from the hydrated output.
-	*
-	* @param keys - Field names to omit from the output
-	* @returns A new Hydrator with the fields omitted
-	*/
 	omit(keys) {
 		const omitFields = Object.fromEntries(keys.map((key) => [key, false]));
-		return new Hydrator({
+		return new HydratorImpl({
 			...this.#props,
 			fields: addObjectToMap(this.#props.fields, omitFields)
 		});
 	}
-	/**
-	* Private method to ensure fields are included in the output if they don't
-	* already have an explicit configuration (including explicit omission).
-	* Used by HydratedQueryBuilder via the exported ensureFields helper function.
-	*/
 	#ensureFields(fieldNames) {
 		const clone = new Map(this.#props.fields);
 		for (const name of fieldNames) if (!clone.has(name)) clone.set(name, true);
-		return new Hydrator({
+		return new HydratorImpl({
 			...this.#props,
 			fields: clone
 		});
 	}
-	/**
-	* Configures extra computed fields to add to the hydrated output.
-	*
-	* @param extras - An object mapping field names to functions that compute
-	*   the field value from the entire input
-	* @returns A new Hydrator with the extras configuration merged
-	*/
 	extras(extras) {
-		return new Hydrator({
+		return new HydratorImpl({
 			...this.#props,
 			extras: addObjectToMap(this.#props.extras, extras)
 		});
 	}
-	/**
-	* Extends this Hydrator with the configuration from another Hydrator.  The
-	* other Hydrator's configuration takes precedence in case of conflicts.
-	*
-	* Both hydrators must have the same `keyBy`, and any overlapping fields
-	* between the two input types must have compatible types.
-	*
-	* @param other - The Hydrator to extend with
-	* @returns A new Hydrator with merged configuration
-	* @throws {KeyByMismatchError} If the keyBy configurations don't match
-	*/
 	extend(other) {
+		const otherImpl = other;
 		const thisKeyBy = JSON.stringify(this.#props.keyBy);
-		const otherKeyBy = JSON.stringify(other.#props.keyBy);
+		const otherKeyBy = JSON.stringify(otherImpl.#props.keyBy);
 		if (thisKeyBy !== otherKeyBy) throw new KeyByMismatchError(thisKeyBy, otherKeyBy);
 		const ownProps = this.#props;
-		const otherProps = other.#props;
-		return new Hydrator({
+		const otherProps = otherImpl.#props;
+		return new HydratorImpl({
 			keyBy: otherProps.keyBy,
 			fields: new Map([...ownProps.fields ?? [], ...otherProps.fields ?? []]),
 			extras: new Map([...ownProps.extras ?? [], ...otherProps.extras ?? []]),
 			collections: new Map([...ownProps.collections ?? [], ...otherProps.collections ?? []]),
-			attachedCollections: new Map([...ownProps.attachedCollections ?? [], ...otherProps.attachedCollections ?? []])
+			attachedCollections: new Map([...ownProps.attachedCollections ?? [], ...otherProps.attachedCollections ?? []]),
+			mapFns: [...this.#props.mapFns ?? [], ...otherProps.mapFns ?? []]
+		});
+	}
+	map(fn) {
+		return new HydratorImpl({
+			...this.#props,
+			mapFns: [...this.#props.mapFns ?? [], fn]
 		});
 	}
 	has(mode, key, prefix, hydrator) {
-		return new Hydrator({
+		return new HydratorImpl({
 			...this.#props,
 			collections: new Map(this.#props.collections).set(key, {
 				prefix,
@@ -347,42 +331,17 @@ var Hydrator = class Hydrator {
 			})
 		});
 	}
-	/**
-	* Shorthand for `has("many", ...)` - configures a nested array collection.
-	*
-	* @param key - The key name for the collection in the output
-	* @param prefix - The prefix used in the input data (e.g., "posts$$")
-	* @param hydrator - The Hydrator configuration for the child entities
-	* @returns A new Hydrator with the nested collection added
-	*/
 	hasMany(key, prefix, hydrator) {
 		return this.has("many", key, prefix, hydrator);
 	}
-	/**
-	* Shorthand for `has("one", ...)` - configures a nested nullable single entity.
-	*
-	* @param key - The key name for the entity in the output
-	* @param prefix - The prefix used in the input data (e.g., "author$$")
-	* @param hydrator - The Hydrator configuration for the child entity
-	* @returns A new Hydrator with the nested entity added
-	*/
 	hasOne(key, prefix, hydrator) {
 		return this.has("one", key, prefix, hydrator);
 	}
-	/**
-	* Shorthand for `has("oneOrThrow", ...)` - configures a nested non-nullable single entity.
-	* Throws an error if the entity is not found during hydration.
-	*
-	* @param key - The key name for the entity in the output.
-	* @param prefix - The prefix used in the input data (e.g., "author$$").
-	* @param hydrator - The Hydrator configuration for the child entity.
-	* @returns A new Hydrator with the nested entity added.
-	*/
 	hasOneOrThrow(key, prefix, hydrator) {
 		return this.has("oneOrThrow", key, prefix, hydrator);
 	}
 	attach(mode, key, fetchFn, keys) {
-		return new Hydrator({
+		return new HydratorImpl({
 			...this.#props,
 			attachedCollections: new Map(this.#props.attachedCollections).set(key, {
 				mode,
@@ -392,40 +351,12 @@ var Hydrator = class Hydrator {
 			})
 		});
 	}
-	/**
-	* Shorthand for `attach("many", ...)` - configures an attached array collection.
-	*
-	* @param key - The property name for the collection in the output.
-	* @param fetchFn - A function that fetches and hydrates the attached data.
-	* @param keys.matchChild - The key(s) on the attached output to use for matching to parents.
-	* @param keys.toParent - The key(s) on the parent input to compare with the child's key.
-	* @returns A new Hydrator with the attached collection added.
-	*/
 	attachMany(key, fetchFn, keys) {
 		return this.attach("many", key, fetchFn, keys);
 	}
-	/**
-	* Shorthand for `attach("one", ...)` - configures an attached nullable single entity.
-	*
-	* @param key - The property name for the entity in the output.
-	* @param fetchFn - A function that fetches and hydrates the attached data.
-	* @param keys.matchChild - The key(s) on the attached output to use for matching to parents.
-	* @param keys.toParent - The key(s) on the parent input to compare with the child's key.
-	* @returns A new Hydrator with the attached entity added.
-	*/
 	attachOne(key, fetchFn, keys) {
 		return this.attach("one", key, fetchFn, keys);
 	}
-	/**
-	* Shorthand for `attach("oneOrThrow", ...)` - configures an attached non-nullable single entity.
-	* Throws an error if the entity is not found during hydration.
-	*
-	* @param key - The property name for the entity in the output
-	* @param fetchFn - A function that fetches and hydrates the attached data
-	* @param keys.matchChild - The key(s) on the attached output to use for matching to parents
-	* @param keys.toParent - The key(s) on the parent input to compare with the child's key.
-	* @returns A new Hydrator with the attached entity added
-	*/
 	attachOneOrThrow(key, fetchFn, keys) {
 		return this.attach("oneOrThrow", key, fetchFn, keys);
 	}
@@ -483,6 +414,12 @@ var Hydrator = class Hydrator {
 			const attachedRows = attachedDataMap.get(mapKey)?.get(inputKey);
 			entity[key] = applyCollectionMode(attachedRows, collection.mode, key);
 		}
+		const { mapFns } = this.#props;
+		if (mapFns) {
+			let result = entity;
+			for (const mapFn of mapFns) result = mapFn(result);
+			return result;
+		}
 		return entity;
 	}
 	/**
@@ -519,7 +456,7 @@ var Hydrator = class Hydrator {
 	}
 };
 function createHydrator(keyBy) {
-	return new Hydrator({ keyBy: keyBy ?? DEFAULT_KEY_BY });
+	return new HydratorImpl({ keyBy: keyBy ?? DEFAULT_KEY_BY });
 }
 function hydrateData(input, hydrator) {
 	hydrator = typeof hydrator === "function" ? hydrator(createHydrator) : hydrator;
@@ -621,9 +558,8 @@ function extractSelectionName(selectionNode) {
 //#endregion
 //#region src/query-builder.ts
 /**
-* Implementation of the {@link HydratedQueryBuilder} interface.
-*
-* @internal
+* Implementation of the {@link HydratedQueryBuilder} interface as well as the
+* {@link MappedHydratedQueryBuilder} interface; there is no runtime distinction.
 */
 var HydratedQueryBuilderImpl = class HydratedQueryBuilderImpl {
 	#props;
@@ -642,9 +578,7 @@ var HydratedQueryBuilderImpl = class HydratedQueryBuilderImpl {
 	toOperationNode() {
 		return this.#props.qb.toOperationNode();
 	}
-	_generics() {
-		return this;
-	}
+	get _generics() {}
 	modify(modifier) {
 		return new HydratedQueryBuilderImpl({
 			...this.#props,
@@ -654,28 +588,10 @@ var HydratedQueryBuilderImpl = class HydratedQueryBuilderImpl {
 	toQuery() {
 		return this.#props.qb;
 	}
-	extras(extras) {
-		return new HydratedQueryBuilderImpl({
-			...this.#props,
-			hydrator: this.#props.hydrator.extras(extras)
-		});
-	}
-	mapFields(mappings) {
+	map(transform) {
 		return new HydratedQueryBuilderImpl({
 			...this.#props,
-			hydrator: this.#props.hydrator.fields(mappings)
-		});
-	}
-	omit(keys) {
-		return new HydratedQueryBuilderImpl({
-			...this.#props,
-			hydrator: this.#props.hydrator.omit(keys)
-		});
-	}
-	with(hydrator) {
-		return new HydratedQueryBuilderImpl({
-			...this.#props,
-			hydrator: this.#props.hydrator.extend(hydrator)
+			hydrator: this.#props.hydrator.map(transform)
 		});
 	}
 	#hydrate(rows) {
@@ -697,6 +613,30 @@ var HydratedQueryBuilderImpl = class HydratedQueryBuilderImpl {
 		const result = await this.#props.qb.executeTakeFirstOrThrow(errorConstructor);
 		return this.#hydrate(result);
 	}
+	extras(extras) {
+		return new HydratedQueryBuilderImpl({
+			...this.#props,
+			hydrator: asFullHydrator(this.#props.hydrator).extras(extras)
+		});
+	}
+	mapFields(mappings) {
+		return new HydratedQueryBuilderImpl({
+			...this.#props,
+			hydrator: asFullHydrator(this.#props.hydrator).fields(mappings)
+		});
+	}
+	omit(keys) {
+		return new HydratedQueryBuilderImpl({
+			...this.#props,
+			hydrator: asFullHydrator(this.#props.hydrator).omit(keys)
+		});
+	}
+	with(hydrator) {
+		return new HydratedQueryBuilderImpl({
+			...this.#props,
+			hydrator: asFullHydrator(this.#props.hydrator).extend(hydrator)
+		});
+	}
 	#addJoin(mode, key, jb, keyBy = DEFAULT_KEY_BY) {
 		const outputNb = jb(new HydratedQueryBuilderImpl({
 			qb: this.#props.qb,
@@ -706,7 +646,7 @@ var HydratedQueryBuilderImpl = class HydratedQueryBuilderImpl {
 		return new HydratedQueryBuilderImpl({
 			...this.#props,
 			qb: outputNb.#props.qb,
-			hydrator: this.#props.hydrator.has(mode, key, makePrefix("", key), outputNb.#props.hydrator)
+			hydrator: asFullHydrator(this.#props.hydrator).has(mode, key, makePrefix("", key), outputNb.#props.hydrator)
 		});
 	}
 	hasMany(key, jb, keyBy) {
@@ -721,7 +661,7 @@ var HydratedQueryBuilderImpl = class HydratedQueryBuilderImpl {
 	#addAttach(mode, key, fetchFn, keys) {
 		return new HydratedQueryBuilderImpl({
 			...this.#props,
-			hydrator: this.#props.hydrator.attach(mode, key, fetchFn, keys)
+			hydrator: asFullHydrator(this.#props.hydrator).attach(mode, key, fetchFn, keys)
 		});
 	}
 	attachMany(key, fetchFn, keys) {
@@ -738,7 +678,7 @@ var HydratedQueryBuilderImpl = class HydratedQueryBuilderImpl {
 		return new HydratedQueryBuilderImpl({
 			...this.#props,
 			qb: this.#props.qb.select(prefixedSelections),
-			hydrator: this.#props.hydrator.fields(Object.fromEntries(prefixedSelections.map((selection$1) => [selection$1.originalName, true])))
+			hydrator: asFullHydrator(this.#props.hydrator).fields(Object.fromEntries(prefixedSelections.map((selection$1) => [selection$1.originalName, true])))
 		});
 	}
 	innerJoin(...args) {
@@ -1160,4 +1100,4 @@ var HydratePlugin = class {
 };
 
 //#endregion
-export { AmbiguousColumnReferenceError, ExpectedOneItemError, HydratePlugin, InvalidInstanceError, KeyByMismatchError, KyselyHydrateError, UnexpectedCaseError, UnexpectedComplexAliasError, UnexpectedSelectAllError, UnexpectedSelectionTypeError, UnsupportedAliasNodeTypeError, UnsupportedNodeTypeError, UnsupportedTableAliasNodeTypeError, WildcardSelectionError, createHydrator, hydrate, hydrateData, map };
+export { AmbiguousColumnReferenceError, ExpectedOneItemError, HydratePlugin, InvalidInstanceError, KeyByMismatchError, KyselyHydrateError, UnexpectedCaseError, UnexpectedComplexAliasError, UnexpectedSelectAllError, UnexpectedSelectionTypeError, UnsupportedAliasNodeTypeError, UnsupportedNodeTypeError, UnsupportedTableAliasNodeTypeError, WildcardSelectionError, createHydrator, hydrate, hydrateData, isFullHydrator, map };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kysely-hydrate",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Explicit ORM-style queries with Kysely",
   "license": "MIT",
   "author": {