├── .npmrc ├── .gitattributes ├── .github └── workflows │ └── build.yml ├── package.json ├── spec.emu ├── .gitignore ├── LICENSE ├── README.md └── index.html /.npmrc: -------------------------------------------------------------------------------- 1 | package-lock=false 2 | -------------------------------------------------------------------------------- /.gitattributes: -------------------------------------------------------------------------------- 1 | index.html -diff merge=ours 2 | spec.js -diff merge=ours 3 | spec.css -diff merge=ours 4 | -------------------------------------------------------------------------------- /.github/workflows/build.yml: -------------------------------------------------------------------------------- 1 | name: Deploy spec 2 | 3 | on: [push] 4 | 5 | jobs: 6 | build: 7 | runs-on: ubuntu-latest 8 | 9 | steps: 10 | - uses: actions/checkout@v2 11 | - uses: actions/setup-node@v1 12 | with: 13 | node-version: '12.x' 14 | - run: npm install 15 | - run: npm run build 16 | - name: commit changes 17 | uses: elstudio/actions-js-build/commit@v3 18 | with: 19 | commitMessage: "fixup: [spec] `npm run build`" 20 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "private": true, 3 | "name": "decorator-metadata", 4 | "description": "Decorator Metadata proposal", 5 | "scripts": { 6 | "start": "npm run build-loose -- --watch", 7 | "build": "npm run build-loose -- --strict", 8 | "build-loose": "ecmarkup --load-biblio @tc39/ecma262-biblio --verbose spec.emu index.html --lint-spec" 9 | }, 10 | "homepage": "https://github.com/tc39/proposal-decorator-metadata#readme", 11 | "repository": { 12 | "type": "git", 13 | "url": "git+https://github.com/tc39/proposal-decorator-metadata.git" 14 | }, 15 | "license": "MIT", 16 | "devDependencies": { 17 | "@tc39/ecma262-biblio": "^2.0.2290", 18 | "ecmarkup": "^12.0.2" 19 | } 20 | } 21 | -------------------------------------------------------------------------------- /spec.emu: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 
 7 | title: Proposal Title Goes Here
 8 | stage: -1
 9 | contributors: Your Name(s) Here
10 |
11 | 12 | 13 |

This is an emu-clause

14 |

This is an algorithm:

