Versioned D.TS Tools

A collection of command-line tools for managing versioned TypeScript definition files, particularly useful for API documentation and version comparison.

Installation

Install globally to use the CLI tools from anywhere:

npm install -g versioned-d.ts-tools

Or install locally in your project:

npm install versioned-d.ts-tools

CLI Tools

version-remover

Removes specific API versions from TypeScript definition files.

version-remover [source d.ts] [output file name] [version string] [optional config file]

Examples:

# Basic usage
version-remover excel.d.ts excel_1_7.d.ts "Api set: ExcelApi 1.8"

# With configuration file for custom replacements
version-remover excel.d.ts excel_1_18.d.ts "Api set: ExcelApi 1.19" my-excel-config.json

This tool removes all declarations marked with the specified version string from the source .d.ts file and creates a new file with the remaining declarations.

Configuration File

You can provide an optional JSON configuration file to specify additional text replacements that should be applied after removing the API version. This is useful for cleaning up type unions or references that become invalid after removing certain APIs.

Some API versions (like "Api set: ExcelApi 1.19", "Api set: ExcelApi 1.11", "Api set: Mailbox 1.14", etc.) may require custom replacements to handle type union cleanups and parameter removals. You'll need to create configuration files for these scenarios based on your specific needs.

You can provide an optional JSON configuration file to specify additional text replacements that should be applied after removing the API version. This is useful for cleaning up type unions or references that become invalid after removing certain APIs.

Configuration file format:

{
  "replacements": [
    {
      "find": "old text to find",
      "replace": "replacement text",
      "description": "Optional description of what this replacement does"
    },
    {
      "find": "/regex pattern/g",
      "replace": "replacement",
      "isRegex": true,
      "description": "Example regex replacement"
    }
  ]
}

Example configuration:

{
  "replacements": [
    {
      "find": "type CardLayoutSection = CardLayoutListSection | CardLayoutTableSection | CardLayoutTwoColumnSection;",
      "replace": "type CardLayoutSection = CardLayoutListSection | CardLayoutTableSection;",
      "description": "Remove CardLayoutTwoColumnSection from union type"
    },
    {
      "find": "icon?: string | EntityCompactLayoutIcons;",
      "replace": "icon?: string;",
      "description": "Remove EntityCompactLayoutIcons from icon property"
    }
  ]
}

whats-new

Compares two TypeScript definition files and generates a markdown report of the differences.

whats-new [new d.ts] [old d.ts] [output file name (minus extension)] [relative path] [config file (optional)]

Examples:

# Basic usage
whats-new excel_1_9.d.ts excel_1_8.d.ts excel_whats_new javascript/api/excel/excel.

# With configuration file for custom link patterns
whats-new office-scripts.d.ts office-scripts-old.d.ts office-scripts-whats-new javascript/api/office-scripts/ my-link-config.json

This generates a markdown file (e.g., excel_whats_new.md) containing a table showing what's new between the two versions.

Configuration File

You can provide an optional JSON configuration file to customize the output by excluding specific fields, classes, and controlling what types of declarations are included.

Configuration file format:

{
  "excludedFieldNames": [
    "load", "set", "toJSON", "context", "track", "untrack"
  ],
  "excludedClassPatterns": [
    "LoadOptions$", "Data$"
  ],
  "excludedFieldPatterns": [
    "\\w+\\??:\\s*\".*\""
  ],
  "includeStaticFields": false,
  "includeEnums": false,
  "linkConfigs": [
    {
      "pathPattern": "office-scripts",
      "globalFunctionTemplate": "/{basePath}#officescript-officescript-{fieldName}-function(1)",
      "classTemplate": "/{basePath}/officescript.{className}",
      "classMemberTemplate": "/{basePath}/officescript.{className}#officescript-officescript-{className}-{fieldName}{suffix}"
    }
  ]
}

Configuration Options:

• excludedFieldNames - Array of exact field names to exclude from output
• excludedClassPatterns - Array of regex patterns for class names to exclude
• excludedFieldPatterns - Array of regex patterns for field declarations to exclude
• includeStaticFields - Boolean to include/exclude static fields (default: true)
• includeEnums - Boolean to include/exclude enum declarations (default: true when loading from config, false for backward compatibility when called directly)
• linkConfigs - Array of custom URL generation templates (see Link Configuration section below)

Enum Configurability:

The includeEnums option provides fine-grained control over enum inclusion:

• Default behavior: When calling the API directly, enums are excluded by default (includeEnums: false) for backward compatibility
• Config file behavior: When loading from a config file, enums are included by default (includeEnums: true) unless explicitly set to false
• Explicit control: Set "includeEnums": true to include enums, or "includeEnums": false to exclude them

This dual-default approach ensures existing integrations continue working while enabling new functionality when explicitly configured.

Link Configuration

The linkConfigs section allows you to customize how URLs are generated for different API types using flexible templates with placeholders.

**Available Template Placeholders:**

- `{basePath}` - relativePath without the trailing dot (e.g., 'javascript/api/excel/excel')
- `{hostName}` - extracted host name (e.g., 'excel', 'office-scripts')
- `{fileName}` - extracted file name (e.g., 'excel', 'officescript')
- `{className}` - class name in lowercase
- `{fieldName}` - field/method name in lowercase
- `{suffix}` - '-member(1)' for methods/functions, '-member' for properties

**Template Types:**

- `globalFunctionTemplate` - For namespace-level functions (global functions)
- `classTemplate` - For class/interface URLs in the first column
- `classMemberTemplate` - For class members (methods, properties, events)

When a configuration file is provided, the tool will use the appropriate URL template based on the pattern matching. The first matching `pathPattern` (regex) wins.

See `example-link-config.json` for a complete example.

## Programmatic Usage

You can also use the utilities programmatically in your own Node.js applications:

```javascript
const { APISet, parseDTS } = require('versioned-d.ts-tools');

// Parse a TypeScript definition file
const apiSet = parseDTS('filename', fileContents);

// Compare two API sets
const diff = newApiSet.diff(oldApiSet);

// Generate markdown output
const markdown = diff.getAsMarkdown('javascript/api/excel/');

License

MIT