@jskit-ai/kernel 0.1.4

package/shared/runtime/application.js

@@ -0,0 +1,323 @@
+import { createContainer } from "./container.js";
+import {
+  DuplicateProviderError,
+  ProviderDependencyError,
+  ProviderLifecycleError,
+  ProviderNormalizationError
+} from "./kernelErrors.js";
+import { ServiceProvider } from "./serviceProvider.js";
+import { normalizeText } from "../support/normalize.js";
+
+function normalizeStringArray(value) {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+
+  return [...new Set(value.map((entry) => String(entry || "").trim()).filter(Boolean))].sort((left, right) =>
+    left.localeCompare(right)
+  );
+}
+
+function nowMilliseconds() {
+  return Date.now();
+}
+
+class Application {
+  constructor({ profile = "", strict = true, container = null } = {}) {
+    this.profile = normalizeText(profile);
+    this.strict = strict !== false;
+    this.container = container || createContainer({ scopeId: "root" });
+
+    this.providerEntries = [];
+    this.registeredProviders = [];
+    this.bootedProviders = [];
+
+    this.diagnostics = {
+      profile: this.profile,
+      providerOrder: [],
+      registeredOrder: [],
+      bootedOrder: [],
+      timings: {
+        register: {},
+        boot: {},
+        shutdown: {}
+      }
+    };
+  }
+
+  bind(token, factory) {
+    this.container.bind(token, factory);
+    return this;
+  }
+
+  singleton(token, factory) {
+    this.container.singleton(token, factory);
+    return this;
+  }
+
+  scoped(token, factory) {
+    this.container.scoped(token, factory);
+    return this;
+  }
+
+  instance(token, value) {
+    this.container.instance(token, value);
+    return this;
+  }
+
+  make(token) {
+    return this.container.make(token);
+  }
+
+  has(token) {
+    return this.container.has(token);
+  }
+
+  createScope(scopeId) {
+    return this.container.createScope(scopeId);
+  }
+
+  tag(token, tagName) {
+    this.container.tag(token, tagName);
+    return this;
+  }
+
+  resolveTag(tagName) {
+    return this.container.resolveTag(tagName);
+  }
+
+  normalizeProviderEntries(providers = []) {
+    if (!Array.isArray(providers)) {
+      throw new ProviderNormalizationError("Providers must be an array.");
+    }
+
+    const entries = [];
+    const seenIds = new Set();
+
+    for (const rawProvider of providers) {
+      const entry = this.normalizeProviderEntry(rawProvider);
+      if (seenIds.has(entry.id)) {
+        throw new DuplicateProviderError(`Provider \"${entry.id}\" is duplicated.`);
+      }
+      seenIds.add(entry.id);
+      entries.push(entry);
+    }
+
+    return entries.sort((left, right) => left.id.localeCompare(right.id));
+  }
+
+  normalizeProviderEntry(rawProvider) {
+    if (!rawProvider) {
+      throw new ProviderNormalizationError("Provider entry is required.");
+    }
+
+    if (typeof rawProvider === "function") {
+      const providerInstance = new rawProvider(this);
+      const providerId = normalizeText(rawProvider.id || providerInstance.id || rawProvider.name);
+      if (!providerId) {
+        throw new ProviderNormalizationError("Provider class must define a stable id.");
+      }
+
+      return {
+        id: providerId,
+        dependsOn: normalizeStringArray(rawProvider.dependsOn || providerInstance.dependsOn),
+        provider: providerInstance
+      };
+    }
+
+    if (typeof rawProvider === "object") {
+      const provider = rawProvider;
+      const providerId = normalizeText(provider.id || provider.constructor?.id || provider.constructor?.name);
+      if (!providerId) {
+        throw new ProviderNormalizationError("Provider object must define id.");
+      }
+
+      return {
+        id: providerId,
+        dependsOn: normalizeStringArray(provider.dependsOn || provider.constructor?.dependsOn),
+        provider
+      };
+    }
+
+    throw new ProviderNormalizationError("Provider entry must be a class or object instance.");
+  }
+
+  sortProviderGraph(entries = []) {
+    const byId = new Map(entries.map((entry) => [entry.id, entry]));
+    const visited = new Set();
+    const visiting = new Set();
+    const ordered = [];
+
+    const visit = (providerId, lineage = []) => {
+      if (visited.has(providerId)) {
+        return;
+      }
+      if (visiting.has(providerId)) {
+        throw new ProviderDependencyError(`Provider dependency cycle detected: ${[...lineage, providerId].join(" -> ")}`);
+      }
+
+      const entry = byId.get(providerId);
+      if (!entry) {
+        throw new ProviderDependencyError(`Provider \"${lineage[lineage.length - 1] || "<unknown>"}\" depends on missing provider \"${providerId}\".`);
+      }
+
+      visiting.add(providerId);
+      for (const dependencyId of entry.dependsOn) {
+        visit(dependencyId, [...lineage, providerId]);
+      }
+      visiting.delete(providerId);
+      visited.add(providerId);
+      ordered.push(entry);
+    };
+
+    for (const entry of [...entries].sort((left, right) => left.id.localeCompare(right.id))) {
+      visit(entry.id, []);
+    }
+
+    return ordered;
+  }
+
+  configureProviders(providers = []) {
+    const normalized = this.normalizeProviderEntries(providers);
+    const ordered = this.sortProviderGraph(normalized);
+
+    this.providerEntries = ordered;
+    this.diagnostics.providerOrder = ordered.map((entry) => entry.id);
+    return this;
+  }
+
+  async registerProviders() {
+    this.registeredProviders = [];
+
+    for (const entry of this.providerEntries) {
+      const startedAt = nowMilliseconds();
+      try {
+        if (typeof entry.provider.register === "function") {
+          await entry.provider.register(this);
+        }
+      } catch (error) {
+        throw new ProviderLifecycleError(`Provider \"${entry.id}\" failed during register().`, {
+          providerId: entry.id,
+          phase: "register",
+          cause: error
+        });
+      } finally {
+        this.diagnostics.timings.register[entry.id] = nowMilliseconds() - startedAt;
+      }
+
+      this.registeredProviders.push(entry);
+      this.diagnostics.registeredOrder.push(entry.id);
+    }
+
+    return this;
+  }
+
+  async bootProviders() {
+    this.bootedProviders = [];
+
+    for (const entry of this.providerEntries) {
+      const startedAt = nowMilliseconds();
+      try {
+        if (typeof entry.provider.boot === "function") {
+          await entry.provider.boot(this);
+        }
+      } catch (error) {
+        throw new ProviderLifecycleError(`Provider \"${entry.id}\" failed during boot().`, {
+          providerId: entry.id,
+          phase: "boot",
+          cause: error
+        });
+      } finally {
+        this.diagnostics.timings.boot[entry.id] = nowMilliseconds() - startedAt;
+      }
+
+      this.bootedProviders.push(entry);
+      this.diagnostics.bootedOrder.push(entry.id);
+    }
+
+    return this;
+  }
+
+  async start({ providers = [] } = {}) {
+    this.configureProviders(providers);
+    await this.registerProviders();
+    await this.bootProviders();
+    return this;
+  }
+
+  async shutdown() {
+    const shutdownOrder = [...this.bootedProviders].reverse();
+
+    for (const entry of shutdownOrder) {
+      const startedAt = nowMilliseconds();
+      try {
+        if (typeof entry.provider.shutdown === "function") {
+          await entry.provider.shutdown(this);
+        }
+      } catch (error) {
+        throw new ProviderLifecycleError(`Provider \"${entry.id}\" failed during shutdown().`, {
+          providerId: entry.id,
+          phase: "shutdown",
+          cause: error
+        });
+      } finally {
+        this.diagnostics.timings.shutdown[entry.id] = nowMilliseconds() - startedAt;
+      }
+    }
+
+    return shutdownOrder.map((entry) => entry.id);
+  }
+
+  getDiagnostics() {
+    return Object.freeze({
+      profile: this.diagnostics.profile,
+      providerOrder: Object.freeze([...this.diagnostics.providerOrder]),
+      registeredOrder: Object.freeze([...this.diagnostics.registeredOrder]),
+      bootedOrder: Object.freeze([...this.diagnostics.bootedOrder]),
+      timings: Object.freeze({
+        register: Object.freeze({ ...this.diagnostics.timings.register }),
+        boot: Object.freeze({ ...this.diagnostics.timings.boot }),
+        shutdown: Object.freeze({ ...this.diagnostics.timings.shutdown })
+      })
+    });
+  }
+}
+
+function createApplication(options = {}) {
+  return new Application(options);
+}
+
+function createProviderClass({ id, dependsOn = [], register = null, boot = null, shutdown = null } = {}) {
+  const providerId = normalizeText(id);
+  if (!providerId) {
+    throw new ProviderNormalizationError("createProviderClass requires id.");
+  }
+
+  class DynamicProvider extends ServiceProvider {
+    static id = providerId;
+
+    static dependsOn = normalizeStringArray(dependsOn);
+
+    async register(app) {
+      if (typeof register === "function") {
+        await register(app);
+      }
+    }
+
+    async boot(app) {
+      if (typeof boot === "function") {
+        await boot(app);
+      }
+    }
+
+    async shutdown(app) {
+      if (typeof shutdown === "function") {
+        await shutdown(app);
+      }
+    }
+  }
+
+  return DynamicProvider;
+}
+
+export { Application, createApplication, createProviderClass };

