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

package/dist/hook/index.d.mts

@@ -0,0 +1,220 @@
+import { EnlaceCallbackPayload, EnlaceErrorCallbackPayload, EnlaceResponse, CoreRequestOptionsBase, WildcardClient, EnlaceClient, EnlaceOptions, EnlaceCallbacks } from 'enlace-core';
+
+/**
+ * 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[];
+};
+/** Runtime request options that includes all possible properties */
+type AnyReactRequestOptions = ReactRequestOptionsBase & {
+    params?: Record<string, string | number>;
+};
+/** Polling interval value: milliseconds to wait, or false to stop polling */
+type PollingIntervalValue = number | false;
+/** Function that determines polling interval based on current data/error state */
+type PollingIntervalFn<TData, TError> = (data: TData | undefined, error: TError | undefined) => PollingIntervalValue;
+/** Polling interval option: static value or dynamic function */
+type PollingInterval<TData = unknown, TError = unknown> = PollingIntervalValue | PollingIntervalFn<TData, TError>;
+/** Options for query mode hooks */
+type UseEnlaceQueryOptions<TData = unknown, TError = unknown> = {
+    /**
+     * Whether the query should execute.
+     * Set to false to skip fetching (useful when ID is "new" or undefined).
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Polling interval in milliseconds, or a function that returns the interval.
+     * When set, the query will refetch after this interval AFTER the previous request completes.
+     * Uses sequential polling (setTimeout after fetch completes), not interval-based.
+     *
+     * Can be:
+     * - `number`: Fixed interval in milliseconds
+     * - `false`: Disable polling
+     * - `(data, error) => number | false`: Dynamic interval based on response
+     *
+     * @example
+     * // Fixed interval
+     * { pollingInterval: 5000 }
+     *
+     * // Conditional polling based on data
+     * { pollingInterval: (order) => order?.status === 'pending' ? 2000 : false }
+     *
+     * @default undefined (no polling)
+     */
+    pollingInterval?: PollingInterval<TData, TError>;
+};
+type ApiClient<TSchema, TDefaultError = unknown, TOptions = ReactRequestOptionsBase> = unknown extends TSchema ? WildcardClient<TOptions> : EnlaceClient<TSchema, TDefaultError, TOptions>;
+type QueryFn<TSchema, TData, TError, TDefaultError = unknown, TOptions = ReactRequestOptionsBase> = (api: ApiClient<TSchema, TDefaultError, TOptions>) => Promise<EnlaceResponse<TData, TError>>;
+type SelectorFn<TSchema, TMethod, TDefaultError = unknown, TOptions = ReactRequestOptionsBase> = (api: ApiClient<TSchema, TDefaultError, TOptions>) => TMethod;
+type HookState = {
+    loading: boolean;
+    fetching: boolean;
+    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 via error check */
+type HookResponseState<TData, TError> = {
+    data: TData;
+    error?: undefined;
+} | {
+    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.
+     * e.g., `/posts/1` generates tags `['posts', 'posts/1']`
+     * @default true
+     */
+    autoGenerateTags?: boolean;
+    /** Auto-revalidate generated tags after successful mutations. @default true */
+    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 enlaceHookReact */
+type EnlaceHook<TSchema, TDefaultError = unknown> = {
+    <TMethod extends (...args: any[]) => Promise<EnlaceResponse<unknown, unknown>>>(selector: SelectorFn<TSchema, TMethod, TDefaultError>): UseEnlaceSelectorResult<TMethod>;
+    <TData, TError>(queryFn: QueryFn<TSchema, TData, TError, TDefaultError>, options?: UseEnlaceQueryOptions<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 = enlaceHookReact<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 } })}
+ */
+declare function enlaceHookReact<TSchema = unknown, TDefaultError = unknown>(baseUrl: string, defaultOptions?: EnlaceOptions, hookOptions?: EnlaceHookOptions): EnlaceHook<TSchema, TDefaultError>;
+
+/**
+ * Handler function called after successful mutations to trigger server-side revalidation.
+ * @param tags - Cache tags to revalidate
+ * @param paths - URL paths to revalidate
+ */
+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;
+};
+/** Next.js hook options (third argument for enlaceHookNext) - extends React's EnlaceHookOptions */
+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.
+     * 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 NextQueryFn<TSchema, TData, TError, TDefaultError = unknown> = QueryFn<TSchema, TData, TError, TDefaultError, NextRequestOptionsBase>;
+type NextSelectorFn<TSchema, TMethod, TDefaultError = unknown> = SelectorFn<TSchema, TMethod, TDefaultError, NextRequestOptionsBase>;
+/** Hook type returned by enlaceHookNext */
+type NextEnlaceHook<TSchema, TDefaultError = unknown> = {
+    <TMethod extends (...args: any[]) => Promise<EnlaceResponse<unknown, unknown>>>(selector: NextSelectorFn<TSchema, TMethod, TDefaultError>): UseEnlaceSelectorResult<TMethod>;
+    <TData, TError>(queryFn: NextQueryFn<TSchema, TData, TError, TDefaultError>, options?: UseEnlaceQueryOptions<TData, TError>): UseEnlaceQueryResult<TData, TError>;
+};
+
+/**
+ * Creates a React hook for making API calls in Next.js Client Components.
+ * Uses Next.js-specific features like serverRevalidator for server-side cache invalidation.
+ *
+ * @example
+ * const useAPI = enlaceHookNext<ApiSchema>('https://api.com', {}, {
+ *   serverRevalidator: (tags) => revalidateTagsAction(tags),
+ *   staleTime: 5000,
+ * });
+ *
+ * // Query mode - auto-fetch
+ * const { loading, data, error } = useAPI((api) => api.posts.$get());
+ *
+ * // Selector mode - trigger for mutations
+ * const { trigger } = useAPI((api) => api.posts.$delete);
+ */
+declare function enlaceHookNext<TSchema = unknown, TDefaultError = unknown>(baseUrl: string, defaultOptions?: EnlaceOptions, hookOptions?: NextHookOptions): NextEnlaceHook<TSchema, TDefaultError>;
+
+export { type AnyReactRequestOptions, type ApiClient, type EnlaceHook, type EnlaceHookOptions, HTTP_METHODS, type HookState, type NextEnlaceHook, type NextHookOptions, type PollingInterval, type PollingIntervalFn, type PollingIntervalValue, type QueryFn, type ReactRequestOptionsBase, type SelectorFn, type TrackedCall, type UseEnlaceQueryOptions, type UseEnlaceQueryResult, type UseEnlaceSelectorResult, enlaceHookNext, enlaceHookReact };

