@common.js/p-memoize 7.1.0 → 8.0.0

package/README.md

@@ -2,4 +2,4 @@
 
 The [p-memoize](https://www.npmjs.com/package/p-memoize) package exported as CommonJS modules.
 
-Exported from [p-memoize@7.1.0](https://www.npmjs.com/package/p-memoize/v/7.1.0) using https://github.com/etienne-martin/common.js.
+Exported from [p-memoize@8.0.0](https://www.npmjs.com/package/p-memoize/v/8.0.0) using https://github.com/etienne-martin/common.js.

package/dist/index.d.ts

@@ -1,15 +1,22 @@
 import type { AsyncReturnType } from 'type-fest';
-export declare type AnyAsyncFunction = (...arguments_: readonly any[]) => Promise<unknown | void>;
-export interface CacheStorage<KeyType, ValueType> {
+export type AnyAsyncFunction = (...arguments_: readonly any[]) => Promise<unknown | void>;
+export type CacheStorage<KeyType, ValueType> = {
     has: (key: KeyType) => Promise<boolean> | boolean;
     get: (key: KeyType) => Promise<ValueType | undefined> | ValueType | undefined;
     set: (key: KeyType, value: ValueType) => Promise<unknown> | unknown;
     delete: (key: KeyType) => unknown;
     clear?: () => unknown;
-}
-export interface Options<FunctionToMemoize extends AnyAsyncFunction, CacheKeyType> {
+};
+/**
+Controls whether a fulfilled value should be written to the cache.
+*/
+export type ShouldCache<KeyType, ValueType, ArgumentsList extends readonly unknown[] = readonly unknown[]> = (value: ValueType, context: {
+    key: KeyType;
+    argumentsList: ArgumentsList;
+}) => boolean | Promise<boolean>;
+export type Options<FunctionToMemoize extends AnyAsyncFunction, CacheKeyType> = {
     /**
-    Determines the cache key for storing the result based on the function arguments. By default, __only the first argument is considered__ and it only works with [primitives](https://developer.mozilla.org/en-US/docs/Glossary/Primitive).
+    Determines the cache key for storing the result based on the function arguments. By default, __only the first argument is considered__ and it only works with [primitives](https://developer.mozilla.org/docs/Glossary/Primitive).
 
     A `cacheKey` function can return any type supported by `Map` (or whatever structure you use in the `cache` option).
 
@@ -41,7 +48,34 @@ export interface Options<FunctionToMemoize extends AnyAsyncFunction, CacheKeyTyp
     @example new WeakMap()
     */
     readonly cache?: CacheStorage<CacheKeyType, AsyncReturnType<FunctionToMemoize>> | false;
-}
+    /**
+    Controls whether a fulfilled value should be written to the cache.
+
+    It runs after the function fulfills and before `cache.set`.
+
+    - Omit to keep current behavior (always write).
+    - Return `false` to skip writing to the cache (in-flight de-duplication is still cleared).
+    - Throw or reject to propagate the error and skip caching.
+
+    @example
+    ```
+    import pMemoize from 'p-memoize';
+
+    // Only cache defined values
+    const getMaybe = pMemoize(async key => db.get(key), {
+        shouldCache: value => value !== undefined,
+    });
+
+    // Only cache non-empty arrays
+    const search = pMemoize(async query => fetchResults(query), {
+        shouldCache: value => Array.isArray(value) && value.length > 0,
+    });
+    ```
+
+    Note: This only affects writes; reads from the cache are unchanged.
+    */
+    readonly shouldCache?: ShouldCache<CacheKeyType, AsyncReturnType<FunctionToMemoize>, Parameters<FunctionToMemoize>>;
+};
 /**
 [Memoize](https://en.wikipedia.org/wiki/Memoization) functions - An optimization used to speed up consecutive function calls by caching the result of calls with identical input.
 
@@ -66,13 +100,14 @@ await delay(2000);
 await memoizedGot('https://sindresorhus.com');
 ```
 */
-export default function pMemoize<FunctionToMemoize extends AnyAsyncFunction, CacheKeyType>(fn: FunctionToMemoize, { cacheKey, cache, }?: Options<FunctionToMemoize, CacheKeyType>): FunctionToMemoize;
+export default function pMemoize<FunctionToMemoize extends AnyAsyncFunction, CacheKeyType = Parameters<FunctionToMemoize>[0], OptionsType = Options<FunctionToMemoize, CacheKeyType>>(fn: FunctionToMemoize, options?: OptionsType & Options<FunctionToMemoize, CacheKeyType>): FunctionToMemoize;
 /**
-- Only class methods and getters/setters can be memoized, not regular functions (they aren't part of the proposal);
-- Only [TypeScript’s decorators](https://www.typescriptlang.org/docs/handbook/decorators.html#parameter-decorators) are supported, not [Babel’s](https://babeljs.io/docs/en/babel-plugin-proposal-decorators), which use a different version of the proposal;
-- Being an experimental feature, they need to be enabled with `--experimentalDecorators`; follow TypeScript’s docs.
+- Only class methods are supported; regular functions are not part of the decorators proposals.
+- Uses the new ECMAScript decorators (TypeScript 5.0+). Legacy `experimentalDecorators` are not supported.
+- Babel’s legacy decorators are not supported.
+- Private methods are not supported.
 
-@returns A [decorator](https://github.com/tc39/proposal-decorators) to memoize class methods or static class methods.
+@returns A decorator to memoize class methods or static class methods.
 
 @example
 ```
@@ -97,7 +132,7 @@ class ExampleWithOptions {
 }
 ```
 */
-export declare function pMemoizeDecorator<FunctionToMemoize extends AnyAsyncFunction, CacheKeyType>(options?: Options<FunctionToMemoize, CacheKeyType>): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => void;
+export declare function pMemoizeDecorator<FunctionToMemoize extends AnyAsyncFunction = AnyAsyncFunction, CacheKeyType = Parameters<FunctionToMemoize>[0]>(options?: Options<NoInfer<FunctionToMemoize>, NoInfer<CacheKeyType>>): <This, Value extends FunctionToMemoize>(value: Value, context: ClassMethodDecoratorContext<This, Value>) => void;
 /**
 Clear all cached data of a memoized function.
 

package/dist/index.js

@@ -42,7 +42,7 @@ await memoizedGot('https://sindresorhus.com');
         return pMemoizeClear;
     }
 });
-var _mimicFn = /*#__PURE__*/ _interopRequireDefault(require("mimic-fn"));
+var _mimicFunction = /*#__PURE__*/ _interopRequireDefault(require("mimic-function"));
 function _arrayLikeToArray(arr, len) {
     if (len == null || len > arr.length) len = arr.length;
     for(var i = 0, arr2 = new Array(len); i < len; i++)arr2[i] = arr[i];
@@ -219,11 +219,12 @@ var __generator = (void 0) && (void 0).__generator || function(thisArg, body) {
     }
 };
 var cacheStore = new WeakMap();
-function pMemoize(fn) {
-    var ref = arguments.length > 1 && arguments[1] !== void 0 ? arguments[1] : {}, _cacheKey = ref.cacheKey, cacheKey = _cacheKey === void 0 ? function(param) {
+function pMemoize(fn, options) {
+    var defaultCacheKey = function(param) {
         var _param = _slicedToArray(param, 1), firstArgument = _param[0];
         return firstArgument;
-    } : _cacheKey, _cache = ref.cache, cache = _cache === void 0 ? new Map() : _cache;
+    };
+    var ref = options !== null && options !== void 0 ? options : {}, _cacheKey = ref.cacheKey, cacheKey = _cacheKey === void 0 ? defaultCacheKey : _cacheKey, _cache = ref.cache, cache = _cache === void 0 ? new Map() : _cache;
     // Promise objects can't be serialized so we keep track of them internally and only provide their resolved values to `cache`
     // `Promise<AsyncReturnType<FunctionToMemoize>>` is used instead of `ReturnType<FunctionToMemoize>` because promise properties are not kept
     var promiseCache = new Map();
@@ -237,15 +238,15 @@ function pMemoize(fn) {
         }
         var _this = this;
         var promise = _asyncToGenerator(function() {
-            var _tmp, promise, result;
+            var _tmp, promise, result, allow, _tmp1;
             return __generator(this, function(_state) {
                 switch(_state.label){
                     case 0:
                         _state.trys.push([
                             0,
                             ,
-                            11,
-                            12
+                            14,
+                            15
                         ]);
                         _tmp = cache;
                         if (!_tmp) return [
@@ -287,7 +288,7 @@ function pMemoize(fn) {
                             6,
                             ,
                             7,
-                            10
+                            13
                         ]);
                         return [
                             2,
@@ -295,31 +296,57 @@ function pMemoize(fn) {
                         ];
                     case 7:
                         if (!cache) return [
+                            3,
+                            12
+                        ];
+                        if (!(options === null || options === void 0 ? void 0 : options.shouldCache)) return [
                             3,
                             9
                         ];
                         return [
                             4,
-                            cache.set(key, result)
+                            options.shouldCache(result, {
+                                key: key,
+                                argumentsList: arguments_
+                            })
                         ];
                     case 8:
-                        _state.sent();
-                        _state.label = 9;
-                    case 9:
+                        _tmp1 = _state.sent();
                         return [
-                            7
+                            3,
+                            10
                         ];
+                    case 9:
+                        _tmp1 = true;
+                        _state.label = 10;
                     case 10:
-                        return [
+                        allow = _tmp1;
+                        if (!allow) return [
                             3,
                             12
                         ];
+                        return [
+                            4,
+                            cache.set(key, result)
+                        ];
                     case 11:
+                        _state.sent();
+                        _state.label = 12;
+                    case 12:
+                        return [
+                            7
+                        ];
+                    case 13:
+                        return [
+                            3,
+                            15
+                        ];
+                    case 14:
                         promiseCache.delete(key);
                         return [
                             7
                         ];
-                    case 12:
+                    case 15:
                         return [
                             2
                         ];
@@ -329,7 +356,7 @@ function pMemoize(fn) {
         promiseCache.set(key, promise);
         return promise;
     };
-    (0, _mimicFn.default)(memoized, fn, {
+    (0, _mimicFunction.default)(memoized, fn, {
         ignoreNonConfigurable: true
     });
     cacheStore.set(memoized, cache);
@@ -337,22 +364,22 @@ function pMemoize(fn) {
 }
 function pMemoizeDecorator() {
     var options = arguments.length > 0 && arguments[0] !== void 0 ? arguments[0] : {};
-    var instanceMap = new WeakMap();
-    return function(target, propertyKey, descriptor) {
-        var input = target[propertyKey]; // eslint-disable-line @typescript-eslint/no-unsafe-assignment
-        if (typeof input !== "function") {
-            throw new TypeError("The decorated value must be a function");
+    return function(value, context) {
+        if (context.kind !== "method") {
+            throw new TypeError("pMemoizeDecorator can only decorate methods");
         }
-        delete descriptor.value;
-        delete descriptor.writable;
-        descriptor.get = function() {
-            if (!instanceMap.has(this)) {
-                var value = pMemoize(input, options);
-                instanceMap.set(this, value);
-                return value;
-            }
-            return instanceMap.get(this);
-        };
+        if (context.private) {
+            throw new TypeError("pMemoizeDecorator cannot decorate private methods");
+        }
+        context.addInitializer(function() {
+            var memoizedMethod = pMemoize(value, options);
+            Object.defineProperty(this, context.name, {
+                configurable: true,
+                writable: true,
+                enumerable: false,
+                value: memoizedMethod
+            });
+        });
     };
 }
 function pMemoizeClear(fn) {

package/package.json

@@ -1,14 +1,15 @@
 {
   "name": "@common.js/p-memoize",
-  "version": "7.1.0",
-  "description": "Memoize promise-returning & async functions",
+  "version": "8.0.0",
+  "description": "p-memoize package exported as CommonJS modules",
   "license": "MIT",
   "repository": "etienne-martin/common.js",
   "funding": "https://github.com/sindresorhus/p-memoize?sponsor=1",
   "type": "commonjs",
-  "types": "dist/index.d.ts",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
   "engines": {
-    "node": ">=14.16"
+    "node": ">=20"
   },
   "scripts": {
     "test": "xo && ava && npm run build && tsd",
@@ -18,27 +19,31 @@
     "dist"
   ],
   "dependencies": {
-    "@common.js/mimic-fn": "^4.0.0"
+    "@common.js/mimic-function": "^5.0.1",
+    "type-fest": "^4.41.0"
   },
   "devDependencies": {
-    "@sindresorhus/tsconfig": "^3.0.1",
-    "@types/serialize-javascript": "^5.0.2",
-    "ava": "^4.3.0",
-    "del-cli": "^4.0.1",
-    "delay": "^5.0.0",
-    "p-defer": "^4.0.0",
-    "p-state": "^1.0.0",
-    "serialize-javascript": "^6.0.0",
-    "ts-node": "^10.8.2",
-    "tsd": "^0.22.0",
-    "xo": "^0.50.0"
+    "@sindresorhus/tsconfig": "^8.0.1",
+    "@types/serialize-javascript": "^5.0.4",
+    "ava": "^6.4.1",
+    "del-cli": "^6.0.0",
+    "delay": "^6.0.0",
+    "p-defer": "^4.0.1",
+    "p-state": "^2.0.1",
+    "serialize-javascript": "^6.0.2",
+    "tsd": "^0.33.0",
+    "tsimp": "^2.0.12",
+    "xo": "^1.2.1"
   },
   "ava": {
+    "environmentVariables": {
+      "TSIMP_DIAG": "ignore"
+    },
     "extensions": {
       "ts": "module"
     },
     "nodeArguments": [
-      "--loader=ts-node/esm"
+      "--import=tsimp/import"
     ]
   },
   "xo": {

package/readme.md

@@ -1,154 +0,0 @@
-# p-memoize
-
-> [Memoize](https://en.wikipedia.org/wiki/Memoization) promise-returning & async functions
-
-Useful for speeding up consecutive function calls by caching the result of calls with identical input.
-
-<!-- Please keep this section in sync with https://github.com/sindresorhus/mem/blob/main/readme.md -->
-
-By default, **only the memoized function's first argument is considered** via strict equality comparison. If you need to cache multiple arguments or cache `object`s *by value*, have a look at alternative [caching strategies](#caching-strategy) below.
-
-This package is similar to [mem](https://github.com/sindresorhus/mem) but with async-specific enhancements; in particular, it allows for asynchronous caches and does not cache rejected promises.
-
-## Install
-
-```sh
-npm install p-memoize
-```
-
-## Usage
-
-```js
-import pMemoize from 'p-memoize';
-import got from 'got';
-
-const memoizedGot = pMemoize(got);
-
-await memoizedGot('https://sindresorhus.com');
-
-// This call is cached
-await memoizedGot('https://sindresorhus.com');
-```
-
-### Caching strategy
-
-Similar to the [caching strategy for `mem`](https://github.com/sindresorhus/mem#options) with the following exceptions:
-
-- Promises returned from a memoized function are locally cached until resolving, when their value is added to `cache`. Special properties assigned to a returned promise will not be kept after resolution and every promise may need to resolve with a serializable object if caching results in a database.
-- `.get()`, `.has()` and `.set()` methods on `cache` can run asynchronously by returning a promise.
-- Instead of `.set()` being provided an object with the properties `value` and `maxAge`, it will only be provided `value` as the first argument. If you want to implement time-based expiry, consider [doing so in `cache`](#time-based-cache-expiration).
-
-## API
-
-### pMemoize(fn, options?)
-
-Returns a memoized version of the given function.
-
-#### fn
-
-Type: `Function`
-
-Promise-returning or async function to be memoized.
-
-#### options
-
-Type: `object`
-
-See the [`mem` options](https://github.com/sindresorhus/mem#options) in addition to the below option.
-
-##### cacheKey
-
-Type: `Function`\
-Default: `arguments_ => arguments_[0]`\
-Example: `arguments_ => JSON.stringify(arguments_)`
-
-Determines the cache key for storing the result based on the function arguments. By default, **only the first argument is considered**.
-
-A `cacheKey` function can return any type supported by `Map` (or whatever structure you use in the `cache` option).
-
-See the [caching strategy](#caching-strategy) section for more information.
-
-##### cache
-
-Type: `object | false`\
-Default: `new Map()`
-
-Use a different cache storage. Must implement the following methods: `.has(key)`, `.get(key)`, `.set(key, value)`, `.delete(key)`, and optionally `.clear()`. You could for example use a `WeakMap` instead or [`quick-lru`](https://github.com/sindresorhus/quick-lru) for a LRU cache. To disable caching so that only concurrent executions resolve with the same value, pass `false`.
-
-See the [caching strategy](https://github.com/sindresorhus/mem#caching-strategy) section in the `mem` package for more information.
-
-### pMemoizeDecorator(options)
-
-Returns a [decorator](https://github.com/tc39/proposal-decorators) to memoize class methods or static class methods.
-
-Notes:
-
-- Only class methods and getters/setters can be memoized, not regular functions (they aren't part of the proposal);
-- Only [TypeScript’s decorators](https://www.typescriptlang.org/docs/handbook/decorators.html#parameter-decorators) are supported, not [Babel’s](https://babeljs.io/docs/en/babel-plugin-proposal-decorators), which use a different version of the proposal;
-- Being an experimental feature, they need to be enabled with `--experimentalDecorators`; follow TypeScript’s docs.
-
-#### options
-
-Type: `object`
-
-Same as options for `pMemoize()`.
-
-```ts
-import {pMemoizeDecorator} from 'p-memoize';
-
-class Example {
-	index = 0
-
-	@pMemoizeDecorator()
-	async counter() {
-		return ++this.index;
-	}
-}
-
-class ExampleWithOptions {
-	index = 0
-
-	@pMemoizeDecorator()
-	async counter() {
-		return ++this.index;
-	}
-}
-```
-
-### pMemoizeClear(memoized)
-
-Clear all cached data of a memoized function.
-
-It will throw when given a non-memoized function.
-
-## Tips
-
-### Time-based cache expiration
-
-```js
-import pMemoize from 'p-memoize';
-import ExpiryMap from 'expiry-map';
-import got from 'got';
-
-const cache = new ExpiryMap(10000); // Cached values expire after 10 seconds
-
-const memoizedGot = pMemoize(got, {cache});
-```
-
-### Caching promise rejections
-
-```js
-import pMemoize from 'p-memoize';
-import pReflect from 'p-reflect';
-
-const memoizedGot = pMemoize(async (url, options) => pReflect(got(url, options)));
-
-await memoizedGot('https://example.com');
-// {isFulfilled: true, isRejected: false, value: '...'}
-```
-
-## Related
-
-- [p-debounce](https://github.com/sindresorhus/p-debounce) - Debounce promise-returning & async functions
-- [p-throttle](https://github.com/sindresorhus/p-throttle) - Throttle promise-returning & async functions
-- [More…](https://github.com/sindresorhus/promise-fun)