@mionjs/router 0.8.6 → 0.8.8

package/src/lib/aotEmitter.ts

@@ -0,0 +1,140 @@
+/* ########
+ * 2025 mion
+ * Author: Ma-jerez
+ * License: MIT
+ * The software is provided "as is", without warranty of any kind.
+ * ######## */
+
+import {
+    getJitFnCaches,
+    getENV,
+    isMionAOTEmitMode,
+    JitFunctionsCache,
+    PureFunctionsCache,
+    MethodsCache,
+    SrcCodeJITCompiledFnsCache,
+    SrcCodePureFunctionsCache,
+    ClientSrcCodeJITCompiledFnsCache,
+    ClientSrcCodePureFunctionsCache,
+    JIT_FUNCTION_IDS,
+} from '@mionjs/core';
+import {getPersistedMethods} from './methodsCache.ts';
+import {createToJavascriptFn} from '@mionjs/run-types';
+
+/** IPC message type for AOT cache emission */
+export interface AOTCacheMessage {
+    type: 'mion-aot-caches';
+    jitFnsCode: string;
+    pureFnsCode: string;
+    routerCacheCode: string;
+}
+
+/** IPC message sent by setPlatformConfig() to signal server readiness */
+export interface PlatformReadyMessage {
+    type: 'mion-platform-ready';
+    routerConfig: Record<string, unknown>;
+    platformConfig: Record<string, unknown>;
+}
+
+/** Serialized cache data before converting to JS code */
+export interface SerializedCaches {
+    jitFnsCode: string;
+    pureFnsCode: string;
+    routerCacheCode: string;
+}
+
+/** JIT function IDs to exclude from AOT caches (toJSCode is only needed at compile time) */
+const EXCLUDED_JIT_FN_IDS = [JIT_FUNCTION_IDS.toJSCode];
+
+/** Pure function names to exclude from AOT caches */
+const EXCLUDED_PURE_FN_NAMES = ['sanitizeCompiledFn'];
+
+/** Returns serialized caches for in-process AOT generation (no IPC needed). Call after initMionRouter(). */
+export async function getSerializedCaches(): Promise<SerializedCaches> {
+    const {jitFnsCache, pureFnsCache} = getJitFnCaches();
+    const routerCache = getPersistedMethods();
+    return serializeCachesToCode(jitFnsCache, pureFnsCache, routerCache);
+}
+
+/**
+ * Emits AOT caches to the parent process via IPC when running in MION_COMPILE mode.
+ * This function is called automatically at the end of initMionRouter() and can also
+ * be called manually for multi-step route registration patterns.
+ */
+export async function emitAOTCaches(): Promise<void> {
+    // Only emit in AOT generation mode (compile, SSR, or serve)
+    if (!isMionAOTEmitMode()) return;
+    // middleware mode: caches remain in global state, read directly via getSerializedCaches()
+    if (getENV('MION_COMPILE') === 'middleware') return;
+
+    // IPC mode: send to parent process
+    if (typeof process.send !== 'function') return;
+
+    // Get the caches
+    const {jitFnsCache, pureFnsCache} = getJitFnCaches();
+    const routerCache = getPersistedMethods();
+
+    // Serialize caches to JS code (filtering happens inside, after createToJavascriptFn)
+    const serialized = await serializeCachesToCode(jitFnsCache, pureFnsCache, routerCache);
+
+    // Send to parent process
+    const message: AOTCacheMessage = {
+        type: 'mion-aot-caches',
+        ...serialized,
+    };
+
+    process.send(message);
+}
+
+/**
+ * Serializes the caches to JavaScript code strings using run-types toJSCode.
+ * Filtering is done AFTER createToJavascriptFn because it adds compile-time-only JIT functions
+ * to the global caches that should be excluded from the serialized output.
+ */
+export async function serializeCachesToCode(
+    jitFnsCache: JitFunctionsCache,
+    pureFnsCache: PureFunctionsCache,
+    routerCache: MethodsCache
+): Promise<SerializedCaches> {
+    const isClient = getENV('MION_AOT_IS_CLIENT') === 'true';
+    const jitToJSCode = isClient
+        ? createToJavascriptFn<ClientSrcCodeJITCompiledFnsCache>()
+        : createToJavascriptFn<SrcCodeJITCompiledFnsCache>();
+    const pureToJSCode = isClient
+        ? createToJavascriptFn<ClientSrcCodePureFunctionsCache>()
+        : createToJavascriptFn<SrcCodePureFunctionsCache>();
+    const routerToJSCode = createToJavascriptFn<MethodsCache>();
+    // Filter AFTER createToJavascriptFn to exclude compile-time-only items (including those just added)
+    const finalJitFns = filterExcludedJitFns(jitFnsCache, EXCLUDED_JIT_FN_IDS);
+    const finalPureFns = filterExcludedPureFns(pureFnsCache, EXCLUDED_PURE_FN_NAMES);
+    return {
+        jitFnsCode: jitToJSCode(finalJitFns as unknown as SrcCodeJITCompiledFnsCache),
+        pureFnsCode: pureToJSCode(finalPureFns as unknown as SrcCodePureFunctionsCache),
+        routerCacheCode: routerToJSCode(routerCache),
+    };
+}
+
+/**
+ * Filters out excluded JIT functions by their function ID.
+ * toJSCode is excluded because it's only needed at compile time.
+ */
+function filterExcludedJitFns(jitFnsCache: JitFunctionsCache, excludedFnIds: string[]): JitFunctionsCache {
+    if (!excludedFnIds.length) return jitFnsCache;
+    return Object.fromEntries(
+        Object.entries(jitFnsCache).filter(([, value]) => !excludedFnIds.includes(value.fnID as string))
+    ) as JitFunctionsCache;
+}
+
+/**
+ * Filters out excluded pure functions by their function name.
+ * sanitizeCompiledFn is excluded because it's only needed at compile time.
+ */
+function filterExcludedPureFns(pureFnsCache: PureFunctionsCache, excludedFnNames: string[]): PureFunctionsCache {
+    if (!excludedFnNames.length) return pureFnsCache;
+    return Object.fromEntries(
+        Object.entries(pureFnsCache).map(([namespace, nsCache]) => [
+            namespace,
+            Object.fromEntries(Object.entries(nsCache).filter(([, value]) => !excludedFnNames.includes(value.fnName))),
+        ])
+    ) as PureFunctionsCache;
+}

