JSON Autocomplete

!npm
!License
!Coverage

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:

``bash


Using npm

npm install @bonniernews/json-autocomplete

Using Yarn

yarn add @bonniernews/json-autocomplete
`

Usage

$3

`typescript
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"}}
`

$3

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

`typescript
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

$3

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

`typescript
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"}}
`

$3

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: (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

`typescript
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:

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

3. Install dependencies:

`bash
npm install
`

4. Create a new branch:

`bash
git checkout -b feature/YourFeature
`

5. Make your changes: Implement your feature or bug fix.
6. Lint and type-check:

`bash
npm run lint
npm run typecheck
`

7. Run tests:

`bash
npm test
`

8. Commit your changes:

`bash
git commit -m "Add your message here"
`

9. Push to your fork:

`bash
git push origin feature/YourFeature
``

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

$3

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.