kysely-hydrate 0.9.0 → 0.10.0

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,95 @@ 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()` initializes a query set from such a query. Any CTEs on the provided
+`SELECT` are hoisted to the top level of the generated SQL—which is where
+Postgres requires data-modifying CTEs to live.
+
+```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
+			.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(),
+			)
+			.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,25 @@ 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.
+   *
+   * 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.
+   * The stripped `SELECT` is inlined as a derived table, just like
+   * {@link selectAs}.
+   *
+   * This enables multi-write CTE orchestration patterns like:
+   * ```sql
+   * WITH "updated" AS (UPDATE ... RETURNING *),
+   *      "audit" AS (INSERT INTO audit_log ... RETURNING *)
+   * SELECT * FROM "updated"
+   * ```
+   *
+   * @param sqb - A select query builder (possibly with CTEs) or factory function.
+   * @returns A new QuerySet with the write query as the base.
+   */
+  write<SQB extends k.SelectQueryBuilder<any, any, T["BaseQuery"]["O"]>>(sqb: WriteQueryBuilderOrFactory<T["DB"], SQB>): MaybeMappedQuerySet<TWithBaseQuery<T, InferTSelectQuery<SQB>>>;
 }
 /**
  * A query set that supports nested joins and automatic hydration.
@@ -2465,6 +2484,8 @@ type UpdateQueryBuilderFactory<InitialDB, UQB extends AnyUpdateQueryBuilder> = (
 type UpdateQueryBuilderOrFactory<InitialDB, UQB extends AnyUpdateQueryBuilder> = UQB | UpdateQueryBuilderFactory<InitialDB, UQB>;
 type DeleteQueryBuilderFactory<InitialDB, DQB extends AnyDeleteQueryBuilder> = (db: DeleteCreator<InitialDB>) => DQB;
 type DeleteQueryBuilderOrFactory<InitialDB, DQB extends AnyDeleteQueryBuilder> = DQB | DeleteQueryBuilderFactory<InitialDB, DQB>;
+type WriteQueryBuilderFactory<InitialDB, SQB extends AnySelectQueryBuilder> = (db: k.Kysely<InitialDB>) => SQB;
+type WriteQueryBuilderOrFactory<InitialDB, SQB extends AnySelectQueryBuilder> = SQB | WriteQueryBuilderFactory<InitialDB, SQB>;
 interface NestedQuerySetFn<in out DB$1, in out Alias extends string> {
   <SQB extends k.SelectQueryBuilder<any, any, InputWithDefaultKey>>(query: SQB): InitialQuerySet<DB$1, Alias, InferTSelectQuery<SQB>>;
   <SQB extends AnySelectQueryBuilder>(query: SQB, keyBy: KeyBy<InferO<NoInfer<SQB>>>): InitialQuerySet<DB$1, Alias, InferTSelectQuery<SQB>>;
@@ -2573,6 +2594,37 @@ 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()
+   *       )
+   *       .selectFrom("updated")
+   *       .selectAll()
+   *   )
+   *   .executeTakeFirst();
+   * ```
+   *
+   * @param alias - The alias for the base query.
+   * @param query - A Kysely select query builder (possibly with CTEs) or factory function.
+   * @param keyBy - The key(s) to uniquely identify rows. Defaults to `"id"`.
+   * @returns A new QuerySet.
+   */
+  writeAs<Alias extends string, SQB extends k.SelectQueryBuilder<any, any, InputWithDefaultKey>>(alias: Alias, query: WriteQueryBuilderOrFactory<DB$1, SQB>): InitialQuerySet<DB$1, Alias, InferTSelectQuery<SQB>>;
+  writeAs<Alias extends string, SQB extends AnySelectQueryBuilder>(alias: Alias, query: WriteQueryBuilderOrFactory<DB$1, 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

@@ -609,6 +609,56 @@ function groupByKey(prefix, inputs, keyBy) {
 	return map;
 }
 
+//#endregion
+//#region src/helpers/cte-hoisting.ts
+/**
+* Extracts the CTE expressions from a query builder's operation node.
+*/
+function extractCTEs(qb) {
+	return qb.toOperationNode().with?.expressions;
+}
+/**
+* A Kysely plugin that strips the WITH clause from a SelectQueryNode,
+* effectively removing all CTEs from the query.
+*/
+var StripWithPlugin = class {
+	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;
+	}
+};
+/**
+* A Kysely plugin that prepends CTE expressions to the outer query's WithNode.
+*/
+var AddCTEsPlugin = class {
+	#expressions;
+	constructor(expressions) {
+		this.#expressions = expressions;
+	}
+	transformQuery(args) {
+		const node = args.node;
+		if (node.kind !== "SelectQueryNode") return node;
+		const existing = node.with?.expressions ?? [];
+		const merged = [...this.#expressions, ...existing];
+		let withNode = k.WithNode.create(merged[0]);
+		for (let i = 1; i < merged.length; i++) withNode = k.WithNode.cloneWithExpression(withNode, merged[i]);
+		return {
+			...node,
+			with: withNode
+		};
+	}
+	async transformResult(args) {
+		return args.result;
+	}
+};
+
 //#endregion
 //#region src/helpers/select-renamer.ts
 const fakeQb = k.createSelectQueryBuilder({
@@ -733,8 +783,20 @@ 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, hoistCTEs } = this.#props;
+		if (isSelectQueryBuilder(baseQuery)) {
+			if (hoistCTEs) {
+				if (isNested) throw new InvalidJoinedQuerySetError(baseAlias);
+				const ctes = extractCTEs(baseQuery);
+				if (ctes?.length) {
+					const stripped = baseQuery.withPlugin(new StripWithPlugin());
+					let qb$1 = db.selectFrom(stripped.as(baseAlias));
+					qb$1 = applyHoistedSelections(qb$1, baseQuery, baseAlias);
+					return qb$1.withPlugin(new AddCTEsPlugin(ctes));
+				}
+			}
+			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 +1114,12 @@ var QuerySetImpl = class QuerySetImpl {
 	delete(iqb) {
 		return this.#asWrite(iqb);
 	}
+	write(sqb) {
+		return this.#clone({
+			baseQuery: typeof sqb === "function" ? sqb(this.#props.db) : sqb,
+			hoistCTEs: true
+		});
+	}
 };
 /**
 * Factory for creating query sets. Obtained by calling {@link querySet}.
@@ -1078,7 +1146,8 @@ var QuerySetCreator = class {
 			orderBy: [],
 			orderByKeys: true,
 			frontModifiers: [],
-			endModifiers: []
+			endModifiers: [],
+			hoistCTEs: false
 		});
 	}
 	selectAs(alias, query, keyBy = DEFAULT_KEY_BY) {
@@ -1093,6 +1162,25 @@ var QuerySetCreator = class {
 	deleteAs(alias, query, keyBy = DEFAULT_KEY_BY) {
 		return this.#createQuerySet(alias, query, keyBy);
 	}
+	writeAs(alias, query, keyBy = DEFAULT_KEY_BY) {
+		const baseQuery = typeof query === "function" ? query(this.#db) : query;
+		return new QuerySetImpl({
+			db: this.#db,
+			baseAlias: alias,
+			baseQuery,
+			keyBy,
+			hydrator: createHydrator().orderByKeys(),
+			joinCollections: /* @__PURE__ */ new Map(),
+			attachCollections: /* @__PURE__ */ new Map(),
+			limit: null,
+			offset: null,
+			orderBy: [],
+			orderByKeys: true,
+			frontModifiers: [],
+			endModifiers: [],
+			hoistCTEs: true
+		});
+	}
 };
 /**
 * 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.0",
 	"description": "Explicit ORM-style queries with Kysely",
 	"homepage": "https://github.com/GiacoCorsiglia/kysely-hydrate#readme",
 	"bugs": {