ai-props 0.1.2 → 2.0.2

package/src/generate.ts

@@ -0,0 +1,276 @@
+/**
+ * Props generation for ai-props
+ *
+ * Core functionality for generating component props using AI.
+ *
+ * @packageDocumentation
+ */
+
+import { generateObject, schema as createSchema, type SimpleSchema } from 'ai-functions'
+import type {
+  PropSchema,
+  GeneratePropsOptions,
+  GeneratePropsResult,
+  AIPropsConfig,
+} from './types.js'
+import { createCacheKey, getDefaultCache } from './cache.js'
+
+/**
+ * Default configuration
+ */
+const DEFAULT_CONFIG: AIPropsConfig = {
+  model: 'sonnet',
+  cache: true,
+  cacheTTL: 5 * 60 * 1000, // 5 minutes
+}
+
+/**
+ * Global configuration
+ */
+let globalConfig: AIPropsConfig = { ...DEFAULT_CONFIG }
+
+/**
+ * Configure global AI props settings
+ */
+export function configureAIProps(config: Partial<AIPropsConfig>): void {
+  globalConfig = { ...globalConfig, ...config }
+}
+
+/**
+ * Get current configuration
+ */
+export function getConfig(): AIPropsConfig {
+  return { ...globalConfig }
+}
+
+/**
+ * Reset configuration to defaults
+ */
+export function resetConfig(): void {
+  globalConfig = { ...DEFAULT_CONFIG }
+}
+
+/**
+ * Resolve a prop schema to a SimpleSchema
+ *
+ * If the schema is a string, it's treated as a named type
+ * that generates a single property or description.
+ */
+function resolveSchema(schema: PropSchema): SimpleSchema {
+  if (typeof schema === 'string') {
+    // Named type or description string
+    return { value: schema }
+  }
+  return schema as SimpleSchema
+}
+
+/**
+ * Build a prompt from context and schema
+ */
+function buildPrompt(
+  schema: PropSchema,
+  context?: Record<string, unknown>,
+  additionalPrompt?: string
+): string {
+  const parts: string[] = []
+
+  // Add context information
+  if (context && Object.keys(context).length > 0) {
+    parts.push('Given the following context:')
+    parts.push(JSON.stringify(context, null, 2))
+    parts.push('')
+  }
+
+  // Add schema information
+  if (typeof schema === 'string') {
+    parts.push(`Generate a value for: ${schema}`)
+  } else {
+    parts.push('Generate props matching the schema.')
+  }
+
+  // Add additional prompt
+  if (additionalPrompt) {
+    parts.push('')
+    parts.push(additionalPrompt)
+  }
+
+  return parts.join('\n')
+}
+
+/**
+ * Generate props using AI
+ *
+ * @example
+ * ```ts
+ * const result = await generateProps({
+ *   schema: {
+ *     title: 'A compelling page title',
+ *     description: 'A brief description',
+ *     keywords: ['Relevant SEO keywords'],
+ *   },
+ *   context: { topic: 'AI-powered applications' },
+ * })
+ *
+ * console.log(result.props)
+ * // { title: '...', description: '...', keywords: [...] }
+ * ```
+ */
+export async function generateProps<T = Record<string, unknown>>(
+  options: GeneratePropsOptions
+): Promise<GeneratePropsResult<T>> {
+  const { schema, context, prompt, model, system } = options
+  const config = getConfig()
+  const startTime = Date.now()
+
+  // Check cache
+  if (config.cache) {
+    const cache = getDefaultCache()
+    const cacheKey = createCacheKey(schema, context)
+    const cached = cache.get<T>(cacheKey)
+
+    if (cached) {
+      return {
+        props: cached.props,
+        cached: true,
+        metadata: {
+          model: config.model || 'cached',
+        },
+      }
+    }
+  }
+
+  // Resolve schema
+  const resolvedSchema = resolveSchema(schema)
+
+  // Build prompt
+  const fullPrompt = buildPrompt(schema, context, prompt)
+
+  // Use custom generator if provided
+  if (config.generate) {
+    const props = await config.generate<T>(resolvedSchema, context || {})
+    return {
+      props,
+      cached: false,
+      metadata: {
+        model: 'custom',
+        duration: Date.now() - startTime,
+      },
+    }
+  }
+
+  // Generate using AI
+  const result = await generateObject({
+    model: model || config.model || 'sonnet',
+    schema: resolvedSchema,
+    prompt: fullPrompt,
+    system: system || config.system,
+  })
+
+  const props = result.object as T
+
+  // Cache result
+  if (config.cache) {
+    const cache = getDefaultCache()
+    const cacheKey = createCacheKey(schema, context)
+    cache.set(cacheKey, props)
+  }
+
+  return {
+    props,
+    cached: false,
+    metadata: {
+      model: model || config.model || 'sonnet',
+      duration: Date.now() - startTime,
+    },
+  }
+}
+
+/**
+ * Generate props synchronously from cache or throw
+ *
+ * Useful for SSR scenarios where async isn't available.
+ * Throws if props aren't in cache.
+ */
+export function getPropsSync<T = Record<string, unknown>>(
+  schema: PropSchema,
+  context?: Record<string, unknown>
+): T {
+  const cache = getDefaultCache()
+  const cacheKey = createCacheKey(schema, context)
+  const cached = cache.get<T>(cacheKey)
+
+  if (!cached) {
+    throw new Error(
+      'Props not in cache. Use generateProps() first or ensure caching is enabled.'
+    )
+  }
+
+  return cached.props
+}
+
+/**
+ * Pre-generate props for warming the cache
+ *
+ * @example
+ * ```ts
+ * await prefetchProps([
+ *   { schema: userProfileSchema, context: { userId: '123' } },
+ *   { schema: productSchema, context: { category: 'electronics' } },
+ * ])
+ * ```
+ */
+export async function prefetchProps(
+  requests: GeneratePropsOptions[]
+): Promise<void> {
+  await Promise.all(requests.map(generateProps))
+}
+
+/**
+ * Generate multiple prop sets in parallel
+ */
+export async function generatePropsMany<T = Record<string, unknown>>(
+  requests: GeneratePropsOptions[]
+): Promise<GeneratePropsResult<T>[]> {
+  return Promise.all(requests.map(req => generateProps<T>(req)))
+}
+
+/**
+ * Merge partial props with generated props
+ *
+ * Generates only the missing props, keeping provided ones.
+ */
+export async function mergeWithGenerated<T extends Record<string, unknown>>(
+  schema: PropSchema,
+  partialProps: Partial<T>,
+  options?: Omit<GeneratePropsOptions, 'schema' | 'context'>
+): Promise<T> {
+  // Get list of missing keys
+  const schemaObj = typeof schema === 'string' ? { value: schema } : schema
+  const schemaKeys = Object.keys(schemaObj as Record<string, unknown>)
+  const providedKeys = Object.keys(partialProps)
+  const missingKeys = schemaKeys.filter(k => !providedKeys.includes(k))
+
+  // If all props are provided, return as-is
+  if (missingKeys.length === 0) {
+    return partialProps as T
+  }
+
+  // Build partial schema for missing props only
+  const partialSchema: Record<string, unknown> = {}
+  for (const key of missingKeys) {
+    partialSchema[key] = (schemaObj as Record<string, unknown>)[key]
+  }
+
+  // Generate missing props
+  const result = await generateProps<Partial<T>>({
+    schema: partialSchema as SimpleSchema,
+    context: partialProps as Record<string, unknown>,
+    ...options,
+  })
+
+  // Merge
+  return {
+    ...result.props,
+    ...partialProps,
+  } as T
+}

