shelving 1.87.0 → 1.88.0

package/{react/useItem.d.ts → db/ItemState.d.ts}

@@ -1,8 +1,8 @@
-import type { ItemValue, ItemData, AsyncItem, Item } from "../db/Item.js";
-import type { Dispatch } from "../util/function.js";
-import { Datas, DataKey } from "../util/data.js";
+import { DataKey, Datas } from "../util/data.js";
+import { Dispatch } from "../util/function.js";
 import { State } from "../state/State.js";
 import { BooleanState } from "../state/BooleanState.js";
+import { ItemValue, Item, AsyncItem, ItemData } from "./Item.js";
 /** Hold the current state of a item. */
 export declare class ItemState<T extends Datas, K extends DataKey<T> = DataKey<T>> extends State<ItemValue<T[K]>> {
     readonly ref: Item<T, K> | AsyncItem<T, K>;
@@ -20,9 +20,3 @@ export declare class ItemState<T extends Datas, K extends DataKey<T> = DataKey<T
     /** Subscribe this state to the source provider. */
     connectSource(): Dispatch;
 }
-/**
- * Use an item in a React component.
- * - Uses the default cache, so will error if not used inside `<Cache>`
- */
-export declare function useItem<T extends Datas, K extends DataKey<T>>(ref: Item<T, K> | AsyncItem<T, K>): ItemState<T, K>;
-export declare function useItem<T extends Datas, K extends DataKey<T>>(ref?: Item<T, K> | AsyncItem<T, K>): ItemState<T, K> | undefined;

package/{react/useItem.js → db/ItemState.js}

@@ -1,12 +1,9 @@
 import { getData } from "../util/data.js";
-import { getOptionalSource } from "../util/source.js";
-import { setMapItem } from "../util/map.js";
-import { CacheProvider } from "../provider/CacheProvider.js";
 import { State } from "../state/State.js";
 import { BooleanState } from "../state/BooleanState.js";
+import { getOptionalSource } from "../util/source.js";
 import { LazyDeferredSequence } from "../sequence/LazyDeferredSequence.js";
-import { useState } from "./useState.js";
-import { useCache } from "./useCache.js";
+import { CacheProvider } from "../provider/CacheProvider.js";
 /** Hold the current state of a item. */
 export class ItemState extends State {
     /** Get the data of the item (throws `RequiredError` if item doesn't exist). */
@@ -58,9 +55,3 @@ export class ItemState extends State {
         return this.from(this.ref);
     }
 }
-export function useItem(ref) {
-    const cache = useCache();
-    const key = ref === null || ref === void 0 ? void 0 : ref.toString();
-    const state = ref && key ? cache.get(key) || setMapItem(cache, key, new ItemState(ref)) : undefined;
-    return useState(state);
-}

package/{react/useQuery.d.ts → db/QueryState.d.ts}

@@ -41,9 +41,3 @@ export declare class QueryState<T extends Datas, K extends DataKey<T> = DataKey<
     /** Iterate over the items. */
     [Symbol.iterator](): Iterator<ItemData<T[K]>>;
 }
-/**
- * Use a query in a React component.
- * - Uses the default cache, so will error if not used inside `<Cache>`
- */
-export declare function useQuery<T extends Datas, K extends DataKey<T>>(ref: Query<T, K> | AsyncQuery<T, K>): QueryState<T, K>;
-export declare function useQuery<T extends Datas, K extends DataKey<T>>(ref?: Query<T, K> | AsyncQuery<T, K>): QueryState<T, K> | undefined;

package/{react/useQuery.js → db/QueryState.js}

@@ -1,12 +1,9 @@
-import { setMapItem } from "../util/map.js";
 import { getFirstItem, getLastItem, getOptionalFirstItem, getOptionalLastItem } from "../util/array.js";
 import { getOptionalSource } from "../util/source.js";
 import { CacheProvider } from "../provider/CacheProvider.js";
 import { State } from "../state/State.js";
 import { BooleanState } from "../state/BooleanState.js";
 import { LazyDeferredSequence } from "../sequence/LazyDeferredSequence.js";
