@a2ui-sdk/utils 0.0.3 → 0.1.1

package/dist/0.8/pathUtils.js

@@ -0,0 +1,111 @@
+/**
+ * Path utility functions for A2UI data model operations.
+ */
+/**
+ * Gets a value from the data model by path.
+ *
+ * @param dataModel - The data model to read from
+ * @param path - The path to the value (e.g., "/user/name")
+ * @returns The value at the path, or undefined if not found
+ *
+ * @example
+ * const model = { user: { name: "John" } };
+ * getValueByPath(model, "/user/name"); // "John"
+ * getValueByPath(model, "/user/age");  // undefined
+ */
+export function getValueByPath(dataModel, path) {
+    if (!path || path === '/') {
+        return dataModel;
+    }
+    // Split path: "/user/name" -> ["user", "name"]
+    const keys = path.split('/').filter(Boolean);
+    let current = dataModel;
+    for (const key of keys) {
+        if (current === null || current === undefined) {
+            return undefined;
+        }
+        if (typeof current !== 'object') {
+            return undefined;
+        }
+        current = current[key];
+    }
+    return current;
+}
+/**
+ * Sets a value in the data model by path, returning a new data model.
+ * This function is immutable - it does not modify the original data model.
+ *
+ * @param dataModel - The data model to update
+ * @param path - The path to set (e.g., "/user/name")
+ * @param value - The value to set
+ * @returns A new data model with the value set
+ *
+ * @example
+ * const model = { user: { name: "John" } };
+ * setValueByPath(model, "/user/name", "Jane");
+ * // Returns: { user: { name: "Jane" } }
+ */
+export function setValueByPath(dataModel, path, value) {
+    if (!path || path === '/') {
+        // Replace the entire data model
+        if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+            return { ...dataModel, ...value };
+        }
+        return dataModel;
+    }
+    // Split path: "/user/name" -> ["user", "name"]
+    const keys = path.split('/').filter(Boolean);
+    // Recursive helper to build the new object structure
+    function setNested(obj, remainingKeys, val) {
+        if (remainingKeys.length === 0) {
+            // This shouldn't happen, but handle gracefully
+            if (typeof val === 'object' && val !== null && !Array.isArray(val)) {
+                return { ...obj, ...val };
+            }
+            return obj;
+        }
+        const [key, ...rest] = remainingKeys;
+        if (rest.length === 0) {
+            // Last key - set the value
+            return {
+                ...obj,
+                [key]: val,
+            };
+        }
+        // Intermediate key - recurse
+        const existingValue = obj[key];
+        const nestedObj = typeof existingValue === 'object' &&
+            existingValue !== null &&
+            !Array.isArray(existingValue)
+            ? existingValue
+            : {};
+        return {
+            ...obj,
+            [key]: setNested(nestedObj, rest, val),
+        };
+    }
+    return setNested(dataModel, keys, value);
+}
+/**
+ * Merges data into the data model at a given path.
+ * This is used for dataModelUpdate messages where contents are merged.
+ *
+ * @param dataModel - The data model to update
+ * @param path - The path to merge at (e.g., "/form")
+ * @param data - The data to merge
+ * @returns A new data model with the data merged
+ */
+export function mergeAtPath(dataModel, path, data) {
+    if (!path || path === '/') {
+        // Merge at root
+        return { ...dataModel, ...data };
+    }
+    // Get current value at path
+    const current = getValueByPath(dataModel, path);
+    const currentObj = typeof current === 'object' && current !== null && !Array.isArray(current)
+        ? current
+        : {};
+    // Merge and set
+    const merged = { ...currentObj, ...data };
+    return setValueByPath(dataModel, path, merged);
+}

package/dist/0.8/pathUtils.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * pathUtils Tests
+ *
+ * Tests for path utility functions used in A2UI data model operations.
+ */
+export {};

package/dist/0.8/pathUtils.test.js

