@gzl10/nexus-backend 0.17.0 → 0.18.0

package/dist/index.d.ts

@@ -1,9 +1,10 @@
-import http from 'node:http';
+import * as http from 'node:http';
+import http__default from 'node:http';
 import { Express, Request, Response, Router, NextFunction, RequestHandler } from 'express';
 export { Express } from 'express';
 import { AbilityBuilder, MongoAbility, RawRuleOf } from '@casl/ability';
 import * as _gzl10_nexus_sdk from '@gzl10/nexus-sdk';
-import { PluginManifest, ModuleManifest, EntityQuery, PaginatedResult, EntityDefinition, ModuleContext, CreateEntityServiceOptions, BaseEntityService as BaseEntityService$1, EntityServiceHooks, CollectionEntityDefinition, SingleEntityDefinition, ViewEntityDefinition, ExternalEntityDefinition, ComputedEntityDefinition, TreeEntityDefinition, DagEntityDefinition, EntityChangePayload, BridgeRule, ValidateSchemas, SSESender, SSEHelper } from '@gzl10/nexus-sdk';
+import { PluginManifest, ModuleManifest, LocaleConfig, SeedContext, EntityQuery, PaginatedResult, EntityDefinition, ModuleContext, CreateEntityServiceOptions, BaseEntityService as BaseEntityService$1, EntityServiceHooks, CollectionEntityDefinition, SingleEntityDefinition, ViewEntityDefinition, ExternalEntityDefinition, ComputedEntityDefinition, TreeEntityDefinition, DagEntityDefinition, EntityChangePayload, BridgeRule, ValidateSchemas, SSESender, SSEHelper } from '@gzl10/nexus-sdk';
 export { AuthRequest, AuthorizationParams, Category, ContextHelpers, CookieOptions, DomainFilterOptions, DomainFilterResult, EntityDefinition, EntityQuery, IdTokenClaims, ModuleAbilities, ModuleContext, ModuleManifest, ModuleMiddlewares, ModuleRequirements, NextFunction, OidcClient, OidcDiscoveryDocument, OidcState, OidcTokens, OidcUserInfo, PaginatedResult, PaginationParams, PluginManifest, Request, RequestHandler, Response, Router, SessionResult, StateManager, TokenExchangeParams, TokenValidationConfig, ValidateSchemas, assertAllowedDomain, checkAllowedDomain, createOidcClient, createStateManager, entityRoom, getOidcClient } from '@gzl10/nexus-sdk';
 import * as express_serve_static_core from 'express-serve-static-core';
 import * as knex from 'knex';
