feat(typeorm): support unique upsert targets (#39)

Author: kauandotnet

.changeset/typeorm-unique-upsert-targets.md

@@ -0,0 +1,9 @@
+---
+"@nestm/crud-typeorm": minor
+---
+
+Allow atomic PostgreSQL upserts to target a complete non-deferrable TypeORM
+unique constraint or non-partial unique index in addition to the primary
+identity. This supports entities with generated primary keys and domain-owned
+alternate identities while preserving scoped conflict-update authorization,
+explicit overwrite allowlists, and single-statement execution.

packages/crud-typeorm/README.md

@@ -173,7 +173,7 @@ path.
 ## Atomic upsert
 
 When a resource enables the core `upsert` operation, configure its binding with
-the complete TypeORM primary identity and the exact persistence fields that may
+a complete TypeORM conflict identity and the exact persistence fields that may
 change on conflict:
 
 ```ts
@@ -194,11 +194,17 @@ const viewerBindings = bindTypeOrmCrud({
 ```
 
 Both lists contain TypeORM entity property paths, not public CRUD field names or
-database column names. `conflictFields` must be non-empty, map exactly once to
-every primary column, and have non-null values in the final scoped insert row.
-`overwriteFields` must be unique, non-primary scalar columns that TypeORM permits
-on both insert and update. This explicit allowlist prevents an upsert from
-silently replacing immutable ownership or secret fields.
+database column names. `conflictFields` must be non-empty, have non-null values
+in the final scoped insert row, and map exactly once to either every primary
+column, every column in a non-deferrable unique constraint, or every column in a
+non-partial unique index. This allows a generated primary key to remain absent
+when an alternate domain identity is the conflict target. Deferrable unique
+constraints and partial unique indexes are rejected because this contract does
+not carry the extra PostgreSQL conflict-target semantics they require.
+`overwriteFields` must be unique, disjoint from the conflict fields, and map to
+non-primary scalar columns that TypeORM permits on both insert and update. This
+explicit allowlist prevents an upsert from silently replacing immutable
+ownership or secret fields.
 
 The adapter emits one PostgreSQL `INSERT ... ON CONFLICT (...) DO UPDATE ...
 WHERE ... RETURNING ...` statement. The normal CRUD predicate and native

packages/crud-typeorm/src/bind-typeorm-crud.ts

@@ -57,7 +57,7 @@ interface BindTypeOrmCrudOptionsBase<
 	 * so a field expressible there is a field a client can change.
 	 */
 	readonly scopeCreateFields?: ScopeCreateFields;
-	/** Atomic upsert primary-conflict and mutable-overwrite persistence paths. */
+	/** Atomic upsert conflict-target and mutable-overwrite persistence paths. */
 	readonly upsert?: CrudBindingUpsertOptions;
 	/** Standard Nest provider form for an adapter; injected repositories remain application-owned. */
 	readonly adapter: TypeOrmCrudAdapterProvider<EntityType, RecordType>;

packages/crud-typeorm/src/typeorm-adapter.ts

@@ -426,6 +426,32 @@ function scalarMutationColumn(
 	return column === undefined || column.isVirtual || column.isVirtualProperty ? undefined : column;
 }
 
+function isUpsertConflictIdentity(
+	metadata: EntityMetadata,
+	columns: readonly TypeOrmColumnMetadata[],
+): boolean {
+	if (sameColumnSet(columns, metadata.primaryColumns)) return true;
+	if (
+		metadata.uniques.some(
+			(unique) => unique.deferrable === undefined && sameColumnSet(columns, unique.columns),
+		)
+	) {
+		return true;
+	}
+	return metadata.indices.some(
+		(index) => index.isUnique && index.where === undefined && sameColumnSet(columns, index.columns),
+	);
+}
+
+function sameColumnSet(
+	left: readonly TypeOrmColumnMetadata[],
+	right: readonly TypeOrmColumnMetadata[],
+): boolean {
+	if (left.length === 0 || left.length !== right.length) return false;
+	const expected = new Set(right);
+	return expected.size === right.length && left.every((column) => expected.has(column));
+}
+
 function strongestIsolationLevel(
 	...levels: readonly (TypeOrmCrudTransactionIsolationLevel | undefined)[]
 ): TypeOrmCrudTransactionIsolationLevel {
@@ -1288,29 +1314,22 @@ export class TypeOrmCrudAdapter<
 		entity: EntityType,
 		propertyPaths: readonly string[],
 	): string[] {
-		const primaryColumns = repository.metadata.primaryColumns;
-		if (propertyPaths.length !== primaryColumns.length || propertyPaths.length === 0) {
-			throw new CrudAdapterError(
-				"unsupported",
-				"TypeORM CRUD upsert conflict fields must map to the complete primary identity.",
-			);
-		}
-		if (primaryColumns.some((column) => column.isVirtual || column.isVirtualProperty)) {
+		if (propertyPaths.length === 0) {
 			throw new CrudAdapterError(
 				"unsupported",
-				"TypeORM CRUD upsert requires a physical scalar primary identity.",
+				"TypeORM CRUD upsert conflict fields must map to a complete primary or unique identity.",
 			);
 		}
 
-		const expected = new Set(primaryColumns);
 		const seenColumns = new Set<TypeOrmColumnMetadata>();
+		const conflictColumns: TypeOrmColumnMetadata[] = [];
 		const databaseNames: string[] = [];
 		for (const propertyPath of propertyPaths) {
 			const column = scalarMutationColumn(repository.metadata, propertyPath);
-			if (column === undefined || !expected.has(column) || seenColumns.has(column)) {
+			if (column === undefined || !column.isInsert || seenColumns.has(column)) {
 				throw new CrudAdapterError(
 					"unsupported",
-					"TypeORM CRUD upsert conflict fields must map to the complete primary identity.",
+					"TypeORM CRUD upsert conflict fields must map to a complete physical primary or unique identity.",
 				);
 			}
 			if (column.getEntityValue(entity) === undefined || column.getEntityValue(entity) === null) {
@@ -1320,12 +1339,13 @@ export class TypeOrmCrudAdapter<
 				);
 			}
 			seenColumns.add(column);
+			conflictColumns.push(column);
 			databaseNames.push(column.databaseName);
 		}
-		if (seenColumns.size !== expected.size) {
+		if (!isUpsertConflictIdentity(repository.metadata, conflictColumns)) {
 			throw new CrudAdapterError(
 				"unsupported",
-				"TypeORM CRUD upsert conflict fields must map to the complete primary identity.",
+				"TypeORM CRUD upsert conflict fields must map to the complete primary identity, a non-deferrable unique constraint, or a non-partial unique index.",
 			);
 		}
 		return databaseNames;

packages/crud-typeorm/tests/typeorm-upsert.spec.ts

@@ -61,6 +61,24 @@ const UPSERT_INPUT = {
 	overwriteFields: ["name"],
 } as const satisfies CrudUpsertInput<DeepPartial<UpsertEntity>>;
 
+const UNIQUE_UPSERT_INPUT = {
+	conflictFields: ["tenantId", "immutable"],
+	predicate: {
+		kind: "and",
+		predicates: [
+			{ kind: "comparison", field: "tenantId", operator: "eq", value: "tenant-a" },
+			{ kind: "comparison", field: "immutable", operator: "eq", value: "fixed" },
+		],
+	},
+	values: {
+		tenantId: "tenant-a",
+		name: "Grace",
+		secret: "ciphertext",
+		immutable: "fixed",
+	},
+	overwriteFields: ["name"],
+} as const satisfies CrudUpsertInput<DeepPartial<UpsertEntity>>;
+
 interface ColumnCapture {
 	readonly propertyPath: string;
 	readonly databaseName: string;
@@ -105,6 +123,15 @@ interface UpsertHarnessOptions {
 	readonly treeType?: string;
 	readonly inheritancePattern?: string;
 	readonly childEntityCount?: number;
+	readonly primaryFields?: readonly Extract<keyof UpsertEntity, string>[];
+	readonly uniqueConstraints?: readonly {
+		readonly fields: readonly Extract<keyof UpsertEntity, string>[];
+		readonly deferrable?: string;
+	}[];
+	readonly uniqueIndexes?: readonly {
+		readonly fields: readonly Extract<keyof UpsertEntity, string>[];
+		readonly where?: string;
+	}[];
 }
 
 function setProperty(target: Record<string, unknown>, path: string, value: unknown): void {
@@ -126,18 +153,19 @@ function createUpsertHarness(options: UpsertHarnessOptions = {}): UpsertHarness
 	const prepareHydratedValue = vi.fn((value: unknown, column: ColumnCapture) =>
 		column.propertyPath === "name" ? `hydrated:${String(value)}` : value,
 	);
+	const primaryFields = new Set(options.primaryFields ?? ["tenantId", "id"]);
 	const columnDefinitions = [
-		["tenantId", "tenant_id", true, true, true],
-		["id", "id", true, true, true],
-		["name", "display_name", false, true, true],
-		["secret", "secret_ciphertext", false, true, true],
-		["immutable", "immutable_value", false, true, false],
+		["tenantId", "tenant_id", true, true],
+		["id", "id", true, true],
+		["name", "display_name", true, true],
+		["secret", "secret_ciphertext", true, true],
+		["immutable", "immutable_value", true, false],
 	] as const;
 	const columns = columnDefinitions.map(
-		([propertyPath, databaseName, isPrimary, isInsert, isUpdate]): ColumnCapture => ({
+		([propertyPath, databaseName, isInsert, isUpdate]): ColumnCapture => ({
 			propertyPath,
 			databaseName,
-			isPrimary,
+			isPrimary: primaryFields.has(propertyPath),
 			isInsert,
 			isUpdate,
 			isVirtual: false,
@@ -147,6 +175,12 @@ function createUpsertHarness(options: UpsertHarnessOptions = {}): UpsertHarness
 		}),
 	);
 	const columnByPath = new Map(columns.map((column) => [column.propertyPath, column]));
+	const metadataColumns = (fields: readonly Extract<keyof UpsertEntity, string>[]) =>
+		fields.map((field) => {
+			const column = columnByPath.get(field);
+			if (column === undefined) throw new Error(`Unknown harness column '${field}'.`);
+			return column;
+		});
 
 	let repository: Repository<UpsertEntity>;
 	const manager = {
@@ -264,6 +298,15 @@ function createUpsertHarness(options: UpsertHarnessOptions = {}): UpsertHarness
 		tableName: "upsert_entity",
 		columns,
 		primaryColumns: columns.filter((column) => column.isPrimary),
+		uniques: (options.uniqueConstraints ?? []).map((unique) => ({
+			columns: metadataColumns(unique.fields),
+			...(unique.deferrable === undefined ? {} : { deferrable: unique.deferrable }),
+		})),
+		indices: (options.uniqueIndexes ?? []).map((index) => ({
+			isUnique: true,
+			columns: metadataColumns(index.fields),
+			...(index.where === undefined ? {} : { where: index.where }),
+		})),
 		findColumnWithPropertyPath: (path: string) => columnByPath.get(path),
 		findColumnWithPropertyPathStrict: (path: string) => columnByPath.get(path),
 		create: () => ({}),
@@ -352,6 +395,28 @@ describe("TypeOrmCrudAdapter atomic upsert", () => {
 		);
 	});
 
+	it.each(["constraint", "index"] as const)(
+		"accepts a complete non-primary unique %s while the generated primary value is absent",
+		async (kind) => {
+			const unique = { fields: ["tenantId", "immutable"] as const };
+			const harness = createUpsertHarness({
+				primaryFields: ["id"],
+				...(kind === "constraint" ? { uniqueConstraints: [unique] } : { uniqueIndexes: [unique] }),
+			});
+
+			const result = await selectedAdapter(harness).upsert(UNIQUE_UPSERT_INPUT, context());
+
+			expect(harness.capture.inserts[0]).toEqual(
+				expect.objectContaining({
+					conflict: ["tenant_id", "immutable_value"],
+					overwrite: ["display_name"],
+					values: expect.not.objectContaining({ id: expect.anything() }),
+				}),
+			);
+			expect(result).toMatchObject({ id: "item-1", name: "hydrated:Grace" });
+		},
+	);
+
 	it("returns null without hydrating when the conflicting row fails authorization", async () => {
 		const harness = createUpsertHarness({ returned: [] });
 		const result = await selectedAdapter(harness).upsert(UPSERT_INPUT, context());
@@ -400,7 +465,7 @@ describe("TypeOrmCrudAdapter atomic upsert", () => {
 		});
 	});
 
-	it("rejects partial, duplicated, non-primary, and absent conflict paths before DML", async () => {
+	it("rejects partial, duplicated, non-unique, and absent conflict paths before DML", async () => {
 		const cases: readonly CrudUpsertInput<DeepPartial<UpsertEntity>>[] = [
 			{ ...UPSERT_INPUT, conflictFields: ["tenantId"] },
 			{ ...UPSERT_INPUT, conflictFields: ["tenantId", "tenantId"] },
@@ -425,6 +490,31 @@ describe("TypeOrmCrudAdapter atomic upsert", () => {
 		}
 	});
 
+	it("rejects deferrable unique constraints and partial unique indexes before DML", async () => {
+		const cases: readonly UpsertHarnessOptions[] = [
+			{
+				primaryFields: ["id"],
+				uniqueConstraints: [
+					{ fields: ["tenantId", "immutable"], deferrable: "INITIALLY DEFERRED" },
+				],
+			},
+			{
+				primaryFields: ["id"],
+				uniqueIndexes: [
+					{ fields: ["tenantId", "immutable"], where: '"immutable_value" IS NOT NULL' },
+				],
+			},
+		];
+
+		for (const options of cases) {
+			const harness = createUpsertHarness(options);
+			await expect(
+				selectedAdapter(harness).upsert(UNIQUE_UPSERT_INPUT, context()),
+			).rejects.toMatchObject({ code: "unsupported" } satisfies Partial<CrudAdapterError>);
+			expect(harness.capture.inserts).toHaveLength(0);
+		}
+	});
+
 	it("rejects primary, immutable, unknown, and duplicated overwrite paths before DML", async () => {
 		for (const overwriteFields of [["id"], ["immutable"], ["missing"], ["name", "name"]] as const) {
 			const harness = createUpsertHarness();

tests/postgres/typeorm-upsert.postgres.spec.ts

@@ -7,8 +7,9 @@ import {
 	DataSource,
 	Entity,
 	type Logger,
-	PrimaryColumn,
+	PrimaryGeneratedColumn,
 	type QueryRunner,
+	Unique,
 	type ValueTransformer,
 } from "typeorm";
 import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
@@ -34,14 +35,18 @@ const secretTransformer: ValueTransformer = {
 };
 
 @Entity({ name: TABLE, synchronize: false })
+@Unique("crud_pg_typeorm_upsert_items_identity_unique", ["tenantId", "viewerUserId", "serverId"])
 class UpsertItem {
-	@PrimaryColumn({ name: "tenant_id", type: "text" })
+	@PrimaryGeneratedColumn("uuid", { name: "id" })
+	readonly id!: string;
+
+	@Column({ name: "tenant_id", type: "text" })
 	readonly tenantId!: string;
 
-	@PrimaryColumn({ name: "viewer_user_id", type: "text" })
+	@Column({ name: "viewer_user_id", type: "text" })
 	readonly viewerUserId!: string;
 
-	@PrimaryColumn({ name: "server_id", type: "text" })
+	@Column({ name: "server_id", type: "text" })
 	readonly serverId!: string;
 
 	@Column({ name: "display_name", type: "text", transformer: visibleTransformer })
@@ -72,6 +77,7 @@ class QueryCaptureLogger implements Logger {
 }
 
 const COLUMNS = {
+	id: "id",
 	tenantId: "tenantId",
 	viewerUserId: "viewerUserId",
 	serverId: "serverId",
@@ -93,6 +99,7 @@ function selectedAdapter(authorizedTenant = "tenant-a") {
 		repository: source().getRepository(UpsertItem),
 		columns: COLUMNS,
 		select: {
+			id: true,
 			tenantId: true,
 			viewerUserId: true,
 			serverId: true,
@@ -169,13 +176,15 @@ describe.skipIf(skipPostgres)("TypeORM atomic upsert", () => {
 		await adminPool.query(`
 			DROP TABLE IF EXISTS ${TABLE};
 			CREATE TABLE ${TABLE} (
+				id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
 				tenant_id text NOT NULL,
 				viewer_user_id text NOT NULL,
 				server_id text NOT NULL,
 				display_name text NOT NULL,
 				allowed_tools jsonb,
 				secret_ciphertext text NOT NULL,
-				PRIMARY KEY (tenant_id, viewer_user_id, server_id)
+				CONSTRAINT crud_pg_typeorm_upsert_items_identity_unique
+					UNIQUE (tenant_id, viewer_user_id, server_id)
 			)
 		`);
 		dataSource = await new DataSource({
@@ -278,6 +287,7 @@ describe.skipIf(skipPostgres)("TypeORM atomic upsert", () => {
 			repository: source().getRepository(UpsertItem),
 			columns: COLUMNS,
 			select: {
+				id: true,
 				tenantId: true,
 				viewerUserId: true,
 				serverId: true,