@@ -0,0 +1,211 @@
+/**
+ * pathUtils Tests
+ *
+ * Tests for path utility functions used in A2UI data model operations.
+ */
+import { describe, it, expect } from 'vitest';
+import { getValueByPath, setValueByPath, mergeAtPath } from './pathUtils.js';
+describe('pathUtils', () => {
+    describe('getValueByPath', () => {
+        const testModel = {
+            user: {
+                name: 'John',
+                age: 30,
+                profile: {
+                    email: 'john@example.com',
+                    active: true,
+                },
+            },
+            items: ['a', 'b', 'c'],
+            count: 42,
+        };
+        it('should return entire data model for empty path', () => {
+            expect(getValueByPath(testModel, '')).toEqual(testModel);
+        });
+        it('should return entire data model for root path', () => {
+            expect(getValueByPath(testModel, '/')).toEqual(testModel);
+        });
+        it('should get top-level string value', () => {
+            const model = { name: 'test' };
+            expect(getValueByPath(model, '/name')).toBe('test');
+        });
+        it('should get top-level number value', () => {
+            expect(getValueByPath(testModel, '/count')).toBe(42);
+        });
+        it('should get top-level array value', () => {
+            expect(getValueByPath(testModel, '/items')).toEqual(['a', 'b', 'c']);
+        });
+        it('should get nested object value', () => {
+            expect(getValueByPath(testModel, '/user')).toEqual({
+                name: 'John',
+                age: 30,
+                profile: {
+                    email: 'john@example.com',
+                    active: true,
+                },
+            });
+        });
+        it('should get deeply nested string value', () => {
+            expect(getValueByPath(testModel, '/user/name')).toBe('John');
+        });
+        it('should get deeply nested number value', () => {
+            expect(getValueByPath(testModel, '/user/age')).toBe(30);
+        });
+        it('should get deeply nested object value', () => {
+            expect(getValueByPath(testModel, '/user/profile')).toEqual({
+                email: 'john@example.com',
+                active: true,
+            });
+        });
+        it('should get very deeply nested value', () => {
+            expect(getValueByPath(testModel, '/user/profile/email')).toBe('john@example.com');
+            expect(getValueByPath(testModel, '/user/profile/active')).toBe(true);
+        });
+        it('should return undefined for non-existent path', () => {
+            expect(getValueByPath(testModel, '/nonexistent')).toBeUndefined();
+        });
+        it('should return undefined for non-existent nested path', () => {
+            expect(getValueByPath(testModel, '/user/nonexistent')).toBeUndefined();
+        });
+        it('should return undefined for path through non-object', () => {
+            expect(getValueByPath(testModel, '/count/nested')).toBeUndefined();
+        });
+        it('should return undefined when intermediate value is null', () => {
+            const model = { user: null };
+            expect(getValueByPath(model, '/user/name')).toBeUndefined();
+        });
+        it('should return undefined when intermediate value is undefined', () => {
+            const model = { user: undefined };
+            expect(getValueByPath(model, '/user/name')).toBeUndefined();
+        });
+        it('should handle paths without leading slash', () => {
+            expect(getValueByPath(testModel, 'user/name')).toBe('John');
+        });
+        it('should handle empty data model', () => {
+            expect(getValueByPath({}, '/user/name')).toBeUndefined();
+        });
+    });
+    describe('setValueByPath', () => {
+        it('should return merged object for empty path with object value', () => {
+            const model = { a: 1 };
+            const result = setValueByPath(model, '', { b: 2 });
+            expect(result).toEqual({ a: 1, b: 2 });
+        });
+        it('should return merged object for root path with object value', () => {
+            const model = { a: 1 };
+            const result = setValueByPath(model, '/', { b: 2 });
+            expect(result).toEqual({ a: 1, b: 2 });
+        });
+        it('should return original model for root path with non-object value', () => {
+            const model = { a: 1 };
+            const result = setValueByPath(model, '/', 'string');
+            expect(result).toEqual({ a: 1 });
+        });
+        it('should return original model for root path with array value', () => {
+            const model = { a: 1 };
+            const result = setValueByPath(model, '/', [1, 2, 3]);
+            expect(result).toEqual({ a: 1 });
+        });
+        it('should set top-level value', () => {
+            const model = { a: 1 };
+            const result = setValueByPath(model, '/b', 2);
+            expect(result).toEqual({ a: 1, b: 2 });
+        });
+        it('should update existing top-level value', () => {
+            const model = { a: 1 };
+            const result = setValueByPath(model, '/a', 2);
+            expect(result).toEqual({ a: 2 });
+        });
+        it('should set nested value in existing object', () => {
+            const model = { user: { name: 'John' } };
+            const result = setValueByPath(model, '/user/age', 30);
+            expect(result).toEqual({ user: { name: 'John', age: 30 } });
+        });
+        it('should update existing nested value', () => {
+            const model = { user: { name: 'John' } };
+            const result = setValueByPath(model, '/user/name', 'Jane');
+            expect(result).toEqual({ user: { name: 'Jane' } });
+        });
+        it('should create nested structure if not exists', () => {
+            const model = {};
+            const result = setValueByPath(model, '/user/profile/email', 'test@test.com');
+            expect(result).toEqual({
+                user: { profile: { email: 'test@test.com' } },
+            });
+        });
+        it('should replace non-object with object when setting nested path', () => {
+            const model = { user: 'string' };
+            const result = setValueByPath(model, '/user/name', 'John');
+            expect(result).toEqual({ user: { name: 'John' } });
+        });
+        it('should be immutable - not modify original model', () => {
+            const model = { user: { name: 'John' } };
+            const result = setValueByPath(model, '/user/name', 'Jane');
+            expect(model).toEqual({ user: { name: 'John' } });
+            expect(result).toEqual({ user: { name: 'Jane' } });
+        });
+        it('should handle setting null value', () => {
+            const model = { user: { name: 'John' } };
+            const result = setValueByPath(model, '/user/name', null);
+            expect(result).toEqual({ user: { name: null } });
+        });
+        it('should handle setting array value', () => {
+            const model = { items: [] };
+            const result = setValueByPath(model, '/items', ['a', 'b']);
+            expect(result).toEqual({ items: ['a', 'b'] });
+        });
+        it('should handle setting object value', () => {
+            const model = { user: null };
+            const result = setValueByPath(model, '/user', { name: 'John' });
+            expect(result).toEqual({ user: { name: 'John' } });
+        });
+    });
+    describe('mergeAtPath', () => {
+        it('should merge at root for empty path', () => {
+            const model = { a: 1 };
+            const result = mergeAtPath(model, '', { b: 2 });
+            expect(result).toEqual({ a: 1, b: 2 });
+        });
+        it('should merge at root for root path', () => {
+            const model = { a: 1 };
+            const result = mergeAtPath(model, '/', { b: 2 });
+            expect(result).toEqual({ a: 1, b: 2 });
+        });
+        it('should overwrite existing keys at root', () => {
+            const model = { a: 1, b: 2 };
+            const result = mergeAtPath(model, '/', { b: 3, c: 4 });
+            expect(result).toEqual({ a: 1, b: 3, c: 4 });
+        });
+        it('should merge at nested path', () => {
+            const model = { user: { name: 'John' } };
+            const result = mergeAtPath(model, '/user', { age: 30 });
+            expect(result).toEqual({ user: { name: 'John', age: 30 } });
+        });
+        it('should overwrite existing keys at nested path', () => {
+            const model = { user: { name: 'John', age: 25 } };
+            const result = mergeAtPath(model, '/user', { age: 30 });
+            expect(result).toEqual({ user: { name: 'John', age: 30 } });
+        });
+        it('should create path if not exists', () => {
+            const model = {};
+            const result = mergeAtPath(model, '/user', { name: 'John' });
+            expect(result).toEqual({ user: { name: 'John' } });
+        });
+        it('should replace non-object at path with merged result', () => {
+            const model = { user: 'string' };
+            const result = mergeAtPath(model, '/user', { name: 'John' });
+            expect(result).toEqual({ user: { name: 'John' } });
+        });
+        it('should handle array at path by treating as non-object', () => {
+            const model = { items: [1, 2, 3] };
+            const result = mergeAtPath(model, '/items', { a: 1 });
+            expect(result).toEqual({ items: { a: 1 } });
+        });
+        it('should be immutable - not modify original model', () => {
+            const model = { user: { name: 'John' } };
+            const result = mergeAtPath(model, '/user', { age: 30 });
+            expect(model).toEqual({ user: { name: 'John' } });
+            expect(result).toEqual({ user: { name: 'John', age: 30 } });
+        });
+    });
+});

