@kosdev-code/kos-ui-sdk 2.0.43 → 2.0.45

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

@@ -1,11 +1,161 @@
 import { IKosDataModel } from '../kosModel';
+import { DependencyLifecycle } from '../../types';
 
-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 {};
+/**
+ * @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

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,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAIjD;;;GAGG;AACH,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;IACxB;;;;;;;;;;;;;OAaG;IACH,SAAS,CAAC,EAAE,mBAAmB,CAAC;CACjC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB,CAChC,OAAO,SAAS,aAAa,GAAG,aAAa;IAE7C;;;;;;OAMG;IACH,kBAAkB,IAAI,OAAO,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,uBAAuB,CACtC,OAAO,SAAS,aAAa,GAAG,aAAa,CAC7C,SAAQ,iBAAiB,CAAC,OAAO,CAAC;CAAG;AAEvC;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,qBAAqB,CACpC,OAAO,SAAS,aAAa,GAAG,aAAa,CAC7C,SAAQ,iBAAiB,CAAC,OAAO,CAAC;CAGnC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AACH,wBAAgB,YAAY,CAAC,OAAO,CAAC,EAAE,mBAAmB,GAAG,cAAc,CAqB1E"}