{"id":15544,"library":"bit-bundler-utils","title":"Bit-Bundler Utilities","description":"Bit-Bundler Utilities (`bit-bundler-utils`) is a Node.js helper library providing essential functionalities for projects built with `bit-bundler` and `bit-imports`. Currently at stable version 5.1.2, this package offers utilities for generating and managing unique module IDs, robustly resolving module and file paths, and asynchronously reading file contents from disk. Its path resolution capabilities are powered by `browser-resolve`, making it suitable for both Node.js and browser-compatible path handling. The library emphasizes stability and integration within the `bit-bundler` ecosystem, maintaining an `active` release cadence with regular patch updates to ensure reliability and address minor issues.","status":"active","version":"5.1.2","language":"javascript","source_language":"en","source_url":"https://github.com/MiguelCastillo/bit-bundler-utils","tags":["javascript","bit-bundler"],"install":[{"cmd":"npm install bit-bundler-utils","lang":"bash","label":"npm"},{"cmd":"yarn add bit-bundler-utils","lang":"bash","label":"yarn"},{"cmd":"pnpm add bit-bundler-utils","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used internally by the `resolvePath` utility for Node.js module resolution, enabling consistent path handling for both Node.js and browser environments.","package":"browser-resolve","optional":false}],"imports":[{"note":"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.","wrong":"import uniqueId from 'bit-bundler-utils/uniqueId';","symbol":"uniqueId","correct":"const uniqueId = require('bit-bundler-utils/uniqueId');"},{"note":"The `resolvePath` function is exported directly as a CommonJS module. It returns a Promise.","wrong":"import resolvePath from 'bit-bundler-utils/resolvePath';","symbol":"resolvePath","correct":"const resolvePath = require('bit-bundler-utils/resolvePath');"},{"note":"The `readFile` function is exported directly as a CommonJS module. It returns a Promise and handles binary files gracefully.","wrong":"import readFile from 'bit-bundler-utils/readFile';","symbol":"readFile","correct":"const readFile = require('bit-bundler-utils/readFile');"}],"quickstart":{"code":"const resolvePath = require('bit-bundler-utils/resolvePath');\nconst readFile = require('bit-bundler-utils/readFile');\nconst uniqueId = require('bit-bundler-utils/uniqueId');\n\nasync function exampleUsage() {\n  try {\n    // Resolve a module path\n    const result = await resolvePath({\n      name: 'some-local-module',\n      baseUrl: process.cwd()\n    });\n    console.log(`Resolved path for 'some-local-module': ${result.path}`);\n\n    // Read a file's content\n    const fileContent = await readFile({\n      path: result.path // Using the resolved path\n    });\n    console.log(`Content snippet from ${result.path}: ${fileContent.source.substring(0, 100)}...`);\n\n    // Generate and set unique IDs\n    const id1 = uniqueId.getId('path/to/moduleA.js');\n    const id2 = uniqueId.getId('path/to/moduleB.js');\n    console.log(`ID for moduleA: ${id1}`);\n    console.log(`ID for moduleB: ${id2}`);\n\n    uniqueId.setId('path/to/special-module.js', 123);\n    console.log(`Explicitly set ID for 'path/to/special-module.js'.`);\n\n  } catch (error) {\n    console.error('An error occurred:', error.message);\n  }\n}\n\nexampleUsage();","lang":"javascript","description":"This quickstart demonstrates resolving a module path, reading its content, and using the unique ID generation and setting functionalities."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"The `uniqueId.getId` method caches its results. Subsequent calls with the same `moduleId` will return the exact same generated ID without re-computation.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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).","cause":"Attempting to call `uniqueId.setId` for the same `moduleId` with a `value` different from what was previously set.","error":"Error: setId can only be set once with a different value. Original value was [original_value], new value is [new_value]"},{"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.","cause":"The package `bit-bundler-utils` is not installed, or the specified subpath (`/resolvePath`, `/readFile`, `/uniqueId`) is incorrect.","error":"Cannot find module 'bit-bundler-utils/resolvePath'"},{"fix":"Change `import` statements to CommonJS `require()` syntax: `const resolvePath = require('bit-bundler-utils/resolvePath');`","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.","error":"TypeError: [exported_function] is not a function"}],"ecosystem":"npm"}