@stacksjs/dtsx 0.9.9 → 0.9.11

package/dist/plugins/vite.d.ts

@@ -0,0 +1,49 @@
+import type { DtsGenerationConfig, GenerationStats } from '../types';
+/**
+ * Create a Vite plugin for dtsx
+ *
+ * @example
+ * ```ts
+ * // vite.config.ts
+ * import { dts } from '@stacksjs/dtsx/plugins/vite'
+ *
+ * export default {
+ *   plugins: [
+ *     dts({
+ *       root: './src',
+ *       outdir: './dist',
+ *     }),
+ *   ],
+ * }
+ * ```
+ */
+export declare function dts(options?: VitePluginOptions): VitePlugin;
+/**
+ * Alias for dts
+ */
+export declare const viteDts: typeof dts;
+/**
+ * Vite plugin options
+ */
+export declare interface VitePluginOptions extends Partial<DtsGenerationConfig> {
+  buildStart?: boolean
+  buildEnd?: boolean
+  writeBundle?: boolean
+  modes?: string[]
+  onGenerated?: (stats: GenerationStats) => void
+  onError?: (error: Error) => void
+}
+/**
+ * Vite plugin interface (minimal type for compatibility)
+ */
+declare interface VitePlugin {
+  name: string
+  apply?: 'build' | 'serve' | ((_config: { mode: string }) => boolean)
+  buildStart?: () => Promise<void> | void
+  buildEnd?: () => Promise<void> | void
+  writeBundle?: () => Promise<void> | void
+}
+/**
+ * Default export
+ */
+export default dts;

package/dist/plugins/webpack.d.ts

@@ -0,0 +1,66 @@
+import type { DtsGenerationConfig, GenerationStats } from '../types';
+/**
+ * Factory function for creating webpack plugin
+ */
+export declare function dtsxWebpack(options?: WebpackPluginOptions): DtsxWebpackPlugin;
+/**
+ * Alias matching common naming convention
+ */
+export declare const dts: typeof dtsxWebpack;
+/**
+ * webpack plugin options
+ */
+export declare interface WebpackPluginOptions extends Partial<DtsGenerationConfig> {
+  onCompile?: boolean
+  afterEmit?: boolean
+  onWatchRun?: boolean
+  onGenerated?: (stats: GenerationStats) => void
+  onError?: (error: Error) => void
+}
+/**
+ * webpack compiler interface (minimal type)
+ */
+declare interface WebpackCompiler {
+  hooks: {
+    compile: { tap: (name: string, callback: () => void) => void }
+    afterEmit: { tapAsync: (name: string, callback: (compilation: unknown, done: () => void) => void) => void }
+    watchRun: { tapAsync: (name: string, callback: (compiler: unknown, done: () => void) => void) => void }
+  }
+  options: {
+    entry?: unknown
+    output?: {
+      path?: string
+    }
+    context?: string
+  }
+}
+/**
+ * webpack plugin for dtsx
+ *
+ * @example
+ * ```ts
+ * // webpack.config.js
+ * const { DtsxWebpackPlugin } = require('@stacksjs/dtsx/plugins/webpack')
+ *
+ * module.exports = {
+ *   entry: './src/index.ts',
+ *   output: {
+ *     path: path.resolve(__dirname, 'dist'),
+ *   },
+ *   plugins: [
+ *     new DtsxWebpackPlugin({
+ *       root: './src',
+ *       outdir: './dist',
+ *     }),
+ *   ],
+ * }
+ * ```
+ */
+export declare class DtsxWebpackPlugin {
+  constructor(options?: WebpackPluginOptions);
+  apply(compiler: WebpackCompiler): void;
+}
+/**
+ * Default export
+ */
+export default DtsxWebpackPlugin;

package/dist/plugins.d.ts

