bun-plugin-dtsx 0.9.8 → 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,149 @@
+# bun-plugin-dtsx
+
+A Bun Bundler plugin for automatic TypeScript declaration file generation using dtsx.
+
+## Installation
+
+```bash
+bun add bun-plugin-dtsx -d
+# or
+npm install bun-plugin-dtsx --save-dev
+```
+
+## Usage
+
+```typescript
+// build.ts
+import { dts } from 'bun-plugin-dtsx'
+
+await Bun.build({
+  entrypoints: ['src/index.ts'],
+  outdir: 'dist',
+  plugins: [
+    dts({
+      // 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` | Bun 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 { dts } from 'bun-plugin-dtsx'
+
+await Bun.build({
+  entrypoints: ['src/index.ts'],
+  outdir: 'dist',
+  plugins: [dts()],
+})
+```
+
+### With Bundled Declarations
+
+```typescript
+import { dts } from 'bun-plugin-dtsx'
+
+await Bun.build({
+  entrypoints: ['src/index.ts'],
+  outdir: 'dist',
+  plugins: [
+    dts({
+      bundle: true,
+      bundleOutput: 'types.d.ts',
+    }),
+  ],
+})
+```
+
+### Multiple Entry Points
+
+```typescript
+import { dts } from 'bun-plugin-dtsx'
+
+await Bun.build({
+  entrypoints: ['src/index.ts', 'src/utils.ts'],
+  outdir: 'dist',
+  plugins: [
+    dts({
+      entryPointsOnly: true,
+    }),
+  ],
+})
+```
+
+### With Callbacks
+
+```typescript
+import { dts } from 'bun-plugin-dtsx'
+
+await Bun.build({
+  entrypoints: ['src/index.ts'],
+  outdir: 'dist',
+  plugins: [
+    dts({
+      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
+
+```typescript
+import { dts } from 'bun-plugin-dtsx'
+
+await Bun.build({
+  entrypoints: ['src/index.ts'],
+  outdir: 'dist',
+  plugins: [
+    dts({
+      include: [/src\/lib/],
+      exclude: ['test', /\.spec\.ts$/],
+    }),
+  ],
+})
+```
+
+### Custom Output Directory
+
+```typescript
+import { dts } from 'bun-plugin-dtsx'
+
+await Bun.build({
+  entrypoints: ['src/index.ts'],
+  outdir: 'dist',
+  plugins: [
+    dts({
+      declarationDir: 'types',
+    }),
+  ],
+})
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -1,21 +1,110 @@
 import type { BunPlugin } from 'bun';
-import type { DtsGenerationOption } from '@stacksjs/dtsx';
-export type { DtsGenerationOption };
+import type { DtsGenerationOption, GenerationStats } from '@stacksjs/dtsx';
+export type { DtsGenerationOption, GenerationStats };
 /**
  * Creates a Bun plugin for generating TypeScript declaration files
  * @param options - Configuration options for DTS generation
  * @returns BunPlugin instance
  */
 export declare function dts(options?: PluginConfig): BunPlugin;
+/**
+ * Create a watch mode plugin that regenerates on file changes
+ */
+export declare function dtsWatch(options?: PluginConfig): BunPlugin;
+/**
+ * Create a plugin that only validates types without generating
+ */
+export declare function dtsCheck(options: Omit<PluginConfig, 'outdir'>): BunPlugin;
+/**
+ * Clear the incremental cache
+ */
+export declare function clearCache(cacheDir?: string): void;
+/**
+ * Error codes for categorizing plugin errors
+ */
+export declare const PluginErrorCodes: {
+  CONFIG_ERROR: 'CONFIG_ERROR';
+  GENERATION_ERROR: 'GENERATION_ERROR';
+  FILE_ERROR: 'FILE_ERROR';
+  CACHE_ERROR: 'CACHE_ERROR';
+  TIMEOUT_ERROR: 'TIMEOUT_ERROR'
+};
+/**
+ * Build event payload
+ */
+export declare interface BuildEvent {
+  type: BuildEventType
+  timestamp: number
+  data: BuildEventData
+}
+/**
+ * Incremental cache entry
+ */
+declare interface CacheEntry {
+  hash: string
+  outputFile: string
+  timestamp: number
+}
 /**
  * Configuration interface extending DtsGenerationOption with build-specific properties
  */
-declare interface PluginConfig extends DtsGenerationOption {
+export declare interface PluginConfig extends DtsGenerationOption {
   build?: {
     config: {
       root?: string
       outdir?: string
     }
   }
+  onSuccess?: (stats: GenerationStats) => void | Promise<void>
+  onError?: (error: DtsxPluginError) => void | Promise<void>
+  failOnError?: boolean
+  incremental?: boolean
+  cacheDir?: string
+  on?: Partial<Record<BuildEventType, BuildEventListener>>
+  timeout?: number
+  continueOnError?: boolean
+  verbose?: boolean
+}
+export type PluginErrorCode = typeof PluginErrorCodes[keyof typeof PluginErrorCodes];
+/**
+ * Build event types
+ */
+export type BuildEventType = 'start' | 'progress' | 'file' | 'complete' | 'error';
+export type BuildEventData = | { type: 'start', files: string[], config: DtsGenerationOption }
+  | { type: 'progress', processed: number, total: number, currentFile: string }
+  | { type: 'file', file: string, outputFile: string, duration: number, cached: boolean }
+  | { type: 'complete', stats: GenerationStats, duration: number, fromCache: number }
+  | { type: 'error', error: DtsxPluginError, file?: string }
+/**
+ * Event listener function
+ */
+export type BuildEventListener = (_event: BuildEvent) => void | Promise<void>;
+/**
+ * Custom error class for bun-plugin-dtsx
+ */
+export declare class DtsxPluginError extends Error {
+  readonly code: PluginErrorCode;
+  readonly context?: Record<string, unknown>;
+  readonly cause?: Error;
+  constructor(message: string, code: PluginErrorCode, context?: Record<string, unknown>, cause?: Error);
+  toJSON(): Record<string, unknown>;
+}
+/**
+ * Event emitter for build events
+ */
+declare class BuildEventEmitter {
+  on(type: BuildEventType, listener: BuildEventListener): void;
+  emit(type: BuildEventType, data: BuildEventData): Promise<void>;
+}
+/**
+ * Incremental cache manager
+ */
+declare class IncrementalCache {
+  constructor(cacheDir: string, configHash: string);
+  save(): void;
+  getEntry(filePath: string): CacheEntry | undefined;
+  setEntry(filePath: string, entry: CacheEntry): void;
+  isValid(filePath: string, currentHash: string): boolean;
+  clear(): void;
 }
-export default dts;
+export default dts;

package/dist/index.js

@@ -1,24 +1,245 @@
 // @bun
+var __require = import.meta.require;
+
 // src/index.ts
+import { createHash } from "crypto";
+import { existsSync, readFileSync, writeFileSync } from "fs";
+import { join, resolve } from "path";
 import process from "process";
 import { generate } from "@stacksjs/dtsx";
-function dts(options = {
-  root: "./src",
-  outdir: "./dist"
-}) {
+var PluginErrorCodes = {
+  CONFIG_ERROR: "CONFIG_ERROR",
+  GENERATION_ERROR: "GENERATION_ERROR",
+  FILE_ERROR: "FILE_ERROR",
+  CACHE_ERROR: "CACHE_ERROR",
+  TIMEOUT_ERROR: "TIMEOUT_ERROR"
+};
+
+class DtsxPluginError extends Error {
+  code;
+  context;
+  cause;
+  constructor(message, code, context, cause) {
+    super(message);
+    this.name = "DtsxPluginError";
+    this.code = code;
+    this.context = context;
+    this.cause = cause;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+  toJSON() {
+    return {
+      name: this.name,
+      code: this.code,
+      message: this.message,
+      context: this.context,
+      stack: this.stack
+    };
+  }
+}
+
+class BuildEventEmitter {
+  listeners = new Map;
+  on(type, listener) {
+    const existing = this.listeners.get(type) || [];
+    existing.push(listener);
+    this.listeners.set(type, existing);
+  }
+  async emit(type, data) {
+    const event = {
+      type,
+      timestamp: Date.now(),
+      data
+    };
+    const listeners = this.listeners.get(type) || [];
+    for (const listener of listeners) {
+      await listener(event);
+    }
+  }
+}
+
+class IncrementalCache {
+  manifest;
+  cacheDir;
+  manifestPath;
+  constructor(cacheDir, configHash) {
+    this.cacheDir = cacheDir;
+    this.manifestPath = join(cacheDir, "manifest.json");
+    this.manifest = this.loadManifest(configHash);
+  }
+  loadManifest(configHash) {
+    try {
+      if (existsSync(this.manifestPath)) {
+        const data = JSON.parse(readFileSync(this.manifestPath, "utf-8"));
+        if (data.configHash === configHash && data.version === "1.0") {
+          return data;
+        }
+      }
+    } catch {}
+    return {
+      version: "1.0",
+      configHash,
+      entries: {}
+    };
+  }
+  save() {
+    try {
+      const { mkdirSync } = __require("fs");
+      mkdirSync(this.cacheDir, { recursive: true });
+      writeFileSync(this.manifestPath, JSON.stringify(this.manifest, null, 2));
+    } catch {}
+  }
+  getEntry(filePath) {
+    return this.manifest.entries[filePath];
+  }
+  setEntry(filePath, entry) {
+    this.manifest.entries[filePath] = entry;
+  }
+  isValid(filePath, currentHash) {
+    const entry = this.getEntry(filePath);
+    return entry?.hash === currentHash;
+  }
+  clear() {
+    this.manifest.entries = {};
+    this.save();
+  }
+}
+function computeConfigHash(config) {
+  const relevantConfig = {
+    root: config.root,
+    outdir: config.outdir,
+    entrypoints: config.entrypoints,
+    clean: config.clean,
+    tsconfigPath: config.tsconfigPath
+  };
+  return createHash("md5").update(JSON.stringify(relevantConfig)).digest("hex");
+}
+function dts(options = {}) {
+  const {
+    onSuccess,
+    onError,
+    failOnError = true,
+    incremental = false,
+    cacheDir = ".dtsx-cache",
+    on,
+    timeout = 60000,
+    continueOnError = false,
+    verbose = false,
+    ...dtsOptions
+  } = options;
+  const emitter = new BuildEventEmitter;
+  if (on) {
+    for (const [type, listener] of Object.entries(on)) {
+      if (listener) {
+        emitter.on(type, listener);
+      }
+    }
+  }
   return {
     name: "bun-plugin-dtsx",
     async setup(build) {
-      const config = normalizeConfig(options, build);
-      await generate(config);
+      const startTime = Date.now();
+      let cache = null;
+      const fromCache = 0;
+      try {
+        const config = normalizeConfig(dtsOptions, build);
+        const configHash = computeConfigHash(config);
+        if (incremental) {
+          cache = new IncrementalCache(resolve(cacheDir), configHash);
+        }
+        await emitter.emit("start", {
+          type: "start",
+          files: config.entrypoints || [],
+          config
+        });
+        if (verbose) {
+          console.log("[bun-plugin-dtsx] Starting declaration generation...");
+          if (incremental) {
+            console.log("[bun-plugin-dtsx] Incremental mode enabled");
+          }
+        }
+        const generateWithTimeout = async () => {
+          return new Promise((resolvePromise, rejectPromise) => {
+            const timeoutId = setTimeout(() => {
+              rejectPromise(new DtsxPluginError(`Generation timed out after ${timeout}ms`, "TIMEOUT_ERROR", { timeout }));
+            }, timeout);
+            generate(config).then((stats2) => {
+              clearTimeout(timeoutId);
+              resolvePromise(stats2);
+            }).catch((err) => {
+              clearTimeout(timeoutId);
+              rejectPromise(err);
+            });
+          });
+        };
+        const stats = await generateWithTimeout();
+        const duration = Date.now() - startTime;
+        if (cache) {
+          cache.save();
+        }
+        await emitter.emit("complete", {
+          type: "complete",
+          stats,
+          duration,
+          fromCache
+        });
+        if (verbose) {
+          console.log(`[bun-plugin-dtsx] Generation complete in ${duration}ms`);
+          if (fromCache > 0) {
+            console.log(`[bun-plugin-dtsx] ${fromCache} files served from cache`);
+          }
+        }
+        if (onSuccess) {
+          await onSuccess(stats);
+        }
+      } catch (error) {
+        const pluginError = wrapError(error);
+        await emitter.emit("error", {
+          type: "error",
+          error: pluginError
+        });
+        if (onError) {
+          await onError(pluginError);
+        } else {
+          console.error("[bun-plugin-dtsx] Error generating declarations:");
+          console.error(`  Code: ${pluginError.code}`);
+          console.error(`  Message: ${pluginError.message}`);
+          if (pluginError.context) {
+            console.error(`  Context: ${JSON.stringify(pluginError.context)}`);
+          }
+          if (verbose && pluginError.stack) {
+            console.error(`  Stack: ${pluginError.stack}`);
+          }
+        }
+        if (failOnError && !continueOnError) {
+          throw pluginError;
+        }
+      }
     }
   };
 }
+function wrapError(error) {
+  if (error instanceof DtsxPluginError) {
+    return error;
+  }
+  if (error instanceof Error) {
+    let code = "GENERATION_ERROR";
+    if (error.message.includes("config") || error.message.includes("Config")) {
+      code = "CONFIG_ERROR";
+    } else if (error.message.includes("file") || error.message.includes("File") || error.message.includes("ENOENT")) {
+      code = "FILE_ERROR";
+    }
+    return new DtsxPluginError(error.message, code, { originalError: error.name }, error);
+  }
+  return new DtsxPluginError(String(error), "GENERATION_ERROR");
+}
 function normalizeConfig(options, build) {
-  const root = options.root || build?.config.root;
-  const outdir = options.outdir || build?.config.outdir;
+  const root = options.root || options.build?.config.root || build?.config.root || "./src";
+  const outdir = options.outdir || options.build?.config.outdir || build?.config.outdir || "./dist";
   if (!root) {
-    throw new Error("[bun-plugin-dtsx] Root directory is required");
+    throw new DtsxPluginError("Root directory is required", "CONFIG_ERROR", { providedRoot: root });
   }
   return {
     ...options,
@@ -30,8 +251,43 @@ function normalizeConfig(options, build) {
     tsconfigPath: options.tsconfigPath
   };
 }
+function dtsWatch(options = {}) {
+  return dts({
+    ...options,
+    incremental: true,
+    verbose: options.verbose ?? true
+  });
+}
+function dtsCheck(options) {
+  return {
+    name: "bun-plugin-dtsx-check",
+    async setup(build) {
+      const config = normalizeConfig({ ...options, outdir: "" }, build);
+      try {
+        await generate({ ...config, clean: false });
+      } catch (error) {
+        const pluginError = wrapError(error);
+        if (options.onError) {
+          await options.onError(pluginError);
+        }
+        if (options.failOnError !== false) {
+          throw pluginError;
+        }
+      }
+    }
+  };
+}
+function clearCache(cacheDir = ".dtsx-cache") {
+  const cache = new IncrementalCache(resolve(cacheDir), "");
+  cache.clear();
+}
 var src_default = dts;
 export {
+  dtsWatch,
+  dtsCheck,
   dts,
-  src_default as default
+  src_default as default,
+  clearCache,
+  PluginErrorCodes,
+  DtsxPluginError
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "bun-plugin-dtsx",
   "type": "module",
-  "version": "0.9.8",
+  "version": "0.9.10",
   "description": "A Bun Bundler plugin that auto generates your DTS types extremely fast.",
   "author": "Chris Breuer <chris@ow3.org>",
   "license": "MIT",
@@ -49,6 +49,6 @@
     "typecheck": "bun tsc --noEmit"
   },
   "dependencies": {
-    "@stacksjs/dtsx": "0.9.7"
+    "@stacksjs/dtsx": "0.9.10"
   }
 }