@azghr/extricate

Extract the first (or every) valid JSON value embedded in text or markdown fences from an LLM reply. Locates and parses; does not repair.

The problem

LLM responses often embed JSON in prose or markdown. Manual extraction is tedious. Regex fails for nested structures and escaped characters. You need reliable JSON extraction from messy text.

Install

npm install @azghr/extricate
# or
pnpm add @azghr/extricate
# or
yarn add @azghr/extricate

Use

Extract JSON from LLM responses:

import extricate from "@azghr/extricate";

const user = extricate('Data: {"name": "Alice", "age": 30} thanks!');
// { name: "Alice", age: 30 }

Extract all JSON values:

const results = extricate.all('{"id": 1} {"id": 2}');
// [{ id: 1 }, { id: 2 }]

Parse fenced blocks:

const result = extricate('```json {"confidence": 0.92} ```');
// result.confidence === 0.92

API

extricate<T = unknown>(text, options?): T

Extract the first valid JSON value from text.

Options:

• prefer?: "object" | "array" | "any" - Control which type to find (default: "any")
• fences?: boolean - Prioritize fenced code blocks (default: true)

Behavior: Scans fenced blocks first, falls back to inline. Throws NoJSONFound if no valid JSON found.

const obj = extricate('[1, 2] {"data": true}', { prefer: "object" });
// { data: true }

extricate.all<T = unknown>(text, options?): T[]

Extract all valid JSON values from text in order.

const results = extricate.all('{"a": 1} {"b": 2}');
// [{ a: 1 }, { b: 2 }]

NoJSONFound

Error thrown when no valid JSON can be found.

import { NoJSONFound } from "@azghr/extricate";

try {
  extricate("Just plain text");
} catch (error) {
  if (error instanceof NoJSONFound) {
    console.log("No JSON found");
  }
}

Non-goals

What extricate does NOT do:

• Does NOT repair malformed JSON - only locates and parses valid JSON
• Does NOT extract primitive values (true, false, null, numbers, strings)
• Does NOT fix truncated structures

extricate('{"missing": "quotes}'); // throws NoJSONFound
extricate('true null 42'); // throws NoJSONFound

TypeScript note

import extricate from "@azghr/extricate";

interface User {
  name: string;
  age: number;
}

const user = extricate<User>(llmResponse);

Related Packages

• @azghr/filterkit - Type-safe filtering
• @azghr/shorn - Byte-budget string truncation
• @azghr/singlet - Deduplicate concurrent calls
• forbear - Rate-limit instructions
• quiesce - Graceful shutdown
• sortition - A/B bucketing
• staleness - Stale-while-revalidate caching

See pnpm-workspace.yaml for all packages.

License

MIT