@nejs/basic-extensions 2.7.0 → 2.8.0

package/dist/mjs/symbol.extensions.js

@@ -0,0 +1,256 @@
+import { Patch } from '@nejs/extension';
+import { Symkeys } from './classes/symkeys.js';
+import { JSONExtensions } from './json.extensions.js';
+const { extractFrom, mightContain } = JSONExtensions.patches;
+/**
+ * `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.
+ */
+export const SymbolExtensions = new Patch(Symbol, {
+    /**
+     * 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.
+     *
+     * @param {string} name The name of the symbol.
+     * @param {*} [data] Optional data to be associated with the symbol.
+     * @returns {symbol} A new symbol created with Symbol.for(), using the
+     * provided name and stringified data (if provided).
+     *
+     * @example
+     * const symbolWithData = Symbol.withData('mySymbol', { foo: 'bar' })
+     * console.log(symbolWithData.toString())
+     * // Output: "Symbol(mySymbol {"foo":"bar"})"
+     *
+     * @example
+     * const symbolWithoutData = Symbol.withData('mySymbol')
+     * console.log(symbolWithoutData.toString())
+     * // Output: "Symbol(mySymbol)"
+     */
+    withData(name, data) {
+        return data !== undefined
+            ? Symbol.for(`${name} ${JSON.stringify(data)}`)
+            : Symbol.for(name);
+    },
+    /**
+     * The `isSymbol` method does exactly what one would it expect. It returns
+     * true if the string matches typeof or instanceof as a symbol.
+     *
+     * @param {*} value checks to see if the `value` is a string
+     * @returns {boolean} `true` if it is a `Symbol`, `false` otherwise
+     */
+    isSymbol(value) {
+        return value && (typeof value === 'symbol');
+    },
+    /**
+     * Returns true if the supplied value is a Symbol created using
+     * `Symbol.for()`.
+     *
+     * @param {any} value 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.
+     * @param {boolean} allowOnlySymbols true if an error should be thrown
+     * if the supplied value is not of type 'symbol'
+     * @returns 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')`
+     */
+    isRegistered(value, allowOnlySymbols = false) {
+        if (!Symbol.isSymbol(value)) {
+            if (allowOnlySymbols) {
+                throw new TypeError('allowOnlySymbols specified; value is not a symbol');
+            }
+            return false;
+        }
+        return Symbol.keyFor(value) !== undefined;
+    },
+    /**
+     * 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')`.
+     *
+     * @param {any} value 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.
+     * @param {boolean} allowOnlySymbols true if an error should be thrown
+     * if the supplied value is not of type 'symbol'
+     * @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')`
+     * @returns true if the `value` in question is both a `symbol` and has
+     * returns `undefined` if passed to `Symbol.keyFor`
+     */
+    isNonRegistered(value, allowOnlySymbols = false) {
+        return !Symbol.isRegistered(value, allowOnlySymbols);
+    },
+    /**
+     * `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}
+     * @see {@link SymKeys}
+     * @example
+     * // 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
+     */
+    keys: new Symkeys('nejs'),
+});
+export const SymbolPrototypeExtensions = new Patch(Symbol.prototype, {
+    [Patch.kMutablyHidden]: {
+        /**
+         * 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}
+         * @readonly
+         *
+         * @example
+         * const sym = Symbol('example')
+         * console.log(typeof sym)        // 'symbol'
+         * console.log(typeof sym.instance) // 'object'
+         */
+        get instance() {
+            return Object(this);
+        },
+        /**
+         * 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 {@link 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.
+         *
+         * @type {Object|Function}
+         * @readonly
+         *
+         * @example
+         * const keys = new Symkeys
+         * const key = keys.add('example', {count: 0})
+         * const data = key.data // note this isn't function!!
+         * const count = data.count
+         *
+         * @example
+         * const sym = Symbol.for('fun {"name":"Brie"}')
+         * let json = sym.data() // {name: 'Brie'} JS object
+         *
+         * @example
+         * const sym = Symbol('mySymbol')
+         * let data = sym.data() // undefined
+         */
+        get data() {
+            if (Symbol?.keys && Symkeys.isSymkey(this)) {
+                const possibleData = Symbol.keys[this];
+                if (possibleData) {
+                    return possibleData;
+                }
+            }
+            return extractFrom(string);
+        },
+        /**
+         * 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.
+         *
+         * @param {any} value - The value to be set as the symbol's data.
+         * @returns {boolean} - Returns true if the data was successfully set,
+         * false otherwise.
+         *
+         * @example
+         * 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
+         *
+         * @example
+         * 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 }
+         */
+        set data(value) {
+            if (Symkeys.isSymkey(this) && Symkeys.hasData(this)) {
+                Symbol.keys.setData(this, value);
+            }
+        },
+        /**
+         * 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.
+         *
+         * @returns {boolean} - Returns true if the symbol might have embedded
+         * JSON, false otherwise.
+         *
+         * @example
+         * const sym = Symbol.for('fun {"name":"Brie"}')
+         * console.log(sym.mightHaveEmbeddedJSON) // Output: true
+         *
+         * @example
+         * const sym = Symbol('mySymbol')
+         * console.log(sym.mightHaveEmbeddedJSON) // Output: false
+         */
+        get mightHaveEmbeddedJSON() {
+            return mightContain(this.description) && typeof this.data === 'function';
+        },
+    }
+});
+//# sourceMappingURL=symbol.extensions.js.map

package/dist/mjs/symbol.extensions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"symbol.extensions.js","sourceRoot":"","sources":["../../src/symbol.extensions.js"],"names":[],"mappings":"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"}

package/dist/mjs/{weakrefextensions.js → weakref.extensions.js}

@@ -13,4 +13,4 @@ export const WeakRefExtensions = new Patch(WeakRef, {
             (value === null || value === undefined));
     },
 });
-//# sourceMappingURL=weakrefextensions.js.map
+//# sourceMappingURL=weakref.extensions.js.map

package/dist/mjs/weakref.extensions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"weakref.extensions.js","sourceRoot":"","sources":["../../src/weakref.extensions.js"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAA;AAEvC,MAAM,CAAC,MAAM,iBAAiB,GAAG,IAAI,KAAK,CAAC,OAAO,EAAE;IAClD;;;;;;OAMG;IACH,gBAAgB,CAAC,KAAK;QACpB,OAAO,CAAC,CACN,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,SAAS,CAAC;YACjE,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,KAAK,KAAK,QAAQ,CAAC;YACxD,CAAC,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,CAAC,CACxC,CAAA;IACH,CAAC;CACF,CAAC,CAAA"}