@nejs/basic-extensions
Advanced tools
@nejs/basic-extensions is a JavaScript library that provides a collection of essential extensions to built-in JavaScript objects like Array, Object, Function, and Reflect. These extensions are designed to enhance the native capabilities of JavaScript objects, providing developers with additional utility methods for common tasks and improving code readability and efficiency.
Array Extensions: Adds convenience methods to JavaScript arrays, like first and last,
for easy access to the first and last elements.
Object Extensions: Introduces utility functions to the Object class, such as methods for checking object types and manipulating properties.
Function Extensions: Enriches the Function class with methods to identify function types, such as arrow functions, async functions, and bound functions.
Reflect Extensions: Extends the Reflect object with advanced property interaction methods, including checks for the presence of multiple or specific keys.
Install @nejs/basic-extensions using npm:
npm install @nejs/basic-extensions
Or using yarn:
yarn add @nejs/basic-extensions
Import the desired extensions in your JavaScript project:
import { ArrayPrototypeExtensions } from '@nejs/basic-extensions';
// Use the Array extensions
import { FunctionExtensions } from '@nejs/basic-extensions';
// Use the Function extensions
ArrayExtensions is a constant that applies a patch to the global
Array constructor. This patch extends the Array with additional
methods and properties, enhancing its functionality.
The Patch function takes two arguments: the target object to be patched
(in this case, Array), and an object containing the methods and
properties to be added to the target object.
Type: Patch
// Using a method added by ArrayExtensions
const arr = [1, 2, 3];
console.log(Array.ifArray(arr, 'Array', 'Not Array')); // Output: 'Array'
ArrayPrototypeExtensions is a constant that applies a patch to the
Array prototype. This patch extends the Array prototype with additional
methods and properties, enhancing its functionality.
The Patch function takes two arguments: the target object to be patched
(in this case, Array.prototype), and an object containing the methods
and properties to be added to the target object.
Type: Patch
// Using a method added by ArrayPrototypeExtensions
const arr = [1, 2, 3];
console.log(arr.ifArray('Array', 'Not Array')); // Output: 'Array'
Checks if the provided value is an array and returns one of two provided values based on the result. This function is a convenience method for performing conditional operations based on the type of the provided value.
Type: function
value any The value to be checked.thenValue (function | any) The value to be returned if the
provided value is an array.elseValue (function | any) The value to be returned if the
provided value is not an array.const arr = [1, 2, 3];
console.log(ArrayExtensions.ifArray(arr, 'Array', 'Not Array'));
// Output: 'Array'
const notArr = "I'm not an array";
console.log(ArrayExtensions.ifArray(notArr, 'Array', 'Not Array'));
// Output: 'Not Array'
Returns any Returns thenValue if the provided value is an array,
otherwise returns elseValue.
Sometimes defining even a short function for the invocation of find
can be troublesome. This helper function performs that job for you. If
the specified element is in the array, true will be returned.
value any the value to search for. This value must triple equals
the array element in order to return true.Returns any true if the exact element exists in the array, false otherwise
The findEntry function searches the entries of the object and returns
the [index, value] entry array for the first matching value found.
findFn function a function that takes the element to be checked
and returns a boolean valueReturns any if findFn returns true, an array with two elements, the first
being the index, the second being the value, is returned.
A getter property that returns the first element of the array. If the
array is empty, it returns undefined. This property is useful for
scenarios where you need to quickly access the first item of an array
without the need for additional checks or method calls.
Returns any The first element of the array or undefined if the array
is empty.
A getter property that returns the last element of the array. It
calculates the last index based on the array's length. If the array is
empty, it returns undefined. This property is beneficial when you need
to access the last item in an array, improving code readability and
avoiding manual index calculation.
Returns any The last element of the array or undefined if the
array is empty.
A getter property that checks if the current context (this) is an
array. This is a convenience method that wraps the native
Array.isArray function.
Type: function
const arr = [1, 2, 3];
console.log(arr.isArray); // Output: true
const notArr = "I'm not an array";
console.log(notArr.isArray); // Output: false
Returns boolean true if the current context is an array,
false otherwise.
Checks if the current context (this) is an array and returns one of
two provided values based on the result. This function is a convenience
method for performing conditional operations based on the type of
the current context.
Type: function
thenValue (function | any) The value to be returned if the
current context is an array.elseValue (function | any) The value to be returned if the
current context is not an array.const arr = [1, 2, 3];
console.log(arr.ifArray('Array', 'Not Array')); // Output: 'Array'
const notArr = "I'm not an array";
console.log(notArr.ifArray('Array', 'Not Array')); // Output: 'Not Array'
Returns any Returns thenValue if the current context is an array,
otherwise returns elseValue.
Checks if at least one element in the array is equal to the provided
value. This method uses the Array.prototype.some function to iterate
over the array and compare each element with the provided value.
Type: function
value any The value to be compared with the array elements.doubleEqualsOkay boolean A flag indicating whether to
use loose equality (==) or strict equality (===) for the comparison.
If true, loose equality is used. If false, strict equality is used. (optional, default true)const arr = [1, 2, 3];
console.log(arr.oneIs(2)); // Output: true
const arr2 = ['1', '2', '3'];
console.log(arr2.oneIs(2, false)); // Output: false
Returns boolean Returns true if at least one element in the array
is equal to the provided value, otherwise false.
Checks if some elements in the array are included in the provided values.
This method uses the Array.prototype.some function to iterate over the
array and checks if any of the elements are included in the provided values.
Type: function
values ...any The values to be checked against the array elements.const arr = [1, 2, 3];
console.log(arr.someAre(2, 4)); // Output: true
const arr2 = ['1', '2', '3'];
console.log(arr2.someAre(4, 5)); // Output: false
Returns boolean Returns true if at least one element in the array
is included in the provided values, otherwise false.
Checks if all elements in the array are equal to the provided value.
This method uses the Array.prototype.every function to iterate over
the array and compare each element with the provided value.
Type: function
value any The value to be compared with the array elements.doubleEqualsOkay boolean A flag indicating whether to
use loose equality (==) or strict equality (===) for the comparison.
If true, loose equality is used. If false, strict equality is used. (optional, default true)const arr = [2, 2, 2];
console.log(arr.allAre(2)); // Output: true
const arr2 = ['2', '2', '2'];
console.log(arr2.allAre(2, false)); // Output: false
Returns boolean Returns true if all elements in the array are equal
to the provided value, otherwise false.
BigIntExtensions is a patch for the JavaScript built-in BigInt class.
It adds utility methods to the BigInt class without modifying the global
namespace directly. This patch includes methods for checking if a value is
a BigInt and conditionally returning a value based on whether the supplied
value is a BigInt or not.
Type: Patch
import { BigIntExtensions } from 'big.int.extension.js'
BigIntExtensions.apply()
// Now the `BigInt` class has additional methods available
Determines if the supplied value is a BigInt. This check is
performed by first checking the typeof the value and then
checking to see if the value is an instanceof BigInt
value any The value that needs to be checked to determine
if it is a BigInt or notconst bigInt = 1234567890123456789012345678901234567890n
isBigInt(bigInt) // true
isBigInt(1234567890123456789012345678901234567890) // false
isBigInt('1234567890123456789012345678901234567890') // false
isBigInt(BigInt('1234567890123456789012345678901234567890')) // true
Returns boolean true if the supplied value is a BigInt,
false otherwise
Conditionally returns a value based on whether the supplied
value is a BigInt or not. If the value is a BigInt,
the thenValue will be returned. If it is not a BigInt,
the elseValue will be returned instead.
value any The value to check to determine if it is a
BigIntthenValue any The value to return if the supplied
value is a BigIntelseValue any The value to return if the supplied
value is not a BigIntconst bigInt = 1234567890123456789012345678901234567890n
const num = 42
ifBigInt(bigInt, 'is a BigInt', 'not a BigInt')
// 'is a BigInt'
ifBigInt(num, 'is a BigInt', 'not a BigInt')
// 'not a BigInt'
Returns any Either the thenValue or elseValue depending
on if the supplied value is a BigInt
BigIntPrototypeExtensions is a patch for the JavaScript built-in
BigInt.prototype. It adds utility methods to the BigInt prototype
without modifying the global namespace directly. This patch includes
methods for checking if a value is a BigInt and conditionally returning
a value based on whether the supplied value is a BigInt or not.
Type: Patch
import { BigIntPrototypeExtensions } from 'big.int.extension.js'
BigIntPrototypeExtensions.apply()
// Now the `BigInt` prototype has additional methods available
A getter method that returns an object representation of the BigInt instance.
This method wraps the BigInt instance in an object, allowing it to be
treated as an object. The returned object is created using the Object()
constructor, which takes the BigInt instance as its argument.
Type: Object
const bigInt = 1234567890123456789012345678901234567890n
console.log(typeof bigInt) // 'bigint'
console.log(typeof bigInt.instance) // 'object'
A getter method that checks if the current instance is a BigInt.
This method uses the pIsBigInt function from the BigIntExtensions
patch to determine if the current instance (this) is a BigInt.
Type: boolean
const bigInt = 1234567890123456789012345678901234567890n
console.log(bigInt.isBigInt) // Output: true
const notBigInt = 42
console.log(notBigInt.isBigInt) // Output: false
Checks if the current object is a BigInt and returns the corresponding value based on the result.
This method uses the pIfBigInt function from the BigIntExtensions
patch to determine if the current object (this) is a BigInt. If it is
a BigInt, the thenValue is returned. Otherwise, the elseValue is
returned.
thenValue any The value to return if the current object
is a BigInt.elseValue any The value to return if the current object
is not a BigInt.const bigInt = 1234567890123456789012345678901234567890n
// 'Is a BigInt'
console.log(bigInt.ifBigInt('Is a BigInt', 'Not a BigInt'))
const notBigInt = 42
// 'Not a BigInt'
console.log(notBigInt.ifBigInt('Is a BigInt', 'Not a BigInt'))
Returns any The thenValue if the current object is a BigInt, or
the elseValue if it is not a BigInt.
Retrieves the properties of a function and its prototype.
This method uses the Reflect.ownKeys function to get all the keys
(including non-enumerable and symbol keys) of the function and its
prototype. It then uses Object.getOwnPropertyDescriptor to get the
property descriptors for each key. The descriptors include information
about the property's value, writability, enumerability, and
configurability.
fn Function The function whose properties are to be retrieved.function MyFunction() {}
MyFunction.myProp = 'hello';
MyFunction.prototype.myProtoProp = 'world';
const result = getClassProperties(MyFunction);
console.log(result);
// Output: [MyFunction, { myProp: { value: 'hello', writable: true,
// enumerable: true, configurable: true } }, MyFunction.prototype,
// { myProtoProp: { value: 'world', writable: true, enumerable: true,
// configurable: true } }]
Returns Array An array containing the function itself, its property descriptors, its prototype, and the prototype's property descriptors.
Determines if a given value is an asynchronous function. It checks if the
value is an instance of Function and if its string representation
includes the keyword 'Async'. This method is particularly useful for
identifying async functions.
value any The value to be checked.Returns boolean Returns true if the value is an async function,
otherwise false.
The ifAsync function checks if a given value is an async function and
returns one of two provided values based on the result. This function is
a convenience method for performing conditional operations based on the
type of a value.
value any The value to be checked. If this is an async function,
thenValue is returned, otherwise elseValue is returned.thenValue any The value to be returned if value is an async
function.elseValue any The value to be returned if value is not an
async function.// Suppose we have an async function and a regular function
async function asyncFunc() { return 'I am async'; }
function regularFunc() { return 'I am regular'; }
// Using ifAsync
console.log(Function.ifAsync(asyncFunc, 'Async', 'Not Async'));
// Output: 'Async'
console.log(Function.ifAsync(regularFunc, 'Async', 'Not Async'));
// Output: 'Not Async'
Returns any Returns thenValue if value is an async function,
otherwise returns elseValue.
The function checks if a given value is an async generator function
value any The value parameter is the value that we want to
check if it is a generator function.Returns boolean true if the value is an instance of a function and
its string tag is 'AsyncGeneratorFunction', otherwise it returns false.
The ifAsyncGenerator function checks if a given value is an async
generator function and returns one of two provided values based on the
result. This function is a convenience method for performing conditional
operations based on the type of a value.
value any The value to be checked. If this is an async
generator function, thenValue is returned, otherwise elseValue is
returned.thenValue any The value to be returned if value is an async
generator function.elseValue any The value to be returned if value is not an
async generator function.// Suppose we have an async generator function and a regular function
async function* asyncGenFunc() { yield 'I am async'; }
function regularFunc() { return 'I am regular'; }
// Using ifAsyncGenerator
console.log(Function.ifAsyncGenerator(asyncGenFunc, 'Async', 'Not Async'));
// Output: 'Async'
console.log(Function.ifAsyncGenerator(regularFunc, 'Async', 'Not Async'));
// Output: 'Not Async'
Returns any Returns thenValue if value is an async generator
function, otherwise returns elseValue.
Checks if a given value is an arrow function. It verifies if the value is
an instance of Function, if its string representation includes the '=>'
symbol, and if it lacks a prototype, which is a characteristic of arrow
functions in JavaScript.
value any The value to be checked.Returns boolean Returns true if the value is an arrow function,
otherwise false.
The ifBigArrow function checks if a given value is an arrow function
and returns one of two provided values based on the result. This function
is a convenience method for performing conditional operations based on
the type of a value.
value any The value to be checked. If this is an arrow function,
thenValue is returned, otherwise elseValue is returned.thenValue any The value to be returned if value is an arrow
function.elseValue any The value to be returned if value is not an
arrow function.// Suppose we have an arrow function and a regular function
const arrowFunc = () => 'I am an arrow function';
function regularFunc() { return 'I am a regular function'; }
// Using ifBigArrow
console.log(Function.ifBigArrow(arrowFunc, 'Arrow', 'Not Arrow'));
// Output: 'Arrow'
console.log(Function.ifBigArrow(regularFunc, 'Arrow', 'Not Arrow'));
// Output: 'Not Arrow'
Returns any Returns thenValue if value is an arrow function,
otherwise returns elseValue.
Determines if a given value is a bound function. Bound functions are
created using the Function.prototype.bind method, which allows setting
the this value at the time of binding. This method checks if the value
is an instance of Function, if its string representation starts with
'bound', and if it lacks a prototype property. These characteristics
are indicative of bound functions in JavaScript.
value any The value to be checked, typically a function.Returns boolean Returns true if the value is a bound function,
otherwise false. Bound functions have a specific format in their
string representation and do not have their own prototype property.
The ifBound function checks if a given value is a bound function and
returns one of two provided values based on the result. This function
is a convenience method for performing conditional operations based on
the type of a value.
value any The value to be checked. If this is a bound function,
thenValue is returned, otherwise elseValue is returned.thenValue any The value to be returned if value is a bound
function.elseValue any The value to be returned if value is not a
bound function.// Suppose we have a bound function and a regular function
const boundFunc = function() { return this.x }.bind({x: 'I am bound'});
function regularFunc() { return 'I am a regular function'; }
// Using ifBound
console.log(Function.ifBound(boundFunc, 'Bound', 'Not Bound'));
// Output: 'Bound'
console.log(Function.ifBound(regularFunc, 'Bound', 'Not Bound'));
// Output: 'Not Bound'
Returns any Returns thenValue if value is a bound function,
otherwise returns elseValue.
Determines if a given value is a class. It checks if the value is an
instance of Function and if its string representation includes the
keyword 'class'. This method is useful for distinguishing classes from
other function types in JavaScript.
value any The value to be checked.Returns boolean Returns true if the value is a class, otherwise
false.
The ifClass function checks if a given value is a class and returns
one of two provided values based on the result. This function is a
convenience method for performing conditional operations based on the
type of a value.
value any The value to be checked. If this is a class,
thenValue is returned, otherwise elseValue is returned.thenValue any The value to be returned if value is a class.elseValue any The value to be returned if value is not a
class.// Suppose we have a class and a regular function
class MyClass {}
function myFunction() {}
// Using ifClass
console.log(Function.ifClass(MyClass, 'Class', 'Not Class'));
// Output: 'Class'
console.log(Function.ifClass(myFunction, 'Class', 'Not Class'));
// Output: 'Not Class'
Returns any Returns thenValue if value is a class, otherwise returns
elseValue.
Checks if a given value is a regular function. This method verifies if
the value is an instance of Function, which includes regular functions,
classes, and async functions but excludes arrow functions.
value any The value to be checked.Returns boolean Returns true if the value is a regular function,
otherwise false.
The ifFunction method checks if a given value is a regular function
and returns one of two provided values based on the result. This method
is a convenience for performing conditional operations based on the
type of a value.
value any The value to be checked. If this is a function,
thenValue is returned, otherwise elseValue is returned.thenValue any The value to be returned if value is a function.elseValue any The value to be returned if value is not a
function.// Suppose we have a function and a non-function value
function myFunction() {}
let notFunction = "I'm not a function";
// Using ifFunction
console.log(Function.ifFunction(myFunction, 'Function', 'Not Function'));
// Output: 'Function'
console.log(Function.ifFunction(notFunction, 'Function', 'Not Function'));
// Output: 'Not Function'
Returns any Returns thenValue if value is a function, otherwise
returns elseValue.
The function checks if a given value is a generator function
value any The value parameter is the value that we want to
check if it is a generator function.Returns boolean true if the value is an instance of a function and
its string tag is 'GeneratorFunction', otherwise it returns false.
The ifGenerator method checks if a given value is a generator function
and returns one of two provided values based on the result. This method
is a convenience for performing conditional operations based on the
type of a value.
value any The value to be checked. If this is a generator
function, thenValue is returned, otherwise elseValue is returned.thenValue any The value to be returned if value is a generator
function.elseValue any The value to be returned if value is not a
generator function.// Suppose we have a generator function and a non-generator function
function* myGenerator() {}
function myFunction() {}
// Using ifGenerator
console.log(Function.ifGenerator(myGenerator, 'Generator', 'Not Generator'));
// Output: 'Generator'
console.log(Function.ifGenerator(myFunction, 'Generator', 'Not Generator'));
// Output: 'Not Generator'
Returns any Returns thenValue if value is a generator function,
otherwise returns elseValue.
This method modifies the behavior of the instanceof operator for a
given class. It does this by defining a custom Symbol.hasInstance
method on the class. The custom method checks if the string tag of the
instance matches the name of the class or if the instance is part of
the prototype chain of the class.
Class Function The class for which to modify the behavior
of the instanceof operator.// Suppose we have a class `MyClass`
class MyClass {}
// And an instance of the class
const myInstance = new MyClass();
// Before applying `StringTagHasInstance`, `instanceof` works as usual
console.log(myInstance instanceof MyClass); // Output: true
// Now we apply `StringTagHasInstance` to `MyClass`
FunctionExtensions.patches.StringTagHasInstance(MyClass);
// `instanceof` now checks the string tag and the prototype chain
console.log(myInstance instanceof MyClass); // Output: true
The FunctionExtensions class is a patch applied to the built-in JavaScript
Function constructor. It extends Function with additional utility methods
for determining the specific type or nature of function-like objects. These
methods allow developers to distinguish between classes, regular functions,
async functions, and arrow functions in a more intuitive and straightforward
manner. This class is part of the @nejs/extension library and enhances the
capabilities of function handling and introspection in JavaScript.
Determines if a given value is an asynchronous function. It checks if the
value is an instance of Function and if its string representation
includes the keyword 'Async'. This method is particularly useful for
identifying async functions.
Returns boolean Returns true if the value is an async function,
otherwise false.
The ifAsync method checks if the current function is asynchronous and
returns one of two provided values based on the result. This method is
a convenience for performing conditional operations based on the
type of a function.
thenValue any The value to be returned if the function is
asynchronous.elseValue any The value to be returned if the function is not
asynchronous.// Suppose we have an async function and a non-async function
async function myAsyncFunction() {}
function myFunction() {}
// Using ifAsync
console.log(myAsyncFunction.ifAsync('Async', 'Not Async'));
// Output: 'Async'
console.log(myFunction.ifAsync('Async', 'Not Async'));
// Output: 'Not Async'
Returns any Returns thenValue if the function is asynchronous,
otherwise returns elseValue.
The function checks if a given value is an async generator function
Returns boolean true if the value is an instance of a function and
its string tag is 'AsyncGeneratorFunction', otherwise it returns false.
The ifAsyncGenerator method checks if the current function is an
asynchronous generator and returns one of two provided values based on
the result. This method is a convenience for performing conditional
operations based on the type of a function.
thenValue any The value to be returned if the function is an
asynchronous generator.elseValue any The value to be returned if the function is not
an asynchronous generator.// Suppose we have an async generator function and a non-async function
async function* myAsyncGeneratorFunction() {}
function myFunction() {}
// Using ifAsyncGenerator
console.log(myAsyncGeneratorFunction.ifAsyncGenerator(
'Async Generator', 'Not Async Generator'
));
// Output: 'Async Generator'
console.log(myFunction.ifAsyncGenerator(
'Async Generator', 'Not Async Generator'
));
// Output: 'Not Async Generator'
Returns any Returns thenValue if the function is an asynchronous
generator, otherwise returns elseValue.
Checks if a given value is an arrow function. It verifies if the value is
an instance of Function, if its string representation includes the '=>'
symbol, and if it lacks a prototype, which is a characteristic of arrow
functions in JavaScript.
Returns boolean Returns true if the value is an arrow function,
otherwise false.
Checks if the current function is a "big arrow" function and returns one of two provided values based on the result.
A "big arrow" function is an arrow function that is not bound
to a specific context and does not have its own this value.
thenValue any The value to be returned if the function
is a "big arrow" function.elseValue any The value to be returned if the function
is not a "big arrow" function.// Suppose we have a "big arrow" function and a regular function
const bigArrowFn = () => {}
function regularFn() {}
// Using ifBigArrow
console.log(bigArrowFn.ifBigArrow('Big Arrow', 'Not Big Arrow'))
// Output: 'Big Arrow'
console.log(regularFn.ifBigArrow('Big Arrow', 'Not Big Arrow'))
// Output: 'Not Big Arrow'
Returns any Returns thenValue if the function is a "big arrow"
function, otherwise returns elseValue.
Determines if a given value is a bound function. Bound functions are
created using the Function.prototype.bind method, which allows setting
the this value at the time of binding. This method checks if the value
is an instance of Function, if its string representation starts with
'bound', and if it lacks a prototype property. These characteristics
are indicative of bound functions in JavaScript.
Returns boolean Returns true if the value is a bound function,
otherwise false. Bound functions have a specific format in their
string representation and do not have their own prototype property.
Checks if the current function is bound and returns one of two provided values based on the result.
A bound function is a function that has a fixed this value and
may have preset arguments. It is created using the
Function.prototype.bind method.
thenValue any The value to be returned if the function
is bound.elseValue any The value to be returned if the function
is not bound.// Suppose we have a bound function and a regular function
const boundFn = function() {}.bind(null)
function regularFn() {}
// Using ifBound
console.log(boundFn.ifBound('Bound', 'Not Bound'))
// Output: 'Bound'
console.log(regularFn.ifBound('Bound', 'Not Bound'))
// Output: 'Not Bound'
Returns any Returns thenValue if the function is bound,
otherwise returns elseValue.
Determines if a given value is a class. It checks if the value is an
instance of Function and if its string representation includes the
keyword 'class'. This method is useful for distinguishing classes from
other function types in JavaScript.
Returns boolean Returns true if the value is a class, otherwise
false.
Checks if the current function is a class and returns one of two provided values based on the result.
A class is a special type of function in JavaScript that is
defined using the class keyword. It serves as a blueprint for
creating objects and encapsulates data and behavior.
thenValue any The value to be returned if the function
is a class.elseValue any The value to be returned if the function
is not a class.// Suppose we have a class and a regular function
class MyClass {}
function myFunction() {}
// Using ifClass
console.log(MyClass.ifClass('Class', 'Not Class'))
// Output: 'Class'
console.log(myFunction.ifClass('Class', 'Not Class'))
// Output: 'Not Class'
Returns any Returns thenValue if the function is a class,
otherwise returns elseValue.
Checks if a given value is a regular function. This method verifies if
the value is an instance of Function, which includes regular functions,
classes, and async functions but excludes arrow functions.
Returns boolean Returns true if the value is a regular function,
otherwise false.
Checks if the current function is a regular function and returns one of two provided values based on the result.
A regular function is an instance of Function, which includes
regular functions, classes, and async functions but excludes
arrow functions.
thenValue any The value to be returned if the function
is a regular function.elseValue any The value to be returned if the function
is not a regular function.// Suppose we have a regular function and an arrow function
function regularFunction() {}
const arrowFunction = () => {}
// Using ifFunction
console.log(regularFunction.ifFunction('Regular', 'Not Regular'))
// Output: 'Regular'
console.log(arrowFunction.ifFunction('Regular', 'Not Regular'))
// Output: 'Not Regular'
Returns any Returns thenValue if the function is a regular
function, otherwise returns elseValue.
The function checks if a given value is a generator function
Returns boolean true if the value is an instance of a function and
its string tag is 'GeneratorFunction', otherwise it returns false.
Checks if the current function is a generator function and returns one of two provided values based on the result.
A generator function is a special type of function that can be paused and resumed, allowing it to yield multiple values over time rather than returning a single value.
thenValue any The value to be returned if the
function is a generator function.elseValue any The value to be returned if the
function is not a generator function.// Suppose we have a generator function and a regular function
function* generatorFunction() {
yield 1
yield 2
yield 3
}
function regularFunction() {}
// Using ifGenerator
console.log(generatorFunction.ifGenerator('Generator', 'Regular'))
// Output: 'Generator'
console.log(regularFunction.ifGenerator('Generator', 'Regular'))
// Output: 'Regular'
Returns any Returns thenValue if the function is a
generator function, otherwise returns elseValue.
Retrieves the properties of the current function and its prototype.
This method uses the getClassProperties function from the
FunctionExtensions.patches object to get all the properties of the
current function and its prototype. The properties include both
enumerable and non-enumerable properties, as well as properties
defined with symbols.
// Suppose we have a function with a property and a prototype property
function MyFunction() {}
MyFunction.myProp = 'hello';
MyFunction.prototype.myProtoProp = 'world';
// Using getClassProperties
const result = MyFunction.getClassProperties();
console.log(result);
// Output: [MyFunction, { myProp: { value: 'hello', writable: true,
// enumerable: true, configurable: true } }, MyFunction.prototype,
// { myProtoProp: { value: 'world', writable: true, enumerable: true,
// configurable: true } }]
Returns Array An array containing the function itself, its property descriptors, its prototype, and the prototype's property descriptors.
The isThenElse function is a utility function that behaves like a
ternary operator. It takes three arguments: boolValue, thenValue,
and elseValue.
It first checks the truthiness of boolValue.
If boolValue is truthy, it returns thenValue; otherwise,
it returns elseValue.
If thenValue or elseValue is a function, it will be invoked with
boolValue as an argument.
If elseValue is not provided, it returns boolValue or thenValue
depending on the truthiness of boolValue.
If only boolValue is provided, it simply returns boolValue.
boolValue any Any object or value that is tested for
truthiness.thenValue (function | any)? The value to return if boolValue
is truthy. If a function, it's invoked with boolValue.elseValue (function | any)? The value to return if boolValue
is falsy. If a function, it's invoked with boolValue.// Using values
isThenElse(true, 'yes', 'no'); // Returns: 'yes'
isThenElse(false, 'yes', 'no'); // Returns: 'no'
// Using functions
isThenElse(true, val => val ? 'yes' : 'no'); // Returns: 'yes'
isThenElse(false, val => val ? 'yes' : 'no'); // Returns: 'no'
Returns (boolean | any) The result of the ternary operation.
Transforms an object to mimic a specified prototype, altering its type conversion and inspection behaviors. This function is especially useful for creating objects that need to behave like different primitive types under various operations.
object Object The object to be transformed.classPrototype options prototype (Function | Object) The prototype or
class to emulate. If a function is provided, its prototype is used.
Defaults to String.prototype. (optional, default String.prototype)toPrimitive Function A function
defining how the object should be converted to a primitive value. It
receives a type hint ('number', 'string', or 'default') and the object,
returning the primitive value. (optional, default (hint,val)=>String(val))Returns (Object | null) The transformed object, or null if neither a class nor a prototype could be derived from the provided prototype parameter.
Masks an object as a string-like object by setting its prototype to String and defining how it converts to primitive types. This is particularly useful when an object needs to behave like a string in certain contexts, such as type coercion or logging.
object Object The object to be masked as a string.stringKey string The object property key used for
the string representation. Defaults to 'value'. (optional, default 'value')toPrimitive Function? Optional custom function for primitive
conversion. If omitted, a default function handling various conversion
hints is used.Returns (Object | null) The string-masked object, or null if the object doesn't have the specified stringKey property.
Masks an object as a number-like object. This allows the object to behave like a number in operations like arithmetic and type coercion. It sets the prototype to Number and defines custom conversion behavior.
object Object The object to be masked as a number
representation. Defaults to 'value'.numberKey toPrimitive Function? Optional custom function for primitive
conversion. If not provided, a default function handling different
conversion hints is used.Returns (Object | null) The number-masked object, or null if the object doesn't have the specified numberKey property.
Generates options for generic masking of an object, providing defaults for prototype and toPrimitive function if not specified.
options Object The options object including prototype,
targetKey, and toPrimitive function.
options.prototype options.targetKey (optional, default 'value')options.toPrimitive Returns Object The options object with defaults applied as necessary.
Generates options for string masking of an object, providing a default toPrimitive function if not specified.
targetKey string The object property key for string
representation.toPrimitive Function Custom function for primitive conversion.Returns Object Options for string masking.
Generates options for number masking of an object, providing a default toPrimitive function if not specified.
targetKey string The object property key for number
representation.toPrimitive Function Custom function for primitive conversion.Returns Object Options for number masking.
Blends the properties of multiple objects into a new object. This function creates a new object that inherits the prototype from the root object and the properties of the other objects and their parent prototypes.
root Object The root object to blend prototypes into.objects ...Object The objects whose prototypes to blend.// Define some objects with properties
const obj1 = { prop1: 'value1' }
const obj2 = { prop2: 'value2' }
const obj3 = { prop3: 'value3' }
// Blend the prototypes of obj2 and obj3 into obj1
const blended = blendProtos(obj1, obj2, obj3)
// Now blended has properties from obj1, obj2, and obj3
console.log(blended.prop1) // Outputs: 'value1'
console.log(blended.prop2) // Outputs: 'value2'
console.log(blended.prop3) // Outputs: 'value3'
Returns Object The new object with blended prototypes.
The extractFrom method attempts to extract a JSON object from a string.
It uses a regular expression to identify potential JSON objects in the
string and attempts to parse them. If a valid JSON object is found, it is
returned. If no valid JSON object is found, the method returns undefined.
NOTE: This method will only find JSON from an iterated upon start spot
until the end of the string. So 'JSON follows {"count": 0}' will
return {count: 0} but 'JSON follows {"count": 0} and more' will
fail to locate any JSON in the String. You've been warned.
string string The string from which to extract a JSON object.// Suppose we have a string with embedded JSON
const str1 = 'Hello {"name":"John", "age":30} World'
const str2 = 'Hello {"name": "John", "age": 30}'
// Using `extractFrom`
console.log(JSON.extractFrom(str1)) // Output: undefined
console.log(JSON.extractFrom(str2)) // Output: {name: 'John', age: 30}
Returns (Object | undefined) The first valid JSON object found in the string, or undefined if no valid JSON object is found.
The mightContain method checks if a string might contain a JSON object.
It uses the JSONStartPattern regular expression to search for potential
JSON objects in the string. If a potential JSON object is found, the method
returns true. If no potential JSON object is found, the method returns false.
string string The string to check for potential JSON objects.detail (optional, default false)// Suppose we have a string with embedded JSON
const str = 'Hello {"name":"John", "age":30} World'
// Using `mightContain`
console.log(JSON.mightContain(str)) // Output: true
Returns boolean Returns true if the string might contain a JSON object, false otherwise.
Getter method for the JSONStartPattern.
This method constructs a regular expression pattern that is used to identify potential JSON objects in a string. The pattern is designed to match various JSON data types including null, boolean, number, string, object, and array.
The pattern is constructed using an array of strings, each representing a part of the pattern. The array is then joined into a single string and passed to the RegExp constructor to create the pattern.
// Using `JSONStartPattern`
const pattern = JSONStartPattern;
const str = 'Hello {"name":"John", "age":30} World';
const match = pattern.exec(str);
console.log(match[0]); // Output: '{"name":"John", "age":30}'
Returns RegExp The constructed regular expression pattern.
Determines if the supplied value is a Map object. This check
is performed by first looking for the Symbol.toStringTag on the
value and checking to see if it is equal to the string "Map".
If that check fails, instanceof is used as a fallback to check
the prototype chain.
value any the value that needs to be checked to determine
if it is a Map object or notconst map = new Map()
isMap(map) // true
isMap(new Set()) // false
isMap([]) // false
isMap({}) // false
Returns boolean true if the supplied value is a Map
object, false otherwise
Conditionally returns a value based on whether the supplied
value is a Map object or not. If the value is a Map
object, the thenValue will be returned. If it is not a Map
object, the elseValue will be returned instead.
value any the value to check to determine if it is a
Map objectthenValue any the value to return if the supplied
value is a Map objectelseValue any the value to return if the supplied
value is not a Map objectconst map = new Map()
const set = new Set()
ifMap(map, 'is a map', 'not a map') // 'is a map'
ifMap(set, 'is a map', 'not a map') // 'not a map'
Returns any either the thenValue or elseValue depending
on if the supplied value is a Map object
Determines if the current object is a Map object
This is a getter that uses the isMap function from the
MapExtensions patch to check if the current object (this) is
a Map object
Type: boolean
const map = new Map()
console.log(map.isMap) // Output: true
const notMap = {}
console.log(notMap.isMap) // Output: false
Conditionally returns a value based on whether the current
object is a Map object or not
If the current object is a Map object, the thenValue will
be returned. If it is not a Map object, the elseValue will
be returned instead.
thenValue any the value to return if the current
object is a Map objectelseValue any the value to return if the current
object is not a Map objectconst map = new Map()
map.ifMap('is a map', 'not a map') // 'is a map'
const notMap = {}
notMap.ifMap('is a map', 'not a map') // 'not a map'
Returns any either the thenValue or elseValue depending
on if the current object is a Map object
The function getKey returns the key associated with a given value
in a map.
value any The value parameter is the value that you want to
find the corresponding key for in the map.strict The "strict" parameter is a boolean value that
determines whether strict equality (===) or loose equality (==) should
be used when comparing the "value" parameter with the values in the
entries of the object. If "strict" is set to true, strict equality will
be used. (optional, default true)Returns any the key associated with the given value. If a matching key is found, it is returned. If no matching key is found, null is returned.
Determines if the supplied value is a Number. This check is
performed by first converting the value to a Number using the
Number() constructor and checking to see if the result is not
NaN. If that check passes, typeof is used to ensure that the
original value is of type "number".
value any The value that needs to be checked to determine if it
is a Number or notconst num = 42
isNumber(num) // true
isNumber('42') // false
isNumber(NaN) // false
isNumber(Infinity) // true
Returns boolean true if the supplied value is a Number,
false otherwise
Checks if all or some of the supplied values are numbers.
This method uses the Array.prototype.every or Array.prototype.some
method to check if all or some of the supplied values are numbers,
respectively. The method to use is determined by the which parameter.
which string Determines the method to use for the
check. Can be either 'every' or 'some'. Defaults to 'every'. (optional, default 'every')values ...any The values to check.areNumbers('every', 1, 2, 3) // true
areNumbers('some', 1, '2', 3) // true
areNumbers('every', 1, '2', 3) // false
Returns boolean Returns true if all or some of the values are
numbers (based on the which parameter), false otherwise.
Conditionally returns a value based on whether the supplied value is
a Number or not. If the value is a Number, the thenValue will
be returned. If it is not a Number, the elseValue will be
returned instead.
value any The value to check to determine if it is a NumberthenValue any The value to return if the supplied value is
a NumberelseValue any The value to return if the supplied value is
not a Numberconst num = 42
const str = 'hello'
ifNumber(num, 'is a number', 'not a number') // 'is a number'
ifNumber(str, 'is a number', 'not a number') // 'not a number'
Returns any Either the thenValue or elseValue depending on if the
supplied value is a Number
Conditionally returns a value based on whether all or some of the supplied values are numbers.
This method uses the areNumbers method to check if all or some of
the supplied values are numbers, based on the which parameter.
If the condition is met, the thenValue is returned, otherwise
the elseValue is returned.
thenValue any The value to return if the condition is met.elseValue any The value to return if the condition is not met.which string Determines the method to use for the
check. Can be either 'every' or 'some'. Defaults to 'every'. (optional, default 'every')numbers ...any The values to check.ifNumbers('All are numbers', 'Not all are numbers', 'every', 1, 2, 3)
// returns 'All are numbers'
ifNumbers('At least one is a number', 'None are numbers', 'some', 1, '2', 3)
// returns 'At least one is a number'
ifNumbers('All are numbers', 'Not all are numbers', 'every', 1, '2', 3)
// returns 'Not all are numbers'
Returns any Either the thenValue or elseValue depending on if all
or some of the supplied values are numbers.
Clamps a value between a minimum and maximum value.
This method checks if the provided value and the min and max bounds are numbers. If they are not, it returns the original value. If they are, it ensures that the value does not go below the minimum value or above the maximum value.
value any The value to clamp.minValue number The minimum value. Defaults
to -Infinity. (optional, default -Infinity)maxValue number The maximum value. Defaults
to Infinity. (optional, default Infinity)clamp(10, 1, 5) // returns 5
clamp(-10, 1, 5) // returns 1
clamp(3, 1, 5) // returns 3
clamp('10', 1, 5) // returns '10'
Returns any Returns the clamped value if all parameters are numbers, otherwise returns the original value.
A patch for the JavaScript built-in Number class that adds utility
methods without modifying the global namespace directly
This patch includes methods for checking if a value is a number and conditionally returning a value based on whether the supplied value is a number or not.
Type: Patch
import { NumberExtensions } from 'number.extension.js'
NumberExtensions.apply()
// Now the `Number` class has additional methods available
Returns an object representation of the number instance.
This getter method creates and returns an object that wraps the number
instance, allowing it to be treated as an object. The returned object
is created using the Object() constructor, which takes the number
instance as its argument.
Type: Object
const num = 42
console.log(typeof num) // 'number'
console.log(typeof num.instance) // 'object'
Determines if the current object is a number
This getter uses the pIsNumber function from the NumberExtensions
patch to check if the current object (this) is a number.
Type: boolean
const num = 42
console.log(num.isNumber) // Output: true
const notNum = "123"
console.log(notNum.isNumber) // Output: false
Checks if the current object is a number and returns the corresponding value based on the result.
This method uses the pIfNumber function from the NumberExtensions
patch to determine if the current object (this) is a number. If it is
a number, the thenValue is returned. Otherwise, the elseValue is
returned.
thenValue any The value to return if the current object is
a numberelseValue any The value to return if the current object is not
a numberconst num = 42
console.log(num.ifNumber('Is a number', 'Not a number'))
// Output: 'Is a number'
const notNum = '123'
console.log(notNum.ifNumber('Is a number', 'Not a number'))
// Output: 'Not a number'
Returns any The thenValue if the current object is a number, or
the elseValue if it is not a number
NumberPrototypeExtensions provides a set of utility methods that
are added to the Number prototype. This allows all number instances
to access new functionality directly, enhancing their capabilities
beyond the standard Number class methods.
These extensions are applied using the Patch class from
'@nejs/extension', ensuring that they do not interfere with the
global namespace or existing properties.
The extensions include methods for checking if a value is a number, conditionally returning values based on whether a value is a number, and more, making number-related tasks more convenient and expressive.
Type: Patch
const num = 42
console.log(num.isNumber) // Output: true
const notNum = "123"
console.log(notNum.isNumber) // Output: false
ObjectExtensions is a constant that applies a patch to the global
Object constructor. This patch extends the Object with additional
methods and properties, enhancing its functionality.
The Patch function takes two arguments: the target object to be patched
(in this case, Object), and an object containing the methods and
properties to be added to the target object.
Type: Patch
ObjectPrototypeExtensions is a constant that applies a patch to the
Object prototype. This patch extends the Object prototype with additional
methods and properties, enhancing its functionality.
The Patch function takes two arguments: the target object to be patched
(in this case, Object.prototype), and an object containing the methods
and properties to be added to the target object.
Type: Patch
// Using a method added by ObjectPrototypeExtensions
const obj = {};
console.log(obj.isObject()); // Output: true
Creates a shallow copy of the provided object(s).
This method uses the copyObject function with the deep parameter
set to false, indicating a shallow copy. It takes a destination
object and any number of source objects, and copies the properties
from the source objects to the destination object. If a property
already exists on the destination object, it will be overwritten.
Note: This method does not copy nested objects or arrays. They are
copied by reference, not by value. To create a deep copy, use the
deepCopy method instead.
destination object The object to which properties will be
copied.sources ...object The source object(s) from which
properties will be copied.const obj1 = { a: 1, b: 2 };
const obj2 = { b: 3, c: 4 };
const result = ObjectExtensions.copy(obj1, obj2);
console.log(result); // Output: { a: 1, b: 3, c: 4 }
Returns object The destination object with the copied properties.
Creates a deep copy of the provided object(s).
This method uses the copyObject function with the deep parameter
set to true, indicating a deep copy. It takes a destination
object and any number of source objects, and copies the properties
from the source objects to the destination object. If a property
already exists on the destination object, it will be overwritten.
Note: This method copies nested objects or arrays by value, not by
reference. To create a shallow copy, use the copy method instead.
destination object The object to which properties will be
copied.sources ...object The source object(s) from which
properties will be copied.const obj1 = { a: 1, b: { c: 2 } };
const obj2 = { b: { d: 3 }, e: 4 };
const result = ObjectExtensions.deepCopy(obj1, obj2);
console.log(result); // Output: { a: 1, b: { d: 3 }, e: 4 }
Returns object The destination object with the copied properties.
A getter property that provides access to the definition types used for object property definitions. These types are used to control the visibility and mutability of object properties.
// Get the symbol for a mutably hidden property
const hiddenSymbol = Object.definitionType.mutablyHidden;
// Define a new mutably hidden property on an object
Object.define(myObject, 'myProperty', myValue, hiddenSymbol);
Returns Object An object with getter properties for each definition
type. The properties are:* mutablyHidden: A symbol representing a mutably hidden property,
non-enumerable, but configurable.
mutablyVisible: A symbol representing a mutably visible property,
enumerable, configurableimmutablyHidden: A symbol representing an immutably hidden property,
non-enumerable, non-configurable.immutablyVisible: A symbol representing an immutably visible
property, enumerable, non-configurable.Defines a new property on an object with a specified value and visibility/mutability flag. The flag determines the visibility and mutability of the property. By default, the property is defined as mutably hidden.
object object The object on which to define the property.key string The name of the property to be defined.value any The value of the property to be defined.flag symbol The
visibility/mutability flag for the property. This should be one of the
symbols available in ObjectExtensions.definitionType. (optional, default Object.definitionType.mutablyHidden)// Define a new mutably hidden property on an object
const myObject = {};
const myValue = 'Hello, world!';
const hiddenSymbol = Object.definitionType.mutablyHidden;
Object.define(myObject, 'myProperty', myValue, hiddenSymbol);
// myObject now has a mutably hidden property 'myProperty' with value
// 'Hello, world!'
Returns object The object with the newly defined property.
Defines a new accessor property on an object with specified getter and setter functions and a visibility/mutability flag. The flag determines the visibility and mutability of the property. By default, the property is defined as mutably hidden.
object object The object on which to define the property.key string The name of the property to be defined.get function The getter function for the property.set function The setter function for the property.flag symbol The
visibility/mutability flag for the property. This should be one of the
symbols available in ObjectExtensions.definitionType. (optional, default Object.definitionType.mutablyHidden)// Define a new mutably hidden accessor property on an object
const myObject = {};
const hiddenSymbol = ObjectExtensions.definitionType.mutablyHidden;
ObjectExtensions.defineAccessor(
myObject,
'myProperty',
() => 'Hello, world!',
(value) => console.log(`Setting value: ${value}`),
hiddenSymbol
);
// myObject now has a mutably hidden property 'myProperty' with getter
// and setter functions
Returns object The object with the newly defined property.
Creates a new object from an array of key-value pairs (entries), with an optional prototype and reducer function. If no prototype is provided, the default Object.prototype is used. If no reducer is provided, a default reducer is used that assigns each value to its corresponding key.
entries Array An array of key-value pairs. Each entry should
be an array where the first element is the key and the second element is
the value. Non-conforming entries are ignored.prototype object The prototype to use for
the new object. If not provided, Object.prototype is used. (optional, default Object.prototype)reducer Function? An optional reducer function to use when
creating the new object. If not provided, a default reducer is used that
assigns each value to its corresponding key. (optional, default undefined)// Create an object with a custom prototype and reducer
const myPrototype = { foo: 'bar' };
const myReducer = (obj, [key, value]) => {
obj[key] = value.toUpperCase();
return obj;
};
const myEntries = [['name', 'John'], ['age', '30']];
const myObject = Object.fromEntriesUsing(
myEntries, myPrototype, myReducer
);
// myObject is now { name: 'JOHN', age: '30' }
// with prototype { foo: 'bar' }
Returns (object | undefined) The new object created from the entries, or undefined if the entries array is not valid or contains no valid entries.
Retrieves the prototype chain entries of a given object.
This method traverses the prototype chain of the provided object and collects an array of entries. Each entry is a pair consisting of the prototype object and its property descriptors.
The property descriptors are obtained using the Reflect.ownKeys
method and the Object.getOwnPropertyDescriptor function.
object Object The object whose prototype chain entries are
to be retrieved.const obj = Object.create({ foo: 'bar' });
console.log(getPrototypeChainEntries(obj));
// Output: [[{ foo: 'bar' }, { foo: { value: 'bar', writable: true,
// enumerable: true, configurable: true } }], [Object.prototype, { ... }]]
Returns Array An array of entries, where each entry is a pair consisting of a prototype object and its property descriptors.
Retrieves the string tag of an object. The string tag is a representation
of the object's type, as defined by its Object.prototype.toString
method. This utility method is helpful for getting a more descriptive
type of an object than what is returned by the typeof operator,
especially for custom objects.
value any The object whose string tag is to be retrieved.strict boolean if this is set to true, undefined will be
returned whenever a supplied object does not have a
Symbol.toStringTag defined, period. if false, the default, (optional, default false)Returns string The string tag of the object, indicating its type.
Determines the type of the given value based on its string tag. This method
uses Object.getStringTag to obtain the string tag of the value, which
represents its more specific type (e.g., Array, Map, Set) rather than just
'object'. The method then maps this string tag to the corresponding type
present in the provided owner object, which defaults to globalThis.
This utility method is especially useful for identifying the specific
constructor or class of an object, beyond the basic types identified by
the typeof operator.
value any The value whose type is to be determined.owner object The object in which to look up the
constructor corresponding to the string tag. Defaults to globalThis,
which covers global constructors like Array, Object, etc. (optional, default globalThis)Returns (Function | object | null | undefined) Returns the constructor or
type of the value based on its string tag. For 'Null' and 'Undefined',
it returns null and undefined, respectively. For other types, it
returns the corresponding constructor (e.g., Array for arrays) if
available in the owner object.
Checks to see if the supplied value is both an object, and has the
appropriate symbol defined.
value any the value to determine if it contains a defined
Symbol.toStringTag defined.Returns any true if the symbol is defined, false otherwise
The function checks if a value is either undefined or null.
value any The parameter "value" is a variable that can hold
any value.Returns boolean true if the value is either undefined or null,
and false otherwise.
The ifNullDefined function checks if a given value is either null or
undefined and returns one of two provided values based on the result.
This function is a convenience method for performing conditional
operations based on the type of a value.
value any The value to be checked. If this is either null
or undefined, thenValue is returned, otherwise elseValue
is returned.thenValue (function | any) The value to be returned if value
is either null or undefined.elseValue (function | any) The value to be returned if value
is not either null or undefined.// Suppose we have a null value and a defined value
let nullValue = null;
let definedValue = "I'm defined";
// Using ifNullDefined
// Output: 'Null or Undefined'
console.log(
Object.ifNullDefined(nullValue, 'Null or Undefined', 'Defined')
);
// Output: 'Defined'
console.log(
Object.ifNullDefined(definedValue, 'Null or Undefined', 'Defined')
);
Returns any Returns thenValue if value is either null or
undefined, otherwise returns elseValue.
Checks if the provided value is an object.
This function checks if the provided value is an instance of an Object or if the value is truthy and its type is 'object'. This is used to determine if a value can have properties and methods like an object.
value any The value to be checked.// Using a string
console.log(isObject('Hello, world!')); // Output: false
// Using an object
console.log(isObject({ key: 'value' })); // Output: true
// Using null
console.log(isObject(null)); // Output: false
Returns boolean Returns true if the value is an object, false
otherwise.
Determines if the provided value is an object. This method checks whether
the value is an instance of Object or if its type is 'object'. It's a
utility method for type-checking, ensuring that a value is an object
before performing operations that are specific to objects.
value any the value to test to see if it is a primitive value typeReturns boolean Returns true if the value is an object,
otherwise false.
},
isObject(value) {
return value && (value instanceof Object || typeof value === 'object');
},/**
Checks to see if the supplied value is a primitive value.
Returns any true if the object is considered widely to be a primitive value, false otherwise.
Executes a conditional function based on whether the provided value is
primitive or not. This method first checks if the value is primitive
using the isPrimitive method. If it is, it returns the thenValue,
otherwise it returns the elseValue.
value any The value to be checked.thenValue (function | any) The value to return if value is
primitive.elseValue (function | any) The value to return if value is
not primitive.// returns 1
ifPrimitive('hello', 1, 2)
// returns 2
ifPrimitive({a: 'hello'}, 1, 2)
Returns any Returns thenValue if the value is primitive, otherwise
elseValue.
Checks if the given value is a valid key for an object. In JavaScript, a valid key can be either a string or a symbol. This method is useful for validating object keys before using them in operations like setting or getting object properties.
value any The value to be checked.Returns boolean Returns true if the value is a valid object key
(string or symbol), otherwise false.
Executes a conditional function based on whether the provided
value is a valid key for an object. This method first checks if
the value is a valid key using the isValidKey method. If it is,
it returns the thenValue, otherwise it returns the elseValue.
value any The value to be checked.thenValue (function | any) The value to return if
value is a valid key.elseValue (function | any) The value to return if
value is not a valid key.// returns 1
ifValidKey('name', 1, 2)
// returns 2
ifValidKey(123, 1, 2)
Returns any Returns thenValue if the value is a valid key,
otherwise elseValue.
A symbol constant defined on Object that can be used to reference storage for an accessor descriptor created with Object.add() or other descriptor assigning and creation methods used by this extension.
The value assigned here is actually another symbol but one generated by Symkeys for uniqueness and has access to data storage.
// returns Symbol(@nejs.object.descriptor.storage)
kDescriptorStore
// add descriptor value to an object
const object = {}
Object.add({object, key: 'name', type: 'accessor'})
object.name = 'Jane Doe'
// Value assigned here is another symbol with its own storage generated
// by Symkeys. Description might be '@nejs.descriptor.store #234sdafj'
object[Object.kDescriptorStore]
// But its nested data can be accessed using the '.data' getter
object[Object.kDescriptorStore].data // { name: 'Jane Doe' }
Returns Symbol Returns a symbol for the descriptor storage.
Creates an object with predefined keys and descriptors. This method is useful for creating objects with specific properties and behaviors.
keys (Array | Object) An array of keys or an object where keys
are the object's own properties. If an array is provided, each key will
be assigned the defaultValue. If an object is provided, its own
properties will be used as keys and their corresponding values as values.defaultValue any The default value for each key. (optional, default undefined)definedAs string Defines how the properties are
defined. If 'data', properties are defined with a value. If 'accessor',
properties are defined with get and set accessors. (optional, default 'data')accessorMeta Object An object containing the get and set accessors
and the thisArg to bind to the accessors. (optional, default {get:undefined,set:undefined, thisArg:undefined})descriptorBase Object The base descriptor for the properties. (optional, default {enumerable:true,configurable:true})extraDescriptors Object Extra descriptors to be
added to the object. (optional, default undefined)prototype Object The prototype of the
created object. (optional, default Object.prototype)// returns { name: undefined }
prekeyed(['name'])
// returns { name: 'John' }
prekeyed({ name: 'John' })
// returns { name: 'John' }
prekeyed(['name'], 'John')
Returns Object Returns the created object.
Strips an object down to only the keys specified. Optionally, any accessors can be made to retain their context on the source object.
object object the object to pare downkeys Array<(string | symbol)> the keys that should appear in the
final reduced objectbindAccessors boolean if this value is true then any
accessors from the source object will continue to have their this
value bound to the source. If the getter or setter on that object is
defined using an arrow function, this will not work as intended. (optional, default true)Returns object an object containing only the keys and symbols
specified in the keys parameter.
Retrieves the prototype chain entries of the current object.
This method traverses the prototype chain of the current object
(this) and collects an array of entries. Each entry is a pair
consisting of the prototype object and its property descriptors.
The property descriptors are obtained using the Reflect.ownKeys
method and the Object.getOwnPropertyDescriptor function.
const obj = Object.create({ foo: 'bar' });
console.log(obj.getPrototypeChainEntries());
// Output: [[{ foo: 'bar' }, { foo: { value: 'bar', writable: true, enumerable: true, configurable: true } }], [Object.prototype, { ... }]]
Returns Array An array of entries, where each entry is a pair consisting of a prototype object and its property descriptors.
Checks to see if the supplied value is both an object, and has the
appropriate symbol defined.
value any the value to determine if it contains a defined
Symbol.toStringTag defined.Returns any true if the symbol is defined, false otherwise
Retrieves the string tag of an object. The string tag is a representation
of the object's type, as defined by its Object.prototype.toString
method. This utility method is helpful for getting a more descriptive
type of an object than what is returned by the typeof operator,
especially for custom objects.
strict boolean if this is set to true, undefined will be
returned whenever a supplied object does not have a
Symbol.toStringTag defined, period. if false, the default, (optional, default false)value any The object whose string tag is to be retrieved.Returns string The string tag of the object, indicating its type.
Strips an object down to only the keys specified. Optionally, any accessors can be made to retain their context on the source object. This is a passthrough to the static Object.stripTo function
keys Array<(string | symbol)> the keys that should appear in the
final reduced objectbindAccessors boolean if this value is true then any
accessors from the source object will continue to have their this
value bound to the source. If the getter or setter on that object is
defined using an arrow function, this will not work as intended. (optional, default true)Returns object an object containing only the keys and symbols
specified in the keys parameter.
Determines if the current value is an object.
This method checks whether the current value is an object,
excluding null. It is a convenience wrapper around the
pIsObject function from the ObjectExtensions patch.
Type: function
const obj = {};
console.log(obj.isObject());
// Output: true
const str = "hello";
console.log(str.isObject());
// Output: false
console.log(null.isObject());
// Output: false
Returns boolean true if the current value is an object
(excluding null), false otherwise.
Checks if the current value is an object and returns one of two provided values based on the result. This function is a convenience method for performing conditional operations based on the type of the current value.
Type: function
thenValue (function | any) The value to be returned if the
current value is an object (excluding null).elseValue (function | any) The value to be returned if the
current value is not an object or is null.const obj = {};
console.log(obj.ifObject('Object', 'Not an object'));
// Output: 'Object'
const str = "hello";
console.log(str.ifObject('Object', 'Not an object'));
// Output: 'Not an object'
console.log(null.ifObject('Object', 'Not an object'));
// Output: 'Not an object'
Returns any Returns thenValue if the current value is an object
(excluding null), otherwise returns elseValue.
Checks if the current value is either null or undefined.
Type: boolean
const obj = null;
console.log(obj.isNullDefined);
// Output: true
const str = "hello";
console.log(str.isNullDefined);
// Output: false
Returns boolean Returns true if the current value is either
null or undefined, false otherwise.
Checks if the current value is either null or undefined and
returns one of two provided values based on the result.
Type: function
thenValue (function | any) The value to be returned if the
current value is either null or undefined.elseValue (function | any) The value to be returned if the
current value is not null or undefined.const obj = null
console.log(obj.ifNullDefined('Null or Undefined', 'Defined'))
// Output: 'Null or Undefined'
const str = "hello"
console.log(str.ifNullDefined('Null or Undefined', 'Defined'))
// Output: 'Defined'
Returns any Returns thenValue if the current value is either
null or undefined, otherwise returns elseValue.
Checks if the current value is a primitive type.
Primitive types in JavaScript include string, number,
bigint, boolean, undefined, symbol, and null.
Type: boolean
const str = "hello"
console.log(str.isPrimitive)
// Output: true
const obj = { key: "value" }
console.log(obj.isPrimitive)
// Output: false
Returns boolean Returns true if the current value is a
primitive type, false otherwise.
Checks if the current value is a primitive type and returns one of two provided values based on the result.
Primitive types in JavaScript include string, number,
bigint, boolean, undefined, symbol, and null.
Type: function
thenValue (function | any) The value to be returned if
the current value is a primitive type.elseValue (function | any) The value to be returned if
the current value is not a primitive type.const str = "hello"
console.log(str.ifPrimitive('Primitive', 'Not Primitive'))
// Output: 'Primitive'
const obj = { key: "value" }
console.log(obj.ifPrimitive('Primitive', 'Not Primitive'))
// Output: 'Not Primitive'
Returns any Returns thenValue if the current value is a
primitive type, otherwise returns elseValue.
Determines if the current value is a valid key for an object.
A valid key is either a string or a symbol. This method is a
convenience wrapper around the pIsValidKey function from the
ObjectExtensions patch.
Type: boolean
const str = "key"
console.log(str.isValidKey)
// Output: true
const sym = Symbol("key")
console.log(sym.isValidKey)
// Output: true
const num = 42
console.log(num.isValidKey)
// Output: false
Returns boolean true if the current value is a valid key for
an object (i.e., a string or symbol), false otherwise.
Checks if the current value is a valid key for an object and returns one of two provided values based on the result. This function is a convenience method for performing conditional operations based on the type of the current value.
A valid key is either a string or a symbol.
Type: function
thenValue (function | any) The value to be returned if the
current value is a valid key for an object.elseValue (function | any) The value to be returned if the
current value is not a valid key for an object.const str = "key"
console.log(str.ifValidKey('Valid Key', 'Not a Valid Key'))
// Output: 'Valid Key'
const num = 42
console.log(num.ifValidKey('Valid Key', 'Not a Valid Key'))
// Output: 'Not a Valid Key'
Returns any Returns thenValue if the current value is a valid key
for an object, otherwise returns elseValue.
Creates a deep or shallow copy of the provided source objects and merges them into the destination object. The function uses a Set to keep track of visited objects to avoid circular references.
deep boolean If true, performs a deep copy, otherwise performs
a shallow copy.destination object The object to which properties will be copied.sources ...object The source object(s) from which properties
will be copied.// Shallow copy
const obj1 = { a: 1, b: { c: 2 } };
const obj2 = { b: { d: 3 }, e: 4 };
const result = copyObject(false, obj1, obj2);
console.log(result); // Output: { a: 1, b: { d: 3 }, e: 4 }
// Deep copy
const obj1 = { a: 1, b: { c: 2 } };
const obj2 = { b: { d: 3 }, e: 4 };
const result = copyObject(true, obj1, obj2);
console.log(result); // Output: { a: 1, b: { c: 2, d: 3 }, e: 4 }
Returns object The destination object with the copied properties.
The ReflectExtensions class is a patch applied to the built-in JavaScript
Reflect object. It extends Reflect with additional utility methods that
enhance its capabilities. These methods provide more advanced ways of
interacting with object properties, such as checking for the presence of
multiple keys at once (hasAll) or verifying if at least one specified key
exists in an object (hasSome). This class is part of the @nejs/extension
library and is designed to offer these extended functionalities in a way
that is consistent with the existing Reflect API, making it intuitive for
developers who are already familiar with standard reflection methods in
JavaScript.
The function checks if an object has all the specified keys.
object The object parameter is the object that we want to
check if it has all the specified keys.keys ...any The keys parameter is a rest parameter, which means
it can accept any number of arguments. In this case, it is expected
to receive multiple keys as arguments.Returns any a boolean value.
The function checks if an object has at least one of the specified keys.
object The object parameter is the object that we want to check
for the presence of certain keys.keys ...any The keys parameter is a rest parameter, which means it can
accept any number of arguments. These arguments are the keys that we want
to check if they exist in the object.Returns any The function hasSome returns a boolean value indicating whether
at least one of the keys provided as arguments exists in the given object.
The metadata method retrieves metadata about a property of an object.
It returns an object containing information about the property, such as
its value, descriptor, and whether it is read-only, assignable, an
accessor, or a data descriptor.
key string The name of the property.owner object The object that owns the property.
If not provided, it defaults to the global object. (optional, default globalThis)const obj = { foo: 'bar' }
const meta = ReflectExtensions.metadata('foo', obj)
console.log(meta.value) // Outputs: 'bar'
console.log(meta.isReadOnly) // Outputs: false
Returns (object | undefined) An object containing metadata about the
property, or undefined if the property does not exist or the owner is
not an object.
Fetches all descriptors of an object, including those mapped to a symbol descriptor value.
object object the object from whose descriptors need to be
retrieved.object is null or not an object
a TypeError exception will be thrownReturns object with keys mapped to object descriptors
Retrieves an array of [key, descriptor] pairs for each property of the
provided object. This method is akin to Object.entries but includes
property descriptors instead of the property values. It's useful for cases
where you need detailed information about properties, including their
configurability, enumerability, and accessors.
object object The object whose property entries are to be
retrieved.Returns Array An array of [key, descriptor] pairs, where each pair consists of the property name (key) and its descriptor. Returns an empty array if the input is not a valid object.
Retrieves an array of values from the property descriptors of the given
object. This method works similarly to Object.values but operates on
property descriptors instead. It's useful when you need the values of
properties including getters, setters, and other descriptor-specific
attributes.
object object The object whose property values are to be
retrieved.Returns Array An array of values extracted from the object's property
descriptors. The values correspond to the value attribute in each
property's descriptor. Returns an empty array if the input is not a valid
object.
A getter method that returns the owner of the property. The owner is the object that owns the property.
const obj = { foo: 'bar' }
const meta = Reflect.metadata('foo', obj)
console.log(meta.owner) // Outputs: obj
Returns object The owner of the property.
A getter method that returns the key of the property. The key is the name of the property.
const obj = { foo: 'bar' }
const meta = Reflect.metadata('foo', obj)
console.log(meta.key) // Outputs: 'foo'
Returns string The key of the property.
A getter method that returns the value of the property.
The value is obtained by invoking the value function.
const obj = { foo: 'bar' }
const meta = Reflect.metadata('foo', obj)
console.log(meta.value) // Outputs: 'bar'
Returns any The value of the property.
A getter method that returns the descriptor of the property. The descriptor is an object that describes a property's configuration. It includes properties like value, writable, enumerable, configurable, get, and set.
const obj = { foo: 'bar' }
const meta = Reflect.metadata('foo', obj)
console.log(meta.descriptor)
// Outputs: {
// value: 'bar',
// writable: true,
// enumerable: true,
// configurable: true
// }
Returns object The descriptor of the property.
A getter method that checks if the property is read-only. A property is considered read-only if it is an accessor property (i.e., it has a getter or a setter) and it does not have a setter. This means that the property can be read, but not written to.
const obj = {
get foo() { return 'bar' }
}
const meta = Reflect.metadata('foo', obj)
console.log(meta.isReadOnly) // Outputs: true
Returns boolean true if the property is read-only,
false otherwise.
A getter method that checks if the property is assignable. A property is considered assignable if it is either configurable or writable. Configurable properties can be modified and deleted, while writable properties can have their values changed.
const obj = { foo: 'bar' }
const meta = Reflect.metadata('foo', obj)
console.log(meta.isAssignable) // Outputs: true
Returns boolean true if the property is assignable,
false otherwise.
A getter method that checks if the property is an accessor.
An accessor property is a property that has a getter method, a setter
method, or both. This method returns true if the property has either
a getter or a setter, and false otherwise.
const obj = {
get foo() { return 'bar' },
set foo(value) { console.log('Setting foo to', value) }
}
const meta = Reflect.metadata('foo', obj)
console.log(meta.isAccessor) // Outputs: true
Returns boolean true if the property is an accessor,
false otherwise.
A getter method that checks if the property is a data property.
A data property is a property that has a value and can be written to.
This method returns true if the property has a value or is writable,
and false otherwise.
const obj = { foo: 'bar' }
const meta = Reflect.metadata('foo', obj)
console.log(meta.isData) // Outputs: true
Returns boolean true if the property is a data property,
false otherwise.
Generates a regular expression pattern that matches any character.
This method creates a regular expression pattern that matches any character. The pattern can be configured to be greedy or non-greedy, and to include or exclude newline characters.
greedy boolean If true, the pattern will be greedy,
meaning it will match as many characters as possible. If false, the
pattern will be non-greedy, meaning it will match as few characters
as possible. (optional, default false)includeNewlines boolean If true, the pattern will
include newline characters ('\n' and '\r'). If false, newline
characters will be excluded from the pattern. (optional, default false)// Generate a non-greedy pattern that excludes newlines
console.log(anything()) // Output: '[.]*?'
// Generate a greedy pattern that includes newlines
console.log(anything(true, true)) // Output: '[.\\n\\r]*'
Returns string The generated regular expression pattern.
Creates a non-capturing group in a regular expression.
This method wraps the provided string in a non-capturing group,
which is denoted by the syntax (?:...) in a regular expression.
Non-capturing groups match the pattern inside the group but do not
capture the matched content for later use.
string string The string to be wrapped in a non-capturing group.// Suppose we have a string 'abc'
const str = 'abc'
// Using `nonCaptureGroup`
console.log(nonCaptureGroup(str)) // Output: '(?:abc)'
Returns string The string wrapped in a non-capturing group.
Creates a capturing group in a regular expression.
This method wraps the provided string in a capturing group,
which is denoted by the syntax (...) in a regular expression.
Capturing groups match the pattern inside the group and capture
the matched content for later use.
string string The string to be wrapped in a capturing group.// Suppose we have a string 'abc'
const str = 'abc'
// Using `captureGroup`
console.log(captureGroup(str)) // Output: '(abc)'
Returns string The string wrapped in a capturing group.
Creates a regular expression pattern that matches any one of the provided strings.
This method takes any number of strings as arguments, and returns a string that represents a regular expression pattern. The pattern matches any one of the provided strings. The strings are joined together with the '|' character, which represents the OR operator in regular expressions.
strings ...string The strings to be included in the pattern.// Suppose we have strings 'abc', 'def', and 'ghi'
const str1 = 'abc'
const str2 = 'def'
const str3 = 'ghi'
// Using `oneOf`
console.log(oneOf(str1, str2, str3)) // Output: 'abc|def|ghi'
Returns string A string representing a regular expression pattern that matches any one of the provided strings.
Creates a regular expression pattern that matches zero or more occurrences of the provided string.
This method wraps the provided string in a non-capturing group,
which is denoted by the syntax (?:...) in a regular expression,
and appends the * character, which represents zero or more
occurrences in regular expressions.
string string The string to be matched zero or more times.// Suppose we have a string 'abc'
const str = 'abc'
// Using `zeroOrMore`
console.log(zeroOrMore(str)) // Output: '(?:abc)*'
Returns string A string representing a regular expression pattern that matches zero or more occurrences of the provided string.
Creates a regular expression pattern that matches zero or one occurrence of the provided string.
This method wraps the provided string in a non-capturing group,
which is denoted by the syntax (?:...) in a regular expression,
and appends the ? character, which represents zero or one
occurrence in regular expressions.
string string The string to be matched zero or one time.// Suppose we have a string 'abc'
const str = 'abc'
// Using `zeroOrOne`
console.log(zeroOrOne(str)) // Output: '(?:abc)?'
Returns string A string representing a regular expression pattern that matches zero or one occurrence of the provided string.
Escapes special characters in a string for use in a regular expression.
This method checks if the RegExp.escape method is available. If it is,
it uses that method to escape the string. If it's not, it uses a polyfill
method to escape the string.
The polyfill method replaces all special characters in the string with
their escaped equivalents. The special characters are defined by the
regular expression /[-[\]{}()*+?.,\\^$|#\s]/g.
string string The string to be escaped.// Suppose we have a string with special characters
const str = 'Hello, [World]!'
// Using `escape` or `escapePolyfill`
console.log(RegExp[RegExp.escape ? 'escapePolyfill' : 'escape'](str))
// Output: 'Hello\\, \\[World\\]\\!'
Returns string The escaped string.
Getter method that returns a string 'null'.
This method is used when you need a string representation of null in your regular expressions. It simply returns the string 'null'.
// Using `null`
console.log(this.null) // Output: 'null'
Returns string A string 'null'.
Getter method that returns a regular expression string for boolean values.
This method uses the oneOf method to create a regular expression
string that matches either 'true' or 'false'. This is useful when you
need to match boolean values in a string using a regular expression.
// Using `bool`
const boolRegex = new RegExp(this.bool)
console.log(boolRegex.test('true')) // Output: true
console.log(boolRegex.test('false')) // Output: true
console.log(boolRegex.test('maybe')) // Output: false
Returns string A regular expression string that matches 'true' or 'false'.
Generates a regular expression string that matches the symbols of specified currencies.
This method uses the Intl API to get the symbols of the specified currencies and constructs a regular expression string that matches these symbols. If no specific currencies are provided, it defaults to all known currencies. If a single currency is provided as a string, it is converted to an array. If the symbols array is empty after filtering out unknown currencies, it defaults back to all known currencies.
symbols (Array | string) The
currencies to include in the regular expression. Can be an array
of currency codes or a single currency code as a string. Defaults
to all known currencies. (optional, default [['*'],['USD','GBP']][0])locale string The locale to use when getting
the currency symbols. Defaults to 'en-US'. (optional, default 'en-US')// Using `currencySymbols` with default parameters
console.log(this.currencySymbols())
// Output: A regular expression string that matches all known
// currency symbols
// Using `currencySymbols` with specific currencies
console.log(this.currencySymbols(['USD', 'EUR']))
// Output: A regular expression string that matches the symbols
// of USD and EUR
Returns string A regular expression string that matches the symbols of the specified currencies.
Getter method that returns a regular expression string for numbers.
This method returns a regular expression string that matches both integer and floating point numbers. The returned regular expression string is '\d+\.?\d*', which matches one or more digits followed by an optional decimal point and zero or more digits.
// Using `number`
const numberRegex = new RegExp(this.number)
console.log(numberRegex.test('123')) // Output: true
console.log(numberRegex.test('123.45')) // Output: true
console.log(numberRegex.test('abc')) // Output: false
Returns string A regular expression string that matches numbers.
Getter method that returns a regular expression string for integers.
This method returns a regular expression string that matches integer numbers. The returned regular expression string is '\d+', which matches one or more digits.
// Using `integer`
const integerRegex = new RegExp(this.integer)
console.log(integerRegex.test('123')) // Output: true
console.log(integerRegex.test('123.45')) // Output: false
console.log(integerRegex.test('abc')) // Output: false
Returns string A regular expression string that matches integers.
Getter method that returns a regular expression string for floating point numbers.
This method returns a regular expression string that matches floating point numbers. It leverages the 'number' getter method which matches both integer and floating point numbers. The returned regular expression string is '\d+\.?\d*', which matches one or more digits followed by an optional decimal point and zero or more digits.
// Using `float`
const floatRegex = new RegExp(this.float)
console.log(floatRegex.test('123.45')) // Output: true
console.log(floatRegex.test('123')) // Output: false
console.log(floatRegex.test('abc')) // Output: false
Returns string A regular expression string that matches floating point numbers.
Getter method that returns a regular expression string for integers.
This method returns a regular expression string that matches integer numbers. The returned regular expression string is '\d+', which matches one or more digits.
// Using `integer`
const integerRegex = new RegExp(this.integer)
console.log(integerRegex.test('123')) // Output: true
console.log(integerRegex.test('123.45')) // Output: false
console.log(integerRegex.test('abc')) // Output: false
Returns string A regular expression string that matches integers.
Getter method that returns a regular expression string for pretty numbers.
This method returns a regular expression string that matches numbers with commas or spaces for thousands separators. The returned regular expression string is '[\d\$]+\.?[\d,\$]*', which matches one or more digits or dollar signs, followed by an optional decimal point, and zero or more digits, commas, or dollar signs.
// Using `pretty`
const prettyRegex = new RegExp(this.pretty)
console.log(prettyRegex.test('1,234.56')) // Output: true
console.log(prettyRegex.test('1234.56')) // Output: true
console.log(prettyRegex.test('1 234.56')) // Output: true
console.log(prettyRegex.test('abc')) // Output: false
Returns string A regular expression string that matches pretty numbers.
Getter method that returns a regular expression string for JavaScript literals.
This method returns a regular expression string that matches JavaScript literals. The returned regular expression string is '[\d_]+', which matches one or more digits or underscores.
// Using `jsLiteral`
const jsLiteralRegex = new RegExp(this.jsLiteral)
console.log(jsLiteralRegex.test('123_456')) // Output: true
console.log(jsLiteralRegex.test('abc')) // Output: false
Returns string A regular expression string that matches JavaScript literals.
SetExtensions is a constant that applies a patch to the global
Set constructor. This patch extends the Set with additional
methods and properties, enhancing its functionality.
The Patch function takes two arguments: the target object to be patched
(in this case, Set), and an object containing the methods and
properties to be added to the target object.
Type: Patch
// Using a method added by SetExtensions
const set = new Set();
console.log(Set.isSet(set)); // Output: true
SetPrototypeExtensions is a constant that applies a patch to the
prototype of the built-in JavaScript Set object. This patch extends the
Set prototype with additional methods and properties, enhancing its
functionality.
The Patch function takes two arguments: the target object to be patched
(in this case, Set.prototype), and an object containing the methods and
properties to be added to the target object.
Type: Patch
// Using a method added by SetPrototypeExtensions
const mySet = new Set();
mySet.myNewMethod(); // Calls the new method added by the patch
Determines if the supplied value is a Set object. This check
is performed by first looking for the Symbol.toStringTag on the
value and checking to see if it is equal to the string "Set".
If that check fails, instanceof is used as a fallback to check
the prototype chain.
value any the value that needs to be checked to determine
if it is a Set object or notconst set = new Set()
isSet(set) // true
isSet(new Map()) // false
isSet([]) // false
isSet({}) // false
Returns boolean true if the supplied value is a Set
object, false otherwise
Conditionally returns a value based on whether the supplied
value is a Set object or not. If the value is a Set
object, the thenValue will be returned. If it is not a Set
object, the elseValue will be returned instead.
value any the value to check to determine if it is a
Set objectthenValue any the value to return if the supplied
value is a Set objectelseValue any the value to return if the supplied
value is not a Set objectconst set = new Set()
const map = new Map()
ifSet(set, 'is a set', 'not a set') // 'is a set'
ifSet(map, 'is a set', 'not a set') // 'not a set'
Returns any either the thenValue or elseValue depending
on if the supplied value is a Set object
Merges multiple iterables into the set. Each element from the iterables is added to the set, ensuring uniqueness of all elements. This method mutates the original set.
iterables ...Iterable One or more iterable objects (like Set
or Array) whose elements will be added to the set.Checks to see if any value within the Set loosely equals the supplied
value.
value any any value that might be loosely equal to an item in the
set, as opposed to Set.has which is the equivalent of a strict or
triple equals (===) checkReturns boolean true if any value within the set is loosely equal to
the supplied value, false otherwise
Checks if every element in the set passes the test implemented by the provided function. The function is called with each element of the set. Note: Since sets do not have indices, the index parameter is always NaN.
everyFn Function The function to test each element. Receives
the element, index (always NaN), and the set itself.thisArg Object? Optional. Value to use as this when executing
everyFn.everyFn is not a function.Returns boolean True if every element passes the test, false otherwise.
Finds the first element in the set satisfying the provided testing function. If no elements satisfy the testing function, undefined is returned. The function is called with each element of the set. Note: Since sets do not have indices, the index parameter is always NaN.
findFn Function The function to execute on each element. It
receives the element, index (always NaN), and the set itself.thisArg Object? Optional. Value to use as this when executing
findFn.findFn is not a function.Returns any The first element that satisfies findFn, or undefined.
Finds the last element in the set satisfying the provided testing function. If no elements satisfy the testing function, undefined is returned. The function is called with each element of the set in reverse order. Note: Since sets do not have indices, the index parameter is always NaN.
findFn Function The function to execute on each element. It
receives the element, index (always NaN), and the set itself.thisArg Object? Optional. Value to use as this when executing
findFn.findFn is not a function.Returns any The last element that satisfies findFn, or undefined.
Determines if the current object is a Set object.
This is a getter that uses the isSet function from the
SetExtensions patch to check if the current object (this) is
a Set object.
Type: boolean
const set = new Set()
console.log(set.isSet) // Output: true
const notSet = {}
console.log(notSet.isSet) // Output: false
Checks if the current object is a Set and returns the corresponding value based on the result.
This method uses the isThenElse function from the
SetExtensions patch to determine if the current object
(this) is a Set. If it is a Set, the thenValue is returned.
Otherwise, the elseValue is returned.
thenValue any The value to return if the current object
is a Set.elseValue any The value to return if the current object
is not a Set.const set = new Set([1, 2, 3])
console.log(set.ifSet('Is a Set', 'Not a Set')) // 'Is a Set'
const notSet = {}
console.log(notSet.ifSet('Is a Set', 'Not a Set')) // 'Not a Set'
Returns any The thenValue if the current object is a Set, or
the elseValue if it is not a Set.
A getter property that returns the number of elements in the set.
This is an alias for the size property of the set.
Returns number The number of elements in the set.
Creates a new array populated with the results of calling the provided function on every element in the set. The function is called with each element of the set. Note: Since sets do not have indices, the index parameter is always NaN.
mapFn Function The function to execute on each element. It
receives the element, index (always NaN), and the set itself.thisArg Object? Optional. Value to use as this when executing
mapFn.mapFn is not a function.Returns Array A new array with each element being the result of the
mapFn.
Applies a function against an accumulator and each element in the set to reduce it to a single value. The function is called with each element of the set. Note: Since sets do not have indices, the index parameter is always NaN.
reduceFn Function The function to execute on each element. It
receives the accumulator, element, index (always NaN), and the set itself.initialValue any The initial value to start reducing from.thisArg Object? Optional. Value to use as this when executing
reduceFn.reduceFn is not a function.Returns any The reduced value.
Tests whether at least one element in the set passes the test implemented by the provided function. The function is called with each element of the set. Note: Since sets do not have indices, the index parameter is always NaN.
someFn Function The function to test each element. It receives
the element, index (always NaN), and the set itself.thisArg Object? Optional. Value to use as this when executing
someFn.someFn is not a function.Returns boolean True if at least one element passes the test, false otherwise.
StringExtensions is a patch for the JavaScript built-in String class. It
adds utility methods to the String class without modifying the global namespace
directly. This patch includes methods for key validation, object type checking,
and retrieving the string tag of an object. These methods are useful for
enhancing the capabilities of the standard String class with additional
utility functions.
The isString method does exactly what one would it expect. It returns
true if the string matches typeof or instanceof as a string.
value any checks to see if the value is a stringReturns boolean true if it is a String, false otherwise
Conditionally returns a value based on whether the supplied
value is a String or not. If the value is a String,
the thenValue will be returned. If it is not a String,
the elseValue will be returned instead.
value any the value to check to determine if it is a
StringthenValue any the value to return if the supplied
value is a StringelseValue any the value to return if the supplied
value is not a Stringconst str = 'hello'
const num = 42
ifString(str, 'is a string', 'not a string') // 'is a string'
ifString(num, 'is a string', 'not a string') // 'not a string'
Returns any either the thenValue or elseValue depending
on if the supplied value is a String
A getter property that returns a pair of parentheses as an array. This property can be used when operations require a clear distinction between the opening and closing parentheses, such as parsing or matching balanced expressions in strings.
Returns [string, string] An array containing a pair of strings: the opening parenthesis '(' as the first element, and the closing parenthesis ')' as the second element.
A getter property that returns a pair of square brackets as an array. This property is particularly useful for operations that require a clear distinction between the opening and closing square brackets, such as parsing arrays in strings or matching balanced expressions within square brackets.
Returns [string, string] An array containing a pair of strings: the opening square bracket '[' as the first element, and the closing square bracket ']' as the second element.
A getter property that returns a pair of curly brackets as an array. This property is particularly useful for operations that require a clear distinction between the opening and closing curly brackets, such as parsing objects in strings or matching balanced expressions within curly brackets. The returned array consists of the opening curly bracket '{' as the first element, and the closing curly bracket '}' as the second element.
Returns [string, string] An array containing a pair of strings: the opening curly bracket '{' as the first element, and the closing curly bracket '}' as the second element.
Generates a random string using base 36 (numbers and lowercase letters). This method is useful when you need a random string that includes both numbers and letters. The generated string does not include the leading '0.' that is part of the string representation of a random number in base 36.
const randomStr = StringExtensions.random36();
console.log(randomStr); // Output: "3n5yzxjkf2o"
Returns string A random string of characters in base 36.
Generates a random string using base 16 (hexadecimal numbers). This method is useful when you need a random string that includes both numbers and letters in hexadecimal format. The generated string does not include the leading '0.' that is part of the string representation of a random number in base 16.
const randomStr = StringExtensions.random16();
console.log(randomStr); // Output: "3a5f4c"
Returns string A random string of characters in base 16.
Generates a random RGB color code.
This method generates a random hexadecimal number, slices off the leading '0.' and takes the first 6 characters. It then pads the end of the string with '0' until it is 6 characters long. The result is a string that can be used as a color code in CSS.
prefix string The prefix to prepend to the color
code. Defaults to '#'. (optional, default '#')const randomColor = StringExtensions.randomRGB();
console.log(randomColor); // Output: "#3a5f4c"
Returns string A random RGB color code.
Generates a random ARGB color code.
This method generates a random hexadecimal number, slices off the leading '0.' and takes the first 8 characters. It then pads the start of the string with '0' until it is 6 characters long and the end of the string with '0' until it is 8 characters long. The result is a string that can be used as a color code in CSS.
prefix string The prefix to prepend to the color
code. Defaults to '#'. (optional, default '#')const randomColor = StringExtensions.randomARGB();
console.log(randomColor); // Output: "#3a5f4c00"
Returns string A random ARGB color code.
Generates a random RGBA color code.
This method generates a random hexadecimal number, slices off the leading '0.' and takes the first 8 characters. It then pads the start of the string with '0' until it is 6 characters long and the end of the string with '0' until it is 8 characters long. The result is a string that can be used as a color code in CSS.
prefix string The prefix to prepend to the color
code. Defaults to '#'. (optional, default '#')const randomColor = StringExtensions.randomRGBA();
console.log(randomColor); // Output: "#3a5f4c00"
Returns string A random RGBA color code.
Generates a random RGB color code.
This method generates a random hexadecimal number, slices off the leading '0.' and pads the end of the string with '0' until it is 8 characters long. It then parses the first 6 characters into three separate 2-character strings, each representing a color component (red, green, blue) in hexadecimal format. These strings are then converted into decimal format and used to construct an RGB color code.
const randomColor = StringExtensions.randomRGB();
console.log(randomColor); // Output: "rgb(58,95,76)"
Returns string A random RGB color code.
Generates a random RGBA color code with optional forced color values.
This method generates a random hexadecimal number, slices off the leading '0.' and pads the end of the string with '0' until it is 8 characters long. It then parses the first 8 characters into four separate 2-character strings, each representing a color component (red, green, blue, alpha) in hexadecimal format. These strings are then converted into decimal format and used to construct an RGBA color code.
If a color component is provided in the force parameter, it will
be used instead of a random value for that component.
force Object An object with properties for each color
component (red, green, blue, alpha) that should be forced to a
specific value. If a property is undefined or not provided, a
random value will be used for that component. (optional, default {red:undefined,green:undefined,blue:undefined,alpha:undefined})
const randomColor = StringExtensions.randomRGBA();
console.log(randomColor); // Output: "rgba(58,95,76,0.50)"
const forcedGreen = StringExtensions.randomRGBA({ green: 255 });
console.log(forcedGreen); // Output: "rgba(58,255,76,0.50)"
Returns string A random RGBA color code.
Applies Select Graphic Rendition (SGR) parameters to a given message for styling in terminal environments. This function allows for the dynamic styling of text output using ANSI escape codes. It supports a variety of modes such as color, brightness, and text decorations like bold or underline.
message string The message to be styled.useModes ...string A series of strings representing the desired
styling modes. Modes can include colors (e.g., 'red', 'blue'), brightness
('bright'), foreground/background ('fg', 'bg'), and text decorations
('bold', 'underline'). Modes can be combined in a single string using
commas or passed as separate arguments.Colors: 'black', 'red', 'green', 'yellow', 'blue', 'magenta', 'cyan', 'white'Color Specifiers: 'fg' -> foreground | 'bg' -> background | 'bright' -> bright colorsModes: 'blink' or 'k' | 'conceal' or 'c' | 'italics' or 'i' | 'strike' or 's'
'bold' or 'b' | 'dim' or 'd' | 'negative' or 'n' | 'underline' or 'u'Examples:* sgr('Hello', 'red') applies red color to 'Hello'.
sgr('World', 'green,bold') applies green color and bold styling
to 'World'.sgr('Example', 'bluebgbright') applies bright blue
background color.Short hand syntax is also allowed:* sgr('hello', 'biu') applies bold, italics and underlinesgr('hello', 'bi,redfg') applies bold, italics and red foregroundAs a bonus, there is a secret getter applied to the return string that
allows you to invoke sgr(...).show to automatically log the output to
console.log. This is done by wrapping the output string in Object()
to make it a String instance and then adding the property descriptor.
A custom Symbol is applied to make it evaluate in nodejs as though it
were a normal string. To strip the extras, wrap the output in String()Returns string The message wrapped in ANSI escape codes corresponding to the specified modes. The returned string, when printed to a terminal, displays the styled message. Additional properties are attached to the result for utility purposes, such as 'show' for immediate console output.
Wraps an object's properties into a formatted string.
This method takes an object and a set of options to format the object's properties into a string. It allows customization of indentation, line endings, maximum line length, and more.
objectOrLines
options Object The formatting options. (optional, default {})
options.indent number The number of indentation
characters to use. (optional, default 2)options.indentCharacter string The character to use
for indentation. (optional, default ' ')options.inspector Array The inspector to use for retrieving object properties. (optional, default [Object,'getOwnPropertyNames'])options.lineEnding string The line ending character. (optional, default '\n')options.maxLen number The maximum line length. (optional, default 78)options.perLine Function A function to apply
per line of output. (optional, default undefined)options.perLinePerProperty Function A function
to apply per property per line of output. (optional, default undefined)options.preProcess Function A function to
preprocess the object's properties. (optional, default undefined)options.preReturn Function A function to apply
to the final output before returning. (optional, default undefined)options.separator string The separator to use
between properties. (optional, default ', ')object Object The object to wrap. (optional, default globalThis)
const obj = { a: 1, b: 2, c: 3 }
const wrapped = StringExtensions.wrap(obj, { maxLen: 20 })
console.log(wrapped)
// Output:
// {
// a: 1,
// b: 2,
// c: 3
// }
Returns string The formatted string representation of the object.
Determines if the current object is a string.
This getter uses the pIsString function from the
StringExtensions patch to check if the current object
(this) is a string.
Type: boolean
const str = "Hello, World!"
console.log(str.isString) // Output: true
const notStr = 123
console.log(notStr.isString) // Output: false
Checks if the current object is a string and returns the corresponding value based on the result.
This method uses the pIfString function from the
StringExtensions patch to determine if the current object
(this) is a string. If it is a string, the thenValue is returned.
Otherwise, the elseValue is returned.
thenValue any The value to return if the current object
is a string.elseValue any The value to return if the current object
is not a string.const str = "Hello, World!"
// 'Is a string'
console.log(str.ifString('Is a string', 'Not a string'))
const notStr = 123
// 'Not a string'
console.log(notStr.ifString('Is a string', 'Not a string'))
Returns any The thenValue if the current object is a string, or
the elseValue if it is not a string.
Returns an object representation of the string instance.
This getter method creates and returns an object that wraps
the string instance, allowing it to be treated as an object.
The returned object is created using the Object()
constructor, which takes the string instance as its argument.
Type: Object
const str = 'Hello, World!'
console.log(typeof str) // 'string'
console.log(typeof str.instance) // 'object'
Extracts a substring from the current string, starting at a given offset and bounded by specified opening and closing tokens. This method is particularly useful for parsing nested structures or quoted strings, where the level of nesting or the presence of escape characters must be considered.
offset number The position in the string from which to start the
search for the substring. (optional, default 0)tokens [string, string] An array containing two strings: the
opening and closing tokens that define the boundaries of the substring
to be extracted. (optional, default parenthesisPair)Returns Object An object with two properties: extracted, the
extracted substring, and newOffset, the position in the original
string immediately after the end of the extracted substring. If no
substring is found, extracted is null and newOffset is the same
as the input offset.
StringPrototypeExtensions provides a set of utility methods that are
added to the String prototype. This allows all string instances to
access new functionality directly, enhancing their capabilities beyond
the standard String class methods. These extensions are applied using
the Patch class from '@nejs/extension', ensuring that they do not
interfere with the global namespace or existing properties.
The extensions include methods for extracting substrings based on specific tokens, checking the presence of certain patterns, and more, making string manipulation tasks more convenient and expressive.
SymbolExtensions is a patch for the JavaScript built-in Symbol class. It
adds utility methods to the Symbol class without modifying the global namespace
directly. This patch includes methods for key validation, object type checking,
and retrieving the string tag of an object. These methods are useful for
enhancing the capabilities of the standard Symbol class with additional
utility functions.
The isSymbol method does exactly what one would it expect. It returns
true if the string matches typeof or instanceof as a symbol.
value any checks to see if the value is a stringReturns boolean true if it is a Symbol, false otherwise
Returns true if the supplied value is a Symbol created using
Symbol.for().
value any assumption is that the supplied value is of type
'symbol' however, unless allowOnlySymbols is set to true, false
will be returned for any non-symbol values.allowOnlySymbols boolean true if an error should be thrown
if the supplied value is not of type 'symbol' (optional, default false)Returns any true if the symbol is registered, meaning, none of the spec
static symbols (toStringTag, iterator, etc...), and no symbols
created by passing a value directly to the Symbol function, such as
Symbol('name')
A function that returns true if the symbol is not registered, meaning,
any of the spec static symbols (toStringTag, iterator, etc...), and
any symbols created by passing a value directly to the Symbol function,
such as Symbol('name').
value any assumption is that the supplied value is of type
'symbol' however, unless allowOnlySymbols is set to true, false will
be returned for any non-symbol values.allowOnlySymbols boolean true if an error should be thrown
if the supplied value is not of type 'symbol' (optional, default false)Returns any true if the symbol is not registered, meaning, any of the
spec static symbols (toStringTag, iterator, etc...), and any symbols
created by passing a value directly to the Symbol function, such as
Symbol('name')
Returns any true if the value in question is both a symbol and has
returns undefined if passed to Symbol.keyFor
keys is an instance of the Symkeys class, initialized with the
domain 'nejs'. The Symkeys class provides a way to easily generate
Symbol.for elements that follow particular pattern. Symkeys also
allows associated data storage with each generated key.
Type: Symkeys
// Returns something like Symbol.for('@nejs.prototype #rwiy2o905d')
const kOriginal = Symbol.keys.add('prototypes')
// Which can be used to retrieve and fetch data associated with that key
// The value stored is an array by default, but can be anything. It can
// be accessed one property at a time
Symbol.keys[kOriginal].original = Object.prototype
Symbol.keys[kOriginal].modified = Object.create(Object.prototype, ...)
// Or wholesale replaced
Symbol.keys[kOriginal] = [Object.prototype, Array.prototype]
// But if all Symbol Extensions are in place, including prototype add-ons
kOriginal.data.original = Object.prototype // ...and...
kOriginal.data = [Object.prototype, Array.prototype] // ...both work
Creates a new Symbol with the given name and optional data. If data is provided, it will be stringified and appended to the symbol's name. This method is useful for creating unique symbols that carry additional metadata.
name string The name of the symbol.data any? Optional data to be associated with the symbol.const symbolWithData = Symbol.withData('mySymbol', { foo: 'bar' })
console.log(symbolWithData.toString())
// Output: "Symbol(mySymbol {"foo":"bar"})"
const symbolWithoutData = Symbol.withData('mySymbol')
console.log(symbolWithoutData.toString())
// Output: "Symbol(mySymbol)"
Returns symbol A new symbol created with Symbol.for(), using the provided name and stringified data (if provided).
Returns an object representation of the symbol instance.
This getter method creates and returns an object that wraps the
symbol instance, allowing it to be treated as an object. The
returned object is created using the Object() constructor,
which takes the symbol instance as its argument.
Type: Object
const sym = Symbol('example')
console.log(typeof sym) // 'symbol'
console.log(typeof sym.instance) // 'object'
Getter method for retrieving the data associated with a symbol.
This method first checks if the symbol is a Symkey created symbol by checking the existence of Symbol.keys and if the symbol's description matches the Symkey pattern. If it is a Symkey symbol, it attempts to fetch its associated data.
NOTE: Symkey data is returned as its value directly, this is because
it is stored in a Map. Embedded JSON data might be expensive
to parse and as such a function is returned when data is accessed that
needs to be invoked in order to decode its contents. See
{@link mightHaveEmbeddedJSON} for more information.
If the symbol is not a Symkey symbol or if no data is associated with it, the method attempts to parse the symbol's description as JSON and returns the first valid JSON object found.
If no valid JSON object is found in the description, the method returns undefined.
const keys = new Symkeys
const key = keys.add('example', {count: 0})
const data = key.data // note this isn't function!!
const count = data.count
const sym = Symbol.for('fun {"name":"Brie"}')
let json = sym.data() // {name: 'Brie'} JS object
const sym = Symbol('mySymbol')
let data = sym.data() // undefined
Sets the data associated with a symbol.
This setter method checks if the symbol is a Symkey and if it has associated data. If both conditions are met, it sets the data of the symbol to the provided value and returns true. If the conditions are not met, it simply returns false.
While Symbols have been upgraded to also support embedded JSON data with this extension, symbol descriptions are static. Non Symkey symbols do not associated their data outside of a symbol, and cannot be changed, there new data cannot be set on them.
value any The value to be set as the symbol's data.const sym = Symbol.for('fun {"name":"Brie"}')
Symkeys.isSymkey(sym) // false; not in Symkey format
let json = sym.data() // {name: 'Brie'} JS object
sym.data = JSON.stringify({name: 'Jane'}) // fails silently
json = sym.data() // {name: 'Brie'} is hard-coded in description
const sym = Symbol('mySymbol')
Symkeys.isSymkey(sym) // false; not in Symkey format
Symkeys.hasData(sym) // false
sym.data = { name: 'John', age: 30 } // will fail silently
Symkeys.hasData(sym) // still false
// Now let's create a Symkey with data
const symWithData = Symkeys.create('mySymbolWithData',
{ name: 'Jane', age: 25 })
Symkeys.isSymkey(symWithData) // true
Symkeys.hasData(symWithData) // true
symWithData.data = { name: 'Jane', age: 26 } // will succeed
Symkeys.getData(symWithData) // returns { name: 'Jane', age: 26 }
Returns boolean Returns true if the data was successfully set, false otherwise.
Checks if the symbol might have embedded JSON data.
This getter method checks if the symbol's description might contain JSON data and if the data property of the symbol is a function. If both conditions are met, it returns true, otherwise it returns false.
const sym = Symbol.for('fun {"name":"Brie"}')
console.log(sym.mightHaveEmbeddedJSON) // Output: true
const sym = Symbol('mySymbol')
console.log(sym.mightHaveEmbeddedJSON) // Output: false
Returns boolean Returns true if the symbol might have embedded JSON, false otherwise.
Custom inspect method for Node.js util.inspect.
NOTE: this will only apply if looking at an instance of Symbol, sadly; {@see SymbolPrototypeExtensions.instance}
This method is used by Node.js util.inspect to provide a custom
representation of the symbol when inspected. It checks if the
symbol's description might contain JSON data and if so, it
truncates the JSON data in the description to a maximum of 30
characters and formats the output with colors using the sgr
function from the String object.
depth number The current depth of the recursive
inspection.options Object The options object passed to
util.inspect.inspect Function The original util.inspect function.const sym = Symbol.for('fun {"name":"John Doe"}')
console.log(util.inspect(sym))
// Output: Symbol.for(fun {"name":"John ...hn Doe"})
Returns string The formatted representation of the symbol.
Extends Promise
Deferreds, which were first introduced by jQuery for browsers in the early
2000s, are a way to manage asynchronous operations. They have been widely
used and replicated by engineers since then. Although the Promise class in
modern JavaScript provides a static method called withResolvers that
returns an object with similar properties to a Deferred, it is not directly
supported by Node.js.
const withResolvers = Promise.withResolvers()
Reflect.has(withResolvers, 'promise') // true
Reflect.has(withResolvers, 'resolve') // true
Reflect.has(withResolvers, 'reject') // true
This Deferred class extends the Promise class, allowing it to capture the
value or reason for easy access after resolution, akin to
Promise.withResolvers. As it extends Promise, it is
'thenable' and works with await as if it were a native Promise. This
allows seamless integration with code expecting Promise-like objects.
options object see above for examples on supported options, but
when supplied, the constructor can take instructions on how to auto
resolve or reject the deferred created here.When the Deferred is settled with Deferred.resolve, the value
passed to that function will be set here as well.
Type: any
When the Deferred is settled with Deferred.reject, the reason
passed to that rejection will also be stored here.
Type: any
Returns a boolean value that indicates whether or not this Deferred has been settled (either resolve or reject have been invoked).
Returns boolean true if either Deferred.resolve or
Deferred.reject have been invoked; false otherwise
A getter that returns a boolean indicating whether the Deferred instance was rejected. This property can be used to check if the Deferred has been settled with a rejection. It is particularly useful in scenarios where the resolution status of the Deferred needs to be checked without accessing the rejection reason or invoking any additional logic.
Returns boolean true if the Deferred was rejected, otherwise false.
A getter that returns a boolean indicating whether the Deferred instance was resolved. This property is useful for checking if the Deferred has been settled with a resolution, allowing for checks on the Deferred's status without needing to access the resolved value or trigger any additional logic.
Returns boolean true if the Deferred was resolved, otherwise false.
Accessor for the promise managed by this Deferred instance.
This getter provides access to the internal promise which is controlled by the Deferred's resolve and reject methods. It allows external code to attach callbacks for the resolution or rejection of the Deferred without the ability to directly resolve or reject it.
Returns Promise The promise controlled by this Deferred instance.
Resolves the Deferred with the given value. If the value is a thenable (i.e., has a "then" method), the Deferred will "follow" that thenable, adopting its eventual state; otherwise, the Deferred will be fulfilled with the value. This function behaves the same as Promise.resolve.
value any The value to resolve the Deferred with.Returns Promise A Promise that is resolved with the given value.
Rejects the Deferred with the given reason. This function behaves the same as Promise.reject. The Deferred will be rejected with the provided reason.
reason any The reason to reject the Deferred with.Returns Promise A Promise that is rejected with the given reason.
Customizes the output of util.inspect on instances of Deferred when
used in Node.js. This method is invoked by Node.js's util.inspect
utility to format the inspection output of a Deferred instance.
The output includes the state of the Deferred (resolved, rejected, or unsettled) along with the resolved value or rejection reason, if applicable. This provides a quick, readable status of the Deferred instance directly in the console or debugging tools.
depth number The depth to which util.inspect will recurse.options object Formatting options provided by util.inspect.inspect function Reference to the util.inspect function.Returns string A formatted string representing the Deferred instance.
A getter for the species symbol which returns a custom DeferredPromise class. This class extends from Deferred and is used to ensure that the constructor signature matches that of a Promise. The executor function passed to the constructor of this class is used to initialize the Deferred object with resolve and reject functions, similar to how a Promise would be initialized.
Returns DeferredPromise A DeferredPromise class that extends Deferred.
The promise backing this deferred object. Created when the constructor
runs, this promise is what all Promise.prototype functions are routed
to.
Type: Promise
The reject() resolver that will be assigned when a new instance is
created. Invoking this function with or without a reason will cause
the deferred's promise to be settled.
Type: function
The resolve() resolver that will be assigned when a new instance is
created. Invoking this function with or without a value will cause
the deferred's promise to be settled.
Type: function
When either Deferred.resolve or Deferred.reject are called,
this property is set to true. Its current status at any time can be
queried using the Deferred.settled getter.
Type: boolean
An optionally associated object, usually the parent from which the descriptor was taken, or undefined if none was able to be derived.
Type: object
Constructs a Descriptor instance which wraps and manages an object property descriptor. The constructor can handle an existing descriptor object or create a new one based on an object and a property key.
object (object | Descriptor) The target object or an existing
Descriptor instance. If it's an object, it is used in conjunction with
key to create a descriptor. If it's a Descriptor instance, it is used
directly as the descriptor.key (string | symbol)? The property key for which the descriptor
is to be created. This parameter is ignored if object is a Descriptor
instance. If key is an object and object is a valid descriptor, key
is treated as the associated object.Detects whether or not this instance is an accessor object descriptor
Returns boolean true if this object has a getter or setter and is not a data descriptor
Detects whether or not this instance is an data object descriptor
Returns boolean true if this object has a value property and is not an accessor descriptor
Detects whether or not this instance is a valid object descriptor
Returns boolean true if this descriptor store is a valid descriptor
Getter around the configurable object descriptor property of
this instance of Descriptor.
Returns boolean a boolean value or undefined if the internal descriptor store is invalid.
Sets the configurable value of this object. If the internal descriptor
store store is invalid, the value is thrown away
value boolean the value to set for the configurable descriptor
property. If this value is not a boolean it will be converted to oneGetter around the enumerable object descriptor property of
this instance of Descriptor.
Returns boolean a boolean value or undefined if the internal descriptor store is invalid.
Sets the enumerable value of this object. If the internal descriptor
store is invalid, the value is thrown away
value boolean the value to set for the enumerable descriptor
property. If this value is not a boolean it will be converted to oneGetter around the writable object descriptor property of
this instance of Descriptor.
Returns boolean a boolean value or undefined if the internal descriptor store is invalid.
Sets the writable value of this object. If the internal descriptor
store is invalid, the value is thrown away
value boolean the value to set for the writable descriptor
property. If this value is not a boolean it will be converted to oneGetter around the value object descriptor property of
this instance of Descriptor.
Returns any any value stored in this descriptor
Sets the value value of this object. If the internal descriptor
store is invalid, the value is thrown away
value any the value to set for the value descriptor
property.Getter around the get object descriptor property of
this instance of Descriptor.
Returns function a function if the getter for this descriptor is
defined or undefined if the internal descriptor object or the getter
is undefined.
Sets the get value of this object. If the internal descriptor
store is invalid, the value is thrown away
value function the getter function for this descriptorRetrieves the get function for this accessor and binds it to the object from which the descriptor was derived, if that value is set. Otherwise this method is identical to the get accessor.
Returns function the getter if one is defined. If possible this
getter will be bound the associated and previously set object.
Getter around the set object descriptor property of
this instance of Descriptor.
Returns function a function if the setter for this descriptor is
defined or undefined if the internal descriptor object or the setter
is undefined.
Sets the set value of this object. If the internal descriptor
store is invalid, the value is thrown away
value function the setter function for this descriptorRetrieves the set function for this accessor and binds it to the object from which the descriptor was derived, if that value is set. Otherwise this method is identical to the set accessor.
Returns function the setter if one is defined. If possible this
setter will be bound the associated and previously set object.
The function checks the descriptor's associated object has been set on this
instance of Descriptor.
Returns boolean true if the object property has been set,
false otherwise
Returns the descriptor's associated object value. This is usually the
parent object from which the descriptor was derived. If the value is preset
it will be returned. Undefined will be returned otherwise
Returns object the associated object for this descriptor or undefined if it has not yet been set.
Sets the descriptor's associated object value. This is usually the
parent object from which the descriptor was derived.
value object sets the object for which this descriptor is to
be associated with.The function returns a string representation of a descriptor object with additional information about its type when used in the NodeJS repl.
depth number The depth parameter is used to specify the
maximum depth to which nested objects and arrays will be formatted. If
the depth is exceeded, the output will be truncated with ellipses.options object The options parameter is an object that
contains various configuration options for the inspect function.
These options can be used to customize the output of the inspection.inspect function The inspect parameter is a function that
is used to convert an object into a string representation. It is
typically used for debugging purposes or when displaying an object's
properties.Returns any a string that represents a descriptor. The string includes the type of the descriptor (either "Accessor" or "Data") and the result of inspecting the descriptor object using the provided options and depth.
Take the descriptor defined by this objects values and apply them to the specified object using the specified key.
object object the object to apply this descriptor toforKey (string | symbol) the string or symbol for which this
descriptor will abe appliedbindAccessors (optional, default false)Converts this Descriptor class instance into a basic object descriptor that is accepted by all the standard JavaScript runtime methods that deal with object descriptors.
bindAccessors (boolean | object) if true, a non-fatal attempt to
bind accessor getter and setter methods is made before returning the
object. If bindAccessors is truthy and is also an object, this is the
object the accessors will be bound to. If the value is falsy or if the
descriptor instance represents a data descriptor, nothing happens. (optional, default false)Returns object the object instance's basic object representation as a descriptor.
Converts this descriptor object into a base representation
hint string one of string, number or default;Returns any if the hint is 'string', then a string identifying the enum
and its type is returned. number will always be NaN since it is incoret
Ensures that the constructor of this object instance's name is returned if the string tag for this instance is queried
Returns string the name of the class
Shorthand for Object.getOwnPropertyDescriptor()
object object a non-null object instancekey (string | symbol) a symbol or string referencing which key on the
object to return a descriptor for.wrap (optional, default false)Returns any an object descriptor for the requested field or null
The function getData retrieves the value of a property from an object
if it exists and is a data property.
object object The "object" parameter is the object from which
we want to retrieve data.property (string | symbol) The property parameter is the name of
the property that you want to retrieve the data from.Returns any either the value of the specified property if it exists and is a data property, or undefined if the property does not exist or is not a data property.
The function getAccessor checks if an object has a getter/setter accessor
for a given property and returns the accessor functions if found.
object The object parameter is the object from which we want to
retrieve the accessor for a specific property.property The property parameter is the name of the property for
which we want to get the accessor.Returns any an object that contains the getter and setter functions for the specified property of the given object. If the property is an accessor property (defined with a getter and/or setter), the returned object will also have additional properties such as "accessor" and "descriptor". If the property is not found or is not an accessor property, the function returns undefined.
The function returns an object with enumerable and configurable properties based on the input parameters.
enumerable A boolean value indicating whether the property
can be enumerated (listed) when iterating over the object's properties. (optional, default false)configurable The configurable parameter determines
whether the property can be deleted or its attributes can be modified.
If configurable is set to true, the property can be deleted and its
attributes can be changed. If configurable is set to false, the
property cannot be deleted and (optional, default false)Returns any An object with the properties enumerable and configurable is
being returned. The values of these properties are determined by the
arguments passed to the base function.
The function "newAccessor" creates a new property descriptor object with a getter and setter function, along with optional enumerable and configurable flags.
getter The getter parameter is a function that will be used as the
getter for the property. It will be called when the property is accessed.
setter The setter parameter is a function that will be used as
the setter for the property. It will be called whenever the property is
assigned a new value.
null Object * getter: A function that will be used as the getter for the
property. (optional, default Descriptor.base())
null.enumerable null.configurable Returns any an object with properties "get", "set", "enumerable", and "configurable".
The function "newData" creates a new data object with customizable properties.
value The value parameter represents the value that will be
assigned to the property.
writable The writable parameter determines whether the
value of the property can be changed. If writable is set to true, the
value can be changed. If writable is set to false, the value cannot be
changed. (optional, default true)
null Object * value: The value to be assigned to the property. (optional, default Descriptor.base())
null.enumerable null.configurable Returns any an object with properties value, enumerable, writable, and
configurable.
The function checks if an object is a likely an object descriptor in JavaScript. This is determined as an object with some of the known descriptor keys (e.g. enumerable, configurable, value, writable, get, or set). Technically, any object could serve as a descriptor but this function only returns true if known descriptor keys are found.
object The object parameter is the object that we want to
check if it is a descriptor.Returns any a boolean value.
The function checks if a given property or descriptor is a data property.
brie
object_orProp property descriptor_orProp The descriptor_orProp parameter can be
either a descriptor or a property name.object The object parameter is the object that you want to
check for data properties.Returns any a boolean value. It returns true if the descriptor object
has any keys that match the DATA_KEYS array, otherwise it returns
false.
The function checks if a given property descriptor or property of an object is an accessor.
object_orProp The descriptor_orProp parameter can be either a
descriptor object or a property name.property The object parameter is the object that you want to
check for accessor properties.Returns any a boolean value. It returns true if the descriptor or property passed as an argument is an accessor descriptor, and false otherwise.
A base descriptor (new for each read) that is both enumerable and configurable
Returns any The method flexible is returning the result of calling the
base method with the arguments true and true.
A base descriptor (new for each read) that is not enumerable but is configurable
Returns any The method enigmatic is returning the result of calling
the base method with the arguments false and true.
A base descriptor (new for each read) that is neither enumerable nor configurable
Returns any The code is returning the result of calling the base method with
the arguments false and false.
A base descriptor (new for each read) that enumerable but not configurable
Returns any The method is returning the result of calling the base
method with the arguments true and false.
The function returns an array of shared descriptor keys.
Returns any An array containing the strings 'configurable' and 'enumerable'.
The function returns an array of accessor descriptor keys.
Returns any An array containing the strings 'get' and 'set' is being returned.
The function returns an array of data descriptor keys.
Returns any An array containing the strings 'value' and 'writable' is being returned.
The Iterable class is designed to provide a convenient way to create synchronous
iterable objects. It can be initialized with either an array or individual elements.
This class implements the iterable protocol, allowing instances to be used with
for...of loops and other standard JavaScript iteration mechanisms.
elementsOrFirstElement (Iterable | any) An iterable object or the
first element.moreElements ...any Additional elements if the first argument is
not an iterable.Implements the iterable protocol. When an instance of Iterable is used
in a for...of loop or spread syntax, this generator function is invoked
to yield the elements one by one in a synchronous manner.
Returns Generator A generator that yields each element of the iterable.
Provides access to the elements as a standard array. Useful for scenarios where array methods and behaviors are needed.
Returns Array An array containing all the elements of the iterable.
Ensures that the constructor of this object instance's name is returned if the string tag for this instance is queried
Returns string the name of the class
Checks if a given value is an iterable. This method determines if the
provided value has a Symbol.iterator property that is a generator
function. It's a precise way to identify if the value conforms to the
iterable protocol using a generator function.
Note: This method specifically checks for generator functions. Some iterables might use regular functions that return an iterator, which this method won't identify.
value any The value to be checked for iterability.Returns boolean Returns true if the value is an iterable implemented using a generator function, false otherwise.
Being able to create a compliant Iterator around any type of iterable
object. This can be wrapped around any type of object that has a
[Symbol.iterator] property assigned to a generator function.
iterable object any object that has a [Symbol.iterator]
property assigned to a generator function.mapEach function when provided mapEach is a callback that
takes an entry as input and receives one as output.Returns a new Array derived from the iterable this object
wraps.
Returns array a new Array generated from the wrapped
iterable. The method is generated from Array.from()
Returns the actual iterable object passed to the constructor that created this instance.
Returns object the object containing the [Symbol.iterator]
The function retrieves the next value in the iterator. If the
the iterator has run its course, reset() can be invoked to
reset the pointer to the beginning of the iteration.
Returns any the next value
Resets the iterator to the beginning allowing it to be iterated over again.
The existence of this symbol on the object instances, indicates that
it can be used in for(.. of ..) loops and its values can be
extracted from calls to Array.from()
Returns Iterator this is returned since this object is already conforming to the expected JavaScript Iterator interface
Ensures that the constructor of this object instance's name is returned if the string tag for this instance is queried
Returns string the name of the class
A private function that when provided has the following signature:
function mapEach(entry) -> entry. This allows any changes to be made
to each element, conditionally and programmatically, as needed before
they are returned to the called code.
Constructs an instance of ParamParser. It takes in parameters, an optional validator function, and an optional parser function. The parameters are validated and if successful, parsed.
parameters Array<any> Arguments passed in by the process.validator (optional, default ()=>{})parser (optional, default ()=>{})const parameters = ['param1', 'param2']
const validator = params => params.every(param => typeof param === 'string')
const parser = params => ({ params })
const paramParser = new ParamParser(parameters, validator, parser)
if (paramParser.success) {
console.log('Parsing successful:', paramParser.results)
} else {
console.error('Parsing failed.')
}
args object arguments that were previously validated
by either the overloaded validate() method or the supplied
validator closure.Returns object returns the output object, or an empty object, after parsing the input arguments or parameters.
Walk the arguments and determine if the supplied input is a valid parsing.
args Array<any> arguments supplied by the process.Returns boolean true if the validation is successful,
false otherwise.
Attempts to parse the given parameters using the provided parsers, throwing an
error if no valid parser is found. This method serves as a convenience wrapper
around safeTryParsers, enforcing strict parsing by automatically enabling
error throwing on failure.
parameters Array<any> The parameters to be parsed.parsers Array<Function> An array of ParamParser subclasses to attempt
parsing with.const parameters = ['param1', 'param2'];
const parsers = [Parser1, Parser2];
const result = ParamParser.tryParsers(parameters, parsers);
if (result.success) {
console.log('Parsing successful:', result.data);
} else {
console.error('Parsing failed.');
}
Returns Object An object containing the parsing result, with a success
property indicating if parsing was successful, and a data property containing
the parsed data if successful.
Tries parsing parameters with each parser in parsers. If
throwOnFail is true, throws an error when validation fails or
no valid parser is found.
This method attempts to parse the given parameters using the
provided list of parsers. It validates the input to ensure both
parameters and parsers are arrays and that parsers
contains at least one valid ParamParser subclass. If
throwOnFail is set to true, it will throw specific errors for
invalid inputs or when no parser succeeds. Otherwise, it returns
an object indicating the success status and the result of
parsing, if successful.
parameters Array<any> The parameters to be parsed.parsers Array<Function> An array of ParamParser
subclasses to attempt parsing with.throwOnFail boolean Whether to throw an
error on failure. (optional, default false)const parameters = ['param1', 'param2'];
const parsers = [Parser1, Parser2];
const result = ParamParser.safeTryParsers(
parameters, parsers, true
);
if (result.success) {
console.log('Parsing successful:', result.data);
} else {
console.error('Parsing failed.');
}
parameters or
parsers are not arrays when throwOnFail is true.parsers
does not contain at least one valid ParamParser subclass
when throwOnFail is true.throwOnFail is true.Returns {success: boolean, data: any} An object with a
success flag and data containing the parsing result, if
successful.
A custom error class that signifies no valid parsers were found
during the parsing process. This error is thrown when all
parsers fail to parse the given parameters and the throwOnFail
flag is set to true in the safeTryParsers method.
try {
const result = ParamParser.safeTryParsers(
parameters, parsers, true
);
} catch (error) {
if (error instanceof ParamParser.NoValidParsersFound) {
console.error(
'No valid parsers could process the parameters.'
);
}
}
Returns Function A class extending Error, representing a specific error when no valid parsers are found.ound.
Represents an error thrown when the parameters provided to a method
are not in an array format as expected. This class extends the
native JavaScript Error class, allowing for instances of this
error to be thrown and caught using standard error handling
mechanisms in JavaScript.
This error is specifically used in scenarios where a method expects its arguments to be provided as an array, and the validation of those arguments fails because they were not provided in an array format. It serves as a clear indicator of the nature of the error to developers, enabling them to quickly identify and rectify the issue in their code.
try {
ParamParser.safeTryParsers(nonArrayParameters, parsers, true);
} catch (error) {
if (error instanceof ParamParser.ParametersMustBeArrayError) {
console.error('Parameters must be provided as an array.');
}
}
A custom error class indicating that the parsers array does not
contain valid parser functions. This error is thrown when the
validation of parsers within ParamParser.safeTryParsers fails
to find any instance that is a subclass of ParamParser. It
extends the native JavaScript Error class, allowing it to be
thrown and caught using standard error handling mechanisms.
This error serves as a clear indicator to developers that the
provided array of parsers does not meet the expected criteria,
specifically that it must contain at least one valid parser
that extends ParamParser. This ensures that the parsing
process can be executed with at least one valid parser function.
try {
ParamParser.safeTryParsers(parameters, [], true);
} catch (error) {
const { ParsersArrayMustContainParsersError } = ParamParser
if (error instanceof ParsersArrayMustContainParsersError) {
console.error(
'The parsers array must contain at least one valid parser.'
);
}
}
A getter method for the toStringTag symbol. This method returns the name of the constructor of the instance. It is used to provide a custom string description of the object, which can be useful for debugging or logging purposes.
const response = new ProxyHandlerResponse();
console.log(response[Symbol.toStringTag]); // logs: "ProxyHandlerResponse"
Returns string The name of the constructor of the instance.
This static method is a Symbol.hasInstance method implementation. It checks if the provided instance is an instance of the class. It does this by comparing the instance's toStringTag or constructor to the class's name or the class itself respectively.
instance Object The instance to check.// Assuming MyClass has implemented this method
const myInstance = new MyClass();
// logs: true
console.log(MyClass[Symbol.hasInstance](myInstance));
Returns boolean True if the instance is of the class, false otherwise.
This static method is used to create a response object. The response object contains the success status, the value, and the context of the response. It also includes a getter for the Symbol.toStringTag property that returns the ResponseType of the ProxyHandler.
success boolean The success status of the response.value any The value of the response.context Object The context of the response.// Create a response object
const response = ProxyHandler.response(
true, 'value', { key: 'context' }
);
// Output: { success: true, value: 'value', context: { key: 'context' },
// [Symbol.toStringTag]: 'ProxyHandlerResponse' }
console.log(response);
Returns Object The response object.
This static getter method is used to retrieve the response type of the ProxyHandler. It returns a string that represents the response type of the ProxyHandler.
ResponseType function A static getter method that
returns the response type of the ProxyHandler.// Get the response type of the ProxyHandler
const responseType = ProxyHandler.ResponseType;
// Output: 'ProxyHandlerResponse'
console.log(responseType);
Returns string A string representing the response type of the ProxyHandler.
This static method is used to retrieve the name of a ProxyHandler type from a given array of arguments. If the array of arguments matches any of the ProxyHandler types, the name of that type is returned. If no match is found, or if the input is not an array, 'custom' is returned.
proxyHandlerType Array<any> An array of arguments to match
against the ProxyHandler types.// Get the name of a type from its arguments
const typeName = ProxyHandler.nameFromType(
['target', 'thisArg', 'argumentsList']
);
// Output: 'apply'
console.log(typeName);
Returns string The name of the matching ProxyHandler type, or 'custom' if no match is found.
This method is used to retrieve all the types of ProxyHandler available in the ProxyHandler.type object. It is useful when you need to iterate over all the types or when you need to check if a certain type exists.
typeNames function A static getter method that returns an
array of keys from the ProxyHandler.type object.// Get all type names
const types = ProxyHandler.typeNames;
// Output: ['apply', 'construct', 'defineProperty', ...]
console.log(types);
Returns Array<string> An array of strings representing the keys of the ProxyHandler.type object.
A static getter method that returns an object containing keyed proxy trap types and their associated expected arguments list by name. A docstring description complete with url shortening links for each entry are provided (links go to the MDN documentation)
type function A static getter method that returns an object
of ProxyHandler types.// Get the 'apply' type
const applyType = ProxyHandler.type.apply;
// Output: ['target', 'thisArg', 'argumentsList']
console.log(applyType());
Returns Object<string, function> An object where each key is a type name and each value is a function that returns an array of strings representing the arguments for that type.
The handler.apply() method is a trap for the [[Call]] object internal method, which is used by operations such as function calls. MDN link: https://t.ly/orBsG
The handler.construct() method is a trap for the [[Construct]] object internal method, which is used by operations such as the new operator. In order for the new operation to be valid on the resulting Proxy object, the target used to initialize the proxy must itself be a valid constructor. MDN link: https://t.ly/1LukS
The handler.defineProperty() method is a trap for the [[DefineOwnProperty]] object internal method, which is used by operations such as Object.defineProperty(). MDN link: https://t.ly/3Ml9y
The handler.deleteProperty() method is a trap for the [[Delete]] object internal method, which is used by operations such as the delete operator. MDN link: https://t.ly/neu2H
The handler.get() method is a trap for the [[Get]] object internal method, which is used by operations such as property accessors. MDN link: https://t.ly/E419x
The handler.getOwnPropertyDescriptor() method is a trap for the [[GetOwnProperty]] object internal method, which is used by operations such as Object.getOwnPropertyDescriptor(). MDN link: https://t.ly/wzPTX
The handler.getPrototypeOf() method is a trap for the [[GetPrototypeOf]] object internal method, which is used by operations such as Object.getPrototypeOf(). MDN link: https://t.ly/Ww4S1
The handler.has() method is a trap for the [[HasProperty]] object internal method, which is used by operations such as the in operator. MDN link: https://t.ly/UcJL-
The handler.isExtensible() method is a trap for the [[IsExtensible]] object internal method, which is used by operations such as Object.isExtensible(). MDN link: https://t.ly/MkdIK
The handler.ownKeys() method is a trap for the [[OwnPropertyKeys]] object internal method, which is used by operations such as Object.keys(), Reflect.ownKeys(), etc. MDN link: https://t.ly/QkiTI
The handler.preventExtensions() method is a trap for the [[PreventExtensions]] object internal method, which is used by operations such as Object.preventExtensions(). MDN link: https://t.ly/nvfjJ
The handler.set() method is a trap for the [[Set]] object internal method, which is used by operations such as using property accessors to set a property's value. MDN link: https://t.ly/FDWcl
The handler.setPrototypeOf() method is a trap for the [[SetPrototypeOf]] object internal method, which is used by operations such as Object.setPrototypeOf(). MDN link: https://t.ly/pS8ej
Extends Map
RefMap class extends the standard Map object to manage a collection of WeakRef values mapped to strong keys. It provides additional functionality such as objectification of values and various utility methods.
Unlike standard Maps or Objects, RefMap stores weak references to objects, allowing them to be garbage-collected if there are no other references to them. This behavior is different from Maps and standard Objects, which maintain strong references to their elements.
args ...any Method to control whether the RefMap should objectify its values. When objectifying, primitive values (number, string, boolean, bigint) are converted to their respective object types, which allows them to be used as WeakRef targets.
setObjectification boolean Flag to enable or disable
objectification. (optional, default true)Returns RefMap The current RefMap instance to allow method chaining.
The function converts a JavaScript Map object into a regular JavaScript object, handling invalid keys by converting them to strings.
Returns object an object; keys that are not either a String or a
Symbol will be converted to a string.
Returns the state indicating whether or not RefMap will attempt to
convert non-valid primitives into targets that are valid input for
new WeakRef object instances. If this value is false then no
objectification will occur.
Returns boolean The current state of objectifyValues.
Setting this value to true, will cause all set values to the Map to
be analyzed for validity as a candidate to be wrapped in a WeakRef
object. If true, and if possible, the object will be turned into an
Object variant first.
value boolean The new state to set for objectifyValues.The get function retrieves a value from a map and returns it, or returns a
default value if the value is null or undefined. The actual retrieved value
is a dereferenced WeakRef. If the result is undefined and this is not the
expected response, it is likely the value has been garbage collected.
key any The key parameter is the key of the value you want to
retrieve from the data structure.defaultValue any The defaultValue parameter is the value that
will be returned if the key does not exist in the map or if the value
associated with the key has been garbage collected (i.e., it no longer
exists).Returns any The method is returning the value associated with the given key. If the value is not found or if it has been garbage collected (deref() returns null), then the defaultValue is returned.
Overrides the set method of Map. Adds a value to the RefMap,
converting it to a WeakRef. Throws an error if the value is not a
valid WeakRef target (e.g., null, undefined, or a registered
symbol). If objectifyValues is enabled, an attempt to convert
primitives to their object variants will be made. These are numbers,
strings, boolean values and bigints.
key any The key to be set on the RefMapvalue any The value to be associated with the keySets multiple values at a single time. The format is an array of array
or rather an array of Object.entries (for example,
[[key1,value1], [key2,value2]]). For each entry pair, if the length
is not 2, either missing a key or value, it will be skipped.
entries values Iterable An iterable of values to add to the RefMap.Returns RepMap returns this to allow for chaining
Removes all elements from the RefMap that have been garbage collected (i.e., their WeakRef no longer points to an object).
Returns RefMap The current RefMap instance to allow method chaining.
Executes a provided function once for each value in the RefMap. The callback function receives the dereferenced value, the value again (as RefMap doesn't use keys), and the RefMap itself. This method provides a way to iterate over and apply operations to the values stored in the RefMap, taking into account that they are weak references and may have been garbage-collected.
forEachFn Function Function to execute for each element. It
takes three arguments: element, element (again, as RefMap has no key), and
the RefMap itself.thisArg any Value to use as this when executing forEachFn.Iterate over the items in the map and pass them to the supplied
function ala Map.prototype.forEach. Note however, there are no
indexes on Maps and as such, the index parameter of the callback
will always be the value's key. Subsequently the array or third
parameter will receive the map instance rather than an array.
forEachFn function the function to use for each element in
the set.thisArg object the this argument to be applied to each
invocation of the forEachFn callback. Note, this value is unable
to be applied if the forEachFn is a big arrow functionReturns an iterator for the values in the RefMap. Each value is dereferenced from its WeakRef before being returned. This method allows iterating over he set's values, similar to how one would iterate over values in a standard Map or Array, but with the understanding that the values are weakly referenced and may no longer exist (in which case they are skipped).
Returns Iterator An iterator for the values.
Determines whether an element with the specified value exists in the
RefMap. For non-objectified sets, this method checks if the dereferenced
values of the map include the specified value.
For objectified sets, strict is set to false which uses loose
equality to allow for things like Object(5) to equal 5. This is important
because otherwise primitives could not be weakly referenced. In the grand
scheme of things, this is only useful if the objectified value is the
one being referenced.
value any The value to check for presence in the RefMap.strict boolean if true, the default, then the supplied value
is hard compared to the dereferenced value (===). If false, then a
loose comparison is used (==) (optional, default true)Returns boolean True if an element with the specified value exists in the RefMap, false otherwise.
The filter function filters the entries of a RefMap object based on
a given filter function. The dereferenced entries of the values of the map
will be passed to the function rather than a WeakRef itself.
A new resulting entry set will be generated and a new RefMap will be made
from these entries and returned. Note that this function never returns
null
filterFn function The filterFn parameter is a function that
will be used to filter the entries in the RefMap. It will be called with
three arguments: the value of the current entry, the key of the current
entry, and the RefMap itself. The function should return truethisArg object The thisArg parameter is an optional argument
that specifies the value to be used as this when executing the
filterFn function. It allows you to explicitly set the context in which
the filterFn function is called. If thisArg is not provided, `thisReturns array The filter method is returning an array of filtered map
entries
The find function iterates over a map and calls a given function on
each value, returning the first value for which the function returns
a truthy value.
The function signature of findFn is
function findFn(value, key, map)
'value' is passed to findFn up to two times; first with the WeakRef
value, second with the result of WeakRef.deref. If findFn
returns true for either of these the dereferenced value will be
returned from the call to RefMap.find.
key represents the key object that the value is mapped to.
map is simply a reference to this map.
findFn findFn is a function that will be called for each
element in the map. It takes three arguments: ref, key, and map;
where ref is the value of the current element in the map, key is
the key of the current element, and map is a reference to the instance
being searched.thisArg The thisArg parameter is the value to be used as
the this value when executing the findFn function. It allows you
to specify the context in which the findFn function should be called.Returns any the first dereferenced value that satisfies the condition
specified by the findFn function. If no value satisfies the condition,
it returns null.
Creates a new array or RefMap with the results of calling a provided
function on every element in the calling RefMap. This method dereferences
each value, applies the mapFn, and collects the results. If toRefMap is
true, a new RefMap is returned; otherwise, an array. This method
differs from Array.map in handling weak references and the potential to
return a new RefMap instead of an array.
mapFn Function Function that produces an element of the new
array or RefMap, taking three arguments.thisArg any Value to use as this when executing mapFn.toRefMap boolean Determines if the output should be a new
RefMap (true) or an array (false).mirrorObjectification boolean If true and toRefMap is
true, the new RefMap mirrors the objectification setting of the
original.Returns (Array | RefMap) A new array or RefMap with each element being
the result of the mapFn.
The function returns an iterator that iterates over the entries of an object, dereferencing any weak references.
Returns Iterator A new iterator object is being returned.
Ensures that the constructor of this object instance's name is returned if the string tag for this instance is queried
Returns string the name of the class
A static method to check if a given value is a valid target for a WeakRef.
value any The value to check for validity as a WeakRef target.Returns boolean True if the value is a valid WeakRef target, false otherwise.
Extends Set
RefSet class extends the standard Set object to manage a collection of WeakRef objects. It provides additional functionality such as objectification of values and various utility methods.
Unlike standard Sets or Arrays, RefSet stores weak references to objects, allowing them to be garbage-collected if there are no other references to them. This behavior is different from Arrays and standard Sets, which maintain strong references to their elements.
Method to control whether the RefSet should objectify its values. When objectifying, primitive values (number, string, boolean, bigint) are converted to their respective object types, which allows them to be used as WeakRef targets.
setObjectification boolean Flag to enable or disable
objectification. (optional, default true)Returns RefSet The current RefSet instance to allow method chaining.
Returns the state indicating whether or not RefSet will attempt to
convert non-valid primitives into targets that are valid input for
new WeakRef object instances. If this value is false then no
objectification will occur.
Returns boolean The current state of objectifyValues.
Setting this value to true, will cause all added values to the Set to
be analyzed for validity as a candidate to be wrapped in a WeakRef
object. If true, and if possible, the object will be turned into an
Object variant first. This will also enable less rigid variable
comparison in the .has() method (i.e. == instead of ===).
value boolean The new state to set for objectifyValues.Overrides the add method of Set. Adds a value to the RefSet, converting it
to a WeakRef. Throws an error if the value is not a valid WeakRef target
(e.g., null, undefined, or a registered symbol). If objectifyValues is
enabled, an attempt to convert primitives to their object variants will be
made. These are numbers, strings, boolean values and big integers.
value any The value to be added to the RefSet.Adds multiple values to the RefSet. The supplied values should be
iterable and truthy. This function defers to .add() for its logic so
each value from the supplied collection of values will also be subject
to the criteria of that function.
values Iterable An iterable of values to add to the RefSet.Removes all elements from the RefSet that have been garbage collected (i.e., their WeakRef no longer points to an object).
Returns RefSet The current RefSet instance to allow method chaining.
Executes a provided function once for each value in the RefSet. The callback function receives the dereferenced value, the value again (as RefSet doesn't use keys), and the RefSet itself. This method provides a way to iterate over and apply operations to the values stored in the RefSet, taking into account that they are weak references and may have been garbage-collected.
forEachFn Function Function to execute for each element. It
takes three arguments: element, element (again, as RefSet has no key), and
the RefSet itself.thisArg any Value to use as this when executing forEachFn.Iterate over the items in the set and pass them to the supplied
function ala Array.prototype.forEach. Note however, there are no
indexes on Sets and as such, the index parameter of the callback
will always be NaN. Subsequently the array or third parameter
will receive the set instance rather than an array.
forEachFn function the function to use for each element in
the set.thisArg object the this argument to be applied to each
invocation of the forEachFn callback. Note, this value is unable
to be applied if the forEachFn is a big arrow functionReturns an iterator for the values in the RefSet. Each value is dereferenced from its WeakRef before being returned. This method allows iterating over he set's values, similar to how one would iterate over values in a standard Set or Array, but with the understanding that the values are weakly referenced and may no longer exist (in which case they are skipped).
Returns Iterator An iterator for the values.
Returns an iterator for the keys of the RefSet. In RefSet, keys and
values are identical, so this method behaves the same as values(). It
provides compatibility with the standard Set interface and allows use in
contexts where keys are expected, despite RefSet not differentiating
between keys and values.
Returns Iterator An iterator for the keys.
Determines whether an element with the specified value exists in the
RefSet. For non-objectified sets, this method checks if the dereferenced
values of the set include the specified value.
For objectified sets, it uses the contains method which accounts for
the objectification. This method differs from standard Set has in that
it works with weak references and considers objectification settings.
value any The value to check for presence in the RefSet.Returns boolean True if an element with the specified value exists in the RefSet, false otherwise.
Checks if the RefSet contains a value that is equal to the specified
value. This method is used primarily in objectified RefSets to determine
the presence of a value, taking into account objectification. It differs
from the has method in that it's tailored for sets that have
transformed their primitive values into objects, whereas has is more
general-purpose.
value any The value to search for in the RefSet.Returns boolean True if the RefSet contains the value, false otherwise.
Creates a new array with all elements that pass the test implemented by
the provided function. This method iterates over each element,
dereferences it, and applies the filter function. Unlike Array filter,
the callback receives the dereferenced value and not an index or array,
reflecting the non-indexed nature of RefSet. Useful for selectively
creating arrays from the set based on certain conditions, especially when
dealing with weak references.
filterFn Function Function to test each element of the RefSet.
The function receives the dereferenced value.thisArg any Value to use as this when executing filterFn.Returns Array A new array with the elements that pass the test.
Returns the value of the first element in the RefSet that satisfies the
provided testing function. Similar to Array find, this method iterates
over the RefSet, dereferencing each value and applying the testing
function. The non-indexed nature of RefSet is considered, as the
callback does not receive an index. This method is useful for finding a
specific element based on a condition.
findFn thisArg any Value to use as this when executing findFn.Returns any The value of the first element in the RefSet that satisfies the testing function, or undefined if none found.
Returns any the dereferenced value if found, or undefined otherwise
Creates a new array or RefSet with the results of calling a provided
function on every element in the calling RefSet. This method dereferences
each value, applies the mapFn, and collects the results. If toRefSet is
true, a new RefSet is returned; otherwise, an array. This method
differs from Array.map in handling weak references and the potential to
return a new RefSet instead of an array.
mapFn Function Function that produces an element of the new
array or RefSet, taking three arguments.thisArg any Value to use as this when executing mapFn.toRefSet boolean Determines if the output should be a new
RefSet (true) or an array (false).mirrorObjectification boolean If true and toRefSet is
true, the new RefSet mirrors the objectification setting of the
original.Returns (Array | RefSet) A new array or RefSet with each element being
the result of the mapFn.
Ensures that the constructor of this object instance's name is returned if the string tag for this instance is queried
Returns string the name of the class
Represents a secure container for storing and retrieving unique symbols associated with data. This class provides methods to add new symbols to the Symkeys and to retrieve data associated with a particular symbol.
domain string an optional prefix string, to which the
separator parameter value will be guaranteed to have in between
the domain (if truthy) and the name of the added key. (optional, default '')separator string defaults to a period. So if your domain
is 'symkeys.internal' then calling add() with a name of
"feature" will result in the full name being
"symkeys.internal.feature" (optional, default '.')// Create a new Symkeys instance
const symkeys = new Symkeys();
// Add a symbol with associated data to the Symkeys
const mySymbol = Symkeys.add('myIdentifier', { foo: 'bar' });
// Retrieve the data using the symbol
const myData = Symkeys.dataFor(mySymbol);
console.log(myData); // Output: { foo: 'bar' }
Adds a new entry to the Symkeys with a unique symbol based on the provided name and associates it with the given data.
named The base name for the symbol to be created.associatedData The data to associate with the symbol. (optional, default {})// Add an entry with associated data
const symbol = Symkeys.add('myEntry', { foo: 'bar' });
// Retrieve the associated data using the symbol
const data = Symkeys.dataFor(symbol);
console.log(data); // Output: { foo: 'bar' }
Returns any The unique symbol created for the entry.
Retrieves the data associated with a given symbol from the Symkeys.
This method allows access to the data that has been associated with a particular symbol in the Symkeys. It is useful for retrieving stored information when only the symbol is known.
forSymbol symbol The symbol whose associated data is to be
retrieved.// Assuming 'mySymbol' is a symbol that has been added to the Symkeys
// with associated data
const data = Symkeys.dataFor(mySymbol);
console.log(data); // Output: The data associated with 'mySymbol'
Returns any The data associated with the symbol, or undefined if the symbol is not found in the Symkeys.
Deletes the data associated with a given symbol from the Symkeys.
This method allows removal of the data that has been associated with a particular symbol in the Symkeys. It is useful when you want to clean up or remove stored information associated with a symbol.
forSymbol Symbol The symbol whose associated data is to be
deleted.replaceWith any Optionally, if replaceWith is not undefined,
a new value can be set after the original is deleted (optional, default undefined)// Assuming 'mySymbol' is a symbol that has been added to the Symkeys
// with associated data
const isDeleted = Symkeys.deleteData(mySymbol);
console.log(isDeleted); // Output: true if data was deleted, false otherwise
Returns boolean Returns true if an element in the Symkeys existed and has been removed, or false if the element does not exist
Checks if the Symkeys instance has data associated with a given symbol.
This method checks if the Symkeys instance has any data associated with the provided symbol. It is useful when you need to verify if data exists for a particular symbol before attempting to retrieve or manipulate it.
forSymbol Symbol The symbol to check for associated data.// Assuming 'mySymbol' is a symbol that has been added to the Symkeys
// with associated data
const hasData = Symkeys.hasData(mySymbol);
console.log(hasData); // Output: true if data exists, false otherwise
Returns boolean Returns true if data exists for the symbol, false otherwise.
Sets the data associated with a given symbol in the Symkeys.
This method allows you to associate data with a particular symbol in the Symkeys. It is useful when you want to store information that can be retrieved later using the symbol.
Note that setting only succeeds if the Symkey symbol has already been added via Symkeys.add
forSymbol Symbol The symbol with which the data is to be
associated.value any The data to be associated with the symbol.// Assuming 'mySymbol' is a symbol that has been added to the Symkeys
// and 'myData' is the data to be associated with 'mySymbol'
Symkeys.setData(mySymbol, myData);
Returns boolean true if the value has been set, false if the key has not yet been added via Symkeys.add
Extracts the token part from a symbol created by the add method.
This method parses the string representation of a symbol to retrieve the unique token that was appended to the symbol's name upon creation. It is useful for debugging or for operations that require knowledge of the token associated with a symbol.
forSymbol symbol The symbol whose token is to be extracted.// Assuming 'mySymbol' is a symbol created with the name 'myEntry'
// and a token 'agftofxob6f'
const token = Symkeys.tokenFor(mySymbol);
console.log(token); // Output: 'agftofxob6f'
Returns any The extracted token or undefined if the token cannot be extracted.
Retrieves the separator used in the Symkeys instance.
This getter method allows access to the separator that is used to distinguish between different parts of a symbol in the Symkeys instance. It is useful when you need to know the separator for parsing symbols or constructing new ones.
// Assuming the Symkeys instance has a separator '.'
const separator = Symkeys.separator;
console.log(separator); // Output: '.'
Returns string The separator used in the Symkeys instance.
Retrieves an iterator for the symbols stored in the Symkeys.
This method provides access to the symbols that have been stored in the Symkeys. It returns an iterator which can be used to loop over all the symbols. This is particularly useful for iterating through all stored data without knowing the individual symbols in advance.
// Assuming the Symkeys has symbols stored
for (const symbol of Symkeys.symbols()) {
console.log(symbol);
}
Returns any An iterator that yields all the symbols stored in the Symkeys.
Calculates a name by combining a provided name, domain, and separator.
This method takes a provided name, domain, and separator as input and constructs a new name by combining these elements. If the domain or separator are not provided, it uses the default domain and separator stored in the Symkeys instance. If the provided name starts with the separator, it removes the leading separator from the name.
If the domain ends with the separator, it removes the trailing separator from the domain. If the domain is empty, it sets the separator to an empty string.
providedName string The name to be used in the calculation.useDomain string? The domain to be used in the calculation.
If not provided, the default domain of the Symkeys instance is used.useSeparator string? The separator to be used in the
calculation. If not provided, the default separator of the Symkeys
instance is used.// Assuming the Symkeys instance has a domain 'symkeys.internal'
// and a separator '.'
const name = Symkeys.calculateName('feature', 'symkeys.public', '/');
console.log(name); // Output: 'symkeys.public/feature'
Returns string The calculated name.
Checks if a given value is a Symkey.
This method checks if the provided value is a Symkey. A Symkey is a symbol that matches a specific pattern. The pattern is defined as a symbol that starts with '@', followed by any characters, a space, a '#', and ends with one or more word characters.
value Symbol The value to check.// Check if a symbol is a Symkey:
const sym = Symbol('@nejs.prototype #rwiy2o905d');
console.log(Symkeys.isSymkey(sym)); // Outputs: true
Returns boolean Returns true if the value is a Symkey, false otherwise.
Generates a random token string.
This method creates a pseudo-random token that can be used for various purposes within the library, such as generating unique identifiers or keys. The token is generated using a base 36 encoding, which includes numbers and lowercase letters.
// Example of getting a random token:
const token = MyClass.token;
console.log(token); // Outputs a string like 'qg6k1zr0is'
Returns any A random token string.
Reusable publicly static key for identifying where data is stored.
Reusable publicly static key for identifying where data is stored.
A static getter that returns a unique, reusable symbol for 'symkeys.domain'.
This getter is used to create a unique symbol that can be used as a key
for storing and retrieving domain-specific data in the Symkeys. The symbol
is created using the Symbol.for method, which ensures that the same
symbol is returned for a given key, in this case 'symkeys.domain'.
// Retrieve the 'symkeys.domain' symbol
const domainSymbol = Symkeys.kDomain;
console.log(domainSymbol); // Outputs: Symbol(symkeys.domain)
Returns Symbol A unique symbol for 'symkeys.domain'.
A static getter that returns a unique, reusable symbol for 'symkeys.separator'.
This getter is used to create a unique symbol that can be used as a key
for storing and retrieving separator-specific data in the Symkeys. The symbol
is created using the Symbol.for method, which ensures that the same
symbol is returned for a given key, in this case 'symkeys.separator'.
// Retrieve the 'symkeys.separator' symbol
const separatorSymbol = Symkeys.kSeparator;
console.log(separatorSymbol); // Outputs: Symbol(symkeys.separator)
Returns Symbol A unique symbol for 'symkeys.separator'.
The AsyncIterable class extends the concept of Iterable to asynchronous operations. It allows creating iterable objects where each element can be an asynchronous entity, like a Promise. This class is particularly useful when dealing with asynchronous data sources, such as API responses, file reading in chunks, or any other data that is not immediately available but arrives over time.
elementsOrFirstElement (Iterable | AsyncGeneratorFunction | Promise | any) An iterable object, an async generator function, a Promise, or the first
element.moreElements ...(Promise | any) Additional elements if the first
argument is not an iterable or an async generator function.Implements the async iterable protocol. When an instance of AsyncIterable
is used in a for await...of loop, this async generator function is
invoked. It yields each element as a Promise, allowing asynchronous
iteration. Elements that are not Promises are automatically wrapped in
a resolved Promise to ensure consistency.
Returns AsyncGenerator An async generator that yields each element as a Promise.
Ensures that the constructor of this object instance's name is returned if the string tag for this instance is queried
Returns string the name of the class
Checks if a given value is an async iterable. This method determines if
the provided value has a Symbol.asyncIterator property that is an async
generator function. It's a precise way to identify if the value conforms
to the async iterable protocol using an async generator function.
Note: This method specifically checks for async generator functions. Some async iterables might use regular async functions that return an async iterator, which this method won't identify.
value any The value to be checked for async iterability.Returns boolean Returns true if the value is an async iterable implemented using an async generator function, false otherwise.
Being able to create a compliant AsyncIterator around any type of
iterable object. This can be wrapped around any type of object that
has a [Symbol.asyncIterator] property assigned to a generator
function.
asyncIterable (object | AsyncGeneratorFunction) any object that has a
[Symbol.asyncIterable] property assigned to a generator function or an
async generator function itself.Returns a new Array derived from the iterable this object
wraps.
Returns array a new Array generated from the wrapped
iterable. The method is generated from using an async for of
loop.
Returns the actual iterable object passed to the constructor that created this instance.
Returns object the object containing the [Symbol.iterator]
The function retrieves the next value in the iterator. If the
the iterator has run its course, reset() can be invoked to
reset the pointer to the beginning of the iteration.
Returns any the next value
Resets the async iterator to the beginning allowing it to be iterated over again.
The existence of this symbol on the object instances, indicates that
it can be used in for(.. of ..) loops and its values can be
extracted from calls to Array.from()
Returns AsyncIterable this is returned since this object is already conforming to the expected JavaScript AsyncIterator interface
Ensures that the constructor of this object instance's name is returned if the string tag for this instance is queried
Returns string the name of the class
Contributions to @nejs/basic-extensions are always welcome. Please refer to our contributing guidelines for more information on how to report issues, submit pull requests, and more.
@nejs/basic-extensions is licensed under the MIT License. See the LICENSE file for more details.
FAQs
Basic but commonly used extensions
The npm package @nejs/basic-extensions receives a total of 0 weekly downloads. As such, @nejs/basic-extensions popularity was classified as not popular.
We found that @nejs/basic-extensions demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
pnpm 10 blocks lifecycle scripts by default to improve security, addressing supply chain attack risks but sparking debate over compatibility and workflow changes.
Product
Socket now supports uv.lock files to ensure consistent, secure dependency resolution for Python projects and enhance supply chain security.
Research
Security News
Socket researchers have discovered multiple malicious npm packages targeting Solana private keys, abusing Gmail to exfiltrate the data and drain Solana wallets.