shelving 1.30.2 → 1.31.1

package/db/Database.d.ts

@@ -56,9 +56,11 @@ 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>;
+    get first(): Entry<T> | PromiseLike<Entry<T>>;
     /**
      * Subscribe to all matching documents.
      * - `next()` is called once with the initial results, and again any time the results change.
@@ -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.31.1",
 	"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 ? ref.max(1) : undefined, maxAge);
+    return ref && results ? callAsync(getQueryFirst, results, ref) : undefined;
+}
+export function useQueryFirst(ref, maxAge) {
+    return throwAsync(useAsyncQueryFirst(ref, maxAge));
+}

package/schema/NumberSchema.js

@@ -1,4 +1,4 @@
-import { toNumber, roundNumber } from "../util/index.js";
+import { toNumber, roundStep } from "../util/index.js";
 import { InvalidFeedback } from "../feedback/index.js";
 import { Schema } from "./Schema.js";
 import { OPTIONAL } from "./OptionalSchema.js";
@@ -15,7 +15,7 @@ export class NumberSchema extends Schema {
         const unsafeNumber = toNumber(unsafeValue);
         if (typeof unsafeNumber !== "number")
             throw new InvalidFeedback("Must be number", { value: unsafeValue });
-        const safeNumber = typeof this.step === "number" ? roundNumber(unsafeNumber, this.step) : unsafeNumber;
+        const safeNumber = typeof this.step === "number" ? roundStep(unsafeNumber, this.step) : unsafeNumber;
         if (typeof this.max === "number" && safeNumber > this.max)
             throw new InvalidFeedback(`Maximum ${this.max}`, { value: safeNumber });
         if (typeof this.min === "number" && safeNumber < this.min)

package/util/assert.d.ts

@@ -29,6 +29,10 @@ export declare function assertArray<T extends ImmutableArray>(value: T | unknown
 export declare function assertLength<T extends {
     length: number;
 }>(value: T | unknown, min: number, max?: number): asserts value is T;
+/** Assert that a value is a number greater than. */
+export declare function assertGreater(value: number | unknown, target: number): asserts value is number;
+/** Assert that a value is a number less than. */
+export declare function assertLess(value: number | unknown, target: number): asserts value is number;
 /** Assert that a value is an instance of something. */
 export declare function assertInstance<T>(value: T | unknown, type: Class<T>): asserts value is T;
 /** Assert that a value is a function. */

package/util/assert.js

@@ -58,6 +58,16 @@ export function assertLength(value, min, max = min) {
     if (!isObject(value) || typeof value.length !== "number" || value.length < min || value.length > max)
         throw new AssertionError(`Must have length ${min}–${max}`, value);
 }
