Merge branch 'main' into align-jekyll-versions-to-github-pages

Author: keithamus

docs/_guide/decorators.md

@@ -37,7 +37,51 @@ class HelloWorldElement extends HTMLElement {
 
 Class Field decorators get given the class and the field name so they can add custom functionality to the field. Because they operate on the fields, they must be put on top of or to the left of the field.
 
-#### Supporting `strictPropertyInitialization`
+### Method Decorators
+
+Method decorators work just like Field Decorators. Put them on top or on the left of the method, like so:
+
+
+```js
+class HelloWorldElement extends HTMLElement {
+
+  @log
+  submit() {
+    // ...
+  }
+
+  // Alternative style
+
+  @log load() {
+    // ...
+  }
+
+}
+```
+
+### Getter/Setter 
+
+Decorators can also be used over a `get` or `set` field. These work just like Field Decorators, but you can put them over one or both the `get` or `set` field. Some decorators might throw an error if you put them over a `get` field, when they expect to be put over a `set` field:
+
+
+```js
+class HelloWorldElement extends HTMLElement {
+
+  @target set something() {
+    // ...
+  }
+
+  // Can be used over just one field
+  @attr get data() {
+    return {}
+  }
+  set data() {
+
+  }
+}
+```
+
+### Supporting `strictPropertyInitialization`
 
 TypeScript comes with various "strict" mode settings, one of which is `strictPropertyInitialization` which lets TypeScript catch potential class properties which might not be assigned during construction of a class. This option conflicts with Catalyst's `@target`/`@targets` decorators, which safely do the assignment but TypeScript's simple heuristics cannot detect this. There are two ways to work around this:
 
@@ -63,28 +107,6 @@ TypeScript comes with various "strict" mode settings, one of which is `strictPro
     }
     ```
 
-### Method Decorators
-
-Catalyst doesn't currently ship with any method decorators, but you might see them in code. They work just like Field Decorators (in fact they're the same thing). Put them on top or on the left of the method, like so:
-
-
-```js
-class HelloWorldElement extends HTMLElement {
-
-  @log
-  submit() {
-    // ...
-  }
-
-  // Alternative style
-
-  @log load() {
-    // ...
-  }
-
-}
-```
-
 ### Function Calling Decorators
 
 You might see some decorators that look like function calls, and that's because they are! Some decorators allow for customisation; calling with additional arguments. Decorators that expect to be called are generally not interchangeable with the non-call variant, a decorators documentation should tell you how to use it.

src/get-property-descriptor.ts

@@ -0,0 +1,7 @@
+export const getPropertyDescriptor = (instance: unknown, key: PropertyKey): PropertyDescriptor | undefined => {
+  while (instance) {
+    const descriptor = Object.getOwnPropertyDescriptor(instance, key)
+    if (descriptor) return descriptor
+    instance = Object.getPrototypeOf(instance)
+  }
+}

src/mark.ts

@@ -1,39 +1,67 @@
+import {getPropertyDescriptor} from './get-property-descriptor.js'
+
 type PropertyType = 'field' | 'getter' | 'setter' | 'method'
-interface PropertyDecorator {
+export interface PropertyDecorator {
   (proto: object, key: PropertyKey, descriptor?: PropertyDescriptor): void
   readonly static: unique symbol
 }
-type GetMarks = (instance: object) => Set<PropertyKey>
-export function createMark(validate: (key: PropertyKey, type: PropertyType) => void): [PropertyDecorator, GetMarks] {
+type GetMarks<T> = (instance: T) => Set<PropertyKey>
+type InitializeMarks<T> = (instance: T) => void
+
+type Context = {
+  kind: PropertyType
+  name: PropertyKey
+  access: PropertyDescriptor
+}
+
+const getType = (descriptor?: PropertyDescriptor): PropertyType => {
+  if (descriptor) {
+    if (typeof descriptor.value === 'function') return 'method'
+    if (typeof descriptor.get === 'function') return 'getter'
+    if (typeof descriptor.set === 'function') return 'setter'
+  }
+  return 'field'
+}
+
+export function createMark<T extends object>(
+  validate: (context: {name: PropertyKey; kind: PropertyType}) => void,
+  initialize: (instance: T, context: Context) => PropertyDescriptor | void
+): [PropertyDecorator, GetMarks<T>, InitializeMarks<T>] {
   const marks = new WeakMap<object, Set<PropertyKey>>()
-  function get(proto: object): Set<PropertyKey> {
+  const get = (proto: object): Set<PropertyKey> => {
     if (!marks.has(proto)) {
       const parent = Object.getPrototypeOf(proto)
-      marks.set(proto, new Set(marks.get(parent) || []))
+      marks.set(proto, new Set(parent ? get(parent) || [] : []))
     }
     return marks.get(proto)!
   }
-  const marker = (proto: object, key: PropertyKey, descriptor?: PropertyDescriptor): void => {
-    if (get(proto).has(key)) return
-    let type: PropertyType = 'field'
-    if (descriptor) {
-      if (typeof descriptor.value === 'function') type = 'method'
-      if (typeof descriptor.get === 'function') type = 'getter'
-      if (typeof descriptor.set === 'function') type = 'setter'
-    }
-    validate(key, type)
-    get(proto).add(key)
+  const marker = (proto: object, name: PropertyKey, descriptor?: PropertyDescriptor): void => {
+    if (get(proto).has(name)) return
+    validate({name, kind: getType(descriptor)})
+    get(proto).add(name)
   }
   marker.static = Symbol()
-
+  const getMarks = (instance: T): Set<PropertyKey> => {
+    const proto = Object.getPrototypeOf(instance)
+    for (const key of proto.constructor[marker.static] || []) {
+      marker(proto, key, Object.getOwnPropertyDescriptor(proto, key))
+    }
+    return new Set(get(proto))
+  }
   return [
     marker as PropertyDecorator,
-    (instance: object): Set<PropertyKey> => {
-      const proto = Object.getPrototypeOf(instance)
-      for (const key of proto.constructor[marker.static] || []) {
-        marker(proto, key, Object.getOwnPropertyDescriptor(proto, key))
+    getMarks,
+    (instance: T): void => {
+      for (const name of getMarks(instance)) {
+        const access: PropertyDescriptor = getPropertyDescriptor(instance, name) || {
+          value: void 0,
+          configurable: true,
+          writable: true,
+          enumerable: true
+        }
+        const newDescriptor = initialize(instance, {name, kind: getType(access), access}) || access
+        Object.defineProperty(instance, name, newDescriptor)
       }
-      return new Set(get(proto))
     }
   ]
 }