shelving 1.153.0 → 1.154.1

package/package.json

@@ -11,7 +11,7 @@
 		"state-management",
 		"query-builder"
 	],
-	"version": "1.153.0",
+	"version": "1.154.1",
 	"repository": "https://github.com/dhoulb/shelving",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"license": "0BSD",
@@ -58,14 +58,14 @@
 	},
 	"devDependencies": {
 		"@biomejs/biome": "^1.9.4",
-		"@google-cloud/firestore": "^7.11.3",
-		"@types/bun": "^1.2.20",
-		"@types/react": "^19.1.11",
-		"@types/react-dom": "^19.1.7",
+		"@google-cloud/firestore": "^7.11.6",
+		"@types/bun": "^1.2.23",
+		"@types/react": "^19.1.16",
+		"@types/react-dom": "^19.1.9",
 		"firebase": "^11.10.0",
 		"react": "^19.1.1",
 		"react-dom": "^19.1.1",
-		"typescript": "^5.9.2"
+		"typescript": "^5.9.3"
 	},
 	"peerDependencies": {
 		"@google-cloud/firestore": ">=7.0.0",

package/schema/DateSchema.js

@@ -1,5 +1,5 @@
 import { ValueFeedback } from "../feedback/Feedback.js";
-import { getDate, requireYMD } from "../util/date.js";
+import { getDate, requireDateString } from "../util/date.js";
 import { formatDate } from "../util/format.js";
 import { NULLABLE } from "./NullableSchema.js";
 import { Schema } from "./Schema.js";
@@ -24,7 +24,7 @@ export class DateSchema extends Schema {
         return this.stringify(date);
     }
     stringify(value) {
-        return requireYMD(value);
+        return requireDateString(value);
     }
     format(value) {
         return formatDate(value);

package/schema/DateTimeSchema.d.ts

@@ -2,7 +2,12 @@ import { DateSchema, type DateSchemaOptions } from "./DateSchema.js";
 /** Allowed options for `DateSchema` */
 export interface DateTimeSchemaOptions extends DateSchemaOptions {
 }
-/** Define a valid date in ISO 8601 format, e.g. `2005-09-12T18:15:00.000Z` */
+/**
+ * Define a valid UTC date in ISO 8601 format, e.g. `2005-09-12T18:15:00.000Z`
+ * - The date includes the `Z` suffix to indicate UTC time, this ensures consistent transfer of the date between client and server.
+ * - If you wish to define an _abstract_ date without a timezone, e.g. a birthday or anniversary, use `DateSchema` instead.
+ * - If you wish to define an _abstract_ time without a timezone, e.g. a daily alarm, use `TimeSchema` instead.
+ */
 export declare class DateTimeSchema extends DateSchema {
     format(value: Date): string;
     stringify(value: Date): string;

package/schema/DateTimeSchema.js

@@ -1,7 +1,12 @@
 import { formatDateTime } from "../util/format.js";
 import { DateSchema } from "./DateSchema.js";
 import { NULLABLE } from "./NullableSchema.js";
-/** Define a valid date in ISO 8601 format, e.g. `2005-09-12T18:15:00.000Z` */
+/**
+ * Define a valid UTC date in ISO 8601 format, e.g. `2005-09-12T18:15:00.000Z`
+ * - The date includes the `Z` suffix to indicate UTC time, this ensures consistent transfer of the date between client and server.
+ * - If you wish to define an _abstract_ date without a timezone, e.g. a birthday or anniversary, use `DateSchema` instead.
+ * - If you wish to define an _abstract_ time without a timezone, e.g. a daily alarm, use `TimeSchema` instead.
+ */
 export class DateTimeSchema extends DateSchema {
     format(value) {
         return formatDateTime(value);

package/schema/TimeSchema.js

@@ -1,5 +1,5 @@
 import { ValueFeedback } from "../feedback/Feedback.js";
-import { getDate, requireTime } from "../util/date.js";
+import { getDate, requireTimeString } from "../util/date.js";
 import { formatTime } from "../util/format.js";
 import { roundStep } from "../util/number.js";
 import { DateSchema } from "./DateSchema.js";
@@ -24,7 +24,7 @@ export class TimeSchema extends DateSchema {
             throw new ValueFeedback(`Maximum ${formatTime(this.max)}`, rounded);
         if (this.min && rounded < this.min)
             throw new ValueFeedback(`Minimum ${formatTime(this.min)}`, rounded);
-        return requireTime(rounded);
+        return requireTimeString(rounded);
     }
 }
 /** Valid time, e.g. `2005-09-12` (required because falsy values are invalid). */

package/util/date.d.ts

@@ -44,14 +44,18 @@ export declare function requireDate(value?: PossibleDate, caller?: AnyCaller): D
 export declare function getTimestamp(value?: unknown): number | undefined;
 /** Convert a possible date to a timestamp (milliseconds past Unix epoch), or throw `RequiredError` if it couldn't be converted. */
 export declare function requireTimestamp(value?: PossibleDate): number;
-/** Convert an unknown value to a YMD date string like "2015-09-12", or `undefined` if it couldn't be converted. */
-export declare function getYMD(value?: unknown): string | undefined;
-/** Convert a possible `Date` instance to a YMD string like "2015-09-12", or throw `RequiredError` if it couldn't be converted.  */
-export declare function requireYMD(value?: PossibleDate, caller?: AnyCaller): string;
-/** Convert an unknown value to a HMS time string like "18:32:00", or `undefined` if it couldn't be converted. */
-export declare function getTime(value?: unknown): string | undefined;
-/** Convert a possible `Date` instance to an HMS string like "18:32:00", or throw `RequiredError` if it couldn't be converted. */
-export declare function requireTime(value?: PossibleDate, caller?: AnyCaller): string;
+/** Convert an unknown value to a local date string like "2015-09-12T18:30:00", or `undefined` if it couldn't be converted. */
+export declare function getDateTimeString(value?: unknown): string | undefined;
+/** Convert a possible `Date` instance to a local YMD string like "2015-09-12T18:30:00", or throw `RequiredError` if it couldn't be converted.  */
+export declare function requireDateTimeString(value?: PossibleDate, caller?: AnyCaller): string;
+/** Convert an unknown value to a local date string like "2015-09-12", or `undefined` if it couldn't be converted. */
+export declare function getDateString(value?: unknown): string | undefined;
+/** Convert a possible `Date` instance to a local date string like "2015-09-12", or throw `RequiredError` if it couldn't be converted.  */
+export declare function requireDateString(value?: PossibleDate, caller?: AnyCaller): string;
+/** Convert an unknown value to a local time string like "18:32:00", or `undefined` if it couldn't be converted. */
+export declare function getTimeString(value?: unknown): string | undefined;
+/** Convert a possible `Date` instance to local time string like "18:32:00", or throw `RequiredError` if it couldn't be converted. */
+export declare function requireTimeString(value?: PossibleDate, caller?: AnyCaller): string;
 /** List of day-of-week strings. */
 export declare const DAYS: readonly ["sunday", "monday", "tuesday", "wednesday", "thursday", "friday", "saturday"];
 /** Type listing day-of-week strings. */

package/util/date.js

@@ -46,7 +46,7 @@ export function getDate(value) {
         const date = new Date(value);
         if (Number.isFinite(date.getTime()))
             return date;
-        const time = new Date(`${requireYMD()}T${value}`);
+        const time = new Date(`${requireDateString()}T${value}`);
         if (Number.isFinite(time.getTime()))
             return time;
     }
@@ -92,31 +92,48 @@ export function getTimestamp(value) {
 export function requireTimestamp(value) {
     return requireDate(value, requireTimestamp).getTime();
 }
-/** Convert an unknown value to a YMD date string like "2015-09-12", or `undefined` if it couldn't be converted. */
-export function getYMD(value) {
+// Helpers.
+function _pad(num, length = 2) {
+    return num.toString().padStart(length, "0");
+}
+function _date(date) {
+    return `${_pad(date.getFullYear(), 4)}-${_pad(date.getMonth() + 1)}-${_pad(date.getDate())}`;
+}
+function _time(date) {
+    return `${_pad(date.getHours())}:${_pad(date.getMinutes())}:${_pad(date.getSeconds())}`;
+}
+function _datetime(date) {
+    return `${_date(date)}T${_time(date)}`;
+}
+/** Convert an unknown value to a local date string like "2015-09-12T18:30:00", or `undefined` if it couldn't be converted. */
+export function getDateTimeString(value) {
     const date = getDate(value);
     if (date)
-        return _ymd(date);
+        return _datetime(date);
 }
-/** Convert a possible `Date` instance to a YMD string like "2015-09-12", or throw `RequiredError` if it couldn't be converted.  */
-export function requireYMD(value, caller = requireYMD) {
-    return _ymd(requireDate(value, caller));
+/** Convert a possible `Date` instance to a local YMD string like "2015-09-12T18:30:00", or throw `RequiredError` if it couldn't be converted.  */
+export function requireDateTimeString(value, caller = requireDateTimeString) {
+    return _datetime(requireDate(value, caller));
 }
-function _ymd(date) {
-    return date.toISOString().slice(0, 10);
-}
-/** Convert an unknown value to a HMS time string like "18:32:00", or `undefined` if it couldn't be converted. */
-export function getTime(value) {
+/** Convert an unknown value to a local date string like "2015-09-12", or `undefined` if it couldn't be converted. */
+export function getDateString(value) {
     const date = getDate(value);
     if (date)
-        return _hms(date);
+        return _date(date);
+}
+/** Convert a possible `Date` instance to a local date string like "2015-09-12", or throw `RequiredError` if it couldn't be converted.  */
+export function requireDateString(value, caller = requireDateString) {
+    return _date(requireDate(value, caller));
 }
-/** Convert a possible `Date` instance to an HMS string like "18:32:00", or throw `RequiredError` if it couldn't be converted. */
-export function requireTime(value, caller = requireTime) {
-    return _hms(requireDate(value, caller));
+/** Convert an unknown value to a local time string like "18:32:00", or `undefined` if it couldn't be converted. */
+export function getTimeString(value) {
+    const date = getDate(value);
+    if (date)
+        return _time(date);
 }
-function _hms(date) {
-    return date.toISOString().slice(11, 19);
+/** Convert a possible `Date` instance to local time string like "18:32:00", or throw `RequiredError` if it couldn't be converted. */
+export function requireTimeString(value, caller = requireTimeString) {
+    return _time(requireDate(value, caller));
 }
 /** List of day-of-week strings. */
 export const DAYS = ["sunday", "monday", "tuesday", "wednesday", "thursday", "friday", "saturday"];

package/util/http.d.ts

@@ -9,41 +9,25 @@ export declare function _getMessageContent(message: Request | Response, MessageE
 /**
  * Get the body content of an HTTP `Request` based on its content type, or throw `RequestError` if the content could not be parsed.
  *
+ * @returns undefined If the request method is `GET` or `HEAD` (these request methods have no body).
  * @returns unknown If content type is `application/json` and has valid JSON (including `undefined` if the content is empty).
  * @returns unknown If content type is `multipart/form-data` then convert it to a simple `Data` object.
  * @returns string If content type is `text/plain` or anything else (including `""` empty string if it's empty).
  *
  * @throws RequestError if the content is not `text/plain`, or `application/json` with valid JSON.
  */
-export declare function getRequestContent(message: Request, caller?: AnyCaller): Promise<unknown>;
+export declare function getRequestContent(request: Request, caller?: AnyCaller): Promise<unknown>;
 /**
  * Get the body content of an HTTP `Response` based on its content type, or throw `ResponseError` if the content could not be parsed.
  *
+ * @returns undefined If the request status is `204 No Content` (this response has no body).
  * @returns unknown If content type is `application/json` and has valid JSON (including `undefined` if the content is empty).
  * @returns unknown If content type is `multipart/form-data` then convert it to a simple `Data` object.
  * @returns string If content type is `text/plain` or anything else (including `""` empty string if it's empty).
  *
  * @throws RequestError if the content is not `text/plain` or `application/json` with valid JSON.
  */
-export declare function getResponseContent(message: Response, caller?: AnyCaller): Promise<unknown>;
-/**
- * Get the body content of an HTTP `Request` as JSON, or throw `RequestError` if the content could not be parsed.
- * - Doesn't check the `Content-Type` header, so it can be used for any request.
- *
- * @returns unknown The parsed JSON content of the request body, or `undefined` if the body is empty.
- *
- * @throws RequestError if the content is not valid JSON.
- */
-export declare function getRequestJSON(message: Request, caller?: AnyCaller): Promise<unknown>;
-/**
- * Get the body content of an HTTP `Response` as JSON, or throw `ResponseError` if the content could not be parsed.
- * - Doesn't check the `Content-Type` header, so it can be used for any response.
- *
- * @returns unknown The parsed JSON content of the response body, or `undefined` if the body is empty.
- *
- * @throws RequestError if the content is not valid JSON.
- */
-export declare function getResponseJSON(message: Response, caller?: AnyCaller): Promise<unknown>;
+export declare function getResponseContent(response: Response, caller?: AnyCaller): Promise<unknown>;
 /**
  * Get an HTTP `Response` for an unknown value.
  *

package/util/http.js

@@ -24,59 +24,47 @@ export async function _getMessageFormData(message, MessageError, caller) {
 }
 export function _getMessageContent(message, MessageError, caller) {
     const type = message.headers.get("Content-Type");
+    if (!type || type?.startsWith("text/"))
+        return message.text();
     if (type?.startsWith("application/json"))
         return _getMessageJSON(message, MessageError, caller);
     if (type?.startsWith("multipart/form-data"))
         return _getMessageFormData(message, MessageError, caller);
-    return message.text();
+    throw new MessageError("Content-Type must be text/*, application/json, or multipart/form-data", { received: type, caller });
 }
 /**
  * Get the body content of an HTTP `Request` based on its content type, or throw `RequestError` if the content could not be parsed.
  *
+ * @returns undefined If the request method is `GET` or `HEAD` (these request methods have no body).
  * @returns unknown If content type is `application/json` and has valid JSON (including `undefined` if the content is empty).
  * @returns unknown If content type is `multipart/form-data` then convert it to a simple `Data` object.
  * @returns string If content type is `text/plain` or anything else (including `""` empty string if it's empty).
  *
  * @throws RequestError if the content is not `text/plain`, or `application/json` with valid JSON.
  */
-export function getRequestContent(message, caller = getRequestContent) {
-    if (message.method === "GET" || message.method === "HEAD")
+export function getRequestContent(request, caller = getRequestContent) {
+    const { method } = request;
+    // The HTTP/1.1 RFC 7231 does not forbid sending a body in GET or HEAD requests, but it is uncommon and not recommended because many servers, proxies, and caches may ignore or mishandle it.
+    if (method === "GET" || method === "HEAD")
         return Promise.resolve(undefined);
-    return _getMessageContent(message, RequestError, caller);
+    return _getMessageContent(request, RequestError, caller);
 }
 /**
  * Get the body content of an HTTP `Response` based on its content type, or throw `ResponseError` if the content could not be parsed.
  *
+ * @returns undefined If the request status is `204 No Content` (this response has no body).
  * @returns unknown If content type is `application/json` and has valid JSON (including `undefined` if the content is empty).
  * @returns unknown If content type is `multipart/form-data` then convert it to a simple `Data` object.
  * @returns string If content type is `text/plain` or anything else (including `""` empty string if it's empty).
  *
  * @throws RequestError if the content is not `text/plain` or `application/json` with valid JSON.
  */
-export function getResponseContent(message, caller = getResponseContent) {
-    return _getMessageContent(message, ResponseError, caller);
-}
-/**
- * Get the body content of an HTTP `Request` as JSON, or throw `RequestError` if the content could not be parsed.
- * - Doesn't check the `Content-Type` header, so it can be used for any request.
- *
- * @returns unknown The parsed JSON content of the request body, or `undefined` if the body is empty.
- *
- * @throws RequestError if the content is not valid JSON.
- */
-export function getRequestJSON(message, caller = getRequestJSON) {
-    return _getMessageJSON(message, RequestError, caller);
-}
-/**
- * Get the body content of an HTTP `Response` as JSON, or throw `ResponseError` if the content could not be parsed.
- * - Doesn't check the `Content-Type` header, so it can be used for any response.
- *
- * @returns unknown The parsed JSON content of the response body, or `undefined` if the body is empty.
- *
- * @throws RequestError if the content is not valid JSON.
- */
-export function getResponseJSON(message, caller = getResponseJSON) {
-    return _getMessageJSON(message, ResponseError, caller);
+export function getResponseContent(response, caller = getResponseContent) {
+    const { status } = response;
+    // RFC 7230 Section 3.3.3: A server MUST NOT send a Content-Length header field in any response with a status code of 1xx (Informational), 204 (No Content), or 304 (Not Modified).
+    if ((status >= 100 && status < 200) || status === 204 || status === 304)
+        return Promise.resolve(undefined);
+    return _getMessageContent(response, ResponseError, caller);
 }
 /**
  * Get an HTTP `Response` for an unknown value.