akanjs 3.0.0-beta.2 → 3.0.0-beta.20

package/server/di/predefinedAdaptor.ts

@@ -1,4 +1,5 @@
 import type { DatabaseMode } from "akanjs";
+import { DatabaseModes } from "akanjs/base";
 import {
   type AdaptorCls,
   BlobStorage,
@@ -10,13 +11,12 @@ import {
   ConsoleLogger,
   type DatabaseAdaptor,
   DatabaseAdaptorRole,
-  DeepseekLlm,
   JsonCompressor,
-  LibsqlDatabase,
   type LlmAdaptor,
   LlmAdaptorRole,
   type LoggingAdaptor,
   LoggingAdaptorRole,
+  OpenaiLlm,
   PostgresDatabase,
   type QueueAdaptor,
   QueueAdaptorRole,
@@ -34,6 +34,7 @@ import {
   type WebsocketAdaptor,
   WebsocketAdaptorRole,
 } from "akanjs/service";
+import { collectAdaptors } from "./resolveHierarchy";
 
 export interface PredefinedAdaptor {
   database: AdaptorCls<DatabaseAdaptor>;
@@ -68,14 +69,19 @@ export const predefinedAdaptor = {
   logging: ConsoleLogger,
   websocket: SolidPubSub,
   compress: JsonCompressor,
-  llm: DeepseekLlm,
+  llm: OpenaiLlm,
+};
+
+export const collectPredefinedDependencies = (adaptors: PredefinedAdaptor): AdaptorCls[] => {
+  const roles = new Set<AdaptorCls>(Object.values(predefinedAdaptorRole));
+  return [...collectAdaptors(Object.values(adaptors))].filter((adaptor) => !roles.has(adaptor));
 };
 
 export const getPredefinedAdaptor = (mode: DatabaseMode = "single"): PredefinedAdaptor => {
-  if (mode === "single") return predefinedAdaptor;
+  if (DatabaseModes.parse(mode, "The database mode") === "single") return predefinedAdaptor;
   return {
     ...predefinedAdaptor,
-    database: mode === "cluster" ? PostgresDatabase : LibsqlDatabase,
+    database: mode === "cluster" ? PostgresDatabase : SqliteDatabase,
     cache: RedisCache,
     queue: BullQueue,
     websocket: WebSocketRedisAdaptor,

package/server/di/resolveHierarchy.ts

@@ -1,13 +1,11 @@
+import { INJECT_META } from "akanjs/base";
+import { type AdaptorCls, CacheAdaptorRole, type InjectInfo, type ServiceCls } from "akanjs/service";
+
 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[]>();
@@ -87,3 +85,114 @@ export function traceCycle<T extends DependencyNode>(graph: Map<string, T>, cand
 
   return candidates;
 }
+
+interface ServiceNode extends DependencyNode {
+  service: ServiceCls;
+}
+
+export interface ServiceHierarchy {
+  graph: Map<string, ServiceNode>;
+  stages: string[][];
+}
+
+export function resolveServiceHierarchy(serviceMap: Map<string, ServiceCls>): ServiceHierarchy {
+  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, { type }] of Object.entries(injectMap)) {
+      if (type !== "service" && type !== "database") continue;
+      const depKey = propKey.replace(type === "service" ? /Service$/ : /Model$/, "");
+      if (serviceMap.has(depKey) && depKey !== key) dependencies.push(depKey);
+    }
+
+    graph.set(key, { key, service, dependencies });
+  }
+  const stages = topologicalStages(graph);
+
+  return { graph, stages };
+}
+
+interface AdaptorNode extends DependencyNode {
+  adaptor: AdaptorCls;
+}
+
+export interface AdaptorHierarchy {
+  graph: Map<string, AdaptorNode>;
+  stages: string[][];
+}
+
+export function collectAdaptors(sources: { [INJECT_META]: Record<string, InjectInfo> }[]): Set<AdaptorCls> {
+  const discovered = new Set<AdaptorCls>();
+
+  function scan(injectMap: Record<string, InjectInfo>) {
+    for (const injectInfo of Object.values(injectMap)) {
+      if (injectInfo.type === "plug" && injectInfo.adaptor && !discovered.has(injectInfo.adaptor)) {
+        discovered.add(injectInfo.adaptor);
+        scan(injectInfo.adaptor[INJECT_META] ?? {});
+      }
+    }
+  }
+
+  for (const source of sources) {
+    scan(source[INJECT_META] ?? {});
+  }
+
+  return discovered;
+}
+
+export function resolveAdaptorHierarchy(
+  adaptorMap: Map<string, AdaptorCls>,
+  adaptorRole: Map<AdaptorCls, AdaptorCls> = new Map(),
+): AdaptorHierarchy {
+  const classToKey = new Map<AdaptorCls, string>();
+  for (const [key, adaptor] of adaptorMap) {
+    classToKey.set(adaptor, key);
+  }
+  for (const [role, provider] of adaptorRole) {
+    const providerKey = classToKey.get(provider);
+    if (providerKey) classToKey.set(role, providerKey);
+  }
+
+  const graph = new Map<string, AdaptorNode>();
+
+  for (const [key, adaptor] of adaptorMap) {
+    const injectMap: Record<string, InjectInfo> = adaptor[INJECT_META] ?? {};
+    const dependencies: string[] = [];
+    const addDependency = (depKey: string) => {
+      if (depKey !== key && !dependencies.includes(depKey)) dependencies.push(depKey);
+    };
+
+    for (const [propKey, injectInfo] of Object.entries(injectMap)) {
+      if (injectInfo.type === "plug") {
+        if (!injectInfo.adaptor) continue;
+        const depKey = classToKey.get(injectInfo.adaptor);
+        if (!depKey) {
+          throw new Error(
+            `Adaptor "${key}" has a plug dependency (property "${propKey}") ` +
+              `on adaptor "${injectInfo.adaptor.refName}" which is not registered.`,
+          );
+        }
+        addDependency(depKey);
+      } else if (injectInfo.type === "use") {
+        if (adaptorMap.has(propKey) && propKey !== key) {
+          addDependency(propKey);
+        }
+      } else if (injectInfo.type === "memory") {
+        const depKey = classToKey.get(CacheAdaptorRole);
+        if (!depKey) {
+          throw new Error(`Adaptor "${key}" has a memory dependency but cache adaptor role is not registered.`);
+        }
+        addDependency(depKey);
+      }
+    }
+
+    graph.set(key, { key, adaptor, dependencies });
+  }
+
+  const stages = topologicalStages(graph);
+
+  return { graph, stages };
+}

package/server/di/utils.ts

@@ -1,5 +1,5 @@
 import { INJECT_META } from "akanjs/base";
-import { lowerlize } from "akanjs/common";
+import { lowerlize, toError } from "akanjs/common";
 import { ConstantRegistry } from "akanjs/constant";
 import type { InjectInfo } from "akanjs/service";
 import type { DatabaseModule, ServiceModule } from "../akanLib";
@@ -68,12 +68,6 @@ export const getModuleDependencyRefNames = (mod: DatabaseModule | ServiceModule)
   return dependencies;
 };
 
-/**
- * The modules a cascade edge forces this one to be mounted with: a `removeRef` target and a monomorphic
- * `removeWith` owner both fail `CascadeRunner.seal` when they are absent, so they are boot dependencies the
- * inject graph cannot see. A polymorphic owner is exempt — an enum list spans optional modules by design, and
- * `cascade: "removeWithAny"` names no module at all.
- */
 export const getModuleCascadeRefNames = (mod: DatabaseModule | ServiceModule) => {
   const dependencies = new Set<string>();
   if (!("constant" in mod)) return dependencies;
@@ -92,10 +86,6 @@ export interface Registration {
   owner: string;
 }
 
-/**
- * A key registered twice is silently last-write-wins everywhere downstream — an app that meant to add a second
- * adaptor gets one, and the other's `onInit` never runs. Refuse the boot instead, naming both claimants.
- */
 export const assertUniqueRegistrations = (kind: string, registrations: Registration[]) => {
   const claimed = new Map<string, string>();
   const clashes: string[] = [];
@@ -108,30 +98,24 @@ export const assertUniqueRegistrations = (kind: string, registrations: Registrat
   throw new Error(`[DI:${kind}] ${clashes.length} duplicate registration(s):\n${clashes.join("\n")}`);
 };
 
-/**
- * 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 });
-    }
-  });
+  const failures = settled.flatMap((res, i) =>
+    res.status === "rejected" ? [{ label: tasks[i]?.label ?? `#${i}`, reason: res.reason }] : [],
+  );
+  throwStageFailures(stageLabel, failures, tasks.length);
+};
+
+export const throwStageFailures = (
+  stageLabel: string,
+  failures: { label: string; reason: unknown }[],
+  total: number,
+) => {
   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));
+  throw new AggregateError(errors, `[DI:${stageLabel}] ${failures.length}/${total} task(s) failed:\n${summary}`);
 };
 
 export const reasonMessage = (reason: unknown): string => {

package/server/head.tsx

@@ -0,0 +1,53 @@
+import type { Head, ResolvedHead, ResolveHeadResult } from "akanjs/client";
+import { isRecord } from "akanjs/common";
+import { AKAN_RSC_HEAD_SNAPSHOT_VERSION, type AkanHeadSnapshotV1 } from "./routeState";
+
+export function createAkanLocaleAlternateHeadSnapshot(languages: Record<string, string>): AkanHeadSnapshotV1 {
+  return {
+    version: AKAN_RSC_HEAD_SNAPSHOT_VERSION,
+    nodes: Object.entries(languages).map(([lang, href]) => ({
+      tag: "link",
+      attrs: { rel: "alternate", hrefLang: lang, href },
+    })),
+  };
+}
+
+export function mergeAkanHeadSnapshots(
+  ...snapshots: Array<AkanHeadSnapshotV1 | null | undefined>
+): AkanHeadSnapshotV1 | undefined {
+  const nodes = snapshots.flatMap((snapshot) => snapshot?.nodes ?? []);
+  return snapshots.some(Boolean) ? { version: AKAN_RSC_HEAD_SNAPSHOT_VERSION, nodes } : undefined;
+}
+
+export function renderAkanHeadSnapshot(snapshot: AkanHeadSnapshotV1): Head {
+  return (
+    <>
+      {snapshot.nodes.map((node, index) => {
+        const key = `${node.tag}:${index}`;
+        const marker = { "data-akan-head": "route", "data-akan-head-key": key };
+        if (node.tag === "title") {
+          return (
+            <title key={key} {...marker}>
+              {node.text ?? ""}
+            </title>
+          );
+        }
+        if (node.tag === "meta") return <meta key={key} {...node.attrs} {...marker} />;
+        return <link key={key} {...node.attrs} {...marker} />;
+      })}
+    </>
+  );
+}
+
+export function shouldRenderLocaleAlternates(options: { isSpecialRoute?: boolean }): boolean {
+  return options.isSpecialRoute !== true;
+}
+
+function isResolvedHead(value: unknown): value is ResolvedHead {
+  return isRecord(value) && "node" in value;
+}
+
+export function resolveHeadResult(value: ResolveHeadResult): ResolvedHead {
+  if (isResolvedHead(value)) return value;
+  return { node: value };
+}

package/server/hmr/clientScript.ts

@@ -1,15 +1,9 @@
-
-
-const SYNC_NAVIGATION_ENABLED =
-  process.env.AKAN_PUBLIC_SYNC_NAVIGATION === "true" ||
-  process.env.AKAN_PUBLIC_SYNC_NAVIGATION === "1" ||
-  process.env.SYNC_DOMAIN === "true" ||
-  process.env.SYNC_DOMAIN === "1";
+import { isSyncNavigationEnabled } from "./wsHub";
 
 export const HMR_CLIENT_SCRIPT = `(function(){
   if (self.__AKAN_HMR_INSTALLED__) return;
   self.__AKAN_HMR_INSTALLED__ = true;
-  var syncNavigationEnabled = ${JSON.stringify(SYNC_NAVIGATION_ENABLED)};
+  var syncNavigationEnabled = ${JSON.stringify(isSyncNavigationEnabled())};
   var syncNavigationClientId = Math.random().toString(36).slice(2) + Date.now().toString(36);
   var proto = location.protocol === "https:" ? "wss:" : "ws:";
   var url = proto + "//" + location.host + "/_akan/hmr";

package/server/hmr/devHmrController.ts

@@ -10,8 +10,7 @@ import {
 } from "../artifact";
 import type { RscWorker } from "../rscWorkerHost";
 import type { RenderState } from "../types";
-import type { ChangeKind } from "./changeBatch";
-import { type HmrMessage, type HmrWsData, HmrWsHub } from "./wsHub";
+import { type ChangeKind, type HmrMessage, type HmrWsData, HmrWsHub } from "./wsHub";
 
 const APP_RUNTIME_METADATA_BASENAMES = new Set(["dict.ts", "sig.ts", "useClient.ts"]);
 
@@ -99,11 +98,13 @@ export class DevHmrController {
   readonly #dirty = new Set<Exclude<ChangeKind, "ignore">>();
   readonly #dirtyFiles = new Set<string>();
   readonly #buildStatusByPhase = new Map<DevBuildStatus["phase"], DevBuildStatus>();
+  readonly #graphSeeds: string[];
 
   constructor({ renderState, rsc, seedIndex, upgradeHmrWs }: DevHmrControllerOptions) {
     this.#renderState = renderState;
     this.#rsc = rsc;
     this.#seedIndex = seedIndex;
+    this.#graphSeeds = [...new Set([...seedIndex.globalLayoutFiles, ...seedIndex.entries.flatMap((e) => e.seeds)])];
     this.#upgradeHmrWs = upgradeHmrWs;
     this.#builderRpc = this.#createBuilderRpc();
     this.routeCache = this.#createRouteCache();
@@ -121,13 +122,8 @@ export class DevHmrController {
     this.#builderRpc.dispose();
   }
 
-  broadcastError(message: string): void {
-    this.#hub.broadcast({ type: "error", message });
-  }
-
   handleWs(req: Request): Response | undefined {
-    const upgraded = this.#upgradeHmrWs(req, { kind: "akan-hmr", openedAt: Date.now() });
-    if (upgraded) return;
+    if (this.#upgradeHmrWs(req, { kind: "akan-hmr", openedAt: Date.now() })) return;
     return new Response("Failed to upgrade HMR WebSocket", { status: 500 });
   }
 
@@ -142,14 +138,15 @@ export class DevHmrController {
       if (!DevHmrController.#isTrustedRscTarget(clientOrigin, targetUrl))
         return new Response("Bad Request", { status: 400 });
       const manifest = await this.ensureRoute(targetUrl);
+      const chunks = DevHmrController.clientChunkUrls(manifest.clientManifest);
       this.#logger.verbose(
-        `[hmr] client-refresh metadata route=${targetUrl.pathname} chunks=${DevHmrController.clientChunkUrls(manifest.clientManifest).length} in ${Date.now() - started}ms`,
+        `[hmr] client-refresh metadata route=${targetUrl.pathname} chunks=${chunks.length} in ${Date.now() - started}ms`,
       );
       return new Response(
         JSON.stringify({
           buildId: this.#renderState.buildId,
           generation: manifest.generation,
-          chunks: DevHmrController.clientChunkUrls(manifest.clientManifest),
+          chunks,
           routeIds: this.routeIdsForPath(targetUrl.pathname),
         }),
         { headers: { "Content-Type": "application/json; charset=utf-8", "Cache-Control": "no-store" } },
@@ -163,7 +160,9 @@ export class DevHmrController {
 
   async ensureRoute(url: URL) {
     const started = Date.now();
-    const matched = RouteSeedIndexStore.match(url.pathname, this.#seedIndex.entries);
+    const matched =
+      RouteSeedIndexStore.match(url.pathname, this.#seedIndex.entries) ??
+      RouteSeedIndexStore.matchPrefix(url.pathname, this.#seedIndex.entries);
     if (matched) await this.routeCache.ensure(matched.entry.routeId, matched.entry.seeds);
     this.#logger.verbose(
       `[route-cache] ensure pathname=${url.pathname} routeId=${matched?.entry.routeId ?? "(none)"} in ${Date.now() - started}ms`,
@@ -187,10 +186,6 @@ export class DevHmrController {
     return [...urls];
   }
 
-  static shouldFullReloadForRuntimeMetadata(files: string[]): boolean {
-    return files.some(isAkanRuntimeMetadataFile);
-  }
-
   #createBuilderRpc() {
     return new BuilderRpc({
       onInvalidate: (ev) => {
@@ -218,7 +213,7 @@ export class DevHmrController {
       onPagesUpdated: async ({ bundlePath, buildId, generation, changedFiles }) => {
         const started = Date.now();
         const files = changedFiles ?? [];
-        const runtimeMetadataChanged = DevHmrController.shouldFullReloadForRuntimeMetadata(files);
+        const runtimeMetadataChanged = files.some(isAkanRuntimeMetadataFile);
         const staleClientEntries = runtimeMetadataChanged ? new Set<string>() : this.#staleClientEntriesForFiles(files);
         const routeIds = runtimeMetadataChanged ? undefined : this.#routeIdsForFiles(files, staleClientEntries);
         const fastRefreshCandidate = !runtimeMetadataChanged && this.#isFastRefreshCandidate(files);
@@ -265,7 +260,12 @@ export class DevHmrController {
     return new RouteClientCache({
       buildRoute: async (routeId, { seeds, knownEntries, generation }) => {
         const expandedSeeds = [...new Set([...this.#seedIndex.globalLayoutFiles, ...seeds])];
-        return this.#builderRpc.buildRoute(routeId, { seeds: expandedSeeds, knownEntries, generation });
+        return this.#builderRpc.buildRoute(routeId, {
+          seeds: expandedSeeds,
+          graphSeeds: this.#graphSeeds,
+          knownEntries,
+          generation,
+        });
       },
       onMerge: async (routeId, { delta, merged, generation }) => {
         const removedEntries = this.#rememberClientEntries(routeId, delta.discoveredEntries ?? delta.newEntries);
@@ -369,26 +369,24 @@ export class DevHmrController {
     for (const [entry, entryDeps] of Object.entries(depsByEntry)) {
       const resolvedEntry = path.resolve(entry);
       this.#recentClientEntries.add(resolvedEntry);
-      const entryRouteIds = this.#clientEntryRouteIds.get(resolvedEntry) ?? new Set<string>();
-      entryRouteIds.add(routeId);
-      this.#clientEntryRouteIds.set(resolvedEntry, entryRouteIds);
+      DevHmrController.#addTo(this.#clientEntryRouteIds, resolvedEntry, routeId);
       for (const dep of entryDeps) {
         const resolvedDep = path.resolve(dep);
         this.#recentClientFiles.add(resolvedDep);
-        const entries = this.#clientFileEntries.get(resolvedDep) ?? new Set<string>();
-        entries.add(resolvedEntry);
-        this.#clientFileEntries.set(resolvedDep, entries);
+        DevHmrController.#addTo(this.#clientFileEntries, resolvedDep, resolvedEntry);
       }
     }
     for (const dep of deps) {
       const resolved = path.resolve(dep);
       this.#recentClientFiles.add(resolved);
-      const routeIds = this.#clientFileRouteIds.get(resolved) ?? new Set<string>();
-      routeIds.add(routeId);
-      this.#clientFileRouteIds.set(resolved, routeIds);
+      DevHmrController.#addTo(this.#clientFileRouteIds, resolved, routeId);
     }
   }
 
+  static #addTo(map: Map<string, Set<string>>, key: string, value: string) {
+    map.set(key, (map.get(key) ?? new Set<string>()).add(value));
+  }
+
   #rememberClientEntries(routeId: string, entries: string[]): Set<string> {
     const nextEntries = new Set(entries.map((entry) => path.resolve(entry)));
     const previousEntries = this.#clientEntriesByRouteId.get(routeId) ?? new Set<string>();
@@ -405,9 +403,7 @@ export class DevHmrController {
     for (const entry of entries) {
       const resolvedEntry = path.resolve(entry);
       this.#recentClientEntries.add(resolvedEntry);
-      const routeIds = this.#clientEntryRouteIds.get(resolvedEntry) ?? new Set<string>();
-      routeIds.add(routeId);
-      this.#clientEntryRouteIds.set(resolvedEntry, routeIds);
+      DevHmrController.#addTo(this.#clientEntryRouteIds, resolvedEntry, routeId);
     }
     return orphanedEntries;
   }
@@ -448,9 +444,9 @@ export class DevHmrController {
   #shouldFullReloadForFiles(files: string[], routeIds: string[] | undefined): boolean {
     if (files.length === 0) return false;
     const runtimeRoots = [
-      `${path.sep}pkgs${path.sep}akanjs${path.sep}server${path.sep}src${path.sep}hmr${path.sep}`,
-      `${path.sep}pkgs${path.sep}akanjs${path.sep}server${path.sep}src${path.sep}rscClient.tsx`,
-      `${path.sep}pkgs${path.sep}akanjs${path.sep}server${path.sep}src${path.sep}ssrFromRscRenderer.tsx`,
+      `${path.sep}pkgs${path.sep}akanjs${path.sep}server${path.sep}hmr${path.sep}`,
+      `${path.sep}pkgs${path.sep}akanjs${path.sep}server${path.sep}rscClient.tsx`,
+      `${path.sep}pkgs${path.sep}akanjs${path.sep}server${path.sep}ssrFromRscRenderer.tsx`,
     ];
     if (files.some((file) => runtimeRoots.some((needle) => path.resolve(file).includes(needle)))) return true;
     if (files.some((file) => path.basename(file).endsWith(".signal.ts"))) return true;

package/server/hmr/wsHub.ts

@@ -1,6 +1,13 @@
 import { Logger } from "akanjs/common";
 import type { BuildPhase } from "../artifact";
 
+export type ChangeKind = "code" | "css" | "config" | "ignore";
+
+export interface ChangeBatch {
+  files: string[];
+  kinds: Set<Exclude<ChangeKind, "ignore">>;
+}
+
 export interface HmrWsData {
   kind: "akan-hmr";
   openedAt: number;
@@ -41,10 +48,6 @@ export class HmrWsHub {
   readonly #conns = new Set<Bun.ServerWebSocket<HmrWsData>>();
   #publish: ((topic: string, payload: string) => void) | null = null;
 
-  get size(): number {
-    return this.#conns.size;
-  }
-
   setPublisher(publish: (topic: string, payload: string) => void): void {
     this.#publish = publish;
   }
@@ -61,8 +64,7 @@ export class HmrWsHub {
   }
 
   broadcast(msg: HmrMessage): void {
-    const payload = JSON.stringify(msg);
-    this.#publish?.(HMR_WS_TOPIC, payload);
+    this.#publish?.(HMR_WS_TOPIC, JSON.stringify(msg));
   }
 
   handleMessage(message: string): void {
@@ -78,7 +80,7 @@ export class HmrWsHub {
   }
 }
 
-const isSyncNavigationEnabled = () =>
+export const isSyncNavigationEnabled = () =>
   process.env.AKAN_PUBLIC_SYNC_NAVIGATION === "true" ||
   process.env.AKAN_PUBLIC_SYNC_NAVIGATION === "1" ||
   process.env.SYNC_DOMAIN === "true" ||

package/server/imageOptimizer.ts

@@ -61,6 +61,7 @@ export class ImageOptimizer {
   static readonly #avif = "image/avif";
   static readonly #heic = "image/heic";
   static readonly #bypassTypes = new Set(["image/x-icon", "image/x-icns", "image/bmp", "image/jxl", "image/heic"]);
+  static readonly #encodableTypes = new Set(["image/jpeg", "image/png", "image/webp", "image/avif"]);
 
   #publicDir: string;
   #cacheDir: string;
@@ -84,20 +85,10 @@ export class ImageOptimizer {
     this.#semaphore = new Semaphore(ImageOptimizer.#resolveConcurrency(this.#config.maxConcurrency));
   }
 
-  /**
-   * Bun.Image encodes on the worker pool that fs, hashing and every other off-thread call also queue on, and the
-   * pool is sized by the CPU count Bun sees — 1 under a container `cpu` limit. Holding image work to half the
-   * slots leaves a stat or a bcrypt waiting behind a couple of encodes instead of behind the whole flood.
-   */
   static #resolveConcurrency(configured: number): number {
     return configured > 0 ? configured : Math.max(1, Math.floor(navigator.hardwareConcurrency / 2));
   }
 
-  /**
-   * AVIF, HEIC and TIFF ride the OS codec, which only the `system` backend has — macOS and Windows.
-   * A Linux container runs the `bun` backend, where both encode and decode raise
-   * `ERR_IMAGE_FORMAT_UNSUPPORTED`, so those types are decided up front rather than thrown at.
-   */
   static #isCodecAvailable(contentType: string): boolean {
     if (contentType !== ImageOptimizer.#avif && contentType !== ImageOptimizer.#heic && contentType !== "image/tiff")
       return true;
@@ -117,10 +108,6 @@ export class ImageOptimizer {
     }
   }
 
-  /**
-   * A cold `srcSet` puts the same width in flight several times over, and the cache file only exists once
-   * the first of them has finished, so identical requests join one run instead of each fetching and encoding.
-   */
   async #loadOptimizedImage(parsed: ParsedImageRequest): Promise<OptimizedImage> {
     const key = `${parsed.href}|${parsed.width}|${parsed.quality}|${parsed.outputType}`;
     const joined = this.#inflight.get(key);
@@ -149,12 +136,6 @@ export class ImageOptimizer {
     return optimized;
   }
 
-  /**
-   * The bytes are keyed by the source's own etag/mtime, so finding them means reading the source first — free for
-   * a local file, a full re-download for a remote one. This pointer is keyed by the request alone and carries the
-   * TTL (upstream `max-age`, floored by `minimumCacheTTL`), so a warm remote image never touches the origin.
-   * Dev is left out: re-fetching every time is what makes an upstream edit show up immediately.
-   */
   async #readRemotePointer(parsed: ParsedImageRequest): Promise<OptimizedImage | null> {
     let pointer: RemoteCachePointer;
     try {
@@ -250,11 +231,12 @@ export class ImageOptimizer {
       return { error: `"q" parameter (quality) of ${quality} is not allowed` };
     }
 
+    const accept = req.headers.get("accept") ?? "";
     return {
       href,
       width,
       quality,
-      outputType: ImageOptimizer.#getPreferredOutputType(req.headers.get("accept") ?? "", this.#config.formats),
+      outputType: this.#config.formats.find((format) => accept.includes(format)) ?? "",
       isRemote,
     };
   }
@@ -329,6 +311,7 @@ export class ImageOptimizer {
       shouldBypass || !params.outputType || inputType === ImageOptimizer.#webp || inputType === ImageOptimizer.#avif
         ? inputType
         : params.outputType;
+    const shouldEncode = !shouldBypass && ImageOptimizer.#encodableTypes.has(outputType);
     const cachePath = this.#getCachePath({
       href: params.href,
       width: params.width,
@@ -351,7 +334,7 @@ export class ImageOptimizer {
     let buffer = source.buffer;
     let contentType = inputType;
     let cacheable = true;
-    if (!shouldBypass) {
+    if (shouldEncode) {
       try {
         buffer = await this.#semaphore.run(() =>
           ImageOptimizer.#optimize(source.buffer, {
@@ -415,10 +398,6 @@ export class ImageOptimizer {
     return await image.jpeg({ quality: options.quality }).toBuffer();
   }
 
-  static #getPreferredOutputType(accept: string, formats: AkanImageFormat[]): AkanImageFormat | "" {
-    return formats.find((format) => accept.includes(format)) ?? "";
-  }
-
   static #hasRemoteMatch(patterns: AkanImagePattern[], url: URL): boolean {
     return patterns.some((pattern) => {
       if (pattern.protocol && `${pattern.protocol}:` !== url.protocol) return false;

package/server/index.ts

@@ -6,7 +6,7 @@ export * from "./artifact";
 export * from "./console";
 export * from "./decorators";
 export * from "./devtools";
-export type { ChangeBatch, ChangeKind } from "./hmr/changeBatch";
+export type { ChangeBatch, ChangeKind } from "./hmr/wsHub";
 export * from "./oauth";
 export * from "./processMetricsCollector";
 export * from "./proxy";

package/server/lifecycle/portInUse.ts

@@ -1,7 +1,4 @@
-/**
- * Detects "address already in use" listen failures across the shapes Bun throws them in
- * (`code: "EADDRINUSE"` on newer versions, message-only on older ones).
- */
+/** Bun reports EADDRINUSE as `code` on newer versions and only in the message on older ones; both count. */
 export const isPortInUseError = (error: unknown): boolean => {
   if (!error || typeof error !== "object") return false;
   const candidate = error as { code?: unknown; message?: unknown };

package/server/lifecycle/runtimeDir.ts

@@ -1,9 +1,5 @@
 import path from "node:path";
 
-/**
- * Where a replica keeps its child sockets and rotating logs. Both the gateway and a solo server resolve it,
- * and they must land on the same directory: switching between the two modes must not move the log file.
- */
 export const resolveRuntimeDir = (runtimeDir?: string): string =>
   path.resolve(
     runtimeDir ??