@farm.js/core 0.1.0-beta.21 → 0.1.0-beta.22

package/dist/app-DwsTpyNZ.d.mts

@@ -0,0 +1,306 @@
+import { F as FarmConfig, C as ParsedRoute, s as RouteModule, v as LayoutModule, I as SSGCollectionResult, x as FarmRequest, y as FarmResponse, a8 as FarmMdxResolvedConfig, a9 as ResolvedFarmDevtoolsConfig, aa as ResolvedFarmAuthConfig, ab as ResolvedFarmPerformanceConfig, ac as ResolvedFarmSecurityConfig } from './client-plugins-QQntVkrv.mjs';
+import { F as FarmDocsResolvedConfig } from './types-DTzm4TCl.mjs';
+import { FarmMarkdownResolvedConfig } from './markdown.mjs';
+import { F as FarmWorkflowsResolvedConfig } from './workflows-CusFV6mn.mjs';
+import { FarmCronResolvedConfig } from './cron.mjs';
+import { R as ResolvedFarmImageConfig } from './image-config-Duob7wER.mjs';
+import { ProgrammaticRedirectRoute, ProgrammaticRouteSearchClientOptions } from './routes.mjs';
+import { ViteDevServer } from 'vite';
+import { M as MetadataImageKind } from './metadata-BxOJ4FJl.mjs';
+import { F as FarmIslandStrategy } from './island-CfGru1MO.mjs';
+import { R as ResolvedFarmRouteRuntimeConfig } from './route-runtime-DoOHzCAD.mjs';
+import { R as ResolvedFarmI18nConfig } from './types-BMxWr97v.mjs';
+import { F as FarmI18nRuntime } from './runtime-Cxpq6xZN.mjs';
+
+declare const STATIC_METADATA_IMAGE_EXTENSIONS: readonly ["png", "jpg", "jpeg", "gif", "webp"];
+type StaticMetadataImageExtension = (typeof STATIC_METADATA_IMAGE_EXTENSIONS)[number];
+interface StaticMetadataImageInfo {
+    extension: StaticMetadataImageExtension;
+    contentType: string;
+    width: number;
+    height: number;
+    alt?: string;
+    hash: string;
+    byteLength: number;
+}
+
+interface RouteEntry {
+    route: ParsedRoute;
+    modulePath: string;
+    markdownSourcePath?: string;
+    pattern: string;
+    source?: "file" | "programmatic";
+    sourceRoot: string;
+}
+interface RouteSlotEntry extends RouteEntry {
+    name: string;
+    ownerPattern: string;
+    interception: boolean;
+    fallback: boolean;
+    containerId: string;
+}
+interface MatchedRouteSlot {
+    name: string;
+    ownerPattern: string;
+    containerId: string;
+    interception: boolean;
+    fallback: boolean;
+    route: RouteSlotEntry;
+    params: Record<string, string>;
+}
+interface MetadataImageEntry extends RouteEntry {
+    kind: MetadataImageKind;
+    fileName: "opengraph-image" | "twitter-image";
+    sourceType: "module" | "static";
+    staticInfo?: StaticMetadataImageInfo;
+}
+/**
+ * Manages route discovery and matching for the Farm.js application
+ */
+declare class RouteManager {
+    private config;
+    private routes;
+    private layouts;
+    private routeSlots;
+    private loadings;
+    private errors;
+    private metadataImages;
+    private redirects;
+    private programmaticPages;
+    private programmaticLayouts;
+    private viteServer?;
+    constructor(config: Required<FarmConfig>, viteServer?: ViteDevServer);
+    /**
+     * Discover all routes in the app directory
+     */
+    discoverRoutes(): Promise<void>;
+    /**
+     * Find matching route for a given URL path
+     */
+    matchRoute(pathname: string, options?: {
+        interceptFrom?: string;
+    }): {
+        route: RouteEntry | null;
+        params: Record<string, string>;
+        layouts: RouteEntry[];
+        slots: MatchedRouteSlot[];
+    };
+    /**
+     * Get all registered routes
+     */
+    getRoutes(): Map<string, RouteEntry>;
+    /**
+     * Get all registered layouts
+     */
+    getLayouts(): Map<string, RouteEntry>;
+    getRouteSlots(): Map<string, RouteSlotEntry>;
+    /** Resolve route rules, inherited layouts, and the page export in precedence order. */
+    resolveRouteRuntimeConfig(pattern: string): Promise<ResolvedFarmRouteRuntimeConfig>;
+    /**
+     * Get all route-level loading boundaries.
+     */
+    getLoadings(): Map<string, RouteEntry>;
+    /**
+     * Get all route-level error boundaries.
+     */
+    getErrors(): Map<string, RouteEntry>;
+    getMetadataImages(): Map<string, MetadataImageEntry>;
+    getRedirects(): ProgrammaticRedirectRoute[];
+    matchRedirect(pathname: string): {
+        redirect: ProgrammaticRedirectRoute;
+        destination: string;
+        statusCode: number;
+        params: Record<string, string>;
+    } | null;
+    /**
+     * Return the nearest matching loading boundary for a pathname.
+     */
+    getMatchingLoading(pathname: string): RouteEntry | null;
+    /**
+     * Return the nearest matching error boundary for a pathname.
+     */
+    getMatchingError(pathname: string): RouteEntry | null;
+    matchMetadataImage(pathname: string): {
+        image: MetadataImageEntry;
+        params: Record<string, string>;
+        pagePath: string;
+    } | null;
+    getMatchingMetadataImage(pathname: string, kind: MetadataImageKind): {
+        image: MetadataImageEntry;
+        params: Record<string, string>;
+    } | null;
+    resolveMetadataImagePath(image: MetadataImageEntry, params?: Record<string, string>): string;
+    /**
+     * Generate a client-side route manifest for SPA navigation
+     * This eliminates the need for server requests during navigation
+     */
+    generateClientManifest(projectRoot: string): {
+        routes: Array<{
+            pattern: string;
+            modulePath: string;
+            shouldHydrate: boolean;
+            isClientComponent: boolean;
+            islandStrategy: FarmIslandStrategy | null;
+            search?: ProgrammaticRouteSearchClientOptions;
+            segments: Array<{
+                segment: string;
+                isDynamic: boolean;
+                isCatchAll?: boolean;
+                isOptional?: boolean;
+            }>;
+        }>;
+        layouts: Array<{
+            pattern: string;
+            modulePath: string;
+        }>;
+        slots: Array<{
+            name: string;
+            ownerPattern: string;
+            pattern: string;
+            modulePath: string;
+            containerId: string;
+            interception: boolean;
+            fallback: boolean;
+            shouldHydrate: boolean;
+            isClientComponent: boolean;
+            segments: RouteEntry["route"]["segments"];
+        }>;
+    };
+    /**
+     * Load a route module dynamically
+     */
+    loadRouteModule(modulePath: string): Promise<RouteModule>;
+    /**
+     * Load a layout module dynamically
+     */
+    loadLayoutModule(modulePath: string): Promise<LayoutModule>;
+    /**
+     * Create a route pattern from parsed route
+     */
+    private createRoutePattern;
+    private discoverFileRoutes;
+    private discoverProgrammaticRoutes;
+    private loadProgrammaticRoutesModule;
+    /**
+     * Find all layouts that should wrap a given path
+     */
+    private findMatchingLayouts;
+    private findMatchingRouteSlots;
+    private matchesRoutePrefix;
+    private findNearestBoundary;
+    /**
+     * Log discovered routes for debugging
+     */
+    private logRoutes;
+    /**
+     * Collect SSG pages for static generation
+     *
+     * Returns all pages marked with `export const ssg = true` along with
+     * their pre-computed paths (for dynamic routes using getStaticPaths)
+     */
+    collectSSGPages(): Promise<SSGCollectionResult>;
+    private toRoutePathname;
+    private localizeRedirectDestination;
+    private getI18nConfig;
+    /**
+     * Check if a route is SSG
+     */
+    isRouteSSG(modulePath: string): Promise<boolean>;
+    /**
+     * Check if a route has ISR (Incremental Static Regeneration)
+     */
+    hasRouteISR(modulePath: string): Promise<boolean>;
+    /**
+     * Get revalidation interval for a route
+     */
+    getRouteRevalidateInterval(modulePath: string): Promise<number | undefined>;
+}
+
+declare class ServerRenderer {
+    private config;
+    private routeManager;
+    private ssgManifest;
+    private dataCache;
+    private i18nRuntime?;
+    constructor(config: Required<FarmConfig>, routeManager: RouteManager, i18nRuntime?: FarmI18nRuntime);
+    runWithRequestContext<T>(request: Request, fn: () => T | Promise<T>): Promise<T>;
+    resolveRouteContext(input: {
+        request: Request;
+        rawRequest?: FarmRequest;
+        params: Record<string, string>;
+        search: Record<string, string | string[] | undefined>;
+        path: string;
+    }): Promise<unknown>;
+    /**
+     * Load SSG manifest from build output
+     */
+    private loadSSGManifest;
+    /**
+     * Check if a path should be served from SSG cache
+     */
+    private shouldServeSSG;
+    private getSSGCacheKey;
+    private getPPRCacheKey;
+    private getCachedSSGPage;
+    private cacheSSGPage;
+    private getCachedPPRShell;
+    private cachePPRShell;
+    private getPPRShellBypassReason;
+    private getPPRHeaders;
+    private serveCachedPPRShell;
+    /**
+     * Regenerate an SSG page in the background (ISR)
+     */
+    private regenerateSSGPage;
+    /**
+     * Serve a pre-rendered SSG page
+     */
+    private serveSSGPage;
+    renderPage(req: FarmRequest, res: FarmResponse): Promise<void>;
+    private renderPageInContext;
+    private wrapWithIntegrationProviders;
+    private resolveRouteMetadata;
+    private resolveMetadataImageReference;
+    private renderMetadataImage;
+    private writeMetadataImageResponse;
+    private writeStaticMetadataImageResponse;
+    private renderRouteErrorBoundary;
+    private renderWithSSR;
+    private render404;
+    private render500;
+    private createFullHTML;
+    private applyDeploymentHeaders;
+    private getDeploymentId;
+}
+
+type NormalizedFarmConfig = Omit<Required<FarmConfig>, "devtools" | "images" | "i18n" | "performance" | "security"> & {
+    docs: FarmDocsResolvedConfig;
+    md: FarmMarkdownResolvedConfig;
+    mdx: FarmMdxResolvedConfig;
+    cron: FarmCronResolvedConfig;
+    workflows: FarmWorkflowsResolvedConfig;
+    devtools: ResolvedFarmDevtoolsConfig;
+    images: ResolvedFarmImageConfig;
+    i18n: ResolvedFarmI18nConfig;
+    auth: ResolvedFarmAuthConfig;
+    performance: ResolvedFarmPerformanceConfig;
+    security: ResolvedFarmSecurityConfig;
+};
+declare class FarmApp {
+    private config;
+    private routeManager;
+    private serverRenderer;
+    private i18nRuntime;
+    private viteServer?;
+    constructor(config?: FarmConfig, viteServer?: ViteDevServer);
+    initialize(): Promise<void>;
+    getRouteManager(): RouteManager;
+    getServerRenderer(): ServerRenderer;
+    getI18nRuntime(): FarmI18nRuntime;
+    getConfig(): NormalizedFarmConfig;
+    private normalizeConfig;
+    private verifyAppStructure;
+}
+declare function createFarmApp(config?: FarmConfig, viteServer?: ViteDevServer): FarmApp;
+
+export { FarmApp as F, RouteManager as R, ServerRenderer as S, createFarmApp as c };

