import { BehaviorSubject, Observable } from 'rxjs';
import { StateObjType } from '../types/state-obj.type';
import * as i0 from "@angular/core";
/**
 * A comprehensive reactive state management service for Angular applications that provides
 * centralized state storage, hierarchical organization, and robust backup/rollback functionality.
 *
 * This service implements a sophisticated state management pattern using RxJS BehaviorSubjects
 * to enable reactive data flow throughout Angular applications. It supports both flat and
 * hierarchical state organization through groups, automatic backup creation for rollback
 * operations, and deep merging capabilities for complex state updates.
 *
 * ## Key Features
 *
 * - **Reactive State Management**: Built on RxJS BehaviorSubjects for reactive data flow
 * - **Hierarchical Organization**: Support for grouped state subjects with nested structures
 * - **Backup & Rollback**: Automatic backup creation with reset functionality for undo operations
 * - **Deep Merging**: Intelligent object merging for partial state updates
 * - **Type Safety**: Full TypeScript support with type guards and strict typing
 * - **Memory Management**: Proper cleanup and resource management to prevent memory leaks
 * - **Change Detection**: Optimized updates with deep equality checks to prevent unnecessary emissions
 *
 * ## Usage Patterns
 *
 * ### Basic State Operations
 * ```typescript
 * // Inject the service
 * constructor(private stateModel: StateModel) {}
 *
 * // Set initial state
 * this.stateModel.set('userProfile', { id: 1, name: 'John', email: 'john@example.com' });
 *
 * // Subscribe to state changes
 * this.stateModel.observe('userProfile').subscribe(profile => {
 *   console.log('Profile updated:', profile);
 * });
 *
 * // Update existing state
 * this.stateModel.update('userProfile', { name: 'Jane Doe' });
 *
 * // Reset to backup value
 * this.stateModel.reset('userProfile');
 * ```
 *
 * ### Grouped State Management
 * ```typescript
 * // Create and populate a group
 * const users = [
 *   { id: 'user1', name: 'John', role: 'admin' },
 *   { id: 'user2', name: 'Jane', role: 'user' }
 * ];
 * this.stateModel.loadGroup('users', 'id', users);
 *
 * // Access grouped subjects
 * this.stateModel.observe('user1', 'users').subscribe(user => {
 *   console.log('User updated:', user);
 * });
 *
 * // Update grouped state
 * this.stateModel.set('currentUser', { id: 3, name: 'Bob' }, 'users');
 * ```
 *
 * ### Form Integration with Backup/Reset
 * ```typescript
 * // Initialize form state
 * this.stateModel.set('formData', this.form.value);
 *
 * // Track form changes
 * this.form.valueChanges.subscribe(value => {
 *   this.stateModel.update('formData', value);
 * });
 *
 * // Reset form to initial state
 * onResetClick() {
 *   this.stateModel.reset('formData');
 *   this.form.patchValue(this.stateModel.value('formData'));
 * }
 * ```
 *
 * ## Architecture
 *
 * The service maintains several core registries:
 * - **Main Directory**: Flat registry of named BehaviorSubjects
 * - **Groups**: Hierarchical registry for organized state subjects
 * - **Backups**: Rollback data for main directory subjects
 * - **Group Backups**: Rollback data for grouped subjects
 * - **Change Tracking**: Reactive notifications for state modifications
 *
 * ## Performance Optimizations
 *
 * - Deep equality checks prevent unnecessary BehaviorSubject emissions
 * - Automatic cleanup prevents memory leaks
 * - Smart merging preserves existing state properties
 * - Lazy initialization of subjects and groups
 *
 * @example
 * ## Complete Example: User Management with Groups
 * ```typescript
 * @Component({...})
 * export class UserManagementComponent implements OnInit {
 *   constructor(private stateModel: StateModel) {}
 *
 *   ngOnInit() {
 *     // Initialize user management state
 *     this.loadUsers();
 *     this.setupSubscriptions();
 *   }
 *
 *   private loadUsers() {
 *     const users = [
 *       { id: 'user1', name: 'John Doe', email: 'john@example.com', active: true },
 *       { id: 'user2', name: 'Jane Smith', email: 'jane@example.com', active: false }
 *     ];
 *
 *     // Create grouped state for users
 *     this.stateModel.loadGroup('users', 'id', users);
 *
 *     // Set selected user
 *     this.stateModel.set('selectedUser', users[0], 'users');
 *   }
 *
 *   private setupSubscriptions() {
 *     // React to selected user changes
 *     this.stateModel.observe('selectedUser', 'users').subscribe(user => {
 *       if (user) {
 *         this.loadUserDetails(user);
 *       }
 *     });
 *
 *     // Monitor all group changes
 *     this.stateModel.groupList.subscribe(groups => {
 *       console.log('Available groups:', groups);
 *     });
 *   }
 *
 *   updateUser(userId: string, updates: Partial<User>) {
 *     // Merge partial updates with existing user data
 *     this.stateModel.dirMerge(updates, userId, 'users');
 *   }
 *
 *   resetUserChanges(userId: string) {
 *     // Reset user to backup state
 *     this.stateModel.reset(userId, 'users');
 *   }
 * }
 * ```
 *
 * @see {@link StateObjType} - Type definition for state values
 * @see {@link BehaviorSubject} - RxJS reactive primitive used for state storage
 *
 * @public
 * @injectable
 * @since 1.0.0
 */
