enlace 0.0.1-beta.3 → 0.0.1-beta.5

package/README.md

@@ -117,6 +117,34 @@ function Posts({ page, limit }: { page: number; limit: number }) {
 - 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 }) {
   // Automatically re-fetches when `id` or query values change
@@ -186,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)
@@ -283,11 +361,106 @@ const useAPI = createEnlaceHook<ApiSchema>(
 );
 ```
 
+### Async Headers
+
+Headers can be provided as a static value, sync function, or async function. This is useful when you need to fetch headers dynamically (e.g., auth tokens from async storage):
+
+```typescript
+// Static headers
+const useAPI = createEnlaceHook<ApiSchema>("https://api.example.com", {
+  headers: { Authorization: "Bearer token" },
+});
+
+// Sync function
+const useAPI = createEnlaceHook<ApiSchema>("https://api.example.com", {
+  headers: () => ({ Authorization: `Bearer ${getToken()}` }),
+});
+
+// Async function
+const useAPI = createEnlaceHook<ApiSchema>("https://api.example.com", {
+  headers: async () => {
+    const token = await getTokenFromStorage();
+    return { Authorization: `Bearer ${token}` };
+  },
+});
+```
+
+This also works for per-request headers:
+
+```typescript
+const { data } = useAPI((api) =>
+  api.posts.get({
+    headers: async () => {
+      const token = await refreshToken();
+      return { Authorization: `Bearer ${token}` };
+    },
+  })
+);
+```
+
+### Global Callbacks
+
+You can set up global `onSuccess` and `onError` callbacks that are called for every request:
+
+```typescript
+const useAPI = createEnlaceHook<ApiSchema>(
+  "https://api.example.com",
+  {
+    headers: { Authorization: "Bearer token" },
+  },
+  {
+    onSuccess: (payload) => {
+      console.log("Request succeeded:", payload.status, payload.data);
+    },
+    onError: (payload) => {
+      if (payload.status === 0) {
+        // Network error
+        console.error("Network error:", payload.error.message);
+      } else {
+        // HTTP error (4xx, 5xx)
+        console.error("HTTP error:", payload.status, payload.error);
+      }
+    },
+  }
+);
+```
+
+**Callback Payloads:**
+
+```typescript
+// onSuccess payload
+type EnlaceCallbackPayload<T> = {
+  status: number;
+  data: T;
+  headers: Headers;
+};
+
+// onError payload (HTTP error or network error)
+type EnlaceErrorCallbackPayload<T> =
+  | { status: number; error: T; headers: Headers }  // HTTP error
+  | { status: 0; error: Error; headers: null };     // Network error
+```
+
+**Use cases:**
+- Global error logging/reporting
+- Toast notifications for all API errors
+- Authentication refresh on 401 errors
+- Analytics tracking
+
 ## Return Types
 
 ### 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
@@ -310,6 +483,19 @@ type UseEnlaceSelectorResult<TMethod> = {
 };
 ```
 
+### Request Options
+
+```typescript
+type RequestOptions = {
+  query?: Record<string, unknown>;        // Query parameters
+  body?: TBody;                           // Request body
+  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
+};
+```
+
 ---
 
 ## Next.js Integration
