Package Overview
ModularityJS is organized as a monorepo with packages grouped by role.
Core
| Package | Description |
|---|---|
@modularityjs/di | Abstract DI contract — decorators and container interface |
@modularityjs/di-inversify | InversifyJS implementation of the DI contract |
@modularityjs/di-awilix | Awilix implementation of the DI contract |
@modularityjs/modularity | Module system — loader, lifecycle, pools, validators |
@modularityjs/plugins | Plugin system with before/after/around interception |
@modularityjs/view | Component registry and recursive view validator |
Contracts and Drivers
Each service follows the contract/driver pattern: an abstract contract package and one or more concrete driver packages. See Architecture for details on the two variants (service contracts and module-level contracts).
Service Contracts
Transport-Pool Contracts
| Service | Contract | Drivers | Description |
|---|---|---|---|
| Logger | @modularityjs/logger | logger-console, logger-file | Transport-pool dispatch with channel routing and level filtering |
Module-Level Contracts
| Service | Contract | Driver | Description |
|---|---|---|---|
| HTTP | @modularityjs/http | http-fastify | Pool-based controller discovery with framework-owned decorators |
| CLI | @modularityjs/cli | cli-commander | Pool-based command discovery with Commander.js |
| Database | @modularityjs/database | database-typeorm, database-prisma. Extensions: database-metrics, database-telemetry | Abstract DatabaseConnection, MigrationRunner, MigrationGenerator; driver-specific entity/schema registration |
| Scheduler | @modularityjs/scheduler | scheduler-croner, scheduler-memory (deterministic manual tick) | Cron-based job scheduler with distributed locking |
| Events | @modularityjs/events | events-memory, events-redis | Typed event bus with pool-based listener discovery and per-handler once deduplication |
| WebSocket | @modularityjs/ws | ws-fastify, ws-redis (multi-instance fan-out) | Gateway-based WebSocket routing with @WsGateway and @OnMessage, rooms, presence |
Infrastructure
| Package | Description |
|---|---|
@modularityjs/exception | Structured exception hierarchy with HTTP mapping. Allowed everywhere — no module wiring required. |
@modularityjs/retry | Retry-policy primitive — computeDelay(policy, attempt) with fixed/exponential strategies, optional jitter and cap. Zero deps, no DI, no Module. Used by queue, webhook-direct, future delivery drivers. |
@modularityjs/validation-schema | Schema typing primitive — Schema<T> interface, ValidationResult, and the native-schema side-channel registry (recordNativeSchema / getNativeSchema) used by validation drivers and OpenAPI tooling. Zero deps, no DI, no Module. |
@modularityjs/redis | Shared ioredis client for all Redis drivers |
@modularityjs/config | Scoped configuration with pluggable sources |
@modularityjs/config-env | Environment variable config source |
HTTP Extensions
| Package | Description |
|---|---|
@modularityjs/http-session | Session middleware for HTTP — cookie-based session persistence via HttpServer hooks |
@modularityjs/http-auth | Auth middleware for HTTP — token extraction and identity injection via extractor pool |
@modularityjs/http-auth-jwt | JWT Bearer adapter — registers an HttpAuthenticator that reads Authorization: Bearer and resolves identity via JwtAuthService |
@modularityjs/http-auth-api-key | API key extractor adapter — registers X-API-Key header extractor |
@modularityjs/http-auth-local | Local auth adapter — HTTP Basic authentication |
@modularityjs/http-auth-oidc | OIDC Bearer token adapter |
@modularityjs/http-auth-session | Session-based auth adapter — resolves identity from session data |
@modularityjs/http-authz | Authorization enforcement — @RequirePermission() checked in the HTTP adapter pipeline (before guards) via AuthzService.can() |
@modularityjs/http-upload | Abstract upload contract — HttpUploadConfig (max size, MIME allowlist) + sanitizeFilename; driver-agnostic |
@modularityjs/http-fastify-upload | Fastify driver — registers @fastify/multipart and binds @UploadedFile()/@UploadedFiles() resolvers |
@modularityjs/http-fastify-formbody | Fastify-driver extension — registers @fastify/formbody for application/x-www-form-urlencoded bodies |
@modularityjs/http-storage | Upload-to-storage integration — HttpStorageService with store() and download() |
@modularityjs/http-i18n | Locale extraction middleware |
@modularityjs/http-rate-limit | Rate limiting middleware |
@modularityjs/http-validation | Validation parameter decorators — @ValidatedBody/Query/Params/Headers(schema) returning 422 on failure |
@modularityjs/http-fastify-cors | Fastify-driver extension — registers @fastify/cors with framework-managed config |
@modularityjs/http-fastify-compression | Fastify-driver extension — registers @fastify/compress (br/gzip/deflate) |
@modularityjs/http-fastify-security-headers | Fastify-driver extension — registers @fastify/helmet (CSP, HSTS, X-Frame-Options, …) |
@modularityjs/http-csrf | CSRF protection — session-stored or HMAC double-submit; @CsrfProtect() decorator |
@modularityjs/http-htmx | HTMX decorator — request helpers and partial-response conventions |
@modularityjs/http-mfa | MFA decorator — @RequireMfa() guard backed by MfaService via session attrs |
@modularityjs/http-feature-flags | Feature-flags adapter — @Variant(key) / @Flag(key) parameter decorators |
@modularityjs/http-openapi | Serves /openapi.json plus a /docs UI via the OpenApiUiRenderer contract |
@modularityjs/http-openapi-swagger | Swagger UI driver — binds OpenApiUiRenderer + ships swagger-ui-dist through the assets pipeline |
@modularityjs/http-openapi-redoc | Redoc driver — binds OpenApiUiRenderer + ships redoc.standalone through the assets pipeline |
@modularityjs/http-openapi-rapidoc | RapiDoc driver — binds OpenApiUiRenderer + ships rapidoc-min through the assets pipeline |
@modularityjs/http-openapi-scalar | Scalar API Reference driver — binds OpenApiUiRenderer + ships the standalone bundle through the assets pipeline |
@modularityjs/http-telemetry | OpenTelemetry HTTP spans for requests and routes |
@modularityjs/http-assets | Serves hashed static assets at /static/* from the assets pipeline |
@modularityjs/http-webhook | Webhook endpoint adapter |
@modularityjs/http-health | /health, /health/live, /health/ready endpoints with probe-filtered aggregation |
@modularityjs/http-idempotency | @Idempotent — replay-safe mutating routes over cache + lock |
@modularityjs/http-metrics | Request counter, duration histogram, in-flight gauge off the abstract request lifecycle |
@modularityjs/http-request-id | X-Request-Id propagation + @RequestId() parameter resolver |
@modularityjs/http-request-id-logger | Bridges the ambient request id into every log entry via LogContextProvidersPool |
@modularityjs/http-cache | @CacheResponse — GET responses cached in CacheService with weak ETag / 304s |
@modularityjs/http-pagination | @Page() resolver and the paginate() envelope |
@modularityjs/http-serialization | Outbound response shaping — Resource classes and @SerializeWith |
@modularityjs/http-tenancy | Per-request tenant resolution entering the tenant scope |
Extensions
| Package | Description |
|---|---|
@modularityjs/health | Health indicators with liveness/readiness probe classification. Built-ins: redis-health, database-health, search-elasticsearch-health |
@modularityjs/scope | Scope chain resolver for multi-tenant contexts |
@modularityjs/exception | Structured exception hierarchy |
@modularityjs/auth-oidc-client | OAuth2/OIDC Authorization Code flow helpers (OidcClientService, OidcFlowService with PKCE) |
@modularityjs/auth-local-email-verification | Hashed single-use email-verification tokens with memory / TypeORM / Prisma stores |
@modularityjs/testing | createTestHarness(), createHttpTestClient(), and the cross-driver conformance suites |
@modularityjs/mcp-server | MCP server contract — expose the app's operations as Model Context Protocol tools (McpToolsPool) |
@modularityjs/http-fastify-mcp-server | Fastify driver for mcp-server — streamable-HTTP MCP endpoint at /mcp, optional Bearer apiKey |
@modularityjs/http-dev-console | /dev console — modules, pools, preferences, routes; extensible via DevConsolePanelsPool |
@modularityjs/config-cli | config:print — effective value + winning source per declared path, secrets redacted |
@modularityjs/config-env-cli | config:env:example — generate .env.example from the declared config schema |
@modularityjs/runner | The modularity bin — dev/start/cli, verify, add, doctor, generators |