@atproto-labs/simple-store 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @atproto-labs/simple-store
+
+## 0.1.0
+
+### Minor Changes
+
+- [#2482](https://github.com/bluesky-social/atproto/pull/2482) [`a8d6c1123`](https://github.com/bluesky-social/atproto/commit/a8d6c112359f5c4c0cfbe2df63443ed275f2a646) Thanks [@matthieusieben](https://github.com/matthieusieben)! - Add OAuth provider capability & support for DPoP signed tokens

package/LICENSE.txt

@@ -0,0 +1,7 @@
+Dual MIT/Apache-2.0 License
+
+Copyright (c) 2022-2024 Bluesky PBC, and Contributors
+
+Except as otherwise noted in individual files, this software is licensed under the MIT license (<http://opensource.org/licenses/MIT>), or the Apache License, Version 2.0 (<http://www.apache.org/licenses/LICENSE-2.0>).
+
+Downstream projects and end users may chose either license individually, or both together, at their discretion. The motivation for this dual-licensing is the additional software patent assurance provided by Apache 2.0.

package/dist/cached-getter.d.ts

@@ -0,0 +1,44 @@
+import { Awaitable, SimpleStore, Key, Value } from './simple-store.js';
+export type GetCachedOptions = {
+    signal?: AbortSignal;
+    /**
+     * Do not use the cache to get the value. Always get a new value from the
+     * getter function.
+     *
+     * @default false
+     */
+    noCache?: boolean;
+    /**
+     * When getting a value from the cache, allow the value to be returned even if
+     * it is stale.
+     *
+     * Has no effect if the `isStale` option was not provided to the CachedGetter.
+     *
+     * @default true // If the CachedGetter has an isStale option
+     * @default false // If no isStale option was provided to the CachedGetter
+     */
+    allowStale?: boolean;
+};
+export type Getter<K, V> = (key: K, options: undefined | GetCachedOptions, storedValue: undefined | V) => Awaitable<V>;
+export type CachedGetterOptions<K, V> = {
+    isStale?: (key: K, value: V) => boolean | PromiseLike<boolean>;
+    onStoreError?: (err: unknown, key: K, value: V) => void | PromiseLike<void>;
+    deleteOnError?: (err: unknown, key: K, value: V) => boolean | PromiseLike<boolean>;
+};
+/**
+ * Wrapper utility that uses a store to speed up the retrieval of values from an
+ * (expensive) getter function.
+ */
+export declare class CachedGetter<K extends Key = string, V extends Value = Value> {
+    readonly getter: Getter<K, V>;
+    readonly store: SimpleStore<K, V>;
+    readonly options?: Readonly<CachedGetterOptions<K, V>> | undefined;
+    private pending;
+    constructor(getter: Getter<K, V>, store: SimpleStore<K, V>, options?: Readonly<CachedGetterOptions<K, V>> | undefined);
+    get(key: K, options?: GetCachedOptions): Promise<V>;
+    bind(key: K): (options?: GetCachedOptions) => Promise<V>;
+    getStored(key: K, options?: GetCachedOptions): Promise<V | undefined>;
+    setStored(key: K, value: V): Promise<void>;
+    delStored(key: K): Promise<void>;
+}
+//# sourceMappingURL=cached-getter.d.ts.map

package/dist/cached-getter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cached-getter.d.ts","sourceRoot":"","sources":["../src/cached-getter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAA;AAEtE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,MAAM,CAAC,EAAE,WAAW,CAAA;IAEpB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;IAEjB;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,OAAO,CAAA;CACrB,CAAA;AAED,MAAM,MAAM,MAAM,CAAC,CAAC,EAAE,CAAC,IAAI,CACzB,GAAG,EAAE,CAAC,EACN,OAAO,EAAE,SAAS,GAAG,gBAAgB,EACrC,WAAW,EAAE,SAAS,GAAG,CAAC,KACvB,SAAS,CAAC,CAAC,CAAC,CAAA;AAEjB,MAAM,MAAM,mBAAmB,CAAC,CAAC,EAAE,CAAC,IAAI;IACtC,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,KAAK,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC,CAAA;IAC9D,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,KAAK,IAAI,GAAG,WAAW,CAAC,IAAI,CAAC,CAAA;IAC3E,aAAa,CAAC,EAAE,CACd,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,CAAC,EACN,KAAK,EAAE,CAAC,KACL,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC,CAAA;CACpC,CAAA;AAOD;;;GAGG;AACH,qBAAa,YAAY,CAAC,CAAC,SAAS,GAAG,GAAG,MAAM,EAAE,CAAC,SAAS,KAAK,GAAG,KAAK;IAIrE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC;IACjC,QAAQ,CAAC,OAAO,CAAC;IALnB,OAAO,CAAC,OAAO,CAA+B;gBAGnC,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,EACpB,KAAK,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,EACxB,OAAO,CAAC,iDAAqC;IAGlD,GAAG,CAAC,GAAG,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,CAAC,CAAC;IA6EzD,IAAI,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,gBAAgB,KAAK,OAAO,CAAC,CAAC,CAAC;IAIlD,SAAS,CAAC,GAAG,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAQrE,SAAS,CAAC,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ1C,SAAS,CAAC,GAAG,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;CAGvC"}

package/dist/cached-getter.js

@@ -0,0 +1,130 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CachedGetter = void 0;
+const returnTrue = () => true;
+const returnFalse = () => false;
+/**
+ * Wrapper utility that uses a store to speed up the retrieval of values from an
+ * (expensive) getter function.
+ */
+class CachedGetter {
+    constructor(getter, store, options) {
+        Object.defineProperty(this, "getter", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: getter
+        });
+        Object.defineProperty(this, "store", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: store
+        });
+        Object.defineProperty(this, "options", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: options
+        });
+        Object.defineProperty(this, "pending", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+    }
+    async get(key, options) {
+        options?.signal?.throwIfAborted();
+        const isStale = this.options?.isStale;
+        const allowStored = options?.noCache
+            ? returnFalse // Never allow stored values to be returned
+            : options?.allowStale || isStale == null
+                ? returnTrue // Always allow stored values to be returned
+                : async (value) => !(await isStale(key, value));
+        // As long as concurrent requests are made for the same key, only one
+        // request will be made to the cache & getter function at a time. This works
+        // because there is no async operation between the while() loop and the
+        // pending.set() call. Because of the "single threaded" nature of
+        // JavaScript, the pending item will be set before the next iteration of the
+        // while loop.
+        let previousExecutionFlow;
+        while ((previousExecutionFlow = this.pending.get(key))) {
+            try {
+                const { isFresh, value } = await previousExecutionFlow;
+                if (isFresh)
+                    return value;
+                if (await allowStored(value))
+                    return value;
+            }
+            catch {
+                // Ignore errors from previous execution flows (they will have been
+                // propagated by that flow).
+            }
+            options?.signal?.throwIfAborted();
+        }
+        const currentExecutionFlow = Promise.resolve()
+            .then(async () => {
+            const storedValue = await this.getStored(key, options);
+            if (storedValue !== undefined && (await allowStored(storedValue))) {
+                // Use the stored value as return value for the current execution
+                // flow. Notify other concurrent execution flows (that should be
+                // "stuck" in the loop before until this promise resolves) that we got
+                // a value, but that it came from the store (isFresh = false).
+                return { isFresh: false, value: storedValue };
+            }
+            return Promise.resolve()
+                .then(async () => (0, this.getter)(key, options, storedValue))
+                .catch(async (err) => {
+                if (storedValue !== undefined) {
+                    if (await this.options?.deleteOnError?.(err, key, storedValue)) {
+                        await this.delStored(key);
+                    }
+                }
+                throw err;
+            })
+                .then(async (value) => {
+                // The value should be stored even is the signal was aborted.
+                await this.setStored(key, value);
+                return { isFresh: true, value };
+            });
+        })
+            .finally(() => {
+            this.pending.delete(key);
+        });
+        if (this.pending.has(key)) {
+            // This should never happen. Indeed, there must not be any 'await'
+            // statement between this and the loop iteration check meaning that
+            // this.pending.get returned undefined. It is there to catch bugs that
+            // would occur in future changes to the code.
+            throw new Error('Concurrent request for the same key');
+        }
+        this.pending.set(key, currentExecutionFlow);
+        const { value } = await currentExecutionFlow;
+        return value;
+    }
+    bind(key) {
+        return async (options) => this.get(key, options);
+    }
+    async getStored(key, options) {
+        try {
+            return await this.store.get(key, options);
+        }
+        catch (err) {
+            return undefined;
+        }
+    }
+    async setStored(key, value) {
+        try {
+            await this.store.set(key, value);
+        }
+        catch (err) {
+            await this.options?.onStoreError?.(err, key, value);
+        }
+    }
+    async delStored(key) {
+        await this.store.del(key);
+    }
+}
+exports.CachedGetter = CachedGetter;
+//# sourceMappingURL=cached-getter.js.map

