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

package/models/models/key-value/index.d.ts

@@ -1,5 +1,9 @@
 export type { KeyValueModel } from './key-value-model';
 export { KeyValue } from './key-value-registration';
+/**
+ * @group KOS Model
+ * @category Key-Value Store
+ */
 export * as KeyValueServices from './services';
 export type * from './types';
 //# sourceMappingURL=index.d.ts.map

package/models/models/key-value/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/key-value/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACpD,OAAO,KAAK,gBAAgB,MAAM,YAAY,CAAC;AAC/C,mBAAmB,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/key-value/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACpD;;;GAGG;AACH,OAAO,KAAK,gBAAgB,MAAM,YAAY,CAAC;AAC/C,mBAAmB,SAAS,CAAC"}

package/models/models/key-value/key-value-model.d.ts

@@ -3,17 +3,128 @@ import { KeyValueUpdate } from './services';
 import { IKosDataModel, IKosIdentifiable, KosCreationContext, KosData, PublicModelInterface } from '../../../core';
 
 export declare const MODEL_TYPE = "key-value-model";
+/**
+ * Key-Value Model - Persistent, reactive state storage with real-time synchronization across KOS applications.
+ *
+ * This model provides a namespaced key-value store that automatically persists data and synchronizes
+ * changes across all connected clients in real-time. Perfect for storing user preferences, application
+ * state, feature flags, or any data that needs to persist between sessions and sync across instances.
+ *
+ * ## Key Features
+ * - **Persistent Storage** - Data survives application restarts and browser refreshes
+ * - **Real-time Synchronization** - Changes propagate instantly to all connected clients
+ * - **Namespace Isolation** - Multiple stores can coexist without key collisions
+ * - **Type-Safe Values** - Supports string, number, boolean, and undefined types
+ * - **Reactive Updates** - Automatic UI updates when values change (locally or remotely)
+ * - **Topic-Based Sync** - Uses KOS event system for distributed state management
+ *
+ * ## Topic-Based Reactivity
+ * The model listens to two KOS topics for real-time synchronization:
+ * - **`/keyVal/set`** - Fired when any key-value pair is updated or added
+ * - **`/keyVal/remove`** - Fired when a key is deleted from the store
+ *
+ * These topics ensure that all instances of the model with the same namespace stay
+ * synchronized across browser tabs, windows, and even different client applications.
+ * The model automatically filters events by namespace to ensure isolation.
+ *
+ * @interface
+ *
+ * @example Basic Usage
+ * ```typescript
+ * const preferences = KeyValue.instance('user-prefs')
+ *   .options({ namespace: 'preferences' })
+ *   .build();
+ *
+ * // Store values
+ * await preferences.updateState('theme', 'dark');
+ * await preferences.updateState('fontSize', 14);
+ *
+ * // Access reactive data
+ * console.log(preferences.data.theme);     // 'dark'
+ * console.log(preferences.data.fontSize);  // 14
+ * ```
+ *
+ * @example React Integration
+ * ```typescript
+ * const UserSettings: React.FC = kosComponent(() => {
+ *   const settings = useModel(KeyValue, 'app-settings');
+ *
+ *   return (
+ *     <div>
+ *       <p>Theme: {settings.data.theme || 'light'}</p>
+ *       <button onClick={() => settings.updateState('theme', 'dark')}>
+ *         Set Dark Theme
+ *       </button>
+ *     </div>
+ *   );
+ * });
+ * ```
+ *
+ * @group KOS Model
+ * @category State Management
+ * @category Key-Value Store
+ * @useDeclaredType
+ * @see {@link KeyValueOptions} - Configuration options for key-value stores
+ * @see {@link KeyValueUpdate} - Update event structure for synchronization
+ */
 export type KeyValueModel = PublicModelInterface<KeyValueModelImpl>;
