# Metadata Proposal - ECMAScript

Note
A shim for this API can be found here: https://github.com/rbuckton/ReflectDecorators

Proposal to add Metadata to ECMAScript.

# 1 Syntax

Note
This section is non-normative.

    // define metadata on an object or property
    Reflect.defineMetadata(metadataKey, metadataValue, target);
    Reflect.defineMetadata(metadataKey, metadataValue, target, propertyKey);

    // check for presence of a metadata key on the prototype chain of an object or property
    let result = Reflect.hasMetadata(metadataKey, target);
    let result = Reflect.hasMetadata(metadataKey, target, propertyKey);

    // check for presence of an own metadata key of an object or property
    let result = Reflect.hasOwnMetadata(metadataKey, target);
    let result = Reflect.hasOwnMetadata(metadataKey, target, propertyKey);

    // get metadata value of a metadata key on the prototype chain of an object or property
    let result = Reflect.getMetadata(metadataKey, target);
    let result = Reflect.getMetadata(metadataKey, target, propertyKey);

    // get metadata value of an own metadata key of an object or property
    let result = Reflect.getOwnMetadata(metadataKey, target);
    let result = Reflect.getOwnMetadata(metadataKey, target, propertyKey);

    // get all metadata keys on the prototype chain of an object or property
    let result = Reflect.getMetadataKeys(target);
    let result = Reflect.getMetadataKeys(target, propertyKey);

    // get all own metadata keys of an object or property
    let result = Reflect.getOwnMetadataKeys(target);
    let result = Reflect.getOwnMetadataKeys(target, propertyKey);

    // delete metadata from an object or property
    let result = Reflect.deleteMetadata(metadataKey, target);
    let result = Reflect.deleteMetadata(metadataKey, target, propertyKey);

    // apply metadata via a decorator to a constructor
    @Reflect.metadata(metadataKey, metadataValue)
    class C {
      // apply metadata via a decorator to a method (property)
      @Reflect.metadata(metadataKey, metadataValue)
      method() {
      }
    }

    // Design-time type annotations
    function Type(type) { return Reflect.metadata("design:type", type); }
    function ParamTypes(...types) { return Reflect.metadata("design:paramtypes", types); }
    function ReturnType(type) { return Reflect.metadata("design:returntype", type); }

    // Decorator application
    @ParamTypes(String, Number)
    class C {
      constructor(text, i) {
      }

      @Type(String)
      get name() { return "text"; }

      @Type(Function)
      @ParamTypes(Number, Number)
      @ReturnType(Number)
      add(x, y) {
        return x + y;
      }
    }

    // Metadata introspection
    let obj = new C("a", 1);
    let paramTypes = Reflect.getMetadata("design:paramtypes", obj, "add"); // [Number, Number]

# 2 Abstract Operations

# 2.1 Operations on Objects

# 2.1.1 GetOrCreateMetadataMap ( O, P, Create )

When the abstract operation GetOrCreateMetadataMap is called with Object O, property key P, and Boolean Create the following steps are taken:

1. Assert: P is undefined or IsPropertyKey(P) is true.
2. Let targetMetadata be the value of O's [[Metadata]] internal slot.
3. If targetMetadata is undefined, then
   1. If Create is false, return undefined.
   2. Set targetMetadata to be a newly created Map object.
   3. Set the [[Metadata]] internal slot of O to targetMetadata.
4. Let metadataMap be ? Invoke(targetMetadata, `"get"`, P).
5. If metadataMap is undefined, then
   1. If Create is false, return undefined.
   2. Set metadataMap to be a newly created Map object.
   3. Perform ? Invoke(targetMetadata, `"set"`, P, metadataMap).
6. Return metadataMap.

# 3 Ordinary and Exotic Objects Behaviors

# 3.1 Ordinary Object Internal Methods and Internal Slots

All ordinary objects have an internal slot called [[Metadata]]. The value of this internal slot is either null or a Map object and is used for storing metadata for an object.

# 3.1.1 [[HasMetadata]] ( MetadataKey, P )

