enlace 0.0.1-beta.1 → 0.0.1-beta.11

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { WildcardClient, EnlaceClient, EnlaceResponse, EnlaceOptions } from 'enlace-core';
+import { EnlaceCallbackPayload, EnlaceErrorCallbackPayload, EnlaceCallbacks, EnlaceOptions, WildcardClient, EnlaceClient } from 'enlace-core';
 export * from 'enlace-core';
 
 /** Per-request options for React hooks */
@@ -11,51 +11,16 @@ 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 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>>;
-type SelectorFn<TSchema, TMethod, TOptions = ReactRequestOptionsBase> = (api: ApiClient<TSchema, TOptions>) => TMethod;
-type HookState = {
-    loading: boolean;
-    fetching: boolean;
-    ok: boolean | undefined;
-    data: unknown;
-    error: unknown;
-};
-type TrackedCall = {
-    path: string[];
-    method: string;
-    options: unknown;
-};
-declare const HTTP_METHODS: readonly ["get", "post", "put", "patch", "delete"];
-type ExtractData<T> = T extends (...args: any[]) => Promise<EnlaceResponse<infer D, unknown>> ? D : never;
-type ExtractError<T> = T extends (...args: any[]) => Promise<EnlaceResponse<unknown, infer E>> ? E : never;
-/** Discriminated union for hook response state - enables type narrowing on ok check */
-type HookResponseState<TData, TError> = {
-    ok: undefined;
-    data: undefined;
-    error: undefined;
-} | {
-    ok: true;
-    data: TData;
-    error: undefined;
-} | {
-    ok: false;
-    data: undefined;
-    error: TError;
-};
-/** Result when hook is called with query function (auto-fetch mode) */
-type UseEnlaceQueryResult<TData, TError> = {
-    loading: boolean;
-    fetching: boolean;
-} & HookResponseState<TData, TError>;
-/** Result when hook is called with method selector (trigger mode) */
-type UseEnlaceSelectorResult<TMethod> = {
-    trigger: TMethod;
-    loading: boolean;
-    fetching: boolean;
-} & HookResponseState<ExtractData<TMethod>, ExtractError<TMethod>>;
-
+/** Options for createEnlaceHookReact factory */
 type EnlaceHookOptions = {
     /**
      * Auto-generate cache tags from URL path for GET requests.
@@ -67,31 +32,57 @@ 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;
 };
-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>;
-};
+
 /**
- * Creates a React hook for making API calls.
- * Called at module level to create a reusable hook.
- *
- * @example
- * const useAPI = createEnlaceHook<ApiSchema>('https://api.com');
- *
- * // Query mode - auto-fetch (auto-tracks changes, no deps array needed)
- * const { loading, data, error } = useAPI((api) => api.posts.get({ query: { userId } }));
- *
- * // Selector mode - typed trigger for lazy calls
- * const { trigger, loading, data, error } = useAPI((api) => api.posts.delete);
- * onClick={() => trigger({ body: { id: 1 } })}
+ * Handler function called after successful mutations to trigger server-side revalidation.
+ * @param tags - Cache tags to revalidate
+ * @param paths - URL paths to revalidate
  */
-declare function createEnlaceHook<TSchema = unknown>(baseUrl: string, defaultOptions?: EnlaceOptions, hookOptions?: EnlaceHookOptions): EnlaceHook<TSchema>;
-
-type Listener = (tags: string[]) => void;
-declare function invalidateTags(tags: string[]): void;
-declare function onRevalidate(callback: Listener): () => 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 & {
+    /**
+     * Handler called after successful mutations to trigger server-side revalidation.
+     * Receives auto-generated or manually specified tags and paths.
+     * @example
+     * ```ts
+     * createEnlaceNext("http://localhost:3000/api/", {}, {
+     *   serverRevalidator: (tags, paths) => revalidateServerAction(tags, paths)
+     * });
+     * ```
+     */
+    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.
+     * Passed to the serverRevalidator handler.
+     */
+    revalidatePaths?: string[];
+    /**
+     * Control server-side revalidation for this specific request.
+     * - true: Force server revalidation
+     * - false: Skip server revalidation
+     * When undefined, follows the global skipServerRevalidation setting.
+     */
+    serverRevalidate?: boolean;
+};
 
-declare function clearCache(key?: string): void;
+declare function createEnlaceNext<TSchema = unknown, TDefaultError = unknown>(baseUrl: string, defaultOptions?: EnlaceOptions | null, nextOptions?: NextOptions): unknown extends TSchema ? WildcardClient<NextRequestOptionsBase> : EnlaceClient<TSchema, TDefaultError, NextRequestOptionsBase>;
 
-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 NextOptions, type NextRequestOptionsBase, createEnlaceNext };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { WildcardClient, EnlaceClient, EnlaceResponse, EnlaceOptions } from 'enlace-core';
+import { EnlaceCallbackPayload, EnlaceErrorCallbackPayload, EnlaceCallbacks, EnlaceOptions, WildcardClient, EnlaceClient } from 'enlace-core';
 export * from 'enlace-core';
 
 /** Per-request options for React hooks */
