enlace 0.0.1-beta.2 → 0.0.1-beta.20

package/dist/index.d.mts

@@ -1,61 +1,38 @@
-import { WildcardClient, EnlaceClient, EnlaceResponse, EnlaceOptions } from 'enlace-core';
+import { EnlaceCallbackPayload, EnlaceErrorCallbackPayload, CoreRequestOptionsBase, EnlaceCallbacks, EnlaceOptions, WildcardClient, EnlaceClient } from 'enlace-core';
 export * from 'enlace-core';
 
-/** Per-request options for React hooks */
-type ReactRequestOptionsBase = {
+/**
+ * Per-request options for React hooks.
+ * Extends CoreRequestOptionsBase which provides conditional params support.
+ * The params option is only available when accessing dynamic URL segments (via _ or index access).
+ */
+type ReactRequestOptionsBase = CoreRequestOptionsBase & {
     /**
      * Cache tags for caching (GET requests only)
      * This will auto generate tags from the URL path if not provided and autoGenerateTags is enabled.
      * But can be manually specified to override auto-generation.
      * */
     tags?: string[];
+    /**
+     * Additional cache tags to merge with auto-generated tags.
+     * Use this when you want to extend (not replace) the auto-generated tags.
+     * @example
+     * api.posts.$get({ additionalTags: ['custom-tag'] })
+     * // If autoGenerateTags produces ['posts'], final tags: ['posts', 'custom-tag']
+     */
+    additionalTags?: string[];
     /** Tags to invalidate after mutation (triggers refetch in matching queries) */
     revalidateTags?: string[];
+    /**
+     * Additional revalidation tags to merge with auto-generated tags.
+     * Use this when you want to extend (not replace) the auto-generated revalidation tags.
+     * @example
+     * api.posts.$post({ body: {...}, additionalRevalidateTags: ['other-tag'] })
+     * // If autoRevalidateTags produces ['posts'], final tags: ['posts', 'other-tag']
+     */
+    additionalRevalidateTags?: string[];
 };
-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 enlaceHookReact factory */
 type EnlaceHookOptions = {
     /**
      * Auto-generate cache tags from URL path for GET requests.
@@ -67,31 +44,59 @@ 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 ServerRevalidateHandler = (tags: string[], paths: string[]) => void | Promise<void>;
+/** Next.js-specific options (third argument for enlaceNext) */
+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
+     * enlaceNext("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;
+};
 
-type Listener = (tags: string[]) => void;
-declare function invalidateTags(tags: string[]): void;
-declare function onRevalidate(callback: Listener): () => void;
+declare function enlaceNext<TSchema = unknown, TDefaultError = unknown>(baseUrl: string, defaultOptions?: EnlaceOptions | null, nextOptions?: NextOptions): unknown extends TSchema ? WildcardClient<NextRequestOptionsBase> : EnlaceClient<TSchema, TDefaultError, NextRequestOptionsBase>;
 
-declare function clearCache(key?: string): void;
+declare function invalidateTags(tags: 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 NextOptions, type NextRequestOptionsBase, enlaceNext, invalidateTags };

package/dist/index.d.ts

@@ -1,61 +1,38 @@
-import { WildcardClient, EnlaceClient, EnlaceResponse, EnlaceOptions } from 'enlace-core';
+import { EnlaceCallbackPayload, EnlaceErrorCallbackPayload, CoreRequestOptionsBase, EnlaceCallbacks, EnlaceOptions, WildcardClient, EnlaceClient } from 'enlace-core';
 export * from 'enlace-core';
 
-/** Per-request options for React hooks */
-type ReactRequestOptionsBase = {
+/**
+ * Per-request options for React hooks.
+ * Extends CoreRequestOptionsBase which provides conditional params support.
+ * The params option is only available when accessing dynamic URL segments (via _ or index access).
+ */
+type ReactRequestOptionsBase = CoreRequestOptionsBase & {
     /**
      * Cache tags for caching (GET requests only)
      * This will auto generate tags from the URL path if not provided and autoGenerateTags is enabled.
      * But can be manually specified to override auto-generation.
      * */
     tags?: string[];
+    /**
+     * Additional cache tags to merge with auto-generated tags.
+     * Use this when you want to extend (not replace) the auto-generated tags.
+     * @example
+     * api.posts.$get({ additionalTags: ['custom-tag'] })
+     * // If autoGenerateTags produces ['posts'], final tags: ['posts', 'custom-tag']
+     */
+    additionalTags?: string[];
     /** Tags to invalidate after mutation (triggers refetch in matching queries) */
     revalidateTags?: string[];
+    /**
+     * Additional revalidation tags to merge with auto-generated tags.
+     * Use this when you want to extend (not replace) the auto-generated revalidation tags.
+     * @example
+     * api.posts.$post({ body: {...}, additionalRevalidateTags: ['other-tag'] })
+     * // If autoRevalidateTags produces ['posts'], final tags: ['posts', 'other-tag']
+     */
+    additionalRevalidateTags?: string[];
 };
-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 enlaceHookReact factory */
 type EnlaceHookOptions = {
     /**
      * Auto-generate cache tags from URL path for GET requests.
@@ -67,31 +44,59 @@ 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 ServerRevalidateHandler = (tags: string[], paths: string[]) => void | Promise<void>;
+/** Next.js-specific options (third argument for enlaceNext) */
+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
+     * enlaceNext("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;
+};
 
-type Listener = (tags: string[]) => void;
-declare function invalidateTags(tags: string[]): void;
-declare function onRevalidate(callback: Listener): () => void;
+declare function enlaceNext<TSchema = unknown, TDefaultError = unknown>(baseUrl: string, defaultOptions?: EnlaceOptions | null, nextOptions?: NextOptions): unknown extends TSchema ? WildcardClient<NextRequestOptionsBase> : EnlaceClient<TSchema, TDefaultError, NextRequestOptionsBase>;
 
-declare function clearCache(key?: string): void;
+declare function invalidateTags(tags: 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 NextOptions, type NextRequestOptionsBase, enlaceNext, invalidateTags };