@kosdev-code/kos-ui-sdk 2.0.41 → 2.1.1

package/core/core/decorators/index.d.ts

@@ -1,11 +1,15 @@
 export * from './kos-child';
 export * from './kos-companion';
+export * from './kos-container-aware';
 export * from './kos-context';
+export * from './kos-future-aware';
 export * from './kos-http-decorators';
 export * from './kos-log';
+export * from './kos-logger-aware';
 export * from './kos-model-effect';
 export * from './kos-parent';
 export * from './kos-reference';
+export * from './kos-trouble-aware';
 export * from './kosDependency';
 export * from './kosModel';
 export * from './kosSubscribe';

package/core/core/decorators/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/core/core/decorators/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,uBAAuB,CAAC;AACtC,cAAc,WAAW,CAAC;AAC1B,cAAc,oBAAoB,CAAC;AACnC,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/core/core/decorators/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,WAAW,CAAC;AAC1B,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,YAAY,CAAC"}

package/core/core/decorators/kos-companion.d.ts

@@ -1,11 +1,128 @@
 import { IKosDataModel } from '../kosModel';
 
-interface DecoratedKosModel<T extends IKosDataModel = IKosDataModel> {
-    new (...args: any[]): T;
-}
-type KosCompantionOptions = {
-    modelType: string;
-};
-export declare const kosCompanion: <T extends IKosDataModel>({ modelType }: KosCompantionOptions) => (constructor: DecoratedKosModel<T>) => any;
-export {};
+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;
+}
+/**
+ * Base interface for all companion models.
+ * Provides the getCompanionParent() method available in both decorator and composition modes.
+ */
+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}`;
+ *   }
+ * }
+ * ```
+ */
+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
+ *   }
+ * }
+ * ```
+ */
+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 { }
+ * ```
+ *
+ * @category KOS Model Decorator
+ * @since 2.1.0
+ */
+export declare function kosCompanion(options?: KosCompanionOptions): ClassDecorator;
 //# sourceMappingURL=kos-companion.d.ts.map

package/core/core/decorators/kos-companion.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"kos-companion.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/core/core/decorators/kos-companion.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAI5C,UAAU,iBAAiB,CAAC,CAAC,SAAS,aAAa,GAAG,aAAa;IACjE,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;CACzB;AAED,KAAK,oBAAoB,GAAG;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC;AAClD,eAAO,MAAM,YAAY,2CACkB,oBAAoB,mBAC/C,kBAAkB,CAAC,CAAC,KAAG,GAGpC,CAAC"}
+{"version":3,"file":"kos-companion.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/core/core/decorators/kos-companion.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAIjD,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,IAAI,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC;IACnC,wFAAwF;IACxF,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B,8DAA8D;IAC9D,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB,CAChC,OAAO,SAAS,aAAa,GAAG,aAAa;IAE7C;;;;;;OAMG;IACH,kBAAkB,IAAI,OAAO,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,uBAAuB,CACtC,OAAO,SAAS,aAAa,GAAG,aAAa,CAC7C,SAAQ,iBAAiB,CAAC,OAAO,CAAC;CAAG;AAEvC;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,qBAAqB,CACpC,OAAO,SAAS,aAAa,GAAG,aAAa,CAC7C,SAAQ,iBAAiB,CAAC,OAAO,CAAC;CAGnC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,wBAAgB,YAAY,CAAC,OAAO,CAAC,EAAE,mBAAmB,GAAG,cAAc,CAmB1E"}

package/core/core/decorators/kos-container-aware.d.ts

