shelving 1.67.0 → 1.68.0

package/package.json

@@ -11,7 +11,7 @@
 		"state-management",
 		"query-builder"
 	],
-	"version": "1.67.0",
+	"version": "1.68.0",
 	"repository": "https://github.com/dhoulb/shelving",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"license": "0BSD",

package/provider/MemoryProvider.d.ts

@@ -16,14 +16,14 @@ export declare class MemoryProvider extends Provider implements SynchronousProvi
     /** List of tables in `{ path: Table }` format. */
     private _tables;
     getTable<T extends Data>({ collection }: DocumentReference<T> | QueryReference<T>): MemoryTable<T>;
-    getDocumentTime<T extends Data>(ref: DocumentReference<T>): number | undefined;
+    getDocumentTime<T extends Data>(ref: DocumentReference<T>): number | null;
     getDocument<T extends Data>(ref: DocumentReference<T>): OptionalEntity<T>;
     subscribeDocument<T extends Data>(ref: DocumentReference<T>, observer: PartialObserver<OptionalEntity<T>>): Unsubscribe;
     addDocument<T extends Data>(ref: QueryReference<T>, data: T): string;
     setDocument<T extends Data>(ref: DocumentReference<T>, data: T): void;
     updateDocument<T extends Data>(ref: DocumentReference<T>, update: DataUpdate<T>): void;
     deleteDocument<T extends Data>(ref: DocumentReference<T>): void;
-    getQueryTime<T extends Data>(ref: QueryReference<T>): number | undefined;
+    getQueryTime<T extends Data>(ref: QueryReference<T>): number | null;
     getQuery<T extends Data>(ref: QueryReference<T>): Entities<T>;
     subscribeQuery<T extends Data>(ref: QueryReference<T>, observer: PartialObserver<Entities<T>>): Unsubscribe;
     setQuery<T extends Data>(ref: QueryReference<T>, data: T): number;
@@ -39,17 +39,21 @@ export declare class MemoryTable<T extends Data> extends Subject<void> {
     protected _times: Map<string, number>;
     protected _listeners: Set<Dispatch<[]>>;
     protected _firing: boolean;
-    getDocumentTime(id: string): number | undefined;
+    getDocumentTime(id: string): number | null;
     getDocument(id: string): OptionalEntity<T>;
     subscribeDocument(id: string, observer: PartialObserver<OptionalEntity<T>>): Unsubscribe;
+    /** Subscribe to a query in this table, but only if the query has been explicitly set (and has a time). */
+    subscribeCachedDocument(id: string, observer: PartialObserver<OptionalEntity<T>>): Unsubscribe;
     addDocument(data: T): string;
     setEntity(entity: Entity<T>): void;
     setDocument(id: string, data: T): void;
     updateDocument(id: string, update: DataUpdate<T>): void;
     deleteDocument(id: string): void;
-    getQueryTime(query: Query<Entity<T>>): number | undefined;
+    getQueryTime(query: Query<Entity<T>>): number | null;
     getQuery(query: Query<Entity<T>>): Entities<T>;
     subscribeQuery(query: Query<Entity<T>>, observer: PartialObserver<Entities<T>>): Unsubscribe;
+    /** Subscribe to a query in this table, but only if the query has been explicitly set (and has a time). */
+    subscribeCachedQuery(query: Query<Entity<T>>, observer: PartialObserver<Entities<T>>): Unsubscribe;
     protected _getWrites(query: Query<Entity<T>>): Iterable<Entity<T>>;
     setEntities(query: Query<Entity<T>>, entities: Entities<T>): number;
     setQuery(query: Query<Entity<T>>, data: T): number;

package/provider/MemoryProvider.js

@@ -76,7 +76,7 @@ export class MemoryTable extends Subject {
         this._firing = false;
     }
     getDocumentTime(id) {
-        return this._times.get(id);
+        return this._times.get(id) || null;
     }
     getDocument(id) {
         return this._data.get(id) || null;
@@ -94,6 +94,23 @@ export class MemoryTable extends Subject {
             }
         });
     }