package/dist/cached-getter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cached-getter.js","sourceRoot":"","sources":["../src/cached-getter.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './cached-getter.js';
+export * from './simple-store.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAA;AAClC,cAAc,mBAAmB,CAAA"}

package/dist/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./cached-getter.js"), exports);
+__exportStar(require("./simple-store.js"), exports);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,qDAAkC;AAClC,oDAAiC"}

package/dist/simple-store.d.ts

@@ -0,0 +1,16 @@
+export type Awaitable<V> = V | PromiseLike<V>;
+export type Key = string | number;
+export type Value = NonNullable<unknown> | null;
+export type GetOptions = {
+    signal?: AbortSignal;
+};
+export interface SimpleStore<K extends Key = string, V extends Value = Value> {
+    /**
+     * @return undefined if the key is not in the store (which is why Value cannot contain "undefined").
+     */
+    get: (key: K, options?: GetOptions) => Awaitable<undefined | V>;
+    set: (key: K, value: V) => Awaitable<void>;
+    del: (key: K) => Awaitable<void>;
+    clear?: () => Awaitable<void>;
+}
+//# sourceMappingURL=simple-store.d.ts.map

package/dist/simple-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"simple-store.d.ts","sourceRoot":"","sources":["../src/simple-store.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAAA;AAE7C,MAAM,MAAM,GAAG,GAAG,MAAM,GAAG,MAAM,CAAA;AACjC,MAAM,MAAM,KAAK,GAAG,WAAW,CAAC,OAAO,CAAC,GAAG,IAAI,CAAA;AAE/C,MAAM,MAAM,UAAU,GAAG;IAAE,MAAM,CAAC,EAAE,WAAW,CAAA;CAAE,CAAA;AAEjD,MAAM,WAAW,WAAW,CAAC,CAAC,SAAS,GAAG,GAAG,MAAM,EAAE,CAAC,SAAS,KAAK,GAAG,KAAK;IAC1E;;OAEG;IACH,GAAG,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,UAAU,KAAK,SAAS,CAAC,SAAS,GAAG,CAAC,CAAC,CAAA;IAC/D,GAAG,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,KAAK,SAAS,CAAC,IAAI,CAAC,CAAA;IAC1C,GAAG,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,SAAS,CAAC,IAAI,CAAC,CAAA;IAChC,KAAK,CAAC,EAAE,MAAM,SAAS,CAAC,IAAI,CAAC,CAAA;CAC9B"}

