shelving 1.175.2 → 1.176.0

package/endpoint/Endpoint.d.ts

@@ -1,7 +1,7 @@
 import { type Schema } from "../schema/Schema.js";
 import { type Data } from "../util/data.js";
 import type { AnyCaller, Arguments } from "../util/function.js";
-import { type OptionalRequestHandler, type RequestMethod, type RequestOptions } from "../util/http.js";
+import { type OptionalRequestHandler, type RequestMethod, type RequestOptions, type RequestParams } from "../util/http.js";
 import { type URLString } from "../util/url.js";
 import type { EndpointCallback } from "./util.js";
 /**
@@ -22,6 +22,13 @@ export declare class Endpoint<P, R> {
     /** Result schema. */
     readonly result: Schema<R>;
     constructor(method: RequestMethod, url: URLString, payload: Schema<P>, result: Schema<R>);
+    /**
+     * Match a request against this endpoint and return the matched `{placeholder}` and `?query` params, or `undefined` otherwise.
+     *
+     * @returns Matched `{placeholder}` params found in the URL path merged with the `?query` params of the URL, or `undefined` if the `Request` does not match this endpoint.
+     * @throws {RequestError} if the request URL is invalid.
+     */
+    match(request: Request, caller?: AnyCaller): RequestParams | undefined;
     /**
      * Return an optional request handler for this endpoint.
      *
@@ -35,7 +42,7 @@ export declare class Endpoint<P, R> {
      * @returns Rendered URL with `{placeholders}` rendered with values from `payload`
      * @throws {RequiredError} if `{placeholders}` are set in the URL but `payload` is not a data object.
      */
-    renderURL(payload: P, caller?: AnyCaller): string;
+    render(payload: P, caller?: AnyCaller): string;
     /**
      * Get an HTTP `Request` object for this endpoint.
      * - Validates a payload against this endpoints payload schema
@@ -47,8 +54,8 @@ export declare class Endpoint<P, R> {
     /**
      * Validate an HTTP `Response` against this endpoint.
      *
-     * @throws `ResponseError` if the response status is not ok (200-299)
-     * @throws `ResponseError` if the response content is invalid.
+     * @throws {ResponseError} if the response status is not ok (200-299)
+     * @throws {ResponseError} if the response content is invalid.
      */
     response(response: Response, caller?: AnyCaller): Promise<R>;
     /**
@@ -56,9 +63,9 @@ export declare class Endpoint<P, R> {
      * - Validate the `payload` against this endpoint's payload schema.
      * - Validate the returned response against this endpoint's result schema.
      *
-     * @throws `string` if the payload is invalid.
-     * @throws `ResponseError` if the response status is not ok (200-299)
-     * @throws `ResponseError` if the response content is invalid.
+     * @throws {string} if the payload is invalid.
+     * @throws {ResponseError} if the response status is not ok (200-299)
+     * @throws {ResponseError} if the response content is invalid.
      */
     fetch(payload: P, options?: RequestOptions, caller?: AnyCaller): Promise<R>;
     /** Convert to string, e.g. `GET https://a.com/user/{id}` */

package/endpoint/Endpoint.js

@@ -32,6 +32,29 @@ export class Endpoint {
         this.payload = payload;
         this.result = result;
     }