@@ -0,0 +1,465 @@
+import { IKosDataModel } from '../kosModel';
+import { IKosModelContainer } from '../kos-container-model';
+
+type MaybePromise<T> = T | Promise<T>;
+/**
+ * Configuration options for the @kosContainerAware decorator.
+ *
+ * @template T The type of models contained in the container (must extend IKosDataModel)
+ */
+export interface KosContainerAwareOptions<T extends IKosDataModel = IKosDataModel> {
+    /**
+     * Container property name on the model instance.
+     *
+     * @default "container"
+     * @example
+     * ```typescript
+     * @kosContainerAware({ containerProperty: "devices" })
+     * class DeviceContainer {
+     *   // Access via: this.devices.addModel(...)
+     * }
+     * ```
+     */
+    containerProperty?: string;
+    /**
+     * Whether to include convenience methods (getModel, addModel, removeModel).
+     *
+     * @default true
+     * @example
+     * ```typescript
+     * @kosContainerAware({ includeMethods: false })
+     * class Container {
+     *   // Only this.container property available, no convenience methods
+     * }
+     * ```
+     */
+    includeMethods?: boolean;
+    /**
+     * Whether to include reactive getters (models, data).
+     *
+     * @default true
+     * @example
+     * ```typescript
+     * @kosContainerAware({ includeGetters: false })
+     * class Container {
+     *   // No this.models or this.data getters, use this.container.data directly
+     * }
+     * ```
+     */
+    includeGetters?: boolean;
+    /**
+     * Container-specific configuration options passed to KosModelContainer constructor.
+     *
+     * @example
+     * ```typescript
+     * @kosContainerAware({
+     *   containerOptions: {
+     *     sortKey: "name",
+     *     indexMap: {
+     *       byType: "deviceType",
+     *       active: (device) => device.isOnline
+     *     },
+     *     parentId: "custom-parent", // Overrides automatic inference
+     *     extensionId: "device-manager"
+     *   }
+     * })
+     * ```
+     */
+    containerOptions?: {
+        /** Default property to sort models by */
+        sortKey?: keyof T;
+        /**
+         * Index mapping for efficient queries. Keys are index names, values are either:
+         * - Property names (string keys) for simple property-based indexing
+         * - Functions that return index keys for complex logic
+         *
+         * @example
+         * ```typescript
+         * indexMap: {
+         *   byStatus: "connectionStatus",                    // Property-based
+         *   byType: (device) => device.type.toLowerCase(),  // Function-based
+         *   needsUpdate: (device) => device.version < "2.0" // Boolean logic
+         * }
+         * ```
+         */
+        indexMap?: Record<string, keyof T | ((model: T) => MaybePromise<string | string[] | undefined>)>;
+        /**
+         * Parent model ID for the container. If not provided, automatically uses
+         * the modelId parameter from the model's constructor.
+         *
+         * @default Inferred from constructor modelId parameter
+         */
+        parentId?: string;
+        /** Extension identifier for the container */
+        extensionId?: string;
+    };
+    /**
+     * Custom name for the reactive models array getter.
+     *
+     * @default "models"
+     * @example
+     * ```typescript
+     * @kosContainerAware({ modelsProperty: "items" })
+     * class Container {
+     *   get items() { return this.container.data; } // Instead of 'models'
+     * }
+     * ```
+     */
+    modelsProperty?: string;
+    /**
+     * Legacy compatibility mode. Uses '_models' as the container property name
+     * instead of 'container' for backward compatibility with existing code.
+     *
+     * @default false
+     * @deprecated Use containerProperty instead for new code
+     */
+    legacy?: boolean;
+}
+/**
+ * Interface for models using @kosContainerAware decorator.
+ *
+ * **IMPORTANT**: Use TypeScript interface merging to add container management properties to your model class.
+ * This provides full type safety and IntelliSense support for all injected container functionality.
+ *
+ * ## Interface Merging Pattern
+ *
+ * ```typescript
+ * // 1. Declare interface merging BEFORE the class
+ * interface MyContainerModelImpl extends KosContainerAware<ItemModel> {}
+ *
+ * // 2. Apply decorator and implement the class
+ * @kosModel("my-container-model")
+ * @kosContainerAware<ItemModel>()
+ * export class MyContainerModelImpl implements IKosDataModel {
+ *   // All container properties are now available with full type safety
+ * }
+ * ```
+ *
+ * ## Custom Container Property Name
+ *
+ * When using a custom `containerProperty` name, use `KosContainerAwareWithProp`:
+ *
+ * ```typescript
+ * // For custom container property name
+ * interface DeviceManagerImpl extends KosContainerAwareWithProp<DeviceModel, "devices"> {}
+ *
+ * @kosContainerAware<DeviceModel>({ containerProperty: "devices" })
+ * class DeviceManagerImpl implements IKosDataModel {
+ *   // Access via: this.devices instead of this.container
+ * }
+ * ```
+ *
+ * ## Injected Properties and Methods
+ *
+ * The decorator automatically injects the following members (configurable via options):
+ *
+ * - **`container`**: Core KosModelContainer instance for direct access (or custom name via `containerProperty`)
+ * - **`getModel(id)`**: Retrieve a model by ID from the container
+ * - **`addModel(model)`**: Add a model to the container
+ * - **`removeModel(id)`**: Remove a model from the container by ID
+ * - **`models`**: Readonly KosModelContainer instance (compatible with IKosModelHolder)
+ * - **`data`**: Reactive array of all model instances (compatible with IKosModelHolder)
+ *
+ * All injected getters are reactive and will automatically update UI components when container contents change.
+ *
+ * @template T The type of models contained in the container (must extend IKosDataModel)
+ *
+ * @example
+ * ```typescript
+ * // Basic usage with minimal configuration
+ * interface DeviceContainerModelImpl extends KosContainerAware<DeviceModel> {}
+ *
+ * @kosModel("device-container-model")
+ * @kosContainerAware<DeviceModel>()
+ * class DeviceContainerModelImpl implements IKosDataModel {
+ *   constructor(modelId: string, options: ContainerOptions, context: KosCreationContext) {
+ *     this.id = modelId;
+ *     // Container automatically injected with parentId: modelId
+ *   }
+ *
+ *   // Use injected methods
+ *   addDevice(device: DeviceModel): void {
+ *     this.addModel(device); // Method injected by decorator
+ *   }
+ *
+ *   // Use injected reactive getters
+ *   get deviceCount(): number {
+ *     return this.data.length; // Reactive array getter injected by decorator
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Advanced usage with indexing and custom configuration
+ * interface UserContainerModelImpl extends KosContainerAware<UserModel> {}
+ *
+ * @kosModel("user-container-model")
+ * @kosContainerAware<UserModel>({
+ *   containerOptions: {
+ *     indexMap: {
+ *       byRole: "role",
+ *       byDepartment: "department",
+ *       active: (user) => user.status === "active"
+ *     },
+ *     sortKey: "lastName"
+ *   }
+ * })
+ * class UserContainerModelImpl implements IKosDataModel {
+ *   // Access indexed data via injected container
+ *   getActiveUsers(): UserModel[] {
+ *     return this.container.getIndexByKey("active", true);
+ *   }
+ *
+ *   getUsersByRole(role: string): UserModel[] {
+ *     return this.container.getIndexByKey("byRole", role);
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link kosContainerAware} - The decorator function
+ * @see {@link KosContainerAwareOptions} - Configuration options
+ */
+export interface KosContainerAware<T extends IKosDataModel = IKosDataModel> {
+    /**
+     * Core container that manages the collection of models.
+     * Provides methods to add, remove, and query model instances.
+     * Automatically injected by @kosContainerAware decorator.
+     */
+    container: IKosModelContainer<T>;
+    /**
+     * Retrieves a model from the container by its ID.
+     * @param id - The unique identifier of the model to retrieve
+     * @returns The model instance if found, undefined otherwise
+     */
+    getModel(id: string): T | undefined;
+    /**
+     * Adds a model to the container.
+     * @param model - The model instance to add
+     */
+    addModel(model: T): void;
+    /**
+     * Removes a model from the container by its ID.
+     * @param id - The unique identifier of the model to remove
+     */
+    removeModel(id: string): void;
+    /**
+     * The container instance managing the models.
+     * Readonly property that provides access to the KosModelContainer.
+     * Compatible with IKosModelHolder interface.
+     * Updates automatically when models are added or removed.
+     */
+    readonly models: IKosModelContainer<T>;
+    /**
+     * Reactive array of all model instances in the container.
+     * This is the actual array of models, compatible with IKosModelHolder interface.
+     * Updates automatically when models are added or removed.
+     */
+    data: T[];
+}
+/**
+ * Base interface providing common container-aware methods and properties.
+ * Used internally by both KosContainerAware and KosContainerAwareWithProp.
+ *
+ * @template T The type of models contained in the container
+ */
+export interface KosContainerAwareBase<T extends IKosDataModel = IKosDataModel> {
+    /**
+     * Retrieves a model from the container by its ID.
+     * @param id - The unique identifier of the model to retrieve
+     * @returns The model instance if found, undefined otherwise
+     */
+    getModel(id: string): T | undefined;
+    /**
+     * Adds a model to the container.
+     * @param model - The model instance to add
+     */
+    addModel(model: T): void;
+    /**
+     * Removes a model from the container by its ID.
+     * @param id - The unique identifier of the model to remove
+     */
+    removeModel(id: string): void;
+    /**
+     * The container instance managing the models.
+     * Readonly property that provides access to the KosModelContainer.
+     * Compatible with IKosModelHolder interface.
+     * Updates automatically when models are added or removed.
+     */
+    readonly models: IKosModelContainer<T>;
+    /**
+     * Reactive array of all model instances in the container.
+     * This is the actual array of models, compatible with IKosModelHolder interface.
+     * Updates automatically when models are added or removed.
+     */
+    data: T[];
+}
+/**
+ * Interface for models using @kosContainerAware decorator with a custom container property name.
+ *
+ * Use this interface when you specify a custom `containerProperty` in the decorator options
+ * to get proper type safety for the custom property name.
+ *
+ * @template T The type of models contained in the container
+ * @template P The custom property name for the container (string literal type)
+ *
+ * @example
+ * ```typescript
+ * // Specify the custom property name "devices" in both the interface and decorator
+ * interface DeviceManagerImpl extends KosContainerAwareWithProp<DeviceModel, "devices"> {}
+ *
+ * @kosModel("device-manager")
+ * @kosContainerAware<DeviceModel>({ containerProperty: "devices" })
+ * class DeviceManagerImpl implements IKosDataModel {
+ *   constructor(modelId: string, options: ContainerOptions, context: KosCreationContext) {
+ *     this.id = modelId;
+ *   }
+ *
+ *   addDevice(device: DeviceModel): void {
+ *     // Access container via custom property name
+ *     this.devices.addModel(device);
+ *   }
+ *
+ *   getDeviceCount(): number {
+ *     // The 'data' property is still available
+ *     return this.data.length;
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Custom property for user management
+ * interface UserManagerImpl extends KosContainerAwareWithProp<UserModel, "users"> {}
+ *
+ * @kosContainerAware<UserModel>({
+ *   containerProperty: "users",
+ *   containerOptions: {
+ *     indexMap: {
+ *       byRole: "role"
+ *     }
+ *   }
+ * })
+ * class UserManagerImpl implements IKosDataModel {
+ *   getUsersByRole(role: string): UserModel[] {
+ *     // Access via this.users instead of this.container
+ *     return this.users.getIndexByKey("byRole", role);
+ *   }
+ * }
+ * ```
+ */
+export type KosContainerAwareWithProp<T extends IKosDataModel = IKosDataModel, P extends string = "container"> = KosContainerAwareBase<T> & {
+    [K in P]: IKosModelContainer<T>;
+};
+/**
+ * Class decorator that automatically adds container management capabilities to a KOS model.
+ *
+ * This decorator eliminates the need for manual container setup by:
+ * - **Adding a container property** (default: `container`) for managing model collections
+ * - **Adding convenience methods** (`getModel`, `addModel`, `removeModel`) if `includeMethods` is true (default)
+ * - **Adding reactive getters** (`models`, `data`) if `includeGetters` is true (default)
+ * - **Automatically inferring parentId** from the model's constructor `modelId` parameter
+ * - **Registering container as @kosChild** for proper lifecycle management and cleanup
+ * - **Supporting custom indexing** via `containerOptions.indexMap` for efficient queries
+ *
+ * ## Automatic Hierarchy Integration
+ *
+ * The decorator automatically registers the container as a `@kosChild`, ensuring:
+ * - Proper lifecycle management (init, load, destroy)
+ * - Automatic cleanup when parent model is destroyed
+ * - Participation in the KOS reactive system
+ * - Memory management and observer disposal
+ *
+ * ## TypeScript Usage
+ *
+ * **IMPORTANT**: Use TypeScript interface merging to get proper type information:
+ *
+ * ```typescript
+ * interface MyContainerModelImpl extends KosContainerAware<MyItemModel> {}
+ *
+ * @kosContainerAware<MyItemModel>()
+ * class MyContainerModelImpl implements IKosDataModel {
+ *   // All container properties are now available with full type safety
+ * }
+ * ```
+ *
+ * ## Configuration Options
+ *
+ * ```typescript
+ * @kosContainerAware<UserModel>({
+ *   containerProperty: "users",        // Custom property name (default: "container")
+ *   includeMethods: true,              // Include convenience methods (default: true)
+ *   includeGetters: true,              // Include reactive getters (default: true)
+ *   modelsProperty: "userList",        // Custom models getter name (default: "models")
+ *   legacy: false,                     // Use "_models" property name (default: false)
+ *   containerOptions: {
+ *     parentId: "custom-parent",       // Override automatic parentId inference
+ *     sortKey: "name",                 // Default sorting key
+ *     extensionId: "my-extension",     // Extension identifier
+ *     indexMap: {                      // Automatic indexing for efficient queries
+ *       byRole: "role",                // Property-based index
+ *       byStatus: (user) => user.active ? "active" : "inactive", // Function-based index
+ *       admins: (user) => user.role === "admin" // Boolean index
+ *     }
+ *   }
+ * })
+ * ```
+ *
+ * @param options Configuration options for the decorator
+ * @returns A class decorator that modifies the target class prototype
+ *
+ * @see {@link KosContainerAware} - Interface for TypeScript merging
+ * @see {@link KosContainerAwareOptions} - Configuration options interface
+ *
+ * @example
+ * ```typescript
+ * // Minimal configuration - parentId automatically inferred
+ * interface ItemContainerModelImpl extends KosContainerAware<ItemModel> {}
+ *
+ * @kosContainerAware<ItemModel>()
+ * class ItemContainerModelImpl implements IKosDataModel {
+ *   id: string;
+ *
+ *   constructor(modelId: string, options: ContainerOptions, context: KosCreationContext) {
+ *     this.id = modelId;
+ *     // Container automatically created with parentId: modelId
+ *   }
+ * }
+ *
+ * // With index configuration
+ * interface UserContainerModelImpl extends KosContainerAware<UserModel> {}
+ *
+ * @kosContainerAware<UserModel>({
+ *   containerOptions: {
+ *     indexMap: {
+ *       byRole: "role",
+ *       byStatus: (user) => user.status
+ *     }
+ *   }
+ * })
+ * class UserContainerModelImpl implements IKosDataModel {
+ *   constructor(modelId: string, options: ContainerOptions, context: KosCreationContext) {
+ *     this.id = modelId;
+ *   }
+ * }
+ *
+ * // Legacy mode for backward compatibility
+ * interface LegacyContainerModelImpl extends KosContainerAware<LegacyModel> {}
+ *
+ * @kosContainerAware<LegacyModel>({
+ *   legacy: true,  // Uses '_models' as property name
+ *   containerOptions: {
+ *     sortKey: "name"
+ *   }
+ * })
+ * class LegacyContainerModelImpl implements IKosDataModel {
+ *   // Container available as this._models for backward compatibility
+ * }
+ * ```
+ *
+ * @category KOS Model Decorator
+ * @since 2.1.0
+ */
+export declare function kosContainerAware<T extends IKosDataModel = IKosDataModel>(options?: KosContainerAwareOptions<T>): ClassDecorator;
+export {};
+//# sourceMappingURL=kos-container-aware.d.ts.map

package/core/core/decorators/kos-container-aware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kos-container-aware.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/core/core/decorators/kos-container-aware.ts"],"names":[],"mappings":"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"}