dart_server 1.0.3

A NestJS-style backend framework for Dart with modules, dependency injection, guards and an Express-like core. Zero external dependencies.

Changelog

1.0.3

API documentation (OpenAPI)

• app.useOpenApi() — serves an interactive documentation UI at /docs and the generated OpenAPI 3.0 specification at /docs/openapi.json, built automatically from the route table (methods, paths, path parameters).
• ApiDoc — optional doc: argument on every route registration (controller and Express-style) for summaries, descriptions, tags, parameter/body/response docs, security references, deprecated and hidden.
• ApiSchema — a minimal JSON-Schema builder (object/string/ integer/number/boolean/array/raw) for payload shapes, plus ApiParam, ApiBody and ApiResponse.
• OpenApiGenerator is exported for offline spec generation (e.g. CI).
• ApiSecurityScheme (apiKey/bearer/basic/raw) — declare authentication on useOpenApi(securitySchemes: ...) and reference it with ApiDoc(security: [...]); the docs UI shows an Authorize button and sends the credential with try-it-out requests.
• The scaffold (dart_server create) wires useOpenApi and documents its routes out of the box.

Logging & startup

• The startup banner now prints the API docs and dev-dashboard URLs (linking via localhost when bound to all interfaces).
• logger() no longer logs the dev dashboard's own polling traffic (marked with the new internalRequestMarker context key); opt back in with logInternal: true. New ignorePaths: option silences other noisy endpoints (e.g. /health) by path prefix.

1.0.2

NestJS-parity release: the full request pipeline, lifecycle and configuration — still zero dependencies, no reflection, no code generation.

Request pipeline

• Guards (Guard, the CanActivate equivalent): attach globally (DartServerFactory.create(root, guards: [...])), per controller (List<Guard> get guards) or per route (routes.get('/', h, guards: [...])). false → 403; throw an HttpError for other statuses. Guard.from((req) => ...) for inline guards.
• Interceptors: wrap handler execution after guards pass (Nest's lifecycle order) — same (req, next) shape as middleware; attach globally, per controller or per route.
• Scoped middleware: controller- and route-level middleware, running before guards (Express-style position, like Nest middleware).
• Exception filters (ExceptionFilter): convert errors into responses, tried most-specific-first (route → controller → global); return null to decline. Unhandled errors fall through to onError / HttpError mapping.

Lifecycle & configuration

• OnShutdown — awaited in reverse creation order when the app closes; pairs with the existing OnInit.
• Graceful shutdown — app.close() now drains in-flight requests before running hooks, is safe under concurrent calls (one shared teardown future), and a failing hook never blocks the rest.
• app.enableShutdownHooks() — run shutdown hooks on SIGINT/SIGTERM (Ctrl-C, container stop), Nest-style. A second signal force-closes connections and stops intercepting, so a stuck shutdown can always be escaped. app.addShutdownHook() registers your own hooks.
• Env — zero-dep .env + Platform.environment configuration (Env.load(), env['KEY'], require, getInt, getBool); the real environment wins over file values.

Ergonomics

• Typed request helpers (the ParseIntPipe equivalents): req.paramInt(), req.param(), req.queryInt(), req.queryBool(), and req.jsonMap() — validation failures become 400s instead of 500s.
• HttpError.tooManyRequests (429) and HttpError.serviceUnavailable (503).
• OnInit/OnShutdown/Guard/ExceptionFilter are interface classes — implement, don't extend.

CLI

• create now scaffolds the full Nest-style starter: app_module + app_controller + app_service (with DI), .env.example, a unit test and an end-to-end test, and enableShutdownHooks() wired in bin/server.dart.
• New generators: make:guard, make:interceptor, make:filter.

1.0.1

• Render the dev-dashboard URL as code instead of an http:// link so the README passes pub.dev's secure-links check.
• Point repository / issue_tracker at the canonical GitHub repository.

1.0.0

Initial release.

Modular architecture (NestJS-style, optional)

• Module — groups providers and controllers, with imports/exports and per-module provider encapsulation (plus isGlobal).
• Provider — dependency injection with singleton, transient and value scopes, resolved via Injector.get<T>(); missing providers and circular dependencies fail fast with DiError.
• Controller — class-based route grouping under a basePath via RouteRegistrar, with constructor injection.
• OnInit — async lifecycle hook awaited during bootstrap in dependency order.
• DartServerFactory.create(rootModule) — wires the graph and mounts every controller's routes; returns an ordinary DartServer.
• No decorators, reflection or codegen — wiring is plain, analyzable Dart.
• CLI: dart_server create scaffolds a modular app; make:resource / make:module / make:controller / make:service / make:repository / make:model generate feature modules under lib/modules/<name>/.

Routing & requests

• Express-style DartServer with get/post/put/delete/patch/head/options/all.
• Path parameters (/users/:id) and a trailing wildcard (/files/*); a * in any non-final segment is rejected at registration.
• Automatic HEAD → GET fallback with the response body stripped.
• Request with path, method, headers, query, params, bodyBytes, body, context, and a lazy, cached json().
• Raw bodyBytes always preserved (binary-safe); body decodes UTF-8 with malformed bytes replaced rather than thrown; json() re-throws on every call for invalid JSON instead of caching null.
• Configurable maxBodyBytes (default 1 MiB) — oversized bodies are rejected with 413 before any handler runs.
• Malformed percent-encoding in a path segment falls back to the raw value instead of producing a 500.

Responses

• Response.json, text, html, status, bytes, redirect, fluent .header().
• HEAD responses send the Content-Length but no body; 204/304/1xx responses send neither a body nor a Content-Length.

Middleware & errors

• Global middleware with next() chaining and per-request context.
• Handler errors are converted to responses inside the chain, so middleware (and logger/cors) observe error responses too.
• HttpError with status-mapped constructors; customizable onError.

CLI (dart_server)

• dart_server create <name> — scaffolds a ready-to-run app (entry point, app wiring, routes, controllers/models/repositories layout) and runs pub get.
• dart_server dev — runs with DART_SERVER_ENV=development and auto-restarts on .dart changes under lib//bin/; dart_server prod runs in production.
• dart_server make:model|controller|repository|middleware|service|resource — code generators with name normalization (snake/camel/Pascal) and --force.
• Installable via dart pub global activate dart_server; zero dependencies (hand-rolled argument parsing).

Dev tools

• app.useDevTools() — an in-process development dashboard at /__dev that tracks recent requests (method, path, status, timing, headers, request/ response bodies), aggregate stats, the live route table and server info, with a JSON snapshot at /__dev/api. Self-contained (no external assets).
• Development-only: disabled when DART_SERVER_ENV/DART_ENV/ENV is production-like; configurable mount path, buffer size and body capture.

Bundled middleware

• logger() — logs successful and errored requests.
• cors() — secure by default: credentials: true with a wildcard origin is refused; use the origins allow-list for credentialed cross-origin access. Pre-flights are detected by Access-Control-Request-Method so explicit app.options(...) routes still run.
• serveStatic() — rejects .. and symlink path-traversal (real target re-checked against the root).

Other

• Zero external runtime dependencies (built on dart:io + dart:convert).
• listen(..., quiet: true) suppresses the startup banner.