package/dist/hook/index.d.ts

@@ -0,0 +1,220 @@
+import { EnlaceCallbackPayload, EnlaceErrorCallbackPayload, EnlaceResponse, CoreRequestOptionsBase, WildcardClient, EnlaceClient, EnlaceOptions, EnlaceCallbacks } from 'enlace-core';
+
+/**
+ * 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[];
+};
+/** Runtime request options that includes all possible properties */
+type AnyReactRequestOptions = ReactRequestOptionsBase & {
+    params?: Record<string, string | number>;
+};
+/** Polling interval value: milliseconds to wait, or false to stop polling */
+type PollingIntervalValue = number | false;
+/** Function that determines polling interval based on current data/error state */
+type PollingIntervalFn<TData, TError> = (data: TData | undefined, error: TError | undefined) => PollingIntervalValue;
+/** Polling interval option: static value or dynamic function */
+type PollingInterval<TData = unknown, TError = unknown> = PollingIntervalValue | PollingIntervalFn<TData, TError>;
+/** Options for query mode hooks */
+type UseEnlaceQueryOptions<TData = unknown, TError = unknown> = {
+    /**
+     * Whether the query should execute.
+     * Set to false to skip fetching (useful when ID is "new" or undefined).
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Polling interval in milliseconds, or a function that returns the interval.
+     * When set, the query will refetch after this interval AFTER the previous request completes.
+     * Uses sequential polling (setTimeout after fetch completes), not interval-based.
+     *
+     * Can be:
+     * - `number`: Fixed interval in milliseconds
+     * - `false`: Disable polling
+     * - `(data, error) => number | false`: Dynamic interval based on response
+     *
+     * @example
+     * // Fixed interval
+     * { pollingInterval: 5000 }
+     *
+     * // Conditional polling based on data
+     * { pollingInterval: (order) => order?.status === 'pending' ? 2000 : false }
+     *
+     * @default undefined (no polling)
+     */
+    pollingInterval?: PollingInterval<TData, TError>;
+};
+type ApiClient<TSchema, TDefaultError = unknown, TOptions = ReactRequestOptionsBase> = unknown extends TSchema ? WildcardClient<TOptions> : EnlaceClient<TSchema, TDefaultError, TOptions>;
+type QueryFn<TSchema, TData, TError, TDefaultError = unknown, TOptions = ReactRequestOptionsBase> = (api: ApiClient<TSchema, TDefaultError, TOptions>) => Promise<EnlaceResponse<TData, TError>>;
+type SelectorFn<TSchema, TMethod, TDefaultError = unknown, TOptions = ReactRequestOptionsBase> = (api: ApiClient<TSchema, TDefaultError, TOptions>) => TMethod;
+type HookState = {
+    loading: boolean;
+    fetching: boolean;
+    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 via error check */
+type HookResponseState<TData, TError> = {
+    data: TData;
+    error?: undefined;
+} | {
+    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.
+     * e.g., `/posts/1` generates tags `['posts', 'posts/1']`
+     * @default true
+     */
+    autoGenerateTags?: boolean;
+    /** Auto-revalidate generated tags after successful mutations. @default true */
+    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 enlaceHookReact */
+type EnlaceHook<TSchema, TDefaultError = unknown> = {
+    <TMethod extends (...args: any[]) => Promise<EnlaceResponse<unknown, unknown>>>(selector: SelectorFn<TSchema, TMethod, TDefaultError>): UseEnlaceSelectorResult<TMethod>;
+    <TData, TError>(queryFn: QueryFn<TSchema, TData, TError, TDefaultError>, options?: UseEnlaceQueryOptions<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 = enlaceHookReact<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 } })}
+ */
+declare function enlaceHookReact<TSchema = unknown, TDefaultError = unknown>(baseUrl: string, defaultOptions?: EnlaceOptions, hookOptions?: EnlaceHookOptions): EnlaceHook<TSchema, TDefaultError>;
+
+/**
+ * Handler function called after successful mutations to trigger server-side revalidation.
+ * @param tags - Cache tags to revalidate
+ * @param paths - URL paths to revalidate
+ */
+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;
+};
+/** Next.js hook options (third argument for enlaceHookNext) - extends React's EnlaceHookOptions */
+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.
+     * 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 NextQueryFn<TSchema, TData, TError, TDefaultError = unknown> = QueryFn<TSchema, TData, TError, TDefaultError, NextRequestOptionsBase>;
+type NextSelectorFn<TSchema, TMethod, TDefaultError = unknown> = SelectorFn<TSchema, TMethod, TDefaultError, NextRequestOptionsBase>;
+/** Hook type returned by enlaceHookNext */
+type NextEnlaceHook<TSchema, TDefaultError = unknown> = {
+    <TMethod extends (...args: any[]) => Promise<EnlaceResponse<unknown, unknown>>>(selector: NextSelectorFn<TSchema, TMethod, TDefaultError>): UseEnlaceSelectorResult<TMethod>;
+    <TData, TError>(queryFn: NextQueryFn<TSchema, TData, TError, TDefaultError>, options?: UseEnlaceQueryOptions<TData, TError>): UseEnlaceQueryResult<TData, TError>;
+};
+
+/**
+ * Creates a React hook for making API calls in Next.js Client Components.
+ * Uses Next.js-specific features like serverRevalidator for server-side cache invalidation.
+ *
+ * @example
+ * const useAPI = enlaceHookNext<ApiSchema>('https://api.com', {}, {
+ *   serverRevalidator: (tags) => revalidateTagsAction(tags),
+ *   staleTime: 5000,
+ * });
+ *
+ * // Query mode - auto-fetch
+ * const { loading, data, error } = useAPI((api) => api.posts.$get());
+ *
+ * // Selector mode - trigger for mutations
+ * const { trigger } = useAPI((api) => api.posts.$delete);
+ */
+declare function enlaceHookNext<TSchema = unknown, TDefaultError = unknown>(baseUrl: string, defaultOptions?: EnlaceOptions, hookOptions?: NextHookOptions): NextEnlaceHook<TSchema, TDefaultError>;
+
+export { type AnyReactRequestOptions, type ApiClient, type EnlaceHook, type EnlaceHookOptions, HTTP_METHODS, type HookState, type NextEnlaceHook, type NextHookOptions, type PollingInterval, type PollingIntervalFn, type PollingIntervalValue, type QueryFn, type ReactRequestOptionsBase, type SelectorFn, type TrackedCall, type UseEnlaceQueryOptions, type UseEnlaceQueryResult, type UseEnlaceSelectorResult, enlaceHookNext, enlaceHookReact };