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

package/common/routeConvention.ts

@@ -13,9 +13,7 @@ export const PAGE_ROUTE_EXPORTS: ReadonlySet<string> = new Set([
   "default",
   "pageConfig",
   "head",
-  "metadata",
   "generateHead",
-  "generateMetadata",
   "Loading",
 ]);
 export const LAYOUT_ROUTE_EXPORTS: ReadonlySet<string> = new Set([...PAGE_ROUTE_EXPORTS, "NotFound", "Error"]);
@@ -27,7 +25,6 @@ export const ROOT_LAYOUT_ROUTE_EXPORTS: ReadonlySet<string> = new Set([
   "reconnect",
   "wsConnect",
   "layoutStyle",
-  "gaTrackingId",
 ]);
 /** Root-layout exports that are plain config rather than components, so a PascalCase check cannot allow them. */
 export const RESERVED_ROUTE_CONFIG_EXPORTS: ReadonlySet<string> = new Set(
@@ -61,22 +58,19 @@ export interface ValidatePageSourceFileOptions {
   filePath?: string;
 }
 
+const toRouteKey = (filePath: string) =>
+  filePath.startsWith("./") ? filePath : `./${filePath.split(/[\\/]/).join("/")}`;
+
 export function isRouteSourceFile(filePath: string): boolean {
   if (!SOURCE_EXT_RE.test(filePath)) return false;
-  const key = filePath.startsWith("./") ? filePath : `./${filePath.split(/[\\/]/).join("/")}`;
-  return tryParseRouteModuleKey(key) !== null;
+  return tryParseRouteModuleKey(toRouteKey(filePath)) !== null;
 }
 
-/**
- * Why a `page/` file breaks the route convention, or null when it is fine. Null also covers a non-source
- * asset, which `page/` tolerates. `akan sync <lib>` reports these alongside its other layout violations,
- * so the rule stays in one place instead of being restated where it cannot afford to throw.
- */
+/** `null` when the file is fine, including a non-source asset, which `page/` tolerates. */
 export function getPageSourceFileViolation(filePath: string): string | null {
   if (!SOURCE_EXT_RE.test(filePath)) return null;
 
-  const key = filePath.startsWith("./") ? filePath : `./${filePath.split(/[\\/]/).join("/")}`;
-  const match = ROUTE_SOURCE_RE.exec(key);
+  const match = ROUTE_SOURCE_RE.exec(toRouteKey(filePath));
   if (!match) return "invalid page source file";
 
   const file = match[1] as string;
@@ -96,8 +90,7 @@ export function validatePageSourceFile(filePath: string, options: ValidatePageSo
 
   const violation = getPageSourceFileViolation(filePath);
   if (!violation) return true;
-  const key = filePath.startsWith("./") ? filePath : `./${filePath.split(/[\\/]/).join("/")}`;
-  throw new Error(`[route-convention] ${violation}: ${options.filePath ?? key}`);
+  throw new Error(`[route-convention] ${violation}: ${options.filePath ?? toRouteKey(filePath)}`);
 }
 
 export function validateSubRoutePageKey(
@@ -222,6 +215,20 @@ export function matchRoutePattern(pattern: string, pathname: string): Record<str
   return params;
 }
 
+export function matchRoutePrefix(pattern: string, pathname: string): Record<string, string> | null {
+  const patternParts = pattern.split("/").filter(Boolean);
+  const pathParts = pathname.split("/").filter(Boolean);
+  if (patternParts.length > pathParts.length) return null;
+  const params: Record<string, string> = {};
+  for (let i = 0; i < patternParts.length; i++) {
+    const pat = patternParts[i];
+    const val = pathParts[i];
+    if (pat.startsWith(":")) params[pat.slice(1)] = decodeURIComponent(val);
+    else if (pat !== val) return null;
+  }
+  return params;
+}
+
 export function assertUniqueRoutePatterns(entries: { key: string; pattern: string }[]): void {
   const byPattern = new Map<string, string>();
   for (const entry of entries) {

package/common/sleep.ts

@@ -1,8 +1 @@
-/** Resolves after the requested delay in milliseconds. */
-export const sleep = async (ms: number) => {
-  return new Promise((resolve) => {
-    setTimeout(() => {
-      resolve(true);
-    }, ms);
-  });
-};
+export const sleep = async (ms: number) => new Promise((resolve) => setTimeout(() => resolve(true), ms));

package/common/subRoute.ts

@@ -14,13 +14,11 @@ export const parseBasePaths = (value: string | string[] | Set<string> | undefine
 
 const normalizeSubRouteHost = (host: string): string => host.trim().toLowerCase().replace(/:\d+$/, "");
 
-/** A hostname never contains these; a fragment carrying one is a malformed entry, not a host we failed to match. */
 const isSubRouteHost = (host: string): boolean => host.length > 0 && !/[\s/=]/.test(host);
 
 /**
- * `"soft=a.com,b.com;office=c.com"` -> `{ soft: ["a.com", "b.com"], office: ["c.com"] }`. A deployment platform
- * renders this value, so a malformed entry is skipped rather than thrown: one bad character must not CrashLoop
- * every pod that received it.
+ * `"soft=a.com,b.com;office=c.com"` -> `{ soft: ["a.com", "b.com"], office: ["c.com"] }`. A malformed entry is
+ * skipped, not thrown: a deployment platform renders this value, and one bad character must not CrashLoop pods.
  */
 export const parseSubRouteHosts = (value: string | undefined | null): Record<string, string[]> => {
   const hostsByBasePath: Record<string, string[]> = {};
@@ -44,9 +42,8 @@ export const parseSubRouteHosts = (value: string | undefined | null): Record<str
 };
 
 /**
- * Unions the env mapping onto the one baked into the build artifact, never replacing it — dropping the env is the
- * rollback path. A basePath the build does not serve is reported back instead of honoured: the route tree is a
- * build output, so accepting one would answer every request under it with a 404 and nothing to explain why.
+ * Unions the env mapping onto the build's own, never replacing it (dropping the env is the rollback path). A basePath
+ * the build does not serve is reported back, not honoured: the route tree is a build output.
  */
 export const resolveSubRouteHosts = ({
   subRoutes,

package/common/toError.ts

@@ -0,0 +1 @@
+export const toError = (reason: unknown): Error => (reason instanceof Error ? reason : new Error(String(reason)));

package/common/tunnelWire.ts

@@ -0,0 +1,263 @@
+import { forwardedHeaders } from "./clientAddress";
+
+/** `http` and `tcp` payloads are raw binary frames; a `websocket` one prefixes each with a `tunnelWsPayload` byte. */
+export type TunnelStreamKind = "http" | "websocket" | "tcp";
+
+export type TunnelResetCode =
+  | "originUnreachable"
+  | "originTimeout"
+  | "originRefused"
+  | "protocol"
+  | "canceled"
+  | "tooLarge"
+  | "internal";
+
+/** Pairs, not a record: `set-cookie` repeats, and a record keyed by name keeps only the last one. */
+export type TunnelHeaderList = [string, string][];
+
+export interface TunnelAgentIdentity {
+  /** The operator's name for this share. */
+  name: string;
+  version: string;
+  platform: string;
+}
+
+export interface TunnelHelloFrame {
+  type: "hello";
+  version: number;
+  /** What the agent intends to serve; the gateway answers with what the token grants. */
+  hostnames: string[];
+  agent: TunnelAgentIdentity;
+}
+
+export interface TunnelReadyFrame {
+  type: "ready";
+  version: number;
+  sessionId: string;
+  /** Authoritative: the agent serves these and nothing else, whatever it asked for. */
+  hostnames: string[];
+  urls: string[];
+  /** Idle data sockets to hold; `maxSockets` is the ceiling the pool never grows past. */
+  idle: number;
+  maxSockets: number;
+  heartbeatMs: number;
+  /** Epoch ms, when the control plane put a TTL on this share. */
+  expiresAt?: number;
+}
+
+export interface TunnelPingFrame {
+  type: "ping";
+  at: number;
+}
+
+export interface TunnelPongFrame {
+  type: "pong";
+  at: number;
+}
+
+/** The gateway noticed the idle pool running short; the agent grows it to `idle`, capped by `maxSockets`. */
+export interface TunnelDemandFrame {
+  type: "demand";
+  idle: number;
+}
+
+/** A graceful goodbye from either side, so the peer stops reconnecting instead of treating it as a drop. */
+export interface TunnelByeFrame {
+  type: "bye";
+  reason?: string;
+}
+
+export type TunnelControlFromAgent = TunnelHelloFrame | TunnelPingFrame | TunnelPongFrame | TunnelByeFrame;
+export type TunnelControlFromGateway =
+  | TunnelReadyFrame
+  | TunnelPingFrame
+  | TunnelPongFrame
+  | TunnelDemandFrame
+  | TunnelByeFrame;
+
+/** First frame on a data socket; the session id names the agent connection it belongs to. */
+export interface TunnelAttachFrame {
+  type: "attach";
+  version: number;
+  sessionId: string;
+}
+
+/** The socket joined the idle pool; until this arrives the agent must not count it toward `idle`. */
+export interface TunnelAttachedFrame {
+  type: "attached";
+}
+
+export interface TunnelOpenFrame {
+  type: "open";
+  streamId: string;
+  kind: TunnelStreamKind;
+  /** The tunnel host the public caller addressed. */
+  hostname: string;
+  /** `http` and `websocket`. */
+  method?: string;
+  /** `http` and `websocket`: path plus query, already percent-encoded. */
+  path?: string;
+  /**
+   * `http` and `websocket`, replayed verbatim: the gateway strips every `forwardedHeaderNames` entry the caller sent
+   * (else Host header injection) and writes `x-forwarded-host` as the tunnel hostname (else CSRF refuses mutations).
+   */
+  headers?: TunnelHeaderList;
+  /** `tcp`: the port on the local origin to dial. */
+  port?: number;
+  /** Whether payload frames follow; absent or false means the request is complete as sent. */
+  body?: boolean;
+}
+
+export interface TunnelHeadFrame {
+  type: "head";
+  streamId: string;
+  /** `101` accepts a `websocket` open and `200` a `tcp` one; any other status is the agent declining. */
+  status: number;
+  statusText?: string;
+  headers: TunnelHeaderList;
+  body?: boolean;
+}
+
+/** No more payload in the direction this was sent; each direction ends independently. */
+export interface TunnelEndFrame {
+  type: "end";
+  streamId: string;
+}
+
+/** The stream failed; its socket is closed rather than returned to the pool. */
+export interface TunnelResetFrame {
+  type: "reset";
+  streamId: string;
+  code: TunnelResetCode;
+  message?: string;
+}
+
+/** Gateway → agent once both directions ended: the socket is idle again. Only `http` streams are released. */
+export interface TunnelReleaseFrame {
+  type: "release";
+  streamId: string;
+}
+
+export type TunnelDataFromAgent = TunnelAttachFrame | TunnelHeadFrame | TunnelEndFrame | TunnelResetFrame;
+export type TunnelDataFromGateway =
+  | TunnelAttachedFrame
+  | TunnelOpenFrame
+  | TunnelEndFrame
+  | TunnelResetFrame
+  | TunnelReleaseFrame;
+
+export type TunnelFrame =
+  | TunnelControlFromAgent
+  | TunnelControlFromGateway
+  | TunnelDataFromAgent
+  | TunnelDataFromGateway;
+
+export const tunnelWsPayload = {
+  text: 0,
+  binary: 1,
+  /** Remainder is UTF-8 JSON `{ code, reason }` — the inner close, which is not the tunnel socket closing. */
+  close: 2,
+} as const;
+
+export type TunnelWsPayloadKind = (typeof tunnelWsPayload)[keyof typeof tunnelWsPayload];
+
+/** Stripped by both ends independently, so neither has to trust the other to have done it. */
+export const tunnelHopByHopHeaders = [
+  "connection",
+  "keep-alive",
+  "proxy-authenticate",
+  "proxy-authorization",
+  "proxy-connection",
+  "te",
+  "trailer",
+  "transfer-encoding",
+  "upgrade",
+] as const;
+
+/**
+ * The only way a refusal reaches the agent, which treats these as final and any other close as a drop to retry: a
+ * refused upgrade arrives as a bare `1006`. Accept the upgrade and close on a later tick, never inside `open`.
+ */
+export const tunnelCloseCode = {
+  unauthorized: 4001,
+  unsupportedVersion: 4002,
+  hostnameNotGranted: 4003,
+  unknownSession: 4004,
+  /** A newer session for the same tunnel took over; this one must not reconnect. */
+  superseded: 4005,
+  streamLimit: 4008,
+  goingAway: 4009,
+} as const;
+
+export type TunnelCloseCode = (typeof tunnelCloseCode)[keyof typeof tunnelCloseCode];
+
+/** Includes `forwarded`, RFC 7239's single-header spelling of the same claim. */
+export const tunnelForwardedHeaders = [...forwardedHeaders, "forwarded"] as const;
+
+const hopByHop = new Set<string>(tunnelHopByHopHeaders);
+
+export const tunnelWireContract = {
+  version: 1,
+  controlPath: "/_tunnel/control",
+  dataPath: "/_tunnel/data",
+  
+  authScheme: "Bearer",
+  defaultIdleSockets: 4,
+  defaultMaxSockets: 128,
+  defaultHeartbeatMs: 30_000,
+
+  /** What a sender splits an `http` or `tcp` payload to. */
+  chunkBytes: 64 * 1024,
+  /** Floor of every tunnel socket's `maxPayloadLength`: an inner 16 MB message plus its prefix rides one frame. */
+  maxFrameBytes: 16 * 1024 * 1024 + 4096,
+
+  stripForwarded: (headers: Headers): Headers => {
+    for (const name of tunnelForwardedHeaders) headers.delete(name);
+    return headers;
+  },
+
+  forwardedHeaderNames: tunnelForwardedHeaders,
+
+  isHopByHop: (name: string): boolean => hopByHop.has(name.toLowerCase()),
+
+  headerList: (headers: Headers): TunnelHeaderList => {
+    const list: TunnelHeaderList = [];
+    headers.forEach((value, name) => {
+      if (!hopByHop.has(name.toLowerCase())) list.push([name, value]);
+    });
+    return list;
+  },
+
+  headersOf: (list: TunnelHeaderList): Headers => {
+    const headers = new Headers();
+    for (const [name, value] of list) {
+      if (!hopByHop.has(name.toLowerCase())) headers.append(name, value);
+    }
+    return headers;
+  },
+
+  encodeWsPayload: (kind: TunnelWsPayloadKind, data: Uint8Array): Uint8Array => {
+    const framed = new Uint8Array(data.byteLength + 1);
+    framed[0] = kind;
+    framed.set(data, 1);
+    return framed;
+  },
+
+  decodeWsPayload: (frame: Uint8Array): { kind: TunnelWsPayloadKind; data: Uint8Array } | null => {
+    if (!frame.byteLength) return null;
+    const kind = frame[0] as TunnelWsPayloadKind;
+    if (kind !== tunnelWsPayload.text && kind !== tunnelWsPayload.binary && kind !== tunnelWsPayload.close) return null;
+    return { kind, data: frame.subarray(1) };
+  },
+
+  parseFrame: (raw: string): TunnelFrame | null => {
+    try {
+      const frame = JSON.parse(raw) as TunnelFrame;
+      return frame && typeof frame === "object" && typeof (frame as { type?: unknown }).type === "string"
+        ? frame
+        : null;
+    } catch {
+      return null;
+    }
+  },
+} as const;

package/common/types.ts

@@ -5,13 +5,9 @@ export interface FetchPolicy<Returns = unknown> {
   onError?: (error: string) => void;
   token?: string;
   partial?: string[];
-  timeout?: number;
-  /**
-   * A `pubsub` subscription only: called after the room has been resubscribed following a dropped connection.
-   *
-   * Whatever was published while the socket was down is gone, and a room cannot say which messages those were, so
-   * a subscriber that has to stay correct reloads here instead of carrying on from a gap it cannot see.
-   */
+  /** Milliseconds, or `false` to wait as long as the runtime will; overrides the endpoint's declared `timeout`. */
+  timeout?: number | false;
+  /** `pubsub` only: called after a resubscribe, since whatever was published while the socket was down is gone. */
   onResync?: () => void;
 }
 
@@ -20,3 +16,6 @@ export type SnakeCaseObj<T> = {
   [K in keyof T as SnakeCase<K & string>]: T[K] extends object ? SnakeCaseObj<T[K]> : T[K];
 };
 export type SnakeMsg<Msg> = SnakeCaseObj<Msg>;
+
+/** Name-based dispatch over a generated surface: `as DynamicRecord` to index, then cast the read, never `as any`. */
+export type DynamicRecord<Value = unknown> = { [key: string]: Value };

package/common/{splitVersion.ts → version.ts}

@@ -1,9 +1,6 @@
-/**
- *
- * semantic version 규격에 맞게 major, minor, patch로 나누는 함수
- * https://semver.org/
- * @params version `major.minor.patch` 형식으로 조합된 버전
- */
+
+export const mergeVersion = (major: number, minor: number, patch: number) => `${major}.${minor}.${patch}`;
+
 export const splitVersion = (version: string) => {
   const [major, minor, patch] = version.split(".");
   if (!major || !minor || !patch) throw new Error("Invalid version");

package/common/{websocketBinaryFrame.ts → websocketContract.ts}

@@ -1,3 +1,46 @@
+export interface WebsocketAuthRequest {
+  key: string;
+  data: [string | null];
+}
+
+export interface WebsocketAuthAckData {
+  type: "auth";
+  revokedRooms: string[];
+}
+
+export const websocketAuthContract = {
+  key: "__auth",
+  makeRequest: (jwt: string | null): WebsocketAuthRequest => ({ key: "__auth", data: [jwt] }),
+  makeAck: (revokedRooms: string[]): WebsocketAuthAckData => ({ type: "auth", revokedRooms }),
+  readJwt: (data: unknown): string | null => {
+    const jwt = Array.isArray(data) ? data[0] : null;
+    return typeof jwt === "string" && jwt.length > 0 ? jwt : null;
+  },
+} as const;
+
+export interface WebsocketHeartbeatRequest {
+  key: string;
+  data: [];
+}
+
+export interface WebsocketHeartbeatAckData {
+  type: "pong";
+}
+
+export const websocketHeartbeatContract = {
+  key: "__ping",
+  /** Under the 60s idle timeout nginx and most CDNs ship with. */
+  intervalMs: 45_000,
+  /** Without any inbound frame this long, the socket is assumed half-open and reconnected. */
+  silenceMs: 45_000 * 3,
+  makeRequest: (): WebsocketHeartbeatRequest => ({ key: "__ping", data: [] }),
+  makeAck: (): WebsocketHeartbeatAckData => ({ type: "pong" }),
+} as const;
+
+export const websocketRoomContract = {
+  idOf: (key: string, args: unknown[]) => `${key}${args.length ? "-" : ""}${args.join("-")}`,
+} as const;
+
 export interface WebsocketBinaryFrame {
   roomId: string;
   payload: Uint8Array;
@@ -11,15 +54,6 @@ const MAX_ROOM_BYTES = 0xffff;
 const encoder = new TextEncoder();
 const decoder = new TextDecoder();
 
-/**
- * Framework-owned binary pubsub frame, shared by the publisher and the client dispatcher. A room whose whole
- * return is `Binary` sends its bytes in a websocket binary frame instead of the JSON `{ type: "pub" }` envelope,
- * because `Buffer.toJSON()` turns bytes into `{ type: "Buffer", data: number[] }` — 3.6x the wire and ~300x the
- * encode cost on a 64 KB payload, and a shape `JSON.parse` never restores.
- *
- * Text and binary frames coexist on one socket, so this is additive: every JSON endpoint is untouched, and a
- * federation gateway relays a binary frame unchanged with no code of its own.
- */
 export const websocketBinaryFrameContract = {
   encode: ({ roomId, payload }: WebsocketBinaryFrame): Uint8Array => {
     const room = encoder.encode(roomId);

package/constant/cascadePaths.ts

@@ -3,11 +3,8 @@ import type { ConstantField, FieldObject } from "./fieldInfo";
 import type { ConstantModelRef } from "./via";
 
 /**
- * Which end of a relation goes away with the other. `removeRef` removes what the field points at when this
- * document is removed; `removeWith` removes this document when what the field points at is removed. The two
- * read identically on a relation field, so the value has to name the direction — a mistake here is a data loss.
- * `removeWithAny` is `removeWith` over an owner that is unknowable at build time, and it names the whole
- * decision in one value so the widening cannot be declared apart from the direction it widens.
+ * `removeRef`: removing this document removes what the field points at. `removeWith`: removing what the field points
+ * at removes this document. `removeWithAny`: `removeWith` over an owner unknowable at build time.
  */
 export const cascadeActions = ["removeRef", "removeWith", "removeWithAny"] as const;
 export type CascadeAction = (typeof cascadeActions)[number];
@@ -46,7 +43,7 @@ export class CascadePaths {
   }
 
   #assertKnownAction(key: string, action: CascadeAction) {
-
+    
     if (!cascadeActions.includes(action)) {
       throw new Error(`Cascade field "${key}" declares cascade: "${action}", which is not one of ${cascadeActions}`);
     }
@@ -62,7 +59,7 @@ export class CascadePaths {
   }
 
   #readOwnerPath(key: string, field: ConstantField, fieldMap: FieldObject): CascadeWithPath {
-
+    
     if (field.arrDepth > 0) throw new Error(`Cascade field "${key}" is an array and names more than one owner`);
     if (field.isMap) throw new Error(`Cascade field "${key}" is a Map and names no owner`);
     const anyOwner = field.cascade === "removeWithAny";
@@ -94,7 +91,7 @@ export class CascadePaths {
     const typeField = fieldMap[typeKey];
     if (!typeField) throw new Error(`Cascade field "${key}" declares refPath: "${typeKey}", which is not a field`);
     if (anyOwner) return this.#readAnyOwner(key, typeKey, typeField);
-
+    
     if (!typeField.enum) {
       throw new Error(
         `Cascade field "${key}" declares refPath: "${typeKey}", which must be an enumOf(...) naming the owner ` +
@@ -113,7 +110,7 @@ export class CascadePaths {
           `already names its owners; use cascade: "removeWith"`,
       );
     }
-
+    
     if (this.#primitiveNameOf(typeField) !== "String") {
       throw new Error(
         `Cascade field "${key}" declares cascade: "removeWithAny", so refPath: "${typeKey}" must be a String ` +

package/constant/constantRegistry.ts

@@ -18,7 +18,6 @@ import {
 } from ".";
 import type { ConstantType, DefaultOf, DocumentModel, QueryOf } from "./types";
 
-/** Runtime registry for Akan constant model metadata, refs, enums, and generated model contracts. */
 export class ConstantRegistry {
   static database = new Map<string, ConstantModel>();
   static scalar = new Map<string, ScalarConstantModel>();
@@ -124,38 +123,14 @@ export class ConstantRegistry {
     lightRef: LightRef,
     insightRef: InsightRef,
     constExports: Record<string, unknown>,
-  ): ConstantModel<
-    T,
-    Input,
-    Obj,
-    Full,
-    Light,
-    Insight,
-    FullFieldObj,
-    Capitalize<T>,
-    DefaultOf<Full>,
-    DefaultOf<Input>,
-    GetStateObject<Full>,
-    GetStateObject<Input>,
-    DefaultOf<Insight>,
-    PurifiedModel<Input>,
-    DocumentModel<Full>,
-    DocumentModel<Input>,
-    QueryOf<DocumentModel<Full>>,
-    GetStateObject<Light>,
-    GetStateObject<Insight>
-  > {
+  ) {
     const modelRefSet = new Set([inputRef, objectRef, fullRef, lightRef, insightRef]);
-    modelRefSet.forEach((modelRef) => {
-      ConstantRegistry.modelRefNameMap.set(modelRef, refName);
-    });
+    for (const modelRef of modelRefSet) ConstantRegistry.modelRefNameMap.set(modelRef, refName);
     inputRef.modelType = "input";
     objectRef.modelType = "object";
     fullRef.modelType = "full";
     lightRef.modelType = "light";
     insightRef.modelType = "insight";
-    type Doc = DocumentModel<Full>;
-    type DocInput = DocumentModel<Input>;
     const cnst: ConstantModel<
       T,
       Input,
@@ -171,8 +146,8 @@ export class ConstantRegistry {
       GetStateObject<Input>,
       DefaultOf<Insight>,
       PurifiedModel<Input>,
-      Doc,
-      DocInput,
+      DocumentModel<Full>,
+      DocumentModel<Input>,
       QueryOf<any>,
       GetStateObject<Light>,
       GetStateObject<Insight>
@@ -202,12 +177,7 @@ export class ConstantRegistry {
       _StateInsight: null as unknown as GetStateObject<Insight>,
     };
     ConstantRegistry.setDatabase(refName, cnst as unknown as ConstantModel);
-    Object.entries(constExports).forEach(([key, value]) => {
-      if ((modelRefSet as Set<unknown>).has(value)) return;
-      else if (typeof value === "function" && isEnum(value as Cls))
-        ConstantRegistry.enum.set(lowerlize(key), value as EnumInstance);
-      else ConstantRegistry.value.set(key, value);
-    });
+    ConstantRegistry.#registerExports(constExports, modelRefSet);
     return cnst;
   }
   static buildScalar<T extends string, Model>(
@@ -224,30 +194,26 @@ export class ConstantRegistry {
       _PurifiedInput: null as unknown as PurifiedModel<Model>,
     };
     ConstantRegistry.setScalar(refName, cnst as unknown as ScalarConstantModel);
-    Object.entries(constExports).forEach(([key, value]) => {
-      if (value === Model) return;
-      else if (typeof value === "function" && isEnum(value as Cls))
+    ConstantRegistry.#registerExports(constExports, new Set([Model]));
+    return cnst;
+  }
+  static #registerExports(constExports: Record<string, unknown>, modelRefs: Set<unknown>) {
+    for (const [key, value] of Object.entries(constExports)) {
+      if (modelRefs.has(value)) continue;
+      if (typeof value === "function" && isEnum(value as Cls))
         ConstantRegistry.enum.set(lowerlize(key), value as EnumInstance);
       else ConstantRegistry.value.set(key, value);
-    });
-    return cnst as unknown as ScalarConstantModel<
-      T,
-      Model,
-      DefaultOf<Model>,
-      DocumentModel<Model>,
-      PurifiedModel<Model>
-    >;
+    }
   }
-  static serialize<Value>(modelRef: Cls | Cls[], value: Value, nullable: boolean = false): Value {
+  static serialize<Value>(modelRef: Cls | Cls[], value: Value, nullable: boolean = false, of?: Cls | Cls[]): Value {
     if (Array.isArray(value) && Array.isArray(modelRef)) {
       const singleModelRef = modelRef.at(0);
       if (!singleModelRef) throw new Error("No model ref found");
       return value.map((v: object) => ConstantRegistry.serialize(singleModelRef as Cls, v)) as unknown as Value;
     } else if (modelRef === Map && value instanceof Map) {
+      if (!of) throw new Error("A Map needs its value type (of) to serialize");
       return Object.fromEntries(
-        [...value.entries()].map(([key, value]: [string, unknown]) => {
-          return [key, ConstantRegistry.serialize(value as Cls, value)];
-        }),
+        [...value.entries()].map(([key, entry]: [string, unknown]) => [key, ConstantRegistry.serialize(of, entry)]),
       ) as unknown as Value;
     } else if (PrimitiveRegistry.has(modelRef as Cls)) {
       return (modelRef as typeof PrimitiveScalar)._serialize(value as PrimitiveValue) as unknown as Value;
@@ -255,17 +221,15 @@ export class ConstantRegistry {
       return serialize(modelRef as ConstantCls, 0, value, "object", { nullable }) as unknown as Value;
     } else throw new Error(`No serialize function for modelRef: ${modelRef}`);
   }
-  static deserialize<Value>(modelRef: Cls | Cls[], value: Value, nullable: boolean = false): Value {
+  static deserialize<Value>(modelRef: Cls | Cls[], value: Value, nullable: boolean = false, of?: Cls | Cls[]): Value {
     if (Array.isArray(value) && Array.isArray(modelRef)) {
       const singleModelRef = modelRef.at(0);
       if (!singleModelRef) throw new Error("No model ref found");
       return value.map((v: object) => ConstantRegistry.deserialize(singleModelRef as Cls, v)) as unknown as Value;
-    } else if (modelRef === Map && value instanceof Map) {
-      return new Map(
-        Object.entries(value).map(([key, value]: [string, unknown]) => {
-          return [key, ConstantRegistry.deserialize(value as Cls, value)];
-        }),
-      ) as unknown as Value;
+    } else if (modelRef === Map && value !== null && typeof value === "object") {
+      if (!of) throw new Error("A Map needs its value type (of) to deserialize");
+      const entries: [string, unknown][] = value instanceof Map ? [...value.entries()] : Object.entries(value);
+      return new Map(entries.map(([key, entry]) => [key, ConstantRegistry.deserialize(of, entry)])) as unknown as Value;
     } else if (PrimitiveRegistry.has(modelRef as Cls)) {
       return (modelRef as typeof PrimitiveScalar)._parse(value as PrimitiveValue) as unknown as Value;
     } else if (ConstantRegistry.modelRefNameMap.has(modelRef as Cls)) {