@@ -56,7 +57,9 @@ interface ServeSPAOptions {
  * serveSPA('/admin', '../admin/dist', { maxAge: '7d', immutable: true })
  * ```
  */
-type ServeSPAFunction = (endpoint: string, distPath: string, options?: ServeSPAOptions) => void;
+type ServeSPAFunction = (endpoint: string, distPath: string, options?: ServeSPAOptions & {
+    viteSrc?: string;
+}) => void | Promise<void>;
 /**
  * Configuration for a frontend SPA.
  *
@@ -89,6 +92,15 @@ interface SpaEntry extends ServeSPAOptions {
     path?: string;
     /** Origin URL for CORS allowlist. Required for external SPAs; optional for served SPAs with a custom domain. */
     origin?: string;
+    /**
+     * Path to frontend source directory (dev only).
+     * When set in development, mounts Vite dev server as middleware with HMR instead of serving static files.
+     * Ignored in production — uses `path` for static files.
+     * Requires `endpoint` to be set. Requires `vite` as a peer dependency.
+     *
+     * @example { endpoint: '/', viteSrc: '../ui', path: '../ui/dist' }
+     */
+    viteSrc?: string;
 }
 /**
  * Discovered plugins and modules.
@@ -110,6 +122,8 @@ interface NexusConfig {
      * Auto-discovered from src/modules/ + passed programmatically to start().
      */
     modules?: ModuleManifest[];
+    /** Supported locales. Default: DEFAULT_LOCALES (en + es) */
+    locales?: LocaleConfig[];
 }
 /**
  * Runtime options for `start()`.
@@ -147,10 +161,52 @@ interface StartOptions extends NexusConfig {
         [eventName: string]: ((data: any) => void | Promise<void>) | undefined;
     };
     /**
-     * Function to define additional CASL rules.
-     * Runs after loading permissions from the DB.
+     * Advanced CASL rules for cases not covered by `seed.roles.add({ permissions })`.
+     * Runs as step 3 in the ability factory (after entity definition permissions).
+     *
+     * **Prefer `onSeed` → `seed.roles.add({ permissions })` for simple role-based permissions.**
+     * Use `casl` only when you need:
+     * - Conditions: `can('update', 'Post', { authorId: user.id })`
+     * - Field-level: `can('read', 'User', ['name', 'email'])`
+     * - Denials: `cannot('delete', 'User')`
+     * - Dynamic logic based on user properties
+     *
+     * @example
+     * ```typescript
+     * casl: (user, { can, cannot }) => {
+     *   if ((user as any).roleNames?.includes('EDITOR')) {
+     *     can('update', 'Post', { authorId: (user as any).id })
+     *     cannot('delete', 'Post')
+     *   }
+     * }
+     * ```
      */
     casl?: CaslRulesFunction;
+    /**
+     * Callback executed after all module seeds have run.
+     * Receives a `SeedContext` with typed helpers — no direct DB access needed.
+     *
+     * - `seed.masters.register()` — lazy, flushed after callback completes
+     * - `seed.roles.add()` — eager, supports `permissions` for CASL assignment
+     * - `seed.users.add()` — eager, supports role assignment by name
+     * - `seed.plugin(name).entity(name).upsert()` — resolves table prefix automatically
+     * - `seed.raw()` — escape hatch for custom tables
+     *
+     * @example
+     * ```typescript
+     * onSeed: async (seed) => {
+     *   seed.masters.register('sources', [
+     *     { code: 'web', label: { en: 'Website', es: 'Sitio web' } }
+     *   ])
+     *   await seed.roles.add({
+     *     name: 'SALES',
+     *     permissions: { 'contacts': ['read', 'create', 'update'] }
+     *   })
+     *   await seed.users.add({ email: 'admin@acme.com', password: 'temp', roles: ['ADMIN'] })
+     * }
+     * ```
+     */
+    onSeed?: (seed: SeedContext) => void | Promise<void>;
     /**
      * Callback executed when the server is fully ready.
      * Runs after listen() and Socket.IO initialization.
@@ -198,9 +254,57 @@ interface ResolvedConfig {
     adminPassword?: string;
 }
 
-declare function start(config?: StartOptions): Promise<http.Server>;
+/**
+ * Starts the Nexus server.
+ *
+ * Lifecycle order:
+ * 1. Logger, DB, migrations
+ * 2. Module/plugin registration and seed
+ * 3. `onSeed` hook (SeedContext with typed helpers)
+ * 4. `beforeRoutes` hook → module routes → `afterRoutes` hook
+ * 5. HTTP listen + Socket.IO
+ * 6. `onReady` hook
+ *
+ * @param config - Optional startup configuration (plugins, modules, lifecycle hooks, SPAs)
+ * @returns The underlying `http.Server` instance
+ * @throws If the server is already running (call `stop()` first)
+ *
+ * @example
+ * ```typescript
+ * import { start } from '@gzl10/nexus-backend'
+ *
+ * const server = await start({
+ *   onSeed: async (seed) => {
+ *     await seed.roles.add({ name: 'SALES', permissions: { 'contacts': ['read', 'create'] } })
+ *   },
+ *   onReady: (_app, port) => console.log(`Ready on ${port}`)
+ * })
+ * ```
+ */
+declare function start(config?: StartOptions): Promise<http__default.Server>;
+/**
+ * Stops the Nexus server gracefully.
+ *
+ * Closes HTTP server, Socket.IO, database connections, and cleans up all state.
+ * Calls `beforeClose` hook if registered. Safe to call multiple times.
+ *
+ * @example
+ * ```typescript
+ * await stop() // server stopped, port freed
+ * ```
+ */
 declare function stop(): Promise<void>;
-declare function restart(config?: StartOptions): Promise<http.Server>;
+/**
+ * Restarts the Nexus server. Calls `stop()` then `start()`.
+ *
+ * If no config is provided, reuses the config from the previous `start()` call.
+ * Plugins, hooks, and SPAs are preserved across restarts.
+ *
+ * @param config - Optional new config. If omitted, reuses previous config.
+ * @returns The new `http.Server` instance
+ */
+declare function restart(config?: StartOptions): Promise<http__default.Server>;
+/** Returns `true` if the server is currently running. */
 declare function isRunning(): boolean;
 
 interface CreateAppOptions {
@@ -208,6 +312,8 @@ interface CreateAppOptions {
     afterRoutes?: (app: Express, serveSPA: ServeSPAFunction) => void | Promise<void>;
     /** Declarative SPA entries (served + CORS). Passed from StartOptions.spas. */
     spas?: SpaEntry[];
+    /** HTTP server for Vite HMR WebSocket (shared with Socket.IO) */
+    httpServer?: http.Server;
 }
 declare function createApp(options?: CreateAppOptions): Promise<express_serve_static_core.Express>;