joist-core 2.3.0-next.99 → 2.4.0

package/build/queries/sql/execute.d.cts

@@ -1,8 +1,9 @@
 import { ColumnsOf, TypeMapEntry } from "../../typeMap.cjs";
 import { SqlCondition } from "../conditions.cjs";
-import { CheckReadQuery, CheckScope, CheckSetQuery, EntityHydrator, NameOf, Plan, Query, QueryJoins, QueryRow, ReadQueryRow, SetOperand, SetOperation, SetQuery, Subquery, WithInput, entityQueryBrand, subqueryBrand } from "./query.cjs";
-import { ExprBrand, ExprLike, exprBrand } from "./Expr.cjs";
+import { CustomColumnInputs, CustomColumnValue, CustomColumnsOf, CustomTableFor } from "./custom.cjs";
 import { TableFor, tableMgmt } from "./Tables.cjs";
+import { CheckReadQuery, CheckScope, CheckSetQuery, EntityHydrator, NameOf, Plan, Query, QueryJoinInput, QueryRow, ReadQueryRow, SetOperand, SetOperation, SetQuery, Subquery, WithInput, entityQueryBrand, subqueryBrand } from "./query.cjs";
+import { ExprBrand, ExprLike, exprBrand } from "./Expr.cjs";
 import { DriverQueryResult } from "../../drivers/Driver.cjs";
 import { IdOf } from "../../EntityManager.cjs";
 import { Entity } from "../../Entity.cjs";
