@jarenjs/core 0.9.2 → 0.34.2

package/dist/types/object.d.ts

@@ -24,12 +24,163 @@ export declare function equalsDeep(target: any, source: any): boolean;
  * @returns {boolean}
  */
 export declare function equalsJson(a: any, b: any): boolean;
+/**
+ * Ordering of two JSON values per RFC 9535 section 2.3.5.2.2 — the
+ * ordering half of the comparison family whose equality half is
+ * `equalsJson`.
+ *
+ * Only two numbers or two strings order at all: numbers by value,
+ * strings by Unicode scalar values (`compareCodePoints`, not the native
+ * `<`). Every other pair — mismatched types, objects, arrays, booleans,
+ * null — is simply `false` in both directions, never an error.
+ *
+ * @param {any} a
+ * @param {any} b
+ * @param {boolean} [orEqual] when true test `<=` instead of `<`
+ * @returns {boolean}
+ */
+export declare function compareJsonScalarLt(a: any, b: any, orEqual?: boolean): boolean;
 /**
  * Check if all items in an array are unique using deep equality
  * @param {any[]} arr - The array to check
  * @returns {boolean} True if all items are unique
  */
 export declare function isUniqueDeepArray(arr: any[]): boolean;
+/**
+ * Deterministic JSON text for plain data: like `JSON.stringify`, but
+ * object keys are emitted in sorted order at every depth, so two
+ * structurally equal values always produce the same string (a stable
+ * cache/memo/fingerprint key regardless of key insertion order).
+ * Non-JSON values follow `JSON.stringify` semantics (undefined members
+ * are dropped, undefined roots return undefined).
+ *
+ * That leniency is what makes it a memo key and not an interchange
+ * format: dropping a member changes the document. For output that is
+ * hashed or signed, use `canonicalizeJson` (`@jarenjs/json/canonical`,
+ * RFC 8785), which rejects every non-JSON input instead of coercing it.
+ * @param {*} value - The value to serialize
+ * @returns {string|undefined} Deterministic JSON text
+ */
+export declare function stableStringify(value: any): string | undefined;
+/**
+ * The suite's one MEMO-GRADE content key: `hashContent(stableStringify
+ * (value) ?? '')`. Two structurally equal plain-JSON values produce the
+ * same key regardless of property insertion order — which is exactly
+ * what a reconciliation key wants and exactly what `JSON.stringify`-based
+ * keys get wrong.
+ *
+ * **This is a 32-bit FINGERPRINT, never an identity.** Distinct values
+ * DO share a key — the birthday bound puts the first collision around
+ * 65k documents, and one turns up after ~113k trivially different query
+ * documents in practice. So it is sound for a vnode `key`, a DOM id, a
+ * bucket index or a diagnostic label, and WRONG as the sole identity of
+ * anything whose reuse changes a result: a compiled query, a query plan,
+ * a registered SQL function body, a memoized render. For those use
+ * {@link semanticKey}, which compares the whole serialization.
+ *
+ * Two further properties a caller must know, inherited from
+ * `stableStringify`: **`undefined` members are dropped** (two values
+ * differing only in an `undefined` member share a key) and there is
+ * **no cycle guard** (a cyclic value overflows the stack). Both are fine
+ * for a fingerprint and wrong for a checksum — for anything hashed,
+ * signed or recorded, use `canonicalizeJson`
+ * (`@jarenjs/json/canonical`, RFC 8785) instead. Do not conflate the
+ * three.
+ * @param {*} value - The value to derive a fingerprint for
+ * @returns {string} base-36 content hash of the stable serialization
+ */
+export declare function contentKey(value: any): string;
+/**
+ * The suite's one COLLISION-FREE semantic key: the COMPLETE
+ * deterministic serialization of a plain-data value. Two values share a
+ * key exactly when they are structurally equal, so a cache keyed by it
+ * can never serve one document's compiled semantics for another —
+ * which a hash-only key inevitably does (see {@link contentKey}).
+ *
+ * Use it wherever reuse changes a RESULT: compiled queries, query
+ * plans, load specifications, safe profiles, registered SQL function
+ * bodies, memoized renders. The key is longer than a fingerprint; for a
+ * bounded cache of a few hundred entries that cost is a few kilobytes
+ * and the alternative is wrong data.
+ *
+ * Injective over plain data, and STRICT about the rest: it distinguishes
+ * `-0` from `0`, `NaN`/`±Infinity` from `null` and from each other, and
+ * a present-but-`undefined` member from an absent one — every case
+ * `stableStringify` silently folds together. Values that cannot be
+ * keyed injectively are REFUSED with a `TypeError` rather than folded:
+ * functions, symbols, cycles, and non-plain objects (a `Date`, `Map`,
+ * `RegExp` or class instance, all of which serialize to `{}`), plus the
+ * two members a serialization cannot show — a symbol key, and an own
+ * array property past the last element. A caller that may hold such a
+ * value must treat the refusal as "not cacheable" and compute afresh —
+ * never as "reuse whatever shares the key".
+ *
+ * The identity covers OWN ENUMERABLE string-keyed properties, the same
+ * surface JSON reads. Two values differing only in a non-enumerable
+ * member are one value to this key, as they are to `JSON.stringify`.
+ * @param {*} value - The value to derive an identity for
+ * @returns {string} the complete deterministic serialization
+ * @throws {TypeError} When the value cannot be keyed injectively
+ */
+export declare function semanticKey(value: any): string;
+/**
+ * True for a JSON object — a non-null object that is not an array.
+ *
+ * This is the JSON data-model predicate, deliberately distinct from
+ * `isObjectType`: it treats `Map`, `Set`, `Date` and every other class
+ * instance as an object too, because at the JSON layer such a value has
+ * already been rejected or serialized before it gets here, and the only
+ * distinction that matters is object-vs-array.
+ *
+ * @param {any} value
+ * @returns {boolean}
+ */
+export declare function isJsonObject(value: any): boolean;
+/**
+ * Assign a member so that a key named `__proto__` becomes an own data
+ * property instead of reassigning the object's prototype. Every builder
+ * that turns untrusted names into members must go through this — a plain
+ * `out[name] = value` is a prototype-pollution hole for that one name.
+ *
+ * @param {Object} out target object
+ * @param {string} name member name, possibly attacker-controlled
+ * @param {any} value
+ */
+export declare function setObjectMember(out: Object, name: string, value: any): void;
+/**
+ * Whether a value can hold JSON members: an object or an array, not null.
+ * The complement of a JSON scalar.
+ * @param {any} value
+ * @returns {boolean}
+ */
+export declare function isJsonContainer(value: any): boolean;
+/**
+ * Copy one JSON container one level deep, preserving member order. Object
+ * spread copies an own `__proto__` data property as an own property
+ * (CreateDataProperty semantics), so this is pollution-safe.
+ * @template T
+ * @param {T} value - The container to copy
+ * @returns {T} A shallow copy; scalars are returned unchanged
+ */
+export declare function shallowCloneJson<T>(value: T): T;
+/**
+ * Deep-copy a JSON value. Scalars are returned as-is; containers are
+ * rebuilt so no part of the result is shared with the input.
+ * @template T
+ * @param {T} value - The JSON value to copy
+ * @returns {T} A deep copy sharing no container with the input
+ */
+export declare function cloneJson<T>(value: T): T;
+/**
+ * Recursively `Object.freeze` a value and everything reachable from it,
+ * returning the value. Scalars pass through untouched. Assumes an acyclic
+ * structure (a JSON value); a cycle would recurse forever.
+ *
+ * @template T
+ * @param {T} value
+ * @returns {T} the same value, deeply frozen
+ */
+export declare function deepFreeze<T>(value: T): T;
 /**
  *
  * @param {Map<any, any>} map

package/dist/types/scan.d.ts

@@ -12,6 +12,7 @@ export declare const CC_SQUOTE = 39;
 export declare const CC_LPAREN = 40;
 export declare const CC_RPAREN = 41;
 export declare const CC_STAR = 42;
+export declare const CC_PLUS = 43;
 export declare const CC_COMMA = 44;
 export declare const CC_MINUS = 45;
 export declare const CC_DOT = 46;
@@ -29,8 +30,14 @@ export declare const CC_LBRACKET = 91;
 export declare const CC_BACKSLASH = 92;
 export declare const CC_RBRACKET = 93;
 export declare const CC_UNDERSCORE = 95;
+export declare const CC_LOWER_B = 98;
+export declare const CC_LOWER_O = 111;
+export declare const CC_LOWER_X = 120;
+export declare const CC_LBRACE = 123;
 export declare const CC_PIPE = 124;
+export declare const CC_RBRACE = 125;
 export declare const CC_TILDE = 126;
+export declare const CC_DEL = 127;
 /**
  * Checks if a char code is an ASCII digit (0-9).
  * @param {number} c - The char code
@@ -43,6 +50,23 @@ export declare function isDigitCode(c: number): boolean;
  * @returns {boolean}
  */
 export declare function isHexDigitCode(c: number): boolean;
