ai-props 2.0.2 → 2.1.3

package/src/ai.js

@@ -0,0 +1,198 @@
+/**
+ * AI() wrapper for components with intelligent prop generation
+ *
+ * The AI() function wraps a component definition and automatically
+ * generates missing props using AI when the component is rendered.
+ *
+ * @packageDocumentation
+ */
+import { mergeWithGenerated } from './generate.js';
+/**
+ * Create an AI-powered component wrapper
+ *
+ * The returned function accepts partial props and generates
+ * any missing props using AI based on the schema.
+ *
+ * @example
+ * ```ts
+ * const UserCard = AI({
+ *   schema: {
+ *     name: 'Full name of the user',
+ *     bio: 'A short biography',
+ *     avatar: 'URL to avatar image',
+ *   },
+ *   defaults: {
+ *     avatar: 'https://example.com/default-avatar.png',
+ *   },
+ * })
+ *
+ * // Generate all props
+ * const props = await UserCard({})
+ *
+ * // Generate only missing props
+ * const props2 = await UserCard({ name: 'John Doe' })
+ * ```
+ */
+export function AI(options) {
+    const { schema, defaults = {}, required = [], exclude = [], config = {} } = options;
+    // Build filtered schema (exclude specified props)
+    const filteredSchema = filterSchema(schema, exclude);
+    /**
+     * The AI component function
+     */
+    const aiComponent = async (partialProps) => {
+        // Merge with defaults
+        const propsWithDefaults = { ...defaults, ...partialProps };
+        // Check if all required props are provided
+        const missingRequired = required.filter(key => propsWithDefaults[key] === undefined);
+        if (missingRequired.length > 0) {
+            throw new Error(`Missing required props: ${missingRequired.join(', ')}`);
+        }
+        // Generate missing props
+        const fullProps = await mergeWithGenerated(filteredSchema, propsWithDefaults, {
+            model: config.model,
+            system: config.system,
+        });
+        return fullProps;
+    };
+    // Attach metadata
+    aiComponent.schema = schema;
+    aiComponent.config = config;
+    // Attach helper method
+    aiComponent.generateProps = async (context) => {
+        return aiComponent(context || {});
+    };
+    return aiComponent;
+}
+/**
+ * Filter schema to exclude certain keys
+ */
+function filterSchema(schema, exclude) {
+    if (typeof schema === 'string') {
+        return schema;
+    }
+    const filtered = {};
+    for (const [key, value] of Object.entries(schema)) {
+        if (!exclude.includes(key)) {
+            filtered[key] = value;
+        }
+    }
+    return filtered;
+}
+/**
+ * Create a typed AI component with inference
+ *
+ * @example
+ * ```ts
+ * const ProductCard = createAIComponent<{
+ *   title: string
+ *   price: number
+ *   description: string
+ * }>({
+ *   schema: {
+ *     title: 'Product title',
+ *     price: 'Price in USD (number)',
+ *     description: 'Product description',
+ *   },
+ * })
+ * ```
+ */
+export function createAIComponent(options) {
+    return AI(options);
+}
+/**
+ * Define props schema with type inference
+ *
+ * @example
+ * ```ts
+ * const userSchema = definePropsSchema({
+ *   name: 'User name',
+ *   email: 'Email address',
+ *   age: 'Age (number)',
+ * })
+ * ```
+ */
+export function definePropsSchema(schema) {
+    return schema;
+}
+/**
+ * Create a component factory for generating multiple instances
+ *
+ * @example
+ * ```ts
+ * const factory = createComponentFactory({
+ *   schema: { name: 'Product name', price: 'Price (number)' },
+ * })
+ *
+ * const products = await factory.generateMany([
+ *   { category: 'electronics' },
+ *   { category: 'clothing' },
+ *   { category: 'food' },
+ * ])
+ * ```
+ */
+export function createComponentFactory(options) {
+    const component = AI(options);
+    return {
+        component,
+        schema: options.schema,
+        /**
+         * Generate a single instance
+         */
+        generate: (context) => component(context || {}),
+        /**
+         * Generate multiple instances
+         */
+        generateMany: async (contexts) => {
+            return Promise.all(contexts.map(ctx => component(ctx)));
+        },
+        /**
+         * Generate with specific overrides
+         */
+        generateWith: async (context, overrides) => {
+            const generated = await component(context);
+            return { ...generated, ...overrides };
+        },
+    };
+}
+/**
+ * Compose multiple AI components
+ *
+ * Creates a component that combines props from multiple schemas.
+ *
+ * @example
+ * ```ts
+ * const FullProfile = composeAIComponents({
+ *   user: userSchema,
+ *   settings: settingsSchema,
+ *   preferences: preferencesSchema,
+ * })
+ *
+ * const profile = await FullProfile({
+ *   user: { name: 'John' },
+ *   settings: {},
+ *   preferences: { theme: 'dark' },
+ * })
+ * ```
+ */
+export function composeAIComponents(components) {
+    const aiComponent = async (partialProps) => {
+        const results = {};
+        // Generate each component's props
+        await Promise.all(Object.entries(components).map(async ([key, options]) => {
+            const component = AI(options);
+            const partial = partialProps[key] || {};
+            results[key] = await component(partial);
+        }));
+        return results;
+    };
+    // Compose schemas
+    const composedSchema = {};
+    for (const [key, options] of Object.entries(components)) {
+        composedSchema[key] = options.schema;
+    }
+    aiComponent.schema = composedSchema;
+    aiComponent.config = {};
+    aiComponent.generateProps = (context) => aiComponent(context || {});
+    return aiComponent;
+}

