├── .gitattributes ├── .gitignore ├── .npmrc ├── LICENSE ├── README.md ├── index.html ├── package.json └── spec.emu /.gitattributes: -------------------------------------------------------------------------------- 1 | index.html -diff merge=ours 2 | spec.js -diff merge=ours 3 | spec.css -diff merge=ours 4 | -------------------------------------------------------------------------------- /.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 | -------------------------------------------------------------------------------- /.npmrc: -------------------------------------------------------------------------------- 1 | package-lock=false 2 | -------------------------------------------------------------------------------- /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 | # Maximally Minimal Mixins 2 | @justinfagnani 3 | 4 | Last Updated: 2018-01-26 5 | 6 | Status: Stage 1 7 | 8 | [View TC39 Slides](https://docs.google.com/presentation/d/e/2PACX-1vSg1tyW2ALwSGR83qcKRQ4__T36CzvwOoPP9ywPpjuFxljmDaBHqKPAY6UFuLor4GHgxuB8WYj3OoIL/pub?start=false&loop=false&delayms=3000) 9 | 10 | ## Overlap with First-Class Protocols Proposal 11 | 12 | This proposal and the [First-Class Protocols Proposal](https://github.com/michaelficarra/proposal-first-class-protocols) overlap in some of the 13 | problem and solution space that they cover. At the January 2018 meeting of TC39 it was agreed 14 | to let both be at Stage 1 with the intention to work together to identify the common problems 15 | they target and possibly a unified proposal. 16 | 17 | ## Goals 18 | 19 | * Pave existing cowpath of the subclass factory pattern with a declarative syntax 20 | * Enable static analysis of mixins and mixin applications 21 | * Make mixin inheritance more attractive than it is now, to be an easy-to-use alternative to subclass inheritance 22 | * Orthogonality to classes - class features naturally apply to mixins 23 | * Provide space to evolve with protocol/trait-like features 24 | * Avoid problems with makeMethod, non-linear prototype chains, etc 25 | 26 | ## Subclass Factory Pattern 27 | 28 | JavaScript arguably already has mixins, made possible by class expressions and extends expressions. 29 | 30 | ```js 31 | let M = (base) => class extends base { 32 | field = 'abc'; 33 | 34 | constructor() { 35 | super(); 36 | // ... 37 | } 38 | 39 | method() { 40 | super.method(); 41 | // ... 42 | } 43 | } 44 | class S {} 45 | class C extends M(S) {} 46 | ``` 47 | 48 | Details and the benefits of this pattern are explained in this 2015 blog post: http://justinfagnani.com/2015/12/21/real-mixins-with-javascript-classes/ 49 | 50 | ## Syntax Sugar for Subclass Factories 51 | 52 | Maximally minimal mixins is simple syntax that de-sugars the following to the above: 53 | 54 | ```js 55 | mixin M { 56 | field = 'abc'; 57 | 58 | constructor() { 59 | super(); 60 | // ... 61 | } 62 | 63 | method() { 64 | super.method(); 65 | // ... 66 | } 67 | } 68 | class S {} 69 | class C extends S with M {} 70 | ``` 71 | 72 | These mixins are strictly less powerful than imperative subclass factories. For instance, there's no way to imperatively mutate the prototype of the subclass, no way to do mixin composition, etc. These abilities are reserved for future evolution. 73 | 74 | ## Why? 75 | 76 | If declarative mixins are just less-powerful sugar for a pattern that's already possible, the obvious question is: why add them at all? 77 | 78 | ### Enable Static Analysis 79 | 80 | Possibly the most immediate benefit of a declarative syntax is improved toolability. The current mixin pattern is so imperative that it's very difficult for static analysis to recognize and properly understand the pattern. 81 | 82 | Typed-variants of JavaScript, like Closure and TypeScript, have recently added support for the imperative pattern, but it's extremely fragile and cumbersome in both. See the Appendix below for examples of how code needs to be structured to satisfy various tools. 83 | 84 | ### Improve Ergonomics 85 | 86 | Even outside of type checking, the ergonomics of declarative mixins are just better than the imperative subclass factory pattern. 87 | 88 | ### Encourage Class-Compatible Mixins 89 | 90 | Subclass factory mixins leverage classes and integrate with the language in ways that other mixin patterns don't. Because subclass factory mixins use actual class declarations/expressions, they automatically get all new features of classes such as public and private fields and decorators. 91 | 92 | Specific syntax for the pattern will encourage its use, and possibly allow platforms to ship mixins for the first time ever once they're an official part of the language. 93 | 94 | As an example, the DOM standard recently added an `EventTarget` base class that can be used to inherit the web platform's `addEventListener()` and related APIs. This is great, but has the usual problems of sharing code via subclass inheritance. With language-level mixins there's a better chance that the DOM can add an `EventTargetMixin`. 95 | 96 | ### Enable Future Improvements 97 | 98 | Like Maximally Minimal Classes, Maximally Minimal Mixins lay the foundation for further evolution. Other proposals in this space (of mixins, traits, interfaces, and protocols) have included additional features, like requirements, namespacing, aliasing, etc. These features can be added to classes and mixins, but it seems a simple starting point would help. 99 | 100 | ## Details 101 | 102 | ### Mixin Declaration 103 | 104 | A _mixin_ is conceptually an abstract subclass - a class without a known superclass at declaration time. For maximal compatibility with current JavaScript language features, we define a mixin as a subclass factory - a function from a class to a new subclass. The declaration defines the difference between the superclass and generated subclass. 105 | 106 | A mixin is declared with the new `mixin` keyword: 107 | 108 | ```js 109 | mixin Name { 110 | } 111 | ``` 112 | 113 | As with classes, `mixin` can be used in a declaration or expression. A mixin declaration or expression is syntactically similar to a class declaration or expression. It has an optional BindingIdentifier and a ClassBody. 114 | 115 | A mixin defines an arrow function (so that they cannot be constructors) with one parameter, the _superclass_. Mixins return a new subclass of the argument as if the mixin body was evaluated as a class expression with the value of argument used as _superclass_ rather than evaluating ClassHeritage as in the ClassDefinitionEvaluation runtime semantics. 116 | 117 | ### Mixin Application 118 | 119 | A mixin is used by _applying_ it to a concrete superclass with the `with` keyword. (This maybe confused with the `with` statement, so another keyword could be used) 120 | 121 | `A with M` calls the mixin function `M` with the argument `A`. This can be used in the extends clause of a class declaration: 122 | 123 | ```js 124 | class C extends A with M {} 125 | ``` 126 | 127 | Applying multiple mixins in one class declaration will be common, so we could offer special syntax for a list of mixins: 128 | 129 | ```js 130 | class C extends A with M1, M2, M3 {} 131 | ``` 132 | 133 | ### `Symbol.mixin` 134 | 135 | Like the `constructor` property, it should be possible to identify the mixin used to create a prototype. `constructor` itself is not suitable to identify the _mixin_, since it will refer to the constructor generated by the mixin application. Mixin application will set the `Symbol.mixin` property of the constructor's `prototype` to reference the mixin function. 136 | 137 | ```js 138 | mixin M {} 139 | class C extends A with M {} 140 | Object.getPrototypeOf(C).prototype.hasOwnProperty(Symbol.mixin); // true 141 | Object.getPrototypeOf(C).prototype[Symbol.mixin] === M; // true 142 | ``` 143 | 144 | ### `instanceof` 145 | 146 | `instanceof` can be defined so that it works with mixins: 147 | 148 | ```js 149 | mixin M {} 150 | class C extends Object with M {} 151 | new C() instanceof M; // true 152 | ``` 153 | 154 | ### Mixin Composition 155 | 156 | Since mixins are just functions, they naturally compose with function syntax: 157 | 158 | ```js 159 | mixin A {} 160 | mixin B {} 161 | let AB = (superclass) => A(B(superclass)); 162 | ``` 163 | 164 | Composition is commonly desired inline with declaration. We can allow mixins to have an `extends` clause like classes, but which must evaluate to a mixin: 165 | 166 | ```js 167 | mixin A extends B {} 168 | ``` 169 | 170 | ### Desugaring 171 | 172 | #### Mixin Declaration 173 | 174 | ```js 175 | mixin M { 176 | #a; 177 | b; 178 | c(); 179 | } 180 | ``` 181 | 182 | Desugars to: 183 | 184 | ```js 185 | Symbol.mixin = Symbol.mixin || Symbol('mixin'); 186 | 187 | let M = (superclass) => { 188 | const _M = class extends superclass { 189 | #a; 190 | b; 191 | c() {} 192 | } 193 | Object.defineProperty(_M.prototype, Symbol.mixin, {value: M}); 194 | return _M; 195 | }; 196 | 197 | Object.defineProperty(M, 'prototype', {}); 198 | 199 | Object.defineProperty(M, Symbol.hasInstance, { 200 | value(o) { 201 | while (o !== undefined) { 202 | if (o.hasOwnProperty(Symbol.mixin) && o[Symbol.mixin] === this) { 203 | return true; 204 | } 205 | o = Object.getPrototypeOf(o); 206 | } 207 | return false; 208 | } 209 | }); 210 | ``` 211 | 212 | #### Mixin Application 213 | 214 | ```js 215 | C with M; 216 | ``` 217 | 218 | Desugars to: 219 | 220 | ```js 221 | M(C) 222 | ``` 223 | 224 | Therefore: 225 | 226 | ```js 227 | class A extends B with M { 228 | // ... 229 | } 230 | ``` 231 | 232 | Desugars to: 233 | 234 | ```js 235 | class A extends M(B) { 236 | // ... 237 | } 238 | ``` 239 | 240 | #### Mixin Composition 241 | 242 | ```js 243 | mixin A extends B { 244 | method() {} 245 | } 246 | ``` 247 | 248 | Desugars to: 249 | 250 | ```js 251 | let A = (superclass) => class extends B(superclass) { 252 | method() {} 253 | } 254 | ``` 255 | 256 | ## Interesting Notes 257 | 258 | ### Orthogonality to Classes 259 | 260 | One of the main implications of this proposal is that mixins are mostly orthogonal to classes. Mixins are a way to declare abstract subclasses and leverage class syntax and semantics. All new declarative features of classes are automatically inherited by mixins. 261 | 262 | This orthogonality can be used in the evolution of both classes and mixins. Some parts of features discussed and/or proposed previously could be broken out and added classes, independently of mixins. 263 | 264 | ### Mixin methods are copied on application 265 | 266 | It sounds like previous discussions around sharing prototypes/methods has had to deal with the question of function identity and home objects. This proposal side-steps these questions by making a copy of methods via the evaluation of a class expression on each mixin application. 267 | 268 | This means that methods defined in mixins get fresh copies for each mixin application: 269 | 270 | ```js 271 | mixin M { 272 | method() {} 273 | } 274 | 275 | class A extends Object with M {} 276 | class B extends Object with M {} 277 | 278 | A.prototype.method === B.prototype.method; // false 279 | ``` 280 | 281 | ### Mixins are functions, but not constructors 282 | 283 | Mixins syntactically may look like classes, and users may expect them to have a `.prototype` property, but they don't. It would be useful to have access to a prototype for the mixin, but in this proposal there's no easy way to allow that - the prototype doesn't exist until application time. It's really a _potential_ prototype. 284 | 285 | To reserve space for a future feature where they is a prototype object at mixin declaration time, we could define `prototype` property of mixins as `undefined`, not-writable, not-configurable. This is shown in the desugaring of the mixin declaration above. 286 | 287 | ## Evolution 288 | 289 | Maximally Minimal Mixins aim to allow for evolution, in the same way as Maximally Minimal Classes successfully have, including adding features from many previously proposed mixin or related features. 290 | 291 | ### First-Class Protocols 292 | 293 | See: https://github.com/michaelficarra/proposal-first-class-protocols 294 | 295 | The First-Class Protocols proposal adds a few interesting features to classes/inheritance: 296 | 297 | * Interfaces 298 | * Requirements 299 | * Mixin-like composition 300 | * Automatically namespaced members 301 | 302 | Requirements could be added to classes and mixins (see Traits below). 303 | 304 | Automatically namespaced members (members that declare a Symbol and a member named by that Symbol in one go), seem generally useful independent of Protocols. If they can be added to classes, then mixins would get them naturally. 305 | 306 | This can be done today with a helper, and syntax could possibly be added later: 307 | 308 | ```js 309 | let makeSymbol = (o, name) => o[name] = Symbol(name); 310 | class A { 311 | [makeSymbol(A, 'myMethod')]() { /* ... */ } 312 | } 313 | class B extends A { 314 | [A.myMethod]() { 315 | super[A.myMethod](); 316 | // ... 317 | } 318 | } 319 | ``` 320 | 321 | ### Traits 322 | 323 | See: http://zqsmm.qiniucdn.com/data/20110512092812/index.html#Traits 324 | 325 | #### Requirements 326 | 327 | Traits can require that the class implement certain members: 328 | 329 | ```js 330 | trait ComparableTrait { 331 | requires lessThan; 332 | requires equals; 333 | } 334 | ``` 335 | 336 | Maximally minimal mixins leave the door open to add such features to classes in general, and therefore to mixins. 337 | 338 | Roughly, a `requires`-like modifier on class members would presumably be tied to some notion of abstract classes. Requirements would be checked when declaring a concrete subclass. Mixins with requirements would be checked when applying the mixin to a concrete class. 339 | 340 | ```js 341 | abstract class A { 342 | require x; 343 | } 344 | abstract class B extends A {} // OK 345 | class C extends A {} // Error: Must implement foo; 346 | class D extends A { // OK 347 | foo() {} 348 | } 349 | ``` 350 | 351 | #### Aliasing 352 | 353 | _TBD: Declarative aliasing / renaming requires some syntax to describe the renaming..._ 354 | 355 | ## Appendix: Analysis of Subclass Factories 356 | 357 | #### TypeScript 358 | 359 | TypeScript added support for mixins in 2.2. It models mixins as intersections of the argument to the subclass factory and the class defined in the factory. This isn't entirely accurate as it doesn't model override semantics, but it's usually close enough. 360 | 361 | ```ts 362 | export type Constructor = new(...args: any[]) => T; 363 | 364 | class S { 365 | baseMethod() {/*...*/} 366 | } 367 | 368 | let M = (base: T) => class extends base { 369 | constructor(...args: any[]) { 370 | super(...args); 371 | } 372 | 373 | mixinMethod() {/*...*/} 374 | }; 375 | 376 | class C extends M(Object) { 377 | subclassMethod() {/*...*/} 378 | } 379 | 380 | let c = new C(); 381 | ``` 382 | 383 | TypeScript correctly infers that `c` has members inherited from `S`, `M`, and `C`. 384 | 385 | In TypeScript classes define a name in both the value and type namespaces, but functions don't, so `M` is a value, but not a type. If you want to use `M` as a type you have to duplicate the declaration with an interface, and cast the new class to the interface: 386 | 387 | ```ts 388 | interface M { 389 | mixinMethod(); 390 | } 391 | 392 | let M = (base: T) => class extends base { 393 | constructor(...args: any[]) { 394 | super(...args); 395 | } 396 | 397 | mixinMethod() {/*...*/} 398 | } as T & Constructor; 399 | ``` 400 | 401 | This is obviously more cumbersome as the mixin interface becomes larger. 402 | 403 | #### Closure 404 | 405 | Closure requires more boilerplate to describe the mixin and application to the compiler: 406 | 407 | ```js 408 | class S { 409 | baseMethod() {/*...*/} 410 | } 411 | 412 | let M = (base) => { 413 | /* 414 | * @implements {MInterface} 415 | */ 416 | class M extends base { 417 | constructor(...args: any[]) { 418 | super(...args); 419 | } 420 | 421 | mixinMethod() {/*...*/} 422 | } 423 | return M; 424 | }; 425 | 426 | /** 427 | * In Closure the interface declaration is required. 428 | * @interface 429 | */ 430 | function MInterface(){} 431 | 432 | /** @return {void} */ 433 | MInterface.prototype.mixinMethod = function(){}; 434 | 435 | /** 436 | * Closure requires you to separately define and cast the mixin application. 437 | * @constructor 438 | * @extends S 439 | * @implements {MInterface} 440 | */ 441 | const CBase = M(Base); 442 | 443 | class C extends CBase { 444 | subclassMethod() {/*...*/} 445 | } 446 | 447 | let c = new C(); 448 | ``` 449 | 450 | #### Polymer Analyzer 451 | 452 | The Polymer Analyzer has specific support for analyzing mixins via custom JSDoc annotations: 453 | 454 | ```js 455 | class S { 456 | baseMethod() {/*...*/} 457 | } 458 | 459 | /** 460 | * @mixinFunction 461 | */ 462 | let M = (base) => { 463 | /** 464 | * @mixinClass 465 | */ 466 | class M extends base { 467 | constructor(...args: any[]) { 468 | super(...args); 469 | } 470 | 471 | mixinMethod() {/*...*/} 472 | } 473 | return M; 474 | }; 475 | 476 | /** 477 | * @extends Object 478 | * @appliesMixin M 479 | */ 480 | class C extends M(Object) { 481 | subclassMethod() {/*...*/} 482 | } 483 | ``` 484 | -------------------------------------------------------------------------------- /index.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | Proposal Title Goes Here

