@a2ui-sdk/utils 0.0.3 → 0.1.1

package/README.md

@@ -0,0 +1,154 @@
+# @a2ui-sdk/utils
+
+Utility functions for working with A2UI protocol. This package provides helpers for data binding resolution, path manipulation, string interpolation, and validation.
+
+## Installation
+
+```bash
+npm install @a2ui-sdk/utils
+```
+
+## Usage
+
+### v0.9 (Latest)
+
+```tsx
+import {
+  // String interpolation
+  hasInterpolation,
+  interpolate,
+
+  // Data binding utilities
+  resolveValue,
+  resolveStringValue,
+  resolveNumberValue,
+  resolveBooleanValue,
+  isPathBinding,
+
+  // Path utilities
+  parsePath,
+  joinPath,
+  getValueAtPath,
+  setValueAtPath,
+
+  // Validation utilities
+  evaluateCheckRule,
+  validateChecks,
+} from '@a2ui-sdk/utils/0.9'
+```
+
+### v0.8
+
+```tsx
+import {
+  // Data binding utilities
+  resolveValue,
+  resolveStringValue,
+  resolveNumberValue,
+  resolveBooleanValue,
+  isPathBinding,
+
+  // Path utilities
+  parsePath,
+  joinPath,
+  getValueAtPath,
+  setValueAtPath,
+} from '@a2ui-sdk/utils/0.8'
+```
+
+### Namespace Import
+
+```tsx
+import { v0_8, v0_9 } from '@a2ui-sdk/utils'
+
+// Use v0.9 utilities
+const { interpolate, hasInterpolation } = v0_9
+```
+
+## API
+
+### String Interpolation (v0.9)
+
+Process strings with embedded expressions:
+
+```tsx
+import { hasInterpolation, interpolate } from '@a2ui-sdk/utils/0.9'
+
+// Check if string contains interpolation
+hasInterpolation('Hello {{name}}') // true
+hasInterpolation('Hello world') // false
+
+// Interpolate string with data
+const data = { name: 'Alice', count: 5 }
+interpolate('Hello {{name}}, you have {{count}} items', data)
+// => 'Hello Alice, you have 5 items'
+```
+
+### Data Binding
+
+Resolve dynamic values from the data model:
+
+```tsx
+import { resolveValue, isPathBinding } from '@a2ui-sdk/utils/0.9'
+
+const dataModel = { user: { name: 'Alice' } }
+
+// Check if value is a path binding
+isPathBinding({ path: '/user/name' }) // true
+isPathBinding('static value') // false
+
+// Resolve value
+resolveValue({ path: '/user/name' }, dataModel) // 'Alice'
+resolveValue('static value', dataModel) // 'static value'
+```
+
+### Path Utilities
+
+Work with JSON Pointer paths (RFC 6901):
+
+```tsx
+import {
+  parsePath,
+  joinPath,
+  getValueAtPath,
+  setValueAtPath,
+} from '@a2ui-sdk/utils/0.9'
+
+// Parse path into segments
+parsePath('/user/profile/name') // ['user', 'profile', 'name']
+
+// Join segments into path
+joinPath(['user', 'profile', 'name']) // '/user/profile/name'
+
+// Get value at path
+const data = { user: { profile: { name: 'Alice' } } }
+getValueAtPath(data, '/user/profile/name') // 'Alice'
+
+// Set value at path (immutable)
+const newData = setValueAtPath(data, '/user/profile/name', 'Bob')
+// data is unchanged, newData has the update
+```
+
+### Validation (v0.9)
+
+Evaluate validation rules:
+
+```tsx
+import { evaluateCheckRule, validateChecks } from '@a2ui-sdk/utils/0.9'
+
+const checks = [
+  {
+    message: 'Name is required',
+    call: 'isNotEmpty',
+    args: { value: { path: '/form/name' } },
+  },
+]
+
+const dataModel = { form: { name: '' } }
+const result = validateChecks(checks, dataModel)
+// { valid: false, errors: ['Name is required'] }
+```
+
+## License
+
+Apache-2.0