When the [[HasMetadata]] internal method of O is called with ECMAScript language value MetadataKey and property key P, the following steps are taken:

1. Return ? OrdinaryHasMetadata(MetadataKey, O, P).

# 3.1.1.1 OrdinaryHasMetadata ( MetadataKey, O, P )

When the abstract operation OrdinaryHasMetadata is called with ECMAScript language value MetadataKey, Object O, and property key P, the following steps are taken:

1. Assert: P is undefined or IsPropertyKey(P) is true.
2. Let hasOwn be ? OrdinaryHasOwnMetadata(MetadataKey, O, P).
3. If hasOwn is true, return true.
4. Let parent be ? O.[[GetPrototypeOf]]().
5. If parent is not null, Return ? parent.[[HasMetadata]](MetadataKey, P).
6. Return false.

# 3.1.2 [[HasOwnMetadata]] ( MetadataKey, P )

When the [[HasOwnMetadata]] internal method of O is called with ECMAScript language value MetadataKey and property key P, the following steps are taken:

1. Return ? OrdinaryHasOwnMetadata(MetadataKey, O, P).

# 3.1.2.1 OrdinaryHasOwnMetadata ( MetadataKey, O, P )

When the abstract operation OrdinaryHasOwnMetadata is called with ECMAScript language value MetadataKey, Object O, and property key P, the following steps are taken:

1. Assert: P is undefined or IsPropertyKey(P) is true.
2. Let metadataMap be ? GetOrCreateMetadataMap(O, P, false).
3. If metadataMap is undefined, return false.
4. Return ? ToBoolean(? Invoke(metadataMap, `"has"`, MetadataKey)).

# 3.1.3 [[GetMetadata]] ( MetadataKey, P )

When the [[GetMatadata]] internal method of O is called with ECMAScript language value MetadataKey and property key P, the following steps are taken:

1. Return ? OrdinaryGetMetadata(MetadataKey, O, P).

# 3.1.3.1 OrdinaryGetMetadata ( MetadataKey, O, P )

When the abstract operation OrdinaryGetMetadata is called with ECMAScript language value MetadataKey, Object O, and property key P, the following steps are taken:

1. Assert: P is undefined or IsPropertyKey(P) is true.
2. Let hasOwn be ? OrdinaryHasOwnMetadata(MetadataKey, O, P).
3. If hasOwn is true, return ? OrdinaryGetOwnMetadata(MetadataKey, O, P).
4. Let parent be ? O.[[GetPrototypeOf]]().
5. If parent is not null, return ? parent.[[GetMetadata]](MetadataKey, P).
6. Return undefined.

# 3.1.4 [[GetOwnMetadata]] ( MetadataKey, P, ParamIndex )

When the [[GetOwnMetadata]] internal method of O is called with ECMAScript language value MetadataKey and property key P, the following steps are taken:

1. Return ? OrdinaryGetOwnMetadata(MetadataKey, O, P).

# 3.1.4.1 OrdinaryGetOwnMetadata ( MetadataKey, O, P )

When the abstract operation OrdinaryGetOwnMetadata is called with ECMAScript language value MetadataKey, Object O, and property key P, the following steps are taken:

1. Assert: P is undefined or IsPropertyKey(P) is true.
2. Let metadataMap be ? GetOrCreateMetadataMap(O, P, false).
3. If metadataMap is undefined, return undefined.
4. Return ? Invoke(metadataMap, `"get"`, MetadataKey).

# 3.1.5 [[DefineOwnMetadata]] ( MetadataKey, MetadataValue, P )

When the [[DefineOwnMetadata]] internal method of O is called with ECMAScript language value MetadataKey, ECMAScript language value MetadataValue, and property key P, the following steps are taken:

1. Return ? OrdinaryDefineOwnMetadata(MetadataKey, MetadataValue, O, P)

# 3.1.5.1 OrdinaryDefineOwnMetadata ( MetadataKey, MetadataValue, O, P )

When the abstract operation OrdinaryDefineOwnProperty is called with ECMAScript language value MetadataKey, ECMAScript language value MetadataValue, Object O, and property key P, the following steps are taken:

