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

package/server/devtools/devtoolsJson.ts

@@ -1,17 +1,9 @@
 import { dayjs } from "akanjs/base";
 import type { Unserializable } from "./types";
 
-/**
- * Coerces arbitrary registry values into something `JSON.stringify` can round-trip.
- *
- * Registries hold whatever a `.constant.ts` happened to export — Dayjs defaults, Maps, Sets, classes,
- * closures, even cyclic graphs. The devtools payloads must never throw on one of those, so anything
- * unrepresentable degrades to an `Unserializable` marker the visualiser can render as-is.
- */
+/** Never throws: what JSON cannot represent (functions, classes, cycles, …) becomes an `Unserializable` marker. */
 export class DevtoolsJson {
-  static readonly #defaultMaxDepth = 6;
-
-  static toSafe(value: unknown, { maxDepth = DevtoolsJson.#defaultMaxDepth }: { maxDepth?: number } = {}): unknown {
+  static toSafe(value: unknown, { maxDepth = 6 }: { maxDepth?: number } = {}): unknown {
     return DevtoolsJson.#coerce(value, maxDepth, new WeakSet<object>());
   }
 
@@ -33,7 +25,6 @@ export class DevtoolsJson {
     }
   }
 
-  /** Returns `undefined` when `value` is not a leaf this method owns, so the caller keeps walking. */
   static #coercePrimitive(value: unknown): unknown {
     switch (typeof value) {
       case "string":
@@ -46,18 +37,15 @@ export class DevtoolsJson {
         return DevtoolsJson.#mark("bigint", String(value));
       case "symbol":
         return DevtoolsJson.#mark("symbol", (value as symbol).description);
-      case "function":
-        return DevtoolsJson.#coerceFunction(value as (...args: never[]) => unknown);
+      case "function": {
+        const isClass = /^\s*class\s/.test(Function.prototype.toString.call(value));
+        return DevtoolsJson.#mark(isClass ? "class" : "function", (value as () => unknown).name || undefined);
+      }
       default:
         return undefined;
     }
   }
 
-  static #coerceFunction(value: (...args: never[]) => unknown): Unserializable {
-    const isClass = /^\s*class\s/.test(Function.prototype.toString.call(value));
-    return DevtoolsJson.#mark(isClass ? "class" : "function", value.name || undefined);
-  }
-
   static #coerceObject(value: object, depthLeft: number, seen: WeakSet<object>): unknown {
     if (dayjs.isDayjs(value)) return value.toISOString();
     if (value instanceof Date) return value.toISOString();

package/server/devtools/devtoolsRouter.ts

@@ -19,21 +19,12 @@ export interface DevtoolsRouterContext {
   getStatus: () => string;
 }
 
-/**
- * Local-dev-only JSON endpoints that describe the running system for developer tools.
- *
- * These are registered as builtin routes rather than as signal endpoints so they stay off the `/api` prefix,
- * skip guards and the middleware chain, and — most importantly — never enter the `serializedSignal` payload
- * that ships to every client bundle in production.
- */
+/** Builtin routes, not signals: off `/api` and guards, and never in the `serializedSignal` payload sent to clients. */
 export class DevtoolsRouter {
   static readonly basePath = "/_akan";
   static readonly logger = new Logger("DevtoolsRouter");
 
-  /**
-   * `AKAN_DEVTOOLS` is an explicit override for debugging a deployed environment; otherwise the endpoints
-   * exist only under `AKAN_PUBLIC_ENV=local`. Shape mirrors `AkanServer.#isOpenApiEnvEnabled`.
-   */
+  /** Local-only unless `AKAN_DEVTOOLS` ("true"/"1", "false"/"0") overrides it, e.g. to debug a deployed env. */
   static isEnabled(env: BaseEnv): boolean {
     const override = process.env.AKAN_DEVTOOLS;
     if (override === "false" || override === "0") return false;
@@ -126,7 +117,6 @@ export class DevtoolsRouter {
     };
   }
 
-  /** `?lang=en` narrows the tree to one language — full dictionaries get large fast. */
   static #dictionary(req: Request): DictionaryData {
     const lang = new URL(req.url).searchParams.get("lang");
     const root = DictionaryRegistry.getRoot();

package/server/devtools/signalSerializer.ts

@@ -24,6 +24,7 @@ import { FetchSerializer } from "../../signal/serializer";
 import type { DatabaseModule, ServiceModule } from "../akanLib";
 import type { DiLifecycle } from "../di/diLifecycle";
 import { SignalResolver } from "../resolver";
+import { ApiRouter } from "../routing/apiRouter";
 import type { EndpointNode, InternalNode, RouteRow, SignalData, SignalNode, SliceNode } from "./types";
 
 export interface SignalSerializerContext {
@@ -33,15 +34,7 @@ export interface SignalSerializerContext {
   websocketPrefix: string;
 }
 
-/**
- * Builds the `/_akan/signal` payload from the live DI container.
- *
- * The client-side `getSerializedSignal()` is deliberately *not* used here: its map is seeded with the `base`
- * signal and only completed at build time via `applySignal`, so on a server process it under-reports the API.
- * Declared endpoints come from `FetchSerializer.serializeRegistry(di.live)` (what `/openapi.json` uses), the
- * framework-generated CRUD/slice endpoints come from the slice endpoint class the resolver synthesized, and
- * internals — absent from `SerializedSignal` entirely — are read straight off `INTERNAL_META`.
- */
+/** Built from the live DI container: on a server, `getSerializedSignal()` holds only the `base` signal. */
 export class SignalSerializer {
   static serialize({ di, serverMode, prefix, websocketPrefix }: SignalSerializerContext): SignalData {
     const serializedSignals = FetchSerializer.serializeRegistry(di.live).signal;
@@ -124,11 +117,6 @@ export class SignalSerializer {
     };
   }
 
-  /**
-   * `FetchSerializer` never populates `prefix`/`globalPrefix` (they are server-routing concerns), so a
-   * `{ globalPrefix: false }` endpoint is unreconstructable from the client payload alone. Read them off
-   * `ENDPOINT_META` instead of widening what ships to every client bundle.
-   */
   static #augmentAll(
     endpoints: Record<string, SerializedEndpoint>,
     endpointCls: EndpointCls,
@@ -157,7 +145,6 @@ export class SignalSerializer {
     return Object.fromEntries(Object.entries(endpoints).filter(([key]) => predicate(key)));
   }
 
-  /** The list/insight pair the resolver synthesizes per slice key — everything else on that class is CRUD. */
   static #sliceDerivedKeys(refName: string, sliceCls: SliceCls | undefined): Set<string> {
     const sliceMeta = (sliceCls?.[SLICE_META] ?? {}) as Record<string, SliceInfo>;
     return new Set(
@@ -215,7 +202,7 @@ export class SignalSerializer {
           method: node.type === "mutation" ? (info.signalOption.method ?? "POST") : transport === "http" ? "GET" : null,
           path:
             transport === "ws"
-              ? SignalSerializer.#joinPath(prefix, websocketPrefix)
+              ? ApiRouter.joinRoutePath(prefix, websocketPrefix)
               : SignalSerializer.#httpPath(key, info, defaultPrefix, prefix),
           guards: node.guards ?? [],
           ...(node.cache !== undefined ? { cache: node.cache } : {}),
@@ -226,34 +213,9 @@ export class SignalSerializer {
     });
   }
 
-  /** Mirrors `SignalResolver.resolveEndpoint` + `ApiRouter.applyGlobalPrefix` so paths match the real route table. */
   static #httpPath(key: string, info: EndpointInfo, defaultPrefix: string | undefined, apiPrefix: string): string {
-    const servicePrefix = SignalSerializer.#resolveServicePrefix(info.signalOption.prefix, defaultPrefix);
-    const localPath = `${servicePrefix}${info.getPath(key)}`;
-    if (info.signalOption.globalPrefix === false) return SignalSerializer.#normalizePath(localPath);
-    return SignalSerializer.#joinPath(apiPrefix, localPath);
-  }
-
-  static #resolveServicePrefix(prefix: false | string | undefined, defaultPrefix?: string): string {
-    if (prefix === false || prefix === "") return "";
-    const resolved = prefix ?? defaultPrefix;
-    if (!resolved) return "";
-    const trimmed = resolved.trim().replace(/^\/+|\/+$/g, "");
-    return trimmed ? `/${trimmed}` : "";
-  }
-
-  static #joinPath(prefix: string, path: string): string {
-    const normalizedPrefix = SignalSerializer.#normalizePath(prefix).replace(/\/$/, "");
-    const normalizedPath = SignalSerializer.#normalizePath(path);
-    if (normalizedPrefix === "/") return normalizedPath;
-    if (normalizedPath === "/") return normalizedPrefix;
-    return `${normalizedPrefix}${normalizedPath}`;
-  }
-
-  static #normalizePath(path: string): string {
-    const trimmed = path.trim();
-    if (!trimmed || trimmed === "/") return "/";
-    return `/${trimmed.replace(/^\/+|\/+$/g, "")}`;
+    const servicePrefix = SignalResolver.resolveServicePrefix(info.signalOption.prefix, defaultPrefix);
+    return ApiRouter.applyGlobalPrefix(apiPrefix, `${servicePrefix}${info.getPath(key)}`, info.signalOption);
   }
 
   static #serializeInternals(
