@softure-ai/core 0.1.8 → 0.1.9

package/CHANGELOG.md

@@ -4,6 +4,15 @@ Newest first. Each version lists what changed for an app that uses `@softure-ai/
 production, the version gets a line `verified in: <app>@<commit>` ([docs/05](../../docs/05-adoption-playbook.md),
 "Definition of done"). Versions before the first one below are described in their GitHub Releases (`core@x.y.z`).
 
+## 0.1.9
+
+- Day arithmetic on `YYYY-MM-DD` days with documented semantics: `isCalendarDay`, `addCalendarDays`,
+  `addCalendarMonths(day, months, { endOfMonth: "clamp" | "overflow" })` (clamp by default: Jan 31 + 1 month =
+  Feb 28/29), `calendarDaysBetween` and `wholeMonthsBetween` (#312).
+- Display: `formatCalendarDay(day, locale, "long" | "medium" | "numeric")`, `formatMoney(minor, currency, locale,
+  { rounded, signed, compact })` (thousands always grouped, so pl writes `1 234,56`) and `formatPercent(basisPoints,
+  locale)`. The pinned ISO 4217 table `CURRENCY_MINOR_UNIT_DIGITS` moves here from billing (#312).
+
 ## 0.1.8
 
 - Request origins (#311): `readRequestHost`, `readRequestOrigin`, `readForwardedProto`, `parseOrigin`,

package/README.md

@@ -296,6 +296,32 @@ app's `timezone` from the config. Both throw a `RangeError` for an invalid date
 getCalendarDay(context.clock, config.timezone); // "2026-10-08"
 ```
 
