enlace 0.0.0-alpha.4 → 0.0.1-beta.10

package/dist/hook/index.d.mts

@@ -0,0 +1,173 @@
+import { EnlaceCallbackPayload, EnlaceErrorCallbackPayload, EnlaceResponse, WildcardClient, EnlaceClient, EnlaceOptions, EnlaceCallbacks } from 'enlace-core';
+
+/** Per-request options for React hooks */
+type ReactRequestOptionsBase = {
+    /**
+     * 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[];
+    /** 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, 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 createEnlaceHookReact 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 createEnlaceHookReact */
+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): UseEnlaceQueryResult<TData, TError>;
+};
+
+/**
+ * Creates a React hook for making API calls.
+ * Called at module level to create a reusable hook.
+ *
+ * @example
+ * const useAPI = createEnlaceHookReact<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 createEnlaceHookReact<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 RevalidateHandler = (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/", {}, {
+     *   revalidator: (tags, paths) => revalidateServerAction(tags, paths)
+     * });
+     * ```
+     */
+    revalidator?: RevalidateHandler;
+};
+/** Next.js hook options (third argument for createEnlaceHookNext) - extends React's EnlaceHookOptions */
+type NextHookOptions = EnlaceHookOptions & Pick<NextOptions, "revalidator">;
+/** 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
+     * This doesn't do anything on the client by itself - it's passed to the revalidator handler.
+     * You must implement the revalidation logic in the revalidator.
+     */
+    revalidatePaths?: string[];
+    /**
+     * Skip server-side revalidation for this request.
+     * Useful when autoRevalidateTags is enabled but you want to opt-out for specific mutations.
+     * You can still pass empty [] to revalidateTags to skip triggering revalidation.
+     * But this flag can be used if you want to revalidate client-side and skip server-side entirely.
+     * Eg. you don't fetch any data on server component and you might want to skip the overhead of revalidation.
+     */
+    skipRevalidator?: 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 createEnlaceHookNext */
+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): UseEnlaceQueryResult<TData, TError>;
+};
+
+/**
+ * Creates a React hook for making API calls in Next.js Client Components.
+ * Uses Next.js-specific features like revalidator for server-side cache invalidation.
+ *
+ * @example
+ * const useAPI = createEnlaceHookNext<ApiSchema>('https://api.com', {}, {
+ *   revalidator: (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 createEnlaceHookNext<TSchema = unknown, TDefaultError = unknown>(baseUrl: string, defaultOptions?: EnlaceOptions, hookOptions?: NextHookOptions): NextEnlaceHook<TSchema, TDefaultError>;
+
+export { type ApiClient, type EnlaceHook, type EnlaceHookOptions, HTTP_METHODS, type HookState, type NextEnlaceHook, type NextHookOptions, type QueryFn, type ReactRequestOptionsBase, type SelectorFn, type TrackedCall, type UseEnlaceQueryOptions, type UseEnlaceQueryResult, type UseEnlaceSelectorResult, createEnlaceHookNext, createEnlaceHookReact };

package/dist/hook/index.d.ts

@@ -0,0 +1,173 @@
+import { EnlaceCallbackPayload, EnlaceErrorCallbackPayload, EnlaceResponse, WildcardClient, EnlaceClient, EnlaceOptions, EnlaceCallbacks } from 'enlace-core';
+
+/** Per-request options for React hooks */
+type ReactRequestOptionsBase = {
+    /**
+     * 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[];
+    /** 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, 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 createEnlaceHookReact 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 createEnlaceHookReact */
+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): UseEnlaceQueryResult<TData, TError>;
+};
+
+/**
+ * Creates a React hook for making API calls.
+ * Called at module level to create a reusable hook.
+ *
+ * @example
+ * const useAPI = createEnlaceHookReact<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 createEnlaceHookReact<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 RevalidateHandler = (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/", {}, {
+     *   revalidator: (tags, paths) => revalidateServerAction(tags, paths)
+     * });
+     * ```
+     */
+    revalidator?: RevalidateHandler;
+};
+/** Next.js hook options (third argument for createEnlaceHookNext) - extends React's EnlaceHookOptions */
+type NextHookOptions = EnlaceHookOptions & Pick<NextOptions, "revalidator">;
+/** 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
+     * This doesn't do anything on the client by itself - it's passed to the revalidator handler.
+     * You must implement the revalidation logic in the revalidator.
+     */
+    revalidatePaths?: string[];
+    /**
+     * Skip server-side revalidation for this request.
+     * Useful when autoRevalidateTags is enabled but you want to opt-out for specific mutations.
+     * You can still pass empty [] to revalidateTags to skip triggering revalidation.
+     * But this flag can be used if you want to revalidate client-side and skip server-side entirely.
+     * Eg. you don't fetch any data on server component and you might want to skip the overhead of revalidation.
+     */
+    skipRevalidator?: 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 createEnlaceHookNext */
+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): UseEnlaceQueryResult<TData, TError>;
+};
+
+/**
+ * Creates a React hook for making API calls in Next.js Client Components.
+ * Uses Next.js-specific features like revalidator for server-side cache invalidation.
+ *
+ * @example
+ * const useAPI = createEnlaceHookNext<ApiSchema>('https://api.com', {}, {
+ *   revalidator: (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 createEnlaceHookNext<TSchema = unknown, TDefaultError = unknown>(baseUrl: string, defaultOptions?: EnlaceOptions, hookOptions?: NextHookOptions): NextEnlaceHook<TSchema, TDefaultError>;
+
+export { type ApiClient, type EnlaceHook, type EnlaceHookOptions, HTTP_METHODS, type HookState, type NextEnlaceHook, type NextHookOptions, type QueryFn, type ReactRequestOptionsBase, type SelectorFn, type TrackedCall, type UseEnlaceQueryOptions, type UseEnlaceQueryResult, type UseEnlaceSelectorResult, createEnlaceHookNext, createEnlaceHookReact };