package/dist/0.8/dataBinding.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Data binding utility functions for A2UI.
+ * Handles resolving value sources and converting data entries.
+ */
+import type { ValueSource, DataModel, DataEntry, DataModelValue } from '@a2ui-sdk/types/0.8';
+/**
+ * Resolves a ValueSource to its actual value.
+ *
+ * @param source - The value source (literal or path reference)
+ * @param dataModel - The data model for path lookups
+ * @param defaultValue - Default value if source is undefined or path not found
+ * @returns The resolved value
+ *
+ * @example
+ * // Literal values
+ * resolveValue({ literalString: "Hello" }, {}); // "Hello"
+ * resolveValue({ literalNumber: 42 }, {});      // 42
+ *
+ * // Path references
+ * const model = { user: { name: "John" } };
+ * resolveValue({ path: "/user/name" }, model);  // "John"
+ * resolveValue({ path: "/user/age" }, model, 0); // 0 (default)
+ */
+export declare function resolveValue<T = unknown>(source: ValueSource | undefined, dataModel: DataModel, defaultValue?: T): T;
+/**
+ * Converts a DataEntry array to a plain object.
+ * This is used for processing dataModelUpdate message contents.
+ *
+ * @param contents - Array of data entries from the server
+ * @returns A plain object with the converted values
+ *
+ * @example
+ * contentsToObject([
+ *   { key: "name", valueString: "John" },
+ *   { key: "age", valueNumber: 30 },
+ *   { key: "active", valueBoolean: true },
+ *   { key: "profile", valueMap: [
+ *     { key: "email", valueString: "john@example.com" }
+ *   ]}
+ * ]);
+ * // Returns: { name: "John", age: 30, active: true, profile: { email: "john@example.com" } }
+ */
+export declare function contentsToObject(contents: DataEntry[]): Record<string, DataModelValue>;
+/**
+ * Resolves action context items to a plain object.
+ * This is used when dispatching actions to resolve all context values.
+ *
+ * @param context - Array of action context items
+ * @param dataModel - The data model for path lookups
+ * @returns A plain object with resolved context values
+ */
+export declare function resolveActionContext(context: Array<{
+    key: string;
+    value: ValueSource;
+}> | undefined, dataModel: DataModel): Record<string, unknown>;

package/dist/0.8/dataBinding.js

@@ -0,0 +1,118 @@
+/**
+ * Data binding utility functions for A2UI.
+ * Handles resolving value sources and converting data entries.
+ */
+import { getValueByPath } from './pathUtils.js';
+/**
+ * Resolves a ValueSource to its actual value.
+ *
+ * @param source - The value source (literal or path reference)
+ * @param dataModel - The data model for path lookups
+ * @param defaultValue - Default value if source is undefined or path not found
+ * @returns The resolved value
+ *
+ * @example
+ * // Literal values
+ * resolveValue({ literalString: "Hello" }, {}); // "Hello"
+ * resolveValue({ literalNumber: 42 }, {});      // 42
+ *
+ * // Path references
+ * const model = { user: { name: "John" } };
+ * resolveValue({ path: "/user/name" }, model);  // "John"
+ * resolveValue({ path: "/user/age" }, model, 0); // 0 (default)
+ */
+export function resolveValue(source, dataModel, defaultValue) {
+    if (source === undefined || source === null) {
+        return defaultValue;
+    }
+    if ('literalString' in source) {
+        return source.literalString;
+    }
+    if ('literalNumber' in source) {
+        return source.literalNumber;
+    }
+    if ('literalBoolean' in source) {
+        return source.literalBoolean;
+    }
+    if ('literalArray' in source) {
+        return source.literalArray;
+    }
+    if ('path' in source) {
+        const value = getValueByPath(dataModel, source.path);
+        if (value === undefined) {
+            return defaultValue;
+        }
+        return value;
+    }
+    return defaultValue;
+}
+/**
+ * Converts a DataEntry array to a plain object.
+ * This is used for processing dataModelUpdate message contents.
+ *
+ * @param contents - Array of data entries from the server
+ * @returns A plain object with the converted values
+ *
+ * @example
+ * contentsToObject([
+ *   { key: "name", valueString: "John" },
+ *   { key: "age", valueNumber: 30 },
+ *   { key: "active", valueBoolean: true },
+ *   { key: "profile", valueMap: [
+ *     { key: "email", valueString: "john@example.com" }
+ *   ]}
+ * ]);
+ * // Returns: { name: "John", age: 30, active: true, profile: { email: "john@example.com" } }
+ */
+export function contentsToObject(contents) {
+    const result = {};
+    for (const entry of contents) {
+        const key = normalizeKey(entry.key);
+        if (entry.valueString !== undefined) {
+            result[key] = entry.valueString;
+        }
+        else if (entry.valueNumber !== undefined) {
+            result[key] = entry.valueNumber;
+        }
+        else if (entry.valueBoolean !== undefined) {
+            result[key] = entry.valueBoolean;
+        }
+        else if (entry.valueMap !== undefined) {
+            result[key] = contentsToObject(entry.valueMap);
+        }
+    }
+    return result;
+}
+/**
+ * Normalizes a key from the data entry format.
+ * Keys can come as "/form/name" or just "name".
+ *
+ * @param key - The key to normalize
+ * @returns The normalized key (last segment)
+ */
+function normalizeKey(key) {
+    // If key contains path separators, take the last segment
+    if (key.includes('/')) {
+        const segments = key.split('/').filter(Boolean);
+        return segments[segments.length - 1] || key;
+    }
+    return key;
+}
+/**
+ * Resolves action context items to a plain object.
+ * This is used when dispatching actions to resolve all context values.
+ *
+ * @param context - Array of action context items
+ * @param dataModel - The data model for path lookups
+ * @returns A plain object with resolved context values
+ */
+export function resolveActionContext(context, dataModel) {
+    if (!context) {
+        return {};
+    }
+    const result = {};
+    for (const item of context) {
+        result[item.key] = resolveValue(item.value, dataModel);
+    }
+    return result;
+}

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

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

