object-generator

High-performance, customizable dummy object generator for testing and benchmarking.

Features

• Guaranteed Structure Consistency
  The nestedSize and depth options are always respected, ensuring consistent object structures even when circular references are enabled with circular: true. This guarantees predictable output regardless of configuration.

• Globally Unique Identifiers
  With globalIndex: true, all keys and string values remain unique across the generated object. This uniqueness eliminates ambiguity and ensures reliable comparisons or traversals.

• Real-World Object Design
  Objects are crafted to mimic real-world data structures as closely as possible. This approach avoids overly simplistic or uniform patterns that could trigger JIT (Just-In-Time) compiler optimizations, making the generator ideal for robust benchmarking and testing scenarios.

• Performance Testing Ready
  Designed for benchmark challenges between libraries by providing diverse and repeatable complex objects!

• Type-Safe
  Fully typed with TypeScript declarations.

Installation

Install the package via npm:

npm install @observ33r/object-generator

Usage

objectGenerator([options])

• options: Optional configuration object (see below).
• Returns: An object of the specified type with generated content based on the provided options.

Options

| Property | Type | Default | Description | | :---: | :---: | :---: | :--- | | prefix | string \| number \| false | false| A prefix to prepend to generated keys/strings. Must be a non-empty string, number or false. | | type | constructor | Object | The type of object to generate. Must be one of Object, Array, Set, Map, or Uint8Array. | | size | number | 16 | Size of the top-level object. Must be an integer. | | nestedSize | number | 16 | Size of nested objects. Must be an integer. | | depth | number | 0 | Maximum depth for nested structures. Must be an integer.| | valueTypes | [constructor \| NaN \| undefined \| null] | [String] | Array of value types to include: Boolean, Number, String, Date, RegExp, Uint8Array, Object, Array, Set, Map, NaN, undefined, null. | | globalIndex | boolean | true | Whether to include a global index in generated keys/values. | | circular | boolean | false | Whether to allow circular references in the generated object. | | shuffle | boolean | false | Whether to shuffle the order of elements or keys. | | seed | number | random | Seed for randomization when shuffle is enabled. If not provided, a random seed is used. |

Examples

Generate a simple Object

import { objectGenerator } from '@observ33r/object-generator';

const obj = objectGenerator({ size: 4 });

console.log(obj);

{
  'string-4-0': 'value-4-0',
  'string-4-1': 'value-4-1',
  'string-4-2': 'value-4-2',
  'string-4-3': 'value-4-3'
}

Generate a nested Object with a prefix

import { objectGenerator } from '@observ33r/object-generator';

const obj = objectGenerator({
  prefix: 'data',
  size: 4,
  nestedSize: 4,
  depth: 1,
  valueTypes: [String, Number, Boolean]
});

console.log(obj);

{
  'data-string-4-0-0-0': 'data-value-4-0-0-0',
  'data-number-4-0-1-1': 1,
  'data-boolean-4-0-2-2': true,
  'data-object-4-0-3-3': {
    'data-string-4-1-4-0': 'data-value-4-1-4-0',
    'data-number-4-1-5-1': 1,
    'data-boolean-4-1-6-2': true,
    'data-string-4-1-7-3': 'data-value-4-1-7-3'
  }
}

Generate a simple numeric Array

import { objectGenerator } from '@observ33r/object-generator';

const arr = objectGenerator({
  type: Array,
  size: 8,
  valueTypes: [Number],
});

console.log(arr);

[
  0, 1, 2, 3,
  4, 5, 6, 7
]

Generate a repeatable shuffled Typed Array

import { objectGenerator } from '@observ33r/object-generator';

const typedArray = objectGenerator({
  type: Uint8Array,
  size: 8,
  shuffle: true,
  seed: 42
});

//Uint8Array
console.log(typedArray);
//or ArrayBuffer
console.log(typedArray.buffer);
//or DataView
console.log(new DataView(typedArray.buffer));

Uint8Array(8) [
  2, 0, 4, 1,
  3, 6, 7, 5
]

ArrayBuffer {
  [Uint8Contents]: <02 00 04 01 03 06 07 05>,
  byteLength: 8
}

DataView {
  byteLength: 8,
  byteOffset: 0,
  buffer: ArrayBuffer {
    [Uint8Contents]: <02 00 04 01 03 06 07 05>,
    byteLength: 8
  }
}

Generate a repeatable shuffled nested Set without a global index

import { objectGenerator } from '@observ33r/object-generator';

const set = objectGenerator({
  type: Set,
  size: 2,
  nestedSize: 2,
  depth: 2,
  valueTypes: [Set],
  globalIndex: false,
  shuffle: true,
  seed: 42
});

console.log(set);

Set(2) {
  Set(2) {
    Set(2) { 'value-2-2-1', 'value-2-2-0' },
    Set(2) { 'value-2-2-0', 'value-2-2-1' }
  },
  Set(2) {
    Set(2) { 'value-2-2-0', 'value-2-2-1' },
    Set(2) { 'value-2-2-1', 'value-2-2-0' }
  }
}

Build

This package uses rollup to generate clean and optimized ESM builds.

To build package from source code, run:

npm run build

Testing

All tests are written in Vitest with native ESM support and zero transform overhead.

You can run the full suite with:

npm test

Contributing

Feel free to open issues or submit pull requests on GitHub.

License

This project is licensed under the MIT License.