@jskit-ai/kernel 0.1.4

package/README.md

@@ -0,0 +1,24 @@
+# kernel
+
+Internal JSKIT framework runtime package.
+
+This package contains the merged runtime internals:
+- container
+- kernel
+- http fastify bridge
+- server runtime primitives
+- support primitives
+- surface routing primitives
+- platform runtime bootstrap
+
+## Historical note
+
+kernel was assembled moving code from these legacy packages and then deleting them:
+
+  - @jskit-ai/container-core
+  - @jskit-ai/http-fastify-core
+  - @jskit-ai/kernel
+  - @jskit-ai/platform-server-runtime
+  - @jskit-ai/server-runtime-core
+  - @jskit-ai/support-core
+  - @jskit-ai/surface-routing

package/_testable/index.js

@@ -0,0 +1,4 @@
+export { createContainer } from "../server/container/index.js";
+export { createApplication } from "../server/kernel/index.js";
+export { createHttpRuntime, compileRouteValidator } from "../server/http/_testable/index.js";
+export { deriveResourceRequiredMetadata } from "../shared/validators/index.js";

package/client/appConfig.js

@@ -0,0 +1,33 @@
+import { isRecord } from "../shared/support/normalize.js";
+
+const CLIENT_APP_CONFIG_GLOBAL_KEY = "__JSKIT_CLIENT_APP_CONFIG__";
+const EMPTY_CLIENT_APP_CONFIG = Object.freeze({});
+
+function normalizeClientAppConfig(source = {}) {
+  if (!isRecord(source)) {
+    return EMPTY_CLIENT_APP_CONFIG;
+  }
+
+  return Object.freeze({ ...source });
+}
+
+function setClientAppConfig(source = {}) {
+  const appConfig = normalizeClientAppConfig(source);
+
+  if (typeof globalThis === "object" && globalThis) {
+    globalThis[CLIENT_APP_CONFIG_GLOBAL_KEY] = appConfig;
+  }
+
+  return appConfig;
+}
+
+function getClientAppConfig() {
+  if (typeof globalThis !== "object" || !globalThis) {
+    return EMPTY_CLIENT_APP_CONFIG;
+  }
+
+  const appConfig = globalThis[CLIENT_APP_CONFIG_GLOBAL_KEY];
+  return isRecord(appConfig) ? appConfig : EMPTY_CLIENT_APP_CONFIG;
+}
+
+export { CLIENT_APP_CONFIG_GLOBAL_KEY, setClientAppConfig, getClientAppConfig };

package/client/componentInteraction.js

@@ -0,0 +1,51 @@
+import {
+  normalizeObject,
+  normalizeText
+} from "../shared/support/normalize.js";
+
+function createComponentInteractionEmitter(emit) {
+  if (typeof emit !== "function") {
+    throw new TypeError("createComponentInteractionEmitter expects emit to be a function.");
+  }
+
+  function emitInteraction(type, payload = {}) {
+    emit("interaction", {
+      type: normalizeText(type),
+      ...normalizeObject(payload)
+    });
+  }
+
+  async function invokeAction(actionName, payload, callback) {
+    emit("action:started", {
+      action: normalizeText(actionName),
+      payload
+    });
+
+    try {
+      if (typeof callback === "function") {
+        await callback();
+      }
+
+      emit("action:succeeded", {
+        action: normalizeText(actionName),
+        payload
+      });
+    } catch (errorValue) {
+      emit("action:failed", {
+        action: normalizeText(actionName),
+        payload,
+        message: String(errorValue?.message || "Action failed")
+      });
+      throw errorValue;
+    }
+  }
+
+  return Object.freeze({
+    emitInteraction,
+    invokeAction
+  });
+}
+
+export {
+  createComponentInteractionEmitter
+};

package/client/componentInteraction.test.js

