types.ts

import { ComponentChildren, ComponentType, VNode } from "preact";
import { Manifest } from "https://deno.land/x/fresh@1.7.3/src/server/mod.ts";
import {
    InnerRenderFunction,
    RenderContext,
} from "https://deno.land/x/fresh@1.7.3/src/server/render.ts";
import * as router from "https://deno.land/x/fresh@1.7.3/src/server/router.ts";

export interface DenoConfig {
    imports?: Record<string, string>;
    importMap?: string;
    tasks?: Record<string, string>;
    lint?: {
        rules: { tags?: string[] };
        exclude?: string[];
    };
    fmt?: {
        exclude?: string[];
    };
    exclude?: string[];
    compilerOptions?: {
        jsx?: string;
        jsxImportSource?: string;
    };
}

// --- APPLICATION CONFIGURATION ---
export interface FreshConfig {
    build?: {
        /**
         * The directory to write generated files to when `dev.ts build` is run.
         * This can be an absolute path, a file URL or a relative path.
         */
        outDir?: string;
        /**
         * This sets the target environment for the generated code. Newer
         * language constructs will be transformed to match the specified
         * support range. See https://esbuild.github.io/api/#target
         * @default {"es2022"}
         */
        target?: string | string[];
    };
    render?: RenderFunction;
    plugins?: Plugin[];
    staticDir?: string;
    router?: RouterOptions;
    server?: Partial<Deno.ServeOptions>;

    // Older versions of Fresh merged the `Deno.ServeTlsOptions` directly.
    // We've moved this to `server`.

    /**
     * Server private key in PEM format
     * @deprecated Use `server.cert` instead
     */
    cert?: string;
    /**
     * Cert chain in PEM format
     * @deprecated Use `server.key` instead
     */
    key?: string;
    /**
     * The port to listen on.
     * @default {8000}
     * @deprecated Use `server.port` instead
     */
    port?: number;
    /**
     * A literal IP address or host name that can be resolved to an IP address.
     *
     * __Note about `0.0.0.0`__ While listening `0.0.0.0` works on all platforms,
     * the browsers on Windows don't work with the address `0.0.0.0`.
     * You should show the message like `server running on localhost:8080` instead of
     * `server running on 0.0.0.0:8080` if your program supports Windows.
     *
     * @default {"0.0.0.0"}
     * @deprecated Use `server.hostname` instead
     */
    hostname?: string;
    /**
     * An {@linkcode AbortSignal} to close the server and all connections.
     * @deprecated Use `server.signal` instead
     */
    signal?: AbortSignal;
    /**
     * Sets `SO_REUSEPORT` on POSIX systems.
     * @deprecated Use `server.reusePort` instead
     */
    reusePort?: boolean;
    /**
     * The handler to invoke when route handlers throw an error.
     * @deprecated Use `server.onError` instead
     */
    onError?: (error: unknown) => Response | Promise<Response>;

    /**
     * The callback which is called when the server starts listening.
     * @deprecated Use `server.onListen` instead
     */
    onListen?: (params: { hostname: string; port: number }) => void;
}

export interface InternalFreshState {
    config: ResolvedFreshConfig;
    manifest: Manifest;
    loadSnapshot: boolean;
    didLoadSnapshot: boolean;
    denoJsonPath: string;
    denoJson: DenoConfig;
    build: boolean;
}

export interface ResolvedFreshConfig {
    dev: boolean;
    build: {
        outDir: string;
        target: string | string[];
    };
    render: RenderFunction;
    plugins: Plugin[];
    staticDir: string;
    router?: RouterOptions;
    server: Partial<Deno.ServeOptions>;
    basePath: string;
}

export interface RouterOptions {
    /**
     *  Controls whether Fresh will append a trailing slash to the URL.
     *  @default {false}
     */
    trailingSlash?: boolean;
    /**
     *  Configures the pattern of files to ignore in islands and routes.
     *
     *  By default Fresh will ignore test files,
     *  for example files with a `.test.ts` or a `_test.ts` suffix.
     *
     *  @default {/(?:[^/]*_|[^/]*\.|)test\.(?:ts|tsx|mts|js|mjs|jsx|)\/*$/}
     */
    ignoreFilePattern?: RegExp;
    /**
     * Serve fresh from a base path instead of from the root.
     *   "/foo/bar" -> http://localhost:8000/foo/bar
     * @default {undefined}
     */
    basePath?: string;
}

export type RenderFunction = (
    ctx: RenderContext,
    render: InnerRenderFunction,
) => void | Promise<void>;

/// --- ROUTES ---

// deno-lint-ignore no-explicit-any
export type PageProps<T = any, S = Record<string, unknown>> = Omit<
    FreshContext<S, T>,
    "render" | "next" | "renderNotFound"
>;

