honovajs 0.0.1 → 0.1.0

package/README.md

@@ -6,9 +6,10 @@ Honova provides a module system, decorators, dependency injection, route metadat
 
 ## Status
 
-- Package version: `0.0.1`
+- Package version: `0.1.0`
 - Runtime target: Cloudflare Workers (also works anywhere Hono runs)
 - Module format: ESM
+- `hono` is a peer dependency: `>=4.13.0 <5`
 
 ## Feature Checklist
 
@@ -27,6 +28,28 @@ Honova provides a module system, decorators, dependency injection, route metadat
 - [x] Controller-level and route-level middleware via `@UseMiddleware`
 - [x] Built-in `not_found` and `internal_error` JSON responses
 
+### Request Pipeline (0.1.0)
+
+- [x] `HttpException` hierarchy + `ValidationException`
+- [x] Exception filters: `@Catch()`, `@UseFilters()`, global filters
+- [x] Guards: `CanActivate`, `@UseGuards()`, global guards
+- [x] Interceptors without RxJS (async onion), `@UseInterceptors()`, global interceptors
+- [x] `ExecutionContext` (class/handler/Hono context/env/`waitUntil`)
+- [x] Metadata API: `createDecorator<T>()` + `Reflector`
+- [x] Validation via Standard Schema v1 (`@Validate`, `getInput`) — zod/valibot/arktype, zero deps
+- [x] Response serialization (plain values → JSON/text/204) + `@HttpCode` / `@Header`
+- [x] Custom providers (`useValue`/`useFactory`/`useClass`/`useExisting`), async factories
+- [x] Async `onModuleInit` (awaited by the request pipeline, single-flight per isolate)
+- [x] Scope bubbling (request scope propagates to consumers, as in Nest)
+- [x] Stage-3 DI: `@Inject` on fields/accessors + `static inject = [...]`
+- [x] Env config validation (`config: { schema }` → `CONFIG` token)
+- [x] JWT guard (`createJwtGuard`) + `@Roles` / `RolesGuard`
+- [x] `@Cron` → Cloudflare Cron Triggers dispatcher (`createScheduledDispatcher`)
+- [x] Standalone context (`createApplicationContext`) for `scheduled()`/`queue()`
+- [x] Testing module (`createTestingModule`, `overrideProvider`, `flushWaitUntil`)
+- [x] HTTP `QUERY` verb (`@HttpQuery`) and `methodNotAllowed` option
+- [x] `@Public()` / `isPublicHandler()` — opt a route out of a global guard
+
 ### Security and Observability
 
 - [x] CORS integration (`hono/cors`)
@@ -64,14 +87,14 @@ Honova provides a module system, decorators, dependency injection, route metadat
 ### Planned / Missing Features
 
 - [x] Request-scoped and transient instance caching semantics validated by tests
-- [ ] Async `onModuleInit` support in runtime
-- [ ] Validation pipes and DTO validation layer
-- [ ] Guard/interceptor abstraction (Nest-style)
-- [ ] Exception filter abstraction
+- [x] Async `onModuleInit` support in runtime
+- [x] Validation pipes and DTO validation layer
+- [x] Guard/interceptor abstraction (Nest-style)
+- [x] Exception filter abstraction
 - [ ] First-class OpenAPI/Swagger generation
 - [ ] CLI scaffolding (`create-honova-app`, generators)
 - [ ] Official Cloudflare starter templates (D1, KV, R2 examples)
-- [ ] More auth primitives (JWT helper, role/permission guard, session middleware)
+- [x] More auth primitives (JWT helper, role/permission guard, session middleware)
 - [ ] E2E test suite with Worker runtime integration
 - [ ] Benchmark/performance suite and guidance
 - [ ] Complete API docs website
@@ -180,7 +203,9 @@ Current runtime behavior:
 - It runs when the provider is resolved for the first time.
 - For singleton providers, it runs once per app instance.
 - Request context is passed when the provider is resolved during a request.
