shelving 1.30.2 → 1.30.3

package/db/Database.d.ts

@@ -56,7 +56,9 @@ export declare class DataQuery<T extends Data = Data> extends Query<T> implement
     get count(): number | PromiseLike<number>;
     /**
      * Get an entry for the first document matching this query.
-     * @return Entry in `[id, data]` format for the first document, or `undefined` if there are no matching documents (possibly promised).
+     *
+     * @return Entry in `[id, data]` format for the first document.
+     * @throws RequiredError if there were no results for this query.
      */
     get first(): Entry<T> | undefined | PromiseLike<Entry<T> | undefined>;
     /**
@@ -100,6 +102,8 @@ export declare class DataQuery<T extends Data = Data> extends Query<T> implement
     validate(unsafeEntries: Results): Results<T>;
     toString(): string;
 }
+/** Get the data for a document from a result for that document. */
+export declare function getQueryFirst<T extends Data>(results: Results<T>, ref: DataQuery<T>): Entry<T>;
 /** A document reference within a specific database. */
 export declare class DataDocument<T extends Data = Data> implements Observable<Result<T>>, Validatable<T> {
     readonly provider: Provider;

package/db/Database.js

@@ -2,7 +2,7 @@ import { callAsync, getFirstItem, throwAsync, validate, toMap, countItems, Trans
 import { DataUpdate, Update } from "../update/index.js";
 import { Feedback, InvalidFeedback } from "../feedback/index.js";
 import { Filters, Query, EqualFilter } from "../query/index.js";
-import { DocumentRequiredError, DocumentValidationError, QueryValidationError } from "./errors.js";
+import { DocumentRequiredError, DocumentValidationError, QueryRequiredError, QueryValidationError } from "./errors.js";
 import { DocumentDelete, DocumentSet, DocumentUpdate, Writes } from "./Write.js";
 /**
  * Combines a database model and a provider.
@@ -81,10 +81,12 @@ export class DataQuery extends Query {
     }
     /**
      * Get an entry for the first document matching this query.
-     * @return Entry in `[id, data]` format for the first document, or `undefined` if there are no matching documents (possibly promised).
+     *
+     * @return Entry in `[id, data]` format for the first document.
+     * @throws RequiredError if there were no results for this query.
      */
     get first() {
-        return callAsync(getFirstItem, this.max(1).results);
+        return callAsync(getQueryFirst, this.max(1).results, this);
     }
     /**
      * Subscribe to all matching documents.
@@ -158,6 +160,13 @@ export class DataQuery extends Query {
         return `${this.collection}?${super.toString()}`;
     }
 }
+/** Get the data for a document from a result for that document. */
+export function getQueryFirst(results, ref) {
+    const first = getFirstItem(results);
+    if (first)
+        return first;
+    throw new QueryRequiredError(ref);
+}
 /** A document reference within a specific database. */
 export class DataDocument {
     constructor(provider, validator, collection, id) {

package/db/errors.d.ts

@@ -7,6 +7,11 @@ export declare class DocumentRequiredError<T extends Data> extends RequiredError
     ref: DataDocument<T>;
     constructor(ref: DataDocument<T>);
 }
+/** Thrown if a query doesn't exist. */
+export declare class QueryRequiredError<T extends Data> extends RequiredError {
+    ref: DataQuery<T>;
+    constructor(ref: DataQuery<T>);
+}
 /** Thrown if a document can't validate. */
 export declare class DocumentValidationError<T extends Data> extends ValidationError {
     ref: DataDocument<T>;

package/db/errors.js

@@ -7,6 +7,14 @@ export class DocumentRequiredError extends RequiredError {
     }
 }
 DocumentRequiredError.prototype.name = "DocumentRequiredError";
+/** Thrown if a query doesn't exist. */
+export class QueryRequiredError extends RequiredError {
+    constructor(ref) {
+        super(`Query "${ref.toString()}" has no results`);
+        this.ref = ref;
+    }
+}
+QueryRequiredError.prototype.name = "QueryRequiredError";
 /** Thrown if a document can't validate. */
 export class DocumentValidationError extends ValidationError {
     constructor(ref, feedback) {

package/package.json

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

package/react/index.d.ts

@@ -7,4 +7,5 @@ export * from "./useFetch.js";
 export * from "./useDocument.js";
 export * from "./useDocumentData.js";
 export * from "./useQuery.js";
+export * from "./useQueryFirst.js";
 export * from "./usePagination.js";

package/react/index.js

@@ -7,4 +7,5 @@ export * from "./useFetch.js";
 export * from "./useDocument.js";
 export * from "./useDocumentData.js";
 export * from "./useQuery.js";
+export * from "./useQueryFirst.js";
 export * from "./usePagination.js";

package/react/useDocumentData.d.ts

@@ -14,7 +14,7 @@ import { DataDocument, Data } from "../index.js";
  * @trhows `Error` if a `CacheProvider` is not part of the database's provider chain.
  * @throws `Error` if there was a problem retrieving the data.
  */
-export declare function useAsyncDocumentData<T extends Data>(ref: DataDocument<T>, maxAge?: number | true): T | Promise<T>;
+export declare function useAsyncDocumentData<T extends Data>(ref: DataDocument<T>, maxAge?: number | true): T | PromiseLike<T>;
 export declare function useAsyncDocumentData<T extends Data>(ref: DataDocument<T> | undefined, maxAge?: number | true): T | PromiseLike<T> | undefined;
 /**
  * Use the cached data of a document in a React component.

package/react/useQueryFirst.d.ts

@@ -0,0 +1,36 @@
+import { DataQuery, Data, Entry } from "../index.js";
+/**
+ * Use the cached data of a document in a React component (or a `Promise` to indicate the data is still loading).
+ * - Requires database to use `CacheProvider` and will error if this does not exist.
+ *
+ * @param ref Query reference or `undefined`.
+ * - If `undefined` is set this function will always return `undefined` (this simplifies scenarios where no document is needed, as hooks must always be called in the same order).
+ * @param maxAge How 'out of date' data is allowed to be before it'll be refetched.
+ * - If `maxAge` is true, a realtime subscription to the data will be created for the lifetime of the component.
+ *
+ * @returns The data of the document, or `Promise` that resolves when the data has loaded.
+ *
+ * @throws `RequiredError` if the query had no results.
+ * @trhows `Error` if a `CacheProvider` is not part of the database's provider chain.
+ * @throws `Error` if there was a problem retrieving the data.
+ */
+export declare function useAsyncQueryFirst<T extends Data>(ref: DataQuery<T>, maxAge?: number | true): Entry<T> | PromiseLike<Entry<T>>;
+export declare function useAsyncQueryFirst<T extends Data>(ref: DataQuery<T> | undefined, maxAge?: number | true): Entry<T> | PromiseLike<Entry<T>> | undefined;
+/**
+ * Use the cached data of a document in a React component.
+ * - Requires database to use `CacheProvider` and will error if this does not exist.
+ *
+ * @param ref Query reference or `undefined`.
+ * - If `undefined` is set this function will always return `undefined` (this simplifies scenarios where no document is needed, as hooks must always be called in the same order).
+ * @param maxAge How 'out of date' data is allowed to be before it'll be refetched.
+ * - If `maxAge` is true, a realtime subscription to the data will be created for the lifetime of the component.
+ *
+ * @returns The data of the document.
+ *
+ * @throws `Promise` that resolves when the data has loaded.
+ * @throws `RequiredError` if the query had no results.
+ * @trhows `Error` if a `CacheProvider` is not part of the database's provider chain.
+ * @throws `Error` if there was a problem retrieving the data.
+ */
+export declare function useQueryFirst<T extends Data>(ref: DataQuery<T>, maxAge?: number | true): Entry<T>;
+export declare function useQueryFirst<T extends Data>(ref: DataQuery<T> | undefined, maxAge?: number | true): Entry<T> | undefined;

package/react/useQueryFirst.js

@@ -0,0 +1,9 @@
+import { callAsync, getQueryFirst, throwAsync } from "../index.js";
+import { useAsyncQuery } from "./useQuery.js";
+export function useAsyncQueryFirst(ref, maxAge) {
+    const results = useAsyncQuery(ref, maxAge);
+    return ref && results ? callAsync(getQueryFirst, results, ref) : undefined;
+}
+export function useQueryFirst(ref, maxAge) {
+    return throwAsync(useAsyncQueryFirst(ref, maxAge));
+}