-import { useState } from "./useState.js";
-import { useCache } from "./useCache.js";
 /** Hold the current state of a query. */
 export class QueryState extends State {
     /** Can more items be loaded after the current result. */
@@ -110,8 +107,3 @@ export class QueryState extends State {
         return this.value.values();
     }
 }
-export function useQuery(ref) {
-    const cache = useCache();
-    const key = ref === null || ref === void 0 ? void 0 : ref.toString();
-    return useState(ref && key ? cache.get(key) || setMapItem(cache, key, new QueryState(ref)) : undefined);
-}

package/db/index.d.ts

@@ -1,5 +1,7 @@
 export * from "./Database.js";
 export * from "./Collection.js";
 export * from "./Item.js";
+export * from "./ItemState.js";
 export * from "./Query.js";
+export * from "./QueryState.js";
 export * from "./Change.js";

package/db/index.js

@@ -1,5 +1,7 @@
 export * from "./Database.js";
 export * from "./Collection.js";
 export * from "./Item.js";
+export * from "./ItemState.js";
 export * from "./Query.js";
+export * from "./QueryState.js";
 export * from "./Change.js";

package/package.json

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

package/react/index.d.ts

@@ -4,5 +4,4 @@ export * from "./useInstance.js";
 export * from "./useCache.js";
 export * from "./useSequence.js";
 export * from "./useState.js";
-export * from "./useItem.js";
-export * from "./useQuery.js";
+export * from "./useData.js";

package/react/index.js

@@ -6,5 +6,4 @@ export * from "./useCache.js";
 // Integration.
 export * from "./useSequence.js";
 export * from "./useState.js";
-export * from "./useItem.js";
-export * from "./useQuery.js";
+export * from "./useData.js";

package/react/useData.d.ts

@@ -0,0 +1,15 @@
+import type { ImmutableArray } from "../util/array.js";
+import { DataKey, Datas } from "../util/data.js";
+import { AsyncItem } from "../db/Item.js";
+import { ItemState } from "../db/ItemState.js";
+import { AsyncQuery } from "../db/Query.js";
+import { QueryState } from "../db/QueryState.js";
+type Reference<T extends Datas, K extends DataKey<T>> = AsyncItem<T, K> | AsyncQuery<T, K>;
+type ReferenceReferenceState<T extends Reference<Datas, string>> = T extends AsyncItem<infer D, infer K> ? ItemState<D, K> : T extends AsyncQuery<infer D, infer K> ? QueryState<D, K> : never;
+/** Use one or more data items or queries. */
+export declare function useData<T extends Reference<Datas, string>>(ref: T): ReferenceReferenceState<T>;
+export declare function useData<T extends Reference<Datas, string>>(ref: T | undefined): ReferenceReferenceState<T> | undefined;
+export declare function useData<T extends ImmutableArray<Reference<Datas, string>>>(...refs: T): {
+    [K in keyof T]: ReferenceReferenceState<T[K]>;
+};
+export {};

package/react/useData.js

@@ -0,0 +1,17 @@
+import { setMapItem } from "../util/map.js";
+import { mapArray } from "../util/transform.js";
+import { AsyncItem } from "../db/Item.js";
+import { ItemState } from "../db/ItemState.js";
+import { QueryState } from "../db/QueryState.js";
+import { useState } from "./useState.js";
+import { useCache } from "./useCache.js";
+export function useData(...refs) {
+    const cache = useCache();
+    const states = mapArray(refs, _getReferenceState, cache);
+    return useState(...states);
+}
+/** Get the corresponding `ItemState` or `QueryState` instance from the cache for a given `Item` or `Query`. */
+function _getReferenceState(ref, cache) {
+    const key = ref === null || ref === void 0 ? void 0 : ref.toString();
+    return ref && key ? cache.get(key) || setMapItem(cache, key, ref instanceof AsyncItem ? new ItemState(ref) : new QueryState(ref)) : undefined;
+}

package/react/useState.d.ts

