@dudousxd/nestjs-inertia 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,461 @@
+import { NestInterceptor, ExecutionContext, CallHandler, NestMiddleware, ForbiddenException, NestModule, OnApplicationBootstrap, OnApplicationShutdown, DynamicModule, MiddlewareConsumer, CanActivate } from '@nestjs/common';
+import { Observable } from 'rxjs';
+import { Request, Response, NextFunction } from 'express';
+import { Reflector, HttpAdapterHost } from '@nestjs/core';
+
+interface InertiaRequest {
+    method: string;
+    originalUrl: string;
+    url: string;
+    header(name: string): string | undefined;
+    body?: unknown;
+    query?: Record<string, unknown>;
+    raw: unknown;
+}
+interface InertiaResponse {
+    statusCode: number;
+    headersSent: boolean;
+    status(code: number): InertiaResponse;
+    setHeader(name: string, value: string): InertiaResponse;
+    getHeader(name: string): string | string[] | number | undefined;
+    json(body: unknown): void;
+    html(body: string): void;
+    end(): void;
+    raw: unknown;
+}
+
+interface ManifestEntry {
+    file: string;
+    css?: string[];
+    imports?: string[];
+}
+type Manifest = Record<string, ManifestEntry>;
+
+type FlashErrors = Record<string, string | Record<string, string>>;
+interface FlashStore {
+    read(req: unknown): FlashErrors | Promise<FlashErrors>;
+    write?(req: unknown, errors: FlashErrors): void | Promise<void>;
+}
+
+declare const INERTIA_MODULE_OPTIONS: unique symbol;
+declare const INERTIA_FEATURE_OPTIONS: unique symbol;
+declare const INERTIA_MANIFEST: unique symbol;
+declare const INERTIA_ASSET_VERSION: unique symbol;
+declare const INERTIA_DEFAULT_SCOPE = "default";
+type InertiaScope = string;
+declare function featureToken(kind: 'OPTIONS' | 'MANIFEST' | 'ASSET_VERSION' | 'SHELL_RENDERER' | 'SSR_LOADER', scope: string, rootId?: string): symbol;
+
+interface PageObject {
+    component: string;
+    props: Record<string, unknown>;
+    url: string;
+    version: string;
+    encryptHistory?: boolean;
+    clearHistory?: boolean;
+    deferredProps?: Record<string, string[]>;
+    mergeProps?: string[];
+    deepMergeProps?: string[];
+    matchPropsOn?: Record<string, string>;
+}
+interface SsrResult {
+    head: string[];
+    body: string;
+}
+type Props = Record<string, unknown>;
+type SharedFactory = (req: unknown) => Props | Promise<Props>;
+type SharedInput = Props | SharedFactory;
+interface ShellRenderCtx {
+    page: PageObject;
+    ssr: SsrResult | null;
+    manifest: unknown;
+    assetVersion: string;
+    ctx: {
+        req: unknown;
+        res: unknown;
+    };
+}
+type RootViewFn = (ctx: ShellRenderCtx) => string | Promise<string>;
+type RootView = string | RootViewFn;
+interface ViteOptions {
+    entry: string;
+    manifestPath?: string;
+    hmrPort?: number;
+}
+interface SsrOptions {
+    enabled?: boolean;
+    bundlePath?: string;
+    devMode?: 'off' | 'vite';
+    throwOnError?: boolean;
+}
+/**
+ * Options controlling the auto-bootstrap of the `@dudousxd/nestjs-inertia-codegen` file watcher
+ * that is started automatically inside `InertiaModule.onApplicationBootstrap` in dev mode.
+ *
+ * @example
+ * // Disable auto-watch entirely (e.g. in CI or when running the CLI watcher manually):
+ * InertiaModule.forRoot({ codegen: { enabled: false } })
+ */
+interface CodegenOptions {
+    /**
+     * Whether to auto-start the codegen watcher when the application bootstraps.
+     *
+     * - `'auto'` (default) — start when `NODE_ENV !== 'production'` AND the
+     *   `@dudousxd/nestjs-inertia-codegen` package is installed AND a
+     *   `nestjs-inertia.config.ts` config file is present.
+     * - `true` — same as `'auto'`.
+     * - `false` — never auto-start; useful when running the CLI watcher (`nestjs-inertia codegen --watch`)
+     *   in a separate terminal or when you want to disable codegen entirely.
+     */
+    enabled?: boolean | 'auto';
+}
+interface InertiaModuleOptions {
+    rootView?: RootView;
+    vite?: ViteOptions;
+    ssr?: SsrOptions;
+    share?: SharedInput;
+    version?: string | (() => string | Promise<string>);
+    historyEncryption?: {
+        default?: boolean;
+    };
+    autoUpgrade303?: boolean;
+    methodSpoofing?: boolean;
+    codegen?: CodegenOptions;
+    flashStore?: FlashStore;
+}
+interface InertiaFeatureOptions extends InertiaModuleOptions {
+    scope: InertiaScope;
+}
+interface InertiaOptionsFactory {
+    createInertiaOptions(): Promise<InertiaModuleOptions> | InertiaModuleOptions;
+}
+interface InertiaFeatureAsyncOptions {
+    scope: string;
+    imports?: unknown[];
+    inject?: unknown[];
+    useExisting?: new (...args: unknown[]) => InertiaOptionsFactory;
+    useClass?: new (...args: unknown[]) => InertiaOptionsFactory;
+    useFactory?: (...args: unknown[]) => Promise<InertiaModuleOptions> | InertiaModuleOptions;
+}
+interface InertiaModuleAsyncOptions {
+    imports?: unknown[];
+    inject?: unknown[];
+    useExisting?: new (...args: unknown[]) => InertiaOptionsFactory;
+    useClass?: new (...args: unknown[]) => InertiaOptionsFactory;
+    useFactory?: (...args: unknown[]) => Promise<InertiaModuleOptions> | InertiaModuleOptions;
+}
+
+interface SsrModule {
+    render(page: PageObject): Promise<{
+        head: string[];
+        body: string;
+    }>;
+}
+interface SsrLoader {
+    load(): Promise<SsrModule | null>;
+}
+interface InertiaServiceDeps {
+    assetVersion: string;
+    manifest: Manifest | null;
+    ssrLoader: SsrLoader;
+    rootViewRender: (ctx: ShellRenderCtx) => Promise<string>;
+    moduleShare: SharedInput | undefined;
+    featureShare: SharedInput | undefined;
+    historyEncryptionDefault?: boolean;
+    flashStore: FlashStore | undefined;
+}
+declare class InertiaService {
+    private readonly req;
+    private readonly res;
+    private readonly deps;
+    private readonly logger;
+    private shared;
+    private encryptHistoryFlag;
+    private clearHistoryFlag;
+    constructor(req: InertiaRequest, res: InertiaResponse, deps: InertiaServiceDeps);
+    share(input: SharedInput): this;
+    /**
+     * Perform an Inertia redirect. For Inertia XHR requests, issues a 409 with
+     * `X-Inertia-Location`; for plain browser visits, issues a 302 redirect.
+     *
+     * Only relative URLs (starting with `/`) or same-origin absolute URLs are
+     * accepted. Absolute URLs pointing to a different host are rejected to prevent
+     * open-redirect vulnerabilities.
+     *
+     * @param url Relative path (e.g. `/dashboard`) or same-origin absolute URL.
+     * @throws Error when `url` is an absolute URL pointing to a different origin.
+     */
+    location(url: string): void;
+    encryptHistory(value?: boolean): this;
+    clearHistory(): this;
+    private resolveShared;
+    render(component: string, props?: Props): Promise<void>;
+}
+
+declare class ErrorBagInterceptor implements NestInterceptor {
+    intercept(context: ExecutionContext, next: CallHandler): Observable<unknown>;
+}
+
+declare class RedirectInterceptor implements NestInterceptor {
+    private readonly options;
+    constructor(options: InertiaModuleOptions);
+    intercept(context: ExecutionContext, next: CallHandler): Observable<unknown>;
+}
+
+declare class MethodSpoofMiddleware implements NestMiddleware {
+    private readonly options;
+    constructor(options: InertiaModuleOptions);
+    use(req: Request & {
+        body?: Record<string, unknown>;
+    }, _res: Response, next: NextFunction): void;
+}
+
+declare class InvalidInertiaConfigException extends Error {
+    constructor(message: string);
+}
+declare class InertiaServiceNotAvailableException extends Error {
+    constructor();
+}
+declare class UnsupportedRootViewExtensionException extends Error {
+    constructor(extension: string);
+}
+declare class MissingTemplateEngineDepException extends Error {
+    constructor(engine: string, packageName: string);
+}
+declare class MissingCookieDepException extends Error {
+    constructor(platform: 'express' | 'fastify');
+}
+
+declare class InvalidCsrfTokenException extends ForbiddenException {
+    constructor();
+}
+
+declare const MARKER: unique symbol;
+type MarkerKind = 'always' | 'optional' | 'defer' | 'merge' | 'once';
+interface Marker<T = unknown> {
+    [MARKER]: true;
+    kind: MarkerKind;
+    value: () => T | Promise<T>;
+    meta: Record<string, unknown>;
+}
+declare function inertiaDecorator(component: string): MethodDecorator;
+declare function always<T>(fn: () => T | Promise<T>): Marker<T>;
+declare function optional<T>(fn: () => T | Promise<T>): Marker<T>;
+/**
+ * @deprecated Use `Inertia.optional()` instead. `Inertia.lazy()` is a deprecated alias
+ * kept for v1/v2 backward compatibility and will be removed in a future major version.
+ */
+declare function lazy<T>(fn: () => T | Promise<T>): Marker<T>;
+declare function defer<T>(fn: () => T | Promise<T>, group?: string): Marker<T>;
+declare function once<T>(fn: () => T | Promise<T>): Marker<T>;
+declare function merge<T>(fn: () => T | Promise<T>, opts?: {
+    matchOn?: string;
+    deep?: boolean;
+}): Marker<T>;
+type InertiaFn = typeof inertiaDecorator & {
+    always: typeof always;
+    optional: typeof optional;
+    lazy: typeof lazy;
+    defer: typeof defer;
+    once: typeof once;
+    merge: typeof merge;
+};
+declare const Inertia: InertiaFn;
+
+declare const INERTIA_USE_SCOPE = "INERTIA_USE_SCOPE";
+declare function UseInertia(scope: string): ClassDecorator & MethodDecorator;
+
+/**
+ * Empty interface for module augmentation by codegen consumers.
+ * Augment this interface (e.g. via `nestjs-inertia.d.ts` emitted by `nestjs-inertia init`)
+ * to register typed `pages` / `shared` / `routes` maps.
+ *
+ * MUST remain an `interface` (not a `type` alias) — `declare module ... { interface ... }`
+ * augmentation only works on interfaces. Converting to `type X = {}` silently breaks the
+ * Link component's `routeParams` typing in every consumer app.
+ */
+interface InertiaRegistry {
+}
+/**
+ * Resolves to the augmented routes map when `InertiaRegistry` has been extended
+ * with a `routes` key (via `nestjs-inertia.d.ts`), otherwise falls back to
+ * `Record<string, unknown>` so client code compiles without codegen.
+ */
+type RegistryRoutes = InertiaRegistry extends {
+    routes: infer R;
+} ? R : Record<string, unknown>;
+
+declare const INERTIA_RENDER_COMPONENT: unique symbol;
+
+declare class InertiaRenderInterceptor implements NestInterceptor {
+    private readonly reflector;
+    constructor(reflector: Reflector);
+    intercept(context: ExecutionContext, next: CallHandler): Observable<unknown>;
+}
+
+interface ShellRenderer {
+    render(ctx: ShellRenderCtx): Promise<string>;
+}
+
+/** Minimal interface matching `Watcher` from `@dudousxd/nestjs-inertia-codegen`. */
+interface CodegenWatcher {
+    close(): Promise<void>;
+}
+/** Minimal interface matching the codegen module's public API used here. */
+interface CodegenModule {
+    loadConfig(cwd?: string): Promise<unknown>;
+    watch(config: unknown): Promise<CodegenWatcher>;
+}
+declare class InertiaModule implements NestModule, OnApplicationBootstrap, OnApplicationShutdown {
+    private readonly httpAdapterHost;
+    private readonly options;
+    private readonly assetVersion;
+    private readonly manifest;
+    private readonly shellRenderer;
+    private readonly ssrLoader;
+    /**
+     * Shared provider set for both `forRoot` and `forRootAsync`.
+     * Does NOT include the options provider(s) — callers prepend those themselves.
+     */
+    private static buildModuleProviders;
+    private static readonly moduleExports;
+    static forRoot(options?: InertiaModuleOptions): DynamicModule;
+    static forRootAsync(asyncOptions: InertiaModuleAsyncOptions): DynamicModule;
+    static forFeature(options: InertiaFeatureOptions): DynamicModule;
+    static forFeatureAsync(asyncOptions: InertiaFeatureAsyncOptions): DynamicModule;
+    private static createFeatureProviders;
+    private static validateAsyncOptions;
+    private static createAsyncOptionsProviders;
+    private readonly logger;
+    private codegenWatcher;
+    constructor(httpAdapterHost: HttpAdapterHost, options: InertiaModuleOptions, assetVersion: string, manifest: Manifest | null, shellRenderer: ShellRenderer, ssrLoader: {
+        load: () => Promise<never>;
+    });
+    /**
+     * Test seam: override in a subclass or via `Object.defineProperty` to inject a stub
+     * codegen module without touching NestJS DI. Production callers never touch this.
+     *
+     * @internal
+     */
+    protected _resolveCodegenModule(): Promise<CodegenModule>;
+    onApplicationBootstrap(): Promise<void>;
+    /**
+     * Auto-starts the codegen file watcher in dev mode.
+     *
+     * Rules (all must pass for the watcher to start):
+     * 1. `process.env.NODE_ENV !== 'production'`
+     * 2. `options.codegen?.enabled !== false`
+     * 3. `@dudousxd/nestjs-inertia-codegen` is resolvable (peer-optional)
+     * 4. A `nestjs-inertia.config.ts` (or equivalent) is present in `process.cwd()`
+     *
+     * If the CLI watcher already holds the lock file, the codegen package returns a
+     * no-op watcher — no conflict occurs.
+     *
+     * This method NEVER throws; any unexpected error is logged as a warning.
+     */
+    private _startCodegenWatcher;
+    onApplicationShutdown(): Promise<void>;
+    configure(consumer: MiddlewareConsumer): void;
+}
+
+type CookieResponse = {
+    cookie?: (name: string, value: string, opts?: unknown) => unknown;
+    setCookie?: (name: string, value: string, opts?: unknown) => unknown;
+};
+/**
+ * Force-issue a new CSRF token on the next response, discarding the existing
+ * one. Call this when the session principal changes (e.g. after issuing a new
+ * session) to prevent token fixation attacks.
+ *
+ * If you need to invalidate prior tokens (e.g., after session principal change),
+ * configure `tokenContext` to return a session-bound value (session ID, nonce) —
+ * old tokens fail verification when that value changes.
+ *
+ * @example
+ * ```ts
+ * rotateCsrfToken(res, { secret: this.csrfSecret });
+ * ```
+ */
+declare function rotateCsrfToken(res: CookieResponse, options: Pick<CsrfCookieOptions, 'secret' | 'cookieName' | 'httpOnly' | 'sameSite' | 'secure'>, context?: string): void;
+interface CsrfCookieOptions {
+    secret: string;
+    cookieName?: string;
+    headerName?: string;
+    sameSite?: 'lax' | 'strict' | 'none';
+    httpOnly?: boolean;
+    secure?: boolean;
+    /**
+     * Optional function to extract a session-bound context value from the request.
+     * When provided, the HMAC payload includes this value so that tokens become
+     * invalid when the context changes (e.g. after a session principal change).
+     * Typical values: session ID, session nonce.
+     *
+     * @example
+     * ```ts
+     * tokenContext: (req) => req.session?.id ?? ''
+     * ```
+     */
+    tokenContext?: (req: unknown) => string;
+}
+declare class CsrfCookieInterceptor implements NestInterceptor {
+    private readonly options;
+    private readonly cookieName;
+    constructor(options: CsrfCookieOptions);
+    intercept(context: ExecutionContext, next: CallHandler): Observable<unknown>;
+}
+
+interface CsrfGuardOptions {
+    secret: string;
+    cookieName?: string;
+    headerName?: string;
+    /**
+     * Optional function to extract a session-bound context value from the request.
+     * Must match the `tokenContext` used in `CsrfCookieInterceptor` for the same app.
+     */
+    tokenContext?: (req: unknown) => string;
+}
+declare class CsrfGuard implements CanActivate {
+    private readonly options;
+    private readonly cookieName;
+    private readonly headerName;
+    constructor(options: CsrfGuardOptions);
+    canActivate(ctx: ExecutionContext): boolean;
+}
+
+/**
+ * Generates a CSRF token.
+ *
+ * @param secret     The HMAC secret.
+ * @param context    Optional session-bound context value (e.g. session ID or nonce).
+ *                   When provided, the context is included in the HMAC payload so that
+ *                   tokens become invalid when the context changes (e.g. after a session
+ *                   principal change). Token format: `<raw>.<context-hex>.<sig>`
+ *                   Without context, format is: `<raw>.<sig>`
+ */
+declare function generateCsrfToken(secret: string, context?: string): string;
+/**
+ * Constant-time buffer comparison that returns `false` for length mismatches
+ * rather than throwing, avoiding a timing oracle on length.
+ */
+declare function timingSafeEqualSafe(a: Buffer, b: Buffer): boolean;
+/**
+ * Verifies a CSRF token.
+ *
+ * @param token    The token string (from cookie or header).
+ * @param secret   The HMAC secret.
+ * @param context  Optional session-bound context value. Must match the context
+ *                 used when the token was generated. If the context has changed
+ *                 (e.g. new session), the old token will fail verification.
+ */
+declare function verifyCsrfToken(token: string, secret: string, context?: string): boolean;
+
+declare const VERSION = "1.0.0";
+
+declare global {
+    namespace Express {
+        interface Request {
+            inertia: InertiaService;
+        }
+    }
+}
+
+export { type CodegenOptions, CsrfCookieInterceptor, type CsrfCookieOptions, CsrfGuard, type CsrfGuardOptions, ErrorBagInterceptor, type FlashErrors, type FlashStore, INERTIA_ASSET_VERSION, INERTIA_DEFAULT_SCOPE, INERTIA_FEATURE_OPTIONS, INERTIA_MANIFEST, INERTIA_MODULE_OPTIONS, INERTIA_RENDER_COMPONENT, INERTIA_USE_SCOPE, Inertia, type InertiaFeatureAsyncOptions, type InertiaFeatureOptions, InertiaModule, type InertiaModuleAsyncOptions, type InertiaModuleOptions, type InertiaOptionsFactory, type InertiaRegistry, InertiaRenderInterceptor, InertiaService, InertiaServiceNotAvailableException, InvalidCsrfTokenException, InvalidInertiaConfigException, MethodSpoofMiddleware, MissingCookieDepException, MissingTemplateEngineDepException, type PageObject, type Props, RedirectInterceptor, type RegistryRoutes, type RootView, type RootViewFn, type SharedFactory, type SharedInput, type ShellRenderCtx, type ShellRenderer, type SsrOptions, type SsrResult, UnsupportedRootViewExtensionException, UseInertia, VERSION, type ViteOptions, featureToken, generateCsrfToken, rotateCsrfToken, timingSafeEqualSafe, verifyCsrfToken };