@arponascension/express-inertia 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,175 @@
+import { RequestHandler, Request } from 'express';
+import { I as InertiaOptions, D as DirectiveHandler, P as PropCallback, A as AlwaysProp, a as DeferredProp, L as LazyProp, M as MergeProp, O as OptionalProp, b as PageProps, c as Page, S as SSROptions, d as SSRResult } from './types-Co2XESgs.mjs';
+export { B as BladeEngineOptions, C as CircuitBreaker, e as CircuitBreakerOptions, f as InertiaRequestHelper, g as InertiaResponseHandler, R as RetryOptions, h as SSRResilienceOptions, i as SecurityOptions, V as ViteConfig, j as calculateBackoff, s as shouldRetry } from './types-Co2XESgs.mjs';
+export { TemplateLocals, clearEngineCache, createInertiaEngine, inertiaEngine } from './engine.mjs';
+import { ViteHelper } from './vite.mjs';
+export { InertiaVitePlugin, InertiaVitePluginOptions, ViteManifest, ViteManifestChunk, createViteHelper, defaultViteHelper, inertiaVitePlugin } from './vite.mjs';
+
+/**
+ * Creates the Inertia Express middleware.
+ *
+ * @example
+ * ```ts
+ * import express from 'express';
+ * import inertia from 'express-inertia';
+ *
+ * const app = express();
+ * app.use(inertia({
+ *   rootView: 'base.ejs',
+ *   version: '1.0.0',
+ *   shared: (req) => ({
+ *     user: req.user,
+ *     flash: req.flash?.() || {},
+ *   }),
+ * }));
+ * ```
+ */
+declare function createInertia(options?: InertiaOptions): RequestHandler;
+
+/**
+ * Middleware that assigns a unique request ID for correlation across logs.
+ * Uses X-Request-ID header if present, otherwise generates a short ID.
+ */
+declare function requestIdMiddleware(): RequestHandler;
+
+/**
+ * Register a global custom Blade directive.
+ * @param name Directive name without the @ (e.g. 'datetime' for @datetime($date))
+ * @param handler Function returning the compiled EJS string or HTML
+ */
+declare function registerDirective(name: string, handler: DirectiveHandler): void;
+/**
+ * Compiles Blade-style directives and Blade-style component tags into valid EJS syntax.
+ */
+declare function compileBladeDirectives(templateSource: string, localDirectives?: Record<string, DirectiveHandler>): string;
+
+/**
+ * Marks a prop as lazy. Lazy props are ONLY evaluated during partial reloads
+ * when specifically requested in the `only` array by the client.
+ */
+declare function lazy<T = any>(callback: PropCallback<T>): LazyProp<T>;
+/**
+ * Marks a prop as always included. Always props are evaluated and returned
+ * on every request, including partial reloads, even if not explicitly requested.
+ */
+declare function always<T = any>(value: T | PropCallback<T>): AlwaysProp<T>;
+/**
+ * Marks a prop as deferred (Inertia v2).
+ */
+declare function defer<T = any>(callback: PropCallback<T>, options?: {
+    group?: string;
+}): DeferredProp<T>;
+/**
+ * Marks a prop as mergeable (Inertia v2).
+ */
+declare function merge<T = any>(value: T | PropCallback<T>): MergeProp<T>;
+/**
+ * Marks a prop as optional.
+ */
+declare function optional<T = any>(callback: PropCallback<T>): OptionalProp<T>;
+declare function isLazy(val: any): val is LazyProp;
+declare function isAlways(val: any): val is AlwaysProp;
+declare function isDeferred(val: any): val is DeferredProp;
+declare function isMerge(val: any): val is MergeProp;
+declare function isOptional(val: any): val is OptionalProp;
+/**
+ * Evaluates and resolves all props (promises, functions, lazy, always, merge, deferred)
+ * based on current Inertia request context and partial reload headers.
+ */
+declare function resolveProps(rawProps: PageProps, req: Request, component: string): Promise<{
+    resolvedProps: PageProps;
+    deferredProps?: Record<string, string[]>;
+    mergeProps?: string[];
+}>;
+/**
+ * Escapes characters for HTML attribute insertion to prevent XSS.
+ */
+declare function escapeHtmlAttr(str: string): string;
+/**
+ * Serializes Page object safely for data-page HTML attribute.
+ */
+declare function serializePage(page: Page): string;
+/**
+ * Safely stringifies an object, replacing circular references with null.
+ */
+declare function safeStringify(obj: any): string;
+/**
+ * Default pattern for safe component names: alphanumeric, hyphens, and underscores,
+ * optionally separated by single forward slashes. Blocks path traversal sequences
+ * like `..`, leading/trailing slashes, and consecutive slashes.
+ */
+declare const DEFAULT_COMPONENT_NAME_PATTERN: RegExp;
+/**
+ * Validates a component name to prevent path traversal and injection attacks.
+ * Throws a TypeError if the name contains suspicious characters.
+ */
+declare function validateComponentName(component: string, pattern?: RegExp): void;
+/**
+ * Recursively sanitizes viewData by stripping functions and undefined values.
+ * Only plain objects and primitive values are preserved.
+ */
+declare function sanitizeViewData(data: Record<string, any>): Record<string, any>;
+/**
+ * Generates a Subresource Integrity (SRI) hash for a given string.
+ * Returns the base64-encoded SHA-384 hash prefixed with 'sha384-'.
+ */
+declare function generateSriHash(content: string | Buffer): Promise<string>;
+
+declare function resetAllCircuitBreakers(): void;
+/**
+ * Executes Server-Side Rendering (SSR) for the given Inertia page.
+ * Returns head elements and rendered HTML body, or null if SSR is disabled or fails.
+ */
+declare function renderSSR(page: Page, options?: boolean | SSROptions): Promise<SSRResult | null>;
+
+interface PrefetchOptions {
+    /**
+     * Whether to include crossorigin attribute.
+     * @default false
+     */
+    crossorigin?: boolean;
+    /**
+     * Whether to include integrity attribute (requires async SRI calculation).
+     * @default false
+     */
+    integrity?: boolean;
+    /**
+     * Prefetch mode: 'prefetch' (default) or 'preload'.
+     */
+    mode?: 'prefetch' | 'preload';
+}
+interface PrefetchEntry {
+    entrypoints: string[];
+    assets?: string[];
+}
+declare class PrefetchHelper {
+    private viteHelper;
+    constructor(viteHelper: ViteHelper);
+    /**
+     * Generates prefetch tags for the given entrypoints.
+     * Uses the Vite manifest to resolve actual asset paths in production.
+     */
+    prefetch(entries: string | string[], options?: PrefetchOptions): string;
+    /**
+     * Generates preload tags for critical assets.
+     */
+    preload(entries: string | string[], options?: Omit<PrefetchOptions, 'mode'>): string;
+    private resolveChunk;
+}
+declare function createPrefetchHelper(viteHelper: ViteHelper): PrefetchHelper;
+
+interface Logger {
+    warn(message: string, meta?: Record<string, any>): void;
+    error(message: string, meta?: Record<string, any>): void;
+    info(message: string, meta?: Record<string, any>): void;
+    debug(message: string, meta?: Record<string, any>): void;
+}
+interface LoggerOptions {
+    prefix?: string;
+    logger?: Logger;
+}
+declare function setGlobalLogger(logger: Logger): void;
+declare function getGlobalLogger(): Logger;
+declare function createLogger(options?: LoggerOptions): Logger;
+
+export { AlwaysProp, DEFAULT_COMPONENT_NAME_PATTERN, DeferredProp, DirectiveHandler, InertiaOptions, LazyProp, type Logger, type LoggerOptions, MergeProp, OptionalProp, Page, PageProps, type PrefetchEntry, PrefetchHelper, type PrefetchOptions, PropCallback, SSROptions, SSRResult, ViteHelper, always, compileBladeDirectives, createInertia, createLogger, createPrefetchHelper, createInertia as default, defer, escapeHtmlAttr, generateSriHash, getGlobalLogger, createInertia as inertia, isAlways, isDeferred, isLazy, isMerge, isOptional, lazy, merge, optional, registerDirective, renderSSR, requestIdMiddleware, resetAllCircuitBreakers, resolveProps, safeStringify, sanitizeViewData, serializePage, setGlobalLogger, validateComponentName };

