@dtsx/vite 0.0.0-stage → 0.11.39

package/README.md

@@ -1,3 +1,157 @@
-# Temporary Holding Version
+# @dtsx/vite
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A Vite plugin for automatic TypeScript declaration file generation using dtsx.
+
+## Installation
+
+```bash
+bun add @dtsx/vite -d
+# or
+npm install @dtsx/vite --save-dev
+```
+
+## Usage
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite'
+import { dts } from '@dtsx/vite'
+
+export default defineConfig({
+  plugins: [
+    dts({
+      // Options
+    }),
+  ],
+})
+```
+
+## Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `trigger` | `'build' \| 'serve' \| 'both'` | `'build'` | When to generate declarations |
+| `timing` | `'before' \| 'after'` | `'before'` | Generate before Vite writes the bundle (after it empties `outDir`) or after the build |
+| `root` | `string` | folder of `build.lib.entry`, else `./src` | Source root; declarations mirror the source from here |
+| `outdir` | `string` | Vite `build.outDir` | Output directory for declarations |
+| `entryPointsOnly` | `boolean` | `true` | Only generate for entry points |
+| `declarationDir` | `string` | Vite 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
+// vite.config.ts
+import { defineConfig } from 'vite'
+import { dts } from '@dtsx/vite'
+
+export default defineConfig({
+  plugins: [dts()],
+})
+```
+
+### With Bundled Declarations
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite'
+import { dts } from '@dtsx/vite'
+
+export default defineConfig({
+  plugins: [
+    dts({
+      bundle: true,
+      bundleOutput: 'types.d.ts',
+    }),
+  ],
+})
+```
+
+### Library Mode
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite'
+import { dts } from '@dtsx/vite'
+
+export default defineConfig({
+  build: {
+    lib: {
+      entry: 'src/index.ts',
+      formats: ['es', 'cjs'],
+    },
+  },
+  plugins: [
+    dts({
+      entryPointsOnly: true,
+    }),
+  ],
+})
+```
+
+### With Callbacks
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite'
+import { dts } from '@dtsx/vite'
+
+export default defineConfig({
+  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
+// vite.config.ts
+import { defineConfig } from 'vite'
+import { dts } from '@dtsx/vite'
+
+export default defineConfig({
+  plugins: [
+    dts({
+      include: [/src\/lib/],
+      exclude: ['test', /\.spec\.ts$/],
+    }),
+  ],
+})
+```
+
+### Dev Server Mode
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite'
+import { dts } from '@dtsx/vite'
+
+export default defineConfig({
+  plugins: [
+    dts({
+      trigger: 'both', // Generate on both build and dev server start
+    }),
+  ],
+})
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,39 @@
+import type { DtsGenerationOption, GenerationStats } from '@dtsx/dtsx';
+import type { Plugin } from 'vite';
+export type { DtsGenerationOption, GenerationStats };
+/**
+ * Creates a Vite plugin for generating TypeScript declaration files
+ * @param options - Configuration options for DTS generation
+ * @returns Vite Plugin instance
+ */
+export declare function dts(options?: DtsPluginOptions): Plugin;
+/**
+ * Create a minimal Vite plugin for just type checking
+ */
+export declare function dtsCheck(_options?: Partial<DtsPluginOptions>): Plugin;
+/**
+ * Create a Vite plugin that bundles all declarations into one file
+ */
+export declare function dtsBundled(options?: DtsPluginOptions & { bundleOutput?: string }): Plugin;
+/**
+ * Configuration interface extending DtsGenerationOption with Vite-specific properties
+ */
+export declare interface DtsPluginOptions extends DtsGenerationOption {
+  trigger?: 'build' | 'serve' | 'both'
+  watch?: boolean
+  watchDebounce?: number
+  watchPatterns?: string[]
+  timing?: 'before' | 'after'
+  hmr?: boolean
+  insertTypesEntry?: boolean
+  typesEntry?: string
+  external?: (string | RegExp)[]
+  includePrivate?: boolean
+  sourceMaps?: boolean
+  skipIfUpToDate?: boolean
+  onSuccess?: (stats: GenerationStats) => void | Promise<void>
+  onError?: (error: Error) => void | Promise<void>
+  onFileChange?: (file: string) => void | Promise<void>
+  onStart?: () => void | Promise<void>
+}
+export default dts;

package/dist/index.js

@@ -0,0 +1,268 @@
+// @bun
+// src/index.ts
+import { watch as fsWatch } from "fs";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "path";
+import { generate } from "@dtsx/dtsx";
+function dts(options = {}) {
+  const {
+    trigger = "build",
+    watch: enableWatch,
+    watchDebounce = 300,
+    watchPatterns = [],
+    timing = "before",
+    hmr = false,
+    insertTypesEntry = false,
+    typesEntry = "index.d.ts",
+    external = [],
+    includePrivate = false,
+    sourceMaps = false,
+    skipIfUpToDate = true,
+    onSuccess,
+    onError,
+    onFileChange,
+    onStart,
+    ...dtsOptions
+  } = options;
+  const state = {
+    viteConfig: null,
+    server: null,
+    watcher: null,
+    debounceTimer: null,
+    lastGeneratedAt: 0,
+    isGenerating: false,
+    changedFiles: new Set
+  };
+  let generatedThisBuild = false;
+  async function generateDeclarations(changedFiles) {
+    if (state.isGenerating) {
+      return null;
+    }
+    state.isGenerating = true;
+    try {
+      await onStart?.();
+      const config = normalizeConfig(dtsOptions, state.viteConfig);
+      const stats = await generate(config);
+      state.lastGeneratedAt = Date.now();
+      state.changedFiles.clear();
+      await onSuccess?.(stats);
+      if (hmr && state.server) {
+        notifyTypeChanges(state.server, config.outdir || "dist");
+      }
+      return stats;
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+      if (onError) {
+        await onError(err);
+      } else {
+        console.error("[vite-plugin-dtsx] Error generating declarations:", err.message);
+        throw err;
+      }
+      return null;
+    } finally {
+      state.isGenerating = false;
+    }
+  }
+  function handleFileChange(filePath) {
+    if (!shouldProcessFile(filePath, dtsOptions.entrypoints, dtsOptions.exclude)) {
+      return;
+    }
+    state.changedFiles.add(filePath);
+    onFileChange?.(filePath);
+    if (state.debounceTimer) {
+      clearTimeout(state.debounceTimer);
+    }
+    state.debounceTimer = setTimeout(() => {
+      const files = Array.from(state.changedFiles);
+      generateDeclarations(files);
+    }, watchDebounce);
+  }
+  function startWatcher(root) {
+    if (state.watcher) {
+      return;
+    }
+    try {
+      state.watcher = fsWatch(root, { recursive: true }, (_eventType, filename) => {
+        if (filename && filename.endsWith(".ts") && !filename.endsWith(".d.ts")) {
+          handleFileChange(join(root, filename));
+        }
+      });
+      console.log("[vite-plugin-dtsx] Watching for file changes...");
+    } catch (error) {
+      console.error("[vite-plugin-dtsx] Failed to start watcher:", error);
+    }
+  }
+  function stopWatcher() {
+    if (state.watcher) {
+      state.watcher.close();
+      state.watcher = null;
+    }
+    if (state.debounceTimer) {
+      clearTimeout(state.debounceTimer);
+      state.debounceTimer = null;
+    }
+  }
+  return {
+    name: "vite-plugin-dtsx",
+    enforce: timing === "before" ? "pre" : "post",
+    configResolved(config) {
+      state.viteConfig = config;
+    },
+    configureServer(server) {
+      state.server = server;
+      const shouldWatch = enableWatch ?? true;
+      if (shouldWatch && (trigger === "serve" || trigger === "both")) {
+        const { cwd, root } = normalizeConfig(dtsOptions, state.viteConfig);
+        startWatcher(resolve(cwd, root));
+      }
+    },
+    async buildStart() {
+      if (timing !== "before" || state.viteConfig?.command !== "serve")
+        return;
+      if (trigger !== "serve" && trigger !== "both")
+        return;
+      await generateDeclarations();
+    },
+    async renderStart() {
+      if (timing !== "before" || generatedThisBuild)
+        return;
+      if (state.viteConfig?.command !== "build" || trigger === "serve")
+        return;
+      generatedThisBuild = true;
+      await generateDeclarations();
+    },
+    async closeBundle() {
+      generatedThisBuild = false;
+      if (timing !== "after")
+        return;
+      if (trigger === "build" || trigger === "both") {
+        await generateDeclarations();
+      }
+    },
+    async buildEnd() {
+      stopWatcher();
+    },
+    async handleHotUpdate({ file, server }) {
+      if (!hmr)
+        return;
+      if (file.endsWith(".ts") && !file.endsWith(".d.ts")) {
+        handleFileChange(file);
+      }
+      return;
+    },
+    generateBundle(_, bundle) {
+      if (!insertTypesEntry)
+        return;
+      const typesPath = typesEntry;
+      if (bundle[typesPath])
+        return;
+      const libConfig = state.viteConfig?.build?.lib;
+      const libName = libConfig && typeof libConfig === "object" && "name" in libConfig ? libConfig.name : "library";
+      bundle[typesPath] = {
+        type: "asset",
+        fileName: typesPath,
+        source: `// Type definitions for ${libName}
+// Generated by vite-plugin-dtsx
+
+export * from './${basename(typesPath, ".d.ts")}';
+`,
+        name: typesPath,
+        names: [typesPath],
+        originalFileName: null,
+        originalFileNames: [],
+        needsCodeReference: false
+      };
+    }
+  };
+}
+function normalizeConfig(options, viteConfig) {
+  const cwd = options.cwd || viteConfig?.root || process.cwd();
+  const root = options.root || defaultRoot(cwd, viteConfig);
+  const outdir = options.outdir || viteConfig?.build?.outDir || "./dist";
+  const exclude = [...options.exclude ?? []];
+  const configFile = viteConfig?.configFile;
+  if (!options.root && configFile && isInside(configFile, resolve(cwd, root)))
+    exclude.push(configFile);
+  return {
+    ...options,
+    cwd,
+    root,
+    entrypoints: options.entrypoints || ["**/*.ts"],
+    exclude,
+    outdir,
+    clean: options.clean,
+    tsconfigPath: options.tsconfigPath
+  };
+}
+function defaultRoot(cwd, viteConfig) {
+  const lib = viteConfig?.build?.lib;
+  const entry = lib ? lib.entry : undefined;
+  const entries = typeof entry === "string" ? [entry] : Array.isArray(entry) ? entry : entry ? Object.values(entry) : [];
+  if (entries.length === 0)
+    return "./src";
+  const directories = entries.map((file) => dirname(resolve(cwd, file)));
+  return directories.reduce(commonDirectory);
+}
+function commonDirectory(a, b) {
+  let common = a;
+  while (!isInside(b, common) && dirname(common) !== common)
+    common = dirname(common);
+  return common;
+}
+function isInside(path, directory) {
+  const rel = relative(directory, path);
+  return rel === "" || !rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel);
+}
+function shouldProcessFile(filePath, _include, exclude) {
+  if (filePath.endsWith(".d.ts")) {
+    return false;
+  }
+  if (filePath.includes("node_modules")) {
+    return false;
+  }
+  if (!filePath.endsWith(".ts") && !filePath.endsWith(".tsx")) {
+    return false;
+  }
+  if (exclude) {
+    for (const pattern of exclude) {
+      if (filePath.includes(pattern)) {
+        return false;
+      }
+    }
+  }
+  return true;
+}
+function notifyTypeChanges(server, outdir) {
+  server.ws.send({
+    type: "custom",
+    event: "dtsx:types-updated",
+    data: {
+      outdir,
+      timestamp: Date.now()
+    }
+  });
+}
+function dtsCheck(_options = {}) {
+  return {
+    name: "vite-plugin-dtsx-check",
+    enforce: "pre",
+    async buildStart() {
+      console.log("[vite-plugin-dtsx] Type checking...");
+    }
+  };
+}
+function dtsBundled(options = {}) {
+  const { bundleOutput: _bundleOutput = "types.d.ts", ...dtsOptions } = options;
+  return {
+    ...dts({
+      ...dtsOptions
+    }),
+    name: "vite-plugin-dtsx-bundled"
+  };
+}
+var src_default = dts;
+export {
+  src_default as default,
+  dts,
+  dtsBundled,
+  dtsCheck
+};

package/package.json

@@ -1,6 +1,64 @@
 {
   "name": "@dtsx/vite",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "type": "module",
+  "version": "0.11.39",
+  "description": "A modern, fast .d.ts generation tool, powered by Bun.",
+  "author": "Chris Breuer <chris@stacksjs.org>",
+  "license": "MIT",
+  "homepage": "https://github.com/stacksjs/dtsx#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stacksjs/dtsx.git"
+  },
+  "bugs": {
+    "url": "https://github.com/stacksjs/dtsx/issues"
+  },
+  "keywords": [
+    "dts",
+    "generation",
+    "isolated declarations",
+    "development",
+    "bun",
+    "stacks",
+    "typescript",
+    "javascript"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "bun build.ts",
+    "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",
+    "release": "bun run changelog && bunx bumpp package.json --all",
+    "test": "bun test",
+    "typecheck": "bunx tsc --noEmit"
+  },
+  "dependencies": {
+    "@dtsx/dtsx": "0.11.39"
+  },
+  "devDependencies": {
+    "vite": "^8.3.6"
+  },
+  "peerDependencies": {
+    "vite": "^4.0.0 || ^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0"
+  },
+  "git-hooks": {
+    "pre-commit": {
+      "staged-lint": {
+        "*.{js,ts,json,yaml,yml,md}": "bunx --bun pickier run . --mode lint --fix"
+      }
+    }
+  }
+}