@farm.js/core 0.1.61 → 0.1.62

package/dist/endpoint.d-BkMSCRf6.d.mts

@@ -0,0 +1,370 @@
+import { FarmCacheInvalidationTarget } from './cache.mjs';
+
+type MultipartField = string | number | boolean | bigint | Blob | Date | null | undefined;
+type MultipartValues = Record<string, MultipartField | readonly MultipartField[]>;
+/**
+ * A real FormData value that retains the submitted value shape for generated
+ * API-client inference.
+ */
+type TypedFormData<TValues> = FormData & {
+    readonly __farmMultipartInput: TValues;
+};
+type MultipartSchema<TSchema> = TSchema & {
+    readonly __farmMultipartSchema: true;
+};
+type FarmStreamResponse<TItem> = Response & {
+    readonly __farmStreamItem: TItem;
+};
+interface FarmAPIStream<TItem> extends AsyncIterable<TItem> {
+    readonly response: Response;
+    cancel(reason?: unknown): Promise<void>;
+}
+type SchemaLike = {
+    parse(data: unknown): unknown;
+};
+/**
+ * Mark a body schema as multipart. The handler still receives the schema's
+ * parsed object; generated clients require `toFormData(...)` for the request.
+ */
+declare function multipart<TSchema extends SchemaLike>(schema: TSchema): MultipartSchema<TSchema>;
+declare function isMultipartSchema(value: unknown): value is MultipartSchema<SchemaLike>;
+/**
+ * Encode a typed object as multipart FormData without converting File or Blob
+ * values to JSON or base64.
+ */
+declare function toFormData<TValues extends MultipartValues>(values: TValues): TypedFormData<TValues>;
+/**
+ * Stream JSON values as newline-delimited JSON. Each source value becomes one
+ * independently decodable item instead of buffering the whole response.
+ */
+declare function jsonStream<TItem>(source: AsyncIterable<TItem> | Iterable<TItem>, init?: ResponseInit): FarmStreamResponse<TItem>;
+declare function isJSONStreamResponse(response: {
+    headers?: Pick<Headers, "get"> | null;
+}): boolean;
+/**
+ * Decode a Farm JSON stream lazily. The response body is read only as the
+ * consumer advances the async iterator, preserving fetch backpressure.
+ */
+declare function readJSONStream<TItem>(response: Response): FarmAPIStream<TItem>;
+declare function isFarmAPIStream(value: unknown): value is FarmAPIStream<unknown>;
+
+/** Server-only schema contract shared by declarative routes and the API runtime. */
+interface RouteSchema {
+    readonly _input?: unknown;
+    readonly _output?: unknown;
+    parse?: (value: unknown) => unknown;
+    parseAsync?: (value: unknown) => Promise<unknown>;
+    readonly "~standard"?: {
+        readonly types?: {
+            input: unknown;
+            output: unknown;
+        };
+        validate(value: unknown): unknown;
+    };
+}
+type RouteSchemaInput<T> = T extends {
+    _input: infer I;
+} ? I : T extends {
+    "~standard": {
+        types?: {
+            input: infer I;
+        };
+    };
+} ? I : unknown;
+type RouteSchemaOutput<T> = T extends {
+    _output: infer O;
+} ? O : T extends {
+    "~standard": {
+        types?: {
+            output: infer O;
+        };
+    };
+} ? O : T extends {
+    parse: (...args: any[]) => infer O;
+} ? Awaited<O> : unknown;
+declare function parseRouteSchema(schema: RouteSchema, value: unknown): Promise<unknown>;
+
+type OpenAPISecurityMode = "public" | "bearer" | "cookie" | "either";
+type OpenAPISchema = Record<string, unknown>;
+type EndpointOpenAPIResponseMetadata = {
+    /** Human-readable description for this response. */
+    description?: string;
+    /** A JSON response. */
+    body: "json";
+    /** Override `application/json`. */
+    contentType?: string;
+    /** OpenAPI schema for the response body. Omit it when the shape is unknown. */
+    schema?: OpenAPISchema;
+} | {
+    /** Human-readable description for this response. */
+    description?: string;
+    /** A response with no body, such as 204 or an empty redirect. */
+    body: "empty";
+} | {
+    /** Human-readable description for this response. */
+    description?: string;
+    /** A streaming response. */
+    body: "stream";
+    /** Stream media type, for example `text/event-stream` or `application/x-ndjson`. */
+    contentType: string;
+    /** OpenAPI schema for each serialized response representation, when known. */
+    schema?: OpenAPISchema;
+} | {
+    /** Human-readable description for this response. */
+    description?: string;
+    /** A binary response. */
+    body: "binary";
+    /** Override `application/octet-stream`. */
+    contentType?: string;
+};
+interface EndpointOpenAPIMetadata {
+    /** Authentication requirement advertised for this operation. */
+    security?: OpenAPISecurityMode;
+    /** Known responses keyed by an HTTP status code or `default`. */
+    responses?: Partial<Record<`${number}` | "default", EndpointOpenAPIResponseMetadata>>;
+}
+
+type AnySchema = RouteSchema;
+type MaybePromise<T> = T | Promise<T>;
+type Simplify<T> = {
+    [TKey in keyof T]: T[TKey];
+} & {};
+type UnionToIntersection<T> = (T extends unknown ? (value: T) => void : never) extends (value: infer TIntersection) => void ? TIntersection : never;
+type InferOutput<T> = RouteSchemaOutput<T>;
+type InferInput<T> = T extends {
+    _input: infer I;
+} ? I : T extends {
+    "~standard": unknown;
+} ? RouteSchemaInput<T> : T extends {
+    parse: (data: infer I) => unknown;
+} ? I : unknown;
+type InferBodyInput<T> = T extends MultipartSchema<AnySchema> ? TypedFormData<InferInput<T>> : InferInput<T>;
+type InferHeadersOutput<T> = [T] extends [never] ? Record<string, string> : T extends AnySchema ? InferOutput<T> : Record<string, string>;
+type InferHeadersInput<T> = [T] extends [never] ? never : InferInput<T>;
+type EndpointErrorSchema = AnySchema & {
+    parse: (data: unknown) => unknown;
+};
+type EndpointErrorDefinitionBase<TStatus extends number> = {
+    status: TStatus;
+    /** Public message safe to expose to API callers. */
+    message?: string;
+};
+type EndpointErrorDefinition<TSchema extends EndpointErrorSchema = EndpointErrorSchema, TStatus extends number = number> = EndpointErrorDefinitionBase<TStatus> & ({
+    /** Schema for the public error payload exposed to API callers. */
+    data: TSchema;
+    schema?: never;
+} | {
+    data?: never;
+    /** @deprecated Use `data` for consistency with server functions. */
+    schema: TSchema;
+});
+type EndpointErrorDefinitions = Record<string, EndpointErrorDefinition<EndpointErrorSchema, number>>;
+type InferEndpointErrorSchema<TDefinition> = TDefinition extends {
+    data: infer TSchema extends AnySchema;
+} ? TSchema : TDefinition extends {
+    schema: infer TSchema extends AnySchema;
+} ? TSchema : never;
+type EndpointErrorContracts<TErrors extends EndpointErrorDefinitions> = {
+    [TCode in keyof TErrors]: {
+        data: InferOutput<InferEndpointErrorSchema<TErrors[TCode]>>;
+        status: TErrors[TCode]["status"];
+    };
+};
+type EndpointErrorHandler<TErrors extends EndpointErrorDefinitions> = <TCode extends keyof TErrors & string>(code: TCode, data: InferInput<InferEndpointErrorSchema<TErrors[TCode]>>) => never;
+/** @deprecated Use `EndpointErrorHandler`. */
+type EndpointFail<TErrors extends EndpointErrorDefinitions> = EndpointErrorHandler<TErrors>;
+declare class EndpointFailure<TCode extends string = string, TData = unknown> extends Error {
+    readonly code: TCode;
+    readonly data: TData;
+    readonly status: number;
+    constructor(code: TCode, data: TData, options: {
+        status: number;
+        message: string;
+    });
+}
+declare function isEndpointFailure(value: unknown): value is EndpointFailure<string, unknown>;
+type EndpointParamValue = string | string[];
+type EndpointParams = Record<string, EndpointParamValue>;
+type EndpointMiddlewareContext<TContext extends object = {}, TBody = unknown, TQuery = unknown, THeaders = Record<string, string>> = {
+    body: TBody;
+    query: TQuery;
+    headers: THeaders;
+    request: Request;
+    /** Context accumulated from middleware that ran earlier in the chain. */
+    context: Readonly<TContext>;
+    params: EndpointParams;
+};
+type EndpointMiddlewareResult<TProvidedContext extends object = object> = TProvidedContext | true | false | Response;
+/** A plain async function. No wrapper or `next()` callback is required. */
+type EndpointMiddleware<TProvidedContext extends object = object, TContext extends object = {}, TBody = unknown, TQuery = unknown, THeaders = Record<string, string>> = (ctx: EndpointMiddlewareContext<TContext, TBody, TQuery, THeaders>) => MaybePromise<EndpointMiddlewareResult<TProvidedContext>>;
+type AnyEndpointMiddleware = (ctx: EndpointMiddlewareContext<any, any, any, any>) => unknown;
+type EndpointInvalidationTarget = FarmCacheInvalidationTarget;
+type EndpointInvalidationContext<TContext extends object = {}, TBody = unknown, TQuery = unknown, THeaders = Record<string, string>> = EndpointMiddlewareContext<TContext, TBody, TQuery, THeaders> & {
+    /** The raw value returned by the endpoint handler. */
+    result: unknown;
+};
+type EndpointInvalidations<TContext extends object = {}, TBody = unknown, TQuery = unknown, THeaders = Record<string, string>> = readonly EndpointInvalidationTarget[] | ((context: EndpointInvalidationContext<TContext, TBody, TQuery, THeaders>) => readonly EndpointInvalidationTarget[] | Promise<readonly EndpointInvalidationTarget[]>);
+/** Metadata used when an installed MCP transport exposes this endpoint as a tool. */
+interface EndpointMCPMetadata {
+    /** Optional MCP tool name. Farm derives one from the method and path when omitted. */
+    name?: string;
+    title?: string;
+    description?: string;
+    readOnlyHint?: boolean;
+    destructiveHint?: boolean;
+    idempotentHint?: boolean;
+    openWorldHint?: boolean;
+}
+/** Opt an endpoint into MCP discovery with derived or explicit tool metadata. */
+type EndpointMCPOptions = true | EndpointMCPMetadata;
+type ValidateEndpointMiddlewares<TMiddlewares extends readonly AnyEndpointMiddleware[]> = {
+    readonly [TIndex in keyof TMiddlewares]: TMiddlewares[TIndex] extends AnyEndpointMiddleware ? [Awaited<ReturnType<TMiddlewares[TIndex]>>] extends [EndpointMiddlewareResult<object>] ? TMiddlewares[TIndex] : never : never;
+};
+type ContextFromMiddlewareResult<TResult> = Exclude<TResult, Response | boolean> extends infer TContext ? [TContext] extends [never] ? {} : TContext extends object ? TContext : {} : {};
+type ContextFromMiddleware<TMiddleware> = TMiddleware extends (...args: any[]) => infer TResult ? ContextFromMiddlewareResult<Awaited<TResult>> : {};
+type InferEndpointMiddlewareContext<TMiddlewares extends readonly ((...args: any[]) => any)[], TContext extends object = {}> = TMiddlewares extends readonly [infer TMiddleware, ...infer TRest] ? TMiddleware extends (...args: any[]) => any ? TRest extends readonly ((...args: any[]) => any)[] ? InferEndpointMiddlewareContext<TRest, Simplify<TContext & ContextFromMiddleware<TMiddleware>>> : Simplify<TContext> : Simplify<TContext> : number extends TMiddlewares["length"] ? Simplify<TContext & UnionToIntersection<ContextFromMiddleware<TMiddlewares[number]>>> : Simplify<TContext>;
+type EndpointOptions<TBody extends AnySchema = never, TQuery extends AnySchema = never, THeaders extends AnySchema = never, TMiddlewares extends readonly AnyEndpointMiddleware[] = readonly [], TErrors extends EndpointErrorDefinitions = {}> = {
+    method?: "GET" | "HEAD" | "QUERY" | "POST" | "PUT" | "DELETE" | "PATCH" | "OPTIONS";
+    body?: TBody;
+    query?: TQuery;
+    headers?: THeaders;
+    middleware?: TMiddlewares;
+    /**
+     * Cache keys, tags, and route paths made stale after a successful handler result.
+     * The resolver receives validated input and middleware context.
+     */
+    invalidates?: EndpointInvalidations<InferEndpointMiddlewareContext<TMiddlewares>, InferOutput<TBody>, InferOutput<TQuery>, InferHeadersOutput<THeaders>>;
+    errors?: TErrors;
+    /** OpenAPI-only operation metadata. This does not enforce authentication at runtime. */
+    openapi?: EndpointOpenAPIMetadata;
+    /**
+     * Opt this endpoint into an installed MCP transport. This is discovery metadata only;
+     * transport and endpoint authorization remain required separately.
+     */
+    mcp?: EndpointMCPOptions;
+    /**
+     * @deprecated Not supported: Farm never ran `use` middleware, so `createEndpoint` throws
+     * when it is set. Put plain functions in `middleware` instead.
+     */
+    use?: never;
+};
+type EndpointHandler<TBody extends AnySchema = never, TQuery extends AnySchema = never, THeaders extends AnySchema = never, TResponse = any, TContext extends object = {}, TErrors extends EndpointErrorDefinitions = {}> = (ctx: {
+    body: InferOutput<TBody>;
+    query: InferOutput<TQuery>;
+    headers: InferHeadersOutput<THeaders>;
+    request: Request;
+    context: Readonly<TContext>;
+    params: EndpointParams;
+    error: EndpointErrorHandler<TErrors>;
+    /** @deprecated Use `error`. */
+    fail: EndpointFail<TErrors>;
+}) => Promise<TResponse> | TResponse;
+type TypedEndpoint<TBody = never, TQuery = never, TResponse = any, THeaders = Record<string, string>, TErrors = never, TBodyInput = TBody, TQueryInput = TQuery, THeadersInput = THeaders> = {
+    __types: {
+        body: TBody;
+        inputBody: TBodyInput;
+        query: TQuery;
+        inputQuery: TQueryInput;
+        headers: THeaders;
+        inputHeaders: THeadersInput;
+        response: TResponse;
+        errors: TErrors;
+    };
+    __path?: string;
+    __method?: string;
+    __openapi?: EndpointOpenAPIMetadata;
+    __mcp?: EndpointMCPOptions;
+} & ((options?: {
+    body?: TBodyInput;
+    query?: TQueryInput;
+    headers?: THeadersInput;
+}) => Promise<TResponse>);
+type CreatedEndpoint<TBody extends AnySchema, TQuery extends AnySchema, THeaders extends AnySchema, TResponse, TErrors extends EndpointErrorDefinitions = {}> = TypedEndpoint<InferOutput<TBody>, InferOutput<TQuery>, Awaited<TResponse>, InferHeadersOutput<THeaders>, EndpointErrorContracts<TErrors>, InferBodyInput<TBody>, InferInput<TQuery>, InferHeadersInput<THeaders>>;
+type AnyEndpointOptions = EndpointOptions<AnySchema, AnySchema, AnySchema, readonly AnyEndpointMiddleware[], EndpointErrorDefinitions>;
+type EndpointBodyFromOptions<TOptions> = TOptions extends {
+    body: infer TBody extends AnySchema;
+} ? TBody : never;
+type EndpointQueryFromOptions<TOptions> = TOptions extends {
+    query: infer TQuery extends AnySchema;
+} ? TQuery : never;
+type EndpointHeadersFromOptions<TOptions> = TOptions extends {
+    headers: infer THeaders extends AnySchema;
+} ? THeaders : never;
+type EndpointMiddlewaresFromOptions<TOptions> = TOptions extends {
+    middleware: infer TMiddlewares extends readonly AnyEndpointMiddleware[];
+} ? TMiddlewares : readonly [];
+type EndpointErrorsFromOptions<TOptions> = TOptions extends {
+    errors: infer TErrors extends EndpointErrorDefinitions;
+} ? TErrors : {};
+type MethodlessEndpointOptions = Omit<AnyEndpointOptions, "method">;
+type EndpointHandlerFromOptions<TOptions, TResponse> = EndpointHandler<EndpointBodyFromOptions<TOptions>, EndpointQueryFromOptions<TOptions>, EndpointHeadersFromOptions<TOptions>, TResponse, InferEndpointMiddlewareContext<EndpointMiddlewaresFromOptions<TOptions>>, EndpointErrorsFromOptions<TOptions>>;
+type ValidatedEndpointHandlerFromOptions<TOptions, TResponse> = EndpointHandlerFromOptions<TOptions, TResponse> & (EndpointMiddlewaresFromOptions<TOptions> extends ValidateEndpointMiddlewares<EndpointMiddlewaresFromOptions<TOptions>> ? unknown : never);
+type CreatedEndpointFromOptions<TOptions, TResponse> = CreatedEndpoint<EndpointBodyFromOptions<TOptions>, EndpointQueryFromOptions<TOptions>, EndpointHeadersFromOptions<TOptions>, TResponse, EndpointErrorsFromOptions<TOptions>>;
+/**
+ * Create a Farm.js API endpoint
+ *
+ * Supports two patterns:
+ * 1. File-based routing (path auto-inferred from file location). The export name
+ *    (`GET`, `POST`, ...) is the HTTP method, so `method` can be omitted:
+ *    `export const GET = createEndpoint(handler)`
+ *    `export const POST = createEndpoint({ body: schema }, handler)`
+ *
+ * 2. Explicit path (for routes.ts at project root), where `method` selects the
+ *    HTTP method and defaults to GET:
+ *    `createEndpoint('/api/hello', { method: 'POST', body: schema }, handler)`
+ */
+declare function createEndpoint<TResponse = any>(handler: EndpointHandler<never, never, never, TResponse>): CreatedEndpoint<never, never, never, TResponse>;
+declare function createEndpoint<const TOptions extends AnyEndpointOptions, TResponse = any>(options: TOptions, handler: ValidatedEndpointHandlerFromOptions<TOptions, TResponse>): CreatedEndpointFromOptions<TOptions, TResponse>;
+declare function createEndpoint<const TOptions extends AnyEndpointOptions, TResponse = any>(path: string, options: TOptions, handler: ValidatedEndpointHandlerFromOptions<TOptions, TResponse>): CreatedEndpointFromOptions<TOptions, TResponse>;
+declare function createEndpoint<TBody extends AnySchema = never, TQuery extends AnySchema = never, THeaders extends AnySchema = never, TResponse = any>(options: EndpointOptions<TBody, TQuery, THeaders, readonly []>, handler: EndpointHandler<TBody, TQuery, THeaders, TResponse>): CreatedEndpoint<TBody, TQuery, THeaders, TResponse>;
+declare function createEndpoint<TBody extends AnySchema = never, TQuery extends AnySchema = never, THeaders extends AnySchema = never, TResponse = any>(path: string, options: EndpointOptions<TBody, TQuery, THeaders, readonly []>, handler: EndpointHandler<TBody, TQuery, THeaders, TResponse>): CreatedEndpoint<TBody, TQuery, THeaders, TResponse>;
+/**
+ * Convenience method for GET requests
+ */
+declare function GET<T = any>(handler: EndpointHandler<never, never, never, T>): CreatedEndpoint<never, never, never, T>;
+declare function GET<const TOptions extends MethodlessEndpointOptions, TResponse = any>(options: TOptions, handler: ValidatedEndpointHandlerFromOptions<TOptions, TResponse>): CreatedEndpointFromOptions<TOptions, TResponse>;
+declare function GET<TQuery extends AnySchema = never, THeaders extends AnySchema = never, TResponse = any>(options: Omit<EndpointOptions<never, TQuery, THeaders, readonly []>, "method">, handler: EndpointHandler<never, TQuery, THeaders, TResponse>): CreatedEndpoint<never, TQuery, THeaders, TResponse>;
+/**
+ * Convenience method for HEAD requests
+ */
+declare function HEAD<T = any>(handler: EndpointHandler<never, never, never, T>): CreatedEndpoint<never, never, never, T>;
+declare function HEAD<const TOptions extends MethodlessEndpointOptions, TResponse = any>(options: TOptions, handler: ValidatedEndpointHandlerFromOptions<TOptions, TResponse>): CreatedEndpointFromOptions<TOptions, TResponse>;
+declare function HEAD<TQuery extends AnySchema = never, THeaders extends AnySchema = never, TResponse = any>(options: Omit<EndpointOptions<never, TQuery, THeaders, readonly []>, "method">, handler: EndpointHandler<never, TQuery, THeaders, TResponse>): CreatedEndpoint<never, TQuery, THeaders, TResponse>;
+/**
+ * Convenience method for safe, idempotent QUERY requests with a request body
+ */
+declare function QUERY<T = any>(handler: EndpointHandler<never, never, never, T>): CreatedEndpoint<never, never, never, T>;
+declare function QUERY<const TOptions extends MethodlessEndpointOptions, TResponse = any>(options: TOptions, handler: ValidatedEndpointHandlerFromOptions<TOptions, TResponse>): CreatedEndpointFromOptions<TOptions, TResponse>;
+declare function QUERY<TBody extends AnySchema = never, TQuery extends AnySchema = never, THeaders extends AnySchema = never, TResponse = any>(options: Omit<EndpointOptions<TBody, TQuery, THeaders, readonly []>, "method">, handler: EndpointHandler<TBody, TQuery, THeaders, TResponse>): CreatedEndpoint<TBody, TQuery, THeaders, TResponse>;
+/**
+ * Convenience method for POST requests
+ */
+declare function POST<T = any>(handler: EndpointHandler<never, never, never, T>): CreatedEndpoint<never, never, never, T>;
+declare function POST<const TOptions extends MethodlessEndpointOptions, TResponse = any>(options: TOptions, handler: ValidatedEndpointHandlerFromOptions<TOptions, TResponse>): CreatedEndpointFromOptions<TOptions, TResponse>;
+declare function POST<TBody extends AnySchema = never, TQuery extends AnySchema = never, THeaders extends AnySchema = never, TResponse = any>(options: Omit<EndpointOptions<TBody, TQuery, THeaders, readonly []>, "method">, handler: EndpointHandler<TBody, TQuery, THeaders, TResponse>): CreatedEndpoint<TBody, TQuery, THeaders, TResponse>;
+/**
+ * Convenience method for PUT requests
+ */
+declare function PUT<T = any>(handler: EndpointHandler<never, never, never, T>): CreatedEndpoint<never, never, never, T>;
+declare function PUT<const TOptions extends MethodlessEndpointOptions, TResponse = any>(options: TOptions, handler: ValidatedEndpointHandlerFromOptions<TOptions, TResponse>): CreatedEndpointFromOptions<TOptions, TResponse>;
+declare function PUT<TBody extends AnySchema = never, TQuery extends AnySchema = never, THeaders extends AnySchema = never, TResponse = any>(options: Omit<EndpointOptions<TBody, TQuery, THeaders, readonly []>, "method">, handler: EndpointHandler<TBody, TQuery, THeaders, TResponse>): CreatedEndpoint<TBody, TQuery, THeaders, TResponse>;
+/**
+ * Convenience method for DELETE requests
+ */
+declare function DELETE<T = any>(handler: EndpointHandler<never, never, never, T>): CreatedEndpoint<never, never, never, T>;
+declare function DELETE<const TOptions extends MethodlessEndpointOptions, TResponse = any>(options: TOptions, handler: ValidatedEndpointHandlerFromOptions<TOptions, TResponse>): CreatedEndpointFromOptions<TOptions, TResponse>;
+declare function DELETE<TBody extends AnySchema = never, TQuery extends AnySchema = never, THeaders extends AnySchema = never, TResponse = any>(options: Omit<EndpointOptions<TBody, TQuery, THeaders, readonly []>, "method">, handler: EndpointHandler<TBody, TQuery, THeaders, TResponse>): CreatedEndpoint<TBody, TQuery, THeaders, TResponse>;
+/**
+ * Convenience method for PATCH requests
+ */
+declare function PATCH<T = any>(handler: EndpointHandler<never, never, never, T>): CreatedEndpoint<never, never, never, T>;
+declare function PATCH<const TOptions extends MethodlessEndpointOptions, TResponse = any>(options: TOptions, handler: ValidatedEndpointHandlerFromOptions<TOptions, TResponse>): CreatedEndpointFromOptions<TOptions, TResponse>;
+declare function PATCH<TBody extends AnySchema = never, TQuery extends AnySchema = never, THeaders extends AnySchema = never, TResponse = any>(options: Omit<EndpointOptions<TBody, TQuery, THeaders, readonly []>, "method">, handler: EndpointHandler<TBody, TQuery, THeaders, TResponse>): CreatedEndpoint<TBody, TQuery, THeaders, TResponse>;
+/**
+ * Convenience method for OPTIONS requests
+ */
+declare function OPTIONS<T = any>(handler: EndpointHandler<never, never, never, T>): CreatedEndpoint<never, never, never, T>;
+declare function OPTIONS<const TOptions extends MethodlessEndpointOptions, TResponse = any>(options: TOptions, handler: ValidatedEndpointHandlerFromOptions<TOptions, TResponse>): CreatedEndpointFromOptions<TOptions, TResponse>;
+declare function OPTIONS<TBody extends AnySchema = never, TQuery extends AnySchema = never, THeaders extends AnySchema = never, TResponse = any>(options: Omit<EndpointOptions<TBody, TQuery, THeaders, readonly []>, "method">, handler: EndpointHandler<TBody, TQuery, THeaders, TResponse>): CreatedEndpoint<TBody, TQuery, THeaders, TResponse>;
+
+export { type AnyEndpointMiddleware as A, POST as B, PUT as C, DELETE as D, type EndpointMCPMetadata as E, type FarmAPIStream as F, GET as G, HEAD as H, type InferEndpointMiddlewareContext as I, type TypedFormData as J, createEndpoint as K, isFarmAPIStream as L, type MultipartField as M, isJSONStreamResponse as N, OPTIONS as O, PATCH as P, QUERY as Q, type RouteSchema as R, isMultipartSchema as S, type TypedEndpoint as T, jsonStream as U, multipart as V, readJSONStream as W, toFormData as X, type OpenAPISecurityMode as Y, type EndpointMCPOptions as a, type EndpointOpenAPIMetadata as b, type EndpointMiddlewareResult as c, type RouteSchemaOutput as d, type RouteSchemaInput as e, EndpointFailure as f, type EndpointErrorContracts as g, type EndpointErrorDefinition as h, isEndpointFailure as i, type EndpointErrorDefinitions as j, type EndpointErrorHandler as k, type EndpointErrorSchema as l, type EndpointFail as m, type EndpointHandler as n, type EndpointInvalidationContext as o, parseRouteSchema as p, type EndpointInvalidationTarget as q, type EndpointInvalidations as r, type EndpointMiddleware as s, type EndpointMiddlewareContext as t, type EndpointOptions as u, type EndpointParamValue as v, type EndpointParams as w, type FarmStreamResponse as x, type MultipartSchema as y, type MultipartValues as z };

