@forinda/kickjs 6.5.0 → 6.5.1

package/dist/views-Kp8Z3AO1.d.mts

@@ -1,275 +0,0 @@
-
-import { f as DepValue, o as ContextDecorator, s as ContextDecoratorSpec, v as MetaValue } from "./app-module-BSpHKlhE.mjs";
-import { F as AdapterFactory, T as RequestContext, f as HttpRuntime, m as RouteEntry } from "./adapter-CEt1MEdF.mjs";
-import { t as BuildRoutesOptions } from "./router-builder-GWgxoOdC.mjs";
-import { Express, NextFunction, Request, Response, Router } from "express";
-import { AsyncLocalStorage } from "node:async_hooks";
-
-//#region src/http/cluster.d.ts
-interface ClusterOptions {
-  /** Number of worker processes (default: os.cpus().length) */
-  workers?: number;
-  /** Delay before forcefully killing a worker during shutdown (ms), default: 5000 */
-  gracefulShutdownTimeout?: number;
-  /** Delay between worker restarts (ms), default: 1000 */
-  restartDelay?: number;
-  /** Max failures in restartWindow before refusing to restart, default: 5 */
-  maxFailures?: number;
-  /** Time window for counting failures (ms), default: 30000 */
-  restartWindow?: number;
-}
-/** Returns true if the current process is the cluster primary */
-declare function isClusterPrimary(): boolean;
-//#endregion
-//#region src/http/define-http-context-decorator.d.ts
-/**
- * Curried form returned by {@link DefineHttpContextDecoratorFn.withParams}.
- * Spell only the per-call params shape `P`; `K` and `D` are inferred
- * from the spec, and `Ctx` is locked to `RequestContext`.
- */
-interface DefineHttpContextDecoratorWithParams<P extends Record<string, unknown>> {
-  <K extends string, D extends Record<string, DepValue> = Record<string, never>>(spec: ContextDecoratorSpec<K, D, P, RequestContext>): ContextDecorator<K, D, P, RequestContext>;
-}
-/**
- * Public shape of {@link defineHttpContextDecorator} — the positional
- * call signature plus the curried `.withParams<P>()` helper that fixes
- * partial-inference for the parameterised case.
- */
-interface DefineHttpContextDecoratorFn {
-  <K extends string, D extends Record<string, DepValue> = Record<string, never>, P extends Record<string, unknown> = Record<string, never>>(spec: ContextDecoratorSpec<K, D, P, RequestContext>): ContextDecorator<K, D, P, RequestContext>;
-  /**
-   * Curried entry point. Spell only `P`; `K` and `D` infer from the
-   * spec. `Ctx` is locked to `RequestContext`.
-   *
-   * ```ts
-   * const LoadTenant = defineHttpContextDecorator.withParams<{
-   *   source: 'header' | 'subdomain'
-   * }>()({
-   *   key: 'tenant',
-   *   deps: { repo: TENANT_REPO },           // D inferred
-   *   paramDefaults: { source: 'header' },
-   *   resolve: (ctx, { repo }, params) => repo.findFor(ctx, params),
-   * })
-   * ```
-   */
-  withParams<P extends Record<string, unknown>>(): DefineHttpContextDecoratorWithParams<P>;
-}
-declare const defineHttpContextDecorator: DefineHttpContextDecoratorFn;
-//#endregion
-//#region src/http/runtimes/express.d.ts
-/**
- * Materialize a controller's {@link RouteEntry}[] onto a fresh `express.Router`.
- * Reproduces the legacy handler ordering precisely: validation → upload →
- * `(ctx, next)` middleware → contributor runner → terminal handler. Each step
- * constructs its own `RequestContext` over the same `req`/`res` — request-scoped
- * state lives in the AsyncLocalStorage store, not on the ctx instance, so the
- * per-step instances share state exactly as before.
- */
-declare function materializeRouter(entries: RouteEntry[]): Router;
-/**
- * Build an Express Router from a controller class decorated with @Get, @Post,
- * etc. The public, back-compatible entry point: a thin shim over
- * {@link buildRouteTable} + {@link materializeRouter}. Returns an
- * `express.Router` exactly as before — modules pass it to `app.use(path, router)`.
- *
- * @see buildRouteTable for the engine-neutral route-table form.
- */
-declare function buildRoutes(controllerClass: any, options?: BuildRoutesOptions): Router;
-/**
- * The default HTTP runtime. Express stays a peer dependency of `@forinda/kickjs`;
- * apps that pass no `runtime` get this and behave exactly as before.
- */
-declare function expressRuntime(): HttpRuntime<Express>;
-//#endregion
-//#region src/http/request-store.d.ts
-/** Per-request storage for REQUEST-scoped DI and request context propagation */
-interface RequestStore {
-  /** Unique request identifier */
-  requestId: string;
-  /**
-   * Per-request singleton cache for REQUEST-scoped services. Keys are
-   * heterogeneous (class constructors, `InjectionToken` objects, raw
-   * strings), so the map type stays `Map<any, any>`.
-   */
-  instances: Map<any, any>;
-  /**
-   * Per-request key/value bag. Canonical backing store for
-   * `RequestContext.set/get` and the Context Contributor pipeline (#107)
-   * since Phase 3. Anything written here is visible to every concrete
-   * execution context constructed for the same request, regardless of
-   * which middleware/contributor wrote it.
-   *
-   * Keys are constrained to `string` per the locked decision in
-   * `architecture.md` §20.12 (#4); the value type is `unknown` because
-   * the concrete shape at each key is determined by the consumer's
-   * `ContextMeta` augmentation, not by the store itself.
-   *
-   * Prefer the {@link getRequestValue} helper over reaching into this
-   * map directly — it threads the augmented `ContextMeta` shape through
-   * `MetaValue<K>` so consumers get typed reads without an `as` cast.
-   * Writes should flow through `ctx.set(key, value)` or a Context
-   * Contributor's return value — see the `setRequestValue` note below
-   * for why this package intentionally does NOT ship a service-level
-   * write helper.
-   */
-  values: Map<string, unknown>;
-  /** Set once {@link disposeRequestStore} has run — guards double-dispose. */
-  disposed?: boolean;
-}
-/** AsyncLocalStorage instance shared across the framework */
-declare const requestStore: AsyncLocalStorage<RequestStore>;
-/**
- * Get the current request store. Throws if called outside a request context.
- * Used by the Container to resolve REQUEST-scoped dependencies.
- */
-declare function getRequestStore(): RequestStore;
-/**
- * Read a per-request `ContextMeta`-keyed value from outside a controller
- * (services, repositories, anywhere with no `ctx` reference). Returns
- * the augmented type for the key — `MetaValue<K>` — so consumers get the
- * same static safety as `ctx.get(key)` without holding the context.
- *
- * Returns `undefined` outside an active request frame (background jobs,
- * startup code, tests without `requestScopeMiddleware()`) — the helper
- * is intentionally null-tolerant so calling it from a service that
- * runs in both request and non-request paths doesn't throw.
- *
- * @example
- * ```ts
- * declare module '@forinda/kickjs' {
- *   interface ContextMeta { tenant: { id: string; name: string } }
- * }
- *
- * @Service()
- * class AuditService {
- *   log(action: string) {
- *     const tenant = getRequestValue('tenant')  // typed: { id; name } | undefined
- *     db.audit.insert({ action, tenantId: tenant?.id })
- *   }
- * }
- * ```
- */
-declare function getRequestValue<K extends string>(key: K): MetaValue<K> | undefined;
-//#endregion
-//#region src/http/middleware/request-scope.d.ts
-/**
- * Wraps each request in an AsyncLocalStorage context.
- * Enables REQUEST-scoped DI and automatic requestId propagation to logs.
- *
- * Should be mounted early in the middleware pipeline (before route handlers).
- * `Application` mounts this automatically unless `contextStore: 'manual'` is set
- * or the user already includes one in their middleware list.
- */
-declare function requestScopeMiddleware(): (req: Request, res: Response, next: NextFunction) => void;
-//#endregion
-//#region src/http/middleware/trace-context.d.ts
-/**
- * W3C Trace Context header name.
- * @see https://www.w3.org/TR/trace-context/#traceparent-header
- */
-declare const TRACEPARENT_HEADER = "traceparent";
-interface TraceContextOptions {
-  /**
-   * When true, respond with a `traceresponse` header containing the trace ID.
-   * Useful for debugging. Default: false.
-   */
-  propagateResponse?: boolean;
-}
-/**
- * Parsed W3C trace context fields.
- */
-interface TraceContext {
-  /** W3C traceparent version (usually '00') */
-  version: string;
-  /** 32-hex-char distributed trace ID */
-  traceId: string;
-  /** 16-hex-char parent span ID */
-  parentSpanId: string;
-  /** 2-hex-char trace flags */
-  flags: string;
-}
-/**
- * Parse a W3C traceparent header value.
- * Returns null if the format is invalid.
- */
-declare function parseTraceparent(header: string): TraceContext | null;
-/**
- * Middleware that extracts W3C `traceparent` header and stores trace context
- * in the request's AsyncLocalStorage store.
- *
- * If no valid `traceparent` header is present, a new traceId is generated
- * so that every request always has a trace ID available for correlation.
- *
- * Must be mounted **after** `requestScopeMiddleware()` (which creates the store).
- *
- * @example
- * ```ts
- * bootstrap({
- *   middleware: [
- *     requestScopeMiddleware(),
- *     traceContext(),          // extracts or generates traceId
- *     requestLogger(),
- *     express.json(),
- *   ],
- * })
- * ```
- */
-declare function traceContext(options?: TraceContextOptions): (req: Request, res: Response, next: NextFunction) => void;
-//#endregion
-//#region src/http/middleware/views.d.ts
-interface ViewAdapterOptions {
-  /**
-   * Template engine — pass the engine module or a render function.
-   * Supported engines: ejs, pug, handlebars, nunjucks, or any
-   * Express-compatible engine with a __express property.
-   *
-   * @example
-   * ```ts
-   * import ejs from 'ejs'
-   * ViewAdapter({ engine: ejs, ext: 'ejs' })
-   *
-   * import pug from 'pug'
-   * ViewAdapter({ engine: pug, ext: 'pug' })
-   * ```
-   */
-  engine: any;
-  /** File extension for templates (e.g., 'ejs', 'pug', 'hbs') */
-  ext: string;
-  /** Directory containing template files (default: 'src/views') */
-  viewsDir?: string;
-  /** Default layout template (optional — depends on engine) */
-  layout?: string;
-}
-/**
- * View/template adapter — pluggable template engine support for KickJS.
- *
- * Registers an Express view engine and sets the views directory.
- * Use `ctx.render()` in controllers to render templates.
- *
- * Migrated to the `defineAdapter()` factory in v4 — call without `new`.
- * The pre-v4 `new ViewAdapter({...})` form is gone; see
- * `docs/guide/migration-v3-to-v4.md` for the rename.
- *
- * @example
- * ```ts
- * import ejs from 'ejs'
- * import { ViewAdapter } from '@forinda/kickjs'
- *
- * bootstrap({
- *   modules,
- *   adapters: [
- *     ViewAdapter({ engine: ejs, ext: 'ejs', viewsDir: 'src/views' }),
- *   ],
- * })
- *
- * // In a controller:
- * @Get('/dashboard')
- * async dashboard(ctx: RequestContext) {
- *   ctx.render('dashboard', { user: currentUser, title: 'Dashboard' })
- * }
- * ```
- */
-declare const ViewAdapter: AdapterFactory<ViewAdapterOptions, unknown>;
-//#endregion
-export { ClusterOptions as _, TraceContextOptions as a, requestScopeMiddleware as c, getRequestValue as d, requestStore as f, defineHttpContextDecorator as g, materializeRouter as h, TraceContext as i, RequestStore as l, expressRuntime as m, ViewAdapterOptions as n, parseTraceparent as o, buildRoutes as p, TRACEPARENT_HEADER as r, traceContext as s, ViewAdapter as t, getRequestStore as u, isClusterPrimary as v };
-//# sourceMappingURL=views-Kp8Z3AO1.d.mts.map

