ai-functions 2.0.2 → 2.1.3

package/test/generate.test.js

@@ -0,0 +1,143 @@
+/**
+ * Tests for generateObject and generateText
+ *
+ * These tests use real AI calls via the Cloudflare AI Gateway.
+ * The gateway caches responses, so repeated test runs are fast and free.
+ *
+ * Required env vars:
+ * - AI_GATEWAY_URL: Cloudflare AI Gateway URL
+ * - AI_GATEWAY_TOKEN: Gateway auth token (or individual provider keys)
+ */
+import { describe, it, expect } from 'vitest';
+import { generateObject, generateText } from '../src/index.js';
+// Skip tests if no gateway configured
+const hasGateway = !!process.env.AI_GATEWAY_URL || !!process.env.ANTHROPIC_API_KEY;
+describe.skipIf(!hasGateway)('generateObject', () => {
+    it('generates a simple object with string fields', async () => {
+        const { object } = await generateObject({
+            model: 'sonnet',
+            schema: {
+                greeting: 'A friendly greeting',
+                language: 'The language of the greeting',
+            },
+            prompt: 'Generate a greeting in French',
+        });
+        expect(object).toBeDefined();
+        expect(typeof object.greeting).toBe('string');
+        expect(typeof object.language).toBe('string');
+        expect(object.greeting.length).toBeGreaterThan(0);
+    });
+    it('generates object with number fields', async () => {
+        const { object } = await generateObject({
+            model: 'sonnet',
+            schema: {
+                name: 'City name',
+                population: 'Population in millions (number)',
+                area: 'Area in square kilometers (number)',
+            },
+            prompt: 'Generate info about Tokyo',
+        });
+        expect(object).toBeDefined();
+        expect(typeof object.name).toBe('string');
+        expect(typeof object.population).toBe('number');
+        expect(typeof object.area).toBe('number');
+    });
+    it('generates object with array fields', async () => {
+        const { object } = await generateObject({
+            model: 'sonnet',
+            schema: {
+                title: 'Recipe title',
+                ingredients: ['List of ingredients'],
+                steps: ['Cooking steps'],
+            },
+            prompt: 'Generate a simple pasta recipe',
+        });
+        expect(object).toBeDefined();
+        expect(typeof object.title).toBe('string');
+        expect(Array.isArray(object.ingredients)).toBe(true);
+        expect(Array.isArray(object.steps)).toBe(true);
+        expect(object.ingredients.length).toBeGreaterThan(0);
+        expect(object.steps.length).toBeGreaterThan(0);
+    });
+    it('generates object with enum fields', async () => {
+        const { object } = await generateObject({
+            model: 'sonnet',
+            schema: {
+                sentiment: 'positive | negative | neutral',
+                confidence: 'Confidence score (number)',
+            },
+            prompt: 'Analyze sentiment: "I love this product!"',
+        });
+        expect(object).toBeDefined();
+        expect(['positive', 'negative', 'neutral']).toContain(object.sentiment);
+        expect(typeof object.confidence).toBe('number');
+    });
+    it('generates nested objects', async () => {
+        const { object } = await generateObject({
+            model: 'sonnet',
+            schema: {
+                person: {
+                    name: 'Full name',
+                    age: 'Age (number)',
+                },
+                address: {
+                    city: 'City name',
+                    country: 'Country name',
+                },
+            },
+            prompt: 'Generate a fictional person living in Japan',
+        });
+        expect(object).toBeDefined();
+        expect(typeof object.person.name).toBe('string');
+        expect(typeof object.person.age).toBe('number');
+        expect(typeof object.address.city).toBe('string');
+        expect(typeof object.address.country).toBe('string');
+    });
+    it('respects system prompt', async () => {
+        const { object } = await generateObject({
+            model: 'sonnet',
+            schema: {
+                response: 'Your response',
+                style: 'formal | casual | pirate',
+            },
+            system: 'You are a pirate. Respond in pirate speak.',
+            prompt: 'Say hello',
+        });
+        expect(object).toBeDefined();
+        expect(object.style).toBe('pirate');
+    });
+});
+describe.skipIf(!hasGateway)('generateText', () => {
+    it('generates simple text response', async () => {
+        const { text } = await generateText({
+            model: 'sonnet',
+            prompt: 'Say "Hello, World!" and nothing else.',
+        });
+        expect(text).toBeDefined();
+        expect(typeof text).toBe('string');
+        expect(text.toLowerCase()).toContain('hello');
+    });
+    it('respects system prompt', async () => {
+        const { text } = await generateText({
+            model: 'sonnet',
+            system: 'You only respond with exactly 3 words.',
+            prompt: 'How are you?',
+        });
+        expect(text).toBeDefined();
+        // Should be approximately 3 words
+        const wordCount = text.trim().split(/\s+/).length;
+        expect(wordCount).toBeLessThanOrEqual(5); // Allow some flexibility
+    });
+    it('handles multi-turn messages', async () => {
+        const { text } = await generateText({
+            model: 'sonnet',
+            messages: [
+                { role: 'user', content: 'My name is Alice.' },
+                { role: 'assistant', content: 'Nice to meet you, Alice!' },
+                { role: 'user', content: 'What is my name?' },
+            ],
+        });
+        expect(text).toBeDefined();
+        expect(text.toLowerCase()).toContain('alice');
+    });
+});