+/**
+ * @ignore
+ * @internal
+ */
 export declare class KeyValueModelImpl implements IKosDataModel, IKosIdentifiable {
     id: string;
     private logger;
     private namespace;
     data: KosData<Record<string, string | number | boolean | undefined>>;
     constructor(modelId: string, options: KeyValueOptions, context: KosCreationContext);
+    /**
+     * @internal
+     */
     init(): Promise<void>;
+    /**
+     * Update or delete a key-value pair in the store.
+     *
+     * Changes are automatically persisted and synchronized across all instances
+     * with the same namespace via KOS topics.
+     *
+     * @param key - The key to update or delete
+     * @param value - The value to set (string | number | boolean), or undefined to delete the key
+     * @returns Promise that resolves when the operation completes
+     *
+     * @example
+     * ```typescript
+     * // Set a value
+     * await keyValue.updateState('theme', 'dark');
+     *
+     * // Delete a key
+     * await keyValue.updateState('theme', undefined);
+     * ```
+     */
     updateState(key: string, value: string | number | boolean | undefined): Promise<void>;
+    /**
+     * Load initial data from persistent storage.
+     *
+     * @internal
+     */
     load(): Promise<void>;
+    /**
+     * Topic handler for `/keyVal/set` events to sync updates across instances.
+     *
+     * Automatically called when any KeyValue model instance updates a value,
+     * ensuring all instances with the same namespace stay synchronized.
+     *
+     * @param update - The key-value update event containing namespace, key, and new value
+     */
     handleStateUpdate(update: KeyValueUpdate): void;
+    /**
+     * Topic handler for `/keyVal/remove` events to sync deletions across instances.
+     *
+     * Automatically called when any KeyValue model instance deletes a key,
+     * ensuring all instances with the same namespace stay synchronized.
+     *
+     * @param update - The key-value update event containing namespace and deleted key
+     */
     handleStateDelete(update: KeyValueUpdate): void;
 }
 //# sourceMappingURL=key-value-model.d.ts.map

package/models/models/key-value/key-value-model.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"key-value-model.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/key-value/key-value-model.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EACb,gBAAgB,EAEhB,kBAAkB,EAClB,OAAO,EACP,oBAAoB,EACrB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAIL,KAAK,cAAc,EACpB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C,eAAO,MAAM,UAAU,oBAAoB,CAAC;AAE5C,MAAM,MAAM,aAAa,GAAG,oBAAoB,CAAC,iBAAiB,CAAC,CAAC;AAEpE,qBACa,iBAAkB,YAAW,aAAa,EAAE,gBAAgB;IACvE,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,CAAC,MAAM,CAAmB;IACjC,OAAO,CAAC,SAAS,CAAS;IAC1B,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,CAAC,CAAC;gBAEnE,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,eAAe,EACxB,OAAO,EAAE,kBAAkB;IAUvB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAIrB,WAAW,CACf,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,GAC3C,OAAO,CAAC,IAAI,CAAC;IAUV,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAO3B,iBAAiB,CAAC,MAAM,EAAE,cAAc;IAQxC,iBAAiB,CAAC,MAAM,EAAE,cAAc;CAMzC"}
+{"version":3,"file":"key-value-model.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/key-value/key-value-model.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EACb,gBAAgB,EAEhB,kBAAkB,EAClB,OAAO,EACP,oBAAoB,EACrB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAIL,KAAK,cAAc,EACpB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C,eAAO,MAAM,UAAU,oBAAoB,CAAC;AAE5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AACH,MAAM,MAAM,aAAa,GAAG,oBAAoB,CAAC,iBAAiB,CAAC,CAAC;AAEpE;;;GAGG;AACH,qBACa,iBAAkB,YAAW,aAAa,EAAE,gBAAgB;IACvE,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,CAAC,MAAM,CAAmB;IACjC,OAAO,CAAC,SAAS,CAAS;IAC1B,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,CAAC,CAAC;gBAEnE,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,eAAe,EACxB,OAAO,EAAE,kBAAkB;IAQ7B;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B;;;;;;;;;;;;;;;;;;OAkBG;IACG,WAAW,CACf,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,GAC3C,OAAO,CAAC,IAAI,CAAC;IAUhB;;;;OAIG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAM3B;;;;;;;OAOG;IAEH,iBAAiB,CAAC,MAAM,EAAE,cAAc;IAOxC;;;;;;;OAOG;IAEH,iBAAiB,CAAC,MAAM,EAAE,cAAc;CAMzC"}