package/dist/views-Kp8Z3AO1.d.mts.map

@@ -1 +0,0 @@
-{"version":3,"file":"views-Kp8Z3AO1.d.mts","names":[],"sources":["../src/http/cluster.ts","../src/http/define-http-context-decorator.ts","../src/http/runtimes/express.ts","../src/http/request-store.ts","../src/http/middleware/request-scope.ts","../src/http/middleware/trace-context.ts","../src/http/middleware/views.ts"],"mappings":";;;;;;;;UAOiB,cAAA;;EAEf,OAAA;;EAEA,uBAAA;;EAEA,YAAA;;EAEA,WAAA;;EAEA,aAAA;AAAA;;iBAIc,gBAAA;;;;;;;;UCuDC,oCAAA,WAA+C,MAAA;EAAA,6BACjC,MAAA,SAAe,QAAA,IAAY,MAAA,iBACtD,IAAA,EAAM,oBAAA,CAAqB,CAAA,EAAG,CAAA,EAAG,CAAA,EAAG,cAAA,IACnC,gBAAA,CAAiB,CAAA,EAAG,CAAA,EAAG,CAAA,EAAG,cAAA;AAAA;;;;;;UAQd,4BAAA;EAAA,6BAGH,MAAA,SAAe,QAAA,IAAY,MAAA,2BAC3B,MAAA,oBAA0B,MAAA,iBAEpC,IAAA,EAAM,oBAAA,CAAqB,CAAA,EAAG,CAAA,EAAG,CAAA,EAAG,cAAA,IACnC,gBAAA,CAAiB,CAAA,EAAG,CAAA,EAAG,CAAA,EAAG,cAAA;EAfc;AAQ7C;;;;;;;;;;;;;;EAwBE,UAAA,WAAqB,MAAA,sBAA4B,oCAAA,CAAqC,CAAA;AAAA;AAAA,cAW3E,0BAAA,EAA4B,4BAQR;;;;;;;;;;;iBC3FjB,iBAAA,CAAkB,OAAA,EAAS,UAAA,KAAe,MAAM;;;;;;;;;iBAiEhD,WAAA,CAAY,eAAA,OAAsB,OAAA,GAAS,kBAAA,GAA0B,MAAM;;AFjG3F;;;iBEyGgB,cAAA,IAAkB,WAAW,CAAC,OAAA;;;;UC5G7B,YAAA;;EAEf,SAAA;;;;;;EAMA,SAAA,EAAW,GAAA;;;;;;;;;;;AHLb;;;;;;;;;;EG0BE,MAAA,EAAQ,GAAG;EHZG;EGcd,QAAA;AAAA;;cAIW,YAAA,EAAY,iBAAA,CAAA,YAAA;;;;AFqCzB;iBE/BgB,eAAA,IAAmB,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAoC/B,eAAA,mBAAkC,GAAA,EAAK,CAAA,GAAI,SAAA,CAAU,CAAA;;;;;AH1ErE;;;;;;iBIyFgB,sBAAA,KAAsB,GAAA,EACnB,OAAA,EAAO,GAAA,EAAO,QAAA,EAAQ,IAAA,EAAQ,YAAA;;;;;;;cCxFpC,kBAAA;AAAA,UAKI,mBAAA;;;;;EAKf,iBAAiB;AAAA;;;;UAMF,YAAA;;EAEf,OAAA;;EAEA,OAAA;;EAEA,YAAA;ELxB6B;EK0B7B,KAAA;AAAA;;;;;iBAqBc,gBAAA,CAAiB,MAAA,WAAiB,YAAY;;ALrC/C;AAIf;;;;AAAgC;;;;ACuDhC;;;;;;;;;;;iBIoBgB,YAAA,CAAa,OAAA,GAAS,mBAAA,IAAwB,GAAA,EAC/C,OAAA,EAAO,GAAA,EAAO,QAAA,EAAQ,IAAA,EAAQ,YAAA;;;UC5F5B,kBAAA;;;;;;;;;;;;;;;EAef,MAAA;;EAGA,GAAA;;EAGA,QAAA;;EAGA,MAAA;AAAA;;;;;;;;;;ANZa;AAIf;;;;AAAgC;;;;ACuDhC;;;;;;;;;;;cKfa,WAAA,EAAW,cAAA,CAAA,kBAAA"}