@@ -0,0 +1,83 @@
+import type { Declaration, DtsGenerationConfig, GenerationStats } from './types';
+/**
+ * Helper to create a plugin
+ */
+export declare function definePlugin(plugin: Plugin): Plugin;
+/**
+ * Built-in plugin: Add banner comment
+ * Adds a banner comment to the top of generated files
+ */
+export declare function createBannerPlugin(banner: string): Plugin;
+/**
+ * Built-in plugin: Filter exports
+ * Only include declarations matching the filter
+ */
+export declare function createFilterPlugin(filter: (name: string) => boolean): Plugin;
+/**
+ * Global plugin manager instance
+ */
+export declare const pluginManager: PluginManager;
+/**
+ * Built-in plugin: Strip internal declarations
+ * Removes declarations marked with @internal in JSDoc
+ */
+export declare const stripInternalPlugin: Plugin;
+/**
+ * Context passed to plugin hooks
+ */
+export declare interface PluginContext {
+  filePath: string
+  sourceCode: string
+  config: DtsGenerationConfig
+  log: {
+    debug: (message: string) => void
+    info: (message: string) => void
+    warn: (message: string) => void
+    error: (message: string) => void
+  }
+}
+/**
+ * Transform context with mutable content
+ */
+export declare interface TransformContext extends PluginContext {
+  content: string
+}
+/**
+ * Declaration context for declaration hooks
+ */
+export declare interface DeclarationContext extends PluginContext {
+  declarations: Declaration[]
+}
+/**
+ * Plugin hook definitions
+ */
+export declare interface PluginHooks {
+  onStart?: (config: DtsGenerationConfig) => DtsGenerationConfig | void | Promise<DtsGenerationConfig | void>
+  onBeforeFile?: (ctx: TransformContext) => string | void | Promise<string | void>
+  onDeclarations?: (ctx: DeclarationContext) => Declaration[] | void | Promise<Declaration[] | void>
+  onAfterFile?: (ctx: TransformContext) => string | void | Promise<string | void>
+  onEnd?: (stats: GenerationStats) => void | Promise<void>
+  onError?: (error: Error, ctx: PluginContext) => void | Promise<void>
+}
+/**
+ * Plugin definition
+ */
+export declare interface Plugin extends PluginHooks {
+  name: string
+  version?: string
+  description?: string
+}
+/**
+ * Plugin manager for handling multiple plugins
+ */
+export declare class PluginManager {
+  register(plugin: Plugin): void;
+  unregister(name: string): boolean;
+  getPlugins(): readonly Plugin[];
+  runOnStart(config: DtsGenerationConfig): Promise<DtsGenerationConfig>;
+  runOnBeforeFile(filePath: string, sourceCode: string): Promise<string>;
+  runOnDeclarations(filePath: string, sourceCode: string, declarations: Declaration[]): Promise<Declaration[]>;
+  runOnAfterFile(filePath: string, sourceCode: string, dtsContent: string): Promise<string>;
+  runOnEnd(stats: GenerationStats): Promise<void>;
+  runOnError(error: Error, filePath: string, sourceCode: string): Promise<void>;
+}

package/dist/process-source.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Process TypeScript source code from a string (for stdin support)
+ * This is a lightweight module that avoids pulling in heavy dependencies
+ * like bun Glob, fs/promises, bundler, cache, config, etc.
+ */
+export declare function processSource(sourceCode: string, filename?: string, keepComments?: boolean, importOrder?: string[], isolatedDeclarations?: boolean): string;
+/**
+ * Fast path for project mode — skips cache lookup/store.
+ * Use when processing many files once (no cache benefit).
+ */
+export declare function processSourceDirect(sourceCode: string, filename?: string, keepComments?: boolean, importOrder?: string[], isolatedDeclarations?: boolean): string;

package/dist/processor/cache.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Get or create a cached RegExp for word boundary matching
+ */
+export declare function getCachedRegex(pattern: string): RegExp;
+/**
+ * Get cached import items or null if not cached
+ */
+export declare function getImportItemsFromCache(importText: string): string[] | null;
+/**
+ * Store import items in cache with eviction
+ */
+export declare function setImportItemsCache(importText: string, items: string[]): void;
+/**
+ * Clear processor caches (useful for testing or memory management)
+ */
+export declare function clearProcessorCaches(): void;

package/dist/processor/comments.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Comment formatting utilities for DTS output
+ */
+/**
+ * Format comments for DTS output
+ */
+export declare function formatComments(comments: string[] | undefined, keepComments?: boolean): string;

package/dist/processor/declarations.d.ts