package/dist/index.d.ts

@@ -0,0 +1,175 @@
+import { RequestHandler, Request } from 'express';
+import { I as InertiaOptions, D as DirectiveHandler, P as PropCallback, A as AlwaysProp, a as DeferredProp, L as LazyProp, M as MergeProp, O as OptionalProp, b as PageProps, c as Page, S as SSROptions, d as SSRResult } from './types-Co2XESgs.js';
+export { B as BladeEngineOptions, C as CircuitBreaker, e as CircuitBreakerOptions, f as InertiaRequestHelper, g as InertiaResponseHandler, R as RetryOptions, h as SSRResilienceOptions, i as SecurityOptions, V as ViteConfig, j as calculateBackoff, s as shouldRetry } from './types-Co2XESgs.js';
+export { TemplateLocals, clearEngineCache, createInertiaEngine, inertiaEngine } from './engine.js';
+import { ViteHelper } from './vite.js';
+export { InertiaVitePlugin, InertiaVitePluginOptions, ViteManifest, ViteManifestChunk, createViteHelper, defaultViteHelper, inertiaVitePlugin } from './vite.js';
+
+/**
+ * Creates the Inertia Express middleware.
+ *
+ * @example
+ * ```ts
+ * import express from 'express';
+ * import inertia from 'express-inertia';
+ *
+ * const app = express();
+ * app.use(inertia({
+ *   rootView: 'base.ejs',
+ *   version: '1.0.0',
+ *   shared: (req) => ({
+ *     user: req.user,
+ *     flash: req.flash?.() || {},
+ *   }),
+ * }));
+ * ```
+ */
+declare function createInertia(options?: InertiaOptions): RequestHandler;
+
+/**
+ * Middleware that assigns a unique request ID for correlation across logs.
+ * Uses X-Request-ID header if present, otherwise generates a short ID.
+ */
+declare function requestIdMiddleware(): RequestHandler;
+
+/**
+ * Register a global custom Blade directive.
+ * @param name Directive name without the @ (e.g. 'datetime' for @datetime($date))
+ * @param handler Function returning the compiled EJS string or HTML
+ */
+declare function registerDirective(name: string, handler: DirectiveHandler): void;
+/**
+ * Compiles Blade-style directives and Blade-style component tags into valid EJS syntax.
+ */
+declare function compileBladeDirectives(templateSource: string, localDirectives?: Record<string, DirectiveHandler>): string;
+
+/**
+ * Marks a prop as lazy. Lazy props are ONLY evaluated during partial reloads
+ * when specifically requested in the `only` array by the client.
+ */
+declare function lazy<T = any>(callback: PropCallback<T>): LazyProp<T>;
+/**
+ * Marks a prop as always included. Always props are evaluated and returned
+ * on every request, including partial reloads, even if not explicitly requested.
+ */
+declare function always<T = any>(value: T | PropCallback<T>): AlwaysProp<T>;
+/**
+ * Marks a prop as deferred (Inertia v2).
+ */
+declare function defer<T = any>(callback: PropCallback<T>, options?: {
+    group?: string;
+}): DeferredProp<T>;
+/**
+ * Marks a prop as mergeable (Inertia v2).
+ */
+declare function merge<T = any>(value: T | PropCallback<T>): MergeProp<T>;
+/**
+ * Marks a prop as optional.
+ */
+declare function optional<T = any>(callback: PropCallback<T>): OptionalProp<T>;
+declare function isLazy(val: any): val is LazyProp;
+declare function isAlways(val: any): val is AlwaysProp;
+declare function isDeferred(val: any): val is DeferredProp;
+declare function isMerge(val: any): val is MergeProp;
+declare function isOptional(val: any): val is OptionalProp;
+/**
+ * Evaluates and resolves all props (promises, functions, lazy, always, merge, deferred)
+ * based on current Inertia request context and partial reload headers.
+ */
+declare function resolveProps(rawProps: PageProps, req: Request, component: string): Promise<{
+    resolvedProps: PageProps;
+    deferredProps?: Record<string, string[]>;
+    mergeProps?: string[];
+}>;
+/**
+ * Escapes characters for HTML attribute insertion to prevent XSS.
+ */
+declare function escapeHtmlAttr(str: string): string;
+/**
+ * Serializes Page object safely for data-page HTML attribute.
+ */
+declare function serializePage(page: Page): string;
+/**
+ * Safely stringifies an object, replacing circular references with null.
+ */
+declare function safeStringify(obj: any): string;
+/**
+ * Default pattern for safe component names: alphanumeric, hyphens, and underscores,
+ * optionally separated by single forward slashes. Blocks path traversal sequences
+ * like `..`, leading/trailing slashes, and consecutive slashes.
+ */
+declare const DEFAULT_COMPONENT_NAME_PATTERN: RegExp;
+/**
+ * Validates a component name to prevent path traversal and injection attacks.
+ * Throws a TypeError if the name contains suspicious characters.
+ */
+declare function validateComponentName(component: string, pattern?: RegExp): void;
+/**
+ * Recursively sanitizes viewData by stripping functions and undefined values.
+ * Only plain objects and primitive values are preserved.
+ */
+declare function sanitizeViewData(data: Record<string, any>): Record<string, any>;
+/**
+ * Generates a Subresource Integrity (SRI) hash for a given string.
+ * Returns the base64-encoded SHA-384 hash prefixed with 'sha384-'.
+ */
+declare function generateSriHash(content: string | Buffer): Promise<string>;
+
+declare function resetAllCircuitBreakers(): void;
+/**
+ * Executes Server-Side Rendering (SSR) for the given Inertia page.
+ * Returns head elements and rendered HTML body, or null if SSR is disabled or fails.
+ */
+declare function renderSSR(page: Page, options?: boolean | SSROptions): Promise<SSRResult | null>;
+
+interface PrefetchOptions {
+    /**
+     * Whether to include crossorigin attribute.
+     * @default false
+     */
+    crossorigin?: boolean;
+    /**
+     * Whether to include integrity attribute (requires async SRI calculation).
+     * @default false
+     */
+    integrity?: boolean;
+    /**
+     * Prefetch mode: 'prefetch' (default) or 'preload'.
+     */
+    mode?: 'prefetch' | 'preload';
+}
+interface PrefetchEntry {
+    entrypoints: string[];
+    assets?: string[];
+}
+declare class PrefetchHelper {
+    private viteHelper;
+    constructor(viteHelper: ViteHelper);
+    /**
+     * Generates prefetch tags for the given entrypoints.
+     * Uses the Vite manifest to resolve actual asset paths in production.
+     */
+    prefetch(entries: string | string[], options?: PrefetchOptions): string;
+    /**
+     * Generates preload tags for critical assets.
+     */
+    preload(entries: string | string[], options?: Omit<PrefetchOptions, 'mode'>): string;
+    private resolveChunk;
+}
+declare function createPrefetchHelper(viteHelper: ViteHelper): PrefetchHelper;
+
+interface Logger {
+    warn(message: string, meta?: Record<string, any>): void;
+    error(message: string, meta?: Record<string, any>): void;
+    info(message: string, meta?: Record<string, any>): void;
+    debug(message: string, meta?: Record<string, any>): void;
+}
+interface LoggerOptions {
+    prefix?: string;
+    logger?: Logger;
+}
+declare function setGlobalLogger(logger: Logger): void;
+declare function getGlobalLogger(): Logger;
+declare function createLogger(options?: LoggerOptions): Logger;
+
+export { AlwaysProp, DEFAULT_COMPONENT_NAME_PATTERN, DeferredProp, DirectiveHandler, InertiaOptions, LazyProp, type Logger, type LoggerOptions, MergeProp, OptionalProp, Page, PageProps, type PrefetchEntry, PrefetchHelper, type PrefetchOptions, PropCallback, SSROptions, SSRResult, ViteHelper, always, compileBladeDirectives, createInertia, createLogger, createPrefetchHelper, createInertia as default, defer, escapeHtmlAttr, generateSriHash, getGlobalLogger, createInertia as inertia, isAlways, isDeferred, isLazy, isMerge, isOptional, lazy, merge, optional, registerDirective, renderSSR, requestIdMiddleware, resetAllCircuitBreakers, resolveProps, safeStringify, sanitizeViewData, serializePage, setGlobalLogger, validateComponentName };