webpack-plugin-dtsx 0.9.10

package/LICENSE.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2024 Open Web Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,249 @@
+# webpack-plugin-dtsx
+
+A webpack plugin for automatic TypeScript declaration file generation using dtsx.
+
+## Installation
+
+```bash
+bun add webpack-plugin-dtsx -d
+# or
+npm install webpack-plugin-dtsx --save-dev
+```
+
+## Usage
+
+```javascript
+// webpack.config.js
+const { DtsxWebpackPlugin } = require('webpack-plugin-dtsx')
+
+module.exports = {
+  entry: './src/index.ts',
+  output: {
+    path: path.resolve(__dirname, 'dist'),
+    filename: 'bundle.js',
+  },
+  plugins: [
+    new DtsxWebpackPlugin({
+      // Options
+    }),
+  ],
+}
+```
+
+### ESM Usage
+
+```javascript
+// webpack.config.mjs
+import { DtsxWebpackPlugin } from 'webpack-plugin-dtsx'
+
+export default {
+  entry: './src/index.ts',
+  output: {
+    path: new URL('./dist', import.meta.url).pathname,
+    filename: 'bundle.js',
+  },
+  plugins: [
+    new DtsxWebpackPlugin(),
+  ],
+}
+```
+
+## Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `trigger` | `'emit' \| 'afterEmit' \| 'done'` | `'afterEmit'` | When to generate declarations |
+| `entryPointsOnly` | `boolean` | `true` | Only generate for entry points |
+| `declarationDir` | `string` | webpack output path | Output directory for declarations |
+| `bundle` | `boolean` | `false` | Bundle all declarations into one file |
+| `bundleOutput` | `string` | `'index.d.ts'` | Bundled output filename |
+| `exclude` | `(string \| RegExp)[]` | `[]` | Patterns to exclude |
+| `include` | `(string \| RegExp)[]` | `[]` | Patterns to include |
+| `emitOnError` | `boolean` | `false` | Emit even with compilation errors |
+| `skipUnchanged` | `boolean` | `true` | Skip if no TS files changed (watch mode) |
+
+## Examples
+
+### Basic Usage
+
+```javascript
+const { DtsxWebpackPlugin } = require('webpack-plugin-dtsx')
+
+module.exports = {
+  // ...
+  plugins: [
+    new DtsxWebpackPlugin(),
+  ],
+}
+```
+
+### With Bundled Declarations
+
+```javascript
+const { DtsxWebpackPlugin } = require('webpack-plugin-dtsx')
+
+module.exports = {
+  // ...
+  plugins: [
+    new DtsxWebpackPlugin({
+      bundle: true,
+      bundleOutput: 'types.d.ts',
+    }),
+  ],
+}
+```
+
+### Custom Output Directory
+
+```javascript
+const { DtsxWebpackPlugin } = require('webpack-plugin-dtsx')
+
+module.exports = {
+  // ...
+  plugins: [
+    new DtsxWebpackPlugin({
+      declarationDir: 'types', // Outputs to dist/types/
+    }),
+  ],
+}
+```
+
+### Generate on Different Phases
+
+```javascript
+const { DtsxWebpackPlugin } = require('webpack-plugin-dtsx')
+
+module.exports = {
+  // ...
+  plugins: [
+    new DtsxWebpackPlugin({
+      // 'emit' - During asset emission
+      // 'afterEmit' - After assets are written (default)
+      // 'done' - When compilation is complete
+      trigger: 'done',
+    }),
+  ],
+}
+```
+
+### With Callbacks
+
+```javascript
+const { DtsxWebpackPlugin } = require('webpack-plugin-dtsx')
+
+module.exports = {
+  // ...
+  plugins: [
+    new DtsxWebpackPlugin({
+      onStart: () => {
+        console.log('Starting declaration generation...')
+      },
+      onSuccess: (stats) => {
+        console.log(`Generated ${stats.totalFiles} files in ${stats.totalTime}ms`)
+      },
+      onError: (error) => {
+        console.error('Failed to generate declarations:', error.message)
+      },
+    }),
+  ],
+}
+```
+
+### Filter Files
+
+```javascript
+const { DtsxWebpackPlugin } = require('webpack-plugin-dtsx')
+
+module.exports = {
+  // ...
+  plugins: [
+    new DtsxWebpackPlugin({
+      include: [/src\/lib/],
+      exclude: ['test', /\.spec\.ts$/],
+    }),
+  ],
+}
+```
+
+### Process All TypeScript Files
+
+```javascript
+const { DtsxWebpackPlugin } = require('webpack-plugin-dtsx')
+
+module.exports = {
+  // ...
+  plugins: [
+    new DtsxWebpackPlugin({
+      entryPointsOnly: false, // Process all TS files in compilation
+    }),
+  ],
+}
+```
+
+## Additional Plugins
+
+### Type Checking Only
+
+```javascript
+const { dtsxCheck } = require('webpack-plugin-dtsx')
+
+module.exports = {
+  plugins: [dtsxCheck()],
+}
+```
+
+### Watch for Declaration Changes
+
+```javascript
+const { dtsxWatch } = require('webpack-plugin-dtsx')
+
+module.exports = {
+  plugins: [
+    dtsxWatch({
+      onDeclarationChange: (file) => {
+        console.log(`Declaration changed: ${file}`)
+      },
+    }),
+  ],
+}
+```
+
+## Factory Function
+
+You can also use the factory function:
+
+```javascript
+const { dtsx } = require('webpack-plugin-dtsx')
+
+module.exports = {
+  plugins: [
+    dtsx({
+      bundle: true,
+    }),
+  ],
+}
+```
+
+## Webpack 4 vs 5
+
+This plugin supports both webpack 4 and webpack 5. The API is the same for both versions.
+
+## TypeScript Configuration
+
+The plugin automatically detects your `tsconfig.json`. You can also specify a custom path:
+
+```javascript
+new DtsxWebpackPlugin({
+  tsconfigPath: './tsconfig.build.json',
+})
+```
+
+## Performance Tips
+
+1. **Use `entryPointsOnly: true`** (default) for faster builds
+2. **Enable `skipUnchanged`** (default) in watch mode
+3. **Use `trigger: 'done'`** if you don't need declarations during emit
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,56 @@
+import type { Compiler } from 'webpack';
+import type { DtsGenerationOption, GenerationStats } from '@stacksjs/dtsx';
+// Re-export types
+export type { DtsGenerationOption, GenerationStats };
+/**
+ * Factory function for creating the plugin
+ */
+export declare function dtsx(options?: DtsxWebpackOptions): DtsxWebpackPlugin;
+/**
+ * Factory function for check plugin
+ */
+export declare function dtsxCheck(): DtsxCheckPlugin;
+/**
+ * Factory function for watch plugin
+ */
+export declare function dtsxWatch(options?: { onDeclarationChange?: (file: string) => void }): DtsxWatchPlugin;
+/**
+ * Plugin configuration options
+ */
+export declare interface DtsxWebpackOptions extends Omit<Partial<DtsGenerationOption>, 'exclude' | 'include'> {
+  trigger?: 'emit' | 'afterEmit' | 'done'
+  entryPointsOnly?: boolean
+  declarationDir?: string
+  bundle?: boolean
+  bundleOutput?: string
+  exclude?: (string | RegExp)[]
+  include?: (string | RegExp)[]
+  emitOnError?: boolean
+  declarationMap?: boolean
+  skipUnchanged?: boolean
+  onSuccess?: (stats: GenerationStats) => void | Promise<void>
+  onError?: (error: Error) => void | Promise<void>
+  onStart?: () => void | Promise<void>
+  onProgress?: (current: number, total: number, file: string) => void
+}
+/**
+ * Webpack plugin for dtsx declaration generation
+ */
+export declare class DtsxWebpackPlugin {
+  constructor(options?: DtsxWebpackOptions);
+  apply(compiler: Compiler): void;
+}
+/**
+ * Create a minimal plugin that only validates types
+ */
+export declare class DtsxCheckPlugin {
+  apply(compiler: Compiler): void;
+}
+/**
+ * Create a plugin that watches for .d.ts changes
+ */
+export declare class DtsxWatchPlugin {
+  constructor(options?: { onDeclarationChange?: (file: string) => void });
+  apply(compiler: Compiler): void;
+}
+export default DtsxWebpackPlugin;

