From f0f8df7583187922b2b1ca51b63bb7dc96af3189 Mon Sep 17 00:00:00 2001 From: Rudy Ges Date: Sun, 15 Oct 2023 10:11:00 +0200 Subject: [PATCH] [js] Update js.lib.Object and js.lib.Symbol From their implementation in js-object haxelib --- std/js/lib/Object.hx | 316 ++++++++++++++++++++----------------------- std/js/lib/Symbol.hx | 112 +++++++++++---- 2 files changed, 234 insertions(+), 194 deletions(-) diff --git a/std/js/lib/Object.hx b/std/js/lib/Object.hx index 55358b7d382..7b80b3d8af8 100644 --- a/std/js/lib/Object.hx +++ b/std/js/lib/Object.hx @@ -22,8 +22,8 @@ package js.lib; -import haxe.extern.Rest; import haxe.DynamicAccess; +import haxe.extern.Rest; /** The `js.lib.Object` constructor creates an object wrapper. @@ -32,230 +32,210 @@ import haxe.DynamicAccess; **/ @:native("Object") extern class Object { - /** - Copies the values of all enumerable own properties from one or more - source objects to a target object. - **/ - static function assign(target:T, sources:Rest<{}>):T; + static var prototype(default,never):ObjectPrototype; /** - Creates a new object with the specified prototype object and properties. - **/ - @:pure static function create(proto:{}, ?propertiesObject:DynamicAccess):T; + The Object.assign() method is used to copy the values of all enumerable + own properties from one or more source objects to a target object. It + will return the target object. - /** - Adds the named properties described by the given descriptors to an object. - **/ - static function defineProperties(obj:T, props:DynamicAccess):T; + Note: this is an ES2015 feature - /** - Adds the named property described by a given descriptor to an object. - **/ - @:overload(function(obj:T, prop:Symbol, descriptor:ObjectPropertyDescriptor):T {}) - static function defineProperty(obj:T, prop:String, descriptor:ObjectPropertyDescriptor):T; + See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/assign + */ + static function assign(target:TSource, sources:Rest<{}>):TDest; /** - Returns an array containing all of the [key, value] pairs of a given - object's own enumerable string properties. - **/ - @:pure static function entries(obj:{}):Array; + The Object.create() method create a new object, using an existing object + to provide the newly created object's __proto__ . (see browser console + for visual evidence.) - /** - Freezes an object: other code can't delete or change any properties. - **/ - static function freeze(obj:T):T; + See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/create + */ + static function create(proto:Null<{}>, ?propertiesObject:DynamicAccess>):TObj; /** - Returns a new object from an iterable of key-value pairs - (reverses Object.entries). - **/ - @:pure static function fromEntries(iterable:Any):T; + The static method Object.defineProperty() defines a new property directly + on an object, or modifies an existing property on an object, and returns + the object. - /** - Returns a property descriptor for a named property on an object. - **/ - @:overload(function(target:Array, propertyKey:Int):Null {}) - @:overload(function(obj:{}, prop:Symbol):Null {}) - @:pure static function getOwnPropertyDescriptor(obj:{}, prop:String):Null; + See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/defineProperty + */ + static function defineProperty(obj:TObj, prop:String, descriptor:ObjectPropertyDescriptor):TObj; /** - Returns an array containing the names of all of the given object's own - enumerable and non-enumerable properties. - **/ - @:pure static function getOwnPropertyNames(obj:{}):Array; + The Object.defineProperties() method defines new or modifies existing + properties directly on an object, returning the object. - /** - Returns an array of all symbol properties found directly upon a given object. - **/ - @:pure static function getOwnPropertySymbols(obj:{}):Array; + See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/defineProperties + */ + static function defineProperties(obj:TObj, props:DynamicAccess>):TObj; /** - Returns the prototype of the specified object. - **/ - @:pure static function getPrototypeOf(obj:{}):Null; + The Object.entries() method returns an array of a given object's own + enumerable property [key, value] pairs, in the same order as that + provided by a for...in loop (the difference being that a for-in loop + enumerates properties in the prototype chain as well). - /** - Compares if two values are the same value. Equates all NaN values - (which differs from both Abstract Equality Comparison and - Strict Equality Comparison). - **/ - @:pure static function is(value1:T, value2:T):Bool; + Note: this is an ES2017 feature - /** - Determines if extending of an object is allowed. - **/ - @:pure static function isExtensible(obj:{}):Bool; + See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/entries + */ + static function entries(obj:TObj):Array>; /** - Determines if an object was frozen. - **/ - @:pure static function isFrozen(obj:{}):Bool; + The Object.freeze() method freezes an object: that is, prevents new + properties from being added to it; prevents existing properties from + being removed; and prevents existing properties, or their enumerability, + configurability, or writability, from being changed, it also prevents the + prototype from being changed. + The method returns the passed object. - /** - Determines if an object is sealed. - **/ - @:pure static function isSealed(obj:{}):Bool; + See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/freeze + */ + static function freeze(obj:TObj):TObj; /** - Returns an array containing the names of all of the given object's own - enumerable string properties. - **/ - @:pure static function keys(obj:{}):Array; + The Object.getOwnPropertyDescriptor() method returns a property + descriptor for an own property (that is, one directly present on an + object and not in the object's prototype chain) of a given object. - /** - Prevents any extensions of an object. - **/ - static function preventExtensions(obj:T):T; + See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/getOwnPropertyDescriptor + */ + static function getOwnPropertyDescriptor(obj:TObj, prop:String):Null>; /** - Prevents other code from deleting properties of an object. - **/ - static function seal(obj:T):T; + The Object.getOwnPropertyDescriptors() method returns all own property + descriptors of a given object. - /** - Sets the prototype (i.e., the internal Prototype property). - **/ - static function setPrototypeOf(obj:T, prototype:Null<{}>):T; + See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/getOwnPropertyDescriptors + */ + static function getOwnPropertyDescriptors(obj:TObj):DynamicAccess>; /** - Returns an array containing the values that correspond to all of - a given object's own enumerable string properties. - **/ - @:pure static function values(obj:{}):Array; + The Object.getOwnPropertyNames() method returns an array of all + properties (including non-enumerable properties except for those which + use Symbol) found directly upon a given object. - /** - Allows the addition of properties to all objects of type Object. - **/ - static var prototype(default, never):ObjectPrototype; + See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/getOwnPropertyNames + */ + static function getOwnPropertyNames(obj:TObj):Array; /** - The Object constructor creates an object wrapper. - **/ - @:pure function new(?value:Any); -} + The Object.getOwnPropertySymbols() method returns an array of all symbol + properties found directly upon a given object. -/** - Type for - @see -**/ -typedef ObjectPrototype = { - /** - Returns a boolean indicating whether an object contains the specified - property as a direct property of that object and not inherited through - the prototype chain. - **/ - var hasOwnProperty(default, never):Function; + Note: this is an ES2015 feature - /** - Returns a boolean indicating whether the object this method is called - upon is in the prototype chain of the specified object. - **/ - var isPrototypeOf(default, never):Function; + See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/getOwnPropertySymbols + */ + static function getOwnPropertySymbols(obj:TObj):Array; /** - Returns a boolean indicating if the internal enumerable attribute is set. - **/ - var propertyIsEnumerable(default, never):Function; + The Object.getPrototypeOf() method returns the prototype (i.e. the value + of the internal [[Prototype]] property) of the specified object. + + See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/getPrototypeOf + */ + static function getPrototypeOf(obj:TObj):TProto; /** - Calls `toString()`. - **/ - var toLocaleString(default, never):Function; + The Object.is() method determines whether two values are the same value. + + Note: this is an ES2015 feature + + See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is + */ + static function is(obj1:TObj, obj2:TObj):Bool; /** - Returns a string representation of the object. - **/ - var toString(default, never):Function; + The Object.isExtensible() method determines if an object is extensible + (whether it can have new properties added to it). + + See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/isExtensible + */ + static function isExtensible(obj:TObj):Bool; /** - Returns the primitive value of the specified object. - **/ - var valueOf(default, never):Function; -} + The Object.isFrozen() determines if an object is frozen. + + See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/isFrozen + */ + static function isFrozen(obj:TObj):Bool; -/** - @see -**/ -typedef ObjectPropertyDescriptor = { /** - `true` if and only if the type of this property descriptor may be - changed and if the property may be deleted from the corresponding object. + The Object.isSealed() method determines if an object is sealed. - Defaults to `false`. - **/ - var ?configurable:Bool; + See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/isSealed + */ + static function isSealed(obj:TObj):Bool; /** - `true` if and only if this property shows up during enumeration of the - properties on the corresponding object. + The Object.keys() method returns an array of a given object's own + enumerable properties, in the same order as that provided by a for...in + loop (the difference being that a for-in loop enumerates properties in + the prototype chain as well). - Defaults to `false`. - **/ - var ?enumerable:Bool; + See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/keys + */ + static function keys(obj:TObj):Array; /** - The value associated with the property. - Can be any valid JavaScript value (number, object, function, etc). - **/ - var ?value:Any; + The Object.preventExtensions() method prevents new properties from ever + being added to an object (i.e. prevents future extensions to the object). + + See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/preventExtensions + */ + static function preventExtensions(obj:TObj):TObj; /** - `true` if and only if the value associated with the property may be - changed with an assignment operator. + The Object.seal() method seals an object, preventing new properties from + being added to it and marking all existing properties as + non-configurable. Values of present properties can still be changed as + long as they are writable. - Defaults to `false`. - **/ - var ?writable:Bool; + See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/seal + */ + static function seal(obj:TObj):TObj; /** - A function which serves as a getter for the property, or `undefined` if - there is no getter. When the property is accessed, this function is - called without arguments and with `this` set to the object through which - the property is accessed (this may not be the object on which the - property is defined due to inheritance). - The return value will be used as the value of the property. - **/ - var ?get:Void->Any; + The Object.setPrototypeOf() method sets the prototype (i.e., the internal + [[Prototype]] property) of a specified object to another object or null. + + Note: this is an ES2015 feature + + See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/setPrototypeOf + */ + static function setPrototypeOf(obj:TObj, proto:Null):TObj; /** - A function which serves as a setter for the property, or undefined if - there is no setter. When the property is assigned to, this function - is called with one argument (the value being assigned to the property) - and with `this` set to the object through which the property is assigned. - **/ - var ?set:Any->Void; -} + The Object.values() method returns an array of a given object's own + enumerable property values, in the same order as that provided by a + for...in loop (the difference being that a for-in loop enumerates + properties in the prototype chain as well). -/** - Key/value access helper for `js.lib.Object.entries()`. -**/ -abstract ObjectEntry(Array) { - public var key(get, never):String; - public var value(get, never):Any; + Note: this is an ES2017 feature - inline function get_key():String - return this[0]; + See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/values + */ + static function values(obj:TObj):Array; +} - inline function get_value():Any - return this[1]; +typedef ObjectPrototype = { + var hasOwnProperty(default,never):Function; + var isPrototypeOf(default,never):Function; + var propertyIsEnumerable(default,never):Function; + var toLocaleString(default,never):Function; + var toString(default,never):Function; + var valueOf(default,never):Function; +} + +typedef ObjectPropertyDescriptor = { + @:optional var value:TProp; + @:optional var configurable:Bool; + @:optional var enumerable:Bool; + @:optional var writable:Bool; + @:optional var get:Void->TProp; + @:optional var set:TProp->Void; } + diff --git a/std/js/lib/Symbol.hx b/std/js/lib/Symbol.hx index 61960149ce1..2ddab5e3905 100644 --- a/std/js/lib/Symbol.hx +++ b/std/js/lib/Symbol.hx @@ -25,44 +25,104 @@ package js.lib; @:native("Symbol") extern class Symbol { /** - To create a new primitive symbol, use `new Symbol()` with an optional string as its `description`. + The Symbol() function returns a value of type symbol, has static + properties that expose several members of built-in objects, has static + methods that expose the global symbol registry, and resembles a built-in + object class but is incomplete as a constructor because it does not + support the syntax "new Symbol()". - NOTE: Unlike in plain JavaScript, `new Symbol()` syntax is used in Haxe. This generates a `Symbol(...)` - expression as required by the JavaScript specification. - **/ - @:pure @:selfCall function new(?description:String); + Every symbol value returned from Symbol() is unique. + A symbol value may be used as an identifier for object properties; this + is the data type's only purpose. + Some further explanation about purpose and usage can be found in the + glossary entry for Symbol. + + The data type symbol is a primitive data type. + + See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol + */ + @:selfCall function new(description:Null = null); + + /** + The Symbol.for(key) method searches for existing symbols in a + runtime-wide symbol registry with the given key and returns it if found. + Otherwise a new symbol gets created in the global symbol registry with + this key. + + See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/for + */ + @:native('for') static function forKey(key:String):Symbol; + + /** + The Symbol.keyFor(sym) method retrieves a shared symbol key from the + global symbol registry for the given symbol. + + See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/keyFor + */ + static function keyFor(symbol:Symbol):Null; + + /** + A method returning the default iterator for an object. Used by for...of. + */ + static var iterator:Symbol; + + /** + A method that matches against a string, also used to determine if an + object may be used as a regular expression. Used by + String.prototype.match(). + */ + static var match:Symbol; + + /** + A method that replaces matched substrings of a string. Used by + String.prototype.replace(). + */ + static var replace:Symbol; /** - Searches for existing symbols with the given key and returns it if found. - Otherwise a new symbol gets created in the global symbol registry with this key. - **/ - @:native("for") static function for_(key:String):Symbol; + A method that returns the index within a string that matches the regular + expression. Used by String.prototype.search(). + */ + static var search:Symbol; /** - Retrieves a shared symbol key from the global symbol registry for the given symbol. - **/ - @:pure static function keyFor(sym:Symbol):Null; + A method that splits a string at the indices that match a regular + expression. Used by String.prototype.split(). + */ + static var split:Symbol; /** - Returns a string containing the description of the Symbol. - **/ - @:pure function toString():String; + A method determining if a constructor object recognizes an object as its + instance. Used by instanceof. + */ + static var hasInstance:Symbol; /** - A method returning the default iterator for an object. - **/ - static var iterator(default, null):Symbol; + A Boolean value indicating if an object should be flattened to its array + elements. Used by Array.prototype.concat(). + */ + static var isConcatSpreadable:Symbol; /** - A method that returns the default AsyncIterator for an object. - **/ - static var asyncIterator(default, null):Symbol; + An object value of whose own and inherited property names are excluded + from the with environment bindings of the associated object. + */ + static var unscopables:Symbol; /** - Retrieve symbol from a given `object`. + A constructor function that is used to create derived objects. + */ + static var species:Symbol; - NOTE: This is a Haxe-specific method that generates an `object[symbol]` expression. - **/ - inline function ofObject(object:{}):Null - return (cast object)[cast this]; + /** + A method converting an object to a primitive value. + */ + static var toPrimitive:Symbol; + + /** + A string value used for the default description of an object. Used by + Object.prototype.toString(). + */ + static var toStringTag:Symbol; } +