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

package/dist/api.cjs

@@ -31,9 +31,12 @@ 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_REF_SYMBOL: () => FARM_API_ROUTE_REF_SYMBOL,
   GET: () => GET,
   HEAD: () => HEAD,
   OPTIONS: () => OPTIONS,
@@ -45,6 +48,8 @@ __export(api_exports, {
   createServerAPIClient: () => createServerAPIClient,
   farmApiPlugin: () => farmApiPlugin,
   invokeAPIRouteEndpoint: () => invokeAPIRouteEndpoint,
+  isAPIRouteRef: () => isAPIRouteRef,
+  isEndpointFailure: () => isEndpointFailure,
   isWebResponse: () => isWebResponse,
   matchAPIRoute: () => matchAPIRoute,
   normalizeRouteResponse: () => normalizeRouteResponse
@@ -53,197 +58,6 @@ 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,6 +175,7 @@ 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() {
@@ -369,6 +184,42 @@ function getFarmCacheInvalidationState() {
   });
 }
 __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 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);
@@ -561,10 +412,28 @@ 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 revalidatePath(routePath) {
+  getFarmDataCache().revalidatePath(routePath);
+}
+__name(revalidatePath, "revalidatePath");
+function invalidate(key) {
+  const clientKey = createRouteDataCacheKey(key);
+  getFarmDataCache().revalidateTag(createRouteDataCacheTag(key), { source: "updateTag" });
+  notifyFarmCacheInvalidation(clientKey);
+}
+__name(invalidate, "invalidate");
 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]);
 }
@@ -671,6 +540,341 @@ function stableSerialize(value, seen = /* @__PURE__ */ new WeakSet()) {
 }
 __name(stableSerialize, "stableSerialize");
 
+// 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,
+    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(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 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 } or { path } 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));
+}
+__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)) {
+    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/route-runtime.ts
 function normalizeFarmRouteRuntimeConfig(value, source = "Route configuration") {
   if (!value) return {};
@@ -1032,10 +1236,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 = {};
@@ -1060,15 +1264,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 +1307,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;
@@ -1569,7 +1822,7 @@ function mergeIntegrationClientData(...values) {
       continue;
     }
     merged = {
-      ...merged || {},
+      ...merged,
       ...data
     };
   }
@@ -2220,6 +2473,19 @@ function normalizeFarmClientCacheKey(key) {
 __name(normalizeFarmClientCacheKey, "normalizeFarmClientCacheKey");
 
 // src/api/client.ts
+var FARM_API_ROUTE_REF_SYMBOL = /* @__PURE__ */ Symbol.for("farm.api.route-ref");
+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");
@@ -2257,6 +2523,9 @@ function createAPIClient(options = {}) {
       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();
@@ -2496,9 +2765,15 @@ function createNestedProxy(path4, client, routeMeta, baseURL, rootAliases) {
   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 (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);
     },
     // When calling as a function
@@ -2521,6 +2796,10 @@ 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 createServerAPIClient(endpoints, options = {}) {
   if (options.integrations === false || Object.prototype.hasOwnProperty.call(endpoints, "integrations")) {
     return endpoints;
@@ -2587,7 +2866,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 +2895,45 @@ 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 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 +3305,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 +3489,12 @@ 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_REF_SYMBOL,
   GET,
   HEAD,
   OPTIONS,
@@ -3192,6 +3506,8 @@ __name(farmApiPlugin, "farmApiPlugin");
   createServerAPIClient,
   farmApiPlugin,
   invokeAPIRouteEndpoint,
+  isAPIRouteRef,
+  isEndpointFailure,
   isWebResponse,
   matchAPIRoute,
   normalizeRouteResponse