+/**
+ * Checks if a char code may start an unquoted name: an ASCII letter,
+ * `_`, or any non-ASCII code unit. Non-ASCII is admitted wholesale rather
+ * than by Unicode category, which is what the RFC 9535 shorthand member
+ * name and the XML Name productions both settle for in practice.
+ * @param {number} c - The char code
+ * @returns {boolean}
+ */
+export declare function isNameStartCode(c: number): boolean;
+/**
+ * Checks if a char code may continue an unquoted name: a name start or an
+ * ASCII digit. Grammars that also admit `-`/`.` inside names (XML Name,
+ * for one) test those separately on top of this.
+ * @param {number} c - The char code
+ * @returns {boolean}
+ */
+export declare function isNameCharCode(c: number): boolean;
 /**
  * Checks if a char code is blank space per RFC 9535 (space, tab,
  * line feed or carriage return).
@@ -62,3 +86,9 @@ export declare function isAsciiLowerCode(c: number): boolean;
  * @returns {boolean}
  */
 export declare function isAsciiUpperCode(c: number): boolean;
+/**
+ * Checks if a char code is an ASCII letter (A-Z or a-z).
+ * @param {number} c - The char code
+ * @returns {boolean}
+ */
+export declare function isAsciiLetterCode(c: number): boolean;

