feat: add unknown on catch

Author: unional

drafts/variables.ts

@@ -0,0 +1,9 @@
+try { throw new Error() }
+catch (e) {
+  // handle error
+}
+
+try { throw new Error() }
+catch (e: any) {
+  // handle error
+}

examples/unknown/standard/catch-clauses.bad.ts

@@ -0,0 +1,6 @@
+try { throw new Error() }
+catch (e: unknown) {
+  if (e instanceof Error) {
+    console.error(e.message)
+  }
+}

examples/unknown/standard/catch-clauses.good.ts

@@ -0,0 +1,14 @@
+import { checkUnknown } from 'type-plus'
+class ErrorA extends Error { }
+class ErrorB extends Error { }
+
+try { throw new ErrorA() }
+catch (e: unknown) {
+  if (checkUnknown(e, ErrorA)) {
+    // handle ErrorA
+  } else if (checkUnknown(e, ErrorB)) {
+    // handle ErrorB
+  } else {
+    // handle generic Error
+  }
+}

examples/unknown/standard/catch-clauses.type-plus.good.ts

@@ -0,0 +1,6 @@
+function castNumber(value: unknown) {
+  return typeof value === 'number' ? value : -1
+}
+
+castNumber(1) // 1
+castNumber({ a: 1 }) // -1

examples/unknown/standard/function-param.ts

@@ -0,0 +1,10 @@
+{
+  "compilerOptions": {
+    "composite": true,
+    "esModuleInterop": true,
+    "moduleResolution": "node",
+    "outDir": "out",
+    "target": "ESNext",
+    "strict": true
+  }
+}

examples/unknown/standard/tsconfig.json

@@ -45,7 +45,7 @@
     "semantic-release": "^17.0.4",
     "standard-version": "^7.1.0",
     "ts-node": "^8.8.1",
