@farm.js/core 0.1.0-beta.3 → 0.1.0-beta.5

package/dist/api.cjs

@@ -36,6 +36,7 @@ __export(api_exports, {
   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,
@@ -47,12 +48,20 @@ __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);
 
@@ -180,7 +189,8 @@ var FARM_CACHE_INVALIDATION_STATE = /* @__PURE__ */ Symbol.for("farm.cacheInvali
 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");
@@ -191,6 +201,12 @@ function notifyFarmCacheInvalidation(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) {
@@ -236,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;
@@ -276,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 ?? []) {
@@ -288,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)
@@ -301,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();
@@ -314,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;
@@ -326,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);
@@ -334,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);
@@ -350,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;
     }
@@ -360,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(() => {
@@ -372,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()) {
@@ -399,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;
@@ -416,16 +656,52 @@ 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) {
-  getFarmDataCache().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);
-  getFarmDataCache().revalidateTag(createRouteDataCacheTag(key), { source: "updateTag" });
+  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)}`;
 }
@@ -486,6 +762,67 @@ function normalizeCacheTag(tag) {
   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}`;
@@ -540,6 +877,179 @@ function stableSerialize(value, seen = /* @__PURE__ */ new WeakSet()) {
 }
 __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) {
@@ -607,6 +1117,7 @@ function createEndpoint(pathOrOptions, optionsOrHandler, maybeHandler) {
   endpoint.__errors = errors;
   endpoint.__types = {
     body: options.body,
+    inputBody: isMultipartSchema(options.body) ? "form-data" : options.body,
     query: options.query,
     headers: options.headers,
     response: null,
@@ -725,37 +1236,12 @@ async function applyEndpointInvalidations(declaration, context, result) {
   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 } or { path } targets"
+      "Endpoint invalidates must resolve to an array of { key }, { path }, or { tag } targets"
     );
   }
-  const clientKeys = [];
-  for (const target of targets) {
-    assertEndpointInvalidationTarget(target);
-    if ("key" in target) {
-      invalidate(target.key);
-      clientKeys.push(createRouteDataCacheKey(target.key));
-    } else {
-      revalidatePath(target.path);
-    }
-  }
-  return Array.from(new Set(clientKeys));
+  return applyFarmCacheInvalidationTargets(targets);
 }
 __name(applyEndpointInvalidations, "applyEndpointInvalidations");
-function assertEndpointInvalidationTarget(target) {
-  if (!target || typeof target !== "object") {
-    throw new TypeError("Endpoint invalidation targets must be { key } or { path } objects");
-  }
-  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;
-  }
-  throw new TypeError(
-    "Endpoint invalidation targets must contain a string/array key or a path string"
-  );
-}
-__name(assertEndpointInvalidationTarget, "assertEndpointInvalidationTarget");
 function createInitialEndpointContext(value) {
   if (value === void 0 || value === null) return EMPTY_ENDPOINT_CONTEXT;
   if (!isPlainEndpointContext(value)) {
@@ -1248,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 || {};
@@ -1352,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;
@@ -2474,6 +2993,7 @@ __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);
@@ -2511,16 +3031,22 @@ 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(
@@ -2528,7 +3054,7 @@ function createAPIClient(options = {}) {
     );
     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");
@@ -2674,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,
@@ -2756,10 +3282,17 @@ 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, {
@@ -2768,13 +3301,29 @@ function createNestedProxy(path4, client, routeMeta, baseURL, rootAliases) {
       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];
       }
       if (typeof prop !== "string") {
         return Reflect.get(_target, prop);
       }
-      return createNestedProxy([...path4, prop], client, routeMeta, baseURL, rootAliases);
+      return createNestedProxy(
+        [...path4, prop],
+        client,
+        routeMeta,
+        baseURL,
+        sameOrigin,
+        rootAliases
+      );
     },
     // When calling as a function
     apply(_target, _thisArg, args) {
@@ -2800,6 +3349,22 @@ 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;
@@ -2904,6 +3469,17 @@ function normalizeError(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 expected = readEndpointErrorEnvelope(data);
   if (expected) {
@@ -3494,6 +4070,7 @@ __name(farmApiPlugin, "farmApiPlugin");
   API_ROUTE_METHODS,
   DELETE,
   EndpointFailure,
+  FARM_API_ROUTE_META_SYMBOL,
   FARM_API_ROUTE_REF_SYMBOL,
   GET,
   HEAD,
@@ -3505,11 +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