@meantjs/format 0.0.0-stage → 0.1.0

package/src/bytes.mjs

@@ -0,0 +1,131 @@
+// `bytes` (spec §5.3): a blob shown and read as utf8, hex or base64.
+//
+//   utf8    input is plain text encoded as UTF-8; input starting with 0x is read as hex.
+//           Display is the decoded text when the bytes are valid UTF-8 without control
+//           characters, else 0x followed by lowercase hex.
+//   hex     input and display carry a 0x prefix (the prefix is optional on input).
+//   base64  RFC 4648 standard alphabet; padding optional on input, always written on display.
+//   max_len counts bytes after encoding.
+//
+// Two display rules go beyond the literal text so that parse(display(x)) = x always holds and so
+// that nothing misleading is shown (both are listed in docs/proposals/w3a-spec-5-3-clarifications.md):
+//   - utf8 text that itself starts with 0x/0X is displayed as hex, because as text it would be read back as hex;
+//   - besides control characters (Cc), text with format characters (Cf, for example bidirectional
+//     overrides, zero-width joiners and the byte order mark) or line and paragraph separators
+//     (Zl, Zp) is displayed as hex.
+
+import { CODES, fail } from "./errors.mjs";
+import { UNSAFE_DISPLAY_CHAR, bytesToHex, hexToBytes, toBytes } from "./util.mjs";
+
+export const BYTES_ENCODINGS = ["utf8", "hex", "base64"];
+
+/** Bound on the size of a text input (bounded work, spec §11.6). */
+const MAX_BYTES_INPUT_CHARS = 4 * 1024 * 1024;
+const HEX_PREFIX = /^0[xX]/;
+
+const B64 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+const B64_VALUE = (() => {
+  const t = new Int8Array(128).fill(-1);
+  for (let i = 0; i < 64; i++) t[B64.charCodeAt(i)] = i;
+  return t;
+})();
+
+function base64Encode(bytes) {
+  let out = "";
+  for (let i = 0; i < bytes.length; i += 3) {
+    const n = (bytes[i] << 16) | ((bytes[i + 1] ?? 0) << 8) | (bytes[i + 2] ?? 0);
+    out += B64[(n >> 18) & 63] + B64[(n >> 12) & 63];
+    out += i + 1 < bytes.length ? B64[(n >> 6) & 63] : "=";
+    out += i + 2 < bytes.length ? B64[n & 63] : "=";
+  }
+  return out;
+}
+
+/** Strict: standard alphabet, canonical padding or none, no stray characters, zero spare bits. */
+function base64Decode(text) {
+  const m = /^([A-Za-z0-9+/]*)(={0,2})$/.exec(text);
+  if (!m) {
+    fail(CODES.BASE64, "not base64: use the standard alphabet (A-Z, a-z, 0-9, + and /) with no spaces, line breaks or URL-safe characters");
+  }
+  const [, body, pad] = m;
+  const rem = body.length % 4;
+  if (rem === 1) fail(CODES.BASE64, "not base64: the length is impossible (one character too many or too few)");
+  if (pad && (rem === 0 || pad.length !== 4 - rem)) fail(CODES.BASE64, "not base64: the '=' padding is wrong");
+  const out = new Uint8Array(Math.floor((body.length * 3) / 4));
+  let acc = 0;
+  let bits = 0;
+  let o = 0;
+  for (let i = 0; i < body.length; i++) {
+    acc = (acc << 6) | B64_VALUE[body.charCodeAt(i)];
+    bits += 6;
+    if (bits >= 8) {
+      out[o++] = (acc >> (bits - 8)) & 255;
+      bits -= 8;
+    }
+    acc &= (1 << bits) - 1;
+  }
+  if (acc !== 0) fail(CODES.BASE64, "not canonical base64: the unused trailing bits must be zero");
+  return out;
+}
+
+function parseHex(text, what) {
+  const bytes = hexToBytes(text.replace(HEX_PREFIX, ""));
+  if (bytes === null) fail(CODES.HEX, `${what} is not hexadecimal: use an even number of digits 0-9 and a-f, for example "0x1a2b" (no spaces)`);
+  return bytes;
+}
+
+export function checkMaxLen(maxLen) {
+  if (maxLen === undefined || maxLen === null) return null;
+  let n = maxLen;
+  if (typeof n === "bigint" || (typeof n === "string" && /^(?:0|[1-9][0-9]*)$/.test(n))) n = Number(n);
+  if (!Number.isSafeInteger(n) || n < 0) fail(CODES.ARG, `max_len must be a non-negative integer, got ${String(maxLen)}`);
+  return n;
+}
+
+/**
+ * @param {string} input
+ * @param {{ encoding: "utf8"|"hex"|"base64", maxLen?: number }} opts  `maxLen` is the tag's max_len, in bytes
+ * @returns {Uint8Array}
+ */
+export function parseBytes(input, { encoding, maxLen } = {}) {
+  if (!BYTES_ENCODINGS.includes(encoding)) fail(CODES.ARG, `bytes encoding must be one of ${BYTES_ENCODINGS.join(", ")}, got ${JSON.stringify(encoding)}`);
+  const max = checkMaxLen(maxLen);
+  if (typeof input !== "string") fail(CODES.TYPE, `bytes input must be a string, got ${typeof input}`);
+  if (input.length > MAX_BYTES_INPUT_CHARS) fail(CODES.TOO_LONG, `bytes input is longer than ${MAX_BYTES_INPUT_CHARS} characters`);
+  let bytes;
+  if (encoding === "utf8") {
+    if (HEX_PREFIX.test(input)) bytes = parseHex(input, "text starting with 0x (read as hex)");
+    else {
+      // TextEncoder would replace a lone surrogate with U+FFFD without saying so.
+      if (!input.isWellFormed()) fail(CODES.UTF8, "the text contains an unpaired surrogate and cannot be encoded as UTF-8");
+      bytes = new TextEncoder().encode(input);
+    }
+  } else if (encoding === "hex") {
+    bytes = parseHex(input, "the value");
+  } else {
+    bytes = base64Decode(input);
+  }
+  if (max !== null && bytes.length > max) fail(CODES.MAX_LEN, `the value is ${bytes.length} bytes after encoding but at most ${max} are allowed`);
+  return bytes;
+}
+
+/**
+ * @param {Uint8Array | number[]} value
+ * @param {{ encoding: "utf8"|"hex"|"base64" }} opts
+ * @returns {string}
+ */
+export function displayBytes(value, { encoding } = {}) {
+  if (!BYTES_ENCODINGS.includes(encoding)) fail(CODES.ARG, `bytes encoding must be one of ${BYTES_ENCODINGS.join(", ")}, got ${JSON.stringify(encoding)}`);
+  const bytes = toBytes(value, "bytes");
+  if (encoding === "hex") return `0x${bytesToHex(bytes)}`;
+  if (encoding === "base64") return base64Encode(bytes);
+  let text;
+  try {
+    // ignoreBOM keeps a leading U+FEFF in the string instead of silently dropping its three bytes
+    text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+  } catch {
+    return `0x${bytesToHex(bytes)}`;
+  }
+  if (UNSAFE_DISPLAY_CHAR.test(text) || HEX_PREFIX.test(text)) return `0x${bytesToHex(bytes)}`;
+  return text;
+}