@@ -0,0 +1,111 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createComponentInteractionEmitter } from "./componentInteraction.js";
+
+test("createComponentInteractionEmitter requires emit function", () => {
+  assert.throws(
+    () => createComponentInteractionEmitter(null),
+    /expects emit to be a function/
+  );
+});
+
+test("createComponentInteractionEmitter emits interaction payload", () => {
+  const events = [];
+  const helpers = createComponentInteractionEmitter((name, payload) => {
+    events.push({
+      name,
+      payload
+    });
+  });
+
+  helpers.emitInteraction("profile:submit", {
+    id: 42
+  });
+
+  assert.deepEqual(events, [
+    {
+      name: "interaction",
+      payload: {
+        type: "profile:submit",
+        id: 42
+      }
+    }
+  ]);
+});
+
+test("createComponentInteractionEmitter emits action lifecycle for success", async () => {
+  const events = [];
+  const helpers = createComponentInteractionEmitter((name, payload) => {
+    events.push({
+      name,
+      payload
+    });
+  });
+
+  await helpers.invokeAction("save", {
+    id: 1
+  }, async () => {});
+
+  assert.deepEqual(events, [
+    {
+      name: "action:started",
+      payload: {
+        action: "save",
+        payload: {
+          id: 1
+        }
+      }
+    },
+    {
+      name: "action:succeeded",
+      payload: {
+        action: "save",
+        payload: {
+          id: 1
+        }
+      }
+    }
+  ]);
+});
+
+test("createComponentInteractionEmitter emits action failure and rethrows", async () => {
+  const events = [];
+  const helpers = createComponentInteractionEmitter((name, payload) => {
+    events.push({
+      name,
+      payload
+    });
+  });
+
+  await assert.rejects(
+    () =>
+      helpers.invokeAction("save", {
+        id: 1
+      }, async () => {
+        throw new Error("boom");
+      }),
+    /boom/
+  );
+
+  assert.deepEqual(events, [
+    {
+      name: "action:started",
+      payload: {
+        action: "save",
+        payload: {
+          id: 1
+        }
+      }
+    },
+    {
+      name: "action:failed",
+      payload: {
+        action: "save",
+        payload: {
+          id: 1
+        },
+        message: "boom"
+      }
+    }
+  ]);
+});

package/client/descriptorSections.js

@@ -0,0 +1,75 @@
+import { isRecord } from "../shared/support/normalize.js";
+import { sortStrings } from "../shared/support/sorting.js";
+
+function normalizeDescriptorUiRoutes(value) {
+  const routeEntries = Array.isArray(value) ? value : [];
+  const normalizedRoutes = [];
+
+  for (const routeEntry of routeEntries) {
+    if (!isRecord(routeEntry)) {
+      continue;
+    }
+
+    try {
+      normalizedRoutes.push(Object.freeze(JSON.parse(JSON.stringify(routeEntry))));
+    } catch {
+      // Skip non-serializable route declarations.
+    }
+  }
+
+  return Object.freeze(normalizedRoutes);
+}
+
+function normalizeDescriptorClientProviders(value) {
+  const entries = Array.isArray(value) ? value : [];
+  const providers = [];
+
+  for (const entry of entries) {
+    if (!isRecord(entry)) {
+      continue;
+    }
+
+    const exportName = String(entry.export || "").trim();
+    if (!exportName) {
+      continue;
+    }
+
+    providers.push(
+      Object.freeze({
+        export: exportName,
+        entrypoint: String(entry.entrypoint || "").trim()
+      })
+    );
+  }
+
+  return Object.freeze(providers);
+}
+
+function normalizeDescriptorClientOptimizeIncludeSpecifiers(value) {
+  return Object.freeze(sortStrings(value));
+}
+
+function normalizeClientDescriptorSections(descriptorValue) {
+  const descriptor = isRecord(descriptorValue) ? descriptorValue : {};
+  const metadata = isRecord(descriptor.metadata) ? descriptor.metadata : {};
+  const runtime = isRecord(descriptor.runtime) ? descriptor.runtime : {};
+  const ui = isRecord(metadata.ui) ? metadata.ui : {};
+  const clientMetadata = isRecord(metadata.client) ? metadata.client : {};
+  const optimizeDeps = isRecord(clientMetadata.optimizeDeps) ? clientMetadata.optimizeDeps : {};
+  const runtimeClient = isRecord(runtime.client) ? runtime.client : {};
+
+  return Object.freeze({
+    descriptorUiRoutes: normalizeDescriptorUiRoutes(ui.routes),
+    descriptorClientProviders: normalizeDescriptorClientProviders(runtimeClient.providers),
+    descriptorClientOptimizeIncludeSpecifiers: normalizeDescriptorClientOptimizeIncludeSpecifiers(
+      optimizeDeps.include
+    )
+  });
+}
+
+export {
+  normalizeDescriptorUiRoutes,
+  normalizeDescriptorClientProviders,
+  normalizeDescriptorClientOptimizeIncludeSpecifiers,
+  normalizeClientDescriptorSections
+};