@@ -35,7 +36,7 @@ type InsertStatement<T extends Entity, R extends MutationReturning | undefined =
   /** CTEs to add to a `WITH` before the INSERT; see `Clauses.with`. */
   readonly with?: WithInput;
 } & NoMutationReadClauses & ({
-  readonly values: InsertValues<T> | readonly InsertValues<T>[];
+  readonly values: readonly InsertValues<T>[];
   readonly from?: never;
 } | {
   readonly from: Q & CheckInsertSource<T, Q>;
@@ -70,7 +71,7 @@ type MutationStatement<T extends Entity, R extends MutationReturning | undefined
 /** Inference starts with the literal POJO; CheckMutation checks its target and every supplied key. */
 type MutationInput = ({
   readonly insert: TableFor<Entity>;
-  readonly values: object | readonly object[];
+  readonly values: readonly object[];
   readonly from?: never;
 } | {
   readonly insert: TableFor<Entity>;
@@ -81,6 +82,19 @@ type MutationInput = ({
   readonly set: object;
 } | {
   readonly delete: TableFor<Entity>;
+} | {
+  readonly insert: CustomTableFor;
+  readonly values: readonly object[];
+  readonly from?: never;
+} | {
+  readonly insert: CustomTableFor;
+  readonly from: SetOperand;
+  readonly values?: never;
+} | {
+  readonly update: CustomTableFor;
+  readonly set: object;
+} | {
+  readonly delete: CustomTableFor;
 }) & {
   readonly returning?: MutationReturning;
   readonly with?: WithInput;
@@ -90,12 +104,12 @@ type MutationRow<M> = M extends {
   readonly returning?: infer R;
 } ? R extends MutationReturning ? R extends ExprLike<unknown> ? QueryRow<R> : { -readonly [K in keyof QueryRow<R>]: QueryRow<R>[K]; } : never : never;
 /** Checks nonliteral statements as well as fresh literals without widening their inferred result. */
-type CheckMutation<M> = M extends unknown ? TargetEntity<M> extends (infer T extends Entity) ? TypeMapEntry<T, "supportsEmExecute"> extends true ? { readonly [K in keyof M]: K extends MutationClause<M> ? unknown : never; } & {
+type CheckMutation<M> = M extends unknown ? [CustomColumnsOf<TargetTable<M>>] extends [never] ? TargetEntity<M> extends (infer T extends Entity) ? TypeMapEntry<T, "supportsEmExecute"> extends true ? { readonly [K in keyof M]: K extends MutationClause<M> ? unknown : never; } & {
   readonly returning?: M extends {
     readonly returning?: infer R;
   } ? CheckReturning<R, NameOf<TargetTable<M>>> : never;
 } & ((M extends {
-  readonly values: infer V;
+  readonly values: infer V extends readonly unknown[];
 } ? {
   readonly values: CheckValues<T, V>;
 } : never) | (M extends {
@@ -108,7 +122,7 @@ type CheckMutation<M> = M extends unknown ? TargetEntity<M> extends (infer T ext
   readonly set: CheckAssignments<V, UpdateValues<T>, NameOf<TargetTable<M>>>;
 } : never) | (M extends {
   readonly delete: unknown;
-} ? unknown : never)) : "SQL mutations require a supported non-inherited target and regenerated metadata" : never : never;
+} ? unknown : never)) : "SQL mutations require a supported non-inherited target and regenerated metadata" : never : CheckCustomMutation<M> : never;
 /** Classifies mutation roots before EntityManager applies write permissions, including malformed roots. */
 declare function isMutation(arg: unknown): boolean;
 /**
@@ -119,12 +133,21 @@ declare function isMutation(arg: unknown): boolean;
 declare function parseStatement(arg: unknown): Plan | undefined;
 /** Retains native counts even when no rows return, and propagates decoding failures after execution. */
 declare function decodeStatementResult(em: EntityHydrator, plan: Plan, result: DriverQueryResult): ExecuteResult<unknown>;
+/** An entity table whose generated metadata permits direct SQL mutations. */
 type MutationTarget<T extends Entity> = TableFor<T> & (TypeMapEntry<T, "supportsEmExecute"> extends true ? unknown : never);
+/** Shared filtering and full-table consent clauses for UPDATE and DELETE. */
 type MutationFilter = {
-  readonly where?: SqlCondition | ExprLike<boolean>;
+  /**
+   * An `{ and: [...] }` or `{ or: [...] }` group, a boolean expression, or a bare condition such as `a.age.gte(18)`.
+   *
+   * Arrays are shorthand for `{ and: [...] }`; undefined conditions are pruned.
+   */
+  readonly where?: SqlCondition | ExprLike<boolean> | readonly (SqlCondition | undefined)[];
+  /** Allows a supplied where to be undefined or fully pruned; unnecessary when where is omitted. */
   readonly allowAll?: boolean;
   readonly softDeletes?: "include" | "exclude";
 };
+/** Read-only query clauses that mutations explicitly reject. */
 type NoMutationReadClauses = Partial<Record<"select" | "join" | "groupBy" | "having" | "orderBy" | "limit" | "offset" | "distinct" | "pruneJoins" | "as" | "union" | "unionAll" | "intersect" | "intersectAll" | "except" | "exceptAll" | "ctes" | "using" | "onConflict", never>>;
 /** Column keys allowed in INSERT, i.e. Book's optional `id` and required `authorId`. */
 type InsertKey<T> = { [K in keyof ColumnsOf<T>]: ColumnsOf<T>[K] extends {
@@ -144,31 +167,105 @@ type DomainValue<T, K extends keyof ColumnsOf<T>> = K extends "id" ? IdOf<T> : C
 } ? IdOf<U> : ColumnsOf<T>[K] extends {
   type: infer V;
 } ? V : never;
+/** A modeled column's domain value with SQL nullability applied. */
 type SqlValue<T, K extends keyof ColumnsOf<T>> = DomainValue<T, K> | (ColumnsOf<T>[K] extends {
   nullable: true;
 } ? null : never);
+/** A modeled-column value, entity reference, or SQL expression that produces one. */
 type Assignment<T, K extends keyof ColumnsOf<T>> = SqlValue<T, K> | ExprLike<SqlValue<T, K>> | (K extends "id" ? never : ColumnsOf<T>[K] extends {
   entity: infer U;
 } ? U : never);
+/** A custom column's declared value with SQL nullability applied. */
+type CustomSqlValue<I> = CustomColumnValue<I> | (I extends {
+  nullable: true;
+} ? null : never);
+/** A custom-column value or SQL expression that produces one. */
+type CustomAssignment<I> = CustomSqlValue<I> | ExprLike<CustomSqlValue<I>>;
+/** Custom-column keys accepted by INSERT, excluding generated columns. */
+type CustomInsertKey<C extends CustomColumnInputs> = { [K in keyof C]: C[K] extends {
+  generated: true;
+} ? never : K; }[keyof C];
+/** Custom-column keys each INSERT row must supply because they have no default and are not nullable. */
+type CustomRequiredInsertKey<C extends CustomColumnInputs> = { [K in CustomInsertKey<C>]: C[K] extends {
+  nullable: true;
+} | {
+  hasDefault: true;
+} ? never : K; }[CustomInsertKey<C>];
+/** Custom-column keys accepted by UPDATE, excluding generated columns and the physical primary key. */
+type CustomUpdateKey<C extends CustomColumnInputs> = { [K in keyof C]: C[K] extends {
+  generated: true;
+} ? never : K extends "id" ? never : C[K] extends {
+  columnName: "id";
+} ? never : K; }[keyof C];
+/** Values accepted by INSERT for a custom table's declared columns. */
+type CustomInsertValues<C extends CustomColumnInputs> = { [K in CustomRequiredInsertKey<C>]: CustomAssignment<C[K]>; } & { [K in Exclude<CustomInsertKey<C>, CustomRequiredInsertKey<C>>]?: CustomAssignment<C[K]> | undefined; };
+/** Assignments accepted by UPDATE for a custom table's writable columns. */
+type CustomUpdateValues<C extends CustomColumnInputs> = { [K in CustomUpdateKey<C>]?: CustomAssignment<C[K]> | undefined; };
+/** Named row shape that an INSERT SELECT source must produce for a custom table. */
+type CustomInsertSourceRow<C extends CustomColumnInputs> = { [K in CustomRequiredInsertKey<C>]: CustomSqlValue<C[K]>; } & { [K in Exclude<CustomInsertKey<C>, CustomRequiredInsertKey<C>>]?: CustomSqlValue<C[K]>; };
+/** Named row shape that an entity INSERT SELECT source must produce. */
 type InsertSourceRow<T> = { [K in RequiredInsertKey<T>]: SqlValue<T, K>; } & { [K in Exclude<InsertKey<T>, RequiredInsertKey<T>>]?: SqlValue<T, K>; };
+/** Named expression projection accepted from an entity INSERT SELECT source. */
 type InsertProjection<T> = { [K in RequiredInsertKey<T>]: ExprLike<SqlValue<T, K>>; } & { [K in Exclude<InsertKey<T>, RequiredInsertKey<T>>]?: ExprLike<SqlValue<T, K>>; };
+/** Collects the keys from every member of a union instead of only their shared keys. */
 type UnionKeys<V> = V extends unknown ? keyof V : never;
 /** Collects every alternative before scope checking; a valid branch cannot hide an unrelated alias. */
 type UnionValue<V, K extends PropertyKey> = V extends unknown ? (K extends keyof V ? V[K] : never) : never;
+/** Extracts the source names carried by a SQL expression. */
 type ExprSource<V> = V extends {
   readonly [exprBrand]: ExprBrand<unknown, infer Src>;
 } ? Src : never;
+/** Rejects expressions that reference tables outside the statement's allowed scope. */
 type CheckExprScope<V, Scope> = string extends ExprSource<V> ? unknown : [Exclude<ExprSource<V>, Scope>] extends [never] ? unknown : "Expression source is not in the statement scope";
+/** Extracts each expression from a scalar or named RETURNING projection. */
 type ReturningExpr<R> = R extends ExprLike<unknown> ? R : R extends undefined ? never : R[keyof R];
+/** Detects an empty named RETURNING projection. */
 type EmptyReturning<R> = R extends object ? (keyof R extends never ? true : false) : false;
+/** Rejects empty RETURNING objects and expressions outside the target scope. */
 type CheckReturning<R, Scope> = true extends EmptyReturning<R> ? never : CheckExprScope<ReturningExpr<R>, Scope>;
+/** Validates assignment keys, values, and expression sources without distributing union inputs. */
 type CheckAssignments<V, Allowed, Scope> = [Exclude<UnionKeys<V>, keyof Allowed>] extends [never] ? Allowed & { [K in UnionKeys<V>]?: CheckExprScope<UnionValue<V, K>, Scope>; } : "SQL assignments have unknown target fields";
-type CheckValues<T extends Entity, V> = ([Extract<V, readonly unknown[]>] extends [never] ? never : readonly CheckAssignments<Extract<V, readonly unknown[]>[number], InsertValues<T>, never>[]) | ([Exclude<V, readonly unknown[]>] extends [never] ? never : CheckAssignments<Exclude<V, readonly unknown[]>, InsertValues<T>, never>);
+/** Checks every entity INSERT row in a readonly collection against writable columns. */
+type CheckValues<T extends Entity, V extends readonly unknown[]> = readonly CheckAssignments<V[number], InsertValues<T>, never>[];
+/**
+ * Checks a custom-table mutation against its declared primitive columns.
+ *
+ * Only clauses for the selected operation are allowed, and `softDeletes` is rejected because there is no entity
+ * policy. Assignments use declaration keys and honor nullability, defaults, and generated columns. INSERT VALUES
+ * cannot read the target row, while UPDATE SET and RETURNING can. INSERT SELECT must be a valid named read with all
+ * required columns and compatible declared value types; runtime checks also compare its SQL codecs and nullability.
+ */
+type CheckCustomMutation<M> = { readonly [K in keyof M]: K extends MutationClause<M> ? (K extends "softDeletes" ? never : unknown) : never; } & {
+  readonly returning?: M extends {
+    readonly returning?: infer R;
+  } ? CheckReturning<R, NameOf<TargetTable<M>>> : never;
+} & ((M extends {
+  readonly values: infer V extends readonly unknown[];
+} ? {
+  readonly values: CheckCustomValues<CustomColumnsOf<TargetTable<M>>, V>;
+} : never) | (M extends {
+  readonly from: infer Q extends SetOperand;
+} ? {
+  readonly from: CheckCustomInsertSource<CustomColumnsOf<TargetTable<M>>, Q>;
+} : never) | (M extends {
+  readonly set: infer V;
+} ? {
+  readonly set: CheckAssignments<V, CustomUpdateValues<CustomColumnsOf<TargetTable<M>>>, NameOf<TargetTable<M>>>;
+} : never) | (M extends {
+  readonly delete: unknown;
+} ? unknown : never));
+/** Checks every custom INSERT row in a readonly collection against declared writable columns. */
+type CheckCustomValues<C extends CustomColumnInputs, V extends readonly unknown[]> = readonly CheckAssignments<V[number], CustomInsertValues<C>, never>[];
+/** Checks a custom INSERT SELECT's named outputs, required columns, values, and read source. */
+type CheckCustomInsertSource<C extends CustomColumnInputs, Q> = SetOperand extends Q ? "INSERT source type lost its select keys; use `satisfies Query` or `satisfies SetQuery` instead of a type annotation" : ReadQueryRow<Q> extends CustomInsertSourceRow<C> ? Exclude<UnionKeys<ReadQueryRow<Q>>, CustomInsertKey<C>> extends never ? CheckReadQuery<Q> & CheckSourceScope<Q> & (Q extends SetQuery<readonly SetOperand[]> ? CheckSetQuery<Q> : unknown) : "INSERT SELECT has unknown target fields" : "INSERT SELECT requires compatible values for all SQL-required fields";
+/** Checks every SELECT expression against the tables visible within its read-query branch. */
 type CheckSourceScope<Q> = Q extends {
   readonly select: infer S;
   readonly from: infer F;
-} ? CheckScope<S, F, "join" extends keyof Q ? Extract<Q[keyof Q & "join"], QueryJoins> : []> : { [K in keyof Q]: K extends SetOperation ? Q[K] extends readonly unknown[] ? { [I in keyof Q[K]]: CheckSourceScope<Q[K][I]>; } : unknown : unknown; };
-type CheckInsertSource<T, Q extends SetOperand> = SetOperand extends Q ? "INSERT source was typed too generically; retain its named output fields" : ReadQueryRow<Q> extends InsertSourceRow<T> ? Exclude<UnionKeys<ReadQueryRow<Q>>, InsertKey<T>> extends never ? CheckReadQuery<Q> & CheckSourceScope<Q> & (Q extends SetQuery<readonly SetOperand[]> ? CheckSetQuery<Q> : unknown) : "INSERT SELECT has unknown target fields" : "INSERT SELECT requires compatible values for all SQL-required fields";
+} ? CheckScope<S, F, "join" extends keyof Q ? Extract<Q[keyof Q & "join"], QueryJoinInput> : []> : { [K in keyof Q]: K extends SetOperation ? Q[K] extends readonly unknown[] ? { [I in keyof Q[K]]: CheckSourceScope<Q[K][I]>; } : unknown : unknown; };
+/** Checks an entity INSERT SELECT's named outputs, required columns, values, and read source. */
+type CheckInsertSource<T, Q extends SetOperand> = SetOperand extends Q ? "INSERT source type lost its select keys; use `satisfies Query` or `satisfies SetQuery` instead of a type annotation" : ReadQueryRow<Q> extends InsertSourceRow<T> ? Exclude<UnionKeys<ReadQueryRow<Q>>, InsertKey<T>> extends never ? CheckReadQuery<Q> & CheckSourceScope<Q> & (Q extends SetQuery<readonly SetOperand[]> ? CheckSetQuery<Q> : unknown) : "INSERT SELECT has unknown target fields" : "INSERT SELECT requires compatible values for all SQL-required fields";
+/** Extracts the entity type from any mutation target clause. */
 type TargetEntity<M> = M extends {
   readonly insert: TableFor<infer T>;
 } | {
@@ -176,6 +273,7 @@ type TargetEntity<M> = M extends {
 } | {
   readonly delete: TableFor<infer T>;
 } ? T : never;
+/** Extracts the table handle from any mutation target clause. */
 type TargetTable<M> = M extends {
   readonly insert: infer A;
 } | {
@@ -183,6 +281,7 @@ type TargetTable<M> = M extends {
 } | {
   readonly delete: infer A;
 } ? A : never;
+/** Clauses permitted by the selected INSERT, UPDATE, or DELETE operation. */
 type MutationClause<M> = "returning" | "with" | (M extends {
   readonly insert: unknown;
 } ? "insert" | (M extends {

package/build/queries/sql/execute.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"execute.d.cts","names":[],"sources":["../../../src/queries/sql/execute.ts"],"mappings":"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"}
+{"version":3,"file":"execute.d.cts","names":[],"sources":["../../../src/queries/sql/execute.ts"],"mappings":"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"}

package/build/queries/sql/execute.d.mts

@@ -1,8 +1,9 @@
 import { ColumnsOf, TypeMapEntry } from "../../typeMap.mjs";
 import { SqlCondition } from "../conditions.mjs";
-import { CheckReadQuery, CheckScope, CheckSetQuery, EntityHydrator, NameOf, Plan, Query, QueryJoins, QueryRow, ReadQueryRow, SetOperand, SetOperation, SetQuery, Subquery, WithInput, entityQueryBrand, subqueryBrand } from "./query.mjs";
-import { ExprBrand, ExprLike, exprBrand } from "./Expr.mjs";
+import { CustomColumnInputs, CustomColumnValue, CustomColumnsOf, CustomTableFor } from "./custom.mjs";
 import { TableFor, tableMgmt } from "./Tables.mjs";
+import { CheckReadQuery, CheckScope, CheckSetQuery, EntityHydrator, NameOf, Plan, Query, QueryJoinInput, QueryRow, ReadQueryRow, SetOperand, SetOperation, SetQuery, Subquery, WithInput, entityQueryBrand, subqueryBrand } from "./query.mjs";
+import { ExprBrand, ExprLike, exprBrand } from "./Expr.mjs";
 import { DriverQueryResult } from "../../drivers/Driver.mjs";
 import { IdOf } from "../../EntityManager.mjs";
 import { Entity } from "../../Entity.mjs";
@@ -35,7 +36,7 @@ type InsertStatement<T extends Entity, R extends MutationReturning | undefined =
   /** CTEs to add to a `WITH` before the INSERT; see `Clauses.with`. */
   readonly with?: WithInput;
 } & NoMutationReadClauses & ({
-  readonly values: InsertValues<T> | readonly InsertValues<T>[];
+  readonly values: readonly InsertValues<T>[];
   readonly from?: never;
 } | {
   readonly from: Q & CheckInsertSource<T, Q>;
@@ -70,7 +71,7 @@ type MutationStatement<T extends Entity, R extends MutationReturning | undefined
 /** Inference starts with the literal POJO; CheckMutation checks its target and every supplied key. */
 type MutationInput = ({
   readonly insert: TableFor<Entity>;
-  readonly values: object | readonly object[];
+  readonly values: readonly object[];
   readonly from?: never;
 } | {
   readonly insert: TableFor<Entity>;
@@ -81,6 +82,19 @@ type MutationInput = ({
   readonly set: object;
 } | {
   readonly delete: TableFor<Entity>;
+} | {
+  readonly insert: CustomTableFor;
+  readonly values: readonly object[];
+  readonly from?: never;
+} | {
+  readonly insert: CustomTableFor;
+  readonly from: SetOperand;
+  readonly values?: never;
+} | {
+  readonly update: CustomTableFor;
+  readonly set: object;
+} | {
+  readonly delete: CustomTableFor;
 }) & {
   readonly returning?: MutationReturning;
   readonly with?: WithInput;
@@ -90,12 +104,12 @@ type MutationRow<M> = M extends {
   readonly returning?: infer R;
 } ? R extends MutationReturning ? R extends ExprLike<unknown> ? QueryRow<R> : { -readonly [K in keyof QueryRow<R>]: QueryRow<R>[K]; } : never : never;
 /** Checks nonliteral statements as well as fresh literals without widening their inferred result. */
-type CheckMutation<M> = M extends unknown ? TargetEntity<M> extends (infer T extends Entity) ? TypeMapEntry<T, "supportsEmExecute"> extends true ? { readonly [K in keyof M]: K extends MutationClause<M> ? unknown : never; } & {
+type CheckMutation<M> = M extends unknown ? [CustomColumnsOf<TargetTable<M>>] extends [never] ? TargetEntity<M> extends (infer T extends Entity) ? TypeMapEntry<T, "supportsEmExecute"> extends true ? { readonly [K in keyof M]: K extends MutationClause<M> ? unknown : never; } & {
   readonly returning?: M extends {
     readonly returning?: infer R;
   } ? CheckReturning<R, NameOf<TargetTable<M>>> : never;
 } & ((M extends {
-  readonly values: infer V;
+  readonly values: infer V extends readonly unknown[];
 } ? {
   readonly values: CheckValues<T, V>;
 } : never) | (M extends {
@@ -108,7 +122,7 @@ type CheckMutation<M> = M extends unknown ? TargetEntity<M> extends (infer T ext
   readonly set: CheckAssignments<V, UpdateValues<T>, NameOf<TargetTable<M>>>;
 } : never) | (M extends {
   readonly delete: unknown;
-} ? unknown : never)) : "SQL mutations require a supported non-inherited target and regenerated metadata" : never : never;
+} ? unknown : never)) : "SQL mutations require a supported non-inherited target and regenerated metadata" : never : CheckCustomMutation<M> : never;
 /** Classifies mutation roots before EntityManager applies write permissions, including malformed roots. */
 declare function isMutation(arg: unknown): boolean;
 /**
@@ -119,12 +133,21 @@ declare function isMutation(arg: unknown): boolean;
 declare function parseStatement(arg: unknown): Plan | undefined;
 /** Retains native counts even when no rows return, and propagates decoding failures after execution. */
 declare function decodeStatementResult(em: EntityHydrator, plan: Plan, result: DriverQueryResult): ExecuteResult<unknown>;
+/** An entity table whose generated metadata permits direct SQL mutations. */
 type MutationTarget<T extends Entity> = TableFor<T> & (TypeMapEntry<T, "supportsEmExecute"> extends true ? unknown : never);
+/** Shared filtering and full-table consent clauses for UPDATE and DELETE. */
 type MutationFilter = {
-  readonly where?: SqlCondition | ExprLike<boolean>;
+  /**
+   * An `{ and: [...] }` or `{ or: [...] }` group, a boolean expression, or a bare condition such as `a.age.gte(18)`.
+   *
+   * Arrays are shorthand for `{ and: [...] }`; undefined conditions are pruned.
+   */
+  readonly where?: SqlCondition | ExprLike<boolean> | readonly (SqlCondition | undefined)[];
+  /** Allows a supplied where to be undefined or fully pruned; unnecessary when where is omitted. */
   readonly allowAll?: boolean;
   readonly softDeletes?: "include" | "exclude";
 };
+/** Read-only query clauses that mutations explicitly reject. */
 type NoMutationReadClauses = Partial<Record<"select" | "join" | "groupBy" | "having" | "orderBy" | "limit" | "offset" | "distinct" | "pruneJoins" | "as" | "union" | "unionAll" | "intersect" | "intersectAll" | "except" | "exceptAll" | "ctes" | "using" | "onConflict", never>>;
 /** Column keys allowed in INSERT, i.e. Book's optional `id` and required `authorId`. */
 type InsertKey<T> = { [K in keyof ColumnsOf<T>]: ColumnsOf<T>[K] extends {
@@ -144,31 +167,105 @@ type DomainValue<T, K extends keyof ColumnsOf<T>> = K extends "id" ? IdOf<T> : C
 } ? IdOf<U> : ColumnsOf<T>[K] extends {
   type: infer V;
 } ? V : never;
+/** A modeled column's domain value with SQL nullability applied. */
 type SqlValue<T, K extends keyof ColumnsOf<T>> = DomainValue<T, K> | (ColumnsOf<T>[K] extends {
   nullable: true;
 } ? null : never);
+/** A modeled-column value, entity reference, or SQL expression that produces one. */
 type Assignment<T, K extends keyof ColumnsOf<T>> = SqlValue<T, K> | ExprLike<SqlValue<T, K>> | (K extends "id" ? never : ColumnsOf<T>[K] extends {
   entity: infer U;
 } ? U : never);
+/** A custom column's declared value with SQL nullability applied. */
+type CustomSqlValue<I> = CustomColumnValue<I> | (I extends {
+  nullable: true;
+} ? null : never);
+/** A custom-column value or SQL expression that produces one. */
+type CustomAssignment<I> = CustomSqlValue<I> | ExprLike<CustomSqlValue<I>>;
+/** Custom-column keys accepted by INSERT, excluding generated columns. */
+type CustomInsertKey<C extends CustomColumnInputs> = { [K in keyof C]: C[K] extends {
+  generated: true;
+} ? never : K; }[keyof C];
+/** Custom-column keys each INSERT row must supply because they have no default and are not nullable. */
+type CustomRequiredInsertKey<C extends CustomColumnInputs> = { [K in CustomInsertKey<C>]: C[K] extends {
+  nullable: true;
+} | {
+  hasDefault: true;
+} ? never : K; }[CustomInsertKey<C>];
+/** Custom-column keys accepted by UPDATE, excluding generated columns and the physical primary key. */
+type CustomUpdateKey<C extends CustomColumnInputs> = { [K in keyof C]: C[K] extends {
+  generated: true;
+} ? never : K extends "id" ? never : C[K] extends {
+  columnName: "id";
+} ? never : K; }[keyof C];
+/** Values accepted by INSERT for a custom table's declared columns. */
+type CustomInsertValues<C extends CustomColumnInputs> = { [K in CustomRequiredInsertKey<C>]: CustomAssignment<C[K]>; } & { [K in Exclude<CustomInsertKey<C>, CustomRequiredInsertKey<C>>]?: CustomAssignment<C[K]> | undefined; };
+/** Assignments accepted by UPDATE for a custom table's writable columns. */
+type CustomUpdateValues<C extends CustomColumnInputs> = { [K in CustomUpdateKey<C>]?: CustomAssignment<C[K]> | undefined; };
+/** Named row shape that an INSERT SELECT source must produce for a custom table. */
+type CustomInsertSourceRow<C extends CustomColumnInputs> = { [K in CustomRequiredInsertKey<C>]: CustomSqlValue<C[K]>; } & { [K in Exclude<CustomInsertKey<C>, CustomRequiredInsertKey<C>>]?: CustomSqlValue<C[K]>; };
+/** Named row shape that an entity INSERT SELECT source must produce. */
 type InsertSourceRow<T> = { [K in RequiredInsertKey<T>]: SqlValue<T, K>; } & { [K in Exclude<InsertKey<T>, RequiredInsertKey<T>>]?: SqlValue<T, K>; };
+/** Named expression projection accepted from an entity INSERT SELECT source. */
 type InsertProjection<T> = { [K in RequiredInsertKey<T>]: ExprLike<SqlValue<T, K>>; } & { [K in Exclude<InsertKey<T>, RequiredInsertKey<T>>]?: ExprLike<SqlValue<T, K>>; };
+/** Collects the keys from every member of a union instead of only their shared keys. */
 type UnionKeys<V> = V extends unknown ? keyof V : never;
 /** Collects every alternative before scope checking; a valid branch cannot hide an unrelated alias. */
 type UnionValue<V, K extends PropertyKey> = V extends unknown ? (K extends keyof V ? V[K] : never) : never;
+/** Extracts the source names carried by a SQL expression. */
 type ExprSource<V> = V extends {
   readonly [exprBrand]: ExprBrand<unknown, infer Src>;
 } ? Src : never;
+/** Rejects expressions that reference tables outside the statement's allowed scope. */
 type CheckExprScope<V, Scope> = string extends ExprSource<V> ? unknown : [Exclude<ExprSource<V>, Scope>] extends [never] ? unknown : "Expression source is not in the statement scope";
+/** Extracts each expression from a scalar or named RETURNING projection. */
 type ReturningExpr<R> = R extends ExprLike<unknown> ? R : R extends undefined ? never : R[keyof R];
+/** Detects an empty named RETURNING projection. */
 type EmptyReturning<R> = R extends object ? (keyof R extends never ? true : false) : false;
+/** Rejects empty RETURNING objects and expressions outside the target scope. */
 type CheckReturning<R, Scope> = true extends EmptyReturning<R> ? never : CheckExprScope<ReturningExpr<R>, Scope>;
+/** Validates assignment keys, values, and expression sources without distributing union inputs. */
 type CheckAssignments<V, Allowed, Scope> = [Exclude<UnionKeys<V>, keyof Allowed>] extends [never] ? Allowed & { [K in UnionKeys<V>]?: CheckExprScope<UnionValue<V, K>, Scope>; } : "SQL assignments have unknown target fields";
-type CheckValues<T extends Entity, V> = ([Extract<V, readonly unknown[]>] extends [never] ? never : readonly CheckAssignments<Extract<V, readonly unknown[]>[number], InsertValues<T>, never>[]) | ([Exclude<V, readonly unknown[]>] extends [never] ? never : CheckAssignments<Exclude<V, readonly unknown[]>, InsertValues<T>, never>);
+/** Checks every entity INSERT row in a readonly collection against writable columns. */
+type CheckValues<T extends Entity, V extends readonly unknown[]> = readonly CheckAssignments<V[number], InsertValues<T>, never>[];
+/**
+ * Checks a custom-table mutation against its declared primitive columns.
+ *
+ * Only clauses for the selected operation are allowed, and `softDeletes` is rejected because there is no entity
+ * policy. Assignments use declaration keys and honor nullability, defaults, and generated columns. INSERT VALUES
+ * cannot read the target row, while UPDATE SET and RETURNING can. INSERT SELECT must be a valid named read with all
+ * required columns and compatible declared value types; runtime checks also compare its SQL codecs and nullability.
+ */
+type CheckCustomMutation<M> = { readonly [K in keyof M]: K extends MutationClause<M> ? (K extends "softDeletes" ? never : unknown) : never; } & {
+  readonly returning?: M extends {
+    readonly returning?: infer R;
+  } ? CheckReturning<R, NameOf<TargetTable<M>>> : never;
+} & ((M extends {
+  readonly values: infer V extends readonly unknown[];
+} ? {
+  readonly values: CheckCustomValues<CustomColumnsOf<TargetTable<M>>, V>;
+} : never) | (M extends {
+  readonly from: infer Q extends SetOperand;
+} ? {
+  readonly from: CheckCustomInsertSource<CustomColumnsOf<TargetTable<M>>, Q>;
+} : never) | (M extends {
+  readonly set: infer V;
+} ? {
+  readonly set: CheckAssignments<V, CustomUpdateValues<CustomColumnsOf<TargetTable<M>>>, NameOf<TargetTable<M>>>;
+} : never) | (M extends {
+  readonly delete: unknown;
+} ? unknown : never));
+/** Checks every custom INSERT row in a readonly collection against declared writable columns. */
+type CheckCustomValues<C extends CustomColumnInputs, V extends readonly unknown[]> = readonly CheckAssignments<V[number], CustomInsertValues<C>, never>[];
+/** Checks a custom INSERT SELECT's named outputs, required columns, values, and read source. */
+type CheckCustomInsertSource<C extends CustomColumnInputs, Q> = SetOperand extends Q ? "INSERT source type lost its select keys; use `satisfies Query` or `satisfies SetQuery` instead of a type annotation" : ReadQueryRow<Q> extends CustomInsertSourceRow<C> ? Exclude<UnionKeys<ReadQueryRow<Q>>, CustomInsertKey<C>> extends never ? CheckReadQuery<Q> & CheckSourceScope<Q> & (Q extends SetQuery<readonly SetOperand[]> ? CheckSetQuery<Q> : unknown) : "INSERT SELECT has unknown target fields" : "INSERT SELECT requires compatible values for all SQL-required fields";
+/** Checks every SELECT expression against the tables visible within its read-query branch. */
 type CheckSourceScope<Q> = Q extends {
   readonly select: infer S;
   readonly from: infer F;
-} ? CheckScope<S, F, "join" extends keyof Q ? Extract<Q[keyof Q & "join"], QueryJoins> : []> : { [K in keyof Q]: K extends SetOperation ? Q[K] extends readonly unknown[] ? { [I in keyof Q[K]]: CheckSourceScope<Q[K][I]>; } : unknown : unknown; };
-type CheckInsertSource<T, Q extends SetOperand> = SetOperand extends Q ? "INSERT source was typed too generically; retain its named output fields" : ReadQueryRow<Q> extends InsertSourceRow<T> ? Exclude<UnionKeys<ReadQueryRow<Q>>, InsertKey<T>> extends never ? CheckReadQuery<Q> & CheckSourceScope<Q> & (Q extends SetQuery<readonly SetOperand[]> ? CheckSetQuery<Q> : unknown) : "INSERT SELECT has unknown target fields" : "INSERT SELECT requires compatible values for all SQL-required fields";
+} ? CheckScope<S, F, "join" extends keyof Q ? Extract<Q[keyof Q & "join"], QueryJoinInput> : []> : { [K in keyof Q]: K extends SetOperation ? Q[K] extends readonly unknown[] ? { [I in keyof Q[K]]: CheckSourceScope<Q[K][I]>; } : unknown : unknown; };
+/** Checks an entity INSERT SELECT's named outputs, required columns, values, and read source. */
+type CheckInsertSource<T, Q extends SetOperand> = SetOperand extends Q ? "INSERT source type lost its select keys; use `satisfies Query` or `satisfies SetQuery` instead of a type annotation" : ReadQueryRow<Q> extends InsertSourceRow<T> ? Exclude<UnionKeys<ReadQueryRow<Q>>, InsertKey<T>> extends never ? CheckReadQuery<Q> & CheckSourceScope<Q> & (Q extends SetQuery<readonly SetOperand[]> ? CheckSetQuery<Q> : unknown) : "INSERT SELECT has unknown target fields" : "INSERT SELECT requires compatible values for all SQL-required fields";
+/** Extracts the entity type from any mutation target clause. */
 type TargetEntity<M> = M extends {
   readonly insert: TableFor<infer T>;
 } | {
@@ -176,6 +273,7 @@ type TargetEntity<M> = M extends {
 } | {
   readonly delete: TableFor<infer T>;
 } ? T : never;
+/** Extracts the table handle from any mutation target clause. */
 type TargetTable<M> = M extends {
   readonly insert: infer A;
 } | {
@@ -183,6 +281,7 @@ type TargetTable<M> = M extends {
 } | {
   readonly delete: infer A;
 } ? A : never;
+/** Clauses permitted by the selected INSERT, UPDATE, or DELETE operation. */
 type MutationClause<M> = "returning" | "with" | (M extends {
   readonly insert: unknown;
 } ? "insert" | (M extends {

package/build/queries/sql/execute.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"execute.d.mts","names":[],"sources":["../../../src/queries/sql/execute.ts"],"mappings":"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"}
+{"version":3,"file":"execute.d.mts","names":[],"sources":["../../../src/queries/sql/execute.ts"],"mappings":"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"}