mn-angular-lib 0.0.44 → 0.0.46

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mn-angular-lib",
-  "version": "0.0.44",
+  "version": "0.0.46",
   "peerDependencies": {
     "@angular/common": "^21.1.3",
     "@angular/core": "^21.1.3"

package/types/mn-angular-lib.d.ts

@@ -8,7 +8,7 @@ import { Observable, BehaviorSubject } from 'rxjs';
 import * as mn_angular_lib from 'mn-angular-lib';
 import * as _angular_forms from '@angular/forms';
 import { ValidationErrors, NgControl, AbstractControl, FormGroup, FormBuilder } from '@angular/forms';
-import { HttpClient } from '@angular/common/http';
+import { HttpClient, HttpStatusCode, HttpHeaders, HttpErrorResponse, HttpResponse, HttpParams } from '@angular/common/http';
 
 declare const mnAlertVariants: tailwind_variants.TVReturnType<{
     kind: {
@@ -2827,6 +2827,10 @@ declare function provideMnConfig(url: string, debugMode?: boolean): Provider[];
  *   providers: [ provideMnComponentConfig(MY_CFG, 'my-component') ]
  * Then in the component:
  *   readonly cfg = inject(MY_CFG)
+ *
+ * The returned config object is **reactive**: when the active locale changes,
+ * all translatable values are re-resolved in place so that templates using
+ * `cfg.someLabel` automatically reflect the new language on the next change-detection cycle.
  */
 declare function provideMnComponentConfig<T extends object>(token: InjectionToken<T>, componentName: string, initial?: Partial<T>): Provider;
 
@@ -2853,6 +2857,297 @@ declare class MnInstanceDirective {
     static ɵdir: i0.ɵɵDirectiveDeclaration<MnInstanceDirective, "[mn-instance]", never, { "mnInstance": { "alias": "mn-instance"; "required": false; }; }, {}, never, never, true, never>;
 }
 
+/**
+ * A structured representation of an API error.
+ *
+ * Captures all relevant details — status, message, validation errors,
+ * and retry information — so consumers can log, display, or act on
+ * failures without inspecting the raw HTTP response.
+ */
+interface ApiError {
+    status: HttpStatusCode | null;
+    message: string;
+    details?: unknown;
+    backendMessage?: string;
+    validationErrors?: Record<string, string[]>;
+    url?: string | null;
+    headers?: HttpHeaders;
+    original: HttpErrorResponse | Error;
+    retryable: boolean;
+    timestamp: string;
+}
+/**
+ * Metadata associated with an API result.
+ *
+ * Attached to both `SuccessResult` and `FailureResult` to provide
+ * transport-level details such as the HTTP status code, response
+ * headers, and the final URL after any redirects.
+ */
+interface ResultMeta {
+    statusCode?: number;
+    headers?: HttpHeaders;
+    url?: string;
+}
+/**
+ * Represents a successful API result containing the response data.
+ *
+ * Discriminated by `ok: true`. Use `result.ok` to narrow the union
+ * before accessing `data`.
+ *
+ * @template T The type of the response data.
+ */
+interface SuccessResult<T> {
+    ok: true;
+    data: T;
+    meta?: ResultMeta;
+}
+/**
+ * Represents a failed API result containing the structured error.
+ *
+ * Discriminated by `ok: false`. Use `result.ok` to narrow the union
+ * before accessing `error`.
+ */
+interface FailureResult {
+    ok: false;
+    error: ApiError;
+    meta?: ResultMeta;
+}
+/**
+ * A discriminated union representing either a successful or failed API result.
+ *
+ * Discriminated by `ok`. Use `result.ok` to narrow the type
+ * before accessing `data` or `error`.
+ *
+ * @template T The type of the response data on success.
+ */
+type Result<T> = SuccessResult<T> | FailureResult;
+/**
+ * A JavaScript primitive value.
+ *
+ * Used as the building block for query parameter values.
+ */
+type Primitive = string | number | boolean | null | undefined;
+/**
+ * A value that can be used as a query parameter.
+ *
+ * Either a single primitive or an array of primitives.
+ * Array values are appended as multiple entries for the same key.
+ */
+type QueryValue = Primitive | Primitive[];
+/**
+ * A record of query parameter key-value pairs.
+ *
+ * Passed to CRUD service methods and converted to `HttpParams`
+ * before the request is sent. `null` and `undefined` values
+ * are silently skipped during conversion.
+ */
+type QueryParams = Record<string, QueryValue>;
+
+/**
+ * Configuration for a CRUD service endpoint.
+ *
+ * Passed to the `CrudService` constructor to define which API
+ * resource the service operates on.
+ */
+interface CrudConfig {
+    endpoint: string;
+}
+/**
+ * Abstract base class for CRUD services.
+ * Provides standard HTTP operations with typed `Result<T>` responses.
+ *
+ * @template TEntity The entity type returned by single-item operations.
+ * @template TListResponse The response type for list operations (defaults to `TEntity[]`).
+ * @template TCreatePayload The payload type for create operations (defaults to `Partial<TEntity>`).
+ * @template TUpdatePayload The payload type for update operations (defaults to `Partial<TEntity>`).
+ * @template TId The type of the entity identifier (defaults to `number`).
+ * @template TGetByIdResponse The response type for getById (defaults to `TEntity`).
+ * @template TCreateResponse The response type for create (defaults to `TEntity`).
+ * @template TUpdateResponse The response type for update and patch (defaults to `TEntity`).
+ * @template TDeleteResponse The response type for delete (defaults to `void`).
+ */
+declare abstract class CrudService<TEntity, TListResponse = TEntity[], TCreatePayload = Partial<TEntity>, TUpdatePayload = Partial<TEntity>, TId extends string | number = number, TGetByIdResponse = TEntity, TCreateResponse = TEntity, TUpdateResponse = TEntity, TDeleteResponse = void> {
+    protected readonly http: HttpClient;
+    protected readonly baseUrl: string;
+    protected readonly endpoint: string;
+    protected constructor(config: CrudConfig);
+    /**
+     * Retrieves all entities from the configured endpoint.
+     *
+     * Sends a GET request to the base endpoint. Query values are
+     * converted to `HttpParams` before the request is sent.
+     *
+     * @param query Optional query parameters appended to the request URL.
+     * @returns An observable emitting a `Result` with the list response or a structured failure.
+     */
+    getAll(query?: QueryParams): Observable<Result<TListResponse>>;
+    /**
+     * Retrieves a single entity by its identifier.
+     *
+     * Sends a GET request to `{endpoint}/{id}`.
+     *
+     * @param id The unique identifier of the entity to retrieve.
+     * @returns An observable emitting a `Result` with the entity or a structured failure.
+     */
+    getById(id: TId): Observable<Result<TGetByIdResponse>>;
+    /**
+     * Creates a new entity at the configured endpoint.
+     *
+     * Sends a POST request with the provided payload as the request body.
+     *
+     * @param payload The data used to create the entity.
+     * @returns An observable emitting a `Result` with the created entity or a structured failure.
+     */
+    create(payload: TCreatePayload): Observable<Result<TCreateResponse>>;
+    /**
+     * Fully replaces an existing entity.
+     *
+     * Sends a PUT request to `{endpoint}/{id}` with the provided payload,
+     * replacing the entire entity.
+     *
+     * @param id The unique identifier of the entity to update.
+     * @param payload The complete data to replace the existing entity with.
+     * @returns An observable emitting a `Result` with the updated entity or a structured failure.
+     */
+    update(id: TId, payload: TUpdatePayload): Observable<Result<TUpdateResponse>>;
+    /**
+     * Partially updates an existing entity.
+     *
+     * Sends a PATCH request to `{endpoint}/{id}` with the provided payload,
+     * merging changes into the existing entity.
+     *
+     * @param id The unique identifier of the entity to patch.
+     * @param payload A partial set of fields to update on the existing entity.
+     * @returns An observable emitting a `Result` with the updated entity or a structured failure.
+     */
+    patch(id: TId, payload: Partial<TUpdatePayload>): Observable<Result<TUpdateResponse>>;
+    /**
+     * Deletes an entity by its identifier.
+     *
+     * Sends a DELETE request to `{endpoint}/{id}`.
+     *
+     * @param id The unique identifier of the entity to delete.
+     * @returns An observable emitting a `Result` with the delete response or a structured failure.
+     */
+    delete(id: TId): Observable<Result<TDeleteResponse>>;
+    /**
+     * Retrieves all entities with the full `HttpResponse` wrapper.
+     *
+     * Behaves like {@link getAll} but observes the complete HTTP response,
+     * giving access to headers, status code, and URL alongside the body.
+     *
+     * @param query Optional query parameters appended to the request URL.
+     * @returns An observable emitting a `Result` with the full HTTP response or a structured failure.
+     */
+    getAllResponse(query?: QueryParams): Observable<Result<HttpResponse<TListResponse>>>;
+    /**
+     * Builds the URL for a single entity by appending the identifier to the endpoint.
+     *
+     * @param id The unique identifier to append.
+     * @returns The full URL targeting the specific entity.
+     */
+    protected itemUrl(id: TId): string;
+    /**
+     * Wraps a value in a `SuccessResult`.
+     *
+     * @template T The type of the response data.
+     * @param data The response data to wrap.
+     * @param meta Optional metadata (status code, headers, URL) to attach.
+     * @returns A `SuccessResult` containing the provided data.
+     */
+    protected success<T>(data: T, meta?: ResultMeta): SuccessResult<T>;
+    /**
+     * Wraps an error in a `FailureResult`.
+     *
+     * When no explicit metadata is provided, metadata is derived from
+     * the `ApiError` itself (status code, headers, URL).
+     *
+     * @param error The structured API error.
+     * @param meta Optional metadata to override the error-derived values.
+     * @returns A `FailureResult` containing the error and metadata.
+     */
+    protected failure(error: ApiError, meta?: ResultMeta): FailureResult;
+    /**
+     * Maps an unknown error into a structured `ApiError`.
+     *
+     * Handles both `HttpErrorResponse` instances and unexpected error types.
+     * Extracts backend messages, validation errors, and retry information
+     * so callers receive a consistent error shape.
+     *
+     * @param error The raw error caught from the HTTP pipeline.
+     * @returns A fully populated `ApiError` object.
+     */
+    protected mapHttpError(error: unknown): ApiError;
+    /**
+     * Extracts a human-readable message from the error response body.
+     *
+     * Checks common keys (`message`, `title`, `detail`, `error`) on the
+     * body object and returns the first non-empty string found.
+     *
+     * @param body The parsed error response body.
+     * @returns The extracted message, or `undefined` if none was found.
+     */
+    protected extractBackendMessage(body: unknown): string | undefined;
+    /**
+     * Extracts field-level validation errors from the error response body.
+     *
+     * Expects an `errors` property on the body containing a record of
+     * field names to error messages (string or string array).
+     *
+     * @param body The parsed error response body.
+     * @returns A record mapping field names to their error messages, or `undefined` if none were found.
+     */
+    protected extractValidationErrors(body: unknown): Record<string, string[]> | undefined;
+    /**
+     * Returns a default user-facing message for the given HTTP status code.
+     *
+     * Provides human-readable messages for common HTTP status codes.
+     * Override this method to customise messages.
+     *
+     * @param status The HTTP status code, or `null` when unknown.
+     * @returns A descriptive error message.
+     */
+    protected defaultMessage(status: HttpStatusCode | null): string;
+    /**
+     * Determines whether a request with the given status can be retried.
+     *
+     * Timeouts, rate-limiting responses, and server errors
+     * (5xx) are considered retryable by default.
+     *
+     * @param status The HTTP status code, or `null` when unknown.
+     * @returns `true` if the request is safe to retry.
+     */
+    protected isRetryable(status: HttpStatusCode | null): boolean;
+    /**
+     * Normalises a raw HTTP status into an `HttpStatusCode | null` value.
+     *
+     * Converts `undefined`, `NaN`, and `0` (network error) to `null`
+     * so downstream code only needs to handle `HttpStatusCode | null`.
+     *
+     * @param status The raw status value from the HTTP response.
+     * @returns The normalised status code, or `null` when indeterminate.
+     */
+    protected normalizeStatus(status: number | null | undefined): HttpStatusCode | null;
+    /**
+     * Converts query parameters into Angular `HttpParams`.
+     *
+     * `null` and `undefined` values are silently skipped.
+     * Array values are appended as multiple entries for the same key.
+     *
+     * @param query The query parameter record to convert.
+     * @returns An `HttpParams` instance, or `undefined` when no parameters are provided.
+     */
+    protected toHttpParams(query?: QueryParams): HttpParams | undefined;
+}
+
+/**
+ * Injection token for the base URL used by all CRUD service requests.
+ *
+ * Provide this token at the application or module level to configure
+ * the root API URL that `CrudService` prepends to every endpoint.
+ */
+declare const API_BASE_URL: InjectionToken<string>;
+
 /**
  * A marker object used in config values to indicate that the value
  * should be resolved via the MnLanguageService.
@@ -2966,5 +3261,5 @@ declare class MnTranslatePipe implements PipeTransform {
     static ɵpipe: i0.ɵɵPipeDeclaration<MnTranslatePipe, "mnTranslate", true>;
 }
 
-export { ActionStyle, BackdropMode, BaseModalBuilder, CloseMode, ColumnSortType, ConfirmationModalBuilder, ConfirmationTone, CustomModalBuilder, DEFAULT_MN_ALERT_CONFIG, FieldAppearance, FieldKind, FormLayoutMode, FormModalBuilder, KeyboardMode, MN_ALERT_CONFIG, MN_CHECKBOX_CONFIG, MN_DATETIME_CONFIG, MN_INPUT_FIELD_CONFIG, MN_INSTANCE_ID, MN_LIB_DUAL_HORIZONTAL_IMAGE, MN_MULTI_SELECT_CONFIG, MN_SECTION_PATH, MN_TEST_COMPONENT_CONFIG, MN_TEXTAREA_CONFIG, MnAlertOutletComponent, MnAlertService, MnAlertStore, MnButton, MnCheckbox, MnConfigService, MnConfirmationBodyComponent, MnCustomBodyHostComponent, MnDatetime, MnDualHorizontalImage, MnFormBodyComponent, MnInformationCard, MnInputField, MnInstanceDirective, MnLanguageService, MnModalRef, MnModalService, MnModalShellComponent, MnMultiSelect, MnSectionDirective, MnTable, MnTestComponent, MnTextarea, MnTranslatePipe, MnWizardBodyComponent, ModalBuilder, ModalCloseReason, ModalIntent, ModalKind, ModalSize, NavigationDirection, OptionState, SelectionMode, StepBuilder, StepState, SubmitMode, Test, ValidationCode, ValidationStatus, WizardFlowMode, WizardModalBuilder, dateTimeAdapter, defaultTextAdapter, isTranslatable, mnAlertVariants, mnButtonVariants, mnCheckboxVariants, mnDatetimeVariants, mnInformationCardVariants, mnInputFieldVariants, mnMultiSelectVariants, mnTextareaVariants, numberAdapter, pickAdapter, provideMnAlerts, provideMnComponentConfig, provideMnConfig, provideMnLanguage };
-export type { BaseModalConfig, CancellationActionConfig, CheckboxFieldConfig, ColorFieldConfig, ColumnDefinition, ConfirmationActionConfig, ConfirmationModalConfig, CursorPaginationStrategy, CustomFieldConfig, CustomModalConfig, DateFieldConfig, DatetimeFieldConfig, FieldDataSource, FieldValidator, FieldVisibilityCondition, FileFieldConfig, FormFieldConfig, FormFieldGroup, FormModalConfig, FormRow, FormRowField, FormValidator, MnAlert, MnAlertConfig, MnAlertId, MnAlertKind, MnAlertTemplateContext, MnAlertVariants, MnButtonTypes, MnButtonVariants, MnCheckboxErrorMessageData, MnCheckboxErrorMessagesData, MnCheckboxProps, MnCheckboxUIConfig, MnCheckboxVariants, MnConfigFile, MnConfigValue, MnDatetimeErrorMessageData, MnDatetimeErrorMessagesData, MnDatetimeMode, MnDatetimeProps, MnDatetimeUIConfig, MnDatetimeVariants, MnDomAttrs, MnDualHorizontalImageConfig, MnDualHorizontalImageTypes, MnErrorMessageData, MnErrorMessagesData, MnImageType, MnInformationCardBaseData, MnInformationCardData, MnInformationCardVariants, MnInputAdapter, MnInputBaseProps, MnInputDateTimeProps, MnInputFieldProps, MnInputFieldUIConfig, MnInputProps, MnInputType, MnInputVariants, MnLanguageConfig, MnMultiSelectErrorMessageData, MnMultiSelectErrorMessagesData, MnMultiSelectOption, MnMultiSelectProps, MnMultiSelectUIConfig, MnMultiSelectVariants, MnShowInput, MnTextareaErrorMessageData, MnTextareaErrorMessagesData, MnTextareaProps, MnTextareaUIConfig, MnTextareaVariants, MnTranslatable, MnTranslationMap, MnTranslations, ModalCancelHandler, ModalCloseEvent, ModalConfig, ModalFooterAction, ModalI18nLabels, ModalInputMap, ModalPollingConfig, ModalRef, ModalResultHandler, ModalStepId, MultiSelectFieldConfig, MultiSelectTableFieldConfig, NumberFieldConfig, OffsetPaginationStrategy, PaginationStrategy, PasswordFieldConfig, RatingFieldConfig, SelectFieldConfig, SelectOption, SingleSelectTableFieldConfig, SliderFieldConfig, SortState, StepBodyConfig, StepGuard, StepValidator, TableAppearance, TableDataSource, TableRowAction, TextFieldConfig, TextareaFieldConfig, ValidationResult, WizardBeforeCompleteValidator, WizardModalConfig, WizardResult, WizardStepChangeEvent, WizardStepChangeHandler, WizardStepConfig };
+export { API_BASE_URL, ActionStyle, BackdropMode, BaseModalBuilder, CloseMode, ColumnSortType, ConfirmationModalBuilder, ConfirmationTone, CrudService, CustomModalBuilder, DEFAULT_MN_ALERT_CONFIG, FieldAppearance, FieldKind, FormLayoutMode, FormModalBuilder, KeyboardMode, MN_ALERT_CONFIG, MN_CHECKBOX_CONFIG, MN_DATETIME_CONFIG, MN_INPUT_FIELD_CONFIG, MN_INSTANCE_ID, MN_LIB_DUAL_HORIZONTAL_IMAGE, MN_MULTI_SELECT_CONFIG, MN_SECTION_PATH, MN_TEST_COMPONENT_CONFIG, MN_TEXTAREA_CONFIG, MnAlertOutletComponent, MnAlertService, MnAlertStore, MnButton, MnCheckbox, MnConfigService, MnConfirmationBodyComponent, MnCustomBodyHostComponent, MnDatetime, MnDualHorizontalImage, MnFormBodyComponent, MnInformationCard, MnInputField, MnInstanceDirective, MnLanguageService, MnModalRef, MnModalService, MnModalShellComponent, MnMultiSelect, MnSectionDirective, MnTable, MnTestComponent, MnTextarea, MnTranslatePipe, MnWizardBodyComponent, ModalBuilder, ModalCloseReason, ModalIntent, ModalKind, ModalSize, NavigationDirection, OptionState, SelectionMode, StepBuilder, StepState, SubmitMode, Test, ValidationCode, ValidationStatus, WizardFlowMode, WizardModalBuilder, dateTimeAdapter, defaultTextAdapter, isTranslatable, mnAlertVariants, mnButtonVariants, mnCheckboxVariants, mnDatetimeVariants, mnInformationCardVariants, mnInputFieldVariants, mnMultiSelectVariants, mnTextareaVariants, numberAdapter, pickAdapter, provideMnAlerts, provideMnComponentConfig, provideMnConfig, provideMnLanguage };
+export type { ApiError, BaseModalConfig, CancellationActionConfig, CheckboxFieldConfig, ColorFieldConfig, ColumnDefinition, ConfirmationActionConfig, ConfirmationModalConfig, CrudConfig, CursorPaginationStrategy, CustomFieldConfig, CustomModalConfig, DateFieldConfig, DatetimeFieldConfig, FailureResult, FieldDataSource, FieldValidator, FieldVisibilityCondition, FileFieldConfig, FormFieldConfig, FormFieldGroup, FormModalConfig, FormRow, FormRowField, FormValidator, MnAlert, MnAlertConfig, MnAlertId, MnAlertKind, MnAlertTemplateContext, MnAlertVariants, MnButtonTypes, MnButtonVariants, MnCheckboxErrorMessageData, MnCheckboxErrorMessagesData, MnCheckboxProps, MnCheckboxUIConfig, MnCheckboxVariants, MnConfigFile, MnConfigValue, MnDatetimeErrorMessageData, MnDatetimeErrorMessagesData, MnDatetimeMode, MnDatetimeProps, MnDatetimeUIConfig, MnDatetimeVariants, MnDomAttrs, MnDualHorizontalImageConfig, MnDualHorizontalImageTypes, MnErrorMessageData, MnErrorMessagesData, MnImageType, MnInformationCardBaseData, MnInformationCardData, MnInformationCardVariants, MnInputAdapter, MnInputBaseProps, MnInputDateTimeProps, MnInputFieldProps, MnInputFieldUIConfig, MnInputProps, MnInputType, MnInputVariants, MnLanguageConfig, MnMultiSelectErrorMessageData, MnMultiSelectErrorMessagesData, MnMultiSelectOption, MnMultiSelectProps, MnMultiSelectUIConfig, MnMultiSelectVariants, MnShowInput, MnTextareaErrorMessageData, MnTextareaErrorMessagesData, MnTextareaProps, MnTextareaUIConfig, MnTextareaVariants, MnTranslatable, MnTranslationMap, MnTranslations, ModalCancelHandler, ModalCloseEvent, ModalConfig, ModalFooterAction, ModalI18nLabels, ModalInputMap, ModalPollingConfig, ModalRef, ModalResultHandler, ModalStepId, MultiSelectFieldConfig, MultiSelectTableFieldConfig, NumberFieldConfig, OffsetPaginationStrategy, PaginationStrategy, PasswordFieldConfig, Primitive, QueryParams, QueryValue, RatingFieldConfig, Result, ResultMeta, SelectFieldConfig, SelectOption, SingleSelectTableFieldConfig, SliderFieldConfig, SortState, StepBodyConfig, StepGuard, StepValidator, SuccessResult, TableAppearance, TableDataSource, TableRowAction, TextFieldConfig, TextareaFieldConfig, ValidationResult, WizardBeforeCompleteValidator, WizardModalConfig, WizardResult, WizardStepChangeEvent, WizardStepChangeHandler, WizardStepConfig };