Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More →
ts-enum-util
Advanced tools
ts-enum-util - npm Package Compare versions
Comparing version 1.0.0 to 2.0.0
@@ -35,3 +35,3 @@ "use strict"; | ||
| * string key for values and using a plain Object: | ||
| * {@link https://jsperf.com/polyfill-map-vs-es6-map-vs-object-with-string-key} | ||
| * {@link https://www.measurethat.net/Benchmarks/Show/2514/1/map-keyed-by-string-or-number} | ||
| */ | ||
@@ -57,20 +57,4 @@ this.keysByValueMap = new Map(); | ||
| /** | ||
| * Creates a new EnumWrapper for an enum-like object. | ||
| * You probably want to use {@link EnumWrapper.getCachedInstance} for typical enums, because it will | ||
| * cache the result. | ||
| * This method may be useful if you want an EnumWrapper for an enum-like object that is dynamically | ||
| * built at runtime, is used only within a limited/transient context in the application, and is likely | ||
| * to clutter the cache without ever being reused. | ||
| * @param enumObj - An enum-like object. | ||
| * @return A new instance of EnumWrapper for the provided enumObj. | ||
| */ | ||
| EnumWrapper.createUncachedInstance = function (enumObj) { | ||
| return new EnumWrapper(enumObj); | ||
| }; | ||
| /** | ||
| * Gets a cached EnumWrapper for an enum-like object. | ||
| * Creates and caches a new EnumWrapper if one is not already cached. | ||
| * This is most useful for typical enums that are statically defined, because the cached EnumWrapper instance | ||
| * will be quickly retrieved/reused on every subsequent call to get() for the same enum object. | ||
| * Use {@link EnumWrapper.createUncachedInstance} if you don't want the EnumWrapper to be cached. | ||
| * @param enumObj - An enum-like object. | ||
@@ -80,6 +64,6 @@ * @return An instance of EnumWrapper for the provided enumObj. | ||
| EnumWrapper.getCachedInstance = function (enumObj) { | ||
| var result = this.instancesCache.get(enumObj); | ||
| var result = EnumWrapper.instancesCache.get(enumObj); | ||
| if (!result) { | ||
| result = this.createUncachedInstance(enumObj); | ||
| this.instancesCache.set(enumObj, result); | ||
| result = new EnumWrapper(enumObj); | ||
| EnumWrapper.instancesCache.set(enumObj, result); | ||
| } | ||
@@ -422,9 +406,11 @@ return result; | ||
| * Used as a cache for {@link EnumWrapper.getCachedInstance} (and {@link $enum}). | ||
| * NOTE: Performance tests show that object key lookups into a Map (even if it's a slow polyfill) are plenty fast | ||
| * for this use case of a relatively small number of items in the map, assuming you don't do something stupid | ||
| * like lookup a cached instance within a tight loop. It's also an order of magnitude faster than building | ||
| * a unique string key for each object and using a fast native Map with the generated string key: | ||
| * {@link https://jsperf.com/map-with-object-keys} | ||
| * NOTE: WeakMap has very fast lookups and avoids memory leaks if used on a temporary | ||
| * enum-like object. Even if a WeakMap implementation is very naiive (like a Map polyfill), | ||
| * lookups are plenty fast for this use case of a relatively small number of enums within | ||
| * a project. Just don't perform cached lookups inside tight loops when | ||
| * you could cache the result in a local variable, and you'll be fine :) | ||
| * {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakMap} | ||
| * {@link https://www.measurethat.net/Benchmarks/Show/2513/5/map-keyed-by-object} | ||
| */ | ||
| EnumWrapper.instancesCache = new Map(); | ||
| EnumWrapper.instancesCache = new WeakMap(); | ||
| return EnumWrapper; | ||
@@ -434,19 +420,9 @@ }()); | ||
| /** | ||
| * Convenience function for getting/creating an {@link EnumWrapper} instance. | ||
| * This is a short-hand way of calling {@link EnumWrapper.getCachedInstance}. | ||
| * or {@link EnumWrapper.createUncachedInstance}. | ||
| * Alias of {@link EnumWrapper.getCachedInstance} for convenience. | ||
| * Gets a cached EnumWrapper for an enum-like object. | ||
| * Creates and caches a new EnumWrapper if one is not already cached. | ||
| * @param enumObj - An enum-like object. | ||
| * @param useCache - If true, then a cached instance is created and/or returned. | ||
| * @return A new or cached instance of EnumWrapper for the provided enumObj. | ||
| * @return An instance of EnumWrapper for the provided enumObj. | ||
| */ | ||
| function $enum(enumObj, useCache) { | ||
| if (useCache === void 0) { useCache = true; } | ||
| if (useCache) { | ||
| return EnumWrapper.getCachedInstance(enumObj); | ||
| } | ||
| else { | ||
| return EnumWrapper.createUncachedInstance(enumObj); | ||
| } | ||
| } | ||
| exports.$enum = $enum; | ||
| exports.$enum = EnumWrapper.getCachedInstance; | ||
| /** | ||
@@ -453,0 +429,0 @@ * Return true if the specified object key value is NOT an integer index key. |
@@ -33,3 +33,3 @@ /** | ||
| * string key for values and using a plain Object: | ||
| * {@link https://jsperf.com/polyfill-map-vs-es6-map-vs-object-with-string-key} | ||
| * {@link https://www.measurethat.net/Benchmarks/Show/2514/1/map-keyed-by-string-or-number} | ||
| */ | ||
@@ -55,20 +55,4 @@ this.keysByValueMap = new Map(); | ||
| /** | ||
| * Creates a new EnumWrapper for an enum-like object. | ||
| * You probably want to use {@link EnumWrapper.getCachedInstance} for typical enums, because it will | ||
| * cache the result. | ||
| * This method may be useful if you want an EnumWrapper for an enum-like object that is dynamically | ||
| * built at runtime, is used only within a limited/transient context in the application, and is likely | ||
| * to clutter the cache without ever being reused. | ||
| * @param enumObj - An enum-like object. | ||
| * @return A new instance of EnumWrapper for the provided enumObj. | ||
| */ | ||
| EnumWrapper.createUncachedInstance = function (enumObj) { | ||
| return new EnumWrapper(enumObj); | ||
| }; | ||
| /** | ||
| * Gets a cached EnumWrapper for an enum-like object. | ||
| * Creates and caches a new EnumWrapper if one is not already cached. | ||
| * This is most useful for typical enums that are statically defined, because the cached EnumWrapper instance | ||
| * will be quickly retrieved/reused on every subsequent call to get() for the same enum object. | ||
| * Use {@link EnumWrapper.createUncachedInstance} if you don't want the EnumWrapper to be cached. | ||
| * @param enumObj - An enum-like object. | ||
@@ -78,6 +62,6 @@ * @return An instance of EnumWrapper for the provided enumObj. | ||
| EnumWrapper.getCachedInstance = function (enumObj) { | ||
| var result = this.instancesCache.get(enumObj); | ||
| var result = EnumWrapper.instancesCache.get(enumObj); | ||
| if (!result) { | ||
| result = this.createUncachedInstance(enumObj); | ||
| this.instancesCache.set(enumObj, result); | ||
| result = new EnumWrapper(enumObj); | ||
| EnumWrapper.instancesCache.set(enumObj, result); | ||
| } | ||
@@ -420,9 +404,11 @@ return result; | ||
| * Used as a cache for {@link EnumWrapper.getCachedInstance} (and {@link $enum}). | ||
| * NOTE: Performance tests show that object key lookups into a Map (even if it's a slow polyfill) are plenty fast | ||
| * for this use case of a relatively small number of items in the map, assuming you don't do something stupid | ||
| * like lookup a cached instance within a tight loop. It's also an order of magnitude faster than building | ||
| * a unique string key for each object and using a fast native Map with the generated string key: | ||
| * {@link https://jsperf.com/map-with-object-keys} | ||
| * NOTE: WeakMap has very fast lookups and avoids memory leaks if used on a temporary | ||
| * enum-like object. Even if a WeakMap implementation is very naiive (like a Map polyfill), | ||
| * lookups are plenty fast for this use case of a relatively small number of enums within | ||
| * a project. Just don't perform cached lookups inside tight loops when | ||
| * you could cache the result in a local variable, and you'll be fine :) | ||
| * {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakMap} | ||
| * {@link https://www.measurethat.net/Benchmarks/Show/2513/5/map-keyed-by-object} | ||
| */ | ||
| EnumWrapper.instancesCache = new Map(); | ||
| EnumWrapper.instancesCache = new WeakMap(); | ||
| return EnumWrapper; | ||
@@ -432,18 +418,9 @@ }()); | ||
| /** | ||
| * Convenience function for getting/creating an {@link EnumWrapper} instance. | ||
| * This is a short-hand way of calling {@link EnumWrapper.getCachedInstance}. | ||
| * or {@link EnumWrapper.createUncachedInstance}. | ||
| * Alias of {@link EnumWrapper.getCachedInstance} for convenience. | ||
| * Gets a cached EnumWrapper for an enum-like object. | ||
| * Creates and caches a new EnumWrapper if one is not already cached. | ||
| * @param enumObj - An enum-like object. | ||
| * @param useCache - If true, then a cached instance is created and/or returned. | ||
| * @return A new or cached instance of EnumWrapper for the provided enumObj. | ||
| * @return An instance of EnumWrapper for the provided enumObj. | ||
| */ | ||
| export function $enum(enumObj, useCache) { | ||
| if (useCache === void 0) { useCache = true; } | ||
| if (useCache) { | ||
| return EnumWrapper.getCachedInstance(enumObj); | ||
| } | ||
| else { | ||
| return EnumWrapper.createUncachedInstance(enumObj); | ||
| } | ||
| } | ||
| export var $enum = EnumWrapper.getCachedInstance; | ||
| /** | ||
@@ -450,0 +427,0 @@ * Return true if the specified object key value is NOT an integer index key. |
@@ -29,7 +29,9 @@ /** | ||
| * Used as a cache for {@link EnumWrapper.getCachedInstance} (and {@link $enum}). | ||
| * NOTE: Performance tests show that object key lookups into a Map (even if it's a slow polyfill) are plenty fast | ||
| * for this use case of a relatively small number of items in the map, assuming you don't do something stupid | ||
| * like lookup a cached instance within a tight loop. It's also an order of magnitude faster than building | ||
| * a unique string key for each object and using a fast native Map with the generated string key: | ||
| * {@link https://jsperf.com/map-with-object-keys} | ||
| * NOTE: WeakMap has very fast lookups and avoids memory leaks if used on a temporary | ||
| * enum-like object. Even if a WeakMap implementation is very naiive (like a Map polyfill), | ||
| * lookups are plenty fast for this use case of a relatively small number of enums within | ||
| * a project. Just don't perform cached lookups inside tight loops when | ||
| * you could cache the result in a local variable, and you'll be fine :) | ||
| * {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakMap} | ||
| * {@link https://www.measurethat.net/Benchmarks/Show/2513/5/map-keyed-by-object} | ||
| */ | ||
@@ -50,3 +52,3 @@ private static readonly instancesCache; | ||
| * string key for values and using a plain Object: | ||
| * {@link https://jsperf.com/polyfill-map-vs-es6-map-vs-object-with-string-key} | ||
| * {@link https://www.measurethat.net/Benchmarks/Show/2514/1/map-keyed-by-string-or-number} | ||
| */ | ||
@@ -70,46 +72,4 @@ private readonly keysByValueMap; | ||
| /** | ||
| * Creates a new EnumWrapper for an enum-like object with number values. | ||
| * You probably want to use {@link EnumWrapper.getCachedInstance} for typical enums, because it will | ||
| * cache the result. | ||
| * This method may be useful if you want an EnumWrapper for an enum-like object that is dynamically | ||
| * built at runtime, is used only within a limited/transient context in the application, and is likely | ||
| * to clutter the cache without ever being reused. | ||
| * @param enumObj - An enum-like object with number values. | ||
| * @return A new instance of EnumWrapper for the provided enumObj. | ||
| * | ||
| * @template T - Type of the enum-like object that is being wrapped. | ||
| */ | ||
| static createUncachedInstance<T extends EnumLike<number, keyof T>>(enumObj: T): EnumWrapper<number, T>; | ||
| /** | ||
| * Creates a new EnumWrapper for an enum-like object with string values. | ||
| * You probably want to use {@link EnumWrapper.getCachedInstance} for typical enums, because it will | ||
| * cache the result. | ||
| * This method may be useful if you want an EnumWrapper for an enum-like object that is dynamically | ||
| * built at runtime, is used only within a limited/transient context in the application, and is likely | ||
| * to clutter the cache without ever being reused. | ||
| * @param enumObj - An enum-like object with string values. | ||
| * @return A new instance of EnumWrapper for the provided enumObj. | ||
| * | ||
| * @template T - Type of the enum-like object that is being wrapped. | ||
| */ | ||
| static createUncachedInstance<T extends EnumLike<string, keyof T>>(enumObj: T): EnumWrapper<string, T>; | ||
| /** | ||
| * Creates a new EnumWrapper for an enum-like object with a mix of number and string values. | ||
| * You probably want to use {@link EnumWrapper.getCachedInstance} for typical enums, because it will | ||
| * cache the result. | ||
| * This method may be useful if you want an EnumWrapper for an enum-like object that is dynamically | ||
| * built at runtime, is used only within a limited/transient context in the application, and is likely | ||
| * to clutter the cache without ever being reused. | ||
| * @param enumObj - An enum-like object with a mix of number and string values. | ||
| * @return A new instance of EnumWrapper for the provided enumObj. | ||
| * | ||
| * @template T - Type of the enum-like object that is being wrapped. | ||
| */ | ||
| static createUncachedInstance<T extends EnumLike<number | string, keyof T>>(enumObj: T): EnumWrapper<number | string, T>; | ||
| /** | ||
| * Gets a cached EnumWrapper for an enum-like object with number values. | ||
| * Creates and caches a new EnumWrapper if one is not already cached. | ||
| * This is most useful for typical enums that are statically defined, because the cached EnumWrapper instance | ||
| * will be quickly retrieved/reused on every subsequent call to get() for the same enum object. | ||
| * Use {@link EnumWrapper.createUncachedInstance} if you don't want the EnumWrapper to be cached. | ||
| * @param enumObj - An enum-like object with number values. | ||
@@ -124,5 +84,2 @@ * @return An instance of EnumWrapper for the provided enumObj. | ||
| * Creates and caches a new EnumWrapper if one is not already cached. | ||
| * This is most useful for typical enums that are statically defined, because the cached EnumWrapper instance | ||
| * will be quickly retrieved/reused on every subsequent call to get() for the same enum object. | ||
| * Use {@link EnumWrapper.createUncachedInstance} if you don't want the EnumWrapper to be cached. | ||
| * @param enumObj - An enum-like object with string values. | ||
@@ -137,5 +94,2 @@ * @return An instance of EnumWrapper for the provided enumObj. | ||
| * Creates and caches a new EnumWrapper if one is not already cached. | ||
| * This is most useful for typical enums that are statically defined, because the cached EnumWrapper instance | ||
| * will be quickly retrieved/reused on every subsequent call to get() for the same enum object. | ||
| * Use {@link EnumWrapper.createUncachedInstance} if you don't want the EnumWrapper to be cached. | ||
| * @param enumObj - An enum-like object with a mixture of number and string values. | ||
@@ -520,33 +474,8 @@ * @return An instance of EnumWrapper for the provided enumObj. | ||
| /** | ||
| * Convenience function for getting/creating an {@link EnumWrapper} instance. | ||
| * This is a short-hand way of calling {@link EnumWrapper.getCachedInstance}. | ||
| * or {@link EnumWrapper.createUncachedInstance}. | ||
| * @param enumObj - An enum-like object with number values. | ||
| * @param useCache - If true, then a cached instance is created and/or returned. | ||
| * @return A new or cached instance of EnumWrapper for the provided enumObj. | ||
| * | ||
| * @template T - Type of the enum-like object that is being wrapped. | ||
| * Alias of {@link EnumWrapper.getCachedInstance} for convenience. | ||
| * Gets a cached EnumWrapper for an enum-like object. | ||
| * Creates and caches a new EnumWrapper if one is not already cached. | ||
| * @param enumObj - An enum-like object. | ||
| * @return An instance of EnumWrapper for the provided enumObj. | ||
| */ | ||
| export declare function $enum<T extends EnumLike<number, keyof T>>(enumObj: T, useCache?: boolean): EnumWrapper<number, T>; | ||
| /** | ||
| * Convenience function for getting/creating an {@link EnumWrapper} instance. | ||
| * This is a short-hand way of calling {@link EnumWrapper.getCachedInstance}. | ||
| * or {@link EnumWrapper.createUncachedInstance}. | ||
| * @param enumObj - An enum-like object with string values. | ||
| * @param useCache - If true, then a cached instance is created and/or returned. | ||
| * @return A new or cached instance of EnumWrapper for the provided enumObj. | ||
| * | ||
| * @template T - Type of the enum-like object that is being wrapped. | ||
| */ | ||
| export declare function $enum<T extends EnumLike<string, keyof T>>(enumObj: T, useCache?: boolean): EnumWrapper<string, T>; | ||
| /** | ||
| * Convenience function for getting/creating an {@link EnumWrapper} instance. | ||
| * This is a short-hand way of calling {@link EnumWrapper.getCachedInstance}. | ||
| * or {@link EnumWrapper.createUncachedInstance}. | ||
| * @param enumObj - An enum-like object with a mixture of number and string values. | ||
| * @param useCache - If true, then a cached instance is created and/or returned. | ||
| * @return A new or cached instance of EnumWrapper for the provided enumObj. | ||
| * | ||
| * @template T - Type of the enum-like object that is being wrapped. | ||
| */ | ||
| export declare function $enum<T extends EnumLike<number | string, keyof T>>(enumObj: T, useCache?: boolean): EnumWrapper<number | string, T>; | ||
| export declare const $enum: typeof EnumWrapper.getCachedInstance; |
| { | ||
| "name": "ts-enum-util", | ||
| "version": "1.0.0", | ||
| "version": "2.0.0", | ||
| "description": "TypeScript Enum Utilities", | ||
@@ -5,0 +5,0 @@ "repository": { |
@@ -29,2 +29,4 @@ [](https://www.npmjs.com/package/ts-enum-util) | ||
| - [Limitations](#limitations) | ||
| - [Known Issues](#known-issues) | ||
| - [`WeakMap` Polyfill](#weakmap-polyfill) | ||
| - [General Concepts](#general-concepts) | ||
@@ -302,6 +304,6 @@ - [Enum-Like Object](#enum-like-object) | ||
| ### Wrapped enums are Map-Like | ||
| A wrapped enum is similar to a read-only `Map` of enum "entry" tuples. | ||
| A wrapped enum is similar to a read-only `Map` of enum name -> enum value. | ||
| See also: | ||
| - [Map-Like Interface](#map-like-interface) | ||
| - [Map-Like Interface](#map-like-interface) (has explanation of why there's no `get()` or `has()` method) | ||
| - [Guaranteed Order of Iteration](#guaranteed-order-of-iteration) | ||
@@ -341,2 +343,3 @@ ```ts | ||
| - `Map` | ||
| - `WeakMap` | ||
| - `Symbol.iterator` | ||
@@ -349,2 +352,10 @@ | ||
| ## Known Issues | ||
| ### `WeakMap` Polyfill | ||
| `WeakMap` polyfills typically store values directly on the "key" object (the run-time `enum` object, in this case) as a non-enumerable "secret" (randomly generated) property. This allows for quick O(1) constant time lookups and garbage collection of the value along with the key object, but does add a property to the object. The `WeakMap` secret property will NOT be iterated in `for ... in` loops, and will NOT be included in the results of `Object.keys()`, but it WILL be included in the result of `Object.getOwnPropertyNames()`. | ||
| It's hard to imagine this actually causing any problems, and all mainstream browsers have natively supported `WeakMap` since about 2014-2015, so I have decided to go ahead with relying on `WeakMap`. If you run into a problem caused by this, please [report an issue on github](https://github.com/UselessPickles/ts-enum-util/issues). | ||
| Read more about the use of `WeakMap` for caching `EnumWrapper` instances here: [Caching](#caching) | ||
| ## General Concepts | ||
@@ -402,8 +413,14 @@ ### Enum-Like Object | ||
| ### Caching | ||
| By default, `EnumWrapper` instances are cached for quick subsequent retrieval via the [$enum](#enum) function. | ||
| `EnumWrapper` instances are cached using an ES6 `WeakMap` for quick subsequent retrieval via the [$enum](#enum) function. This allows you to easily access the `EnumWrapper` functionality for a given enum via the `$enum` function throughout your codebase without worrying about storing a reference to an `EnumWrapper` that is accessible by all of the relevant code. | ||
| The reasoning behind this is that enums are static constructs. A given project will have a relatively small finite number of enums that never change during execution. The combination of caching and the simple [$enum](#enum) function allows you to obtain an `EnumWrapper` instance conveniently whenever you need it, without worrying about maintaining a global reference to it. Of course, it's still good practice to at least temporarily store a reference to the `EnumWrapper` instance within certain code contexts where you heavily use a particular enum's wrapper. | ||
| The use of the `WeakMap` means that even if you use `ts-enum-util` on temporary, dynamically-generated, enum-like objects, there will be no excessive cache bloat or memory leaks. A cached `EnumWrapper` instance will be garbage collected when the enum-like object it is mapped to is garbage collected. | ||
| Consider explicitly avoiding caching (via an optional param to `$enum`) if you are using `ts-enum-util` to work with an ad-hoc dynamically generated "enum-like" object that is specific to a particular function execution, class instance, etc.. This is useful to avoid cluttering the cache and unnecessarily occupying memory with an `EnumWrapper` that will never be retrieved from the cache. | ||
| Although `WeakMap` lookups can be extremely efficient (constant time lookups in typical implementations), beware that the ECMAScript specification only requires lookups to be "on average" less than O(n) linear time. As such, you should still excercise caution against needlessly obtaining cached references via `$enum` when making heavy use of `EnumWrapper` functionality. Consider storing the result of `$enum()` in a local variable before making multiple calls to its methods, especially if the `EnumWrapper`'s features are used within a loop. | ||
| Despite the above warning, it is noteworthy that even the worst case implementation still produces extremely quick lookups for a relatively small number of items (like the number of enums that you are likely have in a project). For example, see [this performance test](https://www.measurethat.net/Benchmarks/Show/2513/5/map-keyed-by-object) of lookups into maps containing 500 entries, including a simple `Map` polyfill implementation. | ||
| Read about a potential [`WeakMap` Polyfill issue](#weakmap-polyfill). | ||
| Read more about `WeakMap` on the [MDN website](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakMap). | ||
| ## API Reference | ||
@@ -427,8 +444,6 @@ Also see the source code or the distributed `index.d.ts` file for complete details of method signatures/overloads, detailed method/param documentation, etc. | ||
| function $enum( | ||
| enumObj: EnumLike, | ||
| useCache: boolean = true | ||
| enumObj: EnumLike | ||
| ): EnumWrapper | ||
| ``` | ||
| - `enumObj` - An enum or "enum-like" object. | ||
| - `useCache` - False to force a new instance of `EnumWrapper` to be created and returned without any caching. | ||
@@ -435,0 +450,0 @@ ### Types |
149
src/index.ts
@@ -32,9 +32,11 @@ /** | ||
| * Used as a cache for {@link EnumWrapper.getCachedInstance} (and {@link $enum}). | ||
| * NOTE: Performance tests show that object key lookups into a Map (even if it's a slow polyfill) are plenty fast | ||
| * for this use case of a relatively small number of items in the map, assuming you don't do something stupid | ||
| * like lookup a cached instance within a tight loop. It's also an order of magnitude faster than building | ||
| * a unique string key for each object and using a fast native Map with the generated string key: | ||
| * {@link https://jsperf.com/map-with-object-keys} | ||
| * NOTE: WeakMap has very fast lookups and avoids memory leaks if used on a temporary | ||
| * enum-like object. Even if a WeakMap implementation is very naiive (like a Map polyfill), | ||
| * lookups are plenty fast for this use case of a relatively small number of enums within | ||
| * a project. Just don't perform cached lookups inside tight loops when | ||
| * you could cache the result in a local variable, and you'll be fine :) | ||
| * {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakMap} | ||
| * {@link https://www.measurethat.net/Benchmarks/Show/2513/5/map-keyed-by-object} | ||
| */ | ||
| private static readonly instancesCache = new Map<object, EnumWrapper>(); | ||
| private static readonly instancesCache = new WeakMap<object, EnumWrapper>(); | ||
@@ -56,3 +58,3 @@ /** | ||
| * string key for values and using a plain Object: | ||
| * {@link https://jsperf.com/polyfill-map-vs-es6-map-vs-object-with-string-key} | ||
| * {@link https://www.measurethat.net/Benchmarks/Show/2514/1/map-keyed-by-string-or-number} | ||
| */ | ||
@@ -80,66 +82,4 @@ private readonly keysByValueMap = new Map<V, keyof T>(); | ||
| /** | ||
| * Creates a new EnumWrapper for an enum-like object with number values. | ||
| * You probably want to use {@link EnumWrapper.getCachedInstance} for typical enums, because it will | ||
| * cache the result. | ||
| * This method may be useful if you want an EnumWrapper for an enum-like object that is dynamically | ||
| * built at runtime, is used only within a limited/transient context in the application, and is likely | ||
| * to clutter the cache without ever being reused. | ||
| * @param enumObj - An enum-like object with number values. | ||
| * @return A new instance of EnumWrapper for the provided enumObj. | ||
| * | ||
| * @template T - Type of the enum-like object that is being wrapped. | ||
| */ | ||
| public static createUncachedInstance<T extends EnumLike<number, keyof T>>( | ||
| enumObj: T | ||
| ): EnumWrapper<number, T>; | ||
| /** | ||
| * Creates a new EnumWrapper for an enum-like object with string values. | ||
| * You probably want to use {@link EnumWrapper.getCachedInstance} for typical enums, because it will | ||
| * cache the result. | ||
| * This method may be useful if you want an EnumWrapper for an enum-like object that is dynamically | ||
| * built at runtime, is used only within a limited/transient context in the application, and is likely | ||
| * to clutter the cache without ever being reused. | ||
| * @param enumObj - An enum-like object with string values. | ||
| * @return A new instance of EnumWrapper for the provided enumObj. | ||
| * | ||
| * @template T - Type of the enum-like object that is being wrapped. | ||
| */ | ||
| public static createUncachedInstance<T extends EnumLike<string, keyof T>>( | ||
| enumObj: T | ||
| ): EnumWrapper<string, T>; | ||
| /** | ||
| * Creates a new EnumWrapper for an enum-like object with a mix of number and string values. | ||
| * You probably want to use {@link EnumWrapper.getCachedInstance} for typical enums, because it will | ||
| * cache the result. | ||
| * This method may be useful if you want an EnumWrapper for an enum-like object that is dynamically | ||
| * built at runtime, is used only within a limited/transient context in the application, and is likely | ||
| * to clutter the cache without ever being reused. | ||
| * @param enumObj - An enum-like object with a mix of number and string values. | ||
| * @return A new instance of EnumWrapper for the provided enumObj. | ||
| * | ||
| * @template T - Type of the enum-like object that is being wrapped. | ||
| */ | ||
| public static createUncachedInstance<T extends EnumLike<number | string, keyof T>>( | ||
| enumObj: T | ||
| ): EnumWrapper<number | string, T>; | ||
| /** | ||
| * Creates a new EnumWrapper for an enum-like object. | ||
| * You probably want to use {@link EnumWrapper.getCachedInstance} for typical enums, because it will | ||
| * cache the result. | ||
| * This method may be useful if you want an EnumWrapper for an enum-like object that is dynamically | ||
| * built at runtime, is used only within a limited/transient context in the application, and is likely | ||
| * to clutter the cache without ever being reused. | ||
| * @param enumObj - An enum-like object. | ||
| * @return A new instance of EnumWrapper for the provided enumObj. | ||
| */ | ||
| public static createUncachedInstance(enumObj: any): EnumWrapper { | ||
| return new EnumWrapper(enumObj); | ||
| } | ||
| /** | ||
| * Gets a cached EnumWrapper for an enum-like object with number values. | ||
| * Creates and caches a new EnumWrapper if one is not already cached. | ||
| * This is most useful for typical enums that are statically defined, because the cached EnumWrapper instance | ||
| * will be quickly retrieved/reused on every subsequent call to get() for the same enum object. | ||
| * Use {@link EnumWrapper.createUncachedInstance} if you don't want the EnumWrapper to be cached. | ||
| * @param enumObj - An enum-like object with number values. | ||
@@ -156,5 +96,2 @@ * @return An instance of EnumWrapper for the provided enumObj. | ||
| * Creates and caches a new EnumWrapper if one is not already cached. | ||
| * This is most useful for typical enums that are statically defined, because the cached EnumWrapper instance | ||
| * will be quickly retrieved/reused on every subsequent call to get() for the same enum object. | ||
| * Use {@link EnumWrapper.createUncachedInstance} if you don't want the EnumWrapper to be cached. | ||
| * @param enumObj - An enum-like object with string values. | ||
@@ -171,5 +108,2 @@ * @return An instance of EnumWrapper for the provided enumObj. | ||
| * Creates and caches a new EnumWrapper if one is not already cached. | ||
| * This is most useful for typical enums that are statically defined, because the cached EnumWrapper instance | ||
| * will be quickly retrieved/reused on every subsequent call to get() for the same enum object. | ||
| * Use {@link EnumWrapper.createUncachedInstance} if you don't want the EnumWrapper to be cached. | ||
| * @param enumObj - An enum-like object with a mixture of number and string values. | ||
@@ -186,5 +120,2 @@ * @return An instance of EnumWrapper for the provided enumObj. | ||
| * Creates and caches a new EnumWrapper if one is not already cached. | ||
| * This is most useful for typical enums that are statically defined, because the cached EnumWrapper instance | ||
| * will be quickly retrieved/reused on every subsequent call to get() for the same enum object. | ||
| * Use {@link EnumWrapper.createUncachedInstance} if you don't want the EnumWrapper to be cached. | ||
| * @param enumObj - An enum-like object. | ||
@@ -194,7 +125,7 @@ * @return An instance of EnumWrapper for the provided enumObj. | ||
| public static getCachedInstance(enumObj: any): EnumWrapper { | ||
| let result = this.instancesCache.get(enumObj); | ||
| let result = EnumWrapper.instancesCache.get(enumObj); | ||
| if (!result) { | ||
| result = this.createUncachedInstance(enumObj); | ||
| this.instancesCache.set(enumObj, result); | ||
| result = new EnumWrapper(enumObj); | ||
| EnumWrapper.instancesCache.set(enumObj, result); | ||
| } | ||
@@ -877,55 +808,9 @@ | ||
| /** | ||
| * Convenience function for getting/creating an {@link EnumWrapper} instance. | ||
| * This is a short-hand way of calling {@link EnumWrapper.getCachedInstance}. | ||
| * or {@link EnumWrapper.createUncachedInstance}. | ||
| * @param enumObj - An enum-like object with number values. | ||
| * @param useCache - If true, then a cached instance is created and/or returned. | ||
| * @return A new or cached instance of EnumWrapper for the provided enumObj. | ||
| * | ||
| * @template T - Type of the enum-like object that is being wrapped. | ||
| */ | ||
| export function $enum<T extends EnumLike<number, keyof T>>( | ||
| enumObj: T, useCache?: boolean | ||
| ): EnumWrapper<number, T>; | ||
| /** | ||
| * Convenience function for getting/creating an {@link EnumWrapper} instance. | ||
| * This is a short-hand way of calling {@link EnumWrapper.getCachedInstance}. | ||
| * or {@link EnumWrapper.createUncachedInstance}. | ||
| * @param enumObj - An enum-like object with string values. | ||
| * @param useCache - If true, then a cached instance is created and/or returned. | ||
| * @return A new or cached instance of EnumWrapper for the provided enumObj. | ||
| * | ||
| * @template T - Type of the enum-like object that is being wrapped. | ||
| */ | ||
| export function $enum<T extends EnumLike<string, keyof T>>( | ||
| enumObj: T, useCache?: boolean | ||
| ): EnumWrapper<string, T>; | ||
| /** | ||
| * Convenience function for getting/creating an {@link EnumWrapper} instance. | ||
| * This is a short-hand way of calling {@link EnumWrapper.getCachedInstance}. | ||
| * or {@link EnumWrapper.createUncachedInstance}. | ||
| * @param enumObj - An enum-like object with a mixture of number and string values. | ||
| * @param useCache - If true, then a cached instance is created and/or returned. | ||
| * @return A new or cached instance of EnumWrapper for the provided enumObj. | ||
| * | ||
| * @template T - Type of the enum-like object that is being wrapped. | ||
| */ | ||
| export function $enum<T extends EnumLike<number | string, keyof T>>( | ||
| enumObj: T, useCache?: boolean | ||
| ): EnumWrapper<number | string, T>; | ||
| /** | ||
| * Convenience function for getting/creating an {@link EnumWrapper} instance. | ||
| * This is a short-hand way of calling {@link EnumWrapper.getCachedInstance}. | ||
| * or {@link EnumWrapper.createUncachedInstance}. | ||
| * Alias of {@link EnumWrapper.getCachedInstance} for convenience. | ||
| * Gets a cached EnumWrapper for an enum-like object. | ||
| * Creates and caches a new EnumWrapper if one is not already cached. | ||
| * @param enumObj - An enum-like object. | ||
| * @param useCache - If true, then a cached instance is created and/or returned. | ||
| * @return A new or cached instance of EnumWrapper for the provided enumObj. | ||
| * @return An instance of EnumWrapper for the provided enumObj. | ||
| */ | ||
| export function $enum(enumObj: any, useCache: boolean = true): EnumWrapper { | ||
| if (useCache) { | ||
| return EnumWrapper.getCachedInstance(enumObj); | ||
| } else { | ||
| return EnumWrapper.createUncachedInstance(enumObj); | ||
| } | ||
| } | ||
| export const $enum = EnumWrapper.getCachedInstance; | ||
@@ -932,0 +817,0 @@ /** |
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
New alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Fixed alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Improved metrics
- Number of lines in readme file
- increased by2.16%
709
Worsened metrics
- Total package byte prevSize
- decreased by-6.15%
148660
- Lines of code
- decreased by-9.99%
2091
No dependency changes