Stage -1 Draft / September 25, 2017

Proposal Title Goes Here

1796 | 1797 | 1798 |

1This is an emu-clause

1799 |

This is an algorithm:

1800 |
  1. Let proposal be undefined.
  2. If IsAccepted(proposal),
    1. Let stage be 0.
  3. Else,
    1. Let stage be -1.
  4. Return ? ToString(proposal). 1801 |
1802 | 1803 |

ACopyright & Software License

1804 | 1805 |

Copyright Notice

1806 |

© 2017 Your Name Goes Here

1807 | 1808 |

Software License

1809 |

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 http://www.ecma-international.org/memento/codeofconduct.htm FOR INFORMATION REGARDING THE LICENSING OF PATENT CLAIMS THAT ARE REQUIRED TO IMPLEMENT ECMA INTERNATIONAL STANDARDS.

1810 | 1811 |

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

1812 | 1813 |
    1814 |
  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
    2. 1815 |
  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. 1816 |
  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. 1817 |
1818 | 1819 |

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.

1820 | 1821 | 1822 |
-------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "private": true, 3 | "name": "template-for-proposals", 4 | "description": "A repository template for ECMAScript proposals.", 5 | "scripts": { 6 | "build": "ecmarkup spec.emu > index.html" 7 | }, 8 | "homepage": "https://github.com/tc39/template-for-proposals#readme", 9 | "repository": { 10 | "type": "git", 11 | "url": "git+https://github.com/tc39/template-for-proposals.git" 12 | }, 13 | "license": "MIT", 14 | "devDependencies": { 15 | "ecmarkup": "^3.11.5" 16 | } 17 | } 18 | -------------------------------------------------------------------------------- /spec.emu: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 
 7 | title: Proposal Title Goes Here
 8 | stage: -1
 9 | contributors: Your Name Goes 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_), 18 | 1. Let _stage_ be *0*. 19 | 1. Else, 20 | 1. Let _stage_ be *-1*. 21 | 1. Return ? ToString(_proposal_). 22 | 23 | 24 | --------------------------------------------------------------------------------