tinyjson-parser
tinyjson-parser

Documentation

Complete guide to using tinyjson-parser

Contents

Installation

npm install tinyjson-parser
# or
pnpm add tinyjson-parser
# or
yarn add tinyjson-parser

Basic Usage

Parse JSON strings with a simple, clean API.

Simple Parsing

import { parseJSON } from 'tinyjson-parser';

const json = '{"name": "world", "count": 42}';
const result = parseJSON(json);
// { name: "world", count: 42 }

Supported Types

tinyjson-parser supports all standard JSON types:

import { parseJSON } from 'tinyjson-parser';

// Objects
parseJSON('{"key": "value"}');

// Arrays
parseJSON('[1, 2, 3]');

// Strings
parseJSON('"hello world"');

// Numbers
parseJSON('42');
parseJSON('-3.14');
parseJSON('1e10');

// Booleans
parseJSON('true');
parseJSON('false');

// Null
parseJSON('null');

// Nested structures
parseJSON('{"users": [{"id": 1, "active": true}]}');

Streaming Parser

Parse large JSON files incrementally by processing data in chunks. Perfect for handling files that don't fit in memory.

Streaming Large Files

import { StreamingParser, parseJSONStream } from 'tinyjson-parser';

// Method 1: Using StreamingParser class
const parser = new StreamingParser();
parser.write('{"name": "');
parser.write('world", "items": [');
parser.write('1, 2, 3]}');
const result = parser.end();
// { name: "world", items: [1, 2, 3] }

// Method 2: Using convenience function
const chunks = ['{"users": [', '{"id": 1}', ']}'];
const data = parseJSONStream(chunks);
// { users: [{ id: 1 }] }

When to Use Streaming

  • •Parsing files larger than available memory
  • •Processing JSON from network streams
  • •Handling real-time JSON data feeds

Error Handling

tinyjson-parser provides detailed error messages with line and column information for easy debugging.

Error Messages

import { parseJSON } from 'tinyjson-parser';

try {
  parseJSON('{"invalid": json}');
} catch (error) {
  // SyntaxError: Unexpected character 'j' at line 1, column 15
  console.error(error.message);
}

try {
  parseJSON('{"trailing": "comma",}');
} catch (error) {
  // SyntaxError: Trailing comma in object is not allowed at line 1, column 25
  console.error(error.message);
}

try {
  parseJSON('{"number": 0123}');
} catch (error) {
  // SyntaxError: Leading zeros not allowed at line 1, column 14
  console.error(error.message);
}

Strict Validation

The parser enforces strict JSON compliance:

  • •No trailing commas in objects or arrays
  • •No leading zeros in numbers (except "0")
  • •Proper string escaping and unicode support
  • •No duplicate commas or colons

Features

⚡ Performance

Optimized tokenizer and parser for maximum speed with minimal memory overhead.

📦 Zero Dependencies

Built from scratch with no external dependencies. Keep your bundle size minimal.

🔍 Detailed Errors

Precise error messages with line and column numbers for easy debugging.

🌊 Streaming Support

Handle large JSON files incrementally with the streaming parser API.

✅ Strict Compliance

Enforces strict JSON specification compliance, rejecting invalid JSON.

📝 TypeScript

Full TypeScript support with excellent type inference and IntelliSense.

API Reference

parseJSON

Parses a complete JSON string and returns the parsed JavaScript value.

function parseJSON(input: string): any

Parameters

input: string - The JSON string to parse

Returns

any - The parsed JavaScript value

Throws

SyntaxError - If the input is not valid JSON

StreamingParser

A class for parsing JSON incrementally from multiple chunks.

class StreamingParser {
  write(chunk: string): void
  end(): any
  needsMoreData(): boolean
}

Methods

write(chunk: string)

Writes a chunk of JSON data to the parser. Can be called multiple times.

end(): any

Signals that all data has been written and returns the parsed JSON value.

needsMoreData(): boolean

Returns true if the parser is waiting for more data to complete parsing.

parseJSONStream

Convenience function to parse JSON from an array of chunks.

function parseJSONStream(chunks: string[]): any

Parameters

chunks: string[] - Array of JSON string chunks

Returns

any - The parsed JavaScript value