package/models/models/key-value/services/key-value-services.d.ts

@@ -1,18 +1,140 @@
+/**
+ * @fileoverview Key-Value service functions for persistent data storage and retrieval.
+ *
+ * This module provides service functions for managing key-value pairs in KOS device storage.
+ * Supports namespaced storage, CRUD operations, and typed value handling for configuration
+ * data, user preferences, and application state persistence.
+ *
+ * @module KeyValueServices
+ */
+/**
+ * Response format for key-value data retrieval.
+ *
+ * Represents the structure of data returned from key-value service endpoints,
+ * supporting primitive types commonly used for configuration and state data.
+ *
+ * @group KOS Model
+ * @category Key-Value Store
+ */
 interface KeyValueResponse {
+    /** Key-value pairs with primitive values */
     [key: string]: string | number | boolean;
 }
+/**
+ * Update request format for key-value operations.
+ *
+ * Defines the structure for updating individual key-value pairs within
+ * specific namespaces, supporting targeted updates without affecting
+ * other stored data.
+ *
+ * @group KOS Model
+ * @category Key-Value Store
+ */
 export interface KeyValueUpdate {
+    /** Namespace identifier for data organization */
     namespace: string;
+    /** Specific key within the namespace */
     key: string;
+    /** Value to store (as string for API compatibility) */
     value: string;
 }
+/**
+ * Removes a specific key-value pair from storage.
+ *
+ * Permanently deletes a key and its associated value from the specified namespace.
+ * This operation cannot be undone, so use with caution for critical data.
+ *
+ * @param namespace - Namespace containing the key to delete
+ * @param key - Specific key to remove from storage
+ *
+ * @throws {Error} When deletion request fails or service is unavailable
+ *
+ * @example Delete User Preference
+ * ```typescript
+ * await deleteKeyValue('user-preferences', 'theme-mode');
+ * console.log('Theme preference cleared');
+ * ```
+ *
+ * @group KOS Model
+ * @category Key-Value Store
+ */
 export declare const deleteKeyValue: (namespace: string, key: string) => Promise<void>;
+/**
+ * Creates or updates a key-value pair in persistent storage.
+ *
+ * Stores a value under the specified key within the given namespace. If the key
+ * already exists, its value will be overwritten. Supports primitive types with
+ * automatic string conversion for API compatibility.
+ *
+ * @param namespace - Namespace for organizing related key-value pairs
+ * @param key - Unique identifier within the namespace
+ * @param value - Value to store (primitive types supported)
+ * @returns Promise resolving to the stored value
+ *
+ * @throws {Error} When update request fails or service returns non-200 status
+ *
+ * @example Store Configuration Setting
+ * ```typescript
+ * await updateKeyValue('device-config', 'maxRetries', 5);
+ * await updateKeyValue('user-prefs', 'darkMode', true);
+ * await updateKeyValue('app-state', 'lastLogin', '2024-01-15');
+ * ```
+ *
+ * @group KOS Model
+ * @category Key-Value Store
+ */
 export declare const updateKeyValue: (namespace: string, key: string, value: string | number | boolean) => Promise<any>;
 /**
- * @category Service
- * Retrieves the initial studio-state data.
+ * Retrieves all key-value pairs from a specified namespace.
+ *
+ * Fetches all stored data within the given namespace as a complete object.
+ * Useful for loading configuration sets, user preferences, or application
+ * state data in bulk operations.
+ *
+ * @param namespace - Namespace to retrieve data from (defaults to "studio")
+ * @returns Promise resolving to object containing all key-value pairs in namespace
+ *
+ * @throws {Error} When retrieval fails or service returns non-200 status
+ *
+ * @example Load Application Configuration
+ * ```typescript
+ * const appConfig = await getKeyValue('app-config');
+ * console.log('Max retries:', appConfig.maxRetries);
+ * console.log('Debug mode:', appConfig.debugMode);
+ *
+ * const userPrefs = await getKeyValue('user-preferences');
+ * const theme = userPrefs.themeMode || 'light';
+ * ```
+ *
+ * @group KOS Model
+ * @category Key-Value Store
  */
 export declare const getKeyValue: (namespace?: string) => Promise<KeyValueResponse>;