@@ -1,11 +1,13 @@
-import { AnyState } from "../state/State.js";
+import type { AnyState } from "../state/State.js";
+import { ImmutableArray } from "../util/array.js";
 /**
- * Subscribe to a Shelving `State` instance.
+ * Subscribe to one or more `State` instances.
  *
- * @param state Shelving `State` instance.
- * - Subscription is recreated every time this value changes.
+ * @param state `State` instance.
+ * - Subscription is recreated every time the state instance changes.
  * - Memoise this value to persist the subscription for the lifetime of the component.
  * - If the value is a `State` instance
  */
-export declare function useState<S extends AnyState>(state: S): S;
-export declare function useState<S extends AnyState>(state?: S | undefined): S | undefined;
+export declare function useState<T extends AnyState>(state: T): T;
+export declare function useState<T extends AnyState>(state?: T | undefined): T | undefined;
+export declare function useState<T extends ImmutableArray<AnyState | undefined>>(...states: T): T;

package/react/useState.js

@@ -1,12 +1,20 @@
 import { useEffect, useState as useReactState } from "react";
-import { State } from "../state/State.js";
-import { BLACKHOLE } from "../util/function.js";
-import { runSequence } from "../util/sequence.js";
-export function useState(state) {
-    const setState = useReactState(state && !state.loading ? state.value : State.NOVALUE)[1];
+import { dispatch } from "../util/function.js";
+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(state ? () => runSequence(state.next, setState, setError) : BLACKHOLE, [state]);
+    useEffect(() => {
+        const forceRerender = () => setValue({});
+        const stops = mapArray(states, _startState, forceRerender, setError);
+        return () => stops.filter(isDefined).forEach(dispatch);
+    }, states);
     if (error)
         throw error;
-    return state;
+    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);
 }

package/schema/NumberSchema.d.ts

@@ -17,9 +17,21 @@ export declare class NumberSchema extends Schema<number> {
 }
 /** Valid number, e.g. `2048.12345` or `0` zero. */
 export declare const NUMBER: NumberSchema;
-/** Valid number, e.g. `2048.12345` or `0` zero, or `null` */
+/** Valid optional number, e.g. `2048.12345` or `0` zero, or `null` */
 export declare const OPTIONAL_NUMBER: import("./OptionalSchema.js").OptionalSchema<number>;
 /** Valid integer number, e.g. `2048` or `0` zero. */
 export declare const INTEGER: NumberSchema;
-/** Valid integer number, e.g. `2048` or `0` zero, or `null` */
+/** Valid positive integer number, e.g. `1,2,3` (not including zero). */
+export declare const POSITIVE_INTEGER: NumberSchema;
+/** Valid non-negative integer number, e.g. `0,1,2,3` (including zero). */
+export declare const NON_NEGATIVE_INTEGER: NumberSchema;
+/** Valid negative integer number, e.g. `-1,-2,-3` (not including zero). */
+export declare const NEGATIVE_INTEGER: NumberSchema;
+/** Valid non-positive integer number, e.g. `0,-1,-2,-3` (including zero). */
+export declare const NON_POSITIVE_INTEGER: NumberSchema;
+/** Valid optional integer number, e.g. `2048` or `0` zero, or `null` */
 export declare const OPTIONAL_INTEGER: import("./OptionalSchema.js").OptionalSchema<number>;
+/** Valid Unix timestamp (including milliseconds). */
+export declare const TIMESTAMP: NumberSchema;
+/** Valid Unix timestamp (including milliseconds). */
+export declare const OPTIONAL_TIMESTAMP: import("./OptionalSchema.js").OptionalSchema<number>;

package/schema/NumberSchema.js

@@ -25,9 +25,21 @@ export class NumberSchema extends Schema {
 }
 /** Valid number, e.g. `2048.12345` or `0` zero. */
 export const NUMBER = new NumberSchema({});
-/** Valid number, e.g. `2048.12345` or `0` zero, or `null` */
+/** Valid optional number, e.g. `2048.12345` or `0` zero, or `null` */
 export const OPTIONAL_NUMBER = OPTIONAL(NUMBER);
 /** Valid integer number, e.g. `2048` or `0` zero. */