package/src/lib/dispatchError.ts

@@ -0,0 +1,60 @@
+import {RpcError, MION_ROUTES, Mutable, StatusCodes, SerializerModes} from '@mionjs/core';
+import type {CallContext, MionHeaders, MionRequest, MionResponse, ResponseBody} from '../types/context.ts';
+import type {RemoteMethod} from '../types/remoteMethods.ts';
+
+/**
+ * Return a Response mion response for any error that happens before or outside the router.
+ * to be used by any adapter layer. ie: node/http, aws/lambda, bun, etc.
+ * Uses thrownErrors with a special platformError key to maintain consistency with route errors.
+ * @param returnErr
+ * @param respHeaders
+ * @returns
+ */
+
+export function getRouterFatalErrorResponse(returnErr: RpcError<string>, respHeaders: MionHeaders): MionResponse {
+    // Store platform error in thrownErrors with special platformError key
+    const body: ResponseBody = {
+        '@thrownErrors': {[MION_ROUTES.platformError]: returnErr},
+    };
+    respHeaders.set('content-type', 'application/json; charset=utf-8');
+    const response: Mutable<MionResponse> = {
+        statusCode: returnErr.statusCode || StatusCodes.SERVER_ERROR, // Global errors are always unexpected
+        hasErrors: true,
+        headers: respHeaders,
+        body,
+        rawBody: JSON.stringify(body),
+        serializer: SerializerModes.json, // global errors are always json
+    };
+    return response;
+}
+
+/**
+ * Handles errors during route dispatch.
+ * All errors passed to this function are unexpected (thrown errors).
+ * Expected errors are returned from handlers and added directly to response.body.
+ * @param context
+ * @param executable
+ * @param err
+ * @returns
+ */
+export function onExecutableError(context: CallContext, executable: RemoteMethod, err: any | RpcError<string> | Error) {
+    const response = context.response as Mutable<MionResponse>;
+    const path = executable.id;
+    const rpcError: RpcError<string> =
+        err instanceof RpcError
+            ? err
+            : new RpcError({
+                  statusCode: StatusCodes.UNEXPECTED_ERROR,
+                  publicMessage: `Unknown error in handler "${path}" of route ExecutionChain.`,
+                  originalError: err,
+                  type: 'unknown-error',
+              });
+    // only first error sets the error header
+    if (!response.hasErrors) response.headers.set('x-rpc-error', rpcError.type);
+    response.statusCode = rpcError.statusCode ?? StatusCodes.UNEXPECTED_ERROR;
+    response.hasErrors = true;
+    // Store unexpected errors for serialization
+    const thrownErrors = context.request.thrownErrors || ({} as Record<string, RpcError<string>>);
+    thrownErrors[path] = rpcError;
+    (context.request as Mutable<MionRequest>).thrownErrors = thrownErrors;
+}

