I am currently in search of a comprehensive example or best practices for creating a definition file (not necessarily a tsd) for a JavaScript library that does not have one in @types or included with the package.
While I have managed to put together a basic solution so far here, it does not exactly align with the guidelines provided in the "Definitions" section on the official TypeScript website.
Within the aforementioned repository, I am utilizing the package @google-cloud/datastore, which as per my knowledge, does not yet have a tsd file. Despite having sufficient documentation to create a manual definition file for the specific components I require, I am facing challenges in determining the best practice for exporting such definitions manually.
Specifically, based on the guidance provided here, it mentions:
/*~ This is the module template file for class modules.
*~ You should rename it to index.d.ts and place it in a folder with the same name as the module.
*~ For example, if you were writing a file for "super-greeter", this
*~ file should be 'super-greeter/index.d.ts'
*/
/*~ Note that ES6 modules cannot directly export class objects.
*~ This file should be imported using the CommonJS-style:
*~ import x = require('someLibrary');
*~
*~ Refer to the documentation to understand common
*~ workarounds for this limitation of ES6 modules.
*/
/*~ If this module is a UMD module that exposes a global variable 'myClassLib' when
*~ loaded outside a module loader environment, declare that global here.
*~ Otherwise, delete this declaration.
*/
According to the instructions above, it appears that I should be able to place an index.d.ts file in a directory outside of my node_modules/@types directory, replicating the same folder structure as my module. Although in my repository there exists a top-level directory @google-cloud/datastore containing an index.ts file, in line with the documentation, it suggests the usage of an index.d.ts file; nonetheless, neither my modules nor the compiler are detecting this. Do I need a compiler option for this?
Furthermore, is the approach I have taken in the repository correct? This method is not explicitly documented on their website, and it involved some guesswork before reaching a resolution. Essentially, I import the JavaScript package google-cloud/datastore into the index.ts, integrate my typings, and then export it for use in my modules. However, my modules must refer to the package using ./@google-cloud/datastore as this signifies the actual location of the TypeScript definitions.
In summary, within TypeScript v2.2.2, what constitutes the recommended practice for generating small, local TypeScript definition files for JavaScript libraries lacking a tsd?
Outcome
I have updated my repository with a solution proposed by Alex, and everything seems to function as anticipated. It is worth mentioning that adding a { "baseUrl": "types" } parameter also seemed to achieve the desired outcome, however, without a clear understanding of why this is correct, I opted for the suggested approach. The --traceResolution flag proved to be exceedingly beneficial throughout this process.
In this demonstration, I made sure to include another module with a TypeScript definition, lodash, to verify that normal module resolution remains accurate.
My directory/file structure:
+ js
...
+ node_modules
+ @google-cloud
+ datastore
+ lodash
+ @types
+ lodash
+ ...
+ types
+ @google-cloud
- index.d.ts
+ datastore
- index.d.ts
- index.ts
- package.json
- tsconfig.json
Resolution Trace
For those interested, I would like to present an example of an incorrect/correct result obtained from calling tsc --traceResolution. The results have been condensed for clarity.
Incorrect: Without the paths parameter, TypeScript resolves @google-cloud/datastore to the index.js file, leading to an erroneous outcome.
======== Module name '@google-cloud/datastore' was successfully resolved to 'C:/Users/Kory/Documents/Repos/playground/manual-typescript-definition/node_modules/@google-cloud/datastore/src/index.js'. ========
Correct: Utilizing the paths parameter. Notice how @google-cloud/datastore now resolves to the index.d.ts file rather than the JavaScript file.
======== Module name '@google-cloud/datastore' was successfully resolved to 'C:/Users/Kory/Documents/Repos/playground/manual-typescript-definition/types/@google-cloud/datastore/index.d.ts'. ========