shelving 1.92.0 → 1.92.2

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/firestore/client/FirestoreClientProvider.js

@@ -1,7 +1,7 @@
 import { addDoc, collection, deleteDoc, doc, documentId, getDoc, getDocs, increment, limit, onSnapshot, orderBy, query, setDoc, updateDoc, where } from "firebase/firestore";
 import { LazyDeferredSequence } from "../../sequence/LazyDeferredSequence.js";
 import { getObject } from "../../util/object.js";
-import { getFilters, getSorts } from "../../util/query.js";
+import { getFilters, getLimit, getOrders } from "../../util/query.js";
 import { mapItems } from "../../util/transform.js";
 import { getUpdates } from "../../util/update.js";
 // Constants.
@@ -23,16 +23,13 @@ function _getQuery(firestore, c, q) {
     return query(collection(firestore, c), ..._getConstraints(q));
 }
 function* _getConstraints(q) {
-    for (const { keys, direction } of getSorts(q)) {
-        const key = keys.join(".");
+    for (const { key, direction } of getOrders(q))
         yield orderBy(key === "id" ? ID : key, direction);
-    }
-    for (const { keys, operator, value } of getFilters(q)) {
-        const key = keys.join(".");
+    for (const { key, operator, value } of getFilters(q))
         yield where(key === "id" ? ID : key, OPERATORS[operator], value);
-    }
-    if (typeof q.$limit === "number")
-        yield limit(q.$limit);
+    const l = getLimit(q);
+    if (typeof l === "number")
+        yield limit(l);
 }
 function _getItems(snapshot) {
     return snapshot.docs.map(_getItemData);
@@ -47,7 +44,7 @@ function _getItemValue(snapshot) {
 }
 /** Convert `Updates` object into corresponding Firestore `FieldValue` instances. */
 const _getFieldValues = (updates) => getObject(mapItems(getUpdates(updates), _getFieldValue));
-const _getFieldValue = ({ keys, action, value }) => [keys.join("."), action === "sum" ? increment(value) : action === "set" ? value : action];
+const _getFieldValue = ({ key, action, value }) => [key, action === "sum" ? increment(value) : action === "set" ? value : action];
 /**
  * Firestore client database provider.
  * - Works with the Firebase JS SDK.

package/firestore/lite/FirestoreLiteProvider.js

@@ -1,7 +1,7 @@
 import { addDoc, collection, deleteDoc, doc, documentId, getDoc, getDocs, increment, limit, orderBy, query, setDoc, updateDoc, where } from "firebase/firestore/lite";
 import { UnsupportedError } from "../../error/UnsupportedError.js";
 import { getObject } from "../../util/object.js";
-import { getFilters, getSorts } from "../../util/query.js";
+import { getFilters, getLimit, getOrders } from "../../util/query.js";
 import { mapItems } from "../../util/transform.js";
 import { getUpdates } from "../../util/update.js";
 // Constants.
@@ -23,16 +23,13 @@ function _getQuery(firestore, c, q) {
     return query(collection(firestore, c), ..._getConstraints(q));
 }
 function* _getConstraints(q) {
-    for (const { keys, direction } of getSorts(q)) {
-        const key = keys.join(".");
+    for (const { key, direction } of getOrders(q))
         yield orderBy(key === "id" ? ID : key, direction);
-    }
-    for (const { keys, operator, value } of getFilters(q)) {
-        const key = keys.join(".");
+    for (const { key, operator, value } of getFilters(q))
         yield where(key === "id" ? ID : key, OPERATORS[operator], value);
-    }
-    if (typeof q.$limit === "number")
-        yield limit(q.$limit);
+    const l = getLimit(q);
+    if (typeof l === "number")
+        yield limit(l);
 }
 function _getItemData(snapshot) {
     const data = snapshot.data();
@@ -44,7 +41,7 @@ function _getItemValue(snapshot) {
 }
 /** Convert `Updates` object into corresponding Firestore `FieldValue` instances. */
 const _getFieldValues = (updates) => getObject(mapItems(getUpdates(updates), _getFieldValue));
-const _getFieldValue = ({ keys, action, value }) => [keys.join("."), action === "sum" ? increment(value) : action === "set" ? value : action];
+const _getFieldValue = ({ key, action, value }) => [key, action === "sum" ? increment(value) : action === "set" ? value : action];
 /**
  * Firestore Lite client database provider.
  * - Works with the Firebase JS SDK.

package/firestore/server/FirestoreServerProvider.js

@@ -1,7 +1,7 @@
 import { FieldPath, FieldValue, Firestore } from "@google-cloud/firestore";
 import { LazyDeferredSequence } from "../../sequence/LazyDeferredSequence.js";
 import { getObject } from "../../util/object.js";
-import { getFilters, getSorts } from "../../util/query.js";
+import { getFilters, getLimit, getOrders } from "../../util/query.js";
 import { mapItems } from "../../util/transform.js";
 import { getUpdates } from "../../util/update.js";
 // Constants.
@@ -21,16 +21,13 @@ const OPERATORS = {
 /** Create a corresponding `QueryReference` from a Query. */
 function _getQuery(firestore, c, q) {
     let query = firestore.collection(c);
-    for (const { keys, direction } of getSorts(q)) {
-        const key = keys.join(".");
+    for (const { key, direction } of getOrders(q))
         query = query.orderBy(key === "id" ? ID : key, direction);
-    }
-    for (const { keys, operator, value } of getFilters(q)) {
-        const key = keys.join(".");
+    for (const { key, operator, value } of getFilters(q))
         query = query.where(key === "id" ? ID : key, OPERATORS[operator], value);
-    }
-    if (typeof q.$limit === "number")
-        query = query.limit(q.$limit);
+    const l = getLimit(q);
+    if (typeof l === "number")
+        query = query.limit(l);
     return query;
 }
 function _getItemArray(snapshot) {
@@ -46,7 +43,7 @@ function _getItemValue(snapshot) {
 }
 /** Convert `Update` instances into corresponding Firestore `FieldValue` instances. */
 const _getFieldValues = (updates) => getObject(mapItems(getUpdates(updates), _getFieldValue));
-const _getFieldValue = ({ keys, action, value }) => [keys.join("."), action === "sum" ? FieldValue.increment(value) : action === "set" ? value : action];
+const _getFieldValue = ({ key, action, value }) => [key, action === "sum" ? FieldValue.increment(value) : action === "set" ? value : action];
 /**
  * Firestore server database provider.
  * - Works with the Firebase Admin SDK for Node.JS

package/package.json

@@ -11,7 +11,7 @@
 		"state-management",
 		"query-builder"
 	],
-	"version": "1.92.0",
+	"version": "1.92.2",
 	"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

@@ -1,5 +1,6 @@
 import type { ImmutableArray } from "./array.js";
 import type { EntryObject } from "./entry.js";
+import type { DeepPartial } from "./object.js";
 /** Data object. */
 export type Data = {
     readonly [K in string]: unknown;
@@ -18,30 +19,51 @@ export type OptionalData<T extends Data> = T | null;
 export type Datas = {
     readonly [K in string]: Data;
 };
-/** Flattened data object with deep keys flattened into `a.c.b` format. */
-export type FlatData<T extends Data> = EntryObject<FlatDataProp<T>>;
+/**
+ * Flattened data object with every branch node of the data, flattened into `a.c.b` format.
+ * - Includes all branches, i.e. `{ a: { a2: number } }` will be `{ "a": object, "a.a2": number }`
+ */
+export type BranchData<T extends Data> = EntryObject<BranchProp<T>>;
 /** Key for a flattened data object with deep keys flattened into `a.c.b` format. */
-export type FlatDataKey<T extends Data> = FlatDataProp<T>[0];
+export type BranchKey<T extends Data> = BranchProp<T>[0];
 /** Value for a flattened data object with deep keys flattened into `a.c.b` format. */
-export type FlatDataValue<T extends Data> = FlatDataProp<T>[1];
+export type BranchValue<T extends Data> = BranchProp<T>[1];
 /** Prop for a flattened data object with deep keys flattened into `a.c.b` format. */
-export type FlatDataProp<T extends Data> = {
-    readonly [K in DataKey<T>]: (T[K] extends Data ? FlatDataProp<T[K]> : readonly [null, T[K]]) extends infer E ? E extends readonly [infer KK, infer VV] ? readonly [KK extends string ? `${K}.${KK}` : K, VV] : never : never;
+export type BranchProp<T extends Data> = {
+    readonly [K in DataKey<T>]: (T[K] extends Data ? readonly [null, T[K]] | BranchProp<T[K]> : readonly [null, T[K]]) extends infer E ? E extends readonly [infer KK, infer VV] ? readonly [KK extends string ? `${K}.${KK}` : K, VV] : never : never;
+}[DataKey<T>];
+/**
+ * Flattened data object with only leaf nodes of the data, flattened into `a.c.b` format.
+ * - Only include leaf nodes, i.e. `{ a: { a2: number } }` will be `{ "a.a2": number }`
+ */
+export type LeafData<T extends Data> = EntryObject<LeafProp<T>>;
+/** Key for a flattened data object with deep keys flattened into `a.c.b` format. */
+export type LeafKey<T extends Data> = LeafProp<T>[0];
+/** Value for a flattened data object with deep keys flattened into `a.c.b` format. */
+export type LeafValue<T extends Data> = LeafProp<T>[1];
+/** Prop for a flattened data object with deep keys flattened into `a.c.b` format. */
+export type LeafProp<T extends Data> = {
+    readonly [K in DataKey<T>]: (T[K] extends Data ? LeafProp<T[K]> : readonly [null, T[K]]) extends infer E ? E extends readonly [infer KK, infer VV] ? readonly [KK extends string ? `${K}.${KK}` : K, VV] : never : never;
 }[DataKey<T>];
 /** Is an unknown value a data object? */
 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>>;
 /** Get the props of a data object as a set of entries. */
 export declare function getDataKeys<T extends Data>(data: T): ImmutableArray<DataKey<T>>;
 export declare function getDataKeys<T extends Data>(data: T | Partial<T>): ImmutableArray<DataKey<T>>;
+/** Get a (possibly deep) prop from a data object. */
+export declare function getDataProp<T extends Data, K extends BranchKey<T>>(data: T, key: K): BranchData<T>[K];
+export declare function getDataProp<T extends Data, K extends BranchKey<T>>(data: DeepPartial<T>, key: K): BranchData<T>[K] | undefined;
+export declare function getDataProp(data: Data, key: string): unknown;
 /** Type that represents an empty data object. */
 export type EmptyData = {
     readonly [K in never]: never;

package/util/data.js

@@ -1,6 +1,6 @@
 import { AssertionError } from "../error/AssertionError.js";
-import { RequiredError } from "../error/RequiredError.js";
-import { isPlainObject } from "./object.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);
 /** Assert that an unknown value is a data object. */
@@ -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);
@@ -22,6 +19,15 @@ export function getDataProps(data) {
 export function getDataKeys(data) {
     return Object.keys(data);
 }
+export function getDataProp(data, key) {
+    let current = data;
+    for (const k of key.split(".")) {
+        if (!isObject(current))
+            return undefined;
+        current = current[k];
+    }
+    return current;
+}
 /** An empty object. */
 export const EMPTY_DATA = { __proto__: null };
 /** Function that returns an an empty object. */

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

@@ -8,23 +8,23 @@ export type MutableObject<K extends PropertyKey = PropertyKey, T = unknown> = {
     [KK in K]: T;
 };
 /** Prop for an object. */
-export type ObjectProp<T extends ImmutableObject = ImmutableObject> = readonly [keyof T, T[keyof T]];
+export type Prop<T> = readonly [keyof T, T[keyof T]];
 /** Key for an object prop. */
-export type ObjectKey<T extends ImmutableObject = ImmutableObject> = keyof T;
+export type Key<T> = keyof T;
 /** Value for an object prop. */
-export type ObjectValue<T extends ImmutableObject = ImmutableObject> = T[keyof T];
+export type Value<T> = T[keyof T];
 /** Something that can be converted to an object. */
-export type PossibleObject<T extends ImmutableObject> = T | Iterable<ObjectProp<T>>;
+export type PossibleObject<T> = T | Iterable<Prop<T>>;
 /** Is an unknown value an unknown object? */
 export declare const isObject: <T extends ImmutableObject<PropertyKey, unknown>>(value: unknown) => value is T;
 /** Assert that a value is an object */
 export declare function assertObject<T extends ImmutableObject>(value: T | unknown): asserts value is T;
 /** is an unknown value an unknown plain object? */
-export declare function isPlainObject(value: ImmutableObject | unknown): value is ImmutableObject;
+export declare function isPlainObject<T extends ImmutableObject>(value: T | unknown): value is T;
 /** Assert that a value is an object */
-export declare function assertPlainObject(value: ImmutableObject | unknown): asserts value is ImmutableObject;
+export declare function assertPlainObject<T extends ImmutableObject>(value: T | unknown): asserts value is T;
 /** Is an unknown value the key for an own prop of an object. */
-export declare const isProp: <T extends ImmutableObject<PropertyKey, unknown>>(obj: T, key: unknown) => key is keyof T;
+export declare const isProp: <T>(obj: T, key: PropertyKey) => key is keyof T;
 /** turn a possible object into an object. */
 export declare function getObject<T extends ImmutableObject>(obj: PossibleObject<T>): T;
 /**
@@ -68,43 +68,30 @@ export type OmitProps<T, TT> = Omit<T, {
     [K in keyof T]: T[K] extends TT ? K : never;
 }[keyof T]>;
 /** Get the props of an object as a set of entries. */
-export declare function getProps<T extends ImmutableObject>(obj: T): ImmutableArray<ObjectProp<T>>;
-export declare function getProps<T extends ImmutableObject>(obj: T | Partial<T>): ImmutableArray<ObjectProp<T>>;
-export declare function getProps<T extends ImmutableObject>(obj: T | Partial<T> | Iterable<ObjectProp<T>>): Iterable<ObjectProp<T>>;
+export declare function getProps<T>(obj: T): ImmutableArray<Prop<T>>;
+export declare function getProps<T>(obj: T | Partial<T>): ImmutableArray<Prop<T>>;
+export declare function getProps<T>(obj: T | Partial<T> | Iterable<Prop<T>>): Iterable<Prop<T>>;
 /** Get the keys of an object as an array. */
-export declare function getKeys<T extends ImmutableObject>(obj: T): ImmutableArray<ObjectKey<T>>;
-export declare function getKeys<T extends ImmutableObject>(obj: T | Partial<T>): ImmutableArray<ObjectKey<T>>;
-export declare function getKeys<T extends ImmutableObject>(obj: T | Partial<T> | Iterable<ObjectKey<T>>): Iterable<ObjectKey<T>>;
-/**
- * Extract the value of a named prop from an object.
- * - Extraction is possibly deep if deeper keys are specified.
- *
- * @param obj The target object to get from.
- * @param k1 The key of the prop in the object to get.
- * @param k2 The sub-key of the prop in the object to get.
- * @param k3 The sub-sub-key of the prop in the object to get.
- * @param k4 The sub-sub-sub-key of the prop in the object to get.
- */
-export declare function getProp<T extends ImmutableObject, K1 extends keyof T, K2 extends keyof T[K1], K3 extends keyof T[K1][K2], K4 extends keyof T[K1][K2][K3]>(obj: T, k1: K1, k2: K2, k3: K3, k4: K4): T[K1][K2][K3][K4];
-export declare function getProp<T extends ImmutableObject, K1 extends keyof T, K2 extends keyof T[K1], K3 extends keyof T[K1][K2]>(obj: T, k1: K1, k2: K2, k3: K3): T[K1][K2][K3];
-export declare function getProp<T extends ImmutableObject, K1 extends keyof T, K2 extends keyof T[K1]>(obj: T, k1: K1, k2: K2): T[K1][K2];
-export declare function getProp<T extends ImmutableObject, K1 extends keyof T>(obj: T, k1: K1): T[K1];
-export declare function getProp(obj: ImmutableObject, key: string, ...keys: readonly string[]): unknown;
+export declare function getKeys<T>(obj: T): ImmutableArray<Key<T>>;
+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];
 /** Set a prop on an object (immutably) and return a new object including that prop. */
-export declare function withProp<T extends ImmutableObject, K extends keyof T>(input: T, key: K, value: T[K]): T;
+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. */
-export declare function withProps<T extends ImmutableObject>(input: T, props: Partial<T>): T;
-export declare function withProps<T extends ImmutableObject>(input: T, props: T | Partial<T> | Iterable<ObjectProp<T>>): T;
+export declare function withProps<T>(input: T, props: Partial<T>): T;
+export declare function withProps<T>(input: T, props: T | Partial<T> | Iterable<Prop<T>>): T;
 /** Remove several props from an object (immutably) and return a new object without those props. */
-export declare function omitProps<T extends ImmutableObject, K extends keyof T>(input: T, ...keys: K[]): Omit<T, K>;
+export declare function omitProps<T, K extends Key<T>>(input: T, ...keys: K[]): Omit<T, K>;
 /** Pick several props from an object and return a new object with only thos props. */
-export declare function pickProps<T extends ImmutableObject, K extends keyof T>(obj: T, ...keys: K[]): Pick<T, K>;
+export declare function pickProps<T, K extends Key<T>>(obj: T, ...keys: K[]): Pick<T, K>;
 /** Set a single named prop on an object (by reference) and return its value. */
-export declare function setProp<T extends MutableObject, K extends keyof T>(obj: T, key: K, value: T[K]): T[K];
+export declare function setProp<T extends MutableObject, K extends Key<T>>(obj: T, key: K, value: T[K]): T[K];
 /** Set several named props on an object (by reference). */
-export declare function setProps<T extends MutableObject>(obj: T, entries: T | Partial<T> | Iterable<ObjectProp<T>>): void;
+export declare function setProps<T extends MutableObject>(obj: T, entries: T | Partial<T> | Iterable<Prop<T>>): void;
 /** Remove several key/value entries from an object (by reference). */
-export declare function deleteProps<T extends MutableObject>(obj: T, ...keys: (keyof T)[]): void;
+export declare function deleteProps<T extends MutableObject>(obj: T, ...keys: Key<T>[]): void;
 /**
  * Format an unknown object as a string.
  * - Use the custom `.toString()` function if it exists (don't use built in `Object.prototype.toString` because it's useless.
@@ -120,7 +107,7 @@ export declare function getPrototype<T>(obj: T): Partial<T> | null;
 /** Shallow clone an object with the same prototype. */
 export declare function cloneObject<T>(input: T): T;
 /** Shallow clone an object with a single changed value. */
-export declare function cloneObjectWith<T, K extends keyof T>(input: T, key: K, value: T[K]): T;
+export declare function cloneObjectWith<T, K extends Key<T>>(input: T, key: K, value: T[K]): T;
 export declare function cloneObjectWith<T, K extends string, V>(input: T, key: K, value: V): T & {
     [KK in K]: V;
 };

package/util/object.js

@@ -1,5 +1,4 @@
 import { AssertionError } from "../error/AssertionError.js";
-import { isArrayLength } from "./array.js";
 import { isIterable } from "./iterate.js";
 /** Is an unknown value an unknown object? */
 export const isObject = (value) => typeof value === "object" && value !== null;
@@ -33,9 +32,9 @@ export function getProps(obj) {
 export function getKeys(obj) {
     return isIterable(obj) ? obj : Object.keys(obj);
 }
-export function getProp(obj, key, ...keys) {
-    const value = obj[key];
-    return !isArrayLength(keys) ? value : isObject(value) ? getProp(value, ...keys) : undefined;
+/** Extract the value of a named prop from an object. */
+export function getProp(obj, key) {
+    return obj[key];
 }
 /** Set a prop on an object (immutably) and return a new object including that prop. */
 export function withProp(input, key, value) {

package/util/query.d.ts

@@ -1,63 +1,63 @@
 import type { ImmutableArray } from "./array.js";
-import type { Data, FlatData, FlatDataKey } from "./data.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 FlatDataKey<T> as K | `${K}` | `!${K}`]?: FlatData<T>[K] | ImmutableArray<FlatData<T>[K]> | undefined;
+    readonly [K in LeafKey<T> as `${K}` | `!${K}`]?: LeafData<T>[K] | ImmutableArray<LeafData<T>[K]> | undefined;
 } & {
-    readonly [K in FlatDataKey<T> as `${K}<` | `${K}<=` | `${K}>` | `${K}>=`]?: FlatData<T>[K] | undefined;
+    readonly [K in LeafKey<T> as `${K}<` | `${K}<=` | `${K}>` | `${K}>=`]?: LeafData<T>[K] | undefined;
 } & {
-    readonly [K in FlatDataKey<T> as `${K}[]`]?: FlatData<T>[K] extends ImmutableArray<infer X> ? X | undefined : never;
+    readonly [K in LeafKey<T> as `${K}[]`]?: LeafData<T>[K] extends ImmutableArray<infer X> ? X | undefined : never;
 } & {
-    readonly $order?: FlatDataKey<T> | `${FlatDataKey<T>}` | `!${FlatDataKey<T>}` | ImmutableArray<`${FlatDataKey<T>}` | `!${FlatDataKey<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. */
 export type Filter = {
-    keys: readonly [string, ...string[]];
+    key: string;
     operator: "is";
     value: unknown;
 } | {
-    keys: readonly [string, ...string[]];
+    key: string;
     operator: "not";
     value: unknown;
 } | {
-    keys: readonly [string, ...string[]];
+    key: string;
     operator: "in";
     value: ImmutableArray;
 } | {
-    keys: readonly [string, ...string[]];
+    key: string;
     operator: "out";
     value: ImmutableArray;
 } | {
-    keys: readonly [string, ...string[]];
+    key: string;
     operator: "contains";
     value: unknown;
 } | {
-    keys: readonly [string, ...string[]];
+    key: string;
     operator: "lt";
     value: unknown;
 } | {
-    keys: readonly [string, ...string[]];
+    key: string;
     operator: "lte";
     value: unknown;
 } | {
-    keys: readonly [string, ...string[]];
+    key: string;
     operator: "gt";
     value: unknown;
 } | {
-    keys: readonly [string, ...string[]];
+    key: string;
     operator: "gte";
     value: unknown;
 };
-/** A single sort that can be applied to a list of data objects. */
-export type Sort = {
-    keys: readonly [string, ...string[]];
+/** A single sort order that can be applied to a list of data objects. */
+export type Order = {
+    key: string;
     direction: "asc" | "desc";
 };
 /** Get the `Filter` objects for a query. */
 export declare function getFilters<T extends Data>(query: Query<T>): ImmutableArray<Filter>;
-/** Get the `Sort` objects for a query. */
-export declare function getSorts<T extends Data>({ $order }: Query<T>): ImmutableArray<Sort>;
+/** Get the `Order` objects for a query. */
+export declare function getOrders<T extends Data>({ $order }: Query<T>): ImmutableArray<Order>;
 /** Get the limit for a query. */
 export declare const getLimit: <T extends Data>({ $limit }: Query<T>) => number | undefined;
 /** Query a set of data items using a query. */
@@ -72,9 +72,9 @@ export declare function matchQueryItem<T extends Data>(item: T, filters: Immutab
 /**  Filter a set of data items using a set of filters. */
 export declare function filterQueryItems<T extends Data>(items: Iterable<T>, filters: ImmutableArray<Filter>): Iterable<T>;
 /** Compare two data items using a set of sorts. */
-export declare function compareQueryItems<T extends Data>(left: T, right: T, sorts: ImmutableArray<Sort>): number;
+export declare function compareQueryItems<T extends Data>(left: T, right: T, sorts: ImmutableArray<Order>): number;
 /**  Sort a set of data items using a set of sorts. */
-export declare function sortQueryItems<T extends Data>(items: Iterable<T>, sorts: ImmutableArray<Sort>): Iterable<T>;
+export declare function sortQueryItems<T extends Data>(items: Iterable<T>, sorts: ImmutableArray<Order>): Iterable<T>;
 /** LImit a set of data items using a set of limit. */
 export declare function limitQueryItems<T extends Data>(items: ImmutableArray<T> | Iterable<T>, limit: number | undefined): Iterable<T>;
 /** Get a query for items that appear before a specified item. */

package/util/query.js

@@ -1,9 +1,9 @@
 import { getLastItem, isArray, limitArray } from "./array.js";
+import { getDataProp } from "./data.js";
 import { isArrayWith, isEqual, isEqualGreater, isEqualLess, isGreater, isInArray, isLess, notEqual, notInArray } from "./equal.js";
 import { limitItems } from "./iterate.js";
-import { getProp, getProps } from "./object.js";
+import { getProps } from "./object.js";
 import { compareAscending, compareDescending, sortArray } from "./sort.js";
-import { splitString } from "./string.js";
 import { isDefined } from "./undefined.js";
 /** Map `Filter` operators to corresponding `Match` function. */
 const MATCHERS = {
@@ -22,38 +22,38 @@ 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) ? { keys: splitString(key.slice(1), "."), operator: "out", value } : { keys: splitString(key.slice(1), "."), operator: "not", value };
-    else if (key.endsWith("[]"))
-        return { keys: splitString(key.slice(0, -2), "."), operator: "contains", value };
-    else if (key.endsWith(">"))
-        return { keys: splitString(key.slice(0, -1), "."), operator: "gt", value };
-    else if (key.endsWith(">="))
-        return { keys: splitString(key.slice(0, -2), "."), operator: "gte", value };
-    else if (key.endsWith("<"))
-        return { keys: splitString(key.slice(0, -1), "."), operator: "lt", value };
-    else if (key.endsWith("<="))
-        return { keys: splitString(key.slice(0, -2), "."), operator: "lte", value };
-    else
-        return isArray(value) ? { keys: splitString(key, "."), operator: "in", value } : { keys: splitString(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 `Sort` objects for a query. */
-export function getSorts({ $order }) {
-    return !$order ? [] : isArray($order) ? $order.map(_getSort) : [_getSort($order)];
+/** Get the `Order` objects for a query. */
+export function getOrders({ $order }) {
+    return (isArray($order) ? $order : [$order]).filter(isDefined).map(_getOrder);
 }
-function _getSort(key) {
+function _getOrder(key) {
     if (key.startsWith("!"))
-        return { keys: splitString(key.slice(1), "."), direction: "desc" };
+        return { key: key.slice(1), direction: "desc" };
     else
-        return { keys: splitString(key, "."), direction: "asc" };
+        return { key, direction: "asc" };
 }
 /** Get the limit for a query. */
 export const getLimit = ({ $limit }) => $limit;
 /** Query a set of data items using a query. */
 export function queryItems(items, query) {
-    return limitQueryItems(sortQueryItems(filterQueryItems(items, getFilters(query)), getSorts(query)), getLimit(query));
+    return limitQueryItems(sortQueryItems(filterQueryItems(items, getFilters(query)), getOrders(query)), getLimit(query));
 }
 /**
  * Query a set of data items for writing using a query.
@@ -64,9 +64,9 @@ export function queryWritableItems(items, query) {
 }
 /** Match a single data item againt a set of filters. */
 export function matchQueryItem(item, filters) {
-    for (const { keys, operator, value } of filters) {
+    for (const { key, operator, value } of filters) {
         const matcher = MATCHERS[operator];
-        if (!matcher(getProp(item, ...keys), value))
+        if (!matcher(getDataProp(item, key), value))
             return false;
     }
     return true;
@@ -84,9 +84,9 @@ export function* filterQueryItems(items, filters) {
 }
 /** Compare two data items using a set of sorts. */
 export function compareQueryItems(left, right, sorts) {
-    for (const { keys, direction } of sorts) {
-        const l = getProp(left, ...keys);
-        const r = getProp(right, ...keys);
+    for (const { key, direction } of sorts) {
+        const l = getDataProp(left, key);
+        const r = getDataProp(right, key);
         const c = direction === "asc" ? compareAscending(l, r) : compareDescending(l, r);
         if (c !== 0)
             return c;
@@ -103,26 +103,24 @@ export function limitQueryItems(items, limit) {
 }
 /** Get a query for items that appear before a specified item. */
 export function getBeforeQuery(query, item) {
-    const sorts = getSorts(query);
+    const sorts = getOrders(query);
     const lastSort = getLastItem(sorts);
     const newQuery = { ...query };
     for (const sort of sorts) {
-        const { keys, direction } = sort;
-        const key = keys.join(".");
-        const value = getProp(item, ...keys);
+        const { key, direction } = sort;
+        const value = getDataProp(item, key);
         newQuery[direction === "asc" ? (sort === lastSort ? `${key}>` : `${key}>=`) : sort === lastSort ? `${key}<` : `${key}<=`] = value;
     }
     return newQuery;
 }
 /** Get a query for items that appear after a specified item. */
 export function getAfterQuery(query, item) {
-    const sorts = getSorts(query);
+    const sorts = getOrders(query);
     const lastSort = getLastItem(sorts);
     const newQuery = { ...query };
     for (const sort of sorts) {
-        const { keys, direction } = sort;
-        const key = keys.join(".");
-        const value = getProp(item, ...keys);
+        const { key, direction } = sort;
+        const value = getDataProp(item, key);
         newQuery[direction === "asc" ? (sort === lastSort ? `${key}<` : `${key}<=`) : sort === lastSort ? `${key}>` : `${key}>=`] = value;
     }
     return newQuery;

package/util/transform.d.ts

@@ -2,7 +2,7 @@ import type { ArrayItem, ImmutableArray } from "./array.js";
 import type { ImmutableDictionary, PossibleDictionary } from "./dictionary.js";
 import type { Entry } from "./entry.js";
 import type { Arguments } from "./function.js";
-import type { ImmutableObject, ObjectValue } from "./object.js";
+import type { ImmutableObject, Value } from "./object.js";
 /** Function that can transform an input value into an output value. */
 export type Transform<I, O, A extends Arguments = []> = (input: I, ...args: A) => O;
 /** Function that can transform an input value into an output value. */
@@ -19,11 +19,11 @@ export declare function mapArray<T extends ImmutableArray>(arr: T, transform: Tr
 export declare function mapArray<I, O, A extends Arguments = []>(arr: Iterable<I>, transform: (v: I, ...args: A) => O, ...args: A): ImmutableArray<O>;
 export declare function mapArray<I, O, A extends Arguments = []>(arr: Iterable<I>, transform: Transform<I, O, A>, ...args: A): ImmutableArray<O>;
 /** Modify the values of the props of an object using a transform. */
-export declare function mapObject<T extends ImmutableObject>(obj: T, transform: Transform<ObjectValue<T>, ObjectValue<T>>): T;
-export declare function mapObject<I extends ImmutableObject, O extends ImmutableObject, A extends Arguments = []>(obj: I, transform: (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, transform: Transform<ObjectValue<I>, ObjectValue<O>, A>, ...args: A): O;
+export declare function mapObject<T extends ImmutableObject>(obj: T, transform: Transform<Value<T>, Value<T>>): T;
+export declare function mapObject<I extends ImmutableObject, O extends ImmutableObject, A extends Arguments = []>(obj: I, transform: (v: Value<I>, ...args: A) => Value<O>, ...args: A): O;
+export declare function mapObject<I extends ImmutableObject, O extends ImmutableObject, A extends Arguments = []>(obj: I, transform: Transform<Value<I>, Value<O>, A>, ...args: A): O;
 /** Modify the values of a dictionary using a transform. */
-export declare const mapDictionary: <I, O, A extends Arguments = []>(dictionary: PossibleDictionary<I>, transform: Transform<I, O, A>, ...args: A) => ImmutableDictionary<O>;
+export declare function mapDictionary<I, O, A extends Arguments = []>(dictionary: PossibleDictionary<I>, transform: (v: I, ...args: A) => O, ...args: A): ImmutableDictionary<O>;
 /** Modify the values of a set of entries using a transform. */
 export declare function mapEntries<K, I, O, A extends Arguments = []>(entries: Iterable<Entry<K, I>>, transform: Transform<I, O, A>, ...args: A): Iterable<Entry<K, O>>;
 /**

package/util/transform.js

@@ -1,3 +1,4 @@
+import { getDictionaryItems } from "./dictionary.js";
 import { getProps } from "./object.js";
 export function* mapItems(items, transform, ...args) {
     for (const item of items)
@@ -9,8 +10,10 @@ export function mapArray(arr, transform, ...args) {
 export function mapObject(obj, transform, ...args) {
     return Object.fromEntries(mapEntries(getProps(obj), transform, ...args));
 }
-/** Modify the values of a dictionary using a transform. */
-export const mapDictionary = mapObject;
+// export function mapDictionary<I, O, A extends Arguments = []>(dictionary: PossibleDictionary<I>, transform: Transform<I, O, A>, ...args: A): ImmutableDictionary<O>;
+export function mapDictionary(dictionary, transform, ...args) {
+    return Object.fromEntries(mapEntries(getDictionaryItems(dictionary), transform, ...args));
+}
 /** Modify the values of a set of entries using a transform. */
 export function* mapEntries(entries, transform, ...args) {
     for (const [k, v] of entries)

package/util/update.d.ts

@@ -1,19 +1,21 @@
 import type { ImmutableArray } from "./array.js";
-import type { Data, FlatData, FlatDataKey } from "./data.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 FlatDataKey<T> as K | `${K}`]?: FlatData<T>[K];
+    readonly [K in BranchKey<T> as `${K}`]?: BranchData<T>[K] | undefined;
 } & {
-    readonly [K in FlatDataKey<T> as `${K}+=` | `${K}-=`]?: FlatData<T>[K] extends number ? FlatData<T>[K] : never;
+    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] | undefined : never;
 };
 /** A single update to a keyed property in an object. */
 export type Update = {
     action: "set";
-    keys: ImmutableArray<string>;
+    key: string;
     value: unknown;
 } | {
     action: "sum";
-    keys: ImmutableArray<string>;
+    key: string;
     value: number;
 };
 /** Yield the prop updates in an `Updates` object as a set of `Update` objects. */

package/util/update.js

@@ -2,28 +2,36 @@ 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([keys, value]) {
-    if (keys.endsWith("+="))
-        return { action: "sum", keys: keys.slice(0, -2).split("."), value: getNumber(value) };
-    else if (keys.endsWith("-="))
-        return { action: "sum", keys: keys.slice(0, -2).split("."), value: 0 - getNumber(value) };
-    else
-        return { action: "set", keys: keys.split("."), value };
+function _getUpdate([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) {
     return reduceItems(getUpdates(updates), _updateProp, data);
 }
-function _updateProp(obj, update, i = 0) {
-    const { action, keys, value } = update;
-    const key = keys[i];
-    if (!key)
+function _updateProp(obj, update) {
+    return _updatePropDeep(obj, update, update.key.split("."), 0);
+}
+function _updatePropDeep(obj, update, keys, i) {
+    const { action, value } = update;
+    const k = keys[i];
+    if (!k)
         return obj; // Shouldn't happen.
-    const oldValue = obj[key];
+    const oldValue = obj[k];
     let newValue = oldValue;
     if (i === keys.length - 1) {
         if (action === "sum")
@@ -36,7 +44,7 @@ function _updateProp(obj, update, i = 0) {
     else {
         if (!isObject(oldValue))
             throw new AssertionError(`Prop "${keys.slice(0, i + 1).join(".")}" is not an object`);
-        newValue = _updateProp(oldValue, update, i + 1);
+        newValue = _updatePropDeep(oldValue, update, keys, i + 1);
     }
-    return oldValue === newValue ? obj : { ...obj, [key]: newValue };
+    return oldValue === newValue ? obj : { ...obj, [k]: newValue };
 }