Tools for managing versioned TypeScript definition files
npm install versioned-d.ts-toolsbash
npm install -g versioned-d.ts-tools
`
Or install locally in your project:
`bash
npm install versioned-d.ts-tools
`
CLI Tools
$3
Removes specific API versions from TypeScript definition files.
`bash
version-remover [source d.ts] [output file name] [version string] [optional config file]
`
Examples:
`bash
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:
`json
{
"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:
`json
{
"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"
}
]
}
`
$3
Compares two TypeScript definition files and generates a markdown report of the differences.
`bash
whats-new [new d.ts] [old d.ts] [output file name (minus extension)] [relative path] [config file (optional)]
`
Examples:
`bash
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:
`json
{
"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/');
``