@prisma-next/sql-builder 0.7.0 → 0.8.0

package/dist/{db-DkZcNekS.d.mts → db-BDDDtxLg.d.mts}

@@ -1,5 +1,6 @@
 import { AnyFromSource, SelectAst } from "@prisma-next/sql-relational-core/ast";
 import { CodecExpression, Expression as Expression$1, ScopeField } from "@prisma-next/sql-relational-core/expression";
+import { AnnotationValue, OperationKind, ValidAnnotations } from "@prisma-next/framework-components/runtime";
 import { ExtractCodecTypes, ExtractFieldInputTypes, ExtractFieldOutputTypes, ExtractQueryOperationTypes, QueryOperationTypesBase, StorageTable, StorageTable as StorageTable$1 } from "@prisma-next/sql-contract/types";
 import { SqlQueryPlan } from "@prisma-next/sql-relational-core/plan";
 
@@ -168,15 +169,34 @@ type InsertValues<Table extends StorageTable, CT extends Record<string, {
   readonly input: unknown;
 }>> = { [K in keyof Table['columns']]?: Table['columns'][K]['codecId'] extends keyof CT ? CT[Table['columns'][K]['codecId']]['input'] : unknown };
 interface InsertQuery<QC extends QueryContext, AvailableScope extends Scope, RowType extends Record<string, ScopeField>> {
+  /**
+   * Attach one or more write-typed annotations to this query plan.
+   * Annotations declare `applicableTo: ['write']` (or `['read', 'write']`)
+   * via `defineAnnotation`; read-only annotations fail to compile here.
+   * Annotations are merged into `plan.meta.annotations` at `.build()` time.
+   * Chainable in any position; multiple calls compose with last-write-wins
+   * on duplicate namespaces.
+   */
+  annotate<As extends readonly AnnotationValue<unknown, OperationKind>[]>(...annotations: As & ValidAnnotations<'write', As>): InsertQuery<QC, AvailableScope, RowType>;
   returning: GatedMethod<QC['capabilities'], ReturningCapability, <Columns extends (keyof AvailableScope['topLevel'] & string)[]>(...columns: Columns) => InsertQuery<QC, AvailableScope, WithFields<EmptyRow, AvailableScope['topLevel'], Columns>>>;
   build(): SqlQueryPlan<ResolveRow<RowType, QC['codecTypes'], QC['resolvedColumnOutputTypes']>>;
 }
 interface UpdateQuery<QC extends QueryContext, AvailableScope extends Scope, RowType extends Record<string, ScopeField>> {
+  /**
+   * Attach one or more write-typed annotations to this query plan.
+   * See `InsertQuery.annotate` for semantics.
+   */
+  annotate<As extends readonly AnnotationValue<unknown, OperationKind>[]>(...annotations: As & ValidAnnotations<'write', As>): UpdateQuery<QC, AvailableScope, RowType>;
   where(expr: ExpressionBuilder<AvailableScope, QC>): UpdateQuery<QC, AvailableScope, RowType>;
   returning: GatedMethod<QC['capabilities'], ReturningCapability, <Columns extends (keyof AvailableScope['topLevel'] & string)[]>(...columns: Columns) => UpdateQuery<QC, AvailableScope, WithFields<EmptyRow, AvailableScope['topLevel'], Columns>>>;
   build(): SqlQueryPlan<ResolveRow<RowType, QC['codecTypes'], QC['resolvedColumnOutputTypes']>>;
 }
 interface DeleteQuery<QC extends QueryContext, AvailableScope extends Scope, RowType extends Record<string, ScopeField>> {
+  /**
+   * Attach one or more write-typed annotations to this query plan.
+   * See `InsertQuery.annotate` for semantics.
+   */
+  annotate<As extends readonly AnnotationValue<unknown, OperationKind>[]>(...annotations: As & ValidAnnotations<'write', As>): DeleteQuery<QC, AvailableScope, RowType>;
   where(expr: ExpressionBuilder<AvailableScope, QC>): DeleteQuery<QC, AvailableScope, RowType>;
   returning: GatedMethod<QC['capabilities'], ReturningCapability, <Columns extends (keyof AvailableScope['topLevel'] & string)[]>(...columns: Columns) => DeleteQuery<QC, AvailableScope, WithFields<EmptyRow, AvailableScope['topLevel'], Columns>>>;
   build(): SqlQueryPlan<ResolveRow<RowType, QC['codecTypes'], QC['resolvedColumnOutputTypes']>>;
@@ -187,6 +207,15 @@ interface JoinedTables<QC extends QueryContext, AvailableScope extends Scope> ex
 //#endregion
 //#region src/types/grouped-query.d.ts
 interface GroupedQuery<QC extends QueryContext, AvailableScope extends Scope, RowType extends Record<string, ScopeField>> extends Subquery<RowType>, WithPagination, WithDistinct, WithAlias<RowType>, WithBuild<QC, RowType> {
+  /**
+   * Attach one or more read-typed annotations to this query plan.
+   * Annotations declare `applicableTo: ['read']` (or `['read', 'write']`)
+   * via `defineAnnotation`; write-only annotations fail to compile here.
+   * Annotations are merged into `plan.meta.annotations` at `.build()` time.
+   * Chainable in any position; multiple calls compose with last-write-wins
+   * on duplicate namespaces.
+   */
+  annotate<As extends readonly AnnotationValue<unknown, OperationKind>[]>(...annotations: As & ValidAnnotations<'read', As>): GroupedQuery<QC, AvailableScope, RowType>;
   groupBy(...fields: ((keyof RowType | keyof AvailableScope['topLevel']) & string)[]): GroupedQuery<QC, AvailableScope, RowType>;
   groupBy(expr: (fields: FieldProxy<OrderByScope<AvailableScope, RowType>>, fns: Functions<QC>) => Expression$1<ScopeField>): GroupedQuery<QC, AvailableScope, RowType>;
   having(expr: (fields: FieldProxy<OrderByScope<AvailableScope, RowType>>, fns: AggregateFunctions<QC>) => Expression$1<BooleanCodecType>): GroupedQuery<QC, AvailableScope, RowType>;
@@ -204,6 +233,15 @@ interface GroupedQuery<QC extends QueryContext, AvailableScope extends Scope, Ro
 //#endregion
 //#region src/types/select-query.d.ts
 interface SelectQuery<QC extends QueryContext, AvailableScope extends Scope, RowType extends Record<string, ScopeField>> extends Subquery<RowType>, WithSelect<QC, AvailableScope, RowType>, WithPagination, WithDistinct, WithAlias<RowType>, WithBuild<QC, RowType> {
+  /**
+   * Attach one or more read-typed annotations to this query plan.
+   * Annotations declare `applicableTo: ['read']` (or `['read', 'write']`)
+   * via `defineAnnotation`; write-only annotations fail to compile here.
+   * Annotations are merged into `plan.meta.annotations` at `.build()` time.
+   * Chainable in any position; multiple calls compose with last-write-wins
+   * on duplicate namespaces.
+   */
+  annotate<As extends readonly AnnotationValue<unknown, OperationKind>[]>(...annotations: As & ValidAnnotations<'read', As>): SelectQuery<QC, AvailableScope, RowType>;
   where(expr: ExpressionBuilder<AvailableScope, QC>): SelectQuery<QC, AvailableScope, RowType>;
   orderBy(field: (keyof RowType | keyof AvailableScope['topLevel']) & string, options?: OrderByOptions): SelectQuery<QC, AvailableScope, RowType>;
   orderBy(expr: (fields: FieldProxy<OrderByScope<AvailableScope, RowType>>, fns: Functions<QC>) => Expression$1<ScopeField>, options?: OrderByOptions): SelectQuery<QC, AvailableScope, RowType>;
@@ -316,4 +354,4 @@ type TableProxyContract = {
 type Db<C extends TableProxyContract> = { [Name in string & keyof C['storage']['tables']]: TableProxy<C, Name> };
 //#endregion
 export { ScopeField as _, GroupedQuery as a, UpdateQuery as c, Expression$1 as d, FieldProxy as f, Scope as g, QueryContext as h, SelectQuery as i, ResolveRow as l, GatedMethod as m, TableProxyContract as n, DeleteQuery as o, Functions as p, TableProxy as r, InsertQuery as s, Db as t, AggregateFunctions as u, Subquery as v };
-//# sourceMappingURL=db-DkZcNekS.d.mts.map
+//# sourceMappingURL=db-BDDDtxLg.d.mts.map

package/dist/db-BDDDtxLg.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"db-BDDDtxLg.d.mts","names":[],"sources":["../src/scope.ts","../src/expression.ts","../src/resolve.ts","../src/types/mutation-query.ts","../src/types/joined-tables.ts","../src/types/grouped-query.ts","../src/types/select-query.ts","../src/types/shared.ts","../src/types/table-proxy.ts","../src/types/db.ts"],"mappings":"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"}

package/dist/exports/types.d.mts

@@ -1,2 +1,2 @@
-import { _ as ScopeField, a as GroupedQuery, c as UpdateQuery, d as Expression, g as Scope, h as QueryContext, i as SelectQuery, l as ResolveRow, m as GatedMethod, n as TableProxyContract, o as DeleteQuery, p as Functions, r as TableProxy, s as InsertQuery, t as Db, u as AggregateFunctions, v as Subquery } from "../db-DkZcNekS.mjs";
+import { _ as ScopeField, a as GroupedQuery, c as UpdateQuery, d as Expression, g as Scope, h as QueryContext, i as SelectQuery, l as ResolveRow, m as GatedMethod, n as TableProxyContract, o as DeleteQuery, p as Functions, r as TableProxy, s as InsertQuery, t as Db, u as AggregateFunctions, v as Subquery } from "../db-BDDDtxLg.mjs";
 export { type AggregateFunctions, type Db, type DeleteQuery, type Expression, type Functions, type GatedMethod, type GroupedQuery, type InsertQuery, type QueryContext, type ResolveRow, type Scope, type ScopeField, type SelectQuery, type Subquery, type TableProxy, type TableProxyContract, type UpdateQuery };

package/dist/index.d.mts

@@ -1,2 +1,2 @@
-import { _ as ScopeField, a as GroupedQuery, c as UpdateQuery, d as Expression, g as Scope, h as QueryContext, i as SelectQuery, l as ResolveRow, m as GatedMethod, o as DeleteQuery, p as Functions, r as TableProxy, s as InsertQuery, t as Db, u as AggregateFunctions, v as Subquery } from "./db-DkZcNekS.mjs";
+import { _ as ScopeField, a as GroupedQuery, c as UpdateQuery, d as Expression, g as Scope, h as QueryContext, i as SelectQuery, l as ResolveRow, m as GatedMethod, o as DeleteQuery, p as Functions, r as TableProxy, s as InsertQuery, t as Db, u as AggregateFunctions, v as Subquery } from "./db-BDDDtxLg.mjs";
 export { type AggregateFunctions, type Db, type DeleteQuery, type Expression, type Functions, type GatedMethod, type GroupedQuery, type InsertQuery, type QueryContext, type ResolveRow, type Scope, type ScopeField, type SelectQuery, type Subquery, type TableProxy, type UpdateQuery };

package/dist/runtime/index.d.mts

@@ -1,4 +1,4 @@
-import { _ as ScopeField, f as FieldProxy, g as Scope, h as QueryContext, p as Functions, t as Db, u as AggregateFunctions } from "../db-DkZcNekS.mjs";
+import { _ as ScopeField, f as FieldProxy, g as Scope, h as QueryContext, p as Functions, t as Db, u as AggregateFunctions } from "../db-BDDDtxLg.mjs";
 import { AnyExpression } from "@prisma-next/sql-relational-core/ast";
 import { Expression } from "@prisma-next/sql-relational-core/expression";
 import { SqlStorage } from "@prisma-next/sql-contract/types";

package/dist/runtime/index.mjs

@@ -1,6 +1,7 @@
 import { AggregateExpr, AndExpr, BinaryExpr, ColumnRef, DeleteAst, DerivedTableSource, ExistsExpr, IdentifierRef, InsertAst, JoinAst, ListExpression, LiteralExpr, NullCheckExpr, OrExpr, OrderByItem, ParamRef, ProjectionItem, SelectAst, SubqueryExpr, TableSource, UpdateAst, collectOrderedParamRefs } from "@prisma-next/sql-relational-core/ast";
 import { codecOf, toExpr } from "@prisma-next/sql-relational-core/expression";
 import { codecRefForStorageColumn } from "@prisma-next/sql-relational-core/codec-descriptor-registry";
+import { assertAnnotationsApplicable } from "@prisma-next/framework-components/runtime";
 //#region src/runtime/expression-impl.ts
 /**
 * Runtime wrapper around a relational-core AST expression node. Carries ScopeField metadata (codecId, nullable) so aggregate-like combinators can propagate the input codec onto their result.
@@ -156,6 +157,33 @@ function createAggregateFunctions(operations) {
 	} });
 }
 //#endregion
+//#region ../../../1-framework/0-foundation/utils/dist/defined-BYcWqtXq.mjs
+/**
+* Returns an object with the key/value if value is defined, otherwise an empty object.
+*
+* Use with spread to conditionally include optional properties while satisfying
+* exactOptionalPropertyTypes. This is explicit about which properties are optional
+* and won't inadvertently strip other undefined values.
+*
+* @example
+* ```typescript
+* // Instead of:
+* const obj = {
+*   required: 'value',
+*   ...(optional ? { optional } : {}),
+* };
+*
+* // Use:
+* const obj = {
+*   required: 'value',
+*   ...ifDefined('optional', optional),
+* };
+* ```
+*/
+function ifDefined(key, value) {
+	return value !== void 0 ? { [key]: value } : {};
+}
+//#endregion
 //#region src/runtime/builder-base.ts
 var BuilderBase = class {
 	ctx;
@@ -190,7 +218,8 @@ function emptyState(from, scope) {
 		distinct: void 0,
 		distinctOn: void 0,
 		scope,
-		rowFields: {}
+		rowFields: {},
+		annotations: /* @__PURE__ */ new Map()
 	};
 }
 function cloneState(state, overrides) {
@@ -221,12 +250,14 @@ function buildSelectAst(state) {
 		selectAllIntent: void 0
 	});
 }
-function buildQueryPlan(ast, ctx) {
+function buildQueryPlan(ast, ctx, annotations) {
 	const paramValues = collectOrderedParamRefs(ast).map((r) => r.value);
+	const annotationsRecord = annotations !== void 0 && annotations.size > 0 ? Object.freeze(Object.fromEntries(annotations)) : void 0;
 	const meta = Object.freeze({
 		target: ctx.target,
 		storageHash: ctx.storageHash,
-		lane: "dsl"
+		lane: "dsl",
+		...ifDefined("annotations", annotationsRecord)
 	});
 	return Object.freeze({
 		ast,
@@ -235,7 +266,7 @@ function buildQueryPlan(ast, ctx) {
 	});
 }
 function buildPlan(state, ctx) {
-	return buildQueryPlan(buildSelectAst(state), ctx);
+	return buildQueryPlan(buildSelectAst(state), ctx, state.annotations);
 }
 function tableToScope(alias, table, options) {
 	const storage = options?.storage;
@@ -406,6 +437,29 @@ var QueryBase = class extends BuilderBase {
 	distinct() {
 		return this.clone(cloneState(this.state, { distinct: true }));
 	}
+	/**
+	* Attach one or more annotations to this query plan.
+	*
+	* Read builders (`SelectQueryImpl`, `GroupedQueryImpl`) accept
+	* annotations whose declared `applicableTo` includes `'read'`.
+	* The type-level `As & ValidAnnotations<'read', As>` gate rejects
+	* write-only annotations at the call site; the runtime check below
+	* fails closed for callers that bypass the type gate (cast / `any`).
+	*
+	* Multiple `.annotate(...)` calls compose; duplicate namespaces use
+	* last-write-wins. The accumulated annotations are merged into
+	* `plan.meta.annotations` at `.build()` time, alongside any framework-
+	* internal metadata under reserved namespaces (e.g. `codecs`).
+	*
+	* Chainable in any position (before / after `.where`, `.select`,
+	* `.limit`, etc.); the returned builder has the same row type.
+	*/
+	annotate(...annotations) {
+		assertAnnotationsApplicable(annotations, "read", "sql-dsl.annotate");
+		const next = new Map(this.state.annotations);
+		for (const annotation of annotations) next.set(annotation.namespace, annotation);
+		return this.clone(cloneState(this.state, { annotations: next }));
+	}
 	groupBy(...args) {
 		const exprs = resolveGroupBy(args, this.state.scope, this.state.rowFields, this.ctx);
 		return new GroupedQueryImpl(cloneState(this.state, { groupBy: [...this.state.groupBy, ...exprs] }), this.ctx);
@@ -549,6 +603,23 @@ var JoinedTablesImpl = class JoinedTablesImpl extends BuilderBase {
 };
 //#endregion
 //#region src/runtime/mutation-impl.ts
+/**
+* Validates and merges a variadic annotations call into a builder's
+* accumulated user-annotations map. Used by `.annotate(...)` on each of
+* the three mutation builders (`InsertQueryImpl`, `UpdateQueryImpl`,
+* `DeleteQueryImpl`); the read builders share the same logic via
+* `QueryBase.annotate()` in `./query-impl.ts`.
+*
+* Runs `assertAnnotationsApplicable` at call time (not at `.build()`) so
+* inapplicable annotations forced through casts surface immediately
+* rather than at plan-construction time.
+*/
+function mergeWriteAnnotations(current, annotations) {
+	assertAnnotationsApplicable(annotations, "write", "sql-dsl.annotate");
+	const next = new Map(current);
+	for (const annotation of annotations) next.set(annotation.namespace, annotation);
+	return next;
+}
 function buildParamValues(values, table, tableName, op, ctx) {
 	const params = {};
 	for (const [col, value] of Object.entries(values)) {
@@ -578,7 +649,8 @@ var InsertQueryImpl = class InsertQueryImpl extends BuilderBase {
 	#values;
 	#returningColumns;
 	#rowFields;
-	constructor(tableName, table, scope, values, ctx, returningColumns = [], rowFields = {}) {
+	#annotations;
+	constructor(tableName, table, scope, values, ctx, returningColumns = [], rowFields = {}, annotations = /* @__PURE__ */ new Map()) {
 		super(ctx);
 		this.#tableName = tableName;
 		this.#table = table;
@@ -586,6 +658,7 @@ var InsertQueryImpl = class InsertQueryImpl extends BuilderBase {
 		this.#values = values;
 		this.#returningColumns = returningColumns;
 		this.#rowFields = rowFields;
+		this.#annotations = annotations;
 	}
 	returning = this._gate({ sql: { returning: true } }, "returning", (...columns) => {
 		const newRowFields = {};
@@ -594,13 +667,23 @@ var InsertQueryImpl = class InsertQueryImpl extends BuilderBase {
 			if (!field) throw new Error(`Column "${col}" not found in scope`);
 			newRowFields[col] = field;
 		}
-		return new InsertQueryImpl(this.#tableName, this.#table, this.#scope, this.#values, this.ctx, columns, newRowFields);
+		return new InsertQueryImpl(this.#tableName, this.#table, this.#scope, this.#values, this.ctx, columns, newRowFields, this.#annotations);
 	});
+	/**
+	* Attach one or more write-typed annotations to this query plan.
+	* The type-level `As & ValidAnnotations<'write', As>` gate rejects
+	* read-only annotations at the call site; the runtime check fails
+	* closed for callers that bypass the type gate. See `QueryBase.annotate`
+	* in `./query-impl.ts` for the read-builder counterpart.
+	*/
+	annotate(...annotations) {
+		return new InsertQueryImpl(this.#tableName, this.#table, this.#scope, this.#values, this.ctx, this.#returningColumns, this.#rowFields, mergeWriteAnnotations(this.#annotations, annotations));
+	}
 	build() {
 		const paramValues = buildParamValues(this.#values, this.#table, this.#tableName, "create", this.ctx);
 		let ast = InsertAst.into(TableSource.named(this.#tableName)).withValues(paramValues);
 		if (this.#returningColumns.length > 0) ast = ast.withReturning(buildReturningProjections(this.#tableName, this.#returningColumns, this.#rowFields));
-		return buildQueryPlan(ast, this.ctx);
+		return buildQueryPlan(ast, this.ctx, this.#annotations);
 	}
 };
 var UpdateQueryImpl = class UpdateQueryImpl extends BuilderBase {
@@ -611,7 +694,8 @@ var UpdateQueryImpl = class UpdateQueryImpl extends BuilderBase {
 	#whereCallbacks;
 	#returningColumns;
 	#rowFields;
-	constructor(tableName, table, scope, setValues, ctx, whereCallbacks = [], returningColumns = [], rowFields = {}) {
+	#annotations;
+	constructor(tableName, table, scope, setValues, ctx, whereCallbacks = [], returningColumns = [], rowFields = {}, annotations = /* @__PURE__ */ new Map()) {
 		super(ctx);
 		this.#tableName = tableName;
 		this.#table = table;
@@ -620,9 +704,10 @@ var UpdateQueryImpl = class UpdateQueryImpl extends BuilderBase {
 		this.#whereCallbacks = whereCallbacks;
 		this.#returningColumns = returningColumns;
 		this.#rowFields = rowFields;
+		this.#annotations = annotations;
 	}
 	where(expr) {
-		return new UpdateQueryImpl(this.#tableName, this.#table, this.#scope, this.#setValues, this.ctx, [...this.#whereCallbacks, expr], this.#returningColumns, this.#rowFields);
+		return new UpdateQueryImpl(this.#tableName, this.#table, this.#scope, this.#setValues, this.ctx, [...this.#whereCallbacks, expr], this.#returningColumns, this.#rowFields, this.#annotations);
 	}
 	returning = this._gate({ sql: { returning: true } }, "returning", (...columns) => {
 		const newRowFields = {};
@@ -631,14 +716,22 @@ var UpdateQueryImpl = class UpdateQueryImpl extends BuilderBase {
 			if (!field) throw new Error(`Column "${col}" not found in scope`);
 			newRowFields[col] = field;
 		}
-		return new UpdateQueryImpl(this.#tableName, this.#table, this.#scope, this.#setValues, this.ctx, this.#whereCallbacks, columns, newRowFields);
+		return new UpdateQueryImpl(this.#tableName, this.#table, this.#scope, this.#setValues, this.ctx, this.#whereCallbacks, columns, newRowFields, this.#annotations);
 	});
+	/**
+	* Attach one or more write-typed annotations to this query plan.
+	* See `InsertQueryImpl.annotate` for semantics; the runtime check
+	* fails closed for callers that bypass the type-level gate.
+	*/
+	annotate(...annotations) {
+		return new UpdateQueryImpl(this.#tableName, this.#table, this.#scope, this.#setValues, this.ctx, this.#whereCallbacks, this.#returningColumns, this.#rowFields, mergeWriteAnnotations(this.#annotations, annotations));
+	}
 	build() {
 		const setParams = buildParamValues(this.#setValues, this.#table, this.#tableName, "update", this.ctx);
 		const whereExpr = combineWhereExprs(this.#whereCallbacks.map((cb) => evaluateWhere(cb, this.#scope, this.ctx.queryOperationTypes)));
 		let ast = UpdateAst.table(TableSource.named(this.#tableName)).withSet(setParams).withWhere(whereExpr);
 		if (this.#returningColumns.length > 0) ast = ast.withReturning(buildReturningProjections(this.#tableName, this.#returningColumns, this.#rowFields));
-		return buildQueryPlan(ast, this.ctx);
+		return buildQueryPlan(ast, this.ctx, this.#annotations);
 	}
 };
 var DeleteQueryImpl = class DeleteQueryImpl extends BuilderBase {
@@ -647,16 +740,18 @@ var DeleteQueryImpl = class DeleteQueryImpl extends BuilderBase {
 	#whereCallbacks;
 	#returningColumns;
 	#rowFields;
-	constructor(tableName, scope, ctx, whereCallbacks = [], returningColumns = [], rowFields = {}) {
+	#annotations;
+	constructor(tableName, scope, ctx, whereCallbacks = [], returningColumns = [], rowFields = {}, annotations = /* @__PURE__ */ new Map()) {
 		super(ctx);
 		this.#tableName = tableName;
 		this.#scope = scope;
 		this.#whereCallbacks = whereCallbacks;
 		this.#returningColumns = returningColumns;
 		this.#rowFields = rowFields;
+		this.#annotations = annotations;
 	}
 	where(expr) {
-		return new DeleteQueryImpl(this.#tableName, this.#scope, this.ctx, [...this.#whereCallbacks, expr], this.#returningColumns, this.#rowFields);
+		return new DeleteQueryImpl(this.#tableName, this.#scope, this.ctx, [...this.#whereCallbacks, expr], this.#returningColumns, this.#rowFields, this.#annotations);
 	}
 	returning = this._gate({ sql: { returning: true } }, "returning", (...columns) => {
 		const newRowFields = {};
@@ -665,13 +760,20 @@ var DeleteQueryImpl = class DeleteQueryImpl extends BuilderBase {
 			if (!field) throw new Error(`Column "${col}" not found in scope`);
 			newRowFields[col] = field;
 		}
-		return new DeleteQueryImpl(this.#tableName, this.#scope, this.ctx, this.#whereCallbacks, columns, newRowFields);
+		return new DeleteQueryImpl(this.#tableName, this.#scope, this.ctx, this.#whereCallbacks, columns, newRowFields, this.#annotations);
 	});
+	/**
+	* Attach one or more write-typed annotations to this query plan.
+	* See `InsertQueryImpl.annotate` for semantics.
+	*/
+	annotate(...annotations) {
+		return new DeleteQueryImpl(this.#tableName, this.#scope, this.ctx, this.#whereCallbacks, this.#returningColumns, this.#rowFields, mergeWriteAnnotations(this.#annotations, annotations));
+	}
 	build() {
 		const whereExpr = combineWhereExprs(this.#whereCallbacks.map((cb) => evaluateWhere(cb, this.#scope, this.ctx.queryOperationTypes)));
 		let ast = DeleteAst.from(TableSource.named(this.#tableName)).withWhere(whereExpr);
 		if (this.#returningColumns.length > 0) ast = ast.withReturning(buildReturningProjections(this.#tableName, this.#returningColumns, this.#rowFields));
-		return buildQueryPlan(ast, this.ctx);
+		return buildQueryPlan(ast, this.ctx, this.#annotations);
 	}
 };
 //#endregion