import { DependencyLifecycle } from '../../types';
import { IKosDataModel } from '../kosModel';
/**
 * @kosService core.companion
 * @kosApiLevel 13
 */
export interface KosCompanionOptions {
    /**
     * Pattern mode:
     * - 'decorator': Proxy all parent properties transparently (default)
     * - 'composition': Only provide getCompanionParent() method
     */
    mode?: "decorator" | "composition";
    /** Properties to exclude from proxying (only applies in decorator mode). Default: [] */
    excludeProperties?: string[];
    /** Custom parent property name. Default: 'companionParent' */
    parentProperty?: string;
    /**
     * Lifecycle phase at which this companion should be created.
     * Defaults to INIT (created immediately during parent instantiation).
     * Use LOAD to create after parent's load() completes, READY for after ready(), etc.
     *
     * @example
     * ```typescript
     * @kosCompanion({ lifecycle: DependencyLifecycle.LOAD })
     * class CarbAgitatorModel implements IKosDataModel {
     *   // Created after assembly.load() completes
     * }
     * ```
     * @kosApiLevel 15
     */
    lifecycle?: DependencyLifecycle;
}
/**
 * Base interface for all companion models.
 * Provides the getCompanionParent() method available in both decorator and composition modes.
 *
 * @kosService core.companion
 * @kosApiLevel 13
 */
export interface KosCompanionAware<TParent extends IKosDataModel = IKosDataModel> {
    /**
     * Gets the companion's parent model instance.
     * Available in both decorator and composition modes.
     * Provides access to the model this companion extends.
     *
     * @returns The parent model instance that this companion enhances
     */
    getCompanionParent(): TParent;
}
/**
 * Interface for models using @kosCompanion in composition mode.
 * Use TypeScript interface merging to add companion capabilities to your model class.
 *
 * @example
 * ```typescript
 * interface ServiceCompanionModelImpl extends KosCompanionComposition<ServiceModel> {}
 *
 * @kosCompanion({ mode: 'composition' })
 * class ServiceCompanionModelImpl implements IKosDataModel {
 *   // Only getCompanionParent() is available
 *   get serviceInfo() {
 *     const parent = this.getCompanionParent();
 *     return `Service: ${parent.serviceName}`;
 *   }
 * }
 * ```
 *
 * @kosService core.companion
 */
export interface KosCompanionComposition<TParent extends IKosDataModel = IKosDataModel> extends KosCompanionAware<TParent> {
}
/**
 * Interface for models using @kosCompanion in decorator mode (default).
 * Use TypeScript interface merging to add full parent transparency to your model class.
 *
 * @example
 * ```typescript
 * interface BrandCompanionModelImpl extends KosCompanionDecorator<AvailabilityModel> {}
 *
 * @kosCompanion() // defaults to decorator mode
 * class BrandCompanionModelImpl implements IKosDataModel {
 *   // All parent properties are available directly
 *   get brandSpecificProperty() {
 *     return this.name; // 'name' from parent AvailabilityModel
 *   }
 * }
 * ```
 *
 * @kosService core.companion
 */
export interface KosCompanionDecorator<TParent extends IKosDataModel = IKosDataModel> extends KosCompanionAware<TParent> {
}
/**
 * Class decorator that adds companion model capabilities to a KOS model.
 *
 * Supports two patterns:
 * 1. **Decorator Pattern** (default): Transparently proxies all parent properties,
 *    making the companion a drop-in replacement for the parent
 * 2. **Composition Pattern**: Only provides getCompanionParent() method,
 *    keeping parent encapsulated
 *
 * **Important**: Use TypeScript interface merging to get proper type information:
 *
 * ```typescript
 * // Decorator pattern - full transparency
 * interface BrandCompanionModelImpl extends KosCompanionAware<AvailabilityModel> {}
 *
 * @kosModel("brand-companion")
 * @kosCompanion() // defaults to decorator mode
 * class BrandCompanionModelImpl implements IKosDataModel {
 *   // All parent properties are available
 *   get brandSpecificProperty() {
 *     return this.name; // 'name' from parent AvailabilityModel
 *   }
 * }
 *
 * // Composition pattern - encapsulated parent
 * interface ServiceCompanionModelImpl extends KosCompanionAware<ServiceModel> {}
 *
 * @kosModel("service-companion")
 * @kosCompanion({ mode: 'composition' })
 * class ServiceCompanionModelImpl implements IKosDataModel {
 *   // Parent is only accessible via getCompanionParent()
 *   get serviceInfo() {
 *     const parent = this.getCompanionParent();
 *     return `Service: ${parent.serviceName}`;
 *   }
 * }
 * ```
 *
 * @param options Configuration options for the companion decorator
 * @returns A class decorator
 *
 * @example
 * ```typescript
 * // Decorator mode - all parent properties proxied
 * @kosCompanion()
 * class MyCompanion { }
 *
 * // Composition mode - only getCompanionParent() available
 * @kosCompanion({ mode: 'composition' })
 * class MyCompanion { }
 *
 * // Decorator mode with exclusions
 * @kosCompanion({ mode: 'decorator', excludeProperties: ['internalState'] })
 * class MyCompanion { }
 *
 * // Lifecycle-deferred companion creation
 * @kosCompanion({ lifecycle: DependencyLifecycle.LOAD })
 * class DataDrivenCompanion { }
 * ```
 *
 * @category KOS Model Decorator
 * @since 2.1.0
 * @kosService core.companion
 * @kosApiLevel 2
 */
export declare function kosCompanion(options?: KosCompanionOptions): ClassDecorator;
//# sourceMappingURL=kos-companion.d.ts.map