package/shared/runtime/container.js

@@ -0,0 +1,261 @@
+import {
+  CircularDependencyError,
+  DuplicateBindingError,
+  InvalidFactoryError,
+  InvalidTokenError,
+  UnresolvedTokenError
+} from "./containerErrors.js";
+
+const LIFETIME_TRANSIENT = "transient";
+const LIFETIME_SINGLETON = "singleton";
+const LIFETIME_SCOPED = "scoped";
+
+function normalizeToken(token) {
+  const kind = typeof token;
+  if (kind === "string") {
+    const normalized = token.trim();
+    if (!normalized) {
+      throw new InvalidTokenError("Container token string cannot be empty.");
+    }
+    return normalized;
+  }
+
+  if (kind === "symbol" || kind === "function") {
+    return token;
+  }
+
+  throw new InvalidTokenError("Container token must be a non-empty string, symbol, or function.", {
+    receivedType: kind
+  });
+}
+
+function tokenLabel(token) {
+  if (typeof token === "string") {
+    return token;
+  }
+
+  if (typeof token === "symbol") {
+    return token.description ? `Symbol(${token.description})` : String(token);
+  }
+
+  if (typeof token === "function") {
+    return token.name ? `Function(${token.name})` : "Function(<anonymous>)";
+  }
+
+  return String(token);
+}
+
+function ensureFactory(factory, token) {
+  if (typeof factory !== "function") {
+    throw new InvalidFactoryError(`Factory for token \"${tokenLabel(token)}\" must be a function.`);
+  }
+}
+
+function normalizeTagName(tagName) {
+  const normalized = String(tagName || "").trim();
+  if (!normalized) {
+    throw new TypeError("Tag name is required.");
+  }
+  return normalized;
+}
+
+function normalizeScopeId(scopeId) {
+  const normalized = String(scopeId || "").trim();
+  return normalized || "scope";
+}
+
+class Container {
+  constructor({ parent = null, scopeId = "root" } = {}) {
+    this.parent = parent instanceof Container ? parent : null;
+    this.scopeId = normalizeScopeId(scopeId);
+    this.bindings = new Map();
+    this.instances = new Map();
+    this.scopedInstances = new Map();
+
+    if (!this.parent) {
+      this.tags = new Map();
+      this.resolutionStack = [];
+    }
+  }
+
+  root() {
+    let node = this;
+    while (node.parent) {
+      node = node.parent;
+    }
+    return node;
+  }
+
+  has(token) {
+    const normalizedToken = normalizeToken(token);
+    return this.findBindingRecord(normalizedToken) !== null || this.findInstanceRecord(normalizedToken) !== null;
+  }
+
+  bind(token, factory) {
+    return this.setBinding(token, factory, LIFETIME_TRANSIENT);
+  }
+
+  singleton(token, factory) {
+    return this.setBinding(token, factory, LIFETIME_SINGLETON);
+  }
+
+  scoped(token, factory) {
+    return this.setBinding(token, factory, LIFETIME_SCOPED);
+  }
+
+  instance(token, value) {
+    const normalizedToken = normalizeToken(token);
+    if (this.bindings.has(normalizedToken) || this.instances.has(normalizedToken)) {
+      throw new DuplicateBindingError(`Token \"${tokenLabel(normalizedToken)}\" is already bound.`);
+    }
+
+    this.instances.set(normalizedToken, value);
+    return this;
+  }
+
+  tag(token, tagName) {
+    const normalizedToken = normalizeToken(token);
+    const normalizedTagName = normalizeTagName(tagName);
+
+    if (!this.has(normalizedToken)) {
+      throw new UnresolvedTokenError(`Cannot tag unresolved token \"${tokenLabel(normalizedToken)}\".`);
+    }
+
+    const rootContainer = this.root();
+    if (!rootContainer.tags.has(normalizedTagName)) {
+      rootContainer.tags.set(normalizedTagName, new Set());
+    }
+    rootContainer.tags.get(normalizedTagName).add(normalizedToken);
+    return this;
+  }
+
+  resolveTag(tagName) {
+    const normalizedTagName = normalizeTagName(tagName);
+    const rootContainer = this.root();
+    const tokens = rootContainer.tags.get(normalizedTagName);
+    if (!tokens || tokens.size < 1) {
+      return [];
+    }
+
+    return [...tokens]
+      .sort((left, right) => tokenLabel(left).localeCompare(tokenLabel(right)))
+      .map((token) => this.make(token));
+  }
+
+  createScope(scopeId = "scope") {
+    return new Container({
+      parent: this,
+      scopeId: normalizeScopeId(scopeId)
+    });
+  }
+
+  make(token) {
+    const normalizedToken = normalizeToken(token);
+    const instanceRecord = this.findInstanceRecord(normalizedToken);
+    if (instanceRecord) {
+      return instanceRecord.value;
+    }
+
+    const bindingRecord = this.findBindingRecord(normalizedToken);
+    if (!bindingRecord) {
+      throw new UnresolvedTokenError(`Token \"${tokenLabel(normalizedToken)}\" is not registered.`);
+    }
+
+    const rootContainer = this.root();
+    const stack = rootContainer.resolutionStack;
+    const stackIndex = stack.indexOf(normalizedToken);
+    if (stackIndex >= 0) {
+      const cycle = stack
+        .slice(stackIndex)
+        .concat([normalizedToken])
+        .map((entry) => tokenLabel(entry));
+      throw new CircularDependencyError(`Circular dependency detected: ${cycle.join(" -> ")}.`, {
+        cycle
+      });
+    }
+
+    stack.push(normalizedToken);
+    try {
+      return this.resolveFromBindingRecord(bindingRecord);
+    } finally {
+      stack.pop();
+    }
+  }
+
+  setBinding(token, factory, lifetime) {
+    const normalizedToken = normalizeToken(token);
+    ensureFactory(factory, normalizedToken);
+
+    if (this.bindings.has(normalizedToken) || this.instances.has(normalizedToken)) {
+      throw new DuplicateBindingError(`Token \"${tokenLabel(normalizedToken)}\" is already bound.`);
+    }
+
+    this.bindings.set(normalizedToken, {
+      token: normalizedToken,
+      factory,
+      lifetime
+    });
+
+    return this;
+  }
+
+  findBindingRecord(token) {
+    let node = this;
+    while (node) {
+      if (node.bindings.has(token)) {
+        return {
+          container: node,
+          binding: node.bindings.get(token)
+        };
+      }
+      node = node.parent;
+    }
+
+    return null;
+  }
+
+  findInstanceRecord(token) {
+    let node = this;
+    while (node) {
+      if (node.instances.has(token)) {
+        return {
+          container: node,
+          value: node.instances.get(token)
+        };
+      }
+      node = node.parent;
+    }
+
+    return null;
+  }
+
+  resolveFromBindingRecord(record) {
+    const { container, binding } = record;
+
+    if (binding.lifetime === LIFETIME_SINGLETON) {
+      if (container.instances.has(binding.token)) {
+        return container.instances.get(binding.token);
+      }
+      const created = binding.factory(this);
+      container.instances.set(binding.token, created);
+      return created;
+    }
+
+    if (binding.lifetime === LIFETIME_SCOPED) {
+      if (this.scopedInstances.has(binding.token)) {
+        return this.scopedInstances.get(binding.token);
+      }
+      const created = binding.factory(this);
+      this.scopedInstances.set(binding.token, created);
+      return created;
+    }
+
+    return binding.factory(this);
+  }
+}
+
+function createContainer(options = {}) {
+  return new Container(options);
+}
+
+export { Container, createContainer, tokenLabel };