+**Day arithmetic.** Work on the `YYYY-MM-DD` strings themselves, never on `Date`s at local midnight: a day
+is a calendar day, whatever DST makes of its hours. Every function throws a `RangeError` for a malformed day
+or a fractional count.
+
+| Function | Semantics |
+| --- | --- |
+| `isCalendarDay(value)` | A real day written `YYYY-MM-DD` (`2026-02-29` and `2026-1-1` are not). |
+| `addCalendarDays(day, days)` | `day` moved by whole days, negative goes back. |
+| `addCalendarMonths(day, months, { endOfMonth })` | `"clamp"` (default): a day the month lacks becomes its last day, Jan 31 + 1 = Feb 28/29. `"overflow"`: it runs on, Jan 31 + 1 = Mar 3 (2026). |
+| `calendarDaysBetween(from, to)` | `to - from` in days; negative when `to` comes first. |
+| `wholeMonthsBetween(from, to)` | The most months `n` with `addCalendarMonths(from, n)` (clamped) not after `to`: Jan 31 to Feb 28 is 1. Swapping the days turns the sign. |
+
+**Display.** One way to show days, money and percentages in every module and app, in `config.locale`:
+
+```ts
+formatCalendarDay("2026-10-04", "en"); // "October 4, 2026"; "medium": "Oct 4, 2026"; "numeric": "10/04/2026"
+formatCalendarDay(toCalendarDay(instant, config.timezone), config.locale); // an instant's day in the app's zone
+formatMoney(123456, "PLN", "en"); // "PLN 1,234.56"; pl groups four digits too
+formatMoney(-123456, "PLN", "en", { rounded: true, signed: true }); // "-PLN 1,235"; { compact: true }: "PLN 1.2K"
+formatPercent(1250, "en"); // "12.5%" (basis points, at most two fraction digits)
+```
+
+A day is formatted at UTC midnight in UTC, so no zone moves it; the Polish long style names the month in
+the genitive. `formatMoney` takes the amount in the currency's minor unit, read from the pinned ISO 4217
+table `CURRENCY_MINOR_UNIT_DIGITS` (a code outside it gets `Intl`'s digits), and always groups thousands.
+
 ## 10. Hooks
 
 `ModuleContext` is what every server function of a module receives: `{ db, clock, config }`
@@ -320,4 +346,5 @@ manifest's `privacy.exports` / `privacy.deletes` flag is true. The `privacy` mod
   are rejected.
 - Route maps mix mounted paths and redirect targets, so two modules may share a path; mount
   collisions are left to `softure doctor`.
-- No date or number formatting helpers beyond the calendar day; apps use `Intl` with `config.locale` and `config.timezone`.
+- Formatting covers days, money and percentages; times of day and other numbers use `Intl` with `config.locale` and
+  `config.timezone`.

package/dist/calendar-day.d.ts

@@ -3,4 +3,27 @@ import type { Clock } from "./clock.js";
 export declare function toCalendarDay(instant: Date, timeZone: string): string;
 /** Today's calendar day (`YYYY-MM-DD`) in `timeZone`, read from `clock`. */
 export declare function getCalendarDay(clock: Clock, timeZone: string): string;
+/** What `addCalendarMonths` does with a day the target month lacks (31 January + 1 month). */
+export type EndOfMonth = "clamp" | "overflow";
+/** Whether `value` is a real calendar day written `YYYY-MM-DD` (`2026-02-29` and `2026-1-1` are not). */
+export declare function isCalendarDay(value: unknown): value is string;
+/** `day` moved by `days` calendar days (negative goes back). Throws a `RangeError` for a malformed day or count. */
+export declare function addCalendarDays(day: string, days: number): string;
+/**
+ * `day` moved by `months` calendar months (negative goes back). A day the target month lacks is the
+ * month's last day with `endOfMonth: "clamp"` (the default: 31 January + 1 month = 28 or 29 February,
+ * as billing periods count), or runs on into the next month with `"overflow"` (3 March in 2026, as
+ * `Date` does). Throws a `RangeError` for a malformed day or count.
+ */
+export declare function addCalendarMonths(day: string, months: number, options?: {
+    readonly endOfMonth?: EndOfMonth;
+}): string;
+/** Calendar days from `from` to `to`: 1 from one day to the next, negative when `to` comes first. */
+export declare function calendarDaysBetween(from: string, to: string): number;
+/**
+ * Whole months from `from` to `to`: the most months `n` for which `addCalendarMonths(from, n)` (clamped)
+ * is not after `to`. So 31 January to 28 February is one month, as a monthly period counts it.
+ * Negative when `to` comes first: `wholeMonthsBetween(to, from)` with the sign turned.
+ */
+export declare function wholeMonthsBetween(from: string, to: string): number;
 //# sourceMappingURL=calendar-day.d.ts.map

package/dist/calendar-day.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"calendar-day.d.ts","sourceRoot":"","sources":["../src/calendar-day.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAIxC,qHAAqH;AACrH,wBAAgB,aAAa,CAAC,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAQrE;AAED,4EAA4E;AAC5E,wBAAgB,cAAc,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAErE"}
+{"version":3,"file":"calendar-day.d.ts","sourceRoot":"","sources":["../src/calendar-day.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAIxC,qHAAqH;AACrH,wBAAgB,aAAa,CAAC,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAQrE;AAED,4EAA4E;AAC5E,wBAAgB,cAAc,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAErE;AAiCD,8FAA8F;AAC9F,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,UAAU,CAAC;AAE9C,yGAAyG;AACzG,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAE7D;AAED,oHAAoH;AACpH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAIjE;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE;IAAE,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAA;CAAO,GAAG,MAAM,CAQzH;AAED,qGAAqG;AACrG,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAGpE;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAOnE"}

package/dist/calendar-day.js

@@ -29,4 +29,91 @@ function createFormatter(timeZone) {
         throw new RangeError(`toCalendarDay: "${timeZone}" is not an IANA time zone`, { cause: error });
     }
 }
+// Arithmetic on calendar days (`YYYY-MM-DD`): civil days with no time zone, so a day is a day even
+// when DST makes it 23 or 25 hours long. A day number counts days since 1970-01-01.
+const DAY_MS = 24 * 60 * 60 * 1000;
+const MONTHS_PER_YEAR = 12;
+const DAY_PATTERN = /^(\d{4})-(\d{2})-(\d{2})$/;
+/** Whether `value` is a real calendar day written `YYYY-MM-DD` (`2026-02-29` and `2026-1-1` are not). */
+export function isCalendarDay(value) {
+    return typeof value === "string" && parseCivilDate(value) !== null;
+}
+/** `day` moved by `days` calendar days (negative goes back). Throws a `RangeError` for a malformed day or count. */
+export function addCalendarDays(day, days) {
+    const operation = "addCalendarDays";
+    assertWhole(operation, days, "days");
+    return fromDayNumber(operation, toDayNumber(operation, day) + days);
+}
+/**
+ * `day` moved by `months` calendar months (negative goes back). A day the target month lacks is the
+ * month's last day with `endOfMonth: "clamp"` (the default: 31 January + 1 month = 28 or 29 February,
+ * as billing periods count), or runs on into the next month with `"overflow"` (3 March in 2026, as
+ * `Date` does). Throws a `RangeError` for a malformed day or count.
+ */
+export function addCalendarMonths(day, months, options = {}) {
+    const operation = "addCalendarMonths";
+    assertWhole(operation, months, "months");
+    const date = readCivilDate(operation, day);
+    const month = date.month + months;
+    const lastDay = new Date(utcMilliseconds({ year: date.year, month: month + 1, day: 0 })).getUTCDate();
+    const target = options.endOfMonth === "overflow" ? date.day : Math.min(date.day, lastDay);
+    return fromDayNumber(operation, utcMilliseconds({ year: date.year, month, day: target }) / DAY_MS);
+}
+/** Calendar days from `from` to `to`: 1 from one day to the next, negative when `to` comes first. */
+export function calendarDaysBetween(from, to) {
+    const operation = "calendarDaysBetween";
+    return toDayNumber(operation, to) - toDayNumber(operation, from);
+}
+/**
+ * Whole months from `from` to `to`: the most months `n` for which `addCalendarMonths(from, n)` (clamped)
+ * is not after `to`. So 31 January to 28 February is one month, as a monthly period counts it.
+ * Negative when `to` comes first: `wholeMonthsBetween(to, from)` with the sign turned.
+ */
+export function wholeMonthsBetween(from, to) {
+    const operation = "wholeMonthsBetween";
+    const start = readCivilDate(operation, from);
+    const end = readCivilDate(operation, to);
+    if (to < from)
+        return -wholeMonthsBetween(to, from);
+    const months = (end.year - start.year) * MONTHS_PER_YEAR + (end.month - start.month);
+    return addCalendarMonths(from, months) > to ? months - 1 : months;
+}
+function assertWhole(operation, count, unit) {
+    if (!Number.isSafeInteger(count))
+        throw new RangeError(`${operation}: ${String(count)} is not a whole number of ${unit}`);
+}
+/** Milliseconds of UTC midnight of a civil date; month and day may overflow, as in `Date.UTC`, for any year. */
+function utcMilliseconds({ year, month, day }) {
+    // Not `Date.UTC`: it reads years 0-99 as 1900-1999.
+    const date = new Date(0);
+    date.setUTCFullYear(year, month, day);
+    return date.getTime();
+}
+function parseCivilDate(text) {
+    const match = DAY_PATTERN.exec(text);
+    if (match === null)
+        return null;
+    const date = { year: Number(match[1]), month: Number(match[2]) - 1, day: Number(match[3]) };
+    const parsed = new Date(utcMilliseconds(date));
+    if (parsed.getUTCMonth() !== date.month || parsed.getUTCDate() !== date.day)
+        return null;
+    return date;
+}
+function readCivilDate(operation, day) {
+    const date = parseCivilDate(day);
+    if (date === null)
+        throw new RangeError(`${operation}: "${day}" is not a YYYY-MM-DD calendar day`);
+    return date;
+}
+function toDayNumber(operation, day) {
+    return utcMilliseconds(readCivilDate(operation, day)) / DAY_MS;
+}
+function fromDayNumber(operation, dayNumber) {
+    const date = new Date(dayNumber * DAY_MS);
+    const year = date.getUTCFullYear();
+    if (year < 0 || year > 9999)
+        throw new RangeError(`${operation}: the result falls outside the years 0000-9999`);
+    const pad = (value) => String(value).padStart(2, "0");
+    return `${String(year).padStart(4, "0")}-${pad(date.getUTCMonth() + 1)}-${pad(date.getUTCDate())}`;
+}
 //# sourceMappingURL=calendar-day.js.map

package/dist/calendar-day.js.map

@@ -1 +1 @@
-{"version":3,"file":"calendar-day.js","sourceRoot":"","sources":["../src/calendar-day.ts"],"names":[],"mappings":"AAIA,MAAM,UAAU,GAAG,IAAI,GAAG,EAA+B,CAAC;AAE1D,qHAAqH;AACrH,MAAM,UAAU,aAAa,CAAC,OAAa,EAAE,QAAgB;IAC3D,IAAI,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC;QACpC,MAAM,IAAI,UAAU,CAAC,6BAA6B,CAAC,CAAC;IACtD,CAAC;IACD,uGAAuG;IACvG,MAAM,KAAK,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;IAC5D,MAAM,QAAQ,GAAG,CAAC,IAAkC,EAAU,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,EAAE,KAAK,IAAI,EAAE,CAAC;IACvH,OAAO,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,IAAI,QAAQ,CAAC,OAAO,CAAC,IAAI,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;AACxF,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,cAAc,CAAC,KAAY,EAAE,QAAgB;IAC3D,OAAO,aAAa,CAAC,KAAK,CAAC,GAAG,EAAE,EAAE,QAAQ,CAAC,CAAC;AAC9C,CAAC;AAED,SAAS,YAAY,CAAC,QAAgB;IACpC,IAAI,MAAM,GAAG,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACtC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,MAAM,GAAG,eAAe,CAAC,QAAQ,CAAC,CAAC;QACnC,UAAU,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IACnC,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,eAAe,CAAC,QAAgB;IACvC,IAAI,CAAC;QACH,OAAO,IAAI,IAAI,CAAC,cAAc,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,EAAE,SAAS,EAAE,CAAC,CAAC;IAC3G,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,UAAU,CAAC,mBAAmB,QAAQ,4BAA4B,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IAClG,CAAC;AACH,CAAC"}
+{"version":3,"file":"calendar-day.js","sourceRoot":"","sources":["../src/calendar-day.ts"],"names":[],"mappings":"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"}

package/dist/currency-digits.d.ts

@@ -0,0 +1,3 @@
+/** Digits of the minor unit per accepted currency code, e.g. `PLN: 2`, `JPY: 0`, `KWD: 3`. */
+export declare const CURRENCY_MINOR_UNIT_DIGITS: Readonly<Record<string, number>>;
+//# sourceMappingURL=currency-digits.d.ts.map

package/dist/currency-digits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"currency-digits.d.ts","sourceRoot":"","sources":["../src/currency-digits.ts"],"names":[],"mappings":"AAgCA,8FAA8F;AAC9F,eAAO,MAAM,0BAA0B,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAIvE,CAAC"}