-export const INTEGER = new NumberSchema({ step: 1, min: Number.MIN_SAFE_INTEGER, max: Number.MAX_SAFE_INTEGER });
-/** Valid integer number, e.g. `2048` or `0` zero, or `null` */
+export const INTEGER = new NumberSchema({ step: 1, min: Number.MIN_SAFE_INTEGER, max: Number.MAX_SAFE_INTEGER, value: 0 });
+/** Valid positive integer number, e.g. `1,2,3` (not including zero). */
+export const POSITIVE_INTEGER = new NumberSchema({ step: 1, min: 1, max: Number.MAX_SAFE_INTEGER, value: 1 });
+/** Valid non-negative integer number, e.g. `0,1,2,3` (including zero). */
+export const NON_NEGATIVE_INTEGER = new NumberSchema({ step: 1, min: 0, max: Number.MAX_SAFE_INTEGER, value: 0 });
+/** Valid negative integer number, e.g. `-1,-2,-3` (not including zero). */
+export const NEGATIVE_INTEGER = new NumberSchema({ step: 1, min: Number.MIN_SAFE_INTEGER, max: -1, value: -1 });
+/** Valid non-positive integer number, e.g. `0,-1,-2,-3` (including zero). */
+export const NON_POSITIVE_INTEGER = new NumberSchema({ step: 1, min: Number.MIN_SAFE_INTEGER, max: 0, value: 0 });
+/** Valid optional integer number, e.g. `2048` or `0` zero, or `null` */
 export const OPTIONAL_INTEGER = OPTIONAL(INTEGER);
+/** Valid Unix timestamp (including milliseconds). */
+export const TIMESTAMP = INTEGER;
+/** Valid Unix timestamp (including milliseconds). */
+export const OPTIONAL_TIMESTAMP = OPTIONAL_INTEGER;

package/util/transform.d.ts

@@ -1,49 +1,54 @@
 import type { ArrayItem, ImmutableArray } from "./array.js";
 import type { Entry } from "./entry.js";
+import { Arguments } from "./function.js";
 import { ImmutableObject, ObjectValue } from "./object.js";
 import { ImmutableDictionary } from "./dictionary.js";
 /** Object that transforms an input value into an output value with its `transform()` method. */
