https://github.com/extra-memoize/extra-memoize
🌳 Yet another memoize library.
https://github.com/extra-memoize/extra-memoize
browser esm library nodejs npm-package typescript
Last synced: 3 months ago
JSON representation
🌳 Yet another memoize library.
- Host: GitHub
- URL: https://github.com/extra-memoize/extra-memoize
- Owner: extra-memoize
- License: mit
- Created: 2021-05-18T03:10:25.000Z (about 5 years ago)
- Default Branch: main
- Last Pushed: 2026-02-14T14:57:28.000Z (5 months ago)
- Last Synced: 2026-02-14T21:44:14.472Z (5 months ago)
- Topics: browser, esm, library, nodejs, npm-package, typescript
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/extra-memoize
- Size: 4.52 MB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# extra-memoize
Yet another memoize library.
## Philosophy
Most memoize functions include strategies (such as TTL), which will actually cause poor cache performance, because memoize functions can only use common interfaces to implement related strategies.
`extra-memoize` takes another approach, its memoize function is very light. It delegates the implementation of the strategies to the cache layer and cache wrapper. This allows the cache backend to fully utilize their performance.
## Install
```sh
npm install --save extra-memoize
# or
yarn add extra-memoize
```
## Usage
```ts
import { memoize } from 'extra-memoize'
import { LRUCache } from '@extra-memoize/memory-cache'
const cache = new LRUCache(100)
const memoized = memoize({ cache }, fn)
```
## API
```ts
enum State {
Miss = 'miss'
, Hit = 'hit'
, Reuse = 'reuse'
, StaleWhileRevalidate = 'stale-while-revalidate'
, StaleIfError = 'stale-if-error'
}
interface ICache {
set(key: string, value: T): void
get(key: string): [State.Miss]
| [State.Hit, T]
}
interface IAsyncCache {
set(key: string, value: T): Promise
get(key: string): Promise<
| [State.Miss]
| [State.Hit, T]
>
}
interface IStaleWhileRevalidateCache {
set(key: string, value: T): void
get(key: string): [State.Miss]
| [
| State.Hit
| State.StaleWhileRevalidate
, T
]
}
interface IStaleWhileRevalidateAsyncCache {
set(key: string, value: T): Promise
get(key: string): Promise<
| [State.Miss]
| [
| State.Hit
| State.StaleWhileRevalidate
, T
]
>
}
interface IStaleIfErrorCache {
set(key: string, value: T): void
get(key: string): [State.Miss]
| [
| State.Hit
| State.StaleIfError
, T
]
}
interface IStaleIfErrorAsyncCache {
set(key: string, value: T): Promise
get(key: string): Promise<
| [State.Miss]
| [
| State.Hit
| State.StaleIfError
, T
]
>
}
interface IStaleWhileRevalidateAndStaleIfErrorCache {
set(key: string, value: T): void
get(key: string): [State.Miss]
| [
| State.Hit
| State.StaleWhileRevalidate
| State.StaleIfError
, T
]
}
interface IStaleWhileRevalidateAndStaleIfErrorAsyncCache {
set(key: string, value: T): Promise
get(key: string): Promise<
| [State.Miss]
| [
| State.Hit
| State.StaleWhileRevalidate
| State.StaleIfError
, T
]
>
}
```
### memoize
```ts
type VerboseResult = [T, State.Hit | State.Miss]
interface IMemoizeOptions {
cache: ICache
name?: string
verbose?: boolean = false
createKey?: (args: Args, name?: string) => string
/**
* Used to judge whether a function execution is too slow.
* Only when the excution time of function is
* greater than or equal to the value (in milliseconds),
* the return value of the function will be cached.
*/
executionTimeThreshold?: number = 0
}
function memoize(
options: IMemoizeOptions & { verbose: true }
, fn: (...args: Args) => Result
): (...args: Args) => VerboseResult
function memoize(
options: IMemoizeOptions & { verbose: false }
, fn: (...args: Args) => Result
): (...args: Args) => Result
function memoize(
options: Omit, 'verbose'>
, fn: (...args: Args) => Result
): (...args: Args) => Result
function memoize(
options: IMemoizeOptions
, fn: (...args: Args) => Result
): (...args: Args) => Result | VerboseResult
```
### memoizeAsync
```ts
type VerboseResult = [T, State.Hit | State.Miss | State.Reuse]
interface IMemoizeAsyncOptions {
cache: ICache | IAsyncCache
name?: string
verbose?: boolean = false
// The default is extra-json-stable-stringify([args, name])
createKey?: (args: Args, name?: string) => string
/**
* Used to judge whether a function execution is too slow.
* Only when the excution time of function is
* greater than or equal to the value (in milliseconds),
* the return value of the function will be cached.
*/
executionTimeThreshold?: number
}
function memoizeAsync(
options: IMemoizeAsyncOptions & { verbose: true }
, fn: (...args: Args) => Awaitable
): (...args: Args) => Promise>
function memoizeAsync(
options: IMemoizeAsyncOptions & { verbose: false }
, fn: (...args: Args) => Awaitable
): (...args: Args) => Promise
function memoizeAsync(
options: Omit, 'verbose'>
, fn: (...args: Args) => Awaitable
): (...args: Args) => Promise
function memoizeAsync(
options: IMemoizeAsyncOptions
, fn: (...args: Args) => Awaitable
): (...args: Args) => Promise>
```
### memoizeStaleWhileRevalidate
```ts
type VerboseResult = [
T
, State.Hit | State.Miss | State.Reuse | State.StaleWhileRevalidate
]
interface IMemoizeStalwWhileRevalidateOptions<
CacheValue
, Args extends any[]
> {
cache:
| IStaleWhileRevalidateCache
| IStaleWhileRevalidateAsyncCache
name?: string
verbose?: boolean = false
// The default is extra-json-stable-stringify([args, name])
createKey?: (args: Args, name?: string) => string
/**
* Used to judge whether a function execution is too slow.
* Only when the excution time of function is
* greater than or equal to the value (in milliseconds),
* the return value of the function will be cached.
*/
executionTimeThreshold?: number
}
function memoizeStaleWhileRevalidate<
CacheValue
, Result extends CacheValue
, Args extends any[]
>(
options: IMemoizeStalwWhileRevalidateOptions & { verbose: true }
, fn: (...args: Args) => Awaitable
): (...args: Args) => Promise>
function memoizeStaleWhileRevalidate<
CacheValue
, Result extends CacheValue
, Args extends any[]
>(
options: IMemoizeStalwWhileRevalidateOptions & { verbose: false }
, fn: (...args: Args) => Awaitable
): (...args: Args) => Promise
function memoizeStaleWhileRevalidate<
CacheValue
, Result extends CacheValue
, Args extends any[]
>(
options: Omit, 'verbose'>
, fn: (...args: Args) => Awaitable
): (...args: Args) => Promise
function memoizeStaleWhileRevalidate<
CacheValue
, Result extends CacheValue
, Args extends any[]
>(
options: IMemoizeStalwWhileRevalidateOptions
, fn: (...args: Args) => Awaitable
): (...args: Args) => Promise>
```
### memoizeStaleIfError
```ts
type VerboseResult = [T, State.Hit | State.Miss | State.StaleIfError]
interface IMemoizeStaleIfErrorOptions {
cache: IStaleIfErrorCache
name?: string
verbose?: boolean = false
// The default is extra-json-stable-stringify([args, name])
createKey?: (args: Args, name?: string) => string
/**
* Used to judge whether a function execution is too slow.
* Only when the excution time of function is
* greater than or equal to the value (in milliseconds),
* the return value of the function will be cached.
*/
executionTimeThreshold?: number
}
function memoizeStaleIfError<
CacheValue
, Result extends CacheValue
, Args extends any[]
>(
options: IMemoizeStaleIfErrorOptions & { verbose: true }
, fn: (...args: Args) => Result
): (...args: Args) => VerboseResult
function memoizeStaleIfError<
CacheValue
, Result extends CacheValue
, Args extends any[]
>(
options: IMemoizeStaleIfErrorOptions & { verbose: false }
, fn: (...args: Args) => Result
): (...args: Args) => Result
function memoizeStaleIfError<
CacheValue
, Result extends CacheValue
, Args extends any[]
>(
options: Omit, 'verbose'>
, fn: (...args: Args) => Result
): (...args: Args) => Result
function memoizeStaleIfError<
CacheValue
, Result extends CacheValue
, Args extends any[]
>(
options: IMemoizeStaleIfErrorOptions
, fn: (...args: Args) => Result
): (...args: Args) => Result | VerboseResult
```
### memoizeAsyncStaleIfError
```ts
type VerboseResult = [
T
, | State.Hit
| State.Miss
| State.Reuse
| State.StaleIfError
]
interface IMemoizeStaleIfErrorOptions {
cache: IStaleIfErrorCache | IStaleifErrorAsyncCache
name?: string
verbose?: boolean = false
// The default is extra-json-stable-stringify([args, name])
createKey?: (args: Args, name?: string) => string
/**
* Used to judge whether a function execution is too slow.
* Only when the excution time of function is
* greater than or equal to the value (in milliseconds),
* the return value of the function will be cached.
*/
executionTimeThreshold?: number
}
function memoizeAsyncStaleIfError<
CacheValue
, Result extends CacheValue
, Args extends any[]
>(
options: IMemoizeAsyncStaleIfError & { verbose: true }
, fn: (...args: Args) => Awaitable
): (...args: Args) => Promise>
function memoizeAsyncStaleIfError<
CacheValue
, Result extends CacheValue
, Args extends any[]
>(
options: IMemoizeAsyncStaleIfError & { verbose: false }
, fn: (...args: Args) => Awaitable
): (...args: Args) => Promise
function memoizeAsyncStaleIfError<
CacheValue
, Result extends CacheValue
, Args extends any[]
>(
options: Omit, 'verbose'>
, fn: (...args: Args) => Awaitable
): (...args: Args) => Promise
function memoizeAsyncStaleIfError<
CacheValue
, Result extends CacheValue
, Args extends any[]
>(
options: IMemoizeAsyncStaleIfError
, fn: (...args: Args) => Awaitable
): (...args: Args) => Promise>
```
### memoizeStaleWhileRevalidateAndStaleIfError
```ts
type VerboseResult = [
T
, | State.Hit
| State.Miss
| State.Reuse
| State.StaleWhileRevalidate
| State.StaleIfError
]
interface IMemoizeStaleWhileRevalidateAndStaleIfError<
CacheValue
, Args extends any[]
> {
cache:
| IStaleWhileRevalidateAndStaleIfErrorCache
| IStaleWhileRevalidateAndStaleIfErrorAsyncCache
name?: string
verbose?: boolean = false
// The default is extra-json-stable-stringify([args, name])
createKey?: (args: Args, name?: string) => string
/**
* Used to judge whether a function execution is too slow.
* Only when the excution time of function is
* greater than or equal to the value (in milliseconds),
* the return value of the function will be cached.
*/
executionTimeThreshold?: number
}
function memoizeStaleWhileRevalidateAndStaleIfError<
CacheValue
, Result extends CacheValue
, Args extends any[]
>(
options: IMemoizeStaleWhileRevalidateAndStaleIfError
& { verbose: true }
, fn: (...args: Args) => Awaitable
): (...args: Args) => Promise>
function memoizeStaleWhileRevalidateAndStaleIfError<
CacheValue
, Result extends CacheValue
, Args extends any[]
>(
options: IMemoizeStaleWhileRevalidateAndStaleIfError
& { verbose: false }
, fn: (...args: Args) => Awaitable
): (...args: Args) => Promise
function memoizeStaleWhileRevalidateAndStaleIfError<
CacheValue
, Result extends CacheValue
, Args extends any[]
>(
options: Omit<
IMemoizeStaleWhileRevalidateAndStaleIfError
, 'verbose'
>
, fn: (...args: Args) => Awaitable
): (...args: Args) => Promise
function memoizeStaleWhileRevalidateAndStaleIfError<
CacheValue
, Result extends CacheValue
, Args extends any[]
>(
options: IMemoizeStaleWhileRevalidateAndStaleIfError
, fn: (...args: Args) => Awaitable
): (...args: Args) => Promise>
```