1. Assert: P is undefined or IsPropertyKey(P) is true.
2. Let metadataMap be ? GetOrCreateMetadataMap(O, P, true).
3. Return ? Invoke(metadataMap, `"set"`, MetadataKey, MetadataValue).

# 3.1.6 [[MetadataKeys]] ( P )

When the [[MetadataKeys]] internal method of O is called with property key P the following steps are taken:

1. Return ? OrdinaryMetadataKeys(O, P).

# 3.1.6.1 OrdinaryMetadataKeys ( O, P )

When the abstract operation OrdinaryMetadataKeys is called with Object O and property key P the following steps are taken:

1. Assert: P is undefined or IsPropertyKey(P) is true.
2. Let ownKeys be ? OrdinaryOwnMetadataKeys(O, P).
3. Let parent be ? O.[[GetPrototypeOf]]().
4. If parent is null, then return ownKeys.
5. Let parentKeys be ? O.[[OrdinaryMetadataKeys]](P).
6. Let ownKeysLen = ? Get(ownKeys, "length").
7. If ownKeysLen is 0, return parentKeys.
8. Let parentKeysLen = ? Get(parentKeys, "length").
9. If parentKeysLen is 0, return ownKeys.
10. Let set be a newly created Set object.
11. Let keys be ? ArrayCreate(0).
12. Let k be 0.
13. For each element key of ownKeys
    1. Let hasKey be ? Invoke(set, `"has"`, key).
    2. If hasKey is false, then
       1. Let Pk be ! ToString(k).
       2. Perform ? Invoke(set, "add", key).
       3. Let defineStatus be CreateDataProperty(keys, Pk, key).
       4. Assert: defineStatus is true.
       5. Increase k by 1.
14. For each element key of parentKeys
    1. Let hasKey be ? Invoke(set, `"has"`, key).
    2. If hasKey is false, then
       1. Let Pk be ! ToString(k).
       2. Perform ? Invoke(set, `"add"`, key).
       3. Let defineStatus be CreateDataProperty(keys, Pk, key).
       4. Assert: defineStatus is true.
       5. Increase k by 1.
15. Perform ? Set(keys, `"length"`, k).
16. return keys.

# 3.1.7 [[OwnMetadataKeys]] ( P )

When the [[OwnMetadataKeys]] internal method of O is called with property key P the following steps are taken:

1. Return OrdinaryOwnMetadataKeys(O, P).

# 3.1.7.1 OrdinaryOwnMetadataKeys ( O, P )

When the abstract operation OrdinaryOwnMetadataKeys is called with Object O and property key P the following steps are taken:

1. Assert: P is undefined or IsPropertyKey(P) is true.
2. Let keys be ? ArrayCreate(0).
3. Let metadataMap be ? GetOrCreateMetadataMap(O, P, false).
4. If metadataMap is undefined, return keys.
5. Let keysObj be ? Invoke(metadataMap, `"keys"`).
6. Let iterator be ? GetIterator(keysObj).
7. Let k be 0.
8. Repeat
   1. Let Pk be ! ToString(k).
   2. Let next be ? IteratorStep(iterator).
   3. If next is false, then
      1. Let setStatus be ? Set(keys, `"length"`, k, true).
      2. Assert: setStatus is true.
      3. Return keys.
   4. Let nextValue be ? IteratorValue(next).
   5. Let defineStatus be CreateDataPropertyOrThrow(keys, Pk, nextValue).
   6. If defineStatus is an abrupt completion, return ? IteratorClose(iterator, defineStatus).
   7. Increase k by 1.

# 3.1.8 [[DeleteMetadata]]( MetadataKey, P )

When the [[DeleteMetadata]] internal method of O is called with ECMAScript language value MetadataKey and property key P the following steps are taken:

1. Assert: P is undefined or IsPropertyKey(P) is true.
2. Let metadataMap be ? GetOrCreateMetadataMap(O, P, false).
3. If metadataMap is undefined, return false.
4. Return ? Invoke(metadataMap, `"delete"`, MetadataKey).

# 4 Reflection

# 4.1 The Reflect Object