package/dist/0.8/dataBinding.test.js

@@ -0,0 +1,271 @@
+/**
+ * dataBinding Tests
+ *
+ * Tests for data binding utility functions used in A2UI.
+ */
+import { describe, it, expect } from 'vitest';
+import { resolveValue, contentsToObject, resolveActionContext, } from './dataBinding.js';
+describe('dataBinding', () => {
+    describe('resolveValue', () => {
+        const testModel = {
+            user: {
+                name: 'John',
+                age: 30,
+                active: true,
+            },
+            items: ['a', 'b', 'c'],
+            count: 42,
+        };
+        describe('with undefined/null source', () => {
+            it('should return default value when source is undefined', () => {
+                expect(resolveValue(undefined, testModel, 'default')).toBe('default');
+            });
+            it('should return default value when source is null', () => {
+                expect(resolveValue(null, testModel, 'default')).toBe('default');
+            });
+            it('should return undefined when no default provided and source is undefined', () => {
+                expect(resolveValue(undefined, testModel)).toBeUndefined();
+            });
+        });
+        describe('with literal values', () => {
+            it('should resolve literalString', () => {
+                const source = { literalString: 'Hello' };
+                expect(resolveValue(source, testModel)).toBe('Hello');
+            });
+            it('should resolve empty literalString', () => {
+                const source = { literalString: '' };
+                expect(resolveValue(source, testModel, 'default')).toBe('');
+            });
+            it('should resolve literalNumber', () => {
+                const source = { literalNumber: 42 };
+                expect(resolveValue(source, testModel)).toBe(42);
+            });
+            it('should resolve zero literalNumber', () => {
+                const source = { literalNumber: 0 };
+                expect(resolveValue(source, testModel, 99)).toBe(0);
+            });
+            it('should resolve negative literalNumber', () => {
+                const source = { literalNumber: -10 };
+                expect(resolveValue(source, testModel)).toBe(-10);
+            });
+            it('should resolve literalBoolean true', () => {
+                const source = { literalBoolean: true };
+                expect(resolveValue(source, testModel)).toBe(true);
+            });
+            it('should resolve literalBoolean false', () => {
+                const source = { literalBoolean: false };
+                expect(resolveValue(source, testModel, true)).toBe(false);
+            });
+            it('should resolve literalArray', () => {
+                const source = { literalArray: ['x', 'y', 'z'] };
+                expect(resolveValue(source, testModel)).toEqual([
+                    'x',
+                    'y',
+                    'z',
+                ]);
+            });
+            it('should resolve empty literalArray', () => {
+                const source = { literalArray: [] };
+                expect(resolveValue(source, testModel, ['default'])).toEqual([]);
+            });
+        });
+        describe('with path references', () => {
+            it('should resolve path to string value', () => {
+                const source = { path: '/user/name' };
+                expect(resolveValue(source, testModel)).toBe('John');
+            });
+            it('should resolve path to number value', () => {
+                const source = { path: '/count' };
+                expect(resolveValue(source, testModel)).toBe(42);
+            });
+            it('should resolve path to boolean value', () => {
+                const source = { path: '/user/active' };
+                expect(resolveValue(source, testModel)).toBe(true);
+            });
+            it('should resolve path to nested object', () => {
+                const source = { path: '/user' };
+                expect(resolveValue(source, testModel)).toEqual({
+                    name: 'John',
+                    age: 30,
+                    active: true,
+                });
+            });
+            it('should resolve path to array', () => {
+                const source = { path: '/items' };
+                expect(resolveValue(source, testModel)).toEqual([
+                    'a',
+                    'b',
+                    'c',
+                ]);
+            });
+            it('should return default when path not found', () => {
+                const source = { path: '/nonexistent' };
+                expect(resolveValue(source, testModel, 'default')).toBe('default');
+            });
+            it('should return undefined when path not found and no default', () => {
+                const source = { path: '/nonexistent' };
+                expect(resolveValue(source, testModel)).toBeUndefined();
+            });
+            it('should handle empty data model', () => {
+                const source = { path: '/user/name' };
+                expect(resolveValue(source, {}, 'default')).toBe('default');
+            });
+        });
+        describe('with unknown source structure', () => {
+            it('should return default value for unknown source structure', () => {
+                const source = { unknown: 'value' };
+                expect(resolveValue(source, testModel, 'default')).toBe('default');
+            });
+        });
+    });
+    describe('contentsToObject', () => {
+        it('should convert string entry', () => {
+            const contents = [{ key: 'name', valueString: 'John' }];
+            expect(contentsToObject(contents)).toEqual({ name: 'John' });
+        });
+        it('should convert number entry', () => {
+            const contents = [{ key: 'age', valueNumber: 30 }];
+            expect(contentsToObject(contents)).toEqual({ age: 30 });
+        });
+        it('should convert boolean entry', () => {
+            const contents = [{ key: 'active', valueBoolean: true }];
+            expect(contentsToObject(contents)).toEqual({ active: true });
+        });
+        it('should convert false boolean entry', () => {
+            const contents = [{ key: 'active', valueBoolean: false }];
+            expect(contentsToObject(contents)).toEqual({ active: false });
+        });
+        it('should convert zero number entry', () => {
+            const contents = [{ key: 'count', valueNumber: 0 }];
+            expect(contentsToObject(contents)).toEqual({ count: 0 });
+        });
+        it('should convert empty string entry', () => {
+            const contents = [{ key: 'name', valueString: '' }];
+            expect(contentsToObject(contents)).toEqual({ name: '' });
+        });
+        it('should convert nested map entry', () => {
+            const contents = [
+                {
+                    key: 'user',
+                    valueMap: [
+                        { key: 'name', valueString: 'John' },
+                        { key: 'age', valueNumber: 30 },
+                    ],
+                },
+            ];
+            expect(contentsToObject(contents)).toEqual({
+                user: { name: 'John', age: 30 },
+            });
+        });
+        it('should convert deeply nested map entry', () => {
+            const contents = [
+                {
+                    key: 'user',
+                    valueMap: [
+                        {
+                            key: 'profile',
+                            valueMap: [{ key: 'email', valueString: 'john@example.com' }],
+                        },
+                    ],
+                },
+            ];
+            expect(contentsToObject(contents)).toEqual({
+                user: { profile: { email: 'john@example.com' } },
+            });
+        });
+        it('should convert multiple entries', () => {
+            const contents = [
+                { key: 'name', valueString: 'John' },
+                { key: 'age', valueNumber: 30 },
+                { key: 'active', valueBoolean: true },
+            ];
+            expect(contentsToObject(contents)).toEqual({
+                name: 'John',
+                age: 30,
+                active: true,
+            });
+        });
+        it('should normalize path keys to last segment', () => {
+            const contents = [
+                { key: '/form/name', valueString: 'John' },
+                { key: '/form/age', valueNumber: 30 },
+            ];
+            expect(contentsToObject(contents)).toEqual({
+                name: 'John',
+                age: 30,
+            });
+        });
+        it('should handle empty contents array', () => {
+            expect(contentsToObject([])).toEqual({});
+        });
+        it('should handle entry with no value type', () => {
+            const contents = [{ key: 'empty' }];
+            expect(contentsToObject(contents)).toEqual({});
+        });
+    });
+    describe('resolveActionContext', () => {
+        const testModel = {
+            user: {
+                name: 'John',
+                age: 30,
+            },
+            selectedId: 'item-123',
+        };
+        it('should return empty object for undefined context', () => {
+            expect(resolveActionContext(undefined, testModel)).toEqual({});
+        });
+        it('should return empty object for empty context array', () => {
+            expect(resolveActionContext([], testModel)).toEqual({});
+        });
+        it('should resolve literalString values', () => {
+            const context = [{ key: 'action', value: { literalString: 'submit' } }];
+            expect(resolveActionContext(context, testModel)).toEqual({
+                action: 'submit',
+            });
+        });
+        it('should resolve literalNumber values', () => {
+            const context = [{ key: 'count', value: { literalNumber: 5 } }];
+            expect(resolveActionContext(context, testModel)).toEqual({ count: 5 });
+        });
+        it('should resolve literalBoolean values', () => {
+            const context = [{ key: 'confirmed', value: { literalBoolean: true } }];
+            expect(resolveActionContext(context, testModel)).toEqual({
+                confirmed: true,
+            });
+        });
+        it('should resolve path references', () => {
+            const context = [{ key: 'userName', value: { path: '/user/name' } }];
+            expect(resolveActionContext(context, testModel)).toEqual({
+                userName: 'John',
+            });
+        });
+        it('should resolve multiple context items', () => {
+            const context = [
+                { key: 'action', value: { literalString: 'update' } },
+                { key: 'userId', value: { path: '/selectedId' } },
+                { key: 'confirmed', value: { literalBoolean: true } },
+            ];
+            expect(resolveActionContext(context, testModel)).toEqual({
+                action: 'update',
+                userId: 'item-123',
+                confirmed: true,
+            });
+        });
+        it('should return undefined for non-existent path', () => {
+            const context = [{ key: 'missing', value: { path: '/nonexistent' } }];
+            expect(resolveActionContext(context, testModel)).toEqual({
+                missing: undefined,
+            });
+        });
+        it('should resolve nested path references', () => {
+            const context = [
+                { key: 'name', value: { path: '/user/name' } },
+                { key: 'age', value: { path: '/user/age' } },
+            ];
+            expect(resolveActionContext(context, testModel)).toEqual({
+                name: 'John',
+                age: 30,
+            });
+        });
+    });
+});

package/dist/0.8/index.d.ts

@@ -0,0 +1,2 @@
+export * from './dataBinding.js';
+export * from './pathUtils.js';

package/dist/0.8/index.js

@@ -0,0 +1,2 @@
+export * from './dataBinding.js';
+export * from './pathUtils.js';

package/dist/0.8/pathUtils.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Path utility functions for A2UI data model operations.
+ */
+import type { DataModel, DataModelValue } from '@a2ui-sdk/types/0.8';
+/**
+ * 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 declare function getValueByPath(dataModel: DataModel, path: string): DataModelValue | undefined;
+/**
+ * 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 declare function setValueByPath(dataModel: DataModel, path: string, value: unknown): DataModel;
+/**
+ * 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 declare function mergeAtPath(dataModel: DataModel, path: string, data: Record<string, unknown>): DataModel;