err-codes.js

/** Runtime error registry shared by emitters, catch materialization and interop.
 *  Codes are private diagnostics; source observes ordinary Error objects.
 *  Internal throws encode a reserved atom, so user-thrown numbers cannot collide.
 *  fs.js forwards POSIX errno values independently of this registry.
 */

/** The 7 built-in Error classes jz models. Class identity is carried by the
 *  SCHEMA ID (module/schema.js's `ctx.schema.errorSid(className)` — one id per
 *  class, minted with this array's name as an internal dedupe salt that never
 *  becomes a property), not by any in-object slot — jz has no prototype chain,
 *  so this array (not a class pointer) is what `instanceof`/toString/interop's
 *  decodeThrown read to tell classes apart, keyed by sid rather than by index
 *  into this array. Order is not a stability contract for any encoding (unlike
 *  the old __errcls__ small-int slot this array used to index) — kept stable
 *  anyway since it's also the emit/instanceof-fold iteration order. */
export const ERR_CLASS_NAMES = ['Error', 'TypeError', 'RangeError', 'SyntaxError', 'ReferenceError', 'URIError', 'EvalError']

/** Physical schema every jz Error-class instance is allocated with — two
 *  perfectly ordinary, perfectly enumerable slots. All 7 classes share this
 *  IDENTICAL prop list; what makes a TypeError a TypeError is which of the 7
 *  DISTINCT schema ids (module/schema.js's errorSid, salted per class name)
 *  its pointer carries, not anything stored in the slots themselves (audit-#9
 *  P0-2 brand redesign — supersedes the old shared-sid + hidden __errcls__
 *  slot + prepare-time-enforced-unspellable-name design, which required every
 *  object consumer — enumeration, dyn dispatch, JSON.stringify, Object.assign,
 *  spread — to individually remember to filter the slot out, and still left
 *  `Object.assign`/spread crashing on a real Error operand because neither
 *  had been taught the slot existed at all). No reservation, no unspellable
 *  name, no filtering: `{ __errcls__: 1 }` is now an ordinary user object. */
export const ERR_SCHEMA_PROPS = ['message', 'name']