package/src/errors.mjs

@@ -0,0 +1,49 @@
+// Every rejection in this package is a FormatError with a stable `code`.
+// Callers (arm C tool layer, the ICRC-21 generator) switch on `code`; `message` is written for a
+// model or a person and says how to fix the input.
+
+export class FormatError extends Error {
+  /**
+   * @param {string} code  one of CODES
+   * @param {string} message
+   */
+  constructor(code, message) {
+    super(message);
+    this.name = "FormatError";
+    this.code = code;
+  }
+}
+
+export const CODES = Object.freeze({
+  // shared
+  TYPE: "E_TYPE", // wrong JavaScript type for an input, for example a number where a decimal string is required
+  SYNTAX: "E_SYNTAX", // the text does not match the grammar
+  RANGE: "E_RANGE", // outside the range of the Candid type or of the representable calendar
+  TOO_LONG: "E_TOO_LONG", // input longer than the bound on work
+  ARG: "E_ARG", // a tag argument is missing or invalid
+  TAG_TYPE: "E_TAG_TYPE", // the tag does not apply to this Candid type
+  TAG_CONFLICT: "E_TAG_CONFLICT", // two formatting tags at one position
+  REF_UNRESOLVED: "E_REF_UNRESOLVED", // a dynamic value was not supplied by the caller
+  // amount
+  EXCESS_PRECISION: "E_EXCESS_PRECISION", // more fractional digits than decimals (never rounded)
+  NEGATIVE: "E_NEGATIVE", // negative input for an unsigned Candid type
+  SYMBOL_MISMATCH: "E_SYMBOL_MISMATCH", // the symbol in the input is not the token's symbol
+  // time
+  INEXACT: "E_INEXACT", // the value cannot be represented exactly in the requested unit
+  CALENDAR_UNIT: "E_CALENDAR_UNIT", // years and months have no fixed length
+  NEEDS_NOW: "E_NEEDS_NOW", // relative time without a `now`
+  // account, subaccount, bytes
+  CHECKSUM: "E_CHECKSUM", // checksum does not match
+  CHECKSUM_MISSING: "E_CHECKSUM_MISSING",
+  NOT_CANONICAL: "E_NOT_CANONICAL", // a valid value written in a non-canonical way
+  PRINCIPAL: "E_PRINCIPAL", // invalid principal text
+  HEX: "E_HEX",
+  BASE64: "E_BASE64",
+  UTF8: "E_UTF8", // text that cannot be encoded as UTF-8 (lone surrogate)
+  LENGTH: "E_LENGTH", // wrong length in bytes
+  MAX_LEN: "E_MAX_LEN", // longer than the tag's max_len
+});
+
+export function fail(code, message) {
+  throw new FormatError(code, message);
+}

