@lantos1618/better-ui 0.1.0

package/lib/aui/__tests__/concise-api.test.ts

@@ -0,0 +1,165 @@
+import aui from '../index';
+import { z } from 'zod';
+
+describe('AUI Concise API Tests', () => {
+  beforeEach(() => {
+    aui.clear();
+  });
+
+  describe('Simple Tool Pattern', () => {
+    it('should create tool with just 2 methods (input + execute)', async () => {
+      const simpleTool = aui
+        .tool('weather')
+        .input(z.object({ city: z.string() }))
+        .execute(async ({ input }) => ({ temp: 72, city: input.city }));
+
+      const result = await simpleTool.run({ city: 'SF' });
+      expect(result).toEqual({ temp: 72, city: 'SF' });
+    });
+
+    it('should work with render method', async () => {
+      const weatherTool = aui
+        .tool('weather')
+        .input(z.object({ city: z.string() }))
+        .execute(async ({ input }) => ({ temp: 72, city: input.city }))
+        .render(({ data }) => ({ type: 'div', props: { children: `${data.city}: ${data.temp}°` } }) as any);
+
+      const result = await weatherTool.run({ city: 'NYC' });
+      expect(result).toEqual({ temp: 72, city: 'NYC' });
+      expect(weatherTool.renderer).toBeDefined();
+    });
+  });
+
+  describe('Complex Tool Pattern', () => {
+    it('should support client optimization', async () => {
+      const searchTool = aui
+        .tool('search')
+        .input(z.object({ query: z.string() }))
+        .execute(async ({ input }) => ({ results: [`Server: ${input.query}`] }))
+        .clientExecute(async ({ input, ctx }) => {
+          const cached = ctx.cache.get(input.query);
+          if (cached) return cached;
+          
+          const result = { results: [`Client: ${input.query}`] };
+          ctx.cache.set(input.query, result);
+          return result;
+        });
+
+      // Server context (isServer: true)
+      const serverResult = await searchTool.run(
+        { query: 'test' }, 
+        { isServer: true, cache: new Map(), fetch: global.fetch }
+      );
+      expect(serverResult.results[0]).toBe('Server: test');
+
+      // Client context (isServer: false)
+      const clientCache = new Map();
+      const clientResult = await searchTool.run(
+        { query: 'test' }, 
+        { isServer: false, cache: clientCache, fetch: global.fetch }
+      );
+      expect(clientResult.results[0]).toBe('Client: test');
+
+      // Check caching works
+      const cachedResult = await searchTool.run(
+        { query: 'test' }, 
+        { isServer: false, cache: clientCache, fetch: global.fetch }
+      );
+      expect(cachedResult).toBe(clientResult); // Same reference = cached
+    });
+  });
+
+  describe('Frontend/Backend Control', () => {
+    it('should allow database queries (backend)', async () => {
+      const dbTool = aui
+        .tool('queryDB')
+        .input(z.object({ table: z.string(), limit: z.number() }))
+        .execute(async ({ input }) => ({
+          rows: Array(input.limit).fill(null).map((_, i) => ({
+            id: i + 1,
+            table: input.table
+          })),
+          count: input.limit
+        }));
+
+      const result = await dbTool.run({ table: 'users', limit: 3 });
+      expect(result.count).toBe(3);
+      expect(result.rows).toHaveLength(3);
+      expect(result.rows[0].table).toBe('users');
+    });
+
+    it('should allow DOM manipulation (frontend)', async () => {
+      const domTool = aui
+        .tool('updateDOM')
+        .input(z.object({ selector: z.string(), text: z.string() }))
+        .clientExecute(async ({ input }) => {
+          // Mock DOM operation
+          return { 
+            success: true, 
+            selector: input.selector, 
+            text: input.text,
+            isClient: true 
+          };
+        });
+
+      const result = await domTool.run(
+        { selector: '#title', text: 'New Title' },
+        { isServer: false, cache: new Map(), fetch: global.fetch }
+      );
+      
+      expect(result.success).toBe(true);
+      expect(result.isClient).toBe(true);
+    });
+
+    it('should handle API calls', async () => {
+      const apiTool = aui
+        .tool('callAPI')
+        .input(z.object({ endpoint: z.string(), method: z.string() }))
+        .execute(async ({ input }) => ({
+          status: 200,
+          endpoint: input.endpoint,
+          method: input.method,
+          data: { message: 'Success' }
+        }));
+
+      const result = await apiTool.run({ endpoint: '/api/users', method: 'GET' });
+      expect(result.status).toBe(200);
+      expect(result.data.message).toBe('Success');
+    });
+  });
+
+  describe('Chaining and Fluent Interface', () => {
+    it('should support method chaining without build()', async () => {
+      const tool = aui
+        .tool('chain-test')
+        .input(z.object({ value: z.number() }))
+        .execute(async ({ input }) => ({ doubled: input.value * 2 }))
+        .describe('Doubles a number')
+        .tag('math', 'simple')
+        .middleware(async ({ input, next }) => {
+          // Log before execution
+          const result = await next();
+          // Log after execution
+          return result;
+        });
+
+      const result = await tool.run({ value: 5 });
+      expect(result.doubled).toBe(10);
+      expect(tool.description).toBe('Doubles a number');
+      expect(tool.tags).toContain('math');
+      expect(tool.tags).toContain('simple');
+    });
+
+    it('should return tool directly without build step', () => {
+      const tool = aui
+        .tool('direct')
+        .input(z.object({ test: z.string() }))
+        .execute(async ({ input }) => input);
+
+      // Tool is immediately usable
+      expect(tool.name).toBe('direct');
+      expect(tool.run).toBeDefined();
+      expect(typeof tool.run).toBe('function');
+    });
+  });
+});