package/dist/currency-digits.js

@@ -0,0 +1,33 @@
+// The minor unit pinned for each currency SOFTURE accepts: an amount in minor units (billing's
+// `price.amount`, `formatMoney`) counts these units on every runtime, whatever the runtime's `Intl`
+// (CLDR) says. Source: ISO 4217 List One, published 2024-06-25, without fund codes, `N.A.` units
+// (metals, XDR, XTS, XXX ...) and UYW (a wage index unit), plus the two choices below. CLDR differs
+// from ISO on AFN, ALL, IRR, KPW, LAK, LBP, MMK, RSD, SOS, SYP and YER (0 instead of 2) and IQD
+// (0 instead of 3), and its HUF and TWD digits have changed between Node builds; the table follows
+// ISO, as Stripe does for all but MGA.
+/** ISO 4217 codes by the digits of their minor unit. */
+const CODES_BY_DIGITS = {
+    0: [
+        "BIF", "CLP", "DJF", "GNF", "ISK", "JPY", "KMF", "KRW", "PYG", "RWF", "UGX", "VND", "VUV", "XAF", "XOF", "XPF",
+        // Override: ISO writes 2, but one ariary is five iraimbilanja (not a decimal subunit), and CLDR
+        // and Stripe both count it without a minor unit.
+        "MGA",
+    ],
+    2: [
+        "AED", "AFN", "ALL", "AMD", "ANG", "AOA", "ARS", "AUD", "AWG", "AZN", "BAM", "BBD", "BDT", "BGN", "BMD", "BND",
+        "BOB", "BRL", "BSD", "BTN", "BWP", "BYN", "BZD", "CAD", "CDF", "CHF", "CNY", "COP", "CRC", "CUC", "CUP", "CVE",
+        "CZK", "DKK", "DOP", "DZD", "EGP", "ERN", "ETB", "EUR", "FJD", "FKP", "GBP", "GEL", "GHS", "GIP", "GMD", "GTQ",
+        "GYD", "HKD", "HNL", "HTG", "HUF", "IDR", "ILS", "INR", "IRR", "JMD", "KES", "KGS", "KHR", "KPW", "KYD", "KZT",
+        "LAK", "LBP", "LKR", "LRD", "LSL", "MAD", "MDL", "MKD", "MMK", "MNT", "MOP", "MRU", "MUR", "MVR", "MWK", "MXN",
+        "MYR", "MZN", "NAD", "NGN", "NIO", "NOK", "NPR", "NZD", "PAB", "PEN", "PGK", "PHP", "PKR", "PLN", "QAR", "RON",
+        "RSD", "RUB", "SAR", "SBD", "SCR", "SDG", "SEK", "SGD", "SHP", "SLE", "SOS", "SRD", "SSP", "STN", "SVC", "SYP",
+        "SZL", "THB", "TJS", "TMT", "TOP", "TRY", "TTD", "TWD", "TZS", "UAH", "USD", "UYU", "UZS", "VED", "VES", "WST",
+        "XCD", "YER", "ZAR", "ZMW", "ZWG",
+        // Addition: the Caribbean guilder, which replaced ANG on 2025-03-31, after the pinned list.
+        "XCG",
+    ],
+    3: ["BHD", "IQD", "JOD", "KWD", "LYD", "OMR", "TND"],
+};
+/** Digits of the minor unit per accepted currency code, e.g. `PLN: 2`, `JPY: 0`, `KWD: 3`. */
+export const CURRENCY_MINOR_UNIT_DIGITS = Object.freeze(Object.fromEntries(Object.entries(CODES_BY_DIGITS).flatMap(([digits, codes]) => codes.map((code) => [code, Number(digits)]))));
+//# sourceMappingURL=currency-digits.js.map

