@meantjs/format 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 The five Candid Profile library packages (`@meantjs/profile`, `/format`, `/consent`, `/tools`, `/reconcile`) release together under one version and pin each other exactly; a version appears here even when this package did not change. Release steps: `docs/releasing.md` in the repository.
 
+## 0.4.0 — 2026-10-30
+
+No changes in this package.
+
+## 0.3.0 — 2026-10-29
+
+- `timestamp` takes `threshold` with `message`, and `labels` (spec §5.3, §15.9, D-055): `displayTimestamp` shows a
+  labelled value as its words, and a value at or above the threshold as the message ("Never"), never as a date.
+  Parsing is unchanged. The two come together, with no default word (`E_ARG`).
+- `formatterFor(node, { token })`: an `amount` whose `token` names its token by a field takes that token's decimals
+  and symbol from the caller; without them it is `E_REF_UNRESOLVED`.
+
 ## 0.2.0 — 2026-10-28
 
 - EVM integer types (spec §15, D-054): `amount` on `uint8`…`uint256` and `int8`…`int256`, `timestamp` and `duration`

package/README.md

@@ -21,6 +21,10 @@ npm install @meantjs/format
   works like a Candid one. `amount` takes `uint8`…`uint256` and `int8`…`int256`, `timestamp` and `duration`
   `uint32`…`uint256` and `int64`…`int256`, each with the bounds of its bits; `bytes` takes `bytes` and `bytesN`
   (exactly N bytes). `amount`'s `threshold` and `message` show a value at or above the threshold as `Unlimited USDC`.