+/**
+ * Removes an entire namespace and all its key-value pairs.
+ *
+ * Permanently deletes all data within the specified namespace. This is a
+ * destructive operation that cannot be undone. Use with extreme caution
+ * for critical data or production systems.
+ *
+ * @param namespace - Namespace to completely remove from storage
+ *
+ * @throws {Error} When deletion request fails or service is unavailable
+ *
+ * @example Clear All User Preferences
+ * ```typescript
+ * // Warning: This removes ALL user preferences permanently
+ * await deleteKeyValueNamespace('user-preferences');
+ * console.log('All user preferences cleared');
+ *
+ * // Better: Clear specific preferences individually
+ * await deleteKeyValue('user-preferences', 'theme-mode');
+ * await deleteKeyValue('user-preferences', 'language');
+ * ```
+ *
+ * @group KOS Model
+ * @category Key-Value Store
+ */
 export declare const deleteKeyValueNamespace: (namespace: string) => Promise<void>;
 export {};
 //# sourceMappingURL=key-value-services.d.ts.map

package/models/models/key-value/services/key-value-services.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"key-value-services.d.ts","sourceRoot":"","sources":["../../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/key-value/services/key-value-services.ts"],"names":[],"mappings":"AAUA,UAAU,gBAAgB;IACxB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;CAC1C;AAED,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;CACf;AAED,eAAO,MAAM,cAAc,cAAqB,MAAM,OAAO,MAAM,kBAKlE,CAAC;AACF,eAAO,MAAM,cAAc,cACd,MAAM,OACZ,MAAM,SACJ,MAAM,GAAG,MAAM,GAAG,OAAO,iBAcjC,CAAC;AACF;;;GAGG;AACH,eAAO,MAAM,WAAW,mDAavB,CAAC;AAEF,eAAO,MAAM,uBAAuB,cAAqB,MAAM,kBAK9D,CAAC"}
+{"version":3,"file":"key-value-services.d.ts","sourceRoot":"","sources":["../../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/key-value/services/key-value-services.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAkBH;;;;;;;;GAQG;AACH,UAAU,gBAAgB;IACxB,4CAA4C;IAC5C,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;CAC1C;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,cAAc;IAC7B,iDAAiD;IACjD,SAAS,EAAE,MAAM,CAAC;IAClB,wCAAwC;IACxC,GAAG,EAAE,MAAM,CAAC;IACZ,uDAAuD;IACvD,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,cAAc,cAAqB,MAAM,OAAO,MAAM,kBAKlE,CAAC;AACF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,cAAc,cACd,MAAM,OACZ,MAAM,SACJ,MAAM,GAAG,MAAM,GAAG,OAAO,iBAcjC,CAAC;AACF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,WAAW,mDAavB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,uBAAuB,cAAqB,MAAM,kBAK9D,CAAC"}

package/models/models/key-value/types/index.d.ts

@@ -1,3 +1,59 @@
+/**
+ * Configuration options for creating KeyValue model instances.
+ *
+ * The namespace option allows you to create isolated key-value stores that don't
+ * interfere with each other, even when using the same keys. This is essential for
+ * organizing different types of data and preventing key collisions.
+ *
+ * @example Default Namespace
+ * ```typescript
+ * // Uses default 'studio' namespace
+ * const store = KeyValue.instance('my-store')
+ *   .options({})
+ *   .build();
+ * ```
+ *
+ * @example Custom Namespace
+ * ```typescript
+ * // Create isolated stores with custom namespaces
+ * const userStore = KeyValue.instance('user')
+ *   .options({ namespace: 'user-data' })
+ *   .build();
+ *
+ * const appStore = KeyValue.instance('app')
+ *   .options({ namespace: 'app-state' })
+ *   .build();
+ *
+ * // Same key, different namespaces = no collision
+ * await userStore.updateState('id', 'user-123');
+ * await appStore.updateState('id', 'app-456');
+ * ```
+ *
+ * @example Namespace Conventions
+ * ```typescript
+ * // Recommended namespace patterns
+ * const examples: KeyValueOptions[] = [
+ *   { namespace: 'user-preferences' },     // User-specific settings
+ *   { namespace: 'application-state' },    // Global app state
+ *   { namespace: 'feature-flags' },        // Feature toggles
+ *   { namespace: 'session-data' },         // Session-specific data
+ *   { namespace: 'cache-layer' },          // Cached API responses
+ *   { namespace: 'dev-tools' }             // Development/debug data
+ * ];
+ * ```
+ *
+ * @group KOS Model
+ * @category Data Persistence
+ * @category Key-Value Store
+ */
 export interface KeyValueOptions {
+  /**
+   * Namespace for the key-value store to prevent key collisions between different stores.
+   *
+   * Defaults to 'studio' if not specified. Choose descriptive namespaces that clearly
+   * indicate the purpose of the stored data.
+   *
+   * @default 'studio'
+   */
   namespace?: string;
 }

package/models/models/kos-expression-evaluator/index.d.ts

@@ -0,0 +1,4 @@
+export type { KosExpressionEvaluatorModel, KosExpressionEvaluatorModelImpl, } from './kos-expression-evaluator-model';
+export type * from './types';
+export declare const KosExpressionEvaluator: import('../../..').KosModelRegistrationType<import('./kos-expression-evaluator-model').KosExpressionEvaluatorModel<string>, import('./types').KosExpressionEvaluatorOptions>;
+//# sourceMappingURL=index.d.ts.map

package/models/models/kos-expression-evaluator/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/kos-expression-evaluator/index.ts"],"names":[],"mappings":"AAEA,YAAY,EACV,2BAA2B,EAC3B,+BAA+B,GAChC,MAAM,kCAAkC,CAAC;AAC1C,mBAAmB,SAAS,CAAC;AAE7B,eAAO,MAAM,sBAAsB,8KACW,CAAC"}

package/models/models/kos-expression-evaluator/kos-expression-evaluator-model.d.ts

@@ -0,0 +1,209 @@
+import { KosExpressionEvaluatorOptions } from './types';
+import { PublicModelInterface } from '../../../core/types';
+import { IKosIdentifiable } from '../../../core/core/types';
+import { IKosDataModel, KosCreationContext } from '../../../core/core/kosModel';
+import { KosModelRegistrationType } from '../../../core';
+
+export declare const MODEL_TYPE = "kos-expression-evaluator-model";
+/**
+ * Result of evaluating an expression, containing either a successful value or error details.
+ *
+ * @example
+ * ```typescript
+ * const result = evaluator.getExpressionValue('myExpression');
+ * if (result?.error) {
+ *   console.error(`Expression error: ${result.error}`);
+ * } else {
+ *   console.log(`Result: ${result?.value}`);
+ * }
+ * ```
+ */
+export interface ExpressionResult {
+    /** The computed value of the expression, or undefined if evaluation failed */
+    value: unknown;
+    /** Error message if expression evaluation failed, undefined if successful */
+    error?: string;
+}
+export interface NamedExpression {
+    /** Unique name identifier for this expression */
+    name: string;
+    /** The expression string (JavaScript-like syntax) */
+    expression: string;
+    /** Getter that returns the cached result */
+    get result(): ExpressionResult;
+    /** Method to evaluate the expression with given context data */
+    evaluate(contextData: Record<string, unknown>): ExpressionResult;
+    /** Method to update the cached result */
+    updateResult(result: ExpressionResult): void;
+}
+/**
+ * KOS Expression Evaluator Model - Reactive expression evaluation with dynamic context and type-safe named expressions.
+ *
+ * This model provides a reactive expression evaluation system that automatically re-evaluates
+ * expressions when their context data changes. Perfect for business rules, computed values,
+ * and conditional logic that needs to stay synchronized with changing data.
+ *
+ * ## Key Features
+ * - **Automatic reactivity** - Expressions re-evaluate when dependencies change thanks to KOS reactive patterns
+ * - **Type safety** - Generic type parameter provides compile-time checking for expression names
+ * - **Efficient updates** - Only affected expressions recalculate when their data dependencies change
+ * - **Synchronous access** - Results available immediately via getters
+ * - **Error handling** - Expressions with runtime errors are handled gracefully
+ * - **KOS model integration** - Add any KOS model to context for fully reactive expressions
+ *
+ * @interface
+ * @example Basic Usage
+ * ```typescript
+ * const evaluator = KosExpressionEvaluatorModel.instance('my-evaluator').build();
+ *
+ * evaluator.setContextData({ temperature: 72, humidity: 45 });
+ * evaluator.addExpression('isComfortable', 'temperature >= 68 && temperature <= 78');
+ *
+ * console.log(evaluator.results.isComfortable?.value); // true
+ * ```
+ *
+ * @group KOS Model
+ * @category Expression Processing
+ * @useDeclaredType
+ */
+export type KosExpressionEvaluatorModel<T extends string = string> = PublicModelInterface<KosExpressionEvaluatorModelImpl<T>>;
+/**
+ * @ignore
+ * @internal
+ */
+export declare class KosExpressionEvaluatorModelImpl<T extends string = string> implements IKosDataModel, IKosIdentifiable {
+    static Registration: KosModelRegistrationType<KosExpressionEvaluatorModel, KosExpressionEvaluatorOptions>;
+    id: string;
+    private logger;
+    private parser;
+    private _data;
+    private _expressions;
+    private _results;
+    private _contextRevision;
+    constructor(modelId: string, _options: KosExpressionEvaluatorOptions, context: KosCreationContext);
+    /**
+     * Get the current context data that expressions are evaluated against.
+     *
+     * @returns The current context data as a record of key-value pairs
+     */
+    get data(): Record<string, unknown>;
+    get contextRevision(): number;
+    /**
+     * Replace the entire context data with new values. All expressions will
+     * automatically re-evaluate against the new context.
+     *
+     * @param newData - Complete new context data to replace existing data
+     *
+     * @example
+     * ```typescript
+     * evaluator.setContextData({ temperature: 75, humidity: 40 });
+     * ```
+     */
+    setContextData(newData: Record<string, unknown>): void;
+    /**
+     * Update a single value in the context data. All expressions using this
+     * value will automatically re-evaluate.
+     *
+     * @param key - The context data key to update
+     * @param value - The new value to set
+     *
+     * @example
+     * ```typescript
+     * evaluator.updateContextValue('temperature', 85);
+     * ```
+     */
+    updateContextValue(key: string, value: unknown): void;
+    /**
+     * Update a nested property in the context data using dot notation.
+     * This method safely updates nested properties without replacing the entire object structure.
+     *
+     * @param path - Dot-separated path to the nested property (e.g., 'sensors.humidity', 'config.thresholds.temp')
+     * @param value - The new value to set at the nested path
+     *
+     * @example
+     * ```typescript
+     * evaluator.updateNestedValue('sensors.humidity', 60);
+     * ```
+     */
+    updateNestedValue(path: string, value: unknown): void;
+    /**
+     * Add a KOS model to the evaluation context. The model's observable properties
+     * will be accessible via dotted notation and expressions will automatically
+     * re-evaluate when the model's data changes.
+     *
+     * @param key - The context key to store the model under
+     * @param model - Any KOS model instance (must be observable)
+     *
+     * @example
+     * ```typescript
+     * const sensorModel = SensorModel.instance('main-sensor').build();
+     * evaluator.addModelToContext('sensor', sensorModel);
+     * evaluator.addExpression('isCritical', 'sensor.temperature > 80');
+     * ```
+     */
+    addModelToContext(key: string, model: unknown): void;
+    /**
+     * Add a named expression that will be automatically evaluated against context data.
+     * The expression will re-evaluate whenever its dependencies in the context change.
+     *
+     * @param name - Unique identifier for this expression (type-safe when using generic)
+     * @param expressionString - JavaScript-like expression string
+     * @throws {Error} If the expression has invalid syntax
+     *
+     * @example
+     * ```typescript
+     * evaluator.addExpression('isHot', 'temperature > 80');
+     * ```
+     */
+    addExpression(name: T, expressionString: string): void;
+    removeExpression(name: T): boolean;
+    getExpression(name: T): NamedExpression | undefined;
+    getExpressionValue(name: T): ExpressionResult | undefined;
+    /**
+     * Get the cached result of an expression without triggering re-evaluation.
+     * This is useful for dependency tracking in effects where you want to avoid
+     * creating reactive chains through the expression evaluation.
+     *
+     * @param name - The expression name to get the cached result for
+     * @returns The last cached result, or undefined if expression doesn't exist
+     *
+     * @example
+     * ```typescript
+     * const cached = evaluator.getCachedExpressionValue('myExpression');
+     * ```
+     */
+    getCachedExpressionValue(name: T): ExpressionResult | undefined;
+    get expressions(): NamedExpression[];
+    get expressionNames(): T[];
+    get results(): Record<T, ExpressionResult>;
+    /**
+     * Force re-evaluation of all expressions and update cached results.
+     * This is called by the effect when context data changes.
+     */
+    private evaluateAllExpressions;
+    /**
+     * Evaluate a specific expression and update the cached result if it changed.
+     */
+    private evaluateExpression;
+    /**
+     * Internal method to update the results object when expression values change.
+     * This is called by ReactiveExpression when its value changes.
+     * ObservableData handles dynamic properties automatically with MobX atoms.
+     */
+    private updateResult;
+    /**
+     * Create an anonymous reactive expression and return its generated ID.
+     * The expression becomes fully reactive and can be accessed via the returned ID.
+     *
+     * @param expressionString - JavaScript-like expression string
+     * @returns Generated UUID that can be used to access the expression via `getExpressionValue(id)` or `results[id]`
+     *
+     * @example
+     * ```typescript
+     * const tempCheckId = evaluator.createExpression('temperature > 75');
+     * const result = evaluator.getExpressionValue(tempCheckId);
+     * ```
+     */
+    createExpression(expressionString: string): string;
+}
+//# sourceMappingURL=kos-expression-evaluator-model.d.ts.map

package/models/models/kos-expression-evaluator/kos-expression-evaluator-model.d.ts.map

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

package/models/models/kos-expression-evaluator/services/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * KOS Expression Evaluator Services
+ *
+ * No services are exported as this is a local computation model.
+ */
+//# sourceMappingURL=index.d.ts.map

package/models/models/kos-expression-evaluator/services/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/kos-expression-evaluator/services/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/models/models/kos-expression-evaluator/services/kos-expression-evaluator-services.d.ts

@@ -0,0 +1,15 @@
+/**
+ * KOS Expression Evaluator Services
+ *
+ * The Expression Evaluator model is a purely computational model that performs
+ * local expression evaluation against context data. It does not require any
+ * HTTP services or external API calls.
+ *
+ * All functionality is self-contained within the model using:
+ * - expr-eval library for expression parsing and evaluation
+ * - KOS reactive patterns for automatic re-evaluation
+ * - Local context data storage
+ *
+ * No external services are needed.
+ */
+//# sourceMappingURL=kos-expression-evaluator-services.d.ts.map

package/models/models/kos-expression-evaluator/services/kos-expression-evaluator-services.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kos-expression-evaluator-services.d.ts","sourceRoot":"","sources":["../../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/kos-expression-evaluator/services/kos-expression-evaluator-services.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG"}

package/models/models/kos-expression-evaluator/types/index.d.ts

@@ -0,0 +1 @@
+export interface KosExpressionEvaluatorOptions {}