ai-props 2.1.3 → 2.4.0

package/dist/mdx.d.ts

@@ -0,0 +1,230 @@
+/**
+ * MDX parsing and rendering with AI-generated props
+ *
+ * Provides utilities for parsing MDX content, extracting component schemas,
+ * and rendering with AI-generated props.
+ *
+ * Key features:
+ * - Content-hash based caching for parsed MDX
+ * - Parallel prop generation for multiple components
+ * - Streaming-ready architecture
+ * - Graceful error handling with detailed messages
+ *
+ * @packageDocumentation
+ */
+export type { ParsedMDX, ComponentSchemas, MDXPropsGeneratorOptions, MDXPropsGenerator, RenderMDXOptions, CompileMDXOptions, CompiledMDXFunction, StreamMDXOptions, MDXCacheEntry, MDXParseError, CacheInvalidationStrategy, MDXCacheOptions, MDXCacheStats, } from './mdx-types.js';
+import type { ParsedMDX, ComponentSchemas, MDXPropsGeneratorOptions, MDXPropsGenerator, RenderMDXOptions, CompileMDXOptions, CompiledMDXFunction, StreamMDXOptions, MDXCacheOptions, MDXCacheStats } from './mdx-types.js';
+/**
+ * Configure the global MDX parse cache
+ *
+ * @param options - Cache configuration options
+ *
+ * @example
+ * ```ts
+ * // Configure with larger cache and longer TTL
+ * configureMDXCache({
+ *   maxSize: 500,
+ *   ttl: 30 * 60 * 1000, // 30 minutes
+ *   autoCleanup: true,
+ * })
+ * ```
+ */
+export declare function configureMDXCache(options: MDXCacheOptions): void;
+/**
+ * Get MDX cache statistics
+ *
+ * Useful for monitoring cache performance and tuning configuration.
+ *
+ * @returns Cache statistics
+ *
+ * @example
+ * ```ts
+ * const stats = getMDXCacheStats()
+ * console.log(`Cache hit ratio: ${(stats.hitRatio * 100).toFixed(1)}%`)
+ * console.log(`Cache size: ${stats.size}/${stats.maxSize}`)
+ * ```
+ */
+export declare function getMDXCacheStats(): MDXCacheStats;
+/**
+ * Invalidate MDX cache entries by tag
+ *
+ * @param tag - Tag to invalidate
+ * @returns Number of entries invalidated
+ */
+export declare function invalidateMDXCacheByTag(tag: string): number;
+/**
+ * Cleanup expired MDX cache entries
+ *
+ * @returns Number of entries removed
+ */
+export declare function cleanupMDXCache(): number;
+/**
+ * Options for parsing MDX
+ */
+export interface ParseMDXOptions {
+    /**
+     * Tags to associate with the cached result for group invalidation
+     *
+     * @example
+     * ```ts
+     * parseMDX(content, { tags: ['page:/products', 'component:Hero'] })
+     * ```
+     */
+    tags?: string[];
+    /**
+     * Skip caching for this parse operation
+     */
+    skipCache?: boolean;
+}
+/**
+ * Parse MDX content string
+ *
+ * Extracts frontmatter, identifies components, and parses component props.
+ * Results are cached based on content hash for performance.
+ *
+ * @param mdx - MDX content string
+ * @param options - Parse options (optional)
+ * @returns Parsed MDX structure
+ *
+ * @example
+ * ```ts
+ * const result = parseMDX(`---
+ * title: Hello
+ * ---
+ *
+ * # {title}
+ *
+ * <Hero />
+ * `)
+ *
+ * console.log(result.frontmatter.title) // 'Hello'
+ * console.log(result.components) // ['Hero']
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Parse with cache tags for group invalidation
+ * const result = parseMDX(content, {
+ *   tags: ['page:/home', 'component:Hero']
+ * })
+ *
+ * // Later, invalidate all home page entries
+ * invalidateMDXCacheByTag('page:/home')
+ * ```
+ */
+export declare function parseMDX(mdx: string, options?: ParseMDXOptions): ParsedMDX;
+/**
+ * Extract prop schemas from MDX component usage
+ *
+ * Analyzes component tags in MDX to infer prop schemas.
+ *
+ * @param mdx - MDX content string
+ * @returns Schemas for each component
+ *
+ * @example
+ * ```ts
+ * const schemas = extractComponentSchemas(`
+ *   <Card title="Hello" count={5} />
+ * `)
+ *
+ * // schemas.Card = { title: 'title (string)', count: 'count (number)' }
+ * ```
+ */
+export declare function extractComponentSchemas(mdx: string): ComponentSchemas;
+/**
+ * Create an MDX props generator
+ *
+ * The generator uses content-hash based caching and supports parallel
+ * generation for multiple components.
+ *
+ * @param options - Generator options
+ * @returns MDX props generator instance
+ *
+ * @example
+ * ```ts
+ * const generator = createMDXPropsGenerator({
+ *   schemas: {
+ *     Hero: { title: 'Hero title', subtitle: 'Hero subtitle' },
+ *   },
+ *   cache: true,
+ *   maxParallel: 3,
+ * })
+ *
+ * const props = await generator.generate(`<Hero />`)
+ * // props.Hero = { title: '...', subtitle: '...' }
+ * ```
+ */
+export declare function createMDXPropsGenerator(options: MDXPropsGeneratorOptions): MDXPropsGenerator;
+/**
+ * Render MDX with injected props
+ *
+ * @param mdx - MDX content string
+ * @param props - Props for each component
+ * @param options - Render options
+ * @returns Rendered content (string or stream)
+ *
+ * @example
+ * ```ts
+ * const html = await renderMDXWithProps(
+ *   `<Hero title="Welcome" />`,
+ *   { Hero: { title: 'Welcome', subtitle: 'To the site' } }
+ * )
+ * ```
+ */
+export declare function renderMDXWithProps(mdx: string, props: Record<string, Record<string, unknown> | null>, options?: RenderMDXOptions): Promise<string | ReadableStream<string>>;
+/**
+ * Stream MDX content with injected props
+ *
+ * Returns a ReadableStream for progressive rendering of MDX content.
+ *
+ * @param mdx - MDX content string
+ * @param props - Props for each component
+ * @param options - Stream options
+ * @returns ReadableStream of rendered content
+ *
+ * @example
+ * ```ts
+ * const stream = await streamMDXWithProps(
+ *   `<Hero title="Welcome" />`,
+ *   { Hero: { title: 'Welcome', subtitle: 'To the site' } }
+ * )
+ *
+ * const reader = stream.getReader()
+ * while (true) {
+ *   const { done, value } = await reader.read()
+ *   if (done) break
+ *   console.log(new TextDecoder().decode(value))
+ * }
+ * ```
+ */
+export declare function streamMDXWithProps(mdx: string, props: Record<string, Record<string, unknown>>, options?: StreamMDXOptions): Promise<ReadableStream<Uint8Array>>;
+/**
+ * Compile MDX to an executable function
+ *
+ * Compilation is lazy - the MDX is parsed once, and the returned function
+ * can be called multiple times with different props.
+ *
+ * @param mdx - MDX content string
+ * @param options - Compile options
+ * @returns Compiled function that accepts props
+ *
+ * @example
+ * ```ts
+ * const compiled = await compileMDX(`<Greeting name="World" />`)
+ * const result = compiled({ Greeting: { name: 'World' } })
+ * ```
+ */
+export declare function compileMDX(mdx: string, options?: CompileMDXOptions): Promise<CompiledMDXFunction>;
+/**
+ * Clear the MDX parse cache
+ *
+ * Use this when you need to force re-parsing of all MDX content.
+ */
+export declare function clearMDXCache(): void;
+/**
+ * Get the current MDX parse cache size
+ *
+ * @returns Number of cached parse results
+ */
+export declare function getMDXCacheSize(): number;
+//# sourceMappingURL=mdx.d.ts.map