+/** Assert that a value is a number greater than. */
+export function assertGreater(value, target) {
+    if (typeof value !== "number" || value <= target)
+        throw new AssertionError(`Must be greater than ${target}`, value);
+}
+/** Assert that a value is a number less than. */
+export function assertLess(value, target) {
+    if (typeof value !== "number" || value >= target)
+        throw new AssertionError(`Must be less than ${target}`, value);
+}
 /** Assert that a value is an instance of something. */
 export function assertInstance(value, type) {
     if (!(value instanceof type))

package/util/color.d.ts

@@ -0,0 +1,29 @@
+/** Things that can be converted to a `Color` instance. */
+export declare type PossibleColor = Color | string;
+/** Represent a color. */
+export declare class Color {
+    readonly r: number;
+    readonly g: number;
+    readonly b: number;
+    readonly a: number;
+    constructor(r?: number | string, g?: number | string, b?: number | string, a?: number | string);
+    /** Convert this color to a six or eight digit hex color. */
+    get hex(): string;
+    /** Convert this color to an `rgb()` string. */
+    get rgb(): string;
+    /** Convert this color to an `rgba()` string. */
+    get rgba(): string;
+    /** Get the sRGB luminance of this color. */
+    get luminance(): number;
+    toString(): string;
+}
+/** Convert a number or string to a color channel number that's within bounds (strings like `0a` or `ff` are parsed as hexadecimal). */
+export declare function getColorChannel(channel: number | string): number;
+/** Convert a possible color to a `Color` instance or `null` */
+export declare function toColor(color: PossibleColor): Color | null;
+/** Convert a possible color to a `Color` instance */
+export declare function getColor(input: PossibleColor): Color;
+/** Is a color light? */
+export declare const isLight: (input: PossibleColor) => boolean;
+/** Is a color dark? */
+export declare const isDark: (input: PossibleColor) => boolean;

package/util/color.js

@@ -0,0 +1,70 @@
+import { AssertionError } from "../error/index.js";
+import { getBetween, roundNumber } from "./number.js";
+// Constants.
+const DARK = 140; // Anything with a luminance > 140 is considered light.
+const MIN = 0; // Maximum value of a channel.
+const MAX = 255; // Maximum value of a channel.
+// Regular expressions.
+const HEX3 = /^#?([0-F])([0-F])([0-F])$/i;
+const HEX6 = /^#?([0-F]{2})([0-F]{2})([0-F]{2})([0-F]{2})?$/i;
+/** Represent a color. */
+export class Color {
+    constructor(r = 255, g = 255, b = 255, a = 255) {
+        this.r = getColorChannel(r);
+        this.g = getColorChannel(g);
+        this.b = getColorChannel(b);
+        this.a = getColorChannel(a);
+    }
+    /** Convert this color to a six or eight digit hex color. */
+    get hex() {
+        return `#${_hex(this.r)}${_hex(this.g)}${_hex(this.b)}${this.a < MAX ? _hex(this.a) : ""}`;
+    }
+    /** Convert this color to an `rgb()` string. */
+    get rgb() {
+        return `rgb(${this.r}, ${this.g}, ${this.b})`;
+    }
+    /** Convert this color to an `rgba()` string. */
+    get rgba() {
+        return `rgba(${this.r}, ${this.g}, ${this.b}, ${roundNumber(this.a / 256, 4)})`;
+    }
+    /** Get the sRGB luminance of this color. */
+    get luminance() {
+        // Green is the largest component of the luminence, etc.
+        return Math.round(0.2126 * this.r + 0.7152 * this.g + 0.0722 * this.b);
+    }
+    toString() {
+        return this.rgba;
+    }
+}
+/** Convert number channel to a hex string (results will be unpredictable if number is outside 0-MAX). */
+const _hex = (channel) => channel.toString(16).padStart(2, "00");
+/** Convert a number or string to a color channel number that's within bounds (strings like `0a` or `ff` are parsed as hexadecimal). */
+export function getColorChannel(channel) {
+    const num = typeof channel === "string" ? parseInt(channel.padStart(2, "00"), 16) : Math.round(channel);
+    if (Number.isFinite(num))
+        return getBetween(num, MIN, MAX);
+    throw new AssertionError("Invalid color channel", channel);
+}
+/** Convert a possible color to a `Color` instance or `null` */
+export function toColor(color) {
+    if (color instanceof Color)
+        return color;
+    const hex3 = color.match(HEX3);
+    if (hex3)
+        return new Color(hex3[1], hex3[2], hex3[3]);
+    const hex6 = color.match(HEX6);
+    if (hex6)
+        return new Color(hex6[1], hex6[2], hex6[3], hex6[4]);
+    return null;
+}
+/** Convert a possible color to a `Color` instance */
+export function getColor(input) {
+    const color = toColor(input);
+    if (color)
+        return color;
+    throw new AssertionError("Invalid color", color);
+}
+/** Is a color light? */
+export const isLight = (input) => getColor(input).luminance > DARK;
+/** Is a color dark? */
+export const isDark = (input) => getColor(input).luminance <= DARK;

package/util/index.d.ts

@@ -4,6 +4,7 @@ export * from "./async.js";
 export * from "./boolean.js";
 export * from "./class.js";
 export * from "./clone.js";
+export * from "./color.js";
 export * from "./constants.js";
 export * from "./data.js";
 export * from "./date.js";

package/util/index.js

@@ -4,6 +4,7 @@ export * from "./async.js";
 export * from "./boolean.js";
 export * from "./class.js";
 export * from "./clone.js";
+export * from "./color.js";
 export * from "./constants.js";
 export * from "./data.js";
 export * from "./date.js";

package/util/number.d.ts

@@ -11,13 +11,6 @@ export declare const IS_NUMBER: (v: unknown) => v is number;
  * - Everything else returns `null`
  */
 export declare function toNumber(value: unknown): number | null;
-/**
- * Convert a stringy number into a number.
- *
- * @param str The string to convert.
- * @return The number, null (valid, meaning no number).
- */
-export declare const stringToNumber: (str: string) => number | null;
 /**
  * Round numbers to a given step.
  *
@@ -25,7 +18,16 @@ export declare const stringToNumber: (str: string) => number | null;
  * @param step The rounding to round to, e.g. `2` or `0.1` (defaults to `1`, i.e. round numbers).
  * @returns The number rounded to the step.
  */
-export declare const roundNumber: (num: number, step?: number) => number;
+export declare function roundStep(num: number, step?: number): number;
+/**
+ * Round a number to a specified set of decimal places.
+ * - Doesn't include excess `0` zeroes like `num.toFixed()` and `num.toPrecision()` do.
+ *
+ * @param num The number to format.
+ * @param precision Maximum of digits shown after the decimal point (defaults to 10), with zeroes trimmed.
+ * @returns The number formatted as a string in the browser's current locale.
+ */
+export declare const roundNumber: (num: number, precision?: number) => string;
 /**
  * Format a number (based on the user's browser settings).
  * @param num The number to format.
@@ -41,3 +43,11 @@ export declare const formatNumber: (num: number, precision?: number) => string;
  * @param end The end of the range, e.g. `20`
  */
 export declare const isBetween: (num: number, start: number, end: number) => boolean;
+/**
+ *  Apply a min/max to a number to return a number that's definitely in the specified range.
+ *
+ * @param num The number to apply the min/max to, e.g. `17`
+ * @param start The start of the range, e.g. `10`
+ * @param end The end of the range, e.g. `20`
+ */
+export declare const getBetween: (num: number, start: number, end: number) => number;

package/util/number.js

@@ -12,33 +12,15 @@ export const IS_NUMBER = (v) => typeof v === "number";
  * - Everything else returns `null`
  */
 export function toNumber(value) {
-    if (typeof value === "number" && Number.isFinite(value))
-        return value;
-    if (typeof value === "string")
-        return stringToNumber(value);
-    if (value instanceof Date)
+    if (typeof value === "number")
+        return Number.isFinite(value) ? value : null;
+    else if (typeof value === "string")
+        return toNumber(parseFloat(value.replace(NUMERIC, "")));
+    else if (value instanceof Date)
         return value.getTime();
     return null;
 }
-const R_NON_NUMERIC = /[^0-9]+/g; // Any non-numeric characters.
-const R_PREFIX = /^[^0-9.]*/; // Characters that come before any digits or decimal points
-/**
- * Convert a stringy number into a number.
- *
- * @param str The string to convert.
- * @return The number, null (valid, meaning no number).
- */
-export const stringToNumber = (str) => {
-    var _a;
-    if (!str)
-        return null;
-    const [a, ...b] = str.split(".");
-    const num = Number.parseFloat(`${a.replace(R_NON_NUMERIC, "")}.${b.join("").replace(R_NON_NUMERIC, "")}`);
-    if (Number.isNaN(num))
-        return null;
-    const isNeg = !((((_a = str.match(R_PREFIX)) === null || _a === void 0 ? void 0 : _a[0]) || "").split("-").length % 2);
-    return Number.isNaN(num) ? null : isNeg ? 0 - num : num;
-};
+const NUMERIC = /[^0-9-.]/g;
 /**
  * Round numbers to a given step.
  *
@@ -46,11 +28,20 @@ export const stringToNumber = (str) => {
  * @param step The rounding to round to, e.g. `2` or `0.1` (defaults to `1`, i.e. round numbers).
  * @returns The number rounded to the step.
  */
-export const roundNumber = (num, step = 1) => {
+export function roundStep(num, step = 1) {
     if (step < 0.00001)
-        throw new AssertionError("roundNumber() does not work accurately with steps smaller than 0.00001", step);
+        throw new AssertionError("roundToStep() does not work accurately with steps smaller than 0.00001", step);
     return Math.round(num / step) * step;
-};
+}
+/**
+ * Round a number to a specified set of decimal places.
+ * - Doesn't include excess `0` zeroes like `num.toFixed()` and `num.toPrecision()` do.
+ *
+ * @param num The number to format.
+ * @param precision Maximum of digits shown after the decimal point (defaults to 10), with zeroes trimmed.
+ * @returns The number formatted as a string in the browser's current locale.
+ */
+export const roundNumber = (num, precision = 10) => new Intl.NumberFormat("en-US", { maximumFractionDigits: precision }).format(num);
 /**
  * Format a number (based on the user's browser settings).
  * @param num The number to format.
@@ -66,3 +57,11 @@ export const formatNumber = (num, precision = 10) => new Intl.NumberFormat(undef
  * @param end The end of the range, e.g. `20`
  */
 export const isBetween = (num, start, end) => num >= start && num <= end;
+/**
+ *  Apply a min/max to a number to return a number that's definitely in the specified range.
+ *
+ * @param num The number to apply the min/max to, e.g. `17`
+ * @param start The start of the range, e.g. `10`
+ * @param end The end of the range, e.g. `20`
+ */
+export const getBetween = (num, start, end) => Math.max(start, Math.min(end, num));