-    "type-plus": "^1.35.1",
+    "type-plus": "^2.2.0",
     "typescript": "^4.0.2"
   },
   "remarkConfig": {

package.json

@@ -8,7 +8,7 @@ TypeScript 4.0 has landed on Augest 20th, 2020.
 - [Labeled Tuple](/pages/04-typescript-syntax/tuple-type.md#labeled-tuple-elements)
 - Class Property Inference from Constructors
 - Short-Circuting Assignement Operators
-- unknown on catch clauses
+- [`unknown` on `catch` clauses](/pages/04-typescript-syntax/unknown.md#unknown-on-catch-clauses)
 - Custom JSX Factories
 
 ## TypeScript 3.9

pages/00-updates/README.md

@@ -0,0 +1,27 @@
+# any
+
+You **should** avoid asserting type as `any`.
+
+> Why?
+
+`as any` is a very powerful statement telling the compiler to turn off type checking.
+
+> Why not?
+
+There are times that the compiler cannot infer the type correctly,
+or the type is specified by other libraries and is incorrect,
+or the type is too complicate to create and does not worth the effort to fix.
+
+For these cases, it is okey to use `as any`.
+Make sure you make this decision consciously.
+
+---
+
+You **should** avoid annotating method parameters and callbacks as `any`.
+
+> Why?
+
+Annotating function parameters and callbacks as `any` has similar effect as asserting them as `any`.
+
+The compiler might able to infer the type for you through inheritence or function type declaration.
+Annotating parameter as `any` overrides that and you loose all benefits of using TypeScript.

pages/04-typescript-syntax/any.md

@@ -1,101 +1,8 @@
 # Basic Types
 
-## any
-
-You **should** avoid asserting type as `any`.
-
-> Why?
-
-`as any` is a very powerful statement telling the compiler to turn off type checking.
-
-> Why not?
-
-There are times that the compiler cannot infer the type correctly,
-or the type is specified by other libraries and is incorrect,
-or the type is too complicate to create and does not worth the effort to fix.
-
-For these cases, it is okey to use `as any`.
-Make sure you make this decision consciously.
-
----
-
-You **should** avoid annotating method parameters and callbacks as `any`.
-
-> Why?
-
-Annotating function parameters and callbacks as `any` has similar effect as asserting them as `any`.
-
-The compiler might able to infer the type for you through inheritence or function type declaration.
-Annotating parameter as `any` overrides that and you loose all benefits of using TypeScript.
-
----
-
-You **may** use `as unknown`.
-
-### References
-
-- <https://github.com/Microsoft/TypeScript/pull/24439>
-- <https://mariusschulz.com/blog/the-unknown-type-in-typescript>
-
-## enum
-
-> Enums allow us to define a set of named constants.
-
-- <https://www.typescriptlang.org/docs/handbook/enums.html>
-- <https://www.typescriptlang.org/docs/handbook/basic-types.html#enum>
-
-There are a few special rules about `enum` type:
-
-- values can be either `string` or `number`
-
-```ts
-enum map { a = 1, b = 'b' }
-}
-```
-
-- it is nominal typed
-
-```ts
-enum JapanVocaloid { miku, luka }
-
-enum ChinaVocaloid { miku, LuoTianyi, XingChen }
-
-let myFavoriteVocaloid = ChinaVocaloid.miku
-
-// error
-myFavoriteVocaloid = JapanVocaloid.miku
-```
-
----
-
-You **should avoid** using `enum`. You **should** use `const` instead.
-
-```ts
-// bad
-enum Color { Red, Green, Blue }
-
-// good
-const COLOR = {
-  Red: 0,
-  Green: 1,
-  Blue: 2
-} as const
-
-// good
-const COLOR_RED = 0
-const COLOR_GREEN = 1
-const COLOR_BLUE = 2
-```
-
-> Why?
-
-While `enum` is more compact,
-and provide additional nominal protection,
-it is a TypeScript syntax.
-It goes against our design principles.
-
-The transpiled code can be different depends on the config options,
-and it can get confusing as it may get erased (`const enum`).
+- [`any`](./any.md)
+- [`unknown`](./unknown.md)
+- [`enum`](./enum.md)
 
 ## References
 

pages/04-typescript-syntax/basic-types.md

@@ -0,0 +1,58 @@
+# enum
+
+> Enums allow us to define a set of named constants.
+
+- <https://www.typescriptlang.org/docs/handbook/enums.html>
+- <https://www.typescriptlang.org/docs/handbook/basic-types.html#enum>
+
+There are a few special rules about `enum` type:
+
+- values can be either `string` or `number`
+
+```ts
+enum map { a = 1, b = 'b' }
+```
+
+- it is nominal typed
+
+```ts
+enum JapanVocaloid { miku, luka }
+
+enum ChinaVocaloid { miku, LuoTianyi, XingChen }
+
+let myFavoriteVocaloid = ChinaVocaloid.miku
+
+// error
+myFavoriteVocaloid = JapanVocaloid.miku
+```
+
+---
+
+You **should avoid** using `enum`. You **should** use `const` instead.
+
+```ts
+// bad
+enum Color { Red, Green, Blue }
+
+// good
+const COLOR = {
+  Red: 0,
+  Green: 1,
+  Blue: 2
+} as const
+
+// good
+const COLOR_RED = 0
+const COLOR_GREEN = 1
+const COLOR_BLUE = 2
+```
+
+> Why?
+
+While `enum` is more compact,
+and provide additional nominal protection,
+it is a TypeScript syntax.
+It goes against our design principles.
+
+The transpiled code can be different depends on the config options,
+and it can get confusing as it may get erased (`const enum`).

pages/04-typescript-syntax/enum.md

@@ -0,0 +1,82 @@
+# unknown
+
+Introduced in: TypeScript 3.0
+
+The `unknown` type is a top type in the TypeScript type system.
+
+In essence, use it to describe values that you do not know the type (hence `unknown`).
+It ensures you performing type checks before using the values.
+
+## `unknown` on `catch` clauses
+
+Introduced in TypeScript 4.0
+
+Before TypeScript 4.0, the variable in the `catch` clause is always `any` and cannot be typed explicitly.
+In TypeScript 4.0 it can now be typed as either `any` or `unknown`.
+
+You **must** type the variable in the `catch` clause as `unknown`.
+
+❌bad
+
+```ts file=../../examples/unknown/standard/catch-clauses.bad.ts
+try { throw new Error() }
+catch (e) {
+  // handle error
+}
+
+try { throw new Error() }
+catch (e: any) {
+  // handle error
+}
+```
+
+✔️ good
+
+```ts file=../../examples/unknown/standard/catch-clauses.good.ts
+try { throw new Error() }
+catch (e: unknown) {
+  if (e instanceof Error) {
+    console.error(e.message)
+  }
+}
+```
+
+✔️ good
+
+```ts file=../../examples/unknown/standard/catch-clauses.type-plus.good.ts
+import { checkUnknown } from 'type-plus'
+class ErrorA extends Error { }
+class ErrorB extends Error { }
+
+try { throw new ErrorA() }
+catch (e: unknown) {
+  if (checkUnknown(e, ErrorA)) {
+    // handle ErrorA
+  } else if (checkUnknown(e, ErrorB)) {
+    // handle ErrorB
+  } else {
+    // handle generic Error
+  }
+}
+```
+
+> Why?
+
+The `unknown` type is a better type to use in the `catch` clause than `any`.
+
+TypeScript only allows you to type the variable as `any` or `unknown` in the `catch` clause.
+This is because the `try` clause can make function calls
+and there is no way to control or know what kind of error (or non-error) those functions could throw.
+
+That's why when handling error you should not assume the type would be `Error` or an explicit list that you expect.
+And `unknown` is a better type than `any` to help enforcing this fact.
+
+### Additional Readings
+
+- <https://devblogs.microsoft.com/typescript/announcing-typescript-4-0/#unknown-on-catch>
+
+## Additional Readings
+
+- <https://github.com/Microsoft/TypeScript/pull/24439>
+- <https://mariusschulz.com/blog/the-unknown-type-in-typescript>
+- <https://blog.logrocket.com/when-to-use-never-and-unknown-in-typescript-5e4d6c5799ad/>

pages/04-typescript-syntax/unknown.md

@@ -1,6 +1,7 @@
 {
   "compilerOptions": {
-    "esModuleInterop": true
+    "esModuleInterop": true,
+    "moduleResolution": "node"
   },
   "files": [],
   "references": [
@@ -10,6 +11,9 @@
     {
       "path": "examples/property-accessor/standard"
     },
+    {
+      "path": "examples/unknown/standard"
+    },
     {
       "path": "examples/tuple/standard"
     }

tsconfig.json

@@ -5685,10 +5685,10 @@ type-fest@^0.8.1:
   resolved "https://registry.yarnpkg.com/type-fest/-/type-fest-0.8.1.tgz#09e249ebde851d3b1e48d27c105444667f17b83d"
   integrity sha512-4dbzIzqvjtgiM5rw1k5rEHtBANKmdudhGyBEajN01fEyhaAIhsoKNy6y7+IN93IfpFtwY9iqi7kD+xwKhQsNJA==
 
-type-plus@^1.35.1:
-  version "1.35.1"
-  resolved "https://registry.yarnpkg.com/type-plus/-/type-plus-1.35.1.tgz#15e39a0922fdf08d8d24cc7d1a5d50d3273434de"
-  integrity sha512-El1yp4aLFVpOwU/emJRxqw7+OsA8gUWILnrS8Ln5rafvHSG5tHopvmQLIBPdkFfRk65ZBcipVlk3XcfkL36jng==
+type-plus@^2.2.0:
+  version "2.2.0"
+  resolved "https://registry.yarnpkg.com/type-plus/-/type-plus-2.2.0.tgz#7d76d01e73ac995e6776b9a94b7e0bc3773e20d5"
+  integrity sha512-dXjp7T85ZjJRCrZxGzBhAGe9anclXyIMGNBqav5pBNVZcPjBhNP/jWxy4t5oStIFGLSmnTJOv6JqiyVQaStkKA==
   dependencies:
     unpartial "^0.6.3"