package/lib/aui/__tests__/core.test.ts

@@ -0,0 +1,265 @@
+import { describe, it, expect, beforeEach } from '@jest/globals';
+import aui, { AUI, z } from '../index';
+
+describe('AUI Core System', () => {
+  let testAUI: AUI;
+
+  beforeEach(() => {
+    testAUI = new AUI();
+  });
+
+  describe('Simple Tool Pattern', () => {
+    it('should create a simple tool with just execute and render', () => {
+      const weatherTool = testAUI
+        .tool('weather')
+        .input(z.object({ city: z.string() }))
+        .execute(async ({ input }) => ({ temp: 72, city: input.city }));
+
+      expect(weatherTool.name).toBe('weather');
+      expect(weatherTool.schema).toBeDefined();
+    });
+
+    it('should execute simple tool correctly', async () => {
+      const weatherTool = testAUI
+        .tool('weather')
+        .input(z.object({ city: z.string() }))
+        .execute(async ({ input }) => ({ temp: 72, city: input.city }));
+
+      const result = await weatherTool.run({ city: 'San Francisco' });
+      expect(result).toEqual({ temp: 72, city: 'San Francisco' });
+    });
+
+    it('should validate input with zod schema', async () => {
+      const tool = testAUI
+        .tool('validated')
+        .input(z.object({ 
+          email: z.string().email(),
+          age: z.number().min(18)
+        }))
+        .execute(async ({ input }) => ({ valid: true, ...input }));
+
+      await expect(tool.run({ email: 'invalid', age: 17 }))
+        .rejects.toThrow();
+      
+      const result = await tool.run({ email: 'test@example.com', age: 25 });
+      expect(result).toEqual({ valid: true, email: 'test@example.com', age: 25 });
+    });
+  });
+
+  describe('Complex Tool Pattern', () => {
+    it('should create tool with client execution', () => {
+      const searchTool = testAUI
+        .tool('search')
+        .input(z.object({ query: z.string() }))
+        .execute(async ({ input }) => [{ id: 1, title: input.query }])
+        .clientExecute(async ({ input, ctx }) => {
+          const cached = ctx.cache.get(input.query);
+          return cached || [{ id: 2, title: `Client: ${input.query}` }];
+        });
+
+      expect(searchTool.name).toBe('search');
+      const config = searchTool.getConfig();
+      expect(config.clientHandler).toBeDefined();
+    });
+
+    it('should use client handler when not on server', async () => {
+      const tool = testAUI
+        .tool('hybrid')
+        .input(z.object({ value: z.string() }))
+        .execute(async ({ input }) => ({ source: 'server', value: input.value }))
+        .clientExecute(async ({ input }) => ({ source: 'client', value: input.value }));
+
+      // Test with client context
+      const clientResult = await tool.run(
+        { value: 'test' }, 
+        { cache: new Map(), fetch, isServer: false }
+      );
+      expect(clientResult).toEqual({ source: 'client', value: 'test' });
+
+      // Test with server context
+      const serverResult = await tool.run(
+        { value: 'test' },
+        { cache: new Map(), fetch, isServer: true }
+      );
+      expect(serverResult).toEqual({ source: 'server', value: 'test' });
+    });
+
+    it('should use cache in client execution', async () => {
+      const cache = new Map();
+      cache.set('cached-query', [{ id: 99, title: 'Cached Result' }]);
+
+      const tool = testAUI
+        .tool('search')
+        .input(z.object({ query: z.string() }))
+        .execute(async ({ input }) => [{ id: 1, title: input.query }])
+        .clientExecute(async ({ input, ctx }) => {
+          const cached = ctx.cache.get(input.query);
+          if (cached) return cached;
+          return [{ id: 2, title: `Fresh: ${input.query}` }];
+        });
+
+      const result = await tool.run(
+        { query: 'cached-query' },
+        { cache, fetch, isServer: false }
+      );
+      
+      expect(result).toEqual([{ id: 99, title: 'Cached Result' }]);
+    });
+  });
+
+  describe('Middleware Support', () => {
+    it('should apply middleware in order', async () => {
+      const logs: string[] = [];
+      
+      const tool = testAUI
+        .tool('middleware-test')
+        .input(z.object({ value: z.number() }))
+        .execute(async ({ input }) => ({ result: input.value * 2 }))
+        .middleware(async ({ input, next }) => {
+          logs.push('middleware-1-before');
+          const result = await next();
+          logs.push('middleware-1-after');
+          return { ...result, middleware1: true };
+        })
+        .middleware(async ({ input, next }) => {
+          logs.push('middleware-2-before');
+          const result = await next();
+          logs.push('middleware-2-after');
+          return { ...result, middleware2: true };
+        });
+
+      const result = await tool.run({ value: 5 });
+      
+      expect(logs).toEqual([
+        'middleware-1-before',
+        'middleware-2-before',
+        'middleware-2-after',
+        'middleware-1-after'
+      ]);
+      
+      expect(result).toEqual({
+        result: 10,
+        middleware1: true,
+        middleware2: true
+      });
+    });
+  });
+
+  describe('Tool Management', () => {
+    it('should register and retrieve tools', () => {
+      const tool1 = testAUI.tool('tool1').execute(async () => 'result1');
+      const tool2 = testAUI.tool('tool2').execute(async () => 'result2');
+
+      expect(testAUI.has('tool1')).toBe(true);
+      expect(testAUI.has('tool2')).toBe(true);
+      expect(testAUI.get('tool1')).toBe(tool1);
+      expect(testAUI.get('tool2')).toBe(tool2);
+    });
+
+    it('should list all tools', () => {
+      testAUI.tool('a').execute(async () => 'a');
+      testAUI.tool('b').execute(async () => 'b');
+      testAUI.tool('c').execute(async () => 'c');
+
+      const tools = testAUI.list();
+      expect(tools).toHaveLength(3);
+      expect(testAUI.getToolNames()).toEqual(['a', 'b', 'c']);
+    });
+
+    it('should execute tool by name', async () => {
+      testAUI
+        .tool('calculator')
+        .input(z.object({ a: z.number(), b: z.number() }))
+        .execute(async ({ input }) => input.a + input.b);
+
+      const result = await testAUI.execute('calculator', { a: 5, b: 3 });
+      expect(result).toBe(8);
+    });
+
+    it('should find tools by tags', () => {
+      testAUI.tool('t1').tag('ai', 'search').execute(async () => 't1');
+      testAUI.tool('t2').tag('ai', 'database').execute(async () => 't2');
+      testAUI.tool('t3').tag('search').execute(async () => 't3');
+
+      const aiTools = testAUI.findByTag('ai');
+      expect(aiTools).toHaveLength(2);
+
+      const searchTools = testAUI.findByTag('search');
+      expect(searchTools).toHaveLength(2);
+
+      const aiSearchTools = testAUI.findByTags('ai', 'search');
+      expect(aiSearchTools).toHaveLength(1);
+      expect(aiSearchTools[0].name).toBe('t1');
+    });
+  });
+
+  describe('Tool Metadata', () => {
+    it('should support descriptions', () => {
+      const tool = testAUI
+        .tool('described')
+        .describe('This tool does something important')
+        .execute(async () => 'result');
+
+      expect(tool.description).toBe('This tool does something important');
+    });
+
+    it('should serialize to JSON', () => {
+      const tool = testAUI
+        .tool('serializable')
+        .describe('Test tool')
+        .tag('test', 'example')
+        .input(z.object({ x: z.number() }))
+        .execute(async ({ input }) => input.x * 2)
+        .clientExecute(async ({ input }) => input.x * 3)
+        .middleware(async ({ next }) => next());
+
+      const json = tool.toJSON();
+      expect(json).toEqual({
+        name: 'serializable',
+        description: 'Test tool',
+        tags: ['test', 'example'],
+        hasInput: true,
+        hasExecute: true,
+        hasClientExecute: true,
+        hasRender: false,
+        hasMiddleware: true
+      });
+    });
+  });
+
+  describe('Error Handling', () => {
+    it('should throw error for tool without execute handler', async () => {
+      const tool = testAUI
+        .tool('incomplete')
+        .input(z.object({ x: z.number() }));
+
+      await expect(tool.run({ x: 5 }))
+        .rejects.toThrow('Tool incomplete has no execute handler');
+    });
+
+    it('should throw error for unknown tool', async () => {
+      await expect(testAUI.execute('nonexistent', {}))
+        .rejects.toThrow('Tool "nonexistent" not found');
+    });
+  });
+
+  describe('Context Creation', () => {
+    it('should create default context', () => {
+      const ctx = testAUI.createContext();
+      expect(ctx.cache).toBeInstanceOf(Map);
+      expect(ctx.fetch).toBeDefined();
+      expect(typeof ctx.isServer).toBe('boolean');
+    });
+
+    it('should merge additional context', () => {
+      const ctx = testAUI.createContext({
+        user: { id: 1, name: 'Test User' },
+        session: { token: 'abc123' }
+      });
+      
+      expect(ctx.user).toEqual({ id: 1, name: 'Test User' });
+      expect(ctx.session).toEqual({ token: 'abc123' });
+      expect(ctx.cache).toBeInstanceOf(Map);
+    });
+  });
+});