export interface StaticFile {
    /** The URL to the static file on disk. */
    localUrl: URL;
    /** The path to the file as it would be in the incoming request. */
    path: string;
    /** The size of the file. */
    size: number;
    /** The content-type of the file. */
    contentType: string;
    /** Hash of the file contents. */
    etag: string;
}

export interface FreshContext<
    State = Record<string, unknown>,
    // deno-lint-ignore no-explicit-any
    Data = any,
    NotFoundData = Data,
> {
    /** @types deprecated */
    localAddr?: Deno.NetAddr;
    remoteAddr: Deno.NetAddr;
    url: URL;
    basePath: string;
    route: string;
    /** @deprecated Use `.route` instead */
    pattern: string;
    destination: router.DestinationKind;
    params: Record<string, string>;
    isPartial: boolean;
    state: State;
    config: ResolvedFreshConfig;
    data: Data;
    /** The error that caused the error page to be loaded. */
    error?: unknown;
    /** Sringified code frame of the error rendering failed (only in development mode) */
    codeFrame?: unknown;

    // These properties may be different
    renderNotFound: (data?: NotFoundData) => Response | Promise<Response>;
    render: (
        data?: Data,
        options?: RenderOptions,
    ) => Response | Promise<Response>;
    Component: ComponentType<unknown>;
    next: () => Promise<Response>;
}
/**
 * Context passed to async route components.
 */
// deno-lint-ignore no-explicit-any
export type RouteContext<T = any, S = Record<string, unknown>> = Omit<
    FreshContext<S, T>,
    "next" | "render"
>;

export interface RouteConfig {
    /**
     * A route override for the page. This is useful for pages where the route
     * can not be expressed through the filesystem routing capabilities.
     *
     * The route override must be a path-to-regexp compatible route matcher.
     */
    routeOverride?: string;

    /**
     * If Content-Security-Policy should be enabled for this page. If 'true', a
     * locked down policy will be used that allows only the scripts and styles
     * that are generated by Fresh. Additional scripts and styles can be added
     * using the `useCSP` hook.
     */
    csp?: boolean;

    /**
     * Skip already inherited layouts
     * Default: `false`
     */
    skipInheritedLayouts?: boolean;

    /**
     * Skip rendering the `routes/_app` template
     * Default: `false`
     */
    skipAppWrapper?: boolean;
}

export interface RenderOptions extends ResponseInit {}

export type ServeHandlerInfo = Deno.ServeHandlerInfo & {
    /**
     * Backwards compatible with std/server
     * @deprecated
     */
    localAddr?: Deno.NetAddr;

    remoteAddr?: Deno.NetAddr;
};

export type ServeHandler = (
    request: Request,
    info: ServeHandlerInfo,
) => Response | Promise<Response>;

// deno-lint-ignore no-explicit-any
export type Handler<T = any, State = Record<string, unknown>> = (
    req: Request,
    ctx: FreshContext<State, T>,
) => Response | Promise<Response>;

// deno-lint-ignore no-explicit-any
export type Handlers<T = any, State = Record<string, unknown>> = {
    [K in router.KnownMethod]?: Handler<T, State>;
};

export interface RouteModule {
    default?: PageComponent<PageProps>;
    // deno-lint-ignore no-explicit-any
    handler?: Handler<any, any> | Handlers<any, any>;
    config?: RouteConfig;
}

// deno-lint-ignore no-explicit-any
export type AsyncRoute<T = any, S = Record<string, unknown>> = (
    req: Request,
    ctx: FreshContext<S, T>,
) => Promise<ComponentChildren | Response>;
// deno-lint-ignore no-explicit-any
export type PageComponent<T = any, S = Record<string, unknown>> =
    | ComponentType<PageProps<T, S>>
    | AsyncRoute<T, S>
    // deno-lint-ignore no-explicit-any
    | ((props: any) => VNode<any> | ComponentChildren);

// deno-lint-ignore no-explicit-any
export interface Route<Data = any> {
    baseRoute: BaseRoute;
    pattern: string;
    url: string;
    name: string;
    component?: PageComponent<Data> | AsyncLayout<Data> | AsyncRoute<Data>;
    handler: Handler<Data> | Handlers<Data>;
    csp: boolean;
    appWrapper: boolean;
    inheritLayouts: boolean;
}

// --- APP ---
export interface AppModule {
    default: ComponentType<PageProps> | AsyncLayout;
}

// deno-lint-ignore no-explicit-any
export type AsyncLayout<T = any, S = Record<string, unknown>> = (
    req: Request,
    ctx: FreshContext<S, T>,
) => Promise<ComponentChildren | Response>;

export interface LayoutConfig {
    /**
     * Skip already inherited layouts
     * Default: `false`
     */
    skipAppWrapper?: boolean;
    /**
     * Skip rendering the `routes/_app`.
     * Default: `false`
     */
    skipInheritedLayouts?: boolean;
}

