|
| 1 | +// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license. |
| 2 | + |
| 3 | +/** |
| 4 | + * [#20671] A `time` field is a zone-less wall clock, and the record validator's |
| 5 | + * `time` arm asks `@objectstack/core`'s one rule (`isUninterpretableTemporalComparand`, |
| 6 | + * the one the `time` comparand door asks). A value that rule does not read is |
| 7 | + * refused with `VALIDATION_FAILED` and the field's `invalid_time` code on insert, |
| 8 | + * update, a multi-row update and the dry-run `validate`, before any driver |
| 9 | + * write. A zone suffix on a time of day is refused in its own sentence (drop |
| 10 | + * the suffix, or use a `datetime` field for an instant). |
| 11 | + * |
| 12 | + * Measured on the base (`fa0a4b661`) through `POST /api/v1/data/:object` and a |
| 13 | + * read-back through `POST /api/v1/data/:object/query`, the process in |
| 14 | + * America/New_York and PostgreSQL 16 at Asia/Shanghai: |
| 15 | + * |
| 16 | + * | written to a `time` | memory | SQLite | PostgreSQL | now | |
| 17 | + * |:--|:--|:--|:--|:--| |
| 18 | + * | `"+010000-01-01T10:00:00Z"` | 201, read back verbatim | 201, verbatim | 500 `DATABASE_ERROR` | 400 | |
| 19 | + * | `"9999-12-31T23:00:00-02:00"` (UTC year 10000) | 201, verbatim | 201, verbatim | 500 | 400 | |
| 20 | + * | `"10:00Z"`, `"10:00+08:00"`, `"10:00:00+0800"` | 201, verbatim | 201, verbatim | 201, `"10:00:00"` | 400, the zone sentence | |
| 21 | + * | `"10:00:00.250Z"` | 201, verbatim | 201, verbatim | 201, `"10:00:00.250"` | 400, the zone sentence | |
| 22 | + * | `"2026-07-15 10:00Z"` (a space and a zone) | 201, `"10:00:00"` | the same | the same | 400 | |
| 23 | + * | `"10:00"`, `"10:00:00"` | 201, `"10:00:00"` | the same | the same | unchanged | |
| 24 | + * | `"2026-07-15T10:00:00Z"`, `"2026-07-15T18:00:00+08:00"` | 201, `"10:00:00"` | the same | the same | unchanged | |
| 25 | + * | `"07/15/2026 10:00"`, `"{now}"`, the number `36000000` | 400 `invalid_time` | the same | the same | unchanged | |
| 26 | + * |
| 27 | + * The REST door over SQLite and PostgreSQL is |
| 28 | + * `packages/rest/src/data-temporal-write-real-day-iso.test.ts`; the memory |
| 29 | + * driver's half is `memory-20671-time-write-zone-less.test.ts`. This file's |
| 30 | + * driver records writes and stores nothing, because the refusal sits in front |
| 31 | + * of every driver. |
| 32 | + */ |
| 33 | + |
| 34 | +import { describe, it, expect, beforeEach } from 'vitest'; |
| 35 | +import { isUninterpretableTemporalComparand } from '@objectstack/core'; |
| 36 | +import { renderValidationMessage } from '@objectstack/spec/system'; |
| 37 | +import { ObjectQL } from './engine.js'; |
| 38 | + |
| 39 | +const schedule = { |
| 40 | + name: 'schedule', |
| 41 | + label: 'Schedule', |
| 42 | + fields: { |
| 43 | + id: { name: 'id', type: 'text' as const, primaryKey: true }, |
| 44 | + customer_id: { name: 'customer_id', type: 'text' as const }, |
| 45 | + slot: { name: 'slot', label: 'Slot', type: 'time' as const }, |
| 46 | + }, |
| 47 | +}; |
| 48 | + |
| 49 | +/** A time of day with a `Z` or an offset: the zone sentence. Each was a 201 at the base, stored two ways by backend. */ |
| 50 | +const ZONED: readonly string[] = [ |
| 51 | + '10:00Z', |
| 52 | + '10:00+08:00', |
| 53 | + '10:00:00Z', |
| 54 | + '10:00:00+0800', |
| 55 | + '10:00:00.250Z', |
| 56 | + '10:00-05:30', |
| 57 | + '23:59:59-00:00', |
| 58 | + ' 10:00Z ', |
| 59 | + '10:00z', |
| 60 | +]; |
| 61 | + |
| 62 | +/** An instant the `time` rule does not read: the plain sentence. Each was a 201 (or a 500 on PostgreSQL) at the base. */ |
| 63 | +const UNREAD_INSTANT: readonly unknown[] = [ |
| 64 | + '+010000-01-01T10:00:00Z', |
| 65 | + '9999-12-31T23:00:00-02:00', |
| 66 | + '-000001-01-01T10:00:00Z', |
| 67 | + '2026-02-30T10:00:00Z', |
| 68 | + '2026-07-15 10:00Z', |
| 69 | + '2026-07-15t10:00:00z', |
| 70 | + new Date(Date.parse('+010000-01-01T10:00:00Z')), |
| 71 | +]; |
| 72 | + |
| 73 | +/** Refused at the base already, kept refused, in the plain sentence. */ |
| 74 | +const STILL_REFUSED: readonly unknown[] = [ |
| 75 | + '25:00', |
| 76 | + '25:00Z', |
| 77 | + '14:60', |
| 78 | + 'not-a-time', |
| 79 | + '14', |
| 80 | + '07/15/2026 10:00', |
| 81 | + 'x2026-07-15T10:00:00Z', |
| 82 | + '{now}', |
| 83 | + 36000000, |
| 84 | +]; |
| 85 | + |
| 86 | +/** A wall clock, or an ISO instant with a four-digit UTC year — each reaches the driver as written. */ |
| 87 | +const ACCEPTED: readonly unknown[] = [ |
| 88 | + '10:00', |
| 89 | + '10:00:00', |
| 90 | + '10:00:00.250', |
| 91 | + ' 10:00 ', |
| 92 | + '00:00', |
| 93 | + '23:59:59.999', |
| 94 | + '2026-07-15T10:00:00Z', |
| 95 | + '2026-07-15T18:00:00+08:00', |
| 96 | + '2026-07-15T10:00:00-0530', |
| 97 | + '2026-07-15T10:00', |
| 98 | + '2026-07-15 10:00', |
| 99 | + new Date(Date.UTC(2026, 6, 15, 10)), |
| 100 | +]; |
| 101 | + |
| 102 | +const REFUSED: readonly unknown[] = [...ZONED, ...UNREAD_INSTANT, ...STILL_REFUSED]; |
| 103 | + |
| 104 | +/** A driver that records every write, and answers none. */ |
| 105 | +function makeRecordingDriver() { |
| 106 | + const writes: Record<string, unknown>[] = []; |
| 107 | + const driver: any = { |
| 108 | + name: 'recording', version: '0.0.0', supports: {}, |
| 109 | + async connect() {}, async disconnect() {}, async checkHealth() { return true; }, async execute() { return null; }, |
| 110 | + async find() { return []; }, |
| 111 | + async findOne() { return { id: 'r1' }; }, |
| 112 | + async count() { return 0; }, |
| 113 | + async aggregate() { return []; }, |
| 114 | + async create(_o: string, data: Record<string, unknown>) { writes.push(data); return { ...data }; }, |
| 115 | + async update(_o: string, id: string, data: Record<string, unknown>) { writes.push(data); return { ...data, id }; }, |
| 116 | + async updateMany(_o: string, _ast: unknown, data: Record<string, unknown>) { writes.push(data); return 0; }, |
| 117 | + async delete() { return true; }, |
| 118 | + async deleteMany() { return 0; }, |
| 119 | + async bulkCreate(_o: string, batch: Record<string, unknown>[]) { writes.push(...batch); return batch; }, |
| 120 | + async beginTransaction() { return { commit: async () => {}, rollback: async () => {} }; }, |
| 121 | + async commit() {}, async rollback() {}, |
| 122 | + }; |
| 123 | + return { driver, writes }; |
| 124 | +} |
| 125 | + |
| 126 | +const refusalOf = async (p: Promise<unknown>) => |
| 127 | + p.then(() => null, (e: any) => e as Error & { code?: string; fields?: Array<{ field: string; code: string; message: string }> }); |
| 128 | + |
| 129 | +const labelOf = (value: unknown) => (value instanceof Date ? `Date ${value.toISOString()}` : JSON.stringify(value)); |
| 130 | + |
| 131 | +/** The sentence a refusal of `value` carries: the zone sentence for a zone-suffixed time of day, else the plain one. */ |
| 132 | +const sentenceFor = (value: unknown) => |
| 133 | + renderValidationMessage({ |
| 134 | + messageKey: ZONED.includes(value as string) ? 'invalid_time_zoned' : 'invalid_time', |
| 135 | + label: 'Slot', |
| 136 | + field: 'slot', |
| 137 | + }); |
| 138 | + |
| 139 | +describe('[#20671] the time write door — a zone-less wall clock, or an ISO instant with a four-digit UTC year, or VALIDATION_FAILED before any write', () => { |
| 140 | + let engine: ObjectQL; |
| 141 | + let writes: Record<string, unknown>[]; |
| 142 | + |
| 143 | + beforeEach(async () => { |
| 144 | + const rec = makeRecordingDriver(); |
| 145 | + writes = rec.writes; |
| 146 | + engine = new ObjectQL(); |
| 147 | + engine.registerDriver(rec.driver, true); |
| 148 | + await engine.init(); |
| 149 | + engine.registry.registerObject(schedule, 'test'); |
| 150 | + }); |
| 151 | + |
| 152 | + const doors = (value: unknown) => [ |
| 153 | + ['insert', () => engine.insert('schedule', { id: 'n1', customer_id: 'c1', slot: value })], |
| 154 | + ['update', () => engine.update('schedule', { id: 'r1', slot: value })], |
| 155 | + ['multi-row update', () => engine.update('schedule', { slot: value }, { where: { customer_id: 'c1' }, multi: true })], |
| 156 | + ] as const; |
| 157 | + |
| 158 | + it('refuses a zone suffix, an unread instant and the junk class on insert, update and a multi-row update, naming the field with invalid_time — and writes nothing', async () => { |
| 159 | + for (const value of REFUSED) { |
| 160 | + for (const [door, call] of doors(value)) { |
| 161 | + const err = await refusalOf(call()); |
| 162 | + expect(err, `${door}, ${labelOf(value)}`).not.toBeNull(); |
| 163 | + expect(err!.code, `${door}, ${labelOf(value)}`).toBe('VALIDATION_FAILED'); |
| 164 | + expect(err!.fields?.map((f) => [f.field, f.code]), `${door}, ${labelOf(value)}`).toEqual([['slot', 'invalid_time']]); |
| 165 | + } |
| 166 | + } |
| 167 | + expect(writes, 'no write — every refusal precedes the driver').toHaveLength(0); |
| 168 | + }); |
| 169 | + |
| 170 | + it('a zone suffix on a time of day is refused in the zone sentence, every other refusal in the plain one', async () => { |
| 171 | + expect(sentenceFor('10:00Z'), 'the two sentences differ').not.toBe(sentenceFor('25:00')); |
| 172 | + for (const value of REFUSED) { |
| 173 | + const err = await refusalOf(engine.insert('schedule', { id: 'n1', slot: value })); |
| 174 | + expect(err!.fields?.[0]?.message, labelOf(value)).toBe(sentenceFor(value)); |
| 175 | + } |
| 176 | + }); |
| 177 | + |
| 178 | + it('the dry-run validate predicts each refusal — and each accepted value as valid', async () => { |
| 179 | + for (const value of REFUSED) { |
| 180 | + const verdict = await engine.validate('schedule', { slot: value }); |
| 181 | + expect(verdict.valid, labelOf(value)).toBe(false); |
| 182 | + expect(verdict.results[0]!.errors, labelOf(value)).toEqual([expect.objectContaining({ field: 'slot', code: 'invalid_time' })]); |
| 183 | + } |
| 184 | + for (const value of ACCEPTED) { |
| 185 | + expect((await engine.validate('schedule', { slot: value })).valid, labelOf(value)).toBe(true); |
| 186 | + } |
| 187 | + }); |
| 188 | + |
| 189 | + it('accepts a wall clock, an ISO instant with a four-digit UTC year and a Date on every door — the POSITIVE CONTROL', async () => { |
| 190 | + for (const value of ACCEPTED) { |
| 191 | + for (const [door, call] of doors(value)) { |
| 192 | + const before = writes.length; |
| 193 | + await expect(call(), `${door}, ${labelOf(value)}`).resolves.toBeDefined(); |
| 194 | + expect(writes.length, `${door}, ${labelOf(value)} reached the driver`).toBe(before + 1); |
| 195 | + expect(writes.at(-1)!.slot, `${door}, ${labelOf(value)} reached it as written`).toEqual(value); |
| 196 | + } |
| 197 | + } |
| 198 | + }); |
| 199 | + |
| 200 | + it('one rule: a string is refused as a written time exactly when core refuses it as a time comparand, save the two write-only refusals', async () => { |
| 201 | + const corpus = [...REFUSED, ...ACCEPTED].filter((v): v is string => typeof v === 'string'); |
| 202 | + // The comparand door exempts a `{placeholder}` (its resolver's vocabulary); |
| 203 | + // the write door refuses it, because a placeholder is not a value. |
| 204 | + const writeOnly = new Set(['{now}']); |
| 205 | + for (const value of corpus) { |
| 206 | + const refused = (await refusalOf(engine.insert('schedule', { id: 'n1', slot: value }))) !== null; |
| 207 | + const expected = writeOnly.has(value) || isUninterpretableTemporalComparand('time', value); |
| 208 | + expect(refused, value).toBe(expected); |
| 209 | + } |
| 210 | + // A number is the other write-only refusal: epoch milliseconds are a |
| 211 | + // comparand, never a written time. |
| 212 | + expect(isUninterpretableTemporalComparand('time', 36000000), 'core reads the number').toBe(false); |
| 213 | + expect(await refusalOf(engine.insert('schedule', { id: 'n1', slot: 36000000 })), 'the write door refuses it').not.toBeNull(); |
| 214 | + }); |
| 215 | +}); |
![objectstack-fleet[bot]](https://avatars.githubusercontent.com/u/254823548?v=4&size=40){kind=avatar}
0 commit comments