tosource: Object to Source Code Converter

Common errors

• ReferenceError: toSource is not defined

  cause Incorrect import statement or attempting to use `toSource` before it's properly imported/required.
  fix For ESM, use `import toSource from 'tosource';`. For CommonJS, use `const toSource = require('tosource');`. Ensure `toSource` is within scope.

• TypeError: tosource is not a function

  cause Often occurs when using a named import (e.g., `import { toSource } from 'tosource';`) instead of the default import for ESM, or a destructured require for CJS, as `toSource` is a default export.
  fix Use the default import for ESM (`import toSource from 'tosource';`) or a standard `require` for CJS (`const toSource = require('tosource');`).

• ERR_REQUIRE_ESM: Must use import to load ES Module

  cause Attempting to use `require()` to import `tosource` in a pure ESM context (e.g., in a package configured with `"type": "module"` in `package.json`).
  fix Switch to `import toSource from 'tosource';` if your environment supports ESM. If you must use CommonJS, ensure your environment is configured for CJS modules.

• Node.js version mismatch

  cause The installed Node.js version is below the minimum requirement (10.x) for `tosource` v2.x.
  fix Upgrade your Node.js runtime to version 10 or higher. You can use tools like `nvm` (Node Version Manager) to manage multiple Node.js versions.

Warnings

• breaking Version 2.x introduces a minimum Node.js requirement of 10.x. Older Node.js environments are not supported.
  Fix: Upgrade your Node.js environment to version 10 or higher. For production, consider using a stable LTS version.
• breaking The handling of negative zero (`-0`) was fixed in `v2.0.0-alpha.3` and now correctly uses `Object.is` for comparison during serialization. This might subtly change output if your application relied on previous serialization behavior for negative zero.
  Fix: Review code that processes serialized output potentially containing negative zero to ensure compatibility with `Object.is` semantics.
• gotcha Functions are serialized by calling their `toString()` method. This means only the function's source code is preserved; its lexical environment (closures) and bound `this` context are not serialized.
  Fix: Be aware that functions serialized by `tosource` are effectively re-created from source when evaluated. Do not rely on them to maintain runtime state or closures from the original context.
• gotcha Multiple references to the same object in the input will result in multiple independent copies in the serialized output, rather than maintaining shared references.
  Fix: Understand that the deserialized object graph will not preserve referential equality for objects that were referenced multiple times in the original structure, unless they form a circular reference (which is handled differently).
• gotcha Circular references within objects are detected and serialized as `{$circularReference:true}`. Attempting to deserialize and execute this without custom handling will result in an object literal, not the original circular structure.
  Fix: Implement custom logic on the consuming end if you need to reconstruct circular references, or ensure your data structures do not contain them if exact reconstruction is critical.
• gotcha The package is currently in an alpha state (`2.0.0-alpha.3`). APIs might change without a full major version bump, and it may contain unresolved bugs. It is not recommended for critical production environments without thorough testing.
  Fix: Proceed with caution, monitor release notes for breaking changes, and thoroughly test in your specific environment before deploying to production. Consider locking to a specific alpha version.

Install

• npm install tosource npm
• yarn add tosource yarn
• pnpm add tosource pnpm

Imports

• toSource (ESM Default)
  wrong:

  import { toSource } from 'tosource';

  correct:

  import toSource from 'tosource';

  Since v2, `tosource` is primarily designed for ESM with a default export. Attempting a named import will result in `toSource is not a function` at runtime.
• toSource (CommonJS)
  wrong:

  const { toSource } = require('tosource');

  correct:

  const toSource = require('tosource');

  While v2 emphasizes ESM, CommonJS is still supported. Ensure you are using a default require, not a destructured named require, as `toSource` is the default export.
• Type Definition

  import type toSource from 'tosource';

  The package ships with TypeScript type definitions. Use `import type` to import the type for the default `toSource` function in TypeScript projects.

Quickstart

Demonstrates serialization of various JavaScript types, including functions, regular expressions, dates, Map, Set, and handling of circular references by marking them.

import toSource from 'tosource';

const complexObject = [
  4,
  5,
  6,
  'hello',
  {
    a: 2,
    b: 3,
    '1': 4,
    if: 5,
    yes: true,
    no: false,
    nan: NaN,
    infinity: Infinity,
    undefined: undefined,
    null: null,
    foo: function (bar) {
      console.log('woo! a is ' + this.a);
      console.log('and bar is ' + bar);
    },
  },
  /we$/gi,
  new Date('Wed, 09 Aug 1995 00:00:00 GMT'),
  new Map([['key1', 'value1'], ['key2', 123]]),
  new Set([1, 2, 'three'])
];

console.log('Serialized Complex Object:\n', toSource(complexObject));

// Example with a circular reference (tosource handles it by marking)
const objWithCircularRef = { id: 1 };
objWithCircularRef.self = objWithCircularRef;
objWithCircularRef.nested = { child: objWithCircularRef };

console.log('\nSerialized Object with Circular Reference:\n', toSource(objWithCircularRef));