مرجع API

كل حزمة من ‎@carats/*‎ صغيرة ومصنَّفة بالكامل. التصريحات أدناه هي كامل الواجهة العامة.

‎@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`‎ يأخذ ‏`PartialFacets`‎ ويُعيد ‏`Facets`‎ ممتلئة بالكامل، ولهذا فإن كل مفتاح في الدخل اختياري. وتسرد ‏`Facets['suspense']`‎ الحالات الثلاث كلها، لكن الدخل الجزئي يسمح بالتصريح بالمهم منها فقط.

‏`head`‎ هو ‏`JSX.Element`‎ لا سلسلة نصية. أسند إليه جزءًا من الوسوم، والإطار يجمعه أثناء التصيير.

‏`getPageComponent`‎ هي الدالة التي بُني عليها مُلحق الخادم. وهي مُصدَّرة لأنها مفيدة بذاتها: بمسار ما فهي تحلّ مكوّنًا مع معاملاته، وهذا يكفي لتحديد ما سيُصيّره الطلب.

‎@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;

علامة `_isHandled` على ‎HTMLAnchorElement‎‎ هي طريقة بيئة التشغيل في وضع علامة على رابط تولّته بالفعل. وبعد معالجة الرابط يصبح التنقل يحدث في العميل بدل المتصفح. لا تُعِد ضبطها بنفسك.

‎@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`‎ هو ‏`CaratsRequest`‎ بدون ‏`data`‎، مع ‏`params`‎. وغياب ‏`data`‎ مقصود: لا يُبلَغ الدوال الخادمية إلا عبر GET، فليس هناك جسم طلب لقراءته.

‎@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`‎ أداة سطر أوامر بلا أي تصديرات وقت تشغيل، لذا لا واجهة يمكن استيرادها. ويُشار إليها في سكربت ‎`build:static`‎ فقط ولا في أي شيفرة تطبيق.