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