shelving 1.110.4 → 1.111.0

package/db/ItemStore.d.ts

@@ -1,7 +1,7 @@
 import type { AbstractProvider } from "./Provider.js";
-import type { StopCallback } from "../util/callback.js";
 import type { DataKey, Database } from "../util/data.js";
 import type { Item, OptionalItem } from "../util/item.js";
+import type { Stop } from "../util/start.js";
 import { BooleanStore } from "../store/BooleanStore.js";
 import { LazyStore } from "../store/LazyStore.js";
 /** Store a single item. */
@@ -23,5 +23,5 @@ export declare class ItemStore<T extends Database, K extends DataKey<T>> extends
     /** Refresh this store if data in the cache is older than `maxAge` (in milliseconds). */
     refreshStale(maxAge: number, provider?: AbstractProvider<T>): void;
     /** Subscribe this store to a provider. */
-    connect(provider?: AbstractProvider<T>): StopCallback;
+    connect(provider?: AbstractProvider<T>): Stop;
 }

package/db/ItemStore.js

@@ -34,7 +34,7 @@ export class ItemStore extends LazyStore {
         this.collection = collection;
         this.id = id;
         // Start loading the value from the provider if it doesn't exist.
-        if (time === null)
+        if (time === undefined)
             this.refresh();
     }
     /** Refresh this store from the source provider. */

package/db/QueryStore.d.ts

@@ -1,7 +1,7 @@
 import type { AbstractProvider } from "./Provider.js";
-import type { StopCallback } from "../util/callback.js";
 import type { DataKey, Database } from "../util/data.js";
 import type { Item, ItemQuery, Items, OptionalItem } from "../util/item.js";
+import type { Stop } from "../util/start.js";
 import { BooleanStore } from "../store/BooleanStore.js";
 import { LazyStore } from "../store/LazyStore.js";
 /** Store a set of multiple items. */
@@ -33,7 +33,7 @@ export declare class QueryStore<T extends Database, K extends DataKey<T>> extend
     /** Refresh this store if data in the cache is older than `maxAge` (in milliseconds). */
     refreshStale(maxAge: number): void;
     /** Subscribe this store to a provider. */
-    connect(provider?: AbstractProvider<T>): StopCallback;
+    connect(provider?: AbstractProvider<T>): Stop;
     /**
      * Load more items after the last once.
      * - Promise that needs to be handled.

package/db/QueryStore.js

@@ -53,7 +53,7 @@ export class QueryStore extends LazyStore {
         this.query = query;
         this.limit = getLimit(query) ?? Infinity;
         // Start loading the value from the provider if it doesn't exist.
-        if (time === null)
+        if (time === undefined)
             this.refresh();
     }
     /** Refresh this store from the source provider. */

package/package.json

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

package/react/index.d.ts

@@ -6,3 +6,4 @@ export * from "./useLazy.js";
 export * from "./useReduce.js";
 export * from "./useSequence.js";
 export * from "./useStore.js";
+export * from "./useMount.js";

package/react/index.js

@@ -6,3 +6,4 @@ export * from "./useLazy.js";
 export * from "./useReduce.js";
 export * from "./useSequence.js";
 export * from "./useStore.js";
+export * from "./useMount.js";

package/react/useMount.d.ts

@@ -0,0 +1,8 @@
+/// <reference types="react" />
+import { type Start } from "../util/start.js";
+/**
+ * Call a `StartCallback` when an element is mounted, and the returned `StopCallback` when it's unmounted again.
+ * - Takes care of state so `start()` won't be called twice for the same element.
+ * - Returns a `RefCallback` which should be set as `ref={ref}` on the target element.
+ */
+export declare function useMount<T extends Element>(start: Start<[T]>): React.RefCallback<T>;

package/react/useMount.js

@@ -0,0 +1,23 @@
+import { useRef } from "react";
+import { Starter } from "../util/start.js";
+/**
+ * Call a `StartCallback` when an element is mounted, and the returned `StopCallback` when it's unmounted again.
+ * - Takes care of state so `start()` won't be called twice for the same element.
+ * - Returns a `RefCallback` which should be set as `ref={ref}` on the target element.
+ */
+export function useMount(start) {
+    const ref = useRef();
+    if (!ref.current) {
+        let current;
+        const starter = new Starter(start);
+        ref.current = (next) => {
+            if (current !== next) {
+                starter.stop();
+                current = next;
+                if (current)
+                    starter.start(current);
+            }
+        };
+    }
+    return ref.current;
+}

package/sequence/LazyDeferredSequence.d.ts

@@ -1,14 +1,11 @@
-import type { StartCallback } from "../util/callback.js";
 import type { Disposable } from "../util/dispose.js";