package/src/lib/handlers.ts

@@ -0,0 +1,75 @@
+/* ########
+ * 2024 mion
+ * Author: Ma-jerez
+ * License: MIT
+ * The software is provided "as is", without warranty of any kind.
+ * ######## */
+
+import {HeadersMiddleFnOptions, MiddleFnOptions, RawMiddleFnOptions, RouteOptions} from '../types/remoteMethods.ts';
+import {HandlerType} from '@mionjs/core';
+import {Handler, HeaderHandler, RawMiddleFnHandler} from '../types/handlers.ts';
+import {HeadersMiddleFnDef, MiddleFnDef, RawMiddleFnDef, RouteDef} from '../types/definitions.ts';
+
+// ############# Route & MiddleFns initialization #############
+// these functions are just helpers to initialize the route & middleFns objects and keep route definitions clean
+
+export function route<H extends Handler>(handler: H, opts?: RouteOptions): RouteDef<H> {
+    return {
+        type: HandlerType.route,
+        handler,
+        options: opts,
+    };
+}
+
+/** Route handler for read-only queries. Uses GET with ?data=base64url on the client when payload fits. */
+export function query<H extends Handler>(handler: H, opts?: RouteOptions): RouteDef<H> {
+    return {
+        type: HandlerType.route,
+        handler,
+        options: {...opts, isMutation: false},
+    };
+}
+
+/** Route handler for mutations. Explicit alias for route() with isMutation: true. */
+export function mutation<H extends Handler>(handler: H, opts?: RouteOptions): RouteDef<H> {
+    return {
+        type: HandlerType.route,
+        handler,
+        options: {...opts, isMutation: true},
+    };
+}
+
+export function middleFn<H extends Handler>(handler: H, opts?: MiddleFnOptions): MiddleFnDef<H> {
+    return {
+        type: HandlerType.middleFn,
+        handler,
+        options: opts,
+    };
+}
+
+/**
+ * MiddleFn for handling HTTP header parameters
+ * Used to define middleFns that receive values from HTTP headers
+ *
+ * @example
+ * ```ts
+ * headersFn(['authorization'], (ctx, token: string): void => {
+ *   // token contains the value of the 'authorization' header
+ * })
+ * ```
+ */
+export function headersFn<H extends HeaderHandler>(handler: H, opts?: HeadersMiddleFnOptions): HeadersMiddleFnDef<H> {
+    return {
+        type: HandlerType.headersMiddleFn,
+        handler,
+        options: opts,
+    };
+}
+
+export function rawMiddleFn<H extends RawMiddleFnHandler>(handler: H, opts?: RawMiddleFnOptions): RawMiddleFnDef<H> {
+    return {
+        type: HandlerType.rawMiddleFn,
+        handler,
+        options: opts,
+    };
+}