package/dist/app-markdown.d.mts

@@ -0,0 +1,24 @@
+import 'react';
+export { df as FarmMarkdownPageModuleInput, de as FarmMarkdownPageSource, db as FarmMdxComponent, dc as FarmMdxComponents, a8 as FarmMdxResolvedConfig, dd as FarmMdxUserConfig, dm as createFarmMarkdownRouteModule, dn as createFarmMarkdownRouteModuleFromFile, dq as createFarmMarkdownSourceResponse, dl as createMarkdownMetadata, dh as isFarmMarkdownPageFile, dp as loadFarmMdxComponents, di as normalizeFarmMarkdownRoutePath, dj as parseMarkdownFrontmatter, dg as resolveMdxConfig, dk as titleFromMarkdown } from './client-plugins-QQntVkrv.mjs';
+import './plugin-BJDf43dc.mjs';
+import 'http';
+import './types-D1A6-XvH.mjs';
+import 'db0';
+import 'unstorage';
+import './integration-api-CHT2OKAf.mjs';
+import '@farming-labs/orm';
+import './types-DTzm4TCl.mjs';
+import '@farming-labs/docs';
+import './markdown.mjs';
+import './observability.mjs';
+import 'vite';
+import './workflows-CusFV6mn.mjs';
+import './cron.mjs';
+import './env.mjs';
+import './server-action-security.mjs';
+import './server-fn-error-DDh14a0V.mjs';
+import './image-config-Duob7wER.mjs';
+import './types-BMxWr97v.mjs';
+import './cache.mjs';
+import './route-runtime-DoOHzCAD.mjs';
+import './font.mjs';

