Repository navigation
Expand file tree
/
Copy pathengine-insert-duplicate-record.test.ts
More file actions
517 lines (436 loc) · 22.4 KB
/
Copy pathengine-insert-duplicate-record.test.ts
File metadata and controls
517 lines (436 loc) · 22.4 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
/**
* #14095 — the insert door's ONE error contract for a driver's unique-constraint
* refusal.
*
* ## What was measured, and why it is a defect rather than a preference
*
* The platform recommends "declare a unique index, attempt the insert, swallow
* the violation" — `createWithAutonumberResync`'s own doc argues against the
* read-then-write alternative. A real application could not complete that
* pattern: on the driver that enforces the index, the RAW driver error
* propagated out of `engine.insert` (`name=SqliteError`,
* `code='SQLITE_CONSTRAINT_UNIQUE'`, `Object.keys(err) = ['code']`, message =
* the whole compiled INSERT), so the app's only readings were a dialect code
* (which stops being idempotent the day the store changes) or the message text.
* The platform's own dialect-independent predicate lives in
* `@objectstack/types`, which an application cannot resolve.
*
* Triage ruled (2026-09-01) for wrapping in ObjectQL: 「抛一个带既有词表码
* (`DUPLICATE_RECORD` 已在 ADR-0112 台账里)的平台错误,原驱动错误作 `cause`
* ⇒ `insert` 在每个驱动上有同一份契约」.
*
* ## What this file pins
*
* Both directions, because only the pair is a contract:
*
* - every driver-error EXIT of the insert door turns a recognised unique
* violation into the envelope — single row, batch via `bulkCreate`, batch
* via the per-row fallback loop, `insertMany`'s partial mode, and the
* last-chance create the autonumber resync issues when the field vanished
* mid-flight; and
* - **nothing else moves**: a NOT NULL violation on a column no field declares
* ([#24768]: on a declared field it is the validator's `ValidationError`), a deadlock, a missing table
* and an unreachable store leave the door as the very object the driver
* threw — asserted on IDENTITY, not on a message match, so a future
* "helpful" re-wrap cannot pass this file.
*
* Refusal cases assert `code` AND `status` (ADR-0112), never `toThrow()` alone:
* a bare `toThrow` is green both when the door envelopes correctly and when a
* driver throws a raw error, which is the whole distinction under test.
*
* The driver fixtures are the dialect shapes `engine-autonumber-resync.test.ts`
* measured; they are restated here rather than shared because this file asks a
* different question of them (what the DOOR raises, not whether the resync
* re-issues) and a shared fixture module would couple the two files' futures.
*/
import { describe, it, expect, beforeEach, vi } from 'vitest';
import { isUniqueViolationError, uniqueViolationColumn } from '@objectstack/types';
import { ObjectQL, ScopedContext } from './engine';
import { DuplicateRecordError, DUPLICATE_RECORD_CODE } from './duplicate-record-error';
import { redactPropagatedDriverFault } from '@objectstack/types';
import { SchemaRegistry } from './registry';
import type { IDataDriver } from '@objectstack/spec/contracts';
/**
* [#21274] The driver's error as it LEAVES the engine: the same class, the same
* code and the database's own diagnostic, with the bound statement and the
* caller's values cut (`redactPropagatedDriverFault`). Until #21274 this was
* the very same object; identity is what the boundary cut gives up, and only
* identity — a driver error with nothing to cut still arrives as itself.
*/
function expectDriverErrorAsItLeaves(actual: unknown, raw: Error): void {
const expected = redactPropagatedDriverFault(raw) as Error;
expect(Object.getPrototypeOf(actual)).toBe(Object.getPrototypeOf(raw));
expect((actual as Error).message).toBe(expected.message);
expect((actual as { code?: unknown }).code).toBe((raw as { code?: unknown }).code);
}
vi.mock('./registry', async () => {
const { createRegistryModuleMock } = await import('./registry-module-mock.js');
return createRegistryModuleMock();
});
/**
* The double's `getObject`, typed.
*
* `createRegistryModuleMock` hands back a FUNCTION with the instance members
* assigned onto it (`Object.assign(SchemaRegistry, instance)`), so the mocked
* `getObject` is reachable off the imported binding at run time — but the
* binding's STATIC type is the real class, which declares `getObject` on
* instances only. Narrowed once here rather than cast at each call site, so
* `tsconfig.test.json` (which does compile this file — the package's plain
* `typecheck` excludes tests and would have said nothing) stays satisfied
* without an assertion in the middle of a test body.
*/
const registryDouble = SchemaRegistry as unknown as { getObject: ReturnType<typeof vi.fn> };
type Row = Record<string, unknown>;
/* --------------------------------------------------------------------------
* Driver fixtures — the shapes the supported dialects actually raise.
* ----------------------------------------------------------------------- */
/** better-sqlite3: names the COLUMN, and buries it behind the compiled statement. */
const sqliteDuplicate = () =>
Object.assign(
new Error(
'insert into `doc` (`email`, `id`, `title`) values (?, ?, ?) - ' +
'UNIQUE constraint failed: doc.email',
),
{ code: 'SQLITE_CONSTRAINT_UNIQUE' },
);
/** node-postgres: the column is in the DETAIL line, not the message. */
const postgresDuplicate = () =>
Object.assign(new Error('duplicate key value violates unique constraint "doc_email_key"'), {
code: '23505',
detail: 'Key (email)=(a@b.example) already exists.',
});
/** mysql2: names the INDEX. `uniqueViolationColumn` refuses to read it as a column. */
const mysqlDuplicate = () =>
Object.assign(new Error("Duplicate entry 'a@b.example' for key 'idx_doc_email'"), {
code: 'ER_DUP_ENTRY',
errno: 1062,
});
/** driver-memory (commit 56c093c4d): already an ADR-0112 envelope, in the platform's own vocabulary. */
const memoryDuplicate = () =>
Object.assign(
new Error('Unique constraint violated on `doc.email`: a record with that value already exists.'),
{ code: 'UNIQUE_VIOLATION', status: 409 },
);
/* -------- the negative side: failures that must NOT change shape --------- */
/**
* [#24768] On a column NO field of `doc` declares: a NOT NULL refusal on a
* declared field is the engine's `ValidationError` now
* (`engine-not-null-refusal.test.ts`), and this one is what still leaves as the
* driver threw it.
*/
const notNullViolation = () =>
Object.assign(new Error('NOT NULL constraint failed: doc.legacy_col'), {
code: 'SQLITE_CONSTRAINT_NOTNULL',
});
const missingTable = () =>
Object.assign(new Error('SQLITE_ERROR: no such table: doc'), { code: 'SQLITE_ERROR' });
const deadlock = () => Object.assign(new Error('deadlock detected'), { code: '40P01' });
const unreachableStore = () =>
Object.assign(new Error('connect ECONNREFUSED 127.0.0.1:5432'), { code: 'ECONNREFUSED' });
/* --------------------------------------------------------------------------
* Rig
* ----------------------------------------------------------------------- */
const SCHEMA = {
name: 'doc',
fields: {
title: { type: 'text' },
email: { type: 'text' },
},
indexes: [{ name: 'idx_doc_email', fields: ['email'], unique: true }],
};
interface DriverOpts {
/** What `create` / `bulkCreate` reject with. `null` = accept everything. */
refuse?: (() => unknown) | null;
/** Omit `bulkCreate` so a batch takes the engine's per-row fallback loop. */
noBulkCreate?: boolean;
}
function makeDriver(opts: DriverOpts = {}) {
const refuse = opts.refuse ?? null;
const stored: Row[] = [];
const driver: any = {
name: 'fake',
version: '0.0.0',
supports: {},
connect: vi.fn().mockResolvedValue(undefined),
disconnect: vi.fn().mockResolvedValue(undefined),
checkHealth: vi.fn().mockResolvedValue(true),
execute: vi.fn(),
find: vi.fn(async () => []),
findOne: vi.fn(),
create: vi.fn(async (_obj: string, row: Row) => {
if (refuse) throw refuse();
const written = { id: `new${stored.length + 1}`, ...row };
stored.push(written);
return written;
}),
update: vi.fn(),
delete: vi.fn(),
count: vi.fn(),
};
if (!opts.noBulkCreate) {
driver.bulkCreate = vi.fn(async (_obj: string, rows: Row[]) => {
if (refuse) throw refuse();
return rows.map((row, i) => ({ id: `new${stored.length + i + 1}`, ...row }));
});
}
return driver as IDataDriver & { create: any; bulkCreate?: any };
}
function makeRig(opts: DriverOpts = {}, schema: unknown = SCHEMA) {
registryDouble.getObject.mockReturnValue(schema);
const driver = makeDriver(opts);
const engine = new ObjectQL();
engine.registerDriver(driver, true);
return { engine, driver };
}
/** The rejection, as the value the caller actually receives. */
async function refusalOf(run: () => Promise<unknown>): Promise<any> {
return run().then(
() => {
throw new Error('expected the insert to be refused');
},
(e) => e as any,
);
}
describe('engine.insert — a driver unique violation is a DUPLICATE_RECORD envelope (#14095)', () => {
beforeEach(() => {
vi.clearAllMocks();
});
/* ====================================================================== *
* (1) The envelope itself
* ==================================================================== */
describe('the envelope, on the single-row door', () => {
it('carries the ADR-0112 code AND status, with the driver error whole on `cause`', async () => {
const raw = sqliteDuplicate();
const { engine } = makeRig({ refuse: () => raw });
await engine.init();
const failure = await refusalOf(() => engine.insert('doc', { title: 't', email: 'a@b.example' }));
// The two halves a refusal test must assert — never `toThrow()` alone.
expect(failure.code).toBe(DUPLICATE_RECORD_CODE);
expect(failure.code).toBe('DUPLICATE_RECORD');
expect(failure.status).toBe(409);
// The driver's own diagnosis is preserved rather than replaced: its class,
// its code and the database's words. [#21274] A copy since the boundary
// cut — the bound statement and the caller's values are what it gave up.
expectDriverErrorAsItLeaves(failure.cause, raw);
expect(failure).toBeInstanceOf(DuplicateRecordError);
expect(failure.name).toBe('DuplicateRecordError');
});
it('names the object, and the COLUMN when the dialect determinably named one', async () => {
const { engine } = makeRig({ refuse: sqliteDuplicate });
await engine.init();
const failure = await refusalOf(() => engine.insert('doc', { title: 't', email: 'a@b.example' }));
expect(failure.object).toBe('doc');
expect(failure.field).toBe('email');
expect(failure.message).toContain("'doc'");
expect(failure.message).toContain("'email'");
expect(failure.message).toContain('No record was written');
});
it('reads the column out of Postgres DETAIL, which is not on the message at all', async () => {
const { engine } = makeRig({ refuse: postgresDuplicate });
await engine.init();
const failure = await refusalOf(() => engine.insert('doc', { title: 't', email: 'a@b.example' }));
expect(failure.code).toBe('DUPLICATE_RECORD');
expect(failure.status).toBe(409);
expect(failure.field).toBe('email');
});
it('names NO field when the dialect named an INDEX — never the index as a column', async () => {
// MySQL's `for key 'idx_doc_email'` is an index name. `uniqueViolationColumn`
// refuses it on the maintainer's 2026-08-08 ruling (#6544): a wrong field
// name is worse than none, because it sends the author to correct an input
// that was never the problem. This door does not widen that contract.
const { engine } = makeRig({ refuse: mysqlDuplicate });
await engine.init();
const failure = await refusalOf(() => engine.insert('doc', { title: 't', email: 'a@b.example' }));
expect(failure.code).toBe('DUPLICATE_RECORD');
expect(failure.status).toBe(409);
expect(failure.field).toBeUndefined();
expect('field' in failure).toBe(true); // the class declares it; the VALUE is absent
expect(failure.message).toContain("'doc'");
expect(failure.message).not.toContain('idx_doc_email');
});
it('normalises a driver that already speaks an envelope — one code, not two', async () => {
// driver-memory raises `UNIQUE_VIOLATION` / 409 (commit 56c093c4d). It is a platform
// envelope, but it is a DIFFERENT one, so an application branching on the
// insert door would still need two spellings. The door answers one.
const raw = memoryDuplicate();
const { engine } = makeRig({ refuse: () => raw });
await engine.init();
const failure = await refusalOf(() => engine.insert('doc', { title: 't', email: 'a@b.example' }));
expect(failure.code).toBe('DUPLICATE_RECORD');
expect(failure.status).toBe(409);
expectDriverErrorAsItLeaves(failure.cause, raw);
expect((failure.cause as any).code).toBe('UNIQUE_VIOLATION');
});
it('is idempotent — an envelope reaching a seam twice does not nest', async () => {
const inner = sqliteDuplicate();
const already = new DuplicateRecordError('doc', inner, 'email');
const { engine } = makeRig({ refuse: () => already });
await engine.init();
const failure = await refusalOf(() => engine.insert('doc', { title: 't' }));
// [#21274] No longer the same object — the boundary cuts the envelope's
// `cause` — but still ONE envelope deep, which is what this pins.
expect(failure).toBeInstanceOf(DuplicateRecordError);
expect(failure.field).toBe(already.field);
expect(failure.cause).not.toBeInstanceOf(DuplicateRecordError);
expectDriverErrorAsItLeaves(failure.cause, inner);
});
});
/* ====================================================================== *
* (2) Every driver-error exit of the door, not just the easy one
* ==================================================================== */
describe('the same contract on every path a driver create failure leaves by', () => {
it('batch insert through `bulkCreate`', async () => {
const raw = sqliteDuplicate();
const { engine, driver } = makeRig({ refuse: () => raw });
await engine.init();
const failure = await refusalOf(() =>
engine.insert('doc', [{ title: 'a', email: 'a@b.example' }, { title: 'b', email: 'a@b.example' }]),
);
expect((driver as any).bulkCreate).toHaveBeenCalledTimes(1);
expect(failure.code).toBe('DUPLICATE_RECORD');
expect(failure.status).toBe(409);
expectDriverErrorAsItLeaves(failure.cause, raw);
expect(failure.field).toBe('email');
});
it('batch insert through the per-row fallback loop (a driver with no `bulkCreate`)', async () => {
const raw = postgresDuplicate();
const { engine, driver } = makeRig({ refuse: () => raw, noBulkCreate: true });
await engine.init();
const failure = await refusalOf(() => engine.insert('doc', [{ title: 'a', email: 'a@b.example' }]));
expect((driver as any).bulkCreate).toBeUndefined();
expect(failure.code).toBe('DUPLICATE_RECORD');
expect(failure.status).toBe(409);
expectDriverErrorAsItLeaves(failure.cause, raw);
});
it("insertMany's partial-row mode — a driver write failure is still a whole-call rejection", async () => {
const raw = sqliteDuplicate();
const { engine } = makeRig({ refuse: () => raw });
await engine.init();
const failure = await refusalOf(() => engine.insertMany('doc', [{ title: 'a', email: 'a@b.example' }]));
expect(failure.code).toBe('DUPLICATE_RECORD');
expect(failure.status).toBe(409);
expectDriverErrorAsItLeaves(failure.cause, raw);
});
it('the scoped-repository facade reaches the same envelope', async () => {
// `ScopedContext.object(name).insert(data)` is what a hook reaches as
// `ctx.api.object(name)` — it delegates to this same door, so it inherits
// the contract rather than declaring a second one.
const raw = sqliteDuplicate();
const { engine } = makeRig({ refuse: () => raw });
await engine.init();
const repo = new ScopedContext({} as any, engine as any).object('doc');
const failure = await refusalOf(() => repo.insert({ title: 't' }));
expect(failure.code).toBe('DUPLICATE_RECORD');
expectDriverErrorAsItLeaves(failure.cause, raw);
});
it('the autonumber resync\'s LAST-CHANCE create, after the field vanished mid-flight', async () => {
// The one exit that sits OUTSIDE the resync loop's own `try`: the engine
// re-seeds, finds nothing left to re-issue because the field is gone from
// the schema, and issues one final create. Its rejection is a second
// driver-error exit, and it is enveloped on the same terms as the first.
const numbered = {
name: 'doc',
fields: { title: { type: 'text' }, doc_no: { type: 'autonumber', required: true, format: 'D-{0000}' } },
};
const raw = mysqlDuplicate();
const { engine } = makeRig({ refuse: () => raw }, numbered);
await engine.init();
// The first refusal is attributed to the number this insert issued, so the
// engine re-seeds; the schema it re-reads no longer declares the field, so
// `applyAutonumbers` issues nothing and the last-chance create runs.
registryDouble.getObject.mockReturnValue({
name: 'doc',
fields: { title: { type: 'text' } },
});
const failure = await refusalOf(() => engine.insert('doc', { title: 't' }));
expect(failure.code).toBe('DUPLICATE_RECORD');
expect(failure.status).toBe(409);
expectDriverErrorAsItLeaves(failure.cause, raw);
});
});
/* ====================================================================== *
* (3) The negative side — the positive controls
* ==================================================================== */
describe('nothing that is not a unique violation changes shape', () => {
const controls: Array<[string, () => unknown]> = [
['a NOT NULL violation on an undeclared column', notNullViolation],
['a missing table', missingTable],
['a deadlock', deadlock],
['an unreachable store', unreachableStore],
];
for (const [label, make] of controls) {
it(`${label} leaves the single-row door as the very object the driver threw`, async () => {
const raw = make();
const { engine } = makeRig({ refuse: () => raw });
await engine.init();
const failure = await refusalOf(() => engine.insert('doc', { title: 't' }));
// Identity, not a message match: this is the assertion a future
// "helpful" re-wrap of every driver error would have to break.
expect(failure).toBe(raw);
expect(failure.code).not.toBe('DUPLICATE_RECORD');
expect(failure).not.toBeInstanceOf(DuplicateRecordError);
expect(failure.status).toBeUndefined();
});
it(`${label} leaves the BATCH door unchanged too`, async () => {
const raw = make();
const { engine } = makeRig({ refuse: () => raw });
await engine.init();
const failure = await refusalOf(() => engine.insert('doc', [{ title: 't' }]));
expect(failure).toBe(raw);
expect(failure).not.toBeInstanceOf(DuplicateRecordError);
});
}
it('a NOT NULL violation is refused as a NOT NULL violation, not as a conflict', async () => {
// SQLite spells NOT NULL and UNIQUE with the same `… constraint failed:
// t.c` shape, so this is the case a message-matching wrap gets wrong. The
// verdict comes from the shared predicate, which deliberately excludes the
// bare `constraint failed` word pair.
expect(isUniqueViolationError(notNullViolation())).toBe(false);
});
});
/* ====================================================================== *
* (4) The envelope does not break the consumers of the raw error
* ==================================================================== */
describe('every existing reader of the raw error keeps its answer', () => {
it('the shared predicate still says yes, through the `cause` chain', async () => {
const { engine } = makeRig({ refuse: sqliteDuplicate });
await engine.init();
const failure = await refusalOf(() => engine.insert('doc', { title: 't' }));
// `isUniqueViolationError` walks `cause`, so a consumer holding the
// envelope gets the same verdict it got from the raw error — which is what
// makes REST's 409 arm and the import runner survive this change.
expect(isUniqueViolationError(failure)).toBe(true);
expect(uniqueViolationColumn(failure)).toBe('email');
});
it('the message never opens with a SQL verb', async () => {
// `@objectstack/rest`'s importer runs every row error through
// `sanitizeRowError`, whose backstop DISCARDS any message starting with
// `insert`/`update`/`delete`/`select`/`with`/`replace` as a leaked
// statement. A message opening "Insert on 'doc' …" would be replaced by
// generic text — measured, which is why the wording is pinned here.
const { engine } = makeRig({ refuse: sqliteDuplicate });
await engine.init();
const failure = await refusalOf(() => engine.insert('doc', { title: 't' }));
expect(/^\s*(insert|update|delete|select|with|replace)\s/i.test(failure.message)).toBe(false);
});
it('carries none of the driver statement or its bound values', async () => {
// #8682's discipline, one layer out: the compiled statement is not quoted
// here (and, since #21274, is cut from `cause` too). REST's declared-4xx arm ships `message` to the client
// verbatim, so quoting the driver here would move the leak onto the wire.
const { engine } = makeRig({ refuse: sqliteDuplicate });
await engine.init();
const failure = await refusalOf(() => engine.insert('doc', { title: 't' }));
expect(failure.message).not.toMatch(/insert into/i);
expect(failure.message).not.toContain('values (?');
expect(String((failure.cause as Error).message)).toMatch(/insert into/i);
});
it('addresses the application author on `developerMessage`, as DELETE_RESTRICTED does', async () => {
const { engine } = makeRig({ refuse: sqliteDuplicate });
await engine.init();
const failure = await refusalOf(() => engine.insert('doc', { title: 't' }));
expect(failure.developerMessage).toContain('DUPLICATE_RECORD');
expect(failure.developerMessage).toContain('cause');
});
});
});