@@ -0,0 +1,37 @@
+import type { Declaration } from '../types';
+/**
+ * Process function declaration to DTS format
+ */
+export declare function processFunctionDeclaration(decl: Declaration, keepComments?: boolean): string;
+/**
+ * Process variable declaration to DTS format
+ */
+export declare function processVariableDeclaration(decl: Declaration, keepComments?: boolean): string;
+/**
+ * Process interface declaration to DTS format
+ */
+export declare function processInterfaceDeclaration(decl: Declaration, keepComments?: boolean): string;
+/**
+ * Process type alias declaration to DTS format
+ */
+export declare function processTypeDeclaration(decl: Declaration, keepComments?: boolean): string;
+/**
+ * Process class declaration to DTS format
+ */
+export declare function processClassDeclaration(decl: Declaration, keepComments?: boolean): string;
+/**
+ * Process enum declaration to DTS format
+ */
+export declare function processEnumDeclaration(decl: Declaration, keepComments?: boolean): string;
+/**
+ * Process import statement
+ */
+export declare function processImportDeclaration(decl: Declaration): string;
+/**
+ * Process export statement
+ */
+export declare function processExportDeclaration(decl: Declaration, keepComments?: boolean): string;
+/**
+ * Process module/namespace declaration to DTS format
+ */
+export declare function processModuleDeclaration(decl: Declaration, keepComments?: boolean): string;

package/dist/processor/imports.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Parse an import statement into its components using string operations
+ * Avoids regex backtracking issues
+ */
+export declare function parseImportStatement(importText: string): {
+  defaultName: string | null
+  namedItems: string[]
+  source: string
+  isTypeOnly: boolean
+} | null;
+/**
+ * Extract all imported items from an import statement (with caching)
+ * Uses simple string operations to avoid regex backtracking
+ */
+export declare function extractAllImportedItems(importText: string): string[];
+/**
+ * Parse an import statement with detailed type-only information for each item
+ * Handles: import type { X }, import { type X, Y }, import * as X, etc.
+ */
+export declare function parseImportDetailed(importText: string): ParsedImport | null;
+/**
+ * Parse an export statement with detailed type-only information
+ * Handles: export type { X }, export { type X, Y }, export * from, etc.
+ */
+export declare function parseExportDetailed(exportText: string): {
+  namedItems: ImportItem[]
+  source: string | null
+  isTypeOnly: boolean
+  isNamespace: boolean
+  isDefault: boolean
+} | null;
+/**
+ * Check if an import item is type-only
+ */
+export declare function isTypeOnlyImportItem(itemText: string): boolean;
+/**
+ * Convert import items to type-only format
+ * E.g., "{ X, Y }" becomes "{ type X, type Y }"
+ */
+export declare function convertToTypeOnlyImport(importText: string): string;
+/**
+ * Merge value and type imports from the same module
+ * Combines separate import statements into one where possible
+ */
+export declare function mergeImports(imports: string[]): string[];
+/**
+ * Represents a single imported item with its type-only status
+ */
+export declare interface ImportItem {
+  name: string
+  originalName: string
+  isTypeOnly: boolean
+  isDefault: boolean
+}
+/**
+ * Detailed import statement parse result
+ */
+export declare interface ParsedImport {
+  defaultName: string | null
+  namedItems: ImportItem[]
+  source: string
+  isTypeOnly: boolean
+  isNamespace: boolean
+  namespaceName: string | null
+}

package/dist/processor/index.d.ts

@@ -0,0 +1,34 @@
+import { extractAllImportedItems, parseImportStatement } from './imports';
+import { formatComments } from './comments';
+import { processClassDeclaration, processEnumDeclaration, processFunctionDeclaration, processInterfaceDeclaration, processModuleDeclaration, processTypeDeclaration, processVariableDeclaration } from './declarations';
+import type { Declaration, ProcessingContext } from '../types';
+/**
+ * Process declarations and convert them to narrow DTS format
+ */
+export declare function processDeclarations(declarations: Declaration[], context: ProcessingContext, keepComments?: boolean, importOrder?: string[]): string;
+// Re-export all public APIs
+export { clearProcessorCaches } from './cache';
+export { formatComments } from './comments';
+export {
+  processClassDeclaration,
+  processEnumDeclaration,
+  processExportDeclaration,
+  processFunctionDeclaration,
+  processImportDeclaration,
+  processInterfaceDeclaration,
+  processModuleDeclaration,
+  processTypeDeclaration,
+  processVariableDeclaration,
+} from './declarations';
+export { extractAllImportedItems, parseImportStatement } from './imports';
+export {
+  extractSatisfiesType,
+  findMatchingBracket,
+  inferArrayType,
+  inferFunctionType,
+  inferNarrowType,
+  inferNarrowTypeInUnion,
+  inferObjectType,
+  isGenericType,
+  parseArrayElements,
+} from './type-inference';