package/dist/app-markdown.d.ts

@@ -0,0 +1,24 @@
+import 'react';
+export { df as FarmMarkdownPageModuleInput, de as FarmMarkdownPageSource, db as FarmMdxComponent, dc as FarmMdxComponents, a8 as FarmMdxResolvedConfig, dd as FarmMdxUserConfig, dm as createFarmMarkdownRouteModule, dn as createFarmMarkdownRouteModuleFromFile, dq as createFarmMarkdownSourceResponse, dl as createMarkdownMetadata, dh as isFarmMarkdownPageFile, dp as loadFarmMdxComponents, di as normalizeFarmMarkdownRoutePath, dj as parseMarkdownFrontmatter, dg as resolveMdxConfig, dk as titleFromMarkdown } from './client-plugins-CbRum1fj.js';
+import './plugin-BJDf43dc.js';
+import 'http';
+import './types-D1A6-XvH.js';
+import 'db0';
+import 'unstorage';
+import './integration-api-CHT2OKAf.js';
+import '@farming-labs/orm';
+import './types-DTzm4TCl.js';
+import '@farming-labs/docs';
+import './markdown.js';
+import './observability.js';
+import 'vite';
+import './workflows-CusFV6mn.js';
+import './cron.js';
+import './env.js';
+import './server-action-security.js';
+import './server-fn-error-DDh14a0V.js';
+import './image-config-Duob7wER.js';
+import './types-BMxWr97v.js';
+import './cache.js';
+import './route-runtime-DoOHzCAD.js';
+import './font.js';

