@abdokouta/react-support 1.1.0 → 1.2.0

package/dist/index.d.ts

@@ -1,6 +1,4 @@
 export { Collection as CollectJsCollection } from 'collect.js';
-import { Newable, ModuleContainer, ServiceIdentifier } from '@abdokouta/react-di';
-export { ModuleContainer, Newable, ServiceIdentifier } from '@abdokouta/react-di';
 
 /**
  * Laravel-style string manipulation class
@@ -869,55 +867,15 @@ declare class SetCollection<T = any> {
 declare function collectSet<T>(items?: Iterable<T>): SetCollection<T>;
 
 /**
- * @fileoverview Base registry implementation
- *
- * This file provides a generic base registry class that uses the Collection
- * interface for storage. It provides a consistent API for all registry
- * implementations across the application.
- *
- * Key Features:
- * - Generic type support for any item type
- * - Default item support (fallback when item not found)
- * - Validation hooks (before add, after add)
- * - Collection-based storage (efficient O(1) operations)
- * - Type-safe API
- * - Consistent interface across all registries
+ * Custom driver creator function.
  *
- * Use Cases:
- * - Theme registry (storing and retrieving themes)
- * - Token registry (managing design tokens)
- * - Plugin registry (managing plugins)
- * - Configuration registry (storing configs)
- * - Any key-value registry needs
- *
- * @module @pixielity/support
- * @category Registries
+ * Receives the raw instance config and returns a driver instance.
  */
-/**
- * Collection interface for registry storage
- */
-interface Collection<T> {
-    add(key: string, value: T): void;
-    get(key: string): T | undefined;
-    getAll(): T[];
-    getKeys(): string[];
-    getAsRecord(): Record<string, T>;
-    has(key: string): boolean;
-    remove(key: string): boolean;
-    clear(): void;
-    size(): number;
-    isEmpty(): boolean;
-    forEach(callback: (value: T, key: string) => void): void;
-    map<U>(callback: (value: T, key: string) => U): U[];
-    filter(predicate: (value: T, key: string) => boolean): T[];
-    find(predicate: (value: T, key: string) => boolean): T | undefined;
-}
+type DriverCreator<T> = (config: Record<string, any>) => T;
+
 /**
  * Validation result for registry operations
  *
- * Used by validation hooks to indicate whether an operation
- * should proceed or be rejected.
- *
  * @example
  * ```typescript
  * const result: ValidationResult = {
@@ -936,6 +894,7 @@ interface ValidationResult {
      */
     error?: string;
 }
+
 /**
  * Base registry options
  *
@@ -974,776 +933,396 @@ interface BaseRegistryOptions<T> {
      */
     afterAdd?: (key: string, item: T) => void;
 }
+
 /**
- * Base registry class
- *
- * A generic registry implementation that provides a consistent API for
- * storing and retrieving items by key. Uses the Collection interface
- * for efficient storage with O(1) operations.
- *
- * This class extends Collection functionality by adding:
- * - Default item support
- * - Validation hooks
- * - Consistent registry API
- *
- * All Collection methods are directly accessible on the registry instance.
- *
- * Performance Characteristics:
- * - register(): O(1) + validation time
- * - get(): O(1)
- * - has(): O(1)
- * - remove(): O(1)
- * - getAll(): O(n)
- * - clear(): O(1)
- *
- * @template T - The type of items stored in the registry
- *
- * @example
- * ```typescript
- * // Create a theme registry
- * const themeRegistry = new BaseRegistry<Theme>({
- *   defaultItem: defaultTheme,
- *   validateBeforeAdd: (key, theme) => {
- *     if (!theme.name) {
- *       return { valid: false, error: 'Theme must have a name' };
- *     }
- *     return { valid: true };
- *   }
- * });
- *
- * // Register themes
- * themeRegistry.register('blue', blueTheme);
- * themeRegistry.register('red', redTheme);
+ * Collection interface for registry storage.
  *
- * // Get a theme
- * const theme = themeRegistry.get('blue');
+ * Defines the contract for a key-value store used internally by
+ * registries. Every method operates on string keys and generic values,
+ * providing O(1) lookups, inserts, and deletes when backed by a Map.
  *
- * // Get all themes
- * const allThemes = themeRegistry.getAll();
- *
- * // Check if theme exists
- * if (themeRegistry.has('blue')) {
- *   console.log('Blue theme exists');
- * }
- * ```
- *
- * @example
- * ```typescript
- * // Create a simple token registry
- * const tokenRegistry = new BaseRegistry<Token>();
- *
- * tokenRegistry.register('primary', { value: '#0000FF' });
- * tokenRegistry.register('secondary', { value: '#FF0000' });
- *
- * const allTokens = tokenRegistry.getAll();
- * console.log(allTokens.length); // 2
- * ```
+ * @typeParam T - The type of values stored in the collection
  */