export const ERR = {
  // ── 1xx TypeError-class ──────────────────────────────────────────────────
  TO_PRIMITIVE: 100,           // OrdinaryToPrimitive: every valueOf/toString returned non-primitive
  ARRAY_FROM_MAPFN: 101,       // Array.from(iterable, mapFn) — mapFn is not callable
  GROUP_BY_CALLBACK: 102,      // Object.groupBy/Map.groupBy — callback is not callable
  CLONE_UNCLONEABLE: 103,      // structuredClone — function/host handle can't be cloned
  ITERATE_NULLISH: 104,        // for-of/spread over null/undefined
  CRYPTO_NOT_TYPED: 105,       // crypto.getRandomValues — receiver not an integer-typed array
  CRYPTO_FLOAT_TYPE: 106,      // crypto.getRandomValues — Float32Array/Float64Array rejected
  JSON_CIRCULAR: 107,          // JSON.stringify — circular reference
  JSON_BIGINT: 108,            // JSON.stringify — BigInt has no JSON representation
  OBJECT_NULLISH: 109,         // Object.keys/values/entries(null/undefined)
  SYMBOL_TO_NUMBER: 110,       // ToNumber(Symbol)
  STRING_SEARCH_REGEX: 111,    // String#{includes,startsWith,endsWith}(regex)
  ENCODE_INTO_RECEIVER: 112,   // String#encodeInto — destination not a Uint8Array
  U8_RECEIVER: 113,            // Uint8Array-only method called on a non-Uint8Array
  ATOMICS_RECEIVER32: 114,     // Atomics.* — receiver not an Int32Array
  ATOMICS_RECEIVER64: 115,     // Atomics.* — receiver not a BigInt64Array
  BIGINT_UNDEF_MIX: 116,       // BigInt arithmetic (+-*/%,&|^,<<,>>) — the other
                                // operand is a dict/Map absent-key read: ToNumeric
                                // reads real JS `undefined` as Number NaN, mismatching
                                // the BigInt operand's type (ES2024 13.15.3 step 6)
  ARRAY_FROM_ITERABLE: 117,    // Array.from — iterable protocol unsupported for this source
  ERROR_MESSAGE_OBJECT: 118,   // Error(message) — runtime object ToPrimitive path is unsupported
  ACCESSOR_DESCRIPTOR: 119,    // Object.defineProperty – accessor descriptor (get/set) at runtime
  BIGINT_NULLISH: 120,         // BigInt(null/undefined) — ToBigInt of a nullish value
  BIGINT_UNSIGNED_SHIFT: 121,  // `>>>` — a BigInt operand at runtime (ES2020 §6.1.6.2.11: no BigInt::unsignedRightShift)
  DATAVIEW_INDEX_WRITE: 122,   // indexed own properties on DataView are unsupported
  BIGINT_TO_NUMBER: 123,      // implicit ToNumber(BigInt)
  PRIMITIVE_PROPERTY: 124,     // a property store on a Number, String, Boolean or BigInt (strict code)
  DELETE_PROPERTY: 125,       // strict delete of a nonconfigurable own property
  FS_BUFFER: 126,              // fs.readSync/writeSync: buffer is not a TypedArray (or, for writeSync, a string)
  FS_OFFSET: 127,              // fs.readSync/writeSync: offset is not a Number
  FS_EMPTY: 128,               // fs.readSync: a nonzero length into an empty buffer

  // ── 2xx RangeError-class ─────────────────────────────────────────────────
  ARRAY_WITH_INDEX: 200,       // Array.prototype.with — index out of range
  ATOMICS_INDEX32: 201,        // Atomics.* — Int32Array index out of range
  ATOMICS_INDEX64: 202,        // Atomics.* — BigInt64Array index out of range
  CRYPTO_QUOTA: 203,           // crypto.getRandomValues — byteLength > 65536
  JSON_TOO_DEEP: 204,          // JSON.stringify — nesting exceeds jz's cycle-stack buffer
  NUMBER_RADIX: 205,           // Number.prototype.toString(radix) — radix outside [2,36]
  NUMBER_TO_BIGINT_RANGE: 206, // BigInt(number) — not a finite integer
  FROM_CODE_POINT_RANGE: 207,  // String.fromCodePoint — not an integer in [0, 0x10FFFF]
  ARRAY_BUFFER_LENGTH: 208,    // new ArrayBuffer(n) — negative or unrepresentable length
  DATAVIEW_INDEX_RANGE: 209,   // DataView get/set — byte offset negative or > 2^53-1
  DATAVIEW_OFFSET_OOB_FAST: 210, // DataView get/set (proven-i32 offset) — outside view bounds
  DATAVIEW_OFFSET_OOB: 211,    // DataView get/set (dynamic offset) — outside view bounds
  TYPED_WITH_INDEX: 212,       // TypedArray.prototype.with — index out of range
  ARRAY_FROM_LENGTH: 213,      // Array.from array-like length exceeds wasm32 array range
  TYPED_SET_OFFSET: 214,       // TypedArray.prototype.set: offset negative or source past the receiver's end
  HEAP_EXHAUSTED: 215,         // an allocation the linear memory cannot grow to hold (its maximum, wasm32 or the engine's limit)
  ARRAY_LENGTH: 216,           // ArraySetLength: ToUint32(value) differs from ToNumber(value)
  FS_RANGE: 217,               // fs.readSync/writeSync: offset or length outside the buffer

  // ── 3xx SyntaxError/URIError-class ───────────────────────────────────────
  JSON_PARSE_SYNTAX: 300,      // JSON.parse — malformed input
  BIGINT_PARSE_DIGIT: 301,     // BigInt(string) — invalid digit for the given radix
  BIGINT_PARSE_EMPTY: 302,     // BigInt(string) — sign/radix prefix with no digits
  URI_TRUNC_ESCAPE: 303,       // decodeURI(Component) — truncated %-escape
  URI_BAD_HEX: 304,            // decodeURI(Component) — non-hex digit after %
  URI_BAD_LEAD_BYTE: 305,      // decodeURI(Component) — invalid UTF-8 leading byte
  URI_TRUNC_CONT_ESCAPE: 306,  // decodeURI(Component) — truncated continuation %-escape
  URI_MISSING_CONT_PERCENT: 307, // decodeURI(Component) — continuation byte not %-escaped
  URI_BAD_CONT_HEX: 308,       // decodeURI(Component) — non-hex digit in continuation escape
  URI_BAD_CONT_BYTE: 309,      // decodeURI(Component) — continuation byte outside 0x80-0xBF
  URI_BAD_CODEPOINT: 310,      // decodeURI(Component) — out-of-range or surrogate code point
  BASE64_TRAILING_CHAR: 311,   // fromBase64 — non-whitespace char after complete padding
  BASE64_EARLY_PAD: 312,       // fromBase64 — '=' with fewer than 2 chars in the quantum
  BASE64_CHAR_AFTER_PAD: 313,  // fromBase64 — value char inside an open padding run
  BASE64_INVALID_CHAR: 314,    // fromBase64 — char outside the base64/base64url alphabet
  BASE64_UNTERMINATED_PAD: 315, // fromBase64 — EOF with an unterminated padding run
  BASE64_LEFTOVER_CHAR: 316,   // fromBase64 — EOF with exactly one leftover quantum char
  TEXT_DECODE_INPUT: 321,     // TextDecoder input is not a BufferSource
  TEXT_DECODE: 320,           // TextDecoder fatal UTF-8 decoding error
  BTOA_CHARACTER: 319,        // btoa — code unit outside the Latin-1 byte range
  HEX_ODD_LENGTH: 317,         // fromHex/setFromHex — odd-length input
  HEX_INVALID_DIGIT: 318,      // fromHex/setFromHex — non-hex character
  DYNAMIC_CODE: 322,           // Function constructor — the target compiles no code at run time
}