package/shared/runtime/containerErrors.js

@@ -0,0 +1,22 @@
+class ContainerError extends Error {
+  constructor(message, details = {}) {
+    super(String(message || "Container error."));
+    this.name = this.constructor.name;
+    this.details = details && typeof details === "object" ? { ...details } : {};
+  }
+}
+
+class InvalidTokenError extends ContainerError {}
+class InvalidFactoryError extends ContainerError {}
+class DuplicateBindingError extends ContainerError {}
+class UnresolvedTokenError extends ContainerError {}
+class CircularDependencyError extends ContainerError {}
+
+export {
+  ContainerError,
+  InvalidTokenError,
+  InvalidFactoryError,
+  DuplicateBindingError,
+  UnresolvedTokenError,
+  CircularDependencyError
+};

package/shared/runtime/index.js

@@ -0,0 +1,18 @@
+export { Container, createContainer, tokenLabel } from "./container.js";
+export {
+  ContainerError,
+  InvalidTokenError,
+  InvalidFactoryError,
+  DuplicateBindingError,
+  UnresolvedTokenError,
+  CircularDependencyError
+} from "./containerErrors.js";
+export { Application, createApplication, createProviderClass } from "./application.js";
+export { ServiceProvider } from "./serviceProvider.js";
+export {
+  KernelError,
+  ProviderNormalizationError,
+  DuplicateProviderError,
+  ProviderDependencyError,
+  ProviderLifecycleError
+} from "./kernelErrors.js";

