shelving 1.92.1 → 1.93.0

package/db/Database.d.ts

@@ -13,7 +13,7 @@ declare abstract class AbstractDatabase<T extends Datas> {
     /** Create a query on a collection in this database. */
     abstract collection<K extends DataKey<T>>(collection: K): CollectionReference<T[K]> | AsyncCollectionReference<T[K]>;
     /** Create a query on a collection in this database. */
-    abstract query<K extends DataKey<T>>(collection: K, query?: ItemQuery<T>): QueryReference<T[K]> | AsyncQueryReference<T[K]>;
+    abstract query<K extends DataKey<T>>(collection: K, query?: ItemQuery<T[K]>): QueryReference<T[K]> | AsyncQueryReference<T[K]>;
     /** Reference an item in a collection in this database. */
     abstract item<K extends DataKey<T>>(collection: K, id: string): ItemReference<T[K]> | AsyncItemReference<T[K]>;
     /** Run a set of changes in this database. */
@@ -42,7 +42,7 @@ export declare class Database<T extends Datas = Datas> extends AbstractDatabase<
     readonly provider: Provider;
     constructor(provider: Provider);
     collection<K extends DataKey<T>>(collection: K): CollectionReference<T[K]>;
-    query<K extends DataKey<T>>(collection: K, query?: ItemQuery<T>): QueryReference<T[K]>;
+    query<K extends DataKey<T>>(collection: K, query?: ItemQuery<T[K]>): QueryReference<T[K]>;
     item<K extends DataKey<T>>(collection: K, id: string): ItemReference<T[K]>;
     change(...changes: Nullish<WriteChange<Data>>[]): ItemChanges;
     get<K extends DataKey<T>>(collection: K, id: string): ItemValue<T[K]>;
@@ -56,7 +56,7 @@ export declare class AsyncDatabase<T extends Datas = Datas> extends AbstractData
     readonly provider: AsyncProvider;
     constructor(provider: AsyncProvider);
     collection<K extends DataKey<T>>(collection: K): AsyncCollectionReference<T[K]>;
-    query<K extends DataKey<T>>(collection: K, query?: ItemQuery<T>): AsyncQueryReference<T[K]>;
+    query<K extends DataKey<T>>(collection: K, query?: ItemQuery<T[K]>): AsyncQueryReference<T[K]>;
     item<K extends DataKey<T>>(collection: K, id: string): AsyncItemReference<T[K]>;
     change(...changes: Nullish<WriteChange<Data>>[]): Promise<ItemChanges>;
     get<K extends DataKey<T>>(collection: K, id: string): Promise<ItemValue<T[K]>>;

package/db/ItemReference.js

@@ -1,4 +1,4 @@
-import { getData } from "../util/data.js";
+import { getRequired } from "../util/null.js";
 import { runSequence } from "../util/sequence.js";
 /** Get the ID from item data. */
 export const getID = ({ id }) => id;
@@ -53,7 +53,7 @@ export class ItemReference extends AbstractItemReference {
         return this.provider.getItem(this.collection, this.id);
     }
     get data() {
-        return getData(this.value);
+        return getRequired(this.value);
     }
     set(data) {
         return this.provider.setItem(this.collection, this.id, data);
@@ -78,7 +78,7 @@ export class AsyncItemReference extends AbstractItemReference {
         return this.provider.getItem(this.collection, this.id);
     }
     get data() {
-        return this.value.then(getData);
+        return this.value.then(getRequired);
     }
     set(data) {
         return this.provider.setItem(this.collection, this.id, data);

package/db/ItemState.js

@@ -2,13 +2,13 @@ import { CacheProvider } from "../provider/CacheProvider.js";
 import { LazyDeferredSequence } from "../sequence/LazyDeferredSequence.js";
 import { BooleanState } from "../state/BooleanState.js";
 import { State } from "../state/State.js";
-import { getData } from "../util/data.js";
+import { getRequired } from "../util/null.js";
 import { getOptionalSource } from "../util/source.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). */
     get data() {
-        return getData(this.value);
+        return getRequired(this.value);
     }
     /** Does the item exist (i.e. its value isn't `null`)? */
     get exists() {

package/db/QueryReference.js

@@ -1,5 +1,5 @@
 import { countArray, getOptionalFirstItem, getOptionalLastItem, isArrayLength } from "../util/array.js";
-import { getData } from "../util/data.js";
+import { getRequired } from "../util/null.js";
 import { cloneObjectWith } from "../util/object.js";
 import { runSequence } from "../util/sequence.js";
 /** Reference to a set of items in a sync or async provider. */
@@ -47,7 +47,7 @@ export class QueryReference extends AbstractQueryReference {
         return getOptionalLastItem(this.items);
     }
     get data() {
-        return getData(this.first);
+        return getRequired(this.first);
     }
     set(data) {
         return this.provider.setQuery(this.collection, this.query, data);
@@ -81,7 +81,7 @@ export class AsyncQueryReference extends AbstractQueryReference {
         return this.items.then(getOptionalLastItem);
     }
     get data() {
-        return this.first.then(getData);
+        return this.first.then(getRequired);
     }
     set(data) {
         return this.provider.setQuery(this.collection, this.query, data);

package/db/QueryState.js

@@ -3,7 +3,7 @@ import { LazyDeferredSequence } from "../sequence/LazyDeferredSequence.js";
 import { BooleanState } from "../state/BooleanState.js";
 import { State } from "../state/State.js";
 import { getOptionalFirstItem, getOptionalLastItem } from "../util/array.js";
-import { getData } from "../util/data.js";
+import { getRequired } from "../util/null.js";
 import { getAfterQuery, getLimit } from "../util/query.js";
 import { getOptionalSource } from "../util/source.js";
 /** Hold the current state of a query. */
@@ -26,7 +26,7 @@ export class QueryState extends State {
     }
     /** Get the first document matched by this query. */
     get data() {
-        return getData(this.first);
+        return getRequired(this.first);
     }
     /** Does the document have at least one result. */
     get exists() {

package/package.json

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

package/state/DataState.js

@@ -1,4 +1,4 @@
-import { getData } from "../util/data.js";
+import { getRequired } from "../util/null.js";
 import { withProp } from "../util/object.js";
 import { updateData } from "../util/update.js";
 import { State } from "./State.js";
@@ -25,7 +25,7 @@ export class DataState extends State {
 export class OptionalDataState extends State {
     /** Get current data value of this state (or throw `Promise` that resolves to the next required value). */
     get data() {
-        return getData(this.value);
+        return getRequired(this.value);
     }
     /** Does the data exist or not? */
     get exists() {

package/util/data.d.ts

@@ -50,9 +50,10 @@ export declare const isData: <T extends Data>(value: unknown) => value is T;
 /** Assert that an unknown value is a data object. */
 export declare function assertData<T extends Data>(value: T | unknown): asserts value is T;
 /** Is an unknown value the key for an own prop of a data object. */
-export declare const isDataProp: <T extends Data>(obj: T, key: unknown) => key is DataKey<T>;
-/** Get the data of a result (returns data or throws `RequiredError` if value is `null` or `undefined`). */
-export declare function getData<T extends Data>(result: OptionalData<T>): T;
+export declare const isDataProp: <T extends Data>(data: T, key: unknown) => key is DataKey<T>;
+/** Convert a data object or set of `DataProp` props for that object back into the full object. */
+export declare function getData<T extends Data>(input: T): T;
+export declare function getData<T extends Data>(input: T | Iterable<DataProp<T>>): Partial<T>;
 /** Get the props of a data object as a set of entries. */
 export declare function getDataProps<T extends Data>(data: T): ImmutableArray<DataProp<T>>;
 export declare function getDataProps<T extends Data>(data: T | Partial<T>): ImmutableArray<DataProp<T>>;

package/util/data.js

@@ -1,5 +1,5 @@
 import { AssertionError } from "../error/AssertionError.js";
-import { RequiredError } from "../error/RequiredError.js";
+import { isIterable } from "./iterate.js";
 import { isObject, isPlainObject } from "./object.js";
 /** Is an unknown value a data object? */
 export const isData = (value) => isPlainObject(value);
@@ -9,12 +9,9 @@ export function assertData(value) {
         throw new AssertionError("Must be data", value);
 }
 /** Is an unknown value the key for an own prop of a data object. */
-export const isDataProp = (obj, key) => typeof key === "string" && Object.prototype.hasOwnProperty.call(obj, key);
-/** Get the data of a result (returns data or throws `RequiredError` if value is `null` or `undefined`). */
-export function getData(result) {
-    if (!result)
-        throw new RequiredError("Data is required");
-    return result;
+export const isDataProp = (data, key) => typeof key === "string" && Object.prototype.hasOwnProperty.call(data, key);
+export function getData(input) {
+    return isIterable(input) ? Object.fromEntries(input) : input;
 }
 export function getDataProps(data) {
     return Object.entries(data);

package/util/null.d.ts

@@ -18,3 +18,5 @@ export declare const notNullish: <T>(value: Nullish<T>) => value is T;
 export declare function assertNotNullish<T>(value: Nullish<T>): asserts value is T;
 /** Get the not-nullish version of value. */
 export declare function getNotNullish<T>(value: Nullish<T>): T;
+/** Get a required value. */
+export declare function getRequired<T>(value: Nullish<T>): T;

package/util/null.js

@@ -1,4 +1,5 @@
 import { AssertionError } from "../error/AssertionError.js";
+import { RequiredError } from "../error/RequiredError.js";
 /** Function that always returns null. */
 export const getNull = () => null;
 /** Is a value null? */
@@ -29,3 +30,9 @@ export function getNotNullish(value) {
     assertNotNullish(value);
     return value;
 }
+/** Get a required value. */
+export function getRequired(value) {
+    if (isNullish(value))
+        throw new RequiredError("Value is required");
+    return value;
+}

package/util/object.d.ts

@@ -77,6 +77,10 @@ export declare function getKeys<T>(obj: T | Partial<T>): ImmutableArray<Key<T>>;
 export declare function getKeys<T>(obj: T | Partial<T> | Iterable<Key<T>>): Iterable<Key<T>>;
 /** Extract the value of a named prop from an object. */
 export declare function getProp<T, K extends Key<T>>(obj: T, key: K): T[K];
+/** Create an object from a single prop. */
+export declare function fromProp<K extends PropertyKey, V>(key: K, value: V): {
+    readonly [KK in K]: V;
+};
 /** Set a prop on an object (immutably) and return a new object including that prop. */
 export declare function withProp<T extends ImmutableObject, K extends Key<T>>(input: T, key: K, value: T[K]): T;
 /** Set several props on an object (immutably) and return a new object including those props. */

package/util/object.js

@@ -36,6 +36,10 @@ export function getKeys(obj) {
 export function getProp(obj, key) {
     return obj[key];
 }
+/** Create an object from a single prop. */
+export function fromProp(key, value) {
+    return { [key]: value };
+}
 /** Set a prop on an object (immutably) and return a new object including that prop. */
 export function withProp(input, key, value) {
     return input[key] === value ? input : { __proto__: getPrototype(input), ...input, [key]: value };

package/util/query.d.ts

@@ -2,13 +2,13 @@ import type { ImmutableArray } from "./array.js";
 import type { Data, LeafData, LeafKey } from "./data.js";
 /** Query that can be applied to a list of data objects. */
 export type Query<T extends Data> = {
-    readonly [K in LeafKey<T> as K | `${K}` | `!${K}`]?: LeafData<T>[K] | ImmutableArray<LeafData<T>[K]> | undefined;
+    readonly [K in LeafKey<T> as `${K}` | `!${K}`]?: LeafData<T>[K] | ImmutableArray<LeafData<T>[K]> | undefined;
 } & {
     readonly [K in LeafKey<T> as `${K}<` | `${K}<=` | `${K}>` | `${K}>=`]?: LeafData<T>[K] | undefined;
 } & {
     readonly [K in LeafKey<T> as `${K}[]`]?: LeafData<T>[K] extends ImmutableArray<infer X> ? X | undefined : never;
 } & {
-    readonly $order?: LeafKey<T> | `${LeafKey<T>}` | `!${LeafKey<T>}` | ImmutableArray<`${LeafKey<T>}` | `!${LeafKey<T>}`>;
+    readonly $order?: `${LeafKey<T>}` | `!${LeafKey<T>}` | undefined | ImmutableArray<`${LeafKey<T>}` | `!${LeafKey<T>}` | undefined>;
     readonly $limit?: number | undefined;
 };
 /** A single filter that can be applied to a list of data objects. */

package/util/query.js

@@ -22,26 +22,26 @@ export function getFilters(query) {
     return getProps(query).map(_getFilters).filter(isDefined);
 }
 function _getFilters([key, value]) {
-    if (key === "$order" || key === "$limit")
-        return;
-    else if (key.startsWith("!"))
-        return isArray(value) ? { key: key.slice(1), operator: "out", value } : { key: key.slice(1), operator: "not", value };
-    else if (key.endsWith("[]"))
-        return { key: key.slice(0, -2), operator: "contains", value };
-    else if (key.endsWith(">"))
-        return { key: key.slice(0, -1), operator: "gt", value };
-    else if (key.endsWith(">="))
-        return { key: key.slice(0, -2), operator: "gte", value };
-    else if (key.endsWith("<"))
-        return { key: key.slice(0, -1), operator: "lt", value };
-    else if (key.endsWith("<="))
-        return { key: key.slice(0, -2), operator: "lte", value };
-    else
-        return isArray(value) ? { key, operator: "in", value } : { key: key, operator: "is", value };
+    if (key !== "$order" && key !== "$limit" && value !== undefined) {
+        if (key.startsWith("!"))
+            return isArray(value) ? { key: key.slice(1), operator: "out", value } : { key: key.slice(1), operator: "not", value };
+        else if (key.endsWith("[]"))
+            return { key: key.slice(0, -2), operator: "contains", value };
+        else if (key.endsWith(">"))
+            return { key: key.slice(0, -1), operator: "gt", value };
+        else if (key.endsWith(">="))
+            return { key: key.slice(0, -2), operator: "gte", value };
+        else if (key.endsWith("<"))
+            return { key: key.slice(0, -1), operator: "lt", value };
+        else if (key.endsWith("<="))
+            return { key: key.slice(0, -2), operator: "lte", value };
+        else
+            return isArray(value) ? { key, operator: "in", value } : { key: key, operator: "is", value };
+    }
 }
 /** Get the `Order` objects for a query. */
 export function getOrders({ $order }) {
-    return !$order ? [] : isArray($order) ? $order.map(_getOrder) : [_getOrder($order)];
+    return (isArray($order) ? $order : [$order]).filter(isDefined).map(_getOrder);
 }
 function _getOrder(key) {
     if (key.startsWith("!"))

package/util/update.d.ts

@@ -2,11 +2,11 @@ import type { ImmutableArray } from "./array.js";
 import type { BranchData, BranchKey, Data, LeafData, LeafKey } from "./data.js";
 /** Set of named updates for a data object. */
 export type Updates<T extends Data = Data> = {
-    readonly [K in BranchKey<T> as `${K}`]?: BranchData<T>[K];
+    readonly [K in BranchKey<T> as `${K}`]?: BranchData<T>[K] | undefined;
 } & {
-    readonly [K in LeafKey<T> as `=${K}`]?: LeafData<T>[K];
+    readonly [K in LeafKey<T> as `=${K}`]?: LeafData<T>[K] | undefined;
 } & {
-    readonly [K in LeafKey<T> as `+=${K}` | `-=${K}`]?: LeafData<T>[K] extends number ? LeafData<T>[K] : never;
+    readonly [K in LeafKey<T> as `+=${K}` | `-=${K}`]?: LeafData<T>[K] extends number ? LeafData<T>[K] | undefined : never;
 };
 /** A single update to a keyed property in an object. */
 export type Update = {

package/util/update.js

@@ -2,19 +2,22 @@ import { AssertionError } from "../error/AssertionError.js";
 import { reduceItems } from "./iterate.js";
 import { getNumber } from "./number.js";
 import { getProps, isObject } from "./object.js";
+import { isDefined } from "./undefined.js";
 /** Yield the prop updates in an `Updates` object as a set of `Update` objects. */
 export function getUpdates(data) {
-    return getProps(data).map(_getUpdate);
+    return getProps(data).map(_getUpdate).filter(isDefined);
 }
 function _getUpdate([key, value]) {
-    if (key.startsWith("+="))
-        return { action: "sum", key: key.slice(2), value: getNumber(value) };
-    else if (key.startsWith("-="))
-        return { action: "sum", key: key.slice(2), value: 0 - getNumber(value) };
-    else if (key.startsWith("="))
-        return { action: "set", key: key.slice(1), value };
-    else
-        return { action: "set", key, value };
+    if (value !== undefined) {
+        if (key.startsWith("+="))
+            return { action: "sum", key: key.slice(2), value: getNumber(value) };
+        else if (key.startsWith("-="))
+            return { action: "sum", key: key.slice(2), value: 0 - getNumber(value) };
+        else if (key.startsWith("="))
+            return { action: "set", key: key.slice(1), value };
+        else
+            return { action: "set", key, value };
+    }
 }
 /** Update a data object with a set of updates. */
 export function updateData(data, updates) {