package/dist/types/schema.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @file The JSON Schema constraint-keyword vocabulary, grouped by the
+ * value family each keyword constrains. Before this file the same
+ * keyword lists were spelled four times (forms' constraint extraction,
+ * emit's dropped-constraint table, the validator's `$data` dispatch
+ * order and its `$ref`-sibling detection) — and a keyword added to one
+ * list silently missed the others. Each site composes the list it wants
+ * from these groups and appends its own extras; the loops stay where
+ * they are, because the drift risk was always in the data, not the
+ * code.
+ *
+ * ORDER IS PART OF THE CONTRACT: the validator's `$data` dispatch
+ * applies keywords in list order and its error order is observable
+ * behaviour, so the internal order of each group is fixed. Membership
+ * consumers are order-insensitive by construction.
+ */
+/** Keywords constraining numeric values, in dispatch order. */
+export declare const NUMERIC_CONSTRAINTS: readonly string[];
+/** Keywords constraining string values, in dispatch order. */
+export declare const STRING_CONSTRAINTS: readonly string[];
+/** Keywords constraining array values, in dispatch order. */
+export declare const ARRAY_CONSTRAINTS: readonly string[];
+/** Keywords constraining object values, in dispatch order. */
+export declare const OBJECT_CONSTRAINTS: readonly string[];

package/dist/types/string.d.ts

@@ -45,6 +45,15 @@ export declare function isAsciiString(str: string): boolean;
  * @returns {number}
  */
 export declare function getStringLength(str: string, useGrapheme?: boolean): number;
+/**
+ * Count occurrences of a UTF-16 code unit in a slice of a string.
+ * @param {string} str - The string to scan
+ * @param {number} code - The char code to count
+ * @param {number} [start] - Inclusive start offset (defaults to 0)
+ * @param {number} [end] - Exclusive end offset (defaults to full length)
+ * @returns {number} Number of occurrences in [start, end)
+ */
+export declare function countCharCode(str: string, code: number, start?: number, end?: number): number;
 /**
  * Count the Unicode code points of a string (surrogate-pair aware;
  * a lone surrogate counts as one code point).
@@ -52,6 +61,28 @@ export declare function getStringLength(str: string, useGrapheme?: boolean): num
  * @returns {number}
  */
 export declare function countCodePoints(str: string): number;
