enlace 0.0.1-beta.10 → 0.0.1-beta.12

package/README.md

@@ -85,37 +85,108 @@ api.users[123].get(); // GET /users/123
 api.users[123].profile.get(); // GET /users/123/profile
 ```
 
-### Endpoint Type
+### Endpoint Types
 
-The `Endpoint` type helper lets you define response data, request body, and optionally override the error type:
+The `Endpoint` type helpers let you define response data, request body, query params, formData, and error types.
+
+#### `Endpoint<TData, TBody?, TError?>`
+
+For endpoints with JSON body:
 
 ```typescript
-// Signature: Endpoint<TData, TBody?, TError?>
-type Endpoint<TData, TBody = never, TError = never>;
+import { Endpoint } from "enlace";
+
+type ApiSchema = {
+  posts: {
+    $get: Post[];                                   // Direct type (simplest)
+    $post: Endpoint<Post, CreatePost>;              // Data + Body
+    $put: Endpoint<Post, UpdatePost, ValidationError>; // Data + Body + Error
+    $delete: void;                                  // void response
+    $patch: Endpoint<Post, never, NotFoundError>;   // Custom error without body
+  };
+};
 ```
 
-**Three ways to define endpoints:**
+#### `EndpointWithQuery<TData, TQuery, TError?>`
+
+For endpoints with typed query parameters:
 
 ```typescript
+import { EndpointWithQuery } from "enlace";
+
 type ApiSchema = {
+  users: {
+    $get: EndpointWithQuery<User[], { page: number; limit: number; search?: string }>;
+  };
   posts: {
-    // 1. Direct type (simplest) - just the data type
-    //    Error comes from global default
-    $get: Post[];
+    $get: EndpointWithQuery<Post[], { status: "draft" | "published" }, ApiError>;
+  };
+};
+
+// Usage - query params are fully typed
+const { data } = useAPI((api) => api.users.get({ query: { page: 1, limit: 10 } }));
+// api.users.get({ query: { foo: "bar" } }); // ✗ Error: 'foo' does not exist
+```
+
+#### `EndpointWithFormData<TData, TFormData, TError?>`
+
+For file uploads (multipart/form-data):
+
+```typescript
+import { EndpointWithFormData } from "enlace";
+
+type ApiSchema = {
+  uploads: {
+    $post: EndpointWithFormData<Upload, { file: Blob | File; name: string }>;
+  };
+  avatars: {
+    $post: EndpointWithFormData<Avatar, { image: File }, UploadError>;
+  };
+};
+
+// Usage - formData is automatically converted to FormData
+const { trigger } = useAPI((api) => api.uploads.post);
+trigger({
+  formData: {
+    file: selectedFile,        // File object
+    name: "document.pdf",      // String - converted automatically
+  }
+});
+// → Sends as multipart/form-data
+```
+
+**FormData conversion rules:**
 
-    // 2. Endpoint with body - Endpoint<Data, Body>
-    //    Error comes from global default
-    $post: Endpoint<Post, CreatePost>;
+| Type | Conversion |
+|------|------------|
+| `File` / `Blob` | Appended directly |
+| `string` / `number` / `boolean` | Converted to string |
+| `object` (nested) | JSON stringified |
+| `array` of primitives | Each item appended separately |
+| `array` of files | Each file appended with same key |
 
-    // 3. Endpoint with custom error - Endpoint<Data, Body, Error>
-    //    Overrides global error type for this endpoint
-    $put: Endpoint<Post, UpdatePost, ValidationError>;
+#### `EndpointFull<T>`
 
-    // void response - use void directly
-    $delete: void;
+Object-style for complex endpoints:
 
-    // Custom error without body - use `never` for body
-    $patch: Endpoint<Post, never, NotFoundError>;
+```typescript
+import { EndpointFull } from "enlace";
+
+type ApiSchema = {
+  products: {
+    $post: EndpointFull<{
+      data: Product;
+      body: CreateProduct;
+      query: { categoryId: string };
+      error: ValidationError;
+    }>;
+  };
+  files: {
+    $post: EndpointFull<{
+      data: FileUpload;
+      formData: { file: File; description: string };
+      query: { folder: string };
+    }>;
   };
 };
 ```
@@ -270,7 +341,7 @@ function PostList({ posts }: { posts: Post[] }) {
 
   const handleDelete = (postId: number) => {
     // Pass the actual ID when triggering
-    trigger({ pathParams: { id: postId } });
+    trigger({ params: { id: postId } });
   };
 
   return (
@@ -295,7 +366,7 @@ const { trigger } = useAPI(
   (api) => api.users[":userId"].posts[":postId"].delete
 );
 
-trigger({ pathParams: { userId: "1", postId: "42" } });
+trigger({ params: { userId: "1", postId: "42" } });
 // → DELETE /users/1/posts/42
 ```
 
@@ -305,7 +376,7 @@ trigger({ pathParams: { userId: "1", postId: "42" } });
 const { trigger } = useAPI((api) => api.products[":id"].patch);
 
 trigger({
-  pathParams: { id: "123" },
+  params: { id: "123" },
   body: { name: "Updated Product" },
 });
 // → PATCH /products/123 with body
