@meantjs/format 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 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.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`
+  on `uint32`…`uint256` and `int64`…`int256`, with the bounds of their bits; `bytes` on `bytes` and `bytes1`…`bytes32`
+  (a `bytesN` takes exactly N bytes). A resolved-form node with `abi` is read like one with `candid`.
+- `amount` takes `threshold` and `message`: `displayAmount` shows a value at or above the threshold as the message
+  (default "Unlimited") and the symbol. Parsing is unchanged.
+
 ## 0.1.0 — 2026-10-28
 
 First published version.

package/README.md

@@ -17,6 +17,14 @@ npm install @meantjs/format
 - **No dependencies** at run time or for tests. Node >= 22.
 - **No I/O.** Dynamic tag arguments (`{ "from": "query:icrc1_decimals" }`) are resolved by the caller and passed in.
 - The choices it made where §5.3 was open were accepted as D-024 and are now in spec §5.3.
+- **EVM types** (spec §15, experimental): a position of an EVM contract's resolved form (`{ abi: "uint256", tags }`)
+  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.1.0",
+  "version": "0.3.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

@@ -5,9 +5,12 @@
 // extra digits are zeros (the literal reading of "more than d fractional digits MUST be rejected").
 
 import { CODES, fail } from "./errors.mjs";
-import { UNSAFE_DISPLAY_CHAR, checkRange, intType, requireString, toBigInt } from "./util.mjs";
+import { ABI_INT_TYPES, UNSAFE_DISPLAY_CHAR, checkRange, intType, requireString, toBigInt, typeWord } from "./util.mjs";
 
-export const AMOUNT_TYPES = ["nat", "int", "nat8", "nat16", "nat32", "nat64", "int8", "int16", "int32", "int64"];
+export const AMOUNT_TYPES = ["nat", "int", "nat8", "nat16", "nat32", "nat64", "int8", "int16", "int32", "int64", ...ABI_INT_TYPES.filter((t) => !/^int(?:8|16|32|64)$/.test(t))];
+
+/** The default `message` of an amount at or above its `threshold` (spec section 5.3; ERC-7730's tokenAmount default). */
+export const DEFAULT_THRESHOLD_MESSAGE = "Unlimited";
 
 // number, then (after whitespace) an optional symbol. "1.", ".5", "1,5", "1e3" and "+1" do not match.
 const AMOUNT_RE = /^(-?)([0-9]+)(?:\.([0-9]+))?(?:\s+(\S(?:.*\S)?))?$/s;
@@ -27,6 +30,33 @@ export function checkSymbol(symbol) {
   return symbol;
 }
 
+/**
+ * @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, `${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);
+}
+
+/**
+ * @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, `${what} must be a string, got ${typeof message}`);
+  const n = [...message].length;
+  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, `${what} ${JSON.stringify(message)} has surrounding whitespace, control or invisible characters`);
+  }
+  return message;
+}
+
 export function checkDecimals(decimals) {
   let d = decimals;
   if (typeof d === "string" && /^(?:0|[1-9][0-9]{0,2})$/.test(d)) d = Number(d);
@@ -55,7 +85,7 @@ export function parseAmount(input, { decimals, symbol, candid = "nat" }) {
     );
   }
   const [, sign, whole, frac = "", given] = m;
-  if (sign && !type.signed) fail(CODES.NEGATIVE, `negative amounts are not allowed here (the Candid type ${candid} is unsigned)`);
+  if (sign && !type.signed) fail(CODES.NEGATIVE, `negative amounts are not allowed here (the ${typeWord(candid)} ${candid} is unsigned)`);
   if (given !== undefined) {
     if (expected === undefined) fail(CODES.SYMBOL_MISMATCH, `this amount has no symbol; remove "${given}" and give the number only`);
     if (asciiLower(given) !== asciiLower(expected)) fail(CODES.SYMBOL_MISMATCH, `the symbol "${given}" is not this token's symbol "${expected}"`);
@@ -73,18 +103,23 @@ export function parseAmount(input, { decimals, symbol, candid = "nat" }) {
 }
 
 /**
- * Display a base-unit integer as "1.5 ICP": trailing fractional zeros removed, symbol appended.
+ * Display a base-unit integer as "1.5 ICP": trailing fractional zeros removed, symbol appended. A value at or above
+ * `threshold` displays as `message` (default "Unlimited") and the symbol: "Unlimited USDC" (spec section 5.3).
  *
  * @param {string | bigint} value
- * @param {{ decimals: number | bigint | string, symbol?: string, candid?: string }} opts
+ * @param {{ decimals: number | bigint | string, symbol?: string, candid?: string, threshold?: string | bigint, message?: string }} opts
  * @returns {string}
  */
