Required dependencies

npm install args eventemitter2 fastest-validator glob ipaddr.js kleur lodash lru-cache recursive-watch

No native build steps, pod installs, or prebuild commands are required. All dependencies are pure JavaScript.

Project setup

1. Copy the source/ directory into your project, for example at lib/moleculer/.
2. (TypeScript) Add a path alias in tsconfig.json:

{
  "compilerOptions": {
    "paths": {
      "moleculer/*": ["lib/moleculer/*"]
    }
  }
}

3. Reference the broker entry point directly:

import ServiceBroker = require("./lib/moleculer/service-broker");

4. No required environment variables for basic usage. Optional env vars used by specific adapters:
   • REDIS_URL - used by Redis cacher/transporter if you pass it as a connection string
   • DATADOG_API_KEY - needed only if using Datadog logger or metrics reporter
5. For ESM projects using the runner, use runner-esm.mjs as the entry point.

Public API

Cachers.resolve

function resolve(
  opt: Record<string, any> | string | boolean | null
): BaseCacher | null;

Resolves and instantiates a cacher from a string name ("Memory", "Redis", a redis:// URL), a config object { type, options }, or true for the default in-memory cacher. Returns null if opt is falsy. Use this when wiring broker options or writing middleware that needs caching without hardcoding a cacher class.

Loggers.resolve

function resolve(
  opt: Record<string, any> | string
): BaseLogger;

Resolves and instantiates a logger by string name ("Console", "Winston", etc.) or config object { type, options }. Throws BrokerOptionsError on unknown type. Use this to build a logger pipeline before constructing the broker, or to swap loggers in tests.

Reporters.resolve (metrics)

function resolve(
  opt: Record<string, any> | string
): BaseReporter;

Resolves a metrics reporter by name ("Prometheus", "StatsD", "Console", etc.) or config object. Throws BrokerOptionsError on unknown type. Use this when configuring the MetricRegistry with a custom reporter list.

Cachers.register / Reporters.register

function register(name: string, value: any): void;

Adds a custom cacher or reporter class under a given name so it can later be resolved by that name string. Use this to extend the framework with third-party adapters without modifying source files.

Working examples

Scenario - Minimal service broker with in-memory caching

Create a broker with the default Memory cacher, define a math service, and call an action.

const ServiceBroker = require("./lib/moleculer/service-broker");

const broker = new ServiceBroker({
  logger: { type: "Console", options: { level: "info" } },
  cacher: "Memory"
});

broker.createService({
  name: "math",
  actions: {
    add(ctx: any) {
      return Number(ctx.params.a) + Number(ctx.params.b);
    }
  }
});

broker.start()
  .then(() => broker.call("math.add", { a: 5, b: 3 }))
  .then((result: number) => console.log("Result:", result))
  .then(() => broker.stop());

Scenario - Custom cacher via Cachers.resolve

Resolve a Redis cacher from a connection string and pass it directly to the broker.

const ServiceBroker = require("./lib/moleculer/service-broker");
const { resolve: resolveCacher } = require("./lib/moleculer/cachers");

const cacher = resolveCacher("redis://localhost:6379");

const broker = new ServiceBroker({ cacher });

broker.createService({
  name: "cache-demo",
  actions: {
    async get(ctx: any) {
      const cached = await this.broker.cacher.get(ctx.params.key);
      if (cached) return cached;
      const value = { computed: true, key: ctx.params.key };
      await this.broker.cacher.set(ctx.params.key, value, 60);
      return value;
    }
  }
});

broker.start()
  .then(() => broker.call("cache-demo.get", { key: "hello" }))
  .then((v: any) => console.log(v))
  .then(() => broker.stop());

Scenario - Prometheus metrics reporter

Wire a Prometheus reporter into the broker so metrics are exposed at /metrics.

const ServiceBroker = require("./lib/moleculer/service-broker");
const { resolve: resolveReporter } = require("./lib/moleculer/metrics/reporters");

const reporter = resolveReporter({ type: "Prometheus", options: { port: 3030 } });

const broker = new ServiceBroker({
  metrics: {
    enabled: true,
    reporter: [reporter]
  }
});

broker.createService({ name: "ping", actions: { ping: () => "pong" } });

broker.start().then(() => {
  console.log("Prometheus metrics available at http://localhost:3030/metrics");
});

Scenario - Register a custom logger and resolve it

const { register, resolve } = require("./lib/moleculer/loggers");
const BaseLogger = require("./lib/moleculer/loggers/base");

class MyLogger extends BaseLogger {
  getLogHandler(bindings: any) {
    return (type: string, args: any[]) => console.log(`[MY] [${type}]`, ...args);
  }
}

register("MyLogger", MyLogger);

const logger = resolve({ type: "MyLogger", options: {} });
console.log(logger instanceof BaseLogger); // true

File walkthrough

• service-broker.js - Top-level broker class; all services, middleware, and subsystems attach here.
• service.js - Defines the Service class that broker.createService() instantiates.
• context.js - Encapsulates a single call/event invocation with params, metadata, and span.
• errors.js - Exports all named error classes (BrokerOptionsError, ServiceNotFoundError, etc.).
• transit.js - Handles serialization and dispatch of packets between nodes.
• packets.js - Packet schema definitions used by transit.
• middleware.js - Runs the ordered middleware chain for every broker operation.
• logger-factory.js - Constructs and binds logger instances to broker/service namespaces.
• constants.js - Shared string constants used across the framework.
• utils.js - isObject, isString, isInheritedClass, and other internal helpers.
• health.js - Gathers node health data for $node.health built-in action.
• lock.js - Lightweight async mutex used internally by cachers.
• runner.js / runner-esm.mjs - CLI entry points for moleculer-runner invocation.
• internals.js - Registers $node.* internal services on the broker.
• async-storage.js - AsyncLocalStorage wrapper for context propagation without explicit passing.
• cpu-usage.js - Periodic CPU sampling used by the cpu-usage load-balancing strategy.
• cachers/ - Base + Memory + MemoryLRU + Redis implementations with factory resolver.
• loggers/ - Base + eight concrete logger adapters with factory resolver.
• metrics/ - MetricRegistry, four metric types, seven reporter adapters, METRIC constants.
• middlewares/ - Built-in middleware hooks (circuit-breaker, bulkhead, retry, timeout, etc.).
• registry/ - Node/service/action/event catalog and endpoint lists.
• serializers/ - Pluggable serialization layer between transit peers.
• strategies/ - Endpoint selection strategies for load balancing.
• tracing/ - Distributed tracing context and exporter adapters.
• transporters/ - Network transport adapters for inter-node communication.
• validators/ - Parameter validation hook wrapping fastest-validator.

Common pitfalls and fixes

• lru-cache API mismatch - lru-cache v7+ changed its API; pin "lru-cache": "^6.0.0" in your package.json to match v0.15.0 expectations.
• Redis cacher peer dep - ioredis is not in dependencies; install it separately with npm install ioredis before using the Redis cacher or transporter.
• ESM / CJS interop - All source files use require(); if your project is "type": "module", use createRequire or import via the .mjs runner; do not rename files.
• fastest-validator version - The validator adapter expects the v1.x API; npm install fastest-validator@^1 explicitly to avoid v2 breaking changes.
• Transporter peer deps not bundled - NATS, Kafka, MQTT, and AMQP adapters each require their own client library (nats, kafkajs, mqtt, amqplib); install only the ones you use.
• TypeScript strict mode - The .d.ts files use implicit any in several places; add "skipLibCheck": true in tsconfig.json to prevent type errors from source declarations.

Vibe-coding prompt template

I have the Moleculer microservices framework source copied into `lib/moleculer/`
in my Node.js/TypeScript project. I also have the file `USAGE.md` in my project
root which documents the real exports, file layout, and working examples for this
source (upstream package: user@example.com).

Please help me integrate it step by step:

1. Read `USAGE.md` and `lib/moleculer/service-broker.js` to understand the broker API.
2. Create a `src/broker.ts` that instantiates a ServiceBroker with a Console logger
   and Memory cacher, using only real exports shown in `USAGE.md`.
3. Create a sample service in `src/services/example.service.ts` with at least two actions.
4. Wire broker start/stop into my existing Express app lifecycle (show where to call
   broker.start() relative to app.listen()).
5. Show how to add a Prometheus metrics reporter using `lib/moleculer/metrics/reporters`
   resolve() function exactly as documented in `USAGE.md`.
6. Point out any missing peer dependencies I need to install based on the adapters I am using.

Do not invent any API methods. Use only symbols visible in `USAGE.md` and the source files.

License and credit

Moleculer is released under the MIT License. See source/LICENSE if present, or refer to the official repository. Upstream package: moleculer on npm, maintained by MoleculerJS.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

完全なインストールガイドと統合プロンプトは購入後に解放されます。