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

package/core/core/decorators/kos-execution-context.d.ts

@@ -0,0 +1,63 @@
+import { HttpMethod, ServiceRequestExecutor } from './kos-service-request';
+
+/**
+ * Symbol used to uniquely identify KosExecutionContext objects.
+ * Decorators use this to reliably detect if the last parameter is an execution context.
+ * @internal
+ */
+export declare const KOS_EXECUTION_CONTEXT: unique symbol;
+/**
+ * Execution context passed to decorated methods for accessing decorator-injected functionality.
+ *
+ * This context provides a type-safe way for decorators to inject runtime functionality
+ * into methods without polluting the class interface or relying on magic parameters.
+ *
+ * Currently used by @kosServiceRequest to inject the $request executor.
+ * Designed to be extensible for future decorators that need to inject runtime functionality.
+ *
+ * @example Using with @kosServiceRequest
+ * ```typescript
+ * @kosServiceRequest({
+ *   path: PATH_VM_INSTALL,
+ *   method: 'post'
+ * })
+ * async createRelease(
+ *   path: string,
+ *   keysetId?: string,
+ *   ctx: KosExecutionContext<paths, typeof PATH_VM_INSTALL, 'post'>
+ * ): Promise<void> {
+ *   const [error, response] = await ctx.$request({
+ *     queryParams: { keySetId: keysetId },
+ *     body: { path }
+ *   });
+ *   if (error) throw new Error(error);
+ *   return response?.data;
+ * }
+ * ```
+ *
+ * @kosService core.service-request
+ * @kosApiLevel 15
+ */
+export interface KosExecutionContext<Paths extends Record<string, any> = Record<string, any>, Path extends keyof Paths = string, Method extends HttpMethod = "get"> {
+    /**
+     * Symbol marker to identify this as a KosExecutionContext
+     * @internal
+     */
+    [KOS_EXECUTION_CONTEXT]: true;
+    /**
+     * Service request executor (injected by @kosServiceRequest)
+     * Executes the service request defined in the decorator configuration.
+     */
+    $request?: ServiceRequestExecutor<Paths, Path, Method>;
+    /**
+     * Future tracker ID string (injected by @kosFuture when trackerPolicy is 'context')
+     * This is the tracker ID that can be used with future management utilities.
+     */
+    $tracker?: string;
+}
+/**
+ * Type guard to check if an object is a KosExecutionContext
+ * @internal
+ */
+export declare function isKosExecutionContext(obj: any): obj is KosExecutionContext;
+//# sourceMappingURL=kos-execution-context.d.ts.map

package/core/core/decorators/kos-execution-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kos-execution-context.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/core/core/decorators/kos-execution-context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAEhF;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,eAAgC,CAAC;AAEnE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,WAAW,mBAAmB,CAClC,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACvD,IAAI,SAAS,MAAM,KAAK,GAAG,MAAM,EACjC,MAAM,SAAS,UAAU,GAAG,KAAK;IAEjC;;;OAGG;IACH,CAAC,qBAAqB,CAAC,EAAE,IAAI,CAAC;IAE9B;;;OAGG;IACH,QAAQ,CAAC,EAAE,sBAAsB,CAAC,KAAK,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;IAEvD;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,GAAG,GAAG,GAAG,IAAI,mBAAmB,CAE1E"}

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