package/src/cache.js

@@ -0,0 +1,182 @@
+/**
+ * Props caching for ai-props
+ *
+ * Provides in-memory caching for generated props to avoid
+ * redundant AI calls with the same context.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Default cache TTL (5 minutes)
+ */
+export const DEFAULT_CACHE_TTL = 5 * 60 * 1000;
+/**
+ * Create a cache key from schema and context
+ */
+export function createCacheKey(schema, context) {
+    const schemaStr = typeof schema === 'string' ? schema : JSON.stringify(schema);
+    const contextStr = context ? JSON.stringify(sortObject(context)) : '';
+    return `${hashString(schemaStr)}:${hashString(contextStr)}`;
+}
+/**
+ * Simple string hash function
+ */
+function hashString(str) {
+    let hash = 0;
+    for (let i = 0; i < str.length; i++) {
+        const char = str.charCodeAt(i);
+        hash = ((hash << 5) - hash) + char;
+        hash = hash & hash; // Convert to 32-bit integer
+    }
+    return hash.toString(36);
+}
+/**
+ * Sort object keys for consistent hashing
+ */
+function sortObject(obj) {
+    const sorted = {};
+    for (const key of Object.keys(obj).sort()) {
+        const value = obj[key];
+        sorted[key] = value && typeof value === 'object' && !Array.isArray(value)
+            ? sortObject(value)
+            : value;
+    }
+    return sorted;
+}
+/**
+ * In-memory props cache implementation
+ */
+export class MemoryPropsCache {
+    cache = new Map();
+    ttl;
+    constructor(ttl = DEFAULT_CACHE_TTL) {
+        this.ttl = ttl;
+    }
+    get(key) {
+        const entry = this.cache.get(key);
+        if (!entry)
+            return undefined;
+        // Check if expired
+        if (Date.now() - entry.timestamp > this.ttl) {
+            this.cache.delete(key);
+            return undefined;
+        }
+        return entry;
+    }
+    set(key, props) {
+        this.cache.set(key, {
+            props,
+            timestamp: Date.now(),
+            key
+        });
+    }
+    delete(key) {
+        return this.cache.delete(key);
+    }
+    clear() {
+        this.cache.clear();
+    }
+    get size() {
+        return this.cache.size;
+    }
+    /**
+     * Remove expired entries
+     */
+    cleanup() {
+        const now = Date.now();
+        let removed = 0;
+        for (const [key, entry] of this.cache) {
+            if (now - entry.timestamp > this.ttl) {
+                this.cache.delete(key);
+                removed++;
+            }
+        }
+        return removed;
+    }
+    /**
+     * Get all entries (for debugging)
+     */
+    entries() {
+        return this.cache.entries();
+    }
+}
+/**
+ * Global default cache instance
+ */
+let defaultCache = null;
+/**
+ * Get or create the default cache
+ */
+export function getDefaultCache() {
+    if (!defaultCache) {
+        defaultCache = new MemoryPropsCache();
+    }
+    return defaultCache;
+}
+/**
+ * Configure the default cache
+ */
+export function configureCache(ttl) {
+    defaultCache = new MemoryPropsCache(ttl);
+}
+/**
+ * Clear the default cache
+ */
+export function clearCache() {
+    if (defaultCache) {
+        defaultCache.clear();
+    }
+}
+/**
+ * LRU (Least Recently Used) cache implementation
+ * For scenarios where memory usage needs to be bounded
+ */
+export class LRUPropsCache {
+    cache = new Map();
+    maxSize;
+    ttl;
+    constructor(maxSize = 100, ttl = DEFAULT_CACHE_TTL) {
+        this.maxSize = maxSize;
+        this.ttl = ttl;
+    }
+    get(key) {
+        const entry = this.cache.get(key);
+        if (!entry)
+            return undefined;
+        // Check if expired
+        if (Date.now() - entry.timestamp > this.ttl) {
+            this.cache.delete(key);
+            return undefined;
+        }
+        // Move to end (most recently used)
+        this.cache.delete(key);
+        this.cache.set(key, entry);
+        return entry;
+    }
+    set(key, props) {
+        // Remove oldest entries if at capacity
+        while (this.cache.size >= this.maxSize) {
+            const oldest = this.cache.keys().next().value;
+            if (oldest) {
+                this.cache.delete(oldest);
+            }
+            else {
+                break;
+            }
+        }
+        this.cache.set(key, {
+            props,
+            timestamp: Date.now(),
+            key
+        });
+    }
+    delete(key) {
+        return this.cache.delete(key);
+    }
+    clear() {
+        this.cache.clear();
+    }
+    get size() {
+        return this.cache.size;
+    }
+}