+import { type Start } from "../util/start.js";
 import { DeferredSequence } from "./DeferredSequence.js";
 /** Deferred sequence of values that calls a `StartCallback` when it has iterators that are iterating, and calls the corresponding `StopCallback` when all iterators have finished. */
 export declare class LazyDeferredSequence<T = void> extends DeferredSequence<T> implements Disposable {
     private _iterating;
-    private _start;
-    private _stop;
-    constructor(start: StartCallback<LazyDeferredSequence<T>>);
+    private _starter;
+    constructor(start: Start<[DeferredSequence<T>]>);
     [Symbol.asyncIterator](): AsyncGenerator<T, void, void>;
-    start(): void;
-    stop(): void;
     [Symbol.dispose](): void;
 }

package/sequence/LazyDeferredSequence.js

@@ -1,39 +1,30 @@
-import { call } from "../util/callback.js";
+import { Starter } from "../util/start.js";
 import { DeferredSequence } from "./DeferredSequence.js";
 import { IteratorSequence } from "./IteratorSequence.js";
 /** Deferred sequence of values that calls a `StartCallback` when it has iterators that are iterating, and calls the corresponding `StopCallback` when all iterators have finished. */
 export class LazyDeferredSequence extends DeferredSequence {
     _iterating = 0;
-    _start;
-    _stop = undefined;
+    _starter;
     constructor(start) {
         super();
-        this._start = start;
+        this._starter = new Starter(start);
     }
     async *[Symbol.asyncIterator]() {
-        this.start();
+        this._starter.start(this);
         this._iterating++;
         try {
             // Delegate to the superclass's async iterator.
-            // Wrap in an `IteratorSequence` because we know the superclass returns `this`
+            // Wrap in an `IteratorSequence` because we know the superclass `AbstractSequence.prototype.[Symbol.asyncIterator]()` simply returns `this`
             // `yield* this` would call this method again and cause an infinite loop.
             yield* new IteratorSequence(super[Symbol.asyncIterator]());
         }
         finally {
             this._iterating--;
-            if (this._iterating < 1 && this._stop)
-                this.stop();
+            if (this._iterating < 1)
+                this._starter.stop();
         }
     }
-    start() {
-        if (!this._stop)
-            this._stop = this._start(this);
-    }
-    stop() {
-        if (this._stop)
-            this._stop = void call(this._stop);
-    }
     [Symbol.dispose]() {
-        this.stop();
+        this._starter[Symbol.dispose]();
     }
 }

package/store/LazyStore.d.ts

@@ -1,17 +1,12 @@
 /// <reference types="node" resolution-mode="require"/>
 import type { NONE } from "../util/constants.js";
-import { type StartCallback } from "../util/callback.js";
+import { type Start } from "../util/start.js";
 import { Store } from "./Store.js";
 /** Store that starts/stops a source subscription when things subscribe to it, and stops when everything has unsubscribed from it. */
 export declare class LazyStore<T> extends Store<T> implements Disposable {
-    constructor(start: StartCallback<Store<T>>, value: T | typeof NONE, time?: number);
-    [Symbol.asyncIterator](): AsyncGenerator<T, void, void>;
     private _iterating;
-    /** Start subscription to `MemoryProvider` if there is one. */
-    start(): void;
-    private _start;
-    /** Stop subscription to `MemoryProvider` if there is one. */
-    stop(): void;
-    private _stop;
+    private readonly _starter;
+    constructor(start: Start<[Store<T>]>, value: T | typeof NONE, time?: number);
+    [Symbol.asyncIterator](): AsyncGenerator<T, void, void>;
     [Symbol.dispose](): void;
 }

package/store/LazyStore.js

