Bit-Bundler Utilities

Common errors

• Error: setId can only be set once with a different value. Original value was [original_value], new value is [new_value]

  cause Attempting to call `uniqueId.setId` for the same `moduleId` with a `value` different from what was previously set.
  fix Review calls to `uniqueId.setId` to ensure consistency. If a module's unique ID needs to change, it indicates a design flaw or a need to reset the `uniqueId` state (which is not directly exposed by the API).

• Cannot find module 'bit-bundler-utils/resolvePath'

  cause The package `bit-bundler-utils` is not installed, or the specified subpath (`/resolvePath`, `/readFile`, `/uniqueId`) is incorrect.
  fix Ensure `bit-bundler-utils` is correctly installed via `npm install bit-bundler-utils` and that the `require()` path matches one of the documented subpath exports.

• TypeError: [exported_function] is not a function

  cause Incorrect module import syntax. This library is CommonJS-based, and direct `import` statements might not correctly resolve its exports or may treat the default export differently than expected.
  fix Change `import` statements to CommonJS `require()` syntax: `const resolvePath = require('bit-bundler-utils/resolvePath');`

Warnings

• gotcha The `uniqueId.setId` method will throw an exception if called more than once for the same `moduleId` but with a *different* `value`. It is designed to ensure a module ID maps to a single, consistent unique value after its initial setting.
  Fix: Ensure `uniqueId.setId` is called with the same `value` for subsequent calls with the same `moduleId`, or design your application to set the ID only once per module. Repeated calls with the *same* `moduleId` and `value` are permitted.
• gotcha The `uniqueId.getId` method caches its results. Subsequent calls with the same `moduleId` will return the exact same generated ID without re-computation.
  Fix: Be aware of the caching behavior when testing or in scenarios where dynamic ID generation with different results for the same input might be expected. This is by design for performance and consistency within the `bit-bundler` ecosystem.
• gotcha This library primarily uses CommonJS (`require()`) module syntax. While modern Node.js environments support ESM (`import`), direct ESM imports for `bit-bundler-utils`'s subpath exports might not work as expected or without additional bundler configuration.
  Fix: Prefer `const module = require('bit-bundler-utils/subpath');` syntax. If you must use ESM, ensure your build tool (e.g., Webpack, Rollup) is configured to handle CommonJS modules within an ESM project, or use dynamic `import()` for CJS modules if supported by your runtime.

Install

• npm install bit-bundler-utils npm
• yarn add bit-bundler-utils yarn
• pnpm add bit-bundler-utils pnpm

Imports

• uniqueId
  wrong:

  import uniqueId from 'bit-bundler-utils/uniqueId';

  correct:

  const uniqueId = require('bit-bundler-utils/uniqueId');

  This module exports an object containing `getId` and `setId` methods. Direct ES module `import` syntax is generally not supported without bundler intervention, as this library is primarily CommonJS.
• resolvePath
  wrong:

  import resolvePath from 'bit-bundler-utils/resolvePath';

  correct:

  const resolvePath = require('bit-bundler-utils/resolvePath');

  The `resolvePath` function is exported directly as a CommonJS module. It returns a Promise.
• readFile
  wrong:

  import readFile from 'bit-bundler-utils/readFile';

  correct:

  const readFile = require('bit-bundler-utils/readFile');

  The `readFile` function is exported directly as a CommonJS module. It returns a Promise and handles binary files gracefully.

Quickstart

This quickstart demonstrates resolving a module path, reading its content, and using the unique ID generation and setting functionalities.

const resolvePath = require('bit-bundler-utils/resolvePath');
const readFile = require('bit-bundler-utils/readFile');
const uniqueId = require('bit-bundler-utils/uniqueId');

async function exampleUsage() {
  try {
    // Resolve a module path
    const result = await resolvePath({
      name: 'some-local-module',
      baseUrl: process.cwd()
    });
    console.log(`Resolved path for 'some-local-module': ${result.path}`);

    // Read a file's content
    const fileContent = await readFile({
      path: result.path // Using the resolved path
    });
    console.log(`Content snippet from ${result.path}: ${fileContent.source.substring(0, 100)}...`);

    // Generate and set unique IDs
    const id1 = uniqueId.getId('path/to/moduleA.js');
    const id2 = uniqueId.getId('path/to/moduleB.js');
    console.log(`ID for moduleA: ${id1}`);
    console.log(`ID for moduleB: ${id2}`);

    uniqueId.setId('path/to/special-module.js', 123);
    console.log(`Explicitly set ID for 'path/to/special-module.js'.`);

  } catch (error) {
    console.error('An error occurred:', error.message);
  }
}

exampleUsage();