package/shared/runtime/kernelErrors.js

@@ -0,0 +1,20 @@
+class KernelError extends Error {
+  constructor(message, details = {}) {
+    super(String(message || "Kernel error."));
+    this.name = this.constructor.name;
+    this.details = details && typeof details === "object" ? { ...details } : {};
+  }
+}
+
+class ProviderNormalizationError extends KernelError {}
+class DuplicateProviderError extends KernelError {}
+class ProviderDependencyError extends KernelError {}
+class ProviderLifecycleError extends KernelError {}
+
+export {
+  KernelError,
+  ProviderNormalizationError,
+  DuplicateProviderError,
+  ProviderDependencyError,
+  ProviderLifecycleError
+};

package/shared/runtime/serviceProvider.js

@@ -0,0 +1,13 @@
+class ServiceProvider {
+  constructor(app) {
+    this.app = app;
+  }
+
+  register() {}
+
+  boot() {}
+
+  shutdown() {}
+}
+
+export { ServiceProvider };

package/shared/support/formatDateTime.js

@@ -0,0 +1,10 @@
+function formatDateTime(value, { fallback = "unknown" } = {}) {
+  const parsedDate = new Date(value);
+  if (Number.isNaN(parsedDate.getTime())) {
+    return fallback;
+  }
+
+  return parsedDate.toLocaleString();
+}
+
+export { formatDateTime };