package/src/lib/headers.ts

@@ -0,0 +1,102 @@
+/* ########
+ * 2022 mion
+ * Author: Ma-jerez
+ * License: MIT
+ * The software is provided "as is", without warranty of any kind.
+ * ######## */
+
+import type {MionHeaders} from '../types/context.ts';
+
+// ############# PUBLIC METHODS #############
+
+type HeadersRecord = Record<string, string>;
+
+/**
+ * Reusable class for managing HTTP headers with case-insensitive access
+ * Similar to the fetch Headers API but optimized for performance
+ * https://developer.mozilla.org/en-US/docs/Web/API/Headers
+ */
+class MionHeadersImpl implements MionHeaders {
+    constructor(private headers: HeadersRecord) {}
+
+    append(name: string, value: string): void {
+        const nl = name.toLowerCase();
+        const existing = this.headers[nl];
+        const headerValue = toSingleHeader(value);
+        if (existing) {
+            this.headers[nl] = `${existing}, ${headerValue}`;
+        } else {
+            this.headers[nl] = headerValue;
+        }
+    }
+
+    delete(name: string): void {
+        const nl = name.toLowerCase();
+        delete this.headers[nl];
+    }
+
+    get(name: string): string | undefined | null {
+        const nl = name.toLowerCase();
+        return this.headers[nl];
+    }
+
+    set(name: string, value: string): void {
+        const ln = name.toLowerCase();
+        this.headers[ln] = value as string;
+    }
+
+    has(name: string): boolean {
+        const nl = name.toLowerCase();
+        return !!this.headers[nl];
+    }
+
+    entries(): IterableIterator<[string, string]> {
+        return new Map(Object.entries(this.headers)).entries();
+    }
+
+    keys(): IterableIterator<string> {
+        return new Map(Object.entries(this.headers)).keys();
+    }
+
+    values(): IterableIterator<string> {
+        return new Map(Object.entries(this.headers)).values();
+    }
+}
+
+/**
+ * Return a Headers Like object from a Headers Record structure (Record<string, string | string[]>)
+ * Returned Headers object is similar to the fetch Headers object but not exactly the same
+ * https://developer.mozilla.org/en-US/docs/Web/API/Headers
+ *
+ * This is optimized to avoid creating the Headers Map if it's not strictly needed.
+ * ie. for incoming header that only use get method, the Headers object is never created and instead the HeadersRecord is used directly.
+ *
+ * This function can be used to create a Headers object from incoming request that has the headers in an object structure.
+ * ie IncomingMessage.headers or ApiGatewayEvent.headers
+ *
+ * @param headersObj
+ * @returns
+ */
+export function headersFromRecord(headersObj: Record<string, string>, skipToLower = false): MionHeaders {
+    // lazy load headers map
+    const headers = parseHeaders(headersObj, skipToLower);
+    return new MionHeadersImpl(headers);
+}
+
+function toSingleHeader(value: string | number): string {
+    if (Array.isArray(value)) return value.join(', ');
+    return value as string;
+}
+
+function parseHeaders(headersObj: Record<string, string>, skipToLower = false): HeadersRecord {
+    if (skipToLower) return headersObj;
+    const entries = Object.entries(headersObj);
+    const headers: HeadersRecord = {};
+    for (let i = 0; i < entries.length; i++) {
+        const [name, value] = entries[i];
+        if (!value) continue;
+        const ln = name.toLowerCase();
+        headers[ln] = toSingleHeader(value);
+    }
+    return headers;
+}

package/src/lib/methodsCache.ts

