@dvirus-js/angular-signals 0.0.1

package/types/dvirus-js-angular-signals.d.ts

@@ -0,0 +1,1560 @@
+import { Signal, WritableSignal, DestroyRef } from '@angular/core';
+import { AbstractControl, FormControlStatus, ValidationErrors, FormArray, FormGroup, FormControl } from '@angular/forms';
+
+/**
+ * Represents a generic object with string keys and values of any type.
+ * Useful as a base type for utility functions and signal helpers.
+ *
+ * @typedef {Record<string, any>} ObjectType
+ */
+type ObjectType = Record<string, any>;
+
+/**
+ * Represents an object where each property is a read-only Signal.
+ * Useful for mapping state objects to their signal equivalents.
+ */
+type SignalObj<T extends ObjectType = ObjectType> = {
+    [Key in keyof T]: Signal<T[Key]>;
+};
+/**
+ * Represents an object where each property is a WritableSignal.
+ * Allows for direct modification of the signal values within the object structure.
+ */
+type SignalObjWritable<T extends ObjectType> = {
+    [Key in keyof T]: WritableSignal<T[Key]>;
+};
+/**
+ * A type representing either a Signal of type T or the raw value of type T.
+ * Useful for inputs that can accept both static values and reactive signals.
+ */
+type SignalOrValue<T> = Signal<T> | T;
+/**
+ * Represents an object where each property can be either a Signal of a certain type
+ * or the raw value of that type.
+ *
+ * @template TValues The type of the values contained within the SignalOrValue properties.
+ *                   Defaults to a union of ObjectType, string, number, or undefined.
+ */
+type SignalOrValueObj<TValues = ObjectType | string | number | boolean | undefined> = TValues extends object ? {
+    [Key in keyof TValues]: SignalOrValue<TValues[Key]>;
+} : Record<string, SignalOrValue<TValues>>;
+/**
+ * Converts a plain object into a writable signal object.
+ * Each property of the source object becomes a WritableSignal initialized with the property's value.
+ *
+ * @param src - The source object to convert.
+ * @returns An object with the same keys as the source, but with values wrapped in WritableSignals.
+ */
+declare function toSignalObj<T extends ObjectType>(src: T): SignalObjWritable<T>;
+/**
+ * Converts a signal object into a plain object.
+ * Each property of the signal object becomes a value from the signal.
+ *
+ * @param src - The signal object to convert.
+ * @returns An object with the same keys as the source, but with values from the signals.
+ */
+declare function fromSignalObj<TData extends ObjectType>(src: SignalOrValueObj<TData>): TData;
+/**
+ * Unwraps a value that might be a Signal.
+ * If the input is a Signal, it returns the signal's value.
+ * If the input is a raw value, it returns the value itself.
+ *
+ * @param value - The signal or value to unwrap.
+ * @returns The raw value of type T.
+ */
+declare function signalOrValue<T>(value: SignalOrValue<T>): T;
+declare function signalOrFunction<T, FnArgs extends any[] = []>(value: SignalOrValue<T> | ((...args: FnArgs) => T), ...fnArgs: FnArgs): T;
+
+/**
+ * Recursively extracts the value type from a form structure.
+ *
+ * Converts form control types to their underlying value types:
+ * - Arrays become arrays of extracted values
+ * - Objects become objects with extracted property values
+ * - Primitives become `T | undefined`
+ *
+ * @template T - The form structure type to extract values from
+ *
+ * @example
+ * ```typescript
+ * type Person = { name: string; age: number };
+ * type PersonValue = SignalFormValueFor<Person>;
+ * // Result: { name: string | undefined; age: number | undefined }
+ * ```
+ */
+type SignalFormValueFor<T> = T extends (infer U)[] ? SignalFormValueFor<U>[] : T extends object ? {
+    [Key in keyof T]: SignalFormValueFor<T[Key]>;
+} : T | undefined;
+/**
+ * Recursively defines the error structure for a form.
+ *
+ * Mirrors the form structure where:
+ * - Arrays become arrays of error structures
+ * - Objects become objects with error properties
+ * - Primitives become error maps (Record<string, string>) or undefined
+ *
+ * @template T - The form structure type to create error structure for
+ *
+ * @example
+ * ```typescript
+ * type Person = { name: string; hobbies: string[] };
+ * type PersonErrors = SignalFormErrorFor<Person>;
+ * // Result: { name: Record<string, string> | undefined; hobbies: (Record<string, string> | undefined)[] }
+ * ```
+ */
+type SignalFormErrorFor<T> = T extends (infer U)[] ? SignalFormErrorFor<U>[] : T extends object ? {
+    [Key in keyof T]: SignalFormErrorFor<T[Key]>;
+} : Record<string, string> | undefined;
+/**
+ * Represents the first error or warning found in a control.
+ *
+ * @template Type - Either 'error' or 'warning' to distinguish validation type
+ *
+ * @property name - The validator name that triggered this error/warning
+ * @property message - The human-readable error/warning message
+ * @property type - Whether this is an 'error' or 'warning'
+ *
+ * @example
+ * ```typescript
+ * const firstError: FirstError<'error'> = {
+ *   name: 'required',
+ *   message: 'This field is required',
+ *   type: 'error'
+ * };
+ * ```
+ */
+type FirstError<Type extends 'warning' | 'error'> = {
+    name: string;
+    message: string;
+    type: Type;
+} | undefined;
+/**
+ * Represents a single form control (primitive value) with validation and state management.
+ *
+ * A control wraps a primitive value (string, number, etc.) and provides:
+ * - Reactive value through Angular signals
+ * - Validation with errors and warnings
+ * - State tracking (touched, dirty, disabled)
+ * - Manual error/warning management
+ *
+ * @template TValue - The type of value this control manages
+ */
+interface SignalFormControl<TValue> {
+    /** Discriminator property set to 'control' for type checking */
+    kind: 'control';
+    /** Writable signal containing the current control value */
+    value: WritableSignal<TValue | undefined>;
+    /** Signal indicating if the control is disabled */
+    disabled: Signal<boolean>;
+    /** Signal indicating if the control has been interacted with */
+    touched: Signal<boolean>;
+    /** Signal indicating if the value has changed from initial */
+    dirty: Signal<boolean>;
+    /** Signal containing all validation errors (from validators + manual) */
+    errors: Signal<Record<string, string>>;
+    /** Signal containing all validation warnings (from warnings + manual) */
+    warnings: Signal<Record<string, string>>;
+    /** Signal containing only manually set errors */
+    selfErrors: Signal<Record<string, string>>;
+    /** Signal containing only manually set warnings */
+    selfWarnings: Signal<Record<string, string>>;
+    /** Signal true when control has errors and is not disabled */
+    invalid: Signal<boolean>;
+    /** Signal true when control has no errors */
+    valid: Signal<boolean>;
+    /** Signal with the first error, if any */
+    firstError: Signal<FirstError<'error'>>;
+    /** Signal with the first warning, if any */
+    firstWarning: Signal<FirstError<'warning'>>;
+    /** Signal with the first error or warning */
+    firstErrorOrWarning: Signal<FirstError<'error' | 'warning'>>;
+    /**
+     * Updates the control value with optional state flags.
+     * @param value - New value to set
+     * @param options - Optional flags for marking dirty/touched
+     */
+    setValue: (value: TValue | undefined, options?: SignalFormSetValueOptions) => void;
+    /**
+     * Resets control to initial value and clears all state.
+     * @param value - Optional new initial value
+     */
+    reset: (value?: TValue | undefined) => void;
+    /** Marks the control as touched */
+    markTouched: () => void;
+    /** Marks the control as not touched */
+    markUntouched: () => void;
+    /** Marks the control as dirty (modified) */
+    markDirty: () => void;
+    /** Marks the control as pristine (unmodified) */
+    markPristine: () => void;
+    /**
+     * Sets the disabled state of the control.
+     * @param disabled - True to disable, false to enable
+     */
+    setDisabled: (disabled: boolean) => void;
+    /**
+     * Adds a manual error with key and message.
+     * @param key - Error identifier key
+     * @param message - Error message
+     */
+    setError: (key: string, message: string) => void;
+    /**
+     * Removes a specific manual error by key.
+     * @param key - Error identifier key to remove
+     */
+    clearError: (key: string) => void;
+    /** Removes all manual errors */
+    clearErrors: () => void;
+    /**
+     * Adds a manual warning with key and message.
+     * @param key - Warning identifier key
+     * @param message - Warning message
+     */
+    setWarning: (key: string, message: string) => void;
+    /**
+     * Removes a specific manual warning by key.
+     * @param key - Warning identifier key to remove
+     */
+    clearWarning: (key: string) => void;
+    /** Removes all manual warnings */
+    clearWarnings: () => void;
+}
+/**
+ * Represents a form array - a collection of form controls/groups with dynamic add/remove capabilities.
+ *
+ * Manages an array of controls where each item can be a control, group, or nested array.
+ * Provides methods for array manipulation (push, insert, remove) and tracks collective state.
+ *
+ * @template TValue - The type of each item in the array
+ */
+interface SignalFormArray<TValue> {
+    /** Discriminator property set to 'array' for type checking */
+    kind: 'array';
+    /** Signal containing the array of child controls */
+    controls: Signal<SignalFormControlLike<TValue>[]>;
+    /** Signal containing array of extracted values from all controls */
+    value: Signal<SignalFormValueFor<TValue>[]>;
+    /** Signal containing array of error structures from all controls */
+    errors: Signal<SignalFormErrorFor<TValue>[]>;
+    /** Signal containing array of warning structures from all controls */
+    warnings: Signal<SignalFormErrorFor<TValue>[]>;
+    /** Signal containing manually set errors on the array itself */
+    selfErrors: Signal<Record<string, string>>;
+    /** Signal containing manually set warnings on the array itself */
+    selfWarnings: Signal<Record<string, string>>;
+    /** Signal indicating if the array is disabled */
+    disabled: Signal<boolean>;
+    /** Signal true when array or any child is touched */
+    touched: Signal<boolean>;
+    /** Signal true when array or any child is dirty */
+    dirty: Signal<boolean>;
+    /** Signal true when array or any child has errors */
+    invalid: Signal<boolean>;
+    /** Signal true when array and all children have no errors */
+    valid: Signal<boolean>;
+    /**
+     * Inserts a control at specified index (defaults to end).
+     * @param item - Item to insert (value, config, or control)
+     * @param index - Position to insert at (optional, defaults to end)
+     * @returns Index where item was inserted
+     */
+    insert: (item: SignalFormInput<TValue, any> | SignalFormValueFor<TValue>, index?: number) => number;
+    /**
+     * Appends a control to the end of the array.
+     * @param item - Item to append (value, config, or control)
+     * @returns Index where item was inserted
+     */
+    push: (item: SignalFormInput<TValue, any> | SignalFormValueFor<TValue>) => number;
+    /**
+     * Removes the control at specified index.
+     * @param index - Index of control to remove
+     */
+    removeAt: (index: number) => void;
+    /** Removes all controls from the array */
+    clear: () => void;
+    /**
+     * Retrieves the control at specified index.
+     * @param index - Index of control to retrieve
+     * @returns Control at index, or undefined if out of bounds
+     */
+    at: (index: number) => SignalFormControlLike<TValue> | undefined;
+    /**
+     * Sets values for all controls (recreates if length differs).
+     * @param value - Array of new values
+     * @param options - Optional flags for marking dirty/touched
+     */
+    setValue: (value: SignalFormValueFor<TValue>[], options?: SignalFormSetValueOptions) => void;
+    /**
+     * Resets all controls to initial state or provided values.
+     * @param value - Optional new initial values
+     */
+    reset: (value?: SignalFormValueFor<TValue>[]) => void;
+    /** Marks the array itself as touched */
+    markTouched: () => void;
+    /** Marks the array itself as untouched */
+    markUntouched: () => void;
+    /** Marks the array itself as dirty */
+    markDirty: () => void;
+    /** Marks the array itself as pristine */
+    markPristine: () => void;
+    /** Marks the array and all children as touched */
+    markAllTouched: () => void;
+    /**
+     * Sets disabled state for array and optionally children.
+     * @param disabled - True to disable, false to enable
+     * @param options - Options to control if children are affected
+     */
+    setDisabled: (disabled: boolean, options?: SignalFormDisableOptions) => void;
+    /**
+     * Adds a manual error to the array.
+     * @param key - Error identifier key
+     * @param message - Error message
+     */
+    setError: (key: string, message: string) => void;
+    /**
+     * Removes a specific manual error.
+     * @param key - Error identifier key to remove
+     */
+    clearError: (key: string) => void;
+    /** Removes all manual errors */
+    clearErrors: () => void;
+    /**
+     * Adds a manual warning to the array.
+     * @param key - Warning identifier key
+     * @param message - Warning message
+     */
+    setWarning: (key: string, message: string) => void;
+    /**
+     * Removes a specific manual warning.
+     * @param key - Warning identifier key to remove
+     */
+    clearWarning: (key: string) => void;
+    /** Removes all manual warnings */
+    clearWarnings: () => void;
+}
+/**
+ * Represents a form group - a structured collection of named form controls.
+ *
+ * Manages an object/record of controls where each property is a control, group, or array.
+ * Provides type-safe access to controls and tracks collective validation state.
+ *
+ * @template TData - The object type defining the structure and types of all controls
+ */
+interface SignalForm<TData extends object> {
+    /** Discriminator property set to 'group' for type checking */
+    kind: 'group';
+    /** Object containing all named child controls */
+    controls: {
+        [Key in keyof TData]: SignalFormControlLike<TData[Key]>;
+    };
+    /** Signal containing object with extracted values from all controls */
+    value: Signal<{
+        [Key in keyof TData]: SignalFormValueFor<TData[Key]>;
+    }>;
+    /** Signal containing object with error structures from all controls */
+    errors: Signal<{
+        [Key in keyof TData]: SignalFormErrorFor<TData[Key]>;
+    }>;
+    /** Signal containing object with warning structures from all controls */
+    warnings: Signal<{
+        [Key in keyof TData]: SignalFormErrorFor<TData[Key]>;
+    }>;
+    /** Signal containing manually set errors on the group itself */
+    selfErrors: Signal<Record<string, string>>;
+    /** Signal containing manually set warnings on the group itself */
+    selfWarnings: Signal<Record<string, string>>;
+    /** Signal indicating if the group is disabled */
+    disabled: Signal<boolean>;
+    /** Signal true when group or any child is touched */
+    touched: Signal<boolean>;
+    /** Signal true when group or any child is dirty */
+    dirty: Signal<boolean>;
+    /** Signal true when group or any child has errors */
+    invalid: Signal<boolean>;
+    /** Signal true when group and all children have no errors */
+    valid: Signal<boolean>;
+    /**
+     * Type-safe method to retrieve a specific control by key.
+     * @param key - Control property name
+     * @returns The control for the specified key
+     */
+    getControl: <Key extends keyof TData>(key: Key) => SignalFormControlLike<TData[Key]>;
+    /**
+     * Updates values for specified controls (partial updates supported).
+     * @param value - Partial object with new values
+     * @param options - Optional flags for marking dirty/touched
+     */
+    setValue: (value: Partial<{
+        [Key in keyof TData]: SignalFormValueFor<TData[Key]>;
+    }>, options?: SignalFormSetValueOptions) => void;
+    /**
+     * Resets all controls to initial state or provided values.
+     * @param value - Optional partial object with new initial values
+     */
+    reset: (value?: Partial<{
+        [Key in keyof TData]: SignalFormValueFor<TData[Key]>;
+    }>) => void;
+    /** Marks the group itself as touched */
+    markTouched: () => void;
+    /** Marks the group itself as untouched */
+    markUntouched: () => void;
+    /** Marks the group itself as dirty */
+    markDirty: () => void;
+    /** Marks the group itself as pristine */
+    markPristine: () => void;
+    /** Marks the group and all children as touched */
+    markAllTouched: () => void;
+    /**
+     * Sets disabled state for group and optionally children.
+     * @param disabled - True to disable, false to enable
+     * @param options - Options to control if children are affected
+     */
+    setDisabled: (disabled: boolean, options?: SignalFormDisableOptions) => void;
+    /**
+     * Adds a manual error to the group.
+     * @param key - Error identifier key
+     * @param message - Error message
+     */
+    setError: (key: string, message: string) => void;
+    /**
+     * Removes a specific manual error.
+     * @param key - Error identifier key to remove
+     */
+    clearError: (key: string) => void;
+    /** Removes all manual errors */
+    clearErrors: () => void;
+    /**
+     * Adds a manual warning to the group.
+     * @param key - Warning identifier key
+     * @param message - Warning message
+     */
+    setWarning: (key: string, message: string) => void;
+    /**
+     * Removes a specific manual warning.
+     * @param key - Warning identifier key to remove
+     */
+    clearWarning: (key: string) => void;
+    /** Removes all manual warnings */
+    clearWarnings: () => void;
+}
+/**
+ * Type utility that maps a value type to its appropriate control interface.
+ *
+ * Automatically determines the correct control type based on the value:
+ * - Arrays → SignalFormArray
+ * - Objects → SignalForm (group)
+ * - Primitives → SignalFormControl
+ *
+ * @template TValue - The value type to map to a control interface
+ *
+ * @example
+ * ```typescript
+ * type StringControl = SignalFormControlLike<string>; // SignalFormControl<string>
+ * type PersonControl = SignalFormControlLike<Person>; // SignalForm<Person>
+ * type HobbiesControl = SignalFormControlLike<string[]>; // SignalFormArray<string>
+ * ```
+ */
+type SignalFormControlLike<TValue> = TValue extends (infer U)[] ? SignalFormArray<U> : TValue extends object ? SignalForm<TValue> : SignalFormControl<TValue>;
+/**
+ * Context object passed to validators and disabled functions.
+ *
+ * Provides access to the current control's value and sibling controls,
+ * enabling cross-field validation and dynamic behavior based on other form values.
+ *
+ * @template TControls - Object type defining all available sibling controls
+ * @template TValue - The type of the current control's value
+ *
+ * @example
+ * ```typescript
+ * const validator: SignalFormValidatorFn<FormModel, string> = (ctx) => {
+ *   const otherControl = ctx.getControl('otherField');
+ *   return ctx.item.value === otherControl.value() ? null : { mismatch: 'Values must match' };
+ * };
+ * ```
+ */
+interface SignalFormContext<TControls extends object, TValue> {
+    /** Object containing the current control's value */
+    item: {
+        value: TValue | undefined;
+    };
+    /**
+     * Function to retrieve sibling controls by key for cross-field logic.
+     * @param controlName - Key of the sibling control to retrieve
+     * @returns The sibling control
+     */
+    getControl: <ControlKey extends keyof TControls>(controlName: ControlKey) => SignalFormControlLike<TControls[ControlKey]>;
+}
+/**
+ * Return type for validation functions.
+ *
+ * Validators return a map of error keys to messages when validation fails,
+ * or null/empty when validation passes. Empty strings and null values are ignored.
+ *
+ * @example
+ * ```typescript
+ * const result: SignalFormValidationError = { required: 'Field is required', min: 'Too small' };
+ * const success: SignalFormValidationError = null;
+ * ```
+ */
+type SignalFormValidationError = Record<string, string | undefined | null> | null;
+/**
+ * Function signature for validators and warnings.
+ *
+ * Takes a context with the current value and sibling controls,
+ * returns error/warning messages or null when validation passes.
+ *
+ * @template TControls - Object type defining available sibling controls
+ * @template TValue - The type of value being validated
+ *
+ * @param ctx - Validation context with current value and control accessor
+ * @returns Error map when validation fails, null when it passes
+ *
+ * @example
+ * ```typescript
+ * const minValidator: SignalFormValidatorFn<any, number> = ({ item }) => {
+ *   return item.value && item.value < 0 ? { min: 'Must be positive' } : null;
+ * };
+ * ```
+ */
+type SignalFormValidatorFn<TControls extends object, TValue> = (ctx: SignalFormContext<TControls, TValue>) => SignalFormValidationError;
+/**
+ * Configuration object for creating a form control with advanced options.
+ *
+ * Allows specifying initial value, validators, warnings, and dynamic disabled logic.
+ *
+ * @template TValue - The type of value the control will manage
+ * @template TControls - Object type defining available sibling controls for validators
+ *
+ * @example
+ * ```typescript
+ * const config: SignalFormControlConfig<number, FormModel> = {
+ *   value: 0,
+ *   validators: [signalFormValidators.min(0)],
+ *   warnings: [signalFormValidators.max(100)],
+ *   disabled: (ctx) => ctx.getControl('otherField').value() === 'locked'
+ * };
+ * ```
+ */
+interface SignalFormControlConfig<TValue, TControls extends object> {
+    /** Initial value (can be a signal or static value) */
+    value: SignalOrValue<TValue | undefined>;
+    /** Disabled state (boolean, signal, or function based on form context) */
+    disabled?: SignalOrValue<boolean> | SignalFormDisabledFn<TControls, TValue>;
+    /** Array of validation functions that mark control as invalid */
+    validators?: SignalFormValidatorFn<TControls, TValue>[];
+    /** Array of validation functions that don't affect validity */
+    warnings?: SignalFormValidatorFn<TControls, TValue>[];
+}
+/**
+ * Input type accepted when creating a form control.
+ *
+ * Flexible input that accepts:
+ * - A raw value (primitive, signal)
+ * - A configuration object with validators and options
+ * - An existing SignalFormControl instance
+ *
+ * @template TValue - The value type for the control
+ * @template TControls - Object type defining available sibling controls
+ */
+type SignalFormControlInput<TValue, TControls extends object> = SignalOrValue<TValue | undefined> | SignalFormControlConfig<TValue, TControls> | SignalFormControl<TValue>;
+/**
+ * Input type accepted when creating a form group.
+ *
+ * @template TData - Object type defining the structure of the group
+ */
+type SignalFormGroupInput<TData extends object> = SignalFormInputs<TData> | SignalForm<TData>;
+/**
+ * Input type accepted when creating a form array.
+ *
+ * @template TItem - The type of each item in the array
+ * @template TControls - Object type defining available sibling controls
+ */
+type SignalFormArrayInput<TItem, TControls extends object> = SignalFormArray<TItem> | SignalFormInput<TItem, TControls>[];
+/**
+ * Recursive input type that automatically maps to the correct control input type.
+ *
+ * Determines the appropriate input type based on value structure:
+ * - Arrays → SignalFormArrayInput
+ * - Objects → SignalFormGroupInput
+ * - Primitives → SignalFormControlInput
+ *
+ * @template TValue - The value type to create an input for
+ * @template TControls - Object type defining available sibling controls
+ */
+type SignalFormInput<TValue, TControls extends object> = TValue extends (infer U)[] ? SignalFormArrayInput<U, TControls> : TValue extends object ? SignalFormGroupInput<TValue> : SignalFormControlInput<TValue, TControls>;
+/**
+ * Type for defining the inputs of a form group.
+ *
+ * Maps each property of TData to its appropriate input type,
+ * all properties are optional to allow partial form definitions.
+ *
+ * @template TData - Object type defining the structure of the form
+ */
+type SignalFormInputs<TData extends object> = {
+    [Key in keyof TData]?: SignalFormInput<TData[Key], TData>;
+};
+/**
+ * Function signature for dynamic disabled logic.
+ *
+ * Determines if a control should be disabled based on form context.
+ *
+ * @template TControls - Object type defining available sibling controls
+ * @template TValue - The type of value in the control
+ *
+ * @param ctx - Context with current value and sibling controls
+ * @returns Boolean indicating if control should be disabled
+ */
+type SignalFormDisabledFn<TControls extends object, TValue> = (ctx: SignalFormContext<TControls, TValue>) => boolean;
+/**
+ * Options for setValue operations.
+ */
+interface SignalFormSetValueOptions {
+    /** Whether to mark the control as dirty (default: true) */
+    markDirty?: boolean;
+    /** Whether to mark the control as touched (default: false) */
+    markTouched?: boolean;
+}
+/**
+ * Options for setDisabled operations.
+ */
+interface SignalFormDisableOptions {
+    /** If true, only disable this control without affecting children (default: false) */
+    onlySelf?: boolean;
+}
+
+/**
+ * Internal type for accessing sibling controls in a form.
+ *
+ * @internal
+ */
+type ControlAccessor$1<TControls extends object> = <Key extends keyof TControls>(controlName: Key) => SignalFormControlLike<TControls[Key]>;
+/**
+ * Type guard to check if an object is a SignalFormArray.
+ *
+ * @template TValue - The type of items in the array
+ * @param obj - Object to check
+ * @returns True if obj is a SignalFormArray
+ *
+ * @example
+ * ```typescript
+ * if (isSignalFormArray(value)) {
+ *   console.log(value.controls().length); // TypeScript knows this is an array
+ * }
+ * ```
+ */
+declare function isSignalFormArray<TValue>(obj: unknown): obj is SignalFormArray<TValue>;
+/**
+ * Creates a reactive form array for managing dynamic collections of controls.
+ *
+ * Builds an array container that can hold multiple controls (primitives, groups, or nested arrays)
+ * with full signal-based reactivity. Provides methods for dynamic addition/removal of items
+ * and tracks collective validation state.
+ *
+ * Features:
+ * - Dynamic array operations (push, insert, remove, clear)
+ * - Reactive value and error tracking across all items
+ * - Collective state management (touched, dirty, valid)
+ * - Manual error/warning management at array level
+ * - Type-safe access to individual controls
+ *
+ * @template TItem - The type of each item in the array
+ * @template TControls - Object type defining available sibling controls
+ *
+ * @param inputItems - Array of initial items (values, configs, or controls)
+ * @param getControl - Optional accessor for sibling controls
+ * @returns Fully configured SignalFormArray instance
+ *
+ * @example
+ * ```typescript
+ * // Array of primitives
+ * const tagsArray = createSignalFormArray(['tag1', 'tag2']);
+ * tagsArray.push('tag3');
+ *
+ * // Array of objects
+ * const addressesArray = createSignalFormArray<Address>([
+ *   { street: '123 Main', city: 'NYC' },
+ *   { street: '456 Oak', city: 'LA' }
+ * ]);
+ *
+ * // Array with validators
+ * const hobbiesArray = createSignalFormArray([
+ *   { value: 'coding', validators: [signalFormValidators.minLength(3)] },
+ *   'gaming'
+ * ]);
+ * ```
+ */
+declare function createSignalFormArray<TItem, TControls extends object = object>(inputItems: SignalFormInput<TItem, TControls>[], getControl?: ControlAccessor$1<TControls>): SignalFormArray<TItem>;
+
+/**
+ * Internal type for accessing sibling controls in a form.
+ *
+ * @internal
+ */
+type ControlAccessor<TControls extends object> = <Key extends keyof TControls>(controlName: Key) => SignalFormControlLike<TControls[Key]>;
+/**
+ * Type guard to check if an object is a SignalFormControl.
+ *
+ * @template TValue - The type of value the control manages
+ * @param obj - Object to check
+ * @returns True if obj is a SignalFormControl
+ *
+ * @example
+ * ```typescript
+ * if (isSignalFormControl(value)) {
+ *   console.log(value.value()); // TypeScript knows this is a control
+ * }
+ * ```
+ */
+declare function isSignalFormControl<TValue>(obj: unknown): obj is SignalFormControl<TValue>;
+/**
+ * Creates a reactive form control with signal-based state management.
+ *
+ * Builds a control that wraps a primitive value (string, number, boolean, etc.)
+ * with validation, state tracking, and reactive updates using Angular signals.
+ *
+ * Features:
+ * - Reactive value updates through signals
+ * - Validators for errors (mark control as invalid)
+ * - Warnings (validation messages without invalidating)
+ * - Dynamic disabled state based on form context
+ * - State tracking (touched, dirty)
+ * - Manual error/warning management
+ *
+ * @template TControls - Object type defining available sibling controls for cross-field validation
+ * @template TValue - The type of value this control manages
+ *
+ * @param input - Control input (raw value, config object, or existing control)
+ * @param getControl - Optional accessor function for sibling controls
+ * @returns Fully configured SignalFormControl instance
+ *
+ * @example
+ * ```typescript
+ * // Simple control
+ * const nameControl = createSignalFormControl('John');
+ *
+ * // With validators
+ * const ageControl = createSignalFormControl({
+ *   value: 25,
+ *   validators: [signalFormValidators.required, signalFormValidators.min(0)],
+ *   warnings: [signalFormValidators.max(120)]
+ * });
+ *
+ * // With dynamic disabled
+ * const emailControl = createSignalFormControl({
+ *   value: '',
+ *   disabled: (ctx) => ctx.getControl('accountType').value() === 'guest'
+ * });
+ * ```
+ */
+declare function createSignalFormControl<TControls extends object, TValue>(input: SignalFormControlInput<TValue, TControls>, getControl?: ControlAccessor<TControls>): SignalFormControl<TValue>;
+
+/**
+ * Type guard to check if an object is a SignalForm (form group).
+ *
+ * @template TData - Object type defining the form structure
+ * @param obj - Object to check
+ * @returns True if obj is a SignalForm
+ *
+ * @example
+ * ```typescript
+ * if (isSignalFormGroup(value)) {
+ *   console.log(value.controls.name); // TypeScript knows this is a form group
+ * }
+ * ```
+ */
+declare function isSignalFormGroup<TData extends object>(obj: unknown): obj is SignalForm<TData>;
+/**
+ * Creates a reactive form group for managing structured form data.
+ *
+ * Builds a typed form container that holds multiple named controls, groups, or arrays.
+ * Each property in the input object becomes a control with full signal-based reactivity.
+ * Provides type-safe access to controls and tracks collective validation state.
+ *
+ * Features:
+ * - Type-safe control access via `.controls` property
+ * - Reactive value and error tracking across all controls
+ * - Collective state management (touched, dirty, valid)
+ * - Manual error/warning management at group level
+ * - Support for nested groups and arrays
+ * - Cross-field validation via getControl accessor
+ *
+ * @template TData - Object type defining the structure and types of all controls
+ *
+ * @param inputs - Object mapping property names to their control inputs
+ * @returns Fully configured SignalForm instance
+ *
+ * @example
+ * ```typescript
+ * // Simple form
+ * const form = createSignalFormGroup({
+ *   name: 'John',
+ *   age: 25
+ * });
+ *
+ * // With validators and nested structure
+ * const form = createSignalFormGroup<User>({
+ *   email: {
+ *     value: '',
+ *     validators: [signalFormValidators.required, signalFormValidators.email]
+ *   },
+ *   age: {
+ *     value: 25,
+ *     validators: [signalFormValidators.min(0)],
+ *     warnings: [signalFormValidators.max(120)]
+ *   },
+ *   address: {
+ *     street: '123 Main St',
+ *     city: 'NYC'
+ *   },
+ *   hobbies: ['coding', 'gaming']
+ * });
+ *
+ * // Access controls
+ * form.controls.email.value(); // Type-safe access
+ * form.getControl('age').setValue(30);
+ * ```
+ */
+declare function createSignalFormGroup<TData extends object>(inputs: SignalFormInputs<TData>): SignalForm<TData>;
+/**
+ * Helper function to create a standalone form control.
+ *
+ * Creates a control without sibling control access. Useful for creating
+ * individual controls outside of a form group context.
+ *
+ * @template TValue - The type of value the control manages
+ * @param input - Control input (raw value, config object, or existing control)
+ * @returns SignalFormControl instance
+ *
+ * @example
+ * ```typescript
+ * const nameControl = formControl('John');
+ * const ageControl = formControl({
+ *   value: 25,
+ *   validators: [signalFormValidators.min(0)]
+ * });
+ * ```
+ */
+declare function formControl<TValue>(input: SignalFormControlInput<TValue, object>): SignalFormControl<TValue>;
+/**
+ * Helper function to create a standalone form array.
+ *
+ * Creates an array without sibling control access. Useful for creating
+ * array controls outside of a form group context.
+ *
+ * @template TValue - The type of each item in the array
+ * @param input - Array of initial items
+ * @returns SignalFormArray instance
+ *
+ * @example
+ * ```typescript
+ * const tagsArray = formArray(['tag1', 'tag2', 'tag3']);
+ * const addressesArray = formArray<Address>([
+ *   { street: '123 Main', city: 'NYC' }
+ * ]);
+ * ```
+ */
+declare function formArray<TValue>(input: SignalFormInput<TValue, object>[]): SignalFormArray<TValue>;
+/**
+ * Helper function to create a form group.
+ *
+ * Alias for createSignalFormGroup. Creates a typed form with multiple controls.
+ *
+ * @template TData - Object type defining the form structure
+ * @param input - Object mapping property names to control inputs
+ * @returns SignalForm instance
+ *
+ * @example
+ * ```typescript
+ * const form = formGroup({
+ *   name: 'John',
+ *   email: {
+ *     value: 'john@example.com',
+ *     validators: [signalFormValidators.email]
+ *   }
+ * });
+ * ```
+ */
+declare function formGroup<TData extends object>(input: SignalFormInputs<TData>): SignalForm<TData>;
+/**
+ * Primary API for creating signal-based reactive forms.
+ *
+ * Alias for `formGroup`. This is the main entry point for creating forms.
+ * Provides type-safe, signal-based form state management with built-in validation.
+ *
+ * @example
+ * ```typescript
+ * // Basic form
+ * const form = signalForm({ name: 'John', age: 25 });
+ *
+ * // Complex form with validation
+ * const form = signalForm<Person>({
+ *   name: {
+ *     value: '',
+ *     validators: [signalFormValidators.required, signalFormValidators.minLength(2)]
+ *   },
+ *   age: {
+ *     value: 30,
+ *     validators: [signalFormValidators.min(0)],
+ *     warnings: [signalFormValidators.max(120)],
+ *     disabled: (ctx) => ctx.getControl('name').value() === 'admin'
+ *   },
+ *   address: {
+ *     street: '123 Main St',
+ *     city: 'NYC'
+ *   },
+ *   hobbies: ['coding', 'gaming']
+ * });
+ *
+ * // Access form state
+ * console.log(form.value()); // { name: '', age: 30, address: {...}, hobbies: [...] }
+ * console.log(form.valid()); // boolean
+ * console.log(form.controls.name.errors()); // { required: 'This field is required' }
+ * ```
+ */
+declare const signalForm: typeof formGroup;
+
+type ValidatorFn = SignalFormValidatorFn<any, any>;
+/**
+ * Validator that enforces a maximum string or number length.
+ *
+ * Converts the value to string and checks if its length exceeds the specified maximum.
+ * Works with both string and number types.
+ *
+ * @param num - Maximum allowed length (inclusive)
+ * @returns Validator function
+ *
+ * @example
+ * ```typescript
+ * const control = signalForm({
+ *   username: { value: 'verylongusername', validators: [signalFormValidators.maxLength(10)] }
+ * });
+ * // control.controls.username.errors() => { maxLength: 'To long' }
+ * ```
+ */
+declare function maxLength(num: number): ValidatorFn;
+/**
+ * Validator that enforces a minimum string or number length.
+ *
+ * Converts the value to string and checks if its length is less than or equal to the specified minimum.
+ * Works with both string and number types.
+ *
+ * @param num - Minimum required length (inclusive)
+ * @returns Validator function
+ *
+ * @example
+ * ```typescript
+ * const control = signalForm({
+ *   code: { value: 'ab', validators: [signalFormValidators.minLength(3)] }
+ * });
+ * // control.controls.code.errors() => { minLength: 'To short' }
+ * ```
+ */
+declare function minLength(num: number): ValidatorFn;
+/**
+ * Validator that enforces a minimum numeric value.
+ *
+ * Checks if a numeric value is less than or equal to the specified minimum.
+ * Value is coerced to a number for comparison.
+ *
+ * @param num - Minimum allowed value (exclusive - value must be greater than this)
+ * @returns Validator function
+ *
+ * @example
+ * ```typescript
+ * const control = signalForm({
+ *   age: { value: -5, validators: [signalFormValidators.min(0)] }
+ * });
+ * // control.controls.age.errors() => { minLength: 'To small' }
+ * ```
+ */
+declare function min(num: number): ValidatorFn;
+/**
+ * Validator that enforces a maximum numeric value.
+ *
+ * Checks if a numeric value exceeds the specified maximum.
+ * Value is coerced to a number for comparison.
+ *
+ * @param num - Maximum allowed value (inclusive)
+ * @returns Validator function
+ *
+ * @example
+ * ```typescript
+ * const control = signalForm({
+ *   age: { value: 150, validators: [signalFormValidators.max(120)] }
+ * });
+ * // control.controls.age.errors() => { minLength: 'To big' }
+ * ```
+ */
+declare function max(num: number): ValidatorFn;
+/**
+ * Validator that checks if a value matches a specified regular expression pattern.
+ *
+ * Accepts either a RegExp object or a string pattern. String patterns are automatically
+ * wrapped with ^ and $ anchors to match the entire value.
+ *
+ * Skips validation for empty values (use with `required` if needed).
+ *
+ * @param valuePattern - Regular expression or pattern string to match against
+ * @returns Validator function
+ *
+ * @example
+ * ```typescript
+ * // Using regex
+ * const control1 = signalForm({
+ *   code: { value: 'abc', validators: [signalFormValidators.pattern(/^[0-9]+$/)] }
+ * });
+ * // control1.controls.code.errors() => { pattern: 'RequiredPattern: ^[0-9]+$, ActualValue: abc' }
+ *
+ * // Using string pattern
+ * const control2 = signalForm({
+ *   zipCode: { value: 'ABC', validators: [signalFormValidators.pattern('[0-9]{5}')] }
+ * });
+ * ```
+ */
+declare function pattern(valuePattern: string | RegExp): ValidatorFn;
+/**
+ * Collection of built-in validators for signal-form controls.
+ *
+ * Provides common validation functions that can be used in the `validators` or `warnings`
+ * arrays of form controls. All validators skip empty values except `required`.
+ *
+ * @property required - Ensures the value is not empty (null, undefined, '', [], 0, empty Set)
+ * @property maxLength - Ensures string/number length doesn't exceed maximum
+ * @property minLength - Ensures string/number length meets minimum requirement
+ * @property min - Ensures numeric value is greater than minimum (exclusive)
+ * @property max - Ensures numeric value doesn't exceed maximum (inclusive)
+ * @property email - Validates email address format using Angular-compatible regex
+ * @property pattern - Validates value matches a regular expression pattern
+ *
+ * @example
+ * ```typescript
+ * const form = signalForm({
+ *   email: {
+ *     value: '',
+ *     validators: [signalFormValidators.required, signalFormValidators.email]
+ *   },
+ *   age: {
+ *     value: 25,
+ *     validators: [signalFormValidators.min(0), signalFormValidators.max(120)],
+ *     warnings: [signalFormValidators.max(100)] // Warning but doesn't invalidate
+ *   },
+ *   username: {
+ *     value: '',
+ *     validators: [
+ *       signalFormValidators.required,
+ *       signalFormValidators.minLength(3),
+ *       signalFormValidators.maxLength(20),
+ *       signalFormValidators.pattern(/^[a-zA-Z0-9_]+$/)
+ *     ]
+ *   }
+ * });
+ * ```
+ */
+declare const signalFormValidators: {
+    required: ValidatorFn;
+    maxLength: typeof maxLength;
+    minLength: typeof minLength;
+    min: typeof min;
+    max: typeof max;
+    email: ValidatorFn;
+    pattern: typeof pattern;
+};
+
+/**
+ * A function interface for a signal-based notification mechanism.
+ * Calling the function returns the current notification count.
+ * Calling `notify()` increments the count, triggering any listeners.
+ */
+interface SignalNotifier {
+    (): number;
+    /**
+     * Triggers a notification by incrementing the internal signal value.
+     */
+    notify: () => void;
+}
+/**
+ * Creates a signal-based notifier function.
+ *
+ * Each call to the returned function returns the current notification count.
+ * Calling `notify()` increments the count, triggering any listeners.
+ *
+ * @returns {SignalNotifier} A notifier function with a `notify` method.
+ *
+ * @example
+ * const notifier = signalNotifier();
+ * effect(() => {
+ *   notifier(); // Reacts to notifications
+ * });
+ * notifier.notify(); // Triggers the effect
+ */
+declare function signalNotifier(): SignalNotifier;
+
+/**
+ * A writable signal enhanced with debounce capabilities.
+ *
+ * Extends `WritableSignal<T>` so it can be read and written like a normal signal,
+ * but also exposes a `setDebounced` method that applies values after a configurable delay
+ * and an `isLoading` signal that indicates whether a debounced update is pending.
+ *
+ * @typeParam T - The type of the signal's value.
+ */
+interface SignalDebounce<T> extends WritableSignal<T> {
+    /** Sets the signal value after the configured debounce delay. */
+    setDebounced(value: T): void;
+    /** Reactive flag that is `true` while a debounced update is pending. */
+    isLoading: Signal<boolean>;
+}
+/**
+ * Creates a debounced writable signal.
+ *
+ * The returned signal can be written to instantly via its `WritableSignal` interface
+ * **or** through `setDebounced(value)` which delays the commit by `debounceTime` ms.
+ * While a debounced write is pending, `isLoading()` returns `true`.
+ *
+ * If a reactive `params` function is supplied, the signal will also track that
+ * source and debounce upstream changes (requires an injection context).
+ *
+ * @typeParam T - The type of the signal's value.
+ * @param options - Configuration object.
+ * @param options.params - Optional reactive source function whose return value
+ *   is tracked and debounced into the signal.
+ * @param options.debounceTime - Delay in milliseconds before a debounced value
+ *   is committed.
+ * @param options.initialValue - Optional initial value for the signal.
+ * @param options.injector - Optional Angular `Injector` to use for setting up
+ *   reactive tracking. Required if `params` is provided and this function is called
+ *   outside of an injection context.
+ * @returns A `SignalDebounce<T>` instance.
+ *
+ * @example
+ * ```ts
+ * // Simple debounced signal with an initial value
+ * const search = signalDebounce<string>({ debounceTime: 300, initialValue: '' });
+ * search.setDebounced('hello'); // commits after 300 ms
+ *
+ * // Tracking a reactive source
+ * const query = signal('angular');
+ * const debounced = signalDebounce({ params: () => query(), debounceTime: 500 });
+ * ```
+ */
+declare function signalDebounce<T>(options: {
+    params?: () => T;
+    debounceTime: number;
+    initialValue?: T;
+    injector?: unknown;
+}): SignalDebounce<T>;
+
+/**
+ * A reactive wrapper around a `Set` backed by Angular signals.
+ * All mutations produce a new `Set` instance, ensuring signal-based change detection works correctly.
+ *
+ * @template T The type of elements stored in the set. Defaults to `number`.
+ */
+interface SignalSet<T = number> {
+    /** The current underlying `Set` (read via signal). */
+    (): Set<T>;
+    /** The number of elements in the set (reactive). */
+    size: Signal<number>;
+    /** A computed signal that returns the set contents as an array. */
+    toArray: Signal<T[]>;
+    /** Adds the element if absent, removes it if present. */
+    toggle: (id: T) => void;
+    /** Returns `true` if the element exists in the set. */
+    has: (id: T) => boolean;
+    /** Adds an element to the set. */
+    add: (id: T) => void;
+    /** Removes an element from the set. */
+    delete: (id: T) => void;
+    /** Removes all elements from the set. */
+    clear: () => void;
+    /** Returns a human-readable string representation, e.g. `SignalSet(1, 2, 3)`. */
+    toString: () => string;
+    /** Converts the set to a JSON-compatible array. e.g. `[1, 2, "a"]` */
+    toJSON: () => T[];
+}
+/**
+ * Creates a reactive `SignalSet` backed by Angular signals.
+ *
+ * Every mutation creates a new `Set`, so Angular's signal equality check triggers updates.
+ *
+ * @template T The element type. Defaults to `number`.
+ * @param initialValue An optional iterable to seed the set with.
+ * @returns A {@link SignalSet} instance.
+ *
+ * @example
+ * ```ts
+ * const selected = signalSet<number>();
+ * selected.add(1);
+ * selected.toggle(2);
+ * console.log(selected.toArray()); // [1, 2]
+ * selected.toggle(1);
+ * console.log(selected.has(1));    // false
+ * ```
+ */
+declare function signalSet<T = number>(initialValue?: Iterable<T> | (() => Iterable<T>)): SignalSet<T>;
+
+/**
+ * Resolves `T` to itself when it is a valid object key (`string | number | symbol`),
+ * otherwise falls back to `string`. Used to type-safe `Record` conversions.
+ */
+type ToKey<T> = T extends string | number | symbol ? T : string;
+/**
+ * A reactive wrapper around a `Map` backed by Angular signals.
+ * All mutations produce a new `Map` instance, ensuring signal-based change detection works correctly.
+ *
+ * @template K The key type. Defaults to `string`.
+ * @template V The value type. Defaults to `unknown`.
+ */
+interface SignalMap<K = string, V = unknown> {
+    /** The current underlying `Map` (read via signal). */
+    (): Map<K, V>;
+    /** The number of entries in the map (reactive). */
+    size: Signal<number>;
+    /** A computed signal that returns the map keys as an array. */
+    keys: Signal<K[]>;
+    /** A computed signal that returns the map values as an array. */
+    values: Signal<V[]>;
+    /** A computed signal that returns the map entries as an array of `[key, value]` tuples. */
+    entries: Signal<[K, V][]>;
+    /** Returns the value associated with `key`, or `undefined` if absent. */
+    get: (key: K) => V | undefined;
+    /** Returns `true` if the map contains the given `key`. */
+    has: (key: K) => boolean;
+    /** Sets (or overwrites) the value for `key` and returns the updated `Map`. */
+    set: (key: K, value: V) => Map<K, V>;
+    /** Removes the entry for `key`. Returns `true` if the key existed. */
+    delete: (key: K) => boolean;
+    /** Removes all entries from the map. */
+    clear: () => void;
+    /** Returns a human-readable string, e.g. `SignalMap(a => 1, b => 2)`. */
+    toString: () => string;
+    /** Converts the map to a JSON-compatible object. */
+    toJSON: () => Record<ToKey<K>, V>;
+}
+/**
+ * Creates a reactive `SignalMap` backed by Angular signals.
+ *
+ * Every mutation creates a new `Map`, so Angular's signal equality check triggers updates.
+ * Accepts either an iterable of `[key, value]` pairs or a plain object as the initial value.
+ *
+ * @template K The key type. Defaults to `string`.
+ * @template V The value type. Defaults to `unknown`.
+ * @param initialValue An optional iterable of entries or a plain object to seed the map.
+ * @returns A {@link SignalMap} instance.
+ *
+ * @example
+ * ```ts
+ * const cache = signalMap<string, number>({ a: 1, b: 2 });
+ * cache.set('c', 3);
+ * console.log(cache.keys());   // ['a', 'b', 'c']
+ * cache.delete('a');            // true
+ * console.log(cache.toJSON());  // {b:2,c:3}
+ * ```
+ */
+declare function signalMap<K = string, V = unknown>(initialValue?: Iterable<[K, V]> | Record<ToKey<K>, V> | (() => Iterable<[K, V]> | Record<ToKey<K>, V>)): SignalMap<K, V>;
+
+/**
+ * Creates a reactive object backed by Angular signals.
+ *
+ * Every property is stored as a `WritableSignal`. Reading a property
+ * (e.g. `obj.name` or `obj['name']`) calls the signal — so it's
+ * automatically tracked in templates, `computed()`, and `effect()`.
+ * Setting a property calls `signal.set()`, which triggers reactivity.
+ *
+ * @example
+ * // In a component:
+ * protected person = signalObject({ name: 'dvirus', age: 30 });
+ *
+ * // In the template (reactive — updates automatically):
+ * // {{ person.name }}
+ *
+ * // In the class:
+ * // person.name = 'changed';   → triggers re-render
+ * // person['age'] = 31;        → triggers re-render
+ */
+type SignalObject<T> = T & {
+    /**
+     * Call the SignalObject as a function to get a reactive snapshot.
+     *
+     * @example
+     * const person = signalObject({ name: 'dvirus', age: 30 });
+     * person(); // { name: 'dvirus', age: 30 } — tracked by Angular
+     */
+    (): T;
+    /**
+     * A computed signal that returns a plain snapshot of all properties.
+     * Reading this tracks ALL properties — any property change triggers reactivity.
+     *
+     * @example
+     * effect(() => console.log(person.$snapshot()));
+     * // logs whenever ANY property changes
+     *
+     * const label = computed(() => {
+     *   const snap = person.$snapshot();
+     *   return `${snap.name} (${snap.age})`;
+     * });
+     */
+    /**
+     * Spreads one or more objects (plain or reactive) into this SignalObject.
+     * Mimics `Object.assign(this, ...sources)` / `{ ...this, ...a, ...b }`.
+     *
+     * - Existing keys → updates the signal (triggers reactivity)
+     * - New keys → creates a new signal and bumps the version
+     * - Accepts plain objects and SignalObjects interchangeably
+     *
+     * @param sources - One or more plain objects or SignalObjects to merge in
+     *
+     * @example
+     * const person = signalObject({ name: 'dvirus' });
+     * person.$assign({ age: 30 }, otherSignalObj);
+     */
+    $assign(...sources: Partial<T>[]): void;
+};
+/**
+ * Creates a reactive object backed by Angular signals.
+ *
+ * Every property is stored as a `WritableSignal`. Reading a property
+ * (e.g. `obj.name` or `obj['name']`) calls the signal — so it's
+ * automatically tracked in templates, `computed()`, and `effect()`.
+ * Setting a property calls `signal.set()`, which triggers reactivity.
+ *
+ * @param initialValue - The plain object to make reactive
+ * @returns A `SignalObject<T>` proxy with reactive property access, `$snapshot`, and `$assign`
+ *
+ * @example
+ * // In a component:
+ * protected person = signalObject({ name: 'dvirus', age: 30 });
+ *
+ * // In the template (reactive — updates automatically):
+ * // {{ person.name }}
+ *
+ * // In the class:
+ * person.name = 'changed';   // triggers re-render
+ * person['age'] = 31;        // triggers re-render
+ *
+ * // Spread (plain snapshot):
+ * const copy = { ...person }; // { name: 'changed', age: 31 }
+ *
+ * // Track all properties reactively:
+ * effect(() => console.log(person.$snapshot()));
+ */
+declare function signalObject<T extends object>(initialValue: T): SignalObject<T>;
+/**
+ * Type guard — checks if a value is a reactive SignalObject proxy.
+ *
+ * @example
+ * isSignalObject(signalObject({ a: 1 })); // true
+ * isSignalObject({ a: 1 });               // false
+ * isSignalObject({ ...signalObject({ a: 1 }) }); // false (spread = plain copy)
+ */
+declare function isSignalObject<T extends Record<string, unknown>>(value: unknown): value is SignalObject<T>;
+/**
+ * Reactively merges multiple SignalObjects (like `{ ...a, ...b }`).
+ * Returns a `Signal` that re-evaluates whenever any source property changes.
+ * Later sources win on key conflicts, just like spread.
+ *
+ * same as `computed(() => ({ ...a, ...b }))`
+ * but with proper tracking of nested properties and support for non-reactive objects as sources.
+ *
+ * @example
+ * const objA = signalObject({ name: 'dvirus', role: 'dev' });
+ * const objB = signalObject({ age: 30, role: 'admin' });
+ * const merged = mergeSignalObjects(objA, objB);
+ * merged(); // { name: 'dvirus', role: 'admin', age: 30 }
+ */
+declare function mergeSignalObjects<T extends object[]>(...sources: [...{
+    [K in keyof T]: T[K] | SignalObject<T[K]>;
+}]): Signal<UnionToIntersection<T[number]>>;
+/**
+ * Extracts the plain object type `U` from a `SignalObject<U>`.
+ * Returns `T` as-is if it's not a `SignalObject`.
+ */
+/**
+ * Converts a union of types into an intersection.
+ * Used to merge multiple object types from `mergeSignalObjects` into a single combined type.
+ *
+ * @example
+ * // UnionToIntersection<{ a: 1 } | { b: 2 }> → { a: 1 } & { b: 2 }
+ */
+type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+
+interface ControlEvent<T> {
+    /**
+     * Form control from which this event is originated.
+     *
+     * Note: the type of the control can't be inferred from T as the event can be emitted by any of child controls
+     */
+    readonly source: AbstractControl<unknown | T>;
+}
+/**
+ * A reactive signal-based wrapper around an `AbstractControl`, exposing
+ * the control's state (value, status, touched, dirty, errors, etc.) as
+ * Angular signals for use in templates and computed expressions.
+ *
+ * @template T - The value type of the underlying form control.
+ * @template TControl - The specific `AbstractControl` type being wrapped (e.g., `FormControl`, `FormGroup`, `FormArray`).
+ */
+interface ControlSignal<T, TControl extends AbstractControl<unknown> = AbstractControl<T>> {
+    /** Signal returning the underlying `AbstractControl` instance with its specific type. */
+    control: TControl;
+    /** Signal returning the current value of the control. */
+    value: Signal<T | null | undefined>;
+    /** Signal returning the current validation status (`VALID`, `INVALID`, `PENDING`, `DISABLED`). */
+    status: Signal<FormControlStatus | null | undefined>;
+    /** Signal returning the most recent `ControlEvent` emitted by the control. */
+    events: Signal<ControlEvent<T> | null | undefined>;
+    /** Signal that is `true` when the control status is `DISABLED`. */
+    disabled: Signal<boolean>;
+    /** Signal that is `true` when the control status is `VALID`. */
+    valid: Signal<boolean>;
+    /** Signal that is `true` when the control status is `INVALID`. */
+    invalid: Signal<boolean>;
+    /** Signal that is `true` when the control has been touched. */
+    touched: Signal<boolean>;
+    /** Signal that is `true` when the control is dirty. */
+    dirty: Signal<boolean>;
+    /** Signal returning the current validation errors, or `null` if there are none. */
+    errors: Signal<ValidationErrors | null>;
+    /** Signal returning the key of the first validation error, or `null`. */
+    firstErrorKey: Signal<string | null>;
+    /** Signal that is `true` when the control is both touched and invalid. */
+    touchedAndInvalid: Signal<boolean>;
+    /**
+     * Signal returning the control's synchronous validators as a `ValidationErrors`-like object, or `null` if there are none.
+     * @Note  that this does not include asynchronous validators, and the shape of the returned object may differ from the actual validation errors emitted by the control.
+     */
+    validators: Signal<ValidationErrors | null>;
+    /** Tears down all internal subscriptions and effects. */
+    unsubscribe(): void;
+}
+/**
+ * Creates a {@link ControlSignal} that mirrors an `AbstractControl`'s
+ * reactive state as Angular signals.
+ *
+ * **Important:** If called outside an injection context, you must manually handle
+ * un-subscription by either:
+ * - Calling the `unsubscribe()` method on the returned {@link ControlSignal}, or
+ * - Passing a `DestroyRef` via the `options` parameter for automatic cleanup.
+ *
+ * If called within an injection context without providing a `DestroyRef`, the
+ * subscriptions will be automatically cleaned up on component destruction.
+ *
+ * @template T - The value type of the form control.
+ * @param control - The form control or a signal wrapping one.
+ * @param options - Optional configuration object containing:
+ *   - `destroyRef`: A `DestroyRef` used for automatic cleanup on destruction.
+ *     If not provided, the function will attempt to inject one from the current
+ *     injection context. If neither is available, manual un-subscription is required.
+ * @returns A {@link ControlSignal} exposing the control's state as signals.
+ * @throws If `control` is a signal and no `Injector` is available.
+ */
+declare function controlSignal<T, TControl extends AbstractControl<unknown> = FormControl<T>>(control: TControl, options?: {
+    destroyRef?: DestroyRef | null;
+}): ControlSignal<T, TControl>;
+/**
+ * Extends {@link ControlSignal} with a strongly-typed `controls` map,
+ * providing a `ControlSignal` for every control in the `FormGroup`.
+ *
+ * @template T - An object type whose keys correspond to the group's control names
+ *   and whose values are the respective control value types.
+ */
+interface FormGroupSignal<TControls extends TypedControlMap> extends ControlSignal<ControlsValue<TControls>, FormGroup<TControls>> {
+    /** The underlying `FormGroup` instance. */
+    control: FormGroup<TControls>;
+    /** A map of child control names to their individual {@link ControlSignal} instances. */
+    controls: {
+        [K in keyof TControls]: NestedControlSignal<TControls[K]>;
+    };
+}
+/**
+ * Creates a {@link FormGroupSignal} for a `FormGroup`. Child controls are
+ * converted recursively, so nested `FormGroup` and `FormArray` structures
+ * are supported.
+ *
+ * @template TControls - A typed map of control names to `AbstractControl` instances.
+ * @param formGroup - The `FormGroup` to wrap.
+ * @param options - Optional `DestroyRef` and `Injector` forwarded to
+ *   each underlying {@link controlSignal} call.
+ * @returns A {@link FormGroupSignal} with both group-level and per-control signals.
+ */
+declare function formGroupSignal<TControls extends TypedControlMap>(formGroup: FormGroup<TControls>, options?: {
+    destroyRef?: DestroyRef | null;
+}): FormGroupSignal<TControls>;
+interface FormArraySignal<TControl extends AbstractControl<unknown>> extends ControlSignal<ControlValue<TControl>[], FormArray<TControl>> {
+    /** The underlying `FormArray` instance. */
+    control: FormArray<TControl>;
+    controls: NestedControlSignal<TControl>[];
+}
+/**
+ * Creates a {@link FormArraySignal} for a `FormArray`. Child controls are
+ * converted recursively, so arrays of `FormGroup`, arrays of `FormArray`,
+ * and arrays of `FormControl` are all supported.
+ */
+declare function formArraySignal<TControl extends AbstractControl<unknown>>(formArray: FormArray<TControl>, options?: {
+    destroyRef?: DestroyRef | null;
+}): FormArraySignal<TControl>;
+type TypedControlMap = Record<string, AbstractControl<unknown>>;
+type ControlValue<TControl extends AbstractControl<unknown>> = TControl extends AbstractControl<infer TValue> ? TValue : never;
+type ControlsValue<TControls extends TypedControlMap> = {
+    [K in keyof TControls]: ControlValue<TControls[K]>;
+};
+type NestedControlSignal<TControl extends AbstractControl<unknown>> = TControl extends FormGroup<infer TControls> ? FormGroupSignal<TControls> : TControl extends FormArray<infer TItemControl> ? FormArraySignal<TItemControl & AbstractControl<unknown>> : ControlSignal<ControlValue<TControl>, TControl>;
+
+/**
+ * Types for the result tuple with discriminated union
+ * @template T - Type of the successful result
+ * @template E - Type of the error, defaults to Error
+ */
+type TryResult<T, E = Error> = [T, null] | [null, E];
+/**
+ * Main wrapper function to handle promise with try-catch
+ * @template T - Type of the successful result
+ * @template E - Type of the error, defaults to Error
+ * @param {()=> T} fn - The function to handle
+ * @returns {TryResult<T, E>} - A tuple with either the result or the error
+ */
+declare function tryCatch<T, E = Error>(fn: () => T): TryResult<T, E>;
+
+/**
+ * Type for value equality comparison function
+ */
+type ValueEqualityFn<T> = (a: T, b: T) => boolean;
+/**
+ * Creates a `WritableSignal` whose value is derived from a computation function,
+ * but can also be overridden manually via `.set()` / `.update()`.
+ * When the reactive dependencies inside the computation change, the signal resets to the new derived value.
+ *
+ * Angular-16 compatible alternative to `linkedSignal` (Angular 19+).
+ *
+ * @overload
+ * @param computation - A computation function that returns the derived value
+ * @param options - Optional configuration (equal, debugName)
+ * @returns A WritableSignal<D>
+ */
+declare function writableSignal<D>(computation: () => D, options?: {
+    equal?: ValueEqualityFn<D>;
+    debugName?: string;
+}): WritableSignal<D>;
+/**
+ *  Creates a `WritableSignal` with explicit source tracking and computation.
+ *  The `source` function provides the reactive dependencies, and the `computation` function derives the value from the source.
+ *  Manual overrides via `.set()` / `.update()` are only valid for the specific source state they were set against.
+ *
+ *  Angular-16 compatible alternative to `linkedSignal` (Angular 19+).
+ *
+ * @overload
+ * @param options - Configuration object with source tracking and computation
+ * @returns A WritableSignal<D>
+ */
+declare function writableSignal<S, D>(options: {
+    source: () => S;
+    computation: (source: S, previous?: {
+        source: S;
+        value: D;
+    }) => D;
+    equal?: ValueEqualityFn<D>;
+    debugName?: string;
+}): WritableSignal<D>;
+
+export { controlSignal, createSignalFormArray, createSignalFormControl, createSignalFormGroup, formArray, formArraySignal, formControl, formGroup, formGroupSignal, fromSignalObj, isSignalFormArray, isSignalFormControl, isSignalFormGroup, isSignalObject, mergeSignalObjects, signalDebounce, signalForm, signalFormValidators, signalMap, signalNotifier, signalObject, signalOrFunction, signalOrValue, signalSet, toSignalObj, tryCatch, writableSignal };
+export type { ControlSignal, FirstError, FormArraySignal, FormGroupSignal, NestedControlSignal, ObjectType, SignalDebounce, SignalForm, SignalFormArray, SignalFormArrayInput, SignalFormContext, SignalFormControl, SignalFormControlConfig, SignalFormControlInput, SignalFormControlLike, SignalFormDisableOptions, SignalFormDisabledFn, SignalFormErrorFor, SignalFormGroupInput, SignalFormInput, SignalFormInputs, SignalFormSetValueOptions, SignalFormValidationError, SignalFormValidatorFn, SignalFormValueFor, SignalMap, SignalNotifier, SignalObj, SignalObjWritable, SignalObject, SignalOrValue, SignalOrValueObj, SignalSet };