Document const enum pitfalls and workarounds

Author: jablko

packages/documentation/copy/en/reference/Enums.md

@@ -365,6 +365,31 @@ let directions = [
 ];
 ```
 
+#### Const enum pitfalls
+
+Inlining const enum values is straightforward at first, but comes with subtle implications.
+These pitfalls pertain to _ambient_ const enums only (basically const enums in `.d.ts` files) and sharing const enums between projects, but because `tsc --declaration` transforms `.ts` files into `.d.ts` files, if you are publishing or consuming `.d.ts` files, these pitfalls likely apply to you.
+
+1. For the reasons laid out in the [`isolatedModules` documentation](/tsconfig#references-to-const-enum-members), that mode is fundamentally incompatible with ambient const enums.
+   This means if you publish ambient const enums, downstream consumers will not be able to use [`isolatedModules`](/tsconfig#isolatedModules) and those values at the same time.
+2. You can easily inline values from version A of a dependency at compile time, and import version B at runtime.
+   Version A and B's enums can have different values, if you are not very careful, resulting in [surprising bugs](https://github.com/microsoft/TypeScript/issues/5219#issue-110947903), like taking the wrong branches of `if` statements.
+   These bugs are especially pernicious because it is common to build and run automated tests at the same time, with the same dependency versions, which does not exercise them at all.
+3. [`importsNotUsedAsValues: "preserve"`](/tsconfig#importsNotUsedAsValues) will not elide imports for const enums used as values, but ambient const enums do not guarantee that runtime `.js` files exist, and the unresolvable import will cause an error at runtime.
+   The usual way to unambiguously elide imports, [type-only imports](/docs/handbook/modules.html#importing-types), [does not allow const enum values](https://github.com/microsoft/TypeScript/issues/40344), currently.
+
+Here are two approaches to avoiding these pitfalls:
+
+A. Do not use const enums entirely.
+   You can easily [ban const enums](https://github.com/typescript-eslint/typescript-eslint/blob/master/docs/getting-started/linting/FAQ.md#how-can-i-ban-specific-language-feature) with the help of a linter.
+   Obviously this avoids any issues with const enums, but prevents your project from inlining its own enum values.
+   Inlining a project's own enum values is not problematic and has performance implications.
+B. Do not publish ambient const enums, by deconstifying them with the help of [`preserveConstEnums`](/tsconfig#preserveConstEnums).
+   This is the approach taken internally by the [TypeScript project itself](https://github.com/microsoft/TypeScript/pull/5422).
+   [`preserveConstEnums`](/tsconfig#preserveConstEnums) emits the same JavaScript for const enums as plain enums, and you can then safely strip the `const` modifier from `.d.ts` files [in a build step](https://github.com/microsoft/TypeScript/blob/1a981d1df1810c868a66b3828497f049a944951c/Gulpfile.js#L144).
+
+   This way downstream consumers will not inline enum values from your project, which avoids the pitfalls above, but a project can still inline its own const enum values, unlike in the first approach.
+
 ## Ambient enums
 
 Ambient enums are used to describe the shape of already existing enum types.