@farm.js/core 0.1.0-beta.14 → 0.1.0-beta.17

package/dist/observability.d.mts

@@ -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.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/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 };