Skip to content

Commit 9465f3b

Browse files
committed
test(dogfood): WIP home field added to an existing object, migrated and recomputed (multi-currency M2-4)
Co-Authored-By: Claude <noreply@anthropic.com>
1 parent 31fe289 commit 9465f3b

1 file changed

Lines changed: 267 additions & 0 deletions

File tree

Lines changed: 267 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,267 @@
1+
// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
2+
//
3+
// [ADR-0144 D5, D7 parameter 1, D8 rule 2] The upgrade path from a `record`
4+
// mode amount with no home field to one that declares `homeAmount`, proven
5+
// with nothing new in the product:
6+
//
7+
// 1. An object already holds rows, written while its amount was `record`
8+
// mode and declared no home field (the shape before the home projection
9+
// shipped).
10+
// 2. The amount gains its `currencyConfig.homeAmount` pointer and the two
11+
// author-declared fields it names. The next boot migrates them through
12+
// the ordinary add-column path: the deferred schema sync `os migrate
13+
// plan` / `os migrate apply` run (`setDeferredDdl`,
14+
// `previewDeferredSchemaWork`, `detectManagedDrift`,
15+
// `flushDeferredSchemaDdl`). The plan lists the two columns as
16+
// `add_columns`, which is additive work, and nothing else; no drift; no
17+
// existing row is touched.
18+
// 3. The explicit recompute (`recomputeHomeAmounts`, behind `os migrate
19+
// recompute-home-amounts`) fills the new home field on every pre-existing
20+
// row with what a fresh write of the same row stores, and lists and skips
21+
// the row whose rate is missing, leaving its home field blank.
22+
//
23+
// Each boot is its own engine and its own driver over the same database, as
24+
// two processes are: a file for the SQLite cells, one schema for PostgreSQL.
25+
// Cells: better-sqlite3 and sqlite-wasm always run; PostgreSQL runs where
26+
// `OS_TEST_POSTGRES_URL` is set and is a named skip otherwise. The in-memory
27+
// driver has no columns to add, so it has no add-column path to prove.
28+
//
29+
// The recompute's own cells (a corrected rate, the skip classes, the
30+
// timezone, two organizations) are `home-amount-projection.test.ts`; this
31+
// file reuses its object and rates.
32+
33+
import { describe, it, expect, beforeAll, afterAll } from 'vitest';
34+
import { mkdtempSync, rmSync } from 'node:fs';
35+
import { tmpdir } from 'node:os';
36+
import { basename, join } from 'node:path';
37+
import { fileURLToPath } from 'node:url';
38+
import { ObjectQL, recomputeHomeAmounts, homeAmountRecomputeComplete } from '@objectstack/objectql';
39+
import { SqlDriver } from '@objectstack/driver-sql';
40+
import { SqliteWasmDriver } from '@objectstack/driver-sqlite-wasm';
41+
import { SysExchangeRate } from '@objectstack/platform-objects/system';
42+
import { installDefaultOrganization, DEFAULT_ORGANIZATION_ID } from './default-organization.testkit.js';
43+
44+
const LIVE_NAMESPACE = `os_lv_${basename(fileURLToPath(import.meta.url)).replace(/\.test\.ts$/, '').replace(/[^a-z0-9]+/gi, '_')}`;
45+
const PG_URL = process.env.OS_TEST_POSTGRES_URL;
46+
47+
async function adminRaw(statements: string[]): Promise<void> {
48+
const admin = new SqlDriver({ client: 'pg', connection: PG_URL } as never);
49+
try {
50+
for (const statement of statements) await admin.execute(statement);
51+
} finally {
52+
await admin.disconnect();
53+
}
54+
}
55+
56+
interface Cell {
57+
readonly id: string;
58+
readonly env: string | null;
59+
readonly url: string | undefined;
60+
/** Create the empty database, before the first boot. */
61+
readonly setup: () => Promise<void>;
62+
/** A new driver over the same database: one per boot. */
63+
readonly open: () => SqlDriver;
64+
readonly teardown: () => Promise<void>;
65+
}
66+
67+
let dir = '';
68+
const fileIn = (name: string) => join(dir, name);
69+
70+
const CELLS: readonly Cell[] = [
71+
{
72+
id: 'driver-sql (better-sqlite3 file)',
73+
env: null,
74+
url: 'sqlite',
75+
setup: async () => { dir = mkdtempSync(join(tmpdir(), 'os-home-upgrade-')); },
76+
open: () => new SqlDriver({ client: 'better-sqlite3', connection: { filename: fileIn('upgrade.db') }, useNullAsDefault: true }),
77+
teardown: async () => { rmSync(dir, { recursive: true, force: true }); },
78+
},
79+
{
80+
id: 'driver-sqlite-wasm (file)',
81+
env: null,
82+
url: 'sqlite-wasm',
83+
setup: async () => { dir = mkdtempSync(join(tmpdir(), 'os-home-upgrade-')); },
84+
open: () => new SqliteWasmDriver({ filename: fileIn('upgrade-wasm.db') }),
85+
teardown: async () => { rmSync(dir, { recursive: true, force: true }); },
86+
},
87+
{
88+
id: 'driver-sql (pg)',
89+
env: 'OS_TEST_POSTGRES_URL',
90+
url: PG_URL,
91+
setup: async () => {
92+
await adminRaw([`drop schema if exists ${LIVE_NAMESPACE} cascade`, `create schema ${LIVE_NAMESPACE}`]);
93+
},
94+
open: () => new SqlDriver({ client: 'pg', connection: PG_URL, searchPath: [LIVE_NAMESPACE] } as never),
95+
teardown: async () => { await adminRaw([`drop schema if exists ${LIVE_NAMESPACE} cascade`]); },
96+
},
97+
];
98+
99+
const SYS = { context: { isSystem: true } };
100+
const OBJECT = 'fx_upgrade';
101+
102+
/** Before: a `record`-mode amount with no home field. */
103+
const BEFORE = {
104+
name: OBJECT,
105+
label: 'FX upgrade',
106+
fields: {
107+
name: { name: 'name', type: 'text' },
108+
currency_code: { name: 'currency_code', type: 'text', valueDomain: 'iso_4217_currency' },
109+
invoice_date: { name: 'invoice_date', type: 'date' },
110+
amount: {
111+
name: 'amount',
112+
type: 'currency',
113+
currencyConfig: { currencyMode: 'record', currencyField: 'currency_code' },
114+
},
115+
},
116+
};
117+
118+
/** After: the one pointer line, and the two fields it names (D8 rule 2: declared by the author, never injected). */
119+
const AFTER = {
120+
...BEFORE,
121+
fields: {
122+
...BEFORE.fields,
123+
amount: {
124+
...BEFORE.fields.amount,
125+
currencyConfig: {
126+
...BEFORE.fields.amount.currencyConfig,
127+
homeAmount: { field: 'amount_home', rateDate: 'invoice_date', rateField: 'amount_rate' },
128+
},
129+
},
130+
amount_home: { name: 'amount_home', type: 'currency', readonly: true },
131+
amount_rate: { name: 'amount_rate', type: 'number', readonly: true },
132+
},
133+
};
134+
135+
const appWith = (object: unknown) => ({
136+
id: 'com.objectstack.dogfood.home-amount-added-to-existing-object',
137+
name: 'Home amount added to an existing object',
138+
version: '1.0.0',
139+
type: 'plugin',
140+
scope: 'system',
141+
objects: [SysExchangeRate, object],
142+
});
143+
144+
const RATES: ReadonlyArray<[string, string, number]> = [
145+
['USD', '2026-01-01', 0.1389],
146+
['USD', '2026-04-01', 0.15],
147+
];
148+
149+
/** The rows stored before the upgrade; SEK has no rate row. */
150+
const ROWS: ReadonlyArray<Record<string, unknown>> = [
151+
{ id: 'up_usd_march', currency_code: 'USD', invoice_date: '2026-03-15', amount: 10000 },
152+
{ id: 'up_usd_april', currency_code: 'USD', invoice_date: '2026-04-15', amount: 1500 },
153+
{ id: 'up_cny', currency_code: 'CNY', invoice_date: '2026-03-15', amount: 12.345 },
154+
{ id: 'up_sek', currency_code: 'SEK', invoice_date: '2026-03-15', amount: 500 },
155+
];
156+
157+
const quiet = { info: () => {}, warn: () => {} };
158+
159+
async function boot(driver: SqlDriver, object: unknown, options: { deferDdl?: boolean } = {}): Promise<ObjectQL> {
160+
const engine = new ObjectQL();
161+
engine.registerDriver(driver, true);
162+
await engine.init();
163+
// `os migrate plan` / `apply` boot with the deferral armed: the sync
164+
// registers the metadata and records the physical work instead of doing it.
165+
if (options.deferDdl) driver.setDeferredDdl(true);
166+
engine.registerApp(appWith(object));
167+
await engine.syncSchemas();
168+
await installDefaultOrganization(engine);
169+
engine.setHomeLocalizationResolver(async () => ({ currency: 'CNY' }));
170+
return engine;
171+
}
172+
173+
for (const cell of CELLS) {
174+
describe.skipIf(!cell.url)(
175+
`a home field added to an object that already holds rows — ${cell.id}${cell.url ? '' : ` (skipped: set ${cell.env} to run this cell)`}`,
176+
() => {
177+
let driver: SqlDriver;
178+
let engine: ObjectQL;
179+
180+
beforeAll(async () => {
181+
await cell.setup();
182+
// ── The first boot: the object with no home field, and its rows. ──
183+
const first = await boot(cell.open(), BEFORE);
184+
for (const [currency, effective_date, rate] of RATES) {
185+
await first.insert('sys_exchange_rate', { currency, effective_date, rate, source: 'manual' }, SYS);
186+
}
187+
for (const row of ROWS) await first.insert(OBJECT, { name: row.id, ...row }, SYS);
188+
await first.destroy();
189+
});
190+
191+
afterAll(async () => {
192+
await engine?.destroy();
193+
await cell.teardown();
194+
});
195+
196+
async function stored(id: unknown) {
197+
const back = await engine.findOne(OBJECT, { where: { id }, context: SYS.context } as never) as Record<string, unknown>;
198+
return {
199+
amount: Number(back.amount),
200+
currency: back.currency_code,
201+
home: back.amount_home == null ? null : Number(back.amount_home),
202+
rate: back.amount_rate == null ? null : Number(back.amount_rate),
203+
};
204+
}
205+
206+
it('the declared home field migrates through the ordinary add-column path, and no stored row moves', async () => {
207+
// ── The upgrade boot, as `os migrate apply` runs it. ──
208+
driver = cell.open();
209+
engine = await boot(driver, AFTER, { deferDdl: true });
210+
211+
// The plan: the two declared columns, as additive work; nothing rewrites a row.
212+
const table = (await driver.previewDeferredSchemaWork()).filter((w) => w.table === OBJECT);
213+
expect(table).toEqual([{ table: OBJECT, kind: 'add_columns', columns: ['amount_home', 'amount_rate'] }]);
214+
expect((await driver.previewDeferredSchemaWork()).filter((w) => w.table !== OBJECT)).toEqual([]);
215+
expect((await driver.detectManagedDrift()).filter((d) => d.table === OBJECT)).toEqual([]);
216+
217+
// The confirmed apply.
218+
const performed = await driver.flushDeferredSchemaDdl();
219+
expect(performed.filter((w) => w.table === OBJECT)).toEqual(table);
220+
expect(await driver.previewDeferredSchemaWork()).toEqual([]);
221+
222+
// Every stored row is still there, as it was, with an empty home field.
223+
expect(await engine.count(OBJECT, { context: SYS.context } as never)).toBe(ROWS.length);
224+
for (const row of ROWS) {
225+
expect(await stored(row.id)).toEqual({ amount: row.amount, currency: row.currency_code, home: null, rate: null });
226+
}
227+
});
228+
229+
it('the recompute fills every pre-existing row with what a fresh write stores; the row with no rate is listed and skipped', async () => {
230+
const run = (apply = false) => recomputeHomeAmounts(engine as never, quiet, { object: OBJECT, apply });
231+
232+
const dry = await run();
233+
expect(dry).toMatchObject({ amounts: 4, unchanged: 0, changed: 3, written: 0, skippedTotal: 1, failures: [] });
234+
for (const row of ROWS) expect((await stored(row.id)).home).toBeNull();
235+
236+
const applied = await run(true);
237+
expect(applied).toMatchObject({ amounts: 4, changed: 3, written: 3, skippedTotal: 1, failures: [] });
238+
expect(applied.skipped).toEqual([
239+
{ recordId: 'up_sek', organizationId: DEFAULT_ORGANIZATION_ID, field: 'amount', reason: 'rate_missing', currency: 'SEK', date: '2026-03-15' },
240+
]);
241+
expect(homeAmountRecomputeComplete(applied)).toBe(false);
242+
243+
// The ADR's own figures: USD 10,000 at 0.1389 is ¥71,994.24; the same currency is rate 1, rounded once.
244+
expect(await stored('up_usd_march')).toMatchObject({ home: 71994.24, rate: 0.1389 });
245+
expect(await stored('up_usd_april')).toMatchObject({ home: 10000, rate: 0.15 });
246+
expect(await stored('up_cny')).toMatchObject({ home: 12.35, rate: 1 });
247+
// The skipped row keeps a blank home field, never a fallback.
248+
expect(await stored('up_sek')).toMatchObject({ home: null, rate: null });
249+
250+
// Equal to a fresh write of the same row, after the upgrade.
251+
for (const row of ROWS.filter((r) => r.id !== 'up_sek')) {
252+
const { id: _old, ...values } = row;
253+
const fresh = await engine.insert(OBJECT, { name: `fresh_${String(row.id)}`, ...values }, SYS);
254+
expect(await stored(row.id)).toEqual(await stored(fresh.id));
255+
}
256+
// A fresh write of the skipped row is refused for the same missing rate.
257+
const refused = await engine.insert(OBJECT, { name: 'fresh_sek', currency_code: 'SEK', invoice_date: '2026-03-15', amount: 500 }, SYS)
258+
.then(() => null, (e: { code?: string }) => e);
259+
expect(refused?.code).toBe('ERR_EXCHANGE_RATE_MISSING');
260+
261+
// A re-run changes nothing and still lists the one row.
262+
const again = await run(true);
263+
expect(again).toMatchObject({ amounts: 7, unchanged: 6, changed: 0, written: 0, skippedTotal: 1 });
264+
});
265+
},
266+
);
267+
}

0 commit comments

Comments
 (0)