package/dist/processor/type-inference.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Enable clean default collection for the next type inference pass.
+ * Must be called before inferNarrowType when you need a @defaultValue.
+ */
+export declare function enableCleanDefaultCollection(): void;
+/**
+ * Consume the computed clean default (also disables collection).
+ * Returns null if no clean default was computed.
+ */
+export declare function consumeCleanDefault(): string | null;
+/**
+ * Infer and narrow types from values
+ * @param inUnion - When true, widens number/boolean literals to their base types (used in array union contexts)
+ * @param _depth - Internal recursion depth counter (do not set manually)
+ */
+export declare function inferNarrowType(value: unknown, isConst?: boolean, inUnion?: boolean, _depth?: number): string;
+/**
+ * Infer and narrow types from values in union context (for arrays)
+ * Widens number/boolean literals to base types unless const
+ */
+export declare function inferNarrowTypeInUnion(value: unknown, isConst?: boolean, _depth?: number): string;
+/**
+ * Infer array type from array literal
+ */
+export declare function inferArrayType(value: string, isConst: boolean, _depth?: number): string;
+/**
+ * Parse array elements handling nested structures
+ */
+export declare function parseArrayElements(content: string): string[];
+/**
+ * Infer object type from object literal
+ */
+export declare function inferObjectType(value: string, isConst: boolean, _depth?: number): string;
+/**
+ * Clean parameter defaults from function parameters
+ */
+export declare function cleanParameterDefaults(params: string): string;
+/**
+ * Find matching bracket for nested structures
+ */
+export declare function findMatchingBracket(str: string, start: number, openChar: string, closeChar: string): number;
+/**
+ * Infer function type from function expression
+ */
+export declare function inferFunctionType(value: string, inUnion?: boolean, _depth?: number, isConst?: boolean): string;
+/**
+ * Check if a type annotation is a generic/broad type that should be replaced with narrow inference
+ */
+export declare function isGenericType(typeAnnotation: string): boolean;
+/**
+ * Extract type from 'satisfies' operator
+ * e.g., "{ port: 3000 } satisfies { port: number }" returns "{ port: number }"
+ */
+export declare function extractSatisfiesType(value: string): string | null;
+/**
+ * Infer mapped type from type expression
+ * Handles patterns like { [K in keyof T]: V }
+ */
+export declare function inferMappedType(typeStr: string): string | null;
+/**
+ * Infer conditional type from type expression
+ * Handles patterns like T extends U ? X : Y
+ */
+export declare function inferConditionalType(typeStr: string): string | null;
+/**
+ * Infer template literal type from type expression
+ * Handles patterns like `${string}-${number}`
+ */
+export declare function inferTemplateLiteralTypeAdvanced(typeStr: string): string | null;
+/**
+ * Infer infer keyword usage in conditional types
+ * Handles patterns like T extends (infer U)[] ? U : never
+ */
+export declare function extractInferTypes(typeStr: string): string[];
+/**
+ * Check if a type uses advanced TypeScript features
+ */
+export declare function isComplexType(_typeStr: string): boolean;
+/**
+ * Simplify complex type for declaration output
+ * Returns simplified version if too complex
+ */
+export declare function simplifyComplexType(typeStr: string, maxDepth?: number): string;
+/**
+ * Parse utility type and extract its parameters
+ * Handles Partial<T>, Required<T>, Pick<T, K>, Omit<T, K>, etc.
+ */
+export declare function parseUtilityType(typeStr: string): { name: string, params: string[] } | null;
+/**
+ * Parse type parameters from a comma-separated string
+ * Handles nested types properly
+ */
+export declare function parseTypeParameters(paramsStr: string): string[];
+/**
+ * Infer keyof type
+ */
+export declare function inferKeyofType(typeStr: string): string | null;
+/**
+ * Infer typeof type
+ */
+export declare function inferTypeofType(typeStr: string): string | null;
+/**
+ * Check if type is an indexed access type
+ * e.g., T[K], Person['name']
+ */
+export declare function isIndexedAccessType(typeStr: string): boolean;

package/dist/processor.d.ts

@@ -1,45 +1,5 @@
-import type { Declaration, ProcessingContext } from './types';
 /**
- * Process declarations and convert them to narrow DTS format
+ * Processor module - re-exports from modular structure
+ * @deprecated Import from './processor/index' directly for better tree-shaking
  */