@@ -0,0 +1,162 @@
+import { FutureAwareContainer, IFutureModel } from '../../../models/models/future/future-types';
+
+/**
+ * @kosService core.future-aware
+ * @kosApiLevel 13
+ */
+export interface KosFutureAwareOptions {
+    /** Setup mode: 'full' includes all UI properties, 'minimal' only futureHandler. Default: 'full' */
+    mode?: "full" | "minimal";
+    /** Custom futureHandler property name. Default: 'futureHandler' */
+    handlerProperty?: string;
+}
+/**
+ * Interface for models using @kosFutureAware in minimal mode.
+ * Use TypeScript interface merging to add the futureHandler property to your model class.
+ *
+ * @example
+ * Add ESLint disable comment at top of file, then:
+ * ```typescript
+ * interface BackgroundServiceModelImpl extends KosFutureAwareMinimal {}
+ *
+ * kosFutureAware({ mode: 'minimal' })
+ * class BackgroundServiceModelImpl implements IKosDataModel {
+ *   // futureHandler is now available via interface merging
+ * }
+ * ```
+ *
+ * @kosService core.future-aware
+ * @kosApiLevel 13
+ */
+export interface KosFutureAwareMinimal<T extends object = Record<string, unknown>> {
+    /**
+     * Core future management container that handles Future lifecycle operations.
+     * Provides methods to add, remove, and query Future instances.
+     * Automatically injected by @kosFutureAware decorator.
+     */
+    futureHandler: FutureAwareContainer<T>;
+}
+/**
+ * Interface for models using @kosFutureAware in full mode (default).
+ * Use TypeScript interface merging to add all Future Container properties to your model class.
+ *
+ * @example
+ * Add ESLint disable comment at top of file, then:
+ * ```typescript
+ * interface CopyLogsModelImpl extends KosFutureAwareFull<CopyProgress> {}
+ *
+ * kosFutureAware() // defaults to full mode
+ * class CopyLogsModelImpl implements IKosDataModel {
+ *   // All Future Container properties are now available automatically
+ *
+ *   onFutureUpdate?(future: IFutureModel<CopyProgress>): void {
+ *     // Access typed clientData
+ *   }
+ * }
+ * ```
+ *
+ * @kosService core.future-aware
+ * @kosApiLevel 13
+ */
+export interface KosFutureAwareFull<T extends object = Record<string, unknown>> extends KosFutureAwareMinimal<T> {
+    /**
+     * Current active Future model instance containing operation details.
+     * Undefined when no operation is active. Automatically updated when
+     * operations start, progress, complete, or fail.
+     */
+    future?: IFutureModel<T>;
+    /**
+     * Current operation progress as a percentage (0-100).
+     * Returns 0 when no Future is active. Updates automatically as the
+     * Future operation progresses via WebSocket events.
+     */
+    progress: number;
+    /**
+     * Current operation status string representation.
+     * Common values: "IDLE", "IN_PROGRESS", "SUCCESS", "ERROR", "CANCELLED".
+     * Returns "IDLE" when no Future is active.
+     */
+    status: string;
+    /**
+     * Whether an operation is currently actively executing.
+     * True when Future exists and has not reached an end state.
+     * False when no Future exists or operation has completed/failed/cancelled.
+     */
+    isRunning: boolean;
+    /**
+     * Whether the current or most recent operation was cancelled.
+     * Remains true after cancellation for status tracking until a new
+     * operation starts. False if operation completed normally or failed.
+     */
+    isCancelled: boolean;
+    /**
+     * Cancels the currently running Future operation.
+     * Sends cancellation request to the backend service managing the Future.
+     * No-op if no Future is currently active.
+     * @returns Promise that resolves when cancellation is acknowledged
+     * @throws Error if cancellation request fails
+     */
+    cancelFuture(): Promise<void>;
+}
+/**
+ * Class decorator that automatically adds Future Container capabilities to a KOS model.
+ *
+ * This decorator eliminates the need for manual Future Container setup by:
+ * - Adding a futureHandler property for managing Future operations
+ * - Adding reactive getters for future, progress, status, isRunning, isCancelled (in full mode)
+ * - Adding cancelFuture method for canceling operations (in full mode)
+ *
+ * **Important**: Use TypeScript interface merging to get proper type information:
+ *
+ * ```typescript
+ * // Add ESLint disable comment at top of file, then:
+ * interface MyModelImpl extends KosFutureAwareFull<MyDataType> {}
+ *
+ * kosFutureAware()
+ * class MyModelImpl implements IKosDataModel {
+ *   // All Future properties are now available with full type safety
+ * }
+ * ```
+ *
+ * Note: This decorator supports single Future operations. For models that need to manage
+ * multiple concurrent Futures, use @kosMultiFutureAware (coming soon).
+ *
+ * @param options Configuration options for the decorator
+ * @returns A class decorator
+ *
+ * @example
+ * ```typescript
+ * // Full mode example
+ * interface DeviceOperationsModelImpl extends KosFutureAwareFull<OperationData> {}
+ *
+ * kosFutureAware()
+ * class DeviceOperationsModelImpl implements IKosDataModel {
+ *   onFutureUpdate?(future: IFutureModel<OperationData>): void {
+ *     // Handle Future updates
+ *   }
+ *
+ *   kosFuture()
+ *   async performOperation(): Promise<OperationData> {
+ *     return { result: "done" };
+ *   }
+ * }
+ *
+ * // Minimal mode example
+ * interface BackgroundServiceModelImpl extends KosFutureAwareMinimal {}
+ *
+ * kosFutureAware({ mode: 'minimal' })
+ * class BackgroundServiceModelImpl implements IKosDataModel {
+ *   kosFuture()
+ *   async backgroundTask() {
+ *     return "done";
+ *   }
+ * }
+ * ```
+ *
+ * @category KOS Model Decorator
+ * @since 2.0.0
+ * @kosService core.future-aware
+ * @kosApiLevel 13
+ */
+export declare function kosFutureAware(options?: KosFutureAwareOptions): ClassDecorator;
+//# sourceMappingURL=kos-future-aware.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"kos-future-aware.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/core/core/decorators/kos-future-aware.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,oBAAoB,EACpB,YAAY,EACb,MAAM,4CAA4C,CAAC;AAGpD;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,mGAAmG;IACnG,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,mEAAmE;IACnE,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,qBAAqB,CACpC,CAAC,SAAS,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAE1C;;;;OAIG;IACH,aAAa,EAAE,oBAAoB,CAAC,CAAC,CAAC,CAAC;CACxC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAC5E,SAAQ,qBAAqB,CAAC,CAAC,CAAC;IAChC;;;;OAIG;IACH,MAAM,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC;IAEzB;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;;;OAIG;IACH,SAAS,EAAE,OAAO,CAAC;IAEnB;;;;OAIG;IACH,WAAW,EAAE,OAAO,CAAC;IAErB;;;;;;OAMG;IACH,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AACH,wBAAgB,cAAc,CAC5B,OAAO,CAAC,EAAE,qBAAqB,GAC9B,cAAc,CAchB"}

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

