|
| 1 | +// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license. |
| 2 | + |
| 3 | +/** |
| 4 | + * [ADR-0144 D5] `currencyConfig.homeAmount: { field, rateDate, rateField }` — |
| 5 | + * a `record`-mode amount declares, by pointer, where the engine stores it |
| 6 | + * converted into the home currency, which date picks the rate, and where the |
| 7 | + * rate used is stored. |
| 8 | + * |
| 9 | + * Two doors, as for `currencyField`: `CurrencyConfigSchema` refuses what one |
| 10 | + * config can see (`homeAmount` outside `record`, a missing, empty or unknown |
| 11 | + * pointer), and the object's `superRefine` refuses what the pointers name. |
| 12 | + * The home and rate fields are platform-written, marked with the existing |
| 13 | + * `readonly: true`. |
| 14 | + */ |
| 15 | + |
| 16 | +import { describe, it, expect } from 'vitest'; |
| 17 | + |
| 18 | +import { CurrencyConfigSchema } from './field.zod'; |
| 19 | +import { ObjectSchema } from './object.zod'; |
| 20 | + |
| 21 | +const HOME = { field: 'amount_home', rateDate: 'invoice_date', rateField: 'amount_rate' } as const; |
| 22 | +const RECORD = { currencyMode: 'record', currencyField: 'currency_code', homeAmount: HOME } as const; |
| 23 | + |
| 24 | +/** The fields every accepted invoice carries; a case overrides one of them. */ |
| 25 | +const BASE_FIELDS = { |
| 26 | + currency_code: { type: 'text', label: 'Currency', valueDomain: 'iso_4217_currency' }, |
| 27 | + invoice_date: { type: 'date', label: 'Invoice date' }, |
| 28 | + amount: { type: 'currency', label: 'Amount', currencyConfig: RECORD }, |
| 29 | + amount_home: { type: 'currency', label: 'Amount (home)', readonly: true }, |
| 30 | + amount_rate: { type: 'number', label: 'Rate used', readonly: true }, |
| 31 | +} as const; |
| 32 | + |
| 33 | +function invoice(overrides: Record<string, unknown> = {}): Record<string, unknown> { |
| 34 | + const fields: Record<string, unknown> = { ...BASE_FIELDS, ...overrides }; |
| 35 | + for (const [k, v] of Object.entries(fields)) if (v === undefined) delete fields[k]; |
| 36 | + return { name: 'invoice', label: 'Invoice', fields }; |
| 37 | +} |
| 38 | + |
| 39 | +/** The issues of a refused object parse, reduced to what an author is shown. */ |
| 40 | +function objectIssues(input: unknown): Array<{ code: string; path: string; message: string }> { |
| 41 | + const r = ObjectSchema.safeParse(input); |
| 42 | + if (r.success) return []; |
| 43 | + return r.error.issues.map((i) => ({ code: i.code, path: i.path.join('.'), message: i.message })); |
| 44 | +} |
| 45 | + |
| 46 | +const AT = 'fields.amount.currencyConfig.homeAmount'; |
| 47 | + |
| 48 | +describe('`CurrencyConfigSchema`: `homeAmount` under `record` only, three required pointers', () => { |
| 49 | + it('accepts a `record` config with all three pointers, keeping them in the parse output', () => { |
| 50 | + const r = CurrencyConfigSchema.safeParse(RECORD); |
| 51 | + expect(r.success).toBe(true); |
| 52 | + if (!r.success) return; |
| 53 | + expect(r.data.homeAmount).toEqual(HOME); |
| 54 | + expect(CurrencyConfigSchema.parse(r.data)).toEqual(r.data); |
| 55 | + }); |
| 56 | + |
| 57 | + it('a `record` config without `homeAmount` parses as before, with no key added', () => { |
| 58 | + const r = CurrencyConfigSchema.parse({ currencyMode: 'record', currencyField: 'currency_code' }); |
| 59 | + expect(JSON.stringify(r)).toBe('{"currencyMode":"record","currencyField":"currency_code"}'); |
| 60 | + }); |
| 61 | + |
| 62 | + it.each([ |
| 63 | + ['fixed', { currencyMode: 'fixed', defaultCurrency: 'USD' }], |
| 64 | + ['dynamic', { currencyMode: 'dynamic' }], |
| 65 | + ['dynamic (defaulted)', {}], |
| 66 | + ] as const)('refuses `homeAmount` under `%s`, at the key, with the remedy', (_mode, config) => { |
| 67 | + const r = CurrencyConfigSchema.safeParse({ ...config, homeAmount: HOME }); |
| 68 | + expect(r.success).toBe(false); |
| 69 | + if (r.success) return; |
| 70 | + expect(r.error.issues).toHaveLength(1); |
| 71 | + expect(r.error.issues[0]!.code).toBe('custom'); |
| 72 | + expect(r.error.issues[0]!.path).toEqual(['homeAmount']); |
| 73 | + expect(r.error.issues[0]!.message).toMatch(/^`homeAmount` is read only under `currencyMode: 'record'`/); |
| 74 | + }); |
| 75 | + |
| 76 | + it.each(['field', 'rateDate', 'rateField'] as const)('refuses a `homeAmount` without `%s` (every pointer is required)', (key) => { |
| 77 | + const { [key]: _dropped, ...rest } = HOME; |
| 78 | + const r = CurrencyConfigSchema.safeParse({ ...RECORD, homeAmount: rest }); |
| 79 | + expect(r.success).toBe(false); |
| 80 | + if (r.success) return; |
| 81 | + expect(r.error.issues.map((i) => i.path.join('.'))).toEqual([`homeAmount.${key}`]); |
| 82 | + expect(r.error.issues[0]!.code).toBe('invalid_type'); |
| 83 | + expect(r.error.issues[0]!.message).toMatch(new RegExp(`^\`homeAmount\` needs \`${key}\`, the name of `)); |
| 84 | + }); |
| 85 | + |
| 86 | + it.each(['field', 'rateDate', 'rateField'] as const)('refuses an empty `homeAmount.%s`, at the pointer', (key) => { |
| 87 | + const r = CurrencyConfigSchema.safeParse({ ...RECORD, homeAmount: { ...HOME, [key]: '' } }); |
| 88 | + expect(r.success).toBe(false); |
| 89 | + if (r.success) return; |
| 90 | + expect(r.error.issues.map((i) => i.path.join('.'))).toEqual([`homeAmount.${key}`]); |
| 91 | + expect(r.error.issues[0]!.message).toMatch(new RegExp(`^\`homeAmount\\.${key}\` names a field: an empty name points at nothing`)); |
| 92 | + }); |
| 93 | + |
| 94 | + it('refuses an unknown key inside `homeAmount`, steering a near-miss to the declared pointer', () => { |
| 95 | + const r = CurrencyConfigSchema.safeParse({ ...RECORD, homeAmount: { field: 'amount_home', rateDate: 'invoice_date', rate: 'amount_rate' } }); |
| 96 | + expect(r.success).toBe(false); |
| 97 | + if (r.success) return; |
| 98 | + const paths = r.error.issues.map((i) => i.path.join('.')); |
| 99 | + expect(paths).toContain('homeAmount.rateField'); |
| 100 | + const unknown = r.error.issues.find((i) => i.code === 'unrecognized_keys'); |
| 101 | + expect(unknown?.message).toContain('rateField'); |
| 102 | + }); |
| 103 | +}); |
| 104 | + |
| 105 | +describe('the object judges what `homeAmount` names', () => { |
| 106 | + it('accepts the honest shape: a readonly `dynamic` home field, a date, a readonly number rate field', () => { |
| 107 | + expect(objectIssues(invoice())).toEqual([]); |
| 108 | + // A `datetime` document date and a home field with an explicit `dynamic` config are honest too. |
| 109 | + expect(objectIssues(invoice({ |
| 110 | + invoice_date: { type: 'datetime', label: 'Issued at' }, |
| 111 | + amount_home: { type: 'currency', label: 'Amount (home)', readonly: true, currencyConfig: { currencyMode: 'dynamic' } }, |
| 112 | + }))).toEqual([]); |
| 113 | + const once = ObjectSchema.parse(invoice()); |
| 114 | + expect(ObjectSchema.parse(once)).toEqual(once); |
| 115 | + }); |
| 116 | + |
| 117 | + it('two amounts with the same code field and document date may share one rate field', () => { |
| 118 | + expect(objectIssues(invoice({ |
| 119 | + tax: { type: 'currency', label: 'Tax', currencyConfig: { ...RECORD, homeAmount: { ...HOME, field: 'tax_home' } } }, |
| 120 | + tax_home: { type: 'currency', label: 'Tax (home)', readonly: true }, |
| 121 | + }))).toEqual([]); |
| 122 | + }); |
| 123 | + |
| 124 | + describe('`homeAmount.field`', () => { |
| 125 | + it('refuses a pointer into nothing, naming the candidates', () => { |
| 126 | + const issues = objectIssues(invoice({ |
| 127 | + amount: { type: 'currency', label: 'Amount', currencyConfig: { ...RECORD, homeAmount: { ...HOME, field: 'home' } } }, |
| 128 | + })); |
| 129 | + expect(issues).toHaveLength(1); |
| 130 | + expect(issues[0]!.code).toBe('custom'); |
| 131 | + expect(issues[0]!.path).toBe(`${AT}.field`); |
| 132 | + expect(issues[0]!.message).toMatch(/^`amount\.currencyConfig\.homeAmount\.field` names `home`, but object `invoice` declares no other field `home`/); |
| 133 | + expect(issues[0]!.message).toContain('candidates: `amount_home`'); |
| 134 | + }); |
| 135 | + |
| 136 | + it('refuses a pointer at the amount itself', () => { |
| 137 | + const issues = objectIssues(invoice({ |
| 138 | + amount: { type: 'currency', label: 'Amount', currencyConfig: { ...RECORD, homeAmount: { ...HOME, field: 'amount' } } }, |
| 139 | + })); |
| 140 | + expect(issues.map((i) => i.path)).toEqual([`${AT}.field`]); |
| 141 | + expect(issues[0]!.message).toContain('declares no other field `amount`'); |
| 142 | + }); |
| 143 | + |
| 144 | + it('refuses a pointer at a field that is not `currency` (a `number`, a currency `formula`)', () => { |
| 145 | + for (const home of [ |
| 146 | + { type: 'number', label: 'Amount (home)', readonly: true }, |
| 147 | + { type: 'formula', label: 'Amount (home)', expression: 'record.amount', returnType: 'currency' }, |
| 148 | + ]) { |
| 149 | + const issues = objectIssues(invoice({ amount_home: home })); |
| 150 | + expect(issues.map((i) => i.path), home.type).toEqual([`${AT}.field`]); |
| 151 | + expect(issues[0]!.message).toMatch(new RegExp(`^\`amount\\.currencyConfig\\.homeAmount\\.field\` names \`amount_home\`, a \`${home.type}\` field`)); |
| 152 | + } |
| 153 | + }); |
| 154 | + |
| 155 | + it.each([ |
| 156 | + ['fixed', { currencyMode: 'fixed', defaultCurrency: 'CNY' }], |
| 157 | + ['record', { currencyMode: 'record', currencyField: 'currency_code' }], |
| 158 | + ] as const)('refuses a `%s`-mode home field: metadata never names the home currency', (mode, currencyConfig) => { |
| 159 | + const issues = objectIssues(invoice({ amount_home: { type: 'currency', label: 'Amount (home)', readonly: true, currencyConfig } })); |
| 160 | + expect(issues.map((i) => i.path)).toEqual([`${AT}.field`]); |
| 161 | + expect(issues[0]!.message).toMatch(new RegExp(`^\`amount\\.currencyConfig\\.homeAmount\\.field\` names \`amount_home\`, a \`${mode}\`-mode currency field`)); |
| 162 | + }); |
| 163 | + |
| 164 | + it('refuses a home field another amount already stores into', () => { |
| 165 | + const issues = objectIssues(invoice({ |
| 166 | + tax: { type: 'currency', label: 'Tax', currencyConfig: RECORD }, |
| 167 | + })); |
| 168 | + expect(issues.map((i) => i.path)).toEqual(['fields.tax.currencyConfig.homeAmount.field']); |
| 169 | + expect(issues[0]!.message).toContain('already the home field of `amount`'); |
| 170 | + }); |
| 171 | + }); |
| 172 | + |
| 173 | + describe('`homeAmount.rateDate`', () => { |
| 174 | + it('refuses a pointer into nothing, naming the date candidates', () => { |
| 175 | + const issues = objectIssues(invoice({ |
| 176 | + amount: { type: 'currency', label: 'Amount', currencyConfig: { ...RECORD, homeAmount: { ...HOME, rateDate: 'doc_date' } } }, |
| 177 | + })); |
| 178 | + expect(issues).toHaveLength(1); |
| 179 | + expect(issues[0]!.code).toBe('custom'); |
| 180 | + expect(issues[0]!.path).toBe(`${AT}.rateDate`); |
| 181 | + expect(issues[0]!.message).toMatch(/^`amount\.currencyConfig\.homeAmount\.rateDate` names `doc_date`, but object `invoice` declares no field `doc_date`/); |
| 182 | + expect(issues[0]!.message).toContain('candidates: `invoice_date`'); |
| 183 | + }); |
| 184 | + |
| 185 | + it('refuses a pointer at a field that is not `date` / `datetime`, and says nothing defaults to `created_at`', () => { |
| 186 | + const issues = objectIssues(invoice({ invoice_date: { type: 'text', label: 'Invoice date' } })); |
| 187 | + expect(issues.map((i) => i.path)).toEqual([`${AT}.rateDate`]); |
| 188 | + expect(issues[0]!.message).toMatch(/^`amount\.currencyConfig\.homeAmount\.rateDate` names `invoice_date`, a `text` field/); |
| 189 | + expect(issues[0]!.message).toContain('nothing defaults to `created_at`'); |
| 190 | + }); |
| 191 | + }); |
| 192 | + |
| 193 | + describe('`homeAmount.rateField`', () => { |
| 194 | + it('refuses a pointer into nothing', () => { |
| 195 | + const issues = objectIssues(invoice({ amount_rate: undefined })); |
| 196 | + expect(issues).toHaveLength(1); |
| 197 | + expect(issues[0]!.code).toBe('custom'); |
| 198 | + expect(issues[0]!.path).toBe(`${AT}.rateField`); |
| 199 | + expect(issues[0]!.message).toMatch(/^`amount\.currencyConfig\.homeAmount\.rateField` names `amount_rate`, but object `invoice` declares no field `amount_rate`/); |
| 200 | + expect(issues[0]!.message).toContain('the object has none'); |
| 201 | + }); |
| 202 | + |
| 203 | + it('refuses a pointer at a field that is not `number`', () => { |
| 204 | + const issues = objectIssues(invoice({ amount_rate: { type: 'currency', label: 'Rate used', readonly: true } })); |
| 205 | + expect(issues.map((i) => i.path)).toEqual([`${AT}.rateField`]); |
| 206 | + expect(issues[0]!.message).toMatch(/^`amount\.currencyConfig\.homeAmount\.rateField` names `amount_rate`, a `currency` field/); |
| 207 | + }); |
| 208 | + |
| 209 | + it('refuses a rate field shared with an amount that names another document date', () => { |
| 210 | + const issues = objectIssues(invoice({ |
| 211 | + due_date: { type: 'date', label: 'Due date' }, |
| 212 | + tax: { type: 'currency', label: 'Tax', currencyConfig: { ...RECORD, homeAmount: { ...HOME, field: 'tax_home', rateDate: 'due_date' } } }, |
| 213 | + tax_home: { type: 'currency', label: 'Tax (home)', readonly: true }, |
| 214 | + })); |
| 215 | + expect(issues.map((i) => i.path)).toEqual(['fields.tax.currencyConfig.homeAmount.rateField']); |
| 216 | + expect(issues[0]!.message).toContain('already stores the rate of `amount`'); |
| 217 | + }); |
| 218 | + }); |
| 219 | + |
| 220 | + describe('the home and rate fields are platform-written (`readonly: true`, no `expression`)', () => { |
| 221 | + it.each(['amount_home', 'amount_rate'] as const)('refuses `%s` without `readonly: true`', (name) => { |
| 222 | + const issues = objectIssues(invoice({ [name]: { ...BASE_FIELDS[name], readonly: false } })); |
| 223 | + const key = name === 'amount_home' ? 'field' : 'rateField'; |
| 224 | + expect(issues.map((i) => i.path)).toEqual([`${AT}.${key}`]); |
| 225 | + expect(issues[0]!.code).toBe('custom'); |
| 226 | + expect(issues[0]!.message).toContain('does not declare `readonly: true`'); |
| 227 | + expect(issues[0]!.message).toContain(`Add \`readonly: true\` to \`${name}\``); |
| 228 | + }); |
| 229 | + |
| 230 | + it.each(['amount_home', 'amount_rate'] as const)('refuses `%s` declaring an `expression`', (name) => { |
| 231 | + const issues = objectIssues(invoice({ [name]: { ...BASE_FIELDS[name], expression: 'record.amount' } })); |
| 232 | + const key = name === 'amount_home' ? 'field' : 'rateField'; |
| 233 | + expect(issues.map((i) => i.path)).toEqual([`${AT}.${key}`]); |
| 234 | + expect(issues[0]!.message).toContain('declares an `expression`'); |
| 235 | + }); |
| 236 | + }); |
| 237 | + |
| 238 | + it('refuses `homeAmount` on a `formula` amount, at `homeAmount`, judging no pointer', () => { |
| 239 | + const issues = objectIssues(invoice({ |
| 240 | + amount: { type: 'formula', label: 'Net', expression: 'record.gross * 0.9', returnType: 'currency', currencyConfig: RECORD }, |
| 241 | + gross: { type: 'currency', label: 'Gross' }, |
| 242 | + amount_rate: undefined, |
| 243 | + })); |
| 244 | + expect(issues.map((i) => i.path)).toEqual([AT]); |
| 245 | + expect(issues[0]!.code).toBe('custom'); |
| 246 | + expect(issues[0]!.message).toMatch(/^`amount\.currencyConfig\.homeAmount` is declared on a `formula` field of object `invoice`, which computes its value on read/); |
| 247 | + }); |
| 248 | +}); |
0 commit comments