package/dist/currency-digits.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"currency-digits.js","sourceRoot":"","sources":["../src/currency-digits.ts"],"names":[],"mappings":"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"}

package/dist/format.d.ts

@@ -0,0 +1,23 @@
+import type { Locale } from "./i18n.js";
+/** `long`: October 4, 2026 (pl names the month in the genitive); `medium`: Oct 4, 2026; `numeric`: 10/04/2026 (pl: 04.10.2026). */
+export type CalendarDayStyle = "long" | "medium" | "numeric";
+export interface FormatMoneyOptions {
+    /** Whole units only, rounded half away from zero: PLN 1,235 for 1234.56. */
+    readonly rounded?: boolean;
+    /** A `+` before a positive amount (a `-` before a negative one is always there); zero has neither. */
+    readonly signed?: boolean;
+    /** The locale's short notation for large amounts: PLN 1.2M. */
+    readonly compact?: boolean;
+}
+/** A `YYYY-MM-DD` day as `locale` writes it. Throws a `RangeError` for a malformed day. */
+export declare function formatCalendarDay(day: string, locale: Locale, style?: CalendarDayStyle): string;
+/**
+ * An amount in the currency's minor unit (2900 PLN = PLN 29.00) in `locale`'s notation, thousands always
+ * grouped (pl writes 1 234,56 where its default would leave four digits together). The minor unit is the pinned ISO
+ * 4217 one (`CURRENCY_MINOR_UNIT_DIGITS`); a code outside the table gets `Intl`'s digits. Throws a
+ * `RangeError` for an amount that is not a whole number of minor units, or a code `Intl` refuses.
+ */
+export declare function formatMoney(minor: number, currency: string, locale: Locale, options?: FormatMoneyOptions): string;
+/** Basis points as a percentage in `locale`: 1250 is 12.5%, at most two fraction digits. Throws a `RangeError` for a non-finite value. */
+export declare function formatPercent(basisPoints: number, locale: Locale): string;
+//# sourceMappingURL=format.d.ts.map

package/dist/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../src/format.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAExC,mIAAmI;AACnI,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE7D,MAAM,WAAW,kBAAkB;IACjC,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,sGAAsG;IACtG,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAcD,2FAA2F;AAC3F,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,GAAE,gBAAyB,GAAG,MAAM,CASvG;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,kBAAuB,GAAG,MAAM,CAarH;AAED,0IAA0I;AAC1I,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAIzE"}

package/dist/format.js

@@ -0,0 +1,63 @@
+// Days, money and percentages as people read them, one way for every module and app. A calendar day
+// is formatted at UTC midnight in UTC, so neither the server's nor the reader's zone moves it.
+import { isCalendarDay } from "./calendar-day.js";
+import { CURRENCY_MINOR_UNIT_DIGITS } from "./currency-digits.js";
+const BASIS_POINTS_PER_UNIT = 10_000;
+const MAX_PERCENT_FRACTION_DIGITS = 2;
+const dayFormatters = new Map();
+const numberFormatters = new Map();
+const DAY_STYLE_OPTIONS = {
+    long: { dateStyle: "long" },
+    medium: { dateStyle: "medium" },
+    numeric: { day: "2-digit", month: "2-digit", year: "numeric" },
+};
+/** A `YYYY-MM-DD` day as `locale` writes it. Throws a `RangeError` for a malformed day. */
+export function formatCalendarDay(day, locale, style = "long") {
+    if (!isCalendarDay(day))
+        throw new RangeError(`formatCalendarDay: "${String(day)}" is not a YYYY-MM-DD calendar day`);
+    const key = `${locale}:${style}`;
+    let format = dayFormatters.get(key);
+    if (format === undefined) {
+        format = new Intl.DateTimeFormat(locale, { ...DAY_STYLE_OPTIONS[style], timeZone: "UTC" });
+        dayFormatters.set(key, format);
+    }
+    return format.format(new Date(`${day}T00:00:00Z`));
+}
+/**
+ * An amount in the currency's minor unit (2900 PLN = PLN 29.00) in `locale`'s notation, thousands always
+ * grouped (pl writes 1 234,56 where its default would leave four digits together). The minor unit is the pinned ISO
+ * 4217 one (`CURRENCY_MINOR_UNIT_DIGITS`); a code outside the table gets `Intl`'s digits. Throws a
+ * `RangeError` for an amount that is not a whole number of minor units, or a code `Intl` refuses.
+ */
+export function formatMoney(minor, currency, locale, options = {}) {
+    if (!Number.isSafeInteger(minor))
+        throw new RangeError(`formatMoney: ${String(minor)} is not a whole number of minor units`);
+    const pinned = Object.hasOwn(CURRENCY_MINOR_UNIT_DIGITS, currency) ? CURRENCY_MINOR_UNIT_DIGITS[currency] : undefined;
+    const digits = pinned ?? getNumberFormatter(locale, { style: "currency", currency }).resolvedOptions().maximumFractionDigits ?? 2;
+    const shownDigits = options.rounded === true ? 0 : digits;
+    const format = getNumberFormatter(locale, {
+        style: "currency",
+        currency,
+        useGrouping: "always",
+        signDisplay: options.signed === true ? "exceptZero" : "auto",
+        ...(options.compact === true ? { notation: "compact" } : { minimumFractionDigits: shownDigits, maximumFractionDigits: shownDigits }),
+    });
+    return format.format(minor / 10 ** digits);
+}
+/** Basis points as a percentage in `locale`: 1250 is 12.5%, at most two fraction digits. Throws a `RangeError` for a non-finite value. */
+export function formatPercent(basisPoints, locale) {
+    if (!Number.isFinite(basisPoints))
+        throw new RangeError(`formatPercent: ${String(basisPoints)} is not a finite number of basis points`);
+    const format = getNumberFormatter(locale, { style: "percent", maximumFractionDigits: MAX_PERCENT_FRACTION_DIGITS });
+    return format.format(basisPoints / BASIS_POINTS_PER_UNIT);
+}
+function getNumberFormatter(locale, options) {
+    const key = `${locale}:${JSON.stringify(options)}`;
+    let format = numberFormatters.get(key);
+    if (format === undefined) {
+        format = new Intl.NumberFormat(locale, options);
+        numberFormatters.set(key, format);
+    }
+    return format;
+}
+//# sourceMappingURL=format.js.map

