Skip to content

Commit 9e6df40

Browse files
fix(objectql): a cleared optional unique text field stores null, so the second record cleared is no longer refused 409 UNIQUE_VIOLATION (#29176) (#29271)
<!-- claude-projects-attribution: {"github_login":"os-steve"} --> _Requested by **Steve** · [project thread](https://claude.ai/code/project/chan_01FdL1XeUyvVNxLreh3F4Qi9?thread=cmsg_01FdL1XeUyvVNxLreh3F4Qi92VQfXZ8RGvh3U16jJnRjhT)_ Fixes #29176 Clause-②: no Metadata-protocol: none ## 维护者速读 - **改了什么**:可选的唯一文本字段(SKU、税号、工号这类)被清空时,服务端写入口把 `''` 存成 `null`。第二条清空的记录不再被 `409 UNIQUE_VIOLATION` 拒绝;REST、批量、导入都走这同一个入口。 - **为什么改**:唯一索引把 `''` 当成一个真实值,而 `null` 互不冲突。用户清空第二条记录就保存不了,只能填假值污染数据。按分诊裁决修在服务端写路径(`packages/objectql`),不改表单。 - **风险与回滚**:只动「可选 + 有唯一约束 + 文本类」字段上恰好为 `''` 的值;必填字段照旧拒绝,真重复照旧 409,`password`/`secret` 的空串拒绝不变,非唯一字段仍存 `''`。已存的 `''` 不迁移。回滚 = revert 本 PR。 - **先看**:`packages/objectql/src/validation/record-validator.ts` 的 `optionalUniqueTextColumns` 与 `normalizeBlankTypedRow` 改动的那一行;`packages/rest/src/rest-data-optional-unique-blank.test.ts`;`.changeset/29176-optional-unique-blank-null.md`。 - **两分钟验证**:`pnpm --filter @objectstack/rest exec vitest run src/rest-data-optional-unique-blank.test.ts`,预期 8 个测试全绿(主干上同一文件 6 红:第二次清空是 409)。 - **需要你做的**:无,席位落地。 ## What changes - **The seam.** `normalizeBlankTypedValues` (`packages/objectql/src/validation/record-validator.ts`) is the engine's existing blank write door: `ObjectQL.insert()` / `update()` and the dry run `validate()` apply it to the caller's payload before the middleware, the caller snapshots, the defaults, the hooks and validation read it (#20308 put it there for non-string-typed columns). Every REST, batch, upsert and import door reaches the engine through those methods. `engine.ts` is not touched. - **The new arm.** Exactly `''` becomes `null` on a column that is all of: - text-like: the spec's `STRING_VALUE_TYPES`, read as the constant, minus `password` and `secret`; - not `required: true`; - covered by a unique constraint, on either surface the drivers build one from: the field's own `unique`, or membership in a declared `indexes[]` entry carrying `unique`. Both are read through the spec's `isUniqueDeclared`, the predicate the drivers use. - Lifecycle columns the engine owns (`id`, `created_at`, …) are never rewritten. - **Edges, each deliberate.** - Whitespace stays a value. The `$empty` operator's ruled table reads `''` and `null` as one answer on a text-like column and whitespace as a value, so this rewrite changes no `$empty` / `is_empty` answer. - `required` columns are excluded, so a required unique field's `''` is refused `required` exactly as today. Without the exclusion, a required field with a `defaultValue` would take the default instead of being refused. - `password` / `secret` are excluded: a maintainer ruling refuses `''` on them while `null` means clear, and rewriting would turn that refusal into a silent clear. - `select` / `radio` / `lookup` / `user` are excluded: the same `$empty` table reads their `''` as a value. See Acceptance notes. - **Defaults.** An optional unique field with a `defaultValue` takes it on insert when sent `''`, exactly as when sent `null` (the typed arm already behaves this way). - `FieldDef` in the validator gains `unique?: unknown`; the function's parameter type gains `indexes?: unknown`. Both widen only. ## Why Triage 6573215352 ruled the layer: "the fix lands on the server write path in packages/objectql: normalise an empty string to null for an optional field before the unique index sees it, which also covers REST and import callers." The scope is the fields a unique constraint covers. A non-unique optional text field keeps storing `''`: the validator's docblock, the `str_empty` round-trip case and two existing pins (`engine-blank-typed-value-door.test.ts`, `rest-data-blank-typed-value.test.ts`) depend on that, and none of them needed an edit. ## Tests No existing test was edited. Three new files: - `packages/objectql/src/validation/record-validator.optional-unique-blank.test.ts` (9 tests): the population pinned to the spec set (12 types), all three unique scopes, the declared-index surface (a plain index member keeps `''`), the controls (no unique, `unique: false`, required, credentials, other string-stored types, a lifecycle column), whitespace and non-blank pass-through, purity. - `packages/objectql/src/engine-optional-unique-blank-door.test.ts` (8 tests): what the driver receives on insert, insert array, `insertMany`, update by id, update by predicate; whitespace and non-blank untouched; the `defaultValue` interaction; `required` unchanged on insert, update and the dry run, including the required-with-default case; `''` on a unique `password` still refused (`EmptyCredentialWriteError`, `VALIDATION_ERROR` / 400). - `packages/rest/src/rest-data-optional-unique-blank.test.ts` (8 tests), real `ObjectQL` + SQLite `SqlDriver` + `RestServer` routes, physical column read past the engine: POST `''` twice, PATCH clear twice, a declared composite unique index member, batch create and `createMany`, a non-unique control keeping `''`, a real duplicate still `409 UNIQUE_VIOLATION` (by POST and by PATCH), a required unique field `400 VALIDATION_FAILED` / `required` with and without a `defaultValue`, and a legacy stored `''` row. <details><summary>Red on main, green on head</summary> `record-validator.ts` restored to `dedc3505` in the tree only, objectql rebuilt (`optionalUniqueTextColumns` absent from all 14 built files), then restored to HEAD (blob `b450ff13` equal to HEAD, `git diff HEAD` empty) and rebuilt. | Reading | objectql (2 new files) | rest (new file) | |---|---|---| | Base `dedc3505` | `Tests 9 failed, 8 passed (17)` | `Tests 6 failed, 2 passed (8)`: POST `[201, 409]`, PATCH `[200, 409]`, declared index `[201, 409]`, batch `[true, false]` | | Head | `Tests 17 passed (17)` | `Tests 8 passed (8)` | The controls that pass on base are the ones that must: required refusals, the credential refusal, the non-unique `''`. </details> <details><summary>Ablations of the three negative pins</summary> Each mutation was made with `scripts/ablation-replace.mjs` (anchor hit 1 → 0, blob changed), objectql rebuilt, and the marker counted in dist by `scripts/ablation-dist-preflight.mjs` (present in 4 built files) before the run. Each was restored to the HEAD blob with `git diff HEAD` empty. A final rebuild shows all three markers absent and the tree clean. | Ablation | Red | |---|---| | A1: the door also rewrites a non-blank value on a covered column | rest `a real duplicate is still refused`: `expected 201 to be 409`; objectql `whitespace and every non-blank value pass through untouched` | | A2: the `required` exclusion removed | objectql `… with a defaultValue refuses "" — it is NOT defaulted` and the unit `required` control; rest `a required unique field refuses ""`: `expected 201 to be 400` | | A3: the credential exclusion removed | objectql `the credential ruling is unchanged`: `expected undefined to be an instance of EmptyCredentialWriteError`, and the unit credentials control | </details> ## Acceptance notes - **Driver families, measured on `dedc3505`** (two rows in a unique text column, through each driver's own `create`): driver-sql on SQLite: two `''` → second refused, two `null` → both land. driver-memory: the same. sqlite-wasm and turso local share `SqlDriver`'s compiler and DDL path, so they were not measured separately. The engine now hands every driver `null`; driver-memory already pins NULL-distinct in `memory-unique-constraint.test.ts`. - **MongoDB, NOT MEASURED** (the `mongod` download for `mongodb-memory-server` is refused with 403 here). By reading: `mongodb-schema.ts` builds field uniqueness as `{ unique: true, sparse: true }`. A sparse index skips a document only when the field is absent, and still indexes an explicit `null`. If that holds, two cleared rows still collide on that driver, because the engine now sends `null`. That would be a driver divergence from the NULL-distinct rule the other drivers keep, and it is outside this card's ruled layer. Reported to the seat. - **Not covered, by scope.** A unique single-value `select` / `lookup` that is cleared also sends `''` (the card's own reading on `showcase_field_zoo`) and still collides on the second record. The `$empty` table reads `''` as a value on those types, so rewriting it is a separate decision. Reported to the seat. - **Stored rows.** Existing `''` values are not migrated (pinned): they keep matching `field = ''`; a newly cleared row matches `$null: true`; `$empty: true` matches both; a new clear no longer collides with a stored `''`. ## Verification Head after `git merge origin/main`: see the PR's check-runs. Local readings: <details><summary>Suites, typecheck, gates, lint</summary> | Run | Head | Result | |---|---|---| | `pnpm --filter @objectstack/objectql test` | `9ef4c2cf` | Test Files 529 passed (529) · Tests 10155 passed (10155) | | `pnpm --filter @objectstack/objectql typecheck` | `9ef4c2cf` | exit 0; `check:test-typecheck` held (new files carry no debt) | | `pnpm --filter @objectstack/rest test` | `9ef4c2cf` | Test Files 368 passed (368) · Tests 6971 passed, 332 skipped (7303) | | `pnpm --filter @objectstack/rest typecheck` | `9ef4c2cf` | exit 0; 0 test-typecheck debt | | `git merge origin/main` (`49aba82b`), then `pnpm install --frozen-lockfile`, rebuild of the rest closure, `spec check:generated` | `8c537232` | all exit 0; every generated artifact up to date. The incoming commits touch neither objectql nor rest, so the scoped re-check is the three new files: 17/17 and 8/8 | | the one later commit (test helpers renamed, see below) | `28fb6173` | the edited file 8/8 | | `dispatch-gates.mjs --commands` (61 families), each run | `28fb6173` | 61 × exit 0; `--ran`: 61 derived, 61 run, 0 NOT-MEASURED, 0 UNRUN | | `pnpm lint` | `28fb6173` | exit 0 | | `check:driver-conformance` before (`49aba82b`) and after | `28fb6173` | 66 covered, 0 DEBT, both | The first gate round (`8c537232`) had one real red: `check:where-matcher` discovered the two expectation helpers in `engine-optional-unique-blank-door.test.ts` as WHERE matchers it could not judge, because they iterated the keys of a payload object. They now iterate a list of names, as the sibling blank-door test does (`28fb6173`). In the same round, two families exited 3 (prerequisite not met, nothing measured): `check-plugin-teardown-shape --self-test` needed its pinned fixture commit fetched, and `check:dual-build-cjs-loads` needed every package built. Both were fixed before round two. Not run locally: the full dogfood battery. The title carries no `!` and `Clause-②` has no `(narrowing)` arm, so it is not owed. </details> ## Human Minimum - [x] 1. Schemas start as Zod; `packages/spec` holds no runtime logic. (not touched) - [x] 2. Every name I added uses the casing for its kind. - [x] 3. No formatter ran; `pnpm lint` passes. - [x] 4. One issue, one branch off an up-to-date `main`, one pull request. - [x] 5. A change that publishes carries a changeset, and both declaration lines are filled in here and in the changeset. - [x] 6. `packages/spec` touched: n/a. - [x] 7. No hand edits to `content/docs/references/`, `packages/*/CHANGELOG.md` or `content/docs/releases/`. - [x] 8. Title, body and comments are in English (the maintainer brief above is Chinese by repo rule). --- _Generated by [Claude Code](https://claude.ai/code/session_01ADHkmPtnUk1SkRHh5gtX6u)_ --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent 6dd6a53 commit 9e6df40

5 files changed

Lines changed: 680 additions & 12 deletions

File tree

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
---
2+
'@objectstack/objectql': patch
3+
---
4+
5+
fix(objectql): a cleared optional unique text field stores `null`, so a second record cleared is no longer refused `409 UNIQUE_VIOLATION`
6+
7+
Clause-②: no
8+
Metadata-protocol: none
9+
10+
A cleared text input is sent as `''`, and the write path stored it as sent. Every unique constraint the drivers build is NULL-distinct, so `null` never collides, but `''` is a value: the first record whose SKU (tax id, employee number, …) was cleared saved, and the second was refused "A record with this value already exists" although neither held a value. Measured on SQLite and the memory driver: two `''` rows collide, two `null` rows do not.
11+
12+
- **Now.** The engine's write door, which `insert`, `insertMany`, `update` (by id and by predicate) and the dry run (`validate`) apply before anything else reads the payload, stores exactly `''` as `null` on a column that is text-like (`text`, `textarea`, `email`, `url`, `phone`, `markdown`, `html`, `richtext`, `code`, `color`, `signature`, `qrcode`), not `required`, and covered by a unique constraint: the field's own `unique`, or membership in a declared `indexes[]` entry carrying `unique`. Every REST, batch, upsert and import door reaches the engine through those methods.
13+
- **Unchanged.** A `required` field given `''` is refused `required` exactly as before, also when it declares a `defaultValue`. A real duplicate is still `409 UNIQUE_VIOLATION`. Whitespace is a value and is stored as sent. `password` and `secret` keep their `''` refusal. A column no unique constraint covers, and `select` / `lookup` columns, keep storing `''`.
14+
- **Defaults.** An optional unique field that declares a `defaultValue` now takes it on insert when sent `''`, exactly as when sent `null`.
15+
- **Rows already stored.** Existing `''` values are not migrated. They keep matching a `field = ''` filter; a newly cleared row matches `$null: true` instead. The `is_empty` filter (`$empty`) matches both, as before. A newly cleared row no longer collides with a stored `''`.
Lines changed: 259 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,259 @@
1+
// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
2+
3+
/**
4+
* #29176 — an empty string on an OPTIONAL text-like column that a unique
5+
* constraint covers reaches the driver as `null`, on every engine write door.
6+
*
7+
* ## The defect
8+
*
9+
* A cleared text input is sent as `''`, and the write path stored it verbatim.
10+
* Every unique constraint the drivers build is NULL-distinct (driver-sql's
11+
* `(organization_id, field)` index, the memory driver's key model), so `null`
12+
* never collides — but `''` is a value, and the second record cleared, or
13+
* created with `''`, was refused `409 UNIQUE_VIOLATION` although neither
14+
* record holds a value.
15+
*
16+
* ## What this file pins
17+
*
18+
* What the DRIVER receives, door by door (the physical column on SQLite, and
19+
* the 409 that no longer fires, are `packages/rest/src/rest-data-optional-unique-blank.test.ts`):
20+
*
21+
* - the rewrite, on both unique surfaces: a field's own `unique`, and a member
22+
* of a declared `indexes[]` entry carrying `unique`;
23+
* - its edges, each a control: a column no unique constraint covers keeps
24+
* `''` (the spec's `str_empty` side of the line); whitespace is a value, as
25+
* the `$empty` operator's ruled table reads it; `select` / `lookup` keep
26+
* `''` (not text-like); a non-blank value is untouched;
27+
* - `required` is unchanged: a required unique field's `''` is refused
28+
* `required` exactly as before — including when the field declares a
29+
* `defaultValue`, which a blank rewritten to `null` would have taken;
30+
* - the credential ruling is unchanged: `''` on a `password` field is still
31+
* refused, never rewritten into a clear.
32+
*/
33+
34+
import { describe, it, expect, beforeEach } from 'vitest';
35+
import { ObjectQL } from './engine.js';
36+
import { ValidationError } from './validation/record-validator.js';
37+
import { EmptyCredentialWriteError, EMPTY_CREDENTIAL_REFUSAL_CODE, EMPTY_CREDENTIAL_REFUSAL_STATUS } from './secret-fields.js';
38+
39+
interface Call { fn: string; data: Record<string, unknown> }
40+
41+
function makeStubDriver() {
42+
const calls: Call[] = [];
43+
const rows = new Map<string, Record<string, unknown>>();
44+
const idOf = (q: any): string | undefined => {
45+
const w = q?.where ?? q?.filter ?? q;
46+
const id = w?.id;
47+
return typeof id === 'string' ? id : undefined;
48+
};
49+
let n = 0;
50+
const driver: any = {
51+
name: 'stub', version: '0.0.0', supports: {},
52+
async connect() {}, async disconnect() {}, async checkHealth() { return true; }, async execute() { return null; },
53+
// Not a query-honouring `find`: nothing here reads rows back through it
54+
// (the by-id prior read is `findOne`), so it answers the whole store.
55+
async find() { return [...rows.values()]; },
56+
async findOne(_o: string, q: any) {
57+
const id = idOf(q);
58+
return (id ? rows.get(id) : rows.values().next().value) ?? null;
59+
},
60+
async count() { return rows.size; },
61+
async create(_o: string, data: Record<string, unknown>) {
62+
calls.push({ fn: 'create', data: { ...data } });
63+
const row = { ...data, id: (data.id as string) ?? `r${++n}` };
64+
rows.set(row.id as string, row);
65+
return row;
66+
},
67+
async bulkCreate(_o: string, list: Record<string, unknown>[]) {
68+
calls.push({ fn: 'bulkCreate', data: { rows: list.map((r) => ({ ...r })) } });
69+
const out: Record<string, unknown>[] = [];
70+
for (const r of list) {
71+
const row = { ...r, id: (r.id as string) ?? `r${++n}` };
72+
rows.set(row.id as string, row);
73+
out.push(row);
74+
}
75+
return out;
76+
},
77+
async update(_o: string, id: string, data: Record<string, unknown>) {
78+
calls.push({ fn: 'update', data: { ...data } });
79+
const row = { ...(rows.get(id) ?? {}), ...data, id };
80+
rows.set(id, row);
81+
return row;
82+
},
83+
async updateMany(_o: string, _ast: unknown, data: Record<string, unknown>) {
84+
calls.push({ fn: 'updateMany', data: { ...data } });
85+
return rows.size;
86+
},
87+
async upsert(o: string, data: Record<string, unknown>) { return this.create(o, data); },
88+
async delete() { return true; },
89+
async bulkUpdate() { return []; }, async bulkDelete() {},
90+
async beginTransaction() { return { commit: async () => {}, rollback: async () => {} }; },
91+
async commit() {}, async rollback() {},
92+
};
93+
return { driver, calls, rows };
94+
}
95+
96+
const OBJ = {
97+
name: 'uniq_blank',
98+
label: 'Unique blank',
99+
fields: {
100+
id: { name: 'id', type: 'text' as const, primaryKey: true },
101+
sku: { name: 'sku', type: 'text' as const, unique: true },
102+
tax_id: { name: 'tax_id', type: 'text' as const, unique: 'global' as const },
103+
email: { name: 'email', type: 'email' as const, unique: 'organization' as const },
104+
grp: { name: 'grp', type: 'text' as const },
105+
code: { name: 'code', type: 'text' as const },
106+
note: { name: 'note', type: 'text' as const },
107+
plain_idx: { name: 'plain_idx', type: 'text' as const },
108+
off: { name: 'off', type: 'text' as const, unique: false },
109+
pick: { name: 'pick', type: 'select' as const, unique: true, options: [{ value: 'a', label: 'A' }] },
110+
ref: { name: 'ref', type: 'lookup' as const, unique: true, reference: 'uniq_blank' },
111+
},
112+
indexes: [
113+
{ name: 'idx_uniq_blank_grp_code', fields: ['grp', 'code'], unique: 'global' as const },
114+
{ name: 'idx_uniq_blank_plain', fields: ['plain_idx'] },
115+
],
116+
};
117+
118+
const REQ = {
119+
name: 'uniq_blank_req',
120+
label: 'Unique blank required',
121+
fields: {
122+
id: { name: 'id', type: 'text' as const, primaryKey: true },
123+
sku: { name: 'sku', type: 'text' as const, unique: true, required: true },
124+
skud: { name: 'skud', type: 'text' as const, unique: true, required: true, defaultValue: 'D-1' },
125+
opt_d: { name: 'opt_d', type: 'text' as const, unique: true, defaultValue: 'O-1' },
126+
},
127+
};
128+
129+
const CRED = {
130+
name: 'uniq_blank_cred',
131+
label: 'Unique blank credential',
132+
fields: {
133+
id: { name: 'id', type: 'text' as const, primaryKey: true },
134+
pin: { name: 'pin', type: 'password' as const, unique: true },
135+
},
136+
};
137+
138+
/** The covered columns of {@link OBJ}: both unique surfaces, three scopes. */
139+
const COVERED_NAMES = ['sku', 'tax_id', 'email', 'code'];
140+
/** The columns that keep their `''`: no unique constraint, or not text-like. */
141+
const KEPT_NAMES = ['note', 'plain_idx', 'off', 'pick', 'ref'];
142+
const blanksOf = (names: readonly string[]) => Object.fromEntries(names.map((n) => [n, '']));
143+
const COVERED = blanksOf(COVERED_NAMES);
144+
const KEPT = blanksOf(KEPT_NAMES);
145+
146+
function expectCoveredNull(data: Record<string, unknown>) {
147+
for (const k of COVERED_NAMES) expect(data[k], k).toBeNull();
148+
}
149+
function expectKeptBlank(data: Record<string, unknown>) {
150+
for (const k of KEPT_NAMES) expect(data[k], k).toBe('');
151+
}
152+
153+
async function refusal(fn: () => Promise<unknown>) {
154+
try { await fn(); return null; } catch (e) {
155+
return {
156+
name: (e as Error).name,
157+
code: (e as { code?: unknown }).code,
158+
fields: e instanceof ValidationError ? e.fields.map((x) => [x.field, x.code]) : undefined,
159+
};
160+
}
161+
}
162+
163+
describe('engine write doors: an optional unique text-like column stores "" as null (#29176)', () => {
164+
let engine: ObjectQL;
165+
let stub: ReturnType<typeof makeStubDriver>;
166+
167+
beforeEach(async () => {
168+
stub = makeStubDriver();
169+
engine = new ObjectQL();
170+
engine.registerDriver(stub.driver, true);
171+
await engine.init();
172+
engine.registry.registerObject(OBJ as any);
173+
engine.registry.registerObject(REQ as any);
174+
engine.registry.registerObject(CRED as any);
175+
});
176+
177+
const last = (fn: string) => [...stub.calls].reverse().find((c) => c.fn === fn)!.data;
178+
const written = () => stub.calls
179+
.filter((c) => c.fn === 'create' || c.fn === 'bulkCreate')
180+
.flatMap((c) => (c.fn === 'bulkCreate' ? (c.data.rows as Record<string, unknown>[]) : [c.data]));
181+
182+
it('insert, one row: every covered column is null; the controls keep ""', async () => {
183+
const payload: Record<string, unknown> = { id: 'a', grp: 'g1', ...COVERED, ...KEPT };
184+
await engine.insert('uniq_blank', payload);
185+
const sent = last('create');
186+
expectCoveredNull(sent);
187+
expectKeptBlank(sent);
188+
// The caller's own object is never rewritten.
189+
expect(payload.sku).toBe('');
190+
});
191+
192+
it('insert, an array of rows and insertMany: every row', async () => {
193+
await engine.insert('uniq_blank', [{ id: 'b1', ...COVERED }, { id: 'b2', ...COVERED }]);
194+
const rows = written();
195+
expect(rows.map((r) => r.id)).toEqual(['b1', 'b2']);
196+
for (const r of rows) expectCoveredNull(r);
197+
198+
stub.calls.length = 0;
199+
const outcomes = await engine.insertMany('uniq_blank', [{ id: 'm1', ...COVERED }]);
200+
expect(outcomes.map((o) => o.ok)).toEqual([true]);
201+
const many = written();
202+
expect(many).toHaveLength(1);
203+
expectCoveredNull(many[0]!);
204+
});
205+
206+
it('update by id and update by predicate', async () => {
207+
await engine.insert('uniq_blank', { id: 'u1', sku: 'S1', tax_id: 'T1', email: 'a@b.co', grp: 'g', code: 'C1' });
208+
await engine.update('uniq_blank', { id: 'u1', ...COVERED, ...KEPT });
209+
const byId = last('update');
210+
expectCoveredNull(byId);
211+
expectKeptBlank(byId);
212+
213+
await engine.update('uniq_blank', { ...COVERED }, { where: { id: { $in: ['u1'] } }, multi: true } as any);
214+
expectCoveredNull(last('updateMany'));
215+
});
216+
217+
it('whitespace and every non-blank value pass through untouched', async () => {
218+
await engine.insert('uniq_blank', { id: 'w1', sku: ' ', tax_id: ' x ', email: 'a@b.co', code: '0' });
219+
const sent = last('create');
220+
expect([sent.sku, sent.tax_id, sent.email, sent.code]).toEqual([' ', ' x ', 'a@b.co', '0']);
221+
});
222+
223+
it('an optional covered field with a defaultValue: a blank takes it on insert, exactly as null does', async () => {
224+
await engine.insert('uniq_blank_req', { id: 'd1', sku: 'S1', skud: 'K1', opt_d: '' });
225+
const blank = last('create');
226+
await engine.insert('uniq_blank_req', { id: 'd2', sku: 'S2', skud: 'K2', opt_d: null });
227+
const nul = last('create');
228+
expect([blank.opt_d, nul.opt_d]).toEqual(['O-1', 'O-1']);
229+
});
230+
231+
it('required is unchanged: a required unique field refuses "" as `required` — insert, update and the dry run', async () => {
232+
const expected = { name: 'ValidationError', code: 'VALIDATION_FAILED', fields: [['sku', 'required']] };
233+
expect(await refusal(() => engine.insert('uniq_blank_req', { id: 'q1', sku: '', skud: 'K1' }))).toEqual(expected);
234+
235+
await engine.insert('uniq_blank_req', { id: 'q2', sku: 'S2', skud: 'K2' });
236+
expect(await refusal(() => engine.update('uniq_blank_req', { id: 'q2', sku: '' }))).toEqual(expected);
237+
238+
const preview = await engine.validate('uniq_blank_req', { id: 'q3', sku: '', skud: 'K3' });
239+
expect(preview.valid).toBe(false);
240+
expect(preview.results?.[0]?.errors.map((e: any) => [e.field, e.code])).toEqual([['sku', 'required']]);
241+
});
242+
243+
it('required is unchanged: a required unique field with a defaultValue refuses "" — it is NOT defaulted', async () => {
244+
// `applyFieldDefaults` reads `''` as a real value, so the default never
245+
// fills it and `required` refuses it. Rewriting the blank to `null` here
246+
// would let the default fill it and the write land.
247+
expect(await refusal(() => engine.insert('uniq_blank_req', { id: 'r1', sku: 'S1', skud: '' })))
248+
.toEqual({ name: 'ValidationError', code: 'VALIDATION_FAILED', fields: [['skud', 'required']] });
249+
expect(written().some((r) => r.id === 'r1')).toBe(false);
250+
});
251+
252+
it('the credential ruling is unchanged: "" on a unique password field is refused, never cleared', async () => {
253+
let thrown: unknown;
254+
try { await engine.insert('uniq_blank_cred', { id: 'p1', pin: '' }); } catch (e) { thrown = e; }
255+
expect(thrown).toBeInstanceOf(EmptyCredentialWriteError);
256+
expect(thrown).toMatchObject({ code: EMPTY_CREDENTIAL_REFUSAL_CODE, status: EMPTY_CREDENTIAL_REFUSAL_STATUS, field: 'pin' });
257+
expect(written().some((r) => r.id === 'p1')).toBe(false);
258+
});
259+
});
Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
2+
3+
/**
4+
* #29176 — the write door's one string-stored arm, at the validator module:
5+
* `normalizeBlankTypedValues` stores `''` as `null` on an OPTIONAL text-like
6+
* column that a unique constraint covers, and on no other string-stored
7+
* column.
8+
*
9+
* The population is read from the spec's own `STRING_VALUE_TYPES`, so a type
10+
* joining the text-like class tomorrow is covered here without an edit, and
11+
* the two credential types are pinned OUT by name. The engine-level half (what
12+
* reaches the driver on every door) is `../engine-optional-unique-blank-door.test.ts`;
13+
* the physical column and the status, through REST on SQLite, are
14+
* `packages/rest/src/rest-data-optional-unique-blank.test.ts`.
15+
*/
16+
17+
import { describe, it, expect } from 'vitest';
18+
import { STRING_VALUE_TYPES } from '@objectstack/spec/data';
19+
import { normalizeBlankTypedValues } from './record-validator.js';
20+
21+
const CREDENTIAL = ['password', 'secret'];
22+
const textLike = [...STRING_VALUE_TYPES].filter((t) => !CREDENTIAL.includes(t));
23+
// Single-value string-stored types the `$empty` table reads `''` as a value on.
24+
const otherStringStored = ['select', 'radio', 'lookup', 'master_detail', 'user', 'autonumber'];
25+
26+
type Def = Record<string, unknown>;
27+
function schemaOf(types: readonly string[], extra: Def = {}, indexes?: unknown[]) {
28+
const fields: Record<string, Def> = {};
29+
for (const t of types) {
30+
fields[`f_${t}`] = {
31+
name: `f_${t}`,
32+
type: t,
33+
...(t === 'lookup' || t === 'master_detail' ? { reference: 'other' } : {}),
34+
...(t === 'select' || t === 'radio' ? { options: [{ value: 'a', label: 'A' }] } : {}),
35+
...extra,
36+
};
37+
}
38+
return { fields, ...(indexes ? { indexes } : {}) } as any;
39+
}
40+
const rowOf = (types: readonly string[], value: unknown) => Object.fromEntries(types.map((t) => [`f_${t}`, value]));
41+
42+
describe('normalizeBlankTypedValues: optional unique text-like columns (#29176)', () => {
43+
it('the population is the spec text-like class minus the credential types', () => {
44+
// A control on the set itself: if it ever emptied, every case below would
45+
// pass over nothing.
46+
expect(textLike.sort()).toEqual(
47+
['code', 'color', 'email', 'html', 'markdown', 'phone', 'qrcode', 'richtext', 'signature', 'text', 'textarea', 'url'],
48+
);
49+
for (const t of CREDENTIAL) expect(STRING_VALUE_TYPES.has(t), t).toBe(true);
50+
});
51+
52+
it.each([[true], ['global'], ['organization']])('field-level unique %j: "" on every text-like column becomes null', (unique) => {
53+
const out = normalizeBlankTypedValues(schemaOf(textLike, { unique }), rowOf(textLike, '')) as Record<string, unknown>;
54+
for (const t of textLike) expect(out[`f_${t}`], t).toBeNull();
55+
});
56+
57+
it('a member of a declared unique index becomes null; a plain index member keeps ""', () => {
58+
const schema = schemaOf(['text'], {}, [{ fields: ['f_text', 'f_textarea'], unique: 'global' }]);
59+
schema.fields.f_textarea = { name: 'f_textarea', type: 'textarea' };
60+
schema.fields.f_plain = { name: 'f_plain', type: 'text' };
61+
schema.indexes.push({ fields: ['f_plain'] }, { fields: ['f_plain'], unique: false });
62+
const out = normalizeBlankTypedValues(schema, { f_text: '', f_textarea: '', f_plain: '' }) as Record<string, unknown>;
63+
expect(out).toEqual({ f_text: null, f_textarea: null, f_plain: '' });
64+
});
65+
66+
it('the controls keep "": no unique constraint, unique: false, required, credentials, other string-stored types', () => {
67+
const cases: Array<[string, any, Record<string, unknown>]> = [
68+
['no unique', schemaOf(textLike), rowOf(textLike, '')],
69+
['unique: false', schemaOf(textLike, { unique: false }), rowOf(textLike, '')],
70+
['required', schemaOf(textLike, { unique: true, required: true }), rowOf(textLike, '')],
71+
['credentials', schemaOf(CREDENTIAL, { unique: true }), rowOf(CREDENTIAL, '')],
72+
['other string-stored', schemaOf(otherStringStored, { unique: true }), rowOf(otherStringStored, '')],
73+
];
74+
for (const [label, schema, row] of cases) expect(normalizeBlankTypedValues(schema, row), label).toBe(row);
75+
});
76+
77+
it('a lifecycle column the engine owns is never rewritten, even when declared unique', () => {
78+
const schema = { fields: { id: { name: 'id', type: 'text', unique: true } } } as any;
79+
const row = { id: '' };
80+
expect(normalizeBlankTypedValues(schema, row)).toBe(row);
81+
});
82+
83+
it('whitespace, and every non-blank value, pass through untouched', () => {
84+
for (const v of [' ', '\t', ' x ', 'abc', '0', null, undefined, 0, false]) {
85+
const row = rowOf(textLike, v);
86+
expect(normalizeBlankTypedValues(schemaOf(textLike, { unique: true }), row), String(v)).toBe(row);
87+
}
88+
});
89+
90+
it('pure: an array is rewritten per row, the caller rows are never mutated', () => {
91+
const schema = schemaOf(['text'], { unique: true });
92+
const rows = [{ f_text: '' }, { f_text: 'S1' }];
93+
const out = normalizeBlankTypedValues(schema, rows) as Array<Record<string, unknown>>;
94+
expect(out).not.toBe(rows);
95+
expect(out).toEqual([{ f_text: null }, { f_text: 'S1' }]);
96+
expect(out[1]).toBe(rows[1]);
97+
expect(rows[0]!.f_text).toBe('');
98+
});
99+
});

0 commit comments

Comments
 (0)