@farm.js/core 0.1.0-beta.6 → 0.1.0-beta.8

package/dist/observability.d.ts

@@ -0,0 +1,335 @@
+type FarmEventLevel = "debug" | "info" | "warn" | "error";
+interface FarmEventBase {
+    type: string;
+    timestamp: number;
+    level: FarmEventLevel;
+    requestId?: string;
+    route?: string;
+    pathname?: string;
+}
+type FarmServerEvent = (FarmEventBase & {
+    type: "server.start";
+    mode: "dev" | "preview" | "production";
+    port?: number;
+}) | (FarmEventBase & {
+    type: "server.ready";
+    url?: string;
+}) | (FarmEventBase & {
+    type: "server.shutdown";
+    reason?: string;
+});
+type FarmRouteEvent = (FarmEventBase & {
+    type: "route.discovered";
+    route: string;
+    filePath: string;
+}) | (FarmEventBase & {
+    type: "route.matched";
+    pathname: string;
+    route: string;
+    params?: Record<string, string>;
+}) | (FarmEventBase & {
+    type: "route.notFound";
+    pathname: string;
+}) | (FarmEventBase & {
+    type: "route.redirect";
+    from: string;
+    to: string;
+    status?: number;
+}) | (FarmEventBase & {
+    type: "route.rewrite";
+    from: string;
+    to: string;
+});
+type FarmRenderEvent = (FarmEventBase & {
+    type: "render.start";
+    route: string;
+    pathname?: string;
+}) | (FarmEventBase & {
+    type: "render.complete";
+    route: string;
+    durationMs: number;
+    status?: number;
+}) | (FarmEventBase & {
+    type: "render.error";
+    route?: string;
+    error: unknown;
+}) | (FarmEventBase & {
+    type: "render.stream.start";
+    route: string;
+}) | (FarmEventBase & {
+    type: "render.stream.shellReady";
+    route: string;
+    durationMs: number;
+}) | (FarmEventBase & {
+    type: "render.stream.complete";
+    route: string;
+    durationMs: number;
+});
+type FarmCacheEvent = (FarmEventBase & {
+    type: "cache.hit";
+    key: string;
+    route?: string;
+    tags?: readonly string[];
+    revalidate?: number | false;
+    stale?: boolean;
+}) | (FarmEventBase & {
+    type: "cache.miss";
+    key: string;
+    route?: string;
+    reason?: string;
+}) | (FarmEventBase & {
+    type: "cache.set";
+    key: string;
+    route?: string;
+    tags?: readonly string[];
+    revalidate?: number | false;
+}) | (FarmEventBase & {
+    type: "cache.dedupe";
+    key: string;
+}) | (FarmEventBase & {
+    type: "cache.bypass";
+    key?: string;
+    route?: string;
+    reason: string;
+}) | (FarmEventBase & {
+    type: "cache.stale";
+    key: string;
+    route?: string;
+    tags?: readonly string[];
+    revalidate?: number | false;
+}) | (FarmEventBase & {
+    type: "cache.revalidatePath";
+    path: string;
+    count: number;
+}) | (FarmEventBase & {
+    type: "cache.revalidateTag";
+    tag: string;
+    profile?: unknown;
+    count: number;
+}) | (FarmEventBase & {
+    type: "cache.updateTag";
+    tag: string;
+    count: number;
+}) | (FarmEventBase & {
+    type: "cache.invalidated";
+    key?: string;
+    route?: string;
+    tag?: string;
+    reason?: string;
+    count?: number;
+}) | (FarmEventBase & {
+    type: "cache.delete";
+    key: string;
+    deleted: boolean;
+}) | (FarmEventBase & {
+    type: "cache.clear";
+    count: number;
+}) | (FarmEventBase & {
+    type: "cache.error";
+    key?: string;
+    operation: "get" | "set" | "delete" | "revalidate";
+    error: unknown;
+});
+type FarmPPREvent = (FarmEventBase & {
+    type: "ppr.shell.hit";
+    route: string;
+    key: string;
+}) | (FarmEventBase & {
+    type: "ppr.shell.miss";
+    route: string;
+    key: string;
+}) | (FarmEventBase & {
+    type: "ppr.shell.cached";
+    route: string;
+    key: string;
+    revalidate?: number;
+}) | (FarmEventBase & {
+    type: "ppr.shell.bypass";
+    route: string;
+    reason: string;
+}) | (FarmEventBase & {
+    type: "ppr.shell.invalidated";
+    route: string;
+    reason?: string;
+    count?: number;
+}) | (FarmEventBase & {
+    type: "ppr.suspense.holeDetected";
+    route: string;
+}) | (FarmEventBase & {
+    type: "ppr.refresh.start";
+    route: string;
+}) | (FarmEventBase & {
+    type: "ppr.refresh.complete";
+    route: string;
+    durationMs: number;
+}) | (FarmEventBase & {
+    type: "ppr.refresh.error";
+    route: string;
+    error: unknown;
+});
+type FarmAPIEvent = (FarmEventBase & {
+    type: "api.request.start";
+    route: string;
+    method: string;
+}) | (FarmEventBase & {
+    type: "api.request.complete";
+    route: string;
+    method: string;
+    status: number;
+    durationMs: number;
+}) | (FarmEventBase & {
+    type: "api.validation.failed";
+    route: string;
+    method: string;
+    issues?: unknown;
+}) | (FarmEventBase & {
+    type: "api.error";
+    route: string;
+    method: string;
+    error: unknown;
+});
+type FarmIntegrationEvent = (FarmEventBase & {
+    type: "integration.registered";
+    name: string;
+}) | (FarmEventBase & {
+    type: "integration.config.validated";
+    name: string;
+}) | (FarmEventBase & {
+    type: "integration.ready";
+    name: string;
+}) | (FarmEventBase & {
+    type: "integration.disposed";
+    name: string;
+}) | (FarmEventBase & {
+    type: "integration.api.call.start";
+    integration: string;
+    operation: string;
+}) | (FarmEventBase & {
+    type: "integration.api.call.complete";
+    integration: string;
+    operation: string;
+    durationMs: number;
+}) | (FarmEventBase & {
+    type: "integration.api.call.error";
+    integration: string;
+    operation: string;
+    error: unknown;
+}) | (FarmEventBase & {
+    type: "integration.webhook.received";
+    integration: string;
+    event?: string;
+}) | (FarmEventBase & {
+    type: "integration.webhook.verified";
+    integration: string;
+    event?: string;
+}) | (FarmEventBase & {
+    type: "integration.webhook.failed";
+    integration: string;
+    reason: string;
+});
+type FarmMiddlewareEvent = (FarmEventBase & {
+    type: "middleware.start";
+    route?: string;
+    name?: string;
+}) | (FarmEventBase & {
+    type: "middleware.complete";
+    route?: string;
+    name?: string;
+    durationMs: number;
+}) | (FarmEventBase & {
+    type: "middleware.shortCircuit";
+    route?: string;
+    name?: string;
+    status?: number;
+}) | (FarmEventBase & {
+    type: "middleware.error";
+    route?: string;
+    name?: string;
+    error: unknown;
+});
+type FarmStorageEvent = (FarmEventBase & {
+    type: "storage.query.start";
+    integration?: string;
+    operation: string;
+}) | (FarmEventBase & {
+    type: "storage.query.complete";
+    integration?: string;
+    operation: string;
+    durationMs: number;
+}) | (FarmEventBase & {
+    type: "storage.query.error";
+    integration?: string;
+    operation: string;
+    error: unknown;
+}) | (FarmEventBase & {
+    type: "storage.schema.ready";
+    integration?: string;
+}) | (FarmEventBase & {
+    type: "storage.schema.error";
+    integration?: string;
+    error: unknown;
+});
+type FarmBuildEvent = (FarmEventBase & {
+    type: "build.start";
+    target?: string;
+}) | (FarmEventBase & {
+    type: "build.complete";
+    target?: string;
+    durationMs: number;
+}) | (FarmEventBase & {
+    type: "build.error";
+    target?: string;
+    error: unknown;
+}) | (FarmEventBase & {
+    type: "routes.generated";
+    pageCount: number;
+    apiCount?: number;
+}) | (FarmEventBase & {
+    type: "types.generated";
+    filePath: string;
+}) | (FarmEventBase & {
+    type: "manifest.generated";
+    routeCount: number;
+});
+type FarmPluginEvent = (FarmEventBase & {
+    type: "plugin.hook.start";
+    plugin: string;
+    hook: string;
+}) | (FarmEventBase & {
+    type: "plugin.hook.complete";
+    plugin: string;
+    hook: string;
+    durationMs: number;
+}) | (FarmEventBase & {
+    type: "plugin.hook.error";
+    plugin: string;
+    hook: string;
+    error: unknown;
+});
+type FarmErrorEvent = FarmEventBase & {
+    type: "error";
+    source: string;
+    error: unknown;
+    route?: string;
+};
+type FarmEvent = FarmServerEvent | FarmRouteEvent | FarmRenderEvent | FarmCacheEvent | FarmPPREvent | FarmAPIEvent | FarmIntegrationEvent | FarmMiddlewareEvent | FarmStorageEvent | FarmBuildEvent | FarmPluginEvent | FarmErrorEvent;
+type FarmEventType = FarmEvent["type"];
+type FarmEventHandler = (event: FarmEvent) => void | Promise<void>;
+type FarmEventInput = FarmEvent extends infer T ? T extends FarmEvent ? Omit<T, "timestamp" | "level"> & Partial<Pick<T, "timestamp" | "level">> : never : never;
+type FarmObservabilityUserConfig = boolean | {
+    logs?: boolean;
+    onEvent?: FarmEventHandler | readonly FarmEventHandler[];
+    events?: readonly FarmEventType[];
+};
+interface FarmResolvedObservabilityConfig {
+    logs: boolean;
+    handlers: FarmEventHandler[];
+    events?: Set<FarmEventType>;
+}
+declare function configureFarmObservability(config: FarmObservabilityUserConfig | undefined): void;
+declare function normalizeFarmObservabilityConfig(config: FarmObservabilityUserConfig | undefined): FarmResolvedObservabilityConfig;
+declare function onFarmEvent(handler: FarmEventHandler): () => void;
+declare function resetFarmObservability(): void;
+declare function emitFarmEvent(input: FarmEventInput): FarmEvent;
+
+export { type FarmAPIEvent, type FarmBuildEvent, type FarmCacheEvent, type FarmErrorEvent, type FarmEvent, type FarmEventBase, type FarmEventHandler, type FarmEventInput, type FarmEventLevel, type FarmEventType, type FarmIntegrationEvent, type FarmMiddlewareEvent, type FarmObservabilityUserConfig, type FarmPPREvent, type FarmPluginEvent, type FarmRenderEvent, type FarmResolvedObservabilityConfig, type FarmRouteEvent, type FarmServerEvent, type FarmStorageEvent, configureFarmObservability, emitFarmEvent, normalizeFarmObservabilityConfig, onFarmEvent, resetFarmObservability };