-export declare function processDeclarations(declarations: Declaration[], context: ProcessingContext, keepComments?: boolean): string;
-/**
- * Process function declaration to DTS format
- */
-export declare function processFunctionDeclaration(decl: Declaration, keepComments?: boolean): string;
-/**
- * Process variable declaration to DTS format
- */
-export declare function processVariableDeclaration(decl: Declaration, keepComments?: boolean): string;
-/**
- * Process interface declaration to DTS format
- */
-export declare function processInterfaceDeclaration(decl: Declaration, keepComments?: boolean): string;
-/**
- * Process type alias declaration to DTS format
- */
-export declare function processTypeDeclaration(decl: Declaration, keepComments?: boolean): string;
-/**
- * Process class declaration to DTS format
- */
-export declare function processClassDeclaration(decl: Declaration, keepComments?: boolean): string;
-/**
- * Process enum declaration to DTS format
- */
-export declare function processEnumDeclaration(decl: Declaration, keepComments?: boolean): string;
-/**
- * Process import statement
- */
-export declare function processImportDeclaration(decl: Declaration): string;
-/**
- * Process export statement
- */
-export declare function processExportDeclaration(decl: Declaration): string;
-/**
- * Process module/namespace declaration to DTS format
- */
-export declare function processModuleDeclaration(decl: Declaration, keepComments?: boolean): string;
-/**
- * Infer and narrow types from values
- */
-export declare function inferNarrowType(value: any, isConst?: boolean): string;
+export * from './processor/index';

package/dist/profiling.d.ts

@@ -0,0 +1,101 @@
+import type { ProfilingConfig } from './types';
+/**
+ * Create a new profiler instance
+ */
+export declare function createProfiler(config?: ProfilingConfig): Profiler;
+/**
+ * Profile a function execution
+ */
+export declare function profileExecution<T>(fn: () => T | Promise<T>, config?: ProfilingConfig): Promise<{ result: T, profile: ProfilingResults }>;
+/**
+ * Create a profiled I/O wrapper
+ */
+export declare function createProfiledIo(profiler: Profiler): {
+  read: <T>(path: string, fn: () => Promise<T>) => Promise<T>
+  write: (path: string, fn: () => Promise<void>, size: number) => Promise<void>
+};
+/**
+ * Create a simple timer
+ */
+export declare function createTimer(): Timer;
+/**
+ * Memory profiling data snapshot
+ */
+export declare interface MemoryProfileSnapshot {
+  timestamp: number
+  heapUsed: number
+  heapTotal: number
+  external: number
+  arrayBuffers: number
+  rss: number
+}
+/**
+ * CPU profiling data
+ */
+export declare interface CpuProfile {
+  timestamp: number
+  user: number
+  system: number
+  total: number
+}
+/**
+ * I/O operation record
+ */
+export declare interface IoOperation {
+  timestamp: number
+  operation: 'read' | 'write'
+  path: string
+  size: number
+  durationMs: number
+}
+/**
+ * Profiling results
+ */
+export declare interface ProfilingResults {
+  startTime: number
+  endTime: number
+  durationMs: number
+  memory: {
+    samples: MemoryProfileSnapshot[]
+    peak: MemoryProfileSnapshot
+    average: MemoryProfileSnapshot
+    warnings: string[]
+  }
+  cpu: {
+    samples: CpuProfile[]
+    totalUser: number
+    totalSystem: number
+  }
+  io: {
+    operations: IoOperation[]
+    totalReads: number
+    totalWrites: number
+    totalReadBytes: number
+    totalWriteBytes: number
+    totalReadMs: number
+    totalWriteMs: number
+  }
+}
+/**
+ * Profiler class for collecting performance data
+ */
+export declare class Profiler {
+  constructor(config?: ProfilingConfig);
+  start(): void;
+  stop(): void;
+  recordIo(operation: 'read' | 'write', path: string, size: number, durationMs: number): void;
+  getResults(): ProfilingResults;
+  formatResults(): string;
+  writeResults(): Promise<void>;
+}
+/**
+ * Simple timer for manual profiling
+ */
+export declare class Timer {
+  mark(name: string): void;
+  measure(name: string, fromMark: string): number;
+  getDurations(name: string): number[];
+  getAverage(name: string): number;
+  getSummary(): Map<string, { count: number, total: number, average: number, min: number, max: number }>;
+  clear(): void;
+}