downlevel-dts
Advanced tools
Comparing version 0.4.0 to 0.5.0
@@ -30,1 +30,4 @@ /// <reference path="./src/test.d.ts" /> | ||
} | ||
declare function guardIsString(val: any): val is string; | ||
declare function assertIsString(val: any, msg?: string): void; | ||
declare function assert(val: any, msg?: string): void; |
13
index.js
@@ -54,2 +54,15 @@ #!/usr/bin/env node | ||
const transform = function(n) { | ||
if (ts.isFunctionDeclaration(n) && n.type && ts.isTypePredicateNode(n.type) && n.type.assertsModifier) { | ||
return ts.createFunctionDeclaration( | ||
n.decorators, | ||
n.modifiers, | ||
n.asteriskToken, | ||
n.name, | ||
n.typeParameters, | ||
n.parameters, | ||
ts.createTypeReferenceNode("void", undefined), | ||
n.body | ||
); | ||
} | ||
if (ts.isGetAccessor(n)) { | ||
@@ -56,0 +69,0 @@ // get x(): number => x: number |
{ | ||
"name": "downlevel-dts", | ||
"version": "0.4.0", | ||
"version": "0.5.0", | ||
"description": "Convert d.ts to be compatible with older typescript compilers", | ||
"homepage": "https://github.com/sandersn/downlevel-dts", | ||
"main": "index.js", | ||
@@ -6,0 +7,0 @@ "bin": "index.js", |
224
README.md
@@ -0,1 +1,223 @@ | ||
downlevel-dts rewrites .d.ts files created by any version of Typescript so | ||
that they work with Typescript 3.4 or later. It does this by | ||
converting code with new features into code that uses equivalent old | ||
features. For example, it rewrites accessors to properties, because | ||
Typescript didn't support accessors in .d.ts files until 3.6: | ||
```ts | ||
declare class C { | ||
get x(): number; | ||
} | ||
``` | ||
becomes | ||
```ts | ||
declare class C { | ||
readonly x: number; | ||
} | ||
``` | ||
## Features | ||
Here is the list of features that are downlevelled: | ||
### `Omit` (3.5) | ||
```ts | ||
type Less = Omit<T, K>; | ||
``` | ||
becomes | ||
```ts | ||
type Less = Pick<T, Exclude<keyof T, K>>; | ||
``` | ||
`Omit` has had non-builtin implementations since Typescript 2.2, but | ||
became built-in in Typescript 3.5. | ||
#### Semantics | ||
`Omit` is a type alias, so the downlevel should behave exactly the same. | ||
### Accessors (3.6) | ||
Typescript prevented accessors from being in .d.ts files until | ||
Typescript 3.6 because they behave very similarly to properties. | ||
However, they behave differently with inheritance, so the distinction | ||
can be useful. | ||
```ts | ||
declare class C { | ||
get x(): number; | ||
} | ||
``` | ||
becomes | ||
```ts | ||
declare class C { | ||
readonly x: number; | ||
} | ||
``` | ||
#### Semantics | ||
The properties emitted downlevel can be overridden in more cases than | ||
the original accessors, so the downlevel d.ts will be less strict. See | ||
[the Typescript 3.7 release | ||
notes](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#the-usedefineforclassfields-flag-and-the-declare-property-modifier) | ||
for more detail. | ||
### `asserts` assertion guards (3.7) | ||
Typescript 3.7 introduced the `asserts` keyword, which provides a way to indicate that a function will throw if a parameter doesn't meet a condition. | ||
This allows Typescript to understand that whatever condition such a function checks must be true for the remainder of the containing scope. | ||
Since there is no way to model this before 3.7, such functions are downlevelled to return `void`: | ||
```ts | ||
declare function assertIsString(val: any, msg?: string): asserts val is string; | ||
declare function assert(val: any, msg?: string): asserts val; | ||
``` | ||
becomes | ||
```ts | ||
declare function assertIsString(val: any, msg?: string): void; | ||
declare function assert(val: any, msg?: string): void; | ||
``` | ||
### Type-only import/export (3.8) | ||
The downlevel emit is quite simple: | ||
```ts | ||
import type { T } from 'x'; | ||
``` | ||
becomes | ||
```ts | ||
import { T } from "x"; | ||
``` | ||
#### Semantics | ||
The downlevel d.ts will be less strict because a class will be | ||
constructable: | ||
```ts | ||
declare class C { | ||
} | ||
export type { C }; | ||
``` | ||
becomes | ||
```ts | ||
declare class C {} | ||
export { C }; | ||
``` | ||
and the latter allows construction: | ||
```ts | ||
import { C } from "x"; | ||
var c = new C(); | ||
``` | ||
### `#private` (3.8) | ||
Typescript 3.8 supports the new ECMAScript-standard #private properties in | ||
addition to its compile-time-only private properties. Since neither | ||
are accessible at compile-time, downlevel-dts converts #private | ||
properties to compile-time private properties: | ||
```ts | ||
declare class C { | ||
#private | ||
} | ||
``` | ||
It becomes: | ||
```ts | ||
declare class C { | ||
private "#private"` | ||
} | ||
``` | ||
#### Semantics | ||
The standard emit for _any_ class with a #private property just adds a | ||
single `#private` line. Similarly, a class with a private property | ||
adds only the name of the property, but not the type. The d.ts | ||
includes only enough information for consumers to avoid interfering | ||
with the private property: | ||
```ts | ||
class C { | ||
#x = 1 | ||
private y = 2 | ||
} | ||
``` | ||
emits | ||
```ts | ||
declare class C { | ||
#private | ||
private y | ||
} | ||
``` | ||
which then downlevels to | ||
```ts | ||
declare class C { | ||
private "#private"; | ||
private y; | ||
} | ||
``` | ||
This is incorrect if your class already has a field named `"#private"`. | ||
But you really shouldn't do this! | ||
The downlevel d.ts incorrectly prevents consumers from creating a | ||
private property themselves named `"#private"`. The consumers of the | ||
d.ts **also** shouldn't do this. | ||
### `export * from 'x'` (3.8) | ||
Typescript 3.8 supports the new ECMAScript-standard `export * as namespace` syntax, which is just syntactic sugar for two import/export | ||
statements: | ||
```ts | ||
export * as ns from 'x'; | ||
``` | ||
becomes | ||
```ts | ||
import * as ns_1 from "x"; | ||
export { ns_1 as ns }; | ||
``` | ||
#### Semantics | ||
The downlevel semantics should be exactly the same as the original. | ||
## Target | ||
Since the earliest downlevel feature is from Typescript 3.5, | ||
downlevel-dts targets Typescript 3.4. In the future the downlevel | ||
target may be configurable as Typescript 3.4 becomes less used. | ||
Currently, Typescript 3.0 features like `unknown` are not | ||
downlevelled, nor are there any other plans to support Typescript 2.x. | ||
### Downlevel semantics | ||
## Usage | ||
@@ -9,3 +231,3 @@ | ||
"typesVersions": { | ||
"<=3.4.0-0": { "*": ["ts3.4/*"] } | ||
"<3.8": { "*": ["ts3.4/*"] } | ||
} | ||
@@ -12,0 +234,0 @@ ``` |
@@ -35,1 +35,4 @@ /// <reference types="node" /> | ||
} | ||
declare function guardIsString(val: any): val is string; | ||
declare function assertIsString(val: any, msg?: string): asserts val is string; | ||
declare function assert(val: any, msg?: string): asserts val; |
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
No website
QualityPackage does not have a website.
Found 1 instance in 1 package
17734
351
1
238