@hardlydifficult/ai-msg 1.0.0

package/README.md

@@ -0,0 +1,77 @@
+# @hardlydifficult/ai-msg
+
+Opinionated utilities for extracting structured output from AI text responses.
+
+LLM responses often wrap structured data in markdown code blocks, preamble text, or trailing commentary. This package reliably extracts JSON and code blocks from messy AI output.
+
+## Installation
+
+```bash
+npm install @hardlydifficult/ai-msg
+```
+
+For typed extraction with Zod validation:
+
+```bash
+npm install @hardlydifficult/ai-msg zod
+```
+
+## Usage
+
+### `extractJson(text): unknown | null`
+
+Extracts the first valid JSON value from text using a three-pass strategy:
+
+1. Direct `JSON.parse` of the trimmed text
+2. Search markdown code blocks (json-tagged first, then any)
+3. Find balanced `{}` or `[]` substrings in prose
+
+```typescript
+import { extractJson } from "@hardlydifficult/ai-msg";
+
+extractJson('{"key": "value"}');
+// { key: "value" }
+
+extractJson('Here is the result:\n```json\n{"key": "value"}\n```\nDone.');
+// { key: "value" }
+
+extractJson('The answer is {"key": "value"} as shown.');
+// { key: "value" }
+
+extractJson("no json here");
+// null
+```
+
+### `extractCodeBlock(text, lang?): string[]`
+
+Extracts all markdown code blocks from text. Optionally filters by language tag.
+
+```typescript
+import { extractCodeBlock } from "@hardlydifficult/ai-msg";
+
+extractCodeBlock("```ts\nconst x = 1;\n```");
+// ["const x = 1;"]
+
+extractCodeBlock("```json\n{}\n```\n```ts\nconst x = 1;\n```", "json");
+// ["{}"]
+
+extractCodeBlock("no code blocks");
+// []
+```
+
+### `extractTyped<T>(text, schema): T | null`
+
+Extracts JSON from text and validates it against a Zod schema. Requires `zod` as a peer dependency.
+
+```typescript
+import { extractTyped } from "@hardlydifficult/ai-msg";
+import { z } from "zod";
+
+const Person = z.object({ name: z.string(), age: z.number() });
+
+extractTyped('{"name": "Alice", "age": 30}', Person);
+// { name: "Alice", age: 30 }
+
+extractTyped('{"name": "Alice", "age": "thirty"}', Person);
+// null
+```

package/dist/extractCodeBlock.d.ts

@@ -0,0 +1,2 @@
+export declare function extractCodeBlock(text: string, lang?: string): string[];
+//# sourceMappingURL=extractCodeBlock.d.ts.map

package/dist/extractCodeBlock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extractCodeBlock.d.ts","sourceRoot":"","sources":["../src/extractCodeBlock.ts"],"names":[],"mappings":"AAEA,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAatE"}

package/dist/extractCodeBlock.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractCodeBlock = extractCodeBlock;
+const codeBlockRegex = /^```(\w*)\s*\n([\s\S]*?)^```/gm;
+function extractCodeBlock(text, lang) {
+    const results = [];
+    for (const match of text.matchAll(codeBlockRegex)) {
+        const tag = match[1];
+        const content = match[2];
+        if (lang !== undefined && tag.toLowerCase() !== lang.toLowerCase()) {
+            continue;
+        }
+        results.push(content.trimEnd());
+    }
+    return results;
+}
+//# sourceMappingURL=extractCodeBlock.js.map

package/dist/extractCodeBlock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extractCodeBlock.js","sourceRoot":"","sources":["../src/extractCodeBlock.ts"],"names":[],"mappings":";;AAEA,4CAaC;AAfD,MAAM,cAAc,GAAG,gCAAgC,CAAC;AAExD,SAAgB,gBAAgB,CAAC,IAAY,EAAE,IAAa;IAC1D,MAAM,OAAO,GAAa,EAAE,CAAC;IAE7B,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC;QAClD,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QACrB,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QACzB,IAAI,IAAI,KAAK,SAAS,IAAI,GAAG,CAAC,WAAW,EAAE,KAAK,IAAI,CAAC,WAAW,EAAE,EAAE,CAAC;YACnE,SAAS;QACX,CAAC;QACD,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IAClC,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/extractJson.d.ts

@@ -0,0 +1,2 @@
+export declare function extractJson(text: string): unknown;
+//# sourceMappingURL=extractJson.d.ts.map

package/dist/extractJson.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extractJson.d.ts","sourceRoot":"","sources":["../src/extractJson.ts"],"names":[],"mappings":"AAWA,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAuCjD"}