+/**
+ * Decode a string into its Unicode code points (surrogate-pair aware).
+ *
+ * `Array.from(str).map(c => c.codePointAt(0))` computes the same thing
+ * but allocates a string per character on the way; this reads the code
+ * units directly. An unpaired surrogate is kept as its own code point
+ * rather than replaced, so the result round-trips through
+ * {@link fromCodePoints} and a caller validating text can see the lone
+ * surrogate and reject it.
+ *
+ * @param {string} str - The string to decode
+ * @returns {number[]} The code points, in order
+ */
+export declare function toCodePoints(str: string): number[];
+/**
+ * Build a string from Unicode code points - the inverse of
+ * {@link toCodePoints}.
+ *
+ * @param {number[]} codePoints - The code points to encode
+ * @returns {string} The resulting string
+ */
+export declare function fromCodePoints(codePoints: number[]): string;
 /**
  * Compare two strings by Unicode scalar values (code points), per
  * RFC 9535 section 2.3.5.2.2. This differs from JavaScript's native
@@ -63,3 +94,68 @@ export declare function countCodePoints(str: string): number;
  * @returns {number} -1 when a < b, 0 when equal, 1 when a > b
  */
 export declare function compareCodePoints(a: string, b: string): number;
+/** FNV-1a 32-bit offset basis — the seed a fresh hash starts from. */
+export declare const FNV1A_OFFSET_BASIS = 2166136261;
+/**
+ * FNV-1a 32-bit hash of a string, as an unsigned 32-bit number. Not
+ * cryptographic — a stable, fast content fingerprint.
+ *
+ * Pass `seed` to continue an existing hash, which is what lets a caller
+ * fold a chunk stream or walk a tree without concatenating the pieces
+ * first: `fnv1a(b, fnv1a(a))` equals `fnv1a(a + b)`. Callers that just want
+ * a fingerprint string should use {@link hashContent} instead, so the whole
+ * suite agrees on one encoding.
+ *
+ * @param {string} str
+ * @param {number} [seed] running hash to continue, unsigned 32-bit
+ * @returns {number} unsigned 32-bit hash
+ */
+export declare function fnv1a(str: string, seed?: number): number;
+/**
+ * FNV-1a 32-bit hash of a string, returned as an unsigned base-36 string
+ * (at most 7 chars). Not cryptographic — a stable, fast content
+ * fingerprint for cache keys and reconciliation keys. The suite's single
+ * content-hash primitive: equal content produces the same fingerprint
+ * (and therefore the same vnode `key`/memo key) everywhere downstream, so
+ * do NOT invent a second hash — {@link fnv1a} is the one mixing step.
+ *
+ * @param {string} str
+ * @returns {string}
+ */
+export declare function hashContent(str: string): string;
+/**
+ * Convert a camelCase identifier to kebab-case by inserting a hyphen
+ * before each ASCII uppercase letter and lower-casing it
+ * (`fontFamily` → `font-family`). Leaves already-hyphenated or
+ * all-lowercase input unchanged.
+ *
+ * @param {string} s
+ * @returns {string}
+ */
+export declare function kebabCase(s: string): string;
+/**
+ * Convert heading text into a URL fragment the way GitHub does, so one
+ * committed document anchors identically on GitHub, in an editor preview
+ * and in a renderer that uses this: lower-case, drop punctuation and
+ * symbols, and turn each whitespace character into a hyphen.
+ *
+ * `-` and `_` survive, as do non-ASCII letters and digits
+ * (`Ünicode Wörks` → `ünicode-wörks`); a `§` or an em dash does not,
+ * because it is a symbol rather than a letter. Text that reduces to
+ * nothing (`***`) yields `''` — what an empty slug means is the caller's
+ * decision, not this function's.
+ *
+ * This is the suite's ONLY slug implementation: a second one would drift
+ * from the first and break the promise above. Whitespace is converted one
+ * character at a time, not per run, because that is what GitHub does and
+ * the resulting `--` is part of the fragment a reader may already have
+ * bookmarked.
+ *
+ * @example
+ * slugify('Hello, World!');   // 'hello-world'
+ * slugify('§ 3.1 — Setup');   // '-31--setup'
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+export declare function slugify(text: string): string;

package/dist/types/text/base64.d.ts

@@ -1,4 +1,6 @@
-export declare function isValidBase64Full(str: any): boolean;
-export declare function isValidBase64Old(str: any): boolean;
-export declare function isValidBase64(str: any): boolean;
-export declare function isValidBase64Fast(str: any): boolean;
+/**
+ * Validate a Base64-encoded string (RFC 4648).
+ * @param {string} str - The candidate encoding
+ * @returns {boolean} True when the string is well-formed Base64
+ */
+export declare function isValidBase64(str: string): boolean;