@@ -6,6 +6,9 @@ import { KosMethodTypes, KosRequest, KosResponse } from '../services/browser-rou
 export declare const HttpRouteHandlers: unique symbol;
 /**
  * Interface for HTTP route configuration
+ *
+ * @kosService core.http-route
+ * @kosApiLevel 12
  */
 export interface IHttpRouteConfig {
     method: KosMethodTypes;
@@ -47,6 +50,9 @@ export interface IHttpRouteConfig {
  *   }
  * }
  * ```
+ *
+ * @kosService core.http-route
+ * @kosApiLevel 12
  */
 export declare const get: (path: string) => (target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
 /**
@@ -62,6 +68,9 @@ export declare const get: (path: string) => (target: any, propertyKey: string, d
  *   res.status(201).send(newUser);
  * }
  * ```
+ *
+ * @kosService core.http-route
+ * @kosApiLevel 12
  */
 export declare const post: (path: string) => (target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
 /**
@@ -78,6 +87,9 @@ export declare const post: (path: string) => (target: any, propertyKey: string,
  *   res.status(200).send(updatedUser);
  * }
  * ```
+ *
+ * @kosService core.http-route
+ * @kosApiLevel 12
  */
 export declare const put: (path: string) => (target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
 /**
@@ -93,6 +105,9 @@ export declare const put: (path: string) => (target: any, propertyKey: string, d
  *   res.status(204).send();
  * }
  * ```
+ *
+ * @kosService core.http-route
+ * @kosApiLevel 12
  */
 export declare const del: (path: string) => (target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"kos-http-decorators.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/core/core/decorators/kos-http-decorators.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAI1F;;GAEG;AACH,eAAO,MAAM,iBAAiB,eAA8B,CAAC;AAO7D;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,cAAc,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,KAAK,CAAC,CAAC,GAAG,EAAE,UAAU,EAAE,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC,CAAC;CACnF;AA2CD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,eAAO,MAAM,GAAG,SAxE4B,MAAM,cAEpC,GAAG,eACE,MAAM,cACP,kBAAkB,uBAoEe,CAAC;AAEpD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,IAAI,SAxF2B,MAAM,cAEpC,GAAG,eACE,MAAM,cACP,kBAAkB,uBAoFiB,CAAC;AAEtD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,GAAG,SAzG4B,MAAM,cAEpC,GAAG,eACE,MAAM,cACP,kBAAkB,uBAqGe,CAAC;AAEpD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,GAAG,SAzH4B,MAAM,cAEpC,GAAG,eACE,MAAM,cACP,kBAAkB,uBAqHkB,CAAC;AAEvD;;GAEG;AACH,eAAO,MAAM,UAAU,SA9HqB,MAAM,cAEpC,GAAG,eACE,MAAM,cACP,kBAAkB,uBA0HP,CAAC;AAE9B;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,GAAG,GAAG,OAAO,CAExD;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,GAAG,GAAG,gBAAgB,EAAE,CAEnE"}
+{"version":3,"file":"kos-http-decorators.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/core/core/decorators/kos-http-decorators.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,cAAc,EACd,UAAU,EACV,WAAW,EACZ,MAAM,4BAA4B,CAAC;AAGpC;;GAEG;AACH,eAAO,MAAM,iBAAiB,eAA8B,CAAC;AAO7D;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,cAAc,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,KAAK,CAChB,CAAC,GAAG,EAAE,UAAU,EAAE,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,IAAI,KAAK,IAAI,CAC9D,CAAC;CACH;AA2CD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,eAAO,MAAM,GAAG,SA3E4B,MAAM,cAEpC,GAAG,eACE,MAAM,cACP,kBAAkB,uBAuEe,CAAC;AAEpD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,IAAI,SA9F2B,MAAM,cAEpC,GAAG,eACE,MAAM,cACP,kBAAkB,uBA0FiB,CAAC;AAEtD;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,GAAG,SAlH4B,MAAM,cAEpC,GAAG,eACE,MAAM,cACP,kBAAkB,uBA8Ge,CAAC;AAEpD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,GAAG,SArI4B,MAAM,cAEpC,GAAG,eACE,MAAM,cACP,kBAAkB,uBAiIkB,CAAC;AAEvD;;GAEG;AACH,eAAO,MAAM,UAAU,SA1IqB,MAAM,cAEpC,GAAG,eACE,MAAM,cACP,kBAAkB,uBAsIP,CAAC;AAE9B;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,GAAG,GAAG,OAAO,CAExD;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,GAAG,GAAG,gBAAgB,EAAE,CAEnE"}

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

@@ -6,6 +6,10 @@ interface DecoratedKosModel<T extends IKosDataModel = IKosDataModel> {
 interface LogConfigProps {
     group?: string;
 }
+/**
+ * @kosService core.logging
+ * @kosApiLevel 2
+ */
 export declare const kosLogger: <T extends IKosDataModel>({ group }?: LogConfigProps) => (constructor: DecoratedKosModel<T>) => any;
 export {};
 //# sourceMappingURL=kos-log.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"kos-log.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/core/core/decorators/kos-log.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAG5C,UAAU,iBAAiB,CAAC,CAAC,SAAS,aAAa,GAAG,aAAa;IACjE,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;CACzB;AAED,UAAU,cAAc;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AACD,eAAO,MAAM,SAAS,wCACiB,cAAc,mBACrC,kBAAkB,CAAC,CAAC,KAAG,GAGpC,CAAC"}
+{"version":3,"file":"kos-log.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/core/core/decorators/kos-log.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAG5C,UAAU,iBAAiB,CAAC,CAAC,SAAS,aAAa,GAAG,aAAa;IACjE,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;CACzB;AAED,UAAU,cAAc;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AACD;;;GAGG;AACH,eAAO,MAAM,SAAS,wCACiB,cAAc,mBACrC,kBAAkB,CAAC,CAAC,KAAG,GAGpC,CAAC"}

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

@@ -0,0 +1,105 @@
+import { KosContextLogger } from '../kosModel';
+
+/**
+ * @kosService core.logger-aware
+ * @kosApiLevel 13
+ */
+export interface KosLoggerAwareOptions {
+    /** Logger property name. Default: 'logger' */
+    loggerProperty?: string;
+    /** Logger context/group name. If not provided, uses model type */
+    loggerContext?: string;
+}
+/**
+ * Interface for models using @kosLoggerAware decorator.
+ * Use TypeScript interface merging to add the logger property to your model class.
+ *
+ * @example
+ * ```typescript
+ * interface MyModelImpl extends KosLoggerAware {}
+ *
+ * @kosModel("my-model")
+ * @kosLoggerAware()
+ * export class MyModelImpl implements IKosDataModel {
+ *   id: string;
+ *
+ *   constructor(modelId: string, options: any, context: KosCreationContext) {
+ *     this.id = modelId;
+ *     // No logger setup needed - automatically injected!
+ *   }
+ *
+ *   async performOperation() {
+ *     this.logger.info("Starting operation"); // Direct access to logger
+ *   }
+ * }
+ * ```
+ *
+ * @kosService core.logger-aware
+ * @kosApiLevel 13
+ */
+export interface KosLoggerAware {
+    /**
+     * KOS context logger for this model instance.
+     * Automatically injected by the @kosLoggerAware decorator.
+     * Shared across all instances of the same model type for optimal performance.
+     * Provides structured logging with debug(), info(), warn(), and error() methods.
+     * Logger context is automatically set to the model type name unless overridden.
+     */
+    logger: KosContextLogger;
+}
+/**
+ * Class decorator that automatically injects a shared logger into a KOS model.
+ *
+ * This decorator eliminates the need for manual logger setup in constructors by:
+ * - Creating a single shared logger per model type (not per instance)
+ * - Using the KosLoggerFactory for consistent logger creation
+ * - Following KOS naming conventions for logger context
+ * - Providing optimal performance through logger reuse
+ *
+ * **Performance Note**: Creates one logger per model type, shared across all instances
+ * of that type. This is much more efficient than per-instance logger creation.
+ *
+ * **Important**: Use TypeScript interface merging to get proper type information:
+ *
+ * ```typescript
+ * interface MyModelImpl extends KosLoggerAware {}
+ *
+ * @kosModel("my-model")
+ * @kosLoggerAware()
+ * export class MyModelImpl implements IKosDataModel {
+ *   // logger property is now available with full type safety
+ *   async doSomething() {
+ *     this.logger.debug("Doing something...");
+ *   }
+ * }
+ * ```
+ *
+ * @param options Configuration options for the logger injection
+ * @returns A class decorator
+ *
+ * @example
+ * ```typescript
+ * // Basic usage with default logger property
+ * @kosLoggerAware()
+ * class MyModel { }
+ *
+ * // Custom logger property name
+ * @kosLoggerAware({ loggerProperty: 'log' })
+ * class MyModel {
+ *   // this.log is available instead of this.logger
+ * }
+ *
+ * // Custom logger context for specialized logging
+ * @kosLoggerAware({ loggerContext: 'analytics' })
+ * class AnalyticsModel {
+ *   // Logger uses "analytics" context instead of model type
+ * }
+ * ```
+ *
+ * @category KOS Model Decorator
+ * @since 2.1.0
+ * @kosService core.logger-aware
+ * @kosApiLevel 13
+ */
+export declare function kosLoggerAware(options?: KosLoggerAwareOptions): ClassDecorator;
+//# sourceMappingURL=kos-logger-aware.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"kos-logger-aware.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/core/core/decorators/kos-logger-aware.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAIpD;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,8CAA8C;IAC9C,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,kEAAkE;IAClE,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;;OAMG;IACH,MAAM,EAAE,gBAAgB,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,wBAAgB,cAAc,CAC5B,OAAO,CAAC,EAAE,qBAAqB,GAC9B,cAAc,CAoChB"}

package/core/core/decorators/kos-model-effect.d.ts

@@ -1,5 +1,12 @@
+/**
+ * @kosService core.model-effect
+ * @kosApiLevel 2
+ */
 interface KosModelEffectProps<T = any> {
     dependencies: (model: T) => any[];
+    /**
+     * @kosApiLevel 3
+     */
     options?: {
         fireImmediately?: boolean;
     };
@@ -22,6 +29,8 @@ interface KosModelEffectProps<T = any> {
  * }
  * ```
  * @category KOS Model Decorator
+ * @kosService core.model-effect
+ * @kosApiLevel 2
  */
 export declare function kosModelEffect<T = any>(props?: KosModelEffectProps<T>): (target: T, _propertyKey: string, descriptor: PropertyDescriptor) => void;
 export {};

package/core/core/decorators/kos-model-effect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"kos-model-effect.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/core/core/decorators/kos-model-effect.ts"],"names":[],"mappings":"AAGA,UAAU,mBAAmB,CAAC,CAAC,GAAG,GAAG;IACnC,YAAY,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,GAAG,EAAE,CAAC;IAClC,OAAO,CAAC,EAAE;QACR,eAAe,CAAC,EAAE,OAAO,CAAC;KAC3B,CAAC;CACH;AACD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,cAAc,CAAC,CAAC,GAAG,GAAG,EAAE,KAAK,CAAC,EAAE,mBAAmB,CAAC,CAAC,CAAC,YACpD,CAAC,gBAAgB,MAAM,cAAc,kBAAkB,UAWxE"}
+{"version":3,"file":"kos-model-effect.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/core/core/decorators/kos-model-effect.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,UAAU,mBAAmB,CAAC,CAAC,GAAG,GAAG;IACnC,YAAY,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,GAAG,EAAE,CAAC;IAClC;;OAEG;IACH,OAAO,CAAC,EAAE;QACR,eAAe,CAAC,EAAE,OAAO,CAAC;KAC3B,CAAC;CACH;AACD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,cAAc,CAAC,CAAC,GAAG,GAAG,EAAE,KAAK,CAAC,EAAE,mBAAmB,CAAC,CAAC,CAAC,YACpD,CAAC,gBAAgB,MAAM,cAAc,kBAAkB,UAWxE"}

package/core/core/decorators/kos-multiple-future-aware.d.ts

@@ -0,0 +1,217 @@
+import { IFutureModel } from '../../../models/models/future/future-types';
+import { MultipleFutureHandler } from '../../../models/models/future/future-aware';
+
+/**
+ * @kosService core.future-aware
+ * @kosApiLevel 14
+ */
+export interface KosMultipleFutureAwareOptions {
+    /** Setup mode: 'full' includes all UI properties, 'minimal' only futureHandler. Default: 'full' */
+    mode?: "full" | "minimal";
+    /** Custom futureHandler property name. Default: 'futureHandler' */
+    handlerProperty?: string;
+}
+/**
+ * Interface for models using @kosMultipleFutureAware in minimal mode.
+ * Use TypeScript interface merging to add the futureHandler property and named futures to your model class.
+ *
+ * @example
+ * Add ESLint disable comment at top of file, then:
+ * ```typescript
+ * interface MaintenanceModelImpl extends KosMultipleFutureAwareMinimal {
+ *   // Add your specific named futures manually for strong typing:
+ *   calibrationFuture?: IFutureModel;
+ *   cleaningFuture?: IFutureModel;
+ * }
+ *
+ * @kosMultipleFutureAware({ mode: 'minimal' })
+ * class MaintenanceModelImpl implements IKosDataModel {
+ *   // futureHandler and named futures are now available via interface merging
+ * }
+ * ```
+ *
+ * @kosService core.future-aware
+ * @kosApiLevel 14
+ */
+export interface KosMultipleFutureAwareMinimal {
+    /**
+     * Core multiple future management container that handles concurrent Future lifecycle operations.
+     * Provides methods to add, remove, and query multiple Future instances.
+     * Automatically injected by @kosMultipleFutureAware decorator.
+     */
+    futureHandler: MultipleFutureHandler;
+    /**
+     * Default future from the handler.
+     * Returns the most recently added future or undefined if no futures are active.
+     */
+    future?: IFutureModel;
+}
+/**
+ * Utility types to generate future property names for multiple futures (for internal use)
+ */
+type FutureGetters<T extends string> = {
+    readonly [K in T as `${K}Future`]?: IFutureModel;
+};
+type ProgressGetters<T extends string> = {
+    readonly [K in T as `${K}Progress`]: number;
+};
+type StatusGetters<T extends string> = {
+    readonly [K in T as `${K}Status`]: string;
+};
+type IsRunningGetters<T extends string> = {
+    readonly [K in T as `${K}IsRunning`]: boolean;
+};
+type IsCancelledGetters<T extends string> = {
+    readonly [K in T as `${K}IsCancelled`]: boolean;
+};
+type CancelMethods<T extends string> = {
+    readonly [K in T as `cancel${Capitalize<K>}`]: () => Promise<void>;
+};
+/**
+ * @kosService core.future-aware
+ */
+export type MultipleFutureProperties<T extends string> = FutureGetters<T> & ProgressGetters<T> & StatusGetters<T> & IsRunningGetters<T> & IsCancelledGetters<T> & CancelMethods<T>;
+/**
+ * Interface for models using @kosMultipleFutureAware in full mode (default).
+ * Use TypeScript interface merging to add all Future Container properties and named futures to your model class.
+ *
+ * @example
+ * Add ESLint disable comment at top of file, then:
+ * ```typescript
+ * interface IceAgitatorModelImpl extends KosMultipleFutureAwareFull<"pour" | "agitate" | "gate"> {}
+ *
+ * @kosMultipleFutureAware() // defaults to full mode
+ * class IceAgitatorModelImpl implements IKosDataModel {
+ *   // All Future Container properties and named futures are now available automatically
+ *   // Access: this.pourFuture, this.agitateFuture, this.gateFuture
+ *
+ *   onFutureUpdate?(future: IFutureModel, alias?: string): void {
+ *     // Handle updates from any managed Future
+ *     // Use alias to identify which future triggered the update
+ *     if (alias === 'pour') {
+ *       console.log(`Pour operation: ${future.progress}%`);
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @kosService core.future-aware
+ */
+export type KosMultipleFutureAwareFull<T extends string = string> = KosMultipleFutureAwareMinimal & MultipleFutureProperties<T> & {
+    /**
+     * Current operation progress as a percentage (0-100) for the default future.
+     * Returns 0 when no default Future is active. Updates automatically as the
+     * Future operation progresses via WebSocket events.
+     */
+    progress: number;
+    /**
+     * Current operation status string representation for the default future.
+     * Common values: "IDLE", "IN_PROGRESS", "SUCCESS", "ERROR", "CANCELLED".
+     * Returns "IDLE" when no default Future is active.
+     */
+    status: string;
+    /**
+     * Whether the default operation is currently actively executing.
+     * True when default Future exists and has not reached an end state.
+     * False when no Future exists or operation has completed/failed/cancelled.
+     */
+    isRunning: boolean;
+    /**
+     * Whether the current or most recent default operation was cancelled.
+     * Remains true after cancellation for status tracking until a new
+     * operation starts. False if operation completed normally or failed.
+     */
+    isCancelled: boolean;
+    /**
+     * Cancels the currently running default Future operation.
+     * Sends cancellation request to the backend service managing the Future.
+     * No-op if no default Future is currently active.
+     * @returns Promise that resolves when cancellation is acknowledged
+     * @throws Error if cancellation request fails
+     */
+    cancelFuture(): Promise<void>;
+};
+/**
+ * Class decorator that automatically adds Multiple Future Container capabilities to a KOS model.
+ *
+ * This decorator eliminates the need for manual MultipleFutureHandler setup by:
+ * - Adding a futureHandler property for managing multiple concurrent Future operations
+ * - Adding reactive getters for default future, progress, status, isRunning, isCancelled (in full mode)
+ * - Adding dynamic named future getters based on @kosFuture aliases
+ * - Adding cancelFuture method for canceling the default operation (in full mode)
+ *
+ * **Important**: Use TypeScript interface merging to get proper type information:
+ *
+ * ```typescript
+ * // Add ESLint disable comment at top of file, then:
+ * interface MyModelImpl extends KosMultipleFutureAwareFull<"operation1" | "operation2"> {}
+ *
+ * @kosMultipleFutureAware()
+ * class MyModelImpl implements IKosDataModel {
+ *   // All Future properties and named futures are now available with full type safety
+ * }
+ * ```
+ *
+ * Note: This decorator supports multiple concurrent Future operations. For models that only need
+ * single Future support, use @kosFutureAware instead.
+ *
+ * @param options Configuration options for the decorator
+ * @returns A class decorator
+ *
+ * @example
+ * ```typescript
+ * // Full mode example with multiple futures
+ * interface IceAgitatorModelImpl extends KosMultipleFutureAwareFull<"pour" | "agitate" | "gate"> {}
+ *
+ * @kosMultipleFutureAware()
+ * class IceAgitatorModelImpl implements IKosDataModel {
+ *   get isPouring() {
+ *     return !!(this.pourFuture && !this.pourFuture?.endState);
+ *   }
+ *
+ *   onFutureUpdate?(future: IFutureModel, alias?: string): void {
+ *     // Handle Future updates from any operation
+ *     // Use alias to discriminate between different future types
+ *     if (alias === 'pour') {
+ *       console.log(`Pouring ice: ${future.progress}%`);
+ *     } else if (alias === 'agitate') {
+ *       console.log(`Agitating: ${future.progress}%`);
+ *     }
+ *   }
+ *
+ *   @kosFuture({ alias: "pour" })
+ *   async pourIce(): Promise<void> {
+ *     // Pour operation
+ *   }
+ *
+ *   @kosFuture({ alias: "agitate" })
+ *   async testAgitate(): Promise<void> {
+ *     // Agitation operation
+ *   }
+ * }
+ *
+ * // Minimal mode example
+ * interface BackgroundServiceModelImpl extends KosMultipleFutureAwareMinimal<"task1" | "task2"> {}
+ *
+ * @kosMultipleFutureAware({ mode: 'minimal' })
+ * class BackgroundServiceModelImpl implements IKosDataModel {
+ *   @kosFuture({ alias: "task1" })
+ *   async backgroundTask1() {
+ *     return "done";
+ *   }
+ *
+ *   @kosFuture({ alias: "task2" })
+ *   async backgroundTask2() {
+ *     return "done";
+ *   }
+ * }
+ * ```
+ *
+ * @category KOS Model Decorator
+ * @since 2.0.0
+ * @kosService core.future-aware
+ * @kosApiLevel 14
+ */
+export declare function kosMultipleFutureAware(options?: KosMultipleFutureAwareOptions): ClassDecorator;
+export {};
+//# sourceMappingURL=kos-multiple-future-aware.d.ts.map

package/core/core/decorators/kos-multiple-future-aware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kos-multiple-future-aware.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/core/core/decorators/kos-multiple-future-aware.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,4CAA4C,CAAC;AACxF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4CAA4C,CAAC;AAG/E;;;GAGG;AACH,MAAM,WAAW,6BAA6B;IAC5C,mGAAmG;IACnG,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,mEAAmE;IACnE,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,6BAA6B;IAC5C;;;;OAIG;IACH,aAAa,EAAE,qBAAqB,CAAC;IAErC;;;OAGG;IACH,MAAM,CAAC,EAAE,YAAY,CAAC;CACvB;AAED;;GAEG;AACH,KAAK,aAAa,CAAC,CAAC,SAAS,MAAM,IAAI;IACrC,QAAQ,EAAE,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC,EAAE,YAAY;CACjD,CAAC;AAEF,KAAK,eAAe,CAAC,CAAC,SAAS,MAAM,IAAI;IACvC,QAAQ,EAAE,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,UAAU,GAAG,MAAM;CAC5C,CAAC;AAEF,KAAK,aAAa,CAAC,CAAC,SAAS,MAAM,IAAI;IACrC,QAAQ,EAAE,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,QAAQ,GAAG,MAAM;CAC1C,CAAC;AAEF,KAAK,gBAAgB,CAAC,CAAC,SAAS,MAAM,IAAI;IACxC,QAAQ,EAAE,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,WAAW,GAAG,OAAO;CAC9C,CAAC;AAEF,KAAK,kBAAkB,CAAC,CAAC,SAAS,MAAM,IAAI;IAC1C,QAAQ,EAAE,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,aAAa,GAAG,OAAO;CAChD,CAAC;AAEF,KAAK,aAAa,CAAC,CAAC,SAAS,MAAM,IAAI;IACrC,QAAQ,EAAE,CAAC,IAAI,CAAC,IAAI,SAAS,UAAU,CAAC,CAAC,CAAC,EAAE,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC;CACnE,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,wBAAwB,CAAC,CAAC,SAAS,MAAM,IAAI,aAAa,CAAC,CAAC,CAAC,GACvE,eAAe,CAAC,CAAC,CAAC,GAClB,aAAa,CAAC,CAAC,CAAC,GAChB,gBAAgB,CAAC,CAAC,CAAC,GACnB,kBAAkB,CAAC,CAAC,CAAC,GACrB,aAAa,CAAC,CAAC,CAAC,CAAC;AAEnB;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,MAAM,0BAA0B,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,IAC9D,6BAA6B,GAC3B,wBAAwB,CAAC,CAAC,CAAC,GAAG;IAC5B;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;;;OAIG;IACH,SAAS,EAAE,OAAO,CAAC;IAEnB;;;;OAIG;IACH,WAAW,EAAE,OAAO,CAAC;IAErB;;;;;;OAMG;IACH,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/B,CAAC;AAEN;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgFG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,CAAC,EAAE,6BAA6B,GACtC,cAAc,CAchB"}