Skip to content

Commit 3a39df5

Browse files
committed
feat(spec): currencyConfig.homeAmount: { field, rateDate, rateField } on a record-mode amount
A `record`-mode amount declares, by three required pointers into the same object, where the engine stores it converted into the home currency, which document date picks the rate, and where the rate used is stored (ADR-0144 D5). - `CurrencyConfigSchema` gains `homeAmount`, a closed shape whose three pointers are required and non-empty; it is refused outside `record`. - `ObjectSchema`'s superRefine gains `refuseDishonestHomeAmount`: the amount is a stored `currency` field; `field` names another `dynamic`-mode `currency` field no other amount stores into; `rateDate` a `date` / `datetime` field; `rateField` a `number` field, shared only by amounts with the same code field and document date. The home and rate fields declare `readonly: true` and no `expression`. Each refusal is located at its pointer and carries a remedy and the object's candidates. - ADR-0144 anchors on field.zod.ts and object.zod.ts gain the D5 invariant. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017ihL2fi9zfJhUTubyJYb6V
1 parent 549203d commit 3a39df5

5 files changed

Lines changed: 528 additions & 5 deletions

File tree

Lines changed: 248 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,248 @@
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

Comments
 (0)