shelving 1.96.2 → 1.97.0

package/provider/MemoryProvider.js

@@ -2,6 +2,7 @@ import { RequiredError } from "../error/RequiredError.js";
 import { DeferredSequence } from "../sequence/DeferredSequence.js";
 import { getArray } from "../util/array.js";
 import { isArrayEqual } from "../util/equal.js";
+import { filterSequence } from "../util/match.js";
 import { queryItems, queryWritableItems } from "../util/query.js";
 import { getRandomKey } from "../util/random.js";
 import { updateData } from "../util/update.js";
@@ -19,7 +20,7 @@ export class MemoryProvider {
     getTable(collection) {
         return this._tables[collection] || (this._tables[collection] = new MemoryTable());
     }
-    getDocumentTime(collection, id) {
+    getItemTime(collection, id) {
         return this.getTable(collection).getItemTime(id);
     }
     getItem(collection, id) {
@@ -70,57 +71,49 @@ export class MemoryTable {
         this._changed = new DeferredSequence();
     }
     getItemTime(id) {
-        return this._times.get(id) || null;
+        return this._times.get(id);
     }
     getItem(id) {
-        return this._data.get(id) || null;
+        return this._data.get(id);
     }
     async *getItemSequence(id) {
-        let last = this.getItem(id);
-        yield last;
+        let last = this._times.get(id);
+        yield this.getItem(id);
         while (true) {
             await this._changed;
-            const next = this.getItem(id);
-            if (next !== last)
-                yield (last = next);
+            const next = this._times.get(id);
+            if (next !== last) {
+                last = next;
+                yield this.getItem(id);
+            }
         }
     }
     /** Subscribe to a query in this table, but only if the query has been explicitly set (i.e. has a time). */
-    async *getCachedItemSequence(id) {
-        let last = undefined;
-        if (this._times.has(id)) {
-            last = this.getItem(id);
-            yield last;
-        }
-        while (true) {
-            await this._changed;
-            if (this._times.has(id)) {
-                const next = this.getItem(id);
-                if (next !== last)
-                    yield (last = next);
-            }
-        }
+    getCachedItemSequence(id) {
+        return filterSequence(this.getItemSequence(id), () => this._times.has(id));
     }
     addItem(data) {
         let id = getRandomKey();
         while (this._data.has(id))
             id = getRandomKey(); // Regenerate ID until unique.
-        this._data.set(id, { ...data, id });
-        this._times.set(id, Date.now());
-        this._changed.resolve();
+        this.setItemData({ ...data, id });
         return id;
     }
-    _setItemData(item, now = Date.now()) {
+    setItemData(item) {
         const id = item.id;
-        this._data.set(id, item);
-        this._times.set(id, now);
+        if (this._data.get(id) !== item) {
+            this._data.set(id, item);
+            this._times.set(id, Date.now());
+            this._changed.resolve();
+            return true;
+        }
+        return false;
     }
     setItem(id, item) {
-        this._setItemData(item.id === id ? item : { ...item, id });
-        this._changed.resolve();
+        return this.setItemData(item.id === id ? item : { ...item, id });
     }
     setItemValue(id, value) {
-        return value === null ? this.deleteItem(id) : this.setItem(id, value);
+        return value ? this.setItem(id, value) : this.deleteItem(id);
     }
     async *setItemValueSequence(id, sequence) {
         for await (const value of sequence) {
@@ -132,22 +125,19 @@ export class MemoryTable {
         const oldItem = this._data.get(id);
         if (!oldItem)
             throw new RequiredError(`Document "${id}" does not exist`);
-        const newItem = updateData(oldItem, updates);
-        if (oldItem !== newItem) {
-            this._data.set(id, newItem);
-            this._times.set(id, Date.now());
-            this._changed.resolve();
-        }
+        return this.setItemData(updateData(oldItem, updates));
     }
     deleteItem(id) {
         if (this._data.has(id)) {
             this._data.delete(id);
             this._times.set(id, Date.now());
             this._changed.resolve();
+            return true;
         }
+        return false;
     }
     getQueryTime(query) {
-        return this._times.get(_getQueryKey(query)) || null;
+        return this._times.get(_getQueryKey(query)) || undefined;
     }
     getQuery(query) {
         return getArray(queryItems(this._data.values(), query));
@@ -163,99 +153,70 @@ export class MemoryTable {
         }
     }
     /** Subscribe to a query in this table, but only if the query has been explicitly set (i.e. has a time). */
-    async *getCachedQuerySequence(query) {
+    getCachedQuerySequence(query) {
         const key = _getQueryKey(query);
-        let last = undefined;
-        if (this._times.has(key)) {
-            last = this.getQuery(query);
-            yield last;
-        }
-        while (true) {
-            await this._changed;
-            if (this._times.has(key)) {
-                const next = this.getQuery(query);
-                if (!last || !isArrayEqual(last, next))
-                    yield (last = next);
-            }
-        }
+        return filterSequence(this.getQuerySequence(query), () => this._times.has(key));
     }
-    _setItems(items, now = Date.now()) {
+    setItemArray(items) {
+        let count = 0;
         for (const item of items)
-            this._setItemData(item, now);
-    }
-    setItems(items) {
-        this._setItems(items);
-        if (items.length)
-            this._changed.resolve();
+            if (this.setItemData(item))
+                count++;
+        return count;
     }
-    async *setItemsSequence(sequence) {
+    async *setItemArraySequence(sequence) {
         for await (const items of sequence) {
-            this.setItems(items);
+            this.setItemArray(items);
             yield items;
         }
     }
-    setQueryItems(query, items) {
+    setQueryArray(query, items) {
         const key = _getQueryKey(query);
-        const now = Date.now();
-        this._times.set(key, now);
-        this._setItems(items, now);
+        this._times.set(key, Date.now());
+        this.setItemArray(items);
         this._changed.resolve();
     }
-    async *setQueryItemsSequence(query, sequence) {
+    async *setQueryArraySequence(query, sequence) {
         const key = _getQueryKey(query);
         for await (const items of sequence) {
-            const now = Date.now();
-            this._times.set(key, now);
-            this._setItems(items, now);
+            this._times.set(key, Date.now());
+            this.setItemArray(items);
             this._changed.resolve();
             yield items;
         }
     }
     setQuery(query, data) {
-        const now = Date.now();
         let count = 0;
-        for (const { id } of queryWritableItems(this._data.values(), query)) {
-            this._data.set(id, { ...data, id });
-            this._times.set(id, now);
-            count++;
-        }
+        for (const { id } of queryWritableItems(this._data.values(), query))
+            if (this.setItem(id, data))
+                count++;
         if (count) {
             const key = _getQueryKey(query);
-            this._times.set(key, now);
+            this._times.set(key, Date.now());
             this._changed.resolve();
         }
         return count;
     }
     updateQuery(query, updates) {
-        const now = Date.now();
         let count = 0;
-        for (const oldItem of queryWritableItems(this._data.values(), query)) {
-            const newItem = updateData(oldItem, updates);
-            if (oldItem !== newItem) {
-                const id = oldItem.id;
-                this._data.set(id, newItem);
-                this._times.set(id, now);
+        for (const { id } of queryWritableItems(this._data.values(), query))
+            if (this.updateItem(id, updates))
                 count++;
-            }
-        }
         if (count) {
             const key = _getQueryKey(query);
-            this._times.set(key, now);
+            this._times.set(key, Date.now());
             this._changed.resolve();
         }
         return count;
     }
     deleteQuery(query) {
-        const now = Date.now();
         let count = 0;
-        for (const { id } of queryWritableItems(this._data.values(), query)) {
-            this._data.delete(id);
-            this._times.set(id, now);
-            count++;
-        }
+        for (const { id } of queryWritableItems(this._data.values(), query))
+            if (this.deleteItem(id))
+                count++;
         if (count) {
             const key = _getQueryKey(query);
-            this._times.set(key, now);
+            this._times.set(key, Date.now());
             this._changed.resolve();
         }
         return count;

package/provider/ValidationProvider.js

@@ -18,12 +18,12 @@ class BaseValidationProvider {
     async *getItemSequence(collection, id) {
         const schema = this.getSchema(collection);
         for await (const unsafeItem of this.source.getItemSequence(collection, id))
-            yield _validateItem(collection, unsafeItem, schema);
+            yield _validateItemValue(collection, unsafeItem, schema);
     }
     async *getQuerySequence(collection, constraints) {
         const schema = this.getSchema(collection);
         for await (const unsafeItems of this.source.getQuerySequence(collection, constraints))
-            yield _validateItems(collection, unsafeItems, schema);
+            yield _validateItemArray(collection, unsafeItems, schema);
     }
 }
 /** Validate a synchronous source provider (source can have any type because validation guarantees the type). */
@@ -33,7 +33,7 @@ export class ValidationProvider extends BaseValidationProvider {
         this.source = source;
     }
     getItem(collection, id) {
-        return _validateItem(collection, this.source.getItem(collection, id), this.getSchema(collection));
+        return _validateItemValue(collection, this.source.getItem(collection, id), this.getSchema(collection));
     }
     addItem(collection, data) {
         return this.source.addItem(collection, validateWithContext(data, this.getSchema(collection), VALIDATION_CONTEXT_ADD));
@@ -49,7 +49,7 @@ export class ValidationProvider extends BaseValidationProvider {
         return this.source.deleteItem(collection, id);
     }
     getQuery(collection, constraints) {
-        return _validateItems(collection, this.source.getQuery(collection, constraints), this.getSchema(collection));
+        return _validateItemArray(collection, this.source.getQuery(collection, constraints), this.getSchema(collection));
     }
     setQuery(collection, constraints, value) {
         return this.source.setQuery(collection, constraints, validate(value, this.getSchema(collection)));
@@ -69,7 +69,7 @@ export class AsyncValidationProvider extends BaseValidationProvider {
         this.source = source;
     }
     async getItem(collection, id) {
-        return _validateItem(collection, await this.source.getItem(collection, id), this.getSchema(collection));
+        return _validateItemValue(collection, await this.source.getItem(collection, id), this.getSchema(collection));
     }
     addItem(collection, data) {
         return this.source.addItem(collection, validateWithContext(data, this.getSchema(collection), VALIDATION_CONTEXT_ADD));
@@ -85,7 +85,7 @@ export class AsyncValidationProvider extends BaseValidationProvider {
         return this.source.deleteItem(collection, id);
     }
     async getQuery(collection, constraints) {
-        return _validateItems(collection, await this.source.getQuery(collection, constraints), this.getSchema(collection));
+        return _validateItemArray(collection, await this.source.getQuery(collection, constraints), this.getSchema(collection));
     }
     setQuery(collection, constraints, value) {
         return this.source.setQuery(collection, constraints, validateWithContext(value, this.getSchema(collection), VALIDATION_CONTEXT_SET));
@@ -99,9 +99,9 @@ export class AsyncValidationProvider extends BaseValidationProvider {
     }
 }
 /** Validate an entity for a document reference. */
-function _validateItem(collection, unsafeEntity, schema) {
+function _validateItemValue(collection, unsafeEntity, schema) {
     if (!unsafeEntity)
-        return null;
+        return undefined;
     try {
         return validateWithContext(unsafeEntity, schema, VALIDATION_CONTEXT_GET);
     }
@@ -112,10 +112,10 @@ function _validateItem(collection, unsafeEntity, schema) {
     }
 }
 /** Validate a set of entities for this query reference. */
-function _validateItems(collection, unsafeEntities, schema) {
-    return Array.from(_yieldValidItems(collection, unsafeEntities, schema));
+function _validateItemArray(collection, unsafeEntities, schema) {
+    return Array.from(_validateItems(collection, unsafeEntities, schema));
 }
-function* _yieldValidItems(collection, unsafeEntities, schema) {
+function* _validateItems(collection, unsafeEntities, schema) {
     let invalid = false;
     const messages = {};
     for (const unsafeEntity of unsafeEntities) {

package/react/useReduce.js

@@ -1,5 +1,5 @@
 import { useRef } from "react";
 export function useReduce(reduce, ...args) {
-    const r = useRef();
-    return (r.current = reduce(r.current, ...args));
+    const ref = useRef();
+    return (ref.current = reduce(ref.current, ...args));
 }

package/react/useState.js

@@ -4,17 +4,12 @@ import { mapArray } from "../util/transform.js";
 import { isDefined } from "../util/undefined.js";
 export function useState(...states) {
     const setValue = useReactState(undefined)[1];
-    const [error, setError] = useReactState(undefined);
     useEffect(() => {
-        const forceRerender = () => setValue({});
-        const stops = mapArray(states, _startState, forceRerender, setError);
+        const rerender = () => setValue({});
+        const stops = mapArray(states, _startState, rerender);
         return () => stops.filter(isDefined).forEach(dispatch);
     }, states);
-    if (error)
-        throw error;
     return states.length <= 1 ? states[0] : states;
 }
-/** Start a subscription to a `ReferenceState` instance. */
-function _startState(state, setValue, setError) {
-    return state === null || state === void 0 ? void 0 : state.next.to(setValue, setError);
-}
+/** Start a subscription to a `ReferenceState` instance and rerender a new value or error is issued. */
+const _startState = (state, rerender) => state === null || state === void 0 ? void 0 : state.next.to(rerender, rerender);

package/sequence/DeferredSequence.d.ts

@@ -1,4 +1,5 @@
-import type { Dispatch, Handler, Stop } from "../util/function.js";
+import type { Stop } from "../util/activity.js";
+import type { Dispatch, Handler } from "../util/function.js";
 import { AbstractSequence } from "./AbstractSequence.js";
 /**
  * Deferred sequence of values.
@@ -30,5 +31,5 @@ export declare class DeferredSequence<T = void, R = void> extends AbstractSequen
     /** Pull values from a source sequence until the returned stop function is called. */
     from(source: AsyncIterable<T>, onError?: Handler): Stop;
     /** Subscrbe to the value of the sequence with a callback until the returned stop function is called. */
-    to(onNext: Dispatch<[T]>, onError?: Handler): Stop;
+    to(onNext: Dispatch<T>, onError?: Handler): Stop;
 }

package/sequence/DeferredSequence.js

@@ -1,4 +1,4 @@
-import { Deferred } from "../util/async.js";
+import { getDeferred } from "../util/async.js";
 import { runSequence } from "../util/sequence.js";
 import { AbstractSequence } from "./AbstractSequence.js";
 /** Used when the deferred sequence has no value or reason queued. */
@@ -41,7 +41,7 @@ export class DeferredSequence extends AbstractSequence {
     }
     /** Get the next promise to be deferred/rejected. */
     get value() {
-        return (this._deferred || (this._deferred = new Deferred()));
+        return (this._deferred || (this._deferred = getDeferred())).promise;
     }
     // Implement `AsyncIterator`
     async next() {

package/sequence/LazyDeferredSequence.d.ts

@@ -1,9 +1,9 @@
-import type { Start } from "../util/function.js";
+import type { Start } from "../util/activity.js";
 import { DeferredSequence } from "./DeferredSequence.js";
 /** Deferred sequence of values that lazily calls a start function when it has iterators that are iterating, and stops the activity when all iterators are done. */
 export declare class LazyDeferredSequence<T = void, R = void> extends DeferredSequence<T, R> {
     /** Store a list of iterators currently iterating over this iterable. */
     private readonly _iterators;
-    constructor(start: Start<[DeferredSequence<T, R>]>);
+    constructor(start: Start<DeferredSequence<T, R>>);
     [Symbol.asyncIterator](): AsyncGenerator<T, R, void>;
 }

package/state/ArrayState.d.ts

@@ -1,8 +1,9 @@
+import type { StateOptions } from "./State.js";
 import type { ImmutableArray } from "../util/array.js";
 import { State } from "./State.js";
 /** State that stores an array and has additional methods to help with that. */
 export declare class ArrayState<T> extends State<ImmutableArray<T>> implements Iterable<T> {
-    constructor(initial?: ImmutableArray<T>);
+    constructor(options?: StateOptions<ImmutableArray<T>>);
     /** Get the length of the current value of this state. */
     get count(): number;
     /** Add items to this array. */

package/state/ArrayState.js

@@ -2,8 +2,8 @@ import { omitArrayItems, toggleArrayItems, withArrayItems } from "../util/array.
 import { State } from "./State.js";
 /** State that stores an array and has additional methods to help with that. */
 export class ArrayState extends State {
-    constructor(initial = []) {
-        super(initial);
+    constructor(options = {}) {
+        super("value" in options ? options : { value: [], ...options });
     }
     /** Get the length of the current value of this state. */
     get count() {

package/state/BooleanState.d.ts

@@ -1,7 +1,8 @@
+import type { StateOptions } from "./State.js";
 import { State } from "./State.js";
 /** State that stores a boolean and has additional methods to help with that. */
 export declare class BooleanState extends State<boolean> {
-    constructor(initial?: boolean);
+    constructor(options?: StateOptions<boolean>);
     /** Toggle the current boolean value. */
     toggle(): void;
 }

package/state/BooleanState.js

@@ -1,8 +1,8 @@
 import { State } from "./State.js";
 /** State that stores a boolean and has additional methods to help with that. */
 export class BooleanState extends State {
-    constructor(initial = false) {
-        super(initial);
+    constructor(options = {}) {
+        super("value" in options ? options : { ...options, value: false });
     }
     /** Toggle the current boolean value. */
     toggle() {

package/state/DataState.d.ts

@@ -13,7 +13,7 @@ export declare class DataState<T extends Data> extends State<T> {
     setProp<K extends DataKey<T>>(name: K, value: T[K]): void;
 }
 /** State that stores an optional data object and has additional methods to help with that. */
-export declare class OptionalDataState<T extends Data> extends State<T | null> {
+export declare class OptionalDataState<T extends Data> extends State<T | undefined> {
     /** Get current data value of this state (or throw `Promise` that resolves to the next required value). */
     get data(): T;
     /** Does the data exist or not? */
@@ -24,6 +24,6 @@ export declare class OptionalDataState<T extends Data> extends State<T | null> {
     getProp<K extends DataKey<T>>(name: K): T[K];
     /** Update a single named prop in this data. */
     setProp<K extends DataKey<T>>(name: K, value: T[K]): void;
-    /** Set the data to `null`. */
+    /** Set the data to `undefined`. */
     unset(): void;
 }

package/state/DataState.js

@@ -43,8 +43,8 @@ export class OptionalDataState extends State {
     setProp(name, value) {
         this.set(withProp(this.data, name, value));
     }
-    /** Set the data to `null`. */
+    /** Set the data to `undefined`. */
     unset() {
-        this.set(null);
+        this.set(undefined);
     }
 }

package/state/DictionaryState.d.ts

@@ -1,9 +1,10 @@
+import type { StateOptions } from "./State.js";
 import type { DictionaryItem, ImmutableDictionary } from "../util/dictionary.js";
 import type { Updates } from "../util/update.js";
 import { State } from "./State.js";
 /** State that stores a dictionary object and has additional methods to help with that. */
 export declare class DictionaryState<T> extends State<ImmutableDictionary<T>> implements Iterable<DictionaryItem<T>> {
-    constructor(initial?: ImmutableDictionary<T>);
+    constructor(options?: StateOptions<ImmutableDictionary<T>>);
     /** Get the length of the current value of this state. */
     get count(): number;
     /** Set a named entry in this object with a different value. */

package/state/DictionaryState.js

@@ -4,8 +4,8 @@ import { updateData } from "../util/update.js";
 import { State } from "./State.js";
 /** State that stores a dictionary object and has additional methods to help with that. */
 export class DictionaryState extends State {
-    constructor(initial = {}) {
-        super(initial);
+    constructor(options = {}) {
+        super("value" in options ? options : { ...options, value: {} });
     }
     /** Get the length of the current value of this state. */
     get count() {

package/state/State.d.ts

@@ -1,8 +1,15 @@
-import type { Dispatch, Handler, Stop } from "../util/function.js";
+import type { Stop } from "../util/activity.js";
+import type { Dispatch, Handler } from "../util/function.js";
 import type { Validatable } from "../util/validate.js";
 import { DeferredSequence } from "../sequence/DeferredSequence.js";
 /** Any `State` instance. */
 export type AnyState = State<any>;
+/** Options for a `State` instance. */
+export type StateOptions<T> = {
+    value?: T;
+    time?: number | undefined;
+    next?: DeferredSequence<T> | undefined;
+};
 /**
  * Stream that retains its most recent value
  * - Current value can be read at `state.value` and `state.data`
@@ -10,34 +17,37 @@ export type AnyState = State<any>;
  * - States can also be in a loading state where they do not have a current value.
  *
  * @param initial The initial value for the state, a `Promise` that resolves to the initial value, a source `Subscribable` to subscribe to, or another `State` instance to take the initial value from and subscribe to.
- * - To set the state to be loading, use the `State.NOVALUE` constant or a `Promise` value.
+ * - To set the state to be loading, use the `NONE` constant or a `Promise` value.
  * - To set the state to an explicit value, use that value or another `State` instance with a value.
  * */
 export declare class State<T> implements AsyncIterable<T>, Validatable<T> {
-    /** The `NOVALUE` symbol indicates no value has been received by a `State` instance. */
-    static readonly NOVALUE: unique symbol;
     /** Deferred sequence this state uses to issue values as they change. */
     readonly next: DeferredSequence<T>;
-    /** Most recently dispatched value (or throw `Promise` that resolves to the next value). */
+    /** Current value of the state (or throw a promise that resolves when this state receives its next value or error). */
     get value(): T;
     private _value;
     /** Time this state was last updated with a new value. */
-    get time(): number | null;
-    protected _time: number | null;
+    get time(): number | undefined;
+    private _time;
+    /** Is there a current value, or is it still loading. */
+    get loading(): boolean;
     /** How old this state's value is (in milliseconds). */
     get age(): number;
+    /** Current error of this state (or `undefined` if there is no reason). */
+    get reason(): unknown;
+    private _reason;
     /** State is initiated with an initial state. */
-    constructor(initial?: T | typeof State.NOVALUE, next?: DeferredSequence<T>);
-    /** Is there a current value, or is it still loading. */
-    get loading(): boolean;
+    constructor(options?: StateOptions<T>);
     /** Set the value of the state. */
     set(next: T): void;
+    /** Set the error reason of the state (will be  */
+    error(reason: unknown): void;
     /** Set the value of the state as values are pulled from a sequence. */
     through(sequence: AsyncIterable<T>): AsyncIterable<T>;
     /** Pull values from a source sequence until the returned stop function is called. */
     from(source: AsyncIterable<T>, onError?: Handler): Stop;
     /** Push values to another state or callback to this state until the returned stop function is called. */
-    to(target: Dispatch<[T]>, onError?: Handler): Stop;
+    to(target: Dispatch<T>, onError?: Handler): Stop;
     [Symbol.asyncIterator](): AsyncIterator<T>;
     /** Validate data set on this state. */
     validate(value: T): T;