package/src/formatter.mjs

@@ -0,0 +1,272 @@
+// formatterFor(node): the one entry point for consumers (arm C, the ICRC-21 consent generator).
+//
+// `node` is a position from the resolved form (docs/profile-v0.md §10): its `candid` type and its
+// `tags`. The function picks the value tag at that position and returns a { parse, display } pair
+// bound to the tag's arguments. Dynamic arguments such as { "from": "query:icrc1_decimals" } are
+// 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 { displayAccount, parseAccount } from "./account.mjs";
+import { displaySubaccount, parseSubaccount } from "./subaccount.mjs";
+import { BYTES_ENCODINGS, checkMaxLen, displayBytes, parseBytes } from "./bytes.mjs";
+
+/** 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"]);
+
+/** A dynamic value ({ from }) replaced by the caller-supplied one; literals pass through. */
+function resolveArg(arg, refs, where) {
+  if (arg === null || typeof arg !== "object" || Array.isArray(arg)) return arg;
+  const from = arg.from;
+  if (typeof from !== "string") fail(CODES.ARG, `${where} is an object without a "from" string`);
+  if (from === "now" || from === "caller") fail(CODES.ARG, `${where}: { "from": "${from}" } is not valid here (only default.value may use it)`);
+  if (!Object.hasOwn(refs, from)) {
+    fail(CODES.REF_UNRESOLVED, `${where} needs the value of "${from}", which the caller did not supply (call it once per canister and pass it in \`refs\`)`);
+  }
+  return refs[from];
+}
+
+function requireCandid(node, allowed, tag) {
+  if (!allowed.includes(node.candid)) fail(CODES.TAG_TYPE, `the ${tag} tag applies to ${allowed.join(", ")}, not ${node.candid}`);
+}
+
+function requireUnit(unit, tag) {
+  if (unit === undefined) fail(CODES.ARG, `the ${tag} tag needs a unit`);
+  unitFactor(unit);
+  return unit;
+}
+
+/**
+ * @typedef {object} Formatter
+ * @property {string} tag  the value tag: amount, timestamp, duration, account, subaccount or bytes
+ * @property {string} candid  the Candid type of the position (`opt` is the node's `optional` flag, not handled here)
+ * @property {Readonly<Record<string, unknown>>} args  the tag's arguments with dynamic values resolved
+ * @property {(input: string, ctx?: { now?: bigint }) => any} parse  throws FormatError. amount, timestamp,
+ *   duration: decimal string in base units / tagged unit; account: { owner, subaccount }; subaccount, bytes: Uint8Array
+ * @property {(value: any) => string} display  throws FormatError
+ * @property {(input: string, ctx?: { now?: bigint }) => { ok: true, value: any } | { ok: false, error: { code: string, message: string } }} safeParse
+ * @property {(value: any) => { ok: true, value: string } | { ok: false, error: { code: string, message: string } }} safeDisplay
+ * @property {() => Description} describe  the text this formatter reads, in words, with examples (see `describeInput`)
+ */
+
+/**
+ * @typedef {object} Description
+ * @property {string} summary  one paragraph for a form hint or a tool input's description
+ * @property {string[]} examples  inputs `parse` accepts (a relative time needs `now`)
+ * @property {string} [pattern]  an ECMAScript regular expression every accepted input matches (JSON Schema `pattern`).
+ *   A necessary condition only: a matching input can still be refused (a range, a checksum). Given for amount and
+ *   subaccount, whose grammar is regular.
+ */
+
+/**
+ * @param {{ candid: string, tags?: Record<string, { args?: Record<string, unknown> }> }} node
+ * @param {{ refs?: Record<string, unknown>, now?: bigint }} [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.
+ * @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");
+  const tags = node.tags ?? {};
+  const present = VALUE_TAGS.filter((t) => Object.hasOwn(tags, t));
+  if (present.length === 0) return null;
+  if (present.length > 1) fail(CODES.TAG_CONFLICT, `a position cannot carry more than one value tag, found ${present.join(", ")}`);
+  const tag = present[0];
+  const raw = tags[tag]?.args ?? {};
+  const arg = (name) => resolveArg(raw[name], refs, `${tag}.${name}`);
+
+  let args;
+  let parse;
+  let display;
+  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 };
+      parse = (input) => parseAmount(input, o);
+      display = (value) => displayAmount(value, o);
+      break;
+    }
+    case "timestamp": {
+      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 o = { unit, candid: node.candid };
+      args = { unit, epoch: "unix" };
+      parse = (input, ctx = {}) => parseTimestamp(input, { ...o, now: ctx.now ?? defaultNow });
+      display = (value) => displayTimestamp(value, o);
+      break;
+    }
+    case "duration": {
+      requireCandid(node, TIME_TYPES, tag);
+      const unit = requireUnit(arg("unit"), tag);
+      const o = { unit, candid: node.candid };
+      args = { unit };
+      parse = (input) => parseDuration(input, o);
+      display = (value) => displayDuration(value, o);
+      break;
+    }
+    case "account": {
+      requireCandid(node, ["record"], tag);
+      if (raw.encoding !== undefined && raw.encoding !== "icrc1") fail(CODES.ARG, `account encoding must be "icrc1", got ${JSON.stringify(raw.encoding)}`);
+      args = { encoding: "icrc1" };
+      parse = (input) => parseAccount(input);
+      display = (value) => displayAccount(value);
+      break;
+    }
+    case "subaccount": {
+      requireCandid(node, ["blob"], tag);
+      args = {};
+      parse = (input) => parseSubaccount(input);
+      display = (value) => displaySubaccount(value);
+      break;
+    }
+    case "bytes": {
+      requireCandid(node, ["blob"], 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 });
+      display = (value) => displayBytes(value, { encoding });
+      break;
+    }
+  }
+
+  const safe = (fn) => (...a) => {
+    try {
+      return { ok: true, value: fn(...a) };
+    } catch (e) {
+      if (e instanceof FormatError) return { ok: false, error: { code: e.code, message: e.message } };
+      throw e;
+    }
+  };
+  // Keep only the examples this position accepts: a range (nat8, nat32 in ns) or a max_len can refuse one. A relative time
+  // is checked against the formatter's own clock when it was given one (`parse` uses it), else against a fixed instant
+  // (2026-01-01T00:00:00Z), since describing must not read a clock.
+  const description = describeInput(tag, args, node.candid, { accepts: (x) => safe(parse)(x, { now: defaultNow ?? DESCRIBE_NOW }).ok });
+  return Object.freeze({
+    tag,
+    candid: node.candid,
+    args: Object.freeze(args),
+    describe: () => ({ ...description, examples: [...description.examples] }),
+    parse,
+    display,
+    safeParse: safe(parse),
+    safeDisplay: safe(display),
+  });
+}
+
+// ---------------------------------------------------------------- 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"] };
+/** 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, "\\$&");
+/** The symbol as `parseAmount` compares it: ASCII letters in either case, everything else exactly. */
+const symbolPattern = (symbol) => [...symbol].map((c) => (/[A-Za-z]/.test(c) ? `[${c.toUpperCase()}${c.toLowerCase()}]` : reEscape(c))).join("");
+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 finer = (what) => (args.unit === "ns" ? "" : ` Stored in ${args.unit}: a ${what} finer than that is an error, not rounded.`);
+  switch (tag) {
+    case "amount": {
+      const { decimals: d, symbol } = args;
+      const examples = d === 0 ? ["1", "250"] : ["1", d === 1 ? "1.5" : "1.25"];
+      if (symbol !== undefined) examples.push(`${examples[1]} ${symbol}`);
+      return {
+        words:
+          `Amount in ${symbol === undefined ? "the token's units" : symbol}: ` +
+          (d === 0 ? "a whole number (this token has no decimal places)" : `a decimal number with at most ${d} digit${d === 1 ? "" : "s"} after the point`) +
+          (symbol === undefined ? "" : `, optionally followed by the symbol ${symbol}`) +
+          `. Digits on both sides of a point, no thousands separators or exponents${signed ? ', "-" for a negative amount' : ""}. ` +
+          "Never rounded: more digits after the point is an error, even zeros.",
+        examples,
+        pattern:
+          `^\\s*${signed ? "-?" : ""}[0-9]+${d === 0 ? "" : `(?:\\.[0-9]{1,${d}})?`}` + (symbol === undefined ? "" : `(?:\\s+${symbolPattern(symbol)})?`) + "\\s*$",
+      };
+    }
+    case "timestamp":
+      return {
+        words:
+          'Time in RFC 3339 with an explicit zone, or relative to the current time as "+" and an ISO 8601 duration with ' +
+          "weeks, days, hours, minutes and seconds only (no years or months; the seconds may have a fraction)." +
+          finer("time"),
+        examples: ["2026-12-25T10:00:00Z", "+PT24H", "+P7D"],
+      };
+    case "duration":
+      return {
+        words:
+          `ISO 8601 duration with weeks, days, hours, minutes and seconds only (no years or months); the seconds may have a fraction${signed ? '; "-" for a negative duration' : ""}.` +
+          finer("duration"),
+        examples: ["PT24H", "P7D", "PT1M30S"],
+      };
+    case "account":
+      return {
+        words: 'ICRC-1 account in text form: a principal for its default subaccount, or "principal-checksum.subaccounthex" for another subaccount.',
+        examples: ["aaaaa-aa", "2vxsx-fae"],
+      };
+    case "subaccount":
+      return {
+        words: 'Subaccount as "#n" or n (a number below 2^64 without leading zeros, stored as 32 big-endian bytes), or as exactly 64 hex characters, optionally after "0x".',
+        examples: ["#0", "#7", "0".repeat(63) + "1"],
+        pattern: "^\\s*(?:#?(?:0|[1-9][0-9]*)|(?:0[xX])?[0-9a-fA-F]{64})\\s*$",
+      };
+    case "bytes": {
+      const max = args.max_len === undefined || args.max_len === null ? "" : ` At most ${args.max_len} bytes after encoding.`;
+      if (args.encoding === "hex") return { words: `Bytes as hexadecimal, an even number of digits, optionally after "0x".${max}`, examples: ["0x1a2b", "1a2b"] };
+      if (args.encoding === "base64") return {
+          words: `Bytes as standard base64 (RFC 4648: A-Z, a-z, 0-9, "+" and "/"; not the URL-safe "-" and "_"), with "=" padding or none, no spaces or line breaks, and the unused bits of the last character zero.${max}`,
+          examples: ["aGk="],
+        };
+      return { words: `Text, stored as its UTF-8 bytes. Text that starts with "0x" is read as hex bytes instead.${max}`, examples: ["invoice 42", "0x1a2b"] };
+    }
+  }
+  throw new Error(`no description for the ${tag} tag`);
+}
+
+/**
+ * The input grammar of a value tag in words (spec §5.3), with the tag's resolved arguments filled in, so a form hint,
+ * a tool schema and the parser share one description. The summary quotes exactly the examples kept.
+ *
+ * @param {string} tag
+ * @param {Readonly<Record<string, any>>} args  the tag's arguments, dynamic values resolved (`Formatter.args`)
+ * @param {string} candid
+ * @param {{ accepts?: (input: string) => boolean }} [options]  keeps only the examples it accepts (`Formatter.describe`
+ *   passes its own parser, so a range or `max_len` that refuses an example leaves it out); default: all of them
+ * @returns {Description}
+ */
+export function describeInput(tag, args, candid, { accepts = () => true } = {}) {
+  // The same checks and normalisation formatterFor applies (decimals may arrive as "0" or 0n), so arguments it would
+  // refuse are refused here too, never described as another grammar.
+  if (VALUE_TAGS.includes(tag)) {
+    requireCandid({ candid }, CANDID_OF[tag], tag);
+    const a = args ?? {};
+    if (tag === "amount") args = { ...a, decimals: checkDecimals(a.decimals), symbol: checkSymbol(a.symbol) };
+    if (tag === "timestamp" || tag === "duration") requireUnit(a.unit, tag);
+    if (tag === "timestamp" && a.epoch !== undefined && a.epoch !== "unix") fail(CODES.ARG, `timestamp epoch must be "unix", got ${JSON.stringify(a.epoch)}`);
+    if (tag === "account" && a.encoding !== undefined && a.encoding !== "icrc1") fail(CODES.ARG, `account encoding must be "icrc1", got ${JSON.stringify(a.encoding)}`);
+    if (tag === "bytes") {
+      if (!BYTES_ENCODINGS.includes(a.encoding)) fail(CODES.ARG, `the bytes tag needs encoding utf8, hex or base64, got ${JSON.stringify(a.encoding)}`);
+      checkMaxLen(a.max_len);
+    }
+  }
+  const g = grammar(tag, args, candid);
+  const examples = g.examples.filter((x) => accepts(x));
+  return {
+    summary: g.words + (examples.length > 0 ? ` For example ${quoted(examples)}.` : ""),
+    examples,
+    ...(g.pattern === undefined ? {} : { pattern: g.pattern }),
+  };
+}

