DTS Buddy

https://github.com/sveltejs/dts-buddy
Admin
DTS Buddy is a tool for automatically generating .d.ts type declaration bundles for TypeScript...
Tokens:3,790
Snippets:28
Trust Score:9.8
License:MIT
Update:6 months ago
Show doc for...
Tokens:
Raw
### Using Path Aliases in JavaScript Source

Source: https://context7.com/sveltejs/dts-buddy/llms.txt

Example of a JavaScript source file utilizing path aliases defined in tsconfig.json for importing types and utilities.

```javascript
// src/index.js - using path aliases
/** @type {import('#types').InternalConfig} */
let config;

import { helper } from '#utils/helpers.js';

/**
 * @param {import('#types').Options}
 * @returns {import('#types').Result}
 */
export function process(options) {
  return helper(options);
}
```

--------------------------------

### Generated TypeScript Declaration File Output

Source: https://context7.com/sveltejs/dts-buddy/llms.txt

Example of a generated .d.ts file by DTS Buddy, including module declarations for different entry points and source map references.

```typescript
// types/index.d.ts (generated output)
declare module 'my-lib' {
  /** Represents a 2D point in space */
  export interface Point {
    /** X coordinate */
    x: number;
    /** Y coordinate */
    y: number;
  }
  /** Represents a geometric shape */
  export interface Shape {
    /** Calculate the area of the shape */
    area(): number;
    /** Calculate the perimeter of the shape */
    perimeter(): number;
  }
  /**
   * Calculate the distance between two points
   * @param a - First point
   * @param b - Second point
   * @returns The Euclidean distance
   */
  export function distance(a: Point, b: Point): number;

  export {};
}

declare module 'my-lib/shapes' {
  /** A circle shape */
  export class Circle implements import('my-lib').Shape {
    center: import('my-lib').Point;
    radius: number;
    constructor(center: import('my-lib').Point, radius: number);
    area(): number;
    perimeter(): number;
  }

  export {};
}

//# sourceMappingURL=index.d.ts.map
```

--------------------------------

### Define ambient modules for type bundles

Source: https://github.com/sveltejs/dts-buddy/blob/main/README.md

An example of how a generated .d.ts bundle uses 'declare module' blocks to expose types for a main package and its subpackages.

```typescript
declare module 'my-lib' {
  /**
   * Add two numbers
   */
  export function add(a: number, b: number): number;
}

declare module 'my-lib/subpackage' {
  /**
   * Multiply two numbers
   */
  export function multiply(a: number, b: number): number;
}
```

--------------------------------

### JSDoc for Type Definitions and Initialization (JavaScript)

Source: https://context7.com/sveltejs/dts-buddy/llms.txt

Demonstrates using JSDoc typedefs for configuration and client initialization in JavaScript. It shows how to define types, initialize a client, and define a client class with methods.

```javascript
// src/index.js
/**
 * A configuration object for the library
 * @typedef {Object} Config
 * @property {string} apiKey - The API key for authentication
 * @property {number} [timeout=5000] - Request timeout in milliseconds
 * @property {boolean} [debug=false] - Enable debug logging
 */

/**
 * Initialize the library with configuration
 * @param {Config} config - The configuration object
 * @returns {Client} A configured client instance
 * @example
 * const client = init({ apiKey: 'abc123', timeout: 10000 });
 */
export function init(config) {
  return new Client(config);
}

/**
 * The main client class
 */
export class Client {
  /** @type {Config} */
  #config;

  /**
   * @param {Config} config
   */
  constructor(config) {
    this.#config = config;
  }

  /**
   * Make a request to the API
   * @param {string} endpoint - The API endpoint
   * @param {Record<string, unknown>} [data] - Optional request data
   * @returns {Promise<Response>}
   */
  async request(endpoint, data) {
    // implementation
  }
}
```

--------------------------------

### Configure package.json for dts-buddy

Source: https://github.com/sveltejs/dts-buddy/blob/main/README.md

Shows how to update package.json to include the generated types and automate the bundling process during the prepublish phase.

```json
{
  "name": "my-lib",
  "version": "1.0.0",
  "type": "module",
  "types": "./types/index.d.ts",
  "files": [
    "src",
    "types"
  ],
  "exports": {
    ".": {
      "types": "./types/index.d.ts",
      "import": "./src/index.js"
    },
    "./subpackage": {
      "types": "./types/index.d.ts",
      "import": "./src/subpackage.js"
    }
  },
  "scripts": {
    "prepublishOnly": "dts-buddy"
  }
}
```

--------------------------------

### Configure Package.json for DTS Buddy

Source: https://context7.com/sveltejs/dts-buddy/llms.txt

This configuration demonstrates how to set up your `package.json` to use DTS Buddy for generating and publishing declaration files. It includes the `types` field pointing to the generated bundle, `files` to include necessary directories, `exports` for module resolution, and a `prepublishOnly` script to run DTS Buddy before publishing.

```json
{
  "name": "my-lib",
  "version": "1.0.0",
  "type": "module",
  "types": "./types/index.d.ts",
  "files": [
    "src",
    "types"
  ],
  "exports": {
    ".": {
      "types": "./types/index.d.ts",
      "import": "./src/index.js"
    },
    "./subpackage": {
      "types": "./types/index.d.ts",
      "import": "./src/subpackage.js"
    },
    "./utils": {
      "types": "./types/index.d.ts",
      "import": "./src/utils.js"
    }
  },
  "scripts": {
    "prepublishOnly": "dts-buddy"
  }
}
```

--------------------------------

### Use dts-buddy JavaScript API

Source: https://github.com/sveltejs/dts-buddy/blob/main/README.md