+    /**
+     * Match a request against this endpoint and return the matched `{placeholder}` and `?query` params, or `undefined` otherwise.
+     *
+     * @returns Matched `{placeholder}` params found in the URL path merged with the `?query` params of the URL, or `undefined` if the `Request` does not match this endpoint.
+     * @throws {RequestError} if the request URL is invalid.
+     */
+    match(request, caller = this.match) {
+        // Ensure the request method e.g. `GET` matches the endpoint method e.g. `POST`.
+        if (request.method !== this.method)
+            return undefined;
+        // Ensure the request URL e.g. `/user/123` matches the endpoint path e.g. `/user/{id}`.
+        // Any `{placeholders}` in the endpoint path are matched against the request URL to extract parameters.
+        const url = getURL(request.url);
+        if (!url)
+            throw new RequestError("Invalid request URL", { received: request.url, caller });
+        const { origin, pathname, searchParams } = url;
+        // Match the matched params.
+        const pathParams = matchTemplate(this.url, `${origin}${pathname}`, caller);
+        if (!pathParams)
+            return undefined;
+        // Merge the `pathParams` (e.g. `{name}` matched in the path) with the `searchParams` (e.g. `?age` in the query).
+        return searchParams.size ? { ...getDictionary(searchParams), ...pathParams } : pathParams;
+    }
     /**
      * Return an optional request handler for this endpoint.
      *
@@ -39,19 +62,9 @@ export class Endpoint {
      */
     handler(callback) {
         const handler = (request, ...args) => {
-            // Ensure the request method e.g. `GET` matches the endpoint method e.g. `POST`.
-            if (request.method !== this.method)
-                return undefined;
-            // Ensure the request URL e.g. `/user/123` matches the endpoint path e.g. `/user/{id}`.
-            // Any `{placeholders}` in the endpoint path are matched against the request URL to extract parameters.
-            const url = getURL(request.url);
-            if (!url)
-                throw new RequestError("Invalid request URL", { received: request.url, caller: handler });
-            const { origin, pathname } = url;
-            const pathParams = matchTemplate(this.url, `${origin}${pathname}`, handler);
-            if (!pathParams)
-                return undefined;
-            return handleEndpoint(this, callback, request, args, handler);
+            const params = this.match(request, handler);
+            if (params)
+                return handleEndpoint(this, callback, request, args, params, handler);
         };
         return handler;
     }