package/dist/format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../src/format.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,4 +1,6 @@
-export { getCalendarDay, toCalendarDay } from "./calendar-day.js";
+export { addCalendarDays, addCalendarMonths, calendarDaysBetween, getCalendarDay, isCalendarDay, toCalendarDay, wholeMonthsBetween, type EndOfMonth, } from "./calendar-day.js";
+export { CURRENCY_MINOR_UNIT_DIGITS } from "./currency-digits.js";
+export { formatCalendarDay, formatMoney, formatPercent, type CalendarDayStyle, type FormatMoneyOptions } from "./format.js";
 export { createTestClock, systemClock, type Clock, type TestClock } from "./clock.js";
 export { formatMessage, getMessage, isLocale, LOCALES, mergeMessages, selectPlural, type DeepPartial, type Dictionaries, type Locale, type MessageOverrides, type MessageTree, type PluralForms, } from "./i18n.js";
 export { coreMessages, type CoreMessages } from "./messages/index.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClE,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,KAAK,KAAK,EAAE,KAAK,SAAS,EAAE,MAAM,YAAY,CAAC;AACtF,OAAO,EACL,aAAa,EACb,UAAU,EACV,QAAQ,EACR,OAAO,EACP,aAAa,EACb,YAAY,EACZ,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,MAAM,EACX,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAChB,KAAK,WAAW,GACjB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,YAAY,EAAE,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACtE,OAAO,EAAE,GAAG,EAAE,EAAE,EAAE,KAAK,GAAG,EAAE,KAAK,SAAS,EAAE,KAAK,EAAE,EAAE,KAAK,MAAM,EAAE,MAAM,aAAa,CAAC;AACtF,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,aAAa,EAAE,WAAW,EAAE,SAAS,EAAE,KAAK,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAC7H,OAAO,EACL,mBAAmB,EACnB,SAAS,EACT,yBAAyB,EACzB,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC1B,KAAK,0BAA0B,EAC/B,KAAK,cAAc,EACnB,KAAK,mBAAmB,GACzB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACjE,OAAO,EAAE,oBAAoB,EAAE,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AAC1E,OAAO,EACL,YAAY,EACZ,oBAAoB,EACpB,YAAY,EACZ,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,UAAU,EACf,KAAK,kBAAkB,EACvB,KAAK,aAAa,GACnB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,iBAAiB,EACjB,WAAW,EACX,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EACjB,gBAAgB,EAChB,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,uBAAuB,GAC7B,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,mBAAmB,EAAE,WAAW,EAAE,KAAK,eAAe,EAAE,KAAK,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AACvG,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,KAAK,YAAY,EAAE,KAAK,aAAa,EAAE,MAAM,eAAe,CAAC;AACpG,OAAO,EAAE,SAAS,EAAE,iBAAiB,EAAE,cAAc,EAAE,KAAK,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,eAAe,EACf,iBAAiB,EACjB,mBAAmB,EACnB,cAAc,EACd,aAAa,EACb,aAAa,EACb,kBAAkB,EAClB,KAAK,UAAU,GAChB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,0BAA0B,EAAE,MAAM,sBAAsB,CAAC;AAClE,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,aAAa,EAAE,KAAK,gBAAgB,EAAE,KAAK,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAC5H,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,KAAK,KAAK,EAAE,KAAK,SAAS,EAAE,MAAM,YAAY,CAAC;AACtF,OAAO,EACL,aAAa,EACb,UAAU,EACV,QAAQ,EACR,OAAO,EACP,aAAa,EACb,YAAY,EACZ,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,MAAM,EACX,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAChB,KAAK,WAAW,GACjB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,YAAY,EAAE,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACtE,OAAO,EAAE,GAAG,EAAE,EAAE,EAAE,KAAK,GAAG,EAAE,KAAK,SAAS,EAAE,KAAK,EAAE,EAAE,KAAK,MAAM,EAAE,MAAM,aAAa,CAAC;AACtF,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,aAAa,EAAE,WAAW,EAAE,SAAS,EAAE,KAAK,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAC7H,OAAO,EACL,mBAAmB,EACnB,SAAS,EACT,yBAAyB,EACzB,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC1B,KAAK,0BAA0B,EAC/B,KAAK,cAAc,EACnB,KAAK,mBAAmB,GACzB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACjE,OAAO,EAAE,oBAAoB,EAAE,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AAC1E,OAAO,EACL,YAAY,EACZ,oBAAoB,EACpB,YAAY,EACZ,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,UAAU,EACf,KAAK,kBAAkB,EACvB,KAAK,aAAa,GACnB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,iBAAiB,EACjB,WAAW,EACX,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EACjB,gBAAgB,EAChB,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,uBAAuB,GAC7B,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,mBAAmB,EAAE,WAAW,EAAE,KAAK,eAAe,EAAE,KAAK,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AACvG,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,KAAK,YAAY,EAAE,KAAK,aAAa,EAAE,MAAM,eAAe,CAAC;AACpG,OAAO,EAAE,SAAS,EAAE,iBAAiB,EAAE,cAAc,EAAE,KAAK,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -1,6 +1,8 @@
 // Public API of @softure-ai/core: the contract every SOFTURE module stands on
 // (docs/02-module-standard.md). The Next.js registry is a separate entry: `@softure-ai/core/next`.