@@ -432,6 +618,8 @@ type EnlaceHookOptions = {
   autoGenerateTags?: boolean;    // default: true
   autoRevalidateTags?: boolean;  // default: true
   staleTime?: number;            // default: 0
+  onSuccess?: (payload: EnlaceCallbackPayload<unknown>) => void;
+  onError?: (payload: EnlaceErrorCallbackPayload<unknown>) => void;
 };
 ```
 

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { WildcardClient, EnlaceClient, EnlaceResponse, EnlaceOptions } from 'enlace-core';
+import { EnlaceCallbackPayload, EnlaceErrorCallbackPayload, EnlaceResponse, WildcardClient, EnlaceClient, EnlaceOptions } from 'enlace-core';
 export * from 'enlace-core';
 
 /** Per-request options for React hooks */
@@ -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>>;
@@ -55,7 +72,7 @@ type UseEnlaceSelectorResult<TMethod> = {
     loading: boolean;
     fetching: boolean;
 } & HookResponseState<ExtractData<TMethod>, ExtractError<TMethod>>;
-
+/** Options for createEnlaceHook factory */
 type EnlaceHookOptions = {
     /**
      * Auto-generate cache tags from URL path for GET requests.
@@ -67,11 +84,17 @@ type EnlaceHookOptions = {
     autoRevalidateTags?: boolean;
     /** Time in ms before cached data is considered stale. @default 0 (always stale) */
     staleTime?: number;
+    /** Callback called on successful API responses */
+    onSuccess?: (payload: EnlaceCallbackPayload<unknown>) => void;
+    /** Callback called on error responses (HTTP errors or network failures) */
+    onError?: (payload: EnlaceErrorCallbackPayload<unknown>) => void;
 };
+/** Hook type returned by createEnlaceHook */
 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.
  * Called at module level to create a reusable hook.
@@ -94,4 +117,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 EnlaceHook, 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

@@ -1,4 +1,4 @@
-import { WildcardClient, EnlaceClient, EnlaceResponse, EnlaceOptions } from 'enlace-core';
+import { EnlaceCallbackPayload, EnlaceErrorCallbackPayload, EnlaceResponse, WildcardClient, EnlaceClient, EnlaceOptions } from 'enlace-core';
 export * from 'enlace-core';
 
 /** Per-request options for React hooks */
@@ -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>>;
@@ -55,7 +72,7 @@ type UseEnlaceSelectorResult<TMethod> = {
     loading: boolean;
     fetching: boolean;
 } & HookResponseState<ExtractData<TMethod>, ExtractError<TMethod>>;
-
+/** Options for createEnlaceHook factory */
 type EnlaceHookOptions = {
     /**
      * Auto-generate cache tags from URL path for GET requests.
@@ -67,11 +84,17 @@ type EnlaceHookOptions = {
     autoRevalidateTags?: boolean;
     /** Time in ms before cached data is considered stale. @default 0 (always stale) */
     staleTime?: number;
+    /** Callback called on successful API responses */
+    onSuccess?: (payload: EnlaceCallbackPayload<unknown>) => void;
+    /** Callback called on error responses (HTTP errors or network failures) */
+    onError?: (payload: EnlaceErrorCallbackPayload<unknown>) => void;
 };
+/** Hook type returned by createEnlaceHook */
 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.
  * Called at module level to create a reusable hook.
@@ -94,4 +117,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 EnlaceHook, 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

@@ -47,7 +47,7 @@ var initialState = {
 function hookReducer(state, action) {
   switch (action.type) {
     case "RESET":
-      return action.state;
+      return action.state ?? initialState;
     case "FETCH_START":
       return {
         ...state,
@@ -184,11 +184,29 @@ 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;
@@ -202,17 +220,22 @@ function useQueryMode(api, trackedCall, options) {
       error: cached?.error
     };
   };
-  const [state, dispatch] = (0, import_react.useReducer)(hookReducer, null, () => getCacheState(true));
+  const [state, dispatch] = (0, import_react.useReducer)(
+    hookReducer,
+    null,
+    () => getCacheState(true)
+  );
   const mountedRef = (0, import_react.useRef)(true);
   const fetchRef = (0, import_react.useRef)(null);
   (0, import_react.useEffect)(() => {
     mountedRef.current = true;
+    if (!enabled) {
+      dispatch({ type: "RESET" });
+      return () => {
+        mountedRef.current = false;
+      };
+    }
     dispatch({ type: "RESET", state: getCacheState(true) });
-    const unsubscribe = subscribeCache(queryKey, () => {
-      if (mountedRef.current) {
-        dispatch({ type: "SYNC_CACHE", state: getCacheState() });
-      }
-    });
     const doFetch = () => {
       const cached2 = getCache(queryKey);
       if (cached2?.promise) {
@@ -220,7 +243,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];
@@ -228,7 +251,7 @@ function useQueryMode(api, trackedCall, options) {
         if (mountedRef.current) {
           setCache(queryKey, {
             data: res.ok ? res.data : void 0,
-            error: res.ok ? void 0 : res.error,
+            error: res.ok || res.status === 0 ? void 0 : res.error,
             ok: res.ok,
             timestamp: Date.now(),
             tags: queryTags
@@ -247,12 +270,17 @@ function useQueryMode(api, trackedCall, options) {
     } else {
       doFetch();
     }
+    const unsubscribe = subscribeCache(queryKey, () => {
+      if (mountedRef.current) {
+        dispatch({ type: "SYNC_CACHE", state: getCacheState() });
+      }
+    });
     return () => {
       mountedRef.current = false;
       fetchRef.current = null;
       unsubscribe();
     };
-  }, [queryKey]);
+  }, [queryKey, enabled]);
   (0, import_react.useEffect)(() => {
     if (queryTags.length === 0) return;
     return onRevalidate((invalidatedTags) => {
@@ -299,23 +327,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);
         }
@@ -333,13 +394,15 @@ function useSelectorMode(method, path, autoRevalidateTags) {
 
 // src/react/createEnlaceHook.ts
 function createEnlaceHook(baseUrl, defaultOptions = {}, hookOptions = {}) {
-  const api = (0, import_enlace_core.createEnlace)(baseUrl, defaultOptions);
   const {
     autoGenerateTags = true,
     autoRevalidateTags = true,
-    staleTime = 0
+    staleTime = 0,
+    onSuccess,
+    onError
   } = hookOptions;
-  function useEnlaceHook(selectorOrQuery) {
+  const api = (0, import_enlace_core.createEnlace)(baseUrl, defaultOptions, { onSuccess, onError });
+  function useEnlaceHook(selectorOrQuery, queryOptions) {
     let trackingResult = {
       trackedCall: null,
       selectorPath: null,
@@ -353,16 +416,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;