ai-props 2.1.1 → 2.3.0

package/.dev.vars

@@ -0,0 +1,2 @@
+AI_GATEWAY_TOKEN=oS40l795q0Hrn-uKQ2Zew6utQV-GPrey6d9lUrlt
+AI_GATEWAY_URL=https://gateway.ai.cloudflare.com/v1/b6641681fe423910342b9ffa1364c76d/mdxai

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # ai-props
 
+## 2.3.0
+
+### Patch Changes
+
+- Updated dependencies [9e2779a]
+- Updated dependencies [2787830]
+  - ai-functions@2.3.0
+  - language-models@2.3.0
+  - ai-providers@2.3.0
+
+## 2.1.3
+
+### Patch Changes
+
+- Documentation and testing improvements
+
+  - Add deterministic AI testing suite with self-validating patterns
+  - Apply StoryBrand narrative to all package READMEs
+  - Update TESTING.md with four principles of deterministic AI testing
+  - Fix duplicate examples package name conflict
+
+- Updated dependencies
+  - ai-functions@2.1.3
+
 ## 2.1.1
 
 ### Patch Changes

package/README.md

@@ -1,44 +1,45 @@
 # ai-props
 
-AI-powered props primitives for intelligent component properties.
+![Stability: Experimental](https://img.shields.io/badge/stability-experimental-red)
 
-## Overview
+**Stop manually writing placeholder props. Let AI fill in the blanks.**
 
-`ai-props` provides utilities for automatically generating component props using AI based on schema definitions. It's designed to work seamlessly with React components, Next.js, and other frameworks.
+You've built a beautiful component library. But every time you use a component, you're stuck inventing placeholder text, mock data, and dummy content. Your `<UserCard />` needs a bio. Your `<ProductCard />` needs a description. Your `<SEOHead />` needs meta tags.
 
-## Installation
+What if your components could intelligently complete themselves?
 
-```bash
-npm install ai-props
-```
-
-## Quick Start
+## Before & After
 
 ```typescript
-import { AI, generateProps } from 'ai-props'
-
-// Define an AI-powered component schema
+// BEFORE: Manual placeholder props (tedious, repetitive, inconsistent)
+<UserCard
+  name="John Doe"
+  bio="Lorem ipsum dolor sit amet..."  // You've typed this a thousand times
+  avatar="/placeholder.png"
+/>
+
+// AFTER: AI-powered props (intelligent, contextual, automatic)
 const UserCard = AI({
   schema: {
     name: 'User name',
     bio: 'User biography',
     avatar: 'Avatar URL',
   },
-  defaults: {
-    avatar: '/default-avatar.png',
-  },
 })
 
-// Generate props with AI
-const props = await UserCard({ name: 'John' })
-// { name: 'John', bio: 'AI-generated bio...', avatar: '/default-avatar.png' }
+const props = await UserCard({ name: 'John Doe' })
+// { name: 'John Doe', bio: 'Software engineer passionate about...', avatar: 'https://...' }
 ```
 
-## Core Features
+## Quick Start
+
+### 1. Install
 
-### AI() Wrapper
+```bash
+npm install ai-props
+```
 
-Create AI-powered component wrappers that automatically fill in missing props:
+### 2. Define Your Schema
 
 ```typescript
 import { AI } from 'ai-props'
@@ -49,17 +50,48 @@ const ProductCard = AI({
     description: 'Product description',
     price: 'Price (number)',
   },
-  required: ['price'],  // Required props won't be generated
-  exclude: ['internal'], // Exclude props from generation
+  required: ['price'],  // AI won't generate required props
 })
+```
 
-// Use the component
+### 3. Generate Props
+
+```typescript
 const props = await ProductCard({ price: 99 })
+// { title: 'Premium Widget Pro', description: 'A high-quality...', price: 99 }
+```
+
+That's it. Your components now complete themselves intelligently.
+
+---
+
+## Core API
+
+### `AI()` - The Smart Component Wrapper
+
+Wrap any component schema to enable intelligent prop generation:
+
+```typescript
+import { AI } from 'ai-props'
+
+const UserCard = AI({
+  schema: {
+    name: 'Full name of the user',
+    bio: 'A short biography',
+    avatar: 'URL to avatar image',
+  },
+  defaults: {
+    avatar: '/default-avatar.png',
+  },
+  exclude: ['internal'],  // Never generate these props
+})
+
+const props = await UserCard({ name: 'Jane' })
 ```
 
-### generateProps()
+### `generateProps()` - Low-Level Generation
 
-Low-level function for direct prop generation:
+Direct access to prop generation with full metadata:
 
 ```typescript
 import { generateProps } from 'ai-props'
@@ -73,14 +105,14 @@ const result = await generateProps({
   context: { topic: 'AI-powered applications' },
 })
 
-console.log(result.props)    // Generated props
-console.log(result.cached)   // Whether result came from cache
-console.log(result.metadata) // Model info, duration, etc.
+console.log(result.props)     // Generated props
+console.log(result.cached)    // Cache hit?
+console.log(result.metadata)  // Model info, duration
 ```
 
-### createAIComponent()
+### `createAIComponent()` - Full TypeScript Support
 
-Create typed AI components:
+Get complete type inference for your generated props:
 
 ```typescript
 import { createAIComponent } from 'ai-props'
@@ -94,18 +126,19 @@ interface ProductProps {
 const ProductCard = createAIComponent<ProductProps>({
   schema: {
     title: 'Product title',
-    price: 'Price (number)',
+    price: 'Price in USD (number)',
     description: 'Product description',
   },
 })
 
-const props = await ProductCard({})
-// props is typed as ProductProps
+const props = await ProductCard({})  // Typed as ProductProps
 ```
 
-### createComponentFactory()
+---
 
-Create a factory for generating multiple instances:
+## Batch & Factory Patterns
+
+### Generate Multiple Items
 
 ```typescript
 import { createComponentFactory } from 'ai-props'
@@ -117,25 +150,18 @@ const factory = createComponentFactory({
   },
 })
 
-// Generate a single instance
+// Single item
 const product = await factory.generate({ category: 'electronics' })
 
-// Generate multiple instances
+// Multiple items in parallel
 const products = await factory.generateMany([
   { category: 'electronics' },
   { category: 'clothing' },
+  { category: 'home' },
 ])
-
-// Generate with overrides
-const custom = await factory.generateWith(
-  { category: 'tech' },
-  { price: 99 }
-)
 ```
 
-### composeAIComponents()
-
-Compose multiple schemas together:
+### Compose Multiple Schemas
 
 ```typescript
 import { composeAIComponents } from 'ai-props'
@@ -155,11 +181,11 @@ const profile = await FullProfile({
 })
 ```
 
-## HOC Utilities
+---
 
-### createPropsEnhancer()
+## SSR & Framework Integration
 
-Create a props enhancer for any component system:
+### Props Enhancer
 
 ```typescript
 import { createPropsEnhancer } from 'ai-props'
@@ -169,15 +195,13 @@ const enhancer = createPropsEnhancer({
     title: 'Page title',
     description: 'Page description',
   },
-  defaults: { title: 'Default Title' },
+  defaults: { title: 'My App' },
 })
 
-const props = await enhancer({ description: 'My page' })
+const props = await enhancer({ description: 'Welcome page' })
 ```
 
-### createAsyncPropsProvider()
-
-Create an async props provider for SSR:
+### Async Props Provider (Next.js)
 
 ```typescript
 import { createAsyncPropsProvider } from 'ai-props'
@@ -196,9 +220,7 @@ export async function getStaticProps() {
 }
 ```
 
-### createBatchGenerator()
-
-Generate props for multiple items efficiently:
+### Batch Generation
 
 ```typescript
 import { createBatchGenerator } from 'ai-props'
@@ -214,15 +236,16 @@ const items = await batch.generate([
 ])
 ```
 
-## Validation
+---
 
-### validateProps()
+## Validation
 
-Validate props against a schema:
+Ensure your props match expectations:
 
 ```typescript
-import { validateProps } from 'ai-props'
+import { validateProps, assertValidProps } from 'ai-props'
 
+// Validate and get errors
 const result = validateProps(
   { name: 'John', age: '25' },
   { name: 'Name', age: 'Age (number)' }
@@ -232,78 +255,56 @@ if (!result.valid) {
   console.log(result.errors)
   // [{ path: 'age', message: 'Expected number, got string' }]
 }
-```
-
-### assertValidProps()
 
-Assert props are valid (throws on error):
-
-```typescript
-import { assertValidProps } from 'ai-props'
-
-assertValidProps(
-  { name: 'John', age: 25 },
-  { name: 'Name', age: 'Age (number)' }
-)
+// Or throw on invalid
+assertValidProps(props, schema)
 ```
 
-### Other Validation Utilities
+### Validation Utilities
 
 ```typescript
 import {
   hasRequiredProps,
   getMissingProps,
   isComplete,
-  getMissingFromSchema,
   sanitizeProps,
   mergeWithDefaults,
   createValidator,
 } from 'ai-props'
 
-// Check required props
-hasRequiredProps({ name: 'John' }, ['name', 'email']) // false
-
-// Get missing props
-getMissingProps({ name: 'John' }, ['name', 'email']) // ['email']
-
-// Check schema completion
-isComplete({ name: 'John' }, { name: 'Name', age: 'Age' }) // false
-
-// Sanitize extra props
-sanitizeProps({ name: 'John', extra: 'value' }, { name: 'Name' })
-// { name: 'John' }
+hasRequiredProps({ name: 'John' }, ['name', 'email'])  // false
+getMissingProps({ name: 'John' }, ['name', 'email'])   // ['email']
+isComplete({ name: 'John' }, { name: 'Name', age: 'Age' })  // false
+sanitizeProps({ name: 'John', extra: 'x' }, { name: 'Name' })  // { name: 'John' }
 
-// Merge with defaults
-mergeWithDefaults({ name: 'John' }, { age: 0 }, { name: 'Name', age: 'Age' })
-// { name: 'John', age: 0 }
-
-// Create reusable validator
 const validate = createValidator({ name: 'Name', age: 'Age (number)' })
-validate({ name: 'John', age: 25 }) // { valid: true, errors: [] }
+validate({ name: 'John', age: 25 })  // { valid: true, errors: [] }
 ```
 
+---
+
 ## Caching
 
-### Cache Configuration
+Avoid redundant AI calls with built-in caching:
 
 ```typescript
 import { configureAIProps, configureCache, clearCache } from 'ai-props'
 
-// Configure global settings
+// Global configuration
 configureAIProps({
   model: 'gpt-4',
   cache: true,
-  cacheTTL: 5 * 60 * 1000, // 5 minutes
+  cacheTTL: 5 * 60 * 1000,  // 5 minutes
 })
 
-// Configure cache with custom TTL
-configureCache(10 * 60 * 1000) // 10 minutes
+// Or configure cache directly
+configureCache(10 * 60 * 1000)
 
-// Clear all cached props
+// Clear when needed
 clearCache()
 ```
 
-### Cache Classes
+### Cache Implementations
 
 ```typescript
 import { MemoryPropsCache, LRUPropsCache } from 'ai-props'
@@ -314,17 +315,15 @@ const memCache = new MemoryPropsCache(5 * 60 * 1000)
 // LRU cache with max entries
 const lruCache = new LRUPropsCache(100, 5 * 60 * 1000)
 
-// Cache operations
 lruCache.set('key', { name: 'John' })
 const entry = lruCache.get<{ name: string }>('key')
-lruCache.delete('key')
-lruCache.clear()
-console.log(lruCache.size)
 ```
 
+---
+
 ## Schema Type Hints
 
-Use type hints in schema strings:
+Use type hints in your schema strings for precise generation:
 
 ```typescript
 const schema = {
@@ -341,33 +340,31 @@ const schema = {
 }
 ```
 
+---
+
 ## Configuration
 
 ```typescript
 import { configureAIProps, getConfig, resetConfig } from 'ai-props'
 
-// Configure globally
 configureAIProps({
-  model: 'sonnet',           // Default model
-  cache: true,               // Enable caching
-  cacheTTL: 300000,          // Cache TTL in ms
-  system: 'Custom prompt',   // System prompt
+  model: 'sonnet',
+  cache: true,
+  cacheTTL: 300000,
+  system: 'Generate realistic, contextual content',
   generate: async (schema, context) => {
-    // Custom generator
-    return { /* generated props */ }
+    // Custom generation logic
+    return { /* props */ }
   },
 })
 
-// Get current config
 const config = getConfig()
-
-// Reset to defaults
 resetConfig()
 ```
 
-## API Reference
+---
 
-### Types
+## TypeScript Reference
 
 ```typescript
 interface PropSchema {
@@ -412,6 +409,22 @@ interface ValidationError {
 }
 ```
 
+---
+
+## What You Achieve
+
+With `ai-props`, you:
+
+- **Ship faster** - No more inventing placeholder content
+- **Stay consistent** - AI generates contextually appropriate props
+- **Type safely** - Full TypeScript inference throughout
+- **Cache intelligently** - Avoid redundant AI calls
+- **Scale effortlessly** - Batch generation for multiple items
+
+Your components become smarter. Your development becomes faster. Your content becomes consistent.
+
+---
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-props",
-  "version": "2.1.1",
+  "version": "2.3.0",
   "description": "AI-powered props primitives for intelligent component properties",
   "type": "module",
   "main": "dist/index.js",
@@ -9,22 +9,48 @@
     ".": {
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts"
+    },
+    "./worker": {
+      "import": "./dist/worker.js",
+      "types": "./dist/worker.d.ts"
+    },
+    "./mdx": {
+      "import": "./dist/mdx.js",
+      "types": "./dist/mdx.d.ts"
+    },
+    "./streaming": {
+      "import": "./dist/streaming.js",
+      "types": "./dist/streaming.d.ts"
+    },
+    "./rpc": {
+      "import": "./dist/rpc.js",
+      "types": "./dist/rpc.d.ts"
+    },
+    "./client": {
+      "import": "./dist/client.js",
+      "types": "./dist/client.d.ts"
     }
   },
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch",
-    "test": "vitest",
+    "test": "vitest run",
+    "test:worker": "vitest --config vitest.workers.config.ts",
     "typecheck": "tsc --noEmit",
     "lint": "eslint .",
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "ai-functions": "2.1.1"
+    "ai-functions": "2.3.0",
+    "ai-providers": "2.3.0",
+    "language-models": "2.3.0",
+    "hono": "^4.0.0"
   },
   "devDependencies": {
+    "@cloudflare/vitest-pool-workers": "^0.8.0",
+    "@cloudflare/workers-types": "^4.20250109.0",
     "typescript": "^5.7.2",
-    "vitest": "^2.1.9"
+    "vitest": "3.0.4"
   },
   "keywords": [
     "ai",

package/src/ai.ts

@@ -8,12 +8,7 @@
  */
 
 import type { SimpleSchema } from 'ai-functions'
-import type {
-  PropSchema,
-  AIComponentOptions,
-  AIComponent,
-  AIPropsConfig,
-} from './types.js'
+import type { PropSchema, AIComponentOptions, AIComponent, AIPropsConfig } from './types.js'
 import { generateProps, mergeWithGenerated } from './generate.js'
 
 /**
@@ -59,23 +54,17 @@ export function AI<P extends Record<string, unknown>>(
 
     // Check if all required props are provided
     const missingRequired = (required as string[]).filter(
-      key => propsWithDefaults[key as keyof P] === undefined
+      (key) => propsWithDefaults[key as keyof P] === undefined
     )
     if (missingRequired.length > 0) {
-      throw new Error(
-        `Missing required props: ${missingRequired.join(', ')}`
-      )
+      throw new Error(`Missing required props: ${missingRequired.join(', ')}`)
     }
 
     // Generate missing props
-    const fullProps = await mergeWithGenerated<P>(
-      filteredSchema,
-      propsWithDefaults as Partial<P>,
-      {
-        model: config.model,
-        system: config.system,
-      }
-    )
+    const fullProps = await mergeWithGenerated<P>(filteredSchema, propsWithDefaults as Partial<P>, {
+      ...(config.model !== undefined && { model: config.model }),
+      ...(config.system !== undefined && { system: config.system }),
+    })
 
     return fullProps
   }
@@ -145,9 +134,7 @@ export function createAIComponent<P extends Record<string, unknown>>(
  * })
  * ```
  */
-export function definePropsSchema<T extends Record<string, string | SimpleSchema>>(
-  schema: T
-): T {
+export function definePropsSchema<T extends Record<string, string | SimpleSchema>>(schema: T): T {
   return schema
 }
 
@@ -185,16 +172,13 @@ export function createComponentFactory<P extends Record<string, unknown>>(
      * Generate multiple instances
      */
     generateMany: async (contexts: Partial<P>[]): Promise<P[]> => {
-      return Promise.all(contexts.map(ctx => component(ctx)))
+      return Promise.all(contexts.map((ctx) => component(ctx)))
     },
 
     /**
      * Generate with specific overrides
      */
-    generateWith: async (
-      context: Partial<P>,
-      overrides: Partial<P>
-    ): Promise<P> => {
+    generateWith: async (context: Partial<P>, overrides: Partial<P>): Promise<P> => {
       const generated = await component(context)
       return { ...generated, ...overrides }
     },
@@ -232,9 +216,7 @@ export function composeAIComponents<
     [K in keyof T]: T[K] extends AIComponentOptions<infer P> ? P : never
   }
 
-  const aiComponent = async (
-    partialProps: Partial<ResultProps>
-  ): Promise<ResultProps> => {
+  const aiComponent = async (partialProps: Partial<ResultProps>): Promise<ResultProps> => {
     const results: Record<string, unknown> = {}
 
     // Generate each component's props
@@ -257,8 +239,7 @@ export function composeAIComponents<
 
   aiComponent.schema = composedSchema as PropSchema
   aiComponent.config = {}
-  aiComponent.generateProps = (context?: Partial<ResultProps>) =>
-    aiComponent(context || {})
+  aiComponent.generateProps = (context?: Partial<ResultProps>) => aiComponent(context || {})
 
   return aiComponent as AIComponent<ResultProps>
 }