-export function displayAmount(value, { decimals, symbol, candid = "nat" }) {
+export function displayAmount(value, { decimals, symbol, candid = "nat", threshold, message }) {
   const d = checkDecimals(decimals);
   const sym = checkSymbol(symbol);
+  const limit = checkThreshold(threshold);
+  const text = checkMessage(message);
+  if (text !== undefined && limit === undefined) fail(CODES.ARG, "amount message needs a threshold");
   const type = intType(candid, AMOUNT_TYPES, "amount");
   const v = toBigInt(value, "amount");
   checkRange(v, type, "amount");
+  if (limit !== undefined && v >= limit) return `${text ?? DEFAULT_THRESHOLD_MESSAGE}${sym ? ` ${sym}` : ""}`;
   const digits = (v < 0n ? -v : v).toString().padStart(d + 1, "0");
   const whole = digits.slice(0, digits.length - d);
   const frac = digits.slice(digits.length - d).replace(/0+$/, "");

package/src/formatter.mjs

@@ -6,11 +6,15 @@
 // resolved by the caller (the library does no I/O) and passed in `refs`, keyed by the `from` string.
 
 import { CODES, FormatError, fail } from "./errors.mjs";
-import { AMOUNT_TYPES, checkDecimals, checkSymbol, displayAmount, parseAmount } from "./amount.mjs";
-import { TIME_TYPES, displayDuration, displayTimestamp, parseDuration, parseTimestamp, unitFactor } from "./time.mjs";
+import { AMOUNT_TYPES, DEFAULT_THRESHOLD_MESSAGE, checkDecimals, checkMessage, checkSymbol, checkThreshold, displayAmount, parseAmount } from "./amount.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";
+import { INT_TYPES, listTypes } from "./util.mjs";
+
+/** The byte types: Candid's blob, the EVM ABI's bytes and bytes1 to bytes32 (spec section 15). */
+const BYTE_TYPES = ["blob", "bytes", ...Array.from({ length: 32 }, (_, i) => `bytes${i + 1}`)];
 
 /** The tags that give a position a text form, in spec §5.1. */
 export const VALUE_TAGS = Object.freeze(["amount", "timestamp", "duration", "account", "subaccount", "bytes"]);
@@ -28,7 +32,7 @@ function resolveArg(arg, refs, where) {
 }
 
 function requireCandid(node, allowed, tag) {
-  if (!allowed.includes(node.candid)) fail(CODES.TAG_TYPE, `the ${tag} tag applies to ${allowed.join(", ")}, not ${node.candid}`);
+  if (!allowed.includes(node.candid)) fail(CODES.TAG_TYPE, `the ${tag} tag applies to ${listTypes(allowed)}, not ${node.candid}`);
 }
 
 function requireUnit(unit, tag) {
@@ -61,14 +65,17 @@ 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 } = {}) {
-  if (node === null || typeof node !== "object" || typeof node.candid !== "string") fail(CODES.TYPE, "node must be a resolved-form position with a `candid` type");
+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 ?? {};
   const present = VALUE_TAGS.filter((t) => Object.hasOwn(tags, t));
   if (present.length === 0) return null;
@@ -83,11 +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"));
-      const o = { decimals, symbol, candid: node.candid };
-      args = { decimals, 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, ...(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;
@@ -96,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": {
@@ -127,12 +160,17 @@ export function formatterFor(node, { refs = {}, now: defaultNow } = {}) {
       break;
     }
     case "bytes": {
-      requireCandid(node, ["blob"], tag);
+      requireCandid(node, BYTE_TYPES, tag);
       const encoding = arg("encoding");
       if (!BYTES_ENCODINGS.includes(encoding)) fail(CODES.ARG, `the bytes tag needs encoding utf8, hex or base64, got ${JSON.stringify(encoding)}`);
       const maxLen = raw.max_len;
       args = { encoding, ...(maxLen === undefined ? {} : { max_len: maxLen }) };
-      parse = (input) => parseBytes(input, { encoding, maxLen });
+      const size = /^bytes(\d+)$/.exec(node.candid)?.[1]; // bytesN holds exactly N bytes
+      parse = (input) => {
+        const b = parseBytes(input, { encoding, maxLen });
+        if (size !== undefined && b.length !== Number(size)) fail(CODES.LENGTH, `${node.candid} holds exactly ${size} bytes, got ${b.length}`);
+        return b;
+      };
       display = (value) => displayBytes(value, { encoding });
       break;
     }
@@ -165,10 +203,10 @@ export function formatterFor(node, { refs = {}, now: defaultNow } = {}) {
 // ---------------------------------------------------------------- describe
 
 /** The Candid types each value tag applies to (the `requireCandid` calls in `formatterFor`). */
-const CANDID_OF = { amount: AMOUNT_TYPES, timestamp: TIME_TYPES, duration: TIME_TYPES, account: ["record"], subaccount: ["blob"], bytes: ["blob"] };
+const CANDID_OF = { amount: AMOUNT_TYPES, timestamp: TIME_TYPES, duration: TIME_TYPES, account: ["record"], subaccount: ["blob"], bytes: BYTE_TYPES };
 /** 2026-01-01T00:00:00Z in ns: the reference instant relative examples are checked against. */
 const DESCRIBE_NOW = 1_767_225_600_000_000_000n;
-const SIGNED = new Set(["int", "int8", "int16", "int32", "int64"]);
+
 // ECMAScript syntax characters only: escaping anything else (such as "-") is an error under the `u` flag, which JSON
 // Schema validators such as Ajv use.
 const reEscape = (s) => s.replace(/[\\^$.*+?()[\]{}|/]/g, "\\$&");
@@ -178,7 +216,7 @@ const quoted = (xs) => xs.map((x) => JSON.stringify(x)).join(", ");
 
 /** The grammar in words (no examples), candidate examples, and a pattern where the grammar is regular. */
 function grammar(tag, args, candid) {
-  const signed = SIGNED.has(candid);
+  const signed = INT_TYPES[candid]?.signed === true;
   const finer = (what) => (args.unit === "ns" ? "" : ` Stored in ${args.unit}: a ${what} finer than that is an error, not rounded.`);
   switch (tag) {
     case "amount": {

package/src/index.d.mts

@@ -52,8 +52,12 @@ export declare class FormatError extends Error {
 export interface AmountOptions {
   decimals: number | bigint | string;
   symbol?: string;
-  /** The Candid type, for the sign and range (default `nat`). */
+  /** The Candid type, or an EVM ABI integer type (`uint256`), for the sign and range (default `nat`). */
   candid?: string;
+  /** Display only: a value at or above it (base units) displays as `message` and the symbol, "Unlimited USDC". */
+  threshold?: string | bigint;
+  /** What a value at or above `threshold` displays as (default "Unlimited"); needs `threshold`. */
+  message?: string;
 }
 /** "1.5" or "1.5 ICP" to base units as a decimal string. Excess precision throws; nothing is rounded. */
 export function parseAmount(input: string, options: AmountOptions): string;
@@ -66,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". */
@@ -111,6 +128,7 @@ export type ParsedValue = string | Account | Uint8Array;
 /** One position's formatter: `formatterFor` returns it with the tag's arguments resolved. */
 export interface Formatter {
   readonly tag: ValueTag;
+  /** The position's Candid type, or its EVM ABI type (`uint256`, `bytes32`) for an EVM position. */
   readonly candid: string;
   readonly args: Readonly<Record<string, unknown>>;
   /** Throws FormatError. */
@@ -122,9 +140,9 @@ export interface Formatter {
   describe(): Description;
 }
 
-/** A position of a resolved form, as far as formatting reads it. */
-export interface FormatNode {
-  candid: string;
+/** A position of a resolved form, as far as formatting reads it: `candid`, or `abi` for an EVM contract's (spec section 15). */
+export type FormatNode = FormatNodeFields & ({ candid: string } | { abi: string; candid?: undefined });
+interface FormatNodeFields {
   tags?: Record<string, { args?: Record<string, unknown> } | undefined>;
   [key: string]: unknown;
 }
@@ -137,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,9 +10,10 @@
 // millisecond precision.
 
 import { CODES, fail } from "./errors.mjs";
-import { checkRange, intType, requireString, toBigInt } from "./util.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"];
+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))];
 
 const NS_PER = Object.freeze({ ns: 1n, us: 1_000n, ms: 1_000_000n, s: 1_000_000_000n });
 const NS_PER_S = 1_000_000_000n;
@@ -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);
 }
 
@@ -227,7 +256,7 @@ export function parseDuration(input, { unit, candid = "nat64" } = {}) {
   const type = intType(candid, TIME_TYPES, "duration");
   const text = requireString(input, "duration").trim();
   const { negative, ns } = parseDurationNs(text, "a duration");
-  if (negative && ns !== 0n && !type.signed) fail(CODES.NEGATIVE, `negative durations are not allowed here (the Candid type ${candid} is unsigned)`);
+  if (negative && ns !== 0n && !type.signed) fail(CODES.NEGATIVE, `negative durations are not allowed here (the ${typeWord(candid)} ${candid} is unsigned)`);
   const v = nsToUnit(negative ? -ns : ns, unit);
   checkRange(v, type, "duration");
   return v.toString();

package/src/util.mjs

@@ -5,7 +5,11 @@ export const MAX_INPUT_CHARS = 1024;
 
 const DEC_INT = /^-?(?:0|[1-9][0-9]*)$/;
 
-/** The Candid integer types the value tags apply to, with their inclusive bounds (null = unbounded). */
+/**
+ * The integer types the value tags apply to, with their inclusive bounds (null = unbounded): Candid's, then the EVM ABI's
+ * uint8 to uint256 and int8 to int256 (spec section 15). int8 to int64 are both Candid and ABI types, with the same
+ * bounds; the others carry `abi: true`, which only changes the wording of messages.
+ */
 export const INT_TYPES = Object.freeze({
   nat: { signed: false, min: 0n, max: null },
   nat8: { signed: false, min: 0n, max: 2n ** 8n - 1n },
@@ -17,12 +21,34 @@ export const INT_TYPES = Object.freeze({
   int16: { signed: true, min: -(2n ** 15n), max: 2n ** 15n - 1n },
   int32: { signed: true, min: -(2n ** 31n), max: 2n ** 31n - 1n },
   int64: { signed: true, min: -(2n ** 63n), max: 2n ** 63n - 1n },
+  ...Object.fromEntries(
+    Array.from({ length: 32 }, (_, i) => BigInt(8 * (i + 1))).flatMap((b) => [
+      [`uint${b}`, { signed: false, min: 0n, max: 2n ** b - 1n, abi: true }],
+      ...(b <= 64n && (b & (b - 1n)) === 0n ? [] : [[`int${b}`, { signed: true, min: -(2n ** (b - 1n)), max: 2n ** (b - 1n) - 1n, abi: true }]]),
+    ]),
+  ),
 });
 
+/** The EVM ABI integer types (uint8 to uint256, int8 to int256), in that order. */
+export const ABI_INT_TYPES = Object.freeze(Array.from({ length: 32 }, (_, i) => 8 * (i + 1)).flatMap((b) => [`uint${b}`, `int${b}`]));
+
+/** How a message names the type: "ABI type" for the EVM-only integer types, "Candid type" otherwise. */
+export const typeWord = (name) => (INT_TYPES[name]?.abi ? "ABI type" : "Candid type");
+
+/** A list of types for a message: the Candid types by name, the ABI's integer and byte families by range. */
+export function listTypes(types) {
+  const candid = types.filter((t) => !INT_TYPES[t]?.abi && !/^bytes\d*$/.test(t));
+  const abi = [];
+  if (types.includes("uint8")) abi.push("uint8 to uint256", "int8 to int256");
+  else if (types.includes("uint32")) abi.push("uint32 to uint256", "int72 to int256");
+  if (types.includes("bytes")) abi.push("bytes", "bytes1 to bytes32");
+  return [...candid, ...abi].join(", ");
+}
+
 /** @param {string} candid @param {string[]} allowed */
 export function intType(candid, allowed, tag) {
   if (!allowed.includes(candid)) {
-    fail(CODES.TAG_TYPE, `the ${tag} tag applies to ${allowed.join(", ")}, not ${candid}`);
+    fail(CODES.TAG_TYPE, `the ${tag} tag applies to ${listTypes(allowed)}, not ${candid}`);
   }
   return INT_TYPES[candid];
 }
@@ -53,9 +79,10 @@ export function toBigInt(value, what = "value") {
 }
 
 export function checkRange(v, type, what) {
-  if (!type.signed && v < 0n) fail(CODES.RANGE, `${what} ${v} is negative but the Candid type is unsigned`);
-  if (type.min !== null && v < type.min) fail(CODES.RANGE, `${what} ${v} is below the minimum ${type.min} of the Candid type`);
-  if (type.max !== null && v > type.max) fail(CODES.RANGE, `${what} ${v} is above the maximum ${type.max} of the Candid type`);
+  const word = type.abi ? "ABI type" : "Candid type";
+  if (!type.signed && v < 0n) fail(CODES.RANGE, `${what} ${v} is negative but the ${word} is unsigned`);
+  if (type.min !== null && v < type.min) fail(CODES.RANGE, `${what} ${v} is below the minimum ${type.min} of the ${word}`);
+  if (type.max !== null && v > type.max) fail(CODES.RANGE, `${what} ${v} is above the maximum ${type.max} of the ${word}`);
 }
 
 // ---------------------------------------------------------------- bytes helpers