package/dist/env-types.cjs

@@ -1,10 +1,10 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true});
 
 
-var _chunk6EODJYCXcjs = require('./chunk-6EODJYCX.cjs');
-require('./chunk-TIWHTW3Q.cjs');
-require('./chunk-S3JO3N4H.cjs');
+var _chunkGSVJ3IIFcjs = require('./chunk-GSVJ3IIF.cjs');
+require('./chunk-5YPBFMBN.cjs');
+require('./chunk-BTZ5O6VM.cjs');
 
 
 
-exports.createEnvTypeDeclarations = _chunk6EODJYCXcjs.createEnvTypeDeclarations; exports.generateEnvTypes = _chunk6EODJYCXcjs.generateEnvTypes;
+exports.createEnvTypeDeclarations = _chunkGSVJ3IIFcjs.createEnvTypeDeclarations; exports.generateEnvTypes = _chunkGSVJ3IIFcjs.generateEnvTypes;

package/dist/env-types.d.mts

@@ -0,0 +1,12 @@
+interface GenerateEnvTypesOptions {
+    root: string;
+    srcDir?: string;
+    outFile?: string;
+    configPath?: string;
+    /** Lower-priority layer config files, ordered before the project config. */
+    layerConfigPaths?: readonly string[];
+}
+declare function generateEnvTypes(options: GenerateEnvTypesOptions): Promise<string>;
+declare function createEnvTypeDeclarations(options: GenerateEnvTypesOptions, outPath: string): string;
+
+export { type GenerateEnvTypesOptions, createEnvTypeDeclarations, generateEnvTypes };

