@jay-framework/stack-server-runtime 0.8.0 → 0.10.0

package/dist/index.d.ts

@@ -1,9 +1,10 @@
-import { AnyJayStackComponentDefinition, PageProps, AnySlowlyRenderResult, UrlParams, JayStackComponentDefinition, AnyFastRenderResult, ServiceMarker } from '@jay-framework/fullstack-component';
+import { AnyJayStackComponentDefinition, PageProps, AnySlowlyRenderResult, UrlParams, JayStackComponentDefinition, AnyFastRenderResult, HttpMethod, CacheOptions, JayAction, JayActionDefinition, ServiceMarker } from '@jay-framework/fullstack-component';
 import { JayComponentCore } from '@jay-framework/component';
 import { ViteDevServer } from 'vite';
 import { JayRoute } from '@jay-framework/stack-route-scanner';
 import { WithValidations } from '@jay-framework/compiler-shared';
 import { JayRollupConfig } from '@jay-framework/rollup-plugin';
+import { TrackByMap } from '@jay-framework/view-state-merge';
 
 interface DevServerPagePart {
     compDefinition: AnyJayStackComponentDefinition;
@@ -11,7 +12,16 @@ interface DevServerPagePart {
     clientImport: string;
     clientPart: string;
 }
-declare function loadPageParts(vite: ViteDevServer, route: JayRoute, pagesBase: string, jayRollupConfig: JayRollupConfig): Promise<WithValidations<DevServerPagePart[]>>;
+interface LoadedPageParts {
+    parts: DevServerPagePart[];
+    /** TrackBy map for server-side merge (slow → fast) */
+    serverTrackByMap?: Record<string, string>;
+    /** TrackBy map for client-side merge (fast → interactive) */
+    clientTrackByMap?: Record<string, string>;
+    /** NPM package names used on this page (for filtering plugin inits) */
+    usedPackages: Set<string>;
+}
+declare function loadPageParts(vite: ViteDevServer, route: JayRoute, pagesBase: string, projectBase: string, jayRollupConfig: JayRollupConfig): Promise<WithValidations<LoadedPageParts>>;
 
 interface SlowlyChangingPhase {
     runSlowlyForPage(pageParams: object, pageProps: PageProps, parts: Array<DevServerPagePart>): Promise<AnySlowlyRenderResult>;
@@ -21,12 +31,359 @@ declare class DevSlowlyChangingPhase implements SlowlyChangingPhase {
     constructor(dontCacheSlowly: boolean);
     runSlowlyForPage(pageParams: UrlParams, pageProps: PageProps, parts: Array<DevServerPagePart>): Promise<AnySlowlyRenderResult>;
 }
-declare function runLoadParams<StaticViewState extends object, ViewState extends object, Refs extends object, Services extends Array<any>, Contexts extends Array<any>, PropsT extends object, Params extends UrlParams, CompCore extends JayComponentCore<PropsT, ViewState>>(compDefinition: JayStackComponentDefinition<StaticViewState, ViewState, Refs, Services, Contexts, PropsT, Params, CompCore>, services: Services): Promise<void>;
-declare function runSlowlyChangingRender<StaticViewState extends object, ViewState extends object, Refs extends object, Services extends Array<any>, Contexts extends Array<any>, PropsT extends object, Params extends UrlParams, CompCore extends JayComponentCore<PropsT, ViewState>>(compDefinition: JayStackComponentDefinition<StaticViewState, ViewState, Refs, Services, Contexts, PropsT, Params, CompCore>): void;
+declare function runLoadParams<Refs extends object, SlowVS extends object, FastVS extends object, InteractiveVS extends object, Services extends Array<any>, Contexts extends Array<any>, PropsT extends object, Params extends UrlParams, CompCore extends JayComponentCore<PropsT, InteractiveVS>>(compDefinition: JayStackComponentDefinition<Refs, SlowVS, FastVS, InteractiveVS, Services, Contexts, PropsT, Params, CompCore>, services: Services): Promise<void>;
+declare function runSlowlyChangingRender<Refs extends object, SlowVS extends object, FastVS extends object, InteractiveVS extends object, Services extends Array<any>, Contexts extends Array<any>, PropsT extends object, Params extends UrlParams, CompCore extends JayComponentCore<PropsT, InteractiveVS>>(compDefinition: JayStackComponentDefinition<Refs, SlowVS, FastVS, InteractiveVS, Services, Contexts, PropsT, Params, CompCore>): void;
 
 declare function renderFastChangingData(pageParams: object, pageProps: PageProps, carryForward: object, parts: Array<DevServerPagePart>): Promise<AnyFastRenderResult>;
 
-declare function generateClientScript(defaultViewState: object, fastCarryForward: object, parts: DevServerPagePart[], jayHtmlPath: string): string;
+/**
+ * Action registry for Jay Stack server-side action handling.
+ *
+ * Actions are registered at build/startup time and can be invoked via HTTP.
+ * The registry maps action names to their definitions (handler, services, method, etc.).
+ */
+
+/**
+ * Registered action entry with resolved metadata.
+ */
+interface RegisteredAction {
+    /** Unique action name */
+    actionName: string;
+    /** HTTP method */
+    method: HttpMethod;
+    /** Cache options (for GET requests) */
+    cacheOptions?: CacheOptions;
+    /** Service markers for dependency injection */
+    services: any[];
+    /** The handler function */
+    handler: (input: any, ...services: any[]) => Promise<any>;
+}
+/**
+ * Result of executing an action.
+ */
+type ActionExecutionResult<T> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: ActionErrorResponse;
+};
+/**
+ * Error response structure for failed actions.
+ */
+interface ActionErrorResponse {
+    code: string;
+    message: string;
+    isActionError: boolean;
+}
+/**
+ * Registry for Jay Stack server actions.
+ *
+ * Manages action registration, lookup, and execution.
+ * Create instances for testing or use the default export for production.
+ *
+ * @example
+ * ```typescript
+ * // For testing - create isolated instance
+ * const registry = new ActionRegistry();
+ * registry.register(myAction);
+ * const result = await registry.execute('my.action', input);
+ *
+ * // For production - use default instance
+ * import { actionRegistry } from '@jay-framework/stack-server-runtime';
+ * actionRegistry.register(myAction);
+ * ```
+ */
+declare class ActionRegistry {
+    private readonly actions;
+    /**
+     * Registers an action with the registry.
+     *
+     * @param action - The JayAction to register (created via makeJayAction/makeJayQuery)
+     */
+    register<I, O, S extends any[]>(action: JayAction<I, O> & JayActionDefinition<I, O, S>): void;
+    /**
+     * Retrieves a registered action by name.
+     *
+     * @param actionName - The unique action name
+     * @returns The registered action or undefined
+     */
+    get(actionName: string): RegisteredAction | undefined;
+    /**
+     * Checks if an action is registered.
+     *
+     * @param actionName - The unique action name
+     * @returns true if the action is registered
+     */
+    has(actionName: string): boolean;
+    /**
+     * Gets all registered action names.
+     *
+     * @returns Array of registered action names
+     */
+    getNames(): string[];
+    /**
+     * Clears all registered actions.
+     */
+    clear(): void;
+    /**
+     * Executes a registered action with the given input.
+     * Resolves services and calls the handler.
+     *
+     * @param actionName - The action to execute
+     * @param input - The input data for the action
+     * @returns The action result or error
+     */
+    execute<T = any>(actionName: string, input: unknown): Promise<ActionExecutionResult<T>>;
+    /**
+     * Gets the cache headers for an action (if applicable).
+     *
+     * @param actionName - The action name
+     * @returns Cache-Control header value or undefined
+     */
+    getCacheHeaders(actionName: string): string | undefined;
+}
+/**
+ * Default action registry instance.
+ * Use this for production; create new instances for testing.
+ */
+declare const actionRegistry: ActionRegistry;
+/**
+ * Registers an action with the default registry.
+ * @deprecated Use actionRegistry.register() instead
+ */
+declare function registerAction<I, O, S extends any[]>(action: JayAction<I, O> & JayActionDefinition<I, O, S>): void;
+/**
+ * Retrieves a registered action by name from the default registry.
+ * @deprecated Use actionRegistry.get() instead
+ */
+declare function getRegisteredAction(actionName: string): RegisteredAction | undefined;
+/**
+ * Checks if an action is registered in the default registry.
+ * @deprecated Use actionRegistry.has() instead
+ */
+declare function hasAction(actionName: string): boolean;
+/**
+ * Gets all registered action names from the default registry.
+ * @deprecated Use actionRegistry.getNames() instead
+ */
+declare function getRegisteredActionNames(): string[];
+/**
+ * Clears all registered actions from the default registry.
+ * @deprecated Use actionRegistry.clear() instead
+ */
+declare function clearActionRegistry(): void;
+/**
+ * Executes an action from the default registry.
+ * @deprecated Use actionRegistry.execute() instead
+ */
+declare function executeAction<T = any>(actionName: string, input: unknown): Promise<ActionExecutionResult<T>>;
+/**
+ * Gets cache headers for an action from the default registry.
+ * @deprecated Use actionRegistry.getCacheHeaders() instead
+ */
+declare function getActionCacheHeaders(actionName: string): string | undefined;
+
+/**
+ * Action discovery and auto-registration for Jay Stack.
+ *
+ * Scans project and plugin directories to discover and register actions
+ * automatically on server startup.
+ */
+
+/**
+ * Vite server interface for SSR module loading.
+ * Using a minimal interface to avoid direct Vite dependency.
+ */
+interface ViteSSRLoader {
+    ssrLoadModule: (url: string) => Promise<Record<string, any>>;
+}
+/**
+ * Options for action discovery.
+ */
+interface ActionDiscoveryOptions {
+    /** Project root directory */
+    projectRoot: string;
+    /** Custom actions directory (default: src/actions) */
+    actionsDir?: string;
+    /** Registry to register actions in (default: global actionRegistry) */
+    registry?: ActionRegistry;
+    /** Whether to log discovery progress */
+    verbose?: boolean;
+    /** Vite server for SSR module loading (required in dev for TypeScript files) */
+    viteServer?: ViteSSRLoader;
+}
+/**
+ * Result of action discovery.
+ */
+interface ActionDiscoveryResult {
+    /** Number of actions discovered and registered */
+    actionCount: number;
+    /** Names of registered actions */
+    actionNames: string[];
+    /** Paths of scanned action files */
+    scannedFiles: string[];
+}
+/**
+ * Discovers and registers actions from the project's actions directory.
+ *
+ * Scans `src/actions/*.actions.ts` for exported actions and registers them.
+ *
+ * @param options - Discovery options
+ * @returns Result with discovered action information
+ *
+ * @example
+ * ```typescript
+ * // In dev-server startup
+ * const result = await discoverAndRegisterActions({
+ *     projectRoot: process.cwd(),
+ *     verbose: true,
+ * });
+ * console.log(`Registered ${result.actionCount} actions`);
+ * ```
+ */
+declare function discoverAndRegisterActions(options: ActionDiscoveryOptions): Promise<ActionDiscoveryResult>;
+/**
+ * Options for discovering plugin actions.
+ */
+interface PluginActionDiscoveryOptions {
+    /** Project root directory */
+    projectRoot: string;
+    /** Registry to register actions in (default: global actionRegistry) */
+    registry?: ActionRegistry;
+    /** Whether to log discovery progress */
+    verbose?: boolean;
+    /** Vite server for SSR module loading (required in dev for TypeScript files) */
+    viteServer?: ViteSSRLoader;
+}
+/**
+ * Discovers and registers actions from all plugins in a project.
+ *
+ * Scans both local plugins (src/plugins/) and installed NPM plugins.
+ *
+ * @param options - Discovery options
+ * @returns Array of registered action names
+ */
+declare function discoverAllPluginActions(options: PluginActionDiscoveryOptions): Promise<string[]>;
+/**
+ * Discovers actions from a single plugin's plugin.yaml file.
+ *
+ * Reads plugin.yaml, finds the `actions` array, and imports those
+ * named exports from the plugin's module.
+ *
+ * @param pluginPath - Path to the plugin directory (containing plugin.yaml)
+ * @param projectRoot - Project root for resolving imports
+ * @param registry - Registry to register actions in
+ * @param verbose - Whether to log progress
+ * @returns Array of registered action names
+ */
+declare function discoverPluginActions(pluginPath: string, projectRoot: string, registry?: ActionRegistry, verbose?: boolean, viteServer?: ViteSSRLoader): Promise<string[]>;
+
+/**
+ * Plugin initialization discovery and execution for Jay Stack.
+ *
+ * Discovers plugins with init configurations (using makeJayInit pattern),
+ * sorts them by dependencies, and executes their init functions in order.
+ *
+ * Auto-discovers `lib/init.ts` files in plugins, or uses the path specified
+ * in `plugin.yaml` via the `init` property.
+ */
+
+/**
+ * Information about a discovered plugin with init.
+ */
+interface PluginWithInit {
+    /** Plugin name from plugin.yaml (used as default init key) */
+    name: string;
+    /** Plugin path (directory containing plugin.yaml) */
+    pluginPath: string;
+    /** Package name for NPM plugins, or path for local plugins */
+    packageName: string;
+    /** Whether this is a local plugin (src/plugins/) or NPM */
+    isLocal: boolean;
+    /**
+     * Init module path relative to plugin root.
+     * Default is 'lib/init' (auto-discovered).
+     * Can be overridden via `init` property in plugin.yaml.
+     */
+    initModule: string;
+    /**
+     * Export name for the init constant.
+     * Default is 'init'.
+     * Can be overridden via `init` property in plugin.yaml (for compiled packages).
+     */
+    initExport: string;
+    /** Dependencies from package.json (for ordering) */
+    dependencies: string[];
+}
+/**
+ * Options for plugin init discovery.
+ */
+interface PluginInitDiscoveryOptions {
+    /** Project root directory */
+    projectRoot: string;
+    /** Whether to log discovery progress */
+    verbose?: boolean;
+}
+/**
+ * Discovers all plugins with init configurations.
+ *
+ * Auto-discovers `lib/init.ts` files in plugins, or uses the path specified
+ * in `plugin.yaml` via the `init` property.
+ *
+ * Scans both local plugins (src/plugins/) and NPM plugins (node_modules/).
+ */
+declare function discoverPluginsWithInit(options: PluginInitDiscoveryOptions): Promise<PluginWithInit[]>;
+/**
+ * Sorts plugins by their dependencies (topological sort).
+ * Plugins with no dependencies come first, then plugins that depend on them, etc.
+ */
+declare function sortPluginsByDependencies(plugins: PluginWithInit[]): PluginWithInit[];
+/**
+ * Executes server init for all plugins in order.
+ *
+ * Uses the `makeJayInit` pattern:
+ * - Loads the init module and finds the JayInit object
+ * - Calls `_serverInit()` if defined
+ * - Stores returned data via `setClientInitData(pluginName, data)`
+ *
+ * @param plugins - Sorted list of plugins with init
+ * @param viteServer - Vite server for SSR module loading (optional)
+ * @param verbose - Whether to log progress
+ */
+declare function executePluginServerInits(plugins: PluginWithInit[], viteServer?: ViteSSRLoader, verbose?: boolean): Promise<void>;
+/**
+ * Information needed to generate client init script for a plugin.
+ */
+interface PluginClientInitInfo {
+    /** Plugin name (used for logging and as data key) */
+    name: string;
+    /** Import path for the init module */
+    importPath: string;
+    /** Export name for the JayInit constant */
+    initExport: string;
+}
+/**
+ * Prepares plugin information for client init script generation.
+ *
+ * For LOCAL plugins: Use the init file path directly
+ * For NPM plugins: Use the `/client` subpath (client bundle exports init)
+ *
+ * Filters to only plugins that have init modules and returns the
+ * information needed to generate client-side imports and execution.
+ */
+declare function preparePluginClientInits(plugins: PluginWithInit[]): PluginClientInitInfo[];
+
+/**
+ * Information needed to generate client init script for the project.
+ */
+interface ProjectClientInitInfo {
+    /** Import path for the init module */
+    importPath: string;
+    /** Export name for the JayInit constant (default: 'init') */
+    initExport?: string;
+}
+declare function generateClientScript(defaultViewState: object, fastCarryForward: object, parts: DevServerPagePart[], jayHtmlPath: string, trackByMap?: TrackByMap, clientInitData?: Record<string, Record<string, any>>, projectInit?: ProjectClientInitInfo, pluginInits?: PluginClientInitInfo[]): string;
 
 /**
  * Service registry for Jay Stack server-side dependency injection.
@@ -144,5 +501,52 @@ declare function runShutdownCallbacks(): Promise<void>;
  * Internal API used by dev-server during hot reload.
  */
 declare function clearLifecycleCallbacks(): void;
+/**
+ * Sets client init data for a specific namespace (plugin or project).
+ * Each namespace's data is kept separate and passed only to the matching
+ * client init callback.
+ *
+ * @param key - Namespace key (plugin name or 'project')
+ * @param data - Data object for this namespace
+ *
+ * @example
+ * ```typescript
+ * // In plugin server init
+ * onInit(async () => {
+ *   setClientInitData('wix-stores', {
+ *     currency: 'USD',
+ *     apiEndpoint: process.env.STORES_API_URL,
+ *   });
+ * });
+ *
+ * // In project jay.init.ts
+ * onInit(async () => {
+ *   setClientInitData('project', {
+ *     oauthClientId: process.env.OAUTH_CLIENT_ID,
+ *     featureFlags: await loadFeatureFlags(),
+ *   });
+ * });
+ * ```
+ */
+declare function setClientInitData(key: string, data: Record<string, any>): void;
+/**
+ * Gets all namespaced client init data.
+ * Internal API used by page rendering to embed data in HTML.
+ *
+ * @returns Object with namespace keys and their data
+ */
+declare function getClientInitData(): Record<string, Record<string, any>>;
+/**
+ * Gets client init data for a specific namespace.
+ *
+ * @param key - Namespace key
+ * @returns Data for that namespace, or empty object if not set
+ */
+declare function getClientInitDataForKey(key: string): Record<string, any>;
+/**
+ * Clears client init data.
+ * Internal API used by dev-server during hot reload.
+ */
+declare function clearClientInitData(): void;
 
-export { DevSlowlyChangingPhase, type SlowlyChangingPhase, clearLifecycleCallbacks, clearServiceRegistry, generateClientScript, getService, hasService, loadPageParts, onInit, onShutdown, registerService, renderFastChangingData, resolveServices, runInitCallbacks, runLoadParams, runShutdownCallbacks, runSlowlyChangingRender };
+export { type ActionDiscoveryOptions, type ActionDiscoveryResult, type ActionErrorResponse, type ActionExecutionResult, ActionRegistry, type DevServerPagePart, DevSlowlyChangingPhase, type LoadedPageParts, type PluginActionDiscoveryOptions, type PluginClientInitInfo, type PluginInitDiscoveryOptions, type PluginWithInit, type ProjectClientInitInfo, type RegisteredAction, type SlowlyChangingPhase, type ViteSSRLoader, actionRegistry, clearActionRegistry, clearClientInitData, clearLifecycleCallbacks, clearServiceRegistry, discoverAllPluginActions, discoverAndRegisterActions, discoverPluginActions, discoverPluginsWithInit, executeAction, executePluginServerInits, generateClientScript, getActionCacheHeaders, getClientInitData, getClientInitDataForKey, getRegisteredAction, getRegisteredActionNames, getService, hasAction, hasService, loadPageParts, onInit, onShutdown, preparePluginClientInits, registerAction, registerService, renderFastChangingData, resolveServices, runInitCallbacks, runLoadParams, runShutdownCallbacks, runSlowlyChangingRender, setClientInitData, sortPluginsByDependencies };