enlace 0.0.1-beta.2 → 0.0.1-beta.4

package/README.md

@@ -15,11 +15,11 @@ import { createEnlaceHook, Endpoint } from "enlace";
 
 type ApiSchema = {
   posts: {
-    $get: Endpoint<Post[]>;
+    $get: Endpoint<Post[], ApiError>;
     $post: Endpoint<Post, ApiError, CreatePost>;
     _: {
-      $get: Endpoint<Post>;
-      $delete: Endpoint<void>;
+      $get: Endpoint<Post, ApiError>;
+      $delete: Endpoint<void, ApiError>;
     };
   };
 };
@@ -52,14 +52,14 @@ import { Endpoint } from "enlace";
 
 type ApiSchema = {
   users: {
-    $get: Endpoint<User[]>;           // GET /users
-    $post: Endpoint<User>;            // POST /users
-    _: {                              // /users/:id
-      $get: Endpoint<User>;           // GET /users/:id
-      $put: Endpoint<User>;           // PUT /users/:id
-      $delete: Endpoint<void>;        // DELETE /users/:id
+    $get: Endpoint<User[], ApiError>;           // GET /users
+    $post: Endpoint<User, ApiError>;            // POST /users
+    _: {                                        // /users/:id
+      $get: Endpoint<User, ApiError>;           // GET /users/:id
+      $put: Endpoint<User, ApiError>;           // PUT /users/:id
+      $delete: Endpoint<void, ApiError>;        // DELETE /users/:id
       profile: {
-        $get: Endpoint<Profile>;      // GET /users/:id/profile
+        $get: Endpoint<Profile, ApiError>;      // GET /users/:id/profile
       };
     };
   };
@@ -74,16 +74,16 @@ api.users[123].profile.get(); // GET /users/123/profile
 ### Endpoint Type
 
 ```typescript
-type Endpoint<TData, TError = unknown, TBody = never> = {
+type Endpoint<TData, TError, TBody = never> = {
   data: TData;    // Response data type
-  error: TError;  // Error response type
-  body: TBody;    // Request body type
+  error: TError;  // Error response type (required)
+  body: TBody;    // Request body type (optional)
 };
 
 // Examples
-type GetUsers = Endpoint<User[]>;                      // GET, no body
+type GetUsers = Endpoint<User[], ApiError>;                   // GET, no body
 type CreateUser = Endpoint<User, ApiError, CreateUserInput>;  // POST with body
-type DeleteUser = Endpoint<void, NotFoundError>;       // DELETE, no response data
+type DeleteUser = Endpoint<void, NotFoundError>;              // DELETE, no response data
 ```
 
 ## React Hooks
@@ -115,6 +115,35 @@ function Posts({ page, limit }: { page: number; limit: number }) {
 - Auto-fetches on mount
 - Re-fetches when dependencies change (no deps array needed!)
 - Returns cached data while revalidating
+- **Request deduplication** — identical requests from multiple components trigger only one fetch
+
+### Conditional Fetching
+
+Skip fetching with the `enabled` option:
+
+```typescript
+function ProductForm({ id }: { id: string | "new" }) {
+  // Skip fetching when creating a new product
+  const { data, loading } = useAPI(
+    (api) => api.products[id].get(),
+    { enabled: id !== "new" }
+  );
+
+  if (id === "new") return <CreateProductForm />;
+  if (loading) return <div>Loading...</div>;
+  return <EditProductForm product={data} />;
+}
+```
+
+```typescript
+// Also useful when waiting for a dependency
+function UserPosts({ userId }: { userId: string | undefined }) {
+  const { data } = useAPI(
+    (api) => api.users[userId!].posts.get(),
+    { enabled: userId !== undefined }
+  );
+}
+```
 
 ```typescript
 function Post({ id }: { id: number }) {
@@ -124,6 +153,34 @@ function Post({ id }: { id: number }) {
 }
 ```
 
+### Request Deduplication
+
+Multiple components requesting the same data will share a single network request:
+
+```typescript
+// Both components render at the same time
+function PostTitle({ id }: { id: number }) {
+  const { data } = useAPI((api) => api.posts[id].get());
+  return <h1>{data?.title}</h1>;
+}
+
+function PostBody({ id }: { id: number }) {
+  const { data } = useAPI((api) => api.posts[id].get());
+  return <p>{data?.body}</p>;
+}
+
+// Only ONE fetch request is made to GET /posts/123
+// Both components share the same cached result
+function PostPage() {
+  return (
+    <>
+      <PostTitle id={123} />
+      <PostBody id={123} />
+    </>
+  );
+}
+```
+
 ### Selector Mode (Manual Trigger)
 
 For mutations or lazy-loaded requests:
@@ -157,6 +214,56 @@ function CreatePost() {
 }
 ```
 
+### Dynamic Path Parameters
+
+Use `:paramName` syntax for dynamic IDs passed at trigger time:
+
+```typescript
+function PostList({ posts }: { posts: Post[] }) {
+  // Define once with :id placeholder
+  const { trigger, loading } = useAPI((api) => api.posts[":id"].delete);
+
+  const handleDelete = (postId: number) => {
+    // Pass the actual ID when triggering
+    trigger({ pathParams: { id: postId } });
+  };
+
+  return (
+    <ul>
+      {posts.map((post) => (
+        <li key={post.id}>
+          {post.title}
+          <button onClick={() => handleDelete(post.id)} disabled={loading}>
+            Delete
+          </button>
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
+**Multiple path parameters:**
+
+```typescript
+const { trigger } = useAPI((api) => api.users[":userId"].posts[":postId"].delete);
+
+trigger({ pathParams: { userId: "1", postId: "42" } });
+// → DELETE /users/1/posts/42
+```
+
+**With request body:**
+
+```typescript
+const { trigger } = useAPI((api) => api.products[":id"].patch);
+
+trigger({
+  pathParams: { id: "123" },
+  body: { name: "Updated Product" },
+});
+// → PATCH /products/123 with body
+```
+
 ## Caching & Auto-Revalidation
 
 ### Automatic Cache Tags (Zero Config)
@@ -259,6 +366,15 @@ const useAPI = createEnlaceHook<ApiSchema>(
 ### Query Mode
 
 ```typescript
+// Basic usage
+const result = useAPI((api) => api.posts.get());
+
+// With options
+const result = useAPI(
+  (api) => api.posts.get(),
+  { enabled: true }  // Skip fetching when false
+);
+
 type UseEnlaceQueryResult<TData, TError> = {
   loading: boolean;   // No cached data and fetching
   fetching: boolean;  // Request in progress
@@ -281,6 +397,18 @@ type UseEnlaceSelectorResult<TMethod> = {
 };
 ```
 
+### Request Options
+
+```typescript
+type RequestOptions = {
+  query?: Record<string, unknown>;        // Query parameters
+  body?: TBody;                           // Request body
+  tags?: string[];                        // Cache tags (GET only)
+  revalidateTags?: string[];              // Tags to invalidate after mutation
+  pathParams?: Record<string, string | number>;  // Dynamic path parameters
+};
+```
+
 ---
 
 ## Next.js Integration

package/dist/index.d.mts

@@ -11,6 +11,23 @@ type ReactRequestOptionsBase = {
     tags?: string[];
     /** Tags to invalidate after mutation (triggers refetch in matching queries) */
     revalidateTags?: string[];
+    /**
+     * Path parameters for dynamic URL segments.
+     * Used to replace :paramName placeholders in the URL path.
+     * @example
+     * // With path api.products[':id'].delete
+     * trigger({ pathParams: { id: '123' } }) // → DELETE /products/123
+     */
+    pathParams?: Record<string, string | number>;
+};
+/** Options for query mode hooks */
+type UseEnlaceQueryOptions = {
+    /**
+     * Whether the query should execute.
+     * Set to false to skip fetching (useful when ID is "new" or undefined).
+     * @default true
+     */
+    enabled?: boolean;
 };
 type ApiClient<TSchema, TOptions = ReactRequestOptionsBase> = unknown extends TSchema ? WildcardClient<TOptions> : EnlaceClient<TSchema, TOptions>;
 type QueryFn<TSchema, TData, TError, TOptions = ReactRequestOptionsBase> = (api: ApiClient<TSchema, TOptions>) => Promise<EnlaceResponse<TData, TError>>;
@@ -70,7 +87,7 @@ type EnlaceHookOptions = {
 };
 type EnlaceHook<TSchema> = {
     <TMethod extends (...args: any[]) => Promise<EnlaceResponse<unknown, unknown>>>(selector: SelectorFn<TSchema, TMethod>): UseEnlaceSelectorResult<TMethod>;
-    <TData, TError>(queryFn: QueryFn<TSchema, TData, TError>): UseEnlaceQueryResult<TData, TError>;
+    <TData, TError>(queryFn: QueryFn<TSchema, TData, TError>, options?: UseEnlaceQueryOptions): UseEnlaceQueryResult<TData, TError>;
 };
 /**
  * Creates a React hook for making API calls.
@@ -94,4 +111,4 @@ declare function onRevalidate(callback: Listener): () => void;
 
 declare function clearCache(key?: string): void;
 
-export { type ApiClient, type EnlaceHookOptions, HTTP_METHODS, type HookState, type QueryFn, type ReactRequestOptionsBase, type SelectorFn, type TrackedCall, type UseEnlaceQueryResult, type UseEnlaceSelectorResult, clearCache, createEnlaceHook, invalidateTags, onRevalidate };
+export { type ApiClient, type EnlaceHookOptions, HTTP_METHODS, type HookState, type QueryFn, type ReactRequestOptionsBase, type SelectorFn, type TrackedCall, type UseEnlaceQueryOptions, type UseEnlaceQueryResult, type UseEnlaceSelectorResult, clearCache, createEnlaceHook, invalidateTags, onRevalidate };

package/dist/index.d.ts

@@ -11,6 +11,23 @@ type ReactRequestOptionsBase = {
     tags?: string[];
     /** Tags to invalidate after mutation (triggers refetch in matching queries) */
     revalidateTags?: string[];
+    /**
+     * Path parameters for dynamic URL segments.
+     * Used to replace :paramName placeholders in the URL path.
+     * @example
+     * // With path api.products[':id'].delete
+     * trigger({ pathParams: { id: '123' } }) // → DELETE /products/123
+     */
+    pathParams?: Record<string, string | number>;
+};
+/** Options for query mode hooks */
+type UseEnlaceQueryOptions = {
+    /**
+     * Whether the query should execute.
+     * Set to false to skip fetching (useful when ID is "new" or undefined).
+     * @default true
+     */
+    enabled?: boolean;
 };
 type ApiClient<TSchema, TOptions = ReactRequestOptionsBase> = unknown extends TSchema ? WildcardClient<TOptions> : EnlaceClient<TSchema, TOptions>;
 type QueryFn<TSchema, TData, TError, TOptions = ReactRequestOptionsBase> = (api: ApiClient<TSchema, TOptions>) => Promise<EnlaceResponse<TData, TError>>;
@@ -70,7 +87,7 @@ type EnlaceHookOptions = {
 };
 type EnlaceHook<TSchema> = {
     <TMethod extends (...args: any[]) => Promise<EnlaceResponse<unknown, unknown>>>(selector: SelectorFn<TSchema, TMethod>): UseEnlaceSelectorResult<TMethod>;
-    <TData, TError>(queryFn: QueryFn<TSchema, TData, TError>): UseEnlaceQueryResult<TData, TError>;
+    <TData, TError>(queryFn: QueryFn<TSchema, TData, TError>, options?: UseEnlaceQueryOptions): UseEnlaceQueryResult<TData, TError>;
 };
 /**
  * Creates a React hook for making API calls.
@@ -94,4 +111,4 @@ declare function onRevalidate(callback: Listener): () => void;
 
 declare function clearCache(key?: string): void;
 
-export { type ApiClient, type EnlaceHookOptions, HTTP_METHODS, type HookState, type QueryFn, type ReactRequestOptionsBase, type SelectorFn, type TrackedCall, type UseEnlaceQueryResult, type UseEnlaceSelectorResult, clearCache, createEnlaceHook, invalidateTags, onRevalidate };
+export { type ApiClient, type EnlaceHookOptions, HTTP_METHODS, type HookState, type QueryFn, type ReactRequestOptionsBase, type SelectorFn, type TrackedCall, type UseEnlaceQueryOptions, type UseEnlaceQueryResult, type UseEnlaceSelectorResult, clearCache, createEnlaceHook, invalidateTags, onRevalidate };

package/dist/index.js

@@ -184,11 +184,26 @@ function onRevalidate(callback) {
 }
 
 // src/react/useQueryMode.ts
+function resolvePath(path, pathParams) {
+  if (!pathParams) return path;
+  return path.map((segment) => {
+    if (segment.startsWith(":")) {
+      const paramName = segment.slice(1);
+      const value = pathParams[paramName];
+      if (value === void 0) {
+        throw new Error(`Missing path parameter: ${paramName}`);
+      }
+      return String(value);
+    }
+    return segment;
+  });
+}
 function useQueryMode(api, trackedCall, options) {
-  const { autoGenerateTags, staleTime } = options;
+  const { autoGenerateTags, staleTime, enabled } = options;
   const queryKey = createQueryKey(trackedCall);
   const requestOptions = trackedCall.options;
-  const queryTags = requestOptions?.tags ?? (autoGenerateTags ? generateTags(trackedCall.path) : []);
+  const resolvedPath = resolvePath(trackedCall.path, requestOptions?.pathParams);
+  const queryTags = requestOptions?.tags ?? (autoGenerateTags ? generateTags(resolvedPath) : []);
   const getCacheState = (includeNeedsFetch = false) => {
     const cached = getCache(queryKey);
     const hasCachedData = cached?.data !== void 0;
@@ -207,6 +222,15 @@ function useQueryMode(api, trackedCall, options) {
   const fetchRef = (0, import_react.useRef)(null);
   (0, import_react.useEffect)(() => {
     mountedRef.current = true;
+    if (!enabled) {
+      dispatch({
+        type: "RESET",
+        state: { loading: false, fetching: false, ok: void 0, data: void 0, error: void 0 }
+      });
+      return () => {
+        mountedRef.current = false;
+      };
+    }
     dispatch({ type: "RESET", state: getCacheState(true) });
     const unsubscribe = subscribeCache(queryKey, () => {
       if (mountedRef.current) {
@@ -220,7 +244,7 @@ function useQueryMode(api, trackedCall, options) {
       }
       dispatch({ type: "FETCH_START" });
       let current = api;
-      for (const segment of trackedCall.path) {
+      for (const segment of resolvedPath) {
         current = current[segment];
       }
       const method = current[trackedCall.method];
@@ -252,7 +276,7 @@ function useQueryMode(api, trackedCall, options) {
       fetchRef.current = null;
       unsubscribe();
     };
-  }, [queryKey]);
+  }, [queryKey, enabled]);
   (0, import_react.useEffect)(() => {
     if (queryTags.length === 0) return;
     return onRevalidate((invalidatedTags) => {
@@ -299,23 +323,56 @@ function createTrackingProxy(onTrack) {
 
 // src/react/useSelectorMode.ts
 var import_react2 = require("react");
-function useSelectorMode(method, path, autoRevalidateTags) {
+function resolvePath2(path, pathParams) {
+  if (!pathParams) return path;
+  return path.map((segment) => {
+    if (segment.startsWith(":")) {
+      const paramName = segment.slice(1);
+      const value = pathParams[paramName];
+      if (value === void 0) {
+        throw new Error(`Missing path parameter: ${paramName}`);
+      }
+      return String(value);
+    }
+    return segment;
+  });
+}
+function hasPathParams(path) {
+  return path.some((segment) => segment.startsWith(":"));
+}
+function useSelectorMode(config) {
+  const { method, api, path, methodName, autoRevalidateTags } = config;
   const [state, dispatch] = (0, import_react2.useReducer)(hookReducer, initialState);
   const methodRef = (0, import_react2.useRef)(method);
+  const apiRef = (0, import_react2.useRef)(api);
   const triggerRef = (0, import_react2.useRef)(null);
   const pathRef = (0, import_react2.useRef)(path);
+  const methodNameRef = (0, import_react2.useRef)(methodName);
   const autoRevalidateRef = (0, import_react2.useRef)(autoRevalidateTags);
   methodRef.current = method;
+  apiRef.current = api;
   pathRef.current = path;
+  methodNameRef.current = methodName;
   autoRevalidateRef.current = autoRevalidateTags;
   if (!triggerRef.current) {
     triggerRef.current = (async (...args) => {
       dispatch({ type: "FETCH_START" });
-      const res = await methodRef.current(...args);
+      const options = args[0];
+      const resolvedPath = resolvePath2(pathRef.current, options?.pathParams);
+      let res;
+      if (hasPathParams(pathRef.current)) {
+        let current = apiRef.current;
+        for (const segment of resolvedPath) {
+          current = current[segment];
+        }
+        const resolvedMethod = current[methodNameRef.current];
+        res = await resolvedMethod(...args);
+      } else {
+        res = await methodRef.current(...args);
+      }
       if (res.ok) {
         dispatch({ type: "FETCH_SUCCESS", data: res.data });
-        const options = args[0];
-        const tagsToInvalidate = options?.revalidateTags ?? (autoRevalidateRef.current ? generateTags(pathRef.current) : []);
+        const tagsToInvalidate = options?.revalidateTags ?? (autoRevalidateRef.current ? generateTags(resolvedPath) : []);
         if (tagsToInvalidate.length > 0) {
           invalidateTags(tagsToInvalidate);
         }
@@ -339,7 +396,7 @@ function createEnlaceHook(baseUrl, defaultOptions = {}, hookOptions = {}) {
     autoRevalidateTags = true,
     staleTime = 0
   } = hookOptions;
-  function useEnlaceHook(selectorOrQuery) {
+  function useEnlaceHook(selectorOrQuery, queryOptions) {
     let trackingResult = {
       trackedCall: null,
       selectorPath: null,
@@ -353,16 +410,18 @@ function createEnlaceHook(baseUrl, defaultOptions = {}, hookOptions = {}) {
     );
     if (typeof result === "function") {
       const actualResult = selectorOrQuery(api);
-      return useSelectorMode(
-        actualResult,
-        trackingResult.selectorPath ?? [],
+      return useSelectorMode({
+        method: actualResult,
+        api,
+        path: trackingResult.selectorPath ?? [],
+        methodName: trackingResult.selectorMethod ?? "",
         autoRevalidateTags
-      );
+      });
     }
     return useQueryMode(
       api,
       trackingResult.trackedCall,
-      { autoGenerateTags, staleTime }
+      { autoGenerateTags, staleTime, enabled: queryOptions?.enabled ?? true }
     );
   }
   return useEnlaceHook;

package/dist/index.mjs

@@ -157,11 +157,26 @@ function onRevalidate(callback) {
 }
 
 // src/react/useQueryMode.ts
+function resolvePath(path, pathParams) {
+  if (!pathParams) return path;
+  return path.map((segment) => {
+    if (segment.startsWith(":")) {
+      const paramName = segment.slice(1);
+      const value = pathParams[paramName];
+      if (value === void 0) {
+        throw new Error(`Missing path parameter: ${paramName}`);
+      }
+      return String(value);
+    }
+    return segment;
+  });
+}
 function useQueryMode(api, trackedCall, options) {
-  const { autoGenerateTags, staleTime } = options;
+  const { autoGenerateTags, staleTime, enabled } = options;
   const queryKey = createQueryKey(trackedCall);
   const requestOptions = trackedCall.options;
-  const queryTags = requestOptions?.tags ?? (autoGenerateTags ? generateTags(trackedCall.path) : []);
+  const resolvedPath = resolvePath(trackedCall.path, requestOptions?.pathParams);
+  const queryTags = requestOptions?.tags ?? (autoGenerateTags ? generateTags(resolvedPath) : []);
   const getCacheState = (includeNeedsFetch = false) => {
     const cached = getCache(queryKey);
     const hasCachedData = cached?.data !== void 0;
@@ -180,6 +195,15 @@ function useQueryMode(api, trackedCall, options) {
   const fetchRef = useRef(null);
   useEffect(() => {
     mountedRef.current = true;
+    if (!enabled) {
+      dispatch({
+        type: "RESET",
+        state: { loading: false, fetching: false, ok: void 0, data: void 0, error: void 0 }
+      });
+      return () => {
+        mountedRef.current = false;
+      };
+    }
     dispatch({ type: "RESET", state: getCacheState(true) });
     const unsubscribe = subscribeCache(queryKey, () => {
       if (mountedRef.current) {
@@ -193,7 +217,7 @@ function useQueryMode(api, trackedCall, options) {
       }
       dispatch({ type: "FETCH_START" });
       let current = api;
-      for (const segment of trackedCall.path) {
+      for (const segment of resolvedPath) {
         current = current[segment];
       }
       const method = current[trackedCall.method];
@@ -225,7 +249,7 @@ function useQueryMode(api, trackedCall, options) {
       fetchRef.current = null;
       unsubscribe();
     };
-  }, [queryKey]);
+  }, [queryKey, enabled]);
   useEffect(() => {
     if (queryTags.length === 0) return;
     return onRevalidate((invalidatedTags) => {
@@ -272,23 +296,56 @@ function createTrackingProxy(onTrack) {
 
 // src/react/useSelectorMode.ts
 import { useRef as useRef2, useReducer as useReducer2 } from "react";
-function useSelectorMode(method, path, autoRevalidateTags) {
+function resolvePath2(path, pathParams) {
+  if (!pathParams) return path;
+  return path.map((segment) => {
+    if (segment.startsWith(":")) {
+      const paramName = segment.slice(1);
+      const value = pathParams[paramName];
+      if (value === void 0) {
+        throw new Error(`Missing path parameter: ${paramName}`);
+      }
+      return String(value);
+    }
+    return segment;
+  });
+}
+function hasPathParams(path) {
+  return path.some((segment) => segment.startsWith(":"));
+}
+function useSelectorMode(config) {
+  const { method, api, path, methodName, autoRevalidateTags } = config;
   const [state, dispatch] = useReducer2(hookReducer, initialState);
   const methodRef = useRef2(method);
+  const apiRef = useRef2(api);
   const triggerRef = useRef2(null);
   const pathRef = useRef2(path);
+  const methodNameRef = useRef2(methodName);
   const autoRevalidateRef = useRef2(autoRevalidateTags);
   methodRef.current = method;
+  apiRef.current = api;
   pathRef.current = path;
+  methodNameRef.current = methodName;
   autoRevalidateRef.current = autoRevalidateTags;
   if (!triggerRef.current) {
     triggerRef.current = (async (...args) => {
       dispatch({ type: "FETCH_START" });
-      const res = await methodRef.current(...args);
+      const options = args[0];
+      const resolvedPath = resolvePath2(pathRef.current, options?.pathParams);
+      let res;
+      if (hasPathParams(pathRef.current)) {
+        let current = apiRef.current;
+        for (const segment of resolvedPath) {
+          current = current[segment];
+        }
+        const resolvedMethod = current[methodNameRef.current];
+        res = await resolvedMethod(...args);
+      } else {
+        res = await methodRef.current(...args);
+      }
       if (res.ok) {
         dispatch({ type: "FETCH_SUCCESS", data: res.data });
-        const options = args[0];
-        const tagsToInvalidate = options?.revalidateTags ?? (autoRevalidateRef.current ? generateTags(pathRef.current) : []);
+        const tagsToInvalidate = options?.revalidateTags ?? (autoRevalidateRef.current ? generateTags(resolvedPath) : []);
         if (tagsToInvalidate.length > 0) {
           invalidateTags(tagsToInvalidate);
         }
@@ -312,7 +369,7 @@ function createEnlaceHook(baseUrl, defaultOptions = {}, hookOptions = {}) {
     autoRevalidateTags = true,
     staleTime = 0
   } = hookOptions;
-  function useEnlaceHook(selectorOrQuery) {
+  function useEnlaceHook(selectorOrQuery, queryOptions) {
     let trackingResult = {
       trackedCall: null,
       selectorPath: null,
@@ -326,16 +383,18 @@ function createEnlaceHook(baseUrl, defaultOptions = {}, hookOptions = {}) {
     );
     if (typeof result === "function") {
       const actualResult = selectorOrQuery(api);
-      return useSelectorMode(
-        actualResult,
-        trackingResult.selectorPath ?? [],
+      return useSelectorMode({
+        method: actualResult,
+        api,
+        path: trackingResult.selectorPath ?? [],
+        methodName: trackingResult.selectorMethod ?? "",
         autoRevalidateTags
-      );
+      });
     }
     return useQueryMode(
       api,
       trackingResult.trackedCall,
-      { autoGenerateTags, staleTime }
+      { autoGenerateTags, staleTime, enabled: queryOptions?.enabled ?? true }
     );
   }
   return useEnlaceHook;

package/dist/next/hook/index.d.mts

@@ -10,6 +10,23 @@ type ReactRequestOptionsBase = {
     tags?: string[];
     /** Tags to invalidate after mutation (triggers refetch in matching queries) */
     revalidateTags?: string[];
+    /**
+     * Path parameters for dynamic URL segments.
+     * Used to replace :paramName placeholders in the URL path.
+     * @example
+     * // With path api.products[':id'].delete
+     * trigger({ pathParams: { id: '123' } }) // → DELETE /products/123
+     */
+    pathParams?: Record<string, string | number>;
+};
+/** Options for query mode hooks */
+type UseEnlaceQueryOptions = {
+    /**
+     * Whether the query should execute.
+     * Set to false to skip fetching (useful when ID is "new" or undefined).
+     * @default true
+     */
+    enabled?: boolean;
 };
 type ApiClient<TSchema, TOptions = ReactRequestOptionsBase> = unknown extends TSchema ? WildcardClient<TOptions> : EnlaceClient<TSchema, TOptions>;
 type QueryFn<TSchema, TData, TError, TOptions = ReactRequestOptionsBase> = (api: ApiClient<TSchema, TOptions>) => Promise<EnlaceResponse<TData, TError>>;
@@ -101,7 +118,7 @@ type NextQueryFn<TSchema, TData, TError> = QueryFn<TSchema, TData, TError, NextR
 type NextSelectorFn<TSchema, TMethod> = SelectorFn<TSchema, TMethod, NextRequestOptionsBase>;
 type NextEnlaceHook<TSchema> = {
     <TMethod extends (...args: any[]) => Promise<EnlaceResponse<unknown, unknown>>>(selector: NextSelectorFn<TSchema, TMethod>): UseEnlaceSelectorResult<TMethod>;
-    <TData, TError>(queryFn: NextQueryFn<TSchema, TData, TError>): UseEnlaceQueryResult<TData, TError>;
+    <TData, TError>(queryFn: NextQueryFn<TSchema, TData, TError>, options?: UseEnlaceQueryOptions): UseEnlaceQueryResult<TData, TError>;
 };
 /**
  * Creates a React hook for making API calls in Next.js Client Components.

package/dist/next/hook/index.d.ts

@@ -10,6 +10,23 @@ type ReactRequestOptionsBase = {
     tags?: string[];
     /** Tags to invalidate after mutation (triggers refetch in matching queries) */
     revalidateTags?: string[];
+    /**
+     * Path parameters for dynamic URL segments.
+     * Used to replace :paramName placeholders in the URL path.
+     * @example
+     * // With path api.products[':id'].delete
+     * trigger({ pathParams: { id: '123' } }) // → DELETE /products/123
+     */
+    pathParams?: Record<string, string | number>;
+};
+/** Options for query mode hooks */
+type UseEnlaceQueryOptions = {
+    /**
+     * Whether the query should execute.
+     * Set to false to skip fetching (useful when ID is "new" or undefined).
+     * @default true
+     */
+    enabled?: boolean;
 };
 type ApiClient<TSchema, TOptions = ReactRequestOptionsBase> = unknown extends TSchema ? WildcardClient<TOptions> : EnlaceClient<TSchema, TOptions>;
 type QueryFn<TSchema, TData, TError, TOptions = ReactRequestOptionsBase> = (api: ApiClient<TSchema, TOptions>) => Promise<EnlaceResponse<TData, TError>>;
@@ -101,7 +118,7 @@ type NextQueryFn<TSchema, TData, TError> = QueryFn<TSchema, TData, TError, NextR
 type NextSelectorFn<TSchema, TMethod> = SelectorFn<TSchema, TMethod, NextRequestOptionsBase>;
 type NextEnlaceHook<TSchema> = {
     <TMethod extends (...args: any[]) => Promise<EnlaceResponse<unknown, unknown>>>(selector: NextSelectorFn<TSchema, TMethod>): UseEnlaceSelectorResult<TMethod>;
-    <TData, TError>(queryFn: NextQueryFn<TSchema, TData, TError>): UseEnlaceQueryResult<TData, TError>;
+    <TData, TError>(queryFn: NextQueryFn<TSchema, TData, TError>, options?: UseEnlaceQueryOptions): UseEnlaceQueryResult<TData, TError>;
 };
 /**
  * Creates a React hook for making API calls in Next.js Client Components.

package/dist/next/hook/index.js

@@ -257,11 +257,26 @@ function onRevalidate(callback) {
 }
 
 // src/react/useQueryMode.ts
+function resolvePath(path, pathParams) {
+  if (!pathParams) return path;
+  return path.map((segment) => {
+    if (segment.startsWith(":")) {
+      const paramName = segment.slice(1);
+      const value = pathParams[paramName];
+      if (value === void 0) {
+        throw new Error(`Missing path parameter: ${paramName}`);
+      }
+      return String(value);
+    }
+    return segment;
+  });
+}
 function useQueryMode(api, trackedCall, options) {
-  const { autoGenerateTags, staleTime } = options;
+  const { autoGenerateTags, staleTime, enabled } = options;
   const queryKey = createQueryKey(trackedCall);
   const requestOptions = trackedCall.options;
-  const queryTags = requestOptions?.tags ?? (autoGenerateTags ? generateTags(trackedCall.path) : []);
+  const resolvedPath = resolvePath(trackedCall.path, requestOptions?.pathParams);
+  const queryTags = requestOptions?.tags ?? (autoGenerateTags ? generateTags(resolvedPath) : []);
   const getCacheState = (includeNeedsFetch = false) => {
     const cached = getCache(queryKey);
     const hasCachedData = cached?.data !== void 0;
@@ -280,6 +295,15 @@ function useQueryMode(api, trackedCall, options) {
   const fetchRef = (0, import_react.useRef)(null);
   (0, import_react.useEffect)(() => {
     mountedRef.current = true;
+    if (!enabled) {
+      dispatch({
+        type: "RESET",
+        state: { loading: false, fetching: false, ok: void 0, data: void 0, error: void 0 }
+      });
+      return () => {
+        mountedRef.current = false;
+      };
+    }
     dispatch({ type: "RESET", state: getCacheState(true) });
     const unsubscribe = subscribeCache(queryKey, () => {
       if (mountedRef.current) {
@@ -293,7 +317,7 @@ function useQueryMode(api, trackedCall, options) {
       }
       dispatch({ type: "FETCH_START" });
       let current = api;
-      for (const segment of trackedCall.path) {
+      for (const segment of resolvedPath) {
         current = current[segment];
       }
       const method = current[trackedCall.method];
@@ -325,7 +349,7 @@ function useQueryMode(api, trackedCall, options) {
       fetchRef.current = null;
       unsubscribe();
     };
-  }, [queryKey]);
+  }, [queryKey, enabled]);
   (0, import_react.useEffect)(() => {
     if (queryTags.length === 0) return;
     return onRevalidate((invalidatedTags) => {
@@ -340,23 +364,56 @@ function useQueryMode(api, trackedCall, options) {
 
 // src/react/useSelectorMode.ts
 var import_react2 = require("react");
-function useSelectorMode(method, path, autoRevalidateTags) {
+function resolvePath2(path, pathParams) {
+  if (!pathParams) return path;
+  return path.map((segment) => {
+    if (segment.startsWith(":")) {
+      const paramName = segment.slice(1);
+      const value = pathParams[paramName];
+      if (value === void 0) {
+        throw new Error(`Missing path parameter: ${paramName}`);
+      }
+      return String(value);
+    }
+    return segment;
+  });
+}
+function hasPathParams(path) {
+  return path.some((segment) => segment.startsWith(":"));
+}
+function useSelectorMode(config) {
+  const { method, api, path, methodName, autoRevalidateTags } = config;
   const [state, dispatch] = (0, import_react2.useReducer)(hookReducer, initialState);
   const methodRef = (0, import_react2.useRef)(method);
+  const apiRef = (0, import_react2.useRef)(api);
   const triggerRef = (0, import_react2.useRef)(null);
   const pathRef = (0, import_react2.useRef)(path);
+  const methodNameRef = (0, import_react2.useRef)(methodName);
   const autoRevalidateRef = (0, import_react2.useRef)(autoRevalidateTags);
   methodRef.current = method;
+  apiRef.current = api;
   pathRef.current = path;
+  methodNameRef.current = methodName;
   autoRevalidateRef.current = autoRevalidateTags;
   if (!triggerRef.current) {
     triggerRef.current = (async (...args) => {
       dispatch({ type: "FETCH_START" });
-      const res = await methodRef.current(...args);
+      const options = args[0];
+      const resolvedPath = resolvePath2(pathRef.current, options?.pathParams);
+      let res;
+      if (hasPathParams(pathRef.current)) {
+        let current = apiRef.current;
+        for (const segment of resolvedPath) {
+          current = current[segment];
+        }
+        const resolvedMethod = current[methodNameRef.current];
+        res = await resolvedMethod(...args);
+      } else {
+        res = await methodRef.current(...args);
+      }
       if (res.ok) {
         dispatch({ type: "FETCH_SUCCESS", data: res.data });
-        const options = args[0];
-        const tagsToInvalidate = options?.revalidateTags ?? (autoRevalidateRef.current ? generateTags(pathRef.current) : []);
+        const tagsToInvalidate = options?.revalidateTags ?? (autoRevalidateRef.current ? generateTags(resolvedPath) : []);
         if (tagsToInvalidate.length > 0) {
           invalidateTags(tagsToInvalidate);
         }
@@ -417,26 +474,30 @@ function createEnlaceHook(baseUrl, defaultOptions = {}, hookOptions = {}) {
     autoRevalidateTags,
     ...nextOptions
   });
-  function useEnlaceHook(selectorOrQuery) {
+  function useEnlaceHook(selectorOrQuery, queryOptions) {
     let trackedCall = null;
     let selectorPath = null;
+    let selectorMethod = null;
     const trackingProxy = createTrackingProxy((result2) => {
       trackedCall = result2.trackedCall;
       selectorPath = result2.selectorPath;
+      selectorMethod = result2.selectorMethod;
     });
     const result = selectorOrQuery(trackingProxy);
     if (typeof result === "function") {
       const actualResult = selectorOrQuery(api);
-      return useSelectorMode(
-        actualResult,
-        selectorPath ?? [],
+      return useSelectorMode({
+        method: actualResult,
+        api,
+        path: selectorPath ?? [],
+        methodName: selectorMethod ?? "",
         autoRevalidateTags
-      );
+      });
     }
     return useQueryMode(
       api,
       trackedCall,
-      { autoGenerateTags, staleTime }
+      { autoGenerateTags, staleTime, enabled: queryOptions?.enabled ?? true }
     );
   }
   return useEnlaceHook;

package/dist/next/hook/index.mjs

@@ -255,11 +255,26 @@ function onRevalidate(callback) {
 }
 
 // src/react/useQueryMode.ts
+function resolvePath(path, pathParams) {
+  if (!pathParams) return path;
+  return path.map((segment) => {
+    if (segment.startsWith(":")) {
+      const paramName = segment.slice(1);
+      const value = pathParams[paramName];
+      if (value === void 0) {
+        throw new Error(`Missing path parameter: ${paramName}`);
+      }
+      return String(value);
+    }
+    return segment;
+  });
+}
 function useQueryMode(api, trackedCall, options) {
-  const { autoGenerateTags, staleTime } = options;
+  const { autoGenerateTags, staleTime, enabled } = options;
   const queryKey = createQueryKey(trackedCall);
   const requestOptions = trackedCall.options;
-  const queryTags = requestOptions?.tags ?? (autoGenerateTags ? generateTags(trackedCall.path) : []);
+  const resolvedPath = resolvePath(trackedCall.path, requestOptions?.pathParams);
+  const queryTags = requestOptions?.tags ?? (autoGenerateTags ? generateTags(resolvedPath) : []);
   const getCacheState = (includeNeedsFetch = false) => {
     const cached = getCache(queryKey);
     const hasCachedData = cached?.data !== void 0;
@@ -278,6 +293,15 @@ function useQueryMode(api, trackedCall, options) {
   const fetchRef = useRef(null);
   useEffect(() => {
     mountedRef.current = true;
+    if (!enabled) {
+      dispatch({
+        type: "RESET",
+        state: { loading: false, fetching: false, ok: void 0, data: void 0, error: void 0 }
+      });
+      return () => {
+        mountedRef.current = false;
+      };
+    }
     dispatch({ type: "RESET", state: getCacheState(true) });
     const unsubscribe = subscribeCache(queryKey, () => {
       if (mountedRef.current) {
@@ -291,7 +315,7 @@ function useQueryMode(api, trackedCall, options) {
       }
       dispatch({ type: "FETCH_START" });
       let current = api;
-      for (const segment of trackedCall.path) {
+      for (const segment of resolvedPath) {
         current = current[segment];
       }
       const method = current[trackedCall.method];
@@ -323,7 +347,7 @@ function useQueryMode(api, trackedCall, options) {
       fetchRef.current = null;
       unsubscribe();
     };
-  }, [queryKey]);
+  }, [queryKey, enabled]);
   useEffect(() => {
     if (queryTags.length === 0) return;
     return onRevalidate((invalidatedTags) => {
@@ -338,23 +362,56 @@ function useQueryMode(api, trackedCall, options) {
 
 // src/react/useSelectorMode.ts
 import { useRef as useRef2, useReducer as useReducer2 } from "react";
-function useSelectorMode(method, path, autoRevalidateTags) {
+function resolvePath2(path, pathParams) {
+  if (!pathParams) return path;
+  return path.map((segment) => {
+    if (segment.startsWith(":")) {
+      const paramName = segment.slice(1);
+      const value = pathParams[paramName];
+      if (value === void 0) {
+        throw new Error(`Missing path parameter: ${paramName}`);
+      }
+      return String(value);
+    }
+    return segment;
+  });
+}
+function hasPathParams(path) {
+  return path.some((segment) => segment.startsWith(":"));
+}
+function useSelectorMode(config) {
+  const { method, api, path, methodName, autoRevalidateTags } = config;
   const [state, dispatch] = useReducer2(hookReducer, initialState);
   const methodRef = useRef2(method);
+  const apiRef = useRef2(api);
   const triggerRef = useRef2(null);
   const pathRef = useRef2(path);
+  const methodNameRef = useRef2(methodName);
   const autoRevalidateRef = useRef2(autoRevalidateTags);
   methodRef.current = method;
+  apiRef.current = api;
   pathRef.current = path;
+  methodNameRef.current = methodName;
   autoRevalidateRef.current = autoRevalidateTags;
   if (!triggerRef.current) {
     triggerRef.current = (async (...args) => {
       dispatch({ type: "FETCH_START" });
-      const res = await methodRef.current(...args);
+      const options = args[0];
+      const resolvedPath = resolvePath2(pathRef.current, options?.pathParams);
+      let res;
+      if (hasPathParams(pathRef.current)) {
+        let current = apiRef.current;
+        for (const segment of resolvedPath) {
+          current = current[segment];
+        }
+        const resolvedMethod = current[methodNameRef.current];
+        res = await resolvedMethod(...args);
+      } else {
+        res = await methodRef.current(...args);
+      }
       if (res.ok) {
         dispatch({ type: "FETCH_SUCCESS", data: res.data });
-        const options = args[0];
-        const tagsToInvalidate = options?.revalidateTags ?? (autoRevalidateRef.current ? generateTags(pathRef.current) : []);
+        const tagsToInvalidate = options?.revalidateTags ?? (autoRevalidateRef.current ? generateTags(resolvedPath) : []);
         if (tagsToInvalidate.length > 0) {
           invalidateTags(tagsToInvalidate);
         }
@@ -415,26 +472,30 @@ function createEnlaceHook(baseUrl, defaultOptions = {}, hookOptions = {}) {
     autoRevalidateTags,
     ...nextOptions
   });
-  function useEnlaceHook(selectorOrQuery) {
+  function useEnlaceHook(selectorOrQuery, queryOptions) {
     let trackedCall = null;
     let selectorPath = null;
+    let selectorMethod = null;
     const trackingProxy = createTrackingProxy((result2) => {
       trackedCall = result2.trackedCall;
       selectorPath = result2.selectorPath;
+      selectorMethod = result2.selectorMethod;
     });
     const result = selectorOrQuery(trackingProxy);
     if (typeof result === "function") {
       const actualResult = selectorOrQuery(api);
-      return useSelectorMode(
-        actualResult,
-        selectorPath ?? [],
+      return useSelectorMode({
+        method: actualResult,
+        api,
+        path: selectorPath ?? [],
+        methodName: selectorMethod ?? "",
         autoRevalidateTags
-      );
+      });
     }
     return useQueryMode(
       api,
       trackedCall,
-      { autoGenerateTags, staleTime }
+      { autoGenerateTags, staleTime, enabled: queryOptions?.enabled ?? true }
     );
   }
   return useEnlaceHook;

package/dist/next/index.d.mts

@@ -12,6 +12,14 @@ type ReactRequestOptionsBase = {
     tags?: string[];
     /** Tags to invalidate after mutation (triggers refetch in matching queries) */
     revalidateTags?: string[];
+    /**
+     * Path parameters for dynamic URL segments.
+     * Used to replace :paramName placeholders in the URL path.
+     * @example
+     * // With path api.products[':id'].delete
+     * trigger({ pathParams: { id: '123' } }) // → DELETE /products/123
+     */
+    pathParams?: Record<string, string | number>;
 };
 
 type EnlaceHookOptions = {

package/dist/next/index.d.ts

@@ -12,6 +12,14 @@ type ReactRequestOptionsBase = {
     tags?: string[];
     /** Tags to invalidate after mutation (triggers refetch in matching queries) */
     revalidateTags?: string[];
+    /**
+     * Path parameters for dynamic URL segments.
+     * Used to replace :paramName placeholders in the URL path.
+     * @example
+     * // With path api.products[':id'].delete
+     * trigger({ pathParams: { id: '123' } }) // → DELETE /products/123
+     */
+    pathParams?: Record<string, string | number>;
 };
 
 type EnlaceHookOptions = {

package/package.json

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