package/dist/mdx.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mdx.d.ts","sourceRoot":"","sources":["../src/mdx.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAkBH,YAAY,EACV,SAAS,EACT,gBAAgB,EAChB,wBAAwB,EACxB,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,EACjB,mBAAmB,EACnB,gBAAgB,EAChB,aAAa,EACb,aAAa,EACb,yBAAyB,EACzB,eAAe,EACf,aAAa,GACd,MAAM,gBAAgB,CAAA;AAEvB,OAAO,KAAK,EACV,SAAS,EACT,gBAAgB,EAChB,wBAAwB,EACxB,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,EACjB,mBAAmB,EACnB,gBAAgB,EAEhB,eAAe,EACf,aAAa,EACd,MAAM,gBAAgB,CAAA;AAmRvB;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI,CAIhE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,IAAI,aAAa,CAEhD;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED;;;;GAIG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAMD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;IAEf;;OAEG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,SAAS,CAuD1E;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,gBAAgB,CAgDrE;AAMD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,wBAAwB,GAAG,iBAAiB,CA8G5F;AAMD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,EACrD,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,MAAM,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC,CAgF1C;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAC9C,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC,CA6BrC;AAMD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,UAAU,CAC9B,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,mBAAmB,CAAC,CAiF9B;AAMD;;;;GAIG;AACH,wBAAgB,aAAa,IAAI,IAAI,CAEpC;AAED;;;;GAIG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAExC"}