-- It must be synchronous in `0.0.1`.
+- It may be async: the request pipeline awaits it (single-flight per isolate).
+  Synchronous resolution paths (`container.resolve`, `inject()`) still require
+  sync inits and throw otherwise.
 
 ## Middleware
 
@@ -252,6 +277,52 @@ class MeController {
 }
 ```
 
+### Opting a route out of a global guard
+
+An application that puts authentication in a global guard has made it the
+default, which is the point: a new route cannot ship unprotected because
+somebody forgot a decorator. The few routes that must stay open then need a way
+to say so.
+
+`@Public()` marks the handler. It does **not** make the router skip guards,
+because only a guard knows whether "public" applies to it: a session guard
+should stand down on a login form, and a CSRF guard should not. Each guard opts
+in by asking.
+
+```ts
+import { Controller, Get, Public, createApp, isPublicHandler } from "honovajs";
+import type { CanActivate, ExecutionContext } from "honovajs";
+
+const session: CanActivate = {
+  canActivate(ctx: ExecutionContext) {
+    if (isPublicHandler(ctx.getHandler())) return true;
+
+    return Boolean(ctx.getContext().req.header("cookie"));
+  },
+};
+
+createApp({ guards: [session] });
+
+@Controller("/")
+class Routes {
+  @Get("/me")
+  me() {
+    return { id: "u_1" };
+  }
+
+  @Get("/health")
+  @Public()
+  health() {
+    return { ok: true };
+  }
+}
+```
+
+The mark is keyed on the handler function, not on a route path, so a handler
+cannot be moved, renamed or copied into another controller and quietly lose, or
+quietly keep, its exemption. It works written above or below the HTTP method
+decorator.
+
 ### API Key
 
 ```ts
@@ -364,3 +435,84 @@ npm run build
 ## License
 
 MIT
+
+## The 0.1.0 Pipeline in One Example
+
+```ts
+import {
+  Controller, Get, Post, Module, Injectable, Inject, createApp,
+  UseGuards, UseInterceptors, Validate, getInput, HttpCode,
+  createJwtGuard, Roles, RolesGuard, NotFoundException,
+  type CanActivate, type HonovaInterceptor, type ExecutionContext,
+  CONFIG, createScheduledDispatcher, Cron,
+} from "honovajs";
+
+// Any Standard Schema library works; zod >= 3.24 shown here.
+import { z } from "zod";
+
+const CreateLink = z.object({ url: z.string().url(), code: z.string().min(3) });
+
+class TimingInterceptor implements HonovaInterceptor {
+  async intercept(ctx: ExecutionContext, next: () => Promise<unknown>) {
+    const start = Date.now();
+    const result = await next();               // handler return value, not a Response
+    console.log(`${ctx.getContext().req.path} took ${Date.now() - start}ms`);
+    return result;                             // may reshape: { data: result }
+  }
+}
+
+@Injectable()
+class LinkService {
+  async find(code: string) {
+    if (code === "missing") throw new NotFoundException("Unknown link");
+    return { code, url: "https://example.com" };
+  }
+
+  @Cron("*/20 * * * *")                        // matches wrangler triggers.crons
+  async expireOutdated() { /* ... */ }
+}
+
+@Controller("/links")
+@UseGuards(createJwtGuard({ secretFromEnv: "JWT_SIGNING_KEY" }), RolesGuard)
+@UseInterceptors(TimingInterceptor)
+class LinkController {
+  constructor(private readonly linkService: LinkService) {}
+
+  @Get("/:code")
+  get(c: any) {
+    return this.linkService.find(c.req.param("code")); // plain object → JSON
+  }
+
+  @Post("/")
+  @Roles(["admin"])
+  @HttpCode(201)
+  @Validate({ body: CreateLink })
+  create(c: any) {
+    const { body } = getInput<{ body: z.infer<typeof CreateLink> }>(c);
+    return body;                                       // 201 JSON
+  }
+}
+
+@Module({ controllers: [LinkController], providers: [LinkService] })
+class AppModule {}
+
+const app = createApp({ security: { cors: true } });
+app.registerModule(AppModule);
+
+export default {
+  fetch: app.fetch,
+  scheduled: createScheduledDispatcher(app),
+};
+```
+
+## Testing
+
+```ts
+import { createTestingModule } from "honovajs";
+
+const testApp = createTestingModule({ controllers: [LinkController], providers: [LinkService] })
+  .overrideProvider(LinkService).useValue({ find: async () => ({ code: "x", url: "y" }) })
+  .compile();
+
+const res = await testApp.request("/links/x", {}, { JWT_SIGNING_KEY: "test" });
+```

