@gera2ld/async-memo 1.0.0

package/README.md

@@ -0,0 +1,163 @@
+# @gera2ld/async-memo
+
+[![npm version][npm-version-src]][npm-version-href]
+[![npm downloads][npm-downloads-src]][npm-downloads-href]
+[![bundle][bundle-src]][bundle-href]
+[![JSDocs][jsdocs-src]][jsdocs-href]
+
+## Usage
+
+### Quick Start
+
+```ts
+import { asyncMemo } from '@gera2ld/async-memo';
+
+const myApi = asyncMemo(myApiCall, {
+  resolver: (params) => [groupKey, cacheKey],
+});
+
+// Call from anywhere
+async function someAction() {
+  const response = await myApi(params);
+}
+
+// Get the current value anytime
+function getValueSync() {
+  return myApi.get(params);
+}
+
+// Get context to avoid passing args around
+function otherPlace() {
+  const ctx = myApi.context(params);
+  ctx.get();        // sync get
+  ctx.reload();     // refresh data
+  ctx.isSettled();  // check loading state
+}
+```
+
+Each `groupKey` has its own cache. The cache is invalidated when the `cacheKey` changes.
+
+### Options
+
+```ts
+interface CacheOptions<T extends unknown[]> {
+  /** Convert args into cacheGroup and cacheKey.
+   * By default the function is only evaluated once. */
+  resolver: (...args: T) => string | [cacheGroup: string, cacheKey: string];
+  /** Whether stale value should be returned. Default: false */
+  mustRevalidate: boolean;
+  /** Time to live in ms, -1 for always. Default: -1 */
+  ttl: number;
+}
+```
+
+### Use Cases
+
+#### Load once globally
+
+This is the default behavior.
+
+```ts
+const loadOnceGlobally = asyncMemo(api);
+// or
+const loadOnceGlobally = asyncMemo(api, {
+  resolver: () => '',
+});
+```
+
+#### Load on param change
+
+```ts
+const loadOnParamChange = asyncMemo(api, {
+  resolver: (params) => ['', JSON.stringify(params)],
+});
+```
+
+#### Cache data for multiple tabs
+
+The data for each tab will be cached in a different group, with the parameters as its cache key.
+
+```ts
+const loadOnParamChange = asyncMemo(api, {
+  resolver: (params) => [params.tab, JSON.stringify(params)],
+});
+```
+
+### Custom Cache Store
+
+For frameworks like MobX or Vue, you can provide a custom cache store:
+
+```ts
+import { createAsyncMemo } from '@gera2ld/async-memo';
+
+function createCache<T>() {
+  // ... your cache implementation
+  return {
+    get(cacheKey: string) { ... },
+    set(cacheKey: string, data?: T) { ... },
+    clear() { ... },
+  };
+}
+
+const asyncMemo = createAsyncMemo(createCache);
+```
+
+<details>
+<summary>MobX example</summary>
+
+```ts
+import { observable } from 'mobx';
+
+function createCache<T>() {
+  const target = observable<{ value: Record<string, T | undefined> }>(
+    { value: {} },
+    { value: observable.ref },
+  );
+  return {
+    get(cacheKey: string) {
+      return target.value[cacheKey];
+    },
+    set(cacheKey: string, data?: T) {
+      target.value = { ...target.value, [cacheKey]: data };
+    },
+    clear() {
+      target.value = {};
+    },
+  };
+}
+```
+
+</details>
+
+<details>
+<summary>Vue example</summary>
+
+```ts
+import { ref } from 'vue';
+
+function createCache<T>() {
+  const target = ref<Record<string, T | undefined>>({});
+  return {
+    get(cacheKey: string) {
+      return target.value[cacheKey];
+    },
+    set(cacheKey: string, data?: T) {
+      target.value = { ...target.value, [cacheKey]: data };
+    },
+    clear() {
+      target.value = {};
+    },
+  };
+}
+```
+
+</details>
+
+[npm-version-src]: https://img.shields.io/npm/v/@gera2ld/async-memo?style=flat&colorA=18181B&colorB=F0DB4F
+[npm-version-href]: https://npmjs.com/package/@gera2ld/async-memo
+[npm-downloads-src]: https://img.shields.io/npm/dm/@gera2ld/async-memo?style=flat&colorA=18181B&colorB=F0DB4F
+[npm-downloads-href]: https://npmjs.com/package/@gera2ld/async-memo
+[bundle-src]: https://img.shields.io/bundlephobia/minzip/@gera2ld/async-memo?style=flat&colorA=18181B&colorB=F0DB4F
+[bundle-href]: https://bundlephobia.com/result?p=@gera2ld/async-memo
+[jsdocs-src]: https://img.shields.io/badge/jsDocs.io-reference-18181B?style=flat&colorA=18181B&colorB=F0DB4F
+[jsdocs-href]: https://www.jsdocs.io/package/@gera2ld/async-memo