-export { getCalendarDay, toCalendarDay } from "./calendar-day.js";
+export { addCalendarDays, addCalendarMonths, calendarDaysBetween, getCalendarDay, isCalendarDay, toCalendarDay, wholeMonthsBetween, } from "./calendar-day.js";
+export { CURRENCY_MINOR_UNIT_DIGITS } from "./currency-digits.js";
+export { formatCalendarDay, formatMoney, formatPercent } from "./format.js";
 export { createTestClock, systemClock } from "./clock.js";
 export { formatMessage, getMessage, isLocale, LOCALES, mergeMessages, selectPlural, } from "./i18n.js";
 export { coreMessages } from "./messages/index.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,mGAAmG;AACnG,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClE,OAAO,EAAE,eAAe,EAAE,WAAW,EAA8B,MAAM,YAAY,CAAC;AACtF,OAAO,EACL,aAAa,EACb,UAAU,EACV,QAAQ,EACR,OAAO,EACP,aAAa,EACb,YAAY,GAOb,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,YAAY,EAAqB,MAAM,qBAAqB,CAAC;AACtE,OAAO,EAAE,GAAG,EAAE,EAAE,EAAkD,MAAM,aAAa,CAAC;AACtF,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,aAAa,EAAE,WAAW,EAAE,SAAS,EAAsB,MAAM,iBAAiB,CAAC;AAC7H,OAAO,EACL,mBAAmB,EACnB,SAAS,EACT,yBAAyB,GAQ1B,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACjE,OAAO,EAAE,oBAAoB,EAAuB,MAAM,eAAe,CAAC;AAC1E,OAAO,EACL,YAAY,EACZ,oBAAoB,EACpB,YAAY,GAUb,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,iBAAiB,EACjB,WAAW,EACX,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EACjB,gBAAgB,GAIjB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,mBAAmB,EAAE,WAAW,EAAuC,MAAM,gBAAgB,CAAC;AACvG,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAyC,MAAM,eAAe,CAAC;AACpG,OAAO,EAAE,SAAS,EAAE,iBAAiB,EAAE,cAAc,EAAmC,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,mGAAmG;AACnG,OAAO,EACL,eAAe,EACf,iBAAiB,EACjB,mBAAmB,EACnB,cAAc,EACd,aAAa,EACb,aAAa,EACb,kBAAkB,GAEnB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,0BAA0B,EAAE,MAAM,sBAAsB,CAAC;AAClE,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,aAAa,EAAkD,MAAM,aAAa,CAAC;AAC5H,OAAO,EAAE,eAAe,EAAE,WAAW,EAA8B,MAAM,YAAY,CAAC;AACtF,OAAO,EACL,aAAa,EACb,UAAU,EACV,QAAQ,EACR,OAAO,EACP,aAAa,EACb,YAAY,GAOb,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,YAAY,EAAqB,MAAM,qBAAqB,CAAC;AACtE,OAAO,EAAE,GAAG,EAAE,EAAE,EAAkD,MAAM,aAAa,CAAC;AACtF,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,aAAa,EAAE,WAAW,EAAE,SAAS,EAAsB,MAAM,iBAAiB,CAAC;AAC7H,OAAO,EACL,mBAAmB,EACnB,SAAS,EACT,yBAAyB,GAQ1B,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACjE,OAAO,EAAE,oBAAoB,EAAuB,MAAM,eAAe,CAAC;AAC1E,OAAO,EACL,YAAY,EACZ,oBAAoB,EACpB,YAAY,GAUb,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,iBAAiB,EACjB,WAAW,EACX,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EACjB,gBAAgB,GAIjB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,mBAAmB,EAAE,WAAW,EAAuC,MAAM,gBAAgB,CAAC;AACvG,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAyC,MAAM,eAAe,CAAC;AACpG,OAAO,EAAE,SAAS,EAAE,iBAAiB,EAAE,cAAc,EAAmC,MAAM,oBAAoB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softure-ai/core",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "The SOFTURE AI module contract: app config, module definitions, Result, Clock and messages.",
   "license": "MIT",
   "type": "module",

package/src/calendar-day.ts

@@ -36,3 +36,107 @@ function createFormatter(timeZone: string): Intl.DateTimeFormat {
     throw new RangeError(`toCalendarDay: "${timeZone}" is not an IANA time zone`, { cause: error });
   }
 }