package/dist/env-types.d.ts

@@ -0,0 +1,12 @@
+interface GenerateEnvTypesOptions {
+    root: string;
+    srcDir?: string;
+    outFile?: string;
+    configPath?: string;
+    /** Lower-priority layer config files, ordered before the project config. */
+    layerConfigPaths?: readonly string[];
+}
+declare function generateEnvTypes(options: GenerateEnvTypesOptions): Promise<string>;
+declare function createEnvTypeDeclarations(options: GenerateEnvTypesOptions, outPath: string): string;
+
+export { type GenerateEnvTypesOptions, createEnvTypeDeclarations, generateEnvTypes };

package/dist/env-types.mjs

@@ -1,9 +1,9 @@
 import {
   createEnvTypeDeclarations,
   generateEnvTypes
-} from "./chunk-45ZSJLDT.mjs";
-import "./chunk-4JCQDWPX.mjs";
-import "./chunk-LPEX4YW6.mjs";
+} from "./chunk-TUPKMMXT.mjs";
+import "./chunk-Q5B4LNON.mjs";
+import "./chunk-Y6FXYEAI.mjs";
 export {
   createEnvTypeDeclarations,
   generateEnvTypes

package/dist/env.cjs

@@ -8,9 +8,9 @@
 
 
 
-var _chunkVEKFLAQMcjs = require('./chunk-VEKFLAQM.cjs');
-require('./chunk-CMGMGHUZ.cjs');
-require('./chunk-S3JO3N4H.cjs');
+var _chunk3EIPOTZVcjs = require('./chunk-3EIPOTZV.cjs');
+require('./chunk-2KMIJDY6.cjs');
+require('./chunk-BTZ5O6VM.cjs');
 
 
 
@@ -21,4 +21,4 @@ require('./chunk-S3JO3N4H.cjs');
 
 
 
-exports.createBundledEnv = _chunkVEKFLAQMcjs.createBundledEnv; exports.env = _chunkVEKFLAQMcjs.env; exports.getEnv = _chunkVEKFLAQMcjs.getEnv; exports.getPublicEnv = _chunkVEKFLAQMcjs.getPublicEnv; exports.getResolvedEnv = _chunkVEKFLAQMcjs.getResolvedEnv; exports.publicEnv = _chunkVEKFLAQMcjs.publicEnv; exports.resolveEnv = _chunkVEKFLAQMcjs.resolveEnv; exports.serverEnv = _chunkVEKFLAQMcjs.serverEnv; exports.setEnv = _chunkVEKFLAQMcjs.setEnv;
+exports.createBundledEnv = _chunk3EIPOTZVcjs.createBundledEnv; exports.env = _chunk3EIPOTZVcjs.env; exports.getEnv = _chunk3EIPOTZVcjs.getEnv; exports.getPublicEnv = _chunk3EIPOTZVcjs.getPublicEnv; exports.getResolvedEnv = _chunk3EIPOTZVcjs.getResolvedEnv; exports.publicEnv = _chunk3EIPOTZVcjs.publicEnv; exports.resolveEnv = _chunk3EIPOTZVcjs.resolveEnv; exports.serverEnv = _chunk3EIPOTZVcjs.serverEnv; exports.setEnv = _chunk3EIPOTZVcjs.setEnv;

package/dist/env.d.mts

@@ -0,0 +1,65 @@
+interface EnvSchema<TOutput = unknown> {
+    parse(value: unknown): TOutput;
+}
+type EnvParser<TOutput = unknown> = EnvSchema<TOutput> | ((value: string | undefined, context: {
+    key: string;
+    scope: "server" | "public";
+}) => TOutput);
+type EnvShape = Record<string, EnvParser<any>>;
+type InferEnvParser<TParser> = TParser extends EnvSchema<infer TOutput> ? TOutput : TParser extends (value: string | undefined, context: any) => infer TOutput ? TOutput : never;
+type InferEnvShape<TShape> = TShape extends EnvShape ? {
+    [K in keyof TShape]: InferEnvParser<TShape[K]>;
+} : {};
+interface FarmEnvConfig<TServer extends EnvShape = EnvShape, TPublic extends EnvShape = EnvShape> {
+    server?: TServer;
+    public?: TPublic;
+}
+interface ResolvedFarmEnv<TServer extends Record<string, any> = Record<string, unknown>, TPublic extends Record<string, any> = Record<string, unknown>> {
+    server: TServer;
+    public: TPublic;
+}
+type InferEnv<TConfig> = TConfig extends FarmEnvConfig<infer TServer, infer TPublic> ? ResolvedFarmEnv<InferEnvShape<TServer>, InferEnvShape<TPublic>> : ResolvedFarmEnv;
+/**
+ * Augmented by generated src/farm.d.ts for project-specific autocomplete.
+ */
+interface FarmEnvTypes {
+}
+type FarmServerEnv = FarmEnvTypes extends {
+    server: infer TServer;
+} ? TServer extends Record<string, any> ? TServer : Record<string, unknown> : Record<string, unknown>;
+type FarmPublicEnv = FarmEnvTypes extends {
+    public: infer TPublic;
+} ? TPublic extends Record<string, any> ? TPublic : Record<string, unknown> : Record<string, unknown>;
+type FarmTypedEnv = ResolvedFarmEnv<FarmServerEnv, FarmPublicEnv>;
+type FarmEnvRuntimeType = "string" | "number" | "boolean" | "json";
+/**
+ * The env a server bundle carries. `runtime.server` lists server keys that are
+ * read from the server's environment instead of being stored in the bundle,
+ * with the type their parsed value had at build time.
+ */
+interface BundledFarmEnv extends ResolvedFarmEnv {
+    runtime?: {
+        server: Record<string, FarmEnvRuntimeType>;
+    };
+}
+declare function resolveEnv<TConfig extends FarmEnvConfig<any, any> | undefined>(config: TConfig, source?: Record<string, string | undefined>): InferEnv<NonNullable<TConfig>>;
+/**
+ * Prepare resolved env for a server bundle. Server values that came from the
+ * build environment are left out and read from the server's environment when
+ * the server uses them, so secrets never land in build output and a restart
+ * picks up a rotated value. Values a parser produced without an env var
+ * (defaults) stay, and so do values the runtime cannot rebuild from the raw
+ * string, because the parser itself does not run in the server bundle.
+ */
+declare function createBundledEnv(env: ResolvedFarmEnv | FarmEnvConfig<any, any> | undefined, source?: Record<string, string | undefined>): BundledFarmEnv;
+declare function setEnv(env: ResolvedFarmEnv | BundledFarmEnv): void;
+declare function getResolvedEnv<TEnv extends ResolvedFarmEnv = FarmTypedEnv>(): TEnv;
+declare function getEnv<TServer extends Record<string, any> = FarmServerEnv>(): TServer;
+declare function getEnv<TKey extends Extract<keyof FarmServerEnv, string>>(key: TKey): FarmServerEnv[TKey];
+declare function getPublicEnv<TPublic extends Record<string, any> = FarmPublicEnv>(): TPublic;
+declare function getPublicEnv<TKey extends Extract<keyof FarmPublicEnv, string>>(key: TKey): FarmPublicEnv[TKey];
+declare const env: FarmServerEnv;
+declare const serverEnv: Record<string, unknown>;
+declare const publicEnv: FarmPublicEnv;
+
+export { type BundledFarmEnv, type EnvParser, type EnvSchema, type EnvShape, type FarmEnvConfig, type FarmEnvRuntimeType, type FarmEnvTypes, type FarmPublicEnv, type FarmServerEnv, type FarmTypedEnv, type InferEnv, type InferEnvParser, type InferEnvShape, type ResolvedFarmEnv, createBundledEnv, env, getEnv, getPublicEnv, getResolvedEnv, publicEnv, resolveEnv, serverEnv, setEnv };

package/dist/env.d.ts

@@ -0,0 +1,65 @@
+interface EnvSchema<TOutput = unknown> {
+    parse(value: unknown): TOutput;
+}
+type EnvParser<TOutput = unknown> = EnvSchema<TOutput> | ((value: string | undefined, context: {
+    key: string;
+    scope: "server" | "public";
+}) => TOutput);
+type EnvShape = Record<string, EnvParser<any>>;
+type InferEnvParser<TParser> = TParser extends EnvSchema<infer TOutput> ? TOutput : TParser extends (value: string | undefined, context: any) => infer TOutput ? TOutput : never;
+type InferEnvShape<TShape> = TShape extends EnvShape ? {
+    [K in keyof TShape]: InferEnvParser<TShape[K]>;
+} : {};
+interface FarmEnvConfig<TServer extends EnvShape = EnvShape, TPublic extends EnvShape = EnvShape> {
+    server?: TServer;
+    public?: TPublic;
+}
+interface ResolvedFarmEnv<TServer extends Record<string, any> = Record<string, unknown>, TPublic extends Record<string, any> = Record<string, unknown>> {
+    server: TServer;
+    public: TPublic;
+}
+type InferEnv<TConfig> = TConfig extends FarmEnvConfig<infer TServer, infer TPublic> ? ResolvedFarmEnv<InferEnvShape<TServer>, InferEnvShape<TPublic>> : ResolvedFarmEnv;
+/**
+ * Augmented by generated src/farm.d.ts for project-specific autocomplete.
+ */
+interface FarmEnvTypes {
+}
+type FarmServerEnv = FarmEnvTypes extends {
+    server: infer TServer;
+} ? TServer extends Record<string, any> ? TServer : Record<string, unknown> : Record<string, unknown>;
+type FarmPublicEnv = FarmEnvTypes extends {
+    public: infer TPublic;
+} ? TPublic extends Record<string, any> ? TPublic : Record<string, unknown> : Record<string, unknown>;
+type FarmTypedEnv = ResolvedFarmEnv<FarmServerEnv, FarmPublicEnv>;
+type FarmEnvRuntimeType = "string" | "number" | "boolean" | "json";
+/**
+ * The env a server bundle carries. `runtime.server` lists server keys that are
+ * read from the server's environment instead of being stored in the bundle,
+ * with the type their parsed value had at build time.
+ */
+interface BundledFarmEnv extends ResolvedFarmEnv {
+    runtime?: {
+        server: Record<string, FarmEnvRuntimeType>;
+    };
+}
+declare function resolveEnv<TConfig extends FarmEnvConfig<any, any> | undefined>(config: TConfig, source?: Record<string, string | undefined>): InferEnv<NonNullable<TConfig>>;
+/**
+ * Prepare resolved env for a server bundle. Server values that came from the
+ * build environment are left out and read from the server's environment when
+ * the server uses them, so secrets never land in build output and a restart
+ * picks up a rotated value. Values a parser produced without an env var
+ * (defaults) stay, and so do values the runtime cannot rebuild from the raw
+ * string, because the parser itself does not run in the server bundle.
+ */
+declare function createBundledEnv(env: ResolvedFarmEnv | FarmEnvConfig<any, any> | undefined, source?: Record<string, string | undefined>): BundledFarmEnv;
+declare function setEnv(env: ResolvedFarmEnv | BundledFarmEnv): void;
+declare function getResolvedEnv<TEnv extends ResolvedFarmEnv = FarmTypedEnv>(): TEnv;
+declare function getEnv<TServer extends Record<string, any> = FarmServerEnv>(): TServer;
+declare function getEnv<TKey extends Extract<keyof FarmServerEnv, string>>(key: TKey): FarmServerEnv[TKey];
+declare function getPublicEnv<TPublic extends Record<string, any> = FarmPublicEnv>(): TPublic;
+declare function getPublicEnv<TKey extends Extract<keyof FarmPublicEnv, string>>(key: TKey): FarmPublicEnv[TKey];
+declare const env: FarmServerEnv;
+declare const serverEnv: Record<string, unknown>;
+declare const publicEnv: FarmPublicEnv;
+
+export { type BundledFarmEnv, type EnvParser, type EnvSchema, type EnvShape, type FarmEnvConfig, type FarmEnvRuntimeType, type FarmEnvTypes, type FarmPublicEnv, type FarmServerEnv, type FarmTypedEnv, type InferEnv, type InferEnvParser, type InferEnvShape, type ResolvedFarmEnv, createBundledEnv, env, getEnv, getPublicEnv, getResolvedEnv, publicEnv, resolveEnv, serverEnv, setEnv };

package/dist/env.mjs

@@ -8,9 +8,9 @@ import {
   resolveEnv,
   serverEnv,
   setEnv
-} from "./chunk-4OOBRCJX.mjs";
-import "./chunk-ONUEYC6N.mjs";
-import "./chunk-LPEX4YW6.mjs";
+} from "./chunk-N33DLJBC.mjs";
+import "./chunk-WXFY5JIY.mjs";
+import "./chunk-Y6FXYEAI.mjs";
 export {
   createBundledEnv,
   env,

package/dist/environment/vite.cjs

@@ -1,9 +1,13 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true});
 
 
-var _chunk3SDFA7UFcjs = require('../chunk-3SDFA7UF.cjs');
-require('../chunk-S3JO3N4H.cjs');
+var _chunkNK2VWS7Pcjs = require('../chunk-NK2VWS7P.cjs');
+require('../chunk-5Y2P454O.cjs');
+require('../chunk-DQJ2CIH7.cjs');
+require('../chunk-E7QOEV5Z.cjs');
+require('../chunk-YTVSWXEZ.cjs');
+require('../chunk-BTZ5O6VM.cjs');
 
 
 