@@ -1,14 +1,15 @@
-import { call } from "../util/callback.js";
+import { Starter } from "../util/start.js";
 import { Store } from "./Store.js";
 /** Store that starts/stops a source subscription when things subscribe to it, and stops when everything has unsubscribed from it. */
 export class LazyStore extends Store {
+    _iterating = 0;
+    _starter;
     constructor(start, value, time) {
         super(value, time);
-        this._start = start;
+        this._starter = new Starter(start);
     }
-    // Override to subscribe to start/stop the source subscription when things subscribe to this.
     async *[Symbol.asyncIterator]() {
-        this.start();
+        this._starter.start(this);
         this._iterating++;
         try {
             yield* super[Symbol.asyncIterator]();
@@ -16,24 +17,10 @@ export class LazyStore extends Store {
         finally {
             this._iterating--;
             if (this._iterating < 1)
-                this.stop();
+                this._starter.stop();
         }
     }
-    _iterating = 0;
-    /** Start subscription to `MemoryProvider` if there is one. */
-    start() {
-        if (!this._stop)
-            this._stop = this._start(this);
-    }
-    _start;
-    /** Stop subscription to `MemoryProvider` if there is one. */
-    stop() {
-        if (this._stop)
-            this._stop = void call(this._stop);
-    }
-    _stop = undefined;
-    // Implement `Disposable`
     [Symbol.dispose]() {
-        this.stop();
+        this._starter[Symbol.dispose]();
     }
 }

package/util/async.d.ts

@@ -1,4 +1,5 @@
-import type { ErrorCallback, ValueCallback } from "./callback.js";
+import type { ValueCallback } from "./callback.js";
+import type { Report } from "./error.js";
 /** Is a value an asynchronous value implementing a `then()` function. */
 export declare const isAsync: <T>(value: T | PromiseLike<T>) => value is PromiseLike<T>;
 /** Is a value a synchronous value. */
@@ -23,14 +24,14 @@ export declare abstract class AbstractPromise<T> extends Promise<T> {
     /** Resolve this promise with a value. */
     protected readonly _resolve: ValueCallback<T>;
     /** Reject this promise with a reason. */
-    protected readonly _reject: ErrorCallback;
+    protected readonly _reject: Report;
     constructor();
 }
 /** Deferred allows you to access the internal resolve/reject callbacks of a `Promise` */
 export type Deferred<T> = {
     promise: Promise<T>;
     resolve: ValueCallback<T>;
-    reject: ErrorCallback;
+    reject: Report;
 };
 /**
  * Get a deferred to access the `resolve()` and `reject()` functions of a promise.

package/util/callback.d.ts

@@ -11,12 +11,6 @@ export type AsyncValueCallback<T = void> = (value: T) => void | PromiseLike<void
 export type ValuesCallback<T extends Arguments = []> = (...values: T) => void;
 /** Callback function that receives multiple values and possibly returns a promise that must be handled. */
 export type AsyncValuesCallback<T extends Arguments = []> = (...values: T) => void | PromiseLike<void>;
-/** Callback function that handles an error. */
-export type ErrorCallback = (reason: unknown) => void;
-/** Callback function that starts something (and returns an optional stop callback). */
-export type StartCallback<T> = (value: T) => StopCallback;
-/** Callback function that stops something. */
-export type StopCallback = () => void;
 /** Safely call a callback function (possibly with a value). */
 export declare function call<A extends Arguments = []>(callback: (...v: A) => unknown, ...values: A): void;
 /** Return a callback function that safely calls a callback function (possibly with a value). */

package/util/error.d.ts

@@ -1,3 +1,4 @@
-/** Handle an error by logging it to the console. */
-import type { ErrorCallback } from "./callback.js";
-export declare const logError: ErrorCallback;
+/** Callback function that reports an error. */
+export type Report = (reason: unknown) => void;
+/** Log an error to the console. */
+export declare const logError: Report;

package/util/error.js

@@ -1,2 +1,3 @@
+/** Log an error to the console. */
 // eslint-disable-next-line no-console
 export const logError = reason => console.error(reason);

package/util/index.d.ts

@@ -18,6 +18,7 @@ export * from "./equal.js";
 export * from "./error.js";
 export * from "./focus.js";
 export * from "./function.js";
+export * from "./start.js";
 export * from "./hash.js";
 export * from "./hydrate.js";
 export * from "./item.js";

package/util/index.js

@@ -18,6 +18,7 @@ export * from "./equal.js";
 export * from "./error.js";
 export * from "./focus.js";
 export * from "./function.js";
+export * from "./start.js";
 export * from "./hash.js";
 export * from "./hydrate.js";
 export * from "./item.js";

package/util/sequence.d.ts

@@ -1,4 +1,6 @@
-import type { AsyncValueCallback, ErrorCallback, StopCallback, ValueCallback } from "./callback.js";
+import type { AsyncValueCallback, ValueCallback } from "./callback.js";
+import type { Report } from "./error.js";
+import type { Stop } from "./start.js";
 import { STOP } from "./constants.js";
 /**
  * Is a value an async iterable object?
@@ -15,4 +17,4 @@ export declare function callSequence<T>(sequence: AsyncIterable<T>, callback: As
 /** Get the first value from an async iterator. **/
 export declare function getNextValue<T>(sequence: AsyncIterable<T>): Promise<T>;
 /** Pull values from a sequence until the returned function is called. */
-export declare function runSequence<T>(sequence: AsyncIterable<T>, onNext?: ValueCallback<T>, onError?: ErrorCallback): StopCallback;
+export declare function runSequence<T>(sequence: AsyncIterable<T>, onNext?: ValueCallback<T>, onError?: Report): Stop;

package/util/start.d.ts

@@ -0,0 +1,18 @@
+import type { Disposable } from "./dispose.js";
+import type { Arguments } from "./function.js";
+/** Callback function that starts something with multiple values and returns an optional stop callback. */
+export type Start<T extends Arguments = []> = (...values: T) => Stop | undefined;
+/** Callback function that stops something. */
+export type Stop = () => void;
+/**
+ * Wrapper class to handle state on start/stop callback process.
+ * - If process has already started, `starter.start()` won't be called twice (including if `start()` didn't return a `stop()` callback).
+ */
+export declare class Starter<T extends Arguments = []> implements Disposable {
+    private readonly _start;
+    private _stop;
+    constructor(start: Start<T>);
+    start(...values: T): void;
+    stop(): void;
+    [Symbol.dispose](): void;
+}

package/util/start.js

@@ -0,0 +1,26 @@
+import { call } from "./callback.js";
+/**
+ * Wrapper class to handle state on start/stop callback process.
+ * - If process has already started, `starter.start()` won't be called twice (including if `start()` didn't return a `stop()` callback).
+ */
+export class Starter {
+    _start;
+    _stop = false;
+    constructor(start) {
+        this._start = start;
+    }
+    start(...values) {
+        if (this._stop === false)
+            this._stop = this._start(...values) || true;
+    }
+    stop() {
+        if (this._stop !== false) {
+            if (typeof this._stop === "function")
+                call(this._stop);
+            this._stop = false;
+        }
+    }
+    [Symbol.dispose]() {
+        this.stop();
+    }
+}

package/util/template.d.ts

@@ -10,7 +10,7 @@ type PlaceholderValues = string | ((name: string) => string) | string[] | Templa
  * @param template The template including template placeholders, e.g. `:name-${country}/{city}`
  * @returns Array of clean string names of found placeholders, e.g. `["name", "country", "city"]`
  */
-export declare const getPlaceholders: (template: string) => readonly string[];
+export declare function getPlaceholders(template: string): readonly string[];
 /**
  * Match a template against a target string.
  * - Turn ":year-:month" and "2016-06..." etc into `{ year: "2016"... }`
@@ -34,5 +34,5 @@ export declare function matchTemplates(templates: Iterable<string> & NotString,
  *
  * @throws {ReferenceError} If a placeholder in the template string is not specified in values.
  */
-export declare const renderTemplate: (template: string, value: PlaceholderValues) => string;
+export declare function renderTemplate(template: string, value: PlaceholderValues): string;
 export {};

package/util/template.js

@@ -15,8 +15,10 @@ const TEMPLATE_CACHE = new Map();
  * @param template The template including template placeholders, e.g. `:name-${country}/{city}`
  * @returns Array of strings alternating separator and placeholder.
  */
-const _splitTemplate = (template) => TEMPLATE_CACHE.get(template) || setMapItem(TEMPLATE_CACHE, template, _split(template));
-const _split = (template) => {
+function _splitTemplate(template) {
+    return TEMPLATE_CACHE.get(template) || setMapItem(TEMPLATE_CACHE, template, _split(template));
+}
+function _split(template) {
     const matches = template.split(R_PLACEHOLDERS);
     let asterisks = 0;
     const chunks = [];
@@ -30,15 +32,19 @@ const _split = (template) => {
         chunks.push({ pre, placeholder, name, post });
     }
     return chunks;
-};
+}
 /**
  * Get list of placeholders named in a template string.
  *
  * @param template The template including template placeholders, e.g. `:name-${country}/{city}`
  * @returns Array of clean string names of found placeholders, e.g. `["name", "country", "city"]`
  */
-export const getPlaceholders = (template) => _splitTemplate(template).map(_getPlaceholder);
-const _getPlaceholder = ({ name }) => name;
+export function getPlaceholders(template) {
+    return _splitTemplate(template).map(_getPlaceholder);
+}
+function _getPlaceholder({ name }) {
+    return name;
+}
 /**
  * Match a template against a target string.
  * - Turn ":year-:month" and "2016-06..." etc into `{ year: "2016"... }`
@@ -94,7 +100,7 @@ export function matchTemplates(templates, target) {
  *
  * @throws {ReferenceError} If a placeholder in the template string is not specified in values.
  */
-export const renderTemplate = (template, value) => {
+export function renderTemplate(template, value) {
     const chunks = _splitTemplate(template);
     if (!chunks.length)
         return template;
@@ -102,8 +108,8 @@ export const renderTemplate = (template, value) => {
     for (const { name, placeholder } of chunks)
         output = output.replace(placeholder, _replace(name, value));
     return output;
-};
-const _replace = (name, value) => {
+}
+function _replace(name, value) {
     if (typeof value === "string")
         return value;
     if (typeof value === "function")
@@ -114,4 +120,4 @@ const _replace = (name, value) => {
             return v;
     }
     throw new ReferenceError(`Template "value.${name}" must be defined`);
-};
+}