WebAssembly (WASM) API Reference
zzson
provides WebAssembly bindings for use in JavaScript environments (browsers, Node.js). The WASM module exposes parsing functions that mirror the Rust API, including forgiving features and strict mode.
Usage
import init, { parse_json, parse_json_with_options } from './pkg/zzson.js';
await init();
const result = parse_json_with_options('{a:1}', { allow_comments: true });
console.log(result); // { a: 1 }
API
parse_json(input: string): any
β Parse with default forgiving optionsparse_json_with_options(input: string, options: object): any
β Parse with custom optionsget_parser_options(): object
β Get default options
Options
All forgiving features can be toggled via options (see features.md).
Recent Fixes
- As of v1.2.4, parsed objects are returned as plain JavaScript objects, not Maps. See Troubleshooting.
π Note: Version 1.2.4 includes a critical fix for object conversion. Previous versions incorrectly returned JavaScript Maps instead of plain objects for parsed JSON. If youβre experiencing issues where
{a:1}
returns{}
, please upgrade to version 1.2.4 or later. See Troubleshooting for details.
To use the WASM bindings, you need to enable the wasm
feature in your Cargo.toml
:
[dependencies]
zzson = { version = "1.1.0", features = ["wasm"] }
After building your Rust project with the wasm
feature (e.g., using wasm-pack
), you can import the generated JavaScript module.
Available JavaScript Functions
The following functions are exposed to JavaScript:
init()
init(): Promise<void>
Initializes the WebAssembly module. This function should be called once when the WASM module is loaded to set up proper panic handling for better debugging experience. It returns a Promise that resolves when the WASM module is ready.
Example:
import init from './pkg/zzson.js';
async function run() {
await init();
console.log("zzson WASM module loaded.");
// Now you can use other zzson functions
}
run();
parse_json(input: string)
parse_json(input: string): any
Parses a JSON-like string into a JavaScript value using default parser options. This is the main parsing function for WebAssembly usage. It accepts relaxed JSON syntax including comments, unquoted keys, trailing commas, and more.
input
: The JSON string to parse (supports forgiving syntax).- Returns: The successfully parsed value converted to a native JavaScript type (object, array, string, number, boolean, null).
- Throws: A
ParseError
object if a parsing error occurs.
Example:
import { parse_json } from './pkg/zzson.js';
try {
const result = parse_json(`{
// This is a comment
key: 'single quotes work',
trailing: 'commas allowed',
}`);
console.log(result);
// Output: { key: 'single quotes work', trailing: 'commas allowed' }
} catch (e) {
console.error(`Parse Error: ${e.message} at position ${e.position}`);
}
parse_json_with_options(input: string, options: object)
parse_json_with_options(input: string, options: object): any
Parses a JSON string with custom parser options. This function allows fine-grained control over which forgiving features to enable.
input
: The JSON string to parse.options
: A JavaScript object with parser configuration properties (seeget_parser_options()
for available properties).- Returns: The successfully parsed value.
- Throws: A
ParseError
object if a parsing error occurs.
Example:
import { parse_json_with_options } from './pkg/zzson.js';
// Strict JSON mode
const strictOptions = {
allowComments: false,
allowTrailingCommas: false,
allowUnquotedKeys: false,
allowSingleQuotes: false,
implicitTopLevel: false,
newlineAsComma: false
};
try {
const result = parse_json_with_options('{"key": "value"}', strictOptions);
console.log(result);
} catch (e) {
console.error(`Strict Parse Error: ${e.message}`);
}
// Enable only specific features
const customOptions = {
allowUnquotedKeys: true,
implicitTopLevel: true
};
try {
const result = parse_json_with_options('key: "value"', customOptions);
console.log(result);
} catch (e) {
console.error(`Custom Parse Error: ${e.message}`);
}
validate_json(input: string)
validate_json(input: string): boolean
Validates if a JSON string can be successfully parsed. This is a lightweight function that checks syntax validity without constructing the full value tree. Useful for input validation.
input
: The JSON string to validate.- Returns:
true
if the input is valid and can be parsed,false
otherwise.
Example:
import { validate_json } from './pkg/zzson.js';
console.log(validate_json('{"key": "value"}')); // true
console.log(validate_json('{key: "value"}')); // true (unquoted keys allowed by default)
console.log(validate_json('{invalid')); // false
get_parser_options()
get_parser_options(): object
Returns the current default configuration for the parser as a JavaScript object. This object can be modified and passed to parse_json_with_options
.
- Returns: A JavaScript object with all available parser options and their default values. The keys are camelCase (e.g.,
allowComments
).
Example:
import { get_parser_options, parse_json_with_options } from './pkg/zzson.js';
const defaultOptions = get_parser_options();
console.log(defaultOptions.allowComments); // true
// Modify specific options
const modifiedOptions = { ...defaultOptions, allowComments: false };
const result = parse_json_with_options('// comment\n{"a":1}', modifiedOptions); // Will throw error if comments are disabled
stringify_value(value: any)
stringify_value(value: any): string
Converts a JavaScript value (typically obtained from a parse_json
operation) back to a compact JSON string representation.
value
: The JavaScript value to stringify.- Returns: A compact JSON string representation.
- Throws: An error if the value cannot be serialized.
Example:
import { parse_json, stringify_value } from './pkg/zzson.js';
const parsed = parse_json('{key: "value", num: 42}');
const jsonString = stringify_value(parsed); // '{"key":"value","num":42}'
console.log(jsonString);
get_version_info()
get_version_info(): object
Returns version and build information for the zzson
library. Useful for debugging and compatibility checking.
- Returns: A JavaScript object with properties like
version
,description
,authors
,homepage
,repository
, andlicense
.
Example:
import { get_version_info } from './pkg/zzson.js';
const info = get_version_info();
console.log(`zzson v${info.version} - ${info.description}`);
ParseError
Class
When a parsing error occurs in parse_json
or parse_json_with_options
, a ParseError
object is thrown. This class provides structured error information.
class ParseError {
readonly message: string;
readonly position: number;
}
message
: A string describing what went wrong.position
: The character position in the input string where the error occurred (0-indexed).
Example (Error Handling):
import { parse_json } from './pkg/zzson.js';
try {
parse_json('{invalid json');
} catch (e) {
if (e instanceof Error && e.message.startsWith('Parse Error:')) { // Basic check for ParseError
console.error(`Caught zzson ParseError: ${e.message} at position ${e.position}`);
} else {
console.error(`Caught unexpected error: ${e}`);
}
}