akanjs 3.0.0-alpha.0 → 3.0.0-alpha.2

package/server/resolver/CascadeRunner.ts

@@ -0,0 +1,201 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { LIBS_REMOVE_HOOK } from "akanjs/base";
+import { Logger } from "akanjs/common";
+import { type CascadeWithPath, type ConstantModel, ConstantRegistry } from "akanjs/constant";
+import { type DocumentSchema, documentQueryHelper } from "akanjs/document";
+import type { DatabaseService, ServiceCls } from "akanjs/service";
+
+/** A relation the removed document owns: the ids it holds name documents to remove. */
+interface RefEdge {
+  readonly key: string;
+  readonly refName: string;
+}
+
+/** A model that declared itself removable with this one: its rows name the removed document as their owner. */
+interface WithEdge {
+  readonly refName: string;
+  readonly key: string;
+  readonly typeKey: string | null;
+}
+
+interface CascadeModule {
+  readonly constant: ConstantModel;
+  readonly schema: DocumentSchema;
+  readonly srvRef: ServiceCls;
+}
+
+interface CascadePlan {
+  readonly refEdges: RefEdge[];
+  readonly withEdges: WithEdge[];
+}
+
+/** One cascade in flight. Shared down the chain so a cycle is caught wherever it closes. */
+interface CascadeContext {
+  readonly seen: Set<string>;
+  readonly depth: number;
+}
+
+/** How deep one removal may cascade before the chain is treated as runaway and abandoned. */
+const maxDepth = 16;
+/** Ids taken per query while draining children one document at a time. */
+const drainSize = 200;
+
+export class CascadeRunner {
+  readonly #modules = new Map<string, CascadeModule>();
+  readonly #plans = new Map<string, CascadePlan>();
+  readonly #bulk = new Set<string>();
+  readonly #context = new AsyncLocalStorage<CascadeContext>();
+  readonly #logger = new Logger("Cascade");
+  #getService: ((refName: string) => DatabaseService) | null = null;
+
+  register(constant: ConstantModel, schema: DocumentSchema, srvRef: ServiceCls) {
+    this.#modules.set(constant.refName, { constant, schema, srvRef });
+  }
+
+  /**
+   * Called once every service is live. A `_postRemove` and a `listenPost("remove")` registered during boot both
+   * count against bulk removal, so the strategy cannot be decided before the last service has initialized.
+   */
+  seal(getService: (refName: string) => DatabaseService) {
+    this.#getService = getService;
+    for (const [refName, mod] of this.#modules) {
+      this.#plans.set(refName, { refEdges: this.#collectRefEdges(refName, mod), withEdges: [] });
+    }
+    for (const [refName, mod] of this.#modules) this.#collectWithEdges(refName, mod);
+    for (const refName of this.#modules.keys()) {
+      if (this.#hasRemoveSideEffect(refName)) continue;
+      this.#bulk.add(refName);
+    }
+    this.#report();
+  }
+
+  async run(refName: string, doc: Record<string, unknown>) {
+    const plan = this.#plans.get(refName);
+    if (!plan?.refEdges.length && !plan?.withEdges.length) return;
+    const parent = this.#context.getStore();
+    const seen = parent?.seen ?? new Set<string>();
+    const depth = (parent?.depth ?? 0) + 1;
+    const id = typeof doc.id === "string" ? doc.id : null;
+    if (id) seen.add(`${refName}:${id}`);
+    if (depth > maxDepth) {
+      this.#logger.error(`Cascade from ${refName} exceeded depth ${maxDepth} and was abandoned`);
+      return;
+    }
+    await this.#context.run({ seen, depth }, async () => {
+      for (const edge of plan.refEdges) await this.#removeRef(edge, doc, seen);
+      if (id) for (const edge of plan.withEdges) await this.#removeWith(edge, refName, id, seen);
+    });
+  }
+
+  async #removeRef(edge: RefEdge, doc: Record<string, unknown>, seen: Set<string>) {
+    const value = doc[edge.key];
+    const ids = (Array.isArray(value) ? value : [value]).filter(
+      (item): item is string => typeof item === "string" && !seen.has(`${edge.refName}:${item}`),
+    );
+    if (!ids.length) return;
+    const service = this.#service(edge.refName);
+    if (this.#bulk.has(edge.refName)) {
+      await service.__removeMany({ id: documentQueryHelper.oneOf(ids) });
+      return;
+    }
+
+    for (const id of ids) await service.__remove(id);
+  }
+
+  async #removeWith(edge: WithEdge, ownerRef: string, ownerId: string, seen: Set<string>) {
+    const service = this.#service(edge.refName);
+    const query = edge.typeKey ? { [edge.key]: ownerId, [edge.typeKey]: ownerRef } : { [edge.key]: ownerId };
+    if (this.#bulk.has(edge.refName)) {
+      await service.__removeMany(query);
+      return;
+    }
+
+    for (;;) {
+      const ids = await service.__listIds(query, { limit: drainSize });
+      if (!ids.length) return;
+      let removed = 0;
+      for (const id of ids) {
+        if (seen.has(`${edge.refName}:${id}`)) continue;
+        await service.__remove(id);
+        removed += 1;
+      }
+      if (!removed) return;
+    }
+  }
+
+  #collectRefEdges(refName: string, mod: CascadeModule) {
+    return [...mod.constant.full.cascade.removeRef].map(([key, modelRef]) => {
+      const target = ConstantRegistry.getRefName(modelRef);
+
+      if (!this.#modules.has(target)) {
+        throw new Error(`Cascade field "${refName}.${key}" removes "${target}", which this app does not mount`);
+      }
+      return { key, refName: target };
+    });
+  }
+
+  #collectWithEdges(childRef: string, mod: CascadeModule) {
+    for (const [key, path] of mod.constant.full.cascade.removeWith) {
+      for (const owner of this.#resolveOwners(childRef, key, path)) {
+        this.#plans.get(owner)?.withEdges.push({ refName: childRef, key, typeKey: path.typeKey });
+      }
+    }
+  }
+
+  #resolveOwners(childRef: string, key: string, path: CascadeWithPath) {
+    if (path.typeValues.length) {
+
+      const mounted = path.typeValues.filter((owner) => this.#modules.has(owner));
+      for (const owner of path.typeValues) {
+        if (mounted.includes(owner)) continue;
+        this.#logger.warn(`Cascade field "${childRef}.${key}" names owner "${owner}", which this app does not mount`);
+      }
+      return mounted;
+    }
+    const owner = path.refName ?? ConstantRegistry.getRefName(path.modelRef as never);
+    if (!this.#modules.has(owner)) {
+      throw new Error(`Cascade field "${childRef}.${key}" is owned by "${owner}", which this app does not mount`);
+    }
+    return [owner];
+  }
+
+  /** Everything a bulk `removeMany` would skip. All of it absent means the two paths leave the same rows behind. */
+  #hasRemoveSideEffect(refName: string) {
+    const mod = this.#modules.get(refName);
+    if (!mod) return true;
+    if (mod.schema.preHooks.get("remove")?.length || mod.schema.postHooks.get("remove")?.length) return true;
+    if ((mod.srvRef as unknown as { [LIBS_REMOVE_HOOK]?: boolean })[LIBS_REMOVE_HOOK]) return true;
+    const proto = mod.srvRef.prototype as { _preRemove?: unknown; _postRemove?: unknown };
+    if (typeof proto._preRemove === "function" || typeof proto._postRemove === "function") return true;
+    const plan = this.#plans.get(refName);
+    return !!plan?.refEdges.length || !!plan?.withEdges.length;
+  }
+
+  /** Neither the strategy nor the edge list is visible from the source, and adding a `_postRemove` to a target
+   * silently flips it from one query back to one per document. A quiet cascade is the one nobody can explain. */
+  #report() {
+    const lines: string[] = [];
+    for (const [refName, plan] of this.#plans) {
+      for (const edge of plan.refEdges) {
+        lines.push(`${refName}.${edge.key} removeRef ${edge.refName} (${this.#strategy(edge.refName)})`);
+      }
+      for (const edge of plan.withEdges) {
+        const path = edge.typeKey ? `${edge.key}+${edge.typeKey}` : edge.key;
+        lines.push(`${refName} removeWith ${edge.refName}.${path} (${this.#strategy(edge.refName)})`);
+      }
+    }
+    if (!lines.length) return;
+    const bulk = lines.filter((line) => line.endsWith("(bulk)")).length;
+    this.#logger.info(`${lines.length} cascade edge(s), ${bulk} in one query`);
+    for (const line of lines) this.#logger.verbose(line);
+  }
+
+  #strategy(refName: string) {
+    return this.#bulk.has(refName) ? "bulk" : "per document";
+  }
+
+  #service(refName: string) {
+    if (!this.#getService) throw new Error(`Cascade ran before the plan was sealed: ${refName}`);
+    return this.#getService(refName);
+  }
+}