package/src/generate.js

@@ -0,0 +1,220 @@
+/**
+ * Props generation for ai-props
+ *
+ * Core functionality for generating component props using AI.
+ *
+ * @packageDocumentation
+ */
+import { generateObject } from 'ai-functions';
+import { createCacheKey, getDefaultCache } from './cache.js';
+/**
+ * Default configuration
+ */
+const DEFAULT_CONFIG = {
+    model: 'sonnet',
+    cache: true,
+    cacheTTL: 5 * 60 * 1000, // 5 minutes
+};
+/**
+ * Global configuration
+ */
+let globalConfig = { ...DEFAULT_CONFIG };
+/**
+ * Configure global AI props settings
+ */
+export function configureAIProps(config) {
+    globalConfig = { ...globalConfig, ...config };
+}
+/**
+ * Get current configuration
+ */
+export function getConfig() {
+    return { ...globalConfig };
+}
+/**
+ * Reset configuration to defaults
+ */
+export function resetConfig() {
+    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) {
+    if (typeof schema === 'string') {
+        // Named type or description string
+        return { value: schema };
+    }
+    return schema;
+}
+/**
+ * Build a prompt from context and schema
+ */
+function buildPrompt(schema, context, additionalPrompt) {
+    const parts = [];
+    // 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(options) {
+    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(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(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;
+    // 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(schema, context) {
+    const cache = getDefaultCache();
+    const cacheKey = createCacheKey(schema, context);
+    const cached = cache.get(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) {
+    await Promise.all(requests.map(generateProps));
+}
+/**
+ * Generate multiple prop sets in parallel
+ */
+export async function generatePropsMany(requests) {
+    return Promise.all(requests.map(req => generateProps(req)));
+}
+/**
+ * Merge partial props with generated props
+ *
+ * Generates only the missing props, keeping provided ones.
+ */
+export async function mergeWithGenerated(schema, partialProps, options) {
+    // Get list of missing keys
+    const schemaObj = typeof schema === 'string' ? { value: schema } : schema;
+    const schemaKeys = Object.keys(schemaObj);
+    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;
+    }
+    // Build partial schema for missing props only
+    const partialSchema = {};
+    for (const key of missingKeys) {
+        partialSchema[key] = schemaObj[key];
+    }
+    // Generate missing props
+    const result = await generateProps({
+        schema: partialSchema,
+        context: partialProps,
+        ...options,
+    });
+    // Merge
+    return {
+        ...result.props,
+        ...partialProps,
+    };
+}