package/dist/observability.mjs

@@ -0,0 +1,16 @@
+import {
+  configureFarmObservability,
+  emitFarmEvent,
+  normalizeFarmObservabilityConfig,
+  onFarmEvent,
+  resetFarmObservability
+} from "./chunk-7ZY5AIJO.mjs";
+import "./chunk-CGILA3WO.mjs";
+export {
+  configureFarmObservability,
+  emitFarmEvent,
+  normalizeFarmObservabilityConfig,
+  onFarmEvent,
+  resetFarmObservability
+};
+//# sourceMappingURL=observability.mjs.map

package/dist/observability.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/params-BALtrRim.d.ts

@@ -0,0 +1,15 @@
+import { Parser } from './query/parsers.js';
+
+type RouteParamsInput = Record<string, string | undefined> | URLSearchParams | Promise<Record<string, string | undefined> | URLSearchParams>;
+declare function loadRouteParams<T extends Record<string, Parser<any>>>(input: RouteParamsInput, parsers: T, options?: {
+    strict?: boolean;
+}): Promise<{
+    [K in keyof T]: ReturnType<T[K]["parse"]>;
+}>;
+declare function parseRouteParams<T extends Record<string, Parser<any>>>(input: Record<string, string | undefined> | URLSearchParams, parsers: T, options?: {
+    strict?: boolean;
+}): {
+    [K in keyof T]: ReturnType<T[K]["parse"]>;
+};
+
+export { type RouteParamsInput as R, loadRouteParams as l, parseRouteParams as p };