+- **Words for times** (spec §5.3, §15.9): `timestamp`'s `labels` show exact values as words, and `threshold` with
+  `message` a value at or above it ("Never" for a deadline of `uint256` max, which is no date). Display only.
+- **An amount in a named token** (spec §15.9): an `amount` whose `token` names its token by a field takes that token's
+  decimals and symbol from the caller, `formatterFor(node, { token: { decimals: 6, symbol: "USDC" } })`.
 
 ```sh
 npm test -w packages/format          # or: npm test at the repo root

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meantjs/format",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Exact value conversion for Candid Profile value tags (amount, timestamp, duration, account, subaccount, bytes): parse human input, display canonical text, never round.",
   "license": "Apache-2.0",
   "repository": {

package/src/amount.mjs

@@ -30,23 +30,29 @@ export function checkSymbol(symbol) {
   return symbol;
 }
 
-/** @returns {bigint | undefined} a validated threshold: a canonical decimal integer string or a bigint, not negative */
-export function checkThreshold(threshold) {
+/**
+ * @param {string} [what]  how errors name the argument: "amount" (base units), or "timestamp" (the tagged unit)
+ * @returns {bigint | undefined} a validated threshold: a canonical decimal integer string or a bigint, not negative
+ */
+export function checkThreshold(threshold, what = "amount") {
   if (threshold === undefined || threshold === null) return undefined;
   if (typeof threshold === "bigint" ? threshold < 0n : typeof threshold !== "string" || !/^(?:0|[1-9][0-9]{0,77})$/.test(threshold)) {
-    fail(CODES.ARG, `amount threshold must be a decimal string of base units (0 or more, at most 78 digits) or a bigint, got ${typeof threshold === "string" ? JSON.stringify(threshold) : String(threshold)}`);
+    fail(CODES.ARG, `${what} threshold must be a decimal string of ${what === "amount" ? "base units" : "the tagged unit"} (0 or more, at most 78 digits) or a bigint, got ${typeof threshold === "string" ? JSON.stringify(threshold) : String(threshold)}`);
   }
   return BigInt(threshold);
 }
 
-/** @returns {string | undefined} a validated threshold message: 1 to 32 characters, nothing invisible */
-export function checkMessage(message) {
+/**
+ * @param {string} [what]  how errors name the text: "amount message", "timestamp message", a timestamp label
+ * @returns {string | undefined} a validated threshold message: 1 to 32 characters, nothing invisible
+ */
+export function checkMessage(message, what = "amount message") {
   if (message === undefined || message === null) return undefined;
-  if (typeof message !== "string") fail(CODES.ARG, `amount message must be a string, got ${typeof message}`);
+  if (typeof message !== "string") fail(CODES.ARG, `${what} must be a string, got ${typeof message}`);
   const n = [...message].length;
-  if (n < 1 || n > 32) fail(CODES.ARG, `amount message must be 1 to 32 characters, got ${n}`);
+  if (n < 1 || n > 32) fail(CODES.ARG, `${what} must be 1 to 32 characters, got ${n}`);
   if (message !== message.trim() || UNSAFE_DISPLAY_CHAR.test(message) || !message.isWellFormed()) {
-    fail(CODES.ARG, `amount message ${JSON.stringify(message)} has surrounding whitespace, control or invisible characters`);
+    fail(CODES.ARG, `${what} ${JSON.stringify(message)} has surrounding whitespace, control or invisible characters`);
   }
   return message;
 }

package/src/formatter.mjs

@@ -7,7 +7,7 @@
 
 import { CODES, FormatError, fail } from "./errors.mjs";
 import { AMOUNT_TYPES, DEFAULT_THRESHOLD_MESSAGE, checkDecimals, checkMessage, checkSymbol, checkThreshold, displayAmount, parseAmount } from "./amount.mjs";
-import { TIME_TYPES, displayDuration, displayTimestamp, parseDuration, parseTimestamp, unitFactor } from "./time.mjs";
+import { TIME_TYPES, checkTimeLabels, displayDuration, displayTimestamp, parseDuration, parseTimestamp, unitFactor } from "./time.mjs";
 import { displayAccount, parseAccount } from "./account.mjs";
 import { displaySubaccount, parseSubaccount } from "./subaccount.mjs";
 import { BYTES_ENCODINGS, checkMaxLen, displayBytes, parseBytes } from "./bytes.mjs";
@@ -65,13 +65,15 @@ function requireUnit(unit, tag) {
 
 /**
  * @param {{ candid: string, tags?: Record<string, { args?: Record<string, unknown> }> }} node
- * @param {{ refs?: Record<string, unknown>, now?: bigint }} [options]
+ * @param {{ refs?: Record<string, unknown>, now?: bigint, token?: { decimals: number | bigint | string, symbol?: string } }} [options]
  *   `refs`: resolved dynamic values keyed by their `from` string, for example
  *   `{ "query:icrc1_decimals": 8, "query:icrc1_symbol": "ICP" }`.
  *   `now`: default clock (nanoseconds, bigint) for relative timestamps; `parse(input, { now })` overrides it.
+ *   `token`: for an amount whose `token` argument names the token by a field (spec section 15.9), the decimals and
+ *   symbol of the token that field holds in this value; the caller reads them, as it resolves `refs`.
  * @returns {Formatter | null}  null when the position has no value tag (render it as Candid text, spec §6)
  */
-export function formatterFor(node, { refs = {}, now: defaultNow } = {}) {
+export function formatterFor(node, { refs = {}, now: defaultNow, token } = {}) {
   if (node !== null && typeof node === "object" && node.candid === undefined && typeof node.abi === "string") node = { ...node, candid: node.abi }; // an EVM position (spec section 15)
   if (node === null || typeof node !== "object" || typeof node.candid !== "string") fail(CODES.TYPE, "node must be a resolved-form position with a `candid` type (or an EVM position's `abi` type)");
   const tags = node.tags ?? {};
@@ -88,14 +90,27 @@ export function formatterFor(node, { refs = {}, now: defaultNow } = {}) {
   switch (tag) {
     case "amount": {
       requireCandid(node, AMOUNT_TYPES, tag);
-      if (raw.decimals === undefined) fail(CODES.ARG, "the amount tag needs decimals");
-      const decimals = checkDecimals(arg("decimals"));
-      const symbol = checkSymbol(arg("symbol"));
+      let decimals;
+      let symbol;
+      if (raw.token !== undefined) {
+        // The token is the one a field of the value names (spec section 15.9): its metadata comes with the value.
+        if (typeof raw.token !== "string" || raw.token === "") fail(CODES.ARG, "amount token must be a relative path to an address");
+        if (raw.decimals !== undefined || raw.symbol !== undefined) fail(CODES.ARG, "an amount with a token takes that token's decimals and symbol, not its own");
+        if (token === undefined || token === null || typeof token !== "object") {
+          fail(CODES.REF_UNRESOLVED, `amount.token: the amount is in the token at ${JSON.stringify(raw.token)}; pass that token's decimals and symbol as \`token\``);
+        }
+        decimals = checkDecimals(token.decimals);
+        symbol = checkSymbol(token.symbol);
+      } else {
+        if (raw.decimals === undefined) fail(CODES.ARG, "the amount tag needs decimals");
+        decimals = checkDecimals(arg("decimals"));
+        symbol = checkSymbol(arg("symbol"));
+      }
       const threshold = checkThreshold(raw.threshold);
       const message = checkMessage(raw.message);
       if (message !== undefined && threshold === undefined) fail(CODES.ARG, "amount message needs a threshold");
       const o = { decimals, symbol, candid: node.candid, threshold, message };