-declare class BaseRegistry<T> implements Collection<T> {
-    /**
-     * Internal collection for storing registry items
-     *
-     * Uses Collection interface for flexible storage implementation.
-     * By default, uses MapCollection for O(1) operations.
-     */
-    protected collection: Collection<T>;
-    /**
-     * Default item to return when requested item is not found
-     *
-     * If set, get() will return this item instead of undefined
-     * when the requested key doesn't exist in the registry.
-     */
-    protected defaultItem?: T;
-    /**
-     * Validation hook called before adding an item
-     *
-     * If provided, this function is called before every register()
-     * operation to validate the item. If validation fails, the
-     * item is not added and an error is thrown.
-     */
-    protected validateBeforeAdd?: (key: string, item: T) => ValidationResult;
-    /**
-     * Hook called after an item is successfully added
-     *
-     * If provided, this function is called after every successful
-     * register() operation. Useful for side effects like logging
-     * or triggering dependent updates.
-     */
-    protected afterAdd?: (key: string, item: T) => void;
-    /**
-     * Creates a new BaseRegistry instance
-     *
-     * Initializes the registry with optional configuration for default
-     * item and validation hooks. By default, uses MapCollection for storage.
-     *
-     * @param options - Registry configuration options
-     *
-     * @example
-     * ```typescript
-     * // Simple registry without options
-     * const registry = new BaseRegistry<Theme>();
-     * ```
-     *
-     * @example
-     * ```typescript
-     * // Registry with default item
-     * const registry = new BaseRegistry<Theme>({
-     *   defaultItem: defaultTheme
-     * });
-     * ```
-     *
-     * @example
-     * ```typescript
-     * // Registry with validation
-     * const registry = new BaseRegistry<Theme>({
-     *   validateBeforeAdd: (key, theme) => {
-     *     if (!theme.name) {
-     *       return { valid: false, error: 'Theme must have a name' };
-     *     }
-     *     return { valid: true };
-     *   },
-     *   afterAdd: (key, theme) => {
-     *     console.log(`Registered theme: ${theme.name}`);
-     *   }
-     * });
-     * ```
-     */
-    constructor(options?: BaseRegistryOptions<T>);
-    /**
-     * Register an item in the registry
-     *
-     * Adds or updates an item in the registry with the specified key.
-     * If an item with the same key already exists, it will be replaced.
-     *
-     * If a validation hook is configured, it will be called before adding
-     * the item. If validation fails, an error is thrown and the item is
-     * not added.
-     *
-     * If an afterAdd hook is configured, it will be called after the item
-     * is successfully added.
-     *
-     * Time Complexity: O(1) + validation time
-     *
-     * @param key - Unique identifier for the item
-     * @param item - Item to register
-     * @throws Error if validation fails
-     *
-     * @example
-     * ```typescript
-     * const registry = new BaseRegistry<Theme>();
-     *
-     * // Register a theme
-     * registry.register('blue', {
-     *   name: 'Blue',
-     *   colors: { accent: '#0000FF' }
-     * });
-     *
-     * // Update existing theme
-     * registry.register('blue', {
-     *   name: 'Blue',
-     *   colors: { accent: '#0066FF' }
-     * });
-     * ```
-     */
-    register(key: string, item: T): void;
+interface Collection<T> {
     /**
-     * Add an item to the collection (alias for register)
+     * Add or replace a value under the given key.
      *
-     * This method is part of the Collection interface.
-     * It delegates to register() to ensure validation hooks are called.
-     *
-     * Time Complexity: O(1) + validation time
-     *
-     * @param key - Unique identifier for the item
-     * @param value - Item to add
+     * @param key   - Unique string identifier
+     * @param value - Value to store
      */
     add(key: string, value: T): void;
     /**
-     * Get an item from the registry
-     *
-     * Retrieves an item by its key. If the item doesn't exist:
-     * - Returns the default item if one was configured
-     * - Returns undefined if no default item was configured
-     *
-     * Time Complexity: O(1)
+     * Retrieve a value by its key.
      *
-     * @param key - Item identifier
-     * @returns Item if found, default item if configured, or undefined
-     *
-     * @example
-     * ```typescript
-     * const theme = registry.get('blue');
-     * ```
+     * @param key - The key to look up
+     * @returns The stored value, or `undefined` if the key does not exist
      */
     get(key: string): T | undefined;
     /**
-     * Get all items in the registry
-     *
-     * Returns an array containing all items in the registry.
-     * The order of items depends on the collection implementation
-     * (MapCollection maintains insertion order).
-     *
-     * Time Complexity: O(n) where n is the number of items
+     * Return every value in the collection as an array.
      *
-     * @returns Array of all items in the registry
+     * Iteration order matches insertion order (Map semantics).
      *
-     * @example
-     * ```typescript
-     * const allThemes = registry.getAll();
-     * ```
+     * @returns An array of all stored values
      */
     getAll(): T[];
     /**
-     * Get all keys in the registry
+     * Return every key in the collection as an array.
      *
-     * Returns an array containing all keys in the registry.
-     * Useful for iteration or checking what items are registered.
-     *
-     * Time Complexity: O(n) where n is the number of items
-     *
-     * @returns Array of all keys in the registry
-     *
-     * @example
-     * ```typescript
-     * const keys = registry.getKeys();
-     * ```
+     * @returns An array of all registered keys
      */
     getKeys(): string[];
     /**
-     * Get registry as a record object
-     *
-     * Converts the registry to a plain JavaScript object (record)
-     * with keys mapping to values. Useful for serialization.
+     * Convert the collection to a plain record object.
      *
-     * Time Complexity: O(n) where n is the number of items
+     * Useful for serialisation or passing data to APIs that
+     * expect a simple `Record<string, T>`.
      *
-     * @returns Record object with keys mapping to values
-     *
-     * @example
-     * ```typescript
-     * const record = registry.getAsRecord();
-     * ```
+     * @returns A shallow copy of the collection as a record
      */
     getAsRecord(): Record<string, T>;
     /**
-     * Check if an item is registered
-     *
-     * Checks whether an item with the specified key exists in the registry.
-     * Does not check the value, only the presence of the key.
-     *
-     * Time Complexity: O(1)
+     * Check whether a key exists in the collection.
      *
-     * @param key - Item identifier to check
-     * @returns True if item is registered, false otherwise
-     *
-     * @example
-     * ```typescript
-     * if (registry.has('blue')) {
-     *   console.log('Blue theme exists');
-     * }
-     * ```
+     * @param key - The key to test
+     * @returns `true` if the key is present
      */
     has(key: string): boolean;
     /**
-     * Remove an item from the registry
-     *
-     * Removes an item with the specified key from the registry.
-     * Returns true if the item was removed, false if it didn't exist.
+     * Remove a key and its associated value.
      *
-     * Time Complexity: O(1)
-     *
-     * @param key - Item identifier to remove
-     * @returns True if item was removed, false if it didn't exist
-     *
-     * @example
-     * ```typescript
-     * const removed = registry.remove('blue');
-     * ```
+     * @param key - The key to remove
+     * @returns `true` if the key existed and was removed, `false` otherwise
      */
     remove(key: string): boolean;
     /**
-     * Clear all items from the registry
-     *
-     * Removes all items from the registry, leaving it empty.
-     * This operation is irreversible.
-     *
-     * Time Complexity: O(1)
-     *
-     * @example
-     * ```typescript
-     * registry.clear();
-     * ```
+     * Remove all entries from the collection.
      */
     clear(): void;
     /**
-     * Get the number of items in the registry
-     *
-     * Returns the total count of items currently registered.
-     *
-     * Time Complexity: O(1)
+     * Return the number of entries in the collection.
      *
-     * @returns Number of items in the registry
-     *
-     * @example
-     * ```typescript
-     * console.log(registry.size()); // 2
-     * ```
+     * @returns The current entry count
      */
     size(): number;
     /**
-     * Check if the registry is empty
-     *
-     * Returns true if the registry contains no items, false otherwise.
-     * This is a convenience method equivalent to checking if size() === 0.
+     * Check whether the collection contains zero entries.
      *
-     * Time Complexity: O(1)
-     *
-     * @returns True if registry has no items, false otherwise
-     *
-     * @example
-     * ```typescript
-     * console.log(registry.isEmpty()); // true
-     * ```
+     * @returns `true` when `size() === 0`
      */
     isEmpty(): boolean;
     /**
-     * Iterate over all items in the registry
-     *
-     * Executes a callback function for each item in the registry.
-     * Items are iterated in insertion order (for MapCollection).
-     *
-     * Time Complexity: O(n) where n is the number of items
+     * Execute a callback for every entry in insertion order.
      *
-     * @param callback - Function to call for each item (value, key)
-     *
-     * @example
-     * ```typescript
-     * registry.forEach((theme, key) => {
-     *   console.log(`${key}: ${theme.name}`);
-     * });
-     * ```
+     * @param callback - Receives `(value, key)` for each entry
      */
     forEach(callback: (value: T, key: string) => void): void;
     /**
-     * Map over all items in the registry
-     *
-     * Transforms each item in the registry using a callback function
-     * and returns an array of the transformed values.
-     *
-     * Time Complexity: O(n) where n is the number of items
+     * Transform every entry and collect the results into an array.
      *
-     * @template U - The type of the transformed items
-     * @param callback - Function to transform each item (value, key) => U
-     * @returns Array of transformed items
-     *
-     * @example
-     * ```typescript
-     * const names = registry.map(theme => theme.name);
-     * ```
+     * @typeParam U - The return type of the mapping function
+     * @param callback - Receives `(value, key)` and returns the mapped value
+     * @returns An array of mapped results in insertion order
      */
     map<U>(callback: (value: T, key: string) => U): U[];
     /**
-     * Filter items in the registry
-     *
-     * Returns an array of items that pass the test implemented by the
-     * provided predicate function.
+     * Return all values whose entries satisfy the predicate.
      *
-     * Time Complexity: O(n) where n is the number of items
-     *
-     * @param predicate - Function to test each item (value, key) => boolean
-     * @returns Array of items that pass the test
-     *
-     * @example
-     * ```typescript
-     * const darkThemes = registry.filter(theme => theme.isDark);
-     * ```
+     * @param predicate - Receives `(value, key)` and returns `true` to keep
+     * @returns An array of matching values
      */
     filter(predicate: (value: T, key: string) => boolean): T[];
     /**
-     * Find an item in the registry
-     *
-     * Returns the first item that satisfies the provided predicate function.
-     * Returns undefined if no item passes the test.
-     *
-     * Time Complexity: O(n) worst case, O(1) best case
+     * Return the first value whose entry satisfies the predicate.
      *
-     * @param predicate - Function to test each item (value, key) => boolean
-     * @returns First item that passes the test, or undefined
-     *
-     * @example
-     * ```typescript
-     * const defaultTheme = registry.find(theme => theme.isDefault);
-     * ```
+     * @param predicate - Receives `(value, key)` and returns `true` to match
+     * @returns The first matching value, or `undefined` if none match
      */
     find(predicate: (value: T, key: string) => boolean): T | undefined;
 }
 
 /**
- * @fileoverview Facade interfaces
+ * @fileoverview Base registry implementation
  *
- * Defines the interfaces for the Facade pattern implementation.
- * Facades provide a static interface to services resolved from the DI container.
+ * A generic key-value registry backed by {@link MapCollection}.
+ * Provides O(1) lookups, optional default values, and validation hooks.
  *
- * @module @abdokouta/react-support
- * @category Facades
+ * @module @abdokouta/support
+ * @category Registries
  */
+
 /**
- * Application interface for facade resolution
+ * Base registry class
+ *
+ * Stores items by string key using {@link MapCollection} for O(1) operations.
+ * Adds default-item fallback, before-add validation, and after-add hooks
+ * on top of the raw collection.
+ *
+ * @typeParam T - The type of items stored in the registry
+ *
+ * @example
+ * ```typescript
+ * const registry = new BaseRegistry<Theme>({
+ *   defaultItem: defaultTheme,
+ *   validateBeforeAdd: (key, theme) => {
+ *     if (!theme.name) return { valid: false, error: 'Theme must have a name' };
+ *     return { valid: true };
+ *   },
+ * });
  *
- * This interface represents the minimal contract that an application/container
- * must implement to work with facades. It mirrors the Laravel Application contract.
+ * registry.register('blue', blueTheme);
+ * registry.get('blue');   // blueTheme
+ * registry.get('nope');   // defaultTheme
+ * ```
  */
-interface FacadeApplication {
+declare class BaseRegistry<T> implements Collection<T> {
+    /**
+     * Internal map-based storage.
+     */
+    protected readonly storage: MapCollection<string, T>;
     /**
-     * Resolve a service from the container
+     * Fallback value returned by {@link get} when a key is missing.
+     */
+    protected defaultItem?: T;
+    /**
+     * Optional validation executed before every {@link register} call.
+     */
+    protected validateBeforeAdd?: (key: string, item: T) => ValidationResult;
+    /**
+     * Optional callback executed after a successful {@link register}.
+     */
+    protected afterAdd?: (key: string, item: T) => void;
+    /**
+     * Create a new registry.
      *
-     * @param abstract - Service identifier (string, symbol, or class)
-     * @returns The resolved service instance
+     * @param options - Optional default item, validation, and lifecycle hooks
      */
-    get<T>(abstract: string | symbol | (new (...args: unknown[]) => T)): T;
+    constructor(options?: BaseRegistryOptions<T>);
     /**
-     * Check if a service has been resolved
+     * Register (add or replace) an item.
+     *
+     * Runs the `validateBeforeAdd` hook first; throws on failure.
+     * Fires the `afterAdd` hook on success.
      *
-     * @param abstract - Service identifier
-     * @returns True if the service has been resolved
+     * @param key  - Unique identifier
+     * @param item - Value to store
+     * @throws Error if validation fails
      */
-    resolved?(abstract: string | symbol): boolean;
+    register(key: string, item: T): void;
     /**
-     * Register a callback to run after a service is resolved
+     * @inheritdoc — delegates to {@link register} so hooks still fire.
+     */
+    add(key: string, value: T): void;
+    /**
+     * Retrieve an item by key.
+     *
+     * Falls back to {@link defaultItem} when the key is not found.
      *
-     * @param abstract - Service identifier
-     * @param callback - Callback to run after resolution
+     * @param key - Item identifier
+     * @returns The stored value, the default item, or `undefined`
+     */
+    get(key: string): T | undefined;
+    /**
+     * Return every stored value in insertion order.
+     */
+    getAll(): T[];
+    /**
+     * Return every registered key in insertion order.
+     */
+    getKeys(): string[];
+    /**
+     * Convert the registry to a plain `Record<string, T>`.
      */
-    afterResolving?(abstract: string | symbol, callback: (service: unknown, app: FacadeApplication) => void): void;
+    getAsRecord(): Record<string, T>;
     /**
-     * Bind an instance to the container
+     * Check whether a key exists.
+     */
+    has(key: string): boolean;
+    /**
+     * Remove an item by key.
      *
-     * @param abstract - Service identifier
-     * @param instance - Instance to bind
+     * @returns `true` if the key existed and was removed
      */
-    instance?(abstract: string | symbol, instance: unknown): void;
-}
-/**
- * Fake interface for testing
- *
- * Facades can be swapped with fakes for testing purposes.
- * Any object implementing this interface is considered a fake.
- */
-interface Fake {
+    remove(key: string): boolean;
+    /**
+     * Remove all items from the registry.
+     */
+    clear(): void;
     /**
-     * Marker to identify fake instances
+     * Return the number of registered items.
      */
-    readonly __isFake: true;
+    size(): number;
+    /**
+     * Return `true` when the registry is empty.
+     */
+    isEmpty(): boolean;
+    /**
+     * Iterate over every entry in insertion order.
+     */
+    forEach(callback: (value: T, key: string) => void): void;
+    /**
+     * Map every entry to a new value and return the results as an array.
+     */
+    map<U>(callback: (value: T, key: string) => U): U[];
+    /**
+     * Return all values whose entries satisfy the predicate.
+     */
+    filter(predicate: (value: T, key: string) => boolean): T[];
+    /**
+     * Return the first value whose entry satisfies the predicate.
+     */
+    find(predicate: (value: T, key: string) => boolean): T | undefined;
 }
-/**
- * Check if an object is a Fake
- *
- * @param obj - Object to check
- * @returns True if the object is a Fake
- */
-declare function isFake(obj: unknown): obj is Fake;
 
 /**
- * @fileoverview Base Facade implementation
+ * Multiple Instance Manager
  *
- * This file provides the base Facade class that enables static access to
- * services resolved from the DI container. Inspired by Laravel's Facade pattern.
+ * Abstract base class for managing multiple named instances backed by
+ * different drivers. TypeScript adaptation of Laravel's
+ * `MultipleInstanceManager` pattern.
  *
- * Uses @abdokouta/react-di's getModuleContainer to resolve services,
- * enabling facades to work outside of React components.
+ * Concrete managers extend this class and implement:
+ * - `getDefaultInstance()` — which instance name to use by default
+ * - `getInstanceConfig(name)` — read config for a named instance
+ * - `createDriver(driver, config)` — create an instance for a known driver
  *
- * Key Features:
- * - Static interface to container-resolved services
- * - Instance caching for performance
- * - Hot-swapping for testing
- * - Fake detection for test assertions
- * - Works outside React components
- *
- * @module @abdokouta/react-support
- * @category Facades
- */
-
-/**
- * Base Facade class
+ * Config is injected via DI in the concrete manager's constructor using
+ * `@Inject(CONFIG_TOKEN)`. The base class handles lazy resolution,
+ * caching, custom driver registration, and instance lifecycle.
  *
- * Provides a static interface to services resolved from the DI container.
- * Subclasses must implement `getFacadeAccessor()` to specify which service
- * the facade represents.
+ * @typeParam T - The type of instance this manager creates
  *
  * @example
  * ```typescript
- * import { Facade } from '@abdokouta/react-support';
- * import { LoggerService } from './logger.service';
- * import { AppModule } from './app.module';
- *
- * class Log extends Facade {
- *   protected static getFacadeAccessor(): ServiceIdentifier {
- *     return LoggerService;
+ * @Injectable()
+ * class CacheManager extends MultipleInstanceManager<Store> {
+ *   constructor(@Inject(CACHE_CONFIG) private config: CacheModuleOptions) {
+ *     super();
  *   }
- * }
  *
- * // Set the module once at app bootstrap
- * Facade.setFacadeModule(AppModule);
+ *   getDefaultInstance() { return this.config.default; }
+ *   getInstanceConfig(name) { return this.config.stores[name]; }
  *
- * // Use the facade statically anywhere
- * Log.info('Hello, world!');
- * Log.error('Something went wrong');
+ *   protected createDriver(driver, config) {
+ *     switch (driver) {
+ *       case 'memory': return new MemoryStore(config);
+ *       case 'redis':  return new RedisStore(config);
+ *       case 'null':   return new NullStore();
+ *       default: throw new Error(`Driver [${driver}] not supported.`);
+ *     }
+ *   }
+ * }
  * ```
  *
- * @example
- * ```typescript
- * // Swap with a fake for testing
- * const fakeLogs: string[] = [];
- * const fakeLogger = {
- *   __isFake: true as const,
- *   info: (msg: string) => fakeLogs.push(msg),
- *   error: (msg: string) => fakeLogs.push(msg),
- * };
+ * @module services/base-manager
+ */
+
+/**
+ * Abstract base manager for multi-instance, multi-driver services.
  *
- * Log.swap(fakeLogger);
- * Log.info('Test message');
- * expect(fakeLogs).toContain('Test message');
- * ```
+ * @typeParam T - The type of instance managed (e.g., Store, RedisConnection)
  */
-declare abstract class Facade {
+declare abstract class MultipleInstanceManager<T> {
     /**
-     * The root module class for resolving services
+     * Resolved instances, keyed by instance name.
+     * Instances are created once and reused on subsequent calls.
      */
-    protected static moduleClass: Newable | null;
+    private readonly instances;
     /**
-     * The module container instance (cached)
+     * Custom driver creators registered via `extend()`.
+     * Keyed by driver name.
      */
-    protected static container: ModuleContainer | null;
+    private readonly customCreators;
     /**
-     * The resolved object instances
+     * The config key that identifies the driver.
+     * Override in subclasses if your config uses a different field name.
      *
-     * Caches resolved instances by their accessor key for performance.
+     * @default 'driver'
      */
-    protected static resolvedInstance: Map<string | symbol, unknown>;
+    protected readonly driverKey: string;
     /**
-     * Indicates if the resolved instance should be cached
-     *
-     * Set to false in subclasses to always resolve fresh instances.
-     */
-    protected static cached: boolean;
-    /**
-     * Hotswap the underlying instance behind the facade
-     *
-     * Useful for testing - swap the real service with a mock or fake.
+     * Get the default instance name.
      *
-     * @param instance - Instance to swap in
+     * Reads from the injected config (e.g., `this.config.default`).
      *
-     * @example
-     * ```typescript
-     * // In tests
-     * const mockLogger = { info: vi.fn(), error: vi.fn() };
-     * Log.swap(mockLogger);
-     *
-     * // Now Log.info() calls mockLogger.info()
-     * Log.info('test');
-     * expect(mockLogger.info).toHaveBeenCalledWith('test');
-     * ```
+     * @returns The name of the default instance
      */
-    static swap(instance: unknown): void;
+    abstract getDefaultInstance(): string;
     /**
-     * Determines whether a "fake" has been set as the facade instance
+     * Get the configuration for a named instance.
      *
-     * @returns True if the current instance is a Fake
+     * Reads from the injected config (e.g., `this.config.stores[name]`).
      *
-     * @example
-     * ```typescript
-     * if (Log.isFake()) {
-     *   console.log('Using fake logger');
-     * }
-     * ```
+     * @param name - Instance name
+     * @returns The config object, or undefined if not configured
      */
-    static isFake(): boolean;
+    abstract getInstanceConfig(name: string): Record<string, any> | undefined;
     /**
-     * Get the root object behind the facade
+     * Create a driver instance for a known driver type.
      *
-     * Resolves and returns the actual service instance.
+     * Called when no custom creator is registered for the driver.
+     * Implement with a switch/map over your package's built-in drivers.
      *
-     * @returns The resolved service instance
+     * @param driver - The driver name (e.g., 'memory', 'redis', 'smtp')
+     * @param config - The raw instance config
+     * @returns A new driver instance
+     * @throws Error if the driver is not supported
      */
-    static getFacadeRoot<T = unknown>(): T;
+    protected abstract createDriver(driver: string, config: Record<string, any>): T;
     /**
-     * Get the registered name of the component
-     *
-     * Subclasses MUST override this method to specify which service
-     * the facade represents.
+     * Get an instance by name.
      *
-     * @returns Service identifier (string, symbol, or class)
-     * @throws Error if not implemented
+     * Returns a cached instance if available, otherwise resolves and caches it.
+     * If no name is provided, returns the default instance.
      *
-     * @example
-     * ```typescript
-     * class Log extends Facade {
-     *   protected static getFacadeAccessor(): ServiceIdentifier {
-     *     return LoggerService; // or 'logger' string token
-     *   }
-     * }
-     * ```
+     * @param name - Instance name (uses default if omitted)
+     * @returns The resolved instance
+     * @throws Error if the instance is not configured
      */
-    protected static getFacadeAccessor(): ServiceIdentifier;
+    instance(name?: string): T;
     /**
-     * Get a consistent key for the accessor
-     */
-    protected static getAccessorKey(accessor: ServiceIdentifier): string | symbol;
-    /**
-     * Resolve the facade root instance from the container
+     * Register a custom driver creator.
      *
-     * @param identifier - Service identifier
-     * @returns Resolved service instance
-     */
-    protected static resolveFacadeInstance<T>(identifier: ServiceIdentifier<T>): T;
-    /**
-     * Get the module container
+     * Custom creators take priority over built-in drivers.
      *
-     * @returns The module container instance
+     * @param driver - Driver name
+     * @param creator - Factory function that creates an instance from config
+     * @returns this (for chaining)
      */
-    protected static getContainer(): ModuleContainer | null;
+    extend(driver: string, creator: DriverCreator<T>): this;
     /**
-     * Clear a resolved facade instance
+     * Remove a cached instance, forcing re-creation on next access.
      *
-     * @param name - Service identifier to clear (defaults to this facade's accessor)
+     * @param name - Instance name (uses default if omitted)
+     * @returns this (for chaining)
      */
-    static clearResolvedInstance(name?: string | symbol): void;
+    forgetInstance(name?: string): this;
     /**
-     * Clear all resolved instances
-     *
-     * Useful for test cleanup.
+     * Remove all cached instances.
      */
-    static clearResolvedInstances(): void;
+    purge(): void;
     /**
-     * Get the module class
+     * Check if an instance has been resolved and cached.
      *
-     * @returns The module class
+     * @param name - Instance name
      */
-    static getFacadeModule(): Newable | null;
+    hasResolvedInstance(name: string): boolean;
     /**
-     * Set the module class for facade resolution
-     *
-     * Must be called during application bootstrap to enable facades.
-     * Call this AFTER Inversiland.run() or Container.configure().build().
-     *
-     * @param module - The root module class
-     *
-     * @example
-     * ```typescript
-     * // In your app bootstrap (main.tsx)
-     * import { Facade } from '@abdokouta/react-support';
-     * import { Container, ContainerProvider } from '@abdokouta/react-di';
-     * import { AppModule } from './app.module';
-     *
-     * // Initialize container
-     * Container.configure().withModule(AppModule).withDefaults().build();
-     *
-     * // Set facade module
-     * Facade.setFacadeModule(AppModule);
-     *
-     * // Now facades work anywhere
-     * ReactDOM.createRoot(document.getElementById("root")!).render(
-     *   <ContainerProvider module={AppModule}>
-     *     <App />
-     *   </ContainerProvider>
-     * );
-     * ```
+     * Get all resolved instance names.
      */
-    static setFacadeModule(module: Newable | null): void;
+    getResolvedInstances(): string[];
     /**
-     * Set the container directly (alternative to setFacadeModule)
+     * Resolve an instance by name.
      *
-     * @param container - The module container instance
-     */
-    static setFacadeContainer(container: ModuleContainer | null): void;
-    /**
-     * @deprecated Use setFacadeModule instead
-     */
-    static setFacadeApplication(app: FacadeApplication | null): void;
-    /**
-     * @deprecated Use getFacadeModule instead
-     */
-    static getFacadeApplication(): FacadeApplication | null;
-}
-
-/**
- * @fileoverview Facade factory with Proxy support
- *
- * Creates facades with automatic method forwarding using JavaScript Proxy.
- * This enables the Laravel-style `Facade::method()` pattern in TypeScript.
- *
- * @module @abdokouta/react-support
- * @category Facades
- */
-
-/**
- * Facade class type with static methods and proxied service methods
- */
-type FacadeClass<T> = typeof Facade & {
-    getFacadeRoot<R = T>(): R;
-} & {
-    [K in keyof T]: T[K];
-};
-/**
- * Options for creating a facade
- */
-interface CreateFacadeOptions<T> {
-    /**
-     * Service identifier (string token, symbol, or class)
-     */
-    accessor: ServiceIdentifier<T>;
-    /**
-     * Whether to cache the resolved instance
-     * @default true
+     * 1. Reads config via `getInstanceConfig()` (from injected config)
+     * 2. Extracts the driver name from the config
+     * 3. Checks custom creators first
+     * 4. Falls back to `createDriver()`
+     *
+     * @param name - Instance name
+     * @returns A new instance
      */
-    cached?: boolean;
+    private resolve;
 }
-/**
- * Create a facade for a service
- *
- * Creates a Proxy-based facade that forwards all method calls to the
- * resolved service instance. This enables the Laravel-style pattern
- * where you can call methods directly on the facade class.
- *
- * @param options - Facade configuration
- * @returns Proxied facade class
- *
- * @example
- * ```typescript
- * // Define your service interface
- * interface ILogger {
- *   info(message: string): void;
- *   error(message: string): void;
- *   debug(message: string): void;
- * }
- *
- * // Create the facade
- * const Log = createFacade<ILogger>({
- *   accessor: 'logger', // or LoggerService class
- * });
- *
- * // Set module at bootstrap
- * Facade.setFacadeModule(AppModule);
- *
- * // Use it statically
- * Log.info('Hello!');
- * Log.error('Oops!');
- * ```
- */
-declare function createFacade<T extends object>(options: CreateFacadeOptions<T>): FacadeClass<T>;
-/**
- * Create a typed facade class (without proxy)
- *
- * @param accessor - Service identifier
- * @returns Facade class constructor
- */
-declare function createFacadeClass<T>(accessor: ServiceIdentifier<T>): typeof Facade;
-/**
- * Get container from a module class
- *
- * @param moduleClass - The module class
- * @returns ModuleContainer instance
- */
-declare function getContainerFromModule(moduleClass: Newable): ModuleContainer;
 
-export { BaseRegistry, type BaseRegistryOptions, Collection$1 as Collection, type CreateFacadeOptions, Facade, type FacadeApplication, type FacadeClass, type Fake, MapCollection, SetCollection, Str, type ValidationResult, collect, collectMap, collectSet, createFacade, createFacadeClass, getContainerFromModule, isFake };
+export { BaseRegistry, type BaseRegistryOptions, Collection$1 as Collection, type DriverCreator, MapCollection, MultipleInstanceManager, type Collection as RegistryCollection, SetCollection, Str, type ValidationResult, collect, collectMap, collectSet };