@kosdev-code/kos-ui-sdk 2.1.4 → 2.1.6

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

@@ -3,6 +3,7 @@ export * from './kos-companion';
 export * from './kos-container-aware';
 export * from './kos-context';
 export * from './kos-future-aware';
+export * from './kos-multiple-future-aware';
 export * from './kos-http-decorators';
 export * from './kos-log';
 export * from './kos-logger-aware';

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,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"}
+{"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,6BAA6B,CAAC;AAC5C,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-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/kosModel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"kosModel.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/core/core/decorators/kosModel.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AA8b5C,UAAU,cAAc;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CACtB,CAAC,SAAS,aAAa,EACvB,CAAC,SAAS,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACtC,MAAM,EAAE,MAAM,GAAG,cAAc,GAAG,cAAc,CAqDjD"}
+{"version":3,"file":"kosModel.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/core/core/decorators/kosModel.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAykB5C,UAAU,cAAc;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CACtB,CAAC,SAAS,aAAa,EACvB,CAAC,SAAS,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACtC,MAAM,EAAE,MAAM,GAAG,cAAc,GAAG,cAAc,CAqDjD"}

package/core/core/decorators/propKeys.d.ts

@@ -12,6 +12,8 @@ export declare const KosModelSymbol: unique symbol;
 export declare const ModelEffects: unique symbol;
 export declare const CompanionParentModel: unique symbol;
 export declare const FutureContainerSetup: unique symbol;
+export declare const MultipleFutureContainerSetup: unique symbol;
+export declare const FutureAliases: unique symbol;
 export declare const TroubleAwareSetup: unique symbol;
 export declare const LoggerSetup: unique symbol;
 export declare const ContainerAwareSetup: unique symbol;

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

@@ -1 +1 @@
-{"version":3,"file":"propKeys.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/core/core/decorators/propKeys.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,eAAO,MAAM,oBAAoB,eAAiC,CAAC;AACnE,eAAO,MAAM,gBAAgB,eAA6B,CAAC;AAC3D,eAAO,MAAM,aAAa,eAA0B,CAAC;AACrD,eAAO,MAAM,WAAW,eAAwB,CAAC;AACjD,eAAO,MAAM,WAAW,eAAwB,CAAC;AACjD,eAAO,MAAM,SAAS,eAAsB,CAAC;AAC7C,eAAO,MAAM,eAAe,eAA4B,CAAC;AACzD,eAAO,MAAM,cAAc,eAA2B,CAAC;AACvD,eAAO,MAAM,YAAY,eAAyB,CAAC;AACnD,eAAO,MAAM,oBAAoB,eAAiC,CAAC;AACnE,eAAO,MAAM,oBAAoB,eAAiC,CAAC;AACnE,eAAO,MAAM,iBAAiB,eAA8B,CAAC;AAC7D,eAAO,MAAM,WAAW,eAAwB,CAAC;AACjD,eAAO,MAAM,mBAAmB,eAAgC,CAAC"}
+{"version":3,"file":"propKeys.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/core/core/decorators/propKeys.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,eAAO,MAAM,oBAAoB,eAAiC,CAAC;AACnE,eAAO,MAAM,gBAAgB,eAA6B,CAAC;AAC3D,eAAO,MAAM,aAAa,eAA0B,CAAC;AACrD,eAAO,MAAM,WAAW,eAAwB,CAAC;AACjD,eAAO,MAAM,WAAW,eAAwB,CAAC;AACjD,eAAO,MAAM,SAAS,eAAsB,CAAC;AAC7C,eAAO,MAAM,eAAe,eAA4B,CAAC;AACzD,eAAO,MAAM,cAAc,eAA2B,CAAC;AACvD,eAAO,MAAM,YAAY,eAAyB,CAAC;AACnD,eAAO,MAAM,oBAAoB,eAAiC,CAAC;AACnE,eAAO,MAAM,oBAAoB,eAAiC,CAAC;AACnE,eAAO,MAAM,4BAA4B,eAExC,CAAC;AACF,eAAO,MAAM,aAAa,eAA0B,CAAC;AACrD,eAAO,MAAM,iBAAiB,eAA8B,CAAC;AAC7D,eAAO,MAAM,WAAW,eAAwB,CAAC;AACjD,eAAO,MAAM,mBAAmB,eAAgC,CAAC"}