package/lib/aui/__tests__/simple-api.test.ts

@@ -0,0 +1,200 @@
+import { describe, it, expect, beforeEach } from '@jest/globals';
+import { AUI } from '../index';
+import { z } from 'zod';
+
+describe('AUI Simple API', () => {
+  let aui: AUI;
+
+  beforeEach(() => {
+    aui = new AUI();
+  });
+
+  describe('Basic Tool Creation', () => {
+    it('should create a simple tool with just execute', async () => {
+      const tool = aui
+        .tool('simple')
+        .execute(async () => ({ result: 'success' }));
+
+      const result = await tool.run({});
+      expect(result).toEqual({ result: 'success' });
+    });
+
+    it('should create a tool with input validation', async () => {
+      const tool = aui
+        .tool('validated')
+        .input(z.object({ name: z.string() }))
+        .execute(async ({ input }) => ({ greeting: `Hello, ${input.name}!` }));
+
+      const result = await tool.run({ name: 'World' });
+      expect(result).toEqual({ greeting: 'Hello, World!' });
+    });
+
+    it('should throw on invalid input', async () => {
+      const tool = aui
+        .tool('strict')
+        .input(z.object({ age: z.number().min(0) }))
+        .execute(async ({ input }) => ({ valid: true, age: input.age }));
+
+      await expect(tool.run({ age: -1 } as any)).rejects.toThrow();
+    });
+  });
+
+  describe('Client/Server Execution', () => {
+    it('should use server execute when on server', async () => {
+      const tool = aui
+        .tool('dual')
+        .execute(async () => ({ from: 'server' }))
+        .clientExecute(async () => ({ from: 'client' }));
+
+      const serverCtx = aui.createContext({ isServer: true });
+      const result = await tool.run({}, serverCtx);
+      expect(result).toEqual({ from: 'server' });
+    });
+
+    it('should use client execute when on client', async () => {
+      const tool = aui
+        .tool('dual')
+        .execute(async () => ({ from: 'server' }))
+        .clientExecute(async () => ({ from: 'client' }));
+
+      const clientCtx = aui.createContext({ isServer: false });
+      const result = await tool.run({}, clientCtx);
+      expect(result).toEqual({ from: 'client' });
+    });
+  });
+
+  describe('Middleware', () => {
+    it('should apply middleware in order', async () => {
+      const log: string[] = [];
+      
+      const tool = aui
+        .tool('middleware')
+        .middleware(async ({ next }) => {
+          log.push('before-1');
+          const result = await next();
+          log.push('after-1');
+          return result;
+        })
+        .middleware(async ({ next }) => {
+          log.push('before-2');
+          const result = await next();
+          log.push('after-2');
+          return result;
+        })
+        .execute(async () => {
+          log.push('execute');
+          return { done: true };
+        });
+
+      await tool.run({});
+      expect(log).toEqual(['before-1', 'before-2', 'execute', 'after-2', 'after-1']);
+    });
+
+    it('should pass context through middleware', async () => {
+      const tool = aui
+        .tool('context-test')
+        .input(z.object({ value: z.number() }))
+        .middleware(async ({ input, ctx, next }) => {
+          ctx.cache.set('multiplier', 2);
+          return next();
+        })
+        .execute(async ({ input, ctx }) => {
+          const multiplier = ctx?.cache.get('multiplier') || 1;
+          return { result: input.value * multiplier };
+        });
+
+      const result = await tool.run({ value: 5 });
+      expect(result).toEqual({ result: 10 });
+    });
+  });
+
+  describe('Tool Registry', () => {
+    it('should register and retrieve tools', () => {
+      const tool1 = aui.tool('tool1').execute(async () => ({}));
+      const tool2 = aui.tool('tool2').execute(async () => ({}));
+
+      expect(aui.has('tool1')).toBe(true);
+      expect(aui.has('tool2')).toBe(true);
+      expect(aui.getToolNames()).toContain('tool1');
+      expect(aui.getToolNames()).toContain('tool2');
+    });
+
+    it('should support tags', () => {
+      const tool1 = aui.tool('tagged1').tag('ai', 'control').execute(async () => ({}));
+      const tool2 = aui.tool('tagged2').tag('ai', 'navigation').execute(async () => ({}));
+      const tool3 = aui.tool('tagged3').tag('control').execute(async () => ({}));
+
+      const aiTools = aui.findByTag('ai');
+      expect(aiTools).toHaveLength(2);
+      
+      const controlTools = aui.findByTags('ai', 'control');
+      expect(controlTools).toHaveLength(1);
+      expect(controlTools[0].name).toBe('tagged1');
+    });
+  });
+
+  describe('Tool Metadata', () => {
+    it('should store and retrieve metadata', () => {
+      const tool = aui
+        .tool('documented')
+        .describe('This tool does something important')
+        .tag('important', 'documented')
+        .input(z.object({ data: z.string() }))
+        .execute(async ({ input }) => ({ processed: input.data }));
+
+      expect(tool.name).toBe('documented');
+      expect(tool.description).toBe('This tool does something important');
+      expect(tool.tags).toEqual(['important', 'documented']);
+    });
+
+    it('should serialize to JSON', () => {
+      const tool = aui
+        .tool('json-tool')
+        .describe('JSON serializable tool')
+        .input(z.object({ x: z.number() }))
+        .execute(async () => ({}))
+        .clientExecute(async () => ({}))
+        .middleware(async ({ next }) => next());
+
+      const json = tool.toJSON();
+      expect(json).toEqual({
+        name: 'json-tool',
+        description: 'JSON serializable tool',
+        tags: [],
+        hasInput: true,
+        hasExecute: true,
+        hasClientExecute: true,
+        hasRender: false,
+        hasMiddleware: true
+      });
+    });
+  });
+
+  describe('Caching Context', () => {
+    it('should cache results in context', async () => {
+      let executionCount = 0;
+      
+      const tool = aui
+        .tool('cacheable')
+        .input(z.object({ key: z.string() }))
+        .clientExecute(async ({ input, ctx }) => {
+          const cached = ctx.cache.get(input.key);
+          if (cached) return cached;
+          
+          executionCount++;
+          const result = { value: `computed-${input.key}`, count: executionCount };
+          ctx.cache.set(input.key, result);
+          return result;
+        });
+
+      const ctx = aui.createContext({ isServer: false });
+      
+      const result1 = await tool.run({ key: 'test' }, ctx);
+      const result2 = await tool.run({ key: 'test' }, ctx);
+      const result3 = await tool.run({ key: 'other' }, ctx);
+      
+      expect(result1).toEqual(result2);
+      expect(executionCount).toBe(2); // Once for 'test', once for 'other'
+    });
+  });
+});