Troubleshooting

This page documents common issues and their solutions when using zzson, particularly with WebAssembly bindings.

WebAssembly Issues

Objects Parsing to Empty Results

Issue: Parsed JSON objects appear empty ({}) even when the input contains valid data like {a:1} or {"a":1}.

Symptoms:

  • Object.keys(result) returns an empty array
  • JSON.stringify(result) returns "{}"
  • Property access on parsed objects returns undefined
  • Browser console shows results as Map(1) instead of plain objects

Root Cause: This was a critical bug in versions prior to 1.2.4 where the WebAssembly bindings used serde_wasm_bindgen::to_value() which converted Rust HashMap objects to JavaScript Map objects instead of plain JavaScript objects.

Solution:

  • Fixed in version 1.2.4: The WebAssembly bindings now use a custom value_to_js() function that creates proper JavaScript objects
  • If using an older version: Upgrade to version 1.2.4 or later

Technical Details: The fix involved replacing the automatic serde conversion with manual object creation:

// Before (problematic):
serde_wasm_bindgen::to_value(&value)

// After (fixed):
value_to_js(&value) // Custom function using js_sys::Object

Browser Caching of WASM Modules

Issue: Changes to the WASM module are not reflected in the browser even after rebuilding.

Solution:

  1. Hard refresh your browser (Ctrl+Shift+R or Cmd+Shift+R)
  2. Clear browser cache
  3. Add cache-busting query parameters to module imports:
    import init from './pkg/zzson.js?v=' + Date.now();
    

WASM Module Loading Failures

Issue: WebAssembly module fails to load with network errors.

Common Causes & Solutions:

  1. Incorrect MIME type: Ensure your web server serves .wasm files with application/wasm MIME type
  2. CORS issues: Serve files from a proper HTTP server, not file:// protocol
  3. Path issues: Verify the path to pkg/zzson.js and pkg/zzson_bg.wasm is correct

Testing Setup: Use a simple HTTP server for testing:

# Python 3
python -m http.server 8080

# Node.js (with http-server package)
npx http-server -p 8080

# Rust (with basic-http-server)
cargo install basic-http-server
basic-http-server docs/ -a 127.0.0.1:8080

Parser Issues

Unquoted Keys Not Working

Issue: JSON with unquoted keys like {key: "value"} fails to parse.

Solution: Ensure allow_unquoted_keys is enabled in parser options:

const options = {
  allow_unquoted_keys: true,
  // ... other options
};
const result = parse_json_with_options(input, options);

Comments Causing Parse Errors

Issue: JSON with comments like // comment or /* comment */ fails to parse.

Solution: Enable comment support in parser options:

const options = {
  allow_comments: true,
  // ... other options
};
const result = parse_json_with_options(input, options);

Debug Tools

Browser Console Debugging

Enable debug logging by using the debug builds of the WebAssembly module. Debug messages will appear in the browser console showing:

  • Token parsing progress
  • Value conversion steps
  • Object creation details

Test Pages

The following test pages are available for debugging:

  • error-debug.html - Error handling and basic parsing tests
  • console-debug.html - Console output capture and display
  • token-debug.html - Token-level parsing analysis
  • deep-debug.html - Comprehensive parsing verification

Manual Testing

Test parsing functionality manually:

// Test basic object parsing
const result1 = parse_json('{"a": 1}');
console.log('Quoted keys:', result1);

// Test unquoted keys (requires options)
const options = { allow_unquoted_keys: true };
const result2 = parse_json_with_options('{a: 1}', options);
console.log('Unquoted keys:', result2);

// Verify object properties
console.log('Keys:', Object.keys(result2));
console.log('JSON:', JSON.stringify(result2));

Getting Help

If you encounter issues not covered here:

  1. Check the GitHub Issues
  2. Review the API documentation
  3. Examine the test files for usage examples
  4. Create a new issue with:
    • Your zzson version
    • Browser and version
    • Minimal reproduction case
    • Expected vs actual behavior