{"_id":"@braingrid/json-guard","_rev":"2-9eba7d1e25847ceca2db83801417b51c","name":"@braingrid/json-guard","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@braingrid/json-guard","version":"0.1.0","keywords":["json","repair","validation","schema","llm","ai","parser"],"_id":"@braingrid/json-guard@0.1.0","maintainers":[{"name":"acossta","email":"nico@acosta.io"},{"name":"braingrid_tyler","email":"tyler@braingrid.ai"}],"dist":{"shasum":"c1c0f5e7e4d69daf0b34be5afa61e26155c11d1e","tarball":"https://registry.npmjs.org/@braingrid/json-guard/-/json-guard-0.1.0.tgz","fileCount":9,"integrity":"sha512-Ga9EuvIEmmlKnopYQtZC8uzkeQZ64Ts3RIdKz3lUObHC9Z3YO87Re8SBGekoF9s/dRnaRW8pLmv3JylTK3tUUg==","signatures":[{"sig":"MEQCIDW/uSBcDjlaisD9PU1/eQFu+9FVgEARU39kzBi1PalzAiB1VGq2LZJfk1gyiFTCSQysVWHrJXCDmUvijtlM6anX+g==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":186727},"main":"./dist/index.cjs","type":"module","_from":"file:braingrid-json-guard-0.1.0.tgz","types":"./dist/index.d.ts","module":"./dist/index.js","exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"require":{"types":"./dist/index.d.cts","default":"./dist/index.cjs"}}},"scripts":{"dev":"tsup --watch","test":"vitest run","build":"tsup","clean":"rm -rf dist","test:watch":"vitest","type-check":"tsc --noEmit"},"_npmUser":{"name":"braingrid_tyler","email":"tyler@braingrid.ai"},"_resolved":"/private/var/folders/mt/c41k7_b167q49y0dr5z1yp040000gn/T/77f72f1e0bbf595bcaafbae714f04c98/braingrid-json-guard-0.1.0.tgz","_integrity":"sha512-Ga9EuvIEmmlKnopYQtZC8uzkeQZ64Ts3RIdKz3lUObHC9Z3YO87Re8SBGekoF9s/dRnaRW8pLmv3JylTK3tUUg==","_npmVersion":"10.9.2","description":"Schema-aware JSON repair engine for LLM output recovery and user input validation","directories":{},"_nodeVersion":"22.17.0","dependencies":{"ajv":"^8.17.0","zod":"^3.23.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.0","vitest":"^2.0.0","typescript":"^5.6.0"},"_npmOperationalInternal":{"tmp":"tmp/json-guard_0.1.0_1762647515753_0.4663146039400652","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@braingrid/json-guard","version":"0.1.1","description":"Schema-aware JSON repair engine for LLM output recovery and user input validation","type":"module","main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"require":{"types":"./dist/index.d.cts","default":"./dist/index.cjs"}}},"scripts":{"build":"tsup","dev":"tsup --watch","type-check":"tsc --noEmit","test":"vitest run","test:watch":"vitest","clean":"rm -rf dist"},"keywords":["json","repair","validation","schema","llm","ai","parser"],"author":{"name":"BrainGrid AI, Inc."},"license":"Apache-2.0","repository":{"type":"git","url":"git+https://github.com/BrainGridAI/ai-kit.git","directory":"packages/json-guard"},"homepage":"https://github.com/BrainGridAI/ai-kit/tree/main/packages/json-guard#readme","bugs":{"url":"https://github.com/BrainGridAI/ai-kit/issues"},"dependencies":{"ajv":"^8.17.0","zod":"^3.23.0"},"devDependencies":{"tsup":"^8.0.0","typescript":"^5.6.0","vitest":"^2.0.0"},"publishConfig":{"access":"public","provenance":false},"gitHead":"34fc61b8d99d92746e6027c8d929d5e90721d37d","_id":"@braingrid/json-guard@0.1.1","_nodeVersion":"20.19.5","_npmVersion":"11.6.2","dist":{"integrity":"sha512-NgV6GoRr1J0Q7YWRTZUeB84uBFNhxgbqeeh1Qvf64zMN9dZlooo/0nH/diMuLM/WupQg+YMecmGzyQXtHwZMwA==","shasum":"d6e501d92142917315739277ba10f741eac5f6fc","tarball":"https://registry.npmjs.org/@braingrid/json-guard/-/json-guard-0.1.1.tgz","fileCount":8,"unpackedSize":186526,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCTa/++b8VmHlB6xv7qNC9VqC14abaj2fSKEgAiQhAFbQIhAIGh5HIcAz7JRrcw6j766Ie29ky1XQXVQIAHI0Wr/S0i"}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:f0752c0b-d593-40c5-85a6-fed2252a7a5e"}},"directories":{},"maintainers":[{"name":"acossta","email":"nico@acosta.io"},{"name":"braingrid_tyler","email":"tyler@braingrid.ai"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/json-guard_0.1.1_1762811515560_0.34331484962381675"},"_hasShrinkwrap":false}},"time":{"created":"2025-11-09T00:18:35.690Z","modified":"2025-11-10T21:51:55.991Z","0.1.0":"2025-11-09T00:18:35.942Z","0.1.1":"2025-11-10T21:51:55.791Z"},"keywords":["json","repair","validation","schema","llm","ai","parser"],"description":"Schema-aware JSON repair engine for LLM output recovery and user input validation","maintainers":[{"name":"acossta","email":"nico@acosta.io"},{"name":"braingrid_tyler","email":"tyler@braingrid.ai"}],"readme":"# @braingrid/json-guard\n\n> Schema-aware JSON repair engine for LLM output recovery and user input validation\n\nA minimal, pluggable JSON repair engine designed to recover malformed AI outputs into schema-valid JSON.\n\n**Philosophy:** \"Repair what's broken, validate it, no modes, no profiles — just JSON that works.\"\n\n## Features\n\n- 🔧 **Automatic Repair** - Fixes common JSON syntax errors from AI outputs\n- 📐 **Schema-Driven** - Uses JSON Schema (Ajv) or Zod for validation\n- 🔌 **Pluggable** - Extensible with custom repair strategies\n- 🎯 **Type-Safe** - Full TypeScript support with generics\n- 🚀 **Dual Package** - ESM and CJS support\n\n## Installation\n\n```bash\npnpm add @braingrid/json-guard\n# or\nnpm install @braingrid/json-guard\n# or\nyarn add @braingrid/json-guard\n```\n\n## Quick Start\n\n```typescript\nimport { createGuard, ajvAdapter } from \"@braingrid/json-guard\";\n\n// Define your schema\nconst schema = ajvAdapter().fromJsonSchema({\n  type: \"object\",\n  required: [\"action\"],\n  properties: {\n    action: { enum: [\"search\", \"create\", \"delete\"] },\n    limit: { type: \"integer\", default: 10 }\n  },\n  additionalProperties: false\n});\n\n// Create a guard\nconst guard = createGuard();\n\n// Repair malformed AI output\nconst result = await guard.repair(\n  \"```json\\n{ action:'Search', limit:'10', extra:true }\\n```\",\n  { schema }\n);\n\nconsole.log(result.value);\n// => { action: \"search\", limit: 10 }\n```\n\n## API\n\n### `createGuard()`\n\nCreates a new Guard instance with all default strategies registered.\n\n```typescript\nconst guard = createGuard();\n```\n\n### `guard.repair<T>(rawInput: string, options: RepairOptions): Promise<GuardResult<T>>`\n\nRepairs malformed JSON against a schema.\n\n**Parameters:**\n\n- `rawInput` (string, required) - The potentially malformed JSON string\n- `options.schema` (SchemaAdapter, required) - Schema adapter for validation\n- `options.defaultStrategies` (string[], optional) - List of built-in strategies to apply\n- `options.customStrategies` (Strategy[], optional) - User-defined strategies to run after defaults\n\n**Returns:** `Promise<GuardResult<T>>`\n\n```typescript\ninterface GuardResult<T = unknown> {\n  ok: boolean;                  // Whether repair succeeded\n  value?: T;                    // Parsed and validated value\n  json?: string;                // Repaired JSON string\n  diagnostics: Diagnostic[];    // Repair diagnostics\n  confidence: number;           // Confidence score (0-1)\n}\n```\n\n## Built-In Strategies\n\nThe following strategies run in order by default:\n\n1. **extractJsonBlock** - Extracts JSON from markdown code blocks or surrounding text\n2. **tolerantParse** - Fixes single quotes, unquoted keys, trailing commas, comments\n3. **separatorNormalizer** - Fixes separator issues (semicolons, missing commas)\n4. **bracketAndQuoteFixer** - Adds missing closing brackets and quotes\n5. **schemaAlign** - Type coercion, enum normalization, default values\n6. **sanitizers** - Removes disallowed properties per schema\n7. **finalize** - Final validation and serialization\n\n## Schema Adapters\n\n### Ajv (JSON Schema)\n\n```typescript\nimport { ajvAdapter } from \"@braingrid/json-guard\";\n\nconst schema = ajvAdapter().fromJsonSchema({\n  type: \"object\",\n  properties: {\n    name: { type: \"string\" },\n    age: { type: \"number\" }\n  }\n});\n```\n\n### Zod\n\n```typescript\nimport { zodAdapter } from \"@braingrid/json-guard\";\nimport { z } from \"zod\";\n\nconst schema = zodAdapter().fromZodSchema(\n  z.object({\n    name: z.string(),\n    age: z.number()\n  })\n);\n```\n\n## Custom Strategies\n\nCreate custom strategies to handle domain-specific repairs:\n\n```typescript\nimport type { Strategy } from \"@braingrid/json-guard\";\n\nconst aliasKeys: Strategy = {\n  name: \"aliasKeys\",\n  async apply({ value }) {\n    if (value && typeof value === \"object\" && \"firstname\" in value) {\n      return {\n        value: { ...value, name: value.firstname },\n        diagnostics: [{\n          severity: \"info\",\n          message: \"Mapped 'firstname' to 'name'\",\n          strategy: \"aliasKeys\"\n        }]\n      };\n    }\n    return { diagnostics: [] };\n  }\n};\n\nconst result = await guard.repair(rawInput, {\n  schema,\n  customStrategies: [aliasKeys]\n});\n```\n\n## Selective Strategy Usage\n\nDisable specific default strategies:\n\n```typescript\nimport { DEFAULT_STRATEGIES } from \"@braingrid/json-guard\";\n\nconst result = await guard.repair(rawInput, {\n  schema,\n  defaultStrategies: DEFAULT_STRATEGIES.filter(\n    s => s !== \"separatorNormalizer\"\n  )\n});\n```\n\n## Examples\n\n### Markdown-Wrapped JSON\n\n```typescript\nconst input = '```json\\n{\"name\": \"test\"}\\n```';\nconst result = await guard.repair(input, { schema });\n// Extracts and validates the JSON\n```\n\n### Single Quotes & Unquoted Keys\n\n```typescript\nconst input = \"{name: 'test', active: true}\";\nconst result = await guard.repair(input, { schema });\n// Fixes to: {\"name\": \"test\", \"active\": true}\n```\n\n### Enum Case Normalization\n\n```typescript\nconst input = '{\"action\": \"CREATE\"}';  // Wrong case\nconst result = await guard.repair(input, { schema });\n// Normalizes to: {\"action\": \"create\"}\n```\n\n### Type Coercion\n\n```typescript\nconst input = '{\"age\": \"30\"}';  // String instead of number\nconst result = await guard.repair(input, { schema });\n// Coerces to: {\"age\": 30}\n```\n\n## TypeScript Types\n\n```typescript\nimport type {\n  Guard,\n  GuardResult,\n  Strategy,\n  SchemaAdapter,\n  Diagnostic\n} from \"@braingrid/json-guard\";\n```\n\n## License\n\nApache-2.0\n\n## Contributing\n\nContributions welcome! Please see the main repository for contribution guidelines.\n","readmeFilename":"README.md","homepage":"https://github.com/BrainGridAI/ai-kit/tree/main/packages/json-guard#readme","repository":{"type":"git","url":"git+https://github.com/BrainGridAI/ai-kit.git","directory":"packages/json-guard"},"author":{"name":"BrainGrid AI, Inc."},"bugs":{"url":"https://github.com/BrainGridAI/ai-kit/issues"},"license":"Apache-2.0"}