@t09tanaka/stoneage 0.1.0

package/dist/core.d.ts

@@ -0,0 +1,473 @@
+import { type ClientAssetRegistry, type ClientStylesheetAsset, type PublicAssetInput } from "./assets.js";
+import { type DeferredFragmentDefaults } from "./fragment.js";
+export * from "./data.js";
+export type RouteParams = Record<string, string | number>;
+export type RouteParamMatcher = (value: string) => boolean;
+export type RouteParamMatchers = Partial<Record<string, RouteParamMatcher>>;
+type RouteParamName<Segment extends string> = Segment extends `${infer Name}.${string}` ? Name : Segment extends `${infer Name}?${string}` ? Name : Segment extends `${infer Name}#${string}` ? Name : Segment;
+type RouteParamRest<Segment extends string> = Segment extends `${string}/${infer Rest}` ? Rest : "";
+export type RouteParamKeys<Pattern extends string> = Pattern extends `${string}:${infer Segment}` ? RouteParamName<Segment extends `${infer BeforeSlash}/${string}` ? BeforeSlash : Segment> | RouteParamKeys<RouteParamRest<Segment>> : never;
+export type RouteParamsFor<Pattern extends string> = [RouteParamKeys<Pattern>] extends [never] ? Record<string, never> : {
+    [Key in RouteParamKeys<Pattern>]: string | number;
+};
+export type RouteParamMatchersFor<Pattern extends string> = [RouteParamKeys<Pattern>] extends [
+    never
+] ? Record<string, never> : Partial<Record<RouteParamKeys<Pattern>, RouteParamMatcher>>;
+export type Dependency = string | {
+    key: string;
+    file: string;
+} | {
+    key: string;
+    value: unknown;
+} | {
+    key: string;
+    hash: string;
+};
+export type SiteConfig = {
+    baseUrl: string;
+    title: string;
+    titleTemplate?: string;
+    description: string;
+    lang?: string;
+    favicon?: string;
+    openGraph?: boolean | SiteOpenGraphMetadata;
+    ogImage?: string;
+    ogImageWidth?: number;
+    ogImageHeight?: number;
+    twitter?: TwitterMetadata;
+    head?: HeadTag[];
+    /**
+     * Path-based metadata resolution hook. Called by `buildSite` once per page
+     * with that page's normalized pathname (after `trailingSlash` is applied,
+     * e.g. `/blog/post/`). Return a `Partial<PageMetadata>` to apply section
+     * images, default OG metadata, canonical overrides, etc. in one place
+     * instead of wiring them onto every route family.
+     *
+     * Resolution precedence (lowest to highest):
+     *   site defaults  <  route `metadata`  <  this hook  <  page-level `metadata`
+     *
+     * Returning `undefined` (or omitting keys) leaves existing values untouched.
+     * The hook is expected to be pure; if it throws, the build fails.
+     * Artifacts (non-HTML entries) never invoke this hook.
+     */
+    metadata?: (pathname: string) => Partial<PageMetadata> | undefined;
+};
+export type SiteOpenGraphMetadata = {
+    siteName?: string;
+};
+export type TwitterMetadata = {
+    card?: string;
+    site?: string;
+    creator?: string;
+    title?: string;
+    description?: string;
+    image?: string;
+};
+export type HeadTag = {
+    tag: "link" | "meta";
+    attrs: Record<string, string | number | boolean | null | undefined>;
+};
+export type RobotsRule = {
+    userAgent: string | string[];
+    allow?: string[];
+    disallow?: string[];
+    crawlDelay?: number;
+};
+export type RobotsConfig = {
+    rules?: RobotsRule[];
+    sitemap?: boolean | string[];
+};
+export type RedirectStatus = 301 | 302 | 303 | 307 | 308;
+export type RedirectRule = {
+    from: string;
+    to: string;
+    status?: RedirectStatus;
+};
+export type TypedRedirectRule<FromPattern extends string, ToPattern extends string> = {
+    from: FromPattern;
+    fromParams: RouteParamsFor<FromPattern>;
+    to: ToPattern;
+    toParams: RouteParamsFor<ToPattern>;
+    status?: RedirectStatus;
+};
+export type RedirectsFromRecordsOptions<RecordItem, FromPattern extends string, ToPattern extends string> = {
+    from: FromPattern;
+    fromParams: (record: RecordItem, index: number) => RouteParamsFor<FromPattern>;
+    to: ToPattern;
+    toParams: (record: RecordItem, index: number) => RouteParamsFor<ToPattern>;
+    status?: RedirectStatus | ((record: RecordItem, index: number) => RedirectStatus);
+};
+export type PublishingConfig = {
+    robots?: RobotsConfig | false;
+    redirects?: RedirectRule[];
+    /**
+     * When `true`, emit a static `<meta http-equiv="refresh">` HTML page at each
+     * internal redirect's `from` path. This makes redirects work on plain static
+     * hosts that do not interpret `redirects.json` / `_redirects`. Off by default
+     * to preserve the existing manifest-only behaviour.
+     */
+    redirectHtml?: boolean;
+    /**
+     * Emit host-native redirect artifacts in addition to the host-neutral
+     * publishing manifests. "netlify" writes Netlify-compatible `_redirects` and
+     * `_headers` files, which Cloudflare Pages also understands.
+     */
+    nativeRedirects?: "netlify" | false;
+    headers?: boolean;
+};
+export type SitemapConfig = {
+    maxUrlsPerFile?: number;
+};
+export type PageMetadata = {
+    title: string;
+    description: string;
+    canonical?: string;
+    openGraph?: boolean;
+    ogTitle?: string;
+    ogDescription?: string;
+    ogImage?: string;
+    ogImageWidth?: number;
+    ogImageHeight?: number;
+    ogType?: string;
+    twitter?: TwitterMetadata;
+    head?: HeadTag[];
+    noindex?: boolean;
+    prefetch?: string[];
+    assets?: string[];
+    islands?: string[];
+    sitemap?: boolean;
+};
+export type PageMetadataInput = Partial<PageMetadata>;
+export type RouteMetadataDefaults = PageMetadataInput;
+export type RouteEntry = {
+    params: RouteParams;
+    path?: string;
+    dependencies?: Dependency[];
+    links?: string[];
+    metadata?: PageMetadataInput;
+    render: () => string | Promise<string>;
+};
+export type RouteFamily = {
+    name: string;
+    pattern: string;
+    metadata?: RouteMetadataDefaults;
+    paramMatchers?: RouteParamMatchers;
+    entries: () => RouteEntry[] | Promise<RouteEntry[]>;
+};
+export type ArtifactBody = string | Buffer | Uint8Array;
+export type ArtifactHeaders = Record<string, string>;
+export type ArtifactResponse = {
+    body: ArtifactBody;
+    contentType?: string;
+    status?: number;
+    headers?: ArtifactHeaders;
+};
+export type ArtifactResponseInit = {
+    contentType?: string;
+    status?: number;
+    headers?: Record<string, string | number | boolean>;
+};
+export type JsonArtifactOptions = ArtifactResponseInit & {
+    pretty?: boolean;
+};
+export type ArtifactContent = ArtifactBody | ArtifactResponse;
+export type ArtifactEntry = {
+    params: RouteParams;
+    path?: string;
+    dependencies?: Dependency[];
+    render: () => ArtifactContent | Promise<ArtifactContent>;
+};
+export type ArtifactFamily = {
+    name: string;
+    pattern: string;
+    paramMatchers?: RouteParamMatchers;
+    entries: () => ArtifactEntry[] | Promise<ArtifactEntry[]>;
+};
+export type FragmentEntry = {
+    params: RouteParams;
+    path?: string;
+    dependencies?: Dependency[];
+    render: () => string | Promise<string>;
+};
+export type FragmentFamily<Params extends RouteParams = RouteParams> = {
+    name: string;
+    pattern: string;
+    paramMatchers?: RouteParamMatchers;
+    path: (params: Params) => string;
+    entries: () => FragmentEntry[] | Promise<FragmentEntry[]>;
+};
+export type SvgAssetEntry<Params extends RouteParams = RouteParams> = {
+    params: Params;
+    dependencies?: Dependency[];
+    width?: number;
+    height?: number;
+    render: () => string | Promise<string>;
+};
+export type SvgAssetFamily<Params extends RouteParams = RouteParams> = {
+    name: string;
+    dir: string;
+    paramMatchers?: RouteParamMatchers;
+    path: (params: Params) => string;
+    entries: () => SvgAssetEntry<Params>[] | Promise<SvgAssetEntry<Params>[]>;
+};
+export type TypedRouteEntry<Pattern extends string> = Omit<RouteEntry, "params"> & {
+    params: RouteParamsFor<Pattern>;
+};
+export type TypedRouteFamily<Pattern extends string> = Omit<RouteFamily, "pattern" | "paramMatchers" | "entries"> & {
+    pattern: Pattern;
+    paramMatchers?: RouteParamMatchersFor<Pattern>;
+    path: (params: RouteParamsFor<Pattern>) => string;
+    entries: () => TypedRouteEntry<Pattern>[] | Promise<TypedRouteEntry<Pattern>[]>;
+};
+export type TypedArtifactEntry<Pattern extends string> = Omit<ArtifactEntry, "params"> & {
+    params: RouteParamsFor<Pattern>;
+};
+export type TypedFragmentEntry<Pattern extends string> = Omit<FragmentEntry, "params"> & {
+    params: RouteParamsFor<Pattern>;
+};
+export type TypedFragmentFamily<Pattern extends string> = Omit<FragmentFamily, "pattern" | "paramMatchers" | "path" | "entries"> & {
+    pattern: Pattern;
+    paramMatchers?: RouteParamMatchersFor<Pattern>;
+    path: (params: RouteParamsFor<Pattern>) => string;
+    entries: () => TypedFragmentEntry<Pattern>[] | Promise<TypedFragmentEntry<Pattern>[]>;
+};
+export type TypedSvgAssetFamily<Params extends RouteParams = RouteParams> = Omit<SvgAssetFamily<Params>, "paramMatchers" | "entries"> & {
+    paramMatchers?: Partial<Record<Extract<keyof Params, string>, RouteParamMatcher>>;
+    entries: () => SvgAssetEntry<Params>[] | Promise<SvgAssetEntry<Params>[]>;
+};
+export type NotFoundConfig = {
+    metadata?: PageMetadataInput;
+    render: () => string | Promise<string>;
+};
+export type BuildConfig = {
+    outDir: string;
+    /**
+     * Optional caller-owned fingerprint for all inputs needed to know whether
+     * the route/artifact plan can be reused. When it matches the previous build
+     * report, StoneAge can return the previous manifest/report without
+     * enumerating routes.
+     */
+    buildFingerprint?: string;
+    /**
+     * Optional caller-owned fingerprint for renderer-wide inputs such as source
+     * templates, CSS inputs, and artifact renderers. This is included in
+     * per-output fingerprints so unchanged data dependencies cannot reuse stale
+     * HTML or artifacts after a renderer-only change.
+     */
+    renderFingerprint?: string;
+    site: SiteConfig;
+    assets?: {
+        stylesheets?: ClientStylesheetAsset[];
+        client?: ClientAssetRegistry;
+        public?: PublicAssetInput[];
+        /**
+         * Directory whose tree is copied verbatim onto the output root. Each file
+         * is expanded into a managed public asset (e.g. `public/images/logo.png`
+         * becomes `/images/logo.png`, `public/CNAME` becomes `/CNAME`). Entries
+         * are tracked in the build report so re-runs are idempotent and removed
+         * source files are pruned from the output.
+         */
+        publicDir?: string;
+    };
+    concurrency?: number;
+    partial?: boolean;
+    prefetch?: {
+        serviceWorker?: boolean;
+        linkRel?: boolean;
+        cacheName?: string;
+        scriptPath?: string;
+        workerPath?: string;
+    };
+    publishing?: PublishingConfig;
+    sitemap?: SitemapConfig;
+    trailingSlash?: "always" | "never";
+    validation?: ValidationConfig;
+    notFound?: NotFoundConfig;
+    routes: RouteFamily[];
+    artifacts?: ArtifactFamily[];
+    fragments?: FragmentConfig;
+    svgAssets?: SvgAssetFamily<any>[];
+};
+export type FragmentConfig = FragmentFamily<any>[] | (DeferredFragmentDefaults & {
+    families?: FragmentFamily<any>[];
+    client?: boolean | {
+        publicPath?: string;
+    };
+});
+export type ValidationConfig = {
+    configPath?: string;
+    configHash?: string;
+    requiredMetadata?: RequiredMetadataKey[];
+    budgets?: SizeBudgetConfig;
+};
+export type RequiredMetadataKey = (typeof requiredMetadataKeys)[number];
+export type SizeBudgetConfig = {
+    maxPages?: number;
+    maxArtifacts?: number;
+    maxRouteFamilyPages?: Record<string, number>;
+    maxArtifactFamilyOutputs?: Record<string, number>;
+    maxHtmlBytes?: number;
+    maxCssBytes?: number;
+    maxJsBytes?: number;
+    maxPublicFileBytes?: number;
+    maxTotalPublicBytes?: number;
+    maxImageBytes?: number;
+    maxBrotliBytes?: number;
+    maxGzipBytes?: number;
+    maxDependencyFanout?: number;
+};
+declare const requiredMetadataKeys: readonly ["title", "description", "canonical", "favicon", "ogImage", "twitterImage"];
+export declare function loadValidationConfig(path: string): Promise<ValidationConfig>;
+export type ManifestPage = {
+    route: string;
+    path: string;
+    outputPath: string;
+    dependencies: Record<string, string>;
+    links: string[];
+    htmlBytes: number;
+    sitemap: boolean;
+};
+export type ManifestArtifact = {
+    route: string;
+    path: string;
+    outputPath: string;
+    dependencies: Record<string, string>;
+    bytes: number;
+    contentType?: string;
+    status?: number;
+    headers?: ArtifactHeaders;
+};
+export type Manifest = {
+    version: 1;
+    pages: ManifestPage[];
+    artifacts: ManifestArtifact[];
+};
+export type BuildReport = {
+    buildFingerprint?: string;
+    renderFingerprint?: string;
+    fragmentDefaultFallbackText?: string;
+    fragmentClientPublicPath?: string;
+    pageCount: number;
+    pagesWritten: number;
+    artifactCount: number;
+    artifactsWritten: number;
+    publicAssetsCopied: number;
+    publicAssetsSkipped: number;
+    publicAssets: string[];
+    staleOutputsRemoved: number;
+    sitemapRendered: boolean;
+    sitemapFiles: string[];
+    routeFamilies: Record<string, number>;
+    routeWrites: Record<string, number>;
+    artifactFamilies: Record<string, number>;
+    artifactWrites: Record<string, number>;
+    missingLinks: string[];
+    largestHtml: Array<{
+        path: string;
+        bytes: number;
+    }>;
+    largestArtifacts: Array<{
+        path: string;
+        bytes: number;
+    }>;
+    validation: BuildValidationReport;
+};
+export type DataFlowFamilySummary = {
+    name: string;
+    outputs: number;
+    written: number;
+    skipped: number;
+    bytes: number;
+};
+export type DataFlowDependencySummary = {
+    key: string;
+    outputs: number;
+    pages: number;
+    artifacts: number;
+    routes: Record<string, number>;
+    artifactRoutes: Record<string, number>;
+};
+export type DataFlowReport = {
+    version: 1;
+    outputs: {
+        pages: number;
+        artifacts: number;
+        total: number;
+    };
+    routeFamilies: DataFlowFamilySummary[];
+    artifactFamilies: DataFlowFamilySummary[];
+    dependencies: DataFlowDependencySummary[];
+};
+export type DataFlowSummaryReport = Omit<DataFlowReport, "dependencies">;
+export type DataFlowDependenciesReport = {
+    version: 1;
+    dependencies: DataFlowDependencySummary[];
+};
+export type BuildValidationReport = {
+    ok: boolean;
+    configPath?: string;
+    configHash?: string;
+    issues: ValidationIssue[];
+};
+export type ValidationIssue = {
+    code: string;
+    message: string;
+    path?: string;
+    bytes?: number;
+    dependency?: string;
+    outputs?: number;
+    limit?: number;
+};
+export type BuildResult = {
+    pagesWritten: number;
+    artifactsWritten: number;
+    publicAssetsCopied: number;
+    publicAssetsSkipped: number;
+    manifest: Manifest;
+    report: BuildReport;
+};
+export type HtmlComponent<Props> = (props: Props) => string;
+export declare const notFoundRouteName = "\0stoneage:not-found";
+export declare const notFoundOutputPath = "404.html";
+export declare function component<Props>(render: HtmlComponent<Props>): HtmlComponent<Props>;
+export declare function routePath(pattern: string, params: RouteParams): string;
+export declare function artifactPath(pattern: string, params: RouteParams): string;
+export declare function fragmentPath(pattern: string, params: RouteParams): string;
+export declare function patternParamMatcher(pattern: RegExp): RouteParamMatcher;
+export declare function pathForRoute<const Pattern extends string>(pattern: Pattern, params: RouteParamsFor<Pattern>): string;
+export declare function pathForArtifact<const Pattern extends string>(pattern: Pattern, params: RouteParamsFor<Pattern>): string;
+export declare function pathForRedirect<const Pattern extends string>(pattern: Pattern, params: RouteParamsFor<Pattern>): string;
+export declare function redirectToRoute<const FromPattern extends string, const ToPattern extends string>(redirect: TypedRedirectRule<FromPattern, ToPattern>): RedirectRule;
+export declare function redirectsFromRecords<RecordItem, const FromPattern extends string, const ToPattern extends string>(records: readonly RecordItem[], options: RedirectsFromRecordsOptions<RecordItem, FromPattern, ToPattern>): RedirectRule[];
+export declare function defineRouteFamily<const Pattern extends string>(config: {
+    name: string;
+    pattern: Pattern;
+    metadata?: RouteMetadataDefaults;
+    paramMatchers?: RouteParamMatchersFor<Pattern>;
+    entries: () => TypedRouteEntry<Pattern>[] | Promise<TypedRouteEntry<Pattern>[]>;
+}): TypedRouteFamily<Pattern>;
+export declare function defineArtifactFamily<const Pattern extends string>(config: {
+    name: string;
+    pattern: Pattern;
+    paramMatchers?: RouteParamMatchersFor<Pattern>;
+    entries: () => TypedArtifactEntry<Pattern>[] | Promise<TypedArtifactEntry<Pattern>[]>;
+}): ArtifactFamily;
+export declare function defineFragmentFamily<const Pattern extends string>(config: {
+    name: string;
+    pattern: Pattern;
+    paramMatchers?: RouteParamMatchersFor<Pattern>;
+    entries: () => TypedFragmentEntry<Pattern>[] | Promise<TypedFragmentEntry<Pattern>[]>;
+}): TypedFragmentFamily<Pattern>;
+export declare function defineSvgAssetFamily<Params extends RouteParams = RouteParams>(config: {
+    name: string;
+    dir?: string;
+    paramMatchers?: Partial<Record<Extract<keyof Params, string>, RouteParamMatcher>>;
+    entries: () => SvgAssetEntry<Params>[] | Promise<SvgAssetEntry<Params>[]>;
+}): TypedSvgAssetFamily<Params>;
+export declare function artifactResponse(body: ArtifactBody, init?: ArtifactResponseInit): ArtifactResponse;
+export declare function jsonArtifact(value: unknown, options?: JsonArtifactOptions): ArtifactResponse;
+export declare function textArtifact(body: string, init?: ArtifactResponseInit): ArtifactResponse;
+export declare function csvArtifact(body: string, init?: ArtifactResponseInit): ArtifactResponse;
+export declare function xmlArtifact(body: string, init?: ArtifactResponseInit): ArtifactResponse;
+export declare function buildSite(config: BuildConfig): Promise<BuildResult>;
+export declare function hashValue(value: unknown): string;