akanjs 3.0.0-beta.22 → 3.0.0-beta.24

package/server/hmr/csrDevRuntime.ts

@@ -0,0 +1,474 @@
+interface RefreshRuntime {
+  injectIntoGlobalHook(host: object): void;
+  register(type: unknown, id: string): void;
+  performReactRefresh(): unknown;
+  createSignatureFunctionForTransform(): (type: unknown, ...rest: unknown[]) => unknown;
+  isLikelyComponentType(value: unknown): boolean;
+  getFamilyByType(value: unknown): unknown;
+}
+
+export type CsrAcceptCallback = (updated: string[]) => void;
+
+export interface CsrHotContext {
+  readonly data: Record<string, unknown> | undefined;
+  accept(deps?: string | string[], callback?: CsrAcceptCallback): void;
+  dispose(callback: (data: Record<string, unknown>) => void): void;
+  invalidate(): void;
+}
+
+export interface CsrModuleRecord {
+  readonly id: string;
+  exports: unknown;
+  readonly hot: CsrHotContext;
+}
+
+export type CsrModuleFactory = (
+  this: unknown,
+  require: (specifier: string) => unknown,
+  module: CsrModuleRecord,
+  exports: unknown,
+  $RefreshReg$: (type: unknown, localId: string) => void,
+  $RefreshSig$: () => (type: unknown, ...rest: unknown[]) => unknown,
+  __akanImport: (specifier: string) => Promise<unknown>,
+) => void;
+
+export interface CsrUpdateMessage {
+  generation: number;
+  url?: string | null;
+  reload?: boolean;
+  reason?: string;
+}
+
+export interface CsrDevRuntimeApi {
+  readonly generation: number;
+  define(id: string, factory: CsrModuleFactory): void;
+  defineHelpers(hash: string, factory: () => Record<string, unknown>): void;
+  helpers(hash: string): Record<string, unknown>;
+  start(options: { generation: number; refresh: string }): void;
+  update(generation: number, factories: Record<string, CsrModuleFactory>): void;
+  accept(ownerId: string, deps: string[], callback: CsrAcceptCallback): void;
+  hot(message: CsrUpdateMessage): void;
+  toESM(mod: unknown, isNodeMode?: number): unknown;
+  reExport(target: object, mod: unknown, secondTarget?: object): object | undefined;
+  inspect(): { generation: number; executed: string[]; modules: number };
+}
+
+interface CsrScriptElement {
+  src: string;
+  dataset: Record<string, string | undefined>;
+  onload: (() => void) | null;
+  onerror: (() => void) | null;
+  remove(): void;
+}
+
+export interface CsrDevRuntimeHost {
+  __akan?: CsrDevRuntimeApi;
+  __AKAN_CSR_LAST_UPDATE__?: { generation: number; executed: string[] };
+  document: {
+    currentScript: unknown;
+    head: { appendChild(node: unknown): unknown };
+    createElement(tagName: "script"): CsrScriptElement;
+  };
+  location: { reload(): void };
+  console: { warn(...args: unknown[]): void };
+  setTimeout(callback: () => void, ms: number): unknown;
+  clearTimeout(handle: unknown): void;
+}
+
+export const installCsrDevRuntime = (host: CsrDevRuntimeHost): void => {
+  if (host.__akan) return;
+  const modulePrefix = "akan-module:";
+  const maxInvalidateRounds = 8;
+
+  class HotContext implements CsrHotContext {
+    selfAccepted = false;
+    invalidated = false;
+    readonly disposers: ((data: Record<string, unknown>) => void)[] = [];
+    readonly acceptedDeps = new Map<string, CsrAcceptCallback>();
+    constructor(readonly data: Record<string, unknown> | undefined) {}
+    accept(deps?: string | string[], callback: CsrAcceptCallback = () => undefined) {
+      if (deps === undefined) {
+        this.selfAccepted = true;
+        return;
+      }
+      for (const dep of Array.isArray(deps) ? deps : [deps])
+        this.acceptedDeps.set(dep.startsWith(modulePrefix) ? dep.slice(modulePrefix.length) : dep, callback);
+    }
+    dispose(callback: (data: Record<string, unknown>) => void) {
+      this.disposers.push(callback);
+    }
+    invalidate() {
+      this.invalidated = true;
+    }
+  }
+
+  class ModuleRecord implements CsrModuleRecord {
+    exports: unknown = {};
+    readonly parents = new Set<string>();
+    readonly children = new Set<string>();
+    readonly hot: HotContext;
+    constructor(
+      readonly id: string,
+      data: Record<string, unknown> | undefined,
+    ) {
+      this.hot = new HotContext(data);
+    }
+  }
+
+  class CsrDevRegistry implements CsrDevRuntimeApi {
+    #factories = new Map<string, CsrModuleFactory>();
+    #helperFactories = new Map<string, () => Record<string, unknown>>();
+    #helperValues = new Map<string, Record<string, unknown>>();
+    #cache = new Map<string, ModuleRecord>();
+    #hotData = new Map<string, Record<string, unknown>>();
+    #refresh: RefreshRuntime | null = null;
+    #refreshTimer: unknown = null;
+    #generation = 0;
+    #executed: string[] = [];
+    #patchQueue: Promise<void> = Promise.resolve();
+    #settling: Promise<void> = Promise.resolve();
+    #reloading = false;
+
+    get generation() {
+      return this.#generation;
+    }
+
+    define(id: string, factory: CsrModuleFactory) {
+      this.#factories.set(id, factory);
+    }
+
+    defineHelpers(hash: string, factory: () => Record<string, unknown>) {
+      if (!this.#helperFactories.has(hash)) this.#helperFactories.set(hash, factory);
+    }
+
+    helpers(hash: string) {
+      const cached = this.#helperValues.get(hash);
+      if (cached) return cached;
+      const factory = this.#helperFactories.get(hash);
+      if (!factory) throw new Error(`[akan-csr] no helpers registered as ${hash}`);
+      const value = factory();
+      this.#helperValues.set(hash, value);
+      return value;
+    }
+
+    start({ generation, refresh }: { generation: number; refresh: string }) {
+      const script = host.document.currentScript as CsrScriptElement | null;
+      const entry = script?.dataset.akanCsrEntry;
+      if (!entry) throw new Error("[akan-csr] the app script carries no data-akan-csr-entry");
+      this.#generation = generation;
+      this.#refresh = this.#load(refresh).exports as RefreshRuntime;
+      
+      this.#refresh.injectIntoGlobalHook(host);
+      this.#load(entry);
+    }
+
+    update(generation: number, factories: Record<string, CsrModuleFactory>) {
+      if (generation <= this.#generation) return;
+      if (generation !== this.#generation + 1) {
+        this.#reload(`missed generation ${this.#generation + 1} before ${generation}`);
+        return;
+      }
+      const ids = Object.keys(factories);
+      for (const id of ids) this.#factories.set(id, factories[id] as CsrModuleFactory);
+      this.#generation = generation;
+      this.#executed = [];
+      const threw = (error: unknown) =>
+        this.#reload(
+          `generation ${generation} threw while applying: ${error instanceof Error ? error.message : error}`,
+        );
+      let pending: Promise<void>[] = [];
+      try {
+        pending = this.#apply(ids.filter((id) => this.#cache.has(id)));
+      } catch (error) {
+        threw(error);
+      }
+      host.__AKAN_CSR_LAST_UPDATE__ = { generation, executed: this.#executed.slice() };
+      if (pending.length > 0) this.#settling = Promise.all(pending).then(() => this.#scheduleRefresh(), threw);
+    }
+
+    accept(ownerId: string, deps: string[], callback: CsrAcceptCallback) {
+      const owner = this.#cache.get(ownerId);
+      if (!owner) throw new Error(`[akan-csr] ${ownerId} accepts updates before it is loaded`);
+      owner.hot.accept(deps, callback);
+    }
+
+    hot(message: CsrUpdateMessage) {
+      if (message.reload) {
+        this.#reload(message.reason ?? "the dev server asked for a reload");
+        return;
+      }
+      if (message.generation <= this.#generation) return;
+      const url = message.url;
+      if (!url) {
+        this.#reload(`generation ${message.generation} arrived without a patch`);
+        return;
+      }
+      
+      this.#patchQueue = this.#patchQueue.then(() => this.#loadPatch(url)).then(() => this.#settling);
+    }
+
+    inspect() {
+      return { generation: this.#generation, executed: this.#executed.slice(), modules: this.#cache.size };
+    }
+
+    readonly toESM = (mod: unknown, _isNodeMode?: number): unknown => {
+
+      if (mod != null && (mod as { __esModule?: boolean }).__esModule) return mod;
+      const namespace: Record<string, unknown> = {};
+      Object.defineProperty(namespace, "default", { value: mod, enumerable: true });
+      if (mod == null || (typeof mod !== "object" && typeof mod !== "function")) return namespace;
+      for (const key of Object.getOwnPropertyNames(mod)) {
+        if (key === "default" || key === "__esModule") continue;
+        Object.defineProperty(namespace, key, { get: () => (mod as Record<string, unknown>)[key], enumerable: true });
+      }
+      return namespace;
+    };
+
+    readonly reExport = (target: object, mod: unknown, secondTarget?: object): object | undefined => {
+      const keys =
+        mod != null && (typeof mod === "object" || typeof mod === "function") ? Object.getOwnPropertyNames(mod) : [];
+      for (const to of secondTarget ? [target, secondTarget] : [target]) {
+        for (const key of keys) {
+          
+          if (key === "default" || key === "__esModule" || Object.prototype.hasOwnProperty.call(to, key)) continue;
+          Object.defineProperty(to, key, { get: () => (mod as Record<string, unknown>)[key], enumerable: true });
+        }
+      }
+      return secondTarget;
+    };
+
+    #loadPatch(url: string) {
+      return new Promise<void>((resolve) => {
+        const script = host.document.createElement("script");
+        script.src = url;
+        script.onload = () => {
+          script.remove();
+          resolve();
+        };
+        script.onerror = () => {
+          this.#reload(`patch ${url} failed to load`);
+          resolve();
+        };
+        host.document.head.appendChild(script);
+      });
+    }
+
+    #requireFrom(parentId: string) {
+      return (specifier: string) => {
+        const record = this.#load(
+          specifier.startsWith(modulePrefix) ? specifier.slice(modulePrefix.length) : specifier,
+        );
+        this.#link(parentId, record);
+        return record.exports;
+      };
+    }
+
+    #link(parentId: string, record: ModuleRecord) {
+      record.parents.add(parentId);
+      this.#cache.get(parentId)?.children.add(record.id);
+    }
+
+    #load(id: string): ModuleRecord {
+      const cached = this.#cache.get(id);
+      if (cached) return cached;
+      const factory = this.#factories.get(id);
+      if (!factory) throw new Error(`[akan-csr] no module registered as ${id}`);
+      const record = new ModuleRecord(id, this.#hotData.get(id));
+      this.#cache.set(id, record);
+      const requireFromHere = this.#requireFrom(id);
+      const register = (type: unknown, localId: string) => this.#refresh?.register(type, `${id} ${localId}`);
+      const signature = () => this.#refresh?.createSignatureFunctionForTransform() ?? ((type: unknown) => type);
+      const importFromHere = (specifier: string) => new Promise((resolve) => resolve(requireFromHere(specifier)));
+      try {
+        factory.call(record.exports, requireFromHere, record, record.exports, register, signature, importFromHere);
+      } catch (error) {
+        this.#cache.delete(id);
+        throw error;
+      }
+      this.#executed.push(id);
+      if (!id.startsWith("stub:") && !id.includes("node_modules/")) this.#afterExecute(record);
+      return record;
+    }
+
+    #isComponent(value: unknown) {
+      const refresh = this.#refresh;
+      if (!refresh) return false;
+      try {
+        return refresh.getFamilyByType(value) !== undefined || refresh.isLikelyComponentType(value);
+      } catch {
+        return false;
+      }
+    }
+
+    #exportEntries(exports: unknown): [string, unknown][] {
+      if (exports == null || (typeof exports !== "object" && typeof exports !== "function")) return [];
+      return Object.keys(exports)
+        .filter((key) => key !== "__esModule")
+        .map((key) => {
+          try {
+            return [key, (exports as Record<string, unknown>)[key]];
+          } catch {
+            return [key, undefined];
+          }
+        });
+    }
+
+    #afterExecute(record: ModuleRecord) {
+      const refresh = this.#refresh;
+      if (!refresh) return;
+      const previous = record.hot.data?.refresh as { boundary: boolean; signature: unknown[] } | undefined;
+      const entries = this.#exportEntries(record.exports);
+      for (const [key, value] of entries)
+        if (this.#isComponent(value)) refresh.register(value, `${record.id} %exports% ${key}`);
+      const boundary =
+        this.#isComponent(record.exports) ||
+        (entries.length > 0 && entries.every(([, value]) => this.#isComponent(value)));
+      if (!boundary) {
+        if (previous?.boundary) record.hot.invalidate();
+        return;
+      }
+      record.hot.accept();
+      const signature = [
+        this.#safeFamily(record.exports),
+        ...entries.flatMap(([key, value]) => [key, this.#safeFamily(value)]),
+      ];
+      record.hot.dispose((data) => {
+        data.refresh = { boundary: true, signature };
+      });
+      if (!previous) return;
+      const changed =
+        !previous.boundary ||
+        previous.signature.length !== signature.length ||
+        previous.signature.some((part, index) => part !== signature[index]);
+      if (changed) record.hot.invalidate();
+      else this.#scheduleRefresh();
+    }
+
+    #safeFamily(value: unknown) {
+      try {
+        return this.#refresh?.getFamilyByType(value);
+      } catch {
+        return undefined;
+      }
+    }
+
+    #scheduleRefresh() {
+      if (this.#refreshTimer !== null) host.clearTimeout(this.#refreshTimer);
+      this.#refreshTimer = host.setTimeout(() => {
+        this.#refreshTimer = null;
+        this.#refresh?.performReactRefresh();
+      }, 16);
+    }
+
+    #apply(changed: string[]): Promise<void>[] {
+      const settling: Promise<void>[] = [];
+      let pending = changed;
+      for (let round = 0; pending.length > 0; round += 1) {
+        if (round === maxInvalidateRounds) {
+          this.#reload("updates kept invalidating their boundaries");
+          return [];
+        }
+        const plan = this.#collectOutdated(pending);
+        if ("reload" in plan) {
+          this.#reload(plan.reload);
+          return [];
+        }
+        const parentsOf = new Map(
+          [...plan.boundaries].map((id) => [id, [...(this.#cache.get(id)?.parents ?? [])]] as const),
+        );
+        this.#dispose(plan.outdated);
+        const invalidated: string[] = [];
+        for (const id of plan.boundaries) {
+          const record = this.#load(id);
+          for (const parent of parentsOf.get(id) ?? []) this.#link(parent, record);
+          if (record.hot.invalidated) invalidated.push(id);
+        }
+        settling.push(...this.#runAcceptedDeps(plan.accepted));
+        pending = [];
+        for (const id of invalidated) {
+          const parents = [...(this.#cache.get(id)?.parents ?? [])];
+          if (parents.length === 0) {
+            this.#reload(`${id} changed its exports and nothing above it can take the update`);
+            return [];
+          }
+          pending.push(...parents);
+        }
+      }
+      return settling;
+    }
+
+    #runAcceptedDeps(accepted: Map<string, Set<string>>): Promise<void>[] {
+      const settling: Promise<void>[] = [];
+      for (const [parentId, deps] of accepted) {
+        const parent = this.#cache.get(parentId);
+        if (!parent) continue;
+        const updatedBy = new Map<CsrAcceptCallback, string[]>();
+        for (const dep of deps) {
+          this.#link(parentId, this.#load(dep));
+          const callback = parent.hot.acceptedDeps.get(dep);
+          if (callback) updatedBy.set(callback, [...(updatedBy.get(callback) ?? []), dep]);
+        }
+        for (const [callback, updated] of updatedBy) {
+          const result: unknown = callback(updated);
+          if (result instanceof Promise) settling.push(result);
+        }
+      }
+      if (accepted.size > 0) this.#scheduleRefresh();
+      return settling;
+    }
+
+    #collectOutdated(
+      start: string[],
+    ): { outdated: Set<string>; boundaries: Set<string>; accepted: Map<string, Set<string>> } | { reload: string } {
+      const outdated = new Set<string>();
+      const boundaries = new Set<string>();
+      const accepted = new Map<string, Set<string>>();
+      const queue = [...start];
+      while (queue.length > 0) {
+        const id = queue.shift() as string;
+        if (outdated.has(id)) continue;
+        const record = this.#cache.get(id);
+        if (!record) continue;
+        outdated.add(id);
+        if (record.hot.selfAccepted && !record.hot.invalidated) {
+          boundaries.add(id);
+          continue;
+        }
+        if (record.parents.size === 0) return { reload: `no component boundary above ${id}` };
+        for (const parentId of record.parents) {
+          if (!this.#cache.get(parentId)?.hot.acceptedDeps.has(id)) {
+            queue.push(parentId);
+            continue;
+          }
+          const deps = accepted.get(parentId) ?? new Set<string>();
+          accepted.set(parentId, deps.add(id));
+        }
+      }
+      for (const parentId of accepted.keys()) if (outdated.has(parentId)) accepted.delete(parentId);
+      return { outdated, boundaries, accepted };
+    }
+
+    #dispose(ids: Set<string>) {
+      for (const id of ids) {
+        const record = this.#cache.get(id);
+        if (!record) continue;
+        const data: Record<string, unknown> = {};
+        for (const dispose of record.hot.disposers) dispose(data);
+        this.#hotData.set(id, data);
+        this.#cache.delete(id);
+        for (const child of record.children) this.#cache.get(child)?.parents.delete(id);
+      }
+    }
+
+    #reload(reason: string) {
+      if (this.#reloading) return;
+      this.#reloading = true;
+      host.console.warn(`[akan-csr] full reload: ${reason}`);
+      host.location.reload();
+    }
+  }
+
+  host.__akan = new CsrDevRegistry();
+};
+
+export const CSR_DEV_RUNTIME_SCRIPT = `(${installCsrDevRuntime.toString()})(self);\n`;

package/server/hmr/csrDevShell.ts

@@ -0,0 +1,111 @@
+import path from "node:path";
+import { resolveStaticPath } from "../staticPath";
+import {
+  CSR_DEV_APP_FILE,
+  CSR_DEV_DIRNAME,
+  CSR_DEV_MANIFEST_FILE,
+  CSR_DEV_ROUTE_PREFIX,
+  type CsrDevLayout,
+  type CsrDevManifest,
+  csrDevModuleFile,
+} from "./csrDevManifest";
+import { CSR_DEV_RUNTIME_SCRIPT } from "./csrDevRuntime";
+import { CsrDevSourceMap, type RawSourceMap } from "./csrDevSourceMap";
+
+export interface CsrDevShellRenderOptions {
+  basePath: string;
+  lang: string;
+  title: string;
+  cssHref: string | null;
+}
+
+export class CsrDevShell {
+  static readonly #runtimeHash = Bun.hash(CSR_DEV_RUNTIME_SCRIPT).toString(36);
+  static readonly #servedFile = /^(app\.js|vendor-[\w-]+\.js|patch-\d+\.js|assets\/[\w.-]+)$/;
+  static readonly #sourceMapFile = /^(app\.js|patch-\d+\.js)\.map$/;
+  readonly #dir: string;
+
+  constructor(artifactDir: string) {
+    this.#dir = path.join(artifactDir, CSR_DEV_DIRNAME);
+  }
+
+  async readManifest(): Promise<CsrDevManifest | null> {
+    const file = Bun.file(path.join(this.#dir, CSR_DEV_MANIFEST_FILE));
+    if (!(await file.exists())) return null;
+    return (await file.json().catch(() => null)) as CsrDevManifest | null;
+  }
+
+  async render({ basePath, lang, title, cssHref }: CsrDevShellRenderOptions): Promise<string | null> {
+    const manifest = await this.readManifest();
+    const entry = manifest?.entries[basePath];
+    if (!manifest || !entry) return null;
+    const stylesheet = cssHref
+      ? `    <link rel="stylesheet" href="${CsrDevShell.#attr(cssHref)}" data-akan-css="active" />\n`
+      : "";
+    return `<!doctype html>
+<html lang="${CsrDevShell.#attr(lang)}">
+  <head>
+    <meta charset="utf-8" />
+    <title>${CsrDevShell.#attr(title)}</title>
+    <base href="/" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+${stylesheet}  </head>
+  <body>
+    <div id="root"></div>
+    <script src="${CSR_DEV_ROUTE_PREFIX}runtime.js?v=${CsrDevShell.#runtimeHash}"></script>
+    <script src="${CSR_DEV_ROUTE_PREFIX}${CsrDevShell.#attr(manifest.vendorFile)}"></script>
+    <script src="${CSR_DEV_ROUTE_PREFIX}${CSR_DEV_APP_FILE}?g=${manifest.generation}" data-akan-csr-entry="${CsrDevShell.#attr(entry)}"></script>
+  </body>
+</html>
+`;
+  }
+
+  async serve(req: Request): Promise<Response> {
+    const name = new URL(req.url).pathname.slice(CSR_DEV_ROUTE_PREFIX.length);
+    if (name === "runtime.js") return CsrDevShell.#js(CSR_DEV_RUNTIME_SCRIPT, "public, max-age=31536000, immutable");
+    if (CsrDevShell.#sourceMapFile.test(name)) return await this.#serveSourceMap(name);
+    if (!CsrDevShell.#servedFile.test(name)) return new Response("Not Found", { status: 404 });
+    const filePath = resolveStaticPath(this.#dir, name);
+    const file = filePath ? Bun.file(filePath) : null;
+    if (!file || !(await file.exists())) return new Response("Not Found", { status: 404 });
+    const cacheControl = name.startsWith("vendor-") ? "public, max-age=31536000, immutable" : "no-store";
+    if (name.startsWith("assets/"))
+      return new Response(file, { headers: CsrDevShell.#headers(file.type, cacheControl) });
+    return CsrDevShell.#js(file, cacheControl);
+  }
+
+  async #serveSourceMap(name: string): Promise<Response> {
+    const generatedFile = name.slice(0, -".map".length);
+    const layoutFile = Bun.file(path.join(this.#dir, `${generatedFile}.layout.json`));
+    if (!(await layoutFile.exists())) return new Response("Not Found", { status: 404 });
+    const layout = (await layoutFile.json()) as CsrDevLayout;
+    const sections = await Promise.all(
+      layout.modules.map(async ([id, line]) => {
+        const file = Bun.file(path.join(this.#dir, csrDevModuleFile(id, ".js.map")));
+        return (await file.exists()) ? { line, map: (await file.json()) as RawSourceMap } : null;
+      }),
+    );
+    const map = CsrDevSourceMap.merge(
+      generatedFile,
+      sections.filter((section) => section !== null),
+      layout.lineCount,
+    );
+    return new Response(JSON.stringify(map), { headers: CsrDevShell.#headers("application/json", "no-store") });
+  }
+
+  static #js(body: string | Blob, cacheControl: string): Response {
+    return new Response(body, { headers: CsrDevShell.#headers("application/javascript; charset=utf-8", cacheControl) });
+  }
+
+  static #headers(contentType: string, cacheControl: string): Headers {
+    return new Headers({
+      "Content-Type": contentType || "application/octet-stream",
+      "Cache-Control": cacheControl,
+      "X-Content-Type-Options": "nosniff",
+    });
+  }
+
+  static #attr(value: string): string {
+    return value.replaceAll("&", "&amp;").replaceAll('"', "&quot;").replaceAll("<", "&lt;");
+  }
+}