export interface LayoutModule {
    // deno-lint-ignore no-explicit-any
    handler?: Handler<any, any> | Handlers<any, any>;
    default: ComponentType<PageProps> | AsyncLayout;
    config?: LayoutConfig;
}

export interface LayoutRoute {
    baseRoute: BaseRoute;
    // deno-lint-ignore no-explicit-any
    handler?: Handler<any, any> | Handlers<any, any>;
    component: LayoutModule["default"];
    appWrapper: boolean;
    inheritLayouts: boolean;
}

// --- UNKNOWN PAGE ---

export type UnknownHandler = (
    req: Request,
    ctx: FreshContext,
) => Response | Promise<Response>;

export interface UnknownPageModule {
    default?: PageComponent<PageProps>;
    handler?: UnknownHandler;
    config?: RouteConfig;
}

export interface UnknownPage {
    baseRoute: BaseRoute;
    pattern: string;
    url: string;
    name: string;
    component?: PageComponent<PageProps>;
    handler: UnknownHandler;
    csp: boolean;
    appWrapper: boolean;
    inheritLayouts: boolean;
}

export type UnknownRenderFunction = (
    req: Request,
    ctx: FreshContext,
) => Promise<Response>;

// --- ERROR PAGE ---

// Nominal/Branded type. Ensures that the string has the expected format
export type BaseRoute = string & { readonly __brand: unique symbol };

export type ErrorHandler = (
    req: Request,
    ctx: FreshContext,
) => Response | Promise<Response>;

export interface ErrorPageModule {
    default?: PageComponent<PageProps>;
    handler?: ErrorHandler;
    config?: RouteConfig;
}

export interface ErrorPage {
    baseRoute: BaseRoute;
    pattern: string;
    url: string;
    name: string;
    component?: PageComponent<PageProps>;
    handler: ErrorHandler;
    csp: boolean;
    appWrapper: boolean;
    inheritLayouts: boolean;
}

// --- MIDDLEWARES ---
export interface MiddlewareRoute {
    baseRoute: BaseRoute;
    module: Middleware;
}

export type MiddlewareHandler<State = Record<string, unknown>> = (
    req: Request,
    ctx: FreshContext<State>,
) => Response | Promise<Response>;

// deno-lint-ignore no-explicit-any
export interface MiddlewareModule<State = any> {
    handler: MiddlewareHandler<State> | MiddlewareHandler<State>[];
}

export interface Middleware<State = Record<string, unknown>> {
    handler: MiddlewareHandler<State> | MiddlewareHandler<State>[];
}

// --- ISLANDS ---

export interface IslandModule {
    // deno-lint-ignore no-explicit-any
    [key: string]: ComponentType<any> | unknown;
}

export interface Island {
    id: string;
    name: string;
    url: string;
    component: ComponentType<unknown>;
    exportName: string;
}

// --- PLUGINS ---

export interface Plugin<State = Record<string, unknown>> {
    /** The name of the plugin. Must be snake-case. */
    name: string;

    /** A map of a snake-case names to a import specifiers. The entrypoints
     * declared here can later be used in the "scripts" option of
     * `PluginRenderResult` to load the entrypoint's code on the client.
     */
    entrypoints?: Record<string, string>;

    /** The render hook is called on the server every time some JSX needs to
     * be turned into HTML. The render hook needs to call the `ctx.render`
     * function exactly once.
     *
     * The hook can return a `PluginRenderResult` object that can do things like
     * inject CSS into the page, or load additional JS files on the client.
     */
    render?(ctx: PluginRenderContext): PluginRenderResult;

    /** The asynchronous render hook is called on the server every time some
     * JSX needs to be turned into HTML, wrapped around all synchronous render
     * hooks. The render hook needs to call the `ctx.renderAsync` function
     * exactly once, and await the result.
     *
     * This is useful for when plugins are generating styles and scripts with
     * asynchronous dependencies. Unlike the synchronous render hook, async render
     * hooks for multiple pages can be running at the same time. This means that
     * unlike the synchronous render hook, you can not use global variables to
     * propagate state between the render hook and the renderer.
     */
    renderAsync?(ctx: PluginAsyncRenderContext): Promise<PluginRenderResult>;

    /**
     * Called before running the Fresh build task
     */
    buildStart?(config: ResolvedFreshConfig): Promise<void> | void;
    /**
     * Called after completing the Fresh build task
     */
    buildEnd?(): Promise<void> | void;

    /**
     * Called after configuration has been loaded
     */
    configResolved?(config: ResolvedFreshConfig): Promise<void> | void;

    routes?: PluginRoute[];

    middlewares?: PluginMiddleware<State>[];

