@jay-framework/stack-server-runtime 0.9.0 → 0.11.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,24 @@ 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>;
+}
+interface LoadPagePartsOptions {
+    /**
+     * Path to pre-rendered jay-html file to use instead of the original.
+     * When provided, this file (with slow-phase bindings resolved) is read.
+     * Import resolution still uses the original jay-html's directory.
+     */
+    preRenderedPath?: string;
+}
+declare function loadPageParts(vite: ViteDevServer, route: JayRoute, pagesBase: string, projectBase: string, jayRollupConfig: JayRollupConfig, options?: LoadPagePartsOptions): Promise<WithValidations<LoadedPageParts>>;
 
 interface SlowlyChangingPhase {
     runSlowlyForPage(pageParams: object, pageProps: PageProps, parts: Array<DevServerPagePart>): Promise<AnySlowlyRenderResult>;
@@ -26,7 +44,395 @@ declare function runSlowlyChangingRender<Refs extends object, SlowVS extends obj
 
 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;
+/**
+ * Executes an action directly with proper service injection.
+ * Use this when calling actions from backend code (e.g., render phases).
+ *
+ * Unlike calling the action directly (which bypasses service injection),
+ * this function resolves services and calls the handler correctly.
+ *
+ * @param action - The JayAction to execute (with definition metadata)
+ * @param input - The input data for the action
+ * @returns The action result (throws on error)
+ *
+ * @example
+ * ```typescript
+ * // In a render phase
+ * import { runAction } from '@jay-framework/stack-server-runtime';
+ * import { searchProducts } from '../actions/stores-actions';
+ *
+ * async function renderFastChanging(props, slowCarryForward, wixStores) {
+ *     // ✅ Correct - services are injected
+ *     const result = await runAction(searchProducts, { query: '', pageSize: 12 });
+ *
+ *     // ❌ Wrong - services are NOT injected (passes empty array)
+ *     // const result = await searchProducts({ query: '', pageSize: 12 });
+ * }
+ * ```
+ */
+declare function runAction<I, O>(action: JayAction<I, O> & JayActionDefinition<I, O, any[]>, input: I): Promise<O>;
+
+/**
+ * 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/).
+ * Also discovers transitive plugin dependencies (plugins that depend on other plugins).
+ */
+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;
+}
+/**
+ * Options for client script generation.
+ */
+interface GenerateClientScriptOptions {
+    /** Enable automation integration (default: true in dev mode) */
+    enableAutomation?: boolean;
+    /**
+     * Slow ViewState that was baked into the pre-rendered jay-html.
+     * When provided, this is merged with fastViewState for the automation API
+     * so that AI/automation tools can see the complete page state.
+     */
+    slowViewState?: object;
+}
+declare function generateClientScript(defaultViewState: object, fastCarryForward: object, parts: DevServerPagePart[], jayHtmlPath: string, trackByMap?: TrackByMap, clientInitData?: Record<string, Record<string, any>>, projectInit?: ProjectClientInitInfo, pluginInits?: PluginClientInitInfo[], options?: GenerateClientScriptOptions): string;
 
 /**
  * Service registry for Jay Stack server-side dependency injection.
@@ -144,5 +550,131 @@ 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;
+
+/**
+ * Cache entry for pre-rendered jay-html
+ */
+interface SlowRenderCacheEntry {
+    /** Path to the pre-rendered jay-html file on disk */
+    preRenderedPath: string;
+    /** Slow ViewState that was baked into the jay-html */
+    slowViewState: object;
+    /** CarryForward data from slow rendering (passed to fast phase) */
+    carryForward: object;
+    /** Timestamp when this entry was created */
+    createdAt: number;
+    /** Source jay-html path (for debugging) */
+    sourcePath: string;
+}
+/**
+ * Cache for pre-rendered jay-html files.
+ *
+ * This cache stores jay-html content that has been transformed with slow-phase
+ * data baked in. The key insight is that since slow ViewState is embedded directly
+ * into the jay-html, we don't need to pass it to the client - only fast and
+ * interactive ViewState is sent.
+ *
+ * Pre-rendered files are written to disk so Vite can pick them up and compile them.
+ */
+declare class SlowRenderCache {
+    private cache;
+    private pathToKeys;
+    private readonly cacheDir;
+    private readonly pagesRoot;
+    /**
+     * @param cacheDir - Directory where pre-rendered jay-html files are stored
+     * @param pagesRoot - Root directory of the pages (for relative path calculation)
+     */
+    constructor(cacheDir: string, pagesRoot: string);
+    /**
+     * Get a cached pre-rendered jay-html entry
+     */
+    get(jayHtmlPath: string, params: Record<string, string>): SlowRenderCacheEntry | undefined;
+    /**
+     * Store a pre-rendered jay-html entry in the cache.
+     * Writes the pre-rendered content to disk and stores metadata in memory.
+     */
+    set(jayHtmlPath: string, params: Record<string, string>, preRenderedJayHtml: string, slowViewState: object, carryForward: object): Promise<string>;
+    /**
+     * Check if a pre-rendered entry exists for the given path and params
+     */
+    has(jayHtmlPath: string, params: Record<string, string>): boolean;
+    /**
+     * Invalidate all cached entries for a given jay-html source path.
+     * This is called when the source file changes.
+     * Also deletes the cached files from disk.
+     */
+    invalidate(jayHtmlPath: string): Promise<void>;
+    /**
+     * Invalidate all entries that depend on a changed file.
+     * The changedPath could be:
+     * - A jay-html file itself
+     * - A component file (page.ts)
+     * - Any other dependency
+     *
+     * @param changedPath - Absolute path to the changed file
+     * @param resolveDependencies - Optional function to resolve which jay-html files depend on the changed file
+     */
+    invalidateByDependency(changedPath: string, resolveDependencies?: (changedPath: string) => string[]): Promise<void>;
+    /**
+     * Clear all cached entries and delete cached files from disk
+     */
+    clear(): Promise<void>;
+    /**
+     * Get the number of cached entries
+     */
+    get size(): number;
+    /**
+     * Get all cached jay-html paths (for debugging/monitoring)
+     */
+    getCachedPaths(): string[];
+}
 
-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 GenerateClientScriptOptions, type LoadedPageParts, type PluginActionDiscoveryOptions, type PluginClientInitInfo, type PluginInitDiscoveryOptions, type PluginWithInit, type ProjectClientInitInfo, type RegisteredAction, SlowRenderCache, type SlowRenderCacheEntry, 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, runAction, runInitCallbacks, runLoadParams, runShutdownCallbacks, runSlowlyChangingRender, setClientInitData, sortPluginsByDependencies };