package/dist/types/text/email.d.ts

@@ -1,3 +1,2 @@
 export declare function isValidEmail(str: any): boolean;
-export declare function isValidEmailFull(str: any): boolean;
 export declare function isValidIdnEmail(str: any): boolean;

package/dist/types/text/host.d.ts

@@ -3,12 +3,43 @@ export declare function isValidIPv4(str: any): boolean;
 export declare function isValidIPv6(str: any): boolean;
 export declare function isValidHostname(str: any): boolean;
 export declare function isValidIdnHostname(str: any): boolean;
-export declare function isValidUrl(str: any): boolean;
-export declare function isValidUrlFull(str: any): boolean;
-export declare function isValidUri(str: any): boolean;
-export declare function isValidUriFull(str: any): boolean;
-export declare function isValidUriRef(str: any): boolean;
-export declare function isValidUriRefFull(str: any): boolean;
 export declare function isValidUriTemplate(str: any): boolean;
-export declare function isValidIRI(str: any): boolean;
-export declare function isValidIRIRef(str: any): boolean;
+/**
+ * Validate an absolute URI (RFC 3986 section 3) - a scheme followed by a
+ * hierarchical part, with an optional query and fragment.
+ * @param {string} str - The candidate URI
+ * @returns {boolean} True for a well-formed URI
+ */
+export declare function isValidUri(str: string): boolean;
+/**
+ * Validate a URI reference (RFC 3986 section 4.1) - a URI or a relative
+ * reference resolved against a base.
+ * @param {string} str - The candidate URI reference
+ * @returns {boolean} True for a well-formed URI reference
+ */
+export declare function isValidUriRef(str: string): boolean;
+/**
+ * Validate an absolute IRI (RFC 3987 section 2.2) - a URI whose
+ * unreserved characters extend into the `ucschar` ranges.
+ * @param {string} str - The candidate IRI
+ * @returns {boolean} True for a well-formed IRI
+ */
+export declare function isValidIRI(str: string): boolean;
+/**
+ * Validate an IRI reference (RFC 3987 section 2.2) - an IRI or a
+ * relative reference resolved against a base.
+ * @param {string} str - The candidate IRI reference
+ * @returns {boolean} True for a well-formed IRI reference
+ */
+export declare function isValidIRIRef(str: string): boolean;
+/**
+ * Validate a URL: a URI carrying one of the web schemes and an
+ * authority. The grammar is RFC 3986's - a URL is a narrower thing than
+ * a URI, not a looser one - so `http://x/a|b` is no more a URL than it
+ * is a URI, while `http://localhost:8080` and `http://127.0.0.1/` are
+ * both perfectly good ones.
+ *
+ * @param {string} str - The candidate URL
+ * @returns {boolean} True for a well-formed http or https URL
+ */
+export declare function isValidUrl(str: string): boolean;

package/dist/types/text/i18n.d.ts

@@ -8,6 +8,18 @@ export declare function isArabicIndicDigit(code: any): boolean;
 export declare function isExtendedArabicIndicDigit(code: any): boolean;
 export declare function isVirama(code: any): boolean;
 export declare function isCombiningMark(code: any): boolean;
-export declare function checkContextualRules(label: any): boolean;
+/**
+ * Check the IDNA contextual rules for a label (RFC 5892 appendix A):
+ * the characters that are only permitted next to particular scripts.
+ *
+ * Takes the label's code points rather than the label, matching
+ * `checkDigitMixing` - callers validating a label have already decoded
+ * it, and decoding it a second time here was the only reason this
+ * needed the string at all.
+ *
+ * @param {number[]} codes - The label's Unicode code points
+ * @returns {boolean} True when every contextual rule holds
+ */
+export declare function checkContextualRules(codes: number[]): boolean;
 export declare function checkDigitMixing(codes: any): boolean;
 export declare function isValidIdnChar(code: any): boolean;

package/dist/types/text/index.d.ts

@@ -6,3 +6,4 @@ export * from './i18n.js';
 export * from './identifiers.js';
 export * from './iregexp.js';
 export * from './misc.js';
+export * from './punycode.js';

