esbuild-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,152 @@
+# esbuild-plugin-dtsx
+
+An esbuild plugin for automatic TypeScript declaration file generation using dtsx.
+
+## Installation
+
+```bash
+bun add esbuild-plugin-dtsx -d
+# or
+npm install esbuild-plugin-dtsx --save-dev
+```
+
+## Usage
+
+```typescript
+import { build } from 'esbuild'
+import { dtsx } from 'esbuild-plugin-dtsx'
+
+await build({
+  entryPoints: ['src/index.ts'],
+  outdir: 'dist',
+  bundle: true,
+  format: 'esm',
+  plugins: [
+    dtsx({
+      // Options
+    }),
+  ],
+})
+```
+
+## Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `trigger` | `'build' \| 'watch' \| 'both'` | `'build'` | When to generate declarations |
+| `entryPointsOnly` | `boolean` | `true` | Only generate for entry points |
+| `declarationDir` | `string` | esbuild outdir | 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` | `true` | Emit even with type errors |
+
+## Examples
+
+### Basic Usage
+
+```typescript
+import { build } from 'esbuild'
+import { dtsx } from 'esbuild-plugin-dtsx'
+
+await build({
+  entryPoints: ['src/index.ts'],
+  outdir: 'dist',
+  plugins: [dtsx()],
+})
+```
+
+### With Bundled Declarations
+
+```typescript
+import { build } from 'esbuild'
+import { dtsx } from 'esbuild-plugin-dtsx'
+
+await build({
+  entryPoints: ['src/index.ts'],
+  outdir: 'dist',
+  plugins: [
+    dtsx({
+      bundle: true,
+      bundleOutput: 'types.d.ts',
+    }),
+  ],
+})
+```
+
+### Watch Mode
+
+```typescript
+import { context } from 'esbuild'
+import { dtsx } from 'esbuild-plugin-dtsx'
+
+const ctx = await context({
+  entryPoints: ['src/index.ts'],
+  outdir: 'dist',
+  plugins: [
+    dtsx({
+      trigger: 'both', // Generate on initial build and rebuilds
+    }),
+  ],
+})
+
+await ctx.watch()
+```
+
+### With Callbacks
+
+```typescript
+import { build } from 'esbuild'
+import { dtsx } from 'esbuild-plugin-dtsx'
+
+await build({
+  entryPoints: ['src/index.ts'],
+  outdir: 'dist',
+  plugins: [
+    dtsx({
+      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)
+      },
+    }),
+  ],
+})
+```
+
+## Additional Plugins
+
+### Type Checking Only
+
+```typescript
+import { dtsxCheck } from 'esbuild-plugin-dtsx'
+
+await build({
+  plugins: [dtsxCheck()],
+})
+```
+
+### Watch for Declaration Changes
+
+```typescript
+import { dtsxWatch } from 'esbuild-plugin-dtsx'
+
+await build({
+  plugins: [
+    dtsxWatch({
+      onDeclarationChange: (file) => {
+        console.log(`Declaration changed: ${file}`)
+      },
+    }),
+  ],
+})
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,40 @@
+import type { DtsGenerationOption, GenerationStats } from '@stacksjs/dtsx';
+import type { Plugin } from 'esbuild';
+// Re-export types
+export type { DtsGenerationOption, GenerationStats };
+/**
+ * Create esbuild plugin for dtsx
+ */
+export declare function dtsx(options?: DtsxEsbuildOptions): Plugin;
+/**
+ * Create a minimal plugin that only validates types
+ */
+export declare function dtsxCheck(): Plugin;
+/**
+ * Create a plugin that watches for .d.ts changes
+ */
+export declare function dtsxWatch(options?: {
+  onDeclarationChange?: (file: string) => void
+}): Plugin;
+/**
+ * Plugin configuration options
+ */
+export declare interface DtsxEsbuildOptions extends Omit<Partial<DtsGenerationOption>, 'exclude' | 'include'> {
+  trigger?: 'build' | 'watch' | 'both'
+  entryPointsOnly?: boolean
+  declarationDir?: string
+  bundle?: boolean
+  bundleOutput?: string
+  sourceMaps?: boolean
+  exclude?: (string | RegExp)[]
+  include?: (string | RegExp)[]
+  emitOnError?: boolean
+  declarationMap?: boolean
+  paths?: Record<string, string[]>
+  baseUrl?: string
+  onSuccess?: (stats: GenerationStats) => void | Promise<void>
+  onError?: (error: Error) => void | Promise<void>
+  onStart?: () => void | Promise<void>
+  onProgress?: (current: number, total: number, file: string) => void
+}
+export default dtsx;

package/dist/index.js