package/test/generic-order.test.ts

@@ -0,0 +1,342 @@
+/**
+ * GREEN Phase: Tests for <TOutput, TInput> generic order
+ *
+ * Issue: primitives.org.ai-z7f
+ *
+ * These tests verify that the generic type parameters follow
+ * the <TOutput, TInput> convention (output first, input second).
+ *
+ * The types have been fixed to use <TOutput, TInput> order.
+ */
+
+import { describe, it, expect } from 'vitest'
+import type {
+  AIFunctionDefinition,
+  BaseFunctionDefinition,
+  CodeFunctionDefinition,
+  GenerativeFunctionDefinition,
+  AgenticFunctionDefinition,
+  HumanFunctionDefinition,
+  DefinedFunction,
+  FunctionDefinition,
+} from '../src/types.js'
+
+// ============================================================================
+// Test data types
+// ============================================================================
+
+interface User {
+  id: string
+  name: string
+  email: string
+}
+
+interface CreateUserInput {
+  name: string
+  email: string
+}
+
+// ============================================================================
+// AIFunctionDefinition generic order tests
+// ============================================================================
+
+describe('AIFunctionDefinition<TOutput, TInput> generic order', () => {
+  describe('output-only usage (single generic)', () => {
+    it('AIFunctionDefinition<string> - first generic should be OUTPUT', () => {
+      // Order: AIFunctionDefinition<TOutput = string, TInput = unknown>
+      //   handler: (input: unknown) => string | Promise<string>
+
+      const def: AIFunctionDefinition<string> = {
+        name: 'test',
+        description: 'test',
+        parameters: {},
+        // handler accepts unknown, returns string
+        handler: (input: unknown) => String(input).toUpperCase(),
+      }
+
+      // Get the result - should be string | Promise<string>
+      const result = def.handler('test')
+
+      // This should compile - result is string | Promise<string>
+      const _s: string | Promise<string> = result
+      expect(result).toBe('TEST')
+    })
+  })
+
+  describe('two-generic usage', () => {
+    it('AIFunctionDefinition<string, number> - handler signature test', () => {
+      // Order: AIFunctionDefinition<TOutput = string, TInput = number>
+      //   handler: (input: number) => string | Promise<string>
+
+      const def: AIFunctionDefinition<string, number> = {
+        name: 'test',
+        description: 'test',
+        parameters: {},
+        // handler accepts number, returns string
+        handler: (input: number): string => `Value: ${input}`,
+      }
+
+      // handler should accept number
+      const result = def.handler(42)
+
+      // result should be string | Promise<string>
+      const _s: string | Promise<string> = result
+      expect(result).toBe('Value: 42')
+    })
+
+    it('AIFunctionDefinition<User, CreateUserInput> - real-world example', () => {
+      // Order: AIFunctionDefinition<TOutput = User, TInput = CreateUserInput>
+      //   handler: (input: CreateUserInput) => User | Promise<User>
+
+      const def: AIFunctionDefinition<User, CreateUserInput> = {
+        name: 'createUser',
+        description: 'Creates a user',
+        parameters: {},
+        // handler accepts CreateUserInput, returns User
+        handler: (input: CreateUserInput): User => ({
+          id: '1',
+          name: input.name,
+          email: input.email,
+        }),
+      }
+
+      // Should accept CreateUserInput
+      const result = def.handler({ name: 'Alice', email: 'alice@test.com' })
+
+      // Should return User with id
+      const _id: string = (result as User).id
+      expect((result as User).id).toBe('1')
+    })
+  })
+})
+
+// ============================================================================
+// BaseFunctionDefinition generic order tests
+// ============================================================================
+
+describe('BaseFunctionDefinition<TOutput, TInput> generic order', () => {
+  it('BaseFunctionDefinition<string, number> - args and returnType', () => {
+    // Order: BaseFunctionDefinition<TOutput = string, TInput = number>
+    //   args: number (TInput)
+    //   returnType?: string (TOutput)
+
+    const def: BaseFunctionDefinition<string, number> = {
+      name: 'test',
+      args: 42, // args is TInput (number)
+      returnType: 'result', // returnType is TOutput (string)
+    }
+
+    // args should be number
+    const _argsNum: number = def.args
+    expect(def.args).toBe(42)
+
+    // returnType should be string
+    const _retStr: string = def.returnType!
+    expect(def.returnType).toBe('result')
+  })
+})
+
+// ============================================================================
+// CodeFunctionDefinition generic order tests
+// ============================================================================
+
+describe('CodeFunctionDefinition<TOutput, TInput> generic order', () => {
+  it('CodeFunctionDefinition<string, {prompt:string}> - args and returnType', () => {
+    // Order: CodeFunctionDefinition<TOutput = string, TInput = {prompt:string}>
+
+    const def: CodeFunctionDefinition<string, { prompt: string }> = {
+      type: 'code',
+      name: 'test',
+      args: { prompt: 'generate code' }, // args is TInput
+      returnType: 'generated code', // returnType is TOutput
+      language: 'typescript',
+    }
+
+    // args should have prompt property
+    const _prompt: string = def.args.prompt
+    expect(def.args.prompt).toBe('generate code')
+
+    // returnType should be string
+    const _ret: string = def.returnType!
+    expect(def.returnType).toBe('generated code')
+  })
+})
+
+// ============================================================================
+// GenerativeFunctionDefinition generic order tests
+// ============================================================================
+
+describe('GenerativeFunctionDefinition<TOutput, TInput> generic order', () => {
+  it('GenerativeFunctionDefinition<Output, Input> - args and returnType', () => {
+    interface Output {
+      title: string
+      content: string
+    }
+    interface Input {
+      topic: string
+    }
+
+    // Order: GenerativeFunctionDefinition<TOutput = Output, TInput = Input>
+
+    const def: GenerativeFunctionDefinition<Output, Input> = {
+      type: 'generative',
+      name: 'test',
+      args: { topic: 'AI' }, // args is TInput
+      returnType: { title: 'AI Article', content: '...' }, // returnType is TOutput
+      output: 'object',
+    }
+
+    // args should have topic
+    const _topic: string = def.args.topic
+    expect(def.args.topic).toBe('AI')
+
+    // returnType should have title
+    const _title: string = def.returnType!.title
+    expect(def.returnType!.title).toBe('AI Article')
+  })
+})
+
+// ============================================================================
+// AgenticFunctionDefinition generic order tests
+// ============================================================================
+
+describe('AgenticFunctionDefinition<TOutput, TInput> generic order', () => {
+  it('AgenticFunctionDefinition<Output, Input> - args and returnType', () => {
+    interface Output {
+      result: string
+    }
+    interface Input {
+      query: string
+    }
+
+    // Order: AgenticFunctionDefinition<TOutput = Output, TInput = Input>
+
+    const def: AgenticFunctionDefinition<Output, Input> = {
+      type: 'agentic',
+      name: 'test',
+      args: { query: 'search' }, // args is TInput
+      returnType: { result: 'found' }, // returnType is TOutput
+      instructions: 'test',
+    }
+
+    // args should have query
+    const _query: string = def.args.query
+    expect(def.args.query).toBe('search')
+
+    // returnType should have result
+    const _result: string = def.returnType!.result
+    expect(def.returnType!.result).toBe('found')
+  })
+})
+
+// ============================================================================
+// HumanFunctionDefinition generic order tests
+// ============================================================================
+
+describe('HumanFunctionDefinition<TOutput, TInput> generic order', () => {
+  it('HumanFunctionDefinition<ApprovalResult, ApprovalInput> - args and returnType', () => {
+    interface ApprovalResult {
+      approved: boolean
+    }
+    interface ApprovalInput {
+      amount: number
+    }
+
+    // Order: HumanFunctionDefinition<TOutput = ApprovalResult, TInput = ApprovalInput>
+
+    const def: HumanFunctionDefinition<ApprovalResult, ApprovalInput> = {
+      type: 'human',
+      name: 'test',
+      args: { amount: 100 }, // args is TInput
+      returnType: { approved: true }, // returnType is TOutput
+      channel: 'workspace',
+      instructions: 'test',
+    }
+
+    // args should have amount
+    const _amount: number = def.args.amount
+    expect(def.args.amount).toBe(100)
+
+    // returnType should have approved
+    const _approved: boolean = def.returnType!.approved
+    expect(def.returnType!.approved).toBe(true)
+  })
+})
+
+// ============================================================================
+// DefinedFunction generic order tests
+// ============================================================================
+
+describe('DefinedFunction<TOutput, TInput> generic order', () => {
+  it('DefinedFunction<User, CreateUserInput> - call signature', () => {
+    // Order: DefinedFunction<TOutput = User, TInput = CreateUserInput>
+    //   call: (args: CreateUserInput) => Promise<User>
+
+    const defined: DefinedFunction<User, CreateUserInput> = {
+      definition: {} as FunctionDefinition<User, CreateUserInput>,
+      // call accepts CreateUserInput, returns Promise<User>
+      call: async (args: CreateUserInput): Promise<User> => ({
+        id: '1',
+        name: args.name,
+        email: args.email,
+      }),
+      asTool: () => ({}) as AIFunctionDefinition<User, CreateUserInput>,
+    }
+
+    // call should accept CreateUserInput
+    const promise = defined.call({ name: 'Alice', email: 'alice@test.com' })
+
+    // Should return Promise<User>
+    promise.then((result) => {
+      const _id: string = result.id
+      expect(result.id).toBe('1')
+    })
+  })
+})
+
+// ============================================================================
+// FunctionDefinition union type tests
+// ============================================================================
+
+describe('FunctionDefinition<TOutput, TInput> union type', () => {
+  it('FunctionDefinition<string, number> - args and returnType through union', () => {
+    // Order: FunctionDefinition<TOutput = string, TInput = number>
+
+    const def: FunctionDefinition<string, number> = {
+      type: 'code',
+      name: 'test',
+      args: 42, // args is TInput (number)
+      returnType: 'result', // returnType is TOutput (string)
+      language: 'typescript',
+    }
+
+    // args should be number
+    const _n: number = def.args
+    expect(def.args).toBe(42)
+
+    // returnType should be string
+    const _s: string = def.returnType!
+    expect(def.returnType).toBe('result')
+  })
+})
+
+// ============================================================================
+// Type inference tests
+// ============================================================================
+
+describe('type inference in generic contexts', () => {
+  it('extracting handler types', () => {
+    // Type to extract handler return from definition
+    type HandlerReturn<T> = T extends { handler: (...args: unknown[]) => infer R } ? R : never
+
+    // With <TOutput, TInput>: AIFunctionDefinition<string, number>
+    //   handler: (number) => string, so HandlerReturn = string | Promise<string>
+
+    type Def = AIFunctionDefinition<string, number>
+    type Result = HandlerReturn<Def>
+
+    // Result should be string | Promise<string>
+    const _s: Result = 'hello'
+    expect('hello').toBe('hello')
+  })
+})