@meantjs/format 0.0.0-bootstrap → 0.1.0

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";

package/src/names.mjs

@@ -0,0 +1,59 @@
+/**
+ * Names (spec section 5.3, D-045): the one normalization and the one resolution rule every consumer uses to turn a
+ * name ("my Savings" without the "my") into the value a `names` set gives for it.
+ */
+
+/** Unicode NFKC, the default full lowercase mapping, White_Space runs made one space, then trimmed. */
+export function normalizeName(text) {
+  return text.normalize("NFKC").toLowerCase().replace(/\p{White_Space}+/gu, " ").trim();
+}
+
+/**
+ * Resolves `input` against a set's entries.
+ *
+ * @param entries  [{ name, value, show?, kind? }] as the set's method lists them
+ * @param input    the text a person or an agent gave
+ * @param opts.isValue  whether a text is a valid value of the position by its own tags and type
+ * @param opts.kind     when given, only entries for which kind(entry.kind) is true can match
+ * @param opts.by       "value" (default) or "show": which field of the entry fills the position
+ * @returns { value, direct: true } for input that is a value; { value, entry } for one match;
+ *          { error: "not_found" } or { error: "ambiguous", entries } otherwise
+ */
+export function resolveName(entries, input, { isValue = () => false, kind, by = "value" } = {}) {
+  if (isValue(input)) return { value: input, direct: true };
+  const want = normalizeName(input);
+  if (!want) return { error: "not_found" };
+  const found = entries.filter((e) => {
+    const name = normalizeName(e.name);
+    return name !== "" && name === want && !isValue(e.name) && (!kind || kind(e.kind));
+  });
+  if (found.length === 0) return { error: "not_found" };
+  if (found.length > 1) return { error: "ambiguous", entries: found };
+  return { value: by === "show" ? found[0].show : found[0].value, entry: found[0] };
+}
+
+/**
+ * A Candid value as one comparable text: numbers and bigints by their digits, bytes by their content, records with
+ * their fields in order of name. Two values have the same key exactly when they are the same Candid value.
+ */
+function valueKey(value) {
+  return JSON.stringify(value, (_, v) => {
+    if (typeof v === "bigint" || typeof v === "number") return `#${v}`;
+    if (ArrayBuffer.isView(v)) return `0x${Array.from(new Uint8Array(v.buffer, v.byteOffset, v.byteLength), (b) => b.toString(16).padStart(2, "0")).join("")}`;
+    if (v !== null && typeof v === "object" && !Array.isArray(v)) return Object.fromEntries(Object.keys(v).sort().map((k) => [k, v[k]]));
+    return v;
+  });
+}
+
+/** The one entry with a name that `value` belongs to, compared as Candid values (an account by owner and subaccount); undefined if none or several. */
+export function ownerOf(entries, value, { by = "value" } = {}) {
+  const key = valueKey(value);
+  const owners = entries.filter((e) => valueKey(by === "show" ? e.show : e.value) === key && normalizeName(e.name) !== "");
+  return owners.length === 1 ? owners[0] : undefined;
+}
+
+/** The display of a named position's value: the name of the one entry it belongs to, then the shown value. */
+export function nameOf(entries, value, { by = "value", show = String } = {}) {
+  const owner = ownerOf(entries, value, { by });
+  return owner ? `${owner.name} (${show(owner.show ?? value)})` : show(value);
+}

package/src/principal.mjs

