@farm.js/core 0.1.0-beta.1 → 0.1.0-beta.4

package/dist/api.cjs

@@ -31,9 +31,13 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/api/index.ts
 var api_exports = {};
 __export(api_exports, {
+  APIClientError: () => APIClientError,
   APIRouteManager: () => APIRouteManager,
   API_ROUTE_METHODS: () => API_ROUTE_METHODS,
   DELETE: () => DELETE,
+  EndpointFailure: () => EndpointFailure,
+  FARM_API_ROUTE_META_SYMBOL: () => FARM_API_ROUTE_META_SYMBOL,
+  FARM_API_ROUTE_REF_SYMBOL: () => FARM_API_ROUTE_REF_SYMBOL,
   GET: () => GET,
   HEAD: () => HEAD,
   OPTIONS: () => OPTIONS,
@@ -44,206 +48,25 @@ __export(api_exports, {
   createEndpoint: () => createEndpoint,
   createServerAPIClient: () => createServerAPIClient,
   farmApiPlugin: () => farmApiPlugin,
+  getAPIRouteRefMetadata: () => getAPIRouteRefMetadata,
   invokeAPIRouteEndpoint: () => invokeAPIRouteEndpoint,
+  isAPIRouteRef: () => isAPIRouteRef,
+  isEndpointFailure: () => isEndpointFailure,
+  isFarmAPIStream: () => isFarmAPIStream,
+  isJSONStreamResponse: () => isJSONStreamResponse,
+  isMultipartSchema: () => isMultipartSchema,
   isWebResponse: () => isWebResponse,
+  jsonStream: () => jsonStream,
   matchAPIRoute: () => matchAPIRoute,
-  normalizeRouteResponse: () => normalizeRouteResponse
+  multipart: () => multipart,
+  normalizeRouteResponse: () => normalizeRouteResponse,
+  readJSONStream: () => readJSONStream,
+  toFormData: () => toFormData
 });
 module.exports = __toCommonJS(api_exports);
 
 // src/api/endpoint.ts
 var import_better_call = require("better-call");
-function createEndpoint(pathOrOptions, optionsOrHandler, maybeHandler) {
-  let path4;
-  let options;
-  let handler;
-  if (typeof pathOrOptions === "string") {
-    path4 = pathOrOptions;
-    options = optionsOrHandler;
-    handler = maybeHandler;
-  } else {
-    path4 = "";
-    options = pathOrOptions;
-    handler = optionsOrHandler;
-  }
-  if (typeof handler !== "function") {
-    throw new TypeError("createEndpoint requires a handler function");
-  }
-  const middleware = normalizeEndpointMiddleware(options.middleware);
-  const wrappedHandler = /* @__PURE__ */ __name(((ctx) => runEndpointMiddleware(middleware, ctx, handler)), "wrappedHandler");
-  const { middleware: _middleware, ...betterCallOptions } = options;
-  const endpoint = (0, import_better_call.createEndpoint)(
-    path4 || "/__farm_auto_path__",
-    betterCallOptions,
-    wrappedHandler
-  );
-  endpoint.__path = path4 || void 0;
-  endpoint.__method = options.method || "GET";
-  endpoint.__autoPath = !path4;
-  endpoint.__handler = wrappedHandler;
-  endpoint.__middleware = middleware;
-  endpoint.__sourceHandler = handler;
-  endpoint.__types = {
-    body: options.body,
-    query: options.query,
-    headers: options.headers,
-    response: null
-  };
-  return endpoint;
-}
-__name(createEndpoint, "createEndpoint");
-var EMPTY_ENDPOINT_MIDDLEWARE = Object.freeze([]);
-var EMPTY_ENDPOINT_CONTEXT = Object.freeze(/* @__PURE__ */ Object.create(null));
-var UNSAFE_ENDPOINT_CONTEXT_KEYS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
-function normalizeEndpointMiddleware(middleware) {
-  if (middleware === void 0) return EMPTY_ENDPOINT_MIDDLEWARE;
-  if (!Array.isArray(middleware)) {
-    throw new TypeError("createEndpoint middleware must be an array of functions");
-  }
-  const normalized = [...middleware];
-  for (const entry of normalized) {
-    if (typeof entry !== "function") {
-      throw new TypeError("createEndpoint middleware entries must be functions");
-    }
-  }
-  return Object.freeze(normalized);
-}
-__name(normalizeEndpointMiddleware, "normalizeEndpointMiddleware");
-async function runEndpointMiddleware(middleware, handlerContext, handler) {
-  let context = createInitialEndpointContext(handlerContext.context);
-  for (let index = 0; index < middleware.length; index++) {
-    const result = await middleware[index]({ ...handlerContext, context });
-    if (isEndpointResponse(result)) return result;
-    if (result === false) return forbiddenEndpointResponse();
-    if (result === true) continue;
-    if (!isPlainEndpointContext(result)) {
-      throw new TypeError(
-        `Endpoint middleware ${index + 1} must return an object, true, false, or a Response`
-      );
-    }
-    context = mergeEndpointContext(context, result, index);
-  }
-  return handler({ ...handlerContext, context });
-}
-__name(runEndpointMiddleware, "runEndpointMiddleware");
-function createInitialEndpointContext(value) {
-  if (value === void 0 || value === null) return EMPTY_ENDPOINT_CONTEXT;
-  if (!isPlainEndpointContext(value)) {
-    throw new TypeError("Endpoint context must be a plain object");
-  }
-  return mergeEndpointContext(EMPTY_ENDPOINT_CONTEXT, value);
-}
-__name(createInitialEndpointContext, "createInitialEndpointContext");
-function mergeEndpointContext(current, added, middlewareIndex) {
-  const next = Object.assign(/* @__PURE__ */ Object.create(null), current);
-  for (const key of Reflect.ownKeys(added)) {
-    if (!Object.prototype.propertyIsEnumerable.call(added, key)) continue;
-    if (typeof key === "string" && UNSAFE_ENDPOINT_CONTEXT_KEYS.has(key)) {
-      throw new TypeError(`Endpoint middleware cannot provide the unsafe context key "${key}"`);
-    }
-    if (Object.prototype.hasOwnProperty.call(current, key)) {
-      const source = middlewareIndex === void 0 ? "Endpoint context" : `Endpoint middleware ${middlewareIndex + 1}`;
-      throw new TypeError(`${source} cannot replace the existing context key "${String(key)}"`);
-    }
-    next[key] = added[key];
-  }
-  return Object.freeze(next);
-}
-__name(mergeEndpointContext, "mergeEndpointContext");
-function isPlainEndpointContext(value) {
-  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
-  const prototype = Object.getPrototypeOf(value);
-  return prototype === Object.prototype || prototype === null;
-}
-__name(isPlainEndpointContext, "isPlainEndpointContext");
-function isEndpointResponse(value) {
-  return value instanceof Response || typeof value === "object" && value !== null && "headers" in value && "status" in value && typeof value.arrayBuffer === "function";
-}
-__name(isEndpointResponse, "isEndpointResponse");
-function forbiddenEndpointResponse() {
-  return new Response(JSON.stringify({ error: "Forbidden" }), {
-    status: 403,
-    headers: { "Content-Type": "application/json" }
-  });
-}
-__name(forbiddenEndpointResponse, "forbiddenEndpointResponse");
-function GET(...args) {
-  if (args.length === 1) {
-    return createEndpoint("", { method: "GET" }, args[0]);
-  }
-  return createEndpoint("", { ...args[0], method: "GET" }, args[1]);
-}
-__name(GET, "GET");
-function HEAD(...args) {
-  if (args.length === 1) {
-    return createEndpoint("", { method: "HEAD" }, args[0]);
-  }
-  return createEndpoint("", { ...args[0], method: "HEAD" }, args[1]);
-}
-__name(HEAD, "HEAD");
-function POST(...args) {
-  if (args.length === 1) {
-    return createEndpoint("", { method: "POST" }, args[0]);
-  }
-  return createEndpoint("", { ...args[0], method: "POST" }, args[1]);
-}
-__name(POST, "POST");
-function PUT(...args) {
-  if (args.length === 1) {
-    return createEndpoint("", { method: "PUT" }, args[0]);
-  }
-  return createEndpoint("", { ...args[0], method: "PUT" }, args[1]);
-}
-__name(PUT, "PUT");
-function DELETE(...args) {
-  if (args.length === 1) {
-    return createEndpoint("", { method: "DELETE" }, args[0]);
-  }
-  return createEndpoint("", { ...args[0], method: "DELETE" }, args[1]);
-}
-__name(DELETE, "DELETE");
-function PATCH(...args) {
-  if (args.length === 1) {
-    return createEndpoint("", { method: "PATCH" }, args[0]);
-  }
-  return createEndpoint("", { ...args[0], method: "PATCH" }, args[1]);
-}
-__name(PATCH, "PATCH");
-function OPTIONS(...args) {
-  if (args.length === 1) {
-    return createEndpoint("", { method: "OPTIONS" }, args[0]);
-  }
-  return createEndpoint("", { ...args[0], method: "OPTIONS" }, args[1]);
-}
-__name(OPTIONS, "OPTIONS");
-
-// src/api/route-manager.ts
-var fs = __toESM(require("fs"));
-var path3 = __toESM(require("path"));
-
-// src/utils.ts
-var import_path = __toESM(require("path"));
-function toViteModuleId(filePath, root) {
-  if (!import_path.default.isAbsolute(filePath)) return filePath;
-  const relativePath = import_path.default.relative(root, filePath);
-  if (relativePath && !relativePath.startsWith("..") && !import_path.default.isAbsolute(relativePath)) {
-    return `/${relativePath.split(import_path.default.sep).join("/")}`;
-  }
-  const normalizedPath = filePath.replace(/\\/g, "/");
-  return normalizedPath.startsWith("/") ? `/@fs${normalizedPath}` : `/@fs/${normalizedPath}`;
-}
-__name(toViteModuleId, "toViteModuleId");
-var logger = {
-  info: /* @__PURE__ */ __name((message) => console.log(`[info] ${message}`), "info"),
-  success: /* @__PURE__ */ __name((message) => console.log(`[success] ${message}`), "success"),
-  warn: /* @__PURE__ */ __name((message) => console.warn(`\u26A0\uFE0F  ${message}`), "warn"),
-  error: /* @__PURE__ */ __name((message) => console.error(`\u274C ${message}`), "error"),
-  ready: /* @__PURE__ */ __name((message) => console.log(`${message}`), "ready"),
-  event: /* @__PURE__ */ __name((message) => console.log(`  ${message}`), "event")
-};
-
-// src/routes.ts
-var import_react = require("react");
 
 // src/observability.ts
 var runtimeHandlers = /* @__PURE__ */ new Set();
@@ -361,14 +184,58 @@ function formatError(error) {
 __name(formatError, "formatError");
 
 // src/cache-invalidation.ts
+var FARM_CACHE_INVALIDATION_HEADER = "x-farm-cache-invalidations";
 var FARM_CACHE_INVALIDATION_STATE = /* @__PURE__ */ Symbol.for("farm.cacheInvalidationState");
 var globalState = globalThis;
 function getFarmCacheInvalidationState() {
   return globalState[FARM_CACHE_INVALIDATION_STATE] ?? (globalState[FARM_CACHE_INVALIDATION_STATE] = {
-    listeners: /* @__PURE__ */ new Set()
+    listeners: /* @__PURE__ */ new Set(),
+    taskListeners: /* @__PURE__ */ new Set()
   });
 }
 __name(getFarmCacheInvalidationState, "getFarmCacheInvalidationState");
+function notifyFarmCacheInvalidation(key) {
+  if (typeof key !== "string" || key.length === 0) return;
+  for (const listener of getFarmCacheInvalidationState().listeners) {
+    listener(key);
+  }
+}
+__name(notifyFarmCacheInvalidation, "notifyFarmCacheInvalidation");
+function notifyFarmCacheTask(task) {
+  for (const listener of getFarmCacheInvalidationState().taskListeners) {
+    listener(task);
+  }
+}
+__name(notifyFarmCacheTask, "notifyFarmCacheTask");
+function applyFarmCacheInvalidations(keys) {
+  if (!Array.isArray(keys)) return;
+  for (const key of keys) {
+    if (typeof key === "string") {
+      notifyFarmCacheInvalidation(key);
+    }
+  }
+}
+__name(applyFarmCacheInvalidations, "applyFarmCacheInvalidations");
+function encodeFarmCacheInvalidations(keys) {
+  const normalized = Array.from(
+    new Set(keys.filter((key) => typeof key === "string" && key.length > 0))
+  );
+  if (normalized.length === 0) return null;
+  return encodeURIComponent(JSON.stringify(normalized));
+}
+__name(encodeFarmCacheInvalidations, "encodeFarmCacheInvalidations");
+function decodeFarmCacheInvalidations(value) {
+  if (!value) return [];
+  try {
+    const parsed = JSON.parse(decodeURIComponent(value));
+    return Array.isArray(parsed) ? Array.from(
+      new Set(parsed.filter((key) => typeof key === "string" && key.length > 0))
+    ) : [];
+  } catch {
+    return [];
+  }
+}
+__name(decodeFarmCacheInvalidations, "decodeFarmCacheInvalidations");
 function subscribeFarmCacheInvalidation(listener) {
   const state = getFarmCacheInvalidationState();
   state.listeners.add(listener);
@@ -385,11 +252,51 @@ __name(_setFarmI18nSnapshotResolver, "_setFarmI18nSnapshotResolver");
 
 // src/cache.ts
 var _FarmDataCache = class _FarmDataCache {
-  constructor() {
+  constructor(config = {}) {
     this.entries = /* @__PURE__ */ new Map();
     this.inflight = /* @__PURE__ */ new Map();
     this.invalidatedTagVersions = /* @__PURE__ */ new Map();
     this.version = 0;
+    this.namespace = "farm";
+    this.local = true;
+    this.lease = {
+      enabled: true,
+      ttlMs: 1e4,
+      waitTimeoutMs: 1e4,
+      pollIntervalMs: 25
+    };
+    this.configure(config);
+  }
+  configure(config = {}) {
+    this.adapter = config.adapter;
+    this.namespace = normalizeCacheNamespace(config.namespace || "farm");
+    this.local = !config.adapter;
+    this.lease = config.lease === false ? { ...this.lease, enabled: false } : {
+      enabled: true,
+      ttlMs: normalizePositiveDuration(config.lease?.ttlMs, 1e4, "cache.lease.ttlMs"),
+      waitTimeoutMs: normalizePositiveDuration(
+        config.lease?.waitTimeoutMs,
+        1e4,
+        "cache.lease.waitTimeoutMs"
+      ),
+      pollIntervalMs: normalizePositiveDuration(
+        config.lease?.pollIntervalMs,
+        25,
+        "cache.lease.pollIntervalMs"
+      )
+    };
+    if (!this.local) {
+      this.entries.clear();
+      this.inflight.clear();
+      this.invalidatedTagVersions.clear();
+      this.version = 0;
+    }
+  }
+  get adapterName() {
+    return this.adapter?.name || (this.adapter ? "custom" : "memory");
+  }
+  get hasAdapter() {
+    return this.adapter !== void 0;
   }
   get size() {
     return this.entries.size;
@@ -425,6 +332,45 @@ var _FarmDataCache = class _FarmDataCache {
     });
     return this.toPublicEntry(entry);
   }
+  async getEntryAsync(key, options = {}) {
+    if (this.local) {
+      const localEntry = this.getEntry(key, options);
+      if (localEntry) return localEntry;
+    }
+    if (!this.adapter) {
+      return this.local ? void 0 : this.getEntry(key, options);
+    }
+    const entry = await this.adapter.get(this.createAdapterKey(key));
+    if (!entry) {
+      emitFarmEvent({ type: "cache.miss", key });
+      return void 0;
+    }
+    assertFarmCacheEntry(entry, key);
+    const stale = await this.isAdapterEntryStale(entry, options.now);
+    if (stale) {
+      emitFarmEvent({
+        type: "cache.stale",
+        key,
+        tags: [...entry.tags],
+        revalidate: entry.revalidate
+      });
+      if (!options.allowStale) {
+        emitFarmEvent({ type: "cache.miss", key, reason: "stale" });
+        return void 0;
+      }
+    }
+    emitFarmEvent({
+      type: "cache.hit",
+      key,
+      tags: [...entry.tags],
+      revalidate: entry.revalidate,
+      stale
+    });
+    if (this.local && !stale) {
+      this.hydrateLocalEntry(entry);
+    }
+    return { ...entry, key };
+  }
   set(key, value, options = {}) {
     const tags = /* @__PURE__ */ new Set();
     for (const tag of options.tags ?? []) {
@@ -437,6 +383,7 @@ var _FarmDataCache = class _FarmDataCache {
       key,
       value,
       tags,
+      tagVersions: void 0,
       createdAt: options.createdAt ?? Date.now(),
       createdVersion: ++this.version,
       revalidate: normalizeRevalidate(options.revalidate)
@@ -450,11 +397,45 @@ var _FarmDataCache = class _FarmDataCache {
     });
     return this.toPublicEntry(entry);
   }
+  async setAsync(key, value, options = {}, tagVersions) {
+    const tags = normalizeCacheOptionsTags(options);
+    const capturedVersions = tagVersions ?? await this.getAdapterTagVersions(Array.from(tags.values()));
+    const entry = {
+      key,
+      value,
+      tags: Array.from(tags),
+      tagVersions: capturedVersions,
+      createdAt: options.createdAt ?? Date.now(),
+      createdVersion: ++this.version,
+      revalidate: normalizeRevalidate(options.revalidate)
+    };
+    if (this.local) {
+      this.hydrateLocalEntry(entry);
+    }
+    if (this.adapter) {
+      await this.adapter.set(this.createAdapterKey(key), entry);
+    }
+    emitFarmEvent({
+      type: "cache.set",
+      key,
+      tags: [...entry.tags],
+      revalidate: entry.revalidate
+    });
+    return entry;
+  }
   delete(key) {
     const deleted = this.entries.delete(key);
     emitFarmEvent({ type: "cache.delete", key, deleted });
     return deleted;
   }
+  async deleteAsync(key) {
+    const deleted = this.entries.delete(key);
+    if (this.adapter) {
+      await this.adapter.delete(this.createAdapterKey(key));
+    }
+    emitFarmEvent({ type: "cache.delete", key, deleted: this.adapter ? true : deleted });
+    return this.adapter ? true : deleted;
+  }
   clear() {
     const count = this.entries.size;
     this.entries.clear();
@@ -463,6 +444,10 @@ var _FarmDataCache = class _FarmDataCache {
     this.version = 0;
     emitFarmEvent({ type: "cache.clear", count });
   }
+  async clearAsync() {
+    this.clear();
+    await this.adapter?.clear?.();
+  }
   isStale(entry, now = Date.now()) {
     if (typeof entry.revalidate === "number" && entry.revalidate > 0 && now - entry.createdAt >= entry.revalidate * 1e3) {
       return true;
@@ -475,6 +460,12 @@ var _FarmDataCache = class _FarmDataCache {
     }
     return false;
   }
+  async isStaleAsync(entry, now = Date.now()) {
+    if (this.adapter) {
+      return this.isAdapterEntryStale(entry, now);
+    }
+    return this.isStale(entry, now);
+  }
   revalidateTag(tag, options = {}) {
     const normalized = normalizeCacheTag(tag);
     const count = this.invalidateTag(normalized);
@@ -483,6 +474,15 @@ var _FarmDataCache = class _FarmDataCache {
     );
     return count;
   }
+  async revalidateTagAsync(tag, options = {}) {
+    const normalized = normalizeCacheTag(tag);
+    const count = this.invalidateTag(normalized);
+    await this.adapter?.invalidateTags?.([this.createAdapterTag(normalized)]);
+    emitFarmEvent(
+      options.source === "updateTag" ? { type: "cache.updateTag", tag: normalized, count } : { type: "cache.revalidateTag", tag: normalized, profile: options.profile, count }
+    );
+    return count;
+  }
   revalidatePath(routePath) {
     const normalizedPath = normalizeRevalidatePath(routePath);
     const pathTag = createPathCacheTag(normalizedPath);
@@ -499,8 +499,25 @@ var _FarmDataCache = class _FarmDataCache {
     }
     return count;
   }
+  async revalidatePathAsync(routePath) {
+    const normalizedPath = normalizeRevalidatePath(routePath);
+    const pathTag = createPathCacheTag(normalizedPath);
+    const pprCount = this.countEntriesForTags([pathTag, "ppr"]);
+    const count = this.invalidateTag(pathTag);
+    await this.adapter?.invalidateTags?.([this.createAdapterTag(pathTag)]);
+    emitFarmEvent({ type: "cache.revalidatePath", path: normalizedPath, count });
+    if (pprCount > 0) {
+      emitFarmEvent({
+        type: "ppr.shell.invalidated",
+        route: normalizedPath,
+        reason: "revalidatePath",
+        count: pprCount
+      });
+    }
+    return count;
+  }
   async getOrSet(key, producer, options = {}) {
-    const cached = this.getEntry(key);
+    const cached = await this.getEntryAsync(key);
     if (cached) {
       return cached.value;
     }
@@ -509,10 +526,8 @@ var _FarmDataCache = class _FarmDataCache {
       emitFarmEvent({ type: "cache.dedupe", key });
       return inflight;
     }
-    const promise = Promise.resolve().then(producer).then((value) => {
-      this.set(key, value, options);
-      return value;
-    }).catch((error) => {
+    const tags = Array.from(normalizeCacheOptionsTags(options));
+    const promise = this.fillCacheEntry(key, producer, options, tags).catch((error) => {
       emitFarmEvent({ type: "cache.error", key, operation: "set", error });
       throw error;
     }).finally(() => {
@@ -521,6 +536,40 @@ var _FarmDataCache = class _FarmDataCache {
     this.inflight.set(key, promise);
     return promise;
   }
+  async fillCacheEntry(key, producer, options, tags) {
+    const leaseKey = `${this.namespace}:lease:${key}`;
+    let leaseToken;
+    if (this.adapter?.acquireLease && this.adapter.releaseLease && this.lease.enabled) {
+      leaseToken = await this.adapter.acquireLease(leaseKey, this.lease.ttlMs);
+      if (!leaseToken) {
+        const shared = await this.waitForAdapterEntry(key);
+        if (shared) {
+          emitFarmEvent({ type: "cache.dedupe", key });
+          return shared.value;
+        }
+        leaseToken = await this.adapter.acquireLease(leaseKey, this.lease.ttlMs);
+      }
+    }
+    try {
+      const initialTagVersions = await this.getAdapterTagVersions(tags);
+      const value = await producer();
+      await this.setAsync(key, value, options, initialTagVersions);
+      return value;
+    } finally {
+      if (leaseToken && this.adapter?.releaseLease) {
+        await this.adapter.releaseLease(leaseKey, leaseToken);
+      }
+    }
+  }
+  async waitForAdapterEntry(key) {
+    const deadline = Date.now() + this.lease.waitTimeoutMs;
+    while (Date.now() < deadline) {
+      await delay(this.lease.pollIntervalMs);
+      const entry = await this.getEntryAsync(key);
+      if (entry) return entry;
+    }
+    return void 0;
+  }
   countEntriesForTag(tag) {
     let count = 0;
     for (const entry of this.entries.values()) {
@@ -548,11 +597,53 @@ var _FarmDataCache = class _FarmDataCache {
       key: entry.key,
       value: entry.value,
       tags: Array.from(entry.tags),
+      tagVersions: entry.tagVersions,
       createdAt: entry.createdAt,
       createdVersion: entry.createdVersion,
       revalidate: entry.revalidate
     };
   }
+  hydrateLocalEntry(entry) {
+    this.entries.set(entry.key, {
+      key: entry.key,
+      value: entry.value,
+      tags: new Set(entry.tags.map(normalizeCacheTag)),
+      tagVersions: entry.tagVersions,
+      createdAt: entry.createdAt,
+      createdVersion: entry.createdVersion ?? ++this.version,
+      revalidate: normalizeRevalidate(entry.revalidate)
+    });
+  }
+  createAdapterKey(key) {
+    return `${this.namespace}:entry:${key}`;
+  }
+  createAdapterTag(tag) {
+    return `${this.namespace}:tag:${tag}`;
+  }
+  async getAdapterTagVersions(tags) {
+    if (!this.adapter?.getTagVersions || tags.length === 0) return {};
+    const normalized = tags.map(normalizeCacheTag);
+    const physicalTags = normalized.map((tag) => this.createAdapterTag(tag));
+    const versions = await this.adapter.getTagVersions(physicalTags);
+    return Object.fromEntries(
+      normalized.map((tag, index) => [
+        tag,
+        normalizeAdapterVersion(versions[physicalTags[index]])
+      ])
+    );
+  }
+  async isAdapterEntryStale(entry, now = Date.now()) {
+    if (typeof entry.revalidate === "number" && entry.revalidate > 0 && now - entry.createdAt >= entry.revalidate * 1e3) {
+      return true;
+    }
+    const currentVersions = await this.getAdapterTagVersions(entry.tags);
+    for (const tag of entry.tags) {
+      if (normalizeAdapterVersion(currentVersions[tag]) > normalizeAdapterVersion(entry.tagVersions?.[tag])) {
+        return true;
+      }
+    }
+    return false;
+  }
 };
 __name(_FarmDataCache, "FarmDataCache");
 var FarmDataCache = _FarmDataCache;
@@ -561,10 +652,64 @@ var farmDataCacheGlobal = globalThis;
 var sharedFarmDataCache = farmDataCacheGlobal[FARM_DATA_CACHE_SYMBOL] ?? (farmDataCacheGlobal[FARM_DATA_CACHE_SYMBOL] = new FarmDataCache());
 var functionIds = /* @__PURE__ */ new WeakMap();
 var nextFunctionId = 0;
+function getFarmDataCache() {
+  return sharedFarmDataCache;
+}
+__name(getFarmDataCache, "getFarmDataCache");
+function updateTag(tag) {
+  const cache = getFarmDataCache();
+  if (cache.hasAdapter) {
+    const task = cache.revalidateTagAsync(tag, { source: "updateTag" }).then(() => void 0);
+    notifyFarmCacheTask(task);
+    return task;
+  }
+  cache.revalidateTag(tag, { source: "updateTag" });
+}
+__name(updateTag, "updateTag");
+function revalidatePath(routePath) {
+  const cache = getFarmDataCache();
+  if (cache.hasAdapter) {
+    const task = cache.revalidatePathAsync(routePath).then(() => void 0);
+    notifyFarmCacheTask(task);
+    return task;
+  }
+  cache.revalidatePath(routePath);
+}
+__name(revalidatePath, "revalidatePath");
+function invalidate(key) {
+  const clientKey = createRouteDataCacheKey(key);
+  const task = updateTag(createRouteDataCacheTag(key));
+  notifyFarmCacheInvalidation(clientKey);
+  return task;
+}
+__name(invalidate, "invalidate");
+async function applyFarmCacheInvalidationTargets(targets) {
+  if (!Array.isArray(targets)) {
+    throw new TypeError("Cache invalidations must resolve to an array of targets.");
+  }
+  const clientKeys = [];
+  for (const target of targets) {
+    assertFarmCacheInvalidationTarget(target);
+    if ("key" in target) {
+      await invalidate(target.key);
+      clientKeys.push(createRouteDataCacheKey(target.key));
+    } else if ("path" in target) {
+      await revalidatePath(target.path);
+    } else {
+      await updateTag(target.tag);
+    }
+  }
+  return Array.from(new Set(clientKeys));
+}
+__name(applyFarmCacheInvalidationTargets, "applyFarmCacheInvalidationTargets");
 function createPathCacheTag(routePath) {
   return `path:${normalizeRevalidatePath(routePath)}`;
 }
 __name(createPathCacheTag, "createPathCacheTag");
+function createRouteDataCacheTag(key) {
+  return `route-data:${createRouteDataCacheKey(key)}`;
+}
+__name(createRouteDataCacheTag, "createRouteDataCacheTag");
 function createRouteDataCacheKey(key) {
   return createFarmCacheKey(Array.isArray(key) ? key : [key]);
 }
@@ -603,73 +748,618 @@ function normalizeRevalidate(revalidate) {
   if (!Number.isFinite(revalidate) || revalidate <= 0) {
     return void 0;
   }
-  return revalidate;
+  return revalidate;
+}
+__name(normalizeRevalidate, "normalizeRevalidate");
+function normalizeCacheTag(tag) {
+  if (typeof tag !== "string") {
+    throw new TypeError("Cache tags must be strings.");
+  }
+  const normalized = tag.trim();
+  if (!normalized) {
+    throw new Error("Cache tags cannot be empty.");
+  }
+  return normalized;
+}
+__name(normalizeCacheTag, "normalizeCacheTag");
+function normalizeCacheNamespace(namespace) {
+  if (typeof namespace !== "string") {
+    throw new TypeError("Cache namespace must be a string.");
+  }
+  const normalized = namespace.trim().replace(/:+$/g, "");
+  if (!normalized) {
+    throw new Error("Cache namespace cannot be empty.");
+  }
+  return normalized;
+}
+__name(normalizeCacheNamespace, "normalizeCacheNamespace");
+function normalizeAdapterVersion(value) {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : 0;
+}
+__name(normalizeAdapterVersion, "normalizeAdapterVersion");
+function normalizePositiveDuration(value, fallback, name) {
+  if (value === void 0) return fallback;
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new TypeError(`${name} must be a positive number of milliseconds.`);
+  }
+  return Math.floor(value);
+}
+__name(normalizePositiveDuration, "normalizePositiveDuration");
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+__name(delay, "delay");
+function normalizeCacheOptionsTags(options) {
+  const tags = /* @__PURE__ */ new Set();
+  for (const tag of options.tags ?? []) {
+    tags.add(normalizeCacheTag(tag));
+  }
+  for (const routePath of options.paths ?? []) {
+    tags.add(createPathCacheTag(routePath));
+  }
+  return tags;
+}
+__name(normalizeCacheOptionsTags, "normalizeCacheOptionsTags");
+function assertFarmCacheEntry(entry, expectedKey) {
+  if (!entry || typeof entry !== "object" || entry.key !== expectedKey || !Array.isArray(entry.tags) || typeof entry.createdAt !== "number") {
+    throw new TypeError(
+      `Cache adapter returned an invalid entry for ${JSON.stringify(expectedKey)}.`
+    );
+  }
+}
+__name(assertFarmCacheEntry, "assertFarmCacheEntry");
+function assertFarmCacheInvalidationTarget(target) {
+  if (!target || typeof target !== "object") {
+    throw new TypeError("Cache invalidation targets must be { key }, { path }, or { tag }.");
+  }
+  if ("key" in target) {
+    const key = target.key;
+    if (typeof key === "string" || Array.isArray(key)) return;
+  } else if ("path" in target && typeof target.path === "string") {
+    return;
+  } else if ("tag" in target && typeof target.tag === "string") {
+    return;
+  }
+  throw new TypeError("Cache invalidation targets must contain a string/array key, path, or tag.");
+}
+__name(assertFarmCacheInvalidationTarget, "assertFarmCacheInvalidationTarget");
+function getFunctionCacheIdentity(fn) {
+  if (fn.name) {
+    return `name:${fn.name}`;
+  }
+  let id = functionIds.get(fn);
+  if (!id) {
+    id = ++nextFunctionId;
+    functionIds.set(fn, id);
+  }
+  return `anonymous:${id}`;
+}
+__name(getFunctionCacheIdentity, "getFunctionCacheIdentity");
+function stableSerialize(value, seen = /* @__PURE__ */ new WeakSet()) {
+  if (value === null) return "null";
+  if (value === void 0) return "undefined";
+  const valueType = typeof value;
+  if (valueType === "string") return JSON.stringify(value);
+  if (valueType === "number" || valueType === "boolean" || valueType === "bigint") {
+    return `${valueType}:${String(value)}`;
+  }
+  if (valueType === "symbol") {
+    return `symbol:${String(value)}`;
+  }
+  if (valueType === "function") {
+    return `function:${getFunctionCacheIdentity(value)}`;
+  }
+  if (value instanceof Date) {
+    return `date:${value.toISOString()}`;
+  }
+  if (value instanceof URL) {
+    return `url:${value.toString()}`;
+  }
+  if (value instanceof RegExp) {
+    return `regexp:${value.toString()}`;
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => stableSerialize(item, seen)).join(",")}]`;
+  }
+  if (value && typeof value === "object") {
+    if (seen.has(value)) {
+      return "[Circular]";
+    }
+    seen.add(value);
+    const entries = Object.entries(value).sort(
+      ([a], [b]) => a.localeCompare(b)
+    );
+    const serialized = entries.map(([key, item]) => `${JSON.stringify(key)}:${stableSerialize(item, seen)}`).join(",");
+    seen.delete(value);
+    return `{${serialized}}`;
+  }
+  return String(value);
+}
+__name(stableSerialize, "stableSerialize");
+
+// src/api/transport.ts
+function multipart(schema) {
+  if (!Object.isExtensible(schema) && !isMultipartSchema(schema)) {
+    throw new TypeError("multipart() requires an extensible schema object");
+  }
+  if (!isMultipartSchema(schema)) {
+    Object.defineProperty(schema, "__farmMultipartSchema", {
+      value: true,
+      configurable: false,
+      enumerable: false,
+      writable: false
+    });
+  }
+  return schema;
+}
+__name(multipart, "multipart");
+function isMultipartSchema(value) {
+  return typeof value === "object" && value !== null && value.__farmMultipartSchema === true && typeof value.parse === "function";
+}
+__name(isMultipartSchema, "isMultipartSchema");
+function toFormData(values) {
+  const formData = new FormData();
+  for (const [key, value] of Object.entries(values)) {
+    if (isUnsafeFormKey(key)) continue;
+    if (Array.isArray(value)) {
+      for (const entry of value) appendFormValue(formData, key, entry);
+      continue;
+    }
+    appendFormValue(formData, key, value);
+  }
+  return formData;
+}
+__name(toFormData, "toFormData");
+function jsonStream(source, init = {}) {
+  const iterator = toAsyncIterator(source);
+  const encoder = new TextEncoder();
+  let finished = false;
+  const body = new ReadableStream(
+    {
+      async pull(controller) {
+        if (finished) return;
+        try {
+          const next = await iterator.next();
+          if (next.done) {
+            finished = true;
+            controller.close();
+            return;
+          }
+          controller.enqueue(encoder.encode(`${JSON.stringify(next.value)}
+`));
+        } catch (error) {
+          finished = true;
+          controller.error(error);
+        }
+      },
+      async cancel(reason) {
+        finished = true;
+        await iterator.return?.(reason);
+      }
+    },
+    {
+      // Do not read the next application event until the response consumer
+      // requests another chunk.
+      highWaterMark: 0
+    }
+  );
+  const headers = new Headers(init.headers);
+  if (!headers.has("content-type")) {
+    headers.set("content-type", "application/x-ndjson; charset=utf-8");
+  }
+  headers.set("cache-control", headers.get("cache-control") ?? "no-store");
+  return new Response(body, {
+    ...init,
+    headers
+  });
+}
+__name(jsonStream, "jsonStream");
+function isJSONStreamResponse(response) {
+  const contentType = response.headers?.get?.("content-type")?.toLowerCase() ?? "";
+  return contentType.includes("application/x-ndjson") || contentType.includes("application/ndjson");
+}
+__name(isJSONStreamResponse, "isJSONStreamResponse");
+function readJSONStream(response) {
+  if (!response.body) {
+    throw new TypeError("Cannot read a JSON stream response without a body");
+  }
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  let completed = false;
+  let claimed = false;
+  const iterator = {
+    async next() {
+      while (true) {
+        const lineEnd = buffer.indexOf("\n");
+        if (lineEnd >= 0) {
+          const line = buffer.slice(0, lineEnd).trim();
+          buffer = buffer.slice(lineEnd + 1);
+          if (!line) continue;
+          return { done: false, value: JSON.parse(line) };
+        }
+        if (completed) {
+          const line = buffer.trim();
+          buffer = "";
+          if (!line) return { done: true, value: void 0 };
+          return { done: false, value: JSON.parse(line) };
+        }
+        const chunk = await reader.read();
+        completed = chunk.done;
+        buffer += decoder.decode(chunk.value, { stream: !chunk.done });
+      }
+    },
+    async return() {
+      completed = true;
+      buffer = "";
+      await reader.cancel();
+      return { done: true, value: void 0 };
+    }
+  };
+  return {
+    response,
+    async cancel(reason) {
+      completed = true;
+      buffer = "";
+      await reader.cancel(reason);
+    },
+    [Symbol.asyncIterator]() {
+      if (claimed) {
+        throw new TypeError("Farm API streams can only be consumed once");
+      }
+      claimed = true;
+      return iterator;
+    }
+  };
+}
+__name(readJSONStream, "readJSONStream");
+function isFarmAPIStream(value) {
+  return typeof value === "object" && value !== null && "response" in value && typeof value.cancel === "function" && typeof value[Symbol.asyncIterator] === "function";
+}
+__name(isFarmAPIStream, "isFarmAPIStream");
+function appendFormValue(formData, key, value) {
+  if (value === void 0) return;
+  if (value === null) {
+    formData.append(key, "");
+    return;
+  }
+  if (value instanceof Blob) {
+    formData.append(key, value);
+    return;
+  }
+  if (value instanceof Date) {
+    formData.append(key, value.toISOString());
+    return;
+  }
+  formData.append(key, String(value));
+}
+__name(appendFormValue, "appendFormValue");
+function isUnsafeFormKey(key) {
+  return key === "__proto__" || key === "constructor" || key === "prototype";
+}
+__name(isUnsafeFormKey, "isUnsafeFormKey");
+function toAsyncIterator(source) {
+  if (Symbol.asyncIterator in Object(source)) {
+    return source[Symbol.asyncIterator]();
+  }
+  const iterator = source[Symbol.iterator]();
+  return {
+    next: /* @__PURE__ */ __name(async () => iterator.next(), "next"),
+    return: iterator.return ? async (value) => iterator.return(value) : void 0
+  };
+}
+__name(toAsyncIterator, "toAsyncIterator");
+
+// src/api/endpoint.ts
+var _EndpointFailure = class _EndpointFailure extends Error {
+  constructor(code, data, options) {
+    super(options.message);
+    this.name = "EndpointFailure";
+    this.code = code;
+    this.data = data;
+    this.status = options.status;
+  }
+};
+__name(_EndpointFailure, "EndpointFailure");
+var EndpointFailure = _EndpointFailure;
+function isEndpointFailure(value) {
+  return value instanceof EndpointFailure;
+}
+__name(isEndpointFailure, "isEndpointFailure");
+function createEndpoint(pathOrOptions, optionsOrHandler, maybeHandler) {
+  let path4;
+  let options;
+  let handler;
+  if (typeof pathOrOptions === "string") {
+    path4 = pathOrOptions;
+    options = optionsOrHandler;
+    handler = maybeHandler;
+  } else {
+    path4 = "";
+    options = pathOrOptions;
+    handler = optionsOrHandler;
+  }
+  if (typeof handler !== "function") {
+    throw new TypeError("createEndpoint requires a handler function");
+  }
+  const middleware = normalizeEndpointMiddleware(options.middleware);
+  const errors = normalizeEndpointErrors(options.errors);
+  const fail = createEndpointFail(errors);
+  const wrappedHandler = /* @__PURE__ */ __name((async (ctx) => {
+    const execution = await runEndpointMiddleware(
+      middleware,
+      ctx,
+      handler,
+      fail,
+      options.invalidates
+    );
+    return execution.result;
+  }), "wrappedHandler");
+  const {
+    middleware: _middleware,
+    errors: _errors,
+    invalidates: _invalidates,
+    ...betterCallOptions
+  } = options;
+  const endpoint = (0, import_better_call.createEndpoint)(
+    path4 || "/__farm_auto_path__",
+    betterCallOptions,
+    wrappedHandler
+  );
+  endpoint.__path = path4 || void 0;
+  endpoint.__method = options.method || "GET";
+  endpoint.__autoPath = !path4;
+  endpoint.__handler = wrappedHandler;
+  endpoint.__farmInvoke = (ctx) => runEndpointMiddleware(middleware, ctx, handler, fail, options.invalidates);
+  endpoint.__middleware = middleware;
+  endpoint.__sourceHandler = handler;
+  endpoint.__invalidates = options.invalidates;
+  endpoint.__errors = errors;
+  endpoint.__types = {
+    body: options.body,
+    inputBody: isMultipartSchema(options.body) ? "form-data" : options.body,
+    query: options.query,
+    headers: options.headers,
+    response: null,
+    errors
+  };
+  return endpoint;
+}
+__name(createEndpoint, "createEndpoint");
+var EMPTY_ENDPOINT_MIDDLEWARE = Object.freeze([]);
+var EMPTY_ENDPOINT_CONTEXT = Object.freeze(/* @__PURE__ */ Object.create(null));
+var UNSAFE_ENDPOINT_CONTEXT_KEYS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
+function normalizeEndpointErrors(definitions) {
+  if (definitions === void 0) return Object.freeze({});
+  if (!isPlainEndpointContext(definitions)) {
+    throw new TypeError("createEndpoint errors must be an object");
+  }
+  const normalized = /* @__PURE__ */ Object.create(null);
+  for (const [code, definition] of Object.entries(definitions)) {
+    if (!code.trim()) {
+      throw new TypeError("Endpoint error codes cannot be empty");
+    }
+    if (!definition || typeof definition !== "object") {
+      throw new TypeError(`Endpoint error "${code}" must be an object`);
+    }
+    if (!Number.isInteger(definition.status) || definition.status < 400 || definition.status > 599) {
+      throw new TypeError(`Endpoint error "${code}" status must be an integer between 400 and 599`);
+    }
+    if (!definition.schema || typeof definition.schema.parse !== "function") {
+      throw new TypeError(`Endpoint error "${code}" requires a schema with parse()`);
+    }
+    if (definition.message !== void 0 && typeof definition.message !== "string") {
+      throw new TypeError(`Endpoint error "${code}" message must be a string`);
+    }
+    normalized[code] = Object.freeze({ ...definition });
+  }
+  return Object.freeze(normalized);
+}
+__name(normalizeEndpointErrors, "normalizeEndpointErrors");
+function createEndpointFail(definitions) {
+  return ((code, data) => {
+    const definition = definitions[code];
+    if (!definition) {
+      throw new TypeError(`Endpoint error "${code}" is not declared`);
+    }
+    const parsed = definition.schema.parse(data);
+    throw new EndpointFailure(code, parsed, {
+      status: definition.status,
+      message: definition.message ?? "Request failed"
+    });
+  });
+}
+__name(createEndpointFail, "createEndpointFail");
+function normalizeEndpointMiddleware(middleware) {
+  if (middleware === void 0) return EMPTY_ENDPOINT_MIDDLEWARE;
+  if (!Array.isArray(middleware)) {
+    throw new TypeError("createEndpoint middleware must be an array of functions");
+  }
+  const normalized = [...middleware];
+  for (const entry of normalized) {
+    if (typeof entry !== "function") {
+      throw new TypeError("createEndpoint middleware entries must be functions");
+    }
+  }
+  return Object.freeze(normalized);
 }
-__name(normalizeRevalidate, "normalizeRevalidate");
-function normalizeCacheTag(tag) {
-  if (typeof tag !== "string") {
-    throw new TypeError("Cache tags must be strings.");
+__name(normalizeEndpointMiddleware, "normalizeEndpointMiddleware");
+async function runEndpointMiddleware(middleware, handlerContext, handler, fail, invalidations) {
+  let context = createInitialEndpointContext(handlerContext.context);
+  for (let index = 0; index < middleware.length; index++) {
+    const result2 = await middleware[index]({ ...handlerContext, context });
+    if (isEndpointResponse(result2)) {
+      return {
+        result: result2,
+        context,
+        handlerExecuted: false,
+        invalidations: []
+      };
+    }
+    if (result2 === false) {
+      return {
+        result: forbiddenEndpointResponse(),
+        context,
+        handlerExecuted: false,
+        invalidations: []
+      };
+    }
+    if (result2 === true) continue;
+    if (!isPlainEndpointContext(result2)) {
+      throw new TypeError(
+        `Endpoint middleware ${index + 1} must return an object, true, false, or a Response`
+      );
+    }
+    context = mergeEndpointContext(context, result2, index);
   }
-  const normalized = tag.trim();
-  if (!normalized) {
-    throw new Error("Cache tags cannot be empty.");
+  const result = await handler({ ...handlerContext, context, fail });
+  return {
+    result,
+    context,
+    handlerExecuted: true,
+    invalidations: await applyEndpointInvalidations(
+      invalidations,
+      {
+        ...handlerContext,
+        context,
+        result
+      },
+      result
+    )
+  };
+}
+__name(runEndpointMiddleware, "runEndpointMiddleware");
+async function applyEndpointInvalidations(declaration, context, result) {
+  if (!declaration || isEndpointResponse(result) && result.status >= 400) {
+    return [];
+  }
+  const targets = typeof declaration === "function" ? await declaration(context) : declaration;
+  if (!Array.isArray(targets)) {
+    throw new TypeError(
+      "Endpoint invalidates must resolve to an array of { key }, { path }, or { tag } targets"
+    );
   }
-  return normalized;
+  return applyFarmCacheInvalidationTargets(targets);
 }
-__name(normalizeCacheTag, "normalizeCacheTag");
-function getFunctionCacheIdentity(fn) {
-  if (fn.name) {
-    return `name:${fn.name}`;
+__name(applyEndpointInvalidations, "applyEndpointInvalidations");
+function createInitialEndpointContext(value) {
+  if (value === void 0 || value === null) return EMPTY_ENDPOINT_CONTEXT;
+  if (!isPlainEndpointContext(value)) {
+    throw new TypeError("Endpoint context must be a plain object");
   }
-  let id = functionIds.get(fn);
-  if (!id) {
-    id = ++nextFunctionId;
-    functionIds.set(fn, id);
+  return mergeEndpointContext(EMPTY_ENDPOINT_CONTEXT, value);
+}
+__name(createInitialEndpointContext, "createInitialEndpointContext");
+function mergeEndpointContext(current, added, middlewareIndex) {
+  const next = Object.assign(/* @__PURE__ */ Object.create(null), current);
+  for (const key of Reflect.ownKeys(added)) {
+    if (!Object.prototype.propertyIsEnumerable.call(added, key)) continue;
+    if (typeof key === "string" && UNSAFE_ENDPOINT_CONTEXT_KEYS.has(key)) {
+      throw new TypeError(`Endpoint middleware cannot provide the unsafe context key "${key}"`);
+    }
+    if (Object.prototype.hasOwnProperty.call(current, key)) {
+      const source = middlewareIndex === void 0 ? "Endpoint context" : `Endpoint middleware ${middlewareIndex + 1}`;
+      throw new TypeError(`${source} cannot replace the existing context key "${String(key)}"`);
+    }
+    next[key] = added[key];
   }
-  return `anonymous:${id}`;
+  return Object.freeze(next);
 }
-__name(getFunctionCacheIdentity, "getFunctionCacheIdentity");
-function stableSerialize(value, seen = /* @__PURE__ */ new WeakSet()) {
-  if (value === null) return "null";
-  if (value === void 0) return "undefined";
-  const valueType = typeof value;
-  if (valueType === "string") return JSON.stringify(value);
-  if (valueType === "number" || valueType === "boolean" || valueType === "bigint") {
-    return `${valueType}:${String(value)}`;
+__name(mergeEndpointContext, "mergeEndpointContext");
+function isPlainEndpointContext(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+__name(isPlainEndpointContext, "isPlainEndpointContext");
+function isEndpointResponse(value) {
+  return value instanceof Response || typeof value === "object" && value !== null && "headers" in value && "status" in value && typeof value.arrayBuffer === "function";
+}
+__name(isEndpointResponse, "isEndpointResponse");
+function forbiddenEndpointResponse() {
+  return new Response(JSON.stringify({ error: "Forbidden" }), {
+    status: 403,
+    headers: { "Content-Type": "application/json" }
+  });
+}
+__name(forbiddenEndpointResponse, "forbiddenEndpointResponse");
+function GET(...args) {
+  if (args.length === 1) {
+    return createEndpoint("", { method: "GET" }, args[0]);
   }
-  if (valueType === "symbol") {
-    return `symbol:${String(value)}`;
+  return createEndpoint("", { ...args[0], method: "GET" }, args[1]);
+}
+__name(GET, "GET");
+function HEAD(...args) {
+  if (args.length === 1) {
+    return createEndpoint("", { method: "HEAD" }, args[0]);
   }
-  if (valueType === "function") {
-    return `function:${getFunctionCacheIdentity(value)}`;
+  return createEndpoint("", { ...args[0], method: "HEAD" }, args[1]);
+}
+__name(HEAD, "HEAD");
+function POST(...args) {
+  if (args.length === 1) {
+    return createEndpoint("", { method: "POST" }, args[0]);
   }
-  if (value instanceof Date) {
-    return `date:${value.toISOString()}`;
+  return createEndpoint("", { ...args[0], method: "POST" }, args[1]);
+}
+__name(POST, "POST");
+function PUT(...args) {
+  if (args.length === 1) {
+    return createEndpoint("", { method: "PUT" }, args[0]);
   }
-  if (value instanceof URL) {
-    return `url:${value.toString()}`;
+  return createEndpoint("", { ...args[0], method: "PUT" }, args[1]);
+}
+__name(PUT, "PUT");
+function DELETE(...args) {
+  if (args.length === 1) {
+    return createEndpoint("", { method: "DELETE" }, args[0]);
   }
-  if (value instanceof RegExp) {
-    return `regexp:${value.toString()}`;
+  return createEndpoint("", { ...args[0], method: "DELETE" }, args[1]);
+}
+__name(DELETE, "DELETE");
+function PATCH(...args) {
+  if (args.length === 1) {
+    return createEndpoint("", { method: "PATCH" }, args[0]);
   }
-  if (Array.isArray(value)) {
-    return `[${value.map((item) => stableSerialize(item, seen)).join(",")}]`;
+  return createEndpoint("", { ...args[0], method: "PATCH" }, args[1]);
+}
+__name(PATCH, "PATCH");
+function OPTIONS(...args) {
+  if (args.length === 1) {
+    return createEndpoint("", { method: "OPTIONS" }, args[0]);
   }
-  if (value && typeof value === "object") {
-    if (seen.has(value)) {
-      return "[Circular]";
-    }
-    seen.add(value);
-    const entries = Object.entries(value).sort(
-      ([a], [b]) => a.localeCompare(b)
-    );
-    const serialized = entries.map(([key, item]) => `${JSON.stringify(key)}:${stableSerialize(item, seen)}`).join(",");
-    seen.delete(value);
-    return `{${serialized}}`;
+  return createEndpoint("", { ...args[0], method: "OPTIONS" }, args[1]);
+}
+__name(OPTIONS, "OPTIONS");
+
+// src/api/route-manager.ts
+var fs = __toESM(require("fs"));
+var path3 = __toESM(require("path"));
+
+// src/utils.ts
+var import_path = __toESM(require("path"));
+function toViteModuleId(filePath, root) {
+  if (!import_path.default.isAbsolute(filePath)) return filePath;
+  const relativePath = import_path.default.relative(root, filePath);
+  if (relativePath && !relativePath.startsWith("..") && !import_path.default.isAbsolute(relativePath)) {
+    return `/${relativePath.split(import_path.default.sep).join("/")}`;
   }
-  return String(value);
+  const normalizedPath = filePath.replace(/\\/g, "/");
+  return normalizedPath.startsWith("/") ? `/@fs${normalizedPath}` : `/@fs/${normalizedPath}`;
 }
-__name(stableSerialize, "stableSerialize");
+__name(toViteModuleId, "toViteModuleId");
+var logger = {
+  info: /* @__PURE__ */ __name((message) => console.log(`[info] ${message}`), "info"),
+  success: /* @__PURE__ */ __name((message) => console.log(`[success] ${message}`), "success"),
+  warn: /* @__PURE__ */ __name((message) => console.warn(`\u26A0\uFE0F  ${message}`), "warn"),
+  error: /* @__PURE__ */ __name((message) => console.error(`\u274C ${message}`), "error"),
+  ready: /* @__PURE__ */ __name((message) => console.log(`${message}`), "ready"),
+  event: /* @__PURE__ */ __name((message) => console.log(`  ${message}`), "event")
+};
+
+// src/routes.ts
+var import_react = require("react");
 
 // src/route-runtime.ts
 function normalizeFarmRouteRuntimeConfig(value, source = "Route configuration") {
@@ -1032,10 +1722,10 @@ __name(invokeAPIRouteEndpoint, "invokeAPIRouteEndpoint");
 async function invokeAPIRouteEndpointInContext(endpoint, request, params) {
   const farmHandler = endpoint.__handler || (isFarmContextHandler(endpoint) ? endpoint : null);
   if (!farmHandler) {
-    const result2 = await endpoint(request, {
+    const result = await endpoint(request, {
       params: Promise.resolve(params)
     });
-    return normalizeRouteResponse(result2);
+    return normalizeRouteResponse(result);
   }
   const url = new URL(request.url);
   const query = {};
@@ -1044,7 +1734,7 @@ async function invokeAPIRouteEndpointInContext(endpoint, request, params) {
   });
   let body = void 0;
   if (request.method.toUpperCase() !== "GET" && request.method.toUpperCase() !== "HEAD") {
-    body = await readJSONBody(request);
+    body = await readRequestBody(request);
   }
   const headers = Object.fromEntries(request.headers.entries());
   const types = endpoint.__types || {};
@@ -1060,15 +1750,30 @@ async function invokeAPIRouteEndpointInContext(endpoint, request, params) {
   if (headersValidation instanceof Response) {
     return headersValidation;
   }
-  const result = await farmHandler({
+  const handlerContext = {
     query: queryValidation,
     body: bodyValidation,
     headers: headersValidation,
     request,
     context: {},
     params
-  });
-  return normalizeRouteResponse(result);
+  };
+  let execution;
+  try {
+    execution = typeof endpoint.__farmInvoke === "function" ? await endpoint.__farmInvoke(handlerContext) : {
+      result: await farmHandler(handlerContext),
+      context: handlerContext.context,
+      handlerExecuted: true,
+      invalidations: []
+    };
+  } catch (error) {
+    if (isEndpointFailure(error)) {
+      return createEndpointFailureResponse(error);
+    }
+    throw error;
+  }
+  const response = normalizeRouteResponse(execution.result);
+  return attachEndpointInvalidations(response, execution.invalidations);
 }
 __name(invokeAPIRouteEndpointInContext, "invokeAPIRouteEndpointInContext");
 function normalizeRouteResponse(result) {
@@ -1088,6 +1793,40 @@ function isWebResponse(value) {
   return value instanceof Response || typeof value === "object" && value !== null && "headers" in value && "status" in value && typeof value.arrayBuffer === "function";
 }
 __name(isWebResponse, "isWebResponse");
+function attachEndpointInvalidations(response, keys) {
+  const existing = decodeFarmCacheInvalidations(
+    response.headers.get(FARM_CACHE_INVALIDATION_HEADER)
+  );
+  const encoded = encodeFarmCacheInvalidations([...existing, ...keys]);
+  if (!encoded) return response;
+  const headers = new Headers(response.headers);
+  headers.set(FARM_CACHE_INVALIDATION_HEADER, encoded);
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers
+  });
+}
+__name(attachEndpointInvalidations, "attachEndpointInvalidations");
+function createEndpointFailureResponse(failure) {
+  return new Response(
+    JSON.stringify({
+      error: {
+        code: failure.code,
+        message: failure.message,
+        data: failure.data
+      }
+    }),
+    {
+      status: failure.status,
+      headers: {
+        "cache-control": "no-store",
+        "content-type": "application/json"
+      }
+    }
+  );
+}
+__name(createEndpointFailureResponse, "createEndpointFailureResponse");
 function isFarmContextHandler(endpoint) {
   if (typeof endpoint !== "function") {
     return false;
@@ -1099,17 +1838,50 @@ function isFarmContextHandler(endpoint) {
   return firstParameter === "ctx" || firstParameter === "context" || firstParameter.startsWith("{");
 }
 __name(isFarmContextHandler, "isFarmContextHandler");
-async function readJSONBody(request) {
+async function readRequestBody(request) {
+  const contentType = request.headers.get("content-type")?.split(";", 1)[0]?.trim().toLowerCase();
   try {
+    if (contentType === "multipart/form-data") {
+      return formDataToObject(await request.clone().formData());
+    }
     const text = await request.clone().text();
-    if (text) {
+    if (!text) return void 0;
+    if (contentType === "application/x-www-form-urlencoded") {
+      return searchParamsToObject(new URLSearchParams(text));
+    }
+    if (contentType === "application/json" || contentType?.endsWith("+json")) {
       return JSON.parse(text);
     }
+    return JSON.parse(text);
   } catch {
   }
   return void 0;
 }
-__name(readJSONBody, "readJSONBody");
+__name(readRequestBody, "readRequestBody");
+function formDataToObject(formData) {
+  return entriesToObject(formData.entries());
+}
+__name(formDataToObject, "formDataToObject");
+function searchParamsToObject(searchParams) {
+  return entriesToObject(searchParams.entries());
+}
+__name(searchParamsToObject, "searchParamsToObject");
+function entriesToObject(entries) {
+  const output = /* @__PURE__ */ Object.create(null);
+  for (const [key, value] of entries) {
+    if (key === "__proto__" || key === "constructor" || key === "prototype") continue;
+    const current = output[key];
+    if (current === void 0) {
+      output[key] = value;
+    } else if (Array.isArray(current)) {
+      current.push(value);
+    } else {
+      output[key] = [current, value];
+    }
+  }
+  return output;
+}
+__name(entriesToObject, "entriesToObject");
 function validateInput(schema, value, error) {
   if (!schema || typeof schema.parse !== "function") {
     return value;
@@ -1569,7 +2341,7 @@ function mergeIntegrationClientData(...values) {
       continue;
     }
     merged = {
-      ...merged || {},
+      ...merged,
       ...data
     };
   }
@@ -2220,6 +2992,20 @@ function normalizeFarmClientCacheKey(key) {
 __name(normalizeFarmClientCacheKey, "normalizeFarmClientCacheKey");
 
 // src/api/client.ts
+var FARM_API_ROUTE_REF_SYMBOL = /* @__PURE__ */ Symbol.for("farm.api.route-ref");
+var FARM_API_ROUTE_META_SYMBOL = /* @__PURE__ */ Symbol.for("farm.api.route-meta");
+var _APIClientError = class _APIClientError extends Error {
+  constructor(code, data, options) {
+    super(options.message);
+    this.name = "APIClientError";
+    this.code = code;
+    this.data = data;
+    this.status = options.status;
+    this.response = options.response;
+  }
+};
+__name(_APIClientError, "APIClientError");
+var APIClientError = _APIClientError;
 function createAPIClient(options = {}) {
   options ?? (options = {});
   const baseURL = options.baseURL || (typeof window !== "undefined" ? window.location.origin : "http://localhost:3000");
@@ -2245,21 +3031,30 @@ function createAPIClient(options = {}) {
         }
       });
     }
+    const headers = {
+      "Content-Type": "application/json",
+      ...options.headers,
+      ...requestOptions.headers
+    };
     const fetchOptions = {
       method: requestOptions.method || "GET",
-      headers: {
-        "Content-Type": "application/json",
-        ...options.headers,
-        ...requestOptions.headers
-      }
+      headers
     };
-    if (requestOptions.body) {
-      fetchOptions.body = JSON.stringify(requestOptions.body);
+    if (requestOptions.body !== void 0) {
+      if (isFormData(requestOptions.body)) {
+        deleteHeader(headers, "content-type");
+        fetchOptions.body = requestOptions.body;
+      } else {
+        fetchOptions.body = JSON.stringify(requestOptions.body);
+      }
     }
     const response = await fetch(url.toString(), fetchOptions);
+    applyFarmCacheInvalidations(
+      decodeFarmCacheInvalidations(response.headers?.get?.(FARM_CACHE_INVALIDATION_HEADER))
+    );
     let data = void 0;
     if (response.status !== 204 && response.status !== 205) {
-      data = await response.json();
+      data = isJSONStreamResponse(response) ? readJSONStream(response) : await response.json();
     }
     return { response, data };
   }, "fetchClient");
@@ -2405,16 +3200,16 @@ function createAPIClient(options = {}) {
             }
           }
           attempt += 1;
-          const delay = typeof clientOptions?.retry?.delay === "function" ? clientOptions.retry.delay(attempt) : clientOptions?.retry?.delay ?? 0;
-          if (delay > 0) {
-            await new Promise((resolve) => setTimeout(resolve, delay));
+          const delay2 = typeof clientOptions?.retry?.delay === "function" ? clientOptions.retry.delay(attempt) : clientOptions?.retry?.delay ?? 0;
+          if (delay2 > 0) {
+            await new Promise((resolve) => setTimeout(resolve, delay2));
           }
         }
       })();
       inflightState.set(cacheKey, { promise, startedAt: now });
       try {
         const result2 = await promise;
-        if (!result2.error && isCacheEnabled) {
+        if (!result2.error && isCacheEnabled && !isFarmAPIStream(result2.data)) {
           const updatedAt = Date.now();
           cacheState.set(cacheKey, {
             data: result2.data,
@@ -2487,19 +3282,48 @@ function createAPIClient(options = {}) {
     clientOptions?.onSettled?.(result.data, result.error);
     return result;
   }, "request");
-  return createNestedProxy([], request, routeMeta, baseURL, rootAliases);
+  return createNestedProxy(
+    [],
+    request,
+    routeMeta,
+    baseURL,
+    options.baseURL === void 0,
+    rootAliases
+  );
 }
 __name(createAPIClient, "createAPIClient");
-function createNestedProxy(path4, client, routeMeta, baseURL, rootAliases) {
+function createNestedProxy(path4, client, routeMeta, baseURL, sameOrigin, rootAliases) {
   const target = /* @__PURE__ */ __name(() => {
   }, "target");
   const proxy = new Proxy(target, {
     // When accessing a property (api.hello)
     get(_target, prop) {
+      if (prop === FARM_API_ROUTE_REF_SYMBOL) {
+        return path4.length > 0;
+      }
+      if (prop === FARM_API_ROUTE_META_SYMBOL) {
+        const metadata = resolveRouteMeta({ path: path4, baseURL });
+        return Object.freeze({
+          path: metadata.routePath,
+          method: metadata.method,
+          baseURL,
+          sameOrigin
+        });
+      }
       if (path4.length === 0 && typeof prop === "string" && rootAliases && prop in rootAliases) {
         return rootAliases[prop];
       }
-      return createNestedProxy([...path4, prop], client, routeMeta, baseURL, rootAliases);
+      if (typeof prop !== "string") {
+        return Reflect.get(_target, prop);
+      }
+      return createNestedProxy(
+        [...path4, prop],
+        client,
+        routeMeta,
+        baseURL,
+        sameOrigin,
+        rootAliases
+      );
     },
     // When calling as a function
     apply(_target, _thisArg, args) {
@@ -2521,6 +3345,26 @@ function createNestedProxy(path4, client, routeMeta, baseURL, rootAliases) {
   return proxy;
 }
 __name(createNestedProxy, "createNestedProxy");
+function isAPIRouteRef(value) {
+  return typeof value === "function" && value[FARM_API_ROUTE_REF_SYMBOL] === true;
+}
+__name(isAPIRouteRef, "isAPIRouteRef");
+function getAPIRouteRefMetadata(value) {
+  if (!isAPIRouteRef(value)) return null;
+  const metadata = value[FARM_API_ROUTE_META_SYMBOL];
+  if (!metadata || typeof metadata !== "object") return null;
+  const candidate = metadata;
+  if (typeof candidate.path !== "string" || typeof candidate.method !== "string" || typeof candidate.baseURL !== "string" || typeof candidate.sameOrigin !== "boolean") {
+    return null;
+  }
+  return {
+    path: candidate.path,
+    method: candidate.method,
+    baseURL: candidate.baseURL,
+    sameOrigin: candidate.sameOrigin
+  };
+}
+__name(getAPIRouteRefMetadata, "getAPIRouteRefMetadata");
 function createServerAPIClient(endpoints, options = {}) {
   if (options.integrations === false || Object.prototype.hasOwnProperty.call(endpoints, "integrations")) {
     return endpoints;
@@ -2587,7 +3431,10 @@ function resolveTargetKey(routeMeta, target, input, baseURL = "http://localhost:
   }
   if (Array.isArray(target)) {
     const [route, routeInput] = target;
-    return resolveTargetKey(routeMeta, route, routeInput, baseURL);
+    if (typeof route === "function") {
+      return resolveTargetKey(routeMeta, route, routeInput, baseURL);
+    }
+    return normalizeFarmClientCacheKey(target);
   }
   if ("key" in target) return normalizeFarmClientCacheKey(target.key);
   if ("path" in target) {
@@ -2613,18 +3460,56 @@ function resolveRouteMeta(meta) {
 }
 __name(resolveRouteMeta, "resolveRouteMeta");
 function normalizeError(error) {
-  if (error instanceof Error) return error;
-  return new Error(typeof error === "string" ? error : "Unknown error");
+  if (error instanceof APIClientError) return error;
+  const normalized = new APIClientError("network_error", void 0, {
+    status: 0,
+    message: error instanceof Error ? error.message : typeof error === "string" ? error : "Network request failed"
+  });
+  normalized.cause = error;
+  return normalized;
 }
 __name(normalizeError, "normalizeError");
+function isFormData(value) {
+  return typeof value === "object" && value !== null && (typeof FormData !== "undefined" && value instanceof FormData || Object.prototype.toString.call(value) === "[object FormData]" && typeof value.entries === "function");
+}
+__name(isFormData, "isFormData");
+function deleteHeader(headers, name) {
+  const normalized = name.toLowerCase();
+  for (const key of Object.keys(headers)) {
+    if (key.toLowerCase() === normalized) delete headers[key];
+  }
+}
+__name(deleteHeader, "deleteHeader");
 function createResponseError2(response, data) {
-  const error = new Error(`HTTP ${response.status}: ${response.statusText}`);
-  error.status = response.status;
-  error.response = response;
-  error.data = data;
-  return error;
+  const expected = readEndpointErrorEnvelope(data);
+  if (expected) {
+    return new APIClientError(expected.code, expected.data, {
+      status: response.status,
+      message: expected.message,
+      response
+    });
+  }
+  return new APIClientError("http_error", data, {
+    status: response.status,
+    message: `HTTP ${response.status}: ${response.statusText}`,
+    response
+  });
 }
 __name(createResponseError2, "createResponseError");
+function readEndpointErrorEnvelope(data) {
+  if (!data || typeof data !== "object") return null;
+  const error = data.error;
+  if (!error || typeof error !== "object") return null;
+  const code = error.code;
+  const message = error.message;
+  if (typeof code !== "string" || typeof message !== "string") return null;
+  return {
+    code,
+    message,
+    data: error.data
+  };
+}
+__name(readEndpointErrorEnvelope, "readEndpointErrorEnvelope");
 
 // src/server/response.ts
 var import_node_events = require("events");
@@ -2996,69 +3881,71 @@ function farmApiPlugin(options = {}) {
         waitForDiscovery: /* @__PURE__ */ __name(() => discoveryPromise, "waitForDiscovery")
       };
       return () => {
-        server.middlewares.use(_withAfterNodeMiddleware(async (req, res, next) => {
-          const url = req.url || "/";
-          const pathname = url.split("?")[0];
-          const method = req.method || "GET";
-          if (discoveryPromise && !discoveryComplete) {
-            await discoveryPromise;
-          }
-          if (!matchAPIRoute(apiRoutesCache, pathname)) {
-            return next();
-          }
-          if (!apiRouterHandler) {
-            return next();
-          }
-          const startTime = Date.now();
-          try {
-            const farmMiddleware = server.__farmMiddleware__;
-            if (farmMiddleware) {
-              await farmMiddleware.waitForDiscovery?.();
-              const middlewareData = /* @__PURE__ */ new Map();
-              const handled = await farmMiddleware.execute(req, res, pathname, middlewareData);
-              if (handled) {
-                const duration2 = Date.now() - startTime;
-                logResponse(method, pathname, res.statusCode || 200, duration2);
-                return;
-              }
+        server.middlewares.use(
+          _withAfterNodeMiddleware(async (req, res, next) => {
+            const url = req.url || "/";
+            const pathname = url.split("?")[0];
+            const method = req.method || "GET";
+            if (discoveryPromise && !discoveryComplete) {
+              await discoveryPromise;
             }
-            const fullUrl = `http://${req.headers.host || "localhost:3000"}${url}`;
-            const headers = new Headers();
-            for (const [key, value] of Object.entries(req.headers)) {
-              if (value) {
-                headers.set(key, Array.isArray(value) ? value.join(", ") : value);
-              }
+            if (!matchAPIRoute(apiRoutesCache, pathname)) {
+              return next();
             }
-            let body;
-            if (method !== "GET" && method !== "HEAD") {
-              body = await new Promise((resolve) => {
-                let data = "";
-                req.on("data", (chunk) => {
-                  data += chunk;
-                });
-                req.on("end", () => {
-                  resolve(data);
+            if (!apiRouterHandler) {
+              return next();
+            }
+            const startTime = Date.now();
+            try {
+              const farmMiddleware = server.__farmMiddleware__;
+              if (farmMiddleware) {
+                await farmMiddleware.waitForDiscovery?.();
+                const middlewareData = /* @__PURE__ */ new Map();
+                const handled = await farmMiddleware.execute(req, res, pathname, middlewareData);
+                if (handled) {
+                  const duration2 = Date.now() - startTime;
+                  logResponse(method, pathname, res.statusCode || 200, duration2);
+                  return;
+                }
+              }
+              const fullUrl = `http://${req.headers.host || "localhost:3000"}${url}`;
+              const headers = new Headers();
+              for (const [key, value] of Object.entries(req.headers)) {
+                if (value) {
+                  headers.set(key, Array.isArray(value) ? value.join(", ") : value);
+                }
+              }
+              let body;
+              if (method !== "GET" && method !== "HEAD") {
+                body = await new Promise((resolve) => {
+                  let data = "";
+                  req.on("data", (chunk) => {
+                    data += chunk;
+                  });
+                  req.on("end", () => {
+                    resolve(data);
+                  });
                 });
+              }
+              const request = new Request(fullUrl, {
+                method,
+                headers,
+                body: body || void 0
               });
+              const response = await apiRouterHandler(request);
+              const duration = Date.now() - startTime;
+              logResponse(method, pathname, response.status, duration);
+              await sendWebResponse(res, response);
+            } catch (error) {
+              const duration = Date.now() - startTime;
+              logResponse(method, pathname, 500, duration);
+              console.error("[FARM] API error:", error);
+              res.statusCode = 500;
+              res.setHeader("Content-Type", "application/json");
+              res.end(JSON.stringify({ error: "Internal server error" }));
             }
-            const request = new Request(fullUrl, {
-              method,
-              headers,
-              body: body || void 0
-            });
-            const response = await apiRouterHandler(request);
-            const duration = Date.now() - startTime;
-            logResponse(method, pathname, response.status, duration);
-            await sendWebResponse(res, response);
-          } catch (error) {
-            const duration = Date.now() - startTime;
-            logResponse(method, pathname, 500, duration);
-            console.error("[FARM] API error:", error);
-            res.statusCode = 500;
-            res.setHeader("Content-Type", "application/json");
-            res.end(JSON.stringify({ error: "Internal server error" }));
-          }
-        }));
+          })
+        );
       };
     },
     async handleHotUpdate({ file, server, modules }) {
@@ -3178,9 +4065,13 @@ function farmApiPlugin(options = {}) {
 __name(farmApiPlugin, "farmApiPlugin");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  APIClientError,
   APIRouteManager,
   API_ROUTE_METHODS,
   DELETE,
+  EndpointFailure,
+  FARM_API_ROUTE_META_SYMBOL,
+  FARM_API_ROUTE_REF_SYMBOL,
   GET,
   HEAD,
   OPTIONS,
@@ -3191,9 +4082,19 @@ __name(farmApiPlugin, "farmApiPlugin");
   createEndpoint,
   createServerAPIClient,
   farmApiPlugin,
+  getAPIRouteRefMetadata,
   invokeAPIRouteEndpoint,
+  isAPIRouteRef,
+  isEndpointFailure,
+  isFarmAPIStream,
+  isJSONStreamResponse,
+  isMultipartSchema,
   isWebResponse,
+  jsonStream,
   matchAPIRoute,
-  normalizeRouteResponse
+  multipart,
+  normalizeRouteResponse,
+  readJSONStream,
+  toFormData
 });
 //# sourceMappingURL=api.cjs.map