@dunx/core

The dependency injection container, modules, lifecycle, configuration, and the Logger and RequestContext contracts for dunx.

No dependencies. The other dunx packages can inject a Logger without installing a logging library.

Install

bun add @dunx/core @dunx/transform

Usage

Constructor injection needs no decorators:

import { AppFactory, Module } from '@dunx/core';

export class UsersService {
  constructor(private readonly repo: UsersRepository) {}
}

@Module({
  providers: [UsersRepository, UsersService],
  exports: [UsersService], // absent means nothing is exported
})
export class UsersModule {}

const app = await AppFactory.create(AppModule);

You do not need @Injectable, @Inject, reflect-metadata or experimentalDecorators. @dunx/transform reads each constructor's parameter types when the file loads. Turn it on in bunfig.toml, once for the app and once for tests:

preload = ["@dunx/transform/preload"]

[test]
preload = ["@dunx/transform/preload"]

What is here

| Area | What it covers | Guide | | ------------- | ------------------------------------------------------------ | ------------------------------------------------------ | | Providers | Constructor injection, provide(), token(), inject() | Providers | | Modules | Scoping, imports, exports, global, forRoot | Modules | | Lifecycle | onInit, onBeforeShutdown, onShutdown, signal handlers | Lifecycle | | Configuration | ConfigModule.forRoot, a validate function or a schema | Configuration | | Logging | The Logger contract and ConsoleLogger | Logging | | Events | EventBus, AppEvent, @OnEvent, EventRegistry | Events | | Stats | Durations, Counter, Gauge, RuntimeStats, EventLoopLag | Metrics | | Resilience | ResiliencePolicy, timeout, retry, backoff, jitter, fallback, CircuitBreaker, Bulkhead | Resilience | | Tracing | The Tracer contract, NoopTracer, and OtelModule on /otel | Tracing |

Subpaths

| Subpath | Contains | | ----------------- | ------------------------------------------------------------------------- | | @dunx/core | Everything above. Never imports @opentelemetry/api | | @dunx/core/otel | OtelModule and OtelTracer, on the optional peer @opentelemetry/api |

bun add @opentelemetry/api   # only for @dunx/core/otel, ^1.4.0

@opentelemetry/api is a peer dependency so that your SDK and dunx use the same copy. With two copies installed, spans can go missing without an error. dunx does not include an SDK or an exporter: register your own before calling create.

Notes

• Each module is its own scope. A module can use what it declares and what the modules it imports export. List what other modules may use in exports; leave exports out and nothing is shared. global: true makes a module's exports available everywhere.

• If a constructor parameter's type does not exist at runtime (an interface, a primitive, a union or a type-only import), boot fails with an error naming that parameter. You never get a silent undefined. A parameter with a default value keeps its default.

• Logger, RequestContext and Tracer can always be injected. The defaults are ConsoleLogger, AsyncRequestContext (on AsyncLocalStorage) and NoopTracer, and a module that binds one replaces the default. @dunx/http relies on this to log requests in an app with no logging module.

• ConsoleLogger collects info and lower into one write per event-loop turn. warn and higher are written at once, along with anything waiting before them.

• The stats classes use only node:perf_hooks and process, so the package still has no dependencies.

• Durations fixes four problems with Node's native histogram:

  | Native histogram | Durations | | ----------------------------------------------------------------- | --------------------------------- | | record(0) throws ERR_OUT_OF_RANGE | A value under 1 is recorded as 1 | | An empty histogram reports min 9223372036854776000, mean NaN | An empty snapshot is { count: 0 } | | percentiles is a Map of bigint, which serialises to {} | percentile(n) returns a number | | mean costs 42.2 us | No mean |

License

MIT