@qzsy/arrow-parser

Parse arrow format LLM structured output into JavaScript objects. Schema-aware parsing supports nested objects and arrays (string arrays and object arrays with ITEM -> START ... END blocks).

Install

npm install @qzsy/arrow-parser

Quick start

Flat parse (scalars only)

import { parseFromLlm } from "@qzsy/arrow-parser";

const text = `DATA -> START
TITLE -> "Hello"
SCORE -> 95
DATA -> END`;

parseFromLlm(text);
// { TITLE: "Hello", SCORE: 95 }

Schema-aware parse (recommended)

Use with JSON Schema (from Zod via zod-to-json-schema):

import { parseToJson } from "@qzsy/arrow-parser";

const schema = {
  type: "object",
  properties: {
    strengths: { type: "array", items: { type: "string" } },
    suggestions: { type: "array", items: { type: "string" } },
  },
};

const text = `DATA -> START
STRENGTHS -> START
观察细致
逻辑清晰
STRENGTHS -> END
SUGGESTIONS -> START
建议加强练习
SUGGESTIONS -> END
DATA -> END`;

parseToJson(text, schema);
// { strengths: ["观察细致", "逻辑清晰"], suggestions: ["建议加强练习"] }

Object arrays

const schema = {
  type: "object",
  properties: {
    dimensions: {
      type: "array",
      items: {
        type: "object",
        properties: {
          description: { type: "string" },
          chartType: { type: "string" },
        },
      },
    },
  },
};

// LLM output:
// DIMENSIONS -> START
// DIMENSION -> START
// DESCRIPTION -> "正确率"
// CHART_TYPE -> BAR
// DIMENSION -> END
// DIMENSIONS -> END

API

| Export | Description | |--------|-------------| | parseToJson(text, schema) | Schema-guided parse into camelCase object | | parseFromLlm(text) | Flat KEY→value parse (uppercase keys) | | tryParsePartial(text) | Incremental / SSE-friendly partial parse | | expandArrowIntentLines(text) | Split lines & comma-separated pairs | | parseArrowQuotedValue(line, key) | Extract quoted string for a key | | fieldToArrowKey(name) | chartType → CHART_TYPE | | arrayItemKey(name) | dimensions → DIMENSION | | JsonSchema | JSON Schema subset type |

Array format rules

| Type | Arrow format | |------|----------------| | string[] | KEY -> START + one plain-text line per item + KEY -> END | | object[] | KEY -> START + repeat ITEM -> START ... ITEM -> END + KEY -> END |

Do not output JSON arrays (KEY -> ["a","b"] or multi-line [ … ]).

Pipeline

Zod Schema → schemaToArrowPrompt (@qzsy/zod-to-arrow) → LLM → parseToJson → zod.safeParse

Testing

This package includes 2800+ generated test cases covering string arrays, object arrays, nested objects, bad JSON-array outputs, and round-trip stability.

pnpm test
pnpm test:coverage

Version

0.2.0 — schema-aware parseToJson, nested block fix, criteria/ITEM array key handling.

See also: 箭头格式规范.md