Skip to content

Commit 69181bf

Browse files
committed
refactor(driver-sql): move the autonumber sequence path out of sql-driver.ts into sql-driver-autonumber.ts
The bodies of SqlDriver#getNextSequenceValue, #fillAutoNumberFields, #issueAutonumbers, #maxAutonumberCounter, #collidingAutoNumberReservations and #resyncSequenceToDataMax move unedited into a new seam module through AutonumberHost. Each method keeps its docblock and signature and hands its body the members it reads (getters for fields, late-bound closures for methods), so TursoDriver's overrides and instance spies are still the ones reached. SEQUENCES_TABLE gains `export` in place and is imported back; five import names whose last reader moved are dropped. Move-only. Co-authored-by: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012UMsT3A7YJv6eQtR5HED2B
1 parent 817cb89 commit 69181bf

2 files changed

Lines changed: 433 additions & 257 deletions

File tree

Lines changed: 367 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,367 @@
1+
// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
2+
3+
/**
4+
* [#25521 cut 11] The autonumber sequence path of `SqlDriver`: the counter
5+
* read-and-advance `getNextSequenceValue`, the per-row fill
6+
* `fillAutoNumberFields`, the issue-ahead door `issueAutonumbers`, the
7+
* bootstrap reading `maxAutonumberCounter`, and the #5495 collision re-seed
8+
* (`collidingAutoNumberReservations`, `resyncSequenceToDataMax`). They moved
9+
* out of `sql-driver.ts` whole.
10+
*
11+
* A MOVE, not a redesign. Each function below is the body of the `SqlDriver`
12+
* method of the same name as it stood, re-indented one level and otherwise
13+
* unedited: the same counter key, the same tenant bucket, the same lock, the
14+
* same bootstrap and the same re-seed.
15+
*
16+
* What did NOT move, and why:
17+
*
18+
* - `ensureSequencesTable` and `ensureSequencesKeyHashShape` write the
19+
* driver's fields, and the series keeps a body that writes `this` in the
20+
* class.
21+
* - `autoNumberValueExists` and `scanMaxNumericTail` each hold a
22+
* tenant-column predicate that `check:tenant-chokepoint`'s ADR-0131 D8 rule
23+
* counts, and that gate scans the driver files, not this module.
24+
* - The small members the sequence-semantics block names (the counter key,
25+
* the tenant bucket, the table definition and the two getters) and
26+
* `attemptWithoutPoisoning` pay nothing to move.
27+
*
28+
* ## How the moved bodies reach the class
29+
*
30+
* The shape the other seam modules apply, after #23050. The class keeps every
31+
* method, because the published `dist/*.d.ts` lists each one's name,
32+
* docblock and position. `TursoDriver` overrides `getNextSequenceValue`,
33+
* `autoNumberValueExists` and `resyncSequenceToDataMax`, and each override
34+
* calls `super` on its local path. Each body is now one literal of exactly the
35+
* {@link AutonumberHost} members that method reads, plus a `.call`. The five
36+
* `async` methods are no longer `async`: each returns the moved function's own
37+
* promise. `maxAutonumberCounter` reads no member, so its method calls the
38+
* function directly.
39+
*
40+
* Methods go as closures that call them on the driver at call time, so a
41+
* subclass override is still the one a body reaches: `fillAutoNumberFields`
42+
* reaches `TursoDriver`'s `getNextSequenceValue`, and
43+
* `collidingAutoNumberReservations` and `issueAutonumbers` reach its
44+
* `autoNumberValueExists` and `resyncSequenceToDataMax`, as they did when
45+
* they called `this.…`. A test spy on the instance is reached the same way. The fields `autoNumberFields`,
46+
* `issuedAutoNumbers`, `knex`, `physicalTableByObject` and
47+
* `sequencesHasKeyHash` go as GETTERS, so each read happens when the body
48+
* makes it, as it did on the class.
49+
*
50+
* The one module-level declaration the bodies read that is not imported from
51+
* elsewhere stays in `sql-driver.ts`: `SEQUENCES_TABLE`. It gained `export`
52+
* there and is imported here, because `ensureSequencesTable`,
53+
* `ensureSequencesKeyHashShape` and the `sequencesTableName` getter still read
54+
* it. The module cycle is evaluation-safe because the value import is read
55+
* only inside a function body, never while the two modules are first
56+
* evaluated. `index.ts` re-exports nothing from this module, so the published
57+
* surface does not move.
58+
*/
59+
60+
import type { DriverOptions } from '@objectstack/spec/data';
61+
import { missingFieldValues, readAutonumberCounter, renderAutonumber } from '@objectstack/spec/data';
62+
import { StorageNameMapping } from '@objectstack/spec/system';
63+
import { isUniqueViolationError, uniqueViolationColumn } from '@objectstack/types';
64+
import type { Knex } from 'knex';
65+
import { GLOBAL_TENANT } from './schema-drift.js';
66+
import type { AutoNumberReservation, SqlDriver } from './sql-driver.js';
67+
import { SEQUENCES_TABLE } from './sql-driver.js';
68+
69+
/**
70+
* The `SqlDriver` members the functions below read — every one of them, and
71+
* no other; each function's `this` is the `Pick` of the members IT reads. Each
72+
* is typed AS the class member (an indexed access on the class), so a change
73+
* to a member's signature on the class is a change here too, and naming a
74+
* member the class does not have is a compile error. See the module header
75+
* for which members are getters.
76+
*/
77+
export interface AutonumberHost {
78+
attemptWithoutPoisoning: SqlDriver['attemptWithoutPoisoning'];
79+
autoNumberCounterKey: SqlDriver['autoNumberCounterKey'];
80+
readonly autoNumberFields: SqlDriver['autoNumberFields'];
81+
autoNumberValueExists: SqlDriver['autoNumberValueExists'];
82+
collidingAutoNumberReservations: SqlDriver['collidingAutoNumberReservations'];
83+
ensureSequencesTable: SqlDriver['ensureSequencesTable'];
84+
fillAutoNumberFields: SqlDriver['fillAutoNumberFields'];
85+
getNextSequenceValue: SqlDriver['getNextSequenceValue'];
86+
injectTenantOnInsert: SqlDriver['injectTenantOnInsert'];
87+
readonly issuedAutoNumbers: SqlDriver['issuedAutoNumbers'];
88+
readonly knex: SqlDriver['knex'];
89+
readonly physicalTableByObject: SqlDriver['physicalTableByObject'];
90+
resolveSequenceTenantId: SqlDriver['resolveSequenceTenantId'];
91+
resyncSequenceToDataMax: SqlDriver['resyncSequenceToDataMax'];
92+
scanMaxNumericTail: SqlDriver['scanMaxNumericTail'];
93+
sequenceKeyHash: SqlDriver['sequenceKeyHash'];
94+
readonly sequencesHasKeyHash: SqlDriver['sequencesHasKeyHash'];
95+
}
96+
97+
/** The body of `SqlDriver#getNextSequenceValue`; the method's docblock there is its contract. */
98+
export async function getNextSequenceValue(this: Pick<AutonumberHost, 'attemptWithoutPoisoning' | 'ensureSequencesTable' | 'knex' | 'resolveSequenceTenantId' | 'scanMaxNumericTail' | 'sequenceKeyHash' | 'sequencesHasKeyHash'>, object: string, tableName: string, field: string, prefix: string, tenantField: string | null, tenantId: string | null, parentTrx?: Knex.Transaction, scope = '', suffix = ''): Promise<number> {
99+
// Pass the caller's transaction so a cold-cache first write inside a batch
100+
// transaction ensures the table on the right connection instead of dead-
101+
// locking on a second one (SQLite pool max=1). `initObjects` normally warms
102+
// this up front, making the call a no-op — this only bites the lazy path.
103+
// The bucket first: an organization-less row on a tenant table is refused
104+
// here (ADR-0131 D9), before the lazy DDL below or any counter read.
105+
const resolvedTenantId = this.resolveSequenceTenantId(tenantField, tenantId, tableName, field);
106+
await this.ensureSequencesTable(parentTrx);
107+
if (scope !== '' && !this.sequencesHasKeyHash) {
108+
// The legacy sequences table could not be migrated to the key_hash shape,
109+
// so it cannot represent per-scope counters. Fail with a clear, actionable
110+
// message instead of corrupting the single legacy counter.
111+
throw new Error(
112+
`Cannot generate a per-scope autonumber for "${object}.${field}": the ` +
113+
`${SEQUENCES_TABLE} table is still the legacy shape. ` +
114+
`Migrate it to the key_hash shape before using date/{field}/per-parent formats.`,
115+
);
116+
}
117+
// `scope` (rendered date/field prefix, boundary-delimited) gives each
118+
// period/group its own counter; '' keeps the single global counter for
119+
// fixed-prefix formats. `prefix` is the full rendered prefix used to
120+
// bootstrap from existing data. The row is keyed by a hash of the composite;
121+
// on an un-migrated legacy table only fixed-prefix (scope '') reaches here,
122+
// so fall back to the original `(object, tenant_id, field)` key for it.
123+
const key = this.sequencesHasKeyHash
124+
? { key_hash: this.sequenceKeyHash(tableName, resolvedTenantId, field, scope) }
125+
: { object: tableName, tenant_id: resolvedTenantId, field };
126+
const insertRow = this.sequencesHasKeyHash
127+
? { ...key, object: tableName, tenant_id: resolvedTenantId, field, scope }
128+
: { ...key };
129+
130+
const runner: Knex | Knex.Transaction = parentTrx ?? this.knex;
131+
132+
return runner.transaction(async (trx) => {
133+
// Lock the row (no-op on SQLite, real lock on Postgres/MySQL).
134+
//
135+
// Speculative, so it runs under a savepoint: `.forUpdate()` on a MISSING
136+
// row does NOT throw on Postgres (measured: returns zero rows), so the
137+
// fallback below is unreachable for the reason the old comment gave. It
138+
// IS reachable for lock-level failures — deadlock (40P01), lock/statement
139+
// timeout (55P03/57014) — and without the savepoint each of those turned
140+
// into a `25P02` from the fallback SELECT, masking the real error.
141+
let existing: any;
142+
const locked = await this.attemptWithoutPoisoning(trx, (scoped) =>
143+
scoped(SEQUENCES_TABLE).where(key).forUpdate().first(),
144+
);
145+
if (locked.ok) {
146+
existing = locked.value;
147+
} else {
148+
// Fall back to a plain SELECT then rely on transaction isolation.
149+
existing = await trx(SEQUENCES_TABLE).where(key).first();
150+
}
151+
152+
if (!existing) {
153+
const seedMax = await this.scanMaxNumericTail(
154+
trx,
155+
tableName,
156+
field,
157+
prefix,
158+
tenantField,
159+
resolvedTenantId === GLOBAL_TENANT ? null : resolvedTenantId,
160+
suffix,
161+
);
162+
const initial = seedMax + 1;
163+
const inserted = await this.attemptWithoutPoisoning(trx, (scoped) =>
164+
scoped(SEQUENCES_TABLE).insert({ ...insertRow, last_value: initial }),
165+
);
166+
if (inserted.ok) return initial;
167+
// Another writer raced us to the first INSERT. Fall through to
168+
// the UPDATE path with the now-present row. This `SELECT … FOR UPDATE`
169+
// blocks until the winner commits, so it sees the committed counter.
170+
existing = await trx(SEQUENCES_TABLE).where(key).forUpdate().first();
171+
if (!existing) throw inserted.error;
172+
}
173+
174+
const next = Number(existing.last_value) + 1;
175+
await trx(SEQUENCES_TABLE).where(key).update({ last_value: next, updated_at: this.knex.fn.now() });
176+
return next;
177+
});
178+
}
179+
180+
/** The body of `SqlDriver#fillAutoNumberFields`; the method's docblock there is its contract. */
181+
export async function fillAutoNumberFields(this: Pick<AutonumberHost, 'autoNumberFields' | 'getNextSequenceValue' | 'physicalTableByObject'>, object: string, row: Record<string, any>, options?: DriverOptions): Promise<AutoNumberReservation[]> {
182+
// Scan/seed the physical (remote) table for an external object; managed
183+
// objects fall through to the storage-mapped name. Config lookup stays
184+
// keyed by object name (matching initObjects/registerExternalObject).
185+
const tableName = this.physicalTableByObject[object] ?? StorageNameMapping.resolveTableName({ name: object } as any);
186+
const cfgs = this.autoNumberFields[object] || this.autoNumberFields[tableName];
187+
if (!cfgs || cfgs.length === 0) return [];
188+
const reservations: AutoNumberReservation[] = [];
189+
const parentTrx = options?.transaction as Knex.Transaction | undefined;
190+
const timezone = options?.timezone;
191+
const now = new Date();
192+
for (const cfg of cfgs) {
193+
if (row[cfg.name] !== undefined && row[cfg.name] !== null && row[cfg.name] !== '') continue;
194+
// A `{field}` token with no value would render to an empty prefix and
195+
// silently merge this record into the wrong counter scope, so refuse to
196+
// generate rather than emit a wrong record number (the referenced field
197+
// must be populated before the autonumber — see field.zod docs).
198+
const missing = missingFieldValues(cfg.tokens, row);
199+
if (missing.length > 0) {
200+
throw new Error(
201+
`Cannot generate autonumber "${object}.${cfg.name}" (format "${cfg.format}"): ` +
202+
`referenced field(s) [${missing.join(', ')}] are empty on the record. ` +
203+
`Fields interpolated into an autonumber format must be set before the record is created.`,
204+
);
205+
}
206+
// Resolve tenant for this row: explicit field on the record wins,
207+
// then driver options, else null → global sequence.
208+
const rowTenant = cfg.tenantField ? row[cfg.tenantField] : undefined;
209+
const optTenant = options?.tenantId;
210+
const tenantId = rowTenant != null && rowTenant !== ''
211+
? String(rowTenant)
212+
: optTenant != null && optTenant !== ''
213+
? String(optTenant)
214+
: null;
215+
// Resolve the scope/prefix for this row (counter-value-independent),
216+
// reserve the next value under that scope, then render the final string.
217+
const probe = renderAutonumber({ tokens: cfg.tokens, seq: 0, record: row, now, timezone });
218+
const next = await this.getNextSequenceValue(
219+
object,
220+
tableName,
221+
cfg.name,
222+
probe.prefix,
223+
cfg.tenantField,
224+
tenantId,
225+
parentTrx,
226+
probe.scope,
227+
probe.suffix,
228+
);
229+
const value = renderAutonumber({ tokens: cfg.tokens, seq: next, record: row, now, timezone }).value;
230+
row[cfg.name] = value;
231+
reservations.push({
232+
field: cfg.name,
233+
tableName,
234+
prefix: probe.prefix,
235+
scope: probe.scope,
236+
suffix: probe.suffix,
237+
tenantField: cfg.tenantField ?? null,
238+
tenantId,
239+
value,
240+
});
241+
}
242+
return reservations;
243+
}
244+
245+
/** The body of `SqlDriver#issueAutonumbers`; the method's docblock there is its contract. */
246+
export async function issueAutonumbers(this: Pick<AutonumberHost, 'autoNumberCounterKey' | 'collidingAutoNumberReservations' | 'fillAutoNumberFields' | 'injectTenantOnInsert' | 'issuedAutoNumbers' | 'resyncSequenceToDataMax'>, object: string, rows: Record<string, unknown>[], options?: DriverOptions, afterCollision?: unknown): Promise<string[][]> {
247+
if (afterCollision === undefined) {
248+
const filled: string[][] = [];
249+
for (const row of rows) {
250+
if (!row || typeof row !== 'object') {
251+
filled.push([]);
252+
continue;
253+
}
254+
// Filled as `create()` fills it: the caller's organization stamped
255+
// first (numbers are issued per organization), on a view, so only
256+
// the numbers land on the caller's row.
257+
const view: Record<string, any> = { ...row };
258+
this.injectTenantOnInsert(object, view, options);
259+
const reserved = await this.fillAutoNumberFields(object, view, options);
260+
for (const r of reserved) row[r.field] = view[r.field];
261+
// A value kept from an earlier issue on this row is still this
262+
// driver's, so it stays described beside the fresh ones (#6943).
263+
const fresh = new Set(reserved.map((r) => r.field));
264+
const kept = (this.issuedAutoNumbers.get(row) ?? []).filter((r) => !fresh.has(r.field));
265+
this.issuedAutoNumbers.set(row, [...kept, ...reserved]);
266+
filled.push(reserved.map((r) => r.field));
267+
}
268+
return filled;
269+
}
270+
271+
const none = rows.map((): string[] => []);
272+
if (options?.transaction !== undefined) return none;
273+
const issued = rows.map((row) => (row && typeof row === 'object' ? this.issuedAutoNumbers.get(row) ?? [] : []));
274+
const colliding = await this.collidingAutoNumberReservations(afterCollision, issued.flat(), options);
275+
if (colliding.length === 0) return none;
276+
277+
const stale = new Set<string>();
278+
for (const reservation of colliding) {
279+
const key = this.autoNumberCounterKey(reservation);
280+
if (stale.has(key)) continue;
281+
stale.add(key);
282+
await this.resyncSequenceToDataMax(reservation);
283+
}
284+
return rows.map((row, i) => {
285+
const emptied: string[] = [];
286+
const kept: AutoNumberReservation[] = [];
287+
for (const reservation of issued[i]) {
288+
if (stale.has(this.autoNumberCounterKey(reservation))) {
289+
delete row[reservation.field];
290+
emptied.push(reservation.field);
291+
} else {
292+
kept.push(reservation);
293+
}
294+
}
295+
if (emptied.length > 0) this.issuedAutoNumbers.set(row, kept);
296+
return emptied;
297+
});
298+
}
299+
300+
/** The body of `SqlDriver#maxAutonumberCounter`; the method's docblock there is its contract. */
301+
export function maxAutonumberCounter(values: Iterable<unknown>, prefix: string, suffix: string): number {
302+
let maxN = 0;
303+
const anchored = prefix !== '' || suffix !== '';
304+
for (const v of values) {
305+
if (typeof v !== 'string') continue;
306+
let n: number;
307+
if (anchored) {
308+
// Spec's inverse of `renderAutonumber` (#6560). It also re-checks the
309+
// prefix in JS: a driver-side `LIKE` can match looser than `startsWith`
310+
// (collation, case-insensitive columns), and a row from another scope
311+
// must not inflate this counter — it reads as `undefined`, same as a
312+
// row carrying no counter at all.
313+
const read = readAutonumberCounter(v, prefix, suffix);
314+
if (read === undefined) continue;
315+
n = read;
316+
} else {
317+
// Unanchored: `prefix` is '' here, so this is the whole value.
318+
n = parseInt(v.replace(/[^0-9]/g, ''), 10);
319+
}
320+
if (Number.isFinite(n) && n > maxN) maxN = n;
321+
}
322+
return maxN;
323+
}
324+
325+
/** The body of `SqlDriver#collidingAutoNumberReservations`; the method's docblock there is its contract. */
326+
export async function collidingAutoNumberReservations(this: Pick<AutonumberHost, 'autoNumberValueExists' | 'knex'>, error: unknown, reservations: AutoNumberReservation[], options?: DriverOptions): Promise<AutoNumberReservation[]> {
327+
if (reservations.length === 0 || !isUniqueViolationError(error)) return [];
328+
329+
const column = uniqueViolationColumn(error);
330+
if (column !== undefined) return reservations.filter((r) => r.field === column);
331+
332+
const runner: Knex | Knex.Transaction = (options?.transaction as Knex.Transaction | undefined) ?? this.knex;
333+
const colliding: AutoNumberReservation[] = [];
334+
for (const reservation of reservations) {
335+
if (await this.autoNumberValueExists(runner, reservation)) colliding.push(reservation);
336+
}
337+
return colliding;
338+
}
339+
340+
/** The body of `SqlDriver#resyncSequenceToDataMax`; the method's docblock there is its contract. */
341+
export async function resyncSequenceToDataMax(this: Pick<AutonumberHost, 'ensureSequencesTable' | 'knex' | 'resolveSequenceTenantId' | 'scanMaxNumericTail' | 'sequenceKeyHash' | 'sequencesHasKeyHash'>, reservation: AutoNumberReservation): Promise<void> {
342+
await this.ensureSequencesTable();
343+
const resolvedTenantId = this.resolveSequenceTenantId(
344+
reservation.tenantField,
345+
reservation.tenantId,
346+
reservation.tableName,
347+
reservation.field,
348+
);
349+
const key = this.sequencesHasKeyHash
350+
? { key_hash: this.sequenceKeyHash(reservation.tableName, resolvedTenantId, reservation.field, reservation.scope) }
351+
: { object: reservation.tableName, tenant_id: resolvedTenantId, field: reservation.field };
352+
353+
await this.knex.transaction(async (trx) => {
354+
const observedMax = await this.scanMaxNumericTail(
355+
trx,
356+
reservation.tableName,
357+
reservation.field,
358+
reservation.prefix,
359+
reservation.tenantField,
360+
resolvedTenantId === GLOBAL_TENANT ? null : resolvedTenantId,
361+
reservation.suffix,
362+
);
363+
const existing = await trx(SEQUENCES_TABLE).where(key).first();
364+
if (!existing || Number(existing.last_value) >= observedMax) return;
365+
await trx(SEQUENCES_TABLE).where(key).update({ last_value: observedMax, updated_at: this.knex.fn.now() });
366+
});
367+
}

0 commit comments

Comments
 (0)