@@ -270,7 +232,6 @@ export class SignalSerializer {
 
   static #serializeInternal(key: string, info: InternalInfo, serverMode: "federation" | "batch" | "all"): InternalNode {
     const option = info.signalOption;
-
     const schedulable = info.type !== "resolveField";
     const skip = schedulable ? SignalResolver.getScheduleSkipReason(info, serverMode) : null;
     return {

package/server/devtools/types.ts

@@ -1,13 +1,3 @@
-/**
- * Payload contracts for the local-dev metadata endpoints consumed by developer tools.
- *
- *   GET /_akan/devtools    -> DevtoolsIndex
- *   GET /_akan/constant    -> DevtoolsEnvelope<"constant",   ConstantData>
- *   GET /_akan/signal      -> DevtoolsEnvelope<"signal",     SignalData>
- *   GET /_akan/dictionary  -> DevtoolsEnvelope<"dictionary", DictionaryData>
- *   GET /_akan/deps        -> DevtoolsEnvelope<"deps",       DepsData>
- */
-
 import type { ConstantType, TextFieldRole } from "akanjs/constant";
 import type { RootDictionary } from "akanjs/dictionary";
 import type { ArgType, HttpMutationMethod, SerializedArg, SerializedReturns } from "akanjs/signal";
@@ -37,7 +27,6 @@ export interface DevtoolsEnvelope<Kind extends string, Data> {
   data: Data;
 }
 
-/** Emitted in place of anything JSON cannot represent. */
 export interface Unserializable {
   __akan: "unserializable";
   type: "function" | "class" | "symbol" | "bigint" | "circular" | "depth-limit";
@@ -179,7 +168,6 @@ export interface SignalNode {
   guards: { get?: string[]; cru?: string[]; create?: string[]; update?: string[]; remove?: string[] };
   internal: Record<string, InternalNode>;
   slice: Record<string, SliceNode>;
-  /** Endpoints declared in `.signal.ts`. */
   endpoint: Record<string, EndpointNode>;
   /** Framework-synthesized endpoints — absent from `SerializedSignal.endpoint`. */
   generated: {