From 3e79f1093bd75ea6b0da14e193748c46d6e03901 Mon Sep 17 00:00:00 2001 From: Luca Casonato Date: Mon, 17 Jun 2024 08:02:43 +0200 Subject: [PATCH 1/2] Document @deno-self-types --- runtime/manual/advanced/typescript/types.md | 24 +++++++++++---------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/runtime/manual/advanced/typescript/types.md b/runtime/manual/advanced/typescript/types.md index d88317ca..f715f2bf 100644 --- a/runtime/manual/advanced/typescript/types.md +++ b/runtime/manual/advanced/typescript/types.md @@ -59,18 +59,18 @@ If you are in control of the source code of the module, or you are in control of how the file is hosted on a web server, there are two ways to inform Deno of the types for a given module, without requiring the importer to do anything special. -### Using the triple-slash reference directive +### Using `@deno-self-types` pragma -Deno supports using the triple-slash reference `types` directive, which adopts -the reference comment used by TypeScript in TypeScript files to _include_ other -files and applies it only to JavaScript files. +If you are providing a JavaScript file, and want to provide a declaration file +that contains the types for this file, you can specify a `@deno-self-types` +directive in the JS file, pointing to the declaration file. For example, if I had created `coolLib.js` and along side of it I had created my type definitions for my library in `coolLib.d.ts` I could do the following in the `coolLib.js` file: ```js -/// +// @deno-self-types="./coolLib.d.ts" // ... the rest of the JavaScript ... ``` @@ -79,10 +79,12 @@ When Deno encounters this directive, it would resolve the `./coolLib.d.ts` file and use that instead of the JavaScript file when TypeScript was type checking the file, but still load the JavaScript file when running the program. -> ℹ️ _Note_ this is a repurposed directive for TypeScript that only applies to -> JavaScript files. Using the triple-slash reference directive of `types` in a -> TypeScript file works under Deno as well, but has essentially the same -> behavior as the `path` directive. +> ℹ️ _Note_: Instead of `@deno-self-types`, a triple slash directive in the form +> of `/// ` can be used. This is not +> recommended anymore. This is a repurposed directive for TypeScript that only +> applies to JavaScript files. Using the triple-slash reference directive of +> `types` in a TypeScript file works under Deno as well, but has essentially the +> same behavior as the `path` directive. ### Using X-TypeScript-Types header @@ -125,8 +127,8 @@ include arbitrary type definitions when type checking programmes. ### Using a triple-slash directive This option couples the type definitions to the code itself. By adding a -triple-slash `types` directive near the type of a module, type checking the file -will include the type definition. For example: +triple-slash `types` directive in a TS file (not a JS file!), near the type of a +module, type checking the file will include the type definition. For example: ```ts /// From b9f3366c6f9afc63510087d549c8aa20b73697ef Mon Sep 17 00:00:00 2001 From: Luca Casonato Date: Mon, 17 Jun 2024 08:04:14 +0200 Subject: [PATCH 2/2] rename --- runtime/manual/advanced/typescript/types.md | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/runtime/manual/advanced/typescript/types.md b/runtime/manual/advanced/typescript/types.md index f715f2bf..fd6d3808 100644 --- a/runtime/manual/advanced/typescript/types.md +++ b/runtime/manual/advanced/typescript/types.md @@ -34,7 +34,7 @@ have direct control over, the ability to do the former is also required. If you are consuming a JavaScript module and you have either created types (a `.d.ts` file) or have otherwise obtained the types you want to use, you can instruct Deno to use that file when type checking instead of the JavaScript file -using the `@deno-types` compiler hint. `@deno-types` needs to be a single line +using the `@ts-types` compiler hint. `@ts-types` needs to be a single line double slash comment, where when used impacts the next import or re-export statement. @@ -42,7 +42,7 @@ For example if I have a JavaScript modules `coolLib.js` and I had a separate `coolLib.d.ts` file that I wanted to use, I would import it like this: ```ts -// @deno-types="./coolLib.d.ts" +// @ts-types="./coolLib.d.ts" import * as coolLib from "./coolLib.js"; ``` @@ -53,16 +53,19 @@ The pattern matching for the compiler hint is somewhat forgiving and will accept quoted and non-question values for the specifier as well as accepting whitespace before and after the equals sign. +> ℹ️ _Note_: The directive `@deno-types` can be used as an alias for `@ts-types`. +> This is not recommended anymore. + ## Providing types when hosting If you are in control of the source code of the module, or you are in control of how the file is hosted on a web server, there are two ways to inform Deno of the types for a given module, without requiring the importer to do anything special. -### Using `@deno-self-types` pragma +### Using `@ts-self-types` pragma If you are providing a JavaScript file, and want to provide a declaration file -that contains the types for this file, you can specify a `@deno-self-types` +that contains the types for this file, you can specify a `@ts-self-types` directive in the JS file, pointing to the declaration file. For example, if I had created `coolLib.js` and along side of it I had created my @@ -70,7 +73,7 @@ type definitions for my library in `coolLib.d.ts` I could do the following in the `coolLib.js` file: ```js -// @deno-self-types="./coolLib.d.ts" +// @ts-self-types="./coolLib.d.ts" // ... the rest of the JavaScript ... ``` @@ -79,8 +82,8 @@ When Deno encounters this directive, it would resolve the `./coolLib.d.ts` file and use that instead of the JavaScript file when TypeScript was type checking the file, but still load the JavaScript file when running the program. -> ℹ️ _Note_: Instead of `@deno-self-types`, a triple slash directive in the form -> of `/// ` can be used. This is not +> ℹ️ _Note_: Instead of `@ts-self-types`, a triple slash directive in the form of +> `/// ` can be used. This is not > recommended anymore. This is a repurposed directive for TypeScript that only > applies to JavaScript files. Using the triple-slash reference directive of > `types` in a TypeScript file works under Deno as well, but has essentially the