/** code → { name, message }. `name` is the ECMAScript error class this site
 *  models (used by interop.js's decodeThrown to build a real host Error). */
export const ERR_INFO = {
  [ERR.TEXT_DECODE_INPUT]: { name: 'TypeError', message: 'TextDecoder input must be an ArrayBuffer or view' },
  [ERR.TEXT_DECODE]: { name: 'TypeError', message: 'The encoded data is not valid UTF-8' },
  [ERR.BTOA_CHARACTER]: { name: 'InvalidCharacterError', message: 'The string contains a character outside the Latin-1 range' },
  [ERR.TO_PRIMITIVE]: { name: 'TypeError', message: 'Cannot convert object to primitive value' },
  [ERR.ARRAY_FROM_MAPFN]: { name: 'TypeError', message: 'Array.from: mapFn is not a function' },
  [ERR.GROUP_BY_CALLBACK]: { name: 'TypeError', message: 'groupBy callback is not a function' },
  [ERR.CLONE_UNCLONEABLE]: { name: 'TypeError', message: 'could not be cloned' },
  [ERR.ITERATE_NULLISH]: { name: 'TypeError', message: 'Cannot iterate null or undefined' },
  [ERR.CRYPTO_NOT_TYPED]: { name: 'TypeError', message: 'getRandomValues: argument must be an integer-typed array' },
  [ERR.DATAVIEW_INDEX_WRITE]: { name: 'TypeError', message: 'DataView indexed properties are unsupported; use setInt8/setUint8 or another DataView setter to write bytes' },
  [ERR.CRYPTO_FLOAT_TYPE]: { name: 'TypeError', message: 'getRandomValues: Float32Array/Float64Array are not allowed' },
  [ERR.JSON_CIRCULAR]: { name: 'TypeError', message: 'Converting circular structure to JSON' },
  [ERR.JSON_BIGINT]: { name: 'TypeError', message: 'Do not know how to serialize a BigInt' },
  [ERR.OBJECT_NULLISH]: { name: 'TypeError', message: 'Cannot convert undefined or null to object' },
  [ERR.ACCESSOR_DESCRIPTOR]: { name: 'TypeError', message: 'Accessor descriptors are declared on classes; Object.defineProperty defines data properties' },
  [ERR.SYMBOL_TO_NUMBER]: { name: 'TypeError', message: 'Cannot convert a Symbol value to a number' },
  [ERR.BIGINT_TO_NUMBER]: { name: 'TypeError', message: 'Cannot convert a BigInt value to a number' },
  [ERR.DELETE_PROPERTY]: { name: 'TypeError', message: 'Cannot delete a non-configurable property' },
  [ERR.FS_BUFFER]: { name: 'TypeError', message: 'The "buffer" argument must be a TypedArray; writeSync also takes a string with no position' },
  [ERR.FS_OFFSET]: { name: 'TypeError', message: 'The "offset" argument must be of type number' },
  [ERR.FS_EMPTY]: { name: 'TypeError', message: "The argument 'buffer' is empty and cannot be written" },
  [ERR.PRIMITIVE_PROPERTY]: { name: 'TypeError', message: 'Cannot create a property on a primitive' },
  [ERR.STRING_SEARCH_REGEX]: { name: 'TypeError', message: 'First argument must not be a regular expression' },
  [ERR.ENCODE_INTO_RECEIVER]: { name: 'TypeError', message: 'encodeInto: destination must be a Uint8Array' },
  [ERR.ARRAY_FROM_ITERABLE]: { name: 'TypeError', message: 'Array.from iterable sources are unsupported; pass an array-like value' },
  [ERR.U8_RECEIVER]: { name: 'TypeError', message: 'receiver must be a Uint8Array' },
  [ERR.ATOMICS_RECEIVER32]: { name: 'TypeError', message: 'Atomics: receiver must be an Int32Array' },
  [ERR.ATOMICS_RECEIVER64]: { name: 'TypeError', message: 'Atomics: receiver must be a BigInt64Array' },
  [ERR.BIGINT_UNDEF_MIX]: { name: 'TypeError', message: 'Cannot mix BigInt and other types, use explicit conversions' },
  [ERR.BIGINT_NULLISH]: { name: 'TypeError', message: 'Cannot convert null or undefined to a BigInt' },
  [ERR.BIGINT_UNSIGNED_SHIFT]: { name: 'TypeError', message: 'BigInts have no unsigned right shift, use >> instead' },
  [ERR.ERROR_MESSAGE_OBJECT]: { name: 'TypeError', message: 'Error message object coercion is not supported; convert it explicitly with String(...)' },

  [ERR.ARRAY_WITH_INDEX]: { name: 'RangeError', message: 'Invalid index' },
  [ERR.ATOMICS_INDEX32]: { name: 'RangeError', message: 'index out of range' },
  [ERR.ATOMICS_INDEX64]: { name: 'RangeError', message: 'index out of range' },
  [ERR.CRYPTO_QUOTA]: { name: 'RangeError', message: 'byteLength exceeds the maximum of 65536' },
  [ERR.JSON_TOO_DEEP]: { name: 'RangeError', message: 'JSON structure nesting too deep' },
  [ERR.NUMBER_RADIX]: { name: 'RangeError', message: 'toString() radix argument must be between 2 and 36' },
  [ERR.NUMBER_TO_BIGINT_RANGE]: { name: 'RangeError', message: 'The number is not a finite integer, cannot convert to a BigInt' },
  [ERR.FROM_CODE_POINT_RANGE]: { name: 'RangeError', message: 'Invalid code point' },
  [ERR.ARRAY_BUFFER_LENGTH]: { name: 'RangeError', message: 'Invalid array buffer length' },
  [ERR.DATAVIEW_INDEX_RANGE]: { name: 'RangeError', message: 'Invalid DataView offset' },
  [ERR.DATAVIEW_OFFSET_OOB_FAST]: { name: 'RangeError', message: 'Offset is outside the bounds of the DataView' },
  [ERR.DATAVIEW_OFFSET_OOB]: { name: 'RangeError', message: 'Offset is outside the bounds of the DataView' },
  [ERR.TYPED_WITH_INDEX]: { name: 'RangeError', message: 'Invalid typed array index' },
  [ERR.ARRAY_FROM_LENGTH]: { name: 'RangeError', message: 'Array.from length exceeds the supported array range' },
  [ERR.TYPED_SET_OFFSET]: { name: 'RangeError', message: 'offset is out of bounds' },
  [ERR.HEAP_EXHAUSTED]: { name: 'RangeError', message: 'Out of memory: the heap cannot grow' },
  [ERR.ARRAY_LENGTH]: { name: 'RangeError', message: 'Invalid array length' },
  [ERR.FS_RANGE]: { name: 'RangeError', message: 'The value of "offset" or "length" is out of range' },

  [ERR.JSON_PARSE_SYNTAX]: { name: 'SyntaxError', message: 'Unexpected token in JSON' },
  [ERR.BIGINT_PARSE_DIGIT]: { name: 'SyntaxError', message: 'Cannot convert string to a BigInt' },
  [ERR.BIGINT_PARSE_EMPTY]: { name: 'SyntaxError', message: 'Cannot convert string to a BigInt' },
  [ERR.URI_TRUNC_ESCAPE]: { name: 'URIError', message: 'URI malformed' },
  [ERR.URI_BAD_HEX]: { name: 'URIError', message: 'URI malformed' },
  [ERR.URI_BAD_LEAD_BYTE]: { name: 'URIError', message: 'URI malformed' },
  [ERR.URI_TRUNC_CONT_ESCAPE]: { name: 'URIError', message: 'URI malformed' },
  [ERR.URI_MISSING_CONT_PERCENT]: { name: 'URIError', message: 'URI malformed' },
  [ERR.URI_BAD_CONT_HEX]: { name: 'URIError', message: 'URI malformed' },
  [ERR.URI_BAD_CONT_BYTE]: { name: 'URIError', message: 'URI malformed' },
  [ERR.URI_BAD_CODEPOINT]: { name: 'URIError', message: 'URI malformed' },
  [ERR.BASE64_TRAILING_CHAR]: { name: 'SyntaxError', message: 'Unexpected character after base64 padding' },
  [ERR.BASE64_EARLY_PAD]: { name: 'SyntaxError', message: 'Unexpected base64 padding' },
  [ERR.BASE64_CHAR_AFTER_PAD]: { name: 'SyntaxError', message: 'Unexpected character after base64 padding' },
  [ERR.BASE64_INVALID_CHAR]: { name: 'SyntaxError', message: 'Invalid base64 character' },
  [ERR.BASE64_UNTERMINATED_PAD]: { name: 'SyntaxError', message: 'Unterminated base64 padding' },
  [ERR.BASE64_LEFTOVER_CHAR]: { name: 'SyntaxError', message: 'Malformed base64 string' },
  [ERR.HEX_ODD_LENGTH]: { name: 'SyntaxError', message: 'Hex string must have an even length' },
  [ERR.HEX_INVALID_DIGIT]: { name: 'SyntaxError', message: 'Invalid hex character' },
  [ERR.DYNAMIC_CODE]: { name: 'TypeError', message: 'Function constructor: the target compiles no code at run time' },
}

/** Internal exception transport. Reserved atom 3 carries a code in its low word;
 *  catch materializes an ordinary branded Error before source can observe it.
 *  User-thrown numbers remain numbers, including values equal to these codes. */
export const ERROR_CODE_HI = 0x7ff80003
export const errorCodeLiteral = code => 'nan:0x80003' + code.toString(16).padStart(8, '0')