CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-json-buffer

JSON parse & stringify that supports binary via base64 encoding

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

index.mddocs/

JSON Buffer

Overview

JSON functions that support Node.js Buffer objects by converting them to base64 encoding during serialization and restoring them during parsing. Unlike standard JSON.stringify which converts Buffers to arrays, json-buffer preserves the binary nature of data.

Package Information

  • Package Name: json-buffer
  • Package Type: npm
  • Language: JavaScript (Node.js)
  • Installation: npm install json-buffer

Core Imports

const JSONB = require('json-buffer');

ES6 modules:

import * as JSONB from 'json-buffer';
// or
import { stringify, parse } from 'json-buffer';

Basic Usage

const JSONB = require('json-buffer');
const Buffer = require('buffer').Buffer;

// Create a buffer with binary data
const buffer = Buffer.from('hello there!');
const data = { message: buffer, type: 'greeting' };

// Stringify with Buffer support
const jsonString = JSONB.stringify(data);
console.log(jsonString);
// Output: {"message":":base64:aGVsbG8gdGhlcmUh","type":"greeting"}

// Parse back to original structure with Buffer restored
const parsed = JSONB.parse(jsonString);
console.log(parsed.message instanceof Buffer); // true
console.log(parsed.message.toString()); // "hello there!"

Capabilities

JSON Stringification with Buffer Support

Converts JavaScript values to JSON strings with special handling for Buffer objects.

/**
 * Stringify JavaScript values with Buffer support
 * @param {any} o - The value to stringify
 * @returns {string|undefined} JSON string representation, or undefined if input is undefined
 */
function stringify(o)

Special Behavior:

  • Buffer objects: Converted to base64 strings prefixed with :base64:
  • String escaping: Strings starting with : are escaped by prefixing with another :
  • toJSON support: Objects with toJSON methods are processed via toJSON
  • Function filtering: Functions are ignored during serialization
  • Undefined handling: Undefined object properties are ignored, undefined array elements become null
  • Undefined input: Returns undefined if input is undefined

Usage Examples:

const JSONB = require('json-buffer');

// Buffer handling
const buffer = Buffer.from('binary data');
JSONB.stringify(buffer);
// Returns: ":base64:YmluYXJ5IGRhdGE="

// String escaping
JSONB.stringify(':special string');
// Returns: "::special string"

// Complex objects
const data = {
  text: 'hello',
  binary: Buffer.from('world'),
  nested: { value: 42 }
};
JSONB.stringify(data);
// Returns: {"text":"hello","binary":":base64:d29ybGQ=","nested":{"value":42}}

// Array with undefined
JSONB.stringify([1, undefined, Buffer.from('test')]);
// Returns: [1,null,":base64:dGVzdA=="]

JSON Parsing with Buffer Restoration

Parses JSON strings back to JavaScript values with automatic Buffer restoration.

/**
 * Parse JSON strings with Buffer restoration
 * @param {string} s - The JSON string to parse
 * @returns {any} Parsed JavaScript value with Buffers restored
 */
function parse(s)

Special Behavior:

  • Buffer restoration: Strings with :base64: prefix are converted back to Buffer objects using base64 decoding
  • String unescaping: Strings starting with : have the first : removed
  • Standard JSON: Uses JSON.parse with custom reviver function for Buffer handling
  • Error propagation: Invalid JSON throws SyntaxError from underlying JSON.parse

Usage Examples:

const JSONB = require('json-buffer');

// Buffer restoration
const jsonString = '":base64:aGVsbG8="';
const result = JSONB.parse(jsonString);
console.log(result instanceof Buffer); // true
console.log(result.toString()); // "hello"

// String unescaping  
const escapedString = '"::special string"';
const unescaped = JSONB.parse(escapedString);
console.log(unescaped); // ":special string"

// Complex object parsing
const complexJson = '{"text":"hello","binary":":base64:d29ybGQ=","nested":{"value":42}}';
const parsed = JSONB.parse(complexJson);
console.log(parsed.text); // "hello"
console.log(parsed.binary instanceof Buffer); // true
console.log(parsed.binary.toString()); // "world"
console.log(parsed.nested.value); // 42

Error Handling

The package relies on standard JSON error handling:

  • SyntaxError: Thrown by parse() when given invalid JSON strings
  • TypeError: Thrown by stringify() for circular references (same as JSON.stringify)
const JSONB = require('json-buffer');

try {
  JSONB.parse('invalid json');
} catch (error) {
  console.log(error instanceof SyntaxError); // true
}

// Circular reference error
const circular = {};
circular.self = circular;
try {
  JSONB.stringify(circular);
} catch (error) {
  console.log(error instanceof TypeError); // true
}

Types

/**
 * Buffer class from Node.js (built-in)
 * Used for handling binary data
 */
class Buffer {
  /**
   * Creates a Buffer from various data types
   * @param {string|number[]|ArrayBuffer} data - The data to create Buffer from
   * @param {string} [encoding] - The encoding to use (e.g., 'base64', 'utf8')
   * @returns {Buffer} New Buffer instance
   */
  static from(data, encoding);
  
  /**
   * Converts Buffer to string representation
   * @param {string} [encoding] - The encoding to use (default: 'utf8')
   * @returns {string} String representation of the Buffer
   */
  toString(encoding);
  
  /**
   * Checks if an object is a Buffer instance
   * @param {any} obj - Object to check
   * @returns {boolean} True if obj is a Buffer
   */
  static isBuffer(obj);
}

docs

index.md

tile.json