@jskit-ai/kernel 0.1.8 → 0.1.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/kernel",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "type": "module",
   "dependencies": {
     "typebox": "^1.0.81"
@@ -32,6 +32,10 @@
     "./shared/support": "./shared/support/index.js",
     "./shared/support/tokens": "./shared/support/tokens.js",
     "./shared/support/normalize": "./shared/support/normalize.js",
+    "./shared/support/permissions": "./shared/support/permissions.js",
+    "./shared/support/deepFreeze": "./shared/support/deepFreeze.js",
+    "./shared/support/listenerSet": "./shared/support/listenerSet.js",
+    "./shared/support/providerLogger": "./shared/support/providerLogger.js",
     "./shared/support/returnToPath": "./shared/support/returnToPath.js",
     "./shared/support/visibility": "./shared/support/visibility.js",
     "./shared/support/linkPath": "./shared/support/linkPath.js",

package/server/runtime/moduleConfig.js

@@ -1,4 +1,5 @@
 import { Check, Errors, Parse } from "typebox/value";
+import { deepFreeze } from "../../shared/support/deepFreeze.js";
 import { normalizeObject, normalizeText } from "../../shared/support/normalize.js";
 
 function normalizeModuleId(value) {
@@ -71,23 +72,6 @@ function buildInvalidConfigMessage(moduleId, issues = []) {
   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 [];

package/shared/actions/executionContext.js

@@ -1,10 +1,6 @@
 import { normalizeRequestMeta } from "./requestMeta.js";
 import { normalizeLowerText, normalizeText } from "./textNormalization.js";
-
-function normalizePermissions(value) {
-  const source = Array.isArray(value) ? value : [];
-  return Array.from(new Set(source.map((entry) => normalizeText(entry)).filter(Boolean)));
-}
+import { normalizePermissionList } from "../support/permissions.js";
 
 function copyRecord(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
@@ -31,10 +27,6 @@ function normalizeActor(actor) {
   return source;
 }
 
-function normalizeMembership(membership) {
-  return copyRecord(membership);
-}
-
 function normalizeTimeMeta(timeMeta) {
   const source = timeMeta && typeof timeMeta === "object" ? timeMeta : {};
   const nowValue = source.now instanceof Date ? source.now : new Date();
@@ -48,7 +40,6 @@ function normalizeTimeMeta(timeMeta) {
 
 const RESERVED_CONTEXT_KEYS = new Set([
   "actor",
-  "membership",
   "permissions",
   "surface",
   "channel",
@@ -74,8 +65,7 @@ function normalizeExecutionContext(context = {}) {
   return Object.freeze({
     ...passthrough,
     actor: normalizeActor(source.actor),
-    membership: normalizeMembership(source.membership),
-    permissions: normalizePermissions(source.permissions),
+    permissions: normalizePermissionList(source.permissions),
     surface: normalizeLowerText(source.surface),
     channel: normalizeLowerText(source.channel) || "internal",
     requestMeta: normalizeRequestMeta(source.requestMeta),
@@ -86,10 +76,9 @@ function normalizeExecutionContext(context = {}) {
 const __testables = {
   normalizeText,
   normalizeLowerText,
-  normalizePermissions,
+  normalizePermissions: normalizePermissionList,
   copyRecord,
   normalizeActor,
-  normalizeMembership,
   normalizeRequestMeta,
   normalizeTimeMeta
 };

package/shared/support/deepFreeze.js

@@ -0,0 +1,18 @@
+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);
+}
+
+export { deepFreeze };

package/shared/support/listenerSet.js

@@ -0,0 +1,26 @@
+function subscribeListener(listeners, listener) {
+  if (!(listeners instanceof Set)) {
+    throw new TypeError("subscribeListener requires a Set.");
+  }
+
+  if (typeof listener !== "function") {
+    return () => {};
+  }
+
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+function createListenerSubscription(listeners) {
+  if (!(listeners instanceof Set)) {
+    throw new TypeError("createListenerSubscription requires a Set.");
+  }
+
+  return function subscribe(listener) {
+    return subscribeListener(listeners, listener);
+  };
+}
+
+export { subscribeListener, createListenerSubscription };

package/shared/support/normalize.js

@@ -29,6 +29,11 @@ function normalizeArray(value) {
   return Array.isArray(value) ? value : [];
 }
 
+function normalizeUniqueTextList(value, { acceptSingle = false } = {}) {
+  const source = Array.isArray(value) ? value : acceptSingle ? [value] : [];
+  return Array.from(new Set(source.map((entry) => normalizeText(entry)).filter(Boolean)));
+}
+
 function normalizeInteger(value, { fallback = 0, min = null, max = null } = {}) {
   const numeric = Number(value);
   if (!Number.isFinite(numeric)) {
@@ -108,6 +113,7 @@ export {
   normalizeObject,
   isRecord,
   normalizeArray,
+  normalizeUniqueTextList,
   normalizeInteger,
   normalizePositiveInteger,
   normalizeOpaqueId,

package/shared/support/normalize.test.js

@@ -4,7 +4,8 @@ import {
   normalizeOpaqueId,
   normalizePositiveInteger,
   normalizeOneOf,
-  normalizeQueryToken
+  normalizeQueryToken,
+  normalizeUniqueTextList
 } from "./normalize.js";
 
 test("normalizeQueryToken trims, lowercases, and falls back when empty", () => {
@@ -46,3 +47,14 @@ test("normalizeOpaqueId preserves opaque identifiers", () => {
   assert.equal(normalizeOpaqueId(""), null);
   assert.equal(normalizeOpaqueId(null), null);
 });
+
+test("normalizeUniqueTextList trims, dedupes, and supports optional single values", () => {
+  assert.deepEqual(normalizeUniqueTextList([" one ", "two", "one", "", null]), ["one", "two"]);
+  assert.deepEqual(normalizeUniqueTextList("one"), []);
+  assert.deepEqual(
+    normalizeUniqueTextList(" one ", {
+      acceptSingle: true
+    }),
+    ["one"]
+  );
+});

package/shared/support/providerLogger.js

@@ -0,0 +1,42 @@
+function asLogger(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return null;
+  }
+  return value;
+}
+
+function callLoggerMethod(logger, methodName, fallbackMethodName, args) {
+  if (logger && typeof logger[methodName] === "function") {
+    logger[methodName](...args);
+    return;
+  }
+
+  if (typeof console[fallbackMethodName] === "function") {
+    console[fallbackMethodName](...args);
+  }
+}
+
+function createProviderLogger(loggerLike = null, { debugEnabled = false, debugMethod = "info" } = {}) {
+  const logger = asLogger(loggerLike);
+  const resolvedDebugMethod = String(debugMethod || "info").trim() || "info";
+
+  return Object.freeze({
+    debug: (...args) => {
+      if (debugEnabled !== true) {
+        return;
+      }
+      callLoggerMethod(logger, resolvedDebugMethod, "info", args);
+    },
+    info: (...args) => {
+      callLoggerMethod(logger, "info", "info", args);
+    },
+    warn: (...args) => {
+      callLoggerMethod(logger, "warn", "warn", args);
+    },
+    error: (...args) => {
+      callLoggerMethod(logger, "error", "error", args);
+    }
+  });
+}
+
+export { createProviderLogger };

package/shared/support/visibility.js

@@ -1,4 +1,4 @@
-import { normalizeOpaqueId, normalizeText } from "./normalize.js";
+import { normalizeObject, normalizeOpaqueId, normalizeText } from "./normalize.js";
 import { ROUTE_VISIBILITY_PUBLIC, ROUTE_VISIBILITY_USER } from "./policies.js";
 
 const ROUTE_VISIBILITY_LEVELS = Object.freeze([ROUTE_VISIBILITY_PUBLIC, ROUTE_VISIBILITY_USER]);
@@ -40,7 +40,7 @@ function normalizeVisibilityScopeKind(value) {
 }
 
 function normalizeVisibilityContext(value = {}) {
-  const source = value && typeof value === "object" && !Array.isArray(value) ? value : {};
+  const source = normalizeObject(value);
   const normalizedVisibility = normalizeRouteVisibilityToken(source.visibility);
   const normalizedScopeKind = normalizeVisibilityScopeKind(source.scopeKind);
 

package/shared/surface/registry.js

@@ -1,3 +1,5 @@
+import { normalizeObject } from "../support/normalize.js";
+
 function normalizeSurfaceId(value) {
   return String(value || "")
     .trim()
@@ -59,7 +61,7 @@ function createSurfaceRegistry(options = {}) {
 
   const normalizedEntries = Object.entries(rawSurfaces)
     .map(([key, value]) => {
-      const sourceDefinition = value && typeof value === "object" && !Array.isArray(value) ? value : {};
+      const sourceDefinition = normalizeObject(value);
       const normalizedId = normalizeSurfaceId(sourceDefinition.id || key);
       if (!normalizedId) {
         return null;

package/shared/validators/index.js

@@ -5,6 +5,7 @@ export { mergeObjectSchemas } from "./mergeObjectSchemas.js";
 export { mergeValidators } from "./mergeValidators.js";
 export { nestValidator } from "./nestValidator.js";
 export { recordIdParamsValidator, positiveIntegerValidator } from "./recordIdParamsValidator.js";
+export { normalizeSettingsFieldInput, normalizeSettingsFieldOutput } from "./settingsFieldNormalization.js";
 export {
   normalizeRequiredFieldList,
   deriveRequiredFieldsFromSchema,

package/shared/validators/settingsFieldNormalization.js

@@ -0,0 +1,40 @@
+import { normalizeObjectInput } from "./inputNormalization.js";
+
+function normalizeSettingsFieldInput(payload = {}, fields = []) {
+  const source = normalizeObjectInput(payload);
+  const normalized = {};
+
+  for (const field of Array.isArray(fields) ? fields : []) {
+    if (!Object.hasOwn(source, field.key)) {
+      continue;
+    }
+    normalized[field.key] = field.normalizeInput(source[field.key], {
+      payload: source
+    });
+  }
+
+  return normalized;
+}
+
+function normalizeSettingsFieldOutput(payload = {}, fields = []) {
+  const settingsSource = normalizeObjectInput(payload);
+  const normalized = {};
+
+  for (const field of Array.isArray(fields) ? fields : []) {
+    const rawValue = Object.hasOwn(settingsSource, field.key)
+      ? settingsSource[field.key]
+      : field.resolveDefault({
+          settings: settingsSource
+        });
+    normalized[field.key] = field.normalizeOutput(rawValue, {
+      settings: settingsSource
+    });
+  }
+
+  return normalized;
+}
+
+export {
+  normalizeSettingsFieldInput,
+  normalizeSettingsFieldOutput
+};