akanjs 0.0.1 → 2.0.0-beta.0

package/server/di/resolveHierarchy.ts

@@ -0,0 +1,89 @@
+export interface DependencyNode {
+  key: string;
+  dependencies: string[];
+}
+
+/**
+ * Groups nodes into sequential stages where all nodes within a stage
+ * can be initialized concurrently (all their dependencies are satisfied
+ * by earlier stages).
+ */
+export function topologicalStages<T extends DependencyNode>(graph: Map<string, T>): string[][] {
+  const inDegree = new Map<string, number>();
+  const dependents = new Map<string, string[]>();
+
+  for (const [key, node] of graph) {
+    inDegree.set(key, node.dependencies.length);
+    dependents.set(key, []);
+  }
+
+  for (const [, node] of graph) {
+    for (const dep of node.dependencies) {
+      dependents.get(dep)?.push(node.key);
+    }
+  }
+
+  let queue: string[] = [];
+  for (const [key, degree] of inDegree) {
+    if (degree === 0) queue.push(key);
+  }
+
+  const stages: string[][] = [];
+  let processed = 0;
+
+  while (queue.length > 0) {
+    stages.push(queue);
+    processed += queue.length;
+
+    const next: string[] = [];
+    for (const key of queue) {
+      for (const dependent of dependents.get(key)!) {
+        const newDegree = inDegree.get(dependent)! - 1;
+        inDegree.set(dependent, newDegree);
+        if (newDegree === 0) next.push(dependent);
+      }
+    }
+    queue = next;
+  }
+
+  if (processed !== graph.size) {
+    const remaining = [...graph.keys()].filter((k) => inDegree.get(k)! > 0);
+    const cycle = traceCycle(graph, remaining);
+    throw new Error(`Circular dependency detected: ${cycle.join(" → ")}`);
+  }
+
+  return stages;
+}
+
+export function traceCycle<T extends DependencyNode>(graph: Map<string, T>, candidates: string[]): string[] {
+  const visited = new Set<string>();
+  const path: string[] = [];
+
+  function dfs(key: string): string[] | null {
+    if (path.includes(key)) {
+      const cycleStart = path.indexOf(key);
+      return [...path.slice(cycleStart), key];
+    }
+    if (visited.has(key)) return null;
+    visited.add(key);
+    path.push(key);
+
+    const node = graph.get(key);
+    if (node) {
+      for (const dep of node.dependencies) {
+        const cycle = dfs(dep);
+        if (cycle) return cycle;
+      }
+    }
+
+    path.pop();
+    return null;
+  }
+
+  for (const key of candidates) {
+    const cycle = dfs(key);
+    if (cycle) return cycle;
+  }
+
+  return candidates;
+}

package/server/di/resolveServiceHierarchy.ts

@@ -0,0 +1,47 @@
+import { INJECT_META } from "akanjs/base";
+import type { InjectInfo, ServiceCls } from "akanjs/service";
+import { type DependencyNode, topologicalStages } from "./resolveHierarchy";
+
+interface ServiceNode extends DependencyNode {
+  service: ServiceCls;
+}
+
+export interface ServiceHierarchy {
+  graph: Map<string, ServiceNode>;
+  classToKey: Map<ServiceCls, string>;
+  /** Each stage contains service map keys that can be initialized concurrently. Stages run sequentially. */
+  stages: string[][];
+}
+
+export function resolveServiceHierarchy(serviceMap: Map<string, ServiceCls>): ServiceHierarchy {
+  const classToKey = new Map<ServiceCls, string>();
+  for (const [key, service] of serviceMap) {
+    classToKey.set(service, key);
+  }
+
+  const graph = new Map<string, ServiceNode>();
+
+  for (const [key, service] of serviceMap) {
+    const injectMap: Record<string, InjectInfo> = service[INJECT_META] ?? {};
+    const dependencies: string[] = [];
+
+    for (const [propKey, injectInfo] of Object.entries(injectMap)) {
+      if (injectInfo.type === "service") {
+        const depKey = propKey.replace(/Service$/, "");
+        if (serviceMap.has(depKey) && depKey !== key) {
+          dependencies.push(depKey);
+        }
+      } else if (injectInfo.type === "database") {
+        const depKey = propKey.replace(/Model$/, "");
+        if (serviceMap.has(depKey) && depKey !== key) {
+          dependencies.push(depKey);
+        }
+      }
+    }
+
+    graph.set(key, { key, service, dependencies });
+  }
+  const stages = topologicalStages(graph);
+
+  return { graph, classToKey, stages };
+}