package/dist/extractJson.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractJson = extractJson;
+const extractCodeBlock_js_1 = require("./extractCodeBlock.js");
+const findBalanced_js_1 = require("./findBalanced.js");
+function tryParse(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+function extractJson(text) {
+    // Pass 1: try the whole text
+    const direct = tryParse(text.trim());
+    if (direct !== undefined) {
+        return direct;
+    }
+    // Pass 2: code blocks — json-tagged first, then any
+    for (const block of (0, extractCodeBlock_js_1.extractCodeBlock)(text, "json")) {
+        const parsed = tryParse(block.trim());
+        if (parsed !== undefined) {
+            return parsed;
+        }
+    }
+    for (const block of (0, extractCodeBlock_js_1.extractCodeBlock)(text)) {
+        const parsed = tryParse(block.trim());
+        if (parsed !== undefined) {
+            return parsed;
+        }
+    }
+    // Pass 3: balanced braces / brackets
+    const obj = (0, findBalanced_js_1.findBalanced)(text, "{", "}");
+    if (obj !== null) {
+        const parsed = tryParse(obj);
+        if (parsed !== undefined) {
+            return parsed;
+        }
+    }
+    const arr = (0, findBalanced_js_1.findBalanced)(text, "[", "]");
+    if (arr !== null) {
+        const parsed = tryParse(arr);
+        if (parsed !== undefined) {
+            return parsed;
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=extractJson.js.map

package/dist/extractJson.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extractJson.js","sourceRoot":"","sources":["../src/extractJson.ts"],"names":[],"mappings":";;AAWA,kCAuCC;AAlDD,+DAAyD;AACzD,uDAAiD;AAEjD,SAAS,QAAQ,CAAC,IAAY;IAC5B,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,SAAgB,WAAW,CAAC,IAAY;IACtC,6BAA6B;IAC7B,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;IACrC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,oDAAoD;IACpD,KAAK,MAAM,KAAK,IAAI,IAAA,sCAAgB,EAAC,IAAI,EAAE,MAAM,CAAC,EAAE,CAAC;QACnD,MAAM,MAAM,GAAG,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;QACtC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,OAAO,MAAM,CAAC;QAChB,CAAC;IACH,CAAC;IACD,KAAK,MAAM,KAAK,IAAI,IAAA,sCAAgB,EAAC,IAAI,CAAC,EAAE,CAAC;QAC3C,MAAM,MAAM,GAAG,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;QACtC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,OAAO,MAAM,CAAC;QAChB,CAAC;IACH,CAAC;IAED,qCAAqC;IACrC,MAAM,GAAG,GAAG,IAAA,8BAAY,EAAC,IAAI,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;IACzC,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;QACjB,MAAM,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC;QAC7B,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,OAAO,MAAM,CAAC;QAChB,CAAC;IACH,CAAC;IAED,MAAM,GAAG,GAAG,IAAA,8BAAY,EAAC,IAAI,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;IACzC,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;QACjB,MAAM,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC;QAC7B,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,OAAO,MAAM,CAAC;QAChB,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/extractTyped.d.ts

@@ -0,0 +1,3 @@
+import { type ZodType } from "zod";
+export declare function extractTyped<T>(text: string, schema: ZodType<T>): T | null;
+//# sourceMappingURL=extractTyped.d.ts.map

package/dist/extractTyped.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extractTyped.d.ts","sourceRoot":"","sources":["../src/extractTyped.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,KAAK,CAAC;AAInC,wBAAgB,YAAY,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,IAAI,CAQ1E"}

package/dist/extractTyped.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractTyped = extractTyped;
+const extractJson_js_1 = require("./extractJson.js");
+function extractTyped(text, schema) {
+    const json = (0, extractJson_js_1.extractJson)(text);
+    if (json === null) {
+        return null;
+    }
+    const result = schema.safeParse(json);
+    return result.success ? result.data : null;
+}
+//# sourceMappingURL=extractTyped.js.map

package/dist/extractTyped.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extractTyped.js","sourceRoot":"","sources":["../src/extractTyped.ts"],"names":[],"mappings":";;AAIA,oCAQC;AAVD,qDAA+C;AAE/C,SAAgB,YAAY,CAAI,IAAY,EAAE,MAAkB;IAC9D,MAAM,IAAI,GAAG,IAAA,4BAAW,EAAC,IAAI,CAAC,CAAC;IAC/B,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QAClB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IACtC,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;AAC7C,CAAC"}

package/dist/findBalanced.d.ts

@@ -0,0 +1,2 @@
+export declare function findBalanced(text: string, openChar: string, closeChar: string): string | null;
+//# sourceMappingURL=findBalanced.d.ts.map

package/dist/findBalanced.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"findBalanced.d.ts","sourceRoot":"","sources":["../src/findBalanced.ts"],"names":[],"mappings":"AAAA,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAChB,MAAM,GAAG,IAAI,CA6Cf"}

package/dist/findBalanced.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findBalanced = findBalanced;
+function findBalanced(text, openChar, closeChar) {
+    const start = text.indexOf(openChar);
+    if (start === -1) {
+        return null;
+    }
+    let depth = 0;
+    let inString = false;
+    let escaped = false;
+    for (let i = start; i < text.length; i++) {
+        const ch = text[i];
+        if (escaped) {
+            escaped = false;
+            continue;
+        }
+        if (ch === "\\") {
+            if (inString) {
+                escaped = true;
+            }
+            continue;
+        }
+        if (ch === '"') {
+            inString = !inString;
+            continue;
+        }
+        if (inString) {
+            continue;
+        }
+        if (ch === openChar) {
+            depth++;
+        }
+        else if (ch === closeChar) {
+            depth--;
+            if (depth === 0) {
+                return text.slice(start, i + 1);
+            }
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=findBalanced.js.map

package/dist/findBalanced.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"findBalanced.js","sourceRoot":"","sources":["../src/findBalanced.ts"],"names":[],"mappings":";;AAAA,oCAiDC;AAjDD,SAAgB,YAAY,CAC1B,IAAY,EACZ,QAAgB,EAChB,SAAiB;IAEjB,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACrC,IAAI,KAAK,KAAK,CAAC,CAAC,EAAE,CAAC;QACjB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,QAAQ,GAAG,KAAK,CAAC;IACrB,IAAI,OAAO,GAAG,KAAK,CAAC;IAEpB,KAAK,IAAI,CAAC,GAAG,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACzC,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QAEnB,IAAI,OAAO,EAAE,CAAC;YACZ,OAAO,GAAG,KAAK,CAAC;YAChB,SAAS;QACX,CAAC;QAED,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC;YAChB,IAAI,QAAQ,EAAE,CAAC;gBACb,OAAO,GAAG,IAAI,CAAC;YACjB,CAAC;YACD,SAAS;QACX,CAAC;QAED,IAAI,EAAE,KAAK,GAAG,EAAE,CAAC;YACf,QAAQ,GAAG,CAAC,QAAQ,CAAC;YACrB,SAAS;QACX,CAAC;QAED,IAAI,QAAQ,EAAE,CAAC;YACb,SAAS;QACX,CAAC;QAED,IAAI,EAAE,KAAK,QAAQ,EAAE,CAAC;YACpB,KAAK,EAAE,CAAC;QACV,CAAC;aAAM,IAAI,EAAE,KAAK,SAAS,EAAE,CAAC;YAC5B,KAAK,EAAE,CAAC;YACR,IAAI,KAAK,KAAK,CAAC,EAAE,CAAC;gBAChB,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;YAClC,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { extractCodeBlock } from "./extractCodeBlock.js";
+export { extractJson } from "./extractJson.js";
+export { extractTyped } from "./extractTyped.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractTyped = exports.extractJson = exports.extractCodeBlock = void 0;
+var extractCodeBlock_js_1 = require("./extractCodeBlock.js");
+Object.defineProperty(exports, "extractCodeBlock", { enumerable: true, get: function () { return extractCodeBlock_js_1.extractCodeBlock; } });
+var extractJson_js_1 = require("./extractJson.js");
+Object.defineProperty(exports, "extractJson", { enumerable: true, get: function () { return extractJson_js_1.extractJson; } });
+var extractTyped_js_1 = require("./extractTyped.js");
+Object.defineProperty(exports, "extractTyped", { enumerable: true, get: function () { return extractTyped_js_1.extractTyped; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,6DAAyD;AAAhD,uHAAA,gBAAgB,OAAA;AACzB,mDAA+C;AAAtC,6GAAA,WAAW,OAAA;AACpB,qDAAiD;AAAxC,+GAAA,YAAY,OAAA"}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@hardlydifficult/ai-msg",
+  "version": "1.0.0",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "peerDependencies": {
+    "zod": ">=3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "zod": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "typescript": "5.8.3",
+    "vitest": "1.6.1",
+    "zod": "3.24.4"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}