@@ -541,12 +612,13 @@ type UseEnlaceSelectorResult<TMethod> = {
 
 ```typescript
 type RequestOptions = {
-  query?: Record<string, unknown>; // Query parameters
-  body?: TBody; // Request body
+  query?: TQuery; // Query parameters (typed when using EndpointWithQuery/EndpointFull)
+  body?: TBody; // Request body (JSON)
+  formData?: TFormData; // FormData fields (auto-converted, for file uploads)
   headers?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>); // Request headers
   tags?: string[]; // Cache tags (GET only)
   revalidateTags?: string[]; // Tags to invalidate after mutation
-  pathParams?: Record<string, string | number>; // Dynamic path parameters
+  params?: Record<string, string | number>; // Dynamic path parameters
 };
 ```
 
@@ -623,7 +695,7 @@ const useAPI = createEnlaceHookNext<ApiSchema, ApiError>(
   "/api",
   {},
   {
-    revalidator: revalidateAction,
+    serverRevalidator: revalidateAction,
   }
 );
 ```
@@ -637,13 +709,46 @@ function CreatePost() {
   const handleCreate = () => {
     trigger({
       body: { title: "New Post" },
-      revalidateTags: ["posts"], // Passed to revalidator
-      revalidatePaths: ["/posts"], // Passed to revalidator
+      revalidateTags: ["posts"], // Passed to serverRevalidator
+      revalidatePaths: ["/posts"], // Passed to serverRevalidator
     });
   };
 }
 ```
 
+### CSR-Heavy Projects
+
+For projects that primarily use client-side rendering with minimal SSR, you can disable server-side revalidation by default:
+
+```typescript
+const useAPI = createEnlaceHookNext<ApiSchema, ApiError>(
+  "/api",
+  {},
+  {
+    serverRevalidator: revalidateAction,
+    skipServerRevalidation: true, // Disable server revalidation by default
+  }
+);
+
+// Mutations won't trigger server revalidation by default
+await trigger({ body: { title: "New Post" } });
+
+// Opt-in to server revalidation when needed
+await trigger({ body: { title: "New Post" }, serverRevalidate: true });
+```
+
+### Per-Request Server Revalidation Control
+
+Override the global setting for individual requests:
+
+```typescript
+// Skip server revalidation for this request
+await trigger({ body: data, serverRevalidate: false });
+
+// Force server revalidation for this request
+await trigger({ body: data, serverRevalidate: true });
+```
+
 ### Next.js Request Options
 
 ```typescript
@@ -652,7 +757,7 @@ api.posts.get({
   revalidate: 60, // ISR revalidation (seconds)
   revalidateTags: ["posts"], // Tags to invalidate after mutation
   revalidatePaths: ["/"], // Paths to revalidate after mutation
-  skipRevalidator: false, // Skip server-side revalidation
+  serverRevalidate: true, // Control server-side revalidation per-request
 });
 ```
 
@@ -710,7 +815,10 @@ type EnlaceHookOptions = {
 
 ### Re-exports from enlace-core
 
-- `Endpoint` — Type helper for schema definition
+- `Endpoint` — Type helper for endpoints with JSON body
+- `EndpointWithQuery` — Type helper for endpoints with typed query params
+- `EndpointWithFormData` — Type helper for file upload endpoints
+- `EndpointFull` — Object-style type helper for complex endpoints
 - `EnlaceResponse` — Response type
 - `EnlaceOptions` — Fetch options type
 

package/dist/hook/index.d.mts

@@ -15,9 +15,9 @@ type ReactRequestOptionsBase = {
      * Used to replace :paramName placeholders in the URL path.
      * @example
      * // With path api.products[':id'].delete
-     * trigger({ pathParams: { id: '123' } }) // → DELETE /products/123
+     * trigger({ params: { id: '123' } }) // → DELETE /products/123
      */
-    pathParams?: Record<string, string | number>;
+    params?: Record<string, string | number>;
 };
 /** Options for query mode hooks */
 type UseEnlaceQueryOptions = {
@@ -108,7 +108,7 @@ declare function createEnlaceHookReact<TSchema = unknown, TDefaultError = unknow
  * @param tags - Cache tags to revalidate
  * @param paths - URL paths to revalidate
  */
-type RevalidateHandler = (tags: string[], paths: string[]) => void | Promise<void>;
+type ServerRevalidateHandler = (tags: string[], paths: string[]) => void | Promise<void>;
 /** Next.js-specific options (third argument for createEnlaceNext) */
 type NextOptions = Pick<EnlaceHookOptions, "autoGenerateTags" | "autoRevalidateTags"> & EnlaceCallbacks & {
     /**
@@ -117,32 +117,37 @@ type NextOptions = Pick<EnlaceHookOptions, "autoGenerateTags" | "autoRevalidateT
      * @example
      * ```ts
      * createEnlaceNext("http://localhost:3000/api/", {}, {
-     *   revalidator: (tags, paths) => revalidateServerAction(tags, paths)
+     *   serverRevalidator: (tags, paths) => revalidateServerAction(tags, paths)
      * });
      * ```
      */
-    revalidator?: RevalidateHandler;
+    serverRevalidator?: ServerRevalidateHandler;
+    /**
+     * Skip server-side revalidation by default for all mutations.
+     * Individual requests can override with serverRevalidate: true.
+     * Useful for CSR-heavy apps where server cache invalidation is rarely needed.
+     * @default false
+     */
+    skipServerRevalidation?: boolean;
 };
 /** Next.js hook options (third argument for createEnlaceHookNext) - extends React's EnlaceHookOptions */
-type NextHookOptions = EnlaceHookOptions & Pick<NextOptions, "revalidator">;
+type NextHookOptions = EnlaceHookOptions & Pick<NextOptions, "serverRevalidator" | "skipServerRevalidation">;
 /** Per-request options for Next.js fetch - extends React's base options */
 type NextRequestOptionsBase = ReactRequestOptionsBase & {
     /** Time in seconds to revalidate, or false to disable */
     revalidate?: number | false;
     /**
-     * URL paths to revalidate after mutation
-     * This doesn't do anything on the client by itself - it's passed to the revalidator handler.
-     * You must implement the revalidation logic in the revalidator.
+     * URL paths to revalidate after mutation.
+     * Passed to the serverRevalidator handler.
      */
     revalidatePaths?: string[];
     /**
-     * Skip server-side revalidation for this request.
-     * Useful when autoRevalidateTags is enabled but you want to opt-out for specific mutations.
-     * You can still pass empty [] to revalidateTags to skip triggering revalidation.
-     * But this flag can be used if you want to revalidate client-side and skip server-side entirely.
-     * Eg. you don't fetch any data on server component and you might want to skip the overhead of revalidation.
+     * Control server-side revalidation for this specific request.
+     * - true: Force server revalidation
+     * - false: Skip server revalidation
+     * When undefined, follows the global skipServerRevalidation setting.
      */
-    skipRevalidator?: boolean;
+    serverRevalidate?: boolean;
 };
 type NextQueryFn<TSchema, TData, TError, TDefaultError = unknown> = QueryFn<TSchema, TData, TError, TDefaultError, NextRequestOptionsBase>;
 type NextSelectorFn<TSchema, TMethod, TDefaultError = unknown> = SelectorFn<TSchema, TMethod, TDefaultError, NextRequestOptionsBase>;
@@ -154,11 +159,11 @@ type NextEnlaceHook<TSchema, TDefaultError = unknown> = {
 
 /**
  * Creates a React hook for making API calls in Next.js Client Components.
- * Uses Next.js-specific features like revalidator for server-side cache invalidation.
+ * Uses Next.js-specific features like serverRevalidator for server-side cache invalidation.
  *
  * @example
  * const useAPI = createEnlaceHookNext<ApiSchema>('https://api.com', {}, {
- *   revalidator: (tags) => revalidateTagsAction(tags),
+ *   serverRevalidator: (tags) => revalidateTagsAction(tags),
  *   staleTime: 5000,
  * });
  *

package/dist/hook/index.d.ts

@@ -15,9 +15,9 @@ type ReactRequestOptionsBase = {
      * Used to replace :paramName placeholders in the URL path.
      * @example
      * // With path api.products[':id'].delete
-     * trigger({ pathParams: { id: '123' } }) // → DELETE /products/123
+     * trigger({ params: { id: '123' } }) // → DELETE /products/123
      */
-    pathParams?: Record<string, string | number>;
+    params?: Record<string, string | number>;
 };
 /** Options for query mode hooks */
 type UseEnlaceQueryOptions = {
@@ -108,7 +108,7 @@ declare function createEnlaceHookReact<TSchema = unknown, TDefaultError = unknow
  * @param tags - Cache tags to revalidate
  * @param paths - URL paths to revalidate
  */
-type RevalidateHandler = (tags: string[], paths: string[]) => void | Promise<void>;
+type ServerRevalidateHandler = (tags: string[], paths: string[]) => void | Promise<void>;
 /** Next.js-specific options (third argument for createEnlaceNext) */
 type NextOptions = Pick<EnlaceHookOptions, "autoGenerateTags" | "autoRevalidateTags"> & EnlaceCallbacks & {
     /**
@@ -117,32 +117,37 @@ type NextOptions = Pick<EnlaceHookOptions, "autoGenerateTags" | "autoRevalidateT
      * @example
      * ```ts
      * createEnlaceNext("http://localhost:3000/api/", {}, {
-     *   revalidator: (tags, paths) => revalidateServerAction(tags, paths)
+     *   serverRevalidator: (tags, paths) => revalidateServerAction(tags, paths)
      * });
      * ```
      */
-    revalidator?: RevalidateHandler;
+    serverRevalidator?: ServerRevalidateHandler;
+    /**
+     * Skip server-side revalidation by default for all mutations.
+     * Individual requests can override with serverRevalidate: true.
+     * Useful for CSR-heavy apps where server cache invalidation is rarely needed.
+     * @default false
+     */
+    skipServerRevalidation?: boolean;
 };
 /** Next.js hook options (third argument for createEnlaceHookNext) - extends React's EnlaceHookOptions */
-type NextHookOptions = EnlaceHookOptions & Pick<NextOptions, "revalidator">;
+type NextHookOptions = EnlaceHookOptions & Pick<NextOptions, "serverRevalidator" | "skipServerRevalidation">;
 /** Per-request options for Next.js fetch - extends React's base options */
 type NextRequestOptionsBase = ReactRequestOptionsBase & {
     /** Time in seconds to revalidate, or false to disable */
     revalidate?: number | false;
     /**
-     * URL paths to revalidate after mutation
-     * This doesn't do anything on the client by itself - it's passed to the revalidator handler.
-     * You must implement the revalidation logic in the revalidator.
+     * URL paths to revalidate after mutation.
+     * Passed to the serverRevalidator handler.
      */
     revalidatePaths?: string[];
     /**
-     * Skip server-side revalidation for this request.
-     * Useful when autoRevalidateTags is enabled but you want to opt-out for specific mutations.
-     * You can still pass empty [] to revalidateTags to skip triggering revalidation.
-     * But this flag can be used if you want to revalidate client-side and skip server-side entirely.
-     * Eg. you don't fetch any data on server component and you might want to skip the overhead of revalidation.
+     * Control server-side revalidation for this specific request.
+     * - true: Force server revalidation
+     * - false: Skip server revalidation
+     * When undefined, follows the global skipServerRevalidation setting.
      */
-    skipRevalidator?: boolean;
+    serverRevalidate?: boolean;
 };
 type NextQueryFn<TSchema, TData, TError, TDefaultError = unknown> = QueryFn<TSchema, TData, TError, TDefaultError, NextRequestOptionsBase>;
 type NextSelectorFn<TSchema, TMethod, TDefaultError = unknown> = SelectorFn<TSchema, TMethod, TDefaultError, NextRequestOptionsBase>;
@@ -154,11 +159,11 @@ type NextEnlaceHook<TSchema, TDefaultError = unknown> = {
 
 /**
  * Creates a React hook for making API calls in Next.js Client Components.
- * Uses Next.js-specific features like revalidator for server-side cache invalidation.
+ * Uses Next.js-specific features like serverRevalidator for server-side cache invalidation.
  *
  * @example
  * const useAPI = createEnlaceHookNext<ApiSchema>('https://api.com', {}, {
- *   revalidator: (tags) => revalidateTagsAction(tags),
+ *   serverRevalidator: (tags) => revalidateTagsAction(tags),
  *   staleTime: 5000,
  * });
  *

package/dist/hook/index.js

@@ -49,7 +49,8 @@ function hookReducer(state, action) {
       return {
         ...state,
         loading: state.data === void 0,
-        fetching: true
+        fetching: true,
+        error: void 0
       };
     case "FETCH_SUCCESS":
       return {
@@ -78,12 +79,21 @@ function generateTags(path) {
 }
 
 // src/utils/sortObjectKeys.ts
-function sortObjectKeys(obj) {
+function sortObjectKeys(obj, seen = /* @__PURE__ */ new WeakSet()) {
   if (obj === null || typeof obj !== "object") return obj;
-  if (Array.isArray(obj)) return obj.map(sortObjectKeys);
+  if (seen.has(obj)) {
+    return "[Circular]";
+  }
+  seen.add(obj);
+  if (Array.isArray(obj)) {
+    return obj.map((item) => sortObjectKeys(item, seen));
+  }
   return Object.keys(obj).sort().reduce(
     (sorted, key) => {
-      sorted[key] = sortObjectKeys(obj[key]);
+      sorted[key] = sortObjectKeys(
+        obj[key],
+        seen
+      );
       return sorted;
     },
     {}
@@ -149,10 +159,9 @@ function clearCacheByTags(tags) {
   cache.forEach((entry) => {
     const hasMatch = entry.tags.some((tag) => tags.includes(tag));
     if (hasMatch) {
-      entry.data = void 0;
-      entry.error = void 0;
       entry.timestamp = 0;
       delete entry.promise;
+      entry.subscribers.forEach((cb) => cb());
     }
   });
 }
@@ -169,12 +178,12 @@ function onRevalidate(callback) {
 }
 
 // src/react/useQueryMode.ts
-function resolvePath(path, pathParams) {
-  if (!pathParams) return path;
+function resolvePath(path, params) {
+  if (!params) return path;
   return path.map((segment) => {
     if (segment.startsWith(":")) {
       const paramName = segment.slice(1);
-      const value = pathParams[paramName];
+      const value = params[paramName];
       if (value === void 0) {
         throw new Error(`Missing path parameter: ${paramName}`);
       }
@@ -187,16 +196,14 @@ function useQueryMode(api, trackedCall, options) {
   const { autoGenerateTags, staleTime, enabled } = options;
   const queryKey = createQueryKey(trackedCall);
   const requestOptions = trackedCall.options;
-  const resolvedPath = resolvePath(
-    trackedCall.path,
-    requestOptions?.pathParams
-  );
+  const resolvedPath = resolvePath(trackedCall.path, requestOptions?.params);
   const queryTags = requestOptions?.tags ?? (autoGenerateTags ? generateTags(resolvedPath) : []);
   const getCacheState = (includeNeedsFetch = false) => {
     const cached = getCache(queryKey);
     const hasCachedData = cached?.data !== void 0;
     const isFetching = !!cached?.promise;
-    const needsFetch = includeNeedsFetch && (!hasCachedData || isStale(queryKey, staleTime));
+    const stale = isStale(queryKey, staleTime);
+    const needsFetch = includeNeedsFetch && (!hasCachedData || stale);
     return {
       loading: !hasCachedData && (isFetching || needsFetch),
       fetching: isFetching || needsFetch,
@@ -240,6 +247,15 @@ function useQueryMode(api, trackedCall, options) {
             tags: queryTags
           });
         }
+      }).catch((err) => {
+        if (mountedRef.current) {
+          setCache(queryKey, {
+            data: void 0,
+            error: err,
+            timestamp: Date.now(),
+            tags: queryTags
+          });
+        }
       });
       setCache(queryKey, {
         promise: fetchPromise,
@@ -310,12 +326,12 @@ function createTrackingProxy(onTrack) {
 
 // src/react/useSelectorMode.ts
 var import_react2 = require("react");
-function resolvePath2(path, pathParams) {
-  if (!pathParams) return path;
+function resolvePath2(path, params) {
+  if (!params) return path;
   return path.map((segment) => {
     if (segment.startsWith(":")) {
       const paramName = segment.slice(1);
-      const value = pathParams[paramName];
+      const value = params[paramName];
       if (value === void 0) {
         throw new Error(`Missing path parameter: ${paramName}`);
       }
@@ -345,7 +361,7 @@ function useSelectorMode(config) {
     triggerRef.current = (async (...args) => {
       dispatch({ type: "FETCH_START" });
       const options = args[0];
-      const resolvedPath = resolvePath2(pathRef.current, options?.pathParams);
+      const resolvedPath = resolvePath2(pathRef.current, options?.params);
       let res;
       if (hasPathParams(pathRef.current)) {
         let current = apiRef.current;
@@ -384,7 +400,10 @@ function createEnlaceHookReact(baseUrl, defaultOptions = {}, hookOptions = {}) {
     onSuccess,
     onError
   } = hookOptions;
-  const api = (0, import_enlace_core.createEnlace)(baseUrl, defaultOptions, { onSuccess, onError });
+  const api = (0, import_enlace_core.createEnlace)(baseUrl, defaultOptions, {
+    onSuccess,
+    onError
+  });
   function useEnlaceHook(selectorOrQuery, queryOptions) {
     let trackingResult = {
       trackedCall: null,
@@ -394,9 +413,7 @@ function createEnlaceHookReact(baseUrl, defaultOptions = {}, hookOptions = {}) {
     const trackingProxy = createTrackingProxy((result2) => {
       trackingResult = result2;
     });
-    const result = selectorOrQuery(
-      trackingProxy
-    );
+    const result = selectorOrQuery(trackingProxy);
     if (typeof result === "function") {
       const actualResult = selectorOrQuery(api);
       return useSelectorMode({
@@ -407,6 +424,11 @@ function createEnlaceHookReact(baseUrl, defaultOptions = {}, hookOptions = {}) {
         autoRevalidateTags
       });
     }
+    if (!trackingResult.trackedCall) {
+      throw new Error(
+        "useAPI query mode requires calling an HTTP method (get, post, etc.). Did you mean to use selector mode? Example: useAPI((api) => api.posts.get())"
+      );
+    }
     return useQueryMode(
       api,
       trackingResult.trackedCall,
@@ -425,18 +447,22 @@ async function executeNextFetch(baseUrl, path, method, combinedOptions, requestO
   const {
     autoGenerateTags = true,
     autoRevalidateTags = true,
-    revalidator,
+    skipServerRevalidation = false,
+    serverRevalidator,
     onSuccess,
     ...coreOptions
   } = combinedOptions;
   const isGet = method === "GET";
   const autoTags = generateTags(path);
   const nextOnSuccess = (payload) => {
-    if (!isGet && !requestOptions?.skipRevalidator) {
-      const revalidateTags = requestOptions?.revalidateTags ?? (autoRevalidateTags ? autoTags : []);
-      const revalidatePaths = requestOptions?.revalidatePaths ?? [];
-      if (revalidateTags.length || revalidatePaths.length) {
-        revalidator?.(revalidateTags, revalidatePaths);
+    if (!isGet) {
+      const shouldRevalidateServer = requestOptions?.serverRevalidate ?? !skipServerRevalidation;
+      if (shouldRevalidateServer) {
+        const revalidateTags = requestOptions?.revalidateTags ?? (autoRevalidateTags ? autoTags : []);
+        const revalidatePaths = requestOptions?.revalidatePaths ?? [];
+        if (revalidateTags.length || revalidatePaths.length) {
+          serverRevalidator?.(revalidateTags, revalidatePaths);
+        }
       }
     }
     onSuccess?.(payload);
@@ -481,11 +507,15 @@ function createEnlaceHookNext(baseUrl, defaultOptions = {}, hookOptions = {}) {
     staleTime = 0,
     ...nextOptions
   } = hookOptions;
-  const api = createEnlaceNext(baseUrl, defaultOptions, {
-    autoGenerateTags,
-    autoRevalidateTags,
-    ...nextOptions
-  });
+  const api = createEnlaceNext(
+    baseUrl,
+    defaultOptions,
+    {
+      autoGenerateTags,
+      autoRevalidateTags,
+      ...nextOptions
+    }
+  );
   function useEnlaceHook(selectorOrQuery, queryOptions) {
     let trackedCall = null;
     let selectorPath = null;
@@ -506,6 +536,11 @@ function createEnlaceHookNext(baseUrl, defaultOptions = {}, hookOptions = {}) {
         autoRevalidateTags
       });
     }
+    if (!trackedCall) {
+      throw new Error(
+        "useAPI query mode requires calling an HTTP method (get, post, etc.). Did you mean to use selector mode? Example: useAPI((api) => api.posts.get())"
+      );
+    }
     return useQueryMode(
       api,
       trackedCall,

package/dist/hook/index.mjs

@@ -2,7 +2,9 @@
 "use client";
 
 // src/react/createEnlaceHookReact.ts
-import { createEnlace } from "enlace-core";
+import {
+  createEnlace
+} from "enlace-core";
 
 // src/react/useQueryMode.ts
 import { useRef, useReducer, useEffect } from "react";
@@ -22,7 +24,8 @@ function hookReducer(state, action) {
       return {
         ...state,
         loading: state.data === void 0,
-        fetching: true
+        fetching: true,
+        error: void 0
       };
     case "FETCH_SUCCESS":
       return {
@@ -51,12 +54,21 @@ function generateTags(path) {
 }
 
 // src/utils/sortObjectKeys.ts
-function sortObjectKeys(obj) {
+function sortObjectKeys(obj, seen = /* @__PURE__ */ new WeakSet()) {
   if (obj === null || typeof obj !== "object") return obj;
-  if (Array.isArray(obj)) return obj.map(sortObjectKeys);
+  if (seen.has(obj)) {
+    return "[Circular]";
+  }
+  seen.add(obj);
+  if (Array.isArray(obj)) {
+    return obj.map((item) => sortObjectKeys(item, seen));
+  }
   return Object.keys(obj).sort().reduce(
     (sorted, key) => {
-      sorted[key] = sortObjectKeys(obj[key]);
+      sorted[key] = sortObjectKeys(
+        obj[key],
+        seen
+      );
       return sorted;
     },
     {}
@@ -122,10 +134,9 @@ function clearCacheByTags(tags) {
   cache.forEach((entry) => {
     const hasMatch = entry.tags.some((tag) => tags.includes(tag));
     if (hasMatch) {
-      entry.data = void 0;
-      entry.error = void 0;
       entry.timestamp = 0;
       delete entry.promise;
+      entry.subscribers.forEach((cb) => cb());
     }
   });
 }
@@ -142,12 +153,12 @@ function onRevalidate(callback) {
 }
 
 // src/react/useQueryMode.ts
-function resolvePath(path, pathParams) {
-  if (!pathParams) return path;
+function resolvePath(path, params) {
+  if (!params) return path;
   return path.map((segment) => {
     if (segment.startsWith(":")) {
       const paramName = segment.slice(1);
-      const value = pathParams[paramName];
+      const value = params[paramName];
       if (value === void 0) {
         throw new Error(`Missing path parameter: ${paramName}`);
       }
@@ -160,16 +171,14 @@ function useQueryMode(api, trackedCall, options) {
   const { autoGenerateTags, staleTime, enabled } = options;
   const queryKey = createQueryKey(trackedCall);
   const requestOptions = trackedCall.options;
-  const resolvedPath = resolvePath(
-    trackedCall.path,
-    requestOptions?.pathParams
-  );
+  const resolvedPath = resolvePath(trackedCall.path, requestOptions?.params);
   const queryTags = requestOptions?.tags ?? (autoGenerateTags ? generateTags(resolvedPath) : []);
   const getCacheState = (includeNeedsFetch = false) => {
     const cached = getCache(queryKey);
     const hasCachedData = cached?.data !== void 0;
     const isFetching = !!cached?.promise;
-    const needsFetch = includeNeedsFetch && (!hasCachedData || isStale(queryKey, staleTime));
+    const stale = isStale(queryKey, staleTime);
+    const needsFetch = includeNeedsFetch && (!hasCachedData || stale);
     return {
       loading: !hasCachedData && (isFetching || needsFetch),
       fetching: isFetching || needsFetch,
@@ -213,6 +222,15 @@ function useQueryMode(api, trackedCall, options) {
             tags: queryTags
           });
         }
+      }).catch((err) => {
+        if (mountedRef.current) {
+          setCache(queryKey, {
+            data: void 0,
+            error: err,
+            timestamp: Date.now(),
+            tags: queryTags
+          });
+        }
       });
       setCache(queryKey, {
         promise: fetchPromise,
@@ -283,12 +301,12 @@ function createTrackingProxy(onTrack) {
 
 // src/react/useSelectorMode.ts
 import { useRef as useRef2, useReducer as useReducer2 } from "react";
-function resolvePath2(path, pathParams) {
-  if (!pathParams) return path;
+function resolvePath2(path, params) {
+  if (!params) return path;
   return path.map((segment) => {
     if (segment.startsWith(":")) {
       const paramName = segment.slice(1);
-      const value = pathParams[paramName];
+      const value = params[paramName];
       if (value === void 0) {
         throw new Error(`Missing path parameter: ${paramName}`);
       }
@@ -318,7 +336,7 @@ function useSelectorMode(config) {
     triggerRef.current = (async (...args) => {
       dispatch({ type: "FETCH_START" });
       const options = args[0];
-      const resolvedPath = resolvePath2(pathRef.current, options?.pathParams);
+      const resolvedPath = resolvePath2(pathRef.current, options?.params);
       let res;
       if (hasPathParams(pathRef.current)) {
         let current = apiRef.current;
@@ -357,7 +375,10 @@ function createEnlaceHookReact(baseUrl, defaultOptions = {}, hookOptions = {}) {
     onSuccess,
     onError
   } = hookOptions;
-  const api = createEnlace(baseUrl, defaultOptions, { onSuccess, onError });
+  const api = createEnlace(baseUrl, defaultOptions, {
+    onSuccess,
+    onError
+  });
   function useEnlaceHook(selectorOrQuery, queryOptions) {
     let trackingResult = {
       trackedCall: null,
@@ -367,9 +388,7 @@ function createEnlaceHookReact(baseUrl, defaultOptions = {}, hookOptions = {}) {
     const trackingProxy = createTrackingProxy((result2) => {
       trackingResult = result2;
     });
-    const result = selectorOrQuery(
-      trackingProxy
-    );
+    const result = selectorOrQuery(trackingProxy);
     if (typeof result === "function") {
       const actualResult = selectorOrQuery(api);
       return useSelectorMode({
@@ -380,6 +399,11 @@ function createEnlaceHookReact(baseUrl, defaultOptions = {}, hookOptions = {}) {
         autoRevalidateTags
       });
     }
+    if (!trackingResult.trackedCall) {
+      throw new Error(
+        "useAPI query mode requires calling an HTTP method (get, post, etc.). Did you mean to use selector mode? Example: useAPI((api) => api.posts.get())"
+      );
+    }
     return useQueryMode(
       api,
       trackingResult.trackedCall,
@@ -402,18 +426,22 @@ async function executeNextFetch(baseUrl, path, method, combinedOptions, requestO
   const {
     autoGenerateTags = true,
     autoRevalidateTags = true,
-    revalidator,
+    skipServerRevalidation = false,
+    serverRevalidator,
     onSuccess,
     ...coreOptions
   } = combinedOptions;
   const isGet = method === "GET";
   const autoTags = generateTags(path);
   const nextOnSuccess = (payload) => {
-    if (!isGet && !requestOptions?.skipRevalidator) {
-      const revalidateTags = requestOptions?.revalidateTags ?? (autoRevalidateTags ? autoTags : []);
-      const revalidatePaths = requestOptions?.revalidatePaths ?? [];
-      if (revalidateTags.length || revalidatePaths.length) {
-        revalidator?.(revalidateTags, revalidatePaths);
+    if (!isGet) {
+      const shouldRevalidateServer = requestOptions?.serverRevalidate ?? !skipServerRevalidation;
+      if (shouldRevalidateServer) {
+        const revalidateTags = requestOptions?.revalidateTags ?? (autoRevalidateTags ? autoTags : []);
+        const revalidatePaths = requestOptions?.revalidatePaths ?? [];
+        if (revalidateTags.length || revalidatePaths.length) {
+          serverRevalidator?.(revalidateTags, revalidatePaths);
+        }
       }
     }
     onSuccess?.(payload);
@@ -458,11 +486,15 @@ function createEnlaceHookNext(baseUrl, defaultOptions = {}, hookOptions = {}) {
     staleTime = 0,
     ...nextOptions
   } = hookOptions;
-  const api = createEnlaceNext(baseUrl, defaultOptions, {
-    autoGenerateTags,
-    autoRevalidateTags,
-    ...nextOptions
-  });
+  const api = createEnlaceNext(
+    baseUrl,
+    defaultOptions,
+    {
+      autoGenerateTags,
+      autoRevalidateTags,
+      ...nextOptions
+    }
+  );
   function useEnlaceHook(selectorOrQuery, queryOptions) {
     let trackedCall = null;
     let selectorPath = null;
@@ -483,6 +515,11 @@ function createEnlaceHookNext(baseUrl, defaultOptions = {}, hookOptions = {}) {
         autoRevalidateTags
       });
     }
+    if (!trackedCall) {
+      throw new Error(
+        "useAPI query mode requires calling an HTTP method (get, post, etc.). Did you mean to use selector mode? Example: useAPI((api) => api.posts.get())"
+      );
+    }
     return useQueryMode(
       api,
       trackedCall,

package/dist/index.d.mts

@@ -16,9 +16,9 @@ type ReactRequestOptionsBase = {
      * Used to replace :paramName placeholders in the URL path.
      * @example
      * // With path api.products[':id'].delete
-     * trigger({ pathParams: { id: '123' } }) // → DELETE /products/123
+     * trigger({ params: { id: '123' } }) // → DELETE /products/123
      */
-    pathParams?: Record<string, string | number>;
+    params?: Record<string, string | number>;
 };
 /** Options for createEnlaceHookReact factory */
 type EnlaceHookOptions = {
@@ -43,7 +43,7 @@ type EnlaceHookOptions = {
  * @param tags - Cache tags to revalidate
  * @param paths - URL paths to revalidate
  */
-type RevalidateHandler = (tags: string[], paths: string[]) => void | Promise<void>;
+type ServerRevalidateHandler = (tags: string[], paths: string[]) => void | Promise<void>;
 /** Next.js-specific options (third argument for createEnlaceNext) */
 type NextOptions = Pick<EnlaceHookOptions, "autoGenerateTags" | "autoRevalidateTags"> & EnlaceCallbacks & {
     /**
@@ -52,30 +52,35 @@ type NextOptions = Pick<EnlaceHookOptions, "autoGenerateTags" | "autoRevalidateT
      * @example
      * ```ts
      * createEnlaceNext("http://localhost:3000/api/", {}, {
-     *   revalidator: (tags, paths) => revalidateServerAction(tags, paths)
+     *   serverRevalidator: (tags, paths) => revalidateServerAction(tags, paths)
      * });
      * ```
      */
-    revalidator?: RevalidateHandler;
+    serverRevalidator?: ServerRevalidateHandler;
+    /**
+     * Skip server-side revalidation by default for all mutations.
+     * Individual requests can override with serverRevalidate: true.
+     * Useful for CSR-heavy apps where server cache invalidation is rarely needed.
+     * @default false
+     */
+    skipServerRevalidation?: boolean;
 };
 /** Per-request options for Next.js fetch - extends React's base options */
 type NextRequestOptionsBase = ReactRequestOptionsBase & {
     /** Time in seconds to revalidate, or false to disable */
     revalidate?: number | false;
     /**
-     * URL paths to revalidate after mutation
-     * This doesn't do anything on the client by itself - it's passed to the revalidator handler.
-     * You must implement the revalidation logic in the revalidator.
+     * URL paths to revalidate after mutation.
+     * Passed to the serverRevalidator handler.
      */
     revalidatePaths?: string[];
     /**
-     * Skip server-side revalidation for this request.
-     * Useful when autoRevalidateTags is enabled but you want to opt-out for specific mutations.
-     * You can still pass empty [] to revalidateTags to skip triggering revalidation.
-     * But this flag can be used if you want to revalidate client-side and skip server-side entirely.
-     * Eg. you don't fetch any data on server component and you might want to skip the overhead of revalidation.
+     * Control server-side revalidation for this specific request.
+     * - true: Force server revalidation
+     * - false: Skip server revalidation
+     * When undefined, follows the global skipServerRevalidation setting.
      */
-    skipRevalidator?: boolean;
+    serverRevalidate?: boolean;
 };
 
 declare function createEnlaceNext<TSchema = unknown, TDefaultError = unknown>(baseUrl: string, defaultOptions?: EnlaceOptions | null, nextOptions?: NextOptions): unknown extends TSchema ? WildcardClient<NextRequestOptionsBase> : EnlaceClient<TSchema, TDefaultError, NextRequestOptionsBase>;

package/dist/index.d.ts

@@ -16,9 +16,9 @@ type ReactRequestOptionsBase = {
      * Used to replace :paramName placeholders in the URL path.
      * @example
      * // With path api.products[':id'].delete
-     * trigger({ pathParams: { id: '123' } }) // → DELETE /products/123
+     * trigger({ params: { id: '123' } }) // → DELETE /products/123
      */
-    pathParams?: Record<string, string | number>;
+    params?: Record<string, string | number>;
 };
 /** Options for createEnlaceHookReact factory */
 type EnlaceHookOptions = {
@@ -43,7 +43,7 @@ type EnlaceHookOptions = {
  * @param tags - Cache tags to revalidate
  * @param paths - URL paths to revalidate
  */
-type RevalidateHandler = (tags: string[], paths: string[]) => void | Promise<void>;
+type ServerRevalidateHandler = (tags: string[], paths: string[]) => void | Promise<void>;
 /** Next.js-specific options (third argument for createEnlaceNext) */
 type NextOptions = Pick<EnlaceHookOptions, "autoGenerateTags" | "autoRevalidateTags"> & EnlaceCallbacks & {
     /**
@@ -52,30 +52,35 @@ type NextOptions = Pick<EnlaceHookOptions, "autoGenerateTags" | "autoRevalidateT
      * @example
      * ```ts
      * createEnlaceNext("http://localhost:3000/api/", {}, {
-     *   revalidator: (tags, paths) => revalidateServerAction(tags, paths)
+     *   serverRevalidator: (tags, paths) => revalidateServerAction(tags, paths)
      * });
      * ```
      */
-    revalidator?: RevalidateHandler;
+    serverRevalidator?: ServerRevalidateHandler;
+    /**
+     * Skip server-side revalidation by default for all mutations.
+     * Individual requests can override with serverRevalidate: true.
+     * Useful for CSR-heavy apps where server cache invalidation is rarely needed.
+     * @default false
+     */
+    skipServerRevalidation?: boolean;
 };
 /** Per-request options for Next.js fetch - extends React's base options */
 type NextRequestOptionsBase = ReactRequestOptionsBase & {
     /** Time in seconds to revalidate, or false to disable */
     revalidate?: number | false;
     /**
-     * URL paths to revalidate after mutation
-     * This doesn't do anything on the client by itself - it's passed to the revalidator handler.
-     * You must implement the revalidation logic in the revalidator.
+     * URL paths to revalidate after mutation.
+     * Passed to the serverRevalidator handler.
      */
     revalidatePaths?: string[];
     /**
-     * Skip server-side revalidation for this request.
-     * Useful when autoRevalidateTags is enabled but you want to opt-out for specific mutations.
-     * You can still pass empty [] to revalidateTags to skip triggering revalidation.
-     * But this flag can be used if you want to revalidate client-side and skip server-side entirely.
-     * Eg. you don't fetch any data on server component and you might want to skip the overhead of revalidation.
+     * Control server-side revalidation for this specific request.
+     * - true: Force server revalidation
+     * - false: Skip server revalidation
+     * When undefined, follows the global skipServerRevalidation setting.
      */
-    skipRevalidator?: boolean;
+    serverRevalidate?: boolean;
 };
 
 declare function createEnlaceNext<TSchema = unknown, TDefaultError = unknown>(baseUrl: string, defaultOptions?: EnlaceOptions | null, nextOptions?: NextOptions): unknown extends TSchema ? WildcardClient<NextRequestOptionsBase> : EnlaceClient<TSchema, TDefaultError, NextRequestOptionsBase>;

package/dist/index.js

@@ -42,18 +42,22 @@ async function executeNextFetch(baseUrl, path, method, combinedOptions, requestO
   const {
     autoGenerateTags = true,
     autoRevalidateTags = true,
-    revalidator,
+    skipServerRevalidation = false,
+    serverRevalidator,
     onSuccess,
     ...coreOptions
   } = combinedOptions;
   const isGet = method === "GET";
   const autoTags = generateTags(path);
   const nextOnSuccess = (payload) => {
-    if (!isGet && !requestOptions?.skipRevalidator) {
-      const revalidateTags = requestOptions?.revalidateTags ?? (autoRevalidateTags ? autoTags : []);
-      const revalidatePaths = requestOptions?.revalidatePaths ?? [];
-      if (revalidateTags.length || revalidatePaths.length) {
-        revalidator?.(revalidateTags, revalidatePaths);
+    if (!isGet) {
+      const shouldRevalidateServer = requestOptions?.serverRevalidate ?? !skipServerRevalidation;
+      if (shouldRevalidateServer) {
+        const revalidateTags = requestOptions?.revalidateTags ?? (autoRevalidateTags ? autoTags : []);
+        const revalidatePaths = requestOptions?.revalidatePaths ?? [];
+        if (revalidateTags.length || revalidatePaths.length) {
+          serverRevalidator?.(revalidateTags, revalidatePaths);
+        }
       }
     }
     onSuccess?.(payload);

package/dist/index.mjs

@@ -21,18 +21,22 @@ async function executeNextFetch(baseUrl, path, method, combinedOptions, requestO
   const {
     autoGenerateTags = true,
     autoRevalidateTags = true,
-    revalidator,
+    skipServerRevalidation = false,
+    serverRevalidator,
     onSuccess,
     ...coreOptions
   } = combinedOptions;
   const isGet = method === "GET";
   const autoTags = generateTags(path);
   const nextOnSuccess = (payload) => {
-    if (!isGet && !requestOptions?.skipRevalidator) {
-      const revalidateTags = requestOptions?.revalidateTags ?? (autoRevalidateTags ? autoTags : []);
-      const revalidatePaths = requestOptions?.revalidatePaths ?? [];
-      if (revalidateTags.length || revalidatePaths.length) {
-        revalidator?.(revalidateTags, revalidatePaths);
+    if (!isGet) {
+      const shouldRevalidateServer = requestOptions?.serverRevalidate ?? !skipServerRevalidation;
+      if (shouldRevalidateServer) {
+        const revalidateTags = requestOptions?.revalidateTags ?? (autoRevalidateTags ? autoTags : []);
+        const revalidatePaths = requestOptions?.revalidatePaths ?? [];
+        if (revalidateTags.length || revalidatePaths.length) {
+          serverRevalidator?.(revalidateTags, revalidatePaths);
+        }
       }
     }
     onSuccess?.(payload);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "enlace",
-  "version": "0.0.1-beta.10",
+  "version": "0.0.1-beta.12",
   "license": "MIT",
   "files": [
     "dist"