Merge branch 'main' into knutkj/traceur-readme-link/1

.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: Build
+
+on:
+  push:
+    branches: [ "main", "release-*" ]
+  pull_request:
+    branches: [ "main", "release-*" ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [10.x]
+
+    steps:
+    - uses: actions/checkout@v3
+
+    - name: Use Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v3
+      with:
+        node-version: ${{ matrix.node-version }}
+
+    - name: Build
+      run: |
+        npm install
+        gulp

.gitignore

@@ -1,4 +1,10 @@
 .vscode/
 node_modules/
 test/**/*.js
-test/**/*.js.map
+test/**/*.js.map
+index.d.mts
+no-conflict.d.mts
+*.js
+*.js.map
+*.mjs
+*.mjs.map

.npmignore

@@ -1,14 +1,20 @@
 .vscode
 node_modules
 out
+docs
 spec
 temp
 test
 typings
 bower.json
 gulpfile.js
+globals.d.ts
 Reflect.ts
 Reflect.js.map
+ReflectLite.ts
+ReflectLite.js.map
+ReflectNoConflict.ts
+ReflectNoConflict.js.map
 spec.html
 tsconfig.json
 tsconfig-release.json

README.md

@@ -1,5 +1,11 @@
 # Metadata Reflection API
 
+NOTE: Now that both [Decorators](https://github.com/tc39/proposal-decorators) and 
+[Decorator Metadata](https://github.com/tc39/proposal-decorator-metadata) have achieved Stage 3 within TC39, the API
+proposed below is no longer being considered for standardization. However, this package will continue to support
+projects that leverage TypeScript's legacy `--experimentalDecorators` option as some projects may not be able to migrate
+to use standard decorators.
+
 * [Detailed proposal][metadata-spec]
 
 ## Installation
@@ -8,6 +14,53 @@
 npm install reflect-metadata
 ```
 
+## Usage
+
+### ES Modules in NodeJS/Browser, TypeScript/Babel, Bundlers
+```ts
+// - Modifies global `Reflect` object (or defines one in ES5 runtimes).
+// - Supports ESM and CommonJS.
+// - Contains internal polyfills for `Map`, `Set`, and `WeakMap` for older runtimes.
+import "reflect-metadata";
+
+// - Modifies global `Reflect` object (or defines one in ES5 runtimes).
+// - Supports ESM and CommonJS.
+// - Requires runtime support for `"exports"` in `package.json`.
+// - Does not include internal polyfills.
+import "reflect-metadata/lite";
+```
+
+### CommonJS
+```ts
+// - Modifies global `Reflect` object (or defines one in ES5 runtimes).
+// - Contains internal polyfills for `Map`, `Set`, and `WeakMap` for older runtimes.
+require("reflect-metadata");
+
+// - Modifies global `Reflect` object (or defines one in ES5 runtimes).
+// - Requires runtime support for `"exports"` in `package.json`.
+// - Does not include internal polyfills.
+require("reflect-metadata/lite");
+```
+
+### In the Browser via `<script>`
+**HTML**
+```html
+<!-- Modifies global `Reflect` object (or defines one in ES5 runtimes). -->
+<!-- Contains internal polyfills for `Map`, `Set`, and `WeakMap` for older runtimes. -->
+<script src="path/to/reflect-metadata/Reflect.js"></script>
+
+<!-- Modifies global `Reflect` object (or defines one in ES5 runtimes). -->
+<!-- Does not include internal polyfills. -->
+<script src="path/to/reflect-metadata/ReflectLite.js"></script>
+```
+
+**Script**
+```js
+// - Makes types available in your editor.
+/// <reference path="path/to/reflect-metadata/standalone.d.ts" />
+
+```
+
 ## Background
 
 * Decorators add the ability to augment a class and its members as the class is defined, through a declarative syntax.