@jskit-ai/kernel 0.1.4

package/server/runtime/moduleConfig.js

@@ -0,0 +1,269 @@
+import { Check, Errors, Parse } from "typebox/value";
+import { normalizeObject, normalizeText } from "../../shared/support/normalize.js";
+
+function normalizeModuleId(value) {
+  const moduleId = normalizeText(value);
+  if (!moduleId) {
+    throw new TypeError("defineModuleConfig requires a non-empty moduleId.");
+  }
+  return moduleId;
+}
+
+function normalizeSchema(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new TypeError("defineModuleConfig requires a schema object.");
+  }
+  return value;
+}
+
+function normalizeIssuePath(issue) {
+  const fromInstancePath = normalizeText(issue?.instancePath || issue?.path).replace(/^\//, "").replace(/\//g, ".");
+  if (fromInstancePath) {
+    return fromInstancePath;
+  }
+
+  const missingProperty = normalizeText(issue?.params?.missingProperty);
+  if (missingProperty) {
+    return missingProperty;
+  }
+
+  const additionalProperties = issue?.params?.additionalProperties;
+  if (Array.isArray(additionalProperties) && additionalProperties.length > 0) {
+    const firstAdditional = normalizeText(additionalProperties[0]);
+    if (firstAdditional) {
+      return firstAdditional;
+    }
+  }
+
+  const oneAdditional = normalizeText(additionalProperties);
+  if (oneAdditional) {
+    return oneAdditional;
+  }
+
+  return "(root)";
+}
+
+function normalizeIssueMessage(issue) {
+  const message = normalizeText(issue?.message || issue?.error || issue?.description);
+  return message || "Invalid value.";
+}
+
+function normalizeValidationIssues(rawIssues = []) {
+  return rawIssues.map((issue) => ({
+    path: normalizeIssuePath(issue),
+    message: normalizeIssueMessage(issue),
+    keyword: normalizeText(issue?.keyword)
+  }));
+}
+
+function formatIssues(issues = []) {
+  return issues
+    .slice(0, 8)
+    .map((issue) => `${issue.path}: ${issue.message}`)
+    .join("; ");
+}
+
+function buildInvalidConfigMessage(moduleId, issues = []) {
+  const summary = formatIssues(issues);
+  if (!summary) {
+    return `Invalid config for module "${moduleId}".`;
+  }
+  return `Invalid config for module "${moduleId}": ${summary}`;
+}
+
+function deepFreeze(value, seen = new WeakSet()) {
+  if (!value || typeof value !== "object") {
+    return value;
+  }
+
+  if (seen.has(value)) {
+    return value;
+  }
+  seen.add(value);
+
+  for (const key of Object.getOwnPropertyNames(value)) {
+    deepFreeze(value[key], seen);
+  }
+
+  return Object.freeze(value);
+}
+
+function normalizeCustomValidationIssues(result) {
+  if (result == null || result === true) {
+    return [];
+  }
+
+  if (result === false) {
+    return [
+      {
+        path: "(custom)",
+        message: "Custom module config validation failed."
+      }
+    ];
+  }
+
+  if (typeof result === "string") {
+    return [
+      {
+        path: "(custom)",
+        message: normalizeText(result) || "Custom module config validation failed."
+      }
+    ];
+  }
+
+  if (Array.isArray(result)) {
+    return result
+      .map((entry) => {
+        if (typeof entry === "string") {
+          return {
+            path: "(custom)",
+            message: normalizeText(entry) || "Custom module config validation failed."
+          };
+        }
+
+        if (!entry || typeof entry !== "object") {
+          return null;
+        }
+
+        return {
+          path: normalizeText(entry.path, { fallback: "(custom)" }),
+          message: normalizeText(entry.message, { fallback: "Custom module config validation failed." })
+        };
+      })
+      .filter(Boolean);
+  }
+
+  if (result && typeof result === "object" && Array.isArray(result.issues)) {
+    return normalizeCustomValidationIssues(result.issues);
+  }
+
+  return [
+    {
+      path: "(custom)",
+      message: "Custom module config validation failed."
+    }
+  ];
+}
+
+class ModuleConfigError extends Error {
+  constructor(message, { moduleId = "", issues = [], cause } = {}) {
+    super(String(message || "Module config error."));
+    this.name = "ModuleConfigError";
+    this.moduleId = normalizeText(moduleId);
+    this.issues = Object.freeze(Array.isArray(issues) ? [...issues] : []);
+    if (cause !== undefined) {
+      this.cause = cause;
+    }
+  }
+}
+
+function validateSchemaOrThrow({ moduleId, schema, value, coerce = false }) {
+  if (coerce) {
+    try {
+      return Parse(schema, value);
+    } catch (cause) {
+      const issues = normalizeValidationIssues([...Errors(schema, value)]);
+      throw new ModuleConfigError(buildInvalidConfigMessage(moduleId, issues), {
+        moduleId,
+        issues,
+        cause
+      });
+    }
+  }
+
+  if (Check(schema, value)) {
+    return value;
+  }
+
+  const issues = normalizeValidationIssues([...Errors(schema, value)]);
+  throw new ModuleConfigError(buildInvalidConfigMessage(moduleId, issues), {
+    moduleId,
+    issues
+  });
+}
+
+function defineModuleConfig({
+  moduleId,
+  schema,
+  load = ({ env }) => env,
+  transform = null,
+  validate = null,
+  coerce = false,
+  freeze = true
+} = {}) {
+  const normalizedModuleId = normalizeModuleId(moduleId);
+  const normalizedSchema = normalizeSchema(schema);
+
+  if (typeof load !== "function") {
+    throw new TypeError(`defineModuleConfig("${normalizedModuleId}") requires load to be a function.`);
+  }
+  if (transform != null && typeof transform !== "function") {
+    throw new TypeError(`defineModuleConfig("${normalizedModuleId}") requires transform to be a function when provided.`);
+  }
+  if (validate != null && typeof validate !== "function") {
+    throw new TypeError(`defineModuleConfig("${normalizedModuleId}") requires validate to be a function when provided.`);
+  }
+
+  function resolve(options = {}) {
+    const source = normalizeObject(options);
+    const env = source.env && typeof source.env === "object" ? source.env : process.env;
+    const context = source.context;
+    const hasRaw = Object.prototype.hasOwnProperty.call(source, "raw");
+
+    let loadedConfig;
+    try {
+      loadedConfig = hasRaw ? source.raw : load({ env, context, moduleId: normalizedModuleId });
+    } catch (cause) {
+      throw new ModuleConfigError(`Failed to load config for module "${normalizedModuleId}".`, {
+        moduleId: normalizedModuleId,
+        cause
+      });
+    }
+
+    let candidate = loadedConfig;
+    if (typeof transform === "function") {
+      candidate = transform(candidate, { env, context, moduleId: normalizedModuleId });
+    }
+
+    let resolvedConfig = validateSchemaOrThrow({
+      moduleId: normalizedModuleId,
+      schema: normalizedSchema,
+      value: candidate,
+      coerce: Boolean(coerce)
+    });
+
+    if (typeof validate === "function") {
+      let customValidationResult;
+      try {
+        customValidationResult = validate(resolvedConfig, { env, context, moduleId: normalizedModuleId });
+      } catch (cause) {
+        throw new ModuleConfigError(`Invalid config for module "${normalizedModuleId}" from custom validation.`, {
+          moduleId: normalizedModuleId,
+          cause
+        });
+      }
+
+      const issues = normalizeCustomValidationIssues(customValidationResult);
+      if (issues.length > 0) {
+        throw new ModuleConfigError(buildInvalidConfigMessage(normalizedModuleId, issues), {
+          moduleId: normalizedModuleId,
+          issues
+        });
+      }
+    }
+
+    if (freeze) {
+      resolvedConfig = deepFreeze(resolvedConfig);
+    }
+
+    return resolvedConfig;
+  }
+
+  return Object.freeze({
+    moduleId: normalizedModuleId,
+    schema: normalizedSchema,
+    resolve
+  });
+}
+
+export { ModuleConfigError, defineModuleConfig };

package/server/runtime/moduleConfig.test.js

@@ -0,0 +1,141 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { Type } from "typebox";
+
+import { ModuleConfigError, defineModuleConfig } from "./moduleConfig.js";
+
+test("defineModuleConfig resolves valid config and freezes nested objects", () => {
+  const moduleConfig = defineModuleConfig({
+    moduleId: "contacts",
+    schema: Type.Object(
+      {
+        mode: Type.Union([Type.Literal("standard"), Type.Literal("strict")]),
+        maxContacts: Type.Integer({ minimum: 1 }),
+        limits: Type.Object({
+          inviteExpiryHours: Type.Integer({ minimum: 1, maximum: 168 })
+        })
+      },
+      { additionalProperties: false }
+    ),
+    load({ env }) {
+      return {
+        mode: String(env.CONTACTS_MODE || "standard"),
+        maxContacts: Number(env.CONTACTS_MAX || 5000),
+        limits: {
+          inviteExpiryHours: Number(env.CONTACTS_INVITE_EXPIRY_HOURS || 24)
+        }
+      };
+    }
+  });
+
+  const config = moduleConfig.resolve({
+    env: {
+      CONTACTS_MODE: "strict",
+      CONTACTS_MAX: "1000",
+      CONTACTS_INVITE_EXPIRY_HOURS: "36"
+    }
+  });
+
+  assert.equal(config.mode, "strict");
+  assert.equal(config.maxContacts, 1000);
+  assert.equal(config.limits.inviteExpiryHours, 36);
+  assert.equal(Object.isFrozen(config), true);
+  assert.equal(Object.isFrozen(config.limits), true);
+});
+
+test("defineModuleConfig reports schema validation issues with module-scoped details", () => {
+  const moduleConfig = defineModuleConfig({
+    moduleId: "contacts",
+    schema: Type.Object(
+      {
+        maxContacts: Type.Integer({ minimum: 1 })
+      },
+      { additionalProperties: false }
+    )
+  });
+
+  assert.throws(
+    () => moduleConfig.resolve({ raw: { maxContacts: 0, unexpected: true } }),
+    (error) => {
+      assert.equal(error instanceof ModuleConfigError, true);
+      assert.equal(error.moduleId, "contacts");
+      assert.equal(error.issues.length >= 1, true);
+      assert.equal(String(error.message).includes('module "contacts"'), true);
+      return true;
+    }
+  );
+});
+
+test("defineModuleConfig supports coercion via TypeBox Parse", () => {
+  const moduleConfig = defineModuleConfig({
+    moduleId: "contacts",
+    coerce: true,
+    schema: Type.Object({
+      maxContacts: Type.Integer({ minimum: 1 }),
+      enabled: Type.Boolean()
+    })
+  });
+
+  const config = moduleConfig.resolve({
+    raw: {
+      maxContacts: "42",
+      enabled: "true"
+    }
+  });
+
+  assert.equal(config.maxContacts, 42);
+  assert.equal(config.enabled, true);
+});
+
+test("defineModuleConfig supports custom cross-field validate hook", () => {
+  const moduleConfig = defineModuleConfig({
+    moduleId: "contacts",
+    schema: Type.Object({
+      mode: Type.Union([Type.Literal("standard"), Type.Literal("strict")]),
+      requireAuditTrail: Type.Boolean()
+    }),
+    validate(value) {
+      if (value.mode === "strict" && value.requireAuditTrail !== true) {
+        return [
+          {
+            path: "requireAuditTrail",
+            message: "must be true when mode is strict"
+          }
+        ];
+      }
+      return true;
+    }
+  });
+
+  assert.throws(
+    () =>
+      moduleConfig.resolve({
+        raw: {
+          mode: "strict",
+          requireAuditTrail: false
+        }
+      }),
+    /requireAuditTrail: must be true when mode is strict/
+  );
+});
+
+test("defineModuleConfig rejects invalid module config definitions", () => {
+  assert.throws(() => defineModuleConfig({}), /moduleId/);
+  assert.throws(
+    () =>
+      defineModuleConfig({
+        moduleId: "contacts",
+        schema: null
+      }),
+    /schema/
+  );
+  assert.throws(
+    () =>
+      defineModuleConfig({
+        moduleId: "contacts",
+        schema: Type.Object({}),
+        load: "not-a-function"
+      }),
+    /load/
+  );
+});

package/server/runtime/pagination.js

@@ -0,0 +1,13 @@
+import { parsePositiveInteger } from "./integers.js";
+
+function normalizePagination(pagination = {}, { defaultPage = 1, defaultPageSize = 20, maxPageSize = 100 } = {}) {
+  const rawPage = parsePositiveInteger(pagination?.page);
+  const rawPageSize = parsePositiveInteger(pagination?.pageSize);
+
+  return {
+    page: rawPage || defaultPage,
+    pageSize: Math.max(1, Math.min(maxPageSize, rawPageSize || defaultPageSize))
+  };
+}
+
+export { normalizePagination };

package/server/runtime/realtimeNormalization.js

@@ -0,0 +1,21 @@
+import { normalizePositiveInteger, normalizeText } from "../../shared/support/normalize.js";
+
+function normalizePositiveIntegerOrNull(value) {
+  const normalized = normalizePositiveInteger(value);
+  if (normalized < 1) {
+    return null;
+  }
+
+  return normalized;
+}
+
+function normalizeScopeKind(value) {
+  const normalized = normalizeText(value).toLowerCase();
+  if (!normalized || normalized === "global") {
+    return "global";
+  }
+
+  return normalized;
+}
+
+export { normalizePositiveIntegerOrNull, normalizeScopeKind };

package/server/runtime/requestUrl.js

@@ -0,0 +1,38 @@
+const LOCAL_BASE_URL = "http://localhost";
+
+export function safeRequestUrl(request) {
+  const rawUrl = request?.raw?.url || request?.url || "/";
+
+  try {
+    return new URL(rawUrl, LOCAL_BASE_URL);
+  } catch {
+    return new URL("/", LOCAL_BASE_URL);
+  }
+}
+
+export function safePathnameFromRequest(request) {
+  return safeRequestUrl(request).pathname;
+}
+
+export function resolveClientIpAddress(request) {
+  const forwardedFor = String(request?.headers?.["x-forwarded-for"] || "").trim();
+  if (forwardedFor) {
+    const [firstHop] = forwardedFor.split(",");
+    const candidate = String(firstHop || "").trim();
+    if (candidate) {
+      return candidate;
+    }
+  }
+
+  const requestIp = String(request?.ip || "").trim();
+  if (requestIp) {
+    return requestIp;
+  }
+
+  const socketAddress = String(request?.socket?.remoteAddress || request?.raw?.socket?.remoteAddress || "").trim();
+  if (socketAddress) {
+    return socketAddress;
+  }
+
+  return "unknown";
+}

package/server/runtime/routeUtils.js

@@ -0,0 +1,20 @@
+import { AppError } from "./errors.js";
+import { defaultMissingHandler } from "../support/defaultMissingHandler.js";
+
+function normalizeIdempotencyKey(value) {
+  const normalized = String(value || "").trim();
+  return normalized || "";
+}
+
+function requireIdempotencyKey(request) {
+  const idempotencyKey = normalizeIdempotencyKey(request?.headers?.["idempotency-key"]);
+  if (!idempotencyKey) {
+    throw new AppError(400, "Idempotency-Key header is required.", {
+      code: "IDEMPOTENCY_KEY_REQUIRED"
+    });
+  }
+
+  return idempotencyKey;
+}
+
+export { defaultMissingHandler, normalizeIdempotencyKey, requireIdempotencyKey };

package/server/runtime/runtimeAssembly.js

@@ -0,0 +1,113 @@
+import { createRuntimeKernel } from "./runtimeKernel.js";
+
+function normalizeRuntimeBundles(bundles) {
+  const source = Array.isArray(bundles) ? bundles : [];
+  return source.filter((entry) => entry && typeof entry === "object");
+}
+
+function mergeRuntimeBundles(bundles = []) {
+  const normalizedBundles = normalizeRuntimeBundles(bundles);
+
+  return normalizedBundles.reduce(
+    (accumulator, bundle) => ({
+      repositoryDefinitions: accumulator.repositoryDefinitions.concat(
+        Array.isArray(bundle.repositoryDefinitions) ? bundle.repositoryDefinitions : []
+      ),
+      serviceDefinitions: accumulator.serviceDefinitions.concat(
+        Array.isArray(bundle.serviceDefinitions) ? bundle.serviceDefinitions : []
+      ),
+      controllerDefinitions: accumulator.controllerDefinitions.concat(
+        Array.isArray(bundle.controllerDefinitions) ? bundle.controllerDefinitions : []
+      ),
+      runtimeServiceIds: accumulator.runtimeServiceIds.concat(
+        Array.isArray(bundle.runtimeServiceIds) ? bundle.runtimeServiceIds : []
+      )
+    }),
+    {
+      repositoryDefinitions: [],
+      serviceDefinitions: [],
+      controllerDefinitions: [],
+      runtimeServiceIds: []
+    }
+  );
+}
+
+function createRuntimeAssembly({
+  bundles = [],
+  dependencies = {},
+  repositoryDependencies = {},
+  serviceDependencies = {},
+  controllerDependencies = {}
+} = {}) {
+  const runtimeBundle = mergeRuntimeBundles(bundles);
+
+  return createRuntimeKernel({
+    runtimeBundle,
+    dependencies,
+    repositoryDependencies,
+    serviceDependencies,
+    controllerDependencies
+  });
+}
+
+function normalizeRouteModuleDefinitions(definitions) {
+  const source = Array.isArray(definitions) ? definitions : [];
+  const normalized = [];
+  const seenIds = new Set();
+
+  for (const entry of source) {
+    const id = String(entry?.id || "").trim();
+    const buildRoutes = entry?.buildRoutes;
+    const resolveOptions = entry?.resolveOptions;
+
+    if (!id) {
+      throw new TypeError("Route module definition id is required.");
+    }
+    if (seenIds.has(id)) {
+      throw new TypeError(`Route module definition "${id}" is duplicated.`);
+    }
+    if (typeof buildRoutes !== "function") {
+      throw new TypeError(`Route module definition "${id}" buildRoutes must be a function.`);
+    }
+    if (resolveOptions != null && typeof resolveOptions !== "function") {
+      throw new TypeError(`Route module definition "${id}" resolveOptions must be a function when provided.`);
+    }
+
+    seenIds.add(id);
+    normalized.push({
+      id,
+      buildRoutes,
+      resolveOptions
+    });
+  }
+
+  return normalized;
+}
+
+function buildRoutesFromManifest({ definitions = [], controllers = {}, routeConfig = {}, missingHandler } = {}) {
+  const normalizedDefinitions = normalizeRouteModuleDefinitions(definitions);
+  const routeList = [];
+
+  for (const definition of normalizedDefinitions) {
+    const resolvedOptions = definition.resolveOptions ? definition.resolveOptions(routeConfig || {}) : {};
+    const routes = definition.buildRoutes(controllers || {}, {
+      ...(resolvedOptions && typeof resolvedOptions === "object" ? resolvedOptions : {}),
+      ...(missingHandler ? { missingHandler } : {})
+    });
+
+    if (!Array.isArray(routes)) {
+      throw new TypeError(`Route module definition "${definition.id}" must return an array.`);
+    }
+
+    routeList.push(...routes);
+  }
+
+  return routeList;
+}
+
+const __testables = {
+  normalizeRuntimeBundles,
+  normalizeRouteModuleDefinitions
+};
+
+export { mergeRuntimeBundles, createRuntimeAssembly, buildRoutesFromManifest, __testables };

package/server/runtime/runtimeKernel.js

@@ -0,0 +1,55 @@
+import { createRuntimeComposition } from "./composition.js";
+
+function normalizeDefinitions(value) {
+  return Array.isArray(value) ? value : [];
+}
+
+function normalizeRuntimeServiceIds(value) {
+  return Array.isArray(value) ? value : [];
+}
+
+function normalizeRuntimeBundle(bundle = {}) {
+  const source = bundle && typeof bundle === "object" ? bundle : {};
+
+  return {
+    repositoryDefinitions: normalizeDefinitions(source.repositoryDefinitions),
+    serviceDefinitions: normalizeDefinitions(source.serviceDefinitions),
+    controllerDefinitions: normalizeDefinitions(source.controllerDefinitions),
+    runtimeServiceIds: normalizeRuntimeServiceIds(source.runtimeServiceIds)
+  };
+}
+
+function createRuntimeKernel({
+  runtimeBundle,
+  dependencies = {},
+  repositoryDependencies = {},
+  serviceDependencies = {},
+  controllerDependencies = {}
+} = {}) {
+  const sharedDependencies = dependencies && typeof dependencies === "object" ? dependencies : {};
+  const normalizedBundle = normalizeRuntimeBundle(runtimeBundle);
+
+  return createRuntimeComposition({
+    ...normalizedBundle,
+    repositoryDependencies: {
+      ...sharedDependencies,
+      ...(repositoryDependencies || {})
+    },
+    serviceDependencies: {
+      ...sharedDependencies,
+      ...(serviceDependencies || {})
+    },
+    controllerDependencies: {
+      ...sharedDependencies,
+      ...(controllerDependencies || {})
+    }
+  });
+}
+
+const __testables = {
+  normalizeDefinitions,
+  normalizeRuntimeServiceIds,
+  normalizeRuntimeBundle
+};
+
+export { normalizeRuntimeBundle, createRuntimeKernel, __testables };