shelving 1.44.1 → 1.46.1

package/db/Database.d.ts

@@ -69,14 +69,14 @@ export declare class DatabaseQuery<T extends Data = Data> extends Query<T> imple
      * @return Entry in `[id, data]` format for the first document.
      * @throws RequiredError if there were no results for this query.
      */
-    get result(): Entry<T> | undefined | PromiseLike<Entry<T> | undefined>;
+    get result(): DocumentResult<T> | PromiseLike<DocumentResult<T>>;
     /**
      * Get an entry for the first document matched by this query.
      *
      * @return Entry in `[id, data]` format for the first document.
      * @throws RequiredError if there were no results for this query.
      */
-    get data(): Entry<T> | PromiseLike<Entry<T>>;
+    get data(): DocumentData<T> | PromiseLike<DocumentData<T>>;
     /**
      * Subscribe to all matching documents.
      * - `next()` is called once with the initial results, and again any time the results change.
@@ -111,7 +111,9 @@ export declare class DatabaseQuery<T extends Data = Data> extends Query<T> imple
     toString(): string;
 }
 /** Get the data for a document from a result for that document. */
-export declare function getQueryData<T extends Data>(entries: Entries<T>, ref: DatabaseQuery<T>): Entry<T>;
+export declare function getQueryData<T extends Data>(entries: Entries<T>, ref: DatabaseQuery<T>): DocumentData<T>;
+/** Get the data for a document from a result for that document. */
+export declare function getQueryResult<T extends Data>(entries: Entries<T>, ref: DatabaseQuery<T>): DocumentResult<T>;
 /** A document reference within a specific database. */
 export declare class DatabaseDocument<T extends Data = Data> implements Observable<Result<T>>, Validatable<T> {
     readonly db: Database;
@@ -132,7 +134,7 @@ export declare class DatabaseDocument<T extends Data = Data> implements Observab
      * Get the result of this document.
      * @return Document's data, or `undefined` if the document doesn't exist (possibly promised).
      */
-    get result(): Result<T> | PromiseLike<Result<T>>;
+    get result(): DocumentResult<T> | PromiseLike<DocumentResult<T>>;
     /**
      * Get the data of this document.
      * - Useful for destructuring, e.g. `{ name, title } = await documentThatMustExist.asyncData`
@@ -140,7 +142,7 @@ export declare class DatabaseDocument<T extends Data = Data> implements Observab
      * @return Document's data (possibly promised).
      * @throws RequiredError if the document's result was undefined.
      */
-    get data(): T | PromiseLike<T>;
+    get data(): DocumentData<T> | PromiseLike<DocumentData<T>>;
     /**
      * Subscribe to the result of this document (indefinitely).
      * - `next()` is called once with the initial result, and again any time the result changes.
@@ -159,5 +161,14 @@ export declare class DatabaseDocument<T extends Data = Data> implements Observab
     validate(unsafeData: Data): T;
     toString(): string;
 }
+/** Database data embeds the corresponding `Document` instance and string ID into the data. */
+export declare type DocumentData<T extends Data> = T & {
+    _id: string;
+    _doc: DatabaseDocument<T>;
+};
+/** Get the data for a document from a result for that document. */
+export declare function getDocumentData<T extends Data>(result: Result<T>, ref: DatabaseDocument<T>): DocumentData<T>;
+/** Database result embeds the corresponding `Document` instance and string ID into the result. */
+export declare type DocumentResult<T extends Data> = DocumentData<T> | null;
 /** Get the data for a document from a result for that document. */
-export declare function getDocumentData<T extends Data>(result: Result<T>, ref: DatabaseDocument<T>): T;
+export declare function getDocumentResult<T extends Data>(result: Result<T>, ref: DatabaseDocument<T>): DocumentResult<T>;

package/db/Database.js

@@ -93,7 +93,7 @@ export class DatabaseQuery extends Query {
      * @throws RequiredError if there were no results for this query.
      */
     get result() {
-        return callAsync(getFirstItem, this.db.provider.getQuery(this.max(1)));
+        return callAsync(getQueryResult, this.db.provider.getQuery(this.max(1)), this);
     }
     /**
      * Get an entry for the first document matched by this query.
@@ -170,7 +170,14 @@ export class DatabaseQuery extends Query {
 export function getQueryData(entries, ref) {
     const first = getFirstItem(entries);
     if (first)
-        return first;
+        return getDocumentData(first[1], ref.doc(first[0]));
+    throw new QueryRequiredError(ref);
+}
+/** Get the data for a document from a result for that document. */
+export function getQueryResult(entries, ref) {
+    const first = getFirstItem(entries);
+    if (first)
+        return getDocumentData(first[1], ref.doc(first[0]));
     throw new QueryRequiredError(ref);
 }
 /** A document reference within a specific database. */
@@ -201,7 +208,7 @@ export class DatabaseDocument {
      * @return Document's data, or `undefined` if the document doesn't exist (possibly promised).
      */
     get result() {
-        return this.db.provider.get(this);
+        return callAsync(getDocumentResult, this.db.provider.get(this), this);
     }
     /**
      * Get the data of this document.
@@ -252,6 +259,10 @@ export class DatabaseDocument {
 /** Get the data for a document from a result for that document. */
 export function getDocumentData(result, ref) {
     if (result)
-        return result;
+        return { ...result, _id: ref.id, _doc: ref };
     throw new DocumentRequiredError(ref);
 }
+/** Get the data for a document from a result for that document. */
+export function getDocumentResult(result, ref) {
+    return result ? getDocumentData(result, ref) : null;
+}

package/package.json

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

package/react/useDocument.d.ts

@@ -1,4 +1,4 @@
-import { DatabaseDocument, Result, Data } from "../index.js";
+import { DatabaseDocument, Result, Data, DocumentData } from "../index.js";
 /**
  * Use the cached result of a document in a React component (or a `Promise` to indicate the result is still loading).
  * - Requires database to use `CacheProvider` and will error if this does not exist.
@@ -33,8 +33,8 @@ export declare function useAsyncDocument<T extends Data>(ref: DatabaseDocument<T
 export declare function useDocument<T extends Data>(ref: DatabaseDocument<T>, maxAge?: number | true): Result<T>;
 export declare function useDocument<T extends Data>(ref: DatabaseDocument<T> | undefined, maxAge?: number | true): Result<T> | undefined;
 /** Use the data of a document or `undefined` if the query has no matching results (or a promise indicating the result is loading). */
-export declare function useAsyncDocumentData<T extends Data>(ref: DatabaseDocument<T>, maxAge?: number | true): T | PromiseLike<T>;
-export declare function useAsyncDocumentData<T extends Data>(ref: DatabaseDocument<T> | undefined, maxAge?: number | true): T | PromiseLike<T> | undefined;
+export declare function useAsyncDocumentData<T extends Data>(ref: DatabaseDocument<T>, maxAge?: number | true): DocumentData<T> | PromiseLike<DocumentData<T>>;
+export declare function useAsyncDocumentData<T extends Data>(ref: DatabaseDocument<T> | undefined, maxAge?: number | true): DocumentData<T> | PromiseLike<DocumentData<T>> | undefined;
 /** Use the data of a document or `undefined` if the query has no matching results. */
 export declare function useDocumentData<T extends Data>(ref: DatabaseDocument<T>, maxAge?: number | true): T;
 export declare function useDocumentData<T extends Data>(ref: DatabaseDocument<T> | undefined, maxAge?: number | true): T | undefined;

package/react/useQuery.d.ts

@@ -1,4 +1,4 @@
-import { Results, DatabaseQuery, Data, Entry } from "../index.js";
+import { Results, DatabaseQuery, Data, DocumentResult, DocumentData } from "../index.js";
 /**
  * Use the cached result of a document in a React component (or a `Promise` to indicate the result is still loading).
  * - Requires database to use `CacheProvider` and will error if this does not exist.
@@ -34,14 +34,14 @@ export declare function useAsyncQuery<T extends Data>(ref: DatabaseQuery<T> | un
 export declare function useQuery<T extends Data>(ref: DatabaseQuery<T>, maxAge?: number | true): Results<T>;
 export declare function useQuery<T extends Data>(ref: DatabaseQuery<T> | undefined, maxAge?: number | true): Results<T> | undefined;
 /** Use the first result of a query or `undefined` if the query has no matching results (or a promise indicating the result is loading). */
-export declare function useAsyncQueryResult<T extends Data>(ref: DatabaseQuery<T>, maxAge?: number | true): Entry<T> | undefined | PromiseLike<Entry<T> | undefined>;
-export declare function useAsyncQueryResult<T extends Data>(ref: DatabaseQuery<T> | undefined, maxAge?: number | true): Entry<T> | undefined | PromiseLike<Entry<T> | undefined>;
+export declare function useAsyncQueryResult<T extends Data>(ref: DatabaseQuery<T>, maxAge?: number | true): DocumentResult<T> | undefined | PromiseLike<DocumentResult<T> | undefined>;
+export declare function useAsyncQueryResult<T extends Data>(ref: DatabaseQuery<T> | undefined, maxAge?: number | true): DocumentResult<T> | undefined | PromiseLike<DocumentResult<T> | undefined>;
 /** Use the first result of a query or `undefined` if the query has no matching results */
-export declare function useQueryResult<T extends Data>(ref: DatabaseQuery<T>, maxAge?: number | true): Entry<T> | undefined;
-export declare function useQueryResult<T extends Data>(ref: DatabaseQuery<T> | undefined, maxAge?: number | true): Entry<T> | undefined;
+export declare function useQueryResult<T extends Data>(ref: DatabaseQuery<T>, maxAge?: number | true): DocumentResult<T>;
+export declare function useQueryResult<T extends Data>(ref: DatabaseQuery<T> | undefined, maxAge?: number | true): DocumentResult<T> | undefined;
 /** Use the first result of a query (or a promise indicating the result is loading). */
-export declare function useAsyncQueryData<T extends Data>(ref: DatabaseQuery<T>, maxAge?: number | true): Entry<T> | PromiseLike<Entry<T>>;
-export declare function useAsyncQueryData<T extends Data>(ref: DatabaseQuery<T> | undefined, maxAge?: number | true): Entry<T> | PromiseLike<Entry<T>> | undefined;
+export declare function useAsyncQueryData<T extends Data>(ref: DatabaseQuery<T>, maxAge?: number | true): DocumentData<T> | PromiseLike<DocumentData<T>>;
+export declare function useAsyncQueryData<T extends Data>(ref: DatabaseQuery<T> | undefined, maxAge?: number | true): DocumentData<T> | PromiseLike<DocumentData<T>> | undefined;
 /** Use the first result of a query. */
-export declare function useQueryData<T extends Data>(ref: DatabaseQuery<T>, maxAge?: number | true): Entry<T>;
-export declare function useQueryData<T extends Data>(ref: DatabaseQuery<T> | undefined, maxAge?: number | true): Entry<T> | undefined;
+export declare function useQueryData<T extends Data>(ref: DatabaseQuery<T>, maxAge?: number | true): DocumentData<T>;
+export declare function useQueryData<T extends Data>(ref: DatabaseQuery<T> | undefined, maxAge?: number | true): DocumentData<T> | undefined;

package/react/useQuery.js

@@ -1,5 +1,5 @@
 import { useState } from "react";
-import { CacheProvider, NOERROR, findSourceProvider, NOVALUE, getMap, callAsync, getQueryData, throwAsync, getFirstItem, ResultsObserver } from "../index.js";
+import { CacheProvider, NOERROR, findSourceProvider, NOVALUE, getMap, callAsync, getQueryData, throwAsync, ResultsObserver, getQueryResult, } from "../index.js";
 import { usePureEffect } from "./usePureEffect.js";
 import { usePureMemo } from "./usePureMemo.js";
 import { usePureState } from "./usePureState.js";
@@ -60,7 +60,7 @@ export function useQuery(ref, maxAge) {
 }
 export function useAsyncQueryResult(ref, maxAge) {
     const results = useAsyncQuery(ref ? ref.max(1) : undefined, maxAge);
-    return ref && results ? callAsync(getFirstItem, results) : undefined;
+    return ref && results ? callAsync(getQueryResult, results, ref) : undefined;
 }
 export function useQueryResult(ref, maxAge) {
     return throwAsync(useAsyncQueryResult(ref, maxAge));

package/util/units.d.ts

@@ -14,7 +14,7 @@ export declare type UnitData = {
 /** Valid system of measurement reference. */
 export declare type UnitType = "percentage" | "angle" | "temperature" | "length" | "speed" | "pace" | "mass" | "time" | "volume";
 /** Valid unit of measurement reference (correspond to units allowed in `Intl.NumberFormat`, but not all). */
-export declare type UnitReference = "percent" | "degree" | "millimeter" | "centimeter" | "meter" | "kilometer" | "mile" | "yard" | "foot" | "inch" | "liter" | "milliliter" | "gallon" | "fluid-ounce" | "gram" | "kilogram" | "pound" | "stone" | "ounce" | "millisecond" | "second" | "minute" | "day" | "hour" | "week" | "month" | "year";
+export declare type UnitReference = "percent" | "degree" | "millimeter" | "centimeter" | "meter" | "kilometer" | "mile" | "yard" | "foot" | "inch" | "liter" | "milliliter" | "gallon" | "fluid-ounce" | "milligram" | "gram" | "kilogram" | "pound" | "stone" | "ounce" | "millisecond" | "second" | "minute" | "day" | "hour" | "week" | "month" | "year";
 /** List of units. */
 export declare const UNITS: {
     [K in UnitReference]: UnitData;

package/util/units.js

@@ -6,23 +6,24 @@ import { NNBSP } from "./string.js";
 export const UNITS = {
     "percent": { type: "percentage", base: 1, suffix: "%" },
     "degree": { type: "angle", base: 1, suffix: "deg" },
-    "millimeter": { type: "length", base: 0.001, suffix: "mm" },
-    "centimeter": { type: "length", base: 0.01, suffix: "cm" },
-    "meter": { type: "length", base: 1, centimeter: 100, millimeter: 1000, suffix: "m" },
-    "kilometer": { type: "length", base: 1000, centimeter: 100000, millimeter: 1000000, suffix: "km" },
-    "inch": { type: "length", base: 0.0254, suffix: "in" },
-    "foot": { type: "length", base: 0.3048, inch: 12, suffix: "ft", plural: "feet" },
-    "yard": { type: "length", base: 0.9144, inch: 36, foot: 3, suffix: "yd" },
-    "mile": { type: "length", base: 1609.344, yard: 1760, foot: 5280, inch: 63360, suffix: "mi" },
+    "millimeter": { type: "length", base: 1, suffix: "mm" },
+    "centimeter": { type: "length", base: 10, suffix: "cm" },
+    "meter": { type: "length", base: 1000, centimeter: 100, millimeter: 1000, suffix: "m" },
+    "kilometer": { type: "length", base: 1000000, centimeter: 100000, millimeter: 1000000, suffix: "km" },
+    "inch": { type: "length", base: 25.4, suffix: "in" },
+    "foot": { type: "length", base: 304.8, inch: 12, suffix: "ft", plural: "feet" },
+    "yard": { type: "length", base: 914.4, inch: 36, foot: 3, suffix: "yd" },
+    "mile": { type: "length", base: 1609344, yard: 1760, foot: 5280, inch: 63360, suffix: "mi" },
     "milliliter": { type: "volume", base: 1, suffix: "ml" },
     "liter": { type: "volume", base: 1000, suffix: "l" },
     "fluid-ounce": { type: "volume", base: 29.5735295625, gallon: 128, suffix: `fl${NNBSP}oz` },
     "gallon": { type: "volume", base: 3785.411784, suffix: "gal" },
-    "gram": { type: "mass", base: 1, suffix: "g" },
-    "kilogram": { type: "mass", base: 1000, suffix: "kg" },
-    "ounce": { type: "mass", base: 28.349523125, pound: 0.0625, suffix: "oz" },
-    "pound": { type: "mass", base: 453.59237, ounce: 16, suffix: "lb" },
-    "stone": { type: "mass", base: 6350.29318, pound: 14, ounce: 224, suffix: "st", plural: "stone" },
+    "milligram": { type: "mass", base: 1, suffix: "mg" },
+    "gram": { type: "mass", base: 1000, suffix: "g" },
+    "kilogram": { type: "mass", base: 1000000, suffix: "kg" },
+    "ounce": { type: "mass", base: 28349.523125, pound: 0.0625, suffix: "oz" },
+    "pound": { type: "mass", base: 453592.37, ounce: 16, suffix: "lb" },
+    "stone": { type: "mass", base: 6350293.18, pound: 14, ounce: 224, suffix: "st", plural: "stone" },
     "millisecond": { type: "time", base: 1, suffix: "ms" },
     "second": { type: "time", base: SECOND, suffix: "s" },
     "minute": { type: "time", base: MINUTE, suffix: "m" },