@stackframe/stack-shared 1.0.0 → 1.2.0

package/dist/interface/serverInterface.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serverInterface.d.ts","sourceRoot":"","sources":["../../src/interface/serverInterface.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,EACtB,oBAAoB,EACpB,QAAQ,EACR,UAAU,EACV,oBAAoB,EACrB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAG7C,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG;IACtC,QAAQ,CAAC,cAAc,EAAE,YAAY,CAAC;CACvC,CAAC;AAEF,MAAM,MAAM,0BAA0B,GAAG,oBAAoB,GAAG;IAC9D,QAAQ,CAAC,cAAc,EAAE,YAAY,CAAC;IACtC,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,QAAQ,CAAC,oBAAoB,EAAE,OAAO,CAAC;CACxC,CAAA;AAGD,MAAM,MAAM,4BAA4B,GAAG,CACvC,sBAAsB,GACtB,CACE;IACA,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC,GACC;IACA,QAAQ,CAAC,wBAAwB,EAAE,MAAM,CAAC;CAC3C,CACF,CACF,CAAC;AAGF,qBAAa,oBAAqB,SAAQ,oBAAoB;IAKhC,OAAO,EAAE,4BAA4B;IAFjE,SAAgB,sBAAsB,EAAE,UAAU,CAAC,UAAU,EAAE,cAAc,GAAG,IAAI,CAAC,CAAC;gBAE1D,OAAO,EAAE,4BAA4B;IAelD,WAAW,CAAC,UAAU,EAAE,UAAU;cAOjC,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,UAAU,GAAG,IAAI;;;;;;IAc7F,oBAAoB,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC;IAW7E,SAAS,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC;IAKtC,6BAA6B,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,0BAA0B,CAAC;IAczF,gBAAgB,CAAC,MAAM,EAAE,MAAM;CAatC"}
+{"version":3,"file":"serverInterface.d.ts","sourceRoot":"","sources":["../../src/interface/serverInterface.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,EACtB,oBAAoB,EACpB,QAAQ,EACR,UAAU,EACV,oBAAoB,EACpB,kBAAkB,EACnB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAG1C,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAE7C,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG;IACtC,QAAQ,CAAC,cAAc,EAAE,YAAY,CAAC;CACvC,CAAC;AAEF,MAAM,MAAM,0BAA0B,GAAG,oBAAoB,GAAG;IAC9D,QAAQ,CAAC,cAAc,EAAE,YAAY,CAAC;IACtC,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,QAAQ,CAAC,oBAAoB,EAAE,OAAO,CAAC;CACxC,CAAA;AAGD,MAAM,MAAM,4BAA4B,GAAG,CACvC,sBAAsB,GACtB,CACE;IACA,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC,GACC;IACA,QAAQ,CAAC,kBAAkB,EAAE,kBAAkB,CAAC;CACjD,CACF,CACF,CAAC;AAGF,qBAAa,oBAAqB,SAAQ,oBAAoB;IAChC,OAAO,EAAE,4BAA4B;gBAArC,OAAO,EAAE,4BAA4B;cAIjD,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,UAAU,GAAG,IAAI;;;;;;IAc7F,oBAAoB,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC;IAW7E,SAAS,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC;IAKtC,6BAA6B,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,0BAA0B,CAAC;IAczF,gBAAgB,CAAC,MAAM,EAAE,MAAM;CAatC"}

package/dist/interface/serverInterface.js

@@ -1,33 +1,10 @@
 import { StackClientInterface, } from "./clientInterface";
 import { Result } from "../utils/results";
-import { AsyncCache } from "../utils/caches";
-import { runAsynchronously } from "../utils/promises";
 export class StackServerInterface extends StackClientInterface {
     options;
-    // note that we intentionally use TokenStore (a reference type) as a key, as different token stores with the same tokens should be treated differently
-    // (if we wouldn't do that, we would cache users across requests, which may cause caching issues)
-    currentServerUserCache;
     constructor(options) {
         super(options);
         this.options = options;
-        this.currentServerUserCache = new AsyncCache(async (key, isFirst) => {
-            if (isFirst) {
-                key.onChange((newValue, oldValue) => {
-                    if (JSON.stringify(newValue) === JSON.stringify(oldValue))
-                        return;
-                    runAsynchronously(this.currentServerUserCache.refresh(key));
-                });
-            }
-            const user = await this.getServerUserByToken(key);
-            return Result.or(user, null);
-        });
-        // TODO override the client user cache to use the server user cache, so we save some requests
-    }
-    async refreshUser(tokenStore) {
-        await Promise.all([
-            super.refreshUser(tokenStore),
-            this.currentServerUserCache.refresh(tokenStore),
-        ]);
     }
     async sendServerRequest(path, options, tokenStore) {
         return await this.sendClientRequest(path, {

package/dist/utils/arrays.d.ts

@@ -8,3 +8,4 @@ export declare function range(startInclusive: number, endExclusive: number, step
 export declare function rotateLeft(arr: readonly any[], n: number): any[];
 export declare function rotateRight(arr: readonly any[], n: number): any[];
 export declare function shuffle<T>(arr: readonly T[]): T[];
+//# sourceMappingURL=arrays.d.ts.map

package/dist/utils/bytes.d.ts

@@ -0,0 +1,3 @@
+export declare function encodeBase32(input: Uint8Array): string;
+export declare function decodeBase32(input: string): Uint8Array;
+//# sourceMappingURL=bytes.d.ts.map

package/dist/utils/bytes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bytes.d.ts","sourceRoot":"","sources":["../../src/utils/bytes.tsx"],"names":[],"mappings":"AAOA,wBAAgB,YAAY,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAgBtD;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,CAuBtD"}

package/dist/utils/bytes.js

@@ -0,0 +1,48 @@
+const crockfordAlphabet = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+const crockfordReplacements = new Map([
+    ["o", "0"],
+    ["i", "1"],
+    ["l", "1"],
+]);
+export function encodeBase32(input) {
+    let bits = 0;
+    let value = 0;
+    let output = "";
+    for (let i = 0; i < input.length; i++) {
+        value = (value << 8) | input[i];
+        bits += 8;
+        while (bits >= 5) {
+            output += crockfordAlphabet[(value >>> (bits - 5)) & 31];
+            bits -= 5;
+        }
+    }
+    if (bits > 0) {
+        output += crockfordAlphabet[(value << (5 - bits)) & 31];
+    }
+    return output;
+}
+export function decodeBase32(input) {
+    const output = new Uint8Array((input.length * 5 / 8) | 0);
+    let bits = 0;
+    let value = 0;
+    let outputIndex = 0;
+    for (let i = 0; i < input.length; i++) {
+        let char = input[i].toLowerCase();
+        if (char === " ")
+            continue;
+        if (crockfordReplacements.has(char)) {
+            char = crockfordReplacements.get(char);
+        }
+        const index = crockfordAlphabet.indexOf(char);
+        if (index === -1) {
+            throw new Error(`Invalid character: ${char}`);
+        }
+        value = (value << 5) | index;
+        bits += 5;
+        if (bits >= 8) {
+            output[outputIndex++] = (value >>> (bits - 8)) & 255;
+            bits -= 8;
+        }
+    }
+    return output;
+}

package/dist/utils/caches.d.ts

@@ -1,15 +1,21 @@
 import { RateLimitOptions, ReactPromise } from "./promises";
-import { ReadonlyAsyncStore } from "./stores";
-export declare class AsyncCache<K extends object, T> {
+/**
+ * Can be used to cache the result of a function call, for example for the `use` hook in React.
+ */
+export declare function cacheFunction<F extends Function>(f: F): F;
+type CacheStrategy = "write-only" | "read-write" | "never";
+export declare class AsyncCache<D extends any[], T> {
     private readonly _fetcher;
-    private readonly _rateLimitOptions;
-    private _map;
-    constructor(_fetcher: (key: K, isFirst: boolean) => Promise<T>, _rateLimitOptions?: Omit<RateLimitOptions, "batchCalls">);
+    private readonly _options;
+    private readonly _map;
+    constructor(_fetcher: (dependencies: D) => Promise<T>, _options?: {
+        onSubscribe?: (key: D, refresh: () => void) => (() => void);
+        rateLimiter?: Omit<RateLimitOptions, "batchCalls">;
+    });
     private _createKeyed;
-    getValueCache(key: K): AsyncValueCache<T>;
-    isAvailable: (key: K) => boolean;
-    setUnavailable: (key: K) => void;
-    get: (key: K) => ({
+    getValueCache(dependencies: D): AsyncValueCache<T>;
+    readonly isCacheAvailable: (key: D) => boolean;
+    readonly getIfCached: (key: D) => ({
         status: "pending";
     } & {
         progress: void;
@@ -26,25 +32,26 @@ export declare class AsyncCache<K extends object, T> {
     } & {
         status: "ok";
     });
-    getOrWait: (key: K) => ReactPromise<T>;
-    refresh: (key: K) => Promise<T>;
-    invalidate: (key: K) => Promise<T>;
-    onChange: (key: K, callback: (value: T, oldValue: T | undefined) => void) => {
-        unsubscribe: () => void;
-    };
-    onceChange: (key: K, callback: (value: T, oldValue: T | undefined) => void) => {
+    readonly getOrWait: (key: D, cacheStrategy: CacheStrategy) => ReactPromise<T>;
+    readonly refresh: (key: D) => Promise<T>;
+    readonly invalidate: (key: D) => Promise<T>;
+    readonly onChange: (key: D, callback: (value: T, oldValue: T | undefined) => void) => {
         unsubscribe: () => void;
     };
 }
-export declare class AsyncValueCache<T> implements ReadonlyAsyncStore<T> {
-    private readonly _rateLimitOptions;
+declare class AsyncValueCache<T> {
+    private readonly _options;
     private _store;
-    private _firstFetcher;
-    private _laterFetcher;
-    constructor(fetcher: (isFirst: boolean) => Promise<T>, _rateLimitOptions?: Omit<RateLimitOptions, "batchCalls">);
-    isAvailable(): boolean;
-    setUnavailable(): void;
-    get(): ({
+    private _fetcher;
+    private readonly _rateLimitOptions;
+    private _subscriptionsCount;
+    private _unsubscribers;
+    constructor(fetcher: () => Promise<T>, _options?: {
+        onSubscribe?: (refresh: () => void) => (() => void);
+        rateLimiter?: Omit<RateLimitOptions, "batchCalls">;
+    });
+    isCacheAvailable(): boolean;
+    getIfCached(): ({
         status: "pending";
     } & {
         progress: void;
@@ -61,7 +68,7 @@ export declare class AsyncValueCache<T> implements ReadonlyAsyncStore<T> {
     } & {
         status: "ok";
     });
-    getOrWait(): ReactPromise<T>;
+    getOrWait(cacheStrategy: CacheStrategy): ReactPromise<T>;
     private _set;
     private _setAsync;
     private _refetch;
@@ -70,7 +77,6 @@ export declare class AsyncValueCache<T> implements ReadonlyAsyncStore<T> {
     onChange(callback: (value: T, oldValue: T | undefined) => void): {
         unsubscribe: () => void;
     };
-    onceChange(callback: (value: T, oldValue: T | undefined) => void): {
-        unsubscribe: () => void;
-    };
 }
+export {};
+//# sourceMappingURL=caches.d.ts.map

package/dist/utils/caches.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"caches.d.ts","sourceRoot":"","sources":["../../src/utils/caches.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAe,MAAM,YAAY,CAAC;AACzE,OAAO,EAAc,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAE1D,qBAAa,UAAU,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC;IAIvC,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,iBAAiB;IAJpC,OAAO,CAAC,IAAI,CAA6C;gBAGtC,QAAQ,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,CAAC,CAAC,EAClD,iBAAiB,GAAE,IAAI,CAAC,gBAAgB,EAAE,YAAY,CAAoC;IAK7G,OAAO,CAAC,YAAY;IASpB,aAAa,CAAC,GAAG,EAAE,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC;IAWzC,WAAW,QAlBF,CAAC,aAkBqC;IAC/C,cAAc,QAnBL,CAAC,UAmB2C;IACrD,GAAG,QApBM,CAAC;;;;;;;;;;;;;;;;OAoBqB;IAC/B,SAAS,QArBA,CAAC,qBAqBiC;IAC3C,OAAO,QAtBE,CAAC,gBAsB6B;IACvC,UAAU,QAvBD,CAAC,gBAuBmC;IAC7C,QAAQ,QAxBC,CAAC;;MAwB+B;IACzC,UAAU,QAzBD,CAAC;;MAyBmC;CAC9C;AAED,qBAAa,eAAe,CAAC,CAAC,CAAE,YAAW,kBAAkB,CAAC,CAAC,CAAC;IAO5D,OAAO,CAAC,QAAQ,CAAC,iBAAiB;IANpC,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,aAAa,CAAmB;IACxC,OAAO,CAAC,aAAa,CAAmB;gBAGtC,OAAO,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,CAAC,CAAC,EACxB,iBAAiB,GAAE,IAAI,CAAC,gBAAgB,EAAE,YAAY,CAAyC;IAmBlH,WAAW,IAAI,OAAO;IAItB,cAAc,IAAI,IAAI;IAItB,GAAG;;;;;;;;;;;;;;;;;IAIH,SAAS,IAAI,YAAY,CAAC,CAAC,CAAC;IAI5B,OAAO,CAAC,IAAI;YAIE,SAAS;YAIT,QAAQ;IAWhB,OAAO,IAAI,OAAO,CAAC,CAAC,CAAC;IAIrB,UAAU,IAAI,OAAO,CAAC,CAAC,CAAC;IAK9B,QAAQ,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,GAAG,SAAS,KAAK,IAAI,GAAG;QAAE,WAAW,EAAE,MAAM,IAAI,CAAA;KAAE;IAI5F,UAAU,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,GAAG,SAAS,KAAK,IAAI,GAAG;QAAE,WAAW,EAAE,MAAM,IAAI,CAAA;KAAE;CAG/F"}
+{"version":3,"file":"caches.d.ts","sourceRoot":"","sources":["../../src/utils/caches.tsx"],"names":[],"mappings":"AAEA,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAqD,MAAM,YAAY,CAAC;AAG/G;;GAEG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,CAYzD;AAGD,KAAK,aAAa,GAAG,YAAY,GAAG,YAAY,GAAG,OAAO,CAAC;AAE3D,qBAAa,UAAU,CAAC,CAAC,SAAS,GAAG,EAAE,EAAE,CAAC;IAItC,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAJ3B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAgD;gBAGlD,QAAQ,EAAE,CAAC,YAAY,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,EACzC,QAAQ,GAAE;QACzB,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,OAAO,EAAE,MAAM,IAAI,KAAK,CAAC,MAAM,IAAI,CAAC,CAAC;QAC5D,WAAW,CAAC,EAAE,IAAI,CAAC,gBAAgB,EAAE,YAAY,CAAC,CAAC;KAC/C;IAKR,OAAO,CAAC,YAAY;IASpB,aAAa,CAAC,YAAY,EAAE,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC;IAelD,QAAQ,CAAC,gBAAgB,QAtBhB,CAAC,aAsBwD;IAClE,QAAQ,CAAC,WAAW,QAvBX,CAAC;;;;;;;;;;;;;;;;OAuB8C;IACxD,QAAQ,CAAC,SAAS,QAxBT,CAAC,mDAwB0C;IACpD,QAAQ,CAAC,OAAO,QAzBP,CAAC,gBAyBsC;IAChD,QAAQ,CAAC,UAAU,QA1BV,CAAC,gBA0B4C;IACtD,QAAQ,CAAC,QAAQ,QA3BR,CAAC;;MA2BwC;CACnD;AAED,cAAM,eAAe,CAAC,CAAC;IASnB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAR3B,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,QAAQ,CAAmB;IACnC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAuC;IACzE,OAAO,CAAC,mBAAmB,CAAK;IAChC,OAAO,CAAC,cAAc,CAAsB;gBAG1C,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACR,QAAQ,GAAE;QACzB,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,IAAI,KAAK,CAAC,MAAM,IAAI,CAAC,CAAC;QACpD,WAAW,CAAC,EAAE,IAAI,CAAC,gBAAgB,EAAE,YAAY,CAAC,CAAC;KAC/C;IAgBR,gBAAgB,IAAI,OAAO;IAI3B,WAAW;;;;;;;;;;;;;;;;;IAIX,SAAS,CAAC,aAAa,EAAE,aAAa,GAAG,YAAY,CAAC,CAAC,CAAC;IASxD,OAAO,CAAC,IAAI;YAIE,SAAS;YAIT,QAAQ;IAahB,OAAO,IAAI,OAAO,CAAC,CAAC,CAAC;IAIrB,UAAU,IAAI,OAAO,CAAC,CAAC,CAAC;IAK9B,QAAQ,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,GAAG,SAAS,KAAK,IAAI,GAAG;QAAE,WAAW,EAAE,MAAM,IAAI,CAAA;KAAE;CA0B7F"}

package/dist/utils/caches.js

@@ -1,12 +1,28 @@
-import { rateLimited } from "./promises";
+import { DependenciesMap } from "./maps";
+import { filterUndefined } from "./objects";
+import { pending, rateLimited, resolved, runAsynchronously } from "./promises";
 import { AsyncStore } from "./stores";
+/**
+ * Can be used to cache the result of a function call, for example for the `use` hook in React.
+ */
+export function cacheFunction(f) {
+    const dependenciesMap = new DependenciesMap();
+    return ((...args) => {
+        if (dependenciesMap.has(args)) {
+            return dependenciesMap.get(args);
+        }
+        const value = f(...args);
+        dependenciesMap.set(args, value);
+        return value;
+    });
+}
 export class AsyncCache {
     _fetcher;
-    _rateLimitOptions;
-    _map = new Map();
-    constructor(_fetcher, _rateLimitOptions = { concurrency: 1, gapMs: 3_000 }) {
+    _options;
+    _map = new DependenciesMap();
+    constructor(_fetcher, _options = {}) {
         this._fetcher = _fetcher;
-        this._rateLimitOptions = _rateLimitOptions;
+        this._options = _options;
         // nothing here yet
     }
     _createKeyed(functionName) {
@@ -15,57 +31,56 @@ export class AsyncCache {
             return valueCache[functionName].apply(valueCache, args);
         };
     }
-    getValueCache(key) {
-        let cache = this._map.get(key);
+    getValueCache(dependencies) {
+        let cache = this._map.get(dependencies);
         if (!cache) {
-            cache = new AsyncValueCache(async (isFirst) => {
-                return await this._fetcher(key, isFirst);
-            }, this._rateLimitOptions);
-            this._map.set(key, cache);
+            cache = new AsyncValueCache(async () => await this._fetcher(dependencies), {
+                ...this._options,
+                onSubscribe: this._options.onSubscribe ? (cb) => this._options.onSubscribe(dependencies, cb) : undefined,
+            });
+            this._map.set(dependencies, cache);
         }
         return cache;
     }
-    isAvailable = this._createKeyed("isAvailable");
-    setUnavailable = this._createKeyed("setUnavailable");
-    get = this._createKeyed("get");
+    isCacheAvailable = this._createKeyed("isCacheAvailable");
+    getIfCached = this._createKeyed("getIfCached");
     getOrWait = this._createKeyed("getOrWait");
     refresh = this._createKeyed("refresh");
     invalidate = this._createKeyed("invalidate");
     onChange = this._createKeyed("onChange");
-    onceChange = this._createKeyed("onceChange");
 }
-export class AsyncValueCache {
-    _rateLimitOptions;
+class AsyncValueCache {
+    _options;
     _store;
-    _firstFetcher;
-    _laterFetcher;
-    constructor(fetcher, _rateLimitOptions = { concurrency: 1, debounceMs: 3_000 }) {
-        this._rateLimitOptions = _rateLimitOptions;
+    _fetcher;
+    _rateLimitOptions;
+    _subscriptionsCount = 0;
+    _unsubscribers = [];
+    constructor(fetcher, _options = {}) {
+        this._options = _options;
         this._store = new AsyncStore();
-        this._firstFetcher = async () => {
-            return await fetcher(true);
+        this._rateLimitOptions = {
+            concurrency: 1,
+            debounceMs: 300,
+            ...filterUndefined(_options.rateLimiter ?? {}),
         };
-        this._laterFetcher = rateLimited(async () => {
-            return await fetcher(false);
-        }, {
+        this._fetcher = rateLimited(fetcher, {
             ...this._rateLimitOptions,
             batchCalls: true,
         });
-        this._refetch(true).catch(() => {
-            this._store.setRejected(new Error("unavailable"));
-        });
     }
-    isAvailable() {
+    isCacheAvailable() {
         return this._store.isAvailable();
     }
-    setUnavailable() {
-        this._store.setUnavailable();
-    }
-    get() {
+    getIfCached() {
         return this._store.get();
     }
-    getOrWait() {
-        return this._store.getOrWait();
+    getOrWait(cacheStrategy) {
+        const cached = this.getIfCached();
+        if (cacheStrategy === "read-write" && cached.status === "ok") {
+            return resolved(cached.data);
+        }
+        return pending(this._refetch(cacheStrategy === "read-write" ? "write-only" : cacheStrategy));
     }
     _set(value) {
         this._store.set(value);
@@ -73,10 +88,12 @@ export class AsyncValueCache {
     async _setAsync(value) {
         return await this._store.setAsync(value);
     }
-    async _refetch(isFirst) {
+    async _refetch(cacheStrategy) {
         try {
-            const res = isFirst ? this._firstFetcher() : this._laterFetcher();
-            await this._setAsync(res);
+            const res = this._fetcher();
+            if (cacheStrategy === "write-only") {
+                await this._setAsync(res);
+            }
             return await res;
         }
         catch (e) {
@@ -85,16 +102,34 @@ export class AsyncValueCache {
         }
     }
     async refresh() {
-        return await this._refetch(false);
+        return await this.getOrWait("write-only");
     }
     async invalidate() {
-        this.setUnavailable();
-        return await this._refetch(false);
+        this._store.setUnavailable();
+        return await this.refresh();
     }
     onChange(callback) {
-        return this._store.onChange(callback);
-    }
-    onceChange(callback) {
-        return this._store.onceChange(callback);
+        const storeObj = this._store.onChange(callback);
+        if (this._subscriptionsCount++ === 0 && this._options.onSubscribe) {
+            const unsubscribe = this._options.onSubscribe(() => {
+                runAsynchronously(this.refresh());
+            });
+            this._unsubscribers.push(unsubscribe);
+        }
+        runAsynchronously(this.refresh());
+        let hasUnsubscribed = false;
+        return {
+            unsubscribe: () => {
+                if (hasUnsubscribed)
+                    return;
+                hasUnsubscribed = true;
+                storeObj.unsubscribe();
+                if (--this._subscriptionsCount === 0) {
+                    for (const unsubscribe of this._unsubscribers) {
+                        unsubscribe();
+                    }
+                }
+            },
+        };
     }
 }

package/dist/utils/crypto.d.ts

@@ -1 +1,2 @@
 export declare function generateSecureRandomString(minBitsOfEntropy?: number): string;
+//# sourceMappingURL=crypto.d.ts.map

package/dist/utils/crypto.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"crypto.d.ts","sourceRoot":"","sources":["../../src/utils/crypto.tsx"],"names":[],"mappings":"AAEA,wBAAgB,0BAA0B,CAAC,gBAAgB,GAAE,MAAY,UAGxE"}
+{"version":3,"file":"crypto.d.ts","sourceRoot":"","sources":["../../src/utils/crypto.tsx"],"names":[],"mappings":"AAMA,wBAAgB,0BAA0B,CAAC,gBAAgB,GAAE,MAAY,UAGxE"}

package/dist/utils/crypto.js

@@ -1,5 +1,9 @@
 import crypto from "node:crypto";
-export function generateSecureRandomString(minBitsOfEntropy = 196) {
+import { encodeBase32 } from "./bytes";
+const characters = "23456789abcdefghjkmnopqrstuvwxyz";
+if (characters.length !== 32)
+    throw new Error("Invalid characters length");
+export function generateSecureRandomString(minBitsOfEntropy = 224) {
     const randomBytes = crypto.randomBytes(Math.ceil(minBitsOfEntropy / 8));
-    return randomBytes.toString("hex");
+    return encodeBase32(randomBytes).toLowerCase();
 }

package/dist/utils/dates.d.ts

@@ -10,3 +10,4 @@ export declare function fromNowDetailed(date: Date): {
  * Returns a string representation of the given date in the format expected by the `datetime-local` input type.
  */
 export declare function getInputDatetimeLocalString(date: Date): string;
+//# sourceMappingURL=dates.d.ts.map

package/dist/utils/dom.d.ts

@@ -2,3 +2,4 @@
  * https://n2d4.github.io/frontend-starter/guides/advanced-concepts#clickable-parents
  */
 export declare function hasClickableParent(element: HTMLElement): boolean;
+//# sourceMappingURL=dom.d.ts.map

package/dist/utils/env.d.ts

@@ -2,3 +2,4 @@
  * Returns the environment variable with the given name, throwing an error if it's undefined or the empty string.
  */
 export declare function getEnvVariable(name: string): string;
+//# sourceMappingURL=env.d.ts.map

package/dist/utils/errors.d.ts

@@ -182,3 +182,4 @@ export declare class StatusError extends Error {
     isServerError(): boolean;
 }
 export {};
+//# sourceMappingURL=errors.d.ts.map

package/dist/utils/html.d.ts

@@ -1,2 +1,3 @@
 export declare function escapeHtml(unsafe: string): string;
 export declare function html(strings: TemplateStringsArray, ...values: any[]): string;
+//# sourceMappingURL=html.d.ts.map

package/dist/utils/json.d.ts

@@ -8,3 +8,4 @@ export type ReadonlyJson = null | boolean | number | string | readonly ReadonlyJ
 export declare function isJson(value: unknown): value is Json;
 export declare function parseJson(json: string): Result<Json>;
 export declare function stringifyJson(json: Json): Result<string>;
+//# sourceMappingURL=json.d.ts.map

package/dist/utils/jwt.d.ts

@@ -1,3 +1,4 @@
 import * as jose from "jose";
 export declare function encryptJWT(payload: any, expirationTime?: string): Promise<string>;
 export declare function decryptJWT(jwt: string): Promise<jose.JWTPayload>;
+//# sourceMappingURL=jwt.d.ts.map

package/dist/utils/maps.d.ts

@@ -0,0 +1,24 @@
+export declare class MaybeWeakMap<K, V> {
+    private readonly _primitiveMap;
+    private readonly _weakMap;
+    constructor(entries?: readonly (readonly [K, V])[] | null);
+    private _isAllowedInWeakMap;
+    get(key: K): V | undefined;
+    set(key: K, value: V): this;
+    delete(key: K): boolean;
+    has(key: K): boolean;
+    [Symbol.toStringTag]: string;
+}
+export declare class DependenciesMap<K extends any[], V> {
+    private _inner;
+    private _valueToResult;
+    private _unwrapFromInner;
+    private _setInInner;
+    get(dependencies: K): V | undefined;
+    set(dependencies: K, value: V): this;
+    delete(dependencies: K): boolean;
+    has(dependencies: K): boolean;
+    clear(): void;
+    [Symbol.toStringTag]: string;
+}
+//# sourceMappingURL=maps.d.ts.map

package/dist/utils/maps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"maps.d.ts","sourceRoot":"","sources":["../../src/utils/maps.tsx"],"names":[],"mappings":"AAEA,qBAAa,YAAY,CAAC,CAAC,EAAE,CAAC;IAC5B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAY;IAC1C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA0B;gBAEvC,OAAO,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI;IAMzD,OAAO,CAAC,mBAAmB;IAI3B,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,SAAS;IAQ1B,GAAG,CAAC,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI;IAS3B,MAAM,CAAC,GAAG,EAAE,CAAC,GAAG,OAAO;IAQvB,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,OAAO;IAQpB,CAAC,MAAM,CAAC,WAAW,CAAC,SAAkB;CACvC;AAWD,qBAAa,eAAe,CAAC,CAAC,SAAS,GAAG,EAAE,EAAE,CAAC;IAC7C,OAAO,CAAC,MAAM,CAA2F;IAEzG,OAAO,CAAC,cAAc;IAStB,OAAO,CAAC,gBAAgB;IAaxB,OAAO,CAAC,WAAW;IAqBnB,GAAG,CAAC,YAAY,EAAE,CAAC,GAAG,CAAC,GAAG,SAAS;IAInC,GAAG,CAAC,YAAY,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI;IAKpC,MAAM,CAAC,YAAY,EAAE,CAAC,GAAG,OAAO;IAIhC,GAAG,CAAC,YAAY,EAAE,CAAC,GAAG,OAAO;IAI7B,KAAK,IAAI,IAAI;IAIb,CAAC,MAAM,CAAC,WAAW,CAAC,SAAqB;CAC1C"}

package/dist/utils/maps.js

@@ -0,0 +1,110 @@
+import { Result } from "./results";
+export class MaybeWeakMap {
+    _primitiveMap;
+    _weakMap;
+    constructor(entries) {
+        const entriesArray = [...entries ?? []];
+        this._primitiveMap = new Map(entriesArray.filter((e) => !this._isAllowedInWeakMap(e[0])));
+        this._weakMap = new WeakMap(entriesArray.filter((e) => this._isAllowedInWeakMap(e[0])));
+    }
+    _isAllowedInWeakMap(key) {
+        return (typeof key === "object" && key !== null) || (typeof key === "symbol" && Symbol.keyFor(key) === undefined);
+    }
+    get(key) {
+        if (this._isAllowedInWeakMap(key)) {
+            return this._weakMap.get(key);
+        }
+        else {
+            return this._primitiveMap.get(key);
+        }
+    }
+    set(key, value) {
+        if (this._isAllowedInWeakMap(key)) {
+            this._weakMap.set(key, value);
+        }
+        else {
+            this._primitiveMap.set(key, value);
+        }
+        return this;
+    }
+    delete(key) {
+        if (this._isAllowedInWeakMap(key)) {
+            return this._weakMap.delete(key);
+        }
+        else {
+            return this._primitiveMap.delete(key);
+        }
+    }
+    has(key) {
+        if (this._isAllowedInWeakMap(key)) {
+            return this._weakMap.has(key);
+        }
+        else {
+            return this._primitiveMap.has(key);
+        }
+    }
+    [Symbol.toStringTag] = "MaybeWeakMap";
+}
+export class DependenciesMap {
+    _inner = { map: new MaybeWeakMap(), hasValue: false, value: undefined };
+    _valueToResult(inner) {
+        if (inner.hasValue) {
+            return Result.ok(inner.value);
+        }
+        else {
+            return Result.error(undefined);
+        }
+    }
+    _unwrapFromInner(dependencies, inner) {
+        if ((dependencies.length === 0)) {
+            return this._valueToResult(inner);
+        }
+        else {
+            const [key, ...rest] = dependencies;
+            const newInner = inner.map.get(key);
+            if (!newInner) {
+                return Result.error(undefined);
+            }
+            return this._unwrapFromInner(rest, newInner);
+        }
+    }
+    _setInInner(dependencies, value, inner) {
+        if (dependencies.length === 0) {
+            const res = this._valueToResult(inner);
+            if (value.status === "ok") {
+                inner.hasValue = true;
+                inner.value = value.data;
+            }
+            else {
+                inner.hasValue = false;
+                inner.value = undefined;
+            }
+            return res;
+        }
+        else {
+            const [key, ...rest] = dependencies;
+            let newInner = inner.map.get(key);
+            if (!newInner) {
+                inner.map.set(key, newInner = { map: new MaybeWeakMap(), hasValue: false, value: undefined });
+            }
+            return this._setInInner(rest, value, newInner);
+        }
+    }
+    get(dependencies) {
+        return Result.or(this._unwrapFromInner(dependencies, this._inner), undefined);
+    }
+    set(dependencies, value) {
+        this._setInInner(dependencies, Result.ok(value), this._inner);
+        return this;
+    }
+    delete(dependencies) {
+        return this._setInInner(dependencies, Result.error(undefined), this._inner).status === "ok";
+    }
+    has(dependencies) {
+        return this._unwrapFromInner(dependencies, this._inner).status === "ok";
+    }
+    clear() {
+        this._inner = { map: new MaybeWeakMap(), hasValue: false, value: undefined };
+    }
+    [Symbol.toStringTag] = "DependenciesMap";
+}

package/dist/utils/math.d.ts

@@ -2,3 +2,4 @@
  * Similar to the modulo operator, but always returns a positive number (even when the input is negative).
  */
 export declare function remainder(n: number, d: number): number;
+//# sourceMappingURL=math.d.ts.map

package/dist/utils/numbers.d.ts

@@ -1,2 +1,3 @@
 export declare function prettyPrintWithMagnitudes(num: number): string;
 export declare function toFixedMax(num: number, maxDecimals: number): string;
+//# sourceMappingURL=numbers.d.ts.map

package/dist/utils/objects.d.ts

@@ -16,3 +16,4 @@ export declare function typedAssign<T extends {}, U extends {}>(target: T, sourc
 export declare function filterUndefined<T extends {}>(obj: T): {
     [k in keyof T]+?: T[k] & ({} | null);
 };
+//# sourceMappingURL=objects.d.ts.map

package/dist/utils/password.d.ts

@@ -1,2 +1,3 @@
 export declare function hashPassword(password: string): Promise<string>;
 export declare function comparePassword(password: string, hash: string): Promise<boolean>;
+//# sourceMappingURL=password.d.ts.map

package/dist/utils/promises.d.ts

@@ -13,6 +13,7 @@ export declare function resolved<T>(value: T): ReactPromise<T>;
  */
 export declare function rejected<T>(reason: unknown): ReactPromise<T>;
 export declare function neverResolve(): ReactPromise<never>;
+export declare function pending<T>(promise: Promise<T>): ReactPromise<T>;
 export declare function wait(ms: number): Promise<void>;
 export declare function waitUntil(date: Date): Promise<void>;
 export declare function runAsynchronously(promiseOrFunc: Promise<unknown> | (() => Promise<unknown>) | undefined): void;
@@ -47,3 +48,4 @@ export type RateLimitOptions = {
 export declare function rateLimited<T>(func: () => Promise<T>, options: RateLimitOptions): () => Promise<T>;
 export declare function throttled<T, A extends any[]>(func: (...args: A) => Promise<T>, delayMs: number): (...args: A) => Promise<T>;
 export {};
+//# sourceMappingURL=promises.d.ts.map

package/dist/utils/promises.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"promises.d.ts","sourceRoot":"","sources":["../../src/utils/promises.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAEnC,OAAO,KAAK,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,OAAO,CAAC;AAElF,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,GAAG,CACvC,gBAAgB,CAAC,CAAC,CAAC,GACnB,iBAAiB,CAAC,CAAC,CAAC,GACpB,eAAe,CAAC,CAAC,CAAC,CACrB,CAAC;AAEF,KAAK,OAAO,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;AACrC,KAAK,MAAM,GAAG,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;AACxC,wBAAgB,aAAa,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,GAAG,YAAY,CAAC,CAAC,CAAC,CA0BzG;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,CAKrD;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,GAAG,YAAY,CAAC,CAAC,CAAC,CAK5D;AAED,wBAAgB,YAAY,IAAI,YAAY,CAAC,KAAK,CAAC,CAIlD;AAED,wBAAsB,IAAI,CAAC,EAAE,EAAE,MAAM,iBAEpC;AAED,wBAAsB,SAAS,CAAC,IAAI,EAAE,IAAI,iBAEzC;AAED,wBAAgB,iBAAiB,CAAC,aAAa,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC,GAAG,SAAS,GAAG,IAAI,CAa9G;AAGD,cAAM,YAAa,SAAQ,KAAK;aACF,EAAE,EAAE,MAAM;gBAAV,EAAE,EAAE,MAAM;CAIvC;AAED,wBAAsB,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC,CAKlG;AAED,wBAAsB,YAAY,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAEjF;AAGD,MAAM,MAAM,gBAAgB,GAAG;IAC7B;;OAEG;IACH,WAAW,EAAE,CAAC,CAAC;IAEf;;OAEG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,wBAAgB,WAAW,CAAC,CAAC,EAC3B,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACtB,OAAO,EAAE,gBAAgB,GACxB,MAAM,OAAO,CAAC,CAAC,CAAC,CAoDlB;AAED,wBAAgB,SAAS,CAAC,CAAC,EAAE,CAAC,SAAS,GAAG,EAAE,EAAE,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAe3H"}
+{"version":3,"file":"promises.d.ts","sourceRoot":"","sources":["../../src/utils/promises.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAEnC,OAAO,KAAK,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,OAAO,CAAC;AAElF,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,GAAG,CACvC,gBAAgB,CAAC,CAAC,CAAC,GACnB,iBAAiB,CAAC,CAAC,CAAC,GACpB,eAAe,CAAC,CAAC,CAAC,CACrB,CAAC;AAEF,KAAK,OAAO,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;AACrC,KAAK,MAAM,GAAG,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;AACxC,wBAAgB,aAAa,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,GAAG,YAAY,CAAC,CAAC,CAAC,CA0BzG;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,CAKrD;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,GAAG,YAAY,CAAC,CAAC,CAAC,CAK5D;AAED,wBAAgB,YAAY,IAAI,YAAY,CAAC,KAAK,CAAC,CAElD;AAED,wBAAgB,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,CAI/D;AAED,wBAAsB,IAAI,CAAC,EAAE,EAAE,MAAM,iBAEpC;AAED,wBAAsB,SAAS,CAAC,IAAI,EAAE,IAAI,iBAEzC;AAED,wBAAgB,iBAAiB,CAAC,aAAa,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC,GAAG,SAAS,GAAG,IAAI,CAa9G;AAGD,cAAM,YAAa,SAAQ,KAAK;aACF,EAAE,EAAE,MAAM;gBAAV,EAAE,EAAE,MAAM;CAIvC;AAED,wBAAsB,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC,CAKlG;AAED,wBAAsB,YAAY,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAEjF;AAGD,MAAM,MAAM,gBAAgB,GAAG;IAC7B;;OAEG;IACH,WAAW,EAAE,CAAC,CAAC;IAEf;;OAEG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,wBAAgB,WAAW,CAAC,CAAC,EAC3B,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACtB,OAAO,EAAE,gBAAgB,GACxB,MAAM,OAAO,CAAC,CAAC,CAAC,CAoDlB;AAED,wBAAgB,SAAS,CAAC,CAAC,EAAE,CAAC,SAAS,GAAG,EAAE,EAAE,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAe3H"}