{"record":{"id":"12c9a1056e15cf31","repo":"toon-format/toon","slug":"result-reason","errorCode":null,"errorMessage":"result.reason","messagePattern":"result\\.reason","errorType":"exception","errorClass":"SyntaxError","httpStatus":null,"severity":"error","filePath":"packages/toon/src/decode/decoders.ts","lineNumber":667,"sourceCode":"\n// #endregion\n\n// #region Shared decoder helpers\n\n// Keeps the detection/parse split free of error decisions. The bare\n// SyntaxError is deliberate: the caller's `withLine` wrapper enriches it into a\n// `ToonDecodeError` with a `cause`, matching the direct-throw path.\nfunction resolveArrayHeader(\n  result: ArrayHeaderParseResult,\n  strict: boolean,\n): { header: ArrayHeaderInfo, inlineValues?: string } | undefined {\n  if (result.kind === 'notHeader') {\n    return undefined\n  }\n\n  if (result.kind === 'invalid') {\n    if (strict) {\n      throw new SyntaxError(result.reason)\n    }\n    return undefined\n  }\n\n  // A valid header may still carry a strict-only violation that non-strict resolves via LWW.\n  if (strict && result.strictError !== undefined) {\n    throw new SyntaxError(result.strictError)\n  }\n\n  return { header: result.header, inlineValues: result.inlineValues }\n}\n\nfunction* yieldObjectFromFields(\n  fields: readonly FieldNode[],\n  primitives: readonly JsonPrimitive[],\n): Generator<JsonStreamEvent> {\n  let cellIndex = 0\n","sourceCodeStart":649,"sourceCodeEnd":685,"githubUrl":"https://github.com/toon-format/toon/blob/604eac266e35166bed6f5b9e3bd586e9c60a9330/packages/toon/src/decode/decoders.ts#L649-L685","documentation":"When resolving an array header that is syntactically recognizable but invalid, strict mode surfaces the header's specific reason (result.reason) as a SyntaxError, while non-strict mode returns undefined so the line is handled as ordinary content. The message text is whatever the header parser reported.","triggerScenarios":"resolveArrayHeader (via headerInfo/arrayHeader, called during array decoding) gets result.kind === 'invalid' with strict:true — e.g. `[abc]:` (non-numeric length) or a malformed field-list in `{...}`.","commonSituations":"Hand-edited array headers with a wrong or missing length; typos like `[2,]:` or `[]:`; generated headers corrupted by template errors; mismatched braces in the field list.","solutions":["Fix the array header to valid form `[N]{fields}:` with a non-negative integer length","Validate length matches the actual item count","Decode with strict:false so invalid headers fall back to normal content parsing","Check the generator emitting the header for template bugs"],"exampleFix":"// before\nitems[abc]:\n  - a\n\n// after\nitems[1]:\n  - a","handlingStrategy":"try-catch","validationCode":"function arrayHeadersLookValid(text: string): string[] {\n  const bad: string[] = []\n  for (const l of text.split('\\n')) {\n    const m = l.match(/^ *\\[([^\\]]*)\\]/)\n    if (m && !/^\\d+$/.test(m[1])) bad.push(l.trim())\n  }\n  return bad\n}","typeGuard":"function isValidArrayHeader(line: string): boolean {\n  return /^\\s*\\[\\d+\\](\\{[^}]*\\})?\\s*:/.test(line)\n}","tryCatchPattern":"try {\n  return decode(input, { strict: true })\n} catch (e) {\n  if (e instanceof SyntaxError) {\n    // e.message is the header parser's result.reason\n    return decode(input, { strict: false }) // invalid header parsed as regular content\n  }\n  throw e\n}","preventionTips":["Emit array headers as `[<nonNegativeInt>]{fields}:` via the encoder","Validate header lengths equal the actual item count","Catch SyntaxError separately from ToonDecodeError since strict header failures throw SyntaxError"],"tags":["toon","decoder","strict-mode","array-header","syntax"],"backgroundTag":"invalid-array-header","analyzedSha":"604eac266e35166bed6f5b9e3bd586e9c60a9330","analyzedAt":"2026-08-31T11:09:25.043Z","schemaVersion":2},"datasetVersion":"2026-08-31T14:17:45.589Z"}