package/dist/0.9/dataBinding.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Data binding utility functions for A2UI 0.9.
+ *
+ * Handles resolving dynamic values with the simplified 0.9 format:
+ * - Literal values: `"string"`, `42`, `true`
+ * - Path bindings: `{"path": "/user/name"}` or `{"path": "relative"}`
+ * - Function calls: `{"call": "functionName", "args": {...}}`
+ */
+import type { DynamicValue, DynamicString, DataModel, FormBindableValue } from '@a2ui-sdk/types/0.9';
+/**
+ * Type guard to check if a value is a path binding.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a path binding object
+ *
+ * @example
+ * isPathBinding({ path: "/user/name" });  // true
+ * isPathBinding("literal");               // false
+ * isPathBinding({ call: "required" });    // false
+ */
+export declare function isPathBinding(value: FormBindableValue | undefined | null): value is {
+    path: string;
+};
+/**
+ * Type guard to check if a value is a function call.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a function call object
+ */
+export declare function isFunctionCall(value: FormBindableValue | undefined | null): value is {
+    call: string;
+    args?: Record<string, DynamicValue>;
+};
+/**
+ * Resolves a dynamic value to its actual value.
+ *
+ * Resolution order:
+ * 1. If value is a path binding object → resolve from data model
+ * 2. If value is a function call → return undefined (function calls not evaluated here)
+ * 3. Otherwise → return literal value
+ *
+ * @param value - The dynamic value (literal, path binding, or function call)
+ * @param dataModel - The data model for path lookups
+ * @param basePath - Optional base path for relative path resolution
+ * @param defaultValue - Default value if undefined or path not found
+ * @returns The resolved value
+ *
+ * @example
+ * // Literal values
+ * resolveValue("Hello", {});        // "Hello"
+ * resolveValue(42, {});             // 42
+ * resolveValue(true, {});           // true
+ *
+ * // Path bindings
+ * const model = { user: { name: "John" } };
+ * resolveValue({ path: "/user/name" }, model);           // "John"
+ * resolveValue({ path: "name" }, model, "/user");        // "John" (relative)
+ * resolveValue({ path: "/nonexistent" }, model, null, "default"); // "default"
+ */
+export declare function resolveValue<T = unknown>(value: FormBindableValue | undefined | null, dataModel: DataModel, basePath?: string | null, defaultValue?: T): T;
+/**
+ * Resolves a DynamicString value to a string.
+ * This is a convenience wrapper for string values.
+ *
+ * Supports interpolation: if the string contains `${...}` expressions,
+ * they will be replaced with values from the data model.
+ *
+ * @param value - The dynamic string value
+ * @param dataModel - The data model for path lookups
+ * @param basePath - Optional base path for relative path resolution
+ * @param defaultValue - Default value if undefined or path not found
+ * @returns The resolved string
+ *
+ * @example
+ * // Simple string
+ * resolveString("Hello", {});  // "Hello"
+ *
+ * // Path binding
+ * resolveString({ path: "/user/name" }, { user: { name: "John" } });  // "John"
+ *
+ * // Interpolation
+ * resolveString("Hello, ${/user/name}!", { user: { name: "John" } });  // "Hello, John!"
+ */
+export declare function resolveString(value: DynamicString | undefined | null, dataModel: DataModel, basePath?: string | null, defaultValue?: string): string;
+/**
+ * Resolves action context values to a plain object.
+ * All path bindings are resolved to their actual values.
+ *
+ * @param context - Object with dynamic values
+ * @param dataModel - The data model for path lookups
+ * @param basePath - Optional base path for relative path resolution
+ * @returns A plain object with resolved context values
+ *
+ * @example
+ * const context = {
+ *   name: { path: "/user/name" },
+ *   action: "submit",
+ *   count: 42
+ * };
+ * resolveContext(context, { user: { name: "John" } });
+ * // Returns: { name: "John", action: "submit", count: 42 }
+ */
+export declare function resolveContext(context: Record<string, DynamicValue> | undefined, dataModel: DataModel, basePath?: string | null): Record<string, unknown>;