@@ -0,0 +1,117 @@
+// Principal text <-> bytes, and the CRC-32 and base32 pieces shared with the ICRC-1 account text.
+//
+// Implemented here, with no dependency, because it is ~60 lines, the algorithm is fixed by the
+// Internet Computer interface specification ("textual ids": lowercase base32 without padding of
+// CRC-32 big-endian followed by the bytes, in groups of five separated by dashes), and it is
+// checked in the tests against the official ICRC-1 vectors, well-known canister ids, node:zlib's
+// CRC-32 and an independent big-integer base32 encoder. See README.md for why not
+// @dfinity/principal (deprecated) or @icp-sdk/core (large).
+
+import { CODES, fail } from "./errors.mjs";
+import { MAX_INPUT_CHARS, asUint8Array } from "./util.mjs";
+
+const ALPHABET = "abcdefghijklmnopqrstuvwxyz234567";
+export const MAX_PRINCIPAL_BYTES = 29;
+
+const CRC_TABLE = (() => {
+  const table = new Uint32Array(256);
+  for (let n = 0; n < 256; n++) {
+    let c = n;
+    for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    table[n] = c >>> 0;
+  }
+  return table;
+})();
+
+/** CRC-32 (IEEE 802.3, the zlib polynomial) as an unsigned 32-bit integer. */
+export function crc32(bytes) {
+  let c = 0xffffffff;
+  for (const b of bytes) c = CRC_TABLE[(c ^ b) & 0xff] ^ (c >>> 8);
+  return (c ^ 0xffffffff) >>> 0;
+}
+
+const crc32BigEndian = (bytes) => {
+  const out = new Uint8Array(4);
+  new DataView(out.buffer).setUint32(0, crc32(bytes), false);
+  return out;
+};
+
+/** RFC 4648 base32, lowercase, no padding. */
+export function base32Encode(bytes) {
+  let out = "";
+  let bits = 0;
+  let acc = 0;
+  for (const b of bytes) {
+    acc = (acc << 8) | b;
+    bits += 8;
+    while (bits >= 5) {
+      out += ALPHABET[(acc >>> (bits - 5)) & 31];
+      bits -= 5;
+    }
+    acc &= (1 << bits) - 1;
+  }
+  if (bits > 0) out += ALPHABET[(acc << (5 - bits)) & 31];
+  return out;
+}
+
+/** Strict decode of lowercase base32 without padding; null on a bad character, length or spare bit. */
+function base32Decode(text) {
+  const out = [];
+  let bits = 0;
+  let acc = 0;
+  for (const ch of text) {
+    const v = ALPHABET.indexOf(ch);
+    if (v < 0) return null;
+    acc = (acc << 5) | v;
+    bits += 5;
+    if (bits >= 8) {
+      out.push((acc >>> (bits - 8)) & 0xff);
+      bits -= 8;
+    }
+    acc &= (1 << bits) - 1;
+  }
+  if (bits >= 5 || acc !== 0) return null; // a stray character or non-zero padding bits
+  return Uint8Array.from(out);
+}
+
+/** The ICRC-1 checksum of an account: base32(CRC-32(owner bytes ++ subaccount bytes)), 7 characters. */
+export function accountChecksum(ownerBytes, subaccount) {
+  const all = new Uint8Array(ownerBytes.length + subaccount.length);
+  all.set(ownerBytes, 0);
+  all.set(subaccount, ownerBytes.length);
+  return base32Encode(crc32BigEndian(all));
+}
+
+/** Canonical principal text for up to 29 bytes. */
+export function principalToText(input) {
+  const bytes = asUint8Array(input);
+  if (bytes === null) fail(CODES.TYPE, "principal bytes must be a Uint8Array");
+  if (bytes.length > MAX_PRINCIPAL_BYTES) fail(CODES.PRINCIPAL, `a principal is at most ${MAX_PRINCIPAL_BYTES} bytes, got ${bytes.length}`);
+  const crc = crc32BigEndian(bytes);
+  const all = new Uint8Array(4 + bytes.length);
+  all.set(crc, 0);
+  all.set(bytes, 4);
+  return base32Encode(all).match(/.{1,5}/g).join("-");
+}
+
+/**
+ * Principal text to bytes. Case-insensitive; the dashes must be exactly where the canonical text
+ * puts them, and the CRC-32 must match. Anything else throws E_PRINCIPAL.
+ */
+export function principalFromText(text) {
+  if (typeof text !== "string") fail(CODES.TYPE, `principal must be a string, got ${typeof text}`);
+  if (text.length > MAX_INPUT_CHARS) fail(CODES.TOO_LONG, "principal text is too long");
+  const lower = text.toLowerCase();
+  const decoded = base32Decode(lower.replaceAll("-", ""));
+  if (decoded === null) fail(CODES.PRINCIPAL, `${JSON.stringify(text)} is not a principal: it must be base32 (a to z, 2 to 7) in groups of five separated by dashes`);
+  if (decoded.length < 4) fail(CODES.PRINCIPAL, `${JSON.stringify(text)} is not a principal: too short`);
+  const data = decoded.subarray(4);
+  if (data.length > MAX_PRINCIPAL_BYTES) fail(CODES.PRINCIPAL, `${JSON.stringify(text)} is not a principal: more than ${MAX_PRINCIPAL_BYTES} bytes`);
+  const expected = crc32BigEndian(data);
+  if (!decoded.subarray(0, 4).every((b, i) => b === expected[i])) {
+    fail(CODES.PRINCIPAL, `${JSON.stringify(text)} is not a principal: the checksum does not match (a character was probably mistyped)`);
+  }
+  const canonical = principalToText(data);
+  if (lower !== canonical) fail(CODES.PRINCIPAL, `${JSON.stringify(text)} is not a canonical principal: dashes must separate groups of five, as in "${canonical}"`);
+  return Uint8Array.from(data);
+}