@@ -11,51 +11,16 @@ 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 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>>;
-type SelectorFn<TSchema, TMethod, TOptions = ReactRequestOptionsBase> = (api: ApiClient<TSchema, TOptions>) => TMethod;
-type HookState = {
-    loading: boolean;
-    fetching: boolean;
-    ok: boolean | undefined;
-    data: unknown;
-    error: unknown;
-};
-type TrackedCall = {
-    path: string[];
-    method: string;
-    options: unknown;
-};
-declare const HTTP_METHODS: readonly ["get", "post", "put", "patch", "delete"];
-type ExtractData<T> = T extends (...args: any[]) => Promise<EnlaceResponse<infer D, unknown>> ? D : never;
-type ExtractError<T> = T extends (...args: any[]) => Promise<EnlaceResponse<unknown, infer E>> ? E : never;
-/** Discriminated union for hook response state - enables type narrowing on ok check */
-type HookResponseState<TData, TError> = {
-    ok: undefined;
-    data: undefined;
-    error: undefined;
-} | {
-    ok: true;
-    data: TData;
-    error: undefined;
-} | {
-    ok: false;
-    data: undefined;
-    error: TError;
-};
-/** Result when hook is called with query function (auto-fetch mode) */
-type UseEnlaceQueryResult<TData, TError> = {
-    loading: boolean;
-    fetching: boolean;
-} & HookResponseState<TData, TError>;
-/** Result when hook is called with method selector (trigger mode) */
-type UseEnlaceSelectorResult<TMethod> = {
-    trigger: TMethod;
-    loading: boolean;
-    fetching: boolean;
-} & HookResponseState<ExtractData<TMethod>, ExtractError<TMethod>>;
-
+/** Options for createEnlaceHookReact factory */
 type EnlaceHookOptions = {
     /**
      * Auto-generate cache tags from URL path for GET requests.
@@ -67,31 +32,57 @@ 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;
 };
-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>;
-};
+
 /**
- * Creates a React hook for making API calls.
- * Called at module level to create a reusable hook.
- *
- * @example
- * const useAPI = createEnlaceHook<ApiSchema>('https://api.com');
- *
- * // Query mode - auto-fetch (auto-tracks changes, no deps array needed)
- * const { loading, data, error } = useAPI((api) => api.posts.get({ query: { userId } }));
- *
- * // Selector mode - typed trigger for lazy calls
- * const { trigger, loading, data, error } = useAPI((api) => api.posts.delete);
- * onClick={() => trigger({ body: { id: 1 } })}
+ * Handler function called after successful mutations to trigger server-side revalidation.
+ * @param tags - Cache tags to revalidate
+ * @param paths - URL paths to revalidate
  */
-declare function createEnlaceHook<TSchema = unknown>(baseUrl: string, defaultOptions?: EnlaceOptions, hookOptions?: EnlaceHookOptions): EnlaceHook<TSchema>;
-
-type Listener = (tags: string[]) => void;
-declare function invalidateTags(tags: string[]): void;
-declare function onRevalidate(callback: Listener): () => 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 & {
+    /**
+     * Handler called after successful mutations to trigger server-side revalidation.
+     * Receives auto-generated or manually specified tags and paths.
+     * @example
+     * ```ts
+     * createEnlaceNext("http://localhost:3000/api/", {}, {
+     *   serverRevalidator: (tags, paths) => revalidateServerAction(tags, paths)
+     * });
+     * ```
+     */
+    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.
+     * Passed to the serverRevalidator handler.
+     */
+    revalidatePaths?: string[];
+    /**
+     * Control server-side revalidation for this specific request.
+     * - true: Force server revalidation
+     * - false: Skip server revalidation
+     * When undefined, follows the global skipServerRevalidation setting.
+     */
+    serverRevalidate?: boolean;
+};
 
-declare function clearCache(key?: string): void;
+declare function createEnlaceNext<TSchema = unknown, TDefaultError = unknown>(baseUrl: string, defaultOptions?: EnlaceOptions | null, nextOptions?: NextOptions): unknown extends TSchema ? WildcardClient<NextRequestOptionsBase> : EnlaceClient<TSchema, TDefaultError, NextRequestOptionsBase>;
 
-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 NextOptions, type NextRequestOptionsBase, createEnlaceNext };