package/dist/cache.d.mts

@@ -0,0 +1,192 @@
+declare function applyFarmCacheInvalidations(keys: unknown): void;
+
+type RevalidateTagProfile = "max" | "default" | "seconds" | "minutes" | "hours" | "days" | "weeks" | "months" | {
+    expire?: number;
+};
+interface FarmCacheOptions {
+    /**
+     * Tag cached data so it can be invalidated with revalidateTag/updateTag.
+     */
+    tags?: readonly string[];
+    /**
+     * Path tags let revalidatePath invalidate data tied to a route.
+     */
+    paths?: readonly string[];
+    /**
+     * Time in seconds before the entry becomes stale. False means no TTL.
+     */
+    revalidate?: number | false;
+}
+interface FarmCacheSetOptions extends FarmCacheOptions {
+    createdAt?: number;
+}
+type RouteDataCacheKey = string | readonly unknown[];
+type FarmCacheInvalidationTarget = {
+    key: RouteDataCacheKey;
+} | {
+    path: string;
+} | {
+    tag: string;
+};
+declare const FARM_DEFINED_CACHE_KEY_DATA: unique symbol;
+/**
+ * A regular Farm cache key carrying the data shape stored under that key.
+ *
+ * The brand exists only in TypeScript. At runtime the value remains the
+ * original string or structured array, so all existing cache APIs continue to
+ * accept untyped keys.
+ */
+type DefinedCacheKey<TData, TKey extends RouteDataCacheKey = RouteDataCacheKey> = TKey & {
+    readonly [FARM_DEFINED_CACHE_KEY_DATA]: TData;
+};
+type CacheKeyFactory<TData, TArguments extends readonly unknown[], TKey extends RouteDataCacheKey = RouteDataCacheKey> = (...args: TArguments) => DefinedCacheKey<TData, TKey>;
+type InferCacheKeyData<TKey> = TKey extends DefinedCacheKey<infer TData, RouteDataCacheKey> ? TData : unknown;
+/**
+ * Optionally add a data type to an existing string/array cache-key factory.
+ *
+ * This helper does not introduce a new runtime key representation. Calling the
+ * returned factory produces the exact key returned by `factory`.
+ */
+declare function defineCacheKey<TData>(): <const TArguments extends readonly unknown[], const TKey extends RouteDataCacheKey>(factory: (...args: TArguments) => TKey) => CacheKeyFactory<TData, TArguments, TKey>;
+interface FarmCacheEntry<T = unknown> {
+    key: string;
+    value: T;
+    tags: readonly string[];
+    /**
+     * Adapter tag versions captured before the cached value was produced.
+     * A later version makes the entry stale across every server instance.
+     */
+    tagVersions?: Readonly<Record<string, number>>;
+    createdAt: number;
+    createdVersion?: number;
+    revalidate?: number | false;
+}
+/**
+ * Asynchronous persistence contract used by distributed Farm caches.
+ *
+ * Implementations are responsible for serializing cache entries and making
+ * tag version updates atomic when the backing service supports it.
+ */
+interface FarmCacheAdapter {
+    readonly name?: string;
+    get<T = unknown>(key: string): Promise<FarmCacheEntry<T> | null | undefined>;
+    set<T = unknown>(key: string, entry: FarmCacheEntry<T>): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear?(): Promise<void>;
+    getTagVersions?(tags: readonly string[]): Promise<Readonly<Record<string, number>>>;
+    invalidateTags?(tags: readonly string[]): Promise<void>;
+    /** Atomically acquire a short-lived regeneration lease. */
+    acquireLease?(key: string, ttlMs: number): Promise<string | null | undefined>;
+    /** Release the lease only when the supplied ownership token still matches. */
+    releaseLease?(key: string, token: string): Promise<void>;
+}
+interface FarmCacheUserConfig {
+    /** Shared cache implementation, for example a Redis-backed adapter. */
+    adapter?: FarmCacheAdapter;
+    /** Prefix isolating applications and deployments sharing one adapter. */
+    namespace?: string;
+    /**
+     * Coordinate cache fills across processes when the adapter implements
+     * acquireLease/releaseLease. Set false to disable.
+     */
+    lease?: false | {
+        ttlMs?: number;
+        waitTimeoutMs?: number;
+        pollIntervalMs?: number;
+    };
+}
+interface FarmCacheStorage {
+    getItem<T = unknown>(key: string): Promise<T | null>;
+    setItem<T = unknown>(key: string, value: T): Promise<unknown>;
+    removeItem(key: string): Promise<unknown>;
+    clear?(base?: string): Promise<unknown>;
+}
+interface StorageFarmCacheAdapterOptions {
+    /** Prefix used inside the supplied storage client. */
+    base?: string;
+}
+/**
+ * Adapt a Farm/unstorage-compatible key-value client to the cache contract.
+ *
+ * This is a portable baseline adapter. Provider-specific adapters should use
+ * their atomic increment/transaction primitives for tag invalidation.
+ */
+declare function storageCacheAdapter(storage: FarmCacheStorage, options?: StorageFarmCacheAdapterOptions): FarmCacheAdapter;
+interface GetFarmCacheEntryOptions {
+    allowStale?: boolean;
+    now?: number;
+}
+interface FarmCacheStaleEntry {
+    tags: Iterable<string>;
+    createdAt: number;
+    createdVersion?: number;
+    revalidate?: number | false;
+}
+declare class FarmDataCache {
+    private entries;
+    private inflight;
+    private invalidatedTagVersions;
+    private version;
+    private adapter?;
+    private namespace;
+    private local;
+    private lease;
+    constructor(config?: FarmCacheUserConfig);
+    configure(config?: FarmCacheUserConfig): void;
+    get adapterName(): string;
+    get hasAdapter(): boolean;
+    get size(): number;
+    get<T>(key: string, options?: GetFarmCacheEntryOptions): T | undefined;
+    getEntry<T = unknown>(key: string, options?: GetFarmCacheEntryOptions): FarmCacheEntry<T> | undefined;
+    getEntryAsync<T = unknown>(key: string, options?: GetFarmCacheEntryOptions): Promise<FarmCacheEntry<T> | undefined>;
+    set<T>(key: string, value: T, options?: FarmCacheSetOptions): FarmCacheEntry<T>;
+    setAsync<T>(key: string, value: T, options?: FarmCacheSetOptions, tagVersions?: Readonly<Record<string, number>>): Promise<FarmCacheEntry<T>>;
+    delete(key: string): boolean;
+    deleteAsync(key: string): Promise<boolean>;
+    clear(): void;
+    clearAsync(): Promise<void>;
+    isStale(entry: FarmCacheStaleEntry, now?: number): boolean;
+    isStaleAsync(entry: FarmCacheEntry, now?: number): Promise<boolean>;
+    revalidateTag(tag: string, options?: {
+        source?: "revalidateTag" | "updateTag";
+        profile?: RevalidateTagProfile;
+    }): number;
+    revalidateTagAsync(tag: string, options?: {
+        source?: "revalidateTag" | "updateTag";
+        profile?: RevalidateTagProfile;
+    }): Promise<number>;
+    revalidatePath(routePath: string): number;
+    revalidatePathAsync(routePath: string): Promise<number>;
+    getOrSet<T>(key: string, producer: () => Promise<T> | T, options?: FarmCacheOptions): Promise<T>;
+    private fillCacheEntry;
+    private waitForAdapterEntry;
+    private countEntriesForTag;
+    private countEntriesForTags;
+    private invalidateTag;
+    private toPublicEntry;
+    private hydrateLocalEntry;
+    private createAdapterKey;
+    private createAdapterTag;
+    private getAdapterTagVersions;
+    private isAdapterEntryStale;
+}
+declare function getFarmDataCache(): FarmDataCache;
+declare function configureFarmCache(config: FarmCacheUserConfig | undefined): void;
+declare function unstable_cache<Args extends unknown[], Result>(fn: (...args: Args) => Result | Promise<Result>, keyParts?: readonly unknown[], options?: FarmCacheOptions): (...args: Args) => Promise<Result>;
+declare function revalidateTag(_tag: string, _profile?: RevalidateTagProfile): void | Promise<void>;
+declare function updateTag(tag: string): void | Promise<void>;
+declare function revalidatePath(routePath: string): void | Promise<void>;
+declare function invalidate(key: RouteDataCacheKey): void | Promise<void>;
+declare function invalidateRouteData(key: RouteDataCacheKey): void | Promise<void>;
+/**
+ * Apply a normalized set of invalidation targets and return browser cache keys
+ * that should be carried with an action/endpoint response.
+ */
+declare function applyFarmCacheInvalidationTargets(targets: readonly FarmCacheInvalidationTarget[]): Promise<readonly string[]>;
+declare function createPathCacheTag(routePath: string): string;
+declare function createRouteDataCacheTag(key: RouteDataCacheKey): string;
+declare function createRouteDataCacheKey(key: RouteDataCacheKey): string;
+declare function normalizeRevalidatePath(routePath: string): string;
+declare function createFarmCacheKey(parts: readonly unknown[]): string;
+
+export { type CacheKeyFactory, type DefinedCacheKey, type FarmCacheAdapter, type FarmCacheEntry, type FarmCacheInvalidationTarget, type FarmCacheOptions, type FarmCacheSetOptions, type FarmCacheStorage, type FarmCacheUserConfig, FarmDataCache, type GetFarmCacheEntryOptions, type InferCacheKeyData, type RevalidateTagProfile, type RouteDataCacheKey, type StorageFarmCacheAdapterOptions, applyFarmCacheInvalidationTargets, applyFarmCacheInvalidations, configureFarmCache, createFarmCacheKey, createPathCacheTag, createRouteDataCacheKey, createRouteDataCacheTag, defineCacheKey, getFarmDataCache, invalidate, invalidateRouteData, normalizeRevalidatePath, revalidatePath, revalidateTag, storageCacheAdapter, unstable_cache, updateTag };