@assebc/ng-signal-http 1.0.0

package/types/assebc-ng-signal-http.d.ts

@@ -0,0 +1,347 @@
+import * as i0 from '@angular/core';
+import { Signal, InjectionToken, EnvironmentProviders } from '@angular/core';
+
+/**
+ * Global configuration passed to `provideSignalHttp()`.
+ *
+ * @example
+ * provideSignalHttp({ baseUrl: 'https://api.example.com', timeout: 10_000 });
+ */
+interface SignalHttpConfig {
+    baseUrl?: string;
+    headers?: Record<string, string>;
+    timeout?: number;
+    interceptors?: HttpInterceptor[];
+}
+/**
+ * Hooks that intercept every request, response, or error in the pipeline.
+ * All three hooks are optional and may return a `Promise`.
+ * Interceptors run in registration order.
+ *
+ * @example
+ * const authInterceptor: HttpInterceptor = {
+ *   request: async (config) => ({
+ *     ...config,
+ *     headers: { ...config.headers, Authorization: `Bearer ${getToken()}` },
+ *   }),
+ * };
+ */
+interface HttpInterceptor {
+    request?: (config: RequestConfig) => RequestConfig | Promise<RequestConfig>;
+    response?: (response: Response) => Response | Promise<Response>;
+    error?: (error: Error) => Error | Promise<never>;
+}
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+/**
+ * Per-request options. Passed to `SignalHttpClient.executeRequest()` or
+ * returned by a `UrlFactory` to provide method and body alongside the URL.
+ *
+ * @example
+ * const config: RequestConfig = {
+ *   url: '/users/1',
+ *   method: 'GET',
+ *   params: { expand: 'address' },
+ * };
+ */
+interface RequestConfig {
+    url: string;
+    method: HttpMethod;
+    headers?: Record<string, string>;
+    body?: unknown;
+    params?: Record<string, string | number | boolean>;
+    /** Overrides the global timeout for this request. */
+    timeout?: number;
+    /** Merged with the internal `AbortController` signal. */
+    signal?: AbortSignal;
+}
+/**
+ * Fine-grained retry configuration for `querySignal`.
+ * `AbortError` is never retried regardless of this config.
+ *
+ * @example
+ * const retry: RetryConfig = {
+ *   count: 3,
+ *   delay: (attempt) => 1000 * 2 ** (attempt - 1),
+ *   shouldRetry: (err) => !(err instanceof HttpError && err.isClientError),
+ * };
+ */
+interface RetryConfig {
+    count: number;
+    delay?: number | ((attempt: number) => number);
+    shouldRetry?: (error: Error, attempt: number) => boolean;
+}
+type HttpClientStatus = 'idle' | 'loading' | 'success' | 'error';
+/**
+ * Options for `querySignal()`.
+ *
+ * @template T - The expected response data type.
+ *
+ * @example
+ * querySignal('/users', { retry: 3, refetchOnFocus: true, staleTime: 60_000 });
+ */
+interface HttpClientOptions<T> {
+    initialValue?: T;
+    lazy?: boolean;
+    retry?: number | RetryConfig;
+    staleTime?: number;
+    refetchInterval?: number;
+    refetchOnFocus?: boolean;
+    refetchOnReconnect?: boolean;
+    onSuccess?: (data: T) => void;
+    onError?: (error: Error) => void;
+}
+/**
+ * State and control handle returned by `querySignal()`.
+ *
+ * @template T - The response data type.
+ *
+ * @example
+ * const result = querySignal<User>('/users/1');
+ * effect(() => console.log(result.status(), result.data()));
+ */
+interface HttpClientResult<T> {
+    readonly data: Signal<T | null>;
+    readonly loading: Signal<boolean>;
+    readonly error: Signal<Error | null>;
+    readonly status: Signal<HttpClientStatus>;
+    readonly isStale: Signal<boolean>;
+    refetch: () => Promise<void>;
+    invalidate: () => void;
+    reset: () => void;
+}
+type QueryStatus = HttpClientStatus;
+type QueryResult<T> = HttpClientResult<T>;
+type RequestOptions<T> = HttpClientOptions<T>;
+/**
+ * Lifecycle callbacks for `mutationSignal()`.
+ *
+ * @template TInput - The input type passed to `mutate()`.
+ * @template TOutput - The response data type.
+ *
+ * @example
+ * mutationSignal(factory, { onSuccess: (data) => toast('Saved!') });
+ */
+interface MutationOptions<TInput, TOutput> {
+    onSuccess?: (data: TOutput, input: TInput) => void;
+    onError?: (error: Error, input: TInput) => void;
+    onSettled?: (data: TOutput | null, error: Error | null, input: TInput) => void;
+}
+/**
+ * State and control handle returned by `mutationSignal()`.
+ *
+ * @template TInput - The input type passed to `mutate()`.
+ * @template TOutput - The response data type.
+ *
+ * @example
+ * const create = mutationSignal<NewUser, User>(factory);
+ * await create.mutate({ name: 'Alice' });
+ */
+interface MutationResult<TInput, TOutput> {
+    readonly isPending: Signal<boolean>;
+    readonly error: Signal<Error | null>;
+    readonly data: Signal<TOutput | null>;
+    mutate: (input: TInput) => Promise<TOutput>;
+    reset: () => void;
+}
+
+/**
+ * Low-level HTTP service that wraps the native Fetch API.
+ * Prefer `querySignal` and `mutationSignal` for component use;
+ * use this directly in guards, resolvers, and async effects.
+ *
+ * @example
+ * const http = inject(SignalHttpClient);
+ * const user = await http.executeRequest<User>({ url: '/users/1', method: 'GET' });
+ */
+declare class SignalHttpClient {
+    private readonly config;
+    /**
+     * Fires a GET request and returns a read-only signal updated when the response arrives.
+     * Must be called from an injection context. The request is aborted on host destroy.
+     *
+     * @param url - Absolute or base-relative URL.
+     * @param options - Per-request overrides (headers, params, timeout, signal).
+     * @returns A read-only `Signal<T | null>` — `null` until the response arrives.
+     *
+     * @example
+     * readonly user = inject(SignalHttpClient).get<User>('/users/1');
+     */
+    get<T>(url: string, options?: Partial<RequestConfig>): Signal<T | null>;
+    /**
+     * Fires a POST request and returns a read-only signal updated when the response arrives.
+     * Must be called from an injection context. The request is aborted on host destroy.
+     *
+     * @param url - Absolute or base-relative URL.
+     * @param body - Request body; serialised to JSON.
+     * @param options - Per-request overrides.
+     * @returns A read-only `Signal<T | null>` — `null` until the response arrives.
+     *
+     * @example
+     * readonly result = inject(SignalHttpClient).post<Token>('/auth/login', credentials);
+     */
+    post<T>(url: string, body?: unknown, options?: Partial<RequestConfig>): Signal<T | null>;
+    /**
+     * Fires a PUT request and returns a read-only signal updated when the response arrives.
+     * Must be called from an injection context. The request is aborted on host destroy.
+     *
+     * @param url - Absolute or base-relative URL.
+     * @param body - Request body; serialised to JSON.
+     * @param options - Per-request overrides.
+     * @returns A read-only `Signal<T | null>` — `null` until the response arrives.
+     *
+     * @example
+     * readonly updated = inject(SignalHttpClient).put<User>('/users/1', { name: 'Alice' });
+     */
+    put<T>(url: string, body?: unknown, options?: Partial<RequestConfig>): Signal<T | null>;
+    /**
+     * Fires a PATCH request and returns a read-only signal updated when the response arrives.
+     * Must be called from an injection context. The request is aborted on host destroy.
+     *
+     * @param url - Absolute or base-relative URL.
+     * @param body - Partial request body; serialised to JSON.
+     * @param options - Per-request overrides.
+     * @returns A read-only `Signal<T | null>` — `null` until the response arrives.
+     *
+     * @example
+     * readonly patched = inject(SignalHttpClient).patch<User>('/users/1', { email: 'new@example.com' });
+     */
+    patch<T>(url: string, body?: unknown, options?: Partial<RequestConfig>): Signal<T | null>;
+    /**
+     * Fires a DELETE request and returns a read-only signal updated when the response arrives.
+     * Must be called from an injection context. The request is aborted on host destroy.
+     *
+     * @param url - Absolute or base-relative URL.
+     * @param options - Per-request overrides.
+     * @returns A read-only `Signal<T | null>` — `null` until the response arrives.
+     *
+     * @example
+     * readonly deleted = inject(SignalHttpClient).delete<void>('/users/1');
+     */
+    delete<T>(url: string, options?: Partial<RequestConfig>): Signal<T | null>;
+    /**
+     * Executes a raw HTTP request and returns a `Promise`.
+     * Use this in effects, event handlers, guards, and resolvers where async/await is preferred.
+     * Runs request → response → error interceptors in registration order.
+     * `AbortError` is re-thrown without passing through error interceptors.
+     *
+     * @param config - Full request configuration including method and URL.
+     * @returns A `Promise` that resolves with the parsed response body.
+     * @throws `HttpError` on non-2xx responses; `AbortError` on cancellation.
+     *
+     * @example
+     * const token = await http.executeRequest<Token>({ url: '/auth/login', method: 'POST', body: creds });
+     */
+    executeRequest<T>(config: RequestConfig): Promise<T>;
+    private createSignal;
+    private buildUrl;
+    private buildHeaders;
+    private parseResponse;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SignalHttpClient, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<SignalHttpClient>;
+}
+
+declare const SIGNAL_HTTP_CONFIG: InjectionToken<SignalHttpConfig>;
+/**
+ * Registers `ng-signal-http` in an Angular application.
+ * Call once in `app.config.ts` inside `ApplicationConfig.providers`.
+ *
+ * @param config - Global HTTP configuration applied to all requests.
+ * @returns Angular `EnvironmentProviders` to add to your app config.
+ *
+ * @example
+ * export const appConfig: ApplicationConfig = {
+ *   providers: [provideSignalHttp({ baseUrl: 'https://api.example.com' })],
+ * };
+ */
+declare function provideSignalHttp(config?: SignalHttpConfig): EnvironmentProviders;
+
+/**
+ * Error thrown when an HTTP request receives a non-2xx response.
+ * Extends the native `Error` class and adds HTTP-specific helpers.
+ *
+ * @example
+ * effect(() => {
+ *   const err = query.error();
+ *   if (err instanceof HttpError && err.isUnauthorized) router.navigate(['/login']);
+ * });
+ */
+declare class HttpError extends Error {
+    readonly status: number;
+    readonly response?: Response | undefined;
+    /**
+     * @param message - Human-readable error description.
+     * @param status - HTTP status code (e.g. 404, 500).
+     * @param response - The raw `Response` object, if available.
+     */
+    constructor(message: string, status: number, response?: Response | undefined);
+    get isClientError(): boolean;
+    get isServerError(): boolean;
+    get isTimeout(): boolean;
+    get isNotFound(): boolean;
+    get isUnauthorized(): boolean;
+    get isForbidden(): boolean;
+}
+
+type UrlFactory = () => string | RequestConfig;
+
+/**
+ * Creates a reactive GET query bound to the current Angular injection context.
+ *
+ * Fetches immediately (unless `lazy: true`) and re-fetches automatically whenever
+ * any signal read inside the `url` factory changes. The in-flight request is
+ * aborted when the host component or service is destroyed.
+ *
+ * @template T - The expected response data type.
+ * @param url - A static URL string or a factory that returns a URL or `RequestConfig`.
+ *              Signal reads inside the factory are tracked — changing them triggers a re-fetch.
+ * @param options - Query behaviour: lazy loading, retry, stale time, polling, callbacks, etc.
+ * @returns An `HttpClientResult<T>` with reactive signals and control methods.
+ *
+ * @example
+ * // Static URL — fetch once on init
+ * const posts = querySignal<Post[]>('/posts');
+ *
+ * @example
+ * // Reactive factory — refetches when postId() changes
+ * const postId = signal(1);
+ * const post = querySignal<Post>(() => `/posts/${postId()}`);
+ *
+ * @example
+ * // With options
+ * const data = querySignal('/feed', {
+ *   retry: 3,
+ *   refetchOnFocus: true,
+ *   staleTime: 60_000,
+ *   onError: (err) => console.error(err),
+ * });
+ */
+declare function querySignal<T>(url: string | UrlFactory, options?: HttpClientOptions<T>): HttpClientResult<T>;
+
+type MutationFactory<TInput> = (input: TInput) => RequestConfig;
+
+/**
+ * Creates an imperative mutation bound to the current Angular injection context.
+ *
+ * Does nothing until `mutate(input)` is called. Calling `mutate()` while a previous
+ * request is in flight cancels the previous request automatically.
+ * The in-flight request is aborted when the host component or service is destroyed.
+ *
+ * @template TInput - The input type passed to `mutate()`.
+ * @template TOutput - The response data type returned by the server.
+ * @param requestFactory - Receives the mutation input and returns a `RequestConfig`.
+ * @param options - Optional lifecycle callbacks (`onSuccess`, `onError`, `onSettled`).
+ * @returns A `MutationResult<TInput, TOutput>` with reactive signals and a `mutate` trigger.
+ *
+ * @example
+ * const createPost = mutationSignal<NewPost, Post>(
+ *   (input) => ({ url: '/posts', method: 'POST', body: input }),
+ *   { onSuccess: (post) => console.log('Created:', post.id) },
+ * );
+ *
+ * // Trigger from an event handler:
+ * await createPost.mutate({ title: 'Hello', body: 'World', userId: 1 });
+ */
+declare function mutationSignal<TInput, TOutput>(requestFactory: MutationFactory<TInput>, options?: MutationOptions<TInput, TOutput>): MutationResult<TInput, TOutput>;
+
+export { HttpError, SIGNAL_HTTP_CONFIG, SignalHttpClient, mutationSignal, provideSignalHttp, querySignal };
+export type { HttpInterceptor, HttpMethod, MutationFactory, MutationOptions, MutationResult, QueryResult, QueryStatus, RequestConfig, RequestOptions, RetryConfig, SignalHttpConfig, UrlFactory };