Teleport JavaScript Object (De)serialization

Common errors

• ReferenceError: require is not defined in ES module scope

  cause Attempting to use CommonJS `require()` syntax within an ES Module (type: 'module' in package.json or .mjs file).
  fix Change `const {parse, stringify} = require('teleport-javascript');` to `import { parse, stringify } from 'teleport-javascript';`

• TypeError: stringify is not a function

  cause Attempting to call `stringify()` or `parse()` directly after a default import, or if the named imports were missed in destructuring.
  fix Ensure you are using named imports: `import { parse, stringify } from 'teleport-javascript';` or `const { parse, stringify } = require('teleport-javascript');`

• TypeError: Cannot convert a BigInt value to a JSON string

  cause Trying to serialize an object containing a `BigInt` using the native `JSON.stringify()` method, which does not support `BigInt`s by default.
  fix Use `teleport-javascript`'s `stringify` function instead: `const stringified = stringify(objWithBigInt);`

Warnings

• gotcha When a `Symbol` is serialized and then deserialized, `teleport-javascript` creates a *new* `Symbol` with the same description, rather than preserving the original `Symbol` reference. This is standard behavior for serialization, but important to note if strict reference equality for `Symbol`s is expected.
  Fix: If exact `Symbol` reference preservation is critical, consider alternative strategies like passing `Symbol`s out-of-band or using a different serialization approach specifically designed for reference tracking beyond object graphs.
• gotcha As with any custom deserialization library, parsing stringified data from untrusted sources carries inherent security risks. While `teleport-javascript` reconstructs objects without executing arbitrary code, specially crafted malicious input could potentially lead to unexpected object structures, resource exhaustion, or other application-specific vulnerabilities.
  Fix: Avoid deserializing input from untrusted sources. If absolutely necessary, sanitize or validate inputs rigorously before passing them to `parse`, and implement robust error handling and resource limits.
• gotcha `teleport-javascript` extends `JSON.stringify`'s capabilities by supporting types like `undefined`, `BigInt`, and `Set` which `JSON.stringify` either omits or throws on. Users expecting strict JSON-compliant output or the default `JSON.stringify` behavior (e.g., omitting `undefined` properties) should be aware of these differences.
  Fix: Understand the full list of supported types and how they are handled. If strict `JSON.stringify` behavior is needed for a subset of the data, use `JSON.stringify` directly on that subset.

Install

• npm install teleport-javascript npm
• yarn add teleport-javascript yarn
• pnpm add teleport-javascript pnpm

Imports

• parse, stringify
  wrong:

  const {parse, stringify} = require('teleport-javascript');

  correct:

  import { parse, stringify } from 'teleport-javascript';

  For ESM environments, use named imports. CommonJS `require` is also supported.
• parse, stringify
  wrong:

  import { parse, stringify } from 'teleport-javascript';

  correct:

  const { parse, stringify } = require('teleport-javascript');

  For CommonJS environments, use destructuring assignment with `require`.
• teleport
  wrong:

  import teleport from 'teleport-javascript';

  correct:

  import * as teleport from 'teleport-javascript';

  The library exports named functions, not a default export. Use `* as` for grouping if preferred.

Quickstart

Demonstrates basic usage of `stringify` and `parse` for a complex object including `BigInt`, `RegExp`, `Set`, `Symbol`, `Date`, `undefined`, and circular references.

import { parse, stringify } from 'teleport-javascript';

const obj = {
  key: 'value',
  undefined: undefined,
  regex: /a-z/gi,
  set: new Set([-Infinity, NaN, Infinity]),
  bigint: 900719925474099123n,
  symbol: Symbol('key'),
  date: new Date()
};
obj.circular = obj; // Add a circular reference

console.log('Original object:', obj);

const stringified = stringify(obj);
console.log('\nStringified output:', stringified);

const parsed = parse(stringified);
console.log('\nParsed object:', parsed);

// Verify circular reference is re-established
console.log('Are circular references restored?', parsed.circular === parsed);
// Verify BigInt and Date types
console.log('BigInt type preserved?', typeof parsed.bigint === 'bigint');
console.log('Date type preserved?', parsed.date instanceof Date);