or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-json-stable-stringify

Deterministic JSON.stringify() to get deterministic hashes from stringified results

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/json-stable-stringify@1.0.x

To install, run

npx @tessl/cli install tessl/npm-json-stable-stringify@1.0.0

index.mddocs/

Fast JSON Stable Stringify

Fast JSON Stable Stringify provides a deterministic version of JSON.stringify() that produces consistent output for the same input, enabling reliable hash generation from stringified JSON objects. It addresses the inherent non-deterministic behavior of standard JSON.stringify() by sorting object keys in a consistent order.

Package Information

  • Package Name: json-stable-stringify
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install json-stable-stringify

Core Imports

const stringify = require('json-stable-stringify');

Basic Usage

const stringify = require('json-stable-stringify');

// Basic usage - keys are sorted alphabetically
const obj = { c: 8, b: [4, 5], a: 3 };
const result = stringify(obj);
console.log(result); // {"a":3,"b":[4,5],"c":8}

// With pretty printing
const prettyResult = stringify(obj, { space: '  ' });
console.log(prettyResult);
// {
//   "a": 3,
//   "b": [
//     4,
//     5
//   ],
//   "c": 8
// }

Capabilities

Stringify Function

Creates a deterministic string representation of JavaScript objects by consistently sorting object keys.

/**
 * Creates a deterministic string representation of JavaScript objects
 * @param {any} obj - The JavaScript value to stringify. Objects with toJSON methods will have those methods called automatically
 * @param {object|function} [opts] - Options object or comparison function
 * @returns {string|undefined} Deterministic JSON string representation
 */
function stringify(obj, opts);

Parameters

  • obj (any): The JavaScript value to stringify. Can be any valid JSON value including objects, arrays, strings, numbers, booleans, or null.
  • opts (object|function, optional): Configuration options or comparison function
    • If function: treated as custom comparison function for object key sorting
    • If object: configuration object with the following properties

Options Object Properties

interface StringifyOptions {
  /** Custom comparison function for object key sorting */
  cmp?: (a: CompareObject, b: CompareObject) => number;
  /** Indentation for pretty-printing (string or number of spaces) */
  space?: string | number;
  /** Whether to handle circular references (default: false) */
  cycles?: boolean;
  /** Custom value transformation function */
  replacer?: (key: string, value: any) => any;
}

interface CompareObject {
  /** The object key being compared */
  key: string;
  /** The value associated with the key */
  value: any;
}

Return Value

  • Type: string | undefined
  • Description: Deterministic JSON string representation of the input object, or undefined if the value cannot be stringified

Error Handling

  • TypeError: Thrown when circular structure is detected and opts.cycles is false or undefined. Error message: "Converting circular structure to JSON"
  • Returns undefined for values that cannot be stringified (like functions without custom replacer)
  • toJSON handling: Objects with toJSON methods are automatically called during stringification

Usage Examples

Custom Key Comparison

const stringify = require('json-stable-stringify');

const obj = { c: 8, b: [4, 5], a: 3 };

// Reverse alphabetical key sorting
const result = stringify(obj, function (a, b) {
  return a.key < b.key ? 1 : -1;
});
console.log(result); // {"c":8,"b":[4,5],"a":3}

// Sort by value (descending)
const obj2 = { d: 6, c: 5, b: 4, a: 10 };
const result2 = stringify(obj2, function (a, b) {
  return a.value < b.value ? 1 : -1;
});
console.log(result2); // {"a":10,"d":6,"c":5,"b":4}

Pretty Printing with Space Option

const stringify = require('json-stable-stringify');

const obj = { b: 1, a: { foo: 'bar', and: [1, 2, 3] } };

// Using string indentation
const result1 = stringify(obj, { space: '  ' });

// Using number of spaces
const result2 = stringify(obj, { space: 4 });

// Using tab character
const result3 = stringify(obj, { space: '\t' });

Custom Replacer Function

const stringify = require('json-stable-stringify');

const obj = { 
  name: 'John', 
  password: 'secret123', 
  age: 30,
  internal: 'hidden'
};

// Remove sensitive fields
const result = stringify(obj, {
  replacer: function(key, value) {
    if (key === 'password' || key === 'internal') {
      return undefined; // Exclude from output
    }
    return value;
  }
});
console.log(result); // {"age":30,"name":"John"}

toJSON Method Handling

Objects with toJSON methods are automatically processed during stringification, similar to native JSON.stringify().

const stringify = require('json-stable-stringify');

// Object with toJSON method returning object
const obj1 = { 
  one: 1, 
  two: 2, 
  toJSON: function() { 
    return { one: 1 }; 
  } 
};
console.log(stringify(obj1)); // {"one":1}

// Object with toJSON method returning string
const obj2 = { 
  one: 1, 
  two: 2, 
  toJSON: function() { 
    return 'one'; 
  } 
};
console.log(stringify(obj2)); // "one"

// Object with toJSON method returning array
const obj3 = { 
  one: 1, 
  two: 2, 
  toJSON: function() { 
    return ['one']; 
  } 
};
console.log(stringify(obj3)); // ["one"]

Handling Circular References

const stringify = require('json-stable-stringify');

const obj = { a: 1 };
obj.circular = obj; // Create circular reference

// With cycles: true - circular references become "__cycle__"
const safe = stringify(obj, { cycles: true });
console.log(safe); // {"a":1,"circular":"__cycle__"}

// With cycles: false (default) - throws TypeError
try {
  const unsafe = stringify(obj);
} catch (error) {
  console.log(error.message); // "Converting circular structure to JSON"
}

Combined Options

const stringify = require('json-stable-stringify');

const obj = { c: 8, b: [{ z: 6, y: 5, x: 4 }, 7], a: 3 };

const result = stringify(obj, {
  space: 2,
  cmp: function(a, b) {
    return a.key < b.key ? -1 : 1; // Alphabetical sorting
  },
  replacer: function(key, value) {
    // Convert numbers to strings
    return typeof value === 'number' ? String(value) : value;
  }
});

Key Features

  1. Deterministic Output: Always produces the same string for the same input object structure
  2. Key Sorting: Automatically sorts object keys alphabetically by default
  3. Custom Sorting: Supports custom comparison functions for flexible key ordering
  4. Pretty Printing: Optional indentation support for readable output
  5. Circular Reference Handling: Configurable behavior for circular object structures
  6. Replacer Support: Custom value transformation like standard JSON.stringify
  7. Cross-platform: Works in all JavaScript environments (Node.js, browsers)
  8. No Dependencies: Pure JavaScript implementation with no external dependencies

Compatibility

  • Node.js: All versions
  • Browsers: IE8+ and all modern browsers
  • Module Systems: CommonJS (primary), potentially ES modules depending on build setup