-      args = { decimals, symbol, ...(threshold === undefined ? {} : { threshold: threshold.toString(), message: message ?? DEFAULT_THRESHOLD_MESSAGE }) };
+      args = { decimals, symbol, ...(raw.token === undefined ? {} : { token: raw.token }), ...(threshold === undefined ? {} : { threshold: threshold.toString(), message: message ?? DEFAULT_THRESHOLD_MESSAGE }) };
       parse = (input) => parseAmount(input, o);
       display = (value) => displayAmount(value, o);
       break;
@@ -104,10 +119,20 @@ export function formatterFor(node, { refs = {}, now: defaultNow } = {}) {
       requireCandid(node, TIME_TYPES, tag);
       if (raw.epoch !== undefined && raw.epoch !== "unix") fail(CODES.ARG, `timestamp epoch must be "unix", got ${JSON.stringify(raw.epoch)}`);
       const unit = requireUnit(arg("unit"), tag);
+      const threshold = checkThreshold(raw.threshold, "timestamp");
+      const message = checkMessage(raw.message, "timestamp message");
+      if ((threshold === undefined) !== (message === undefined)) fail(CODES.ARG, "a timestamp threshold and its message go together: give both or neither");
+      const labels = checkTimeLabels(raw.labels);
       const o = { unit, candid: node.candid };
-      args = { unit, epoch: "unix" };
+      const shown = { ...o, threshold, message, labels: raw.labels };
+      args = {
+        unit,
+        epoch: "unix",
+        ...(threshold === undefined ? {} : { threshold: threshold.toString(), message }),
+        ...(labels === undefined ? {} : { labels: Object.fromEntries([...labels].map(([k, v]) => [k.toString(), v])) }),
+      };
       parse = (input, ctx = {}) => parseTimestamp(input, { ...o, now: ctx.now ?? defaultNow });
-      display = (value) => displayTimestamp(value, o);
+      display = (value) => displayTimestamp(value, shown);
       break;
     }
     case "duration": {

package/src/index.d.mts

@@ -70,8 +70,21 @@ export function convertUnit(value: string | bigint, from: TimeUnit, to: TimeUnit
 export function alignNow(nowNs: bigint, unit: TimeUnit): bigint;
 /** An RFC 3339 time, or "+" and an ISO 8601 duration from `now` (ns, required then). Returns the count of `unit`. */
 export function parseTimestamp(input: string, options: { unit: TimeUnit; candid?: string; now?: bigint }): string;
-/** Canonical RFC 3339 UTC, for example "2026-10-09T12:00:00.5Z". */
-export function displayTimestamp(value: string | bigint, options: { unit: TimeUnit; candid?: string }): string;
+export interface TimestampOptions {
+  unit: TimeUnit;
+  candid?: string;
+  /** Display only (spec section 15.9): a value at or above it (in `unit`) displays as `message`; needs `message`. */
+  threshold?: string | bigint;
+  /** What a value at or above `threshold` displays as ("Never"); needs `threshold`. */
+  message?: string;
+  /** Display only: exact values (decimal strings of `unit`) shown as words, `{ "0": "Only in the block it is used" }`. */
+  labels?: Record<string, string>;
+}
+/**
+ * Canonical RFC 3339 UTC, for example "2026-10-09T12:00:00.5Z"; a value `labels` names, or at or above `threshold`,
+ * displays as its words instead, so that it is never read as a date.
+ */
+export function displayTimestamp(value: string | bigint, options: TimestampOptions): string;
 /** An ISO 8601 duration of W, D, H, M and S ("PT24H"); returns the count of `unit`. */
 export function parseDuration(input: string, options: { unit: TimeUnit; candid?: string }): string;
 /** Canonical ISO 8601: "P1D", "PT1H30M", "PT0S". */
@@ -142,8 +155,10 @@ export const VALUE_TAGS: readonly ValueTag[];
  *
  * @param options.refs dynamic tag values keyed by their `from`: `{ "query:icrc1_decimals": 8 }`
  * @param options.now default clock for relative timestamps, ns since the Unix epoch
+ * @param options.token for an amount whose `token` names its token by a field (spec section 15.9): the decimals and
+ *   symbol of the token that field holds in this value, which the caller reads as it resolves `refs`
  */
-export function formatterFor(node: FormatNode, options?: { refs?: Record<string, unknown>; now?: bigint }): Formatter | null;
+export function formatterFor(node: FormatNode, options?: { refs?: Record<string, unknown>; now?: bigint; token?: { decimals: number | bigint | string; symbol?: string } }): Formatter | null;
 /** `Formatter.describe` without a formatter; `accepts` keeps only the examples it returns true for. */
 export function describeInput(tag: ValueTag, args: Readonly<Record<string, unknown>>, candid: string, options?: { accepts?: (input: string) => boolean }): Description;
 

package/src/time.mjs

@@ -10,6 +10,7 @@
 // millisecond precision.
 
 import { CODES, fail } from "./errors.mjs";
+import { checkMessage, checkThreshold } from "./amount.mjs";
 import { ABI_INT_TYPES, checkRange, intType, requireString, toBigInt, typeWord } from "./util.mjs";
 
 export const TIME_TYPES = ["nat", "int", "nat32", "nat64", "int64", ...ABI_INT_TYPES.filter((t) => (t.startsWith("u") ? Number(t.slice(4)) >= 32 : Number(t.slice(3)) > 64))];
@@ -203,15 +204,43 @@ export function parseTimestamp(input, { unit, candid = "nat64", now } = {}) {
 }
 
 /**
- * Display a timestamp as canonical RFC 3339 UTC, for example "2026-10-09T12:00:00.5Z".
+ * A timestamp's `labels` (spec section 15.9): words for exact values, keyed by the value in the tagged unit as a
+ * canonical decimal string. At most 16, each 1 to 32 characters with nothing invisible.
+ *
+ * @returns {Map<bigint, string> | undefined}
+ */
+export function checkTimeLabels(labels) {
+  if (labels === undefined || labels === null) return undefined;
+  if (typeof labels !== "object" || Array.isArray(labels)) fail(CODES.ARG, "timestamp labels must be an object of value to words");
+  const entries = Object.entries(labels);
+  if (entries.length < 1 || entries.length > 16) fail(CODES.ARG, `timestamp labels must have 1 to 16 entries, got ${entries.length}`);
+  const out = new Map();
+  for (const [k, v] of entries) {
+    if (!/^(?:0|[1-9][0-9]{0,77})$/.test(k)) fail(CODES.ARG, `a timestamp label's value must be a decimal string of the tagged unit (0 or more, at most 78 digits), got ${JSON.stringify(k)}`);
+    out.set(BigInt(k), checkMessage(v, `timestamp label of ${k}`));
+  }
+  return out;
+}
+
+/**
+ * Display a timestamp as canonical RFC 3339 UTC, for example "2026-10-09T12:00:00.5Z". Display only (spec section
+ * 15.9): a value that `labels` names shows its words, and a value at or above `threshold` shows `message` ("Never"
+ * for a deadline of uint256 max), so that such a value is never read as a date.
  *
  * @param {string | bigint} value integer count of `unit` since the Unix epoch
+ * @param {{ unit: string, candid?: string, threshold?: string | bigint, message?: string, labels?: Record<string, string> }} opts
  */
-export function displayTimestamp(value, { unit, candid = "nat64" } = {}) {
+export function displayTimestamp(value, { unit, candid = "nat64", threshold, message, labels } = {}) {
   const f = unitFactor(unit);
   const type = intType(candid, TIME_TYPES, "timestamp");
+  const limit = checkThreshold(threshold, "timestamp");
+  const text = checkMessage(message, "timestamp message");
+  if ((limit === undefined) !== (text === undefined)) fail(CODES.ARG, "a timestamp threshold and its message go together: give both or neither");
+  const words = checkTimeLabels(labels);
   const v = toBigInt(value, "timestamp");
   checkRange(v, type, "timestamp");
+  if (words?.has(v)) return words.get(v);
+  if (limit !== undefined && v >= limit) return text;
   return rfc3339FromNs(v * f);
 }