package/dist/0.9/dataBinding.js

@@ -0,0 +1,165 @@
+/**
+ * Data binding utility functions for A2UI 0.9.
+ *
+ * Handles resolving dynamic values with the simplified 0.9 format:
+ * - Literal values: `"string"`, `42`, `true`
+ * - Path bindings: `{"path": "/user/name"}` or `{"path": "relative"}`
+ * - Function calls: `{"call": "functionName", "args": {...}}`
+ */
+import { getValueByPath, resolvePath } from './pathUtils.js';
+import { interpolate } from '@a2ui-sdk/utils/0.9';
+/**
+ * Type guard to check if a value is a path binding.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a path binding object
+ *
+ * @example
+ * isPathBinding({ path: "/user/name" });  // true
+ * isPathBinding("literal");               // false
+ * isPathBinding({ call: "required" });    // false
+ */
+export function isPathBinding(value) {
+    return (value !== undefined &&
+        value !== null &&
+        typeof value === 'object' &&
+        !Array.isArray(value) &&
+        'path' in value &&
+        typeof value.path === 'string');
+}
+/**
+ * Type guard to check if a value is a function call.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a function call object
+ */
+export function isFunctionCall(value) {
+    return (value !== undefined &&
+        value !== null &&
+        typeof value === 'object' &&
+        !Array.isArray(value) &&
+        'call' in value &&
+        typeof value.call === 'string');
+}
+/**
+ * Resolves a dynamic value to its actual value.
+ *
+ * Resolution order:
+ * 1. If value is a path binding object → resolve from data model
+ * 2. If value is a function call → return undefined (function calls not evaluated here)
+ * 3. Otherwise → return literal value
+ *
+ * @param value - The dynamic value (literal, path binding, or function call)
+ * @param dataModel - The data model for path lookups
+ * @param basePath - Optional base path for relative path resolution
+ * @param defaultValue - Default value if undefined or path not found
+ * @returns The resolved value
+ *
+ * @example
+ * // Literal values
+ * resolveValue("Hello", {});        // "Hello"
+ * resolveValue(42, {});             // 42
+ * resolveValue(true, {});           // true
+ *
+ * // Path bindings
+ * const model = { user: { name: "John" } };
+ * resolveValue({ path: "/user/name" }, model);           // "John"
+ * resolveValue({ path: "name" }, model, "/user");        // "John" (relative)
+ * resolveValue({ path: "/nonexistent" }, model, null, "default"); // "default"
+ */
+export function resolveValue(value, dataModel, basePath = null, defaultValue) {
+    if (value === undefined || value === null) {
+        return defaultValue;
+    }
+    // Path binding
+    if (isPathBinding(value)) {
+        const resolvedPath = resolvePath(value.path, basePath);
+        const result = getValueByPath(dataModel, resolvedPath);
+        if (result === undefined) {
+            return defaultValue;
+        }
+        return result;
+    }
+    // Function call - not evaluated here, return default
+    if (isFunctionCall(value)) {
+        return defaultValue;
+    }
+    // Literal value
+    return value;
+}
+/**
+ * Resolves a DynamicString value to a string.
+ * This is a convenience wrapper for string values.
+ *
+ * Supports interpolation: if the string contains `${...}` expressions,
+ * they will be replaced with values from the data model.
+ *
+ * @param value - The dynamic string value
+ * @param dataModel - The data model for path lookups
+ * @param basePath - Optional base path for relative path resolution
+ * @param defaultValue - Default value if undefined or path not found
+ * @returns The resolved string
+ *
+ * @example
+ * // Simple string
+ * resolveString("Hello", {});  // "Hello"
+ *
+ * // Path binding
+ * resolveString({ path: "/user/name" }, { user: { name: "John" } });  // "John"
+ *
+ * // Interpolation
+ * resolveString("Hello, ${/user/name}!", { user: { name: "John" } });  // "Hello, John!"
+ */
+export function resolveString(value, dataModel, basePath = null, defaultValue = '') {
+    // Handle undefined/null
+    if (value === undefined || value === null) {
+        return defaultValue;
+    }
+    // Handle path binding
+    if (isPathBinding(value)) {
+        const resolvedPath = resolvePath(value.path, basePath);
+        const result = getValueByPath(dataModel, resolvedPath);
+        if (result === undefined || result === null) {
+            return defaultValue;
+        }
+        return String(result);
+    }
+    // Handle function call (not evaluated here)
+    if (isFunctionCall(value)) {
+        return defaultValue;
+    }
+    // Handle string literal - perform interpolation
+    if (typeof value === 'string') {
+        return interpolate(value, dataModel, basePath);
+    }
+    // Other types (number, boolean) - convert to string
+    return String(value);
+}
+/**
+ * Resolves action context values to a plain object.
+ * All path bindings are resolved to their actual values.
+ *
+ * @param context - Object with dynamic values
+ * @param dataModel - The data model for path lookups
+ * @param basePath - Optional base path for relative path resolution
+ * @returns A plain object with resolved context values
+ *
+ * @example
+ * const context = {
+ *   name: { path: "/user/name" },
+ *   action: "submit",
+ *   count: 42
+ * };
+ * resolveContext(context, { user: { name: "John" } });
+ * // Returns: { name: "John", action: "submit", count: 42 }
+ */
+export function resolveContext(context, dataModel, basePath = null) {
+    if (!context) {
+        return {};
+    }
+    const result = {};
+    for (const [key, value] of Object.entries(context)) {
+        result[key] = resolveValue(value, dataModel, basePath);
+    }
+    return result;
+}

package/dist/0.9/dataBinding.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * dataBinding Tests
+ *
+ * Tests for data binding utility functions used in A2UI 0.9.
+ */
+export {};