@meantjs/format 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 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.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,10 @@ 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`.
 
 ```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.2.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,27 @@ 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) {
+  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)}`);
+  }
+  return BigInt(threshold);
+}
+
+/** @returns {string | undefined} a validated threshold message: 1 to 32 characters, nothing invisible */
+export function checkMessage(message) {
+  if (message === undefined || message === null) return undefined;
+  if (typeof message !== "string") fail(CODES.ARG, `amount message 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 (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`);
+  }
+  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 +79,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 +97,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 { 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 { 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) {
@@ -68,7 +72,8 @@ function requireUnit(unit, tag) {
  * @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");
+  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;
@@ -86,8 +91,11 @@ export function formatterFor(node, { refs = {}, now: defaultNow } = {}) {
       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 };
+      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 }) };
       parse = (input) => parseAmount(input, o);
       display = (value) => displayAmount(value, o);
       break;
@@ -127,12 +135,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 +178,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 +191,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;
@@ -111,6 +115,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 +127,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;
 }

package/src/time.mjs

@@ -10,9 +10,9 @@
 // millisecond precision.
 
 import { CODES, fail } from "./errors.mjs";
-import { checkRange, intType, requireString, toBigInt } from "./util.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;
@@ -227,7 +227,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