15 | 16 | 1. Let _proposal_ be *undefined*. 17 | 1. If IsAccepted(_proposal_), then 18 | 1. Let _stage_ be *0*ℤ. 19 | 1. Else, 20 | 1. Let _stage_ be *-1*ℤ. 21 | 1. Return ? ToString(_proposal_). 22 | 23 | 24 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # Logs 2 | logs 3 | *.log 4 | npm-debug.log* 5 | 6 | # Runtime data 7 | pids 8 | *.pid 9 | *.seed 10 | 11 | # Directory for instrumented libs generated by jscoverage/JSCover 12 | lib-cov 13 | 14 | # Coverage directory used by tools like istanbul 15 | coverage 16 | 17 | # nyc test coverage 18 | .nyc_output 19 | 20 | # Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files) 21 | .grunt 22 | 23 | # node-waf configuration 24 | .lock-wscript 25 | 26 | # Compiled binary addons (http://nodejs.org/api/addons.html) 27 | build/Release 28 | 29 | # Dependency directories 30 | node_modules 31 | jspm_packages 32 | 33 | # Optional npm cache directory 34 | .npm 35 | 36 | # Optional REPL history 37 | .node_repl_history 38 | 39 | # Only apps should have lockfiles 40 | yarn.lock 41 | package-lock.json 42 | npm-shrinkwrap.json 43 | pnpm-lock.yaml 44 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2017 ECMA TC39 and contributors 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Decorator Metadata 4 | 5 | **Stage**: 3 6 | 7 | **Spec Text**: https://github.com/pzuraq/ecma262/pull/10 8 | 9 | This proposal seeks to extend the [Decorators](https://github.com/tc39/proposal-decorators) 10 | proposal by adding the ability for decorators to associate _metadata_ with the 11 | value being decorated. 12 | 13 | ## Overview 14 | 15 | Decorators are functions that allow users to metaprogram by wrapping and 16 | replacing existing values. This allows them to solve a number of use cases quite 17 | well, such as memoization, reactivity, method binding, and more. However, there 18 | are a number of use cases which require code _external_ to the decorator and 19 | decorated class to be able to introspect and understand what decorations were 20 | applied, including: 21 | 22 | - Validation 23 | - Serialization 24 | - Web component definition 25 | - Dependency injection 26 | - Declarative routing/application structure 27 | - ...and more 28 | 29 | In previous iterations of the decorators proposal, all decorators had access to 30 | the class prototype, allowing them to associate metadata directly via a 31 | `WeakMap` by using the class as a key. This is no longer possible in the most 32 | recent version, however, as decorators only have access to the value they are 33 | _directly_ decorating (e.g. method decorators have access to the method, field 34 | decorators have access to the field, etc). 35 | 36 | This proposal extends decorators by providing a metadata _object_, which can be 37 | used either to directly store metadata, or as a WeakMap key. This object is 38 | provided via the decorator's context argument, and is then accessible via the 39 | `Symbol.metadata` property on the class definition after decoration. 40 | 41 | ## Detailed Design 42 | 43 | The overall decorator signature will be updated to the following: 44 | 45 | ```ts 46 | type Decorator = (value: Input, context: { 47 | kind: string; 48 | name: string | symbol; 49 | access: { 50 | get?(): unknown; 51 | set?(value: unknown): void; 52 | }; 53 | isPrivate?: boolean; 54 | isStatic?: boolean; 55 | addInitializer?(initializer: () => void): void; 56 | + metadata?: Record; 57 | }) => Output | void; 58 | ``` 59 | 60 | The new `metadata` property is a plain JavaScript object. The same object is 61 | passed to every decorator applied to a class or any of its elements. After the 62 | class has been fully defined, it is assigned to the `Symbol.metadata` property 63 | of the class. 64 | 65 | An example usage might look like: 66 | 67 | ```js 68 | function meta(key, value) { 69 | return (_, context) => { 70 | context.metadata[key] = value; 71 | }; 72 | } 73 | 74 | @meta('a', 'x') 75 | class C { 76 | @meta('b', 'y') 77 | m() {} 78 | } 79 | 80 | C[Symbol.metadata].a; // 'x' 81 | C[Symbol.metadata].b; // 'y' 82 | ``` 83 | 84 | ### Inheritance 85 | 86 | If the decorated class has a parent class, then the prototype of the `metadata` 87 | object is set to the metadata object of the superclass. This allows metadata to 88 | be inherited in a natural way, taking advantage of shadowing by default, 89 | mirroring class inheritance. For example: 90 | 91 | ```js 92 | function meta(key, value) { 93 | return (_, context) => { 94 | context.metadata[key] = value; 95 | }; 96 | } 97 | 98 | @meta('a', 'x') 99 | class C { 100 | @meta('b', 'y') 101 | m() {} 102 | } 103 | 104 | C[Symbol.metadata].a; // 'x' 105 | C[Symbol.metadata].b; // 'y' 106 | 107 | class D extends C { 108 | @meta('b', 'z') 109 | m() {} 110 | } 111 | 112 | D[Symbol.metadata].a; // 'x' 113 | D[Symbol.metadata].b; // 'z' 114 | ``` 115 | 116 | In addition, metadata from the parent can be read during decoration, so it can 117 | be modified or extended by children rather than overriding it. 118 | 119 | ```ts 120 | function appendMeta(key, value) { 121 | return (_, context) => { 122 | // NOTE: be sure to copy, not mutate 123 | const existing = context.metadata[key] ?? []; 124 | context.metadata[key] = [...existing, value]; 125 | }; 126 | } 127 | 128 | @appendMeta('a', 'x') 129 | class C {} 130 | 131 | @appendMeta('a', 'z') 132 | class D extends C {} 133 | 134 | C[Symbol.metadata].a; // ['x'] 135 | D[Symbol.metadata].a; // ['x', 'z'] 136 | ``` 137 | 138 | ### Private Metadata 139 | 140 | In addition to public metadata placed directly on the metadata object, the 141 | object can be used as a key in a `WeakMap` if the decorator author does not want 142 | to share their metadata. 143 | 144 | ```ts 145 | const PRIVATE_METADATA = new WeakMap(); 146 | 147 | function meta(key, value) { 148 | return (_, context) => { 149 | let metadata = PRIVATE_METADATA.get(context.metadata); 150 | 151 | if (!metadata) { 152 | metadata = {}; 153 | PRIVATE_METADATA.set(context.metadata, metadata); 154 | } 155 | 156 | metadata[key] = value; 157 | }; 158 | } 159 | 160 | @meta('a', 'x') 161 | class C { 162 | @meta('b', 'y') 163 | m() {} 164 | } 165 | 166 | PRIVATE_METADATA.get(C[Symbol.metadata]).a; // 'x' 167 | PRIVATE_METADATA.get(C[Symbol.metadata]).b; // 'y' 168 | ``` 169 | -------------------------------------------------------------------------------- /index.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | Proposal Title Goes Here
2519 |

Stage -1 Draft / January 17, 2024

Proposal Title Goes Here

2528 | 2529 | 2530 |

1 This is an emu-clause

2531 |

This is an algorithm:

2532 |
  1. Let proposal be undefined.
  2. If IsAccepted(proposal), then
    1. Let stage be 0ℤ.
  3. Else,
    1. Let stage be -1ℤ.
  4. Return ? ToString(proposal).
 2533 | 2534 |

A Copyright & Software License

2535 | 2536 |

Copyright Notice

2537 |

© 2024 Your Name(s) Here

2538 | 2539 |

Software License

2540 |

All Software contained in this document ("Software") is protected by copyright and is being made available under the "BSD License", included below. This Software may be subject to third party rights (rights from parties other than Ecma International), including patent rights, and no licenses under such third party rights are granted under this license even if the third party concerned is a member of Ecma International. SEE THE ECMA CODE OF CONDUCT IN PATENT MATTERS AVAILABLE AT https://ecma-international.org/memento/codeofconduct.htm FOR INFORMATION REGARDING THE LICENSING OF PATENT CLAIMS THAT ARE REQUIRED TO IMPLEMENT ECMA INTERNATIONAL STANDARDS.

2541 | 2542 |

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

2543 | 2544 |
    2545 |
  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
    2. 2546 |
  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
    3. 2547 |
  3. Neither the name of the authors nor Ecma International may be used to endorse or promote products derived from this software without specific prior written permission.
    4. 2548 |
2549 | 2550 |

THIS SOFTWARE IS PROVIDED BY THE ECMA INTERNATIONAL "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL ECMA INTERNATIONAL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

2551 | 2552 | 2553 |
--------------------------------------------------------------------------------