|
| 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