@jay-framework/stack-server-runtime 0.7.0 → 0.9.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { AnyJayStackComponentDefinition, PageProps, AnySlowlyRenderResult, UrlParams, JayStackComponentDefinition, AnyFastRenderResult } from '@jay-framework/fullstack-component';
+import { AnyJayStackComponentDefinition, PageProps, AnySlowlyRenderResult, UrlParams, JayStackComponentDefinition, AnyFastRenderResult, ServiceMarker } from '@jay-framework/fullstack-component';
 import { JayComponentCore } from '@jay-framework/component';
 import { ViteDevServer } from 'vite';
 import { JayRoute } from '@jay-framework/stack-route-scanner';
@@ -21,11 +21,128 @@ 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, ServerContexts extends Array<any>, ClientContexts extends Array<any>, PropsT extends object, Params extends UrlParams, CompCore extends JayComponentCore<PropsT, ViewState>>(compDefinition: JayStackComponentDefinition<StaticViewState, ViewState, Refs, ServerContexts, ClientContexts, PropsT, Params, CompCore>, serverContexts: ServerContexts): Promise<void>;
-declare function runSlowlyChangingRender<StaticViewState extends object, ViewState extends object, Refs extends object, ServerContexts extends Array<any>, ClientContexts extends Array<any>, PropsT extends object, Params extends UrlParams, CompCore extends JayComponentCore<PropsT, ViewState>>(compDefinition: JayStackComponentDefinition<StaticViewState, ViewState, Refs, ServerContexts, ClientContexts, 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;
 
-export { DevSlowlyChangingPhase, type SlowlyChangingPhase, generateClientScript, loadPageParts, renderFastChangingData, runLoadParams, runSlowlyChangingRender };
+/**
+ * Service registry for Jay Stack server-side dependency injection.
+ *
+ * Services are global singletons (not hierarchical like client contexts) that provide
+ * infrastructure capabilities like database connections, API clients, etc.
+ *
+ * Note: ServiceMarker and createJayService are defined in @jay-framework/fullstack-component
+ * to avoid circular dependencies. This module contains only the runtime implementation.
+ */
+
+/**
+ * Registers a service instance with the given marker.
+ * Typically called within an `onInit()` callback.
+ *
+ * @param marker - The service marker created with `createJayService()`
+ * @param service - The service instance to register
+ *
+ * @example
+ * ```typescript
+ * onInit(async () => {
+ *   const db = await createDatabase();
+ *   registerService(DATABASE_SERVICE, db);
+ * });
+ * ```
+ */
+declare function registerService<ServiceType>(marker: ServiceMarker<ServiceType>, service: ServiceType): void;
+/**
+ * Retrieves a registered service by its marker.
+ * Throws an error if the service is not found.
+ *
+ * @param marker - The service marker
+ * @returns The registered service instance
+ * @throws Error if service is not registered
+ *
+ * @example
+ * ```typescript
+ * onShutdown(async () => {
+ *   const db = getService(DATABASE_SERVICE);
+ *   await db?.close();
+ * });
+ * ```
+ */
+declare function getService<ServiceType>(marker: ServiceMarker<ServiceType>): ServiceType;
+/**
+ * Checks if a service is registered.
+ *
+ * @param marker - The service marker
+ * @returns true if the service is registered
+ */
+declare function hasService<ServiceType>(marker: ServiceMarker<ServiceType>): boolean;
+/**
+ * Clears all registered services.
+ * Internal API used by dev-server during hot reload.
+ */
+declare function clearServiceRegistry(): void;
+/**
+ * Resolves an array of service markers to their registered instances.
+ * Used by the runtime to inject services into render functions.
+ *
+ * @param serviceMarkers - Array of service markers to resolve
+ * @returns Array of resolved service instances
+ *
+ * @example
+ * ```typescript
+ * const services = resolveServices([DATABASE_SERVICE, INVENTORY_SERVICE]);
+ * // Returns: [databaseInstance, inventoryInstance]
+ * ```
+ */
+declare function resolveServices(serviceMarkers: any[]): Array<any>;
+type InitCallback = () => void | Promise<void>;
+type ShutdownCallback = () => void | Promise<void>;
+/**
+ * Registers a callback to be executed during service initialization.
+ * Multiple callbacks can be registered and will be executed in order.
+ *
+ * @param callback - Async or sync function to initialize services
+ *
+ * @example
+ * ```typescript
+ * onInit(async () => {
+ *   const db = await connectToDatabase(process.env.DATABASE_URL);
+ *   registerService(DATABASE_SERVICE, db);
+ * });
+ * ```
+ */
+declare function onInit(callback: InitCallback): void;
+/**
+ * Registers a callback to be executed during service shutdown.
+ * Multiple callbacks can be registered. They execute in reverse order (LIFO).
+ *
+ * @param callback - Async or sync function to clean up services
+ *
+ * @example
+ * ```typescript
+ * onShutdown(async () => {
+ *   const db = getService(DATABASE_SERVICE);
+ *   await db?.close();
+ * });
+ * ```
+ */
+declare function onShutdown(callback: ShutdownCallback): void;
+/**
+ * Executes all registered init callbacks in order.
+ * Internal API called by dev-server on startup.
+ */
+declare function runInitCallbacks(): Promise<void>;
+/**
+ * Executes all registered shutdown callbacks in reverse order (LIFO).
+ * Internal API called by dev-server on shutdown/reload.
+ */
+declare function runShutdownCallbacks(): Promise<void>;
+/**
+ * Clears all registered lifecycle callbacks.
+ * Internal API used by dev-server during hot reload.
+ */
+declare function clearLifecycleCallbacks(): void;
+
+export { DevSlowlyChangingPhase, type SlowlyChangingPhase, clearLifecycleCallbacks, clearServiceRegistry, generateClientScript, getService, hasService, loadPageParts, onInit, onShutdown, registerService, renderFastChangingData, resolveServices, runInitCallbacks, runLoadParams, runShutdownCallbacks, runSlowlyChangingRender };

package/dist/index.js

@@ -3,6 +3,53 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { parseJayFile } from "@jay-framework/compiler-jay-html";
 import { createRequire } from "module";
+const serviceRegistry = /* @__PURE__ */ new Map();
+function registerService(marker, service) {
+  serviceRegistry.set(marker, service);
+}
+function getService(marker) {
+  const service = serviceRegistry.get(marker);
+  if (service === void 0) {
+    const symbolKey = marker;
+    const serviceName = symbolKey.description || "Unknown service";
+    throw new Error(
+      `Service '${serviceName}' not found. Did you register it in jay.init.ts?
+Make sure to call: registerService(${serviceName.toUpperCase()}_SERVICE, ...)`
+    );
+  }
+  return service;
+}
+function hasService(marker) {
+  return serviceRegistry.has(marker);
+}
+function clearServiceRegistry() {
+  serviceRegistry.clear();
+}
+function resolveServices(serviceMarkers) {
+  return serviceMarkers.map((marker) => getService(marker));
+}
+const initCallbacks = [];
+const shutdownCallbacks = [];
+function onInit(callback) {
+  initCallbacks.push(callback);
+}
+function onShutdown(callback) {
+  shutdownCallbacks.push(callback);
+}
+async function runInitCallbacks() {
+  for (const callback of initCallbacks) {
+    await callback();
+  }
+}
+async function runShutdownCallbacks() {
+  for (let i = shutdownCallbacks.length - 1; i >= 0; i--) {
+    await shutdownCallbacks[i]();
+  }
+}
+function clearLifecycleCallbacks() {
+  initCallbacks.length = 0;
+  shutdownCallbacks.length = 0;
+}
 function isLeftSideParamsSubsetOfRightSideParams(left, right) {
   return Object.keys(left).reduce((prev, curr) => prev && left[curr] === right[curr], true);
 }
@@ -21,7 +68,8 @@ class DevSlowlyChangingPhase {
     for (const part of parts) {
       const { compDefinition } = part;
       if (compDefinition.loadParams) {
-        const compParams = compDefinition.loadParams([]);
+        const services = resolveServices(compDefinition.services);
+        const compParams = compDefinition.loadParams(services);
         if (!await findMatchingParams(pageParams, compParams))
           return notFound();
       }
@@ -31,9 +79,10 @@ class DevSlowlyChangingPhase {
     for (const part of parts) {
       const { compDefinition, key } = part;
       if (compDefinition.slowlyRender) {
+        const services = resolveServices(compDefinition.services);
         const slowlyRenderedPart = await compDefinition.slowlyRender(
           { ...pageProps, ...pageParams },
-          []
+          ...services
         );
         if (slowlyRenderedPart.kind === "PartialRender") {
           if (!key) {
@@ -50,8 +99,8 @@ class DevSlowlyChangingPhase {
     return partialRender(slowlyViewState, carryForward);
   }
 }
-async function runLoadParams(compDefinition, serverContexts) {
-  compDefinition.loadParams(serverContexts);
+async function runLoadParams(compDefinition, services) {
+  compDefinition.loadParams(services);
 }
 function runSlowlyChangingRender(compDefinition) {
 }
@@ -62,9 +111,11 @@ async function renderFastChangingData(pageParams, pageProps, carryForward, parts
     const { compDefinition, key } = part;
     if (compDefinition.fastRender) {
       const partSlowlyCarryForward = key ? carryForward[key] : carryForward;
+      const services = resolveServices(compDefinition.services);
       const fastRenderedPart = await compDefinition.fastRender(
         { ...pageProps, ...pageParams },
-        ...[partSlowlyCarryForward]
+        partSlowlyCarryForward,
+        ...services
       );
       if (fastRenderedPart.kind === "PartialRender") {
         if (!key) {
@@ -114,12 +165,12 @@ const require2 = createRequire(import.meta.url);
 async function loadPageParts(vite, route, pagesBase, jayRollupConfig) {
   const exists = await fs.access(route.compPath, fs.constants.F_OK).then(() => true).catch(() => false);
   const parts = [];
-  const pageCode = path.resolve(pagesBase, "./page.ts");
   if (exists) {
-    const pageComponent = (await vite.ssrLoadModule(route.compPath)).page;
+    const pageComponent = (await vite.ssrLoadModule(route.compPath + "?jay-server")).page;
     parts.push({
       compDefinition: pageComponent,
-      clientImport: `import {page} from '${pageCode}'`,
+      // Client import uses client-only code (server code stripped)
+      clientImport: `import {page} from '${route.compPath}?jay-client'`,
       clientPart: `{comp: page.comp, contextMarkers: []}`
     });
   }
@@ -141,14 +192,18 @@ async function loadPageParts(vite, route, pagesBase, jayRollupConfig) {
     for await (const headlessImport of jayHtml.headlessImports) {
       const module2 = headlessImport.codeLink.module;
       const name = headlessImport.codeLink.names[0].name;
-      const modulePath = module2[0] === "." ? path.resolve(dirName, module2) : require2.resolve(module2, { paths: require2.resolve.paths(dirName) });
-      const compDefinition = (await vite.ssrLoadModule(modulePath))[name];
+      const isLocalModule = module2[0] === "." || module2[0] === "/";
+      const modulePath = isLocalModule ? path.resolve(dirName, module2) : require2.resolve(module2, { paths: require2.resolve.paths(dirName) });
+      const serverModulePath = isLocalModule ? modulePath + "?jay-server" : modulePath;
+      const compDefinition = (await vite.ssrLoadModule(serverModulePath))[name];
       const moduleImport = module2.startsWith("./") ? path.resolve(pagesBase, module2) : module2;
+      const isNpmPackage = !module2.startsWith("./") && !module2.startsWith("../");
+      const clientModuleImport = isNpmPackage ? `${moduleImport}/client` : `${moduleImport}?jay-client`;
       const key = headlessImport.key;
       const part = {
         key,
         compDefinition,
-        clientImport: `import {${name}} from '${moduleImport}'`,
+        clientImport: `import {${name}} from '${clientModuleImport}'`,
         clientPart: `{comp: ${name}.comp, contextMarkers: [], key: '${headlessImport.key}'}`
       };
       parts.push(part);
@@ -158,9 +213,19 @@ async function loadPageParts(vite, route, pagesBase, jayRollupConfig) {
 }
 export {
   DevSlowlyChangingPhase,
+  clearLifecycleCallbacks,
+  clearServiceRegistry,
   generateClientScript,
+  getService,
+  hasService,
   loadPageParts,
+  onInit,
+  onShutdown,
+  registerService,
   renderFastChangingData,
+  resolveServices,
+  runInitCallbacks,
   runLoadParams,
+  runShutdownCallbacks,
   runSlowlyChangingRender
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jay-framework/stack-server-runtime",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "license": "Apache-2.0",
   "main": "dist/index.js",
   "types": "dist/index.d.mts",
@@ -26,16 +26,16 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@jay-framework/compiler-jay-html": "^0.7.0",
-    "@jay-framework/component": "^0.7.0",
-    "@jay-framework/fullstack-component": "^0.7.0",
-    "@jay-framework/runtime": "^0.7.0",
-    "@jay-framework/stack-route-scanner": "^0.7.0"
+    "@jay-framework/compiler-jay-html": "^0.9.0",
+    "@jay-framework/component": "^0.9.0",
+    "@jay-framework/fullstack-component": "^0.9.0",
+    "@jay-framework/runtime": "^0.9.0",
+    "@jay-framework/stack-route-scanner": "^0.9.0"
   },
   "devDependencies": {
-    "@jay-framework/dev-environment": "^0.7.0",
-    "@jay-framework/jay-cli": "^0.7.0",
-    "@jay-framework/stack-client-runtime": "^0.7.0",
+    "@jay-framework/dev-environment": "^0.9.0",
+    "@jay-framework/jay-cli": "^0.9.0",
+    "@jay-framework/stack-client-runtime": "^0.9.0",
     "@types/express": "^5.0.2",
     "@types/node": "^22.15.21",
     "nodemon": "^3.0.3",