Bit-Bundler Service

Common errors

• Error: The 'node' argument must be of type string. Received an instance of [object Undefined]

  cause Attempting to run the service with an incompatible or outdated Node.js version, or missing environmental setup for core dependencies.
  fix Ensure Node.js v6 is used, as specified in `engines.node`. However, using such an old Node.js version is a major security risk. A more viable fix would involve updating the service's source code to be compatible with a modern Node.js runtime.

• Error: listen EADDRINUSE :::4000

  cause The default port (4000) for the service is already in use by another application.
  fix Specify a different port using the `PORT` environment variable: `PORT=8080 node index.js`

• Error: Must provide document for GraphQL request.

  cause The GraphQL API was called without a valid query or mutation in the request body, or with an improperly formatted request.
  fix Ensure your HTTP POST request to `/graphql` includes a JSON body with a `query` field containing a valid GraphQL query string. When using `curl`, escape double quotes appropriately.

Warnings

• breaking This project is explicitly tagged as an 'experiment' in its README. It is not intended for production use and may not be actively maintained or receive security updates. Relying on it for critical applications is strongly discouraged.
  Fix: Do not use this package for production environments. Consider actively maintained and production-ready bundlers or build services.
• breaking The package's `engines.node` specifies `>=6`, which is an extremely outdated Node.js version. Running this service on modern Node.js versions may lead to compatibility issues or failures. It also implies a lack of recent security updates for the runtime environment itself.
  Fix: While `npm install` might proceed, direct execution `node index.js` on recent Node.js versions might fail due to deprecated APIs or syntax. Running an ancient Node.js v6 is a major security risk. No direct fix is available without source code modifications.
• gotcha The service allows bundling arbitrary npm modules specified by name and version. Without proper sandboxing and security measures, this could be a severe supply chain vulnerability if malicious module names or versions are requested.
  Fix: If deploying, implement robust security sandboxing, input validation, and whitelist modules and versions, or run in an isolated environment where bundle execution cannot compromise the host system.

Install

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

Imports

• Service Interaction (General)
  wrong:

  import BitBundlerService from 'bit-bundler-service';

  correct:

  // Interact via HTTP POST requests to http://localhost:4000/graphql

  This package is a standalone web service with a GraphQL API. It is not designed for programmatic import as a library into other Node.js applications. Functionality is accessed by making HTTP requests to its GraphQL endpoint.
• createBundle (GraphQL Operation)
  wrong:

  import { createBundle } from 'bit-bundler-service';

  correct:

  const query = `query bundler($modules: [Module]) { bundler { createBundle(modules: $modules) } }`; /* ... then POST to /graphql with variables */

  The 'createBundle' function is part of the GraphQL API schema. It is invoked by sending a GraphQL query to the service's endpoint, not by importing a function from the package.
• getBundle (GraphQL Operation)
  wrong:

  import { getBundle } from 'bit-bundler-service';

  correct:

  const query = `query getBundle { bundler { getBundle(id: "BUNDLE_ID") { hash, bundle, sourcemap } } }`; /* ... then POST to /graphql */

  Similar to 'createBundle', 'getBundle' is a GraphQL operation. Access its capabilities by constructing and sending the appropriate GraphQL query over HTTP.

Quickstart

This quickstart demonstrates how to set up and run the bit-bundler-service locally, then interact with its GraphQL API to create and retrieve a bundled JavaScript module. It shows how to pass module details to `createBundle` and then fetch the resulting bundle using its ID.

npm install # In the cloned bit-bundler-service directory

# Start the service with GraphiQL enabled for easy testing
DEBUG=true node index.js &

# Wait for the server to start, then make a GraphQL request
# (e.g., using curl or a GraphQL client like Insomnia/GraphiQL)

# Example GraphQL Query (save as createBundle.graphql):
// query bundler($modules: [Module]) {
//   bundler {
//     createBundle(modules: $modules)
//   }
// }

# Example GraphQL Variables (save as createBundleVariables.json):
// {
//   "modules": [
//     {
//       "name": "spromise",
//       "version": "^1.0.0"
//     },
//     {
//       "name": "lodash.get",
//       "version": "^4.4.2"
//     }
//   ]
// }

# Send the request to create a bundle
curl -X POST -H "Content-Type: application/json" \
  --data '{"query": "query bundler($modules: [Module]) { bundler { createBundle(modules: $modules) } }", "variables": { "modules": [ { "name": "spromise", "version": "^1.0.0" }, { "name": "lodash.get", "version": "^4.4.2" } ] } }' \
  http://localhost:4000/graphql

# The response will contain a bundle ID. Use it to retrieve the bundle:
# Assuming 'BUNDLE_ID' is the ID returned from createBundle (e.g., e91671086147d525a5887479b9ad6bfd02f0d1ad)
curl -X POST -H "Content-Type: application/json" \
  --data '{"query": "query getBundle { bundler { getBundle(id: \"e91671086147d525a5887479b9ad6bfd02f0d1ad\") { hash, bundle, sourcemap } } }"}' \
  http://localhost:4000/graphql