Demonstrates how to programmatically generate a type bundle using the dts-buddy JavaScript API.

```javascript
import { createBundle } from 'dts-buddy';

await createBundle({
  project: 'tsconfig.json',
  output: 'types/index.d.ts',
  modules: {
    'my-lib': 'src/index.js',
    'my-lib/subpackage': 'src/subpackage.js'
  }
});
```

--------------------------------

### Tsconfig.json with Path Aliases

Source: https://context7.com/sveltejs/dts-buddy/llms.txt

Configuration for tsconfig.json demonstrating the use of 'baseUrl' and 'paths' for aliasing module imports, which DTS Buddy supports.

```json
// tsconfig.json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "#types": ["./src/internal/types.d.ts"],
      "#utils/*": ["./src/internal/utils/*"]
    }
  },
  "include": ["src"]
}
```

--------------------------------

### DTS Buddy CLI Usage for Declaration Bundling

Source: https://context7.com/sveltejs/dts-buddy/llms.txt

The DTS Buddy command-line interface (CLI) automates the generation of TypeScript declaration bundles. It can infer entry points from `package.json` or accept them manually. The CLI supports specifying custom output locations, tsconfig files, module mappings, and enabling debug output for intermediate files.

```bash
# Basic usage - infers output and modules from package.json
dts-buddy

# Specify custom output location
dts-buddy types/index.d.ts

# Manually specify modules when package.json exports can't be inferred
dts-buddy types/index.d.ts -m my-lib:src/index.js -m my-lib/subpackage:src/subpackage.js

# Use custom tsconfig location
dts-buddy --project tsconfig.build.json

# Enable debug output to inspect intermediate .d.ts files
dts-buddy --debug debug-output

# Full example with all options
dts-buddy types/index.d.ts \
  --project tsconfig.json \
  --module my-lib:src/index.js \
  --module my-lib/utils:src/utils.ts \
  --debug debug
```

--------------------------------

### Create TypeScript Declaration Bundle with DTS Buddy API

Source: https://context7.com/sveltejs/dts-buddy/llms.txt

The `createBundle` function programmatically generates a single TypeScript declaration file (.d.ts) for a package. It processes source files, resolves imports and paths, and can output source maps. It accepts options for output path, module mappings, tsconfig path, compiler options, and file inclusion/exclusion patterns.

```javascript
import { createBundle } from 'dts-buddy';

// Basic usage with automatic inference from package.json
await createBundle({
  output: 'types/index.d.ts',
  modules: {
    'my-lib': 'src/index.js',
    'my-lib/subpackage': 'src/subpackage.js'
  }
});

// Advanced usage with full options
await createBundle({
  // Path to output .d.ts file (required)
  output: 'types/index.d.ts',

  // Map of module names to entry point files (required)
  modules: {
    'my-lib': 'src/index.js',
    'my-lib/utils': 'src/utils.ts',
    'my-lib/types': 'src/types.d.ts'
  },

  // Path to tsconfig.json (defaults to 'tsconfig.json')
  project: 'tsconfig.json',

  // Additional compiler options to merge with tsconfig
  compilerOptions: {
    baseUrl: '.',
    paths: {
      '#internal/*': ['./src/internal/*']
    }
  },

  // Glob patterns for files to include (defaults to tsconfig.include or ['**'])
  include: ['src/**/*.ts', 'src/**/*.js'],

  // Glob patterns for files to exclude (defaults to tsconfig.exclude or [])
  exclude: ['**/*.test.ts', '**/__tests__/**'],

  // Directory to emit intermediate .d.ts files for debugging
  debug: 'debug'
});

// Output: types/index.d.ts and types/index.d.ts.map
```

--------------------------------

### TypeScript Interfaces and Classes for Geometry (TypeScript)

Source: https://context7.com/sveltejs/dts-buddy/llms.txt

Defines TypeScript interfaces for Point and Shape, and implements a Circle class. It also includes a utility function to calculate the distance between two points.

```typescript
// src/types.ts
/** Represents a 2D point in space */
export interface Point {
  /** X coordinate */
  x: number;
  /** Y coordinate */
  y: number;
}

/** Represents a geometric shape */
export interface Shape {
  /** Calculate the area of the shape */
  area(): number;
  /** Calculate the perimeter of the shape */
  perimeter(): number;
}

// src/geometry.ts
import type { Point, Shape } from './types.js';

/** A circle shape */
export class Circle implements Shape {
  constructor(
    public center: Point,
    public radius: number
  ) {}

  area(): number {
    return Math.PI * this.radius ** 2;
  }

  perimeter(): number {
    return 2 * Math.PI * this.radius;
  }
}

/**
 * Calculate the distance between two points
 * @param a - First point
 * @param b - Second point
 * @returns The Euclidean distance
 */
export function distance(a: Point, b: Point): number {
  return Math.sqrt((b.x - a.x) ** 2 + (b.y - a.y) ** 2);
}
```

--------------------------------

### Stripping Internal Declarations with JSDoc @internal

Source: https://context7.com/sveltejs/dts-buddy/llms.txt

Demonstrates how to mark functions and types as internal using the JSDoc @internal tag, ensuring they are excluded from generated declaration files.

```javascript
// src/index.js
/**
 * Public API function
 * @param {string} input
 * @returns {string}
 */
export function publicFunction(input) {
  return internalHelper(input);
}

/**
 * This function is for internal use only
 * @internal
 * @param {string} input
 * @returns {string}
 */
export function internalHelper(input) {
  return input.toUpperCase();
}

/**
 * @typedef {Object} PublicType
 * @property {string} name
 */

/**
 * @internal
 * @typedef {Object} InternalType
 * @property {string} secret
 */
```
Tokens:
Raw