export declare class StateModel {
    /**
     * Registry of backup values for state subjects to enable rollback functionality.
     *
     * Stores the original values of state subjects when they are created or modified through the
     * {@link StateModel.set} method. These backup values remain immutable during subsequent
     * {@link StateModel.update} operations and can be restored using {@link StateModel.reset}.
     * This mechanism supports undo/reset patterns commonly used in form controls and dialog
     * components.
     *
     * @remarks
     * The backup system follows these rules:
     * - Backups are created/updated only by the `set()` method
     * - The `update()` method does not modify backup values
     * - The `reset()` method restores values from this backup registry
     * - Backups are stored as deep clones to prevent reference mutations
     *
     * @example
     * Basic backup and reset workflow:
     * ```typescript
     * // Setting creates backup automatically
     * stateModel.set('userForm', { name: 'John', email: 'john@example.com' });
     *
     * // Backup contains original value
     * console.log(stateModel.backups['userForm']);
     * // Output: { name: 'John', email: 'john@example.com' }
     *
     * // Updates don't affect backup
     * stateModel.update('userForm', { name: 'Jane', email: 'jane@example.com' });
     *
     * // Backup remains unchanged
     * console.log(stateModel.backups['userForm']);
     * // Output: { name: 'John', email: 'john@example.com' }
     *
     * // Reset restores from backup
     * stateModel.reset('userForm');
     * // Current value: { name: 'John', email: 'john@example.com' }
     * ```
     *
     * @see {@link StateModel.set} - Creates and updates backup values
     * @see {@link StateModel.update} - Modifies state without affecting backups
     * @see {@link StateModel.reset} - Restores state from backup values
     * @see {@link StateModel.groupBackups} - Backup registry for grouped subjects
     *
     * @since 1.0.0
     */
    backups: Record<string, StateObjType>;
    /**
     * A registry of reactive state subjects that can be observed by any component
     * throughout the application. This registry uses a key-value mapping pattern
     * where each key represents a unique state identifier and each value is a
     * BehaviorSubject containing the state data.
     *
     * This design pattern provides centralized state management with reactive
     * capabilities, allowing components to subscribe to specific state changes
     * without tight coupling to state producers.
     *
     * @example
     * ```typescript
     * // Subscribe to a specific state
     * this.stateModel.dir['userProfile'].subscribe(profile => {
     *   console.log('User profile updated:', profile);
     * });
     *
     * // Access current value
     * const currentUser = this.stateModel.dir['userProfile'].value;
     * ```
     *
     * @see {@link StateModel.observe} For safe access to subjects with automatic creation
     * @see {@link StateModel.set} For creating and updating state subjects
     * @see {@link StateModel.update} For modifying existing state subjects
     *
     * @public
     * @since 1.0.0
     */
    dir: Record<string, BehaviorSubject<StateObjType>>;
    /**
     * A reactive registry of all group names currently managed by the state system.
     *
     * This BehaviorSubject maintains an array of string identifiers representing
     * all group names that exist in the {@link StateModel.groups} registry. It provides
     * a reactive way to track when new groups are created or existing groups are removed,
     * enabling components to respond to structural changes in the grouped state architecture.
     *
     * The group list is automatically maintained by the state management system:
     * - Group names are added when {@link StateModel.loadGroup} creates new groups
     * - Group names are removed when {@link StateModel.removeGroup} deletes groups
     * - The list is kept in sync with the actual {@link StateModel.groups} registry
     *
     * @example
     * Subscribe to group registry changes:
     * ```typescript
     * this.stateModel.groupList.subscribe(groupNames => {
     *   console.log('Available groups:', groupNames);
     *   // Output: ['users', 'settings', 'navigation']
     * });
     * ```
     *
     * @example
     * Check if a specific group exists:
     * ```typescript
     * const hasUsersGroup = this.stateModel.groupList.value.includes('users');
     * ```
     *
     * @see {@link StateModel.groups} - The actual group registry this list tracks
     * @see {@link StateModel.loadGroup} - Method that adds group names to this list
     * @see {@link StateModel.removeGroup} - Method that removes group names from this list
     *
     * @public
     * @since 1.0.0
     */
    groupList: BehaviorSubject<string[]>;
    /**
     * Hierarchical registry of backup values for grouped state subjects to enable rollback functionality.
     *
     * This two-tier backup system maintains original values for state subjects organized within groups,
     * complementing the main {@link StateModel.backups} registry for ungrouped subjects. Each group
     * maintains its own backup registry, where backup values remain immutable during subsequent
     * {@link StateModel.update} operations and can be restored using {@link StateModel.reset}.
     *
     * The structure follows a group-name → subject-name → backup-value hierarchy, allowing for
     * fine-grained backup management within the grouped state architecture. This supports complex
     * UI patterns where different feature areas require independent rollback capabilities.
     *
     * @remarks
     * The hierarchical backup system follows these rules:
     * - Group backups are created/updated only by the `set()` method when a group name is specified
     * - The `update()` method does not modify backup values in any group
     * - The `reset()` method can restore individual subjects within specific groups
     * - Group removal via `removeGroup()` clears all backup data for that group
     * - Backups are stored as deep clones to prevent reference mutations
     *
     * @example
     * Grouped backup and reset workflow:
     * ```typescript
     * // Setting with group creates backup automatically
     * stateModel.set('currentUser', { id: 1, name: 'John' }, 'users');
     * stateModel.set('permissions', ['read', 'write'], 'users');
     *
     * // Group backup structure:
     * // {
     * //   'users': {
     * //     'currentUser': { id: 1, name: 'John' },
     * //     'permissions': ['read', 'write']
     * //   }
     * // }
     *
     * // Updates don't affect group backups
     * stateModel.update('currentUser', { id: 1, name: 'Jane' }, 'users');
     *
     * // Group backup remains unchanged
     * console.log(stateModel.groupBackups['users']['currentUser']);
     * // Output: { id: 1, name: 'John' }
     *
     * // Reset specific subject within group
     * stateModel.reset('currentUser', 'users');
     * // Current value restored: { id: 1, name: 'John' }
     * ```
     *
     * @see {@link StateModel.backups} - Main backup registry for ungrouped subjects
     * @see {@link StateModel.groups} - The grouped subjects this backup system supports
     * @see {@link StateModel.set} - Creates and updates group backup values
     * @see {@link StateModel.reset} - Restores state from group backup values
     * @see {@link StateModel.removeGroup} - Clears all backups for a specific group
     *
     * @public
     * @since 1.0.0
     */
    groupBackups: Record<string, Record<string, StateObjType>>;
    /**
     * A Directory of grouped BehaviorSubjects where each group is itself a BehaviorSubject
     * containing a Record of named BehaviorSubjects. This nested structure allows for
     * reactive group management where the entire group can be observed for changes,
     * and individual subjects within each group can also be observed independently.
     *
     * The outer Record maps group names to BehaviorSubjects, where each BehaviorSubject
     * contains a Record mapping subject names to their respective BehaviorSubjects.
     * This enables hierarchical state management with both group-level and item-level
     * reactivity.
     *
     * @example
     * ```typescript
     * // Access a specific subject within a group
     * const userSubject = this.groups['users'].value['john'];
     *
     * // Subscribe to changes in the entire group
     * this.groups['users'].subscribe(groupRecord => {
     *   console.log('Group changed:', Object.keys(groupRecord));
     * });
     *
     * // Subscribe to changes in a specific subject within the group
     * this.groups['users'].value['john'].subscribe(userData => {
     *   console.log('User data changed:', userData);
     * });
     * ```
     */
    groups: Record<string, BehaviorSubject<Record<string, BehaviorSubject<StateObjType>>>>;
    /**
     * A reactive tracker that emits the name of the most recently updated state subject.
     *
     * This BehaviorSubject provides a centralized way to monitor state change activity
     * across the entire state management system. It emits the subject name whenever
     * any state modification occurs through the {@link StateModel.set}, {@link StateModel.update},
     * or {@link StateModel.initiate} methods, enabling reactive side effects and UI updates
     * based on specific state changes.
     *
     * The tracker operates across both individual subjects in {@link StateModel.dir}
     * and grouped subjects in {@link StateModel.groups}, providing unified change
     * detection regardless of state organization.
     *
     * @example
     * Monitor all state changes:
     * ```typescript
     * this.stateModel.updated.subscribe(subjectName => {
     *   if (subjectName) {
     *     console.log(`State subject '${subjectName}' was updated`);
     *     // Trigger side effects, analytics, or UI updates
     *   }
     * });
     * ```
     *
     * @example
     * React to specific subject changes:
     * ```typescript
     * this.stateModel.updated.pipe(
     *   filter(name => name === 'userProfile'),
     *   switchMap(() => this.stateModel.observe('userProfile'))
     * ).subscribe(profile => {
     *   // Handle user profile changes
     * });
     * ```
     *
     * @remarks
     * - Emits `undefined` on initialization
     * - Always emits the subject name, not the group name for grouped subjects
     * - Useful for implementing global state change listeners and audit trails
     * - Can be used to invalidate caches or trigger data synchronization
     *
     * @see {@link StateModel.set} - Method that triggers updates when setting state
     * @see {@link StateModel.update} - Method that triggers updates when modifying state
     * @see {@link StateModel.initiate} - Method that triggers updates when initializing state
     *
     * @public
     * @since 1.0.0
     */
    updated: BehaviorSubject<string | undefined>;
    /**
     * Type guard that determines whether a value is a plain object suitable for deep merging operations.
     *
     * This utility method implements a type-safe check to identify plain objects created by object
     * literals or the Object constructor, distinguishing them from arrays, dates, class instances,
     * and other specialized object types. It uses the reliable `Object.prototype.toString.call()`
     * approach to ensure accurate type detection across different JavaScript contexts and
     * inheritance chains.
     *
     * Plain objects are defined as objects with `[object Object]` as their internal [[Class]] slot,
     * which includes:
     * - Object literals: `{ key: 'value' }`
     * - Objects created with `new Object()`
     * - Objects created with `Object.create(Object.prototype)`
     *
     * Non-plain objects that return `false` include:
     * - Arrays: `[1, 2, 3]`
     * - Dates: `new Date()`
     * - RegExp: `/pattern/`
     * - Functions: `() => {}`
     * - Class instances: `new MyClass()`
     * - Built-in objects: `Math`, `JSON`, etc.
     * - Primitives: `null`, `undefined`, strings, numbers, booleans
     *
     * @param val - The value to test for plain object status. Accepts any type including
     *   primitives, objects, arrays, null, or undefined.
     *
     * @returns Type predicate indicating whether the value is a plain object. When `true`,
     *   TypeScript narrows the type to `Record<string, unknown>`, enabling safe property access
     *   and iteration. When `false`, the value is not suitable for deep merging operations.
     *
     * @example
     * Basic plain object detection:
     * ```typescript
     * this.isPlainObject({});                    // true
     * this.isPlainObject({ name: 'John' });      // true
     * this.isPlainObject(new Object());          // true
     * this.isPlainObject([1, 2, 3]);             // false
     * this.isPlainObject(new Date());            // false
     * this.isPlainObject(null);                  // false
     * this.isPlainObject('string');              // false
     * ```
     *
     * @example
     * Usage in merge operations:
     * ```typescript
     * if (this.isPlainObject(sourceObj) && this.isPlainObject(targetObj)) {
     *   // Safe to perform recursive merge
     *   return this.merge(sourceObj, targetObj);
     * } else {
     *   // Replace non-plain objects completely
     *   return sourceObj;
     * }
     * ```
     *
     * @example
     * Type narrowing with type guard:
     * ```typescript
     * function processValue(input: unknown) {
     *   if (this.isPlainObject(input)) {
     *     // TypeScript knows 'input' is Record<string, unknown>
     *     console.log(Object.keys(input)); // No type error
     *     return input.someProperty;        // Safe property access
     *   }
     *   // Handle non-plain objects differently
     *   return input;
     * }
     * ```
     *
     * @remarks
     * - Uses `Object.prototype.toString.call()` for reliable cross-frame type detection
     * - Serves as a TypeScript type guard for enhanced type safety in merge operations
     * - Essential for preventing incorrect recursive merging of arrays, dates, and class instances
     * - Performance is O(1) with minimal overhead for type checking
     * - Does not check for object enumerability or property descriptors
     *
     * @see {@link StateModel.merge} - Primary consumer of this type guard for safe object merging
     * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/toString
     *
     * @internal
     * @since 1.0.0
     */
    private isPlainObject;
    /**
     * Retrieves the current values from all BehaviorSubjects in the state registry.
     *
     * Extracts and returns the current values from all registered state subjects,
     * either from the main {@link StateModel.dir} registry or from a specific group
     * within {@link StateModel.groups}. The returned object uses subject names as keys
     * and their current values as the corresponding values, providing a snapshot
     * of the current state at the time of invocation.
     *
     * Values are deep cloned through the {@link StateModel.value} method to prevent
     * external mutations from affecting the state management system.
     *
     * @param groupName - Optional group name to limit extraction to subjects within
     *   a specific group. When `null` (default), retrieves values from all subjects
     *   in the main directory. When specified, only retrieves values from subjects
     *   within the named group.
     *
     * @returns A record object where keys are subject names and values are the
     *   current state values of the corresponding BehaviorSubjects. Returns an
     *   empty object if no subjects exist or if the specified group doesn't exist.
     *
     * @example
     * Get all values from the main directory:
     * ```typescript
     * const allValues = this.stateModel.getDirValues();
     * // Returns: { userProfile: {...}, settings: {...}, navigation: {...} }
     * ```
     *
     * @example
     * Get values from a specific group:
     * ```typescript
     * const userValues = this.stateModel.getDirValues('users');
     * // Returns: { currentUser: {...}, permissions: [...] }
     * ```
     *
     * @see {@link StateModel.dir} - Main state subject registry
     * @see {@link StateModel.groups} - Grouped state subject registry
     * @see {@link StateModel.value} - Method used internally to extract values
     *
     * @public
     * @since 1.0.0
     */
    getDirValues(groupName?: string | null): Record<string, StateObjType>;
    /**
     * Determines whether a BehaviorSubject with the specified name exists in the state registry.
     *
     * This method performs existence checks in either the main {@link StateModel.dir} registry
     * or within a specific group in {@link StateModel.groups}. When a group name is provided,
     * the method first verifies the group exists before checking for the subject within that group.
     * This dual-level checking supports the hierarchical state management architecture.
     *
     * @param subjectName - The name of the BehaviorSubject to check for existence.
     *   This parameter is required and represents the unique identifier for the state subject.
     * @param groupName - Optional group name to limit the search to subjects within
     *   a specific group. When `null` (default), searches in the main directory registry.
     *   When specified, searches only within the named group.
     *
     * @returns `true` if the subject exists in the specified location (main directory
     *   or within the specified group), `false` otherwise. Returns `false` if the
     *   specified group doesn't exist.
     *
     * @example
     * Check for subject in main directory:
     * ```typescript
     * const hasUserProfile = this.stateModel.has('userProfile');
     * // Returns true if 'userProfile' exists in main directory
     * ```
     *
     * @example
     * Check for subject within a specific group:
     * ```typescript
     * const hasCurrentUser = this.stateModel.has('currentUser', 'users');
     * // Returns true if 'currentUser' exists within 'users' group
     * ```
     *
     * @see {@link StateModel.dir} - Main state subject registry
     * @see {@link StateModel.groups} - Grouped state subject registry
     * @see {@link StateModel.observe} - Method for safely accessing subjects with automatic creation
     *
     * @public
     * @since 1.0.0
     */
    has(subjectName: string, groupName?: string | null): boolean;
    /**
     * Initializes or resets a BehaviorSubject to an undefined state within the state management system.
     *
     * This method creates new BehaviorSubjects with an initial value of `undefined`, or resets existing
     * subjects to `undefined` if they currently contain other values. It supports both standalone subjects
     * in the main {@link StateModel.dir} registry and grouped subjects within {@link StateModel.groups}.
     * When working with grouped subjects, the method will automatically create the parent group if it
     * doesn't exist.
     *
     * The initialization process includes:
     * - Creating new BehaviorSubjects with `undefined` as the initial value
     * - Resetting existing subjects to `undefined` (no-op if already `undefined`)
     * - Setting up corresponding backup entries for rollback functionality
     * - Auto-creating group structures when specified
     * - Triggering the {@link StateModel.updated} notification system
     *
     * @param subjectName - The unique identifier for the BehaviorSubject to initialize or reset.
     *   Must be a non-empty string that will serve as the key in the state registry.
     * @param groupName - Optional group name to organize the subject within a hierarchical structure.
     *   When `null` (default), the subject is created in the main directory. When specified, the subject
     *   is created within the named group, and the group itself is created if it doesn't exist.
     *
     * @returns void - This method performs side effects but returns no value.
     *
     * @example
     * Initialize a standalone subject:
     * ```typescript
     * // Creates a new BehaviorSubject with undefined value
     * this.stateModel.initiate('userProfile');
     *
     * // Access the initialized subject
     * this.stateModel.observe('userProfile').subscribe(value => {
     *   console.log(value); // undefined initially
     * });
     * ```
     *
     * @example
     * Initialize a subject within a group:
     * ```typescript
     * // Creates both 'users' group and 'currentUser' subject if they don't exist
     * this.stateModel.initiate('currentUser', 'users');
     *
     * // Reset an existing grouped subject to undefined
     * this.stateModel.set('currentUser', { id: 1, name: 'John' }, 'users');
     * this.stateModel.initiate('currentUser', 'users'); // Resets to undefined
     * ```
     *
     * @example
     * Resetting existing subjects:
     * ```typescript
     * // Subject with existing data
     * this.stateModel.set('settings', { theme: 'dark', lang: 'en' });
     *
     * // Reset to undefined (triggers backup and notification)
     * this.stateModel.initiate('settings');
     *
     * // No-op if already undefined
     * this.stateModel.initiate('settings'); // No change, no notification
     * ```
     *
     * @remarks
     * - Early return optimization: If the target subject already has an `undefined` value, the method returns early without triggering notifications
     * - Group auto-creation: When a group name is specified but the group doesn't exist, both the group and backup registry are automatically created
     * - Backup management: All initiated subjects receive corresponding backup entries set to `undefined`
     * - Notification system: The {@link StateModel.updated} BehaviorSubject is notified with the subject name after successful operations
     *
     * @see {@link StateModel.set} - For setting subjects with specific initial values
     * @see {@link StateModel.observe} - For safely accessing and subscribing to subjects
     * @see {@link StateModel.reset} - For restoring subjects from backup values
     * @see {@link StateModel.loadGroup} - For bulk group creation with multiple subjects
     *
     * @public
     * @since 1.0.0
     */
    initiate(subjectName: string, groupName?: string | null): void;
    /**
     * Performs deep equality comparison between two values to determine if they are structurally identical.
     *
     * This utility method implements recursive deep comparison for complex data structures including
     * objects, arrays, and primitives. It's used throughout the state management system to prevent
     * unnecessary BehaviorSubject emissions when values haven't actually changed, optimizing
     * performance and preventing infinite subscription loops.
     *
     * The comparison follows these rules:
     * - Uses strict equality (`===`) for primitives and identical references
     * - Considers `null` and `undefined` as distinct values (not equal to each other)
     * - Recursively compares array elements in order
     * - Recursively compares object properties by key-value pairs
     * - Returns `false` for mismatched types or structures
     *
     * @param value - The first value to compare. Can be any type including primitives,
     *   objects, arrays, null, or undefined.
     * @param other - The second value to compare against. Can be any type including
     *   primitives, objects, arrays, null, or undefined.
     *
     * @returns `true` if the values are deeply equal, `false` if they differ in structure
     *   or content, or `undefined` if the comparison cannot be determined (currently this
     *   method always returns a boolean).
     *
     * @example
     * Primitive comparisons:
     * ```typescript
     * this.stateModel.isEqual(5, 5);           // true
     * this.stateModel.isEqual('hello', 'hi');  // false
     * this.stateModel.isEqual(null, undefined); // false
     * ```
     *
     * @example
     * Array comparisons:
     * ```typescript
     * this.stateModel.isEqual([1, 2, 3], [1, 2, 3]);     // true
     * this.stateModel.isEqual([1, 2], [1, 2, 3]);        // false
     * this.stateModel.isEqual([[1, 2]], [[1, 2]]);       // true (nested arrays)
     * ```
     *
     * @example
     * Object comparisons:
     * ```typescript
     * const obj1 = { name: 'John', age: 30, hobbies: ['read', 'code'] };
     * const obj2 = { name: 'John', age: 30, hobbies: ['read', 'code'] };
     * const obj3 = { age: 30, name: 'John', hobbies: ['read', 'code'] };
     *
     * this.stateModel.isEqual(obj1, obj2); // true
     * this.stateModel.isEqual(obj1, obj3); // true (key order doesn't matter)
     * ```
     *
     * @example
     * Usage in state management optimization:
     * ```typescript
     * // Prevents unnecessary emissions
     * const currentValue = this.dir['userProfile'].value;
     * if (!this.isEqual(currentValue, newValue)) {
     *   this.dir['userProfile'].next(newValue);
     * }
     * ```
     *
     * @remarks
     * - This method is used internally by {@link StateModel.set}, {@link StateModel.update},
     *   and {@link StateModel.reset} to optimize performance
     * - Handles circular references gracefully by comparing object structure
     * - Performance scales with object depth and complexity
     * - Does not compare object prototypes or non-enumerable properties
     *
     * @see {@link StateModel.set} - Uses this method to prevent duplicate state updates
     * @see {@link StateModel.update} - Uses this method for change detection
     * @see {@link StateModel.dirEquals} - Higher-level equality check for directory objects
     *
     * @public
     * @since 1.0.0
     */
    isEqual(value: unknown, other: unknown): boolean | undefined;
    /**
     * Creates and initializes a hierarchical group within the state management system.
     *
     * This method establishes a new group in the {@link StateModel.groups} registry as a
     * BehaviorSubject containing a Record of named BehaviorSubjects. The group provides
     * hierarchical state organization where both the group container and individual subjects
     * within it are reactive. Optionally populates the group with BehaviorSubjects created
     * from an array of objects, using a specified property as the subject identifier.
     *
     * The method performs the following operations:
     * - Creates the group BehaviorSubject if it doesn't exist
     * - Optionally creates individual BehaviorSubjects from object array using keyName as identifier
     * - Updates the reactive {@link StateModel.groupList} registry
     * - Maintains referential integrity within the hierarchical state structure
     *
     * @param groupName - The unique identifier for the group to create or initialize.
     *   This name will be used as the key in the {@link StateModel.groups} registry.
     * @param keyName - Optional property name within objects to use as BehaviorSubject
     *   identifiers. When provided with `objArray`, this property's value becomes the
     *   subject name within the group. Must exist as a string or number property in each object.
     * @param objArray - Optional array of objects to transform into BehaviorSubjects within
     *   the group. Each object becomes the initial value of a BehaviorSubject, with the
     *   subject name derived from the object's `keyName` property.
     *
     * @example
     * Create an empty group:
     * ```typescript
     * this.stateModel.loadGroup('users');
     * // Creates: groups['users'] = BehaviorSubject<Record<string, BehaviorSubject<StateObjType>>>({})
     * ```
     *
     * @example
     * Populate group from object array:
     * ```typescript
     * const userData = [
     *   { id: 'user1', name: 'John', role: 'admin' },
     *   { id: 'user2', name: 'Jane', role: 'user' }
     * ];
     * this.stateModel.loadGroup('users', 'id', userData);
     * // Creates subjects: groups['users'].value['user1'], groups['users'].value['user2']
     * ```
     *
     * @see {@link StateModel.groups} - The hierarchical group registry this method modifies
     * @see {@link StateModel.groupList} - Reactive list of all group names, updated by this method
     * @see {@link StateModel.removeGroup} - Method for removing entire groups
     * @see {@link StateModel.observe} - Method for accessing subjects within groups
     *
     * @public
     * @since 1.0.0
     */
    loadGroup(groupName: string, keyName?: string | null, objArray?: unknown[] | null): void;
    /**
     * Performs a deep merge of two objects, combining their properties into a new object.
     *
     * This method recursively merges nested objects while preserving the structure of both input objects.
     * Properties from `newObj` take precedence over properties from `oldObj`. For nested plain objects,
     * the merge operation continues recursively. For primitives, arrays, dates, and other non-plain
     * object types, values from `newObj` completely replace corresponding values from `oldObj`.
     *
     * The merge operation follows these rules:
     * - If `newObj` is not a plain object (null, undefined, array, etc.), returns `oldObj` unchanged
     * - If `oldObj` is null or undefined, treats it as an empty object for merging purposes
     * - Nested plain objects are merged recursively using the same rules
     * - Non-object values (primitives, arrays, dates, etc.) from `newObj` replace values in `oldObj`
     * - Returns a new object without mutating the original input objects
     *
     * @param newObj - The source object whose properties will be merged into the base object.
     *   If not a plain object, the merge operation returns `oldObj` unchanged.
     * @param oldObj - The base object to merge into. Null or undefined values are treated as empty objects.
     *
     * @returns A new merged object containing properties from both inputs, with `newObj` properties
     *   taking precedence. Returns `oldObj` unchanged if `newObj` is not a plain object.
     *
     * @example
     * Basic object merging:
     * ```typescript
     * const base = { name: 'John', age: 30, city: 'New York' };
     * const updates = { age: 31, country: 'USA' };
     * const result = this.stateModel.merge(updates, base);
     * // Result: { name: 'John', age: 31, city: 'New York', country: 'USA' }
     * ```
     *
     * @example
     * Nested object merging:
     * ```typescript
     * const base = { user: { name: 'John', settings: { theme: 'light', lang: 'en' } } };
     * const updates = { user: { settings: { theme: 'dark' } } };
     * const result = this.stateModel.merge(updates, base);
     * // Result: { user: { name: 'John', settings: { theme: 'dark', lang: 'en' } } }
     * ```
     *
     * @example
     * Handling non-plain objects:
     * ```typescript
     * const base = { items: [1, 2, 3], date: new Date('2023-01-01') };
     * const updates = { items: [4, 5], date: new Date('2024-01-01') };
     * const result = this.stateModel.merge(updates, base);
     * // Arrays and dates are replaced, not merged
     * // Result: { items: [4, 5], date: new Date('2024-01-01') }
     * ```
     *
     * @example
     * State update pattern:
     * ```typescript
     * // Merge partial user profile updates
     * const currentProfile = this.stateModel.value('userProfile');
     * const profileUpdates = { preferences: { notifications: false } };
     * const mergedProfile = this.stateModel.merge(profileUpdates, currentProfile);
     * this.stateModel.set('userProfile', mergedProfile);
     * ```
     *
     * @remarks
     * - Uses {@link StateModel.isPlainObject} to determine if objects can be merged recursively
     * - Preserves prototype chains and does not modify input objects
     * - Performance scales with object depth and number of properties
     * - Ideal for implementing partial state updates and configuration merging
     *
     * @see {@link StateModel.isPlainObject} - Helper method used to identify mergeable objects
     * @see {@link StateModel.update} - Method that could benefit from merge operations
     * @see {@link StateModel.set} - Method for applying merged results to state
     *
     * @public
     * @since 1.0.0
     */
    merge(newObj: Record<string, unknown> | null | undefined, oldObj: Record<string, unknown> | null | undefined): Record<string, unknown> | null | undefined;
    /**
     * Compares an external object with the current value of a state subject for
     * deep equality.
     *
     * This method performs deep equality comparison between a provided object and the current
     * value of a BehaviorSubject stored in either the main {@link StateModel.dir} registry
     * or within a specific group in {@link StateModel.groups}. It leverages the internal
     * {@link StateModel.isEqual} method to provide structural comparison rather than reference
     * equality, making it ideal for change detection and validation scenarios.
     *
     * The comparison process follows this hierarchy:
     * 1. First checks for the subject in the main directory registry
     * 2. If not found and a group name is provided, searches within the specified group
     * 3. Returns `undefined` if the subject doesn't exist in either location
     * 4. Performs deep equality comparison if the subject is found
     *
     * @param obj - The external object to compare against the state subject's current value.
     *   Can be any type including primitives, objects, arrays, null, or undefined.
     * @param dirObjName - The name of the state subject to compare against. This identifier
     *   is used to locate the BehaviorSubject in either the main directory or specified group.
     * @param groupName - Optional group name to limit the search to subjects within a specific
     *   group. When `null` (default), searches only in the main directory. When specified,
     *   searches only within the named group if not found in the main directory.
     *
     * @returns `true` if the objects are deeply equal, `false` if they differ in structure
     *   or content, or `undefined` if the specified subject doesn't exist in the target location.
     *
     * @example
     * Compare with main directory subject:
     * ```typescript
     * const userProfile = { id: 1, name: 'John', email: 'john@example.com' };
     * const isEqual = this.stateModel.dirEquals(userProfile, 'currentUser');
     *
     * if (isEqual === true) {
     *   console.log('Objects are identical');
     * } else if (isEqual === false) {
     *   console.log('Objects differ');
     * } else {
     *   console.log('Subject does not exist');
     * }
     * ```
     *
     * @example
     * Compare with grouped subject:
     * ```typescript
     * const settingsData = { theme: 'dark', language: 'en', notifications: true };
     * const isEqual = this.stateModel.dirEquals(settingsData, 'preferences', 'user');
     *
     * // Use result for change detection
     * if (isEqual === false) {
     *   // Settings have changed, update UI or trigger side effects
     *   this.stateModel.set('preferences', settingsData, 'user');
     * }
     * ```
     *
     * @example
     * Form validation use case:
     * ```typescript
     * // Check if form data matches current state before submission
     * const formData = this.userForm.value;
     * const hasChanges = this.stateModel.dirEquals(formData, 'userProfile') === false;
     *
     * if (hasChanges) {
     *   // Enable save button or show unsaved changes indicator
     *   this.showUnsavedChanges = true;
     * }
     * ```
     *
     * @remarks
     * - This method is particularly useful for change detection in reactive forms and components
     * - The comparison is structural, not referential, allowing for meaningful equality checks
     * - Returning `undefined` allows callers to distinguish between "different values" and "subject not found"
     * - Performance scales with object complexity due to deep comparison algorithm
     *
     * @see {@link StateModel.isEqual} - The underlying deep equality comparison method
     * @see {@link StateModel.dir} - Main state subject registry searched by this method
     * @see {@link StateModel.groups} - Grouped state registry searched when group name is specified
     * @see {@link StateModel.has} - Method to check subject existence without value comparison
     *
     * @public
     * @since 1.0.0
     */
    dirEquals(obj: unknown, dirObjName: string, groupName?: string | null): boolean | undefined;
    /**
     * Merges a new object with the current value of a state subject, updating the subject if changes are detected.
     *
     * This method provides intelligent merging capabilities by combining a new object with the existing
     * value of a BehaviorSubject stored in either the main {@link StateModel.dir} registry or within
     * a specific group in {@link StateModel.groups}. It leverages the internal {@link StateModel.merge}
     * method for deep merging and automatically updates the state subject only when the merged result
     * differs from the current value, providing optimization for unnecessary operations.
     *
     * The merge operation follows this workflow:
     * 1. Locates the target state subject in the main directory or specified group
     * 2. If the subject doesn't exist, creates it using {@link StateModel.set} with the new object
     * 3. If the subject exists, performs a deep merge of the new object with the current value
     * 4. Updates the subject only if the merged result differs from the current value
     * 5. Returns the final merged result for further use
     *
     * This method is ideal for implementing partial state updates, configuration merging, and
     * incremental data modifications without losing existing state properties.
     *
     * @param newObj - The source object to merge with the current state subject value.
     *   Properties from this object take precedence during the merge operation. If not a plain
     *   object (null, undefined, array, etc.), the merge may not behave as expected.
     * @param dirObjName - The name of the state subject to merge with. This identifier is used
     *   to locate the BehaviorSubject in either the main directory or specified group.
     * @param groupName - Optional group name to locate the subject within a hierarchical structure.
     *   When `null` (default), searches in the main directory. When specified, searches within
     *   the named group and creates the subject there if it doesn't exist.
     *
     * @returns The merged object result, or the original `newObj` if the target subject didn't
     *   exist and was newly created. Returns `undefined` if the merge operation cannot be completed.
     *
     * @example
     * Merge with existing main directory subject:
     * ```typescript
     * // Existing state
     * this.stateModel.set('userProfile', { name: 'John', email: 'john@example.com', age: 30 });
     *
     * // Merge partial updates
     * const updates = { email: 'john.doe@example.com', city: 'New York' };
     * const result = this.stateModel.dirMerge(updates, 'userProfile');
     * // Result: { name: 'John', email: 'john.doe@example.com', age: 30, city: 'New York' }
     * ```
     *
     * @example
     * Merge with grouped subject:
     * ```typescript
     * // Existing grouped state
     * this.stateModel.set('preferences', { theme: 'light', language: 'en' }, 'settings');
     *
     * // Merge new preferences
     * const newPrefs = { theme: 'dark', notifications: true };
     * const result = this.stateModel.dirMerge(newPrefs, 'preferences', 'settings');
     * // Result: { theme: 'dark', language: 'en', notifications: true }
     * ```
     *
     * @example
     * Auto-creation when subject doesn't exist:
     * ```typescript
     * // Subject doesn't exist yet
     * const initialData = { status: 'active', priority: 'high' };
     * const result = this.stateModel.dirMerge(initialData, 'taskState');
     * // Creates new subject with initialData and returns it
     * ```
     *
     * @example
     * Nested object merging:
     * ```typescript
     * // Existing nested state
     * this.stateModel.set('appConfig', {
     *   ui: { theme: 'light', sidebar: 'expanded' },
     *   api: { timeout: 5000, retries: 3 }
     * });
     *
     * // Merge partial nested updates
     * const updates = { ui: { theme: 'dark' }, api: { timeout: 8000 } };
     * const result = this.stateModel.dirMerge(updates, 'appConfig');
     * // Result: {
     * //   ui: { theme: 'dark', sidebar: 'expanded' },
     * //   api: { timeout: 8000, retries: 3 }
     * // }
     * ```
     *
     * @remarks
     * - Uses {@link StateModel.merge} internally for deep merging operations
     * - Automatically creates missing subjects using {@link StateModel.set} when needed
     * - Updates subjects only when merged results differ from current values (performance optimization)
     * - Supports both standalone subjects and grouped subjects within hierarchical organization
     * - The merge operation preserves existing properties not present in the new object
     * - Does not affect backup values - only updates current state values
     *
     * @see {@link StateModel.merge} - The underlying deep merge method used by this operation
     * @see {@link StateModel.set} - Method used to create subjects when they don't exist
     * @see {@link StateModel.isEqual} - Method used for change detection optimization
     * @see {@link StateModel.dir} - Main state subject registry
     * @see {@link StateModel.groups} - Grouped state registry for hierarchical organization
     * @see {@link StateModel.dirEquals} - Method for comparing objects with state subjects
     *
     * @public
     * @since 1.0.0
     */
    dirMerge(newObj: Record<string, unknown> | null | undefined, dirObjName: string, groupName?: string | null): Record<string, unknown> | null | undefined;
    /**
     * Provides safe access to a BehaviorSubject with automatic initialization if it doesn't exist.
     *
     * This method serves as the primary access point for retrieving BehaviorSubjects from either
     * the main {@link StateModel.dir} registry or from grouped subjects within {@link StateModel.groups}.
     * It implements a fail-safe pattern by automatically creating missing subjects or groups with
     * `undefined` initial values, enabling reactive subscription patterns even when the target
     * state hasn't been explicitly initialized yet.
     *
     * The method follows a hierarchical search pattern:
     * - For ungrouped subjects: searches in the main directory registry
     * - For grouped subjects: searches within the specified group, creating the group if necessary
     * - Auto-initializes missing subjects using {@link StateModel.initiate} with `undefined` values
     * - Guarantees that a valid BehaviorSubject is always returned for subscription
     *
     * This design pattern supports reactive programming where components can subscribe to state
     * changes before the state producer has set initial values, preventing timing-related issues
     * in component initialization and data flow.
     *
     * @param subjectName - The unique identifier for the BehaviorSubject to retrieve or create.
     *   Must be a non-empty string that serves as the key in the state registry.
     * @param groupName - Optional group name to locate the subject within a hierarchical structure.
     *   When `null` (default), searches in the main directory. When specified, searches within
     *   the named group and creates the group if it doesn't exist.
     *
     * @returns A BehaviorSubject that can be immediately subscribed to. If the subject didn't
     *   exist, it will be initialized with an `undefined` value and can be updated later through
     *   {@link StateModel.set} or {@link StateModel.update} methods.
     *
     * @example
     * Subscribe to an ungrouped subject:
     * ```typescript
     * // Safe subscription even if 'userProfile' doesn't exist yet
     * this.stateModel.observe('userProfile').subscribe(profile => {
     *   if (profile) {
     *     console.log('User profile loaded:', profile);
     *   } else {
     *     console.log('User profile not yet initialized');
     *   }
     * });
     * ```
     *
     * @example
     * Subscribe to a grouped subject:
     * ```typescript
     * // Creates 'users' group and 'currentUser' subject if they don't exist
     * this.stateModel.observe('currentUser', 'users').subscribe(user => {
     *   this.handleUserChange(user);
     * });
     *
     * // Later, another component can set the value
     * this.stateModel.set('currentUser', { id: 1, name: 'John' }, 'users');
     * ```
     *
     * @example
     * Reactive form integration:
     * ```typescript
     * // Component can subscribe before data is loaded
     * ngOnInit() {
     *   this.stateModel.observe('formData').subscribe(data => {
     *     if (data) {
     *       this.form.patchValue(data);
     *     }
     *   });
     * }
     *
     * // Service loads data asynchronously
     * loadFormData() {
     *   this.http.get('/api/form-data').subscribe(data => {
     *     this.stateModel.set('formData', data);
     *   });
     * }
     * ```
     *
     * @remarks
     * - This method is idempotent: multiple calls with the same parameters return the same BehaviorSubject instance
     * - Auto-initialization uses `undefined` as the default value to indicate uninitialized state
     * - The returned BehaviorSubject maintains referential integrity for consistent subscription behavior
     * - Group creation is transparent and doesn't emit notifications to {@link StateModel.updated}
     *
     * @see {@link StateModel.dir} - Main state subject registry accessed by this method
     * @see {@link StateModel.groups} - Grouped state registry for hierarchical organization
     * @see {@link StateModel.initiate} - Method used internally for auto-initialization
     * @see {@link StateModel.has} - Method to check subject existence without auto-creation
     * @see {@link StateModel.set} - Method for setting initial or updated values
     * @see {@link StateModel.update} - Method for modifying existing state values
     *
     * @public
     * @since 1.0.0
     */
    observe(subjectName: string, groupName?: string | null): Observable<StateObjType>;
    observeGroup(groupName: string): Observable<Record<string, BehaviorSubject<StateObjType>>>;
    /**
     * Safely removes a BehaviorSubject from the state management system and cleans up all associated resources.
     *
     * This method performs comprehensive cleanup of state subjects by removing them from the appropriate
     * registry ({@link StateModel.dir} or {@link StateModel.groups}), properly completing the BehaviorSubject
     * to prevent memory leaks, and removing corresponding backup entries to maintain system integrity.
     * The method supports both standalone subjects and grouped subjects with automatic resource cleanup.
     *
     * The removal process includes:
     * - Calling `complete()` on the BehaviorSubject to properly terminate all subscriptions
     * - Removing the subject from the main directory or specified group registry
     * - Cleaning up corresponding backup entries to prevent stale data
     * - Updating group BehaviorSubjects to reflect structural changes when removing grouped subjects
     *
     * @param subjectName - The unique identifier of the BehaviorSubject to remove from the state system.
     *   Must match an existing subject name in either the main directory or specified group.
     * @param groupName - Optional group name containing the subject to remove. When `null` (default),
     *   removes the subject from the main {@link StateModel.dir} registry. When specified, removes
     *   the subject from within the named group in {@link StateModel.groups}.
     *
     * @example
     * Remove a standalone subject:
     * ```typescript
     * // Remove 'userProfile' from main directory
     * this.stateModel.rem('userProfile');
     * // Subject is completed and removed from dir and backups
     * ```
     *
     * @example
     * Remove a grouped subject:
     * ```typescript
     * // Remove 'currentUser' from 'users' group
     * this.stateModel.rem('currentUser', 'users');
     * // Subject is completed and removed from the group and group backups
     * ```
     *
     * @remarks
     * - Safe to call even if the subject doesn't exist (no-op behavior)
     * - Always calls `complete()` before deletion to prevent memory leaks
     * - Group structure is automatically updated when removing grouped subjects
     * - Does not remove empty groups - use {@link StateModel.removeGroup} for complete group removal
     * - Backup cleanup ensures no stale rollback data remains in the system
     *
     * @see {@link StateModel.dir} - Main state subject registry
     * @see {@link StateModel.groups} - Grouped state subject registry
     * @see {@link StateModel.backups} - Backup registry for rollback functionality
     * @see {@link StateModel.groupBackups} - Group-specific backup registry
     * @see {@link StateModel.removeGroup} - Method for removing entire groups
     * @see {@link StateModel.observe} - Method for accessing subjects safely
     *
     * @public
     * @since 1.0.0
     */
    rem(subjectName: string, groupName?: string | null): void;
    /**
     * Completely removes a hierarchical group from the state management system and cleans up all associated resources.
     *
     * This method performs comprehensive cleanup of an entire group by removing it from the {@link StateModel.groups}
     * registry, updating the reactive {@link StateModel.groupList} to reflect the structural change, and clearing
     * all corresponding backup entries from {@link StateModel.groupBackups}. Unlike {@link StateModel.rem} which
     * removes individual subjects, this method eliminates the entire group container and all nested BehaviorSubjects
     * within it.
     *
     * The removal process includes:
     * - Deleting the entire group BehaviorSubject and all nested subject BehaviorSubjects
     * - Removing the group name from the reactive {@link StateModel.groupList}
     * - Clearing all backup data associated with the group to prevent memory leaks
     * - Automatically updating subscribers to the {@link StateModel.groupList} about the structural change
     *
     * @param groupName - The unique identifier of the group to remove from the state management system.
     *   Must match an existing group name in the {@link StateModel.groups} registry. If the group doesn't
     *   exist, the method safely performs no operations without throwing errors.
     *
     * @example
     * Remove an entire user management group:
     * ```typescript
     * // Assume group contains multiple subjects: 'currentUser', 'permissions', 'settings'
     * this.stateModel.removeGroup('users');
     *
     * // All subjects within 'users' group are now inaccessible
     * // Group is removed from groupList array
     * // All backup data for the group is cleared
     * ```
     *
     * @example
     * Reactive cleanup detection:
     * ```typescript
     * // Subscribe to group list changes
     * this.stateModel.groupList.subscribe(groups => {
     *   console.log('Available groups:', groups);
     *   // Will show updated list after removeGroup() is called
     * });
     *
     * // Remove group and observe the change
     * this.stateModel.removeGroup('temporaryData');
     * ```
     *
     * @remarks
     * - Safe to call even if the group doesn't exist (no-op behavior)
     * - All nested BehaviorSubjects are automatically cleaned up with the group removal
     * - Backup data cleanup prevents memory leaks and stale rollback information
     * - The {@link StateModel.groupList} BehaviorSubject automatically notifies subscribers of the change
     * - Use {@link StateModel.rem} instead if you only need to remove individual subjects within a group
     *
     * @see {@link StateModel.groups} - The hierarchical group registry this method modifies
     * @see {@link StateModel.groupList} - Reactive list automatically updated by this method
     * @see {@link StateModel.groupBackups} - Backup registry cleared by this method
     * @see {@link StateModel.loadGroup} - Method for creating new groups
     * @see {@link StateModel.rem} - Method for removing individual subjects within groups
     *
     * @public
     * @since 1.0.0
     */
    removeGroup(groupName: string): void;
    /**
     * Restores a BehaviorSubject to its backup value, effectively rolling back any changes made since the last {@link StateModel.set} operation.
     *
     * This method implements the rollback functionality of the state management system by restoring
     * a BehaviorSubject's value from its corresponding backup entry. It operates on both standalone
     * subjects in the main {@link StateModel.dir} registry and grouped subjects within {@link StateModel.groups}.
     * The restoration only occurs if the current value differs from the backup value, providing
     * optimization for unnecessary operations.
     *
     * Common use cases include:
     * - Reset button functionality in forms and dialogs
     * - Canceling unsaved changes in user interfaces
     * - Implementing undo operations in data entry workflows
     * - Reverting state when dialogs are closed without saving
     *
     * The method performs deep cloning of backup values to prevent reference mutations and uses
     * {@link StateModel.isEqual} for efficient change detection before applying the reset operation.
     *
     * @param subjectName - The unique identifier of the BehaviorSubject to reset. Must correspond
     *   to an existing subject in either the main directory or specified group.
     * @param groupName - Optional group name containing the subject to reset. When `null` (default),
     *   resets the subject from the main {@link StateModel.dir} registry. When specified, resets
     *   the subject from within the named group in {@link StateModel.groups}.
     *
     * @example
     * Reset a standalone subject:
     * ```typescript
     * // Set initial value and backup
     * this.stateModel.set('userForm', { name: 'John', email: 'john@example.com' });
     *
     * // Make changes to the state
     * this.stateModel.update('userForm', { name: 'Jane', email: 'jane@example.com' });
     *
     * // Reset to backup value
     * this.stateModel.reset('userForm');
     * // Current value is now: { name: 'John', email: 'john@example.com' }
     * ```
     *
     * @example
     * Reset a grouped subject:
     * ```typescript
     * // Set initial grouped value
     * this.stateModel.set('preferences', { theme: 'light', lang: 'en' }, 'settings');
     *
     * // Update the grouped subject
     * this.stateModel.update('preferences', { theme: 'dark', lang: 'es' }, 'settings');
     *
     * // Reset grouped subject to backup
     * this.stateModel.reset('preferences', 'settings');
     * // Restored to: { theme: 'light', lang: 'en' }
     * ```
     *
     * @example
     * Integration with UI components:
     * ```typescript
     * // In a component with reset functionality
     * onResetClick(): void {
     *   this.stateModel.reset('formData');
     *   this.form.patchValue(this.stateModel.value('formData'));
     * }
     *
     * onDialogCancel(): void {
     *   this.stateModel.reset('dialogState');
     *   this.dialogRef.close();
     * }
     * ```
     *
     * @remarks
     * - No-op if the subject doesn't exist or has no backup value
     * - No-op if current value equals backup value (optimized for performance)
     * - Uses deep cloning to prevent reference mutations during reset
     * - Does not trigger {@link StateModel.updated} notifications to prevent reset loops
     * - Backup values are created and updated only by the {@link StateModel.set} method
     *
     * @see {@link StateModel.set} - Creates and updates backup values used by this method
     * @see {@link StateModel.backups} - Main backup registry for ungrouped subjects
     * @see {@link StateModel.groupBackups} - Backup registry for grouped subjects
     * @see {@link StateModel.isEqual} - Method used for change detection optimization
     * @see {@link StateModel.value} - Method for retrieving current subject values
     *
     * @public
     * @since 1.0.0
     */
    reset(subjectName: string, groupName?: string | null): void;
    /**
     * Creates or updates a BehaviorSubject with a specified value and establishes a backup for rollback functionality.
     *
     * This method serves as the primary state setting mechanism within the state management system. It creates new
     * BehaviorSubjects or updates existing ones with the provided value, while simultaneously creating or updating
     * corresponding backup entries that enable rollback operations via {@link StateModel.reset}. The method supports
     * both standalone subjects in the main {@link StateModel.dir} registry and hierarchically organized subjects
     * within named groups in {@link StateModel.groups}.
     *
     * Key behaviors include:
     * - Deep cloning of input values to prevent reference mutations
     * - Automatic backup creation/updates for rollback functionality
     * - Early return optimization when setting identical values (via {@link StateModel.isEqual})
     * - Auto-creation of group structures when targeting grouped subjects
     * - Notification emission through {@link StateModel.updated} for reactive subscribers
     *
     * Unlike {@link StateModel.update}, this method always updates the backup registry, making it ideal for
     * establishing "checkpoint" values that can be restored later. This pattern is commonly used in form
     * controls, dialog components, and any UI requiring save/cancel functionality.
     *
     * @param subjectName - The unique identifier for the BehaviorSubject to create or update.
     *   Must be a non-empty string that serves as the key in the state registry.
     * @param initialValue - The value to assign to the BehaviorSubject and store as the backup value.
     *   This value is deep cloned to prevent external reference mutations.
     * @param groupName - Optional group name for hierarchical organization. When `null` (default),
     *   the subject is managed in the main directory. When specified, the subject is organized
     *   within the named group, and the group is auto-created if it doesn't exist.
     *
     * @example
     * Set a standalone subject with backup:
     * ```typescript
     * // Creates subject and backup for rollback capability
     * this.stateModel.set('userProfile', { name: 'John', email: 'john@example.com' });
     *
     * // Later modifications don't affect the backup
     * this.stateModel.update('userProfile', { name: 'Jane', email: 'jane@example.com' });
     *
     * // Reset restores the original set() value
     * this.stateModel.reset('userProfile'); // Back to John's data
     * ```
     *
     * @example
     * Set a grouped subject with hierarchical organization:
     * ```typescript
     * // Creates 'settings' group and 'theme' subject within it
     * this.stateModel.set('theme', { mode: 'dark', accent: 'blue' }, 'settings');
     * this.stateModel.set('language', 'en-US', 'settings');
     *
     * // Access grouped subject
     * this.stateModel.observe('theme', 'settings').subscribe(theme => {
     *   console.log('Theme changed:', theme);
     * });
     * ```
     *
     * @example
     * Form checkpoint pattern:
     * ```typescript
     * // Establish initial form state as checkpoint
     * const formData = { name: '', email: '', preferences: {} };
     * this.stateModel.set('formState', formData);
     *
     * // User makes changes via updates (backups remain unchanged)
     * onFormChange(newData: any) {
     *   this.stateModel.update('formState', newData);
     * }
     *
     * // Cancel button restores checkpoint
     * onCancel() {
     *   this.stateModel.reset('formState'); // Back to initial formData
     * }
     *
     * // Save button establishes new checkpoint
     * onSave() {
     *   const currentData = this.stateModel.value('formState');
     *   this.stateModel.set('formState', currentData); // New backup point
     * }
     * ```
     *
     * @remarks
     * - Values are automatically deep cloned to prevent external mutations
     * - Setting identical values triggers early return (no notification or backup update)
     * - Group structures are transparently created when needed
     * - Backup values are only updated by this method, not by {@link StateModel.update}
     * - The {@link StateModel.updated} BehaviorSubject emits the subject name after successful operations
     *
     * @see {@link StateModel.update} - For modifying subjects without affecting backups
     * @see {@link StateModel.reset} - For restoring subjects from backup values
     * @see {@link StateModel.observe} - For safely accessing and subscribing to subjects
     * @see {@link StateModel.backups} - Main backup registry updated by this method
     * @see {@link StateModel.groupBackups} - Group backup registry for hierarchical subjects
     * @see {@link StateModel.isEqual} - Deep equality method used for change detection
     *
     * @public
     * @since 1.0.0
     */
    set(subjectName: string, initialValue: StateObjType, groupName?: string | null): void;
    /**
     * Retrieves a deep clone of the current value from a BehaviorSubject in the state management system.
     *
     * This method provides safe access to the current value of a BehaviorSubject stored in either
     * the main {@link StateModel.dir} registry or within a specific group in {@link StateModel.groups}.
     * The returned value is always a deep clone to prevent external mutations from affecting the
     * internal state management system, ensuring data integrity and preventing unintended side effects.
     *
     * The method searches hierarchically:
     * - For ungrouped subjects: retrieves from the main directory registry
     * - For grouped subjects: retrieves from within the specified group
     * - Returns `null` if the subject or group doesn't exist
     * - Handles special cases like `false` values correctly without treating them as falsy
     *
     * This is the recommended way to access current state values for display, computation, or
     * external API calls, as it provides a safe snapshot without risking state corruption.
     *
     * @param subjectName - The unique identifier of the BehaviorSubject whose value should be retrieved.
     *   Must correspond to an existing subject in either the main directory or specified group.
     * @param groupName - Optional group name containing the target subject. When `null` (default),
     *   searches in the main {@link StateModel.dir} registry. When specified, searches within
     *   the named group in {@link StateModel.groups}.
     *
     * @returns A deep clone of the BehaviorSubject's current value, preserving the original data
     *   type and structure. Returns `null` if the subject doesn't exist in the specified location
     *   or if the target group doesn't exist. Returns `false` explicitly when the stored value
     *   is boolean `false` to distinguish it from other falsy values.
     *
     * @example
     * Retrieve value from main directory:
     * ```typescript
     * // Get user profile data safely
     * const userProfile = this.stateModel.value('userProfile');
     * if (userProfile) {
     *   console.log('User name:', userProfile.name);
     *   // Mutations to userProfile won't affect the state
     *   userProfile.name = 'Modified'; // Safe - doesn't change state
     * }
     * ```
     *
     * @example
     * Retrieve value from a grouped subject:
     * ```typescript
     * // Get settings from specific group
     * const themeSettings = this.stateModel.value('theme', 'userSettings');
     * if (themeSettings) {
     *   this.applyTheme(themeSettings);
     * }
     * ```
     *
     * @example
     * Handle boolean false values correctly:
     * ```typescript
     * // Set a boolean false value
     * this.stateModel.set('feature', false);
     *
     * // Retrieve handles false correctly
     * const featureEnabled = this.stateModel.value('feature');
     * console.log(featureEnabled); // false (not null)
     * console.log(featureEnabled === false); // true
     * ```
     *
     * @example
     * Safe data manipulation pattern:
     * ```typescript
     * // Get current form data
     * const formData = this.stateModel.value('userForm');
     * if (formData) {
     *   // Create modified copy for submission
     *   const submissionData = {
     *     ...formData,
     *     lastModified: new Date(),
     *     submitted: true
     *   };
     *
     *   // Submit without affecting original state
     *   this.submitForm(submissionData);
     * }
     * ```
     *
     * @remarks
     * - Values are deep cloned using `JSON.parse(JSON.stringify())` for complete isolation
     * - Special handling for `false` values to prevent incorrect falsy evaluation
     * - Returns `null` consistently for non-existent subjects to distinguish from `undefined` values
     * - Performance scales with object complexity due to deep cloning operation
     * - Does not trigger any state changes or notifications
     *
     * @see {@link StateModel.observe} - For reactive subscription to state changes
     * @see {@link StateModel.set} - For setting state values
     * @see {@link StateModel.update} - For modifying existing state values
     * @see {@link StateModel.has} - For checking subject existence without retrieving values
     * @see {@link StateModel.dir} - Main state subject registry
     * @see {@link StateModel.groups} - Grouped state subject registry
     *
     * @public
     * @since 1.0.0
     */
    value(subjectName: string, groupName?: string | null): any;
    /**
     * Modifies the value of an existing BehaviorSubject without affecting backup values used for rollback operations.
     *
     * This method provides non-destructive state updates by modifying the current value of a BehaviorSubject
     * while preserving the backup values established by {@link StateModel.set}. It supports both standalone
     * subjects in the main {@link StateModel.dir} registry and grouped subjects within {@link StateModel.groups}.
     * When the target subject doesn't exist, the method automatically delegates to {@link StateModel.set}
     * to create the subject with proper backup initialization.
     *
     * Key behaviors include:
     * - Deep cloning of input values to prevent reference mutations
     * - Preservation of existing backup values (unlike {@link StateModel.set})
     * - Early return optimization when updating to identical values (via {@link StateModel.isEqual})
     * - Auto-creation of subjects via {@link StateModel.set} when they don't exist
     * - Auto-creation of group structures when targeting non-existent grouped subjects
     *
     * This method is ideal for temporary state changes, form input handling, and any scenario where
     * you want to modify state while maintaining the ability to rollback to previously set checkpoint values.
     *
     * @param subjectName - The unique identifier of the BehaviorSubject to update. Must be a non-empty
     *   string that serves as the key in the state registry.
     * @param newValue - The new value to assign to the BehaviorSubject. This value is deep cloned
     *   to prevent external reference mutations. Can be any valid {@link StateObjType} including
     *   primitives, objects, arrays, or null/undefined values.
     * @param groupName - Optional group name for hierarchical organization. When `null` (default),
     *   updates the subject in the main directory. When specified, updates the subject within
     *   the named group, creating the group if it doesn't exist.
     *
     * @example
     * Update existing subject without affecting backup:
     * ```typescript
     * // Set initial value with backup
     * this.stateModel.set('userForm', { name: 'John', email: 'john@example.com' });
     *
     * // Update without changing backup
     * this.stateModel.update('userForm', { name: 'Jane', email: 'jane@example.com' });
     *
     * // Backup still contains original data
     * this.stateModel.reset('userForm'); // Restores to John's data
     * ```
     *
     * @example
     * Form input handling pattern:
     * ```typescript
     * // Initialize form with checkpoint
     * this.stateModel.set('formData', this.initialFormState);
     *
     * // Handle user input changes
     * onInputChange(fieldName: string, value: any) {
     *   const currentData = this.stateModel.value('formData');
     *   const updatedData = { ...currentData, [fieldName]: value };
     *   this.stateModel.update('formData', updatedData);
     * }
     *
     * // Reset discards all updates, restoring checkpoint
     * onReset() {
     *   this.stateModel.reset('formData');
     * }
     * ```
     *
     * @example
     * Auto-creation when subject doesn't exist:
     * ```typescript
     * // Subject doesn't exist yet - delegates to set() method
     * this.stateModel.update('newSubject', { created: true });
     * // Equivalent to: this.stateModel.set('newSubject', { created: true });
     * ```
     *
     * @remarks
     * - Values are automatically deep cloned to prevent external mutations
     * - Updating to identical values triggers early return (no state change or notification)
     * - Does not emit {@link StateModel.updated} notifications for existing subjects (only when creating new ones via delegation)
     * - Backup values remain unchanged, preserving rollback capability to the last {@link StateModel.set} operation
     * - Group structures are transparently created when targeting non-existent groups
     *
     * @see {@link StateModel.set} - For creating subjects with backup checkpoints
     * @see {@link StateModel.reset} - For restoring subjects from backup values
     * @see {@link StateModel.observe} - For reactive subscription to state changes
     * @see {@link StateModel.isEqual} - Deep equality method used for change detection
     * @see {@link StateObjType} - Type definition for acceptable values
     *
     * @public
     * @since 1.0.0
     */
    update(subjectName: string, newValue: StateObjType, groupName?: string | null): void;
    static ɵfac: i0.ɵɵFactoryDeclaration<StateModel, never>;
    static ɵprov: i0.ɵɵInjectableDeclaration<StateModel>;
}