@kosdev-code/kos-ui-sdk 0.1.0-dev.5053

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

@@ -0,0 +1,150 @@
+import { FutureAwareContainer, IFutureModel } from '../../../models/models/future/future-types';
+
+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
+ * }
+ * ```
+ */
+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
+ *   }
+ * }
+ * ```
+ */
+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
+ */
+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,MAAM,WAAW,qBAAqB;IACpC,mGAAmG;IACnG,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,mEAAmE;IACnE,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;;;;GAcG;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;;;;;;;;;;;;;;;;;;GAkBG;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AACH,wBAAgB,cAAc,CAC5B,OAAO,CAAC,EAAE,qBAAqB,GAC9B,cAAc,CAchB"}

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

@@ -0,0 +1,110 @@
+import { KosMethodTypes, KosRequest, KosResponse } from '../services/browser-router';
+
+/**
+ * Symbol to store HTTP route metadata on the model prototype
+ */
+export declare const HttpRouteHandlers: unique symbol;
+/**
+ * Interface for HTTP route configuration
+ */
+export interface IHttpRouteConfig {
+    method: KosMethodTypes;
+    path: string;
+    handler: string;
+    middleware?: Array<(req: KosRequest, res: KosResponse, next: () => void) => void>;
+}
+/**
+ * Decorator for GET endpoints
+ * @param path - The route path (e.g., "/api/users/:id")
+ *
+ * Supports PropKeys for dynamic path segments:
+ * - {MODEL_ID} - replaced with the model's ID
+ * - {PROP_propertyName} - replaced with model.propertyName value
+ *
+ * @example Basic usage:
+ * ```typescript
+ * @get("/api/users/:id")
+ * async getUser(req: KosRequest<"/api/users/:id">, res: KosResponse) {
+ *   const userId = req.params.id;
+ *   const user = await this.userService.getUser(userId);
+ *   res.status(200).send(user);
+ * }
+ * ```
+ *
+ * @example With PropKeys:
+ * ```typescript
+ * class TenantApiModel {
+ *   tenantId = "acme-corp";
+ *
+ *   @get("/api/tenants/{PROP_tenantId}/users")
+ *   async getTenantUsers(req: KosRequest, res: KosResponse) {
+ *     // Route registered as: /api/tenants/acme-corp/users
+ *   }
+ *
+ *   @get("/api/models/{MODEL_ID}/config")
+ *   async getModelConfig(req: KosRequest, res: KosResponse) {
+ *     // Route registered as: /api/models/<actual-model-id>/config
+ *   }
+ * }
+ * ```
+ */
+export declare const get: (path: string) => (target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+/**
+ * Decorator for POST endpoints
+ * @param path - The route path
+ *
+ * @example
+ * ```typescript
+ * @post("/api/users")
+ * async createUser(req: KosRequest<"/api/users">, res: KosResponse) {
+ *   const userData = req.body;
+ *   const newUser = await this.userService.createUser(userData);
+ *   res.status(201).send(newUser);
+ * }
+ * ```
+ */
+export declare const post: (path: string) => (target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+/**
+ * Decorator for PUT endpoints
+ * @param path - The route path
+ *
+ * @example
+ * ```typescript
+ * @put("/api/users/:id")
+ * async updateUser(req: KosRequest<"/api/users/:id">, res: KosResponse) {
+ *   const userId = req.params.id;
+ *   const updates = req.body;
+ *   const updatedUser = await this.userService.updateUser(userId, updates);
+ *   res.status(200).send(updatedUser);
+ * }
+ * ```
+ */
+export declare const put: (path: string) => (target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+/**
+ * Decorator for DELETE endpoints
+ * @param path - The route path
+ *
+ * @example
+ * ```typescript
+ * @del("/api/users/:id")
+ * async deleteUser(req: KosRequest<"/api/users/:id">, res: KosResponse) {
+ *   const userId = req.params.id;
+ *   await this.userService.deleteUser(userId);
+ *   res.status(204).send();
+ * }
+ * ```
+ */
+export declare const del: (path: string) => (target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+/**
+ * Alias for del decorator
+ */
+export declare const httpDelete: (path: string) => (target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+/**
+ * Check if a model has HTTP route handlers
+ */
+export declare function hasHttpRouteHandlers(model: any): boolean;
+/**
+ * Get HTTP route handlers from a model
+ */
+export declare function getHttpRouteHandlers(model: any): IHttpRouteConfig[];
+//# sourceMappingURL=kos-http-decorators.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,11 @@
+import { IKosDataModel } from '../kosModel';
+
+interface DecoratedKosModel<T extends IKosDataModel = IKosDataModel> {
+    new (...args: any[]): T;
+}
+interface LogConfigProps {
+    group?: string;
+}
+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

@@ -0,0 +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"}

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

@@ -0,0 +1,96 @@
+import { KosContextLogger } from '../kosModel';
+
+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
+ *   }
+ * }
+ * ```
+ */
+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
+ */
+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,MAAM,WAAW,qBAAqB;IACpC,8CAA8C;IAC9C,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,kEAAkE;IAClE,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;;OAMG;IACH,MAAM,EAAE,gBAAgB,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,wBAAgB,cAAc,CAC5B,OAAO,CAAC,EAAE,qBAAqB,GAC9B,cAAc,CAoChB"}

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

@@ -0,0 +1,28 @@
+interface KosModelEffectProps<T = any> {
+    dependencies: (model: T) => any[];
+    options?: {
+        fireImmediately?: boolean;
+    };
+}
+/**
+ * Decorator for defining a Kos model effect function within a Kos Data Model class.
+ *
+ * @param props - An object containing configuration parameters for the topic handler.
+ * @returns A decorator function.
+ *
+ * @example
+ * ```typescript
+ * class MyKosDataModel implements IKosDataModel {
+ *   // ...
+ *
+ *   @kosModelEffect()
+ *   handleModelEffect() {
+ *     // Handle the received topic payload here.
+ *   }
+ * }
+ * ```
+ * @category KOS Model Decorator
+ */
+export declare function kosModelEffect<T = any>(props?: KosModelEffectProps<T>): (target: T, _propertyKey: string, descriptor: PropertyDescriptor) => void;
+export {};
+//# sourceMappingURL=kos-model-effect.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,193 @@
+import { IFutureModel } from '../../../models/models/future/future-types';
+import { MultipleFutureHandler } from '../../../models/models/future/future-aware';
+
+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
+ * }
+ * ```
+ */
+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>;
+};
+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): void {
+ *     // Handle updates from any managed Future
+ *   }
+ * }
+ * ```
+ */
+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): void {
+ *     // Handle Future updates from any operation
+ *   }
+ *
+ *   @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
+ */
+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,MAAM,WAAW,6BAA6B;IAC5C,mGAAmG;IACnG,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,mEAAmE;IACnE,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;GAkBG;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,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;;;;;;;;;;;;;;;;;;;GAmBG;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwEG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,CAAC,EAAE,6BAA6B,GACtC,cAAc,CAchB"}

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

@@ -0,0 +1,11 @@
+import { IKosDataModel } from '../kosModel';
+
+interface DecoratedKosModel<T extends IKosDataModel = IKosDataModel> {
+    new (...args: any[]): T;
+}
+export interface KosParentProps {
+    parentId?: string;
+}
+export declare const kosParentAware: <T extends IKosDataModel>(options?: KosParentProps) => (constructor: DecoratedKosModel<T>) => any;
+export {};
+//# sourceMappingURL=kos-parent.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"kos-parent.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/core/core/decorators/kos-parent.ts"],"names":[],"mappings":"AAEA,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,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAUD,eAAO,MAAM,cAAc,sCACW,cAAc,mBACpC,kBAAkB,CAAC,CAAC,KAAG,GAIpC,CAAC"}

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

@@ -0,0 +1,6 @@
+interface ReferenceProps {
+    modelType: string;
+}
+export declare const kosReference: (props: ReferenceProps) => (target: {} | any, name: PropertyKey) => any;
+export {};
+//# sourceMappingURL=kos-reference.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"kos-reference.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/core/core/decorators/kos-reference.ts"],"names":[],"mappings":"AAMA,UAAU,cAAc;IACtB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,eAAO,MAAM,YAAY,UACf,cAAc,cACb,EAAE,GAAG,GAAG,QAAQ,WAAW,KAAG,GAGtC,CAAC"}