This section contains amendments to the Reflect object.

# 4.1.1 Metadata Decorator Functions

A metadata decorator function is an anonymous built-in function that has [[MetadataKey]] and [[MetadataValue]] internal slots.

When a metadata decorator function F is called with arguments target and key, the following steps are taken:

1. Assert: F has a [[MetadataKey]] internal slot whose value is an ECMAScript language value, or undefined.
2. Assert: F has a [[MetadataValue]] internal slot whose value is an ECMAScript language value, or undefined.
3. If Type(target) is not Object, throw a TypeError exception.
4. If key is not undefined and IsPropertyKey(key) is false, throw a TypeError exception.
5. Let metadataKey be the value of F's [[MetadataKey]] internal slot.
6. Let metadataValue be the value of F's [[MetadataValue]] internal slot.
7. Perform ? target.[[DefineMetadata]](metadataKey, metadataValue, target, key).
8. Return undefined.

# 4.1.2 Reflect.metadata ( metadataKey, metadataValue )

When the `metadata` function is called with arguments metadataKey and metadataValue, the following steps are taken:

1. Let decorator be a new built-in function object as defined in Metadata Decorator Functions.
2. Set the [[MetadataKey]] internal slot of decorator to metadataKey.
3. Set the [[MetadataValue]] internal slot of decorator to metadataValue.
4. Return decorator.

# 4.1.3 Reflect.defineMetadata ( metadataKey, metadataValue, target [, propertyKey] )

When the `defineMetadata` function is called with arguments metadataKey, metadataValue, target, and propertyKey, the following steps are taken:

1. If Type(target) is not Object, throw a TypeError exception.
2. Return ? target.[[DefineMetadata]](metadataKey, metadataValue, propertyKey).

# 4.1.4 Reflect.hasMetadata ( metadataKey, target [, propertyKey] )

When the `hasMetadata` function is called with arguments metadataKey, target, and propertyKey, the following steps are taken:

1. If Type(target) is not Object, throw a TypeError exception.
2. Return ? target.[[HasMetadata]](metadataKey, propertyKey).

# 4.1.5 Reflect.hasOwnMetadata ( metadataKey, target [, propertyKey] )

When the `hasOwnMetadata` function is called with arguments metadataKey, target, and propertyKey, the following steps are taken:

1. If Type(target) is not Object, throw a TypeError exception.
2. Return ? target.[[HasOwn]](metadataKey, propertyKey).

# 4.1.6 Reflect.getMetadata ( metadataKey, target [, propertyKey] )

When the `getMetadata` function is called with arguments metadataKey, target, and propertyKey, the following steps are taken:

1. If Type(target) is not Object, throw a TypeError exception.
2. Return ? target.[[GetMetadata]](metadataKey, propertyKey).

# 4.1.7 Reflect.getOwnMetadata ( metadataKey, target [, propertyKey] )

When the `getOwnMetadata` function is called with arguments metadataKey, target, and propertyKey, the following steps are taken:

1. If Type(target) is not Object, throw a TypeError exception.
2. Return ? target.[[GetOwnMetadata]](metadataKey, propertyKey).

# 4.1.8 Reflect.getMetadataKeys ( target [, propertyKey] )

When the `getMetadataKeys` function is called with arguments target and propertyKey, the following steps are taken:

1. If Type(target) is not Object, throw a TypeError exception.
2. Return ? target.[[GetMetadataKeys]](propertyKey).

# 4.1.9 Reflect.getOwnMetadataKeys ( target [, propertyKey] )

When the `getOwnMetadataKeys` function is called with arguments target and propertyKey, the following steps are taken:

1. If Type(target) is not Object, throw a TypeError exception.
2. Return ? target.[[GetOwnMetadataKeys]](propertyKey).

# 4.1.10 Reflect.deleteMetadata ( metadataKey, target [, propertyKey] )

When the `deleteMetadata` function is called with arguments metadataKey, target, and propertyKey, the following steps are taken:

1. If Type(target) is not Object, throw a TypeError exception.
2. Return ? target.[[DeleteMetadata]](metadataKey, propertyKey).