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).