package/dist/index.d.ts

@@ -0,0 +1,71 @@
+export interface CacheContext<U> {
+    call(): Promise<U>;
+    /** Return the currently cached value immediately. */
+    get(): U | undefined;
+    /** Override the cache with the specified value. */
+    set(value: U, ttl?: number): void;
+    /** Delete the currently cached value. */
+    delete(): void;
+    /** Invalidate the current cached value and send a new request without deleting the old value. */
+    reload(): Promise<U>;
+    /** Whether the latest request is settled. */
+    isSettled(): boolean;
+    /** Whether the value returned by `get` is fresh. */
+    isFresh(): boolean;
+}
+export interface CachedFunction<T extends unknown[], U, S extends CacheStorage> {
+    (...args: T): Promise<U>;
+    /** Return the currently cached value immediately. */
+    get(...args: T): U | undefined;
+    /** Delete the currently cached value. */
+    delete(...args: T): void;
+    /** Invalidate the current cached value and send a new request without deleting the old value. */
+    reload(...args: T): Promise<U>;
+    /** Whether the latest request is settled. */
+    isSettled(...args: T): boolean;
+    /** Whether the value returned by `get` is fresh. */
+    isFresh(...args: T): boolean;
+    /** Clear cache. */
+    clear(): void;
+    /** Get the cache context so we don't need to pass `args` around. */
+    context(...args: T): CacheContext<U>;
+    /** The cache storage, only used for testing purpose. */
+    cache: S;
+}
+type CachePrimitiveKey = string | number | undefined;
+export interface CacheOptions<T extends unknown[]> {
+    /**
+     * Convert args into `cacheGroup` and `cacheKey`.
+     * If `cacheKey` is not provided, `cacheGroup` will be used.
+     * By default the args are ignored and the function is only evaluated once.
+     *
+     * Each `cacheGroup` stores a cached value, `cacheKey` determines whether the value is stale and needs to be reloaded.
+     *
+     * @returns `cacheGroup` or `[cacheGroup, cacheKey]`.
+     */
+    resolver: (...args: T) => CachePrimitiveKey | [cacheGroup: CachePrimitiveKey, cacheKey: CachePrimitiveKey];
+    /**
+     * Whether stale value should be returned.
+     */
+    mustRevalidate: boolean;
+    /**
+     * Time to live, -1 for always. Default as `-1`.
+     */
+    ttl: number;
+}
+export interface CacheData<U = unknown> {
+    key: string;
+    promise: Promise<U>;
+    settled: boolean;
+    value?: U;
+    expiresAt: number;
+}
+export interface CacheStorage<U = unknown> {
+    get(cacheGroup: string): CacheData<U> | undefined;
+    set(cacheGroup: string, data?: CacheData<U>): void;
+    clear(): void;
+}
+export declare function createAsyncMemoStorage(): Map<string, CacheData<unknown>>;
+export declare function createAsyncMemo<S extends CacheStorage = ReturnType<typeof createAsyncMemoStorage>>(cacheFactory?: () => S): <U, T extends unknown[]>(fn: (...args: T) => Promise<U>, options?: Partial<CacheOptions<T>>) => CachedFunction<T, U, S>;
+export declare const asyncMemo: <U, T extends unknown[]>(fn: (...args: T) => Promise<U>, options?: Partial<CacheOptions<T>> | undefined) => CachedFunction<T, U, Map<string, CacheData<unknown>>>;
+export {};

