akanjs 0.0.1 → 2.0.0-beta.0

package/server/artifact/routeClientCache.ts

@@ -0,0 +1,224 @@
+import { Logger } from "akanjs/common";
+import type { SsrManifest } from "../ssrTypes";
+import type { BuildRouteClientResult, ClientManifest } from "./manifestTypes";
+import type { RoutesManifest } from "./routesManifestStore";
+
+/**
+ * Snapshot of every per-route build's accumulated output for one HMR
+ * generation. Callers should take a `snapshot()` before rendering so an
+ * invalidate cannot mutate the manifest while a request is consuming it.
+ */
+export interface MergedManifest {
+  generation: number;
+  clientManifest: ClientManifest;
+  ssrManifest: SsrManifest;
+  /** Absolute entry-file paths seen across every build so far. */
+  knownEntries: Set<string>;
+}
+
+type RouteBuildFn = (
+  routeId: string,
+  info: { seeds: string[]; knownEntries: Set<string>; generation: number },
+) => Promise<BuildRouteClientResult>;
+type OnMergeFn = (
+  routeId: string,
+  info: { delta: BuildRouteClientResult; merged: MergedManifest; generation: number },
+) => void | Promise<void>;
+
+interface RouteClientCacheOptions {
+  buildRoute: RouteBuildFn;
+  onMerge?: OnMergeFn;
+}
+
+type PendingBuild = { generation: number; promise: Promise<BuildRouteClientResult> };
+export interface InvalidateClientEntriesOptions {
+  routePredicate: (routeId: string) => boolean;
+  staleEntries: Iterable<string>;
+}
+
+export class RouteClientCache {
+  readonly #logger = new Logger("RouteClientCache");
+  readonly #built = new Map<string, BuildRouteClientResult>();
+  readonly #building = new Map<string, PendingBuild>();
+  merged: MergedManifest = {
+    generation: 0,
+    clientManifest: {},
+    ssrManifest: { moduleLoading: null, moduleMap: {} },
+    knownEntries: new Set<string>(),
+  };
+  readonly #buildRoute: RouteBuildFn;
+  readonly #onMerge?: OnMergeFn;
+
+  constructor({ buildRoute, onMerge }: RouteClientCacheOptions) {
+    this.#buildRoute = buildRoute;
+    this.#onMerge = onMerge;
+  }
+
+  #getEmptyDelta(): BuildRouteClientResult {
+    return {
+      manifestDelta: {},
+      ssrManifestDelta: { moduleLoading: null, moduleMap: {} },
+      newEntries: [],
+      clientDeps: [],
+    };
+  }
+  #getEmptyMerged(generation: number): MergedManifest {
+    return {
+      generation,
+      clientManifest: {},
+      ssrManifest: { moduleLoading: null, moduleMap: {} },
+      knownEntries: new Set<string>(),
+    };
+  }
+  seed(manifest: RoutesManifest): void {
+    Object.assign(this.merged.clientManifest, manifest.clientManifest);
+    Object.assign(this.merged.ssrManifest.moduleMap, manifest.ssrManifest.moduleMap);
+    for (const abs of manifest.knownEntries) this.merged.knownEntries.add(abs);
+    for (const routeId of manifest.routeIds) this.#built.set(routeId, this.#getEmptyDelta());
+  }
+
+  async ensure(routeId: string, seeds: string[]): Promise<MergedManifest> {
+    if (this.#built.has(routeId)) return this.merged;
+    const existing = this.#building.get(routeId);
+    if (existing && existing.generation === this.merged.generation) {
+      await existing.promise;
+      return this.merged;
+    }
+    const generation = this.merged.generation;
+    const promise = this.#runBuild(routeId, seeds, generation);
+    this.#building.set(routeId, { generation, promise });
+    try {
+      await promise;
+    } finally {
+      const current = this.#building.get(routeId);
+      if (current?.promise === promise) this.#building.delete(routeId);
+    }
+    return this.merged;
+  }
+
+  snapshot(): MergedManifest {
+    return {
+      generation: this.merged.generation,
+      clientManifest: { ...this.merged.clientManifest },
+      ssrManifest: {
+        moduleLoading: this.merged.ssrManifest.moduleLoading,
+        moduleMap: Object.fromEntries(
+          Object.entries(this.merged.ssrManifest.moduleMap).map(([url, byName]) => [url, { ...byName }]),
+        ),
+      },
+      knownEntries: new Set(this.merged.knownEntries),
+    };
+  }
+
+  async #runBuild(routeId: string, seeds: string[], generation: number): Promise<BuildRouteClientResult> {
+    const started = Date.now();
+    const knownEntries = new Set(this.merged.knownEntries);
+    this.#logger.verbose(`[route-cache] build start routeId=${routeId} generation=${generation} seeds=${seeds.length}`);
+    const delta = await this.#buildRoute(routeId, { seeds, knownEntries, generation });
+    if (this.merged.generation !== generation) {
+      this.#logger.verbose(
+        `[route-cache] stale build ignored routeId=${routeId} generation=${generation} current=${this.merged.generation}`,
+      );
+      return delta;
+    }
+    for (const [key, row] of Object.entries(delta.manifestDelta)) this.merged.clientManifest[key] = row;
+    for (const [url, byName] of Object.entries(delta.ssrManifestDelta.moduleMap))
+      this.merged.ssrManifest.moduleMap[url] = byName;
+    for (const entry of delta.newEntries) this.merged.knownEntries.add(entry);
+    this.#built.set(routeId, delta);
+    this.#logger.verbose(
+      `[route-cache] build done routeId=${routeId} generation=${generation} entries=+${delta.newEntries.length} deps=${delta.clientDeps.length} in ${Date.now() - started}ms`,
+    );
+    await this.#onMerge?.(routeId, { delta, merged: this.snapshot(), generation });
+    return delta;
+  }
+
+  invalidate(predicate: (routeId: string) => boolean): string[] {
+    const dropped: string[] = [];
+    for (const id of [...this.#built.keys()]) {
+      if (predicate(id)) {
+        this.#built.delete(id);
+        dropped.push(id);
+      }
+    }
+    if (dropped.length > 0) {
+      this.#rebuildKnownEntriesPreservingManifest(this.merged.generation + 1);
+      this.#building.clear();
+      this.#logger.verbose(`[route-cache] invalidated ${dropped.length} routes: ${dropped.join(", ")}`);
+    }
+    return dropped;
+  }
+
+  invalidateClientEntries({ routePredicate, staleEntries }: InvalidateClientEntriesOptions): string[] {
+    const normalizedStaleEntries = new Set([...staleEntries].map((entry) => RouteClientCache.#normalizePath(entry)));
+    const dropped: string[] = [];
+    for (const id of [...this.#built.keys()]) {
+      if (routePredicate(id)) {
+        this.#built.delete(id);
+        dropped.push(id);
+      }
+    }
+    if (dropped.length === 0 && normalizedStaleEntries.size === 0) return dropped;
+
+    this.#rebuildKnownEntriesPreservingManifest(this.merged.generation + 1, normalizedStaleEntries);
+    this.#building.clear();
+    this.#logger.verbose(
+      `[route-cache] client invalidated routes=${dropped.join(",") || "(none)"} entries=${normalizedStaleEntries.size}`,
+    );
+    return dropped;
+  }
+
+  clear(): string[] {
+    const dropped: string[] = [];
+    for (const id of [...this.#built.keys()]) {
+      this.#built.delete(id);
+      dropped.push(id);
+    }
+    const nextGeneration = this.merged.generation + 1;
+    this.merged = this.#getEmptyMerged(nextGeneration);
+    this.#building.clear();
+    this.#logger.verbose(`[route-cache] cleared generation=${nextGeneration} dropped=${dropped.length}`);
+    return dropped;
+  }
+
+  #rebuildKnownEntriesPreservingManifest(generation: number, staleEntries: Set<string> = new Set()): void {
+    const staleUrls = new Set<string>();
+    for (const [key, row] of Object.entries(this.merged.clientManifest)) {
+      if (!RouteClientCache.#manifestKeyMatchesEntries(key, staleEntries)) continue;
+      staleUrls.add(row.id);
+      for (const chunk of row.chunks) staleUrls.add(chunk);
+    }
+
+    const next: MergedManifest = {
+      generation,
+      clientManifest: Object.fromEntries(
+        Object.entries(this.merged.clientManifest).filter(
+          ([key, row]) => !RouteClientCache.#manifestKeyMatchesEntries(key, staleEntries) && !staleUrls.has(row.id),
+        ),
+      ),
+      ssrManifest: {
+        moduleLoading: this.merged.ssrManifest.moduleLoading,
+        moduleMap: Object.fromEntries(
+          Object.entries(this.merged.ssrManifest.moduleMap)
+            .filter(([url]) => !staleUrls.has(url))
+            .map(([url, byName]) => [url, { ...byName }]),
+        ),
+      },
+      knownEntries: new Set(
+        [...this.merged.knownEntries].filter((entry) => !staleEntries.has(RouteClientCache.#normalizePath(entry))),
+      ),
+    };
+    this.merged = next;
+  }
+
+  static #normalizePath(filePath: string): string {
+    return filePath.split("\\").join("/");
+  }
+
+  static #manifestKeyMatchesEntries(key: string, entries: Set<string>): boolean {
+    if (entries.size === 0) return false;
+    const hashIdx = key.lastIndexOf("#");
+    const entryKey = hashIdx >= 0 ? key.slice(0, hashIdx) : key;
+    return entries.has(RouteClientCache.#normalizePath(entryKey));
+  }
+}

package/server/artifact/routeSeedIndexStore.ts

@@ -0,0 +1,89 @@
+import path from "node:path";
+import { matchRoutePattern } from "akanjs/common";
+
+/**
+ * Runtime counterpart to `akanjs/devkit`'s `routeSeedIndex.ts`. The index
+ * itself is computed at build time by the CLI (which walks the `pages`
+ * registry and parses loader sources) and serialized to
+ * `route-seed-index.json`. The server only loads that JSON at boot and matches
+ * incoming pathnames against its route seed entries.
+ *
+ * Keeping this runtime-safe means `akanjs/server` never has to reach into
+ * `app/pages.ts` or Function.prototype.toString() — which is what made the
+ * previous in-process computation prone to drifting from the build pipeline.
+ */
+export interface RouteSeedEntry {
+  routeId: string;
+  pattern: string;
+  seeds: string[];
+}
+
+export interface RouteSeedIndex {
+  entries: RouteSeedEntry[];
+  globalLayoutFiles: string[];
+}
+
+export interface MatchedRoute {
+  entry: RouteSeedEntry;
+  params: Record<string, string>;
+}
+
+type SerializedRouteSeedEntry = Pick<RouteSeedEntry, "routeId"> & Partial<Pick<RouteSeedEntry, "pattern" | "seeds">>;
+
+interface SerializedRouteSeedIndex {
+  entries: SerializedRouteSeedEntry[];
+  globalLayoutFiles?: string[];
+}
+
+export const ROUTE_SEED_INDEX_JSON = "route-seed-index.json";
+
+export class RouteSeedIndexStore {
+  static async load(artifactDir: string): Promise<RouteSeedIndex> {
+    const absPath = path.join(path.resolve(artifactDir), ROUTE_SEED_INDEX_JSON);
+    const file = Bun.file(absPath);
+    if (!(await file.exists())) {
+      throw new Error(
+        `[route-seed-index] ${absPath} missing — rebuild with \`akan build\` or \`akan start-backend\` so the index is generated`,
+      );
+    }
+    const json = (await file.json()) as unknown;
+    if (!json || typeof json !== "object") {
+      throw new Error(`[route-seed-index] ${absPath} is not a valid JSON object`);
+    }
+    return RouteSeedIndexStore.normalize(json as SerializedRouteSeedIndex, path.resolve(artifactDir));
+  }
+
+  static normalize(index: SerializedRouteSeedIndex, artifactDir: string): RouteSeedIndex {
+    const normalizedArtifactDir = path.resolve(artifactDir);
+    return {
+      entries: index.entries.map((entry) => ({
+        ...entry,
+        pattern: entry.pattern ?? entry.routeId,
+        seeds: (entry.seeds ?? []).map((seed) =>
+          RouteSeedIndexStore.#normalizeArtifactPath(seed, normalizedArtifactDir),
+        ),
+      })),
+      globalLayoutFiles: (index.globalLayoutFiles ?? []).map((file) =>
+        RouteSeedIndexStore.#normalizeArtifactPath(file, normalizedArtifactDir),
+      ),
+    };
+  }
+
+  /**
+   * Match `pathname` against every registered route pattern using the same
+   * `:param` semantics as route tree matching. Returns the first entry that
+   * matches, along with the extracted parameters.
+   */
+  static match(pathname: string, entries: RouteSeedEntry[]): MatchedRoute | null {
+    for (const entry of entries) {
+      const params = matchRoutePattern(entry.pattern ?? entry.routeId, pathname);
+      if (params) return { entry, params };
+    }
+    return null;
+  }
+
+  static #normalizeArtifactPath(artifactPath: string, artifactDir: string): string {
+    if (path.isAbsolute(artifactPath)) return artifactPath;
+    return path.resolve(artifactDir, artifactPath);
+  }
+}

package/server/artifact/routesManifestStore.ts

@@ -0,0 +1,120 @@
+import fs from "node:fs";
+import path from "node:path";
+import type { SsrManifest, SsrManifestEntry } from "../ssrTypes";
+import type { ClientManifest } from "./manifestTypes";
+
+export interface RoutesManifest {
+  routeIds: string[];
+  clientManifest: ClientManifest;
+  ssrManifest: SsrManifest;
+  knownEntries: string[];
+}
+
+type SerializedRoutesManifest = Omit<RoutesManifest, "knownEntries"> & Partial<Pick<RoutesManifest, "knownEntries">>;
+
+export class RoutesManifestStore {
+  static serialize(manifest: RoutesManifest, artifactDir: string): RoutesManifest {
+    const normalizedArtifactDir = path.resolve(artifactDir);
+    return {
+      ...manifest,
+      clientManifest: RoutesManifestStore.#serializeClientManifest(manifest.clientManifest, normalizedArtifactDir),
+      ssrManifest: RoutesManifestStore.#serializeSsrManifest(manifest.ssrManifest, normalizedArtifactDir),
+      knownEntries: manifest.knownEntries.map((entry) =>
+        RoutesManifestStore.#serializeArtifactPath(entry, normalizedArtifactDir),
+      ),
+    };
+  }
+
+  static async read(artifactDir: string): Promise<RoutesManifest | null> {
+    const normalizedArtifactDir = path.resolve(artifactDir);
+    const manifestPath = path.join(normalizedArtifactDir, "routes-manifest.json");
+    const file = Bun.file(manifestPath);
+    if (!(await file.exists())) return null;
+    const json = (await file.json()) as unknown;
+    if (!json || typeof json !== "object") return null;
+    return RoutesManifestStore.normalize(json as SerializedRoutesManifest, normalizedArtifactDir);
+  }
+
+  static normalize(manifest: SerializedRoutesManifest, artifactDir: string): RoutesManifest {
+    return {
+      ...manifest,
+      clientManifest: RoutesManifestStore.#normalizeClientManifest(manifest.clientManifest),
+      ssrManifest: RoutesManifestStore.#normalizeSsrManifest(manifest.ssrManifest, artifactDir),
+      knownEntries: (manifest.knownEntries ?? []).map((entry) =>
+        RoutesManifestStore.#normalizeStoredPath(entry, artifactDir),
+      ),
+    };
+  }
+
+  static #serializeClientManifest(clientManifest: ClientManifest, artifactDir: string): ClientManifest {
+    const serialized: ClientManifest = {};
+    for (const [key, row] of Object.entries(clientManifest)) {
+      serialized[RoutesManifestStore.#serializeArtifactPath(key, artifactDir)] = row;
+    }
+    return serialized;
+  }
+
+  static #normalizeClientManifest(clientManifest: ClientManifest): ClientManifest {
+    const normalized: ClientManifest = {};
+    for (const [key, row] of Object.entries(clientManifest)) {
+      normalized[key] = row;
+    }
+    return normalized;
+  }
+
+  static #serializeSsrManifest(ssrManifest: SsrManifest, artifactDir: string): SsrManifest {
+    const moduleMap: SsrManifest["moduleMap"] = {};
+    for (const [entryUrl, byName] of Object.entries(ssrManifest.moduleMap)) {
+      const serializedByName: Record<string, SsrManifestEntry> = {};
+      for (const [name, entry] of Object.entries(byName)) {
+        serializedByName[name] = {
+          ...entry,
+          id: RoutesManifestStore.#serializeArtifactPath(entry.id, artifactDir),
+          chunks: entry.chunks.map((chunk) => RoutesManifestStore.#serializeArtifactPath(chunk, artifactDir)),
+        };
+      }
+      moduleMap[entryUrl] = serializedByName;
+    }
+    return { ...ssrManifest, moduleMap };
+  }
+
+  static #normalizeSsrManifest(ssrManifest: SsrManifest, artifactDir: string): SsrManifest {
+    const moduleMap: SsrManifest["moduleMap"] = {};
+    for (const [entryUrl, byName] of Object.entries(ssrManifest.moduleMap)) {
+      const normalizedByName: Record<string, SsrManifestEntry> = {};
+      for (const [name, entry] of Object.entries(byName)) {
+        normalizedByName[name] = {
+          ...entry,
+          id: RoutesManifestStore.#normalizeArtifactPath(entry.id, artifactDir),
+          chunks: entry.chunks.map((chunk) => RoutesManifestStore.#normalizeArtifactPath(chunk, artifactDir)),
+        };
+      }
+      moduleMap[entryUrl] = normalizedByName;
+    }
+    return { ...ssrManifest, moduleMap };
+  }
+
+  static #serializeArtifactPath(artifactPath: string, artifactDir: string): string {
+    if (!path.isAbsolute(artifactPath)) return artifactPath;
+    return path.relative(artifactDir, artifactPath).split(path.sep).join("/");
+  }
+
+  static #normalizeStoredPath(storedPath: string, artifactDir: string): string {
+    if (path.isAbsolute(storedPath)) return storedPath;
+    return path.resolve(artifactDir, storedPath);
+  }
+
+  static #normalizeArtifactPath(artifactPath: string, artifactDir: string): string {
+    if (!path.isAbsolute(artifactPath)) return path.resolve(artifactDir, artifactPath);
+    if (fs.existsSync(artifactPath)) return artifactPath;
+
+    const marker = `${path.sep}.akan${path.sep}artifact${path.sep}`;
+    const markerIndex = artifactPath.lastIndexOf(marker);
+    if (markerIndex >= 0) {
+      const rel = artifactPath.slice(markerIndex + marker.length);
+      return path.resolve(artifactDir, rel);
+    }
+
+    return path.resolve(artifactDir, "client", path.basename(artifactPath));
+  }
+}