package/client/index.d.ts

@@ -0,0 +1,70 @@
+export type ClientLogger = {
+  info?: (...args: any[]) => void;
+  warn?: (...args: any[]) => void;
+  error?: (...args: any[]) => void;
+  debug?: (...args: any[]) => void;
+  isDebugEnabled?: boolean;
+};
+
+export function getClientAppConfig(): Readonly<Record<string, any>>;
+
+export function resolveClientBootstrapDebugEnabled(options?: {
+  env?: Record<string, any>;
+  debugEnabled?: boolean;
+  debugEnvKey?: string;
+}): boolean;
+
+export function createShellRouter(options?: {
+  createRouter: (options: { history?: any; routes: any[] }) => any;
+  history?: any;
+  routes?: any[];
+  surfaceRuntime: any;
+  surfaceMode?: string;
+  fallbackRoute?: any;
+  notFoundComponent?: any;
+  guard?: false | ((to: any) => any) | Record<string, any>;
+}): Readonly<{
+  router: any;
+  activeRoutes: readonly any[];
+  fallbackRoute: any;
+}>;
+
+export function bootstrapClientShellApp(options?: {
+  createApp: (rootComponent: any) => any;
+  rootComponent: any;
+  appConfig?: Record<string, any>;
+  appPlugins?: any[];
+  router: any;
+  bootClientModules: (context: any) => Promise<any>;
+  surfaceRuntime: any;
+  surfaceMode?: string;
+  env?: Record<string, any>;
+  fallbackRoute?: any;
+  logger?: ClientLogger;
+  createBootstrapLogger?: (options: {
+    env?: Record<string, any>;
+    logger?: ClientLogger;
+    debugEnabled?: boolean;
+    debugEnvKey?: string;
+  }) => ClientLogger;
+  debugEnabled?: boolean;
+  debugEnvKey?: string;
+  debugMessage?: string;
+  onAfterModulesBootstrapped?: (context: any) => void | Promise<void>;
+  mountSelector?: string;
+}): Promise<
+  Readonly<{
+    app: any;
+    router: any;
+    clientBootstrap: any;
+    logger: Required<ClientLogger>;
+    debugEnabled: boolean;
+  }>
+>;
+
+export function createComponentInteractionEmitter(
+  emit: (eventName: string, payload: any) => void
+): Readonly<{
+  emitInteraction: (type: string, payload?: Record<string, any>) => void;
+  invokeAction: (actionName: string, payload: any, callback?: () => Promise<any> | any) => Promise<void>;
+}>;

package/client/index.js

@@ -0,0 +1,3 @@
+export { getClientAppConfig } from "./appConfig.js";
+export { resolveClientBootstrapDebugEnabled, createSurfaceShellRouter as createShellRouter, bootstrapClientShellApp } from "./shellBootstrap.js";
+export { createComponentInteractionEmitter } from "./componentInteraction.js";

package/client/logging.js

@@ -0,0 +1,38 @@
+import { isRecord } from "../shared/support/normalize.js";
+
+function createStructuredLogger(logger = console) {
+  if (isRecord(logger)) {
+    return Object.freeze({
+      info: typeof logger.info === "function" ? logger.info.bind(logger) : console.info.bind(console),
+      warn: typeof logger.warn === "function" ? logger.warn.bind(logger) : console.warn.bind(console),
+      error: typeof logger.error === "function" ? logger.error.bind(logger) : console.error.bind(console),
+      debug: typeof logger.debug === "function" ? logger.debug.bind(logger) : () => {}
+    });
+  }
+
+  return Object.freeze({
+    info: console.info.bind(console),
+    warn: console.warn.bind(console),
+    error: console.error.bind(console),
+    debug: () => {}
+  });
+}
+
+function summarizeRouterRoutes(router) {
+  if (!router || typeof router.getRoutes !== "function") {
+    return Object.freeze([]);
+  }
+
+  return Object.freeze(
+    router.getRoutes().map((route) =>
+      Object.freeze({
+        name: String(route?.name || "").trim(),
+        path: String(route?.path || "").trim(),
+        metaScope: String(route?.meta?.jskit?.scope || "").trim(),
+        metaSurface: String(route?.meta?.jskit?.surface || "").trim()
+      })
+    )
+  );
+}
+
+export { createStructuredLogger, summarizeRouterRoutes };