package/src/index.d.mts

@@ -0,0 +1,169 @@
+// Types for @meantjs/format. Hand-written; the source is plain ES modules (src/*.mjs).
+// test/types.test.mjs keeps the declared names equal to the runtime exports, and `npm run types` compiles a consumer
+// against these declarations under strict TypeScript.
+
+/** The value tags (spec §5.1). */
+export type ValueTag = "amount" | "timestamp" | "duration" | "account" | "subaccount" | "bytes";
+export type TimeUnit = "ns" | "us" | "ms" | "s";
+export type BytesEncoding = "utf8" | "hex" | "base64";
+/** Bytes as the library takes them: a Uint8Array (from any realm) or an array of byte values. */
+export type ByteInput = Uint8Array | readonly number[];
+/** An ICRC-1 account as `parseAccount` returns it: `subaccount` null is the default subaccount. */
+export interface Account {
+  owner: string;
+  subaccount: Uint8Array | null;
+}
+
+/** The stable rejection codes; `FormatError.code` is one of them. */
+export const CODES: Readonly<{
+  TYPE: "E_TYPE";
+  SYNTAX: "E_SYNTAX";
+  RANGE: "E_RANGE";
+  TOO_LONG: "E_TOO_LONG";
+  ARG: "E_ARG";
+  TAG_TYPE: "E_TAG_TYPE";
+  TAG_CONFLICT: "E_TAG_CONFLICT";
+  REF_UNRESOLVED: "E_REF_UNRESOLVED";
+  EXCESS_PRECISION: "E_EXCESS_PRECISION";
+  NEGATIVE: "E_NEGATIVE";
+  SYMBOL_MISMATCH: "E_SYMBOL_MISMATCH";
+  INEXACT: "E_INEXACT";
+  CALENDAR_UNIT: "E_CALENDAR_UNIT";
+  NEEDS_NOW: "E_NEEDS_NOW";
+  CHECKSUM: "E_CHECKSUM";
+  CHECKSUM_MISSING: "E_CHECKSUM_MISSING";
+  NOT_CANONICAL: "E_NOT_CANONICAL";
+  PRINCIPAL: "E_PRINCIPAL";
+  HEX: "E_HEX";
+  BASE64: "E_BASE64";
+  UTF8: "E_UTF8";
+  LENGTH: "E_LENGTH";
+  MAX_LEN: "E_MAX_LEN";
+}>;
+export type FormatErrorCode = (typeof CODES)[keyof typeof CODES];
+
+/** Every rejection in this package. `message` says how to fix the input. */
+export declare class FormatError extends Error {
+  constructor(code: FormatErrorCode, message: string);
+  name: "FormatError";
+  code: FormatErrorCode;
+}
+
+export interface AmountOptions {
+  decimals: number | bigint | string;
+  symbol?: string;
+  /** The Candid type, for the sign and range (default `nat`). */
+  candid?: 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;
+/** Base units to "1.5 ICP". A number is refused: pass a decimal string or a bigint. */
+export function displayAmount(value: string | bigint, options: AmountOptions): string;
+
+/** An integer between units; to a coarser unit it must be an exact multiple (E_INEXACT otherwise). */
+export function convertUnit(value: string | bigint, from: TimeUnit, to: TimeUnit): string;
+/** A clock reading in ns floored to `unit`, as `parseTimestamp` applies it to `now`. */
+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;
+/** 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". */
+export function displayDuration(value: string | bigint, options: { unit: TimeUnit; candid?: string }): string;
+
+/** ICRC-1 account text; the checksum is verified and non-canonical text is refused. */
+export function parseAccount(input: string): Account;
+/** An account in the ICRC-1 textual encoding; a subaccount absent, null or all zero is the default. */
+export function displayAccount(account: { owner: string | Uint8Array; subaccount?: ByteInput | null }): string;
+/** Canonical principal text to its bytes; the CRC-32 must match. */
+export function principalFromText(text: string): Uint8Array;
+/** Up to 29 bytes to canonical principal text. */
+export function principalToText(bytes: Uint8Array): string;
+/** "#n", a decimal n, or 64 hex characters to 32 bytes. */
+export function parseSubaccount(input: string): Uint8Array;
+/** "#n" when the first 24 bytes are zero, else 64 lowercase hex characters. */
+export function displaySubaccount(value: ByteInput): string;
+/** Text in the tag's encoding to bytes; `maxLen` is the tag's `max_len`. */
+export function parseBytes(input: string, options: { encoding: BytesEncoding; maxLen?: number }): Uint8Array;
+export function displayBytes(value: ByteInput, options: { encoding: BytesEncoding }): string;
+/**
+ * The value as a Uint8Array of this realm, viewing the same memory, or null. Accepts a Uint8Array made in another
+ * realm (an iframe, a `node:vm` context), which fails `instanceof Uint8Array`; refuses other typed arrays, DataViews,
+ * look-alike objects and views of a detached buffer.
+ */
+export function asUint8Array(value: unknown): Uint8Array | null;
+
+/** The text a position reads, in words, with examples that parse there. */
+export interface Description {
+  summary: string;
+  examples: string[];
+  /** An ECMAScript regular expression every accepted input matches (amount and subaccount only). */
+  pattern?: string;
+}
+
+export type SafeResult<T> = { ok: true; value: T } | { ok: false; error: { code: FormatErrorCode; message: string } };
+
+/** What `parse` returns per tag: base units or a unit count as a decimal string, an account, or bytes. */
+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;
+  readonly candid: string;
+  readonly args: Readonly<Record<string, unknown>>;
+  /** Throws FormatError. */
+  parse(input: string, context?: { now?: bigint }): ParsedValue;
+  /** Throws FormatError. */
+  display(value: unknown): string;
+  safeParse(input: string, context?: { now?: bigint }): SafeResult<ParsedValue>;
+  safeDisplay(value: unknown): SafeResult<string>;
+  describe(): Description;
+}
+
+/** A position of a resolved form, as far as formatting reads it. */
+export interface FormatNode {
+  candid: string;
+  tags?: Record<string, { args?: Record<string, unknown> } | undefined>;
+  [key: string]: unknown;
+}
+
+/** The value tags, in spec order. */
+export const VALUE_TAGS: readonly ValueTag[];
+/**
+ * The formatter of a position, or null when it has no value tag (show it as Candid text). Throws FormatError for a
+ * missing ref, an invalid tag argument, a tag that does not fit the Candid type, or two value tags.
+ *
+ * @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
+ */
+export function formatterFor(node: FormatNode, options?: { refs?: Record<string, unknown>; now?: bigint }): 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;
+
+/** One entry of a names set (spec section 5.3, D-045), as the set's method lists it. */
+export interface NameEntry<V = unknown> {
+  name: string;
+  value: V;
+  show?: unknown;
+  kind?: unknown;
+}
+/** The result of resolveName: the input itself when it is a value, the one matching entry's value, or why not. */
+export type NameResolution<V = unknown> =
+  | { value: string; direct: true }
+  | { value: V | unknown; entry: NameEntry<V> }
+  | { error: "not_found" }
+  | { error: "ambiguous"; entries: NameEntry<V>[] };
+/** Unicode NFKC, the default full lowercase mapping, White_Space runs made one space, then trimmed. */
+export function normalizeName(text: string): string;
+/** Resolves a person's or an agent's text against a set's entries by the rule of spec section 5.3. */
+export function resolveName<V>(
+  entries: NameEntry<V>[],
+  input: string,
+  opts?: { isValue?: (text: string) => boolean; kind?: (kind: unknown) => boolean; by?: "value" | "show" },
+): NameResolution<V>;
+/** The one entry with a name that a value belongs to, compared as Candid values (an account by owner and subaccount). */
+export function ownerOf<V>(entries: NameEntry<V>[], value: unknown, opts?: { by?: "value" | "show" }): NameEntry<V> | undefined;
+/** A named position's display: the one owning entry's name beside the shown value, or the value alone. */
+export function nameOf<V>(entries: NameEntry<V>[], value: V, opts?: { by?: "value" | "show"; show?: (value: unknown) => string }): string;

package/src/index.mjs

@@ -0,0 +1,17 @@
+export { FormatError, CODES } from "./errors.mjs";
+export { parseAmount, displayAmount } from "./amount.mjs";
+export {
+  alignNow,
+  convertUnit,
+  displayDuration,
+  displayTimestamp,
+  parseDuration,
+  parseTimestamp,
+} from "./time.mjs";
+export { parseAccount, displayAccount } from "./account.mjs";
+export { principalFromText, principalToText } from "./principal.mjs";
+export { parseSubaccount, displaySubaccount } from "./subaccount.mjs";
+export { parseBytes, displayBytes } from "./bytes.mjs";
+export { describeInput, formatterFor, VALUE_TAGS } from "./formatter.mjs";
+export { asUint8Array } from "./util.mjs";
+export { normalizeName, resolveName, nameOf, ownerOf } from "./names.mjs";