JSON Autocomplete

A utility to incrementally build and complete JSON strings from potentially incomplete JSON append operations with caching capabilities. Perfect for modern LLM applications that should stream json output. Perfectly combined with chat completions API from OpenAI.

Table of Contents

• Features
• Installation
• Usage
  • Basic Example
  • Using jsonAutocomplete Helper
• API Reference
  • createJsonAutocomplete()
  • jsonAutocomplete
• Contributing
• License
• Support

Features

• Incremental Building: Append parts of a JSON string incrementally and get the best possible valid JSON.
• String Handling: Correctly handles strings, escape characters, and nested structures.
• Error Checking: Detects unbalanced brackets and braces.
• Caching Capabilities: Efficiently manages the internal state to optimize performance.

Installation

You can install JSON Autocomplete via npm or Yarn:

# Using npm
npm install @bonniernews/json-autocomplete

# Using Yarn
yarn add @bonniernews/json-autocomplete

Usage

Basic Example

import { createJsonAutocomplete } from "@bonniernews/json-autocomplete";

// Create a new autocompleter instance
const autocompleter = createJsonAutocomplete();

// Append incomplete JSON fragments
const part1 = '{"name": "Alice", "age": 30';
const completed1 = autocompleter.append(part1);
console.log(completed1); // Outputs: {"name": "Alice", "age": 30}

const part2 = ', "address": {"street": "123 Main St';
const completed2 = autocompleter.append(part2);
console.log(completed2); // Outputs: {"name": "Alice", "age": 30, "address": {"street": "123 Main St"}}

const part3 = '", "city": "Wonderland"}}';
const completed3 = autocompleter.append(part3);
console.log(completed3); // Outputs: {"name": "Alice", "age": 30, "address": {"street": "123 Main St", "city": "Wonderland"}}

Using jsonAutocomplete Helper

For simpler use cases, you can use the jsonAutocomplete helper function which manages the autocompleter instance internally.

import { jsonAutocomplete } from "@bonniernews/json-autocomplete";

const incompleteJson1 = '{"isActive": true, "roles": ["admin", "user"';
const completedJson1 = jsonAutocomplete(incompleteJson1);
console.log(completedJson1); // Outputs: {"isActive": true, "roles": ["admin", "user"]}

const incompleteJson2 = ', "permissions": {"read": true, "write": false';
const completedJson2 = jsonAutocomplete(incompleteJson2);
console.log(completedJson2); // Outputs: {"isActive": true, "roles": ["admin", "user"], "permissions": {"read": true, "write": false}}

API Reference

createJsonAutocomplete()

Creates a new JSON autocompleter instance.

Returns

An object with the following method:

• append(part: string): string: Appends a fragment of JSON and returns the best possible valid JSON string constructed from all appended fragments.

Example

import { createJsonAutocomplete } from "@bonniernews/json-autocomplete";

const autocompleter = createJsonAutocomplete();

const jsonPart1 = '{"product": "Laptop", "price": 1200';
const completedJson1 = autocompleter.append(jsonPart1);
console.log(completedJson1); // {"product": "Laptop", "price": 1200}

const jsonPart2 = ', "specs": {"cpu": "Intel i7", "ram": "16GB"';
const completedJson2 = autocompleter.append(jsonPart2);
console.log(completedJson2); // {"product": "Laptop", "price": 1200, "specs": {"cpu": "Intel i7", "ram": "16GB"}}

const jsonPart3 = "}}";
const completedJson3 = autocompleter.append(jsonPart3);
console.log(completedJson3); // {"product": "Laptop", "price": 1200, "specs": {"cpu": "Intel i7", "ram": "16GB"}}

jsonAutocomplete

A helper function to incrementally autocomplete a JSON string without manually managing the autocompleter instance.

Parameters

• incompleteJsonString: string: The incomplete JSON string fragment.
• autocompleter?: ReturnType<typeof createJsonAutocomplete>: (Optional) An existing autocompleter instance. If not provided, a new one is created.

Returns

• string: The best possible valid JSON string constructed from all appended fragments.

Example

import { jsonAutocomplete } from "@bonniernews/json-autocomplete";

let completedJson = jsonAutocomplete('{"title": "Book"');
console.log(completedJson); // {"title": "Book"}

completedJson = jsonAutocomplete(', "author": "Jane Doe"');
console.log(completedJson); // {"title": "Book", "author": "Jane Doe"}

completedJson = jsonAutocomplete("}");
console.log(completedJson); // {"title": "Book", "author": "Jane Doe"}

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository: Click the Fork button at the top right of the repository page.

2. Clone your fork:

   git clone https://github.com/your-username/json-autocomplete.git
   cd json-autocomplete
   

3. Install dependencies:

   npm install
   

4. Create a new branch:

   git checkout -b feature/YourFeature
   

5. Make your changes: Implement your feature or bug fix.

6. Lint and type-check:

   npm run lint
   npm run typecheck
   

7. Run tests:

   npm test
   

8. Commit your changes:

   git commit -m "Add your message here"
   

9. Push to your fork:

   git push origin feature/YourFeature
   

10. Create a Pull Request: Go to the original repository and submit a pull request.

Code of Conduct

Please adhere to the Bonnier News Code of Conduct in all your interactions with the project.

License

This project is licensed under the MIT License. You are free to use, modify, and distribute it as per the license terms.

Support

If you encounter any issues or have questions, please open an issue on GitHub.