package/dist/adapters/db/drizzle.d.ts

@@ -1,4 +1,4 @@
-import type { DatabaseAdapter } from "../../database/manager";
+import type { DatabaseAdapter } from "../../database/manager.js";
 export interface DrizzleAdapterOptions<TClient> {
     connect: (url: string) => Promise<TClient> | TClient;
     disconnect?: (client: TClient) => Promise<void> | void;

package/dist/adapters/db/drizzle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"drizzle.d.ts","sourceRoot":"","sources":["../../../src/adapters/db/drizzle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAE9D,MAAM,WAAW,qBAAqB,CAAC,OAAO;IAC5C,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IACrD,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CACxD;AAED,wBAAgB,oBAAoB,CAClC,GAAG,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnC,OAAO,EAEP,OAAO,EAAE,qBAAqB,CAAC,OAAO,CAAC,GACtC,eAAe,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,CAAC,CAMxC"}
+{"version":3,"file":"drizzle.d.ts","sourceRoot":"","sources":["../../../src/adapters/db/drizzle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAEjE,MAAM,WAAW,qBAAqB,CAAC,OAAO;IAC5C,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IACrD,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CACxD;AAED,wBAAgB,oBAAoB,CAClC,GAAG,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnC,OAAO,EAEP,OAAO,EAAE,qBAAqB,CAAC,OAAO,CAAC,GACtC,eAAe,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,CAAC,CAMxC"}

package/dist/adapters/db/index.d.ts

@@ -1,5 +1,5 @@
-export * from "./drizzle";
-export * from "./mongodb";
-export * from "./mondel";
-export * from "./prisma";
+export * from "./drizzle.js";
+export * from "./mongodb.js";
+export * from "./mondel.js";
+export * from "./prisma.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/adapters/db/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/adapters/db/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/adapters/db/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC"}

package/dist/adapters/db/index.js

@@ -1,5 +1,5 @@
-export * from "./drizzle";
-export * from "./mongodb";
-export * from "./mondel";
-export * from "./prisma";
+export * from "./drizzle.js";
+export * from "./mongodb.js";
+export * from "./mondel.js";
+export * from "./prisma.js";
 //# sourceMappingURL=index.js.map

package/dist/adapters/db/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/adapters/db/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/adapters/db/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC"}

package/dist/adapters/db/mondel.d.ts

@@ -1,2 +1,2 @@
-export { type MongoDbAdapterOptions as MondelAdapterOptions, createMongoDbAdapter as createMondelAdapter, } from "./mongodb";
+export { type MongoDbAdapterOptions as MondelAdapterOptions, createMongoDbAdapter as createMondelAdapter, } from "./mongodb.js";
 //# sourceMappingURL=mondel.d.ts.map

package/dist/adapters/db/mondel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mondel.d.ts","sourceRoot":"","sources":["../../../src/adapters/db/mondel.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,qBAAqB,IAAI,oBAAoB,EAClD,oBAAoB,IAAI,mBAAmB,GAC5C,MAAM,WAAW,CAAC"}
+{"version":3,"file":"mondel.d.ts","sourceRoot":"","sources":["../../../src/adapters/db/mondel.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,qBAAqB,IAAI,oBAAoB,EAClD,oBAAoB,IAAI,mBAAmB,GAC5C,MAAM,cAAc,CAAC"}

package/dist/adapters/db/mondel.js

@@ -1,2 +1,2 @@
-export { createMongoDbAdapter as createMondelAdapter, } from "./mongodb";
+export { createMongoDbAdapter as createMondelAdapter, } from "./mongodb.js";
 //# sourceMappingURL=mondel.js.map

package/dist/adapters/db/mondel.js.map

@@ -1 +1 @@
-{"version":3,"file":"mondel.js","sourceRoot":"","sources":["../../../src/adapters/db/mondel.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,oBAAoB,IAAI,mBAAmB,GAC5C,MAAM,WAAW,CAAC"}
+{"version":3,"file":"mondel.js","sourceRoot":"","sources":["../../../src/adapters/db/mondel.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,oBAAoB,IAAI,mBAAmB,GAC5C,MAAM,cAAc,CAAC"}

package/dist/adapters/db/mongodb.d.ts

@@ -1,4 +1,4 @@
-import type { DatabaseAdapter } from "../../database/manager";
+import type { DatabaseAdapter } from "../../database/manager.js";
 export interface MongoDbAdapterOptions<TClient, TConnectOptions> {
     connect: (url: string, options: TConnectOptions) => Promise<TClient> | TClient;
     disconnect?: (client: TClient) => Promise<void> | void;

package/dist/adapters/db/mongodb.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mongodb.d.ts","sourceRoot":"","sources":["../../../src/adapters/db/mongodb.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAE9D,MAAM,WAAW,qBAAqB,CAAC,OAAO,EAAE,eAAe;IAC7D,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IAC/E,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CACxD;AAED,wBAAgB,oBAAoB,CAClC,GAAG,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnC,OAAO,EACP,eAAe,EAEf,cAAc,EAAE,qBAAqB,CAAC,OAAO,EAAE,eAAe,CAAC,GAC9D,eAAe,CAAC,GAAG,EAAE,OAAO,EAAE,eAAe,CAAC,CAMhD"}
+{"version":3,"file":"mongodb.d.ts","sourceRoot":"","sources":["../../../src/adapters/db/mongodb.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAEjE,MAAM,WAAW,qBAAqB,CAAC,OAAO,EAAE,eAAe;IAC7D,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IAC/E,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CACxD;AAED,wBAAgB,oBAAoB,CAClC,GAAG,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnC,OAAO,EACP,eAAe,EAEf,cAAc,EAAE,qBAAqB,CAAC,OAAO,EAAE,eAAe,CAAC,GAC9D,eAAe,CAAC,GAAG,EAAE,OAAO,EAAE,eAAe,CAAC,CAMhD"}

package/dist/adapters/db/prisma.d.ts

@@ -1,4 +1,4 @@
-import type { DatabaseAdapter } from "../../database/manager";
+import type { DatabaseAdapter } from "../../database/manager.js";
 export interface PrismaAdapterOptions<TClient> {
     connect: (url: string) => Promise<TClient> | TClient;
     disconnect?: (client: TClient) => Promise<void> | void;

package/dist/adapters/db/prisma.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prisma.d.ts","sourceRoot":"","sources":["../../../src/adapters/db/prisma.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAE9D,MAAM,WAAW,oBAAoB,CAAC,OAAO;IAC3C,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IACrD,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CACxD;AAED,wBAAgB,mBAAmB,CACjC,GAAG,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnC,OAAO,SAAS;IAAE,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;CAAE,EAE5D,OAAO,EAAE,oBAAoB,CAAC,OAAO,CAAC,GACrC,eAAe,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,CAAC,CAexC"}
+{"version":3,"file":"prisma.d.ts","sourceRoot":"","sources":["../../../src/adapters/db/prisma.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAEjE,MAAM,WAAW,oBAAoB,CAAC,OAAO;IAC3C,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IACrD,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CACxD;AAED,wBAAgB,mBAAmB,CACjC,GAAG,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnC,OAAO,SAAS;IAAE,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;CAAE,EAE5D,OAAO,EAAE,oBAAoB,CAAC,OAAO,CAAC,GACrC,eAAe,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,CAAC,CAexC"}

package/dist/core/application.d.ts

@@ -1,11 +1,19 @@
 import { Hono, type MiddlewareHandler } from "hono";
 import { cors } from "hono/cors";
 import { secureHeaders } from "hono/secure-headers";
-import { Container } from "./container/container";
-import { type DbManagerMiddlewareOptions } from "../database/middleware";
-import type { Constructor } from "./types";
+import { Container } from "./container/container.js";
+import { type DbManagerMiddlewareOptions } from "../database/middleware.js";
+import type { Constructor, Token } from "./types.js";
+import type { GuardRef } from "./pipeline/guards.js";
+import type { InterceptorRef } from "./pipeline/interceptors.js";
+import type { FilterRef } from "./pipeline/filters-binding.js";
+import { type StandardSchemaV1 } from "./validation/standard-schema.js";
 export interface SecurityOptions {
-    cors?: Parameters<typeof cors>[0];
+    /**
+     * CORS is opt-in: pass `true` for hono's defaults or a config object.
+     * (Earlier versions applied permissive CORS unconditionally.)
+     */
+    cors?: boolean | Parameters<typeof cors>[0];
     secureHeaders?: boolean | Parameters<typeof secureHeaders>[0];
 }
 export interface ObservabilityOptions {
@@ -14,6 +22,14 @@ export interface ObservabilityOptions {
     logLevel?: "debug" | "info" | "warn" | "error";
     redactHeaders?: string[];
 }
+export interface ConfigOptions {
+    /** Standard Schema validated against the env bindings, once per isolate. */
+    schema: StandardSchemaV1;
+    /** DI token the validated config is provided under. Default: CONFIG. */
+    token?: Token;
+}
+/** Default DI token for the validated environment config. */
+export declare const CONFIG: unique symbol;
 export interface ApplicationOptions<Env extends Record<string, unknown>> {
     basePath?: string;
     globalMiddlewares?: MiddlewareHandler[];
@@ -22,8 +38,38 @@ export interface ApplicationOptions<Env extends Record<string, unknown>> {
     observability?: ObservabilityOptions;
     di?: {
         strict?: boolean;
+        /**
+         * Resolve a constructor dependency from the parameter NAME when no other
+         * token is available.
+         *
+         * On by default for compatibility, and it warns whenever it actually
+         * resolves something — it reads identifiers out of
+         * `Function.prototype.toString()`, so a minifier silently breaks it, and it
+         * masks a genuinely missing token by appearing to work in development.
+         *
+         * Set it to `false` in any application that is minified or bundled, which
+         * turns that silent degradation into a boot-time error. Prefer
+         * `design:paramtypes` (`emitDecoratorMetadata`) or an explicit `@Inject`.
+         */
+        inferByParamName?: boolean;
     };
+    /** Global guards, first in the guard chain. Classes are DI-resolved. */
+    guards?: GuardRef[];
+    /** Global interceptors, outermost in the onion. */
+    interceptors?: InterceptorRef[];
+    /** Global exception filters, last before the default mapping. */
+    filters?: FilterRef[];
+    /** Env-bindings validation + typed CONFIG provider. */
+    config?: ConfigOptions;
+    /** Respond 405 + Allow instead of 404 for known paths (hono middleware). */
+    methodNotAllowed?: boolean;
 }
+/** Context key holding the id assigned to the current request. */
+export declare const REQUEST_ID_CONTEXT_KEY = "requestId";
+/** Reads the current request id, wherever in the pipeline you are. */
+export declare function getRequestId(c: {
+    get(key: never): unknown;
+}): string | undefined;
 export declare class Application<Env extends Record<string, unknown> = Record<string, unknown>> {
     private app;
     private readonly container;
@@ -32,13 +78,31 @@ export declare class Application<Env extends Record<string, unknown> = Record<st
     private readonly registeredControllers;
     private readonly registeredModules;
     private readonly moduleResolutionStack;
+    private configValidation;
+    private configOptions;
     constructor(options?: ApplicationOptions<Env>);
+    /**
+     * Validates env bindings once per isolate (single-flight across concurrent
+     * first requests) and provides the parsed value under the config token.
+     * Env bindings only exist at request time on Workers, so this cannot run at
+     * construction.
+     */
+    private registerConfig;
+    /**
+     * Validates env bindings once per isolate and registers the CONFIG
+     * provider. Public because non-fetch handlers (scheduled(), queue()) enter
+     * outside the HTTP middleware chain and must be able to prepare config too.
+     */
+    ensureConfig(env: unknown): Promise<void>;
     registerModule(moduleClass: Constructor): this;
+    private registerProviderDefinition;
     use(middleware: MiddlewareHandler): this;
     getContainer(): Container;
     getHono(): Hono<{
         Bindings: Env;
     }>;
+    /** Class providers registered so far — used by the scheduling dispatcher. */
+    getRegisteredProviders(): Constructor[];
     fetch: (request: Request, env: Env, ctx: any) => Response | Promise<Response>;
 }
 export declare function createApp<Env extends Record<string, unknown> = Record<string, unknown>>(options?: ApplicationOptions<Env>): Application<Env>;

package/dist/core/application.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"application.d.ts","sourceRoot":"","sources":["../../src/core/application.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,KAAK,iBAAiB,EAAE,MAAM,MAAM,CAAC;AACpD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAClD,OAAO,EAA6B,KAAK,0BAA0B,EAAE,MAAM,wBAAwB,CAAC;AAEpG,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAG3C,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,UAAU,CAAC,OAAO,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IAClC,aAAa,CAAC,EAAE,OAAO,GAAG,UAAU,CAAC,OAAO,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;CAC/D;AAED,MAAM,WAAW,oBAAoB;IACnC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;IAC/C,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,kBAAkB,CAAC,GAAG,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iBAAiB,CAAC,EAAE,iBAAiB,EAAE,CAAC;IACxC,QAAQ,CAAC,EAAE,0BAA0B,CAAC,GAAG,CAAC,CAAC;IAC3C,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B,aAAa,CAAC,EAAE,oBAAoB,CAAC;IACrC,EAAE,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;CAC3B;AA6CD,qBAAa,WAAW,CAAC,GAAG,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACpF,OAAO,CAAC,GAAG,CAA0B;IACrC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IACrC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAA0B;IAC9D,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAA0B;IAChE,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA0B;IAC5D,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAqB;gBAE/C,OAAO,GAAE,kBAAkB,CAAC,GAAG,CAAM;IA0CjD,cAAc,CAAC,WAAW,EAAE,WAAW,GAAG,IAAI;IA2D9C,GAAG,CAAC,UAAU,EAAE,iBAAiB,GAAG,IAAI;IAKxC,YAAY,IAAI,SAAS;IAIzB,OAAO,IAAI,IAAI,CAAC;QAAE,QAAQ,EAAE,GAAG,CAAA;KAAE,CAAC;IAIlC,KAAK,GAAI,SAAS,OAAO,EAAE,KAAK,GAAG,EAAE,KAAK,GAAG,KAAG,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAE1E;CACH;AAED,wBAAgB,SAAS,CAAC,GAAG,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACrF,OAAO,GAAE,kBAAkB,CAAC,GAAG,CAAM,GACpC,WAAW,CAAC,GAAG,CAAC,CAElB"}
+{"version":3,"file":"application.d.ts","sourceRoot":"","sources":["../../src/core/application.ts"],"names":[],"mappings":"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"}

package/dist/core/application.js

@@ -1,21 +1,43 @@
 import { Hono } from "hono";
 import { cors } from "hono/cors";
 import { secureHeaders } from "hono/secure-headers";
-import { Container } from "./container/container";
-import { createDbManagerMiddleware } from "../database/middleware";
-import { Router } from "./router/router";
-import { getInjectableMetadata, getModuleMetadata } from "./metadata";
+import { methodNotAllowed } from "hono/method-not-allowed";
+import { Container } from "./container/container.js";
+import { createDbManagerMiddleware } from "../database/middleware.js";
+import { Router } from "./router/router.js";
+import { getInjectableMetadata, getModuleMetadata } from "./metadata.js";
+import { isStandardSchema } from "./validation/standard-schema.js";
+/** Default DI token for the validated environment config. */
+export const CONFIG = Symbol("honova:config");
 const defaultRedactHeaders = ["authorization", "cookie", "set-cookie", "x-api-key"];
+/** Context key holding the id assigned to the current request. */
+export const REQUEST_ID_CONTEXT_KEY = "requestId";
+/** Reads the current request id, wherever in the pipeline you are. */
+export function getRequestId(c) {
+    return c.get(REQUEST_ID_CONTEXT_KEY);
+}
 function createObservabilityMiddleware(options) {
     const requestIdHeader = options?.requestIdHeader ?? "x-request-id";
     const accessLogs = options?.enableAccessLogs ?? true;
     const level = options?.logLevel ?? "info";
-    const redactHeaders = options?.redactHeaders ?? defaultRedactHeaders;
+    // Custom entries extend the defaults rather than replace them — replacing
+    // silently re-enabled Authorization/Cookie logging at debug level.
+    const redactHeaders = [...defaultRedactHeaders, ...(options?.redactHeaders ?? [])];
+    // Client-supplied ids are convenient for tracing but must not become a
+    // header/log injection vector: accept a conservative charset or mint one.
+    const safeIdPattern = /^[A-Za-z0-9._-]{1,128}$/;
     return async (c, next) => {
-        const requestId = c.req.header(requestIdHeader) ?? crypto.randomUUID();
+        const incoming = c.req.header(requestIdHeader);
+        const requestId = incoming && safeIdPattern.test(incoming) ? incoming : crypto.randomUUID();
         const start = Date.now();
+        // Published on the context before the request runs, not just on the way
+        // out: exception filters and handlers build response bodies mid-request and
+        // need the same id that ends up in the header and the access log.
+        c.set(REQUEST_ID_CONTEXT_KEY, requestId);
         await next();
-        c.res.headers.set(requestIdHeader, requestId);
+        // c.header() instead of c.res.headers.set(): a handler that returns a
+        // proxied fetch() Response has immutable headers, which .set() throws on.
+        c.header(requestIdHeader, requestId);
         if (!accessLogs) {
             return;
         }
@@ -51,30 +73,90 @@ export class Application {
         };
         this.app = new Hono({ strict: false });
         this.container = new Container();
-        this.container.configure({ strict: options.di?.strict ?? true });
+        this.container.configure({
+            strict: options.di?.strict ?? true,
+            inferByParamName: options.di?.inferByParamName ?? true,
+        });
+        Container.setActive(this.container);
         if (options.basePath) {
             this.app = this.app.basePath(options.basePath);
         }
         this.app.use("*", createObservabilityMiddleware(options.observability));
-        this.app.use("*", cors(options.security?.cors));
+        if (options.security?.cors) {
+            const settings = typeof options.security.cors === "boolean" ? undefined : options.security.cors;
+            this.app.use("*", cors(settings));
+        }
         if (options.security?.secureHeaders) {
             const settings = typeof options.security.secureHeaders === "boolean"
                 ? undefined
                 : options.security.secureHeaders;
             this.app.use("*", secureHeaders(settings));
         }
+        if (options.config) {
+            this.registerConfig(options.config);
+        }
         if (options.database) {
             this.app.use("*", createDbManagerMiddleware(options.database));
         }
         for (const middleware of options.globalMiddlewares ?? []) {
             this.app.use("*", middleware);
         }
+        if (options.methodNotAllowed) {
+            this.app.use("*", methodNotAllowed({ app: this.app }));
+        }
         this.app.notFound((c) => c.json({ error: { code: "not_found", message: "Route not found" } }, 404));
         this.app.onError((err, c) => {
             console.error(err);
             return c.json({ error: { code: "internal_error", message: "Internal server error" } }, 500);
         });
-        this.router = new Router(this.app, this.container);
+        const globals = {
+            guards: options.guards ?? [],
+            interceptors: options.interceptors ?? [],
+            filters: options.filters ?? [],
+        };
+        this.router = new Router(this.app, this.container, globals);
+    }
+    /**
+     * Validates env bindings once per isolate (single-flight across concurrent
+     * first requests) and provides the parsed value under the config token.
+     * Env bindings only exist at request time on Workers, so this cannot run at
+     * construction.
+     */
+    registerConfig(config) {
+        if (!isStandardSchema(config.schema)) {
+            throw new Error("config.schema must implement Standard Schema v1 (zod >= 3.24, valibot, arktype).");
+        }
+        this.configOptions = config;
+        this.app.use("*", async (c, next) => {
+            await this.ensureConfig(c.env);
+            await next();
+        });
+    }
+    /**
+     * Validates env bindings once per isolate and registers the CONFIG
+     * provider. Public because non-fetch handlers (scheduled(), queue()) enter
+     * outside the HTTP middleware chain and must be able to prepare config too.
+     */
+    async ensureConfig(env) {
+        const config = this.configOptions;
+        if (!config) {
+            return;
+        }
+        if (!this.configValidation) {
+            const token = config.token ?? CONFIG;
+            this.configValidation = Promise.resolve(config.schema["~standard"].validate(env)).then((result) => {
+                if (result.issues) {
+                    const detail = result.issues.map((issue) => issue.message).join("; ");
+                    throw new Error(`Environment validation failed: ${detail}`);
+                }
+                this.container.registerProvider({ provide: token, useValue: result.value });
+            });
+            // Allow retry on the next request if validation itself failed.
+            this.configValidation.catch(() => {
+                this.configValidation = undefined;
+            });
+        }
+        await this.configValidation;
     }
     registerModule(moduleClass) {
         if (this.registeredModules.has(moduleClass)) {
@@ -97,14 +179,7 @@ export class Application {
                 this.registerModule(imported);
             }
             for (const provider of metadata.providers ?? []) {
-                const injectableMetadata = getInjectableMetadata(provider);
-                if (!injectableMetadata) {
-                    throw new Error(`Provider ${provider.name} in ${moduleClass.name} must be decorated with @Injectable().`);
-                }
-                if (!this.registeredProviders.has(provider)) {
-                    this.container.register(provider);
-                    this.registeredProviders.add(provider);
-                }
+                this.registerProviderDefinition(provider, moduleClass);
             }
             for (const controller of metadata.controllers ?? []) {
                 if (this.registeredControllers.has(controller)) {
@@ -121,6 +196,25 @@ export class Application {
             this.moduleResolutionStack.pop();
         }
     }
+    registerProviderDefinition(provider, moduleClass) {
+        if (typeof provider === "function") {
+            const injectableMetadata = getInjectableMetadata(provider);
+            if (!injectableMetadata) {
+                throw new Error(`Provider ${provider.name} in ${moduleClass.name} must be decorated with @Injectable().`);
+            }
+            if (!this.registeredProviders.has(provider)) {
+                this.container.register(provider);
+                this.registeredProviders.add(provider);
+            }
+            return;
+        }
+        // Custom providers (useValue/useFactory/useClass/useExisting) need no
+        // @Injectable — the definition itself is the registration.
+        this.container.registerProvider(provider);
+        if ("useClass" in provider) {
+            this.registeredProviders.add(provider.useClass);
+        }
+    }
     use(middleware) {
         this.app.use("*", middleware);
         return this;
@@ -131,6 +225,10 @@ export class Application {
     getHono() {
         return this.app;
     }
+    /** Class providers registered so far — used by the scheduling dispatcher. */
+    getRegisteredProviders() {
+        return [...this.registeredProviders];
+    }
 }
 export function createApp(options = {}) {
     return new Application(options);