@chidchanun/bcp 0.1.8 → 0.1.10

package/packages/server/src/page-loader.ts

@@ -0,0 +1,643 @@
+import fs from "node:fs";
+import path from "node:path";
+import {
+    pathToFileURL,
+} from "node:url";
+
+import {
+    executePageGuards,
+    type PageGuardData,
+} from "./page-guard.js";
+
+import {
+    headers,
+} from "./request-context.js";
+
+export const LOADER_DATA_PARAM =
+    "__bcp_loader_data";
+export const GUARD_DATA_PARAM =
+    "__bcp_guard_data";
+export const GUARD_DATA_HEADER =
+    "x-bcp-guard-data";
+
+const SERVER_DATA_MARKER =
+    "__bcp_server_data";
+
+export interface PageLoaderContext {
+    params: Record<string, any>;
+    searchParams: URLSearchParams;
+    guardData: Readonly<PageGuardData>;
+}
+
+export type PageLoader = (
+    context: PageLoaderContext
+) =>
+    | unknown
+    | Promise<unknown>;
+
+export interface PageServerDataEnvelope {
+    __bcp_server_data: true;
+    hasPageLoader: boolean;
+    hasGuard: boolean;
+    loaderData: unknown;
+    guardData: PageGuardData;
+}
+
+export interface PageLoaderExecution {
+    /*
+     * hasLoader remains the SSR-provider switch for backward compatibility.
+     * It is true when either loader or guard data must be made available to
+     * React during server rendering.
+     */
+    hasLoader: boolean;
+    hasPageLoader?: boolean;
+    hasGuard?: boolean;
+    data: unknown;
+    loaderData?: unknown;
+    guardData?: PageGuardData;
+    response: Response | null;
+}
+
+export function findPageLoaderFile(
+    pageFilePath: string
+): string | null {
+    const directory =
+        path.dirname(
+            pageFilePath
+        );
+    const tsFile =
+        path.join(
+            directory,
+            "loader.ts"
+        );
+    const tsxFile =
+        path.join(
+            directory,
+            "loader.tsx"
+        );
+    const hasTs =
+        fs.existsSync(
+            tsFile
+        );
+    const hasTsx =
+        fs.existsSync(
+            tsxFile
+        );
+
+    if (hasTs && hasTsx) {
+        throw new Error(
+            `BCP Framework: both loader.ts and loader.tsx exist in "${directory}".`
+        );
+    }
+
+    if (hasTs) {
+        return tsFile;
+    }
+
+    if (hasTsx) {
+        return tsxFile;
+    }
+
+    return null;
+}
+
+export function routeHasPageLoader(
+    pageFilePath: string
+): boolean {
+    return findPageLoaderFile(
+        pageFilePath
+    ) !== null;
+}
+
+export async function executePageLoader(
+    pageFilePath: string,
+    params: Record<string, any>,
+    requestUrl: URL,
+    moduleVersion = 0
+): Promise<PageLoaderExecution> {
+    const appDirectory =
+        findAppDirectory(
+            pageFilePath
+        );
+    const guardExecution =
+        await executePageGuards(
+            appDirectory,
+            pageFilePath,
+            params,
+            requestUrl,
+            moduleVersion
+        );
+
+    if (
+        guardExecution.response
+    ) {
+        return createExecution({
+            hasPageLoader:
+                false,
+            hasGuard:
+                guardExecution.hasGuard,
+            loaderData:
+                undefined,
+            guardData:
+                guardExecution.data,
+            response:
+                guardExecution.response,
+        });
+    }
+
+    const loaderFile =
+        findPageLoaderFile(
+            pageFilePath
+        );
+
+    if (!loaderFile) {
+        return createExecution({
+            hasPageLoader:
+                false,
+            hasGuard:
+                guardExecution.hasGuard,
+            loaderData:
+                undefined,
+            guardData:
+                guardExecution.data,
+            response:
+                null,
+        });
+    }
+
+    const moduleUrl =
+        pathToFileURL(
+            loaderFile
+        );
+
+    moduleUrl.searchParams.set(
+        "bcp-loader",
+        String(
+            moduleVersion
+        )
+    );
+
+    const loaderModule =
+        await import(
+            moduleUrl.href
+        ) as {
+            loader?: unknown;
+        };
+
+    if (
+        typeof loaderModule.loader !==
+        "function"
+    ) {
+        throw new Error(
+            `BCP Framework: loader "${loaderFile}" must export a named loader() function.`
+        );
+    }
+
+    return executePageLoaderFunction(
+        loaderModule.loader as
+            PageLoader,
+        params,
+        requestUrl,
+        loaderFile,
+        guardExecution.data,
+        guardExecution.hasGuard
+    );
+}
+
+export async function executePageLoaderFunction(
+    loader: PageLoader,
+    params: Record<string, any>,
+    requestUrl: URL,
+    label = "loader",
+    explicitGuardData?: PageGuardData,
+    explicitHasGuard?: boolean
+): Promise<PageLoaderExecution> {
+    const headerGuardData =
+        explicitGuardData ===
+            undefined
+            ? await readGuardDataHeader()
+            : null;
+    const guardData =
+        explicitGuardData ??
+        headerGuardData?.data ??
+        {};
+    const hasGuard =
+        explicitHasGuard ??
+        headerGuardData?.hasGuard ??
+        false;
+
+    const result =
+        await loader({
+            params: {
+                ...params,
+            },
+            searchParams:
+                new URLSearchParams(
+                    requestUrl.searchParams
+                ),
+            guardData: {
+                ...guardData,
+            },
+        });
+
+    if (
+        result instanceof
+        Response
+    ) {
+        return createExecution({
+            hasPageLoader:
+                true,
+            hasGuard,
+            loaderData:
+                undefined,
+            guardData,
+            response:
+                result,
+        });
+    }
+
+    assertLoaderData(
+        result,
+        label
+    );
+
+    return createExecution({
+        hasPageLoader:
+            true,
+        hasGuard,
+        loaderData:
+            result,
+        guardData,
+        response:
+            null,
+    });
+}
+
+export function attachLoaderDataToParams(
+    params: Record<string, any>,
+    execution: PageLoaderExecution
+): Record<string, any> {
+    let result = {
+        ...params,
+    };
+    const hasGuard =
+        execution.hasGuard ===
+        true;
+    const guardData =
+        execution.guardData ??
+        {};
+    const hasPageLoader =
+        execution.hasPageLoader ??
+        execution.hasLoader;
+    const loaderData =
+        execution.hasPageLoader ===
+            undefined
+            ? execution.data
+            : execution.loaderData;
+
+    if (hasGuard) {
+        result = {
+            ...result,
+            [GUARD_DATA_PARAM]:
+                guardData,
+        };
+    }
+
+    if (hasPageLoader) {
+        result = {
+            ...result,
+            [LOADER_DATA_PARAM]:
+                loaderData,
+        };
+    }
+
+    return result;
+}
+
+export function isPageServerDataEnvelope(
+    value: unknown
+): value is PageServerDataEnvelope {
+    return (
+        value !== null &&
+        typeof value ===
+            "object" &&
+        (
+            value as
+            Record<string, unknown>
+        )[SERVER_DATA_MARKER] ===
+            true
+    );
+}
+
+function createExecution(
+    input: {
+        hasPageLoader: boolean;
+        hasGuard: boolean;
+        loaderData: unknown;
+        guardData: PageGuardData;
+        response: Response | null;
+    }
+): PageLoaderExecution {
+    const data:
+        PageServerDataEnvelope = {
+        __bcp_server_data:
+            true,
+        hasPageLoader:
+            input.hasPageLoader,
+        hasGuard:
+            input.hasGuard,
+        loaderData:
+            input.loaderData,
+        guardData: {
+            ...input.guardData,
+        },
+    };
+
+    return {
+        hasLoader:
+            input.hasPageLoader ||
+            input.hasGuard,
+        hasPageLoader:
+            input.hasPageLoader,
+        hasGuard:
+            input.hasGuard,
+        data,
+        loaderData:
+            input.loaderData,
+        guardData:
+            data.guardData,
+        response:
+            input.response,
+    };
+}
+
+async function readGuardDataHeader():
+Promise<{
+    hasGuard: true;
+    data: PageGuardData;
+} | null> {
+    let requestHeaders:
+        Headers;
+
+    try {
+        requestHeaders =
+            await headers();
+    } catch {
+        return null;
+    }
+
+    const encoded =
+        requestHeaders.get(
+            GUARD_DATA_HEADER
+        );
+
+    if (!encoded) {
+        return null;
+    }
+
+    let parsed:
+        unknown;
+
+    try {
+        parsed =
+            JSON.parse(
+                Buffer.from(
+                    encoded,
+                    "base64url"
+                ).toString(
+                    "utf8"
+                )
+            );
+    } catch {
+        throw new Error(
+            "BCP Framework: invalid internal guard data header."
+        );
+    }
+
+    assertGuardHeaderData(
+        parsed
+    );
+
+    return {
+        hasGuard:
+            true,
+        data:
+            parsed,
+    };
+}
+
+function assertGuardHeaderData(
+    value: unknown
+): asserts value is PageGuardData {
+    if (
+        value === null ||
+        Array.isArray(
+            value
+        ) ||
+        typeof value !==
+            "object"
+    ) {
+        throw new Error(
+            "BCP Framework: invalid internal guard data header."
+        );
+    }
+
+    const prototype =
+        Object.getPrototypeOf(
+            value
+        );
+
+    if (
+        prototype !==
+            Object.prototype &&
+        prototype !==
+            null
+    ) {
+        throw new Error(
+            "BCP Framework: invalid internal guard data header."
+        );
+    }
+}
+
+function findAppDirectory(
+    pageFilePath: string
+): string {
+    let current =
+        path.dirname(
+            path.resolve(
+                pageFilePath
+            )
+        );
+
+    while (true) {
+        if (
+            path.basename(
+                current
+            ) === "app"
+        ) {
+            return current;
+        }
+
+        const parent =
+            path.dirname(
+                current
+            );
+
+        if (parent === current) {
+            throw new Error(
+                `BCP Framework: could not resolve app directory for page "${pageFilePath}".`
+            );
+        }
+
+        current =
+            parent;
+    }
+}
+
+function assertLoaderData(
+    value: unknown,
+    loaderLabel: string
+): void {
+    const seen =
+        new Set<object>();
+
+    validateJsonValue(
+        value,
+        "$",
+        seen,
+        loaderLabel
+    );
+}
+
+function validateJsonValue(
+    value: unknown,
+    location: string,
+    seen: Set<object>,
+    loaderLabel: string
+): void {
+    if (
+        value === null ||
+        typeof value ===
+            "string" ||
+        typeof value ===
+            "boolean"
+    ) {
+        return;
+    }
+
+    if (
+        typeof value ===
+        "number"
+    ) {
+        if (
+            Number.isFinite(
+                value
+            )
+        ) {
+            return;
+        }
+
+        throwInvalidLoaderData(
+            loaderLabel,
+            location,
+            "numbers must be finite"
+        );
+    }
+
+    if (
+        typeof value !==
+        "object"
+    ) {
+        throwInvalidLoaderData(
+            loaderLabel,
+            location,
+            `unsupported ${typeof value} value`
+        );
+    }
+
+    const objectValue =
+        value as object;
+
+    if (seen.has(objectValue)) {
+        throwInvalidLoaderData(
+            loaderLabel,
+            location,
+            "circular references are not supported"
+        );
+    }
+
+    seen.add(
+        objectValue
+    );
+
+    try {
+        if (Array.isArray(value)) {
+            value.forEach(
+                (
+                    item,
+                    index
+                ) => {
+                    validateJsonValue(
+                        item,
+                        `${location}[${index}]`,
+                        seen,
+                        loaderLabel
+                    );
+                }
+            );
+            return;
+        }
+
+        const prototype =
+            Object.getPrototypeOf(
+                value
+            );
+
+        if (
+            prototype !==
+                Object.prototype &&
+            prototype !==
+                null
+        ) {
+            throwInvalidLoaderData(
+                loaderLabel,
+                location,
+                "only plain objects and arrays are supported"
+            );
+        }
+
+        for (
+            const [
+                key,
+                item,
+            ]
+            of Object.entries(
+                value as Record<
+                    string,
+                    unknown
+                >
+            )
+        ) {
+            validateJsonValue(
+                item,
+                `${location}.${key}`,
+                seen,
+                loaderLabel
+            );
+        }
+    } finally {
+        seen.delete(
+            objectValue
+        );
+    }
+}
+
+function throwInvalidLoaderData(
+    loaderLabel: string,
+    location: string,
+    reason: string
+): never {
+    throw new Error(
+        `BCP Framework: loader "${loaderLabel}" returned non-serializable data at ${location}: ${reason}.`
+    );
+}