From b811012c092c7ff0dd9a5cba7b19665c65bc404a Mon Sep 17 00:00:00 2001
From: Nathan Shively-Sanders <293473+sandersn@users.noreply.github.com>
Date: Tue, 18 Feb 2020 11:12:21 -0800
Subject: [PATCH] add downlevel semantics to README (#25)

---
 README.md | 93 ++++++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 85 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index ebb403a..897c573 100644
--- a/README.md
+++ b/README.md
@@ -37,6 +37,10 @@ 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
@@ -58,11 +62,17 @@ declare class C {
 }
 ```
 
+#### 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.
+
 ### Type-only import/export (3.8)
 
-Typescript 3.8 supports type-only imports, but they are stricter than
-Typescript's original imports, which let you import types or values.
-So the downlevel emit is quite simple:
+The downlevel emit is quite simple:
 
 ```ts
 import type { T } from 'x';
@@ -74,6 +84,31 @@ becomes
 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
@@ -87,7 +122,6 @@ declare class C {
 }
 ```
 
-(This is the standard emit for _any_ class with a #private property.)
 It becomes:
 
 ```ts
@@ -96,9 +130,46 @@ declare class C {
 }
 ```
 
+#### 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
@@ -115,14 +186,20 @@ import * as ns_1 from "x";
 export { ns_1 as ns };
 ```
 
+#### Semantics
+
+The downlevel semantics should be exactly the same as the original.
+
 ## Target
 
-All told, that means that downlevel-dts targets Typescript 3.4. In the
-future the downlevel target may be configurable as Typescript 3.4
-becomes less used.
+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 plans to support Typescript 2.x.
+downlevelled, nor are there any other plans to support Typescript 2.x.
+
+### Downlevel semantics
 
 ## Usage