@@ -0,0 +1,72 @@
+/* ########
+ * 2024 mion
+ * Author: Ma-jerez
+ * License: MIT
+ * The software is provided "as is", without warranty of any kind.
+ * ######## */
+
+import {MethodsCache, MethodMetadata, isMionAOTEmitMode, getJitFunctionsFromHash} from '@mionjs/core';
+import {RemoteMethod} from '../types/remoteMethods.ts';
+import {AnyHandler} from '../types/handlers.ts';
+import {IS_TEST_ENV} from '../constants.ts';
+
+export let persistedMethods: MethodsCache = {};
+
+// ############# PUBLIC METHODS #############
+
+export function addToPersistedMethods(id: string, method: RemoteMethod) {
+    if (!shouldCompile() || !!persistedMethods[id]) return;
+    persistedMethods[id] = method;
+}
+
+export function getPersistedMethod(id: string, handler: AnyHandler): RemoteMethod | undefined {
+    const method = persistedMethods?.[id];
+    if (!method) return;
+    return restorePersistedMethod(method, handler);
+}
+
+/** Gets method metadata from the persisted methods cache by id. */
+export function getPersistedMethodMetadata(id: string): MethodMetadata | undefined {
+    const method = persistedMethods[id];
+    return method;
+}
+
+export function getPersistedMethods(): Readonly<MethodsCache> {
+    return persistedMethods;
+}
+
+export function setPersistedMethods(newCompiled: MethodsCache) {
+    persistedMethods = newCompiled;
+}
+
+export function resetPersistedMethods() {
+    persistedMethods = {};
+}
+
+function restorePersistedMethod(method: MethodMetadata, handler: AnyHandler): RemoteMethod {
+    const restored = method as any as RemoteMethod;
+    if (restored.paramsJitFns && restored.returnJitFns && restored.paramNames && !!restored.handler)
+        return method as RemoteMethod;
+    restored.handler = handler;
+    restored.paramsJitFns = getJitFunctionsFromHash(method.paramsJitHash);
+    restored.returnJitFns = getJitFunctionsFromHash(method.returnJitHash);
+    if (IS_TEST_ENV) (restored as any).isRestored = true;
+    return restored;
+}
+
+function shouldCompile() {
+    return isMionAOTEmitMode();
+}
+
+/**
+ * Loads compiled methods data into the persistedMethods cache.
+ * This function merges the provided methods data into the existing persistedMethods without overwriting existing entries.
+ * @param compiledMethods - Object containing compiled methods data to merge into the cache
+ */
+export function loadCompiledMethods(compiledMethods: MethodsCache) {
+    for (const [key, value] of Object.entries(compiledMethods)) {
+        if (!(key in persistedMethods)) {
+            persistedMethods[key] = value;
+        }
+    }
+}

package/src/lib/queryBody.ts

@@ -0,0 +1,40 @@
+/* ########
+ * 2025 mion
+ * Author: Ma-jerez
+ * License: MIT
+ * The software is provided "as is", without warranty of any kind.
+ * ######## */
+
+import {fromBase64Url, SerializerModes} from '@mionjs/core';
+import type {SerializerCode} from '@mionjs/core';
+
+/** Result of decoding a base64url query body from ?data= */
+export interface QueryBodyResult {
+    rawBody: string;
+    bodyType: SerializerCode;
+}
+
+/** Detects and decodes base64url-encoded request body from ?data= query param.
+ * Returns decoded body + bodyType if found, undefined otherwise. */
+export function decodeQueryBody(urlQuery: string | undefined, rawBody: unknown): QueryBodyResult | undefined {
+    if (rawBody) return undefined;
+    if (!urlQuery) return undefined;
+    const dataValue = extractDataParam(urlQuery);
+    if (!dataValue) return undefined;
+    return {
+        rawBody: fromBase64Url(dataValue),
+        bodyType: SerializerModes.stringifyJson,
+    };
+}
+
+function extractDataParam(urlQuery: string): string | undefined {
+    if (urlQuery.startsWith('data=')) {
+        const ampIndex = urlQuery.indexOf('&', 5);
+        return ampIndex === -1 ? urlQuery.slice(5) : urlQuery.slice(5, ampIndex);
+    }
+    const idx = urlQuery.indexOf('&data=');
+    if (idx === -1) return undefined;
+    const start = idx + 6;
+    const ampIndex = urlQuery.indexOf('&', start);
+    return ampIndex === -1 ? urlQuery.slice(start) : urlQuery.slice(start, ampIndex);
+}