akanjs 2.0.5 → 2.0.7

package/server/processMetricsCollector.ts

@@ -1,4 +1,5 @@
 import type { AkanMetricsReport } from "akanjs/service";
+import { getTraceSnapshot, isTraceEnabled } from "akanjs/signal";
 
 type BunJscHeapStats = {
   heapSize?: number;
@@ -8,19 +9,83 @@ type BunJscHeapStats = {
   protectedObjectCount?: number;
 };
 
+/**
+ * Samples event-loop scheduling delay by measuring how late a fixed-interval timer
+ * actually fires. The sample window is summarized and reset on each metrics report,
+ * so values reflect recent load rather than process lifetime.
+ */
+class EventLoopLagMonitor {
+  static readonly #maxSamples = 600;
+  #timer: ReturnType<typeof setInterval> | null = null;
+  #intervalMs = 500;
+  #lastTickAt = 0;
+  #samples: number[] = [];
+  #maxMs = 0;
+
+  start(intervalMs = 500): void {
+    if (this.#timer) return;
+    this.#intervalMs = intervalMs;
+    this.#lastTickAt = performance.now();
+    this.#timer = setInterval(() => {
+      const now = performance.now();
+      const lag = Math.max(0, now - this.#lastTickAt - this.#intervalMs);
+      this.#lastTickAt = now;
+      this.#maxMs = Math.max(this.#maxMs, lag);
+      if (this.#samples.length < EventLoopLagMonitor.#maxSamples) this.#samples.push(lag);
+      else this.#samples[Math.floor(Math.random() * EventLoopLagMonitor.#maxSamples)] = lag;
+    }, intervalMs);
+    
+    (this.#timer as { unref?: () => void }).unref?.();
+  }
+
+  /** Summarize the current window and reset it. */
+  snapshotAndReset(): { meanMs: number; p99Ms: number; maxMs: number } | null {
+    if (this.#samples.length === 0) return null;
+    const sorted = [...this.#samples].sort((a, b) => a - b);
+    const sum = sorted.reduce((acc, v) => acc + v, 0);
+    const p99Index = Math.min(sorted.length - 1, Math.floor(0.99 * sorted.length));
+    const result = {
+      meanMs: round(sum / sorted.length),
+      p99Ms: round(sorted[p99Index] ?? 0),
+      maxMs: round(this.#maxMs),
+    };
+    this.#samples = [];
+    this.#maxMs = 0;
+    return result;
+  }
+}
+
+const round = (value: number, digits = 3): number => {
+  const factor = 10 ** digits;
+  return Math.round(value * factor) / factor;
+};
+
 export class ProcessMetricsCollector {
   static readonly #defaultMemoryLogIntervalMs = 60_000;
+  static readonly #lagMonitor = new EventLoopLagMonitor();
 
   static parseMemoryLogIntervalMs(value = process.env.AKAN_MEMORY_LOG_INTERVAL_MS) {
     const parsed = Number.parseInt(value ?? "", 10);
     return Number.isFinite(parsed) && parsed > 0 ? parsed : ProcessMetricsCollector.#defaultMemoryLogIntervalMs;
   }
 
+  /** Begin sampling event-loop lag. Idempotent; safe to call from each server role. */
+  static startEventLoopLagMonitor(intervalMs = 500): void {
+    ProcessMetricsCollector.#lagMonitor.start(intervalMs);
+  }
+
   static async collect(extra: AkanMetricsReport = {}): Promise<AkanMetricsReport> {
-    if (process.env.AKAN_MEMORY_GC_ON_REPORT === "1") Bun.gc(true);
+    ProcessMetricsCollector.#lagMonitor.start();
+    let gcDurationMs: number | undefined;
+    if (process.env.AKAN_MEMORY_GC_ON_REPORT === "1") {
+      const gcStart = performance.now();
+      Bun.gc(true);
+      gcDurationMs = round(performance.now() - gcStart);
+    }
     const memory = process.memoryUsage();
     const resourceUsage = process.resourceUsage?.();
     const jsc = await ProcessMetricsCollector.#collectJscHeapStats();
+    const lag = ProcessMetricsCollector.#lagMonitor.snapshotAndReset();
     return {
       pid: process.pid,
       reportedAt: Date.now(),
@@ -45,6 +110,15 @@ export class ProcessMetricsCollector {
             jscProtectedObjectCount: jsc.protectedObjectCount,
           }
         : {}),
+      ...(lag
+        ? {
+            eventLoopLagMeanMs: lag.meanMs,
+            eventLoopLagP99Ms: lag.p99Ms,
+            eventLoopLagMaxMs: lag.maxMs,
+          }
+        : {}),
+      ...(gcDurationMs !== undefined ? { gcDurationMs } : {}),
+      ...(isTraceEnabled() ? { trace: getTraceSnapshot() } : {}),
       ...extra,
     };
   }
@@ -64,6 +138,10 @@ export class ProcessMetricsCollector {
       ...(metrics.jscHeapSizeBytes !== undefined
         ? [`jscHeap=${ProcessMetricsCollector.formatBytes(metrics.jscHeapSizeBytes)}`]
         : []),
+      ...(metrics.eventLoopLagMeanMs !== undefined
+        ? [`elLag=${metrics.eventLoopLagMeanMs}/${metrics.eventLoopLagP99Ms ?? 0}/${metrics.eventLoopLagMaxMs ?? 0}ms`]
+        : []),
+      ...(metrics.gcDurationMs !== undefined ? [`gc=${metrics.gcDurationMs}ms`] : []),
     ].join(" ");
   }
 

package/server/proxy/localeWebProxy.ts

@@ -1,22 +1,39 @@
-import { match as matchLocale } from "@formatjs/intl-localematcher";
 import { parseAkanI18nEnv } from "akanjs/common";
-import Negotiator from "negotiator";
 import { AkanResponse } from "./akanResponse";
 import type { WebProxy } from "./types";
 
 function getLocale(request: Bun.BunRequest): string {
   const i18n = parseAkanI18nEnv();
-  if (!request.headers.get("accept-language")) return i18n.defaultLocale;
-  const negotiatorHeaders: Record<string, string> = {};
-  request.headers.forEach((value, key) => {
-    negotiatorHeaders[key] = value;
-  });
-  try {
-    const languages = new Negotiator({ headers: negotiatorHeaders }).languages();
-    return matchLocale(languages, i18n.locales, i18n.defaultLocale);
-  } catch {
-    return i18n.defaultLocale;
+  const acceptLanguage = request.headers.get("accept-language");
+  if (!acceptLanguage) return i18n.defaultLocale;
+  return matchAcceptedLocale(acceptLanguage, i18n.locales, i18n.defaultLocale);
+}
+
+function matchAcceptedLocale(acceptLanguage: string, locales: string[], defaultLocale: string): string {
+  const localeByLower = new Map(locales.map((locale) => [locale.toLowerCase(), locale]));
+  const acceptedLanguages = acceptLanguage
+    .split(",")
+    .map((part, index) => {
+      const [tag = "", ...params] = part.trim().split(";");
+      const quality = params
+        .map((param) => param.trim())
+        .find((param) => param.startsWith("q="))
+        ?.slice(2);
+      const q = quality === undefined ? 1 : Number(quality);
+      return { tag: tag.trim().toLowerCase(), q: Number.isFinite(q) ? q : 0, index };
+    })
+    .filter(({ tag, q }) => tag.length > 0 && q > 0)
+    .sort((a, b) => b.q - a.q || a.index - b.index);
+
+  for (const { tag } of acceptedLanguages) {
+    if (tag === "*") return defaultLocale;
+    const exact = localeByLower.get(tag);
+    if (exact) return exact;
+    const [language] = tag.split("-");
+    const baseMatch = locales.find((locale) => locale.toLowerCase().split("-")[0] === language);
+    if (baseMatch) return baseMatch;
   }
+  return defaultLocale;
 }
 
 export class LocaleWebProxy implements WebProxy {

package/server/resolver/database.resolver.ts

@@ -27,6 +27,22 @@ import {
   DatabaseAdaptorRole,
   type DocumentStore,
 } from "akanjs/service";
+import { getCurrentTrace, traceDataLoaderBatch } from "akanjs/signal";
+
+/**
+ * Times a store query and records it against the active request trace (no-op when
+ * tracing is disabled). Used to surface "queries per request" and DB latency share.
+ */
+const timedQuery = async <T>(fn: () => Promise<T>): Promise<T> => {
+  const trace = getCurrentTrace();
+  if (!trace) return await fn();
+  const start = performance.now();
+  try {
+    return await fn();
+  } finally {
+    trace.countDbQuery(performance.now() - start);
+  }
+};
 
 export class DatabaseResolver {
   static resolveDatabase(constant: ConstantModel, database: DatabaseModel): AdaptorCls<DatabaseInstance> {
@@ -55,6 +71,18 @@ export class DatabaseResolver {
     const schema = new DocumentSchema();
     database.model._onSchema(schema as any);
     database.model._libsOnSchema(schema as any);
+    const filterMeta = getFilterMeta(database.filter);
+    const indexedSortFieldKeys = new Set<string>();
+    for (const sort of Object.values(filterMeta.sort)) {
+      if (!sort || typeof sort !== "object") continue;
+      const sortFields = Object.entries(sort as Record<string, 1 | -1>);
+      if (!sortFields.length) continue;
+      const fields = Object.fromEntries([["removedAt", 1] as const, ...sortFields]);
+      const key = Object.keys(fields).join(",");
+      if (indexedSortFieldKeys.has(key)) continue;
+      indexedSortFieldKeys.add(key);
+      schema.index(fields);
+    }
 
     class DatabaseModelInstance extends adapt(`${modelName}Model`, ({ plug }) => ({
       __database: plug(DatabaseAdaptorRole, (database) => database),
@@ -71,7 +99,12 @@ export class DatabaseResolver {
         await this.__store.ensure();
         this.__model = this.#createModelFacade() as unknown as Mdl<any, any>;
         this.__loader = new DataLoader<string, any>(
-          async (ids) => await Promise.all(ids.map((id) => this.__store.findOne({ id }))),
+          async (ids) => {
+            traceDataLoaderBatch(ids.length);
+            const docs = await timedQuery(() => this.__store.find({ id: documentQueryHelper.oneOf([...ids]) }));
+            const byId = new Map(docs.map((doc) => [String(doc.id), doc]));
+            return ids.map((id) => byId.get(String(id)) ?? null);
+          },
           { name: `${modelName}Loader`, cache: false },
         );
         Object.assign(this, {
@@ -81,18 +114,35 @@ export class DatabaseResolver {
         Object.entries(getLoaderInfos(database.model)).forEach(([key, loaderInfo]) => {
           Object.assign(this, {
             [key]: new DataLoader<any, any>(async (keys) => {
-              return await Promise.all(
-                keys.map(async (key) => {
-                  const query =
-                    loaderInfo.type === "query"
-                      ? key
-                      : {
-                          [loaderInfo.field as string]:
-                            loaderInfo.type === "arrayField" ? documentQueryHelper.has(key) : key,
-                        };
-                  return await this.__store.findOne(documentQueryHelper.all(loaderInfo.defaultQuery, query));
-                }),
+              traceDataLoaderBatch(keys.length);
+              if (loaderInfo.type === "query") {
+                const fields = loaderInfo.field as string[];
+                const query = { kind: "any", queries: keys } as QueryOf<unknown>;
+                const docs = await timedQuery(() =>
+                  this.__store.find(documentQueryHelper.all(loaderInfo.defaultQuery, query)),
+                );
+                const byKey = new Map(docs.map((doc) => [fields.map((field) => String(doc[field])).join(""), doc]));
+                return keys.map(
+                  (queryKey) => byKey.get(fields.map((field) => String(queryKey[field])).join("")) ?? null,
+                );
+              }
+              const field = loaderInfo.field as string;
+              const query = {
+                [field]: documentQueryHelper.oneOf([...keys]),
+              };
+              const docs = await timedQuery(() =>
+                this.__store.find(documentQueryHelper.all(loaderInfo.defaultQuery, query)),
               );
+              if (loaderInfo.type === "arrayField") {
+                const byKey = new Map<string, unknown>();
+                for (const doc of docs) {
+                  const values = Array.isArray(doc[field]) ? doc[field] : [];
+                  for (const value of values) if (!byKey.has(String(value))) byKey.set(String(value), doc);
+                }
+                return keys.map((key) => byKey.get(String(key)) ?? null);
+              }
+              const byKey = new Map(docs.map((doc) => [String(doc[field]), doc]));
+              return keys.map((key) => byKey.get(String(key)) ?? null);
             }),
           });
         });
@@ -105,7 +155,7 @@ export class DatabaseResolver {
         }
         const createFindManyChain = (
           query: QueryOf<any>,
-          options: { sort?: any; skip?: number; limit?: number } = {},
+          options: { sort?: any; skip?: number; limit?: number; select?: any } = {},
         ) => {
           const chain: any = {
             sort(sort: any) {
@@ -117,8 +167,8 @@ export class DatabaseResolver {
             limit(limit: number) {
               return createFindManyChain(query, { ...options, limit });
             },
-            select() {
-              return createFindManyChain(query, options);
+            select(select?: any) {
+              return createFindManyChain(query, { ...options, select });
             },
             
             then(resolve: (value: any[]) => void, reject: (reason: unknown) => void) {
@@ -130,7 +180,7 @@ export class DatabaseResolver {
           };
           return chain;
         };
-        const createFindOneChain = (query: QueryOf<any>, options: { sort?: any; skip?: number } = {}) => {
+        const createFindOneChain = (query: QueryOf<any>, options: { sort?: any; skip?: number; select?: any } = {}) => {
           const chain: any = {
             sort(sort: any) {
               return createFindOneChain(query, { ...options, sort });
@@ -138,8 +188,8 @@ export class DatabaseResolver {
             skip(skip: number) {
               return createFindOneChain(query, { ...options, skip });
             },
-            select() {
-              return createFindOneChain(query, options);
+            select(select?: any) {
+              return createFindOneChain(query, { ...options, select });
             },
             
             then(resolve: (value: any | null) => void, reject: (reason: unknown) => void) {
@@ -153,10 +203,13 @@ export class DatabaseResolver {
         };
         return Object.assign(Model, {
           refName: modelName,
-          pickOne: (query: QueryOf<any>, _projection?: any) => store.pickOne(query),
-          pickById: (id: string | undefined, _projection?: any) => {
+          pickOne: (query: QueryOf<any>, projection?: any) => store.pickOne(query, { select: projection }),
+          pickById: (id: string | undefined, projection?: any) => {
             if (!id) throw new Error("No Document ID");
-            return store.pickById(id);
+            return store.findOne({ id }, { select: projection }).then((doc) => {
+              if (!doc) throw new Error(`No Document (${modelName}): ${id}`);
+              return doc;
+            });
           },
           exists: async (query: QueryOf<any>) => await store.exists(query),
           sample: (query: QueryOf<any>, size = 1) => store.find(query, { sample: size, limit: size }),
@@ -184,20 +237,20 @@ export class DatabaseResolver {
       }
 
       async __list(query?: QueryOf<any>, queryOption?: ListQueryOption): Promise<any[]> {
-        const { find, sort, skip, limit, sample } = getListQuery(query, queryOption);
-        return await this.__store.find(find, { sort, skip, limit, sample });
+        const { find, sort, skip, limit, sample, select } = getListQuery(query, queryOption);
+        return await timedQuery(() => this.__store.find(find, { sort, skip, limit, sample, select }));
       }
       async __listIds(query?: QueryOf<any>, queryOption?: ListQueryOption): Promise<string[]> {
         const { find, sort, skip, limit, sample } = getListQuery(query, queryOption);
-        return await this.__store.findIds(find, { sort, skip, limit, sample });
+        return await timedQuery(() => this.__store.findIds(find, { sort, skip, limit, sample }));
       }
       async __find(query?: QueryOf<any>, queryOption?: FindQueryOption): Promise<any | null> {
         const { find, sort, skip, sample } = getFindQuery(query, queryOption);
-        return await this.__store.findOne(find, { sort, skip, sample });
+        return await timedQuery(() => this.__store.findOne(find, { sort, skip, sample }));
       }
       async __findId(query?: QueryOf<any>, queryOption?: FindQueryOption): Promise<string | null> {
         const { find, sort, skip, sample } = getFindQuery(query, queryOption);
-        return await this.__store.findId(find, { sort, skip, sample });
+        return await timedQuery(() => this.__store.findId(find, { sort, skip, sample }));
       }
       async __pick(query?: QueryOf<any>, queryOption?: FindQueryOption): Promise<any> {
         const { find, sort, skip, sample } = getFindQuery(query, queryOption);
@@ -213,7 +266,7 @@ export class DatabaseResolver {
         return await this.__store.exists(query);
       }
       async __count(query?: QueryOf<any>): Promise<number> {
-        return await this.__store.count(query);
+        return await timedQuery(() => this.__store.count(query));
       }
       async __insight(query?: QueryOf<any>): Promise<any> {
         return await this.__store.insight(query);
@@ -254,13 +307,13 @@ export class DatabaseResolver {
         return await this.__store.clone(data);
       }
       async __create(data: DataInputOf<any, any>) {
-        return await this.__store.create(data);
+        return await timedQuery(() => this.__store.create(data));
       }
       async [`create${className}`](data: DataInputOf<any, any>) {
         return this.__create(data);
       }
       async __update(id: string, data: DataInputOf<any, any>) {
-        return await this.__store.update(id, data);
+        return await timedQuery(() => this.__store.update(id, data));
       }
       async [`update${className}`](id: string, data: DataInputOf<any, any>) {
         return this.__update(id, data);
@@ -289,8 +342,6 @@ export class DatabaseResolver {
       const queryOption = hasQueryOption ? lastArg : {};
       return { query, queryOption };
     };
-    const filterMeta = getFilterMeta(database.filter);
-
     Object.entries(filterMeta.query).forEach(([queryKey, filterInfo]) => {
       const queryFn = filterInfo.queryFn;
       if (!queryFn) throw new Error(`No query function for key: ${queryKey}`);

package/server/resolver/signal.resolver.ts

@@ -1,4 +1,15 @@
-import { type BaseEnv, type Cls, ENDPOINT_META, getEnv, ID, INTERNAL_META, Int, SLICE_META } from "akanjs/base";
+import {
+  type BaseEnv,
+  type Cls,
+  ENDPOINT_META,
+  FIELD_META,
+  getEnv,
+  ID,
+  INTERNAL_META,
+  Int,
+  PrimitiveRegistry,
+  SLICE_META,
+} from "akanjs/base";
 import { capitalize, Logger } from "akanjs/common";
 import { serialize } from "akanjs/constant";
 import { documentQueryHelper } from "akanjs/document";
@@ -169,7 +180,12 @@ export class SignalResolver {
             const sort = requestArgs[argLength + 2] ?? "latest";
             const internalArgs = requestArgs.slice(argLength + 3);
             const query = await sliceInfo.execFn?.apply(this, [...args, ...internalArgs, documentQueryHelper]);
-            return (await this[serviceName].__list(query, { skip, limit, sort })) as any;
+            return (await this[serviceName].__list(query, {
+              skip,
+              limit,
+              sort,
+              select: SignalResolver.#selectForConstant(sliceInfo.light),
+            })) as any;
           });
 
         const insightKey = `${refName}Insight${capitalizedKey}`;
@@ -249,37 +265,37 @@ export class SignalResolver {
       if (endpointInfo.signalOption.globalPrefix !== undefined) {
         routeOptions[path] = { globalPrefix: endpointInfo.signalOption.globalPrefix };
       }
+      const normalHttpHandler = async (req: Bun.BunRequest) =>
+        await SignalContext.try(endpoint, endpointInfo, key, async () => {
+          const context = await new SignalContext(key, req, {
+            endpointInfo,
+            adaptor: endpoint,
+            registry,
+            env,
+            live,
+            middleware,
+          }).init();
+          return await context.exec();
+        });
       switch (endpointInfo.type) {
         case "query":
-          routes[path] = {
-            GET: async (req) =>
-              await SignalContext.try(endpoint, endpointInfo, key, async () => {
-                const context = await new SignalContext(key, req, {
-                  endpointInfo,
-                  adaptor: endpoint,
-                  registry,
-                  env,
-                  live,
-                  middleware,
-                }).init();
-                return await context.exec();
-              }),
-          };
+          routes[path] = SignalResolver.#canUsePrimitiveQueryFastPath(endpointInfo, middleware)
+            ? {
+                GET: async (req) => {
+                  if (SignalResolver.#hasAuthCredential(req)) return await normalHttpHandler(req);
+                  return await SignalContext.try(endpoint, endpointInfo, key, async () => {
+                    const result = await endpointInfo.execFn?.call(endpoint);
+                    return result instanceof Response ? result : Response.json(result);
+                  });
+                },
+              }
+            : {
+                GET: normalHttpHandler,
+              };
           break;
         case "mutation":
           routes[path] = {
-            POST: async (req) =>
-              await SignalContext.try(endpoint, endpointInfo, key, async () => {
-                const context = await new SignalContext(key, req, {
-                  endpointInfo,
-                  adaptor: endpoint,
-                  registry,
-                  env,
-                  live,
-                  middleware,
-                }).init();
-                return await context.exec();
-              }),
+            POST: normalHttpHandler,
           };
           break;
         case "pubsub":
@@ -349,6 +365,29 @@ export class SignalResolver {
     return trimmed ? `/${trimmed}` : "";
   }
 
+  static #selectForConstant(constant: Cls): Record<string, true> | undefined {
+    const fields = (constant as { [FIELD_META]?: Record<string, unknown> })[FIELD_META];
+    if (!fields) return undefined;
+    return Object.fromEntries(Object.keys(fields).map((field) => [field, true]));
+  }
+
+  static #canUsePrimitiveQueryFastPath(endpointInfo: EndpointInfo, middleware: Map<string, MiddlewareCls>) {
+    return (
+      process.env.AKAN_TRACE !== "1" &&
+      endpointInfo.args.length === 0 &&
+      endpointInfo.internalArgs.length === 0 &&
+      (endpointInfo.signalOption.guards?.length ?? 0) === 0 &&
+      (endpointInfo.signalOption.middlewares?.length ?? 0) === 0 &&
+      [...middleware.values()].every((MiddlewareCls) => MiddlewareCls.refName === "AccountMiddleware") &&
+      endpointInfo.returns.arrDepth === 0 &&
+      PrimitiveRegistry.has(endpointInfo.returns.returnRef as Cls)
+    );
+  }
+
+  static #hasAuthCredential(req: Request) {
+    return Boolean(req.headers.get("authorization") || req.headers.get("cookie")?.includes("jwt="));
+  }
+
   static async handleWsOpen(ws: Bun.ServerWebSocket<any>, registry: InjectRegistry) {
     await SignalResolver.#getWebsocket(registry).registerSocket(ws);
   }

package/service/ipcTypes.ts

@@ -94,6 +94,11 @@ export interface AkanMetricsReport {
   httpHtmlCacheHits?: number;
   httpHtmlCacheMisses?: number;
   httpHtmlCacheBypass?: number;
+  eventLoopLagMeanMs?: number;
+  eventLoopLagP99Ms?: number;
+  eventLoopLagMaxMs?: number;
+  gcDurationMs?: number;
+  trace?: unknown;
 }
 
 export type AkanIpcMessage =