Stage: 3
Spec Text: pzuraq/ecma262#10
This proposal seeks to extend the Decorators proposal by adding the ability for decorators to associate metadata with the value being decorated.
Decorators are functions that allow users to metaprogram by wrapping and replacing existing values. This allows them to solve a number of use cases quite well, such as memoization, reactivity, method binding, and more. However, there are a number of use cases which require code external to the decorator and decorated class to be able to introspect and understand what decorations were applied, including:
- Validation
- Serialization
- Web component definition
- Dependency injection
- Declarative routing/application structure
- ...and more
In previous iterations of the decorators proposal, all decorators had access to
the class prototype, allowing them to associate metadata directly via a
WeakMap by using the class as a key. This is no longer possible in the most
recent version, however, as decorators only have access to the value they are
directly decorating (e.g. method decorators have access to the method, field
decorators have access to the field, etc).
This proposal extends decorators by providing a metadata object, which can be
used either to directly store metadata, or as a WeakMap key. This object is
provided via the decorator's context argument, and is then accessible via the
Symbol.metadata property on the class definition after decoration.
The overall decorator signature will be updated to the following:
type Decorator = (value: Input, context: {
kind: string;
name: string | symbol;
access: {
get?(): unknown;
set?(value: unknown): void;
};
isPrivate?: boolean;
isStatic?: boolean;
addInitializer?(initializer: () => void): void;
+ metadata?: Record<string | number | symbol, unknown>;
}) => Output | void;The new metadata property is a plain JavaScript object. The same object is
passed to every decorator applied to a class or any of its elements. After the
class has been fully defined, it is assigned to the Symbol.metadata property
of the class.
An example usage might look like:
function meta(key, value) {
return (_, context) => {
context.metadata[key] = value;
};
}
@meta('a', 'x')
class C {
@meta('b', 'y')
m() {}
}
C[Symbol.metadata].a; // 'x'
C[Symbol.metadata].b; // 'y'If the decorated class has a parent class, then the prototype of the metadata
object is set to the metadata object of the superclass. This allows metadata to
be inherited in a natural way, taking advantage of shadowing by default,
mirroring class inheritance. For example:
function meta(key, value) {
return (_, context) => {
context.metadata[key] = value;
};
}
@meta('a', 'x')
class C {
@meta('b', 'y')
m() {}
}
C[Symbol.metadata].a; // 'x'
C[Symbol.metadata].b; // 'y'
class D extends C {
@meta('b', 'z')
m() {}
}
D[Symbol.metadata].a; // 'x'
D[Symbol.metadata].b; // 'z'In addition, metadata from the parent can be read during decoration, so it can be modified or extended by children rather than overriding it.
function appendMeta(key, value) {
return (_, context) => {
// NOTE: be sure to copy, not mutate
const existing = context.metadata[key] ?? [];
context.metadata[key] = [...existing, value];
};
}
@appendMeta('a', 'x')
class C {}
@appendMeta('a', 'z')
class D extends C {}
C[Symbol.metadata].a; // ['x']
D[Symbol.metadata].a; // ['x', 'z']In addition to public metadata placed directly on the metadata object, the
object can be used as a key in a WeakMap if the decorator author does not want
to share their metadata.
const PRIVATE_METADATA = new WeakMap();
function meta(key, value) {
return (_, context) => {
let metadata = PRIVATE_METADATA.get(context.metadata);
if (!metadata) {
metadata = {};
PRIVATE_METADATA.set(context.metadata, metadata);
}
metadata[key] = value;
};
}
@meta('a', 'x')
class C {
@meta('b', 'y')
m() {}
}
PRIVATE_METADATA.get(C[Symbol.metadata]).a; // 'x'
PRIVATE_METADATA.get(C[Symbol.metadata]).b; // 'y'