package/dist/simple-store.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=simple-store.js.map

package/dist/simple-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"simple-store.js","sourceRoot":"","sources":["../src/simple-store.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@atproto-labs/simple-store",
+  "version": "0.1.0",
+  "license": "MIT",
+  "description": "Simple store interfaces & utilities",
+  "keywords": [
+    "cache",
+    "isomorphic"
+  ],
+  "homepage": "https://atproto.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bluesky-social/atproto",
+    "directory": "packages/internal/simple-store"
+  },
+  "type": "commonjs",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "typescript": "^5.3.3"
+  },
+  "scripts": {
+    "build": "tsc --build tsconfig.build.json"
+  }
+}

package/src/cached-getter.ts

@@ -0,0 +1,160 @@
+import { Awaitable, SimpleStore, Key, Value } from './simple-store.js'
+
+export type GetCachedOptions = {
+  signal?: AbortSignal
+
+  /**
+   * Do not use the cache to get the value. Always get a new value from the
+   * getter function.
+   *
+   * @default false
+   */
+  noCache?: boolean
+
+  /**
+   * When getting a value from the cache, allow the value to be returned even if
+   * it is stale.
+   *
+   * Has no effect if the `isStale` option was not provided to the CachedGetter.
+   *
+   * @default true // If the CachedGetter has an isStale option
+   * @default false // If no isStale option was provided to the CachedGetter
+   */
+  allowStale?: boolean
+}
+
+export type Getter<K, V> = (
+  key: K,
+  options: undefined | GetCachedOptions,
+  storedValue: undefined | V,
+) => Awaitable<V>
+
+export type CachedGetterOptions<K, V> = {
+  isStale?: (key: K, value: V) => boolean | PromiseLike<boolean>
+  onStoreError?: (err: unknown, key: K, value: V) => void | PromiseLike<void>
+  deleteOnError?: (
+    err: unknown,
+    key: K,
+    value: V,
+  ) => boolean | PromiseLike<boolean>
+}
+
+type PendingItem<V> = Promise<{ value: V; isFresh: boolean }>
+
+const returnTrue = () => true
+const returnFalse = () => false
+
+/**
+ * Wrapper utility that uses a store to speed up the retrieval of values from an
+ * (expensive) getter function.
+ */
+export class CachedGetter<K extends Key = string, V extends Value = Value> {
+  private pending = new Map<K, PendingItem<V>>()
+
+  constructor(
+    readonly getter: Getter<K, V>,
+    readonly store: SimpleStore<K, V>,
+    readonly options?: Readonly<CachedGetterOptions<K, V>>,
+  ) {}
+
+  async get(key: K, options?: GetCachedOptions): Promise<V> {
+    options?.signal?.throwIfAborted()
+
+    const isStale = this.options?.isStale
+
+    const allowStored: (value: V) => Awaitable<boolean> = options?.noCache
+      ? returnFalse // Never allow stored values to be returned
+      : options?.allowStale || isStale == null
+        ? returnTrue // Always allow stored values to be returned
+        : async (value: V) => !(await isStale(key, value))
+
+    // As long as concurrent requests are made for the same key, only one
+    // request will be made to the cache & getter function at a time. This works
+    // because there is no async operation between the while() loop and the
+    // pending.set() call. Because of the "single threaded" nature of
+    // JavaScript, the pending item will be set before the next iteration of the
+    // while loop.
+    let previousExecutionFlow: undefined | PendingItem<V>
+    while ((previousExecutionFlow = this.pending.get(key))) {
+      try {
+        const { isFresh, value } = await previousExecutionFlow
+
+        if (isFresh) return value
+        if (await allowStored(value)) return value
+      } catch {
+        // Ignore errors from previous execution flows (they will have been
+        // propagated by that flow).
+      }
+
+      options?.signal?.throwIfAborted()
+    }
+
+    const currentExecutionFlow: PendingItem<V> = Promise.resolve()
+      .then(async () => {
+        const storedValue = await this.getStored(key, options)
+        if (storedValue !== undefined && (await allowStored(storedValue))) {
+          // Use the stored value as return value for the current execution
+          // flow. Notify other concurrent execution flows (that should be
+          // "stuck" in the loop before until this promise resolves) that we got
+          // a value, but that it came from the store (isFresh = false).
+          return { isFresh: false, value: storedValue }
+        }
+
+        return Promise.resolve()
+          .then(async () => (0, this.getter)(key, options, storedValue))
+          .catch(async (err) => {
+            if (storedValue !== undefined) {
+              if (await this.options?.deleteOnError?.(err, key, storedValue)) {
+                await this.delStored(key)
+              }
+            }
+            throw err
+          })
+          .then(async (value) => {
+            // The value should be stored even is the signal was aborted.
+            await this.setStored(key, value)
+            return { isFresh: true, value }
+          })
+      })
+      .finally(() => {
+        this.pending.delete(key)
+      })
+
+    if (this.pending.has(key)) {
+      // This should never happen. Indeed, there must not be any 'await'
+      // statement between this and the loop iteration check meaning that
+      // this.pending.get returned undefined. It is there to catch bugs that
+      // would occur in future changes to the code.
+      throw new Error('Concurrent request for the same key')
+    }
+
+    this.pending.set(key, currentExecutionFlow)
+
+    const { value } = await currentExecutionFlow
+    return value
+  }
+
+  bind(key: K): (options?: GetCachedOptions) => Promise<V> {
+    return async (options) => this.get(key, options)
+  }
+
+  async getStored(key: K, options?: GetCachedOptions): Promise<V | undefined> {
+    try {
+      return await this.store.get(key, options)
+    } catch (err) {
+      return undefined
+    }
+  }
+
+  async setStored(key: K, value: V): Promise<void> {
+    try {
+      await this.store.set(key, value)
+    } catch (err) {
+      await this.options?.onStoreError?.(err, key, value)
+    }
+  }
+
+  async delStored(key: K): Promise<void> {
+    await this.store.del(key)
+  }
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from './cached-getter.js'
+export * from './simple-store.js'

package/src/simple-store.ts

@@ -0,0 +1,16 @@
+export type Awaitable<V> = V | PromiseLike<V>
+
+export type Key = string | number
+export type Value = NonNullable<unknown> | null
+
+export type GetOptions = { signal?: AbortSignal }
+
+export interface SimpleStore<K extends Key = string, V extends Value = Value> {
+  /**
+   * @return undefined if the key is not in the store (which is why Value cannot contain "undefined").
+   */
+  get: (key: K, options?: GetOptions) => Awaitable<undefined | V>
+  set: (key: K, value: V) => Awaitable<void>
+  del: (key: K) => Awaitable<void>
+  clear?: () => Awaitable<void>
+}

package/tsconfig.build.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../../tsconfig/isomorphic.json",
+  "compilerOptions": {
+    "rootDir": "./src",
+    "outDir": "./dist"
+  },
+  "include": ["./src"]
+}

package/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "include": [],
+  "references": [{ "path": "./tsconfig.build.json" }]
+}