@@ -62,7 +75,7 @@ export class Endpoint {
      * @returns Rendered URL with `{placeholders}` rendered with values from `payload`
      * @throws {RequiredError} if `{placeholders}` are set in the URL but `payload` is not a data object.
      */
-    renderURL(payload, caller = this.renderURL) {
+    render(payload, caller = this.render) {
         return renderTemplate(this.url, isData(payload) ? payload : {}, caller); // Empty object in `renderTemplate()` will throw intended `RequiredError` for missing `{placeholder}`
     }
     /**
@@ -78,8 +91,8 @@ export class Endpoint {
     /**
      * Validate an HTTP `Response` against this endpoint.
      *
-     * @throws `ResponseError` if the response status is not ok (200-299)
-     * @throws `ResponseError` if the response content is invalid.
+     * @throws {ResponseError} if the response status is not ok (200-299)
+     * @throws {ResponseError} if the response content is invalid.
      */
     async response(response, caller = this.response) {
         // Get the response.
@@ -103,9 +116,9 @@ export class Endpoint {
      * - Validate the `payload` against this endpoint's payload schema.
      * - Validate the returned response against this endpoint's result schema.
      *
-     * @throws `string` if the payload is invalid.
-     * @throws `ResponseError` if the response status is not ok (200-299)
-     * @throws `ResponseError` if the response content is invalid.
+     * @throws {string} if the payload is invalid.
+     * @throws {ResponseError} if the response status is not ok (200-299)
+     * @throws {ResponseError} if the response content is invalid.
      */
     async fetch(payload, options = {}, caller = this.fetch) {
         const response = await fetch(this.request(payload, options, caller));
@@ -122,19 +135,10 @@ export class Endpoint {
  * @param callback The endpoint callback function that implements the logic for this endpoint by receiving the payload and returning the response.
  * @param request The entire HTTP request that is being handled (payload was possibly extracted from this somehow).
  *
- * @throws `string` if the payload is invalid.
- * @throws `ValueError` if `callback()` returns an invalid result.
+ * @throws {string} if the payload is invalid.
+ * @throws {ValueError} if `callback()` returns an invalid result.
  */
-async function handleEndpoint(endpoint, callback, request, args, caller = handleEndpoint) {
-    // Parse URL and collect path/query params for payload merging.
-    const url = getURL(request.url);
-    if (!url)
-        throw new RequestError("Invalid request URL", { received: request.url, caller });
-    const { origin, pathname, searchParams } = url;
-    const pathParams = matchTemplate(endpoint.url, `${origin}${pathname}`, caller);
-    if (!pathParams)
-        throw new RequestError("Invalid endpoint route", { received: request.url, endpoint, caller });
-    const params = searchParams.size ? { ...getDictionary(searchParams), ...pathParams } : pathParams;
+async function handleEndpoint(endpoint, callback, request, args, params, caller = handleEndpoint) {
     // Extract a data object from the request body and combine it with URL params.
     const content = await getRequestContent(request, caller);
     const unsafePayload = content === undefined ? params : isPlainObject(content) ? { ...content, ...params } : content;

package/package.json

@@ -11,7 +11,7 @@
 		"state-management",
 		"query-builder"
 	],
-	"version": "1.175.2",
+	"version": "1.176.0",
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/dhoulb/shelving.git"
@@ -59,7 +59,7 @@
 		"build:test:unit": "bun test ./dist/**/*.test.js --bail"
 	},
 	"devDependencies": {
-		"@biomejs/biome": "^2.4.6",
+		"@biomejs/biome": "^2.4.7",
 		"@google-cloud/firestore": "^8.3.0",
 		"@types/bun": "^1.3.10",
 		"@types/react": "^19.2.14",

package/util/data.d.ts

@@ -1,7 +1,9 @@
+import type { UnionToIntersection } from "@google-cloud/firestore";
 import type { ImmutableArray } from "./array.js";
 import type { EntryObject } from "./entry.js";
 import type { AnyCaller } from "./function.js";
 import type { DeepPartial } from "./object.js";
+import type { Resolve } from "./types.js";
 /** Data object. */
 export type Data = {
     readonly [K in string]: unknown;
@@ -10,11 +12,14 @@ export type Data = {
 export type PartialData<T extends Data> = {
     readonly [K in keyof T]?: T[K] | undefined;
 };
-/** Key for a data object prop. */
+/** Helper type to get the key for for a data object prop. */
 export type DataKey<T extends Data> = keyof T & string;
-/** Value for a data object prop. */
-export type DataValue<T extends Data> = T[keyof T & string];
-/** Prop for a data object. */
+/** Helper type to get the value for a data object prop. */
+export type DataValue<T extends Data> = T[DataKey<T>];
+/**
+ * Helper type to get a prop for a data object.
+ * i.e. `DataProp<{ a: number }>` produces `readonly ["a", number"]`
+ */
 export type DataProp<T extends Data> = {
     readonly [K in DataKey<T>]: readonly [K, T[K]];
 }[DataKey<T>];
@@ -23,31 +28,43 @@ export type Database = {
     readonly [K in string]: Data;
 };
 /**
- * Flattened data object with every branch node of the data, flattened into `a.c.b` format.
- * - Includes all branches, i.e. `{ a: { a2: number } }` will be `{ "a": object, "a.a2": number }`
+ * Helper type to get a flattened data object with every branch node of the data, flattened into `a.c.b` format.
+ * i.e. `BranchData<{ a: { a2: number } }>` produces `{ "a": object, "a.a2": number }`
  */
 export type BranchData<T extends Data> = EntryObject<BranchProp<T>>;
-/** Key for a flattened data object with deep keys flattened into `a.c.b` format. */
+/** Helper type to get the key for a flattened data object with deep keys flattened into `a.c.b` format. */
 export type BranchKey<T extends Data> = BranchProp<T>[0];
-/** Value for a flattened data object with deep keys flattened into `a.c.b` format. */
+/** Helper type to get the value for a flattened data object with deep keys flattened into `a.c.b` format. */
 export type BranchValue<T extends Data> = BranchProp<T>[1];
-/** Prop for a flattened data object with deep keys flattened into `a.c.b` format. */
+/** Helper type to get the prop for a flattened data object with deep keys flattened into `a.c.b` format. */
 export type BranchProp<T extends Data> = {
     readonly [K in DataKey<T>]: (T[K] extends Data ? readonly [null, T[K]] | BranchProp<T[K]> : readonly [null, T[K]]) extends infer E ? E extends readonly [infer KK, infer VV] ? readonly [KK extends string ? `${K}.${KK}` : K, VV] : never : never;
 }[DataKey<T>];
 /**
- * Flattened data object with only leaf nodes of the data, flattened into `a.c.b` format.
- * - Only include leaf nodes, i.e. `{ a: { a2: number } }` will be `{ "a.a2": number }`
+ * Helper type to get a flattened data object with only leaf nodes of the data, flattened into `a.c.b` format.
+ * i.e. `LeafData<{ a: { a2: number } }>` produces `{ "a.a2": number }`
  */
 export type LeafData<T extends Data> = EntryObject<LeafProp<T>>;
-/** Key for a flattened data object with deep keys flattened into `a.c.b` format. */
+/** Helper type to get the leaf keys for a flattened data object with deep keys flattened into `a.c.b` format. */
 export type LeafKey<T extends Data> = LeafProp<T>[0];
-/** Value for a flattened data object with deep keys flattened into `a.c.b` format. */
+/** Helper type to get the leaf values for a flattened data object with deep keys flattened into `a.c.b` format. */
 export type LeafValue<T extends Data> = LeafProp<T>[1];
-/** Prop for a flattened data object with deep keys flattened into `a.c.b` format. */
+/** Helper type to get the leaf props for a flattened data object with deep keys flattened into `a.c.b` format. */
 export type LeafProp<T extends Data> = {
     readonly [K in DataKey<T>]: (T[K] extends Data ? LeafProp<T[K]> : readonly [null, T[K]]) extends infer E ? E extends readonly [infer KK, infer VV] ? readonly [KK extends string ? `${K}.${KK}` : K, VV] : never : never;
 }[DataKey<T>];
+/**
+ * Object with one level of data nested beneath each prop.
+ * i.e. `{ A: { a: number }, B: { b: string } }`
+ */
+export type NestedData = {
+    readonly [key: string]: Data;
+};
+/**
+ * Helper type to flatten one level of nested data into a single flat `Data` type.
+ * i.e. `FlattenData<{ A: { a: number }, B: { b: string } }>` produces `{ a: number, b: string }`
+ */
+export type FlattenData<T extends NestedData> = Resolve<UnionToIntersection<T[keyof T]>>;
 /** Is an unknown value a data object? */
 export declare function isData(value: unknown): value is Data;
 /** Assert that an unknown value is a data object. */

package/util/duration.d.ts

@@ -111,7 +111,7 @@ export declare function isToday(target: PossibleDate, current?: PossibleDate, ca
  * - Makes a sensible choice about the best time unit to use.
  * - Years will be used for anything 18 months or more, e.g. `in 2 years`
  * - Months will be used for anything 10 weeks or more, e.g. `in 14 months`
- * - Weeks will be used for anything 2 weeks or more, e.g. `in 9 weeks`
+ * - Weeks will be used for anything 10 days or more, e.g. `in 9 weeks`
  * - Days will be used for anything 1 day or more, e.g. `in 13 days`
  * - Hours will be used for anything 1 hour or more, e.g. `in 23 hours`
  * - Minutes will be used for anything 1 minute or more, e.g. `1 minute ago` or `in 59 minutes`

package/util/duration.js

@@ -155,7 +155,7 @@ export function isToday(target, current, caller = isToday) {
  * - Makes a sensible choice about the best time unit to use.
  * - Years will be used for anything 18 months or more, e.g. `in 2 years`
  * - Months will be used for anything 10 weeks or more, e.g. `in 14 months`
- * - Weeks will be used for anything 2 weeks or more, e.g. `in 9 weeks`
+ * - Weeks will be used for anything 10 days or more, e.g. `in 9 weeks`
  * - Days will be used for anything 1 day or more, e.g. `in 13 days`
  * - Hours will be used for anything 1 hour or more, e.g. `in 23 hours`
  * - Minutes will be used for anything 1 minute or more, e.g. `1 minute ago` or `in 59 minutes`
@@ -163,17 +163,19 @@ export function isToday(target, current, caller = isToday) {
  */
 export function getBestTimeUnit(ms) {
     const abs = Math.abs(ms);
-    if (abs > 18 * MONTH)
+    if (abs >= 18 * MONTH)
         return TIME_UNITS.require("year");
-    if (abs > 10 * WEEK)
+    if (abs >= 10 * WEEK)
         return TIME_UNITS.require("month");
-    if (abs > DAY)
+    if (abs >= 10 * DAY)
+        return TIME_UNITS.require("week");
+    if (abs >= DAY)
         return TIME_UNITS.require("day");
-    if (abs > HOUR)
+    if (abs >= HOUR)
         return TIME_UNITS.require("hour");
-    if (abs > MINUTE)
+    if (abs >= MINUTE)
         return TIME_UNITS.require("minute");
-    if (abs > SECOND)
+    if (abs >= SECOND)
         return TIME_UNITS.require("second");
     return TIME_UNITS.require("millisecond");
 }

package/util/entry.d.ts

@@ -7,11 +7,14 @@ import type { ImmutableSet } from "./set.js";
  * - Always readonly.
  */
 export type Entry<K = unknown, T = unknown> = readonly [K, T];
-/** Extract the type for the value of an entry. */
+/** Helper type to extract the type for the value of an entry. */
 export type EntryKey<X> = X extends Entry<infer Y, unknown> ? Y : never;
-/** Extract the type for the value of an entry. */
+/** Helper type to extract the type for the value of an entry. */
 export type EntryValue<X> = X extends Entry<unknown, infer Y> ? Y : never;
-/** Convert an entry back into an object. */
+/**
+ * Helper type to turn an entry back into an object with one property.
+ * i.e. `EntryObject<Entry<"a", string>>` produces `{ a: string }`
+ */
 export type EntryObject<T extends Entry<PropertyKey, unknown>> = {
     readonly [E in T as E[0]]: E[1];
 };

package/util/http.d.ts

@@ -1,6 +1,7 @@
 import { RequestError } from "../error/RequestError.js";
 import { ResponseError } from "../error/ResponseError.js";
 import { type Data } from "./data.js";
+import type { ImmutableDictionary } from "./dictionary.js";
 import type { AnyCaller, Arguments } from "./function.js";
 import type { URLString } from "./url.js";
 /** A handler function takes a `Request` and optional extra arguments and returns a `Response` (possibly asynchronously). */
@@ -63,6 +64,8 @@ export type RequestHeadMethod = "HEAD" | "GET";
 export type RequestBodyMethod = "POST" | "PUT" | "PATCH" | "DELETE";
 /** Configurable options for endpoint. */
 export type RequestOptions = Omit<RequestInit, "method" | "body">;
+/** Params in requests are a dictionary of strings. */
+export type RequestParams = ImmutableDictionary<string>;
 /**
  * Create a `Request` instance for a method/url and payload.
  *

package/util/types.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Helper type to turn a union type into an intersection type.
+ * i.e. `A & B` becomes `A | B`
+ */
+export type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+/**
+ * Helper type to resolve and normalise an object.
+ * i.e. `{ a: string } & { b: number }` becomes `{ a: string, b: number }`
+ */
+export type Resolve<T> = {
+    [K in keyof T]: T[K];
+};

package/util/types.js

@@ -0,0 +1 @@
+export {};