package/dist/types/text/misc.d.ts

@@ -1,4 +1,18 @@
 export declare function isValidISBN10(str: any): boolean;
 export declare function isValidISBN13(str: any): boolean;
 export declare function isValidCountryAlpha2(str: any): boolean;
-export declare function isValidIBAN(str: any): boolean;
+/**
+ * Validate an International Bank Account Number (ISO 13616).
+ *
+ * Three independent things have to hold, and a string that satisfies only
+ * the first two is the common counterfeit: the country's registered
+ * length, the alphanumeric body shape, and the ISO 7064 MOD 97-10 check
+ * digits. Both written forms are accepted - the compact electronic format
+ * (`NL91ABNA0417164300`) and the ISO 13616-2 print format, which groups
+ * into fours with single spaces (`NL91 ABNA 0417 1643 00`). Lowercase is
+ * accepted for the same reason the other testers here accept it.
+ *
+ * @param {string} str - The candidate IBAN
+ * @returns {boolean} True when the string is a well-formed IBAN
+ */
+export declare function isValidIBAN(str: string): boolean;

package/dist/types/text/punycode.d.ts

@@ -1,86 +1,46 @@
-export declare const punycodeVersion = "2.1.0";
 /**
- * Creates an array containing the numeric code points of each Unicode
- * character in the string. While JavaScript uses UCS-2 internally,
- * this function will convert a pair of surrogate halves (each of which
- * UCS-2 exposes as separate characters) into a single code point,
- * matching UTF-16.
- * @see `punycode.ucs2.encode`
- * @see <https://mathiasbynens.be/notes/javascript-encoding>
- * @memberOf punycode.ucs2
- * @name decode
- * @param {String} string The Unicode input string (UCS-2).
- * @returns {Array} The new array of code points.
- */
-export declare function ucs2decode(string: string): any[];
-/**
- * Creates a string based on an array of numeric code points.
- * @see `punycode.ucs2.decode`
- * @memberOf punycode.ucs2
- * @name encode
- * @param {Array} codePoints The array of numeric code points.
- * @returns {String} The new Unicode string (UCS-2).
- */
-export declare const ucs2encode: (array: any) => string;
-/**
- * Converts a basic code point into a digit/integer.
- * @see `digitToBasic()`
- * @private
- * @param {Number} codePoint The basic numeric code point value.
- * @returns {Number} The numeric value of a basic code point (for use in
- * representing integers) in the range `0` to `base - 1`, or `base` if
- * the code point does not represent a value.
- */
-export declare function basicToDigit(codePoint: number): number;
-/**
- * Converts a digit/integer into a basic code point.
- * @see `basicToDigit()`
- * @private
- * @param {Number} digit The numeric value of a basic code point.
- * @returns {Number} The basic code point whose value (when used for
- * representing integers) is `digit`, which needs to be in the range
- * `0` to `base - 1`. If `flag` is non-zero, the uppercase form is
- * used; else, the lowercase form is used. The behavior is undefined
- * if `flag` is non-zero and `digit` has no uppercase form.
- */
-export declare function digitToBasic(digit: number, flag: any): number;
-/**
- * Converts a Punycode string of ASCII-only symbols to a string of Unicode
- * symbols.
- * @memberOf punycode
- * @param {String} input The Punycode string of ASCII-only symbols.
- * @returns {String} The resulting string of Unicode symbols.
- */
-export declare function decode(input: string): string;
-/**
- * Converts a string of Unicode symbols (e.g. a domain name label) to a
- * Punycode string of ASCII-only symbols.
- * @memberOf punycode
- * @param {String} input The string of Unicode symbols.
- * @returns {String} The resulting Punycode string of ASCII-only symbols.
- */
-export declare function encode(str: any): string;
-/**
- * Converts a Punycode string representing a domain name or an email address
- * to Unicode. Only the Punycoded parts of the input will be converted, i.e.
- * it doesn't matter if you call it on a string that has already been
- * converted to Unicode.
- * @memberOf punycode
- * @param {String} input The Punycoded domain name or email address to
- * convert to Unicode.
- * @returns {String} The Unicode representation of the given Punycode
- * string.
- */
-export declare function toUnicode(input: string): string;
-/**
- * Converts a Unicode string representing a domain name or an email address to
- * Punycode. Only the non-ASCII parts of the domain name will be converted,
- * i.e. it doesn't matter if you call it with a domain that's already in
- * ASCII.
- * @memberOf punycode
- * @param {String} input The domain name or email address to convert, as a
- * Unicode string.
- * @returns {String} The Punycode representation of the given domain name or
- * email address.
- */
-export declare function toASCII(input: string): string;
+ * Decode a Punycode string to Unicode. The input is a bare encoded
+ * label - the `xn--` prefix, if any, belongs to the caller.
+ *
+ * @param {string} input - The Punycode-encoded text
+ * @returns {string} The decoded Unicode text
+ * @throws {RangeError} On a non-basic input character, a truncated digit
+ *   sequence, or an integer overflow
+ * @example
+ * punycodeDecode('bcher-kva'); // 'bücher'
+ */
+export declare function punycodeDecode(input: string): string;
+/**
+ * Encode Unicode text as Punycode. The result is a bare encoded label -
+ * prefixing it with `xn--` is the caller's job.
+ *
+ * @param {string} str - The Unicode text
+ * @returns {string} The Punycode-encoded text
+ * @throws {RangeError} On an integer overflow
+ * @example
+ * punycodeEncode('bücher'); // 'bcher-kva'
+ */
+export declare function punycodeEncode(str: string): string;
+/**
+ * Convert a domain name or email address to its Unicode form, decoding
+ * every `xn--` label. Labels that are not encoded are left alone, so
+ * calling this on an already-Unicode name is harmless.
+ *
+ * @param {string} input - The domain name or email address
+ * @returns {string} The Unicode form
+ * @example
+ * domainToUnicode('xn--bcher-kva.example'); // 'bücher.example'
+ */
+export declare function domainToUnicode(input: string): string;
+/**
+ * Convert a domain name or email address to its ASCII (ACE) form,
+ * encoding every label that carries non-ASCII characters. Labels that
+ * are already ASCII are left alone, so calling this on an ASCII name is
+ * harmless.
+ *
+ * @param {string} input - The domain name or email address
+ * @returns {string} The ACE form
+ * @example
+ * domainToASCII('bücher.example'); // 'xn--bcher-kva.example'
+ */
+export declare function domainToASCII(input: string): string;

