Referencia de la API

Todos los paquetes @carats/* son pequeños y están tipados por completo. Las declaraciones siguientes son toda la superficie pública.

@carats/core

interface CaratsRequest<T = any> {
    url: string;
    headers: Record<string, string>;
    cookies: Record<string, string>;
    method: string;
    data: T;
}
declare function findClosest(fileName: string): string | undefined;

@carats/render

interface CaratsComponent<T = any> extends JSX.FunctionComponent<T> {
    defaultProps?: T;
    head?: JSX.Element;
    burnished?: boolean;
    recast?: boolean;
}
type CaratsComponentWithThis<T = any> =
    ((this: CaratsComponent<T>, props: T) => JSX.Element) & CaratsComponent<T>;
interface Facets {
    inAppRouting?: boolean;
    routes: Record<string, CaratsComponent>;
    suspense: {
        loading: () => JSX.Element;
        error: (error: Error) => JSX.Element;
        notFound: () => JSX.Element;
    };
}
interface PartialFacets {
    inAppRouting?: boolean;
    routes?: Record<string, CaratsComponent>;
    suspense?: Partial<Facets['suspense']>;
}
interface PageComponentResult {
    component: CaratsComponent<any>;
    params: Record<string, string>;
    route: string;
}
interface BurnishOptions {
    recast?: boolean;
}
declare function defineFacets(facets: PartialFacets): Facets;
declare function getPageComponent(this: Facets, url: string): PageComponentResult;
declare function Burnish<T = any>(component: CaratsComponentWithThis<T>, options?: BurnishOptions): CaratsComponentWithThis<T>;
declare function Burnish<T = any>(component: CaratsComponent<T>, options?: BurnishOptions): CaratsComponent<T>;

defineFacets toma un PartialFacets y devuelve un Facets completamente poblado, y por eso todas las claves de la entrada son opcionales. Facets['suspense'] enumera los tres estados, pero la entrada parcial permite declarar solo los que importan.

head es un JSX.Element, no una cadena. Asígnale un fragmento de etiquetas y el framework recogerá ese fragmento durante el renderizado.

getPageComponent es la función sobre la que está construido el plugin del servidor. Se exporta porque es útil por sí sola: dada una URL resuelve un componente junto con sus parámetros, lo que basta para averiguar qué renderizaría una petición.

@carats/csr

declare global {
    interface HTMLAnchorElement {
        _isHandled: boolean;
    }
    interface Window {
        carats: {
            ssp: {
                for: string | undefined;
                data: any;
            };
        };
    }
}
declare function mount(facets: Facets): Facets;
declare function clientRender(): Promise<void>;
declare function goTo(url: string): void;

El indicador _isHandled de HTMLAnchorElement es la forma que tiene el entorno de ejecución de marcar un enlace del que ya se ha hecho cargo. Una vez gestionado un enlace, la navegación ocurre en el cliente en lugar del navegador. No lo asignes tú.

@carats/hooks

type MaybePromise<T> = T | Promise<T>;
type ClearCallback = () => MaybePromise<void>;
type HydrationCallback = () => MaybePromise<ClearCallback | void>;
declare function afterMount(callback: HydrationCallback): void;
declare function beforeMount(callback: HydrationCallback): void;
declare function clearHydrations(): Promise<void>;
type Getter<T> = () => T;
type Factory<T> = (currentValue: T) => T;
type Setter<T> = {
    (fn: Factory<T>): T;
    (value: T): T;
};
type Subscriber<T> = (value: T) => void;
type Subscribe<T> = (subscriber: Subscriber<T>) => () => void;
type State<T> = {
    get: Getter<T>;
    set: Setter<T>;
    subscribe: Subscribe<T>;
};
declare function use<T>(): State<T>;
declare function use<T>(initialState: T): State<T>;

@carats/ssr

import { CaratsRequest } from '@carats/core';
import { Facets } from '@carats/render';

interface CaratsServerEntry {
    render: (req: CaratsRequest<never>) => Promise<{
        html?: string;
        head?: string;
    }>;
    getServerProps: <T = any>(req: CaratsRequest<never>) => Promise<T> | T;
    facets: Facets;
    culets: Record<string, Culet>;
}
type CuletArgs = Omit<CaratsRequest, 'data'> & {
    params: Record<string, string>;
};
type Culet<T extends Object = any> = (request: CuletArgs) => T;
declare const seat: <T extends Culet>(f: T) => T;
declare function culet<T extends Object = any>(route: string, culet: Culet<T>): Culet<T>;
declare function defineServerEntry(facets: Facets): CaratsServerEntry;

CuletArgs es CaratsRequest sin data, más params. La ausencia de data es deliberada: a un culet solo se llega con GET, así que no hay cuerpo de petición que leer.

@carats/express

import { Router } from 'express';
declare const carats: () => Router;

@carats/url

declare function qs(query: Record<string, string>): string;
declare function parseUrl(url: string): {
    path: string;
    query: Record<string, string>;
};
declare function matchRoute(route: string, path: string): Record<string, string> | false;
declare function replaceParams(route: string, params: Record<string, string>): string;

@carats/ssg

#!/usr/bin/env bun

@carats/ssg distribuye una herramienta de línea de comandos y ninguna exportación de ejecución, así que no tiene superficie importable. Se hace referencia a él en el script build:static y en ningún sitio del código de la aplicación.