@@ -0,0 +1,251 @@
+// src/index.ts
+import { generate } from "@stacksjs/dtsx";
+import { resolve, dirname, relative, join } from "node:path";
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+function dtsx(options = {}) {
+  const {
+    trigger = "build",
+    entryPointsOnly = true,
+    declarationDir,
+    bundle: bundleDeclarations = false,
+    bundleOutput = "index.d.ts",
+    sourceMaps = false,
+    exclude = [],
+    include = [],
+    emitOnError = true,
+    declarationMap = false,
+    paths,
+    baseUrl,
+    onSuccess,
+    onError,
+    onStart,
+    onProgress,
+    ...dtsOptions
+  } = options;
+  const state = {
+    buildOptions: null,
+    isWatchMode: false,
+    generatedFiles: /* @__PURE__ */ new Set(),
+    errors: []
+  };
+  return {
+    name: "dtsx",
+    setup(build) {
+      state.buildOptions = build.initialOptions;
+      state.isWatchMode = !!build.initialOptions.watch;
+      const shouldRun = trigger === "both" || trigger === "build" && !state.isWatchMode || trigger === "watch" && state.isWatchMode;
+      if (!shouldRun) {
+        return;
+      }
+      build.onEnd(async (result) => {
+        if (result.errors.length > 0 && !emitOnError) {
+          console.log("[dtsx] Skipping declaration generation due to build errors");
+          return;
+        }
+        try {
+          await onStart?.();
+          const config = normalizeConfig(
+            dtsOptions,
+            state.buildOptions,
+            declarationDir
+          );
+          let filesToProcess = [];
+          if (entryPointsOnly) {
+            filesToProcess = getEntryPoints(state.buildOptions);
+          } else {
+            filesToProcess = getTypeScriptFiles(result, state.buildOptions);
+          }
+          filesToProcess = filterFiles(filesToProcess, include, exclude);
+          if (filesToProcess.length === 0) {
+            console.log("[dtsx] No files to process");
+            return;
+          }
+          console.log(`[dtsx] Generating declarations for ${filesToProcess.length} file(s)...`);
+          const stats = await generate({
+            ...config,
+            entrypoints: filesToProcess.map((f) => relative(config.cwd || process.cwd(), f))
+          });
+          state.generatedFiles = /* @__PURE__ */ new Set();
+          if (bundleDeclarations && state.generatedFiles.size > 0) {
+            await bundleDeclarationsFiles(
+              Array.from(state.generatedFiles),
+              join(config.outdir || "dist", bundleOutput)
+            );
+          }
+          await onSuccess?.(stats);
+          console.log(`[dtsx] Generated ${state.generatedFiles.size} declaration file(s)`);
+        } catch (error) {
+          const err = error instanceof Error ? error : new Error(String(error));
+          state.errors.push(err);
+          if (onError) {
+            await onError(err);
+          } else {
+            console.error("[dtsx] Error generating declarations:", err.message);
+          }
+        }
+      });
+    }
+  };
+}
+function normalizeConfig(options, buildOptions, declarationDir) {
+  const outdir = declarationDir || buildOptions.outdir || "dist";
+  const cwd = options.cwd || process.cwd();
+  let tsconfigPath = options.tsconfigPath;
+  if (!tsconfigPath) {
+    const defaultPaths = ["tsconfig.json", "tsconfig.build.json"];
+    for (const p of defaultPaths) {
+      if (existsSync(resolve(cwd, p))) {
+        tsconfigPath = p;
+        break;
+      }
+    }
+  }
+  return {
+    cwd,
+    root: options.root || "./src",
+    outdir,
+    tsconfigPath,
+    clean: options.clean ?? false,
+    keepComments: options.keepComments ?? true,
+    ...options
+  };
+}
+function getEntryPoints(options) {
+  const entryPoints = options.entryPoints;
+  if (!entryPoints) {
+    return [];
+  }
+  if (Array.isArray(entryPoints)) {
+    return entryPoints.filter((e) => typeof e === "string");
+  }
+  if (typeof entryPoints === "object") {
+    return Object.values(entryPoints);
+  }
+  return [];
+}
+function getTypeScriptFiles(result, options) {
+  const files = [];
+  if (result.metafile) {
+    for (const input of Object.keys(result.metafile.inputs)) {
+      if (input.endsWith(".ts") || input.endsWith(".tsx")) {
+        if (!input.endsWith(".d.ts")) {
+          files.push(resolve(input));
+        }
+      }
+    }
+  }
+  if (files.length === 0) {
+    files.push(...getEntryPoints(options));
+  }
+  return files;
+}
+function 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;
+  });
+}
+async function bundleDeclarationsFiles(files, outputPath) {
+  const contents = [
+    "/**",
+    " * Bundled TypeScript declarations",
+    ` * Generated by dtsx esbuild plugin`,
+    " */",
+    ""
+  ];
+  const imports = /* @__PURE__ */ new Map();
+  const declarations = [];
+  for (const file of files) {
+    if (!existsSync(file)) continue;
+    const content = readFileSync(file, "utf-8");
+    const lines = content.split("\n");
+    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], /* @__PURE__ */ 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("\n"));
+  console.log(`[dtsx] Bundled declarations to ${outputPath}`);
+}
+function dtsxCheck() {
+  return {
+    name: "dtsx-check",
+    setup(build) {
+      build.onEnd(async (result) => {
+        if (result.errors.length === 0) {
+          console.log("[dtsx-check] Build passed type checking");
+        }
+      });
+    }
+  };
+}
+function dtsxWatch(options = {}) {
+  return {
+    name: "dtsx-watch",
+    setup(build) {
+      const { onDeclarationChange } = options;
+      build.onResolve({ filter: /\.d\.ts$/ }, (args) => {
+        return {
+          path: args.path,
+          watchFiles: [args.path]
+        };
+      });
+      build.onLoad({ filter: /\.d\.ts$/ }, (args) => {
+        onDeclarationChange?.(args.path);
+        return null;
+      });
+    }
+  };
+}
+var index_default = dtsx;
+export {
+  index_default as default,
+  dtsx,
+  dtsxCheck,
+  dtsxWatch
+};

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "esbuild-plugin-dtsx",
+  "type": "module",
+  "version": "0.9.10",
+  "description": "An esbuild 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/esbuild-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",
+    "esbuild",
+    "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": {
+    "esbuild": ">=0.27.3"
+  }
+}