package/docs/CONVERT.md

@@ -0,0 +1,45 @@
+# `@jarenjs/core/convert`
+
+A tiny, data-driven engine for **pure, deterministic** quantity
+conversion. Zero dependencies. Import the barrel (`@jarenjs/core/convert`)
+or a single module.
+
+## Static dimensional conversion — `registry.js` + `convert.js`
+
+`convert(value, fromId, toId)` converts within a dimension, affine through
+the dimension's base unit:
+
+```
+base   = value * factor + offset
+target = (base - offset') / factor'
+```
+
+Most dimensions are linear (`offset` absent); **temperature** is affine
+(°C/°F/K/°R). Digital storage ships both **binary** (KiB/MiB, 1024) and
+**decimal** (KB/MB, 1000) prefixes. Dimensions: length, area, volume,
+mass, temperature, time, speed, pressure, energy, power, data, datarate,
+frequency, angle.
+
+Helpers: `unitsOf(dimension)`, `dimensions()`, `dimensionOf(unitId)`.
+Cross-dimension conversion throws a clear `RangeError`.
+
+## Currency — `currency.js`
+
+`convertCurrency(value, from, to, rateTable)` — the pure rate-table
+primitive. Deterministic, side-effect free, and it **never fetches**: the
+caller supplies the `{ code: rate }` table (or a `{ base, rates, at }`
+envelope). It lives in core because the dividing line is **purity**, not
+constant-vs-variable factors — this function is as pure as the fixed-factor
+path, it just receives its factors as an argument. Only *fetching* the
+table is impure, and that stays in the app component (see `@jarenjs/calc`).
+
+Rate convention: `rate[code]` is the value of one unit of `code` in the
+table's base currency, so `result = value * rate[from] / rate[to]`.
+`currenciesOf(rateTable)` lists the codes.
+
+## Not here
+
+Number-base conversion (HEX/DEC/OCT/BIN) is `@jarenjs/core/math/word.js`
+(`toBase`/`fromBase`), standalone — base is a notation, not a dimension,
+so the converter has no "base" category.
+Fuel-economy (mpg ↔ L/100km) is non-affine and outside this model.