typescript-tpm
v0.1.7
Published
Typescript Definition Package Manager
Downloads
13
Readme
TPM: Typescript Package Manager
TPM provides useful programatic access to finding typescript definitions. The TPM library can be used to create other tools, like TSD. It will also provide its own tools to install definition files, to demonstrate how the library can be used, and to allow access to features before other tools integrate them.
I wouldn't mind if TPM was merged into another tool, so long as it provided similar functionality.
Installation
For API access
npm install typescript-tpm
For Command-line access
npm install -g typescript-tpm
Command-line Tool
TPM has its own definition installer to demonstrate how to use the library, and to provide early access to features.
Install dependencies by reading any .json
file that is similar to package.json
. This installs the dependencies to types/:folder/:file.d.ts
by default.
tpm install package.json -o types/
tpm install bower.json -o types/
# defaults to package.json and -o types/
tpm install
Create a single reference file pointing to all other reference files. Your application only needs to reference this single file to contain all definition files.
tpm index types/**/*.d.ts -o types/all.d.ts
Grunt Tasks
All of the command-line options are available as grunt tasks. This plugin requires Grunt ~0.4.1
If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:
npm install grunt-plugin-test --save-dev
Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:
grunt.loadNpmTasks('grunt-plugin-test');
Overview
In your project's Gruntfile, add a section named tpm-install
or tpm-index
to the data object passed into grunt.initConfig()
.
tpm-install
installs the definitions for a given package.json
or bower.json
.
tpm-index
creates a reference file pointing to all the definition files specified, so you only have to include one.
// dest is optional on both of these, the default is shown here
grunt.initConfig({
"tpm-install": {
all: {src: "package.json", dest: "types/"}
},
"tpm-index": {
all: {src: ["types/**/*.d.ts", dest: "types/all.d.ts"]}
}
})
grunt.registerTask("tpm", ['tpm-install', 'tpm-index')
Then, you can install definition files and build the index by typing
grunt tpm
Finding Definition Files
TPM has the ability to look up definition files (from DefinitelyTyped) by name, or by NPM, bower, or other package name. This will allow tools to install the definition corresponding to any dependency automatically.
This happens in two steps. First, download the index. This is constructed from the most recent data available online. Cache this and then use it to get definitions.
import tpm = require('tpm')
var cachedIndex:IDefinitionIndex
tpm.loadIndex().then(function(index) {
cachedIndex = index
})
Do not read the index directly. Instead use findDefinitions
to read from a cached index. This is synchronous, as it just uses the cached index.
var angularVersions:IDefinitionVersion[] = tpm.findDefinitions(cachedIndex, "angular")
var jqueryVersions:IDefinitionVersion[] = tpm.findDefinitions(cachedIndex, "jquery")
This would return an array of definitions, one per version if there are more. Usually it will just return 1. The URL is provided for convenience. Other tools can generate their own URL.
// IDefinitionVersion[]
[
{
"name": "angular",
"aliases": ["angularjs", "angular-browserify"],
"path": "angularjs/angular.d.ts",
"url": "https://raw.github.com/borisyankov/DefinitelyTyped/master/angularjs/angular.d.ts"
"commit": "master",
"version": "latest",
}
]
name
- the name of the package on DefinitelyTyped.
aliases
- other names that map to this definition
path
- the path to the definition within DefinitelyTyped
version
- this will contain version information if multiple versions exist. Otherwise it will be "latest"
commit
- almost always equal to "master". If the definition no longer exists on DefinitelyTyped, but did at some previous commit or in another branch, commit
will refer to a commit or branch where the definition exists
url
- for convenience, a download URL is provided for the definition file. Other tools can generate their own url from the data.
Default Definition Names
The DefinitelyTyped repository is read dynamically. This repository hosts corrections and aliases to it in the data
directory. We do not need an alias for every package. We only need them if they differ from the name of the file on DefinitelyTyped.
The name of the definition file is used as the default name. For example, on DefinitelyTyped, the name of the AngularJS definition is angular
, because its file is /angularjs/angular.d.ts
. Angular Resource is named angular-resource
and the file is /angularjs/angular-resource.d.ts
.
Aliases
This repository hosts the mapping of other names to the default names.
For example: angular-browserify
should map to the angular
definition. To specify an alias, edit data/alias.ts
then send us a pull request.
export var all:IAlias[] = [
...
{name: "angular", alias: "angular-browserify"},
...
]
Utilities
These features may be duplicated in other tools, but are provided here to demonstrate how to use the library, and to allow it to function if not yet implemented in other tools.
Get the contents of a definition
definitionContents(definition:IDefinitionVersion):Q.IPromise<NodeBuffer>
Download a definition to a file path.
downloadDefinition(definition:IDefinitionVersion, filepath:string):Q.IPromise<void>
Download a definition to a folder. If folder
is "types/" then it will download to "types/jquery/jquery.d.ts"
downloadDefinitionToFolder(definition, folder):Q.IPromise<void>
Create a single reference file pointing to other reference files. Your application only needs to reference this one file. Note that this can be used to reference your own definition files too!
createReferenceFile(typeFilePaths:string[], indexFilePath:string):Q.IPromise<void>
// example contents of indexFilePath if definitionFilePaths contained these three files
/// <reference path="app/mytypes.ts" />
/// <reference path="types/jquery/jquery.d.ts" />
/// <reference path="types/jquery/jquery.d.ts" />
Find definitions given a file similar to package.json
. This will work with bower.json
and package.json
.
// packageData should have a `dependencies` property
// name: version/folder/package, etc
findPackageDefinitions(cachedIndex:IDefinitionIndex, packageData:any):IDefinitionVersion[]
Later
Versioning: more information in alias files, matching up versions in generateFullIndex
. Correct versions in findPackageDefinitions
Feedback
Please provide feedback in one of these threads, or in an issue in this repository.
- https://github.com/borisyankov/DefinitelyTyped/issues/428
- https://typescript.codeplex.com/discussions/461449#post1104904