@stacksjs/dtsx 0.9.8 → 0.9.10

package/dist/type-mappings.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Get preset mappings
+ */
+export declare function getPresetMappings(preset: TypeMappingPreset): TypeMappingRule[];
+/**
+ * Create a type mapper with configuration
+ */
+export declare function createTypeMapper(config?: TypeMappingConfig): TypeMapper;
+/**
+ * Apply type mappings to declaration text
+ */
+export declare function applyTypeMappings(declarationText: string, mapper: TypeMapper, context?: Partial<TypeMappingContext>): string;
+/**
+ * Default type mapper instance
+ */
+export declare const defaultTypeMapper: TypeMapper;
+/**
+ * Strict type mapper instance
+ */
+export declare const strictTypeMapper: TypeMapper;
+/**
+ * Built-in type transformers
+ * @defaultValue
+ * ```ts
+ * {
+ *   /**
+ *    * Make all types readonly
+ *    */
+ *   makeReadonly: (type: string) => any,
+ *   /**
+ *    * Make type nullable
+ *    */
+ *   makeNullable: (type: string) => any,
+ *   /**
+ *    * Make type optional (add undefined)
+ *    */
+ *   makeOptional: (type: string) => any,
+ *   /**
+ *    * Remove null/undefined from type
+ *    */
+ *   makeRequired: (type: string) => any,
+ *   /**
+ *    * Wrap in Promise
+ *    */
+ *   promisify: (type: string) => any,
+ *   /**
+ *    * Unwrap Promise
+ *    */
+ *   unpromisify: (type: string) => any,
+ *   /**
+ *    * Convert to array type
+ *    */
+ *   arrayify: (type: string) => any,
+ *   /**
+ *    * Unwrap array type
+ *    */
+ *   unarrayify: (type: string) => any
+ * }
+ * ```
+ */
+export declare const TypeTransformers: {
+  /**
+   * Make all types readonly
+   */
+  makeReadonly: (type: string) => any;
+  /**
+   * Make type nullable
+   */
+  makeNullable: (type: string) => any;
+  /**
+   * Make type optional (add undefined)
+   */
+  makeOptional: (type: string) => any;
+  /**
+   * Remove null/undefined from type
+   */
+  makeRequired: (type: string) => any;
+  /**
+   * Wrap in Promise
+   */
+  promisify: (type: string) => any;
+  /**
+   * Unwrap Promise
+   */
+  unpromisify: (type: string) => any;
+  /**
+   * Convert to array type
+   */
+  arrayify: (type: string) => any;
+  /**
+   * Unwrap array type
+   */
+  unarrayify: (type: string) => any
+};
+/**
+ * Custom type mappings for DTS generation
+ * Allows users to specify type replacements and transformations
+ */
+/**
+ * Type mapping rule
+ */
+export declare interface TypeMappingRule {
+  pattern: string | RegExp
+  replacement: string
+  condition?: (context: TypeMappingContext) => boolean
+  global?: boolean
+  priority?: number
+}
+/**
+ * Context passed to type mapping functions
+ */
+export declare interface TypeMappingContext {
+  type: string
+  declarationName?: string
+  declarationKind?: string
+  filePath?: string
+  isReturnType?: boolean
+  isParameterType?: boolean
+  isPropertyType?: boolean
+}
+/**
+ * Type mapping configuration
+ */
+export declare interface TypeMappingConfig {
+  rules: TypeMappingRule[]
+  presets?: TypeMappingPreset[]
+  includeDefaults?: boolean
+}
+/**
+ * Available type mapping presets
+ */
+export type TypeMappingPreset = | 'strict' // Convert 'any' to 'unknown'
+  | 'readonly' // Add readonly to array types
+  | 'nullable' // Convert undefined unions to optional
+  | 'branded' // Use branded types for primitives
+  | 'simplified' // Simplify complex utility types;
+/**
+ * Type mapper class for applying transformations
+ */
+export declare class TypeMapper {
+  constructor(config?: TypeMappingConfig);
+  map(type: string, context?: Partial<TypeMappingContext>): string;
+  mapAll(types: string[], context?: Partial<TypeMappingContext>): string[];
+  addRule(rule: TypeMappingRule): void;
+  removeRules(pattern: string | RegExp): number;
+  clearCache(): void;
+  getRules(): readonly TypeMappingRule[];
+}

package/dist/types.d.ts

@@ -13,6 +13,131 @@ export declare interface DtsGenerationConfig {
   tsconfigPath: string
   verbose: boolean | string[]
   outputStructure?: 'mirror' | 'flat'
+  importOrder?: string[]
+  dryRun?: boolean
+  stats?: boolean
+  continueOnError?: boolean
+  logLevel?: 'debug' | 'info' | 'warn' | 'error' | 'silent'
+  exclude?: string[]
+  outputFormat?: 'text' | 'json'
+  progress?: boolean
+  diff?: boolean
+  validate?: boolean
+  watch?: boolean
+  parallel?: boolean
+  concurrency?: number
+  declarationMap?: boolean
+  plugins?: import('./plugins').Plugin[]
+  bundle?: boolean
+  bundleOutput?: string
+  incremental?: boolean
+  clearCache?: boolean
+  indentStyle?: 'spaces' | 'tabs'
+  indentSize?: number
+  prettier?: boolean
+  include?: string[]
+  isolatedDeclarations?: boolean
+  typeMappings?: import('./type-mappings').TypeMappingConfig
+  lineEnding?: 'lf' | 'crlf' | 'auto'
+  normalizeOutput?: boolean
+  declarationOrder?: {
+    kinds?: import('./types').DeclarationKind[]
+    alphabetize?: boolean
+    groupExports?: boolean
+  }
+  tracking?: TrackingConfig
+  profiling?: ProfilingConfig
+  typeInference?: TypeInferenceConfig
+  typeChecking?: TypeCheckingConfig
+  typeValidation?: TypeValidationConfig
+}
+/**
+ * Tracking configuration for debugging type and import usage
+ */
+export declare interface TrackingConfig {
+  types?: boolean
+  relationships?: boolean
+  usage?: boolean
+  imports?: boolean
+  importUsage?: boolean
+  importRelationships?: boolean
+}
+/**
+ * Profiling configuration for performance analysis
+ */
+export declare interface ProfilingConfig {
+  memory?: boolean
+  memoryLimit?: number
+  cpu?: boolean
+  samplingInterval?: number
+  io?: boolean
+  trackOperations?: ('read' | 'write')[]
+  outputFile?: string
+}
+/**
+ * Type inference configuration
+ */
+export declare interface TypeInferenceConfig {
+  enabled?: boolean
+  strictness?: 'loose' | 'normal' | 'strict'
+  inferReturnTypes?: boolean
+  inferConstTypes?: boolean
+}
+/**
+ * Type checking configuration
+ */
+export declare interface TypeCheckingConfig {
+  enabled?: boolean
+  strictness?: 'loose' | 'normal' | 'strict'
+  warningsAsErrors?: boolean
+  maxErrors?: number
+}
+/**
+ * Type validation configuration
+ */
+export declare interface TypeValidationConfig {
+  enabled?: boolean
+  rules?: {
+    noAny?: boolean
+    noUnknown?: boolean
+    noImplicitAny?: boolean
+    explicitReturnTypes?: boolean
+    explicitParameterTypes?: boolean
+  }
+}
+/**
+ * Source location for error reporting
+ */
+export declare interface SourceLocation {
+  line: number
+  column: number
+  offset?: number
+}
+/**
+ * Detailed error information with source location
+ */
+export declare interface DtsError {
+  file: string
+  message: string
+  code?: string
+  location?: SourceLocation
+  stack?: string
+  suggestion?: string
+}
+/**
+ * Generation statistics
+ */
+export declare interface GenerationStats {
+  filesProcessed: number
+  filesGenerated: number
+  filesFailed: number
+  filesValidated: number
+  validationErrors: number
+  declarationsFound: number
+  importsProcessed: number
+  exportsProcessed: number
+  durationMs: number
+  errors: DtsError[]
 }
 /**
  * Declaration
@@ -20,7 +145,7 @@ export declare interface DtsGenerationConfig {
  * Represents a parsed declaration from TypeScript source
  */
 export declare interface Declaration {
-  kind: 'function' | 'variable' | 'interface' | 'type' | 'class' | 'enum' | 'import' | 'export' | 'module'
+  kind: DeclarationKind
   name: string
   text: string
   leadingComments?: string[]
@@ -34,10 +159,11 @@ export declare interface Declaration {
   members?: Declaration[]
   parameters?: ParameterDeclaration[]
   returnType?: string
-  value?: any
+  value?: unknown
   source?: string
   specifiers?: ImportSpecifier[]
   isTypeOnly?: boolean
+  isSideEffect?: boolean
   isAsync?: boolean
   isGenerator?: boolean
   overloads?: string[]
@@ -71,19 +197,23 @@ export declare interface ProcessingContext {
   filePath: string
   sourceCode: string
   declarations: Declaration[]
-  imports: Map<string, Set<string>>
-  exports: Set<string>
-  usedTypes: Set<string>
+  imports?: Map<string, Set<string>>
+  exports?: Set<string>
+  usedTypes?: Set<string>
 }
 /**
  * DtsGenerationOption
  *
  * This is the configuration object for the DTS generation process.
  */
-export type DtsGenerationOption = Partial<DtsGenerationConfig>
+export type DtsGenerationOption = Partial<DtsGenerationConfig>;
 /**
  * DtsGenerationOptions
  *
  * This is the configuration object for the DTS generation process.
  */
-export type DtsGenerationOptions = DtsGenerationOption | DtsGenerationOption[]
+export type DtsGenerationOptions = DtsGenerationOption | DtsGenerationOption[];
+/**
+ * Declaration kind - all possible declaration types
+ */
+export type DeclarationKind = 'function' | 'variable' | 'interface' | 'type' | 'class' | 'enum' | 'import' | 'export' | 'module' | 'namespace' | 'unknown';

package/dist/utils.d.ts

@@ -1,5 +1,57 @@
 import type { DtsGenerationConfig } from './types';
+/**
+ * Exhaustive check helper for switch statements
+ * This function should never be called if all cases are handled
+ * TypeScript will error if a case is missing
+ */
+export declare function assertNever(value: never, message?: string): never;
 export declare function writeToFile(filePath: string, content: string): Promise<void>;
 export declare function getAllTypeScriptFiles(directory?: string): Promise<string[]>;
 // only checks for 2 potentially nested levels
-export declare function checkIsolatedDeclarations(options?: DtsGenerationConfig): Promise<boolean>;
+export declare function checkIsolatedDeclarationsConfig(options?: DtsGenerationConfig): Promise<boolean>;
+/**
+ * Validate a .d.ts file content against TypeScript compiler
+ */
+export declare function validateDtsContent(content: string, filename: string): ValidationResult;
+/**
+ * Simple line-by-line diff between two strings
+ * Returns formatted diff output with +/- prefixes
+ */
+export declare function createDiff(oldContent: string, newContent: string, filename: string): string;
+/**
+ * Generate a simple source map for a declaration file
+ * This creates a basic 1:1 mapping since we're doing declaration extraction
+ */
+export declare function generateDeclarationMap(dtsContent: string, dtsFilename: string, sourceFilename: string, sourceContent: string): DeclarationSourceMap;
+/**
+ * Add source map URL comment to declaration content
+ */
+export declare function addSourceMapComment(dtsContent: string, mapFilename: string): string;
+/**
+ * Validation error details
+ */
+export declare interface ValidationError {
+  line: number
+  column: number
+  message: string
+  code?: string
+  suggestion?: string
+}
+/**
+ * Validation result for a .d.ts file
+ */
+export declare interface ValidationResult {
+  isValid: boolean
+  errors: ValidationError[]
+}
+/**
+ * Source map for declaration files
+ */
+export declare interface DeclarationSourceMap {
+  version: 3
+  file: string
+  sourceRoot: string
+  sources: string[]
+  sourcesContent: string[]
+  mappings: string
+}

package/dist/watcher.d.ts

@@ -0,0 +1,64 @@
+import type { DtsGenerationConfig } from './types';
+/**
+ * Create a file watcher for .d.ts generation
+ */
+export declare function createWatcher(config: WatchConfig, buildFn: (files?: string[]) => Promise<WatchBuildResult>): Watcher;
+/**
+ * Watch and generate .d.ts files
+ */
+export declare function watchAndGenerate(config: DtsGenerationConfig & WatchConfig, generator: (config: DtsGenerationConfig) => Promise<{ filesProcessed: number, errors: string[] }>): Promise<Watcher>;
+/**
+ * Format watch build result for display
+ */
+export declare function formatWatchResult(result: WatchBuildResult): string;
+/**
+ * Create a simple console logger for watch mode
+ */
+export declare function createWatchLogger(): {
+  onChange: (event: WatchEvent) => void
+  onBuildStart: () => void
+  onBuildComplete: (result: WatchBuildResult) => void
+  onError: (error: Error) => void
+};
+/**
+ * Watch configuration
+ */
+export declare interface WatchConfig {
+  root: string
+  include?: string[]
+  exclude?: string[]
+  debounce?: number
+  initialBuild?: boolean
+  clearScreen?: boolean
+  onChange?: (event: WatchEvent) => void | Promise<void>
+  onBuildStart?: () => void | Promise<void>
+  onBuildComplete?: (result: WatchBuildResult) => void | Promise<void>
+  onError?: (error: Error) => void | Promise<void>
+}
+/**
+ * Watch event
+ */
+export declare interface WatchEvent {
+  type: 'add' | 'change' | 'unlink'
+  path: string
+  relativePath: string
+}
+/**
+ * Build result from watch
+ */
+export declare interface WatchBuildResult {
+  success: boolean
+  duration: number
+  filesProcessed: number
+  errors: string[]
+}
+/**
+ * Watcher instance
+ */
+export declare interface Watcher {
+  start: () => Promise<void>
+  stop: () => void
+  rebuild: () => Promise<WatchBuildResult>
+  isWatching: () => boolean
+  getWatchedFiles: () => string[]
+}

package/dist/worker.d.ts

@@ -0,0 +1,84 @@
+import type { Declaration, DtsGenerationConfig } from './types';
+/**
+ * Create a worker pool with default configuration
+ */
+export declare function createWorkerPool(config?: WorkerPoolConfig): WorkerPool;
+/**
+ * Process files in parallel using a temporary worker pool
+ */
+export declare function parallelProcess(files: Array<{ path: string, content: string }>, config?: Partial<DtsGenerationConfig>, poolConfig?: WorkerPoolConfig): Promise<WorkerResult[]>;
+/**
+ * Batch files into chunks for processing
+ */
+export declare function batchFiles<T>(files: T[], batchSize: number): T[][];
+/**
+ * Calculate optimal batch size based on file count and CPU cores
+ */
+export declare function calculateOptimalBatchSize(fileCount: number, cpuCount?: number): number;
+/**
+ * Worker pool configuration
+ */
+export declare interface WorkerPoolConfig {
+  maxWorkers?: number
+  taskTimeout?: number
+  recycleAfter?: number
+  idleTimeout?: number
+  initialWorkers?: number
+}
+/**
+ * Task to be processed by a worker
+ */
+export declare interface WorkerTask {
+  id: string
+  type: 'process' | 'extract' | 'transform' | 'process-batch'
+  filePath: string
+  sourceCode?: string
+  files?: Array<{ filePath: string, sourceCode?: string, outPath?: string }>
+  filePaths?: string[]
+  sources?: string[]
+  outPaths?: string[]
+  config: Partial<DtsGenerationConfig>
+  writeOutput?: boolean
+}
+/**
+ * Result from a worker task
+ */
+export declare interface WorkerBatchResult {
+  filePath: string
+  success: boolean
+  content?: string
+  declarations?: Declaration[]
+  error?: string
+}
+export declare interface WorkerResult {
+  id: string
+  success: boolean
+  filePath: string
+  content?: string
+  declarations?: Declaration[]
+  batchResults?: WorkerBatchResult[]
+  error?: string
+  duration: number
+}
+/**
+ * Worker statistics
+ */
+export declare interface WorkerStats {
+  totalTasks: number
+  completedTasks: number
+  failedTasks: number
+  averageDuration: number
+  activeWorkers: number
+  idleWorkers: number
+}
+/**
+ * Worker pool for parallel processing
+ */
+export declare class WorkerPool {
+  constructor(config?: WorkerPoolConfig);
+  init(): Promise<void>;
+  submit(task: WorkerTask): Promise<WorkerResult>;
+  processFiles(files: Array<{ path: string, content: string }>, config?: Partial<DtsGenerationConfig>): Promise<WorkerResult[]>;
+  getStats(): WorkerStats;
+  shutdown(): Promise<void>;
+}

package/dist/workspace.d.ts

@@ -0,0 +1,62 @@
+import type { DtsGenerationConfig, GenerationStats } from './types';
+/**
+ * Discover workspace projects from TypeScript project references
+ */
+export declare function discoverWorkspaceProjects(rootTsConfig: string): Promise<WorkspaceProject[]>;
+/**
+ * Sort projects by their dependencies (topological sort)
+ * Projects with no dependencies come first
+ */
+export declare function sortProjectsByDependencies(projects: WorkspaceProject[]): WorkspaceProject[];
+/**
+ * Generate declarations for all projects in a workspace
+ */
+export declare function generateWorkspace(config: WorkspaceConfig): Promise<WorkspaceGenerationResult>;
+/**
+ * Discover and generate declarations for a monorepo
+ * Automatically discovers projects from TypeScript project references
+ */
+export declare function generateMonorepo(rootPath: string, options?: Partial<DtsGenerationConfig>): Promise<WorkspaceGenerationResult>;
+/**
+ * Parse workspace patterns from package.json workspaces field
+ */
+export declare function discoverWorkspaceFromPackageJson(rootPath: string): Promise<string[]>;
+/**
+ * Resolve workspace patterns to actual project paths
+ */
+export declare function resolveWorkspacePatterns(rootPath: string, patterns: string[]): Promise<string[]>;
+/**
+ * Generate declarations for a workspace defined in package.json
+ */
+export declare function generateFromPackageWorkspaces(rootPath: string, options?: Partial<DtsGenerationConfig>): Promise<WorkspaceGenerationResult>;
+/**
+ * Workspace project configuration
+ */
+export declare interface WorkspaceProject {
+  name: string
+  root: string
+  tsconfigPath: string
+  references: string[]
+  config?: Partial<DtsGenerationConfig>
+}
+/**
+ * Workspace configuration
+ */
+export declare interface WorkspaceConfig {
+  root: string
+  projects: WorkspaceProject[]
+  sharedConfig?: Partial<DtsGenerationConfig>
+}
+/**
+ * Result of workspace generation
+ */
+export declare interface WorkspaceGenerationResult {
+  success: boolean
+  projects: Array<{
+    name: string
+    stats: GenerationStats
+    success: boolean
+    error?: string
+  }>
+  durationMs: number
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stacksjs/dtsx",
   "type": "module",
-  "version": "0.9.8",
+  "version": "0.9.10",
   "description": "A modern, fast .d.ts generation tool, powered by Bun.",
   "author": "Chris Breuer <chris@stacksjs.org>",
   "license": "MIT",
@@ -25,9 +25,35 @@
   ],
   "exports": {
     ".": {
+      "types": "./dist/index.d.ts",
       "import": "./dist/src/index.js"
     },
+    "./vite": {
+      "types": "./dist/plugins/vite.d.ts",
+      "import": "./dist/src/plugins/vite.js"
+    },
+    "./bun": {
+      "types": "./dist/plugins/bun.d.ts",
+      "import": "./dist/src/plugins/bun.js"
+    },
+    "./esbuild": {
+      "types": "./dist/plugins/esbuild.d.ts",
+      "import": "./dist/src/plugins/esbuild.js"
+    },
+    "./tsup": {
+      "types": "./dist/plugins/tsup.d.ts",
+      "import": "./dist/src/plugins/tsup.js"
+    },
+    "./webpack": {
+      "types": "./dist/plugins/webpack.d.ts",
+      "import": "./dist/src/plugins/webpack.js"
+    },
+    "./plugins": {
+      "types": "./dist/plugins/index.d.ts",
+      "import": "./dist/src/plugins/index.js"
+    },
     "./*": {
+      "types": "./dist/*.d.ts",
       "import": "./dist/*"
     }
   },
@@ -40,16 +66,19 @@
     "dist"
   ],
   "scripts": {
+    "benchmark": "bun run benchmark.ts",
+    "benchmark:ci": "bun run benchmark.ts --ci --json",
+    "benchmark:quick": "bun run benchmark.ts --quick",
     "build": "bun build.ts && bun run compile",
-    "compile": "bun build ./bin/cli.ts --compile --minify --outfile bin/dtsx",
+    "compile": "bun build ./bin/cli.ts --compile --minify --format=esm --outfile bin/dtsx",
     "compile:all": "bun run compile:linux-x64 && bun run compile:linux-arm64 && bun run compile:windows-x64 && bun run compile:darwin-x64 && bun run compile:darwin-arm64",
-    "compile:linux-x64": "bun build ./bin/cli.ts --compile --minify --target=bun-linux-x64 --outfile bin/dtsx-linux-x64",
-    "compile:linux-arm64": "bun build ./bin/cli.ts --compile --minify --target=bun-linux-arm64 --outfile bin/dtsx-linux-arm64",
-    "compile:windows-x64": "bun build ./bin/cli.ts --compile --minify --target=bun-windows-x64 --outfile bin/dtsx-windows-x64.exe",
-    "compile:darwin-x64": "bun build ./bin/cli.ts --compile --minify --target=bun-darwin-x64 --outfile bin/dtsx-darwin-x64",
-    "compile:darwin-arm64": "bun build ./bin/cli.ts --compile --minify --target=bun-darwin-arm64 --outfile bin/dtsx-darwin-arm64",
-    "lint": "bunx --bun eslint .",
-    "lint:fix": "bunx --bun eslint . --fix",
+    "compile:linux-x64": "bun build ./bin/cli.ts --compile --minify --format=esm --target=bun-linux-x64 --outfile bin/dtsx-linux-x64",
+    "compile:linux-arm64": "bun build ./bin/cli.ts --compile --minify --format=esm --target=bun-linux-arm64 --outfile bin/dtsx-linux-arm64",
+    "compile:windows-x64": "bun build ./bin/cli.ts --compile --minify --format=esm --target=bun-windows-x64 --outfile bin/dtsx-windows-x64.exe",
+    "compile:darwin-x64": "bun build ./bin/cli.ts --compile --minify --format=esm --target=bun-darwin-x64 --outfile bin/dtsx-darwin-x64",
+    "compile:darwin-arm64": "bun build ./bin/cli.ts --compile --minify --format=esm --target=bun-darwin-arm64 --outfile bin/dtsx-darwin-arm64",
+    "lint": "bunx --bun pickier run . --mode lint",
+    "lint:fix": "bunx --bun pickier run . --mode lint --fix",
     "fresh": "bunx rimraf node_modules/ bun.lock && bun i",
     "changelog": "bunx changelogen --output CHANGELOG.md",
     "prepublishOnly": "bun --bun run build && bun run compile:all && bun run zip",
@@ -64,17 +93,26 @@
     "zip:darwin-x64": "zip -j bin/dtsx-darwin-x64.zip bin/dtsx-darwin-x64",
     "zip:darwin-arm64": "zip -j bin/dtsx-darwin-arm64.zip bin/dtsx-darwin-arm64"
   },
+  "peerDependencies": {
+    "typescript": ">=5.9.3"
+  },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": false
+    }
+  },
   "dependencies": {
     "@stacksjs/clapp": "^0.2.0"
   },
   "devDependencies": {
     "bunfig": "^0.15.6",
-    "tinyglobby": "^0.2.15"
+    "oxc-parser": "^0.112.0",
+    "typescript": "^5.9.3"
   },
   "git-hooks": {
     "pre-commit": {
       "staged-lint": {
-        "*.{js,ts,json,yaml,yml,md}": "bunx --bun eslint . --fix"
+        "*.{js,ts,json,yaml,yml,md}": "bunx --bun pickier run . --mode lint --fix"
       }
     }
   }