webspresso 0.0.101 → 0.0.102

package/index.d.ts

@@ -68,6 +68,14 @@ export interface CreateAppOptions {
   compression?: boolean | CompressionOptions;
   /** Shutdown and lifecycle configuration */
   shutdown?: ShutdownOptions;
+  /**
+   * Ahead-Of-Time (AOT) route manifest: boolean to enable/disable loading, or explicit path to manifest JSON file
+   */
+  routesManifest?: boolean | string;
+  /**
+   * Precompiled Nunjucks templates: boolean to enable/disable loading, or explicit path to compiled bundle file
+   */
+  precompiledTemplates?: boolean | string;
   /** Development tooling and DX options */
   dev?: {
     banner?: boolean;
@@ -657,6 +665,25 @@ export function detectLocale(
   defaultLocale: string
 ): string;
 
+export interface TranslateValidationIssuesOptions {
+  req?: Request;
+  t?: Translator;
+  locale?: string;
+  pagesDir?: string;
+  routeDir?: string;
+  isDev?: boolean;
+}
+
+export function translateValidationIssues<T = unknown>(
+  issues: T[],
+  options?: TranslateValidationIssuesOptions
+): T[];
+
+export function getTranslatorForRequest(
+  req?: Request,
+  options?: { pagesDir?: string; routeDir?: string; isDev?: boolean }
+): { t: Translator; locale: string };
+
 export function parseNjkFrontmatter(content: string): {
   body: string;
   fm: Record<string, unknown> | null;
@@ -1561,9 +1588,38 @@ export interface AdminPanelPluginOptions {
     windowMs?: number;
     blockDurationMs?: number;
   };
+  /** Lazy / On-Demand mount: defers plugin initialization until first request to adminPath or service execution */
+  lazy?: boolean | LazyPluginOptions;
   [key: string]: unknown;
 }
 
+export interface LazyPluginOptions {
+  name?: string;
+  prefix?: string | string[];
+  services?: string[];
+  helpers?: string[];
+  events?: string[];
+  dependencies?: Record<string, string> | string[];
+  csp?: Record<string, string[]>;
+  onHydrate?: (realPlugin: WebspressoPlugin) => void;
+}
+
+export interface LazyPlugin extends WebspressoPlugin {
+  isLazy: true;
+  readonly isHydrated: boolean;
+  hydrate(): WebspressoPlugin;
+}
+
+export function lazyPlugin(
+  pluginFactory: (() => WebspressoPlugin) | WebspressoPlugin,
+  lazyOptions?: LazyPluginOptions
+): LazyPlugin;
+
+export function defineLazyPlugin(
+  pluginFactory: (() => WebspressoPlugin) | WebspressoPlugin,
+  lazyOptions?: LazyPluginOptions
+): LazyPlugin;
+
 export function adminPanelPlugin(options?: AdminPanelPluginOptions): WebspressoPlugin;
 
 export function dataExchangePlugin(options?: Record<string, unknown>): WebspressoPlugin;
@@ -3142,11 +3198,14 @@ export interface ApiContext<TBody = any, TParams = Record<string, string>, TQuer
   query: TQuery;
   body: TBody;
   input: { body?: TBody; params?: TParams; query?: TQuery; headers?: Record<string, string> };
+  locale: string;
+  t: Translator;
   service: WebspressoServiceCaller;
   module: string | null;
   config: Record<string, unknown>;
   logger: Console;
   db: unknown;
+  sse?: (sourceOrOptions?: any, maybeOptions?: any) => any;
 }
 
 export interface DefineApiOptions<TResult = any, TBody = any, TParams = Record<string, string>, TQuery = Record<string, string>> {
@@ -3213,7 +3272,21 @@ export function scanRoutes(options?: {
   pages?: boolean | { dir?: string; prefix?: string };
   api?: boolean | { dir?: string; prefix?: string };
   modules?: boolean | { dir?: string };
-}): RouteDescriptor[];
+}): RouteDescriptor[] & { scannedPagesFiles?: string[]; scannedPagesDir?: string | null };
+
+export function discoverAppRoutes(options?: {
+  rootDir?: string;
+  pages?: boolean | { dir?: string; prefix?: string };
+  api?: boolean | { dir?: string; prefix?: string };
+  modules?: boolean | { dir?: string };
+  routes?: Array<{ method?: string; path: string }>;
+  isDev?: boolean;
+}): {
+  descriptors: RouteDescriptor[];
+  routeTable: RouteTable;
+  scannedPagesFiles: string[];
+  scannedPagesDir: string | null;
+};
 
 export function parseFileRoute(
   relativePath: string,
@@ -3225,6 +3298,88 @@ export function compileRouteTable(
   options?: { explicitRoutes?: Array<{ method?: string; path: string }>; isDev?: boolean }
 ): RouteTable;
 
+export function generateRouteManifest(options?: {
+  rootDir?: string;
+  pages?: boolean | string | { dir?: string; prefix?: string };
+  api?: boolean | string | { dir?: string; prefix?: string };
+  modules?: boolean | { dir?: string };
+  pagesDir?: string;
+  outDir?: string;
+  outFile?: string;
+  silent?: boolean;
+}): {
+  manifest: {
+    version: number;
+    generatedAt: string;
+    pagesDirRel: string;
+    scannedPagesFiles: string[];
+    routes: Array<{
+      type: 'page' | 'api';
+      method: string;
+      path: string;
+      source: string;
+      module?: string | null;
+      moduleConfig?: { name?: string } | null;
+    }>;
+  };
+  manifestPath: string;
+  routeCount: number;
+  scannedFilesCount: number;
+};
+
+export function loadRouteManifest(options?: {
+  rootDir?: string;
+  manifestPath?: string;
+}): {
+  manifest: {
+    version: number;
+    generatedAt: string;
+    pagesDirRel: string;
+    scannedPagesFiles: string[];
+    routes: Array<{
+      type: 'page' | 'api';
+      method: string;
+      path: string;
+      source: string;
+      module?: string | null;
+      moduleConfig?: { name?: string } | null;
+    }>;
+  };
+  descriptors: RouteDescriptor[] & { scannedPagesFiles?: string[]; scannedPagesDir?: string | null };
+} | null;
+
+export function precompileTemplates(options?: {
+  rootDir?: string;
+  viewsDir?: string;
+  pagesDir?: string;
+  outDir?: string;
+  outFile?: string;
+  env?: any;
+}): {
+  templateCount: number;
+  manifestPath: string;
+  bundle: {
+    version: number;
+    generatedAt: string;
+    templates: Record<string, string>;
+    frontmatter: Record<string, any>;
+  };
+};
+
+export function loadPrecompiledTemplates(options?: {
+  rootDir?: string;
+  bundlePath?: string;
+}): {
+  loader: any;
+  templateCount: number;
+  bundle: {
+    version: number;
+    generatedAt: string;
+    templates: Record<string, string>;
+    frontmatter: Record<string, any>;
+  };
+} | null;
+
 export interface GenerateTypesOptions {
   /** Root directory of the project (default: process.cwd()) */
   rootDir?: string;

package/index.js

@@ -58,13 +58,21 @@ const {
 const { definePage } = require('./src/pages/define-page');
 const { defineApi } = require('./src/api/define-api');
 const { defineModule } = require('./src/modules/define-module');
-const { scanRoutes } = require('./src/discovery/scan-routes');
+const { scanRoutes, discoverAppRoutes } = require('./src/discovery/scan-routes');
+const { generateRouteManifest, loadRouteManifest } = require('./src/discovery/route-manifest');
+const { precompileTemplates, loadPrecompiledTemplates } = require('./src/template/precompile');
 const { parseFileRoute } = require('./src/discovery/file-route-parser');
 const { compileRouteTable, RouteTable } = require('./src/routing/route-table');
 const { mountDiscoveredRoutes } = require('./src/routing/mount-discovered-routes');
 
-// ORM exports (lazy loaded)
-const orm = require('./core/orm');
+// Lazy-loaded ORM accessor
+let _orm = null;
+function getOrm() {
+  if (!_orm) {
+    _orm = require('./core/orm');
+  }
+  return _orm;
+}
 
 // Lazy-loaded built-in plugins
 const plugins = require('./plugins');
@@ -99,12 +107,6 @@ module.exports = {
   discoverServices: require('./src/services').discoverServices,
   filePathToServiceName: require('./src/services').filePathToServiceName,
   toCamelCase: require('./src/services').toCamelCase,
-  createAuthServices: require('./src/services').createAuthServices,
-  createMailServices: require('./src/services').createMailServices,
-  createMediaServices: require('./src/services').createMediaServices,
-  createFileManagerServices: require('./src/services').createFileManagerServices,
-  createSystemServices: require('./src/services').createSystemServices,
-  createExchangeServices: require('./src/services').createExchangeServices,
   validateServiceInput: require('./src/services').validateServiceInput,
   executeService: require('./src/services').executeService,
 
@@ -171,12 +173,6 @@ module.exports = {
   createPluginManager,
   getPluginManager,
   resetPluginManager,
-  
-  // ORM
-  ...orm,
-
-  // Direct zdb export (for convenience)
-  zdb: orm.zdb,
 
   // Discovery, Pages, API, Modules & Routing primitives
   definePage,
@@ -186,11 +182,18 @@ module.exports = {
   defineModule,
   module: defineModule,
   scanRoutes,
+  discoverAppRoutes,
+  generateRouteManifest,
+  loadRouteManifest,
+  precompileTemplates,
+  loadPrecompiledTemplates,
   parseFileRoute,
   compileRouteTable,
   RouteTable,
   mountDiscoveredRoutes,
   resolveMiddlewares: require('./src/routing/middleware-resolver').resolveMiddlewares,
+  translateValidationIssues: require('./src/api/validation-i18n').translateValidationIssues,
+  getTranslatorForRequest: require('./src/api/validation-i18n').getTranslatorForRequest,
 
   // Forms & Flash subsystem (AdonisJS & Django-inspired)
   createFlashMiddleware: require('./core/forms').createFlashMiddleware,
@@ -218,10 +221,62 @@ module.exports = {
   loadListeners: require('./core/events').loadListeners,
 };
 
-// Define lazy getters for plugins and heavy core subsystems
+// Define lazy getters for plugins, ORM, and heavy core subsystems
 Object.defineProperties(module.exports, {
   ...Object.getOwnPropertyDescriptors(plugins),
 
+  // Built-in Services Creators (lazy loaded)
+  createAuthServices: { get: () => require('./src/services').createAuthServices, enumerable: true, configurable: true },
+  createMailServices: { get: () => require('./src/services').createMailServices, enumerable: true, configurable: true },
+  createMediaServices: { get: () => require('./src/services').createMediaServices, enumerable: true, configurable: true },
+  createFileManagerServices: { get: () => require('./src/services').createFileManagerServices, enumerable: true, configurable: true },
+  createSystemServices: { get: () => require('./src/services').createSystemServices, enumerable: true, configurable: true },
+  createExchangeServices: { get: () => require('./src/services').createExchangeServices, enumerable: true, configurable: true },
+
+  // ORM & Database Layer (lazy loaded)
+  orm: { get: () => getOrm(), enumerable: true, configurable: true },
+  createDatabase: { get: () => getOrm().createDatabase, enumerable: true, configurable: true },
+  createInMemoryDatabase: { get: () => getOrm().createInMemoryDatabase, enumerable: true, configurable: true },
+  defineModel: { get: () => getOrm().defineModel, enumerable: true, configurable: true },
+  zdb: { get: () => getOrm().zdb, enumerable: true, configurable: true },
+  BaseRepository: { get: () => getOrm().BaseRepository, enumerable: true, configurable: true },
+  Repository: { get: () => getOrm().Repository, enumerable: true, configurable: true },
+  createRepository: { get: () => getOrm().createRepository, enumerable: true, configurable: true },
+  getModel: { get: () => getOrm().getModel, enumerable: true, configurable: true },
+  getAllModels: { get: () => getOrm().getAllModels, enumerable: true, configurable: true },
+  hasModel: { get: () => getOrm().hasModel, enumerable: true, configurable: true },
+  clearRegistry: { get: () => getOrm().clearRegistry, enumerable: true, configurable: true },
+  isCascadeEnabled: { get: () => getOrm().isCascadeEnabled, enumerable: true, configurable: true },
+  extractColumnsFromSchema: { get: () => getOrm().extractColumnsFromSchema, enumerable: true, configurable: true },
+  getColumnMeta: { get: () => getOrm().getColumnMeta, enumerable: true, configurable: true },
+  generateNanoid: { get: () => getOrm().generateNanoid, enumerable: true, configurable: true },
+  zodNanoid: { get: () => getOrm().zodNanoid, enumerable: true, configurable: true },
+  extendZ: { get: () => getOrm().extendZ, enumerable: true, configurable: true },
+  omitHiddenColumns: { get: () => getOrm().omitHiddenColumns, enumerable: true, configurable: true },
+  sanitizeForOutput: { get: () => getOrm().sanitizeForOutput, enumerable: true, configurable: true },
+  ModelEvents: { get: () => getOrm().ModelEvents, enumerable: true, configurable: true },
+  Hooks: { get: () => getOrm().Hooks, enumerable: true, configurable: true },
+  HookCancellationError: { get: () => getOrm().HookCancellationError, enumerable: true, configurable: true },
+  createEventContext: { get: () => getOrm().createEventContext, enumerable: true, configurable: true },
+  getTransactionContext: { get: () => getOrm().getTransactionContext, enumerable: true, configurable: true },
+  createTransactionContext: { get: () => getOrm().createTransactionContext, enumerable: true, configurable: true },
+  runTransaction: { get: () => getOrm().runTransaction, enumerable: true, configurable: true },
+  createSchemaHelpers: { get: () => getOrm().createSchemaHelpers, enumerable: true, configurable: true },
+  loadRelations: { get: () => getOrm().loadRelations, enumerable: true, configurable: true },
+  loadRelation: { get: () => getOrm().loadRelation, enumerable: true, configurable: true },
+  parseRelationTree: { get: () => getOrm().parseRelationTree, enumerable: true, configurable: true },
+  QueryComplexityError: { get: () => getOrm().QueryComplexityError, enumerable: true, configurable: true },
+  validateQueryComplexity: { get: () => getOrm().validateQueryComplexity, enumerable: true, configurable: true },
+  resolveQueryLimits: { get: () => getOrm().resolveQueryLimits, enumerable: true, configurable: true },
+  DEFAULT_QUERY_LIMITS: { get: () => getOrm().DEFAULT_QUERY_LIMITS, enumerable: true, configurable: true },
+  buildSearchClause: { get: () => getOrm().buildSearchClause, enumerable: true, configurable: true },
+  tokenizeSearchTerm: { get: () => getOrm().tokenizeSearchTerm, enumerable: true, configurable: true },
+  detectDialect: { get: () => getOrm().detectDialect, enumerable: true, configurable: true },
+  defineFactory: { get: () => getOrm().defineFactory, enumerable: true, configurable: true },
+  FactoryBuilder: { get: () => getOrm().FactoryBuilder, enumerable: true, configurable: true },
+  diffSchema: { get: () => getOrm().diffSchema, enumerable: true, configurable: true },
+  makeMigrations: { get: () => getOrm().makeMigrations, enumerable: true, configurable: true },
+
   // Cascading Middleware & Layouts
   cascading: { get: () => require('./src/routing/cascading'), enumerable: true, configurable: true },
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webspresso",
-  "version": "0.0.101",
+  "version": "0.0.102",
   "description": "Minimal, production-ready SSR framework for Node.js with file-based routing, Nunjucks templating, built-in i18n, and CLI tooling",
   "main": "index.js",
   "types": "index.d.ts",
@@ -47,21 +47,21 @@
     "test:services": "vitest run tests/**/service*",
     "test:plugins": "vitest run tests/**/plugin* tests/unit/*plugin*.test.js",
     "test:core": "vitest run tests/unit/core* tests/unit/server* tests/unit/routing* tests/unit/template*",
-    "test:branches": "vitest run tests/unit/*branches.test.js",
-    "test:fast": "vitest run tests/unit/*branches.test.js tests/unit/auth.test.js tests/unit/services.test.js tests/unit/server.test.js",
+    "test:branches": "vitest run tests/unit/*scenarios*.test.js tests/unit/*branches*.test.js",
+    "test:fast": "vitest run tests/unit/*scenarios*.test.js tests/unit/*branches*.test.js tests/unit/auth.test.js tests/unit/services.test.js tests/unit/server.test.js",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "test:coverage:quick": "vitest run --coverage",
     "test:coverage:changed": "vitest run --coverage --changed",
     "test:coverage:full": "FULL_REPORT=true vitest run --coverage",
-    "test:coverage:branches": "vitest run tests/unit/*branches.test.js --coverage",
+    "test:coverage:branches": "vitest run tests/unit/*scenarios*.test.js tests/unit/*branches*.test.js --coverage",
     "test:coverage:unit": "vitest run tests/unit/ --coverage",
     "test:coverage:core": "vitest run tests/unit/core* tests/unit/server* tests/unit/routing* tests/unit/template* --coverage",
     "test:coverage:auth": "vitest run tests/**/auth* tests/unit/server-auth-branches.test.js --coverage",
     "test:coverage:orm": "vitest run tests/**/orm* tests/**/database* --coverage",
     "test:coverage:services": "vitest run tests/**/service* --coverage",
     "test:coverage:plugins": "vitest run tests/**/plugin* tests/unit/*plugin*.test.js --coverage",
-    "test:coverage:fast": "vitest run tests/unit/*branches.test.js tests/unit/auth.test.js tests/unit/services.test.js tests/unit/server.test.js --coverage",
+    "test:coverage:fast": "vitest run tests/unit/*scenarios*.test.js tests/unit/*branches*.test.js tests/unit/auth.test.js tests/unit/services.test.js tests/unit/server.test.js --coverage",
     "test:e2e": "playwright test",
     "test:e2e:ui": "playwright test --ui",
     "test:e2e:debug": "playwright test --debug",

package/plugins/admin-panel/index.js

@@ -55,8 +55,20 @@ function adminPanelPlugin(options = {}) {
     richTextSanitize = true,
     dataExchange: dataExchangeOption = true,
     loginRateLimit,
+    lazy: lazyOption,
   } = options;
 
+  if (lazyOption) {
+    const { lazyPlugin } = require('../lazy');
+    const lazyOpts = typeof lazyOption === 'object' ? lazyOption : {};
+    return lazyPlugin(() => adminPanelPlugin({ ...options, lazy: false }), {
+      name: 'admin-panel',
+      prefix: adminPath,
+      services: ['exchange.export', 'exchange.import'],
+      ...lazyOpts,
+    });
+  }
+
   const adminUsersConfig = typeof adminUsersOption === 'object' ? adminUsersOption : { enabled: adminUsersOption !== false };
 
   // Validate required options

package/plugins/csrf/index.js

@@ -199,7 +199,7 @@ function csrfPlugin(options = {}) {
 
         if (!submitted || !safeCompare(submitted, csrfTokenValue)) {
           res.status(errorStatus);
-          if (req.accepts('html') && !req.path.startsWith('/api')) {
+          if (typeof req.accepts === 'function' && req.accepts('html') && !req.path.startsWith('/api')) {
             return res.send(`<h1>${errorStatus} Forbidden</h1><p>${errorMessage}</p>`);
           } else {
             return res.json({ error: errorMessage });

package/plugins/file-manager/index.js

@@ -44,8 +44,21 @@ function fileManagerPlugin(options = {}) {
     permissions = null,
     security: securityOpts = { validateMagicBytes: true, sanitizeSvg: true },
     includePage = true,
+    lazy: lazyOption,
   } = options;
 
+  if (lazyOption) {
+    const { lazyPlugin } = require('../lazy');
+    const lazyOpts = typeof lazyOption === 'object' ? lazyOption : {};
+    return lazyPlugin(() => fileManagerPlugin({ ...options, lazy: false }), {
+      name: 'file-manager',
+      prefix: apiPrefix,
+      services: ['file-manager.list', 'file-manager.upload', 'file-manager.delete', 'file-manager.create-folder'],
+      dependencies: { 'admin-panel': '*' },
+      ...lazyOpts,
+    });
+  }
+
   const resolvedBaseDir = path.resolve(baseDir);
 
   const handlers = createFileManagerApiHandlers({

package/plugins/index.js

@@ -61,6 +61,8 @@ module.exports = {
   get createApiKeyMiddleware() { return require('./api-key').createApiKeyMiddleware; },
   get webhooksPlugin() { return require('./webhooks').webhooksPlugin; },
   get WebhookDispatcher() { return require('./webhooks').WebhookDispatcher; },
+  get lazyPlugin() { return require('./lazy').lazyPlugin; },
+  get defineLazyPlugin() { return require('./lazy').defineLazyPlugin; },
 };