\n\n \n\n# memoize (@-xun/memoize)\n\n\n\nAn extremely flexible memoization cache and global singleton used to speed up\nexpensive function calls.\n\nProvides a simple but powerful API. Supports any number of parameters and/or a\nfinal \"options\" object parameter, asynchronous and synchronous functions, and\nper-function \"scoped\" caching. Provides nuanced usage statistics and\nsuper-powered TypeScript types for smooth DX.\n\n\n\n---\n\n\n\n\n\n\n- [Install](#install)\n- [Usage](#usage)\n - [`memoize`](#memoize)\n - [`memoizer`](#memoizer)\n - [Other Considerations](#other-considerations)\n- [Appendix](#appendix)\n - [Published Package Details](#published-package-details)\n - [License](#license)\n- [Contributing and Support](#contributing-and-support)\n - [Contributors](#contributors)\n\n\n\n\n\n \n\n## Install\n\n\n\nTo install:\n\n```shell\nnpm install @-xun/memoize\n```\n\n## Usage\n\nOriginal function without memoization:\n\n```typescript\nfunction doExpensiveAnalysisOfFile(\n filePath: string,\n options: { activateFunctionality?: boolean } = {}\n) {\n const { activateFunctionality } = options;\n const complexResult = expensiveAnalysis(filePath, activateFunctionality);\n\n return complexResult;\n}\n\ndoExpensiveAnalysisOfFile('/repos/project/some-file.js', {\n activateFunctionality: true\n});\n```\n\n \n\n\n\n### [`memoize`](./docs/src/functions/memoize.md)\n\n\n\n`memoize` can be used to wrap an existing function with caching/memoization\nfeatures.\n\n---\n\nSimple memoization:\n\n```typescript\nimport { memoize } from '@-xun/memoize';\n\n// vv memoized function\nconst memoizedDoExpensiveAnalysisOfFile = memoize(doExpensiveAnalysisOfFile);\n\n// vv cache id component(s)\nconst result = memoizedDoExpensiveAnalysisOfFile('/repos/project/some-file.js');\nmemoizedDoExpensiveAnalysisOfFile('/repos/project/some-file.js') === result; // true\n```\n\n \n\nExpiring memoization, where cache entries are evicted after a certain amount of\ntime:\n\n```typescript\nimport { memoize } from '@-xun/memoize';\n\nconst memoizedDoExpensiveAnalysisOfFile = memoize(doExpensiveAnalysisOfFile, {\n maxAgeMs: 10_000\n});\n\nconst result = memoizedDoExpensiveAnalysisOfFile('/repos/project/some-file.js');\nmemoizedDoExpensiveAnalysisOfFile('/repos/project/some-file.js') === result; // true\n```\n\n \n\nMemoization of an async function, optionally allowing the caller to explicitly\nrecompute the cached value when desired:\n\n```typescript\nimport { memoize } from '@-xun/memoize';\n\n// Suppose \"asyncDoExpensiveAnalysisOfFile\" is defined as an async version of\n// \"doExpensiveAnalysisOfFile\"\n\nconst memoizedDoExpensiveAnalysisOfFile = memoize(\n asyncDoExpensiveAnalysisOfFile,\n { addUseCachedOption: true }\n);\n\nconst result = await memoizedDoExpensiveAnalysisOfFile(\n '/repos/project/some-file.js',\n {\n // Will look in the cache for a result first (wrt the given filePath).\n useCached: true\n }\n);\n\n(await memoizedDoExpensiveAnalysisOfFile('/repos/project/some-file.js', {\n // Will look in the cache for a result first (wrt the given filePath).\n useCached: true\n})) === result; // true\n\n(await memoizedDoExpensiveAnalysisOfFile('/repos/project/some-file.js', {\n // Will bypass the cache and force recomputation, then cache the result.\n useCached: false\n})) !== result; // true\n```\n\n \n\n\n\n### [`memoizer`](./docs/src/variables/memoizer.md)\n\n\n\n`memoizer` can be used to implement caching/memoization within a function\nitself.\n\n---\n\nBasic memoization:\n\n```typescript\nimport { memoizer } from '@-xun/memoize';\n\nfunction doExpensiveAnalysisOfFile(\n filePath: string,\n options: { activateFunctionality: boolean }\n): AnalysisResult {\n const { activateFunctionality } = options;\n\n // vv memoized function\n let complexResult = memoizer.get(doExpensiveAnalysisOfFile, [\n filePath, // <-- first cache id component\n options // <-- second cache id component\n ]);\n\n if (complexResult === undefined) {\n complexResult = expensiveAnalysis(filePath, activateFunctionality);\n memoizer.set(doExpensiveAnalysisOfFile, [filePath, options], complexResult);\n }\n\n return complexResult;\n}\n\nconst result = doExpensiveAnalysisOfFile('/repos/project/some-file.js', {\n activateFunctionality: true\n});\n\ndoExpensiveAnalysisOfFile('/repos/project/some-file.js', {\n activateFunctionality: true\n}) === result; // true\n\ndoExpensiveAnalysisOfFile('/repos/project/some-file.js', {\n activateFunctionality: false\n}) !== result; // true\n```\n\n \n\nOptional memoization, allowing the caller to explicitly recompute the cached\nvalue when desired:\n\n```typescript\nimport { memoizer } from '@-xun/memoize';\n\n// It is usually ideal to force the caller to acknowledge that they're dealing\n// with a memoized function, which can prevent bad surprises. Still, we could\n// have made useCached optional if we wanted to.\n\nfunction doExpensiveAnalysisOfFile(\n filePath: string,\n {\n useCached,\n ...cacheIdComponents\n }: { activateFunctionality?: boolean; useCached: boolean }\n): AnalysisResult {\n const { activateFunctionality } = cacheIdComponents;\n let complexResult;\n\n if (useCached) {\n complexResult = memoizer.get(doExpensiveAnalysisOfFile, [\n filePath,\n cacheIdComponents\n ]);\n }\n\n if (complexResult === undefined) {\n complexResult = expensiveAnalysis(filePath, activateFunctionality);\n\n memoizer.set(\n doExpensiveAnalysisOfFile,\n [filePath, cacheIdComponents],\n complexResult\n );\n }\n\n return complexResult;\n}\n\nconst result = doExpensiveAnalysisOfFile('/repos/project/some-file.js', {\n // Will look in the cache for a result first (wrt the given filePath).\n useCached: true\n});\n\ndoExpensiveAnalysisOfFile('/repos/project/some-file.js', {\n // Will look in the cache for a result first (wrt the given filePath).\n useCached: true\n}) === result; // true\n\ndoExpensiveAnalysisOfFile('/repos/project/some-file.js', {\n // Will bypass the cache and force recomputation, then cache the result.\n useCached: false\n}) !== result; // true\n```\n\n \n\nMore complex memoization, where we accept an array of things with all, some, or\nnone have been cached already. Our goal here is to do as little work as\npossible:\n\n```typescript\nimport { memoizer } from '@-xun/memoize';\n\nfunction doExpensiveAnalysisOfFiles(\n filePaths: string[],\n {\n useCached = true,\n ...cacheIdComponents\n }: { activateFunctionality?: boolean; useCached?: boolean } = {}\n): AnalysisResult[] {\n const { activateFunctionality } = cacheIdComponents;\n const complexResults = [];\n\n for (const filePath of filePaths) {\n let complexResult;\n\n if (useCached) {\n complexResult = memoizer.get<\n typeof doExpensiveAnalysisOfFiles,\n // DO \"unpack\" id components; go from `T | T[]` to `T` (this is the default).\n 'expect unpacked ids',\n // DO \"unpack\" the return value; go from `T | T[]` to `T`.\n 'expect unpacked value'\n >(doExpensiveAnalysisOfFiles, [filePath, cacheIdComponents]);\n }\n\n if (complexResult === undefined) {\n complexResult = expensiveAnalysis(filePath, activateFunctionality);\n\n memoizer.set<\n typeof doExpensiveAnalysisOfFiles,\n // DO \"unpack\" id components; go from `T | T[]` to `T` (this is the default).\n 'expect unpacked ids',\n // DO \"unpack\" the return value; go from `T | T[]` to `T`.\n 'expect unpacked value'\n >(\n doExpensiveAnalysisOfFiles,\n [filePath, cacheIdComponents],\n complexResult\n );\n }\n\n complexResults.push(complexResult);\n }\n\n return complexResults;\n}\n\nconst result = doExpensiveAnalysisOfFiles([\n '/repos/project/some-file-1.js',\n '/repos/project/some-file-2.js',\n '/repos/project/some-file-3.js'\n]);\n\n// Even though the parameters are different, we can still take advantage of the\n// memoized result of the previous invocation! No extra work is done by the\n// following:\ndoExpensiveAnalysisOfFiles(['/repos/project/some-file-2.js'])[0] === result[1]; // true\n```\n\n \n\nMore complex memoization, where we accept and memoize an array of things in one\nshot:\n\n```typescript\nimport { memoizer } from '@-xun/memoize';\n\nfunction doExpensiveAnalysisOfFiles(\n filePaths: string[],\n {\n useCached,\n ...cacheIdComponents\n }: { activateFunctionality?: boolean; useCached: boolean }\n): AnalysisResult[] {\n const { activateFunctionality } = cacheIdComponents;\n let complexResults;\n\n if (useCached) {\n complexResults = memoizer.get<\n typeof doExpensiveAnalysisOfFiles,\n // DO NOT \"unpack\" id components; leave them as they are.\n 'expect ids as-is',\n // DO NOT \"unpack\" the return value; leave it as-is (this is the default).\n 'expect value as-is'\n >(doExpensiveAnalysisOfFiles, [filePaths, cacheIdComponents]);\n }\n\n if (complexResults === undefined) {\n complexResults = expensiveAnalyses(filePaths, activateFunctionality);\n\n memoizer.set<\n typeof doExpensiveAnalysisOfFiles,\n // DO NOT \"unpack\" id components; leave them as they are.\n 'expect ids as-is',\n // DO NOT \"unpack\" the return value; leave it as-is (this is the default).\n 'expect value as-is'\n >(\n doExpensiveAnalysisOfFiles,\n [filePaths, cacheIdComponents],\n complexResults\n );\n }\n\n return complexResults;\n}\n\nconst result = doExpensiveAnalysisOfFiles(\n [\n '/repos/project/some-file-1.js',\n '/repos/project/some-file-2.js',\n '/repos/project/some-file-3.js'\n ],\n {\n activateFunctionality: true,\n useCached: true\n }\n);\n\ndoExpensiveAnalysisOfFiles(\n [\n '/repos/project/some-file-1.js',\n '/repos/project/some-file-2.js',\n '/repos/project/some-file-3.js'\n ],\n {\n // This being false means a different cache key is generated and the\n // previous results are not reused, even though filePaths (the other id\n // component) is the same!\n activateFunctionality: false,\n useCached: true\n }\n) !== result; // true\n```\n\n \n\nMemoization of an async function using object-style parameters:\n\n```typescript\nimport { memoizer } from '@-xun/memoize';\n\nasync function doExpensiveAnalysisOfFile({\n useCached,\n ...cacheIdComponents\n}: {\n filePath: string;\n activateFunctionality?: boolean;\n useCached: boolean;\n}): Promise {\n const { filePath, activateFunctionality } = cacheIdComponents;\n let complexResult: AnalysisResult | undefined;\n\n if (useCached) {\n // memoizer.get returns a promise iff its first parameter is detected to be\n // an async function or iff memoizer.set is called with `wasPromised: true`.\n complexResult = await memoizer.get(doExpensiveAnalysisOfFile, [\n cacheIdComponents\n ]);\n }\n\n if (complexResult === undefined) {\n // Do not put promises into the cache. Intellisense will attempt to stop you\n // from doing so. memoizer.get will return the value wrapped in a promise.\n complexResult = await expensiveAnalysis(filePath, activateFunctionality);\n memoizer.set(doExpensiveAnalysisOfFile, [cacheIdComponents], complexResult);\n }\n\n return complexResult;\n}\n\nconst result = await doExpensiveAnalysisOfFile({\n filePath: '/repos/project/some-file.js',\n // Will look in the cache for a result first (wrt the given filePath).\n useCached: true\n});\n\n(await doExpensiveAnalysisOfFile({\n filePath: '/repos/project/some-file.js',\n // Will look in the cache for a result first (wrt the given filePath).\n useCached: true\n})) === result; // true\n\n(await doExpensiveAnalysisOfFile({\n filePath: '/repos/project/some-file.js',\n // Will bypass the cache and force recomputation, then cache the result.\n useCached: false\n})) !== result; // true\n```\n\n \n\nPiecemeal memoization, where we customize which parameters are considered as\ncomponents of the cache key and ignore the others:\n\n```typescript\nimport { memoizer } from '@-xun/memoize';\n\nfunction doExpensiveAnalysisOfFile({\n useCached,\n activateFunctionality = true,\n // We only want to use a subset of options as the cache id components.\n ...cacheIdComponents\n}: {\n filePath: string;\n activateFunctionality: boolean;\n activateOtherFunctionality?: boolean;\n somethingElse: number;\n useCached: boolean;\n}): AnalysisResult {\n // We'll use this type to tell memoizer what id components to look out for.\n type MemoizedDoExpensiveAnalysisOfFile = (\n ...args: [typeof cacheIdComponents]\n ) => ReturnType;\n\n // These three properties will be used as components for our cache \"id\". If\n // one of them changes, the cache will miss. The other properties are ignored.\n const { filePath, activateOtherFunctionality, somethingElse } =\n cacheIdComponents;\n\n let complexResult;\n\n if (useCached) {\n complexResult = memoizer.get(\n doExpensiveAnalysisOfFile as MemoizedDoExpensiveAnalysisOfFile,\n [cacheIdComponents]\n );\n }\n\n if (complexResult === undefined) {\n complexResult = expensiveAnalysis(\n filePath,\n activateFunctionality,\n activateOtherFunctionality\n );\n\n memoizer.set(\n doExpensiveAnalysisOfFile as MemoizedDoExpensiveAnalysisOfFile,\n [cacheIdComponents],\n complexResult\n );\n }\n\n doSomethingElse(somethingElse);\n return complexResult;\n}\n\nconst result = doExpensiveAnalysisOfFile({\n filePath: '/repos/project/some-file.js',\n useCached: true,\n activateFunctionality: true,\n somethingElse: 5\n});\n\n// Cache hit (despite activateFunctionality)\ndoExpensiveAnalysisOfFile({\n filePath: '/repos/project/some-file.js',\n useCached: true,\n activateFunctionality: false,\n somethingElse: 5\n}) === result; // true\n\n// Cache miss (despite activateFunctionality)\ndoExpensiveAnalysisOfFile({\n filePath: '/repos/project/some-file.js',\n useCached: true,\n activateFunctionality: true,\n somethingElse: 6\n}) !== result; // true\n```\n\n \n\nExpiring cache entries (in this example: 10 seconds after being set unless set\nagain), clearing the cache on a per-scope basis, and accessing cache usage\nmetadata:\n\n```typescript\nimport { memoizer } from '@-xun/memoize';\n\nasync function doExpensiveAnalysisOfFile({\n useCached,\n ...cacheIdComponents\n}: {\n filePath: string;\n activateFunctionality?: boolean;\n useCached: boolean;\n}): Promise {\n const { filePath, activateFunctionality } = cacheIdComponents;\n let complexResult: AnalysisResult | undefined;\n\n if (useCached) {\n complexResult = await memoizer.get(doExpensiveAnalysisOfFile, [\n cacheIdComponents\n ]);\n }\n\n if (complexResult === undefined) {\n complexResult = await expensiveAnalysis(filePath, activateFunctionality);\n memoizer.set(\n doExpensiveAnalysisOfFile,\n [cacheIdComponents],\n complexResult,\n { maxAgeMs: 10_000 }\n );\n }\n\n return complexResult;\n}\n\nconst result = await doExpensiveAnalysisOfFile({\n filePath: '/repos/project/some-file.js',\n useCached: true\n});\n\n// Hits the cache\n(await doExpensiveAnalysisOfFile({\n filePath: '/repos/project/some-file.js',\n useCached: true\n})) === result;\n\n// Clears the cache but only for the specified function\nmemoizer.clear([doExpensiveAnalysisOfFile]);\n\n// Misses the cache\n(await doExpensiveAnalysisOfFile({\n filePath: '/repos/project/some-file.js',\n useCached: true\n})) !== result;\n\n// If we waited 10 seconds and tried calling doExpensiveAnalysisOfFile again,\n// we would miss the cache again, expirations (below) would be set to 1, and\n// pendingExpirations (also below) would be set to 0.\n\n// If we waited only 5 seconds before calling doExpensiveAnalysisOfFile again,\n// we would hit the cache instead.\n\nconsole.log(memoizer);\n\n// {\n// set: [Function: setInCache],\n// sets: 2,\n// setsOverwrites: 0,\n// setsCreated: 2,\n// get: [Function: getFromCache],\n// gets: 3,\n// getsHits: 1,\n// getsMisses: 2,\n// clear: [Function: clearCacheByScope],\n// clearAll: [Function: clearCache],\n// clears: 1,\n// expirations: 0,\n// pendingExpirations: 1,\n// cachedScopes: 1,\n// cachedEntries: 1,\n// }\n```\n\n### Other Considerations\n\n- The internal cache is implemented as a global singleton that will persist\n across the entire runtime (but not cross-realm), even when imported from\n different packages. No need to worry about any of the usual package hazards.\n\n- The `useCached` property, if used as part of an \"options\" object, is omitted\n from the type of the secondary optional parameter. The name of this property\n can be customized, and additional properties can be similarly omitted, using\n the `SecondaryKeysToOmit` generic parameter on `memoizer.get` and\n `memoizer.set`.\n\n- The order of id components will change the derived cache key, resulting in a\n recomputation. If this is not desired, ensure id components are passed to\n `memoizer`'s functions in consistently.\n\n- All id components passed to `memoize` and `memoizer`'s functions must be\n [serializable][1] via `JSON.stringify` or explicitly `undefined`. If any id\n components are defined but not serializable, create a wrapper function that\n transforms any unserializable parameters into some serializable representation\n before passing them to `memoize`/`memoizer`.\n\n> [!CAUTION]\n>\n> `JSON.stringify` will not consistently throw when it encounters unserializable\n> or semi-serializable id components!\n>\n> If used carelessly, this can lead to arbitrary cache key collisions where the\n> memoizer functions return the same result for obviously different sets of\n> function parameters when it clearly shouldn't.\n>\n> To prevent this, ensure your function's memoized parameters (specifically the\n> parameters used as id components) are serializable.\n\n\n\n## Appendix\n\n\n\nFurther documentation can be found under [`docs/`][x-repo-docs].\n\n\n\n\n### Published Package Details\n\nThis is a [CJS2 package][x-pkg-cjs-mojito] with statically-analyzable exports\nbuilt by Babel for use in Node.js versions that are not end-of-life. For\nTypeScript users, this package supports both `\"Node10\"` and `\"Node16\"` module\nresolution strategies.\n\n\n\n\n\nExpand details\n\nThat means both CJS2 (via `require(...)`) and ESM (via `import { ... } from ...`\nor `await import(...)`) source will load this package from the same entry points\nwhen using Node. This has several benefits, the foremost being: less code\nshipped/smaller package size, avoiding [dual package\nhazard][x-pkg-dual-package-hazard] entirely, distributables are not\npacked/bundled/uglified, a drastically less complex build process, and CJS\nconsumers aren't shafted.\n\nEach entry point (i.e. `ENTRY`) in [`package.json`'s\n`exports[ENTRY]`][x-repo-package-json] object includes one or more [export\nconditions][x-pkg-exports-conditions]. These entries may or may not include: an\n[`exports[ENTRY].types`][x-pkg-exports-types-key] condition pointing to a type\ndeclaration file for TypeScript and IDEs, a\n[`exports[ENTRY].module`][x-pkg-exports-module-key] condition pointing to\n(usually ESM) source for Webpack/Rollup, a `exports[ENTRY].node` and/or\n`exports[ENTRY].default` condition pointing to (usually CJS2) source for Node.js\n`require`/`import` and for browsers and other environments, and [other\nconditions][x-pkg-exports-conditions] not enumerated here. Check the\n[package.json][x-repo-package-json] file to see which export conditions are\nsupported.\n\nNote that, regardless of the [`{ \"type\": \"...\" }`][x-pkg-type] specified in\n[`package.json`][x-repo-package-json], any JavaScript files written in ESM\nsyntax (including distributables) will always have the `.mjs` extension. Note\nalso that [`package.json`][x-repo-package-json] may include the\n[`sideEffects`][x-pkg-side-effects-key] key, which is almost always `false` for\noptimal [tree shaking][x-pkg-tree-shaking] where appropriate.\n\n\n\n\n\n\n\n### License\n\n\n\nSee [LICENSE][x-repo-license].\n\n\n\n\n## Contributing and Support\n\n**[New issues][x-repo-choose-new-issue] and [pull requests][x-repo-pr-compare]\nare always welcome and greatly appreciated! 🤩** Just as well, you can [star 🌟\nthis project][x-badge-repo-link] to let me know you found it useful! ✊🏿 Or [buy\nme a beer][x-repo-sponsor], I'd appreciate it. Thank you!\n\nSee [CONTRIBUTING.md][x-repo-contributing] and [SUPPORT.md][x-repo-support] for\nmore information.\n\n\n\n\n\n### Contributors\n\n\n\n\n\n\n[](#contributors-)\n\n\n\n\nThanks goes to these wonderful people ([emoji\nkey][x-repo-all-contributors-emojis]):\n\n\n\n\n\n\n
![](\"https://raw.githubusercontent.com/Xunnamius/memoize/refs/heads/main/logo.png\"){kind=logo}
\n![\"Bernard\"/](\"https://avatars.githubusercontent.com/u/656017?v=4?s=100\")
![](\"https://raw.githubusercontent.com/all-contributors/all-contributors-cli/1b8533af435da9854653492b1327a23a4dbd0a10/assets/logo-small.svg\"){kind=logo}
\n Add your contributions\n \n