+    /** Subscribe to a query in this table, but only if the query has been explicitly set (and has a time). */
+    subscribeCachedDocument(id, observer) {
+        // Call next() immediately with initial results.
+        let last = this.getDocument(id);
+        if (this._times.has(id))
+            dispatchNext(observer, last);
+        // Call next() every time the collection changes.
+        return this.subscribe(() => {
+            if (this._times.has(id)) {
+                const next = this.getDocument(id);
+                if (next !== last) {
+                    last = next;
+                    dispatchNext(observer, last);
+                }
+            }
+        });
+    }
     addDocument(data) {
         let id = getRandomKey();
         while (this._data.has(id))
@@ -122,7 +139,7 @@ export class MemoryTable extends Subject {
         this.next();
     }
     getQueryTime(query) {
-        return this._times.get(_getQueryReference(query));
+        return this._times.get(_getQueryReference(query)) || null;
     }
     getQuery(query) {
         return getArray(query.transform(this._data.values()));
@@ -140,6 +157,24 @@ export class MemoryTable extends Subject {
             }
         });
     }
+    /** Subscribe to a query in this table, but only if the query has been explicitly set (and has a time). */
+    subscribeCachedQuery(query, observer) {
+        // Call next() immediately with initial results.
+        const ref = _getQueryReference(query);
+        let last = this.getQuery(query);
+        if (this._times.has(ref))
+            dispatchNext(observer, last);
+        // Call next() every time the collection changes.
+        return this.subscribe(() => {
+            if (this._times.has(ref)) {
+                const next = this.getQuery(query);
+                if (next !== last) {
+                    last = next;
+                    dispatchNext(observer, last);
+                }
+            }
+        });
+    }
     _getWrites(query) {
         // Queries that have no limit don't care about sorting either.
         // So sorting can be skipped for performance.
@@ -196,5 +231,5 @@ export class MemoryTable extends Subject {
 }
 function _getQueryReference(query) {
     // Queries that have no limit don't care about sorting either.
-    return query.limit ? `filters=${query.filters.toString()}` : Query.prototype.toString.call(query);
+    return query.limit ? `{${query.filters.toString()}}` : Query.prototype.toString.call(query);
 }

package/provider/ThroughProvider.d.ts

@@ -32,4 +32,4 @@ export interface AsynchronousThroughProvider extends AsynchronousProvider {
     new (source: AsynchronousProvider): AsynchronousProvider;
 }
 /** Find a specific source provider in a database's provider stack. */
-export declare function findSourceProvider<P extends Provider>(provider: Provider, type: Class<P>): P;
+export declare function findSourceProvider<P extends Provider>(provider: Provider, type: Class<P>): P | undefined;

package/provider/ThroughProvider.js

@@ -1,4 +1,3 @@
-import { AssertionError } from "../error/AssertionError.js";
 import { Provider } from "./Provider.js";
 /**
  * Pass all reads and writes through to a source provider.
@@ -48,5 +47,4 @@ export function findSourceProvider(provider, type) {
         return provider;
     if (provider instanceof ThroughProvider)
         return findSourceProvider(provider.source, type);
-    throw new AssertionError(`Source provider ${type.name} not found`, provider);
 }

package/react/useCache.d.ts

@@ -0,0 +1,26 @@
+/// <reference types="react" />
+/**
+ * Controller that creates an independent cache.
+ * - The cache is a `Map` instance that stores indexed items.
+ */
+export declare class CacheController<T> {
+    protected _context: import("react").Context<Map<string, T> | undefined>;
+    /** Use this cache in a component. */
+    readonly useCache: () => Map<string, T>;
+    /** Component that provides a cache of this type to its children. */
+    readonly Cache: ({ children }: {
+        children: React.ReactNode;
+    }) => React.ReactElement | null;
+}
+/**
+ * Default cache
+ * - This is a flexible generic cache intended to be the default.
+ * - Use this cache unless
+ */
+export declare const CACHE: CacheController<any>;
+/** Use a global cache in a component. */
+export declare const useCache: () => Map<string, any>;
+/** Component that provides a global cache to its children. */
+export declare const Cache: ({ children }: {
+    children: React.ReactNode;
+}) => React.ReactElement | null;

package/react/useCache.js

@@ -0,0 +1,36 @@
+import { useContext, createContext, createElement } from "react";
+import { ConditionError } from "../error/ConditionError.js";
+import { useReduce } from "./useReduce.js";
+/**
+ * Controller that creates an independent cache.
+ * - The cache is a `Map` instance that stores indexed items.
+ */
+export class CacheController {
+    constructor() {
+        this._context = createContext(undefined);
+        /** Use this cache in a component. */
+        this.useCache = () => {
+            const cache = useContext(this._context);
+            if (!cache)
+                throw new ConditionError("useCache() must be used inside <Cache>");
+            return cache;
+        };
+        /** Component that provides a cache of this type to its children. */
+        this.Cache = ({ children }) => {
+            const cache = useReduce(_reduceMap);
+            return createElement(this._context.Provider, { children, value: cache });
+        };
+    }
+}
+/** Reducer that gets an existing `Map` instance or creates a new one. */
+const _reduceMap = (previous) => previous || new Map();
+/**
+ * Default cache
+ * - This is a flexible generic cache intended to be the default.
+ * - Use this cache unless
+ */
+export const CACHE = new CacheController(); // eslint-disable-line @typescript-eslint/no-explicit-any
+/** Use a global cache in a component. */
+export const useCache = CACHE.useCache;
+/** Component that provides a global cache to its children. */
+export const Cache = CACHE.Cache;

package/react/useDocument.d.ts

@@ -1,19 +1,12 @@
 import type { Unsubscribe } from "../observe/Observable.js";
 import type { DocumentReference } from "../db/Reference.js";
-import type { Data, OptionalEntity } from "../util/data.js";
-import { Entity } from "../util/data.js";
+import type { Data, OptionalEntity, Entity } from "../util/data.js";
 import { State } from "../state/State.js";
-import { MemoryTable } from "../provider/MemoryProvider.js";
 import { BooleanState } from "../state/BooleanState.js";
 /** Hold the current state of a document. */
 export declare class DocumentState<T extends Data> extends State<OptionalEntity<T>> {
     readonly ref: DocumentReference<T>;
     readonly busy: BooleanState;
-    protected readonly _table: MemoryTable<T>;
-    /** Time this state was last updated with a new value. */
-    get time(): number | undefined;
-    /** How old this state's value is (in milliseconds). */
-    get age(): number;
     /** Get the data of the document (throws `RequiredError` if document doesn't exist). */
     get data(): Entity<T>;
     /** Does the document exist (i.e. its value isn't `null`)? */
@@ -25,14 +18,11 @@ export declare class DocumentState<T extends Data> extends State<OptionalEntity<
     refreshStale(maxAge: number): void;
     /** Subscribe this state to the source provider. */
     connectSource(): Unsubscribe;
+    /** Subscribe this state to any `CacheProvider` that exists in the provider chain. */
+    connectCache(): Unsubscribe | void;
     protected _addFirstObserver(): void;
     protected _removeLastObserver(): void;
 }
-/**
- * Use a document in a React component.
- * - Use `useDocument(ref).data` to get the data of the document.
- * - Use `useDocument(ref).value` to get the data of the document or `null` if it doesn't exist.
- * - Use `useDocument(ref).exists` to check if the document is loaded before accessing `.data` or `.value`
- */
+/** Use a document in a React component. */
 export declare function useDocument<T extends Data>(ref: DocumentReference<T>): DocumentState<T>;
 export declare function useDocument<T extends Data>(ref?: DocumentReference<T>): DocumentState<T> | undefined;

package/react/useDocument.js

@@ -1,16 +1,21 @@
+import { reduceMapItem } from "../util/map.js";
 import { getDocumentData, isSameReference } from "../db/Reference.js";
 import { CacheProvider } from "../provider/CacheProvider.js";
 import { findSourceProvider } from "../provider/ThroughProvider.js";
 import { State } from "../state/State.js";
-import { MatchObserver } from "../observe/MatchObserver.js";
 import { BooleanState } from "../state/BooleanState.js";
 import { ConditionError } from "../error/ConditionError.js";
-import { useReduce } from "./useReduce.js";
+import { NOVALUE } from "../util/constants.js";
 import { useSubscribe } from "./useSubscribe.js";
+import { useCache } from "./useCache.js";
 /** Hold the current state of a document. */
 export class DocumentState extends State {
     constructor(ref) {
-        super();
+        var _a;
+        const table = (_a = findSourceProvider(ref.db.provider, CacheProvider)) === null || _a === void 0 ? void 0 : _a.memory.getTable(ref);
+        const time = table ? table.getDocumentTime(ref.id) : null;
+        const isCached = typeof time === "number";
+        super(table && isCached ? table.getDocument(ref.id) : NOVALUE);
         this.busy = new BooleanState();
         /** Refresh this state from the source provider. */
         this.refresh = async () => {
@@ -30,23 +35,11 @@ export class DocumentState extends State {
                 }
             }
         };
-        this._table = findSourceProvider(ref.db.provider, CacheProvider).memory.getTable(ref);
+        this._time = time;
         this.ref = ref;
-        // If the result is cached use it as the initial value.
-        const isCached = typeof this._table.getDocumentTime(ref.id) === "number";
-        if (isCached)
-            this.next(this._table.getDocument(ref.id)); // Use the existing cached value.
-        else
-            void this.refresh(); // Queue a request to refresh the value.
-    }
-    /** Time this state was last updated with a new value. */
-    get time() {
-        return this._table.getDocumentTime(this.ref.id);
-    }
-    /** How old this state's value is (in milliseconds). */
-    get age() {
-        const time = this.time;
-        return typeof time === "number" ? Date.now() - time : Infinity;
+        // Queue a request to refresh the value if it doesn't exist.
+        if (this.loading)
+            void this.refresh();
     }
     /** Get the data of the document (throws `RequiredError` if document doesn't exist). */
     get data() {
@@ -65,11 +58,15 @@ export class DocumentState extends State {
     connectSource() {
         return this.connect(() => this.ref.subscribe({}));
     }
+    /** Subscribe this state to any `CacheProvider` that exists in the provider chain. */
+    connectCache() {
+        var _a;
+        const table = (_a = findSourceProvider(this.ref.db.provider, CacheProvider)) === null || _a === void 0 ? void 0 : _a.memory.getTable(this.ref);
+        table && this.connect(() => table.subscribeCachedDocument(this.ref.id, this));
+    }
     // Override to subscribe to the cache when an observer is added.
     _addFirstObserver() {
-        // Connect this state to the source.
-        // Connect through a `MatchObserver` that only dispatches `next()` if the document is actually cached (it might just be `null` because no document has been cached yet).
-        this.connect(() => this._table.subscribeDocument(this.ref.id, new MatchObserver(() => this._table.getDocumentTime(this.ref.id) !== undefined, this)));
+        this.connectCache();
     }
     // Override to unsubscribe from the cache when an observer is removed.
     _removeLastObserver() {
@@ -78,9 +75,10 @@ export class DocumentState extends State {
     }
 }
 /** Reuse the previous `DocumentState` or create a new one. */
-const _getDocumentState = (previous, ref) => !ref ? undefined : previous && isSameReference(previous.ref, ref) ? previous : new DocumentState(ref);
+const _reduceDocumentState = (existing, ref) => (existing && isSameReference(existing.ref, ref) ? existing : new DocumentState(ref));
 export function useDocument(ref) {
-    const state = useReduce(_getDocumentState, ref);
+    const cache = useCache();
+    const state = ref ? reduceMapItem(cache, ref.toString(), _reduceDocumentState, ref) : undefined;
     useSubscribe(state);
     return state;
 }

package/react/useQuery.d.ts

@@ -1,20 +1,13 @@
 import type { Unsubscribe } from "../observe/Observable.js";
 import type { QueryReference } from "../db/Reference.js";
-import type { Data, Entities, OptionalEntity } from "../util/data.js";
-import { Entity } from "../util/data.js";
+import type { Data, Entities, OptionalEntity, Entity } from "../util/data.js";
 import { State } from "../state/State.js";
-import { MemoryTable } from "../provider/MemoryProvider.js";
 import { BooleanState } from "../state/BooleanState.js";
 /** Hold the current state of a query. */
 export declare class QueryState<T extends Data> extends State<Entities<T>> {
     readonly ref: QueryReference<T>;
     readonly busy: BooleanState;
     readonly limit: number;
-    protected readonly _table: MemoryTable<T>;
-    /** Time this state was last updated with a new value. */
-    get time(): number | undefined;
-    /** How old this state's value is (in milliseconds). */
-    get age(): number;
     /** Can more items be loaded after the current result. */
     get hasMore(): boolean;
     protected _hasMore: boolean;
@@ -37,6 +30,8 @@ export declare class QueryState<T extends Data> extends State<Entities<T>> {
     refreshStale(maxAge: number): void;
     /** Subscribe this state to the source provider. */
     connectSource(): Unsubscribe;
+    /** Subscribe this state to any `CacheProvider` that exists in the provider chain. */
+    connectCache(): Unsubscribe | void;
     protected _addFirstObserver(): void;
     protected _removeLastObserver(): void;
     /**
@@ -45,11 +40,6 @@ export declare class QueryState<T extends Data> extends State<Entities<T>> {
      */
     readonly loadMore: () => Promise<void>;
 }
-/**
- * Use a query in a React component.
- * - Use `useQuery(ref).data` to get the data of the query.
- * - Use `useQuery(ref).value` to get the data of the query or `null` if it doesn't exist.
- * - Use `useQuery(ref).exists` to check if the query is loaded before accessing `.data` or `.value`
- */
+/** Use a query in a React component. */
 export declare function useQuery<T extends Data>(ref: QueryReference<T>): QueryState<T>;
 export declare function useQuery<T extends Data>(ref?: QueryReference<T>): QueryState<T> | undefined;

package/react/useQuery.js

@@ -1,17 +1,21 @@
+import { reduceMapItem } from "../util/map.js";
 import { getQueryFirstData, getQueryFirstValue, isSameReference } from "../db/Reference.js";
 import { CacheProvider } from "../provider/CacheProvider.js";
 import { findSourceProvider } from "../provider/ThroughProvider.js";
 import { State } from "../state/State.js";
-import { MatchObserver } from "../observe/MatchObserver.js";
 import { ConditionError } from "../error/ConditionError.js";
 import { BooleanState } from "../state/BooleanState.js";
-import { useReduce } from "./useReduce.js";
+import { NOVALUE } from "../util/constants.js";
 import { useSubscribe } from "./useSubscribe.js";
+import { useCache } from "./useCache.js";
 /** Hold the current state of a query. */
 export class QueryState extends State {
     constructor(ref) {
-        var _a;
-        super();
+        var _a, _b;
+        const table = (_a = findSourceProvider(ref.db.provider, CacheProvider)) === null || _a === void 0 ? void 0 : _a.memory.getTable(ref);
+        const time = table ? table.getQueryTime(ref) : null;
+        const isCached = typeof time === "number";
+        super(table && isCached ? table.getQuery(ref) : NOVALUE);
         this.busy = new BooleanState();
         this._hasMore = false;
         /** Refresh this state from the source provider. */
@@ -55,24 +59,12 @@ export class QueryState extends State {
                 }
             }
         };
-        this._table = findSourceProvider(ref.db.provider, CacheProvider).memory.getTable(ref);
+        this._time = time;
         this.ref = ref;
-        this.limit = (_a = ref.limit) !== null && _a !== void 0 ? _a : Infinity;
-        // If the result is cached use it as the initial value.
-        const isCached = typeof this._table.getQueryTime(ref) === "number";
-        if (isCached)
-            this.next(this._table.getQuery(ref)); // Use the existing cached value.
-        else
-            void this.refresh(); // Queue a request to refresh the value.
-    }
-    /** Time this state was last updated with a new value. */
-    get time() {
-        return this._table.getQueryTime(this.ref);
-    }
-    /** How old this state's value is (in milliseconds). */
-    get age() {
-        const time = this.time;
-        return typeof time === "number" ? Date.now() - time : Infinity;
+        this.limit = (_b = ref.limit) !== null && _b !== void 0 ? _b : Infinity;
+        // Queue a request to refresh the value if it doesn't exist.
+        if (this.loading)
+            void this.refresh();
     }
     /** Can more items be loaded after the current result. */
     get hasMore() {
@@ -111,11 +103,15 @@ export class QueryState extends State {
     connectSource() {
         return this.connect(() => this.ref.subscribe({}));
     }
+    /** Subscribe this state to any `CacheProvider` that exists in the provider chain. */
+    connectCache() {
+        var _a;
+        const table = (_a = findSourceProvider(this.ref.db.provider, CacheProvider)) === null || _a === void 0 ? void 0 : _a.memory.getTable(this.ref);
+        return table && this.connect(() => table.subscribeCachedQuery(this.ref, this));
+    }
     // Override to subscribe to the cache when an observer is added.
     _addFirstObserver() {
-        // Connect this state to the source.
-        // Connect through a `MatchObserver` that only dispatches `next()` if the query is actually cached (it might just be `[]` because no query has been cached yet).
-        this.connect(() => this._table.subscribeQuery(this.ref, new MatchObserver(() => this._table.getQueryTime(this.ref) !== undefined, this)));
+        this.connectCache();
     }
     // Override to unsubscribe from the cache when an observer is removed.
     _removeLastObserver() {
@@ -124,9 +120,10 @@ export class QueryState extends State {
     }
 }
 /** Reuse the previous `QueryState` or create a new one. */
-const _getQueryState = (previous, ref) => !ref ? undefined : previous && isSameReference(previous.ref, ref) ? previous : new QueryState(ref);
+const _reduceQueryState = (existing, ref) => (existing && isSameReference(existing.ref, ref) ? existing : new QueryState(ref));
 export function useQuery(ref) {
-    const state = useReduce(_getQueryState, ref);
+    const cache = useCache();
+    const state = ref ? reduceMapItem(cache, ref.toString(), _reduceQueryState, ref) : undefined;
     useSubscribe(state);
     return state;
 }

package/state/State.d.ts

@@ -1,4 +1,4 @@
-import { NOERROR } from "../util/constants.js";
+import { NOVALUE, NOERROR } from "../util/constants.js";
 import { Matchable } from "../util/match.js";
 import { Subject } from "../observe/Subject.js";
 import { Observer } from "../observe/Observer.js";
@@ -20,7 +20,14 @@ export declare class State<T> extends Subject<T> implements Matchable<T, void> {
     /** Most recently dispatched value (or throw `Promise` that resolves to the next value). */
     get value(): T;
     private _value;
+    /** Time this state was last updated with a new value. */
+    get time(): number | null;
+    protected _time: number | null;
+    /** How old this state's value is (in milliseconds). */
+    get age(): number;
     /** State is initiated with an initial state. */
+    constructor(initial: T | typeof NOVALUE);
+    constructor();
     constructor(...args: [] | [T]);
     /** Is there a current value, or is it still loading. */
     get loading(): boolean;

package/state/State.js

@@ -14,12 +14,12 @@ import { dispatchComplete, dispatchError, dispatchNext } from "../observe/Observ
  * - To set the state to an explicit value, use that value or another `State` instance with a value.
  * */
 export class State extends Subject {
-    /** State is initiated with an initial state. */
     constructor(...args) {
         super();
         /** Cached reason this state errored. */
         this.reason = NOERROR;
         this._value = args.length ? args[0] : NOVALUE;
+        this._time = args.length ? Date.now() : null;
     }
     /** Most recently dispatched value (or throw `Promise` that resolves to the next value). */
     get value() {
@@ -29,6 +29,15 @@ export class State extends Subject {
             throw awaitNext(this);
         return this._value;
     }
+    /** Time this state was last updated with a new value. */
+    get time() {
+        return this._time;
+    }
+    /** How old this state's value is (in milliseconds). */
+    get age() {
+        const time = this.time;
+        return time !== null ? Date.now() - time : Infinity;
+    }
     /** Is there a current value, or is it still loading. */
     get loading() {
         return this._value === NOVALUE;
@@ -59,6 +68,7 @@ export class State extends Subject {
     // Override to save value that is dispatched.
     _dispatch(value) {
         this._value = value;
+        this._time = Date.now();
         super._dispatch(value);
     }
     // Implement Matchable to see if a value matches the current value of this state.

package/util/map.d.ts

@@ -1,4 +1,5 @@
 import type { Entry } from "./entry.js";
+import type { Arguments } from "./function.js";
 /**
  * `Map` with string keys that cannot be changed.
  * - Only allows keys to be `string`
@@ -20,3 +21,5 @@ export declare type PossibleMap<T> = ImmutableMap<T> | Iterable<Entry<T>>;
 /** Convert an iterable to a `Map` (if it's already a `Map` it passes through unchanged). */
 export declare function getMap<T>(iterable: ImmutableMap<T> | Iterable<Entry<T>>): ImmutableMap<T>;
 export declare function getMap<T>(iterable: PossibleMap<T>): ImmutableMap<T>;
+/** Function that lets new items in a map be created and updated by calling a `reduce()` callback that receives the existing value. */
+export declare function reduceMapItem<K, T, A extends Arguments = []>(map: Map<K, T>, key: K, reduce: (existing: T | undefined, ...a: A) => T, ...args: A): T;

package/util/map.js

@@ -8,3 +8,11 @@ export function limitMap(map, limit) {
 export function getMap(iterable) {
     return iterable instanceof Map ? iterable : new Map(iterable);
 }
+/** Function that lets new items in a map be created and updated by calling a `reduce()` callback that receives the existing value. */
+export function reduceMapItem(map, key, reduce, ...args) {
+    const existing = map.get(key);
+    const next = reduce(existing, ...args);
+    if (existing !== next)
+        map.set(key, next);
+    return next;
+}