shelving 1.153.0 → 1.154.0

package/package.json

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