    islands?: PluginIslands;
}

export interface PluginRenderContext {
    render: PluginRenderFunction;
}

export interface PluginAsyncRenderContext {
    renderAsync: PluginAsyncRenderFunction;
}

export interface PluginRenderResult {
    /** CSS styles to be injected into the page. */
    styles?: PluginRenderStyleTag[];
    /** JS scripts to ship to the client. */
    scripts?: PluginRenderScripts[];
    /** Link tags for the page */
    links?: PluginRenderLink[];
    /** Body HTML transformed by the plugin */
    htmlText?: string;
}

export interface PluginRenderStyleTag {
    cssText: string;
    media?: string;
    id?: string;
}

export type PluginRenderLink = {
    crossOrigin?: string;
    href?: string;
    hreflang?: string;
    media?: string;
    referrerPolicy?: string;
    rel?: string;
    title?: string;
    type?: string;
};

export interface PluginRenderScripts {
    /** The "key" of the entrypoint (as specified in `Plugin.entrypoints`) for the
     * script that should be loaded. The script must be an ES module that exports
     * a default function.
     *
     * The default function is invoked with the `state` argument specified below.
     */
    entrypoint: string;
    /** The state argument that is passed to the default export invocation of the
     * entrypoint's default export. The state must be JSON-serializable.
     */
    state: unknown;
}

export type PluginRenderFunction = () => PluginRenderFunctionResult;

export type PluginAsyncRenderFunction = () =>
    | PluginRenderFunctionResult
    | Promise<PluginRenderFunctionResult>;

export interface PluginRenderFunctionResult {
    /** The HTML text that was rendered. */
    htmlText: string;
    /** If the renderer encountered any islands that require hydration on the
     * client. */
    requiresHydration: boolean;
}

export interface PluginMiddleware<State = Record<string, unknown>> {
    /** A path in the format of a filename path without filetype */
    path: string;

    middleware: Middleware<State>;
}

export interface PluginRoute {
    /** A path in the format of a filename path without filetype */
    path: string;

    component?:
        | ComponentType<PageProps>
        | ComponentType<AppProps>
        | AsyncRoute
        | AsyncLayout;

    // deno-lint-ignore no-explicit-any
    handler?: Handler<any, any> | Handlers<any, any>;
}

export interface PluginIslands {
    baseLocation: string;
    paths: string[];
}

// --- Deprecated types ---

/**
 * @deprecated This type was a short-lived alternative to `Handlers`. Please use `Handlers` instead.
 */
export type MultiHandler<T> = Handlers<T>;

/**
 * @deprecated Use {@linkcode FreshConfig} instead
 */
export type StartOptions = FreshConfig;

/**
 * @deprecated Use {@linkcode FreshConfig} interface instead.
 */
export type FreshOptions = FreshConfig;

/**
 * @deprecated Use {@linkcode FreshContext} interface instead
 */
export type HandlerContext<
    Data = unknown,
    State = Record<string, unknown>,
    NotFoundData = Data,
> = FreshContext<State, Data, NotFoundData>;

/**
 * @deprecated Use {@linkcode FreshContext} interface instead
 */
// deno-lint-ignore no-explicit-any
export type AppContext<T = any, S = Record<string, unknown>> = FreshContext<
    S,
    T
>;

/**
 * @deprecated Use {@linkcode FreshContext} interface instead
 */
// deno-lint-ignore no-explicit-any
export type LayoutContext<T = any, S = Record<string, unknown>> = FreshContext<
    S,
    T
>;

/**
 * @deprecated Use {@linkcode FreshContext} interface instead
 */
export type UnknownHandlerContext<State = Record<string, unknown>> =
    FreshContext<State>;

/**
 * @deprecated Use {@linkcode FreshContext} interface instead
 */
export type ErrorHandlerContext<State = Record<string, unknown>> = FreshContext<
    State
>;

/**
 * @deprecated Use {@linkcode FreshContext} interface instead
 */
export type MiddlewareHandlerContext<State = Record<string, unknown>> =
    FreshContext<State>;

/**
 * @deprecated Use {@linkcode PageProps} instead
 */
// deno-lint-ignore no-explicit-any
export type LayoutProps<T = any, S = Record<string, unknown>> = PageProps<T, S>;

/**
 * @deprecated Use {@linkcode PageProps} instead
 */
// deno-lint-ignore no-explicit-any
export type UnknownPageProps<T = any, S = Record<string, unknown>> = PageProps<
    T,
    S
>;

/**
 * @deprecated Use {@linkcode PageProps} instead
 */
// deno-lint-ignore no-explicit-any
export type AppProps<T = any, S = Record<string, unknown>> = PageProps<T, S>;

/**
 * @deprecated Use {@linkcode PageProps} instead
 */
export type ErrorPageProps = PageProps;