package/server/di/utils.ts

@@ -0,0 +1,40 @@
+interface StageTask {
+  label: string;
+  run: () => Promise<unknown>;
+}
+
+/**
+ * Run every task in parallel and, if any rejects, throw a single
+ * `AggregateError` that enumerates every failing label + cause. This replaces
+ * the previous `Promise.all` flow where a second concurrent failure in the
+ * same stage would hide the first, making boot errors hard to localize.
+ */
+export const runStage = async (stageLabel: string, tasks: StageTask[]): Promise<void> => {
+  if (tasks.length === 0) return;
+  const settled = await Promise.allSettled(tasks.map((t) => t.run()));
+  const failures: { label: string; reason: unknown }[] = [];
+  settled.forEach((res, i) => {
+    if (res.status === "rejected") {
+      const task = tasks[i];
+      failures.push({ label: task ? task.label : `#${i}`, reason: res.reason });
+    }
+  });
+  if (failures.length === 0) return;
+  const summary = failures.map((f) => `  • ${f.label}: ${reasonMessage(f.reason)}`).join("\n");
+  const errors = failures.map((f) => toError(f.reason));
+  throw new AggregateError(errors, `[DI:${stageLabel}] ${failures.length}/${tasks.length} task(s) failed:\n${summary}`);
+};
+
+export const toError = (reason: unknown): Error => {
+  return reason instanceof Error ? reason : new Error(String(reason));
+};
+
+export const reasonMessage = (reason: unknown): string => {
+  if (reason instanceof Error) {
+    if (reason instanceof AggregateError && reason.errors?.length) {
+      return `${reason.message} [${reason.errors.length} nested]`;
+    }
+    return reason.message;
+  }
+  return String(reason);
+};

package/server/hmr/changeBatch.ts

@@ -0,0 +1,14 @@
+/**
+ * Runtime-safe change-classification types shared between the dev-time
+ * filesystem watcher (which lives in `akanjs/devkit/frontendBuild`) and
+ * the server-side HMR controller that consumes its batches over IPC.
+ *
+ * Keeping these as a types-only module lets the server package stay
+ * completely independent of `fs.watch` / `node:fs`.
+ */
+export type ChangeKind = "code" | "css" | "config" | "ignore";
+
+export interface ChangeBatch {
+  files: string[];
+  kinds: Set<Exclude<ChangeKind, "ignore">>;
+}

package/server/hmr/clientScript.ts