package/shared/support/formatDateTime.test.js

@@ -0,0 +1,15 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { formatDateTime } from "./formatDateTime.js";
+
+test("formatDateTime returns fallback for invalid values", () => {
+  assert.equal(formatDateTime("not-a-date"), "unknown");
+  assert.equal(formatDateTime("not-a-date", { fallback: "n/a" }), "n/a");
+});
+
+test("formatDateTime formats valid date-like values", () => {
+  const formatted = formatDateTime("2026-03-14T12:34:56.000Z");
+  assert.equal(typeof formatted, "string");
+  assert.ok(formatted.length > 0);
+  assert.notEqual(formatted, "unknown");
+});

package/shared/support/index.js

@@ -0,0 +1,14 @@
+export { isRecord } from "./normalize.js";
+export { pickOwnProperties } from "./pickOwnProperties.js";
+export { formatDateTime } from "./formatDateTime.js";
+export { appendQueryString } from "./queryPath.js";
+export { normalizePermissionList, hasPermission } from "./permissions.js";
+export {
+  normalizeReturnToPath,
+  resolveAllowedOriginsFromPlacementContext
+} from "./returnToPath.js";
+export {
+  isTransientQueryError,
+  shouldRetryTransientQueryFailure,
+  transientQueryRetryDelay
+} from "./queryResilience.js";