+
+// Arithmetic on calendar days (`YYYY-MM-DD`): civil days with no time zone, so a day is a day even
+// when DST makes it 23 or 25 hours long. A day number counts days since 1970-01-01.
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const MONTHS_PER_YEAR = 12;
+const DAY_PATTERN = /^(\d{4})-(\d{2})-(\d{2})$/;
+
+interface CivilDate {
+  readonly year: number;
+  /** 0-based, as `Date` counts months. */
+  readonly month: number;
+  readonly day: number;
+}
+
+/** What `addCalendarMonths` does with a day the target month lacks (31 January + 1 month). */
+export type EndOfMonth = "clamp" | "overflow";
+
+/** Whether `value` is a real calendar day written `YYYY-MM-DD` (`2026-02-29` and `2026-1-1` are not). */
+export function isCalendarDay(value: unknown): value is string {
+  return typeof value === "string" && parseCivilDate(value) !== null;
+}
+
+/** `day` moved by `days` calendar days (negative goes back). Throws a `RangeError` for a malformed day or count. */
+export function addCalendarDays(day: string, days: number): string {
+  const operation = "addCalendarDays";
+  assertWhole(operation, days, "days");
+  return fromDayNumber(operation, toDayNumber(operation, day) + days);
+}
+
+/**
+ * `day` moved by `months` calendar months (negative goes back). A day the target month lacks is the
+ * month's last day with `endOfMonth: "clamp"` (the default: 31 January + 1 month = 28 or 29 February,
+ * as billing periods count), or runs on into the next month with `"overflow"` (3 March in 2026, as
+ * `Date` does). Throws a `RangeError` for a malformed day or count.
+ */
+export function addCalendarMonths(day: string, months: number, options: { readonly endOfMonth?: EndOfMonth } = {}): string {
+  const operation = "addCalendarMonths";
+  assertWhole(operation, months, "months");
+  const date = readCivilDate(operation, day);
+  const month = date.month + months;
+  const lastDay = new Date(utcMilliseconds({ year: date.year, month: month + 1, day: 0 })).getUTCDate();
+  const target = options.endOfMonth === "overflow" ? date.day : Math.min(date.day, lastDay);
+  return fromDayNumber(operation, utcMilliseconds({ year: date.year, month, day: target }) / DAY_MS);
+}
+
+/** Calendar days from `from` to `to`: 1 from one day to the next, negative when `to` comes first. */
+export function calendarDaysBetween(from: string, to: string): number {
+  const operation = "calendarDaysBetween";
+  return toDayNumber(operation, to) - toDayNumber(operation, from);
+}
+
+/**
+ * Whole months from `from` to `to`: the most months `n` for which `addCalendarMonths(from, n)` (clamped)
+ * is not after `to`. So 31 January to 28 February is one month, as a monthly period counts it.
+ * Negative when `to` comes first: `wholeMonthsBetween(to, from)` with the sign turned.
+ */
+export function wholeMonthsBetween(from: string, to: string): number {
+  const operation = "wholeMonthsBetween";
+  const start = readCivilDate(operation, from);
+  const end = readCivilDate(operation, to);
+  if (to < from) return -wholeMonthsBetween(to, from);
+  const months = (end.year - start.year) * MONTHS_PER_YEAR + (end.month - start.month);
+  return addCalendarMonths(from, months) > to ? months - 1 : months;
+}
+
+function assertWhole(operation: string, count: number, unit: string): void {
+  if (!Number.isSafeInteger(count)) throw new RangeError(`${operation}: ${String(count)} is not a whole number of ${unit}`);
+}
+
+/** Milliseconds of UTC midnight of a civil date; month and day may overflow, as in `Date.UTC`, for any year. */
+function utcMilliseconds({ year, month, day }: CivilDate): number {
+  // Not `Date.UTC`: it reads years 0-99 as 1900-1999.
+  const date = new Date(0);
+  date.setUTCFullYear(year, month, day);
+  return date.getTime();
+}
+
+function parseCivilDate(text: string): CivilDate | null {
+  const match = DAY_PATTERN.exec(text);
+  if (match === null) return null;
+  const date = { year: Number(match[1]), month: Number(match[2]) - 1, day: Number(match[3]) };
+  const parsed = new Date(utcMilliseconds(date));
+  if (parsed.getUTCMonth() !== date.month || parsed.getUTCDate() !== date.day) return null;
+  return date;
+}
+
+function readCivilDate(operation: string, day: string): CivilDate {
+  const date = parseCivilDate(day);
+  if (date === null) throw new RangeError(`${operation}: "${day}" is not a YYYY-MM-DD calendar day`);
+  return date;
+}
+
+function toDayNumber(operation: string, day: string): number {
+  return utcMilliseconds(readCivilDate(operation, day)) / DAY_MS;
+}
+
+function fromDayNumber(operation: string, dayNumber: number): string {
+  const date = new Date(dayNumber * DAY_MS);
+  const year = date.getUTCFullYear();
+  if (year < 0 || year > 9999) throw new RangeError(`${operation}: the result falls outside the years 0000-9999`);
+  const pad = (value: number): string => String(value).padStart(2, "0");
+  return `${String(year).padStart(4, "0")}-${pad(date.getUTCMonth() + 1)}-${pad(date.getUTCDate())}`;
+}

package/src/currency-digits.ts

@@ -0,0 +1,38 @@
+// The minor unit pinned for each currency SOFTURE accepts: an amount in minor units (billing's
+// `price.amount`, `formatMoney`) counts these units on every runtime, whatever the runtime's `Intl`
+// (CLDR) says. Source: ISO 4217 List One, published 2024-06-25, without fund codes, `N.A.` units
+// (metals, XDR, XTS, XXX ...) and UYW (a wage index unit), plus the two choices below. CLDR differs
+// from ISO on AFN, ALL, IRR, KPW, LAK, LBP, MMK, RSD, SOS, SYP and YER (0 instead of 2) and IQD
+// (0 instead of 3), and its HUF and TWD digits have changed between Node builds; the table follows
+// ISO, as Stripe does for all but MGA.
+
+/** ISO 4217 codes by the digits of their minor unit. */
+const CODES_BY_DIGITS: Readonly<Record<0 | 2 | 3, readonly string[]>> = {
+  0: [
+    "BIF", "CLP", "DJF", "GNF", "ISK", "JPY", "KMF", "KRW", "PYG", "RWF", "UGX", "VND", "VUV", "XAF", "XOF", "XPF",
+    // Override: ISO writes 2, but one ariary is five iraimbilanja (not a decimal subunit), and CLDR
+    // and Stripe both count it without a minor unit.
+    "MGA",
+  ],
+  2: [
+    "AED", "AFN", "ALL", "AMD", "ANG", "AOA", "ARS", "AUD", "AWG", "AZN", "BAM", "BBD", "BDT", "BGN", "BMD", "BND",
+    "BOB", "BRL", "BSD", "BTN", "BWP", "BYN", "BZD", "CAD", "CDF", "CHF", "CNY", "COP", "CRC", "CUC", "CUP", "CVE",
+    "CZK", "DKK", "DOP", "DZD", "EGP", "ERN", "ETB", "EUR", "FJD", "FKP", "GBP", "GEL", "GHS", "GIP", "GMD", "GTQ",
+    "GYD", "HKD", "HNL", "HTG", "HUF", "IDR", "ILS", "INR", "IRR", "JMD", "KES", "KGS", "KHR", "KPW", "KYD", "KZT",
+    "LAK", "LBP", "LKR", "LRD", "LSL", "MAD", "MDL", "MKD", "MMK", "MNT", "MOP", "MRU", "MUR", "MVR", "MWK", "MXN",
+    "MYR", "MZN", "NAD", "NGN", "NIO", "NOK", "NPR", "NZD", "PAB", "PEN", "PGK", "PHP", "PKR", "PLN", "QAR", "RON",
+    "RSD", "RUB", "SAR", "SBD", "SCR", "SDG", "SEK", "SGD", "SHP", "SLE", "SOS", "SRD", "SSP", "STN", "SVC", "SYP",
+    "SZL", "THB", "TJS", "TMT", "TOP", "TRY", "TTD", "TWD", "TZS", "UAH", "USD", "UYU", "UZS", "VED", "VES", "WST",
+    "XCD", "YER", "ZAR", "ZMW", "ZWG",
+    // Addition: the Caribbean guilder, which replaced ANG on 2025-03-31, after the pinned list.
+    "XCG",
+  ],
+  3: ["BHD", "IQD", "JOD", "KWD", "LYD", "OMR", "TND"],
+};
+
+/** Digits of the minor unit per accepted currency code, e.g. `PLN: 2`, `JPY: 0`, `KWD: 3`. */
+export const CURRENCY_MINOR_UNIT_DIGITS: Readonly<Record<string, number>> = Object.freeze(
+  Object.fromEntries(
+    Object.entries(CODES_BY_DIGITS).flatMap(([digits, codes]) => codes.map((code) => [code, Number(digits)] as const)),
+  ),
+);