package/server/resolver/database.resolver.ts

@@ -47,7 +47,11 @@ const timedQuery = async <T>(fn: () => Promise<T>): Promise<T> => {
 };
 
 export class DatabaseResolver {
-  static resolveDatabase(constant: ConstantModel, database: DatabaseModel): AdaptorCls<DatabaseInstance> {
+  /** Returns the schema alongside the adaptor: the cascade planner reads its `remove` hooks to pick a strategy. */
+  static resolveDatabase(
+    constant: ConstantModel,
+    database: DatabaseModel,
+  ): { adaptor: AdaptorCls<DatabaseInstance>; schema: DocumentSchema } {
     const [modelName, className]: [string, string] = [database.refName, capitalize(database.refName)];
 
     const resolveSort = (sortKey?: string | null) =>
@@ -85,6 +89,16 @@ export class DatabaseResolver {
       schema.index(fields);
     }
 
+    for (const path of constant.full.cascade.removeWith.values()) {
+      const fields = path.typeKey
+        ? { removedAt: 1, [path.typeKey]: 1, [path.key]: 1 }
+        : { removedAt: 1, [path.key]: 1 };
+      const key = Object.keys(fields).join(",");
+      if (indexedSortFieldKeys.has(key)) continue;
+      indexedSortFieldKeys.add(key);
+      schema.index(fields as { [key: string]: 1 | -1 });
+    }
+
     class DatabaseModelInstance extends adapt(`${modelName}Model`, ({ plug }) => ({
       __database: plug(DatabaseAdaptorRole, (database) => database),
       __cache: plug(CacheAdaptorRole, (cache) => new CacheDatabase(modelName, cache)),
@@ -222,7 +236,7 @@ export class DatabaseResolver {
           updateOne: (query: QueryOf<any>, update: DocumentUpdateInput, options?: { upsert?: boolean }) =>
             store.updateOneByQuery(query, update, options),
           updateMany: (query: QueryOf<any>, update: DocumentUpdateInput) => store.updateManyByQuery(query, update),
-          deleteMany: (query: QueryOf<any>) => store.deleteManyByQuery(query),
+          removeMany: (query: QueryOf<any>) => store.removeManyByQuery(query),
           bulkWrite: (
             operations: { updateOne: { filter: QueryOf<any>; update: DocumentUpdateInput; upsert?: boolean } }[],
           ) => store.bulkWrite(operations),
@@ -322,6 +336,9 @@ export class DatabaseResolver {
       async __remove(id: string) {
         return await this.__store.remove(id);
       }
+      async __removeMany(query: QueryOf<any>) {
+        return await timedQuery(() => this.__store.removeManyByQuery(query));
+      }
       async [`remove${className}`](id: string) {
         return this.__remove(id);
       }
@@ -389,6 +406,9 @@ export class DatabaseResolver {
       });
     });
     applyMixins(DatabaseModelInstance, [database.model]);
-    return DatabaseModelInstance as unknown as AdaptorCls<DatabaseInstance<any, any, any, any, any, any>>;
+    return {
+      adaptor: DatabaseModelInstance as unknown as AdaptorCls<DatabaseInstance<any, any, any, any, any, any>>,
+      schema,
+    };
   }
 }

package/server/resolver/index.ts

@@ -1,3 +1,4 @@
+export * from "./CascadeRunner";
 export * from "./database.resolver";
 export * from "./service.resolver";
 export * from "./signal.resolver";

package/server/resolver/service.resolver.ts

@@ -1,6 +1,6 @@
 import type { PromiseOrObject } from "akanjs/base";
 import { capitalize } from "akanjs/common";
-import { type ConstantModel, ConstantRegistry, type QueryOf } from "akanjs/constant";
+import type { QueryOf } from "akanjs/constant";
 import {
   type CRUDEventType,
   type DatabaseModel,
@@ -15,13 +15,10 @@ import {
   type SaveEventType,
 } from "akanjs/document";
 import type { DatabaseService, ServiceCls } from "akanjs/service";
+import type { CascadeRunner } from "./CascadeRunner";
 
 export class ServiceResolver {
-  static #getDefaultDbServiceMethods(
-    className: string,
-    cascades: [string, string][],
-    getService: (refName: string) => DatabaseService,
-  ) {
+  static #getDefaultDbServiceMethods(refName: string, className: string, cascade: CascadeRunner) {
     const dbServiceMethods = {
       async __get(this: DatabaseService, id: string) {
         return await this.__databaseModel.__get(id);
@@ -99,37 +96,24 @@ export class ServiceResolver {
         return this.__update(id, data);
       },
       async __remove(this: DatabaseService, id: string): Promise<Doc> {
-
-        const targets = cascades.map(([key, refName]) => [key, getService(refName)] as const);
         await this.__libsPreRemove(id);
         const doc = await this.__databaseModel.__remove(id);
         const removed = await this.__libsPostRemove(doc);
-        for (const [key, target] of targets) {
-          const value = (removed as Record<string, unknown>)[key];
-          const ids = (Array.isArray(value) ? value : [value]).filter((v): v is string => typeof v === "string");
-
-          for (const targetId of ids) await target.__remove(targetId);
-        }
+        await cascade.run(refName, removed as Record<string, unknown>);
         return removed;
       },
       async [`remove${className}`](this: DatabaseService, id: string): Promise<Doc> {
         return this.__remove(id);
       },
+      async __removeMany(this: DatabaseService, query: QueryOf<any>) {
+        return await this.__databaseModel.__removeMany(query);
+      },
     };
     return dbServiceMethods;
   }
-  static resolveDatabaseService(
-    constant: ConstantModel,
-    database: DatabaseModel,
-    srvRef: ServiceCls,
-    getService: (refName: string) => DatabaseService,
-  ): ServiceCls {
+  static resolveDatabaseService(database: DatabaseModel, srvRef: ServiceCls, cascade: CascadeRunner): ServiceCls {
     const className = capitalize(database.refName);
-
-    const cascades = [...constant.full.cascade.remove].map(
-      ([key, modelRef]) => [key, ConstantRegistry.getRefName(modelRef)] as [string, string],
-    );
-    Object.assign(srvRef.prototype, ServiceResolver.#getDefaultDbServiceMethods(className, cascades, getService));
+    Object.assign(srvRef.prototype, ServiceResolver.#getDefaultDbServiceMethods(database.refName, className, cascade));
     const getQueryDataFromKey = (queryKey: string, args: any): { query: any; queryOption: any } => {
       const lastArg = args.at(-1);
       const hasQueryOption =

package/server/rscWorker.tsx

@@ -24,6 +24,7 @@ import { renderToReadableStream } from "react-server-dom-webpack/server.node";
 import type { ClientManifest } from "./artifact";
 import {
   LruTtlCache,
+  type LruTtlCacheOptions,
   parsePositiveInt,
   type RouteCacheEntry,
   type RouteCacheInvalidation,
@@ -122,6 +123,9 @@ interface FlightRenderResult {
   cancelled: boolean;
 }
 
+/** Well above any sensible TTL: this reclaims a cache nobody is reading, not tracks expiry closely. */
+const RESULT_CACHE_SWEEP_INTERVAL_MS = 60_000;
+
 function hashRscTraceCacheKey(cacheKey: string): string {
   let hash = 5381;
   for (let index = 0; index < cacheKey.length; index += 1) hash = (hash * 33) ^ cacheKey.charCodeAt(index);
@@ -197,11 +201,14 @@ export class RscRenderer {
     pagesBundleBuildId: 0,
   };
   readonly #routeStats = new Map<string, RouteRenderStats>();
+
   #resultCache = new LruTtlCache<CachedRscResult>(
     parsePositiveInt(process.env.AKAN_RSC_RESULT_CACHE_MAX_ENTRIES) ?? 100,
+    RscRenderer.#resultCacheOptions(),
   );
   #patchResultCache = new LruTtlCache<CachedRscResult>(
     parsePositiveInt(process.env.AKAN_RSC_RESULT_CACHE_MAX_ENTRIES) ?? 100,
+    RscRenderer.#resultCacheOptions(),
   );
   readonly #activeRenderReaders = new Map<string, ReadableStreamDefaultReader<Uint8Array>>();
   readonly #cancelledRenderRequests = new Set<string>();
@@ -818,7 +825,11 @@ export class RscRenderer {
       rscLoadedRouteModuleKeys: routeStats.loadedModuleKeys,
       rscTopRoutesByRenderCount: this.#topRoutes((route) => route.count),
       rscTopRoutesByFlightBytes: this.#topRoutes((route) => route.flightBytes),
-      rscResultCacheEntries: this.#resultCache.size + this.#patchResultCache.size,
+
+      rscResultCacheEntries: this.#resultCache.size,
+      rscResultCacheBytes: this.#resultCache.byteSize,
+      rscPatchResultCacheEntries: this.#patchResultCache.size,
+      rscPatchResultCacheBytes: this.#patchResultCache.byteSize,
       rscResultCacheHits: this.#resultCacheHits,
       rscResultCacheMisses: this.#resultCacheMisses,
       rscResultCacheBypass: this.#resultCacheBypass,
@@ -899,7 +910,7 @@ export class RscRenderer {
       });
     };
     try {
-      while (true) {
+      for (;;) {
         if (options.requestId && this.#cancelledRenderRequests.has(options.requestId)) {
           await reader.cancel();
           return { chunks, bytes, chunksCount, control: null, lateControlSent, cancelled: true };
@@ -1125,6 +1136,15 @@ export class RscRenderer {
     return decision;
   }
 
+  static #resultCacheOptions(): LruTtlCacheOptions<CachedRscResult> {
+    return {
+      sizeOf: (result) => result.bytes,
+      maxBytes: LruTtlCache.parseByteCeiling(process.env.AKAN_RSC_RESULT_CACHE_MAX_BYTES),
+      maxEntryBytes: LruTtlCache.parseByteCeiling(process.env.AKAN_RSC_RESULT_CACHE_MAX_BODY_BYTES),
+      sweepIntervalMs: RESULT_CACHE_SWEEP_INTERVAL_MS,
+    };
+  }
+
   #getCachedResult(cacheKey: string): CachedRscResult | null {
     const cached = this.#resultCache.get(cacheKey);
     if (!cached) {
@@ -1146,11 +1166,19 @@ export class RscRenderer {
   }
 
   #setCachedResult(cacheKey: string, result: CachedRscResult, ttl: number): void {
-    this.#resultCache.set(cacheKey, result, ttl);
+    this.#logRejectedStore("full", result, this.#resultCache.set(cacheKey, result, ttl));
   }
 
   #setCachedPatchResult(cacheKey: string, result: CachedRscResult, ttl: number): void {
-    this.#patchResultCache.set(cacheKey, result, ttl);
+    this.#logRejectedStore("patch", result, this.#patchResultCache.set(cacheKey, result, ttl));
+  }
+
+  /** A silently dropped store looks identical to a cache miss; say which route is too big to cache. */
+  #logRejectedStore(kind: string, result: CachedRscResult, stored: boolean): void {
+    if (stored) return;
+    this.#logger.verbose(
+      `${kind} result cache store skipped pathname=${result.pathname} bytes=${result.bytes} reason=body-too-large`,
+    );
   }
 
   #runWithRequest<T>(request: Request, fn: () => Promise<T>): Promise<T> {

package/server/rscWorkerHost.ts

@@ -89,6 +89,66 @@ export function createRscWorkerInvalidateCacheMessage(
   };
 }
 
+/**
+ * The RSC worker samples its own process with the same `ProcessMetricsCollector.collect` its host
+ * replica uses, so its report carries `pid` / `rssBytes` / `role` / … under the identical names.
+ * `AkanServer` spreads the host's report into its own `collect({ role, ...webRouter.getMetrics() })`
+ * and `collect` spreads `extra` last (`processMetricsCollector.ts:122`) — so passing these through
+ * unprefixed silently overwrote the replica's own process fields, and the replica's RSS was reported
+ * nowhere. Rename them onto `rscWorker*`; the `rsc*` render counters, which only the worker
+ * produces, pass through untouched.
+ *
+ * XXX A new process-level field in `ProcessMetricsCollector.collect` must be added here too, or it
+ * starts shadowing the replica again.
+ */
+export function projectRscWorkerProcessMetrics(metrics: AkanMetricsReport): AkanMetricsReport {
+  const {
+    role: _role,
+    pid: _pid,
+    trace: _trace,
+    reportedAt,
+    rssBytes,
+    heapTotalBytes,
+    heapUsedBytes,
+    externalBytes,
+    arrayBuffersBytes,
+    cpuUserMicros,
+    cpuSystemMicros,
+    maxRssKb,
+    jscHeapSizeBytes,
+    jscHeapCapacityBytes,
+    jscExtraMemorySizeBytes,
+    jscObjectCount,
+    jscProtectedObjectCount,
+    eventLoopLagMeanMs,
+    eventLoopLagP99Ms,
+    eventLoopLagMaxMs,
+    gcDurationMs,
+    ...renderMetrics
+  } = metrics;
+  return {
+    ...renderMetrics,
+    rscWorkerReportedAt: reportedAt,
+    rscWorkerRssBytes: rssBytes,
+    rscWorkerHeapTotalBytes: heapTotalBytes,
+    rscWorkerHeapUsedBytes: heapUsedBytes,
+    rscWorkerExternalBytes: externalBytes,
+    rscWorkerArrayBuffersBytes: arrayBuffersBytes,
+    rscWorkerCpuUserMicros: cpuUserMicros,
+    rscWorkerCpuSystemMicros: cpuSystemMicros,
+    rscWorkerMaxRssKb: maxRssKb,
+    rscWorkerJscHeapSizeBytes: jscHeapSizeBytes,
+    rscWorkerJscHeapCapacityBytes: jscHeapCapacityBytes,
+    rscWorkerJscExtraMemorySizeBytes: jscExtraMemorySizeBytes,
+    rscWorkerJscObjectCount: jscObjectCount,
+    rscWorkerJscProtectedObjectCount: jscProtectedObjectCount,
+    rscWorkerEventLoopLagMeanMs: eventLoopLagMeanMs,
+    rscWorkerEventLoopLagP99Ms: eventLoopLagP99Ms,
+    rscWorkerEventLoopLagMaxMs: eventLoopLagMaxMs,
+    rscWorkerGcDurationMs: gcDurationMs,
+  };
+}
+
 export function createRscHostRenderStream(input: {
   setPending: (pending: RscPending) => void;
   deletePending: () => void;
@@ -464,18 +524,7 @@ export class RscWorker {
   }
 
   getMetrics(): AkanMetricsReport {
-    const {
-      rscWorkerPid: _rscWorkerPid,
-      rscWorkerStatus: _rscWorkerStatus,
-      rscWorkerRestartCount: _rscWorkerRestartCount,
-      rscWorkerRecycleCount: _rscWorkerRecycleCount,
-      rscWorkerLastRecycleReason: _rscWorkerLastRecycleReason,
-      rscPendingRenderCount: _rscPendingRenderCount,
-      rscQueuedSendCount: _rscQueuedSendCount,
-      rscHostPendingChunkOverflowCount: _rscHostPendingChunkOverflowCount,
-      ...workerMetrics
-    } = this.#lastWorkerMetrics;
-    return Object.assign(workerMetrics, {
+    return Object.assign(projectRscWorkerProcessMetrics(this.#lastWorkerMetrics), {
       rscWorkerPid: this.#proc.pid,
       rscWorkerStatus: this.#status,
       rscWorkerRestartCount: this.#restartCount,

package/server/ssrFromRscRenderer.tsx

@@ -411,7 +411,7 @@ export function interleaveRscScriptsWithHtml(
       const pumpRscScripts = async () => {
         rscReader = rscClientStream.getReader();
         try {
-          while (true) {
+          for (;;) {
             const { value, done } = await rscReader.read();
             if (done || errored) break;
             await waitForRscQueueDrain();
@@ -446,7 +446,7 @@ export function interleaveRscScriptsWithHtml(
 
         htmlReader = htmlStream.getReader();
         try {
-          while (true) {
+          for (;;) {
             const { value, done } = await htmlReader.read();
             if (done || errored) break;
             controller.enqueue(value);

package/server/webRouter.ts

@@ -56,6 +56,8 @@ import type { BaseBuildArtifact, HttpRoutes, RenderState } from "./types";
 
 const CLIENT_CLOSED_REQUEST_STATUS = 499;
 export const DEFAULT_HTML_RESULT_CACHE_MAX_BODY_BYTES = 2 * 1024 * 1024;
+/** Well above any sensible TTL: this only has to reclaim a cache nobody is reading, not track expiry closely. */
+const ROUTE_CACHE_SWEEP_INTERVAL_MS = 60_000;
 const APPLE_APP_SITE_ASSOCIATION_PATH = "/.well-known/apple-app-site-association";
 const ANDROID_ASSET_LINKS_PATH = "/.well-known/assetlinks.json";
 
@@ -286,6 +288,11 @@ export class WebRouter {
   };
   readonly #htmlCache = new LruTtlCache<CachedHtmlResult>(
     parsePositiveInt(process.env.AKAN_HTML_RESULT_CACHE_MAX_ENTRIES) ?? 100,
+    {
+      sizeOf: (result) => result.html.length,
+      maxBytes: LruTtlCache.parseByteCeiling(process.env.AKAN_HTML_RESULT_CACHE_MAX_BYTES),
+      sweepIntervalMs: ROUTE_CACHE_SWEEP_INTERVAL_MS,
+    },
   );
   #htmlCacheHits = 0;
   #htmlCacheMisses = 0;
@@ -669,6 +676,7 @@ export class WebRouter {
     this.#devHmr?.dispose();
     this.#devHmr = null;
     this.#builderRpc = null;
+    this.#htmlCache.dispose();
     this.#rsc.kill();
     this.#hub = null;
   }
@@ -686,6 +694,7 @@ export class WebRouter {
       httpCsrCount: this.#requestStats.csr,
       httpImageCount: this.#requestStats.image,
       httpHtmlCacheEntries: this.#htmlCache.size,
+      httpHtmlCacheBytes: this.#htmlCache.byteSize,
       httpHtmlCacheHits: this.#htmlCacheHits,
       httpHtmlCacheMisses: this.#htmlCacheMisses,
       httpHtmlCacheBypass: this.#htmlCacheBypass,

package/service/ipcTypes.ts

@@ -55,6 +55,26 @@ export interface AkanMetricsReport {
   rscWorkerRestartCount?: number;
   rscWorkerRecycleCount?: number;
   rscWorkerLastRecycleReason?: string;
+
+  rscWorkerReportedAt?: number;
+  rscWorkerRssBytes?: number;
+  rscWorkerHeapTotalBytes?: number;
+  rscWorkerHeapUsedBytes?: number;
+  rscWorkerExternalBytes?: number;
+  rscWorkerArrayBuffersBytes?: number;
+  rscWorkerCpuUserMicros?: number;
+  rscWorkerCpuSystemMicros?: number;
+  rscWorkerMaxRssKb?: number;
+  rscWorkerJscHeapSizeBytes?: number;
+  rscWorkerJscHeapCapacityBytes?: number;
+  /** Off-heap bytes JSC attributes to JS objects — typed-array backing stores, i.e. cached Flight chunks. */
+  rscWorkerJscExtraMemorySizeBytes?: number;
+  rscWorkerJscObjectCount?: number;
+  rscWorkerJscProtectedObjectCount?: number;
+  rscWorkerEventLoopLagMeanMs?: number;
+  rscWorkerEventLoopLagP99Ms?: number;
+  rscWorkerEventLoopLagMaxMs?: number;
+  rscWorkerGcDurationMs?: number;
   rscPendingRenderCount?: number;
   rscQueuedSendCount?: number;
   rscHostPendingChunkOverflowCount?: number;
@@ -80,9 +100,13 @@ export interface AkanMetricsReport {
   rscLastRenderLoadedModuleDelta?: number;
   rscLastRenderLoadedModules?: string[];
   rscResultCacheEntries?: number;
+  rscResultCacheBytes?: number;
+  rscPatchResultCacheEntries?: number;
+  rscPatchResultCacheBytes?: number;
   rscResultCacheHits?: number;
   rscResultCacheMisses?: number;
   rscResultCacheBypass?: number;
+  /** Keys the SSR chunk registry tracks — NOT a memory bound; the modules stay in Bun's ESM registry. */
   ssrChunkRegistrySize?: number;
   ssrChunkLoadCount?: number;
   ssrChunkCacheHitCount?: number;
@@ -93,6 +117,7 @@ export interface AkanMetricsReport {
   httpCsrCount?: number;
   httpImageCount?: number;
   httpHtmlCacheEntries?: number;
+  httpHtmlCacheBytes?: number;
   httpHtmlCacheHits?: number;
   httpHtmlCacheMisses?: number;
   httpHtmlCacheBypass?: number;

package/service/predefinedAdaptor/database.adaptor.ts

@@ -95,7 +95,7 @@ export interface DocumentStore {
     query: DocumentQuery,
     update: DocumentUpdateInput,
   ): Promise<{ acknowledged: boolean; matchedCount: number; modifiedCount: number }>;
-  deleteManyByQuery(
+  removeManyByQuery(
     query: DocumentQuery,
   ): Promise<{ acknowledged: boolean; matchedCount: number; modifiedCount: number }>;
   bulkWrite(
@@ -1081,8 +1081,8 @@ export class SqlDocumentStore {
     return { acknowledged: true, matchedCount: changes, modifiedCount: changes };
   }
 
-  async deleteManyByQuery(query: DocumentQuery) {
-    
+  async removeManyByQuery(query: DocumentQuery) {
+
     return this.updateManyByQuery(query, { removedAt: dayjs() });
   }
 

package/service/serve.ts

@@ -1,4 +1,4 @@
-import { type Cls, INJECT_META } from "akanjs/base";
+import { type Cls, INJECT_META, LIBS_REMOVE_HOOK } from "akanjs/base";
 import { applyMixins, capitalize, Logger, lowerlize } from "akanjs/common";
 import type { DatabaseModel } from "akanjs/document";
 
@@ -146,6 +146,10 @@ export function serve(
     const postUpdateFns = extSrvs.map((srv) => srv.prototype._postUpdate);
     const preRemoveFns = extSrvs.map((srv) => srv.prototype._preRemove);
     const postRemoveFns = extSrvs.map((srv) => srv.prototype._postRemove);
+
+    Object.assign(srvRef, {
+      [LIBS_REMOVE_HOOK]: preRemoveFns.some(Boolean) || postRemoveFns.some(Boolean),
+    });
     Object.assign(srvRef.prototype, {
       async __libsPreCreate(this: DatabaseService, data: DatabaseServiceData) {
         let result = data;

package/service/types.ts

@@ -11,6 +11,7 @@ import type {
   ListQueryOption,
   QueryMethodPart,
   SaveEventType,
+  UpdateResult,
 } from "akanjs/document";
 
 type ServiceMixinOmitKey =
@@ -101,6 +102,7 @@ export type DatabaseService<
   __create: (data: _DataInputOfDoc) => Promise<Doc>;
   __update: (id: string, data: Partial<Doc>) => Promise<Doc>;
   __remove: (id: string) => Promise<Doc>;
+  __removeMany: (query: _QueryOfDoc) => Promise<UpdateResult>;
   __list(query?: _QueryOfDoc, queryOption?: _ListQueryOption): Promise<Doc[]>;
   __listIds(query?: _QueryOfDoc, queryOption?: _ListQueryOption): Promise<string[]>;
   __find(query?: _QueryOfDoc, queryOption?: _FindQueryOption): Promise<Doc | null>;

package/types/base/symbols.d.ts

@@ -3,6 +3,7 @@ export declare const SLICE_META: unique symbol;
 export declare const FILTER_META: unique symbol;
 export declare const LOADER_META: unique symbol;
 export declare const INJECT_META: unique symbol;
+export declare const LIBS_REMOVE_HOOK: unique symbol;
 export declare const ENDPOINT_META: unique symbol;
 export declare const ENDPOINT_DICT_SHAPE: unique symbol;
 export declare const SLICE_DICT_SHAPE: unique symbol;