@@ -0,0 +1,310 @@
+
+
+export const HMR_CLIENT_SCRIPT = `(function(){
+  if (self.__AKAN_HMR_INSTALLED__) return;
+  self.__AKAN_HMR_INSTALLED__ = true;
+  var proto = location.protocol === "https:" ? "wss:" : "ws:";
+  var url = proto + "//" + location.host + "/_akan/hmr";
+  var attempts = 0;
+  var socket = null;
+  var lastBuildId = null;
+  var refreshRuntimePromise = null;
+  var refreshQueue = Promise.resolve();
+  var overlayEl = null;
+  var overlayLabelEl = null;
+  var overlayStyleEl = null;
+  var overlayTimer = null;
+  var overlayHideTimer = null;
+  var overlayNextToken = 1;
+  var overlayJobs = {};
+  self.__AKAN_HMR_PHASE__ = null;
+
+  self.$RefreshReg$ = self.$RefreshReg$ || function(){};
+  self.$RefreshSig$ = self.$RefreshSig$ || function(){ return function(type){ return type; }; };
+
+  function connect(){
+    try { socket = new WebSocket(url); }
+    catch(e){ console.error("[akan-hmr] ws init failed", e); schedule(); return; }
+    socket.addEventListener("open", function(){ attempts = 0; });
+    socket.addEventListener("message", function(ev){
+      var msg;
+      try { msg = JSON.parse(ev.data); } catch (e){ return; }
+      if (!msg || typeof msg.type !== "string") return;
+      if (msg.type === "hello") {
+        if (lastBuildId !== null && msg.buildId !== lastBuildId) {
+          location.reload();
+          return;
+        }
+        lastBuildId = msg.buildId;
+        return;
+      }
+      if (msg.type === "reload") {
+        beginHmrOverlay("Reloading...", true);
+        try { self.__AKAN_RSC_CLEAR_CACHE__ && self.__AKAN_RSC_CLEAR_CACHE__(); } catch(e){}
+        setTimeout(function(){ location.reload(); }, 30);
+        return;
+      }
+      if (msg.type === "rsc-refresh") {
+        refreshRsc(msg);
+        return;
+      }
+      if (msg.type === "client-refresh") {
+        refreshClient(msg);
+        return;
+      }
+      if (msg.type === "css-update") {
+        var cssUrl = selectCssUrl(msg.cssAssets);
+        if (cssUrl) swapCss(cssUrl);
+        else {
+          beginHmrOverlay("Reloading...", true);
+          location.reload();
+        }
+        return;
+      }
+      if (msg.type === "error") { console.error("[akan-hmr]", msg.message); return; }
+    });
+    socket.addEventListener("close", function(){ socket = null; schedule(); });
+    socket.addEventListener("error", function(){ try { socket && socket.close(); } catch(e){} });
+  }
+
+  function schedule(){
+    attempts = Math.min(attempts + 1, 6);
+    var delay = Math.min(30000, 250 * Math.pow(2, attempts - 1));
+    setTimeout(connect, delay);
+  }
+
+  function ensureOverlay(){
+    if (overlayEl && overlayLabelEl) return overlayEl;
+    if (!overlayStyleEl) {
+      overlayStyleEl = document.createElement("style");
+      overlayStyleEl.textContent =
+        "@keyframes akan-hmr-spin{to{transform:rotate(360deg)}}" +
+        ".__akan_hmr_overlay{position:fixed;left:16px;bottom:16px;z-index:2147483647;display:flex;align-items:center;gap:9px;padding:10px 12px;border-radius:999px;background:rgba(17,24,39,.94);color:#fff;font:500 13px/1.2 ui-sans-serif,system-ui,-apple-system,BlinkMacSystemFont,Segoe UI,sans-serif;box-shadow:0 10px 28px rgba(0,0,0,.28);pointer-events:none;opacity:0;transform:translateY(6px);transition:opacity .15s ease,transform .15s ease;backdrop-filter:blur(8px)}" +
+        ".__akan_hmr_overlay[data-show=true]{opacity:1;transform:translateY(0)}" +
+        ".__akan_hmr_spinner{width:14px;height:14px;border:2px solid rgba(255,255,255,.32);border-top-color:#fff;border-radius:999px;animation:akan-hmr-spin .75s linear infinite;flex:none}" +
+        "@media (prefers-reduced-motion:reduce){.__akan_hmr_overlay{transition:none}.__akan_hmr_spinner{animation:none}}";
+      document.head.appendChild(overlayStyleEl);
+    }
+    overlayEl = document.createElement("div");
+    overlayEl.className = "__akan_hmr_overlay";
+    overlayEl.setAttribute("role", "status");
+    overlayEl.setAttribute("aria-live", "polite");
+    overlayEl.innerHTML = '<span class="__akan_hmr_spinner" aria-hidden="true"></span><span data-akan-hmr-label>Updating...</span>';
+    overlayLabelEl = overlayEl.querySelector("[data-akan-hmr-label]");
+    (document.body || document.documentElement).appendChild(overlayEl);
+    return overlayEl;
+  }
+
+  function activeOverlayTokens(){
+    return Object.keys(overlayJobs);
+  }
+
+  function latestOverlayLabel(){
+    var keys = activeOverlayTokens();
+    if (keys.length === 0) return "Updating...";
+    return overlayJobs[keys[keys.length - 1]] || "Updating...";
+  }
+
+  function showOverlayNow(){
+    overlayTimer = null;
+    if (activeOverlayTokens().length === 0) return;
+    var el = ensureOverlay();
+    if (overlayHideTimer) {
+      clearTimeout(overlayHideTimer);
+      overlayHideTimer = null;
+    }
+    if (overlayLabelEl) overlayLabelEl.textContent = latestOverlayLabel();
+    requestAnimationFrame(function(){ el.setAttribute("data-show", "true"); });
+  }
+
+  function beginHmrOverlay(label, immediate){
+    var token = overlayNextToken++;
+    overlayJobs[token] = label || "Updating...";
+    if (overlayLabelEl) overlayLabelEl.textContent = latestOverlayLabel();
+    if (overlayHideTimer) {
+      clearTimeout(overlayHideTimer);
+      overlayHideTimer = null;
+    }
+    if (immediate) {
+      if (overlayTimer) clearTimeout(overlayTimer);
+      showOverlayNow();
+    } else if (!overlayTimer && (!overlayEl || overlayEl.getAttribute("data-show") !== "true")) {
+      overlayTimer = setTimeout(showOverlayNow, 120);
+    }
+    return token;
+  }
+
+  function setHmrOverlayLabel(token, label){
+    if (!overlayJobs[token]) return;
+    overlayJobs[token] = label || "Updating...";
+    if (overlayLabelEl) overlayLabelEl.textContent = latestOverlayLabel();
+  }
+
+  function endHmrOverlay(token){
+    delete overlayJobs[token];
+    if (activeOverlayTokens().length > 0) {
+      if (overlayLabelEl) overlayLabelEl.textContent = latestOverlayLabel();
+      return;
+    }
+    if (overlayTimer) {
+      clearTimeout(overlayTimer);
+      overlayTimer = null;
+    }
+    if (!overlayEl) return;
+    overlayEl.setAttribute("data-show", "false");
+    if (overlayHideTimer) clearTimeout(overlayHideTimer);
+    overlayHideTimer = setTimeout(function(){
+      if (overlayEl && activeOverlayTokens().length === 0 && overlayEl.parentNode) {
+        overlayEl.parentNode.removeChild(overlayEl);
+        overlayEl = null;
+        overlayLabelEl = null;
+      }
+    }, 180);
+  }
+
+  function refreshRsc(msg){
+    var started = performance.now();
+    var overlayToken = beginHmrOverlay("Refreshing page...");
+    try { self.__AKAN_RSC_CLEAR_CACHE__ && self.__AKAN_RSC_CLEAR_CACHE__(); } catch(e){}
+    if (!self.__AKAN_RSC_REFRESH__) {
+      console.warn("[akan-hmr] RSC refresh API unavailable, falling back to full reload");
+      setHmrOverlayLabel(overlayToken, "Reloading...");
+      setTimeout(function(){ location.reload(); }, 30);
+      return;
+    }
+    Promise.resolve(self.__AKAN_RSC_REFRESH__({ buildId: msg.buildId })).then(function(){
+      lastBuildId = msg.buildId;
+      endHmrOverlay(overlayToken);
+      console.debug && console.debug("[akan-hmr] RSC refreshed", {
+        buildId: msg.buildId,
+        generation: msg.generation,
+        routeIds: msg.routeIds,
+        changedFiles: msg.changedFiles && msg.changedFiles.length,
+        durationMs: Math.round(performance.now() - started)
+      });
+    }, function(err){
+      console.error("[akan-hmr] RSC refresh failed, falling back to full reload", err);
+      setHmrOverlayLabel(overlayToken, "Update failed, reloading...");
+      setTimeout(function(){ location.reload(); }, 250);
+    });
+  }
+
+  function ensureRefreshRuntime(){
+    if (refreshRuntimePromise) return refreshRuntimePromise;
+    refreshRuntimePromise = import("react-refresh/runtime").then(function(mod){
+      var runtime = mod.default || mod;
+      if (!self.__AKAN_REACT_REFRESH_READY__) {
+        runtime.injectIntoGlobalHook(self);
+        self.$RefreshReg$ = function(type, id){ runtime.register(type, id); };
+        self.$RefreshSig$ = runtime.createSignatureFunctionForTransform;
+        self.__AKAN_REACT_REFRESH_READY__ = true;
+        self.__AKAN_REACT_REFRESH_RUNTIME__ = runtime;
+      }
+      return runtime;
+    });
+    return refreshRuntimePromise;
+  }
+
+  function refreshClient(msg){
+    refreshQueue = refreshQueue.then(function(){ return doRefreshClient(msg); }, function(){ return doRefreshClient(msg); });
+  }
+
+  function setHmrPhase(phase){
+    self.__AKAN_HMR_PHASE__ = phase;
+  }
+
+  function doRefreshClient(msg){
+    var started = performance.now();
+    var metadataAt = started;
+    var importAt = started;
+    var refreshAt = started;
+    var overlayToken = beginHmrOverlay("Updating...");
+    var fallbackToRsc = false;
+    return ensureRefreshRuntime().then(function(runtime){
+      setHmrOverlayLabel(overlayToken, "Fetching update...");
+      var endpoint = new URL("/_akan/hmr/client-refresh", location.origin);
+      endpoint.searchParams.set("url", location.href);
+      if (msg.buildId != null) endpoint.searchParams.set("buildId", String(msg.buildId));
+      return fetch(endpoint, { credentials: "same-origin", cache: "no-store" })
+        .then(function(res){
+          if (!res.ok) throw new Error("client-refresh metadata failed " + res.status + " " + res.statusText);
+          return res.json();
+        })
+        .then(function(info){
+          metadataAt = performance.now();
+          var chunks = Array.isArray(info.chunks) ? info.chunks : [];
+          if (chunks.length === 0) throw new Error("no client chunks returned");
+          setHmrPhase("refresh-import");
+          setHmrOverlayLabel(overlayToken, "Importing update...");
+          return Promise.all(chunks.map(function(chunk){ return import(chunk); })).then(function(){
+            importAt = performance.now();
+            setHmrPhase("react-refresh");
+            setHmrOverlayLabel(overlayToken, "Applying update...");
+            try {
+              runtime.performReactRefresh();
+            } finally {
+              setHmrPhase(null);
+            }
+            refreshAt = performance.now();
+            lastBuildId = msg.buildId;
+            console.debug && console.debug("[akan-hmr] React Fast Refresh applied", {
+              buildId: msg.buildId,
+              generation: msg.generation,
+              chunks: chunks.length,
+              routeIds: info.routeIds || msg.routeIds,
+              changedFiles: msg.changedFiles && msg.changedFiles.length,
+              metadataMs: Math.round(metadataAt - started),
+              importMs: Math.round(importAt - metadataAt),
+              refreshMs: Math.round(refreshAt - importAt),
+              durationMs: Math.round(refreshAt - started)
+            });
+            endHmrOverlay(overlayToken);
+          }, function(err){
+            setHmrPhase(null);
+            throw err;
+          });
+        });
+    }).catch(function(err){
+      console.warn("[akan-hmr] React Fast Refresh failed, falling back to RSC refresh", err);
+      fallbackToRsc = true;
+      endHmrOverlay(overlayToken);
+      refreshRsc(msg);
+    }).finally(function(){
+      if (!fallbackToRsc) endHmrOverlay(overlayToken);
+    });
+  }
+
+  function swapCss(href){
+    var overlayToken = beginHmrOverlay("Updating styles...");
+    var link = document.createElement("link");
+    link.rel = "stylesheet";
+    link.href = href;
+    link.setAttribute("data-akan-css", "pending");
+    link.addEventListener("load", function(){
+      var prev = document.querySelectorAll("link[data-akan-css=active]");
+      for (var i = 0; i < prev.length; i++) prev[i].parentNode && prev[i].parentNode.removeChild(prev[i]);
+      link.setAttribute("data-akan-css", "active");
+      endHmrOverlay(overlayToken);
+    });
+    link.addEventListener("error", function(){
+      if (link.parentNode) link.parentNode.removeChild(link);
+      endHmrOverlay(overlayToken);
+    });
+    document.head.appendChild(link);
+  }
+
+  function selectCssUrl(cssAssets){
+    if (!cssAssets || typeof cssAssets !== "object") return null;
+    var parts = location.pathname.split("/").filter(Boolean);
+    for (var i = 0; i < parts.length; i++) {
+      var asset = cssAssets[parts[i]];
+      if (asset && asset.cssUrl) return asset.cssUrl;
+    }
+    return cssAssets[""] && cssAssets[""].cssUrl ? cssAssets[""].cssUrl : null;
+  }
+
+  ensureRefreshRuntime().catch(function(err){
+    console.warn("[akan-hmr] React Refresh runtime preload failed", err);
+  });
+  connect();
+})();`;