package/src/format.ts

@@ -0,0 +1,79 @@
+// Days, money and percentages as people read them, one way for every module and app. A calendar day
+// is formatted at UTC midnight in UTC, so neither the server's nor the reader's zone moves it.
+import { isCalendarDay } from "./calendar-day.js";
+import { CURRENCY_MINOR_UNIT_DIGITS } from "./currency-digits.js";
+import type { Locale } from "./i18n.js";
+
+/** `long`: October 4, 2026 (pl names the month in the genitive); `medium`: Oct 4, 2026; `numeric`: 10/04/2026 (pl: 04.10.2026). */
+export type CalendarDayStyle = "long" | "medium" | "numeric";
+
+export interface FormatMoneyOptions {
+  /** Whole units only, rounded half away from zero: PLN 1,235 for 1234.56. */
+  readonly rounded?: boolean;
+  /** A `+` before a positive amount (a `-` before a negative one is always there); zero has neither. */
+  readonly signed?: boolean;
+  /** The locale's short notation for large amounts: PLN 1.2M. */
+  readonly compact?: boolean;
+}
+
+const BASIS_POINTS_PER_UNIT = 10_000;
+const MAX_PERCENT_FRACTION_DIGITS = 2;
+
+const dayFormatters = new Map<string, Intl.DateTimeFormat>();
+const numberFormatters = new Map<string, Intl.NumberFormat>();
+
+const DAY_STYLE_OPTIONS: Readonly<Record<CalendarDayStyle, Intl.DateTimeFormatOptions>> = {
+  long: { dateStyle: "long" },
+  medium: { dateStyle: "medium" },
+  numeric: { day: "2-digit", month: "2-digit", year: "numeric" },
+};
+
+/** A `YYYY-MM-DD` day as `locale` writes it. Throws a `RangeError` for a malformed day. */
+export function formatCalendarDay(day: string, locale: Locale, style: CalendarDayStyle = "long"): string {
+  if (!isCalendarDay(day)) throw new RangeError(`formatCalendarDay: "${String(day)}" is not a YYYY-MM-DD calendar day`);
+  const key = `${locale}:${style}`;
+  let format = dayFormatters.get(key);
+  if (format === undefined) {
+    format = new Intl.DateTimeFormat(locale, { ...DAY_STYLE_OPTIONS[style], timeZone: "UTC" });
+    dayFormatters.set(key, format);
+  }
+  return format.format(new Date(`${day}T00:00:00Z`));
+}
+
+/**
+ * An amount in the currency's minor unit (2900 PLN = PLN 29.00) in `locale`'s notation, thousands always
+ * grouped (pl writes 1 234,56 where its default would leave four digits together). The minor unit is the pinned ISO
+ * 4217 one (`CURRENCY_MINOR_UNIT_DIGITS`); a code outside the table gets `Intl`'s digits. Throws a
+ * `RangeError` for an amount that is not a whole number of minor units, or a code `Intl` refuses.
+ */
+export function formatMoney(minor: number, currency: string, locale: Locale, options: FormatMoneyOptions = {}): string {
+  if (!Number.isSafeInteger(minor)) throw new RangeError(`formatMoney: ${String(minor)} is not a whole number of minor units`);
+  const pinned = Object.hasOwn(CURRENCY_MINOR_UNIT_DIGITS, currency) ? CURRENCY_MINOR_UNIT_DIGITS[currency] : undefined;
+  const digits = pinned ?? getNumberFormatter(locale, { style: "currency", currency }).resolvedOptions().maximumFractionDigits ?? 2;
+  const shownDigits = options.rounded === true ? 0 : digits;
+  const format = getNumberFormatter(locale, {
+    style: "currency",
+    currency,
+    useGrouping: "always",
+    signDisplay: options.signed === true ? "exceptZero" : "auto",
+    ...(options.compact === true ? { notation: "compact" } : { minimumFractionDigits: shownDigits, maximumFractionDigits: shownDigits }),
+  });
+  return format.format(minor / 10 ** digits);
+}
+
+/** Basis points as a percentage in `locale`: 1250 is 12.5%, at most two fraction digits. Throws a `RangeError` for a non-finite value. */
+export function formatPercent(basisPoints: number, locale: Locale): string {
+  if (!Number.isFinite(basisPoints)) throw new RangeError(`formatPercent: ${String(basisPoints)} is not a finite number of basis points`);
+  const format = getNumberFormatter(locale, { style: "percent", maximumFractionDigits: MAX_PERCENT_FRACTION_DIGITS });
+  return format.format(basisPoints / BASIS_POINTS_PER_UNIT);
+}
+
+function getNumberFormatter(locale: Locale, options: Intl.NumberFormatOptions): Intl.NumberFormat {
+  const key = `${locale}:${JSON.stringify(options)}`;
+  let format = numberFormatters.get(key);
+  if (format === undefined) {
+    format = new Intl.NumberFormat(locale, options);
+    numberFormatters.set(key, format);
+  }
+  return format;
+}

package/src/index.ts

@@ -1,6 +1,17 @@
 // Public API of @softure-ai/core: the contract every SOFTURE module stands on
 // (docs/02-module-standard.md). The Next.js registry is a separate entry: `@softure-ai/core/next`.
-export { getCalendarDay, toCalendarDay } from "./calendar-day.js";
+export {
+  addCalendarDays,
+  addCalendarMonths,
+  calendarDaysBetween,
+  getCalendarDay,
+  isCalendarDay,
+  toCalendarDay,
+  wholeMonthsBetween,
+  type EndOfMonth,
+} from "./calendar-day.js";
+export { CURRENCY_MINOR_UNIT_DIGITS } from "./currency-digits.js";
+export { formatCalendarDay, formatMoney, formatPercent, type CalendarDayStyle, type FormatMoneyOptions } from "./format.js";
 export { createTestClock, systemClock, type Clock, type TestClock } from "./clock.js";
 export {
   formatMessage,