kysely-hydrate 0.9.0 → 0.10.1

package/README.md

@@ -36,7 +36,7 @@ compromising the power or control of SQL. It offers these features:
 - [Application-level joins](#application-level-joins-with-attach)
 - [Mapped fields](#mapped-properties-with-mapfields) in hydrated queries
 - [Computed properties](#computed-properties-with-extras) in hydrated queries
-- [Hydrated writes](#hydrated-writes) (INSERT/UPDATE/DELETE with RETURNING)
+- [Hydrated writes](#hydrated-writes) (INSERT/UPDATE/DELETE with RETURNING, including multi-write CTE orchestration)
 - [Counts, ordering, and limits](#pagination-and-aggregation) accounting for row explosion from nested joins
 
 For example:
@@ -138,6 +138,9 @@ type Result = Array<{
   - [Output transformations with `.map()`](#output-transformations-with-map)
   - [Composable mappings with `.with()`](#composable-mappings-with-with)
   - [Hydrated writes](#hydrated-writes)
+    - [Initializing with writes](#initializing-with-writes-querysetas)
+    - [Reusing query sets for writes](#reusing-query-sets-for-writes)
+    - [Multi-write orchestration with `.writeAs()` and `.write()`](#multi-write-orchestration-with-writeas-and-write)
   - [Type helpers](#type-helpers)
 - [Hydrators](#hydrators)
   - [Creating hydrators with `createHydrator()`](#creating-hydrators-with-createhydrator)
@@ -1169,6 +1172,97 @@ type Result = {
 };
 ```
 
+#### Multi-write orchestration with `.writeAs()` and `.write()`
+
+Sometimes a single `INSERT`, `UPDATE`, or `DELETE` isn't enough and you need to
+orchestrate multiple writes in one statement. For example, updating a user _and_
+inserting an audit log entry atomically.
+
+In Postgres, this is done with data-modifying CTEs: a `SELECT` whose `WITH`
+clause contains `INSERT`, `UPDATE`, or `DELETE` statements. Kysely supports this
+natively with `.with()`.
+
+`writeAs()` takes two callbacks. The first builds CTEs and returns a query
+creator. The second builds the SELECT that references CTE names. The CTEs are
+placed at the top level of the generated SQL—which is where Postgres requires
+data-modifying CTEs to live—while the SELECT becomes a derived table with no
+CTEs to strip.
+
+```ts
+const result = await querySet(db)
+	.writeAs(
+		"updated",
+		(db) =>
+			db
+				// Data-modifying CTE: update the user
+				.with("updated", (qb) =>
+					qb
+						.updateTable("users")
+						.set({ email: "new@example.com" })
+						.where("id", "=", userId)
+						.returningAll(),
+				)
+				// Data-modifying CTE: insert an audit log entry
+				.with("audit", (qb) =>
+					qb.insertInto("audit_log").values({ userId, action: "email_changed" }).returning(["id"]),
+				),
+		// Select from the update result
+		(qc) => qc.selectFrom("updated").select(["id", "username", "email"]),
+	)
+	.executeTakeFirstOrThrow();
+// ⬇
+type Result = { id: number; username: string; email: string };
+```
+
+**Generated SQL:**
+
+```sql
+WITH "updated" AS (
+  UPDATE "users" SET "email" = $1 WHERE "id" = $2 RETURNING *
+),
+"audit" AS (
+  INSERT INTO "audit_log" ("userId", "action") VALUES ($3, $4) RETURNING "id"
+)
+SELECT "updated"."id", "updated"."username", "updated"."email"
+FROM (SELECT "id", "username", "email" FROM "updated") AS "updated"
+```
+
+Like `insertAs` and friends, `writeAs()` supports joins, extras, and all the
+usual query set features.
+
+`.write()` is the instance-method equivalent—it switches the base query of an
+existing query set, just like `.insert()` does for inserts:
+
+```ts
+const usersQuerySet = querySet(db)
+	.selectAs("user", db.selectFrom("users").select(["id", "username", "email"]))
+	.leftJoinMany("posts" /* ... */)
+	.extras({ gravatarUrl: (u) => getGravatar(u.email) });
+
+// Reuse the canonical query set for a select query with data-modifying CTE.
+const result = await usersQuerySet
+	.write(
+		(db) =>
+			db.with("updated", (qb) =>
+				qb
+					.updateTable("users")
+					.set({ email: "new@example.com" })
+					.where("id", "=", userId)
+					.returningAll(),
+			),
+		(qc) => qc.selectFrom("updated").select(["id", "username", "email"]),
+	)
+	.executeTakeFirstOrThrow();
+// ⬇ Result includes posts and gravatarUrl!
+type Result = {
+	id: number;
+	username: string;
+	email: string;
+	gravatarUrl: string;
+	posts: Array<{ id: number; title: string; user_id: number }>;
+};
+```
+
 ### Type Helpers
 
 Kysely Hydrate provides type helpers that mirror

package/dist/index.d.mts

@@ -1366,6 +1366,18 @@ interface MappedQuerySet<in out T extends TQuerySet> extends k.Compilable, k.Ope
    * Like {@link insert}, but switches to a `DELETE` statement.
    */
   delete<IQB extends k.DeleteQueryBuilder<any, any, T["BaseQuery"]["O"]>>(dqb: DeleteQueryBuilderOrFactory<T["DB"], IQB>): MaybeMappedQuerySet<TWithBaseQuery<T, InferTDeleteQuery<IQB>>>;
+  /**
+   * Switches the base query to a `SELECT` that may contain data-modifying CTEs.
+   *
+   * Callback 1 receives `db`, builds CTEs, and returns a query creator.
+   * Callback 2 receives a query creator typed with the CTE names and builds
+   * the SELECT.
+   *
+   * @param cteFn - Builds CTEs; returns a query creator.
+   * @param selectFn - Builds the SELECT referencing CTE names.
+   * @returns A new QuerySet with the write query as the base.
+   */
+  write<NewDB, SQB extends k.SelectQueryBuilder<any, any, T["BaseQuery"]["O"]>>(cteFn: (db: k.Kysely<T["DB"]>) => k.QueryCreator<NewDB>, selectFn: (qc: k.QueryCreator<NewDB>) => SQB): MaybeMappedQuerySet<TWithBaseQuery<T, InferTSelectQuery<SQB>>>;
 }
 /**
  * A query set that supports nested joins and automatic hydration.
@@ -2573,6 +2585,36 @@ declare class QuerySetCreator<in out DB$1> {
    */
   deleteAs<Alias extends string, DQB extends k.DeleteQueryBuilder<any, any, InputWithDefaultKey>>(alias: Alias, query: DeleteQueryBuilderOrFactory<DB$1, DQB>): InitialQuerySet<DB$1, Alias, InferTDeleteQuery<DQB>>;
   deleteAs<Alias extends string, UQB extends AnyDeleteQueryBuilder>(alias: Alias, query: DeleteQueryBuilderOrFactory<DB$1, UQB>, keyBy: KeyBy<InferO<NoInfer<UQB>>>): InitialQuerySet<DB$1, Alias, InferTDeleteQuery<UQB>>;
+  /**
+   * Initializes a new query set with a base `SELECT` query that may contain
+   * data-modifying CTEs.
+   *
+   * Any CTEs on the provided query will be hoisted to the top level of the
+   * generated SQL, which is required by Postgres for data-modifying CTEs.
+   *
+   * This enables multi-write CTE orchestration patterns like:
+   * ```ts
+   * const result = await querySet(db)
+   *   .writeAs("updated",
+   *     (db) => db.with("updated", (qb) =>
+   *       qb.updateTable("users")
+   *         .set({ email: "new@example.com" })
+   *         .where("id", "=", 1)
+   *         .returningAll()
+   *     ),
+   *     (qc) => qc.selectFrom("updated").selectAll()
+   *   )
+   *   .executeTakeFirst();
+   * ```
+   *
+   * @param alias - The alias for the base query.
+   * @param cteFn - A callback that receives `db` and builds the CTEs, returning a query creator.
+   * @param selectFn - A callback that receives the query creator and builds the SELECT referencing CTE names.
+   * @param keyBy - The key(s) to uniquely identify rows. Defaults to `"id"`.
+   * @returns A new QuerySet.
+   */
+  writeAs<Alias extends string, NewDB, SQB extends k.SelectQueryBuilder<any, any, InputWithDefaultKey>>(alias: Alias, cteFn: (db: k.Kysely<DB$1>) => k.QueryCreator<NewDB>, selectFn: (qc: k.QueryCreator<NewDB>) => SQB): InitialQuerySet<DB$1, Alias, InferTSelectQuery<SQB>>;
+  writeAs<Alias extends string, NewDB, SQB extends AnySelectQueryBuilder>(alias: Alias, cteFn: (db: k.Kysely<DB$1>) => k.QueryCreator<NewDB>, selectFn: (qc: k.QueryCreator<NewDB>) => SQB, keyBy: KeyBy<InferO<NoInfer<SQB>>>): InitialQuerySet<DB$1, Alias, InferTSelectQuery<SQB>>;
 }
 /**
  * Creates a new {@link QuerySetCreator} for building query sets with nested joins

package/dist/index.mjs

@@ -691,6 +691,25 @@ function extractSelectionName(selectionNode) {
 * @see {@link QuerySet} - Query builder interface
 * @see {@link MappedQuerySet} - Mapped query builder interface
 */
+/**
+* A stateless Kysely plugin that strips the WITH clause from a
+* SelectQueryNode.  Used to remove CTEs that the query creator
+* attaches to queries built via `selectFn` in `.write()` / `.writeAs()`.
+* The CTEs are already captured separately in `writeQueryCreator`.
+*/
+const stripWithPlugin = {
+	transformQuery(args) {
+		const node = args.node;
+		if (node.kind === "SelectQueryNode" && node.with) return {
+			...node,
+			with: void 0
+		};
+		return node;
+	},
+	async transformResult(args) {
+		return args.result;
+	}
+};
 const filteringJoins = new Set([
 	"innerJoin",
 	"innerJoinLateral",
@@ -733,8 +752,16 @@ var QuerySetImpl = class QuerySetImpl {
 		return this.#props.baseQuery;
 	}
 	#getSelectFromBase(isNested, isLocalSubquery) {
-		const { db, baseQuery, baseAlias } = this.#props;
-		if (isSelectQueryBuilder(baseQuery)) return applyHoistedSelections(db.selectFrom(baseQuery.as(baseAlias)), baseQuery, baseAlias);
+		const { db, baseQuery, baseAlias, writeQueryCreator } = this.#props;
+		if (isSelectQueryBuilder(baseQuery)) {
+			if (writeQueryCreator) {
+				if (isNested) throw new InvalidJoinedQuerySetError(baseAlias);
+				let qb$1 = writeQueryCreator.selectFrom(baseQuery.as(baseAlias));
+				qb$1 = applyHoistedSelections(qb$1, baseQuery, baseAlias);
+				return qb$1;
+			}
+			return applyHoistedSelections(db.selectFrom(baseQuery.as(baseAlias)), baseQuery, baseAlias);
+		}
 		if (isNested) throw new InvalidJoinedQuerySetError(baseAlias);
 		let qb = (isLocalSubquery ? db : db.with("__base", () => baseQuery)).selectFrom(`__base as ${baseAlias}`);
 		if (!isLocalSubquery) return qb.selectAll(baseAlias);
@@ -1052,6 +1079,14 @@ var QuerySetImpl = class QuerySetImpl {
 	delete(iqb) {
 		return this.#asWrite(iqb);
 	}
+	write(cteFn, selectFn) {
+		const qc = cteFn(this.#props.db);
+		const baseQuery = selectFn(qc).withPlugin(stripWithPlugin);
+		return this.#clone({
+			baseQuery,
+			writeQueryCreator: qc
+		});
+	}
 };
 /**
 * Factory for creating query sets. Obtained by calling {@link querySet}.
@@ -1078,7 +1113,8 @@ var QuerySetCreator = class {
 			orderBy: [],
 			orderByKeys: true,
 			frontModifiers: [],
-			endModifiers: []
+			endModifiers: [],
+			writeQueryCreator: null
 		});
 	}
 	selectAs(alias, query, keyBy = DEFAULT_KEY_BY) {
@@ -1093,6 +1129,26 @@ var QuerySetCreator = class {
 	deleteAs(alias, query, keyBy = DEFAULT_KEY_BY) {
 		return this.#createQuerySet(alias, query, keyBy);
 	}
+	writeAs(alias, cteFn, selectFn, keyBy) {
+		const qc = cteFn(this.#db);
+		const baseQuery = selectFn(qc).withPlugin(stripWithPlugin);
+		return new QuerySetImpl({
+			db: this.#db,
+			baseAlias: alias,
+			baseQuery,
+			keyBy: keyBy ?? DEFAULT_KEY_BY,
+			hydrator: createHydrator().orderByKeys(),
+			joinCollections: /* @__PURE__ */ new Map(),
+			attachCollections: /* @__PURE__ */ new Map(),
+			limit: null,
+			offset: null,
+			orderBy: [],
+			orderByKeys: true,
+			frontModifiers: [],
+			endModifiers: [],
+			writeQueryCreator: qc
+		});
+	}
 };
 /**
 * Creates a new {@link QuerySetCreator} for building query sets with nested joins

package/package.json

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