package/dist/index.js

@@ -0,0 +1,104 @@
+const K = {
+  mustRevalidate: !1,
+  resolver: () => "",
+  ttl: -1
+};
+function O() {
+  return /* @__PURE__ */ new Map();
+}
+function P(x) {
+  return (y, D) => {
+    const n = (x || O)(), { mustRevalidate: M, resolver: w, ttl: a } = {
+      ...K,
+      ...D
+    }, F = (...e) => {
+      const s = w(...e);
+      return (Array.isArray(s) ? s : [s, s]).map((r) => `${r ?? ""}`);
+    }, o = (e) => (...s) => {
+      const t = F(...s);
+      return e(t, s);
+    }, i = ([e, s]) => {
+      const t = n.get(e);
+      return t?.key === s && t.settled;
+    }, l = ([e, s]) => {
+      const t = n.get(e);
+      return t?.key === s && t.settled && (t.expiresAt < 0 || t.expiresAt > Date.now());
+    }, h = ([e, s]) => {
+      const t = n.get(e);
+      if (t && (!M || l([e, s])))
+        return t.value;
+    }, v = ([e, s], t, r = a) => {
+      const c = r < 0 ? r : Date.now() + r;
+      n.set(e, {
+        key: s,
+        ...n.get(e),
+        promise: t == null ? Promise.reject() : Promise.resolve(t),
+        value: t,
+        expiresAt: c,
+        settled: !0
+      });
+    }, f = ([e]) => {
+      n.set(e);
+    }, S = () => {
+      n.clear();
+    }, d = ([e, s], t) => {
+      const r = n.get(e), c = y(...t), u = {
+        ...r,
+        key: s,
+        promise: c,
+        // Set to -1 until the promise is either resolved or rejected
+        expiresAt: -1,
+        settled: !1
+      };
+      n.set(e, u);
+      const p = (m, C) => {
+        if (n.get(e) !== u)
+          return;
+        let g;
+        m ? g = 0 : g = a < 0 ? a : Date.now() + a, n.set(e, {
+          ...u,
+          value: C,
+          expiresAt: g,
+          settled: !0
+        });
+      };
+      return c.then(
+        (m) => {
+          p(!1, m);
+        },
+        () => {
+          p(!0);
+        }
+      ), c;
+    }, A = (e, s) => {
+      const [t, r] = e, c = n.get(t);
+      return c?.key === r && (l(e) || !i(e)) ? c.promise : d(e, s);
+    }, j = (e, s) => ({
+      call: () => A(e, s),
+      get: () => h(e),
+      set: (t, r = -1) => {
+        v(e, t, r);
+      },
+      delete: () => f(e),
+      reload: () => d(e, s),
+      isSettled: () => i(e),
+      isFresh: () => l(e)
+    });
+    return Object.assign(o(A), {
+      get: o(h),
+      delete: o(f),
+      reload: o(d),
+      isSettled: o(i),
+      isFresh: o(l),
+      context: o(j),
+      clear: S,
+      cache: n
+    });
+  };
+}
+const _ = P();
+export {
+  _ as asyncMemo,
+  P as createAsyncMemo,
+  O as createAsyncMemoStorage
+};

package/dist/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@gera2ld/async-memo",
+  "version": "1.0.0",
+  "description": "Cache asynchronous functions where they should be",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "keywords": [
+    "api",
+    "cache",
+    "async"
+  ],
+  "author": "Gerald <code@gera2ld.space>",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gera2ld/async-memo.git"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.3",
+    "vite": "^7.3.1",
+    "vitest": "^4.0.18"
+  },
+  "scripts": {
+    "build:js": "vite build",
+    "build:types": "tsc",
+    "build": "pnpm run /^build:/",
+    "test": "vitest --run"
+  }
+}