package/dist/params-ry-lxqmy.d.mts

@@ -0,0 +1,15 @@
+import { Parser } from './query/parsers.mjs';
+
+type RouteParamsInput = Record<string, string | undefined> | URLSearchParams | Promise<Record<string, string | undefined> | URLSearchParams>;
+declare function loadRouteParams<T extends Record<string, Parser<any>>>(input: RouteParamsInput, parsers: T, options?: {
+    strict?: boolean;
+}): Promise<{
+    [K in keyof T]: ReturnType<T[K]["parse"]>;
+}>;
+declare function parseRouteParams<T extends Record<string, Parser<any>>>(input: Record<string, string | undefined> | URLSearchParams, parsers: T, options?: {
+    strict?: boolean;
+}): {
+    [K in keyof T]: ReturnType<T[K]["parse"]>;
+};
+
+export { type RouteParamsInput as R, loadRouteParams as l, parseRouteParams as p };

package/dist/plugin-BJDf43dc.d.mts

@@ -0,0 +1,165 @@
+type MaybePromise<T> = T | Promise<T>;
+type FarmClientPluginEnforce = "pre" | "post";
+type FarmClientNavigationAction = "push" | "replace" | "pop";
+type FarmClientHydrationMode = "hydrate" | "render";
+interface FarmClientLocation {
+    href: string;
+    pathname: string;
+    search: string;
+    hash: string;
+}
+interface FarmClientPluginRouter {
+    navigate(href: string, options?: Record<string, unknown>): MaybePromise<void>;
+    prefetch?(href: string): MaybePromise<void>;
+    getNavigationState?(): unknown;
+}
+interface FarmClientPluginMetadata {
+    name: string;
+    version?: string;
+}
+interface FarmClientPluginSetupEvent<TPublic = undefined> {
+    plugin: FarmClientPluginMetadata;
+    public: Readonly<TPublic>;
+    router: FarmClientPluginRouter;
+    isDev: boolean;
+    isProd: boolean;
+    deploymentId?: string;
+}
+interface FarmClientPluginStateEvent<TState = unknown, TPublic = undefined> extends FarmClientPluginSetupEvent<TPublic> {
+    state: TState;
+}
+interface FarmClientHydrationSession {
+    container: Element;
+    location: FarmClientLocation;
+    mode: FarmClientHydrationMode;
+    startedAt: number;
+}
+interface FarmClientHydrationEvent<TState = unknown, TPublic = undefined> extends FarmClientPluginStateEvent<TState, TPublic>, FarmClientHydrationSession {
+}
+interface FarmClientHydrationCompleteEvent<TState = unknown, TPublic = undefined> extends FarmClientHydrationEvent<TState, TPublic> {
+    durationMs: number;
+    recovered: boolean;
+}
+interface FarmClientNavigationSession {
+    id: string;
+    from: FarmClientLocation | null;
+    to: FarmClientLocation;
+    action: FarmClientNavigationAction;
+    signal: AbortSignal;
+    startedAt: number;
+    route?: {
+        pattern?: string | null;
+        params?: Record<string, string>;
+    };
+}
+interface FarmClientNavigationEvent<TState = unknown, TPublic = undefined> extends FarmClientPluginStateEvent<TState, TPublic>, FarmClientNavigationSession {
+}
+interface FarmClientNavigationLoadedEvent<TState = unknown, TPublic = undefined> extends FarmClientNavigationEvent<TState, TPublic> {
+    durationMs: number;
+    data?: unknown;
+}
+interface FarmClientNavigationResolvedEvent<TState = unknown, TPublic = undefined> extends FarmClientNavigationEvent<TState, TPublic> {
+    durationMs: number;
+}
+interface FarmClientNavigationErrorEvent<TState = unknown, TPublic = undefined> extends FarmClientNavigationResolvedEvent<TState, TPublic> {
+    error: unknown;
+}
+type FarmClientPluginErrorPhase = "setup" | "hydration" | "navigation" | "window" | "unhandled-rejection" | "performance" | `plugin:${string}` | (string & {});
+interface FarmClientPluginErrorEvent<TState = unknown, TPublic = undefined> extends FarmClientPluginStateEvent<TState, TPublic> {
+    error: unknown;
+    phase: FarmClientPluginErrorPhase;
+    location: FarmClientLocation;
+    navigation?: FarmClientNavigationSession;
+}
+interface FarmClientPerformanceEvent<TState = unknown, TPublic = undefined> extends FarmClientPluginStateEvent<TState, TPublic> {
+    entry: PerformanceEntry;
+    location: FarmClientLocation;
+}
+interface FarmClientPluginCloseEvent<TState = unknown, TPublic = undefined> extends FarmClientPluginStateEvent<TState, TPublic> {
+    reason: "pagehide" | "hmr" | "manual" | (string & {});
+}
+interface FarmClientPlugin<TState = unknown, TPublic = undefined> {
+    setup?(event: FarmClientPluginSetupEvent<TPublic>): MaybePromise<TState>;
+    hydration?: {
+        before?(event: FarmClientHydrationEvent<TState, TPublic>): MaybePromise<void>;
+        after?(event: FarmClientHydrationCompleteEvent<TState, TPublic>): MaybePromise<void>;
+    };
+    navigation?: {
+        before?(event: FarmClientNavigationEvent<TState, TPublic>): MaybePromise<void>;
+        loaded?(event: FarmClientNavigationLoadedEvent<TState, TPublic>): MaybePromise<void>;
+        resolved?(event: FarmClientNavigationResolvedEvent<TState, TPublic>): MaybePromise<void>;
+        rendered?(event: FarmClientNavigationResolvedEvent<TState, TPublic>): MaybePromise<void>;
+        error?(event: FarmClientNavigationErrorEvent<TState, TPublic>): MaybePromise<void>;
+    };
+    error?(event: FarmClientPluginErrorEvent<TState, TPublic>): MaybePromise<void>;
+    performance?(event: FarmClientPerformanceEvent<TState, TPublic>): MaybePromise<void>;
+    close?(event: FarmClientPluginCloseEvent<TState, TPublic>): MaybePromise<void>;
+}
+interface FarmClientPluginRegistration<TPublic = undefined> {
+    name: string;
+    version?: string;
+    enforce?: FarmClientPluginEnforce;
+    definition: FarmClientPlugin<any, TPublic>;
+    public?: TPublic;
+}
+interface FarmClientPluginManagerOptions {
+    router: FarmClientPluginRouter;
+    isDev?: boolean;
+    isProd?: boolean;
+    deploymentId?: string;
+    window?: Window;
+}
+declare class FarmClientPluginManager {
+    private readonly registrations;
+    private readonly options;
+    private readonly instances;
+    private readonly performanceObservers;
+    private startPromise?;
+    private closePromise?;
+    private currentNavigation?;
+    private navigationSequence;
+    private starting;
+    private started;
+    private closed;
+    private readonly reportedErrors;
+    private readonly handleWindowError;
+    private readonly handleUnhandledRejection;
+    private readonly handlePageHide;
+    constructor(registrations: readonly FarmClientPluginRegistration[], options: FarmClientPluginManagerOptions);
+    start(): Promise<void>;
+    beginHydration(input: {
+        container: Element;
+        mode: FarmClientHydrationMode;
+    }): Promise<FarmClientHydrationSession>;
+    completeHydration(session: FarmClientHydrationSession, options?: {
+        recovered?: boolean;
+    }): Promise<void>;
+    failHydration(session: FarmClientHydrationSession, error: unknown): Promise<void>;
+    beginNavigation(input: {
+        from?: string | URL | FarmClientLocation | null;
+        to: string | URL | FarmClientLocation;
+        action: FarmClientNavigationAction;
+        route?: FarmClientNavigationSession["route"];
+    }): Promise<FarmClientNavigationSession>;
+    markNavigationLoaded(session: FarmClientNavigationSession, data?: unknown): Promise<void>;
+    resolveNavigation(session: FarmClientNavigationSession): Promise<void>;
+    scheduleNavigationRendered(session: FarmClientNavigationSession): Promise<void>;
+    failNavigation(session: FarmClientNavigationSession, error: unknown): Promise<void>;
+    reportError(error: unknown, phase: FarmClientPluginErrorPhase, navigation?: FarmClientNavigationSession, location?: FarmClientLocation): Promise<void>;
+    close(reason?: FarmClientPluginCloseEvent["reason"]): Promise<void>;
+    getPlugins(): readonly FarmClientPluginMetadata[];
+    private startInternal;
+    private installBrowserListeners;
+    private installPerformanceObservers;
+    private closeInternal;
+    private runHook;
+    private runErrorHooks;
+    private createSetupEvent;
+    private createStateEvent;
+    private getLocation;
+    private getBaseUrl;
+    private logHookError;
+}
+declare function createClientPluginManager(registrations: readonly FarmClientPluginRegistration[], options: FarmClientPluginManagerOptions): FarmClientPluginManager;
+
+export { FarmClientPluginManager as F, type FarmClientHydrationCompleteEvent as a, type FarmClientHydrationEvent as b, createClientPluginManager as c, type FarmClientHydrationMode as d, type FarmClientHydrationSession as e, type FarmClientLocation as f, type FarmClientNavigationAction as g, type FarmClientNavigationErrorEvent as h, type FarmClientNavigationEvent as i, type FarmClientNavigationLoadedEvent as j, type FarmClientNavigationResolvedEvent as k, type FarmClientNavigationSession as l, type FarmClientPerformanceEvent as m, type FarmClientPlugin as n, type FarmClientPluginCloseEvent as o, type FarmClientPluginEnforce as p, type FarmClientPluginErrorEvent as q, type FarmClientPluginErrorPhase as r, type FarmClientPluginManagerOptions as s, type FarmClientPluginMetadata as t, type FarmClientPluginRegistration as u, type FarmClientPluginRouter as v, type FarmClientPluginSetupEvent as w, type FarmClientPluginStateEvent as x };