package/dist/index.js

@@ -0,0 +1,312 @@
+// src/index.ts
+import { generate } from "@stacksjs/dtsx";
+import { resolve, relative, join, dirname } from "node:path";
+import { existsSync, mkdirSync, writeFileSync, readFileSync } from "node:fs";
+var PLUGIN_NAME = "DtsxWebpackPlugin";
+
+class DtsxWebpackPlugin {
+  options;
+  state;
+  constructor(options = {}) {
+    this.options = {
+      trigger: "afterEmit",
+      entryPointsOnly: true,
+      bundle: false,
+      bundleOutput: "index.d.ts",
+      emitOnError: false,
+      declarationMap: false,
+      skipUnchanged: true,
+      ...options
+    };
+    this.state = {
+      lastBuildFiles: new Set,
+      generatedFiles: new Set,
+      isFirstBuild: true,
+      errors: []
+    };
+  }
+  apply(compiler) {
+    const { trigger } = this.options;
+    switch (trigger) {
+      case "emit":
+        compiler.hooks.emit.tapAsync(PLUGIN_NAME, (compilation, callback) => {
+          this.handleGeneration(compiler, compilation).then(() => callback()).catch(callback);
+        });
+        break;
+      case "afterEmit":
+        compiler.hooks.afterEmit.tapAsync(PLUGIN_NAME, (compilation, callback) => {
+          this.handleGeneration(compiler, compilation).then(() => callback()).catch(callback);
+        });
+        break;
+      case "done":
+        compiler.hooks.done.tapAsync(PLUGIN_NAME, (stats, callback) => {
+          this.handleGeneration(compiler, stats.compilation).then(() => callback()).catch(callback);
+        });
+        break;
+    }
+    compiler.hooks.watchRun.tap(PLUGIN_NAME, () => {
+      this.state.isFirstBuild = false;
+    });
+  }
+  async handleGeneration(compiler, compilation) {
+    const {
+      entryPointsOnly,
+      declarationDir,
+      bundle,
+      bundleOutput,
+      exclude = [],
+      include = [],
+      emitOnError,
+      skipUnchanged,
+      onSuccess,
+      onError,
+      onStart,
+      ...dtsOptions
+    } = this.options;
+    if (compilation.errors.length > 0 && !emitOnError) {
+      console.log(`[${PLUGIN_NAME}] Skipping declaration generation due to compilation errors`);
+      return;
+    }
+    try {
+      await onStart?.();
+      let filesToProcess = this.getFilesToProcess(compiler, compilation, entryPointsOnly);
+      filesToProcess = this.filterFiles(filesToProcess, include, exclude);
+      if (skipUnchanged && !this.state.isFirstBuild) {
+        const currentFiles = new Set(filesToProcess);
+        const hasChanges = this.hasFileChanges(currentFiles);
+        if (!hasChanges) {
+          console.log(`[${PLUGIN_NAME}] No TypeScript changes detected, skipping`);
+          return;
+        }
+        this.state.lastBuildFiles = currentFiles;
+      }
+      if (filesToProcess.length === 0) {
+        console.log(`[${PLUGIN_NAME}] No files to process`);
+        return;
+      }
+      console.log(`[${PLUGIN_NAME}] Generating declarations for ${filesToProcess.length} file(s)...`);
+      const outputPath = compiler.options.output?.path || "dist";
+      const outdir = declarationDir ? resolve(outputPath, declarationDir) : outputPath;
+      const config = this.normalizeConfig(dtsOptions, compiler, outdir);
+      const stats = await generate({
+        ...config,
+        entrypoints: filesToProcess.map((f) => relative(config.cwd || process.cwd(), f))
+      });
+      this.state.generatedFiles = new Set;
+      if (bundle && this.state.generatedFiles.size > 0) {
+        await this.bundleDeclarations(Array.from(this.state.generatedFiles), join(outdir, bundleOutput));
+      }
+      await onSuccess?.(stats);
+      console.log(`[${PLUGIN_NAME}] Generated ${this.state.generatedFiles.size} declaration file(s)`);
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+      this.state.errors.push(err);
+      if (onError) {
+        await onError(err);
+      } else {
+        console.error(`[${PLUGIN_NAME}] Error generating declarations:`, err.message);
+      }
+    }
+  }
+  getFilesToProcess(compiler, compilation, entryPointsOnly) {
+    const files = [];
+    if (entryPointsOnly) {
+      const entries = compiler.options.entry;
+      if (typeof entries === "string") {
+        files.push(resolve(entries));
+      } else if (Array.isArray(entries)) {
+        for (const entry of entries) {
+          if (typeof entry === "string") {
+            files.push(resolve(entry));
+          }
+        }
+      } else if (typeof entries === "object") {
+        for (const [, entry] of Object.entries(entries)) {
+          if (typeof entry === "string") {
+            files.push(resolve(entry));
+          } else if (typeof entry === "object" && entry.import) {
+            const imports = Array.isArray(entry.import) ? entry.import : [entry.import];
+            for (const imp of imports) {
+              if (typeof imp === "string") {
+                files.push(resolve(imp));
+              }
+            }
+          }
+        }
+      }
+    } else {
+      for (const module of compilation.modules) {
+        const resource = module.resource;
+        if (resource && this.isTypeScriptFile(resource)) {
+          files.push(resource);
+        }
+      }
+    }
+    return files.filter((f) => this.isTypeScriptFile(f));
+  }
+  isTypeScriptFile(file) {
+    return (file.endsWith(".ts") || file.endsWith(".tsx")) && !file.endsWith(".d.ts");
+  }
+  filterFiles(files, include, exclude) {
+    return files.filter((file) => {
+      for (const pattern of exclude) {
+        if (typeof pattern === "string") {
+          if (file.includes(pattern))
+            return false;
+        } else if (pattern.test(file)) {
+          return false;
+        }
+      }
+      if (include.length > 0) {
+        for (const pattern of include) {
+          if (typeof pattern === "string") {
+            if (file.includes(pattern))
+              return true;
+          } else if (pattern.test(file)) {
+            return true;
+          }
+        }
+        return false;
+      }
+      return true;
+    });
+  }
+  hasFileChanges(currentFiles) {
+    if (currentFiles.size !== this.state.lastBuildFiles.size) {
+      return true;
+    }
+    for (const file of currentFiles) {
+      if (!this.state.lastBuildFiles.has(file)) {
+        return true;
+      }
+    }
+    return false;
+  }
+  normalizeConfig(options, compiler, outdir) {
+    const context = compiler.options.context || process.cwd();
+    let tsconfigPath = options.tsconfigPath;
+    if (!tsconfigPath) {
+      const defaultPaths = ["tsconfig.json", "tsconfig.build.json"];
+      for (const p of defaultPaths) {
+        if (existsSync(resolve(context, p))) {
+          tsconfigPath = p;
+          break;
+        }
+      }
+    }
+    return {
+      cwd: context,
+      root: options.root || "./src",
+      outdir,
+      tsconfigPath,
+      clean: options.clean ?? false,
+      keepComments: options.keepComments ?? true,
+      ...options
+    };
+  }
+  async bundleDeclarations(files, outputPath) {
+    const contents = [
+      "/**",
+      " * Bundled TypeScript declarations",
+      ` * Generated by ${PLUGIN_NAME}`,
+      " */",
+      ""
+    ];
+    const imports = new Map;
+    const declarations = [];
+    for (const file of files) {
+      if (!existsSync(file))
+        continue;
+      const content = readFileSync(file, "utf-8");
+      const lines = content.split(`
+`);
+      for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed.startsWith("import ")) {
+          const match = trimmed.match(/from\s+['"]([^'"]+)['"]/);
+          if (match && !match[1].startsWith(".")) {
+            if (!imports.has(match[1])) {
+              imports.set(match[1], new Set);
+            }
+            const specMatch = trimmed.match(/\{([^}]+)\}/);
+            if (specMatch) {
+              specMatch[1].split(",").forEach((s) => {
+                imports.get(match[1]).add(s.trim());
+              });
+            }
+          }
+          continue;
+        }
+        if (trimmed.startsWith("import ") || trimmed === "")
+          continue;
+        declarations.push(line);
+      }
+    }
+    for (const [source, specifiers] of imports) {
+      if (specifiers.size > 0) {
+        contents.push(`import { ${Array.from(specifiers).join(", ")} } from '${source}';`);
+      }
+    }
+    if (imports.size > 0) {
+      contents.push("");
+    }
+    contents.push(...declarations);
+    const outDir = dirname(outputPath);
+    if (!existsSync(outDir)) {
+      mkdirSync(outDir, { recursive: true });
+    }
+    writeFileSync(outputPath, contents.join(`
+`));
+    console.log(`[${PLUGIN_NAME}] Bundled declarations to ${outputPath}`);
+  }
+}
+function dtsx(options = {}) {
+  return new DtsxWebpackPlugin(options);
+}
+
+class DtsxCheckPlugin {
+  apply(compiler) {
+    compiler.hooks.done.tap("DtsxCheckPlugin", (stats) => {
+      if (stats.hasErrors()) {
+        console.log("[DtsxCheckPlugin] Build has errors, skipping type check");
+        return;
+      }
+      console.log("[DtsxCheckPlugin] Build passed");
+    });
+  }
+}
+function dtsxCheck() {
+  return new DtsxCheckPlugin;
+}
+
+class DtsxWatchPlugin {
+  options;
+  constructor(options = {}) {
+    this.options = options;
+  }
+  apply(compiler) {
+    const { onDeclarationChange } = this.options;
+    compiler.hooks.afterEmit.tap("DtsxWatchPlugin", (compilation) => {
+      if (!onDeclarationChange)
+        return;
+      for (const file of compilation.emittedAssets) {
+        if (file.endsWith(".d.ts")) {
+          onDeclarationChange(file);
+        }
+      }
+    });
+  }
+}
+function dtsxWatch(options = {}) {
+  return new DtsxWatchPlugin(options);
+}
+var src_default = DtsxWebpackPlugin;
+export {
+  dtsxWatch,
+  dtsxCheck,
+  dtsx,
+  src_default as default,
+  DtsxWebpackPlugin,
+  DtsxWatchPlugin,
+  DtsxCheckPlugin
+};

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "webpack-plugin-dtsx",
+  "type": "module",
+  "version": "0.9.10",
+  "description": "A webpack plugin that auto generates your DTS types extremely fast.",
+  "author": "Chris Breuer <chris@ow3.org>",
+  "license": "MIT",
+  "homepage": "https://github.com/stacksjs/dtsx/tree/main/packages/webpack-plugin#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stacksjs/dtsx.git"
+  },
+  "bugs": {
+    "url": "https://github.com/stacksjs/dtsx/issues"
+  },
+  "keywords": [
+    "dts",
+    "dtsx",
+    "emit",
+    "generation",
+    "typescript",
+    "types",
+    "auto",
+    "stacks",
+    "webpack",
+    "plugin",
+    "package"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./*": {
+      "import": "./dist/*"
+    }
+  },
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "LICENSE.md",
+    "README.md",
+    "dist"
+  ],
+  "scripts": {
+    "build": "bun build.ts",
+    "prepublishOnly": "bun run build",
+    "test": "bun test",
+    "typecheck": "bun tsc --noEmit"
+  },
+  "dependencies": {
+    "@stacksjs/dtsx": "0.9.10"
+  },
+  "peerDependencies": {
+    "webpack": "^4.0.0 || ^5.0.0"
+  }
+}