-export interface Transformable<I, O> {
-    transform(input: I): O;
+export interface Transformable<I, O, A extends Arguments = []> {
+    transform(input: I, ...args: A): O;
 }
 /** Object that transforms an input value into an output value with its `transform()` method. */
-export interface AsyncTransformable<I, O> {
-    transform(input: I): O | PromiseLike<O>;
+export interface AsyncTransformable<I, O, A extends Arguments = []> {
+    transform(input: I, ...args: A): O | PromiseLike<O>;
 }
 /** Is an unknown value a transformable. */
-export declare const isTransformable: <T extends Transformable<unknown, unknown>>(value: unknown) => value is T;
+export declare const isTransformable: <T extends Transformable<unknown, unknown, Arguments>>(value: unknown) => value is T;
 /** Function that can transform an input value into an output value. */
-export type Transform<I, O> = (input: I) => O;
+export type Transform<I, O, A extends Arguments = []> = (input: I, ...args: A) => O;
 /** Function that can transform an input value into an output value. */
-export type AsyncTransform<I, O> = (input: I) => O | PromiseLike<O>;
+export type AsyncTransform<I, O, A extends Arguments = []> = (input: I, ...args: A) => O | PromiseLike<O>;
 /** Something that can transform an input value into an output value (or a plain value). */
-export type Transformer<I, O> = Transformable<I, O> | Transform<I, O> | O;
+export type Transformer<I, O, A extends Arguments = []> = Transformable<I, O, A> | Transform<I, O, A> | O;
 /** Something that can transform an input value into an output value (or a plain value). */
-export type AsyncTransformer<I, O> = AsyncTransformable<I, O> | AsyncTransform<I, O> | O;
+export type AsyncTransformer<I, O, A extends Arguments = []> = AsyncTransformable<I, O, A> | AsyncTransform<I, O, A> | O;
 /** Transform a value using a transformer. */
-export declare function transform<I, O>(input: I, transformer: (v: I) => O): O;
-export declare function transform<I, O>(input: I, transformer: (v: I) => O | PromiseLike<O>): O | PromiseLike<O>;
-export declare function transform<I, O>(input: I, transformer: Transformer<I, O>): O;
-export declare function transform<I, O>(input: I, transformer: AsyncTransformer<I, O>): O;
+export declare function transform<I, O, A extends Arguments = []>(input: I, transformer: (v: I) => O, ...args: A): O;
+export declare function transform<I, O, A extends Arguments = []>(input: I, transformer: (v: I) => O | PromiseLike<O>, ...args: A): O | PromiseLike<O>;
+export declare function transform<I, O, A extends Arguments = []>(input: I, transformer: Transformer<I, O, A>, ...args: A): O;
+export declare function transform<I, O, A extends Arguments = []>(input: I, transformer: AsyncTransformer<I, O, A>, ...args: A): O;
 /** Modify a set of items using a transformer. */
-export declare function mapItems<I, O>(items: Iterable<I>, transformer: Transformer<I, O>): Iterable<O>;
+export declare function mapItems<I, O, A extends Arguments = []>(items: Iterable<I>, transformer: (v: I, ...args: A) => O, ...args: A): Iterable<O>;
+export declare function mapItems<I, O, A extends Arguments = []>(items: Iterable<I>, transformer: Transformer<I, O, A>, ...args: A): Iterable<O>;
 /** Modify the items of an array using a transformer. */
 export declare function mapArray<T extends ImmutableArray>(arr: T, transformer: Transformer<ArrayItem<T>, ArrayItem<T>>): T;
-export declare function mapArray<I, O>(arr: Iterable<I>, transformer: Transformer<I, O>): ImmutableArray<O>;
+export declare function mapArray<I, O, A extends Arguments = []>(arr: Iterable<I>, transformer: (v: I, ...args: A) => O, ...args: A): ImmutableArray<O>;
+export declare function mapArray<I, O, A extends Arguments = []>(arr: Iterable<I>, transformer: Transformer<I, O, A>, ...args: A): ImmutableArray<O>;
 /** Modify the values of the props of an object using a transformer. */
 export declare function mapObject<T extends ImmutableObject>(obj: T, transformer: Transformer<ObjectValue<T>, ObjectValue<T>>): T;
-export declare function mapObject<I extends ImmutableObject, O extends ImmutableObject>(obj: I, transformer: Transformer<ObjectValue<I>, ObjectValue<O>>): O;
+export declare function mapObject<I extends ImmutableObject, O extends ImmutableObject, A extends Arguments = []>(obj: I, transformer: (v: ObjectValue<I>, ...args: A) => ObjectValue<O>, ...args: A): O;
+export declare function mapObject<I extends ImmutableObject, O extends ImmutableObject, A extends Arguments = []>(obj: I, transformer: Transformer<ObjectValue<I>, ObjectValue<O>>, ...args: A): O;
 /** Modify the values of a dictionary using a transformer. */
-export declare const mapDictionary: <I, O>(dictionary: ImmutableDictionary<I>, transformer: Transformer<I, O>) => ImmutableDictionary<O>;
+export declare const mapDictionary: <I, O, A extends Arguments = []>(dictionary: ImmutableDictionary<I>, transformer: Transformer<I, O, A>, ...args: A) => ImmutableDictionary<O>;
 /** Modify the values of a set of entries using a transformer. */
-export declare function mapEntries<K, I, O>(entries: Iterable<Entry<K, I>>, transformer: Transformer<I, O>): Iterable<Entry<K, O>>;
+export declare function mapEntries<K, I, O, A extends Arguments = []>(entries: Iterable<Entry<K, I>>, transformer: Transformer<I, O, A>, ...args: A): Iterable<Entry<K, O>>;
 /** Set of named transformers for a data object (or `undefined` to skip the transform). */
-export type Transformers<T extends ImmutableObject> = {
-    readonly [K in keyof T]?: Transformer<T[K], T[K]> | undefined;
+export type Transformers<T extends ImmutableObject, A extends Arguments = []> = {
+    readonly [K in keyof T]?: Transformer<T[K], T[K], A> | undefined;
 };
 /** Transform an object using a set of named transformers. */
-export declare function transformObject<T extends ImmutableObject>(obj: T, transforms: Transformers<T>): T;
+export declare function transformObject<T extends ImmutableObject, A extends Arguments = []>(obj: T, transforms: Transformers<T, A>, ...args: A): T;
 /** Transform a dictionary object using a set of named transformers. */
-export declare const transformDictionary: <T>(dict: ImmutableDictionary<T>, transforms: Transformers<ImmutableDictionary<T>>) => ImmutableDictionary<T>;
+export declare const transformDictionary: <T, A extends Arguments = []>(dict: ImmutableDictionary<T>, transforms: Transformers<ImmutableDictionary<T>, A>, ...args: A) => ImmutableDictionary<T>;
 /** Transform items in a sequence as they are yielded using a (potentially async) transformer. */
-export declare function mapSequence<L, R>(sequence: AsyncIterable<L>, transformer: AsyncTransformer<L, R>): AsyncIterable<R>;
+export declare function mapSequence<I, O, A extends Arguments = []>(sequence: AsyncIterable<I>, transformer: (input: I, ...args: A) => O | PromiseLike<O>, ...args: A): AsyncIterable<O>;
+export declare function mapSequence<I, O, A extends Arguments = []>(sequence: AsyncIterable<I>, transformer: AsyncTransformer<I, O, A>, ...args: A): AsyncIterable<O>;

package/util/transform.js

@@ -2,40 +2,38 @@ import { isFunction } from "./function.js";
 import { getProps, isObject } from "./object.js";
 /** Is an unknown value a transformable. */
 export const isTransformable = (value) => isObject(value) && typeof value.transform === "function";
-export function transform(input, transformer) {
-    return isFunction(transformer) ? transformer(input) : isTransformable(transformer) ? transformer.transform(input) : transformer;
+export function transform(input, transformer, ...args) {
+    return isFunction(transformer) ? transformer(input, ...args) : isTransformable(transformer) ? transformer.transform(input, ...args) : transformer;
 }
-/** Modify a set of items using a transformer. */
-export function* mapItems(items, transformer) {
+export function* mapItems(items, transformer, ...args) {
     for (const item of items)
-        yield transform(item, transformer);
+        yield transform(item, transformer, ...args);
 }
-export function mapArray(arr, transformer) {
-    return Array.from(mapItems(arr, transformer));
+export function mapArray(arr, transformer, ...args) {
+    return Array.from(mapItems(arr, transformer, ...args));
 }
-export function mapObject(obj, transformer) {
-    return Object.fromEntries(mapEntries(getProps(obj), transformer));
+export function mapObject(obj, transformer, ...args) {
+    return Object.fromEntries(mapEntries(getProps(obj), transformer, ...args));
 }
 /** Modify the values of a dictionary using a transformer. */
 export const mapDictionary = mapObject;
 /** Modify the values of a set of entries using a transformer. */
-export function* mapEntries(entries, transformer) {
+export function* mapEntries(entries, transformer, ...args) {
     for (const [k, v] of entries)
-        yield [k, transform(v, transformer)];
+        yield [k, transform(v, transformer, ...args)];
 }
 /** Transform an object using a set of named transformers. */
-export function transformObject(obj, transforms) {
-    return { ...obj, ...Object.fromEntries(_transformObjectProps(obj, transforms)) };
+export function transformObject(obj, transforms, ...args) {
+    return { ...obj, ...Object.fromEntries(_transformObjectProps(obj, transforms, ...args)) };
 }
-function* _transformObjectProps(obj, transforms) {
+function* _transformObjectProps(obj, transforms, ...args) {
     for (const [k, v] of getProps(transforms))
         if (v !== undefined)
-            yield [k, transform(obj[k], v)];
+            yield [k, transform(obj[k], v, ...args)];
 }
 /** Transform a dictionary object using a set of named transformers. */
 export const transformDictionary = transformObject;
-/** Transform items in a sequence as they are yielded using a (potentially async) transformer. */
-export async function* mapSequence(sequence, transformer) {
+export async function* mapSequence(sequence, transformer, ...args) {
     for await (const item of sequence)
-        yield transform(item, transformer);
+        yield transform(item, transformer, ...args);
 }