ngx-api-forms 1.0.0

package/index.d.ts

@@ -0,0 +1,621 @@
+import * as _angular_forms from '@angular/forms';
+import { FormGroup, ValidationErrors } from '@angular/forms';
+import * as i0 from '@angular/core';
+import { Signal, OnInit, OnChanges, SimpleChanges } from '@angular/core';
+import { HttpErrorResponse, HttpInterceptorFn, HttpContext, HttpContextToken } from '@angular/common/http';
+import { Observable } from 'rxjs';
+
+/**
+ * ngx-api-forms - Models & Interfaces
+ *
+ * Core types for bridging API validation errors to Angular Reactive Forms.
+ */
+
+/**
+ * A single field-level validation error returned by the API.
+ */
+interface ApiFieldError {
+    /** The form control name / field property name */
+    field: string;
+    /** The validation constraint key (e.g. 'required', 'minLength', 'isEmail') */
+    constraint: string;
+    /** The human-readable error message */
+    message: string;
+}
+/**
+ * Raw error shape from class-validator / NestJS (ValidationPipe).
+ * This is the standard shape when `exceptionFactory` is not customized.
+ */
+interface ClassValidatorError {
+    property: string;
+    constraints?: Record<string, string>;
+    children?: ClassValidatorError[];
+}
+/**
+ * Raw error shape from Laravel validation.
+ * Laravel returns `{ errors: { field: ['message1', 'message2'] } }`.
+ */
+type LaravelValidationErrors = Record<string, string[]>;
+/**
+ * Raw error shape from Django REST Framework.
+ * DRF returns `{ field: ['message1', 'message2'] }`.
+ */
+type DjangoValidationErrors = Record<string, string[]>;
+/**
+ * Raw error shape from Zod (.flatten()).
+ * Zod returns `{ fieldErrors: { field: ['message1'] } }`.
+ */
+interface ZodFlatError {
+    formErrors: string[];
+    fieldErrors: Record<string, string[]>;
+}
+/**
+ * Sentinel field name used by presets to tag errors that are not bound to a
+ * specific form control (e.g. Django `non_field_errors`, Zod `formErrors`).
+ *
+ * FormBridge also routes any ApiFieldError whose field does not match a control
+ * to `globalErrorsSignal`, so custom presets do not need to use this constant -
+ * unmatched fields are captured automatically.
+ */
+declare const GLOBAL_ERROR_FIELD = "__global__";
+/**
+ * An error that does not belong to any specific form control.
+ *
+ * Sources:
+ * - Django `non_field_errors` / `detail`
+ * - Zod `formErrors`
+ * - Any API error whose field name does not match a control in the form
+ */
+interface GlobalError {
+    /** The human-readable error message */
+    message: string;
+    /** The constraint key (e.g. 'serverError') */
+    constraint: string;
+    /** The original field name from the API response, if any */
+    originalField?: string;
+}
+/**
+ * An ErrorPreset knows how to parse a specific API error shape
+ * into a normalized array of `ApiFieldError`.
+ *
+ * This is the extension point for supporting any backend.
+ */
+interface ErrorPreset {
+    /** Unique name for identification (e.g. 'class-validator', 'laravel') */
+    readonly name: string;
+    /**
+     * Parse the raw API error body into normalized field errors.
+     * Should return an empty array if the format is not recognized.
+     */
+    parse(error: unknown): ApiFieldError[];
+    /**
+     * Optional constraint map shipped with this preset.
+     * When provided, FormBridge merges it into its constraint resolution table
+     * automatically - no need to pass a `constraintMap` in the config.
+     */
+    readonly constraintMap?: ConstraintMap;
+}
+/**
+ * Maps a constraint key to an Angular validation error key.
+ * For example: `{ isEmail: 'email', minLength: 'minlength' }`
+ */
+type ConstraintMap = Record<string, string>;
+/**
+ * Configuration for i18n error message resolution.
+ */
+interface I18nConfig {
+    /**
+     * Prefix for i18n translation keys.
+     * Example: 'forms.errors' → key becomes 'forms.errors.email.required'
+     */
+    prefix?: string;
+    /**
+     * Custom resolver function for translating error keys.
+     * If provided, this is called instead of using a prefix.
+     *
+     * @param field - The form field name
+     * @param constraint - The constraint key
+     * @param message - The original API message
+     * @returns The translated message, or null to use the original
+     */
+    resolver?: (field: string, constraint: string, message: string) => string | null;
+}
+/**
+ * Configuration options for creating a FormBridge instance.
+ */
+interface FormBridgeConfig {
+    /**
+     * The error preset to use for parsing API errors.
+     * Can be a single preset or an array (tried in order).
+     */
+    preset?: ErrorPreset | ErrorPreset[];
+    /**
+     * Custom constraint-to-Angular-error mapping.
+     * Overrides the defaults from the preset.
+     * Example: `{ isEmail: 'email', isNotEmpty: 'required' }`
+     */
+    constraintMap?: ConstraintMap;
+    /**
+     * i18n configuration for error messages.
+     */
+    i18n?: I18nConfig;
+    /**
+     * When true, unmapped API errors are set as `{ generic: message }` on the control.
+     * When false (default), unmapped errors are ignored.
+     */
+    catchAll?: boolean;
+    /**
+     * When true, existing validation errors on the form are preserved
+     * when applying API errors (merged). When false (default), API errors
+     * replace existing errors on affected controls.
+     */
+    mergeErrors?: boolean;
+    /**
+     * When true, logs warnings to the console when:
+     * - No preset produces results for a given error payload.
+     * - A parsed error field does not match any form control.
+     *
+     * Useful during development. Should be disabled in production.
+     */
+    debug?: boolean;
+}
+/**
+ * Represents a resolved error on a specific form field.
+ */
+interface ResolvedFieldError {
+    /** The form control name */
+    field: string;
+    /** The Angular validation error key (e.g. 'required', 'email') */
+    errorKey: string;
+    /** The error message */
+    message: string;
+}
+/**
+ * Return type for `getFirstError()`.
+ */
+interface FirstError {
+    field: string;
+    errorKey: string;
+    message: string;
+}
+/**
+ * Options for `enableForm()`.
+ */
+interface EnableFormOptions {
+    /** Control names to exclude from enabling */
+    except?: string[];
+}
+/**
+ * Options for `disableForm()`.
+ */
+interface DisableFormOptions {
+    /** Control names to exclude from disabling */
+    except?: string[];
+}
+/**
+ * Extract control names from a typed FormGroup.
+ */
+type FormControlNames<T extends FormGroup> = T extends FormGroup<infer C> ? Extract<keyof C, string> : string;
+/**
+ * Signature for a custom error handler that can intercept
+ * errors before they are applied to the form.
+ */
+type ErrorInterceptor = (errors: ApiFieldError[], form: FormGroup) => ApiFieldError[];
+
+/**
+ * FormBridge - The core class of ngx-api-forms.
+ *
+ * Bridges API validation errors to Angular Reactive Forms with:
+ * - Automatic error parsing via presets (class-validator, Laravel, Django, Zod)
+ * - i18n-friendly error messages
+ * - Angular Signals support
+ * - SSR-safe operations
+ */
+
+/**
+ * FormBridge wraps an Angular FormGroup and provides a clean API
+ * for bridging API validation errors and managing form state.
+ *
+ * @example
+ * ```typescript
+ * const bridge = new FormBridge(myForm, {
+ *   preset: classValidatorPreset(),
+ * });
+ *
+ * // Apply API errors
+ * bridge.applyApiErrors(err.error);
+ *
+ * // Use signals in templates
+ * readonly errors = bridge.errorsSignal;
+ * readonly firstError = bridge.firstErrorSignal;
+ * ```
+ */
+declare class FormBridge<T extends FormGroup = FormGroup> {
+    private readonly _form;
+    private readonly _presets;
+    private readonly _constraintMap;
+    private readonly _i18n;
+    private readonly _catchAll;
+    private readonly _mergeErrors;
+    private readonly _debug;
+    private _interceptors;
+    /** Signal containing the last set of resolved API errors */
+    private readonly _apiErrors;
+    /** Signal containing global (non-field) errors */
+    private readonly _globalErrors;
+    /** Tracks which error keys were set by the API on each control */
+    private _apiErrorKeys;
+    /** Reactive signal of all current API errors applied to the form */
+    readonly errorsSignal: Signal<ResolvedFieldError[]>;
+    /**
+     * Reactive signal of global (non-field) errors.
+     *
+     * Contains errors from:
+     * - Django `non_field_errors` / `detail`
+     * - Zod `formErrors`
+     * - Any API error whose field does not match a form control
+     */
+    readonly globalErrorsSignal: Signal<GlobalError[]>;
+    /** Reactive signal of the first error (or null) */
+    readonly firstErrorSignal: Signal<FirstError | null>;
+    /** Whether any API errors are currently applied */
+    readonly hasErrorsSignal: Signal<boolean>;
+    constructor(form: T, config?: FormBridgeConfig);
+    /**
+     * Parse and apply API validation errors to the form.
+     *
+     * Tries each configured preset in order until one returns results.
+     * Errors are mapped to Angular form control errors.
+     *
+     * @param apiError - The raw error body from the API (e.g. `err.error`)
+     * @returns The array of resolved field errors that were applied
+     */
+    applyApiErrors(apiError: unknown): ResolvedFieldError[];
+    /**
+     * Clear only the errors that were set by `applyApiErrors()`.
+     * Client-side validation errors (e.g. `Validators.required`) are preserved.
+     */
+    clearApiErrors(): void;
+    /**
+     * Get the first error across all form controls.
+     */
+    getFirstError(): FirstError | null;
+    /**
+     * Get all errors for a specific field.
+     */
+    getFieldErrors(fieldName: string): ValidationErrors | null;
+    /**
+     * Register an error interceptor that can modify or filter errors
+     * before they are applied to the form.
+     * Returns a dispose function to remove the interceptor.
+     */
+    addInterceptor(interceptor: ErrorInterceptor): () => void;
+    /**
+     * Access the underlying FormGroup.
+     */
+    get form(): T;
+    private _resolvePresetConstraintMap;
+    private _applyErrors;
+    private _resolveNestedControl;
+    private _resolveErrorKey;
+    private _resolveMessage;
+}
+/**
+ * Factory function to create a FormBridge instance.
+ *
+ * @example
+ * ```typescript
+ * import { createFormBridge, classValidatorPreset } from 'ngx-api-forms';
+ *
+ * const bridge = createFormBridge(this.myForm, {
+ *   preset: classValidatorPreset(),
+ *   i18n: { prefix: 'validation' },
+ * });
+ *
+ * // In your API call error handler:
+ * bridge.applyApiErrors(err.error);
+ * ```
+ */
+declare function createFormBridge<T extends FormGroup>(form: T, config: FormBridgeConfig): FormBridge<T>;
+declare function createFormBridge<T extends FormGroup>(form: T): FormBridge<T>;
+/**
+ * Alias for `createFormBridge`.
+ *
+ * Both functions are identical since FormBridge no longer holds internal
+ * subscriptions. Kept for API compatibility with existing code.
+ *
+ * @example
+ * ```typescript
+ * @Component({ ... })
+ * export class MyComponent {
+ *   private form = inject(FormBuilder).group({ email: [''] });
+ *   private bridge = provideFormBridge(this.form, {
+ *     preset: classValidatorPreset(),
+ *   });
+ *
+ *   onSubmit() {
+ *     this.http.post('/api', this.form.value).subscribe({
+ *       error: (err) => this.bridge.applyApiErrors(err.error),
+ *     });
+ *   }
+ * }
+ * ```
+ */
+declare function provideFormBridge<T extends FormGroup>(form: T, config: FormBridgeConfig): FormBridge<T>;
+declare function provideFormBridge<T extends FormGroup>(form: T): FormBridge<T>;
+
+/**
+ * class-validator / NestJS error preset.
+ *
+ * Parses the standard ValidationPipe error format:
+ * ```json
+ * {
+ *   "statusCode": 400,
+ *   "message": [
+ *     { "property": "email", "constraints": { "isEmail": "email must be an email" } }
+ *   ],
+ *   "error": "Bad Request"
+ * }
+ * ```
+ *
+ * Also handles flat string messages from NestJS:
+ * ```json
+ * { "statusCode": 400, "message": "email is already used" }
+ * ```
+ */
+
+/**
+ * Creates a class-validator / NestJS error preset.
+ *
+ * @param options.noInference - When true, skips constraint guessing for string messages.
+ *   Structured `constraints` objects (e.g. `{ isEmail: 'message' }`) are always used as-is.
+ *   Only affects the fallback string message parser.
+ *
+ * @example
+ * ```typescript
+ * import { classValidatorPreset } from 'ngx-api-forms';
+ *
+ * const bridge = createFormBridge(form, { preset: classValidatorPreset() });
+ *
+ * // No inference on string messages
+ * const bridge = createFormBridge(form, { preset: classValidatorPreset({ noInference: true }) });
+ * ```
+ */
+declare function classValidatorPreset(options?: {
+    noInference?: boolean;
+}): ErrorPreset;
+/**
+ * Default constraint map for class-validator.
+ * Maps class-validator constraint names to Angular form error keys.
+ */
+declare const CLASS_VALIDATOR_CONSTRAINT_MAP: Record<string, string>;
+
+/**
+ * NgxFormError directive.
+ *
+ * Automatically displays the error message for a form control.
+ * Works with both client-side validators and API errors set by FormBridge.
+ *
+ * @example
+ * ```html
+ * <input formControlName="email" />
+ * <span ngxFormError="email" [form]="myForm"></span>
+ * <!-- Displays: "email must be a valid email" -->
+ *
+ * <!-- With custom error map -->
+ * <span ngxFormError="email"
+ *       [form]="myForm"
+ *       [errorMessages]="{ required: 'Email is required', email: 'Invalid email' }">
+ * </span>
+ * ```
+ */
+
+declare class NgxFormErrorDirective implements OnInit, OnChanges {
+    private readonly el;
+    private readonly renderer;
+    private readonly destroyRef;
+    private readonly resubscribe$;
+    /** The form control name to observe */
+    controlName: string;
+    /** The parent FormGroup */
+    form: FormGroup;
+    /**
+     * Optional map of error keys to display messages.
+     * If not provided, the raw error value is used (which is the API message
+     * when set by FormBridge).
+     */
+    errorMessages?: Record<string, string>;
+    /**
+     * CSS class applied to the host element when an error is displayed.
+     * Default: 'ngx-form-error-visible'
+     */
+    errorClass: string;
+    /**
+     * Whether to show errors only when the control is touched.
+     * Default: true
+     */
+    showOnTouched: boolean;
+    ngOnInit(): void;
+    ngOnChanges(changes: SimpleChanges): void;
+    private _subscribe;
+    private _updateDisplay;
+    private _show;
+    private _hide;
+    static ɵfac: i0.ɵɵFactoryDeclaration<NgxFormErrorDirective, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<NgxFormErrorDirective, "[ngxFormError]", never, { "controlName": { "alias": "ngxFormError"; "required": false; }; "form": { "alias": "form"; "required": false; }; "errorMessages": { "alias": "errorMessages"; "required": false; }; "errorClass": { "alias": "errorClass"; "required": false; }; "showOnTouched": { "alias": "showOnTouched"; "required": false; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * HttpContext token that carries a FormBridge reference on a request.
+ * Used by `withFormBridge()` to tag requests for automatic error handling.
+ */
+declare const FORM_BRIDGE: HttpContextToken<FormBridge<_angular_forms.FormGroup<any>> | null>;
+/**
+ * Configuration for `apiErrorInterceptor`.
+ */
+interface ApiErrorInterceptorConfig {
+    /**
+     * Preset(s) used for standalone parsing when no FormBridge is attached
+     * but `onError` is provided. Ignored when a FormBridge is attached
+     * (the bridge uses its own presets).
+     * Defaults to `classValidatorPreset()`.
+     */
+    preset?: ErrorPreset | ErrorPreset[];
+    /**
+     * HTTP status codes that trigger error handling.
+     * Defaults to `[422, 400]`.
+     */
+    statusCodes?: number[];
+    /**
+     * Global callback invoked for every matching error response,
+     * whether or not a FormBridge is attached.
+     * Receives the parsed field errors and the raw HttpErrorResponse.
+     * When a FormBridge is attached, receives ResolvedFieldError[];
+     * otherwise receives ApiFieldError[] from standalone parsing.
+     */
+    onError?: (errors: (ApiFieldError | ResolvedFieldError)[], response: HttpErrorResponse) => void;
+}
+/**
+ * Create an Angular functional HTTP interceptor that handles API validation errors.
+ *
+ * When a response matches one of the configured status codes (default: 422, 400):
+ * - If the request was tagged with `withFormBridge(bridge)`, errors are automatically
+ *   applied to that bridge. Zero code needed in `subscribe()`.
+ * - If an `onError` callback is provided, it is called with the parsed errors for
+ *   global handling (store, toast, logging, etc.).
+ * - The error is always re-thrown so downstream `catchError` or `error` callbacks
+ *   still fire when needed.
+ *
+ * @example
+ * ```typescript
+ * // app.config.ts
+ * import { provideHttpClient, withInterceptors } from '@angular/common/http';
+ * import { apiErrorInterceptor } from 'ngx-api-forms';
+ *
+ * export const appConfig = {
+ *   providers: [
+ *     provideHttpClient(
+ *       withInterceptors([apiErrorInterceptor()])
+ *     ),
+ *   ],
+ * };
+ *
+ * // component.ts -- zero error handling code
+ * this.http.post('/api/save', data, withFormBridge(this.bridge)).subscribe({
+ *   next: () => this.router.navigate(['/done']),
+ * });
+ * ```
+ */
+declare function apiErrorInterceptor(config?: ApiErrorInterceptorConfig): HttpInterceptorFn;
+/**
+ * Attach a FormBridge to an HTTP request via HttpContext.
+ *
+ * When used with `apiErrorInterceptor`, the interceptor automatically calls
+ * `bridge.applyApiErrors()` on 422/400 responses. No error handling needed
+ * in `subscribe()`.
+ *
+ * @param bridge - The FormBridge instance to receive API errors
+ * @returns An options object to spread into HttpClient methods
+ *
+ * @example
+ * ```typescript
+ * // Errors are applied automatically -- no subscribe error handler needed
+ * this.http.post('/api/save', data, withFormBridge(this.bridge)).subscribe();
+ *
+ * // Works with all HttpClient methods
+ * this.http.put('/api/users/1', data, withFormBridge(this.bridge)).subscribe();
+ * ```
+ */
+declare function withFormBridge(bridge: FormBridge): {
+    context: HttpContext;
+};
+
+/**
+ * Standalone utility functions for common form operations.
+ * These are tree-shakeable and don't require DI.
+ */
+
+/**
+ * Parse raw API error body into normalized field errors without touching any form.
+ * Tries each preset in order until one returns results.
+ *
+ * Use this when you only need the parsing logic (e.g. in an HttpInterceptor,
+ * a store effect, or any context where you don't have a FormBridge).
+ *
+ * @param apiError - The raw error body from the API (e.g. `err.error`)
+ * @param preset - One or more presets to try. Defaults to class-validator.
+ * @param options - Optional settings. `debug: true` logs a warning when no preset matches.
+ * @returns Normalized array of field errors
+ *
+ * @example
+ * ```typescript
+ * import { parseApiErrors } from 'ngx-api-forms';
+ * import { laravelPreset } from 'ngx-api-forms/laravel';
+ *
+ * const errors = parseApiErrors(err.error, laravelPreset());
+ * // [{ field: 'email', constraint: 'required', message: 'The email field is required.' }]
+ * ```
+ */
+declare function parseApiErrors(apiError: unknown, preset?: ErrorPreset | ErrorPreset[], options?: {
+    debug?: boolean;
+}): ApiFieldError[];
+/**
+ * Wrap an Observable with form submit lifecycle management.
+ *
+ * Standalone submit helper. Useful when you want disable/enable lifecycle
+ * without a full FormBridge instance.
+ *
+ * - Disables the form before subscribing
+ * - Re-enables the form on success or error
+ * - Returns the original Observable (errors are re-thrown)
+ *
+ * @param form - The FormGroup to manage
+ * @param source - The Observable to wrap (e.g. HttpClient call)
+ * @param options.onError - Callback invoked with the error before re-throwing
+ * @returns The wrapped Observable
+ *
+ * @example
+ * ```typescript
+ * import { wrapSubmit } from 'ngx-api-forms';
+ *
+ * wrapSubmit(this.form, this.http.post('/api', data), {
+ *   onError: (err) => this.bridge.applyApiErrors(err.error),
+ * }).subscribe();
+ * ```
+ */
+declare function wrapSubmit<T>(form: FormGroup, source: Observable<T>, options?: {
+    onError?: (err: unknown) => void;
+}): Observable<T>;
+/**
+ * Convert a plain object to FormData.
+ * Handles Files, Blobs, Arrays, Dates, nested objects.
+ */
+declare function toFormData(data: Record<string, unknown>): FormData;
+/**
+ * Enable all controls in a form, with optional exceptions.
+ */
+declare function enableForm(form: FormGroup, options?: EnableFormOptions): void;
+/**
+ * Disable all controls in a form, with optional exceptions.
+ */
+declare function disableForm(form: FormGroup, options?: DisableFormOptions): void;
+/**
+ * Reset all errors on a form's controls (client-side and API).
+ */
+declare function clearFormErrors(form: FormGroup): void;
+/**
+ * Get a flat record of only the dirty (changed) fields.
+ */
+declare function getDirtyValues(form: FormGroup): Record<string, unknown>;
+/**
+ * Check if any control in the form has a specific error key.
+ */
+declare function hasError(form: FormGroup, errorKey: string): boolean;
+/**
+ * Get the error message for a specific field and error key.
+ * Returns the error value if it's a string, otherwise the error key.
+ */
+declare function getErrorMessage(form: FormGroup, fieldName: string, errorKey?: string): string | null;
+
+export { CLASS_VALIDATOR_CONSTRAINT_MAP, FORM_BRIDGE, FormBridge, GLOBAL_ERROR_FIELD, NgxFormErrorDirective, apiErrorInterceptor, classValidatorPreset, clearFormErrors, createFormBridge, disableForm, enableForm, getDirtyValues, getErrorMessage, hasError, parseApiErrors, provideFormBridge, toFormData, withFormBridge, wrapSubmit };
+export type { ApiErrorInterceptorConfig, ApiFieldError, ClassValidatorError, ConstraintMap, DisableFormOptions, DjangoValidationErrors, EnableFormOptions, ErrorInterceptor, ErrorPreset, FirstError, FormBridgeConfig, FormControlNames, GlobalError, I18nConfig, LaravelValidationErrors, ResolvedFieldError, ZodFlatError };

package/laravel/index.d.ts

@@ -0,0 +1,49 @@
+import { ErrorPreset, ConstraintMap } from 'ngx-api-forms';
+
+/**
+ * Laravel validation error preset.
+ *
+ * Parses the standard Laravel validation error format:
+ * ```json
+ * {
+ *   "message": "The given data was invalid.",
+ *   "errors": {
+ *     "email": ["The email field is required.", "The email must be a valid email address."],
+ *     "name": ["The name must be at least 3 characters."]
+ *   }
+ * }
+ * ```
+ */
+
+/**
+ * Default constraint map for Laravel.
+ */
+declare const LARAVEL_CONSTRAINT_MAP: ConstraintMap;
+/**
+ * Creates a Laravel validation error preset.
+ *
+ * @param options.noInference - When true, skips English-language constraint guessing.
+ *   The raw error message is used directly and the constraint is set to `'serverError'`.
+ *   Use this when your backend returns translated or custom messages.
+ * @param options.constraintPatterns - Custom regex patterns for constraint inference.
+ *   Keys are constraint names, values are RegExp tested against the raw message.
+ *   Checked before the built-in English patterns.
+ *   Example: `{ required: /obligatoire/i, email: /courriel.*invalide/i }`
+ *
+ * @example
+ * ```typescript
+ * import { laravelPreset } from 'ngx-api-forms/laravel';
+ *
+ * // Default: infer constraint from English messages
+ * const bridge = createFormBridge(form, { preset: laravelPreset() });
+ *
+ * // No inference: raw messages, no guessing
+ * const bridge = createFormBridge(form, { preset: laravelPreset({ noInference: true }) });
+ * ```
+ */
+declare function laravelPreset(options?: {
+    noInference?: boolean;
+    constraintPatterns?: Record<string, RegExp>;
+}): ErrorPreset;
+
+export { LARAVEL_CONSTRAINT_MAP, laravelPreset };