package/src/hoc.ts

@@ -0,0 +1,309 @@
+/**
+ * Higher-Order Component (HOC) for React components
+ *
+ * Provides withAIProps HOC for wrapping React components
+ * with AI-powered prop generation.
+ *
+ * @packageDocumentation
+ */
+
+import type { SimpleSchema } from 'ai-functions'
+import type { PropSchema, AIComponentOptions, AIPropsConfig } from './types.js'
+import { generateProps, mergeWithGenerated } from './generate.js'
+
+/**
+ * Options for withAIProps HOC
+ */
+export interface WithAIPropsOptions<P> extends Omit<AIComponentOptions<P>, 'schema'> {
+  /** Schema for props to generate */
+  schema: PropSchema
+  /** Loading component to show while generating */
+  loading?: () => unknown
+  /** Error component to show on generation failure */
+  error?: (error: Error) => unknown
+  /** Fallback props to use if generation fails */
+  fallback?: Partial<P>
+}
+
+/**
+ * Create props wrapper that can be used with any component system
+ *
+ * This is framework-agnostic and returns the enhanced props.
+ *
+ * @example
+ * ```ts
+ * const enhancer = createPropsEnhancer({
+ *   schema: {
+ *     title: 'Page title',
+ *     description: 'Page description',
+ *   },
+ *   defaults: {
+ *     title: 'Default Title',
+ *   },
+ * })
+ *
+ * // Use with any component
+ * const props = await enhancer({ description: 'My page' })
+ * // { title: 'Default Title', description: 'My page' }
+ *
+ * const generatedProps = await enhancer({})
+ * // { title: 'AI-generated title', description: 'AI-generated description' }
+ * ```
+ */
+export function createPropsEnhancer<P extends Record<string, unknown>>(
+  options: WithAIPropsOptions<P>
+) {
+  const { schema, defaults = {}, required = [], exclude = [], config = {}, fallback } = options
+
+  return async (partialProps: Partial<P>): Promise<P> => {
+    try {
+      // Merge with defaults
+      const propsWithDefaults = { ...defaults, ...partialProps }
+
+      // Check required props
+      const missingRequired = (required as string[]).filter(
+        key => propsWithDefaults[key as keyof P] === undefined
+      )
+      if (missingRequired.length > 0) {
+        throw new Error(`Missing required props: ${missingRequired.join(', ')}`)
+      }
+
+      // Filter out excluded props from schema
+      const filteredSchema = filterSchemaKeys(schema, exclude as string[])
+
+      // Generate missing props
+      return await mergeWithGenerated<P>(
+        filteredSchema,
+        propsWithDefaults as Partial<P>,
+        {
+          model: config.model,
+          system: config.system,
+        }
+      )
+    } catch (error) {
+      if (fallback) {
+        return { ...defaults, ...fallback, ...partialProps } as P
+      }
+      throw error
+    }
+  }
+}
+
+/**
+ * Filter schema to exclude certain keys
+ */
+function filterSchemaKeys(schema: PropSchema, exclude: string[]): PropSchema {
+  if (typeof schema === 'string' || exclude.length === 0) {
+    return schema
+  }
+
+  const filtered: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(schema)) {
+    if (!exclude.includes(key)) {
+      filtered[key] = value
+    }
+  }
+  return filtered as SimpleSchema
+}
+
+/**
+ * Create an async props provider
+ *
+ * Returns a function that generates props on each call.
+ * Useful for SSR and static generation.
+ *
+ * @example
+ * ```ts
+ * const getPageProps = createAsyncPropsProvider({
+ *   schema: {
+ *     title: 'SEO-optimized page title',
+ *     meta: { description: 'Meta description' },
+ *   },
+ * })
+ *
+ * // In getStaticProps or getServerSideProps
+ * export async function getStaticProps() {
+ *   const props = await getPageProps({ slug: 'about' })
+ *   return { props }
+ * }
+ * ```
+ */
+export function createAsyncPropsProvider<P extends Record<string, unknown>>(
+  options: WithAIPropsOptions<P>
+) {
+  const enhancer = createPropsEnhancer(options)
+
+  return {
+    /**
+     * Get props with AI generation
+     */
+    getProps: enhancer,
+
+    /**
+     * Get props for multiple items
+     */
+    getManyProps: async (contexts: Partial<P>[]): Promise<P[]> => {
+      return Promise.all(contexts.map(enhancer))
+    },
+
+    /**
+     * Get props with caching hint
+     */
+    getCachedProps: async (
+      context: Partial<P>,
+      revalidate?: number
+    ): Promise<{ props: P; revalidate?: number }> => {
+      const props = await enhancer(context)
+      return { props, revalidate }
+    },
+  }
+}
+
+/**
+ * Create a props transformer
+ *
+ * Transforms existing props by filling in missing values.
+ *
+ * @example
+ * ```ts
+ * const transformUserProps = createPropsTransformer({
+ *   schema: {
+ *     displayName: 'Display name for the user',
+ *     initials: 'User initials (2 letters)',
+ *   },
+ * })
+ *
+ * const user = await transformUserProps({
+ *   username: 'johndoe',
+ *   email: 'john@example.com',
+ * })
+ * // { username: 'johndoe', email: '...', displayName: 'John Doe', initials: 'JD' }
+ * ```
+ */
+export function createPropsTransformer<
+  I extends Record<string, unknown>,
+  O extends Record<string, unknown>
+>(options: {
+  schema: PropSchema
+  transform?: (input: I, generated: Record<string, unknown>) => O
+  config?: AIPropsConfig
+}) {
+  const { schema, transform, config = {} } = options
+
+  return async (input: I): Promise<I & O> => {
+    const result = await generateProps({
+      schema,
+      context: input,
+      model: config.model,
+      system: config.system,
+    })
+
+    const generated = result.props as Record<string, unknown>
+
+    if (transform) {
+      return { ...input, ...transform(input, generated) }
+    }
+
+    return { ...input, ...generated } as I & O
+  }
+}
+
+/**
+ * Create a conditional props generator
+ *
+ * Only generates props when a condition is met.
+ *
+ * @example
+ * ```ts
+ * const maybeGenerateProps = createConditionalGenerator({
+ *   schema: { summary: 'Article summary' },
+ *   condition: (props) => !props.summary && props.content?.length > 100,
+ * })
+ * ```
+ */
+export function createConditionalGenerator<P extends Record<string, unknown>>(options: {
+  schema: PropSchema
+  condition: (props: Partial<P>) => boolean
+  config?: AIPropsConfig
+}) {
+  const { schema, condition, config = {} } = options
+
+  return async (props: Partial<P>): Promise<P> => {
+    if (!condition(props)) {
+      return props as P
+    }
+
+    return mergeWithGenerated(schema, props, {
+      model: config.model,
+      system: config.system,
+    })
+  }
+}
+
+/**
+ * Batch props generator for list rendering
+ *
+ * Efficiently generates props for multiple items.
+ *
+ * @example
+ * ```ts
+ * const batchGenerator = createBatchGenerator({
+ *   schema: { title: 'Item title', description: 'Item description' },
+ * })
+ *
+ * const items = await batchGenerator.generate([
+ *   { id: 1, category: 'tech' },
+ *   { id: 2, category: 'science' },
+ *   { id: 3, category: 'art' },
+ * ])
+ * ```
+ */
+export function createBatchGenerator<P extends Record<string, unknown>>(options: {
+  schema: PropSchema
+  concurrency?: number
+  config?: AIPropsConfig
+}) {
+  const { schema, concurrency = 3, config = {} } = options
+
+  return {
+    /**
+     * Generate props for multiple items
+     */
+    generate: async (items: Partial<P>[]): Promise<P[]> => {
+      const results: P[] = []
+
+      // Process in batches based on concurrency
+      for (let i = 0; i < items.length; i += concurrency) {
+        const batch = items.slice(i, i + concurrency)
+        const batchResults = await Promise.all(
+          batch.map(item =>
+            mergeWithGenerated<P>(schema, item, {
+              model: config.model,
+              system: config.system,
+            })
+          )
+        )
+        results.push(...batchResults)
+      }
+
+      return results
+    },
+
+    /**
+     * Generate props one at a time (for rate limiting)
+     */
+    generateSequential: async (items: Partial<P>[]): Promise<P[]> => {
+      const results: P[] = []
+
+      for (const item of items) {
+        const result = await mergeWithGenerated<P>(schema, item, {
+          model: config.model,
+          system: config.system,
+        })
+        results.push(result)
+      }
+
+      return results
+    },
+  }
+}

