kysely-hydrate 0.2.1 → 0.4.0

package/README.md

@@ -131,6 +131,7 @@ By design, Kysely has the following constraints:
     - [`.hasMany()`](#hasmany)
     - [`.hasOne()`](#hasone)
     - [`.hasOneOrThrow()`](#hasoneorthrow)
+    - [Hydrated lateral joins](#hydrated-lateral-joins)
   - [Application-level joins with `.attach*()`](#application-level-joins-with-attach)
     - [`.attachMany()`](#attachmany)
     - [`.attachOne()`](#attachone)
@@ -138,6 +139,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 +148,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)
@@ -463,12 +466,86 @@ but you know the record must exist.
 
 > [!NOTE]
 > Like `hydrate()`, `hasOneOrThrow()` also accepts an optional final `keyBy` argument with the
-> same semantics (see [Keying and deduplication with `keyBy`](#keying-and-deduplication-with-keyby)).
+> same semantics (see [Keying and deduplication with
+> `keyBy`](#keying-and-deduplication-with-keyby)).
+
+#### Hydrated lateral joins
+
+Kysely supports lateral joins by passing a subquery to methods like
+`innerJoinLateral`, `leftJoinLateral`, etc.
+
+In addition to Kysely's default behavior, Kysely Hydrate also lets you pass an
+**aliased hydrated subquery** to these methods. When you do, the subquery’s
+selections are automatically added to the parent query (with the usual
+prefixing), and the nested result is hydrated according to the nested hydration
+config. This makes it possible to compose hydrated queries through lateral
+joins.
+
+Here’s an example selecting each user and their latest post (scoped per-user
+inside the lateral subquery):
+
+```ts
+const query = hydrate(db.selectFrom("users").select(["users.id", "users.username"]), "id")
+  .hasOne("latestPost", ({ innerJoinLateral }) =>
+    innerJoinLateral((db) =>
+      hydrate(
+        db
+          .selectFrom("posts")
+          .select(["posts.id", "posts.title"])
+          .whereRef("posts.user_id", "=", "users.id")
+          .orderBy("posts.id", "desc")
+          .limit(1),
+        "id",
+      ).as("latest_post_subquery"),
+      // You can omit `(join) => join.onTrue()` for the hydrated-subquery overload.
+    ),
+  );
+
+const result = await query.execute();
+// ⬇
+type Result = Array<{
+  id: number;
+  username: string;
+  latestPost: { id: number; title: string };
+}>;
+```
+
+The hydrated lateral subquery is “hoisted” into the parent select list, and its
+columns are prefixed under the relation key (e.g. `latestPost$$id`,
+`latestPost$$title`) so the hydration layer can un-flatten them.
+
+```sql
+select
+  "users"."id",
+  "users"."username",
+  "latest_post_subquery"."id" as "latestPost$$id",
+  "latest_post_subquery"."title" as "latestPost$$title"
+from "users"
+inner join lateral (
+  select "posts"."id", "posts"."title"
+  from "posts"
+  where "posts"."user_id" = "users"."id"
+  limit ?
+) as "latest_post_subquery" on true
+```
+
+> [!WARNING]
+> You cannot use `.selectAll()` in cases where Kysely Hydrate needs to resolve
+> and rewrite nested selections for prefixing. Prefer explicit `.select([...])`
+> (it will throw if selections can’t be resolved).
+
+> [!WARNING]
+> You're still writing SQL.  Lateral joins are powerful, but it’s easy to build
+> queries that don’t compose the way you expect (limits/order-by scopes,
+> correlation, etc). When in doubt, inspect the output with
+> `.toQuery().compile()`.
 
 #### SQL output
 
 Kysely Hydrate produces the SQL you tell it to with exactly one exception: it
-aliases nested selections to avoid naming collisions.
+aliases nested selections to avoid naming collisions.  (Kysely Hydrate also
+hoists selections from hydrated lateral join subqueries, as described
+[above](#hydrated-lateral-joins)—but only if you use that feature.)
 
 For example, `users.id` remains `users.id`, but `posts.id` nested under "posts"
 becomes `posts$$id`.  The hydration layer then un-flattens these aliases back
@@ -779,6 +856,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 +1153,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 +1174,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 +1289,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);
 // ⬇