@observ33r/object-generator

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.