package/src/index.ts

@@ -0,0 +1,66 @@
+/**
+ * ai-props - AI-powered props for intelligent component properties
+ *
+ * This package provides utilities for automatically generating
+ * component props using AI based on schema definitions.
+ *
+ * @packageDocumentation
+ */
+
+// Export types
+export * from './types.js'
+
+// Export core functionality
+export {
+  AI,
+  createAIComponent,
+  definePropsSchema,
+  createComponentFactory,
+  composeAIComponents,
+} from './ai.js'
+
+// Export generation functions
+export {
+  generateProps,
+  getPropsSync,
+  prefetchProps,
+  generatePropsMany,
+  mergeWithGenerated,
+  configureAIProps,
+  getConfig,
+  resetConfig,
+} from './generate.js'
+
+// Export cache utilities
+export {
+  MemoryPropsCache,
+  LRUPropsCache,
+  createCacheKey,
+  getDefaultCache,
+  configureCache,
+  clearCache,
+  DEFAULT_CACHE_TTL,
+} from './cache.js'
+
+// Export HOC and enhancers
+export {
+  createPropsEnhancer,
+  createAsyncPropsProvider,
+  createPropsTransformer,
+  createConditionalGenerator,
+  createBatchGenerator,
+  type WithAIPropsOptions,
+} from './hoc.js'
+
+// Export validation utilities
+export {
+  validateProps,
+  hasRequiredProps,
+  getMissingProps,
+  isComplete,
+  getMissingFromSchema,
+  sanitizeProps,
+  mergeWithDefaults,
+  createValidator,
+  assertValidProps,
+} from './validate.js'