-exports.farmEnvironmentFunctionsPlugin = _chunk3SDFA7UFcjs.farmEnvironmentFunctionsPlugin; exports.transformEnvironmentFunctions = _chunk3SDFA7UFcjs.transformEnvironmentFunctions;
+exports.farmEnvironmentFunctionsPlugin = _chunkNK2VWS7Pcjs.farmEnvironmentFunctionsPlugin; exports.transformEnvironmentFunctions = _chunkNK2VWS7Pcjs.transformEnvironmentFunctions;

package/dist/environment/vite.d.mts

@@ -0,0 +1,31 @@
+import { Plugin } from 'vite';
+import { FarmEnvironment } from '../environment.mjs';
+import { R as ResolvedFarmLayer } from '../layers.d-CcS42OGR.mjs';
+import 'rolldown/utils';
+import 'rolldown';
+
+interface AstNode {
+    type: string;
+    start: number;
+    end: number;
+    [key: string]: unknown;
+}
+interface TransformEnvironmentFunctionsOptions {
+    code: string;
+    id: string;
+    environment: FarmEnvironment;
+    parse: (code: string) => AstNode;
+}
+interface TransformEnvironmentFunctionsResult {
+    code: string;
+}
+declare function transformEnvironmentFunctions(options: TransformEnvironmentFunctionsOptions): TransformEnvironmentFunctionsResult | null;
+interface FarmEnvironmentFunctionsPluginOptions {
+    /** The app's root, srcDir, and layers: where Farm loads programmatic routes files from. */
+    root?: string;
+    srcDir?: string;
+    layers?: readonly ResolvedFarmLayer[];
+}
+declare function farmEnvironmentFunctionsPlugin(options?: FarmEnvironmentFunctionsPluginOptions): Plugin;
+
+export { type FarmEnvironmentFunctionsPluginOptions, type TransformEnvironmentFunctionsOptions, type TransformEnvironmentFunctionsResult, farmEnvironmentFunctionsPlugin, transformEnvironmentFunctions };