package/server/decorators.ts

@@ -0,0 +1,95 @@
+
+
+type DecoratedInstance = {
+  logger?: { warn?: (message: string) => void; trace?: (message: string) => void };
+  __database?: { transaction?: <T>(fn: () => Promise<T>) => Promise<T> };
+  __databaseModel?: {
+    __database?: { transaction?: <T>(fn: () => Promise<T>) => Promise<T> };
+    __model?: { modelName: string };
+    __cache?: {
+      get: (key: string) => Promise<string | null>;
+      set: (key: string, value: string, option: unknown) => unknown;
+    };
+  };
+  database?: { transaction?: <T>(fn: () => Promise<T>) => Promise<T> };
+  connection?: { transaction?: <T>(fn: () => Promise<T>) => Promise<T> };
+  __model?: { modelName: string };
+  __cache?: {
+    get: (key: string) => Promise<string | null>;
+    set: (key: string, value: string, option: unknown) => unknown;
+  };
+};
+
+/** Method decorator that catches errors and logs a warning instead of throwing. */
+export const Try = () => {
+  return (_target: unknown, key: string, descriptor: PropertyDescriptor) => {
+    const originMethod = descriptor.value as (this: unknown, ...args: unknown[]) => unknown;
+    descriptor.value = async function (...args: unknown[]) {
+      try {
+        const result = await originMethod.apply(this, args);
+        return result;
+      } catch (e) {
+        (this as DecoratedInstance).logger?.warn?.(`${key} action error return: ${e}`);
+      }
+    };
+  };
+};
+
+/** Method decorator that runs the method inside the detected database transaction. */
+export const Transaction = (): MethodDecorator => {
+  return ((_target: unknown, key: string, descriptor: PropertyDescriptor) => {
+    const originMethod = descriptor.value as (this: unknown, ...args: unknown[]) => unknown;
+    descriptor.value = async function (...args: unknown[]) {
+      const instance = this as DecoratedInstance;
+      const database =
+        instance.__database ?? instance.__databaseModel?.__database ?? instance.database ?? instance.connection;
+      if (!database?.transaction) throw new Error(`No transactional database in function ${key}`);
+      return await database.transaction(async () => await originMethod.apply(this, args));
+    };
+    return descriptor;
+  }) as MethodDecorator;
+};
+
+/** Method decorator that caches method results for the given timeout in milliseconds. */
+export const Cache = (timeout = 1000, getCacheKey?: (...args: unknown[]) => string): MethodDecorator => {
+  return ((_target: unknown, key: string, descriptor: PropertyDescriptor) => {
+    const originMethod = descriptor.value as (this: unknown, ...args: unknown[]) => unknown;
+    const cacheMap = new Map<string, unknown>();
+    const timerMap = new Map<string, NodeJS.Timeout>();
+    descriptor.value = async function (...args: unknown[]) {
+      const instance = this as DecoratedInstance;
+      const classType = instance.__model ? "doc" : instance.__databaseModel ? "service" : "class";
+      const model = instance.__model ?? instance.__databaseModel?.__model;
+      const cache = instance.__cache ?? instance.__databaseModel?.__cache;
+      const cacheKeyValue = getCacheKey ? getCacheKey(...args) : JSON.stringify(args);
+      const cacheKey = `${classType}:${model?.modelName ?? "unknown"}:${key}:${cacheKeyValue}`;
+      const getCache = async (cacheKey: string) => {
+        if (classType === "class") return cacheMap.get(cacheKey);
+        const cached = (await cache?.get(cacheKey)) as string | null;
+        if (cached) return JSON.parse(cached);
+        return null;
+      };
+      const setCache = async (cacheKey: string, value: unknown) => {
+        if (classType === "class") {
+          const existingTimer = timerMap.get(cacheKey);
+          if (existingTimer) clearTimeout(existingTimer);
+          cacheMap.set(cacheKey, value);
+          const timer = setTimeout(() => {
+            cacheMap.delete(cacheKey);
+            timerMap.delete(cacheKey);
+          }, timeout);
+          timerMap.set(cacheKey, timer);
+        } else await cache?.set(cacheKey, JSON.stringify(value), { PX: timeout });
+      };
+      const cachedData = await getCache(cacheKey);
+      if (cachedData) {
+        instance.logger?.trace?.(`${model?.modelName ?? "unknown"} cache hit: ${cacheKey}`);
+        return cachedData;
+      }
+      const result = await originMethod.apply(this, args);
+      await setCache(cacheKey, result);
+      instance.logger?.trace?.(`${model?.modelName ?? "unknown"} cache set: ${cacheKey}`);
+      return result;
+    };
+  }) as MethodDecorator;
+};