shelving 1.152.0 → 1.152.2

package/api/Endpoint.d.ts

@@ -1,4 +1,4 @@
-import type { Path } from "../util/path.js";
+import type { AbsolutePath } from "../util/path.js";
 import { type Validator } from "../util/validate.js";
 import type { EndpointCallback, EndpointHandler } from "./util.js";
 /** Types for an HTTP request or response that does something. */
@@ -15,12 +15,12 @@ export declare class Endpoint<P, R> {
     /** Endpoint method. */
     readonly method: EndpointMethod;
     /** Endpoint path, e.g. `/patient/{id}` */
-    readonly path: Path;
+    readonly path: AbsolutePath;
     /** Payload validator. */
     readonly payload: Validator<P>;
     /** Result validator. */
     readonly result: Validator<R>;
-    constructor(method: EndpointMethod, path: Path, payload: Validator<P>, result: Validator<R>);
+    constructor(method: EndpointMethod, path: AbsolutePath, payload: Validator<P>, result: Validator<R>);
     /**
      * Return an `EndpointHandler` for this endpoint.
      *
@@ -46,34 +46,34 @@ export type EndpointType<X extends Endpoint<unknown, unknown>> = X extends Endpo
  * Represent a GET request to a specified path, with validated payload and return types.
  * "The GET method requests a representation of the specified resource. Requests using GET should only retrieve data and should not contain a request content."
  */
-export declare function GET<P, R>(path: Path, payload?: Validator<P>, result?: Validator<R>): Endpoint<P, R>;
-export declare function GET<P>(path: Path, payload: Validator<P>): Endpoint<P, undefined>;
-export declare function GET<R>(path: Path, payload: undefined, result: Validator<R>): Endpoint<undefined, R>;
+export declare function GET<P, R>(path: AbsolutePath, payload?: Validator<P>, result?: Validator<R>): Endpoint<P, R>;
+export declare function GET<P>(path: AbsolutePath, payload: Validator<P>): Endpoint<P, undefined>;
+export declare function GET<R>(path: AbsolutePath, payload: undefined, result: Validator<R>): Endpoint<undefined, R>;
 /**
  * Represent a POST request to a specified path, with validated payload and return types.
  * "The POST method submits an entity to the specified resource, often causing a change in state or side effects on the server.
  */
-export declare function POST<P, R>(path: Path, payload?: Validator<P>, result?: Validator<R>): Endpoint<P, R>;
-export declare function POST<P>(path: Path, payload: Validator<P>): Endpoint<P, undefined>;
-export declare function POST<R>(path: Path, payload: undefined, result: Validator<R>): Endpoint<undefined, R>;
+export declare function POST<P, R>(path: AbsolutePath, payload?: Validator<P>, result?: Validator<R>): Endpoint<P, R>;
+export declare function POST<P>(path: AbsolutePath, payload: Validator<P>): Endpoint<P, undefined>;
+export declare function POST<R>(path: AbsolutePath, payload: undefined, result: Validator<R>): Endpoint<undefined, R>;
 /**
  * Represent a PUT request to a specified path, with validated payload and return types.
  * "The PUT method replaces all current representations of the target resource with the request content."
  */
-export declare function PUT<P, R>(path: Path, payload?: Validator<P>, result?: Validator<R>): Endpoint<P, R>;
-export declare function PUT<P>(path: Path, payload: Validator<P>): Endpoint<P, undefined>;
-export declare function PUT<R>(path: Path, payload: undefined, result: Validator<R>): Endpoint<undefined, R>;
+export declare function PUT<P, R>(path: AbsolutePath, payload?: Validator<P>, result?: Validator<R>): Endpoint<P, R>;
+export declare function PUT<P>(path: AbsolutePath, payload: Validator<P>): Endpoint<P, undefined>;
+export declare function PUT<R>(path: AbsolutePath, payload: undefined, result: Validator<R>): Endpoint<undefined, R>;
 /**
  * Represent a PATCH request to a specified path, with validated payload and return types.
  * "The PATCH method applies partial modifications to a resource."
  */
-export declare function PATCH<P, R>(path: Path, payload?: Validator<P>, result?: Validator<R>): Endpoint<P, R>;
-export declare function PATCH<P>(path: Path, payload: Validator<P>): Endpoint<P, undefined>;
-export declare function PATCH<R>(path: Path, payload: undefined, result: Validator<R>): Endpoint<undefined, R>;
+export declare function PATCH<P, R>(path: AbsolutePath, payload?: Validator<P>, result?: Validator<R>): Endpoint<P, R>;
+export declare function PATCH<P>(path: AbsolutePath, payload: Validator<P>): Endpoint<P, undefined>;
+export declare function PATCH<R>(path: AbsolutePath, payload: undefined, result: Validator<R>): Endpoint<undefined, R>;
 /**
  * Represent a DELETE request to a specified path, with validated payload and return types.
  * "The DELETE method deletes the specified resource."
  */
-export declare function DELETE<P, R>(path: Path, payload?: Validator<P>, result?: Validator<R>): Endpoint<P, R>;
-export declare function DELETE<P>(path: Path, payload: Validator<P>): Endpoint<P, undefined>;
-export declare function DELETE<R>(path: Path, payload: undefined, result: Validator<R>): Endpoint<undefined, R>;
+export declare function DELETE<P, R>(path: AbsolutePath, payload?: Validator<P>, result?: Validator<R>): Endpoint<P, R>;
+export declare function DELETE<P>(path: AbsolutePath, payload: Validator<P>): Endpoint<P, undefined>;
+export declare function DELETE<R>(path: AbsolutePath, payload: undefined, result: Validator<R>): Endpoint<undefined, R>;

package/api/util.js

@@ -32,9 +32,9 @@ export function handleEndpoints(request, endpoints) {
         if (!pathParams)
             continue;
         // Make a simple dictionary object from the `{placeholder}` path params and the `?a=123` query params from the URL.
-        const params = searchParams.size ? { ...getDictionary(searchParams), ...pathParams } : pathParams;
+        const combinedParams = searchParams.size ? { ...getDictionary(searchParams), ...pathParams } : pathParams;
         // Get the response by calling the callback.
-        return handleEndpoint(endpoint, callback, params, request);
+        return handleEndpoint(endpoint, callback, combinedParams, request);
     }
     // No handler matched the request.
     throw new NotFoundError("No matching endpoint", { received: requestUrl, caller: handleEndpoints });

package/package.json

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

package/util/template.d.ts

@@ -1,20 +1,18 @@
 import type { ImmutableArray } from "./array.js";
 import { type ImmutableDictionary } from "./dictionary.js";
 import type { AnyCaller } from "./function.js";
-import type { NotString } from "./string.js";
-/** Dictionary of named template values in `{ myPlaceholder: "value" }` format. */
-export type TemplateDictionary = ImmutableDictionary<string>;
-/** Callback that returns the right replacement string for a given placeholder. */
-export type TemplateCallback = (placeholder: string) => string;
+import { type NotString, type PossibleString } from "./string.js";
 /**
  * Things that can be converted to the value for a named placeholder.
  *
- * `string` — Single string used for every `{placeholder}`
+ * `PossibleString` — Single string used for every `{placeholder}`
  * `ImmutableArray<string>` — Array of strings (or functions that return strings) used for `*` numbered placeholders e.g. `["John"]`
- * `TemplateValues` — Object containing named strings used for named placeholders, e.g. `{ myPlaceholder: "Ellie" }`
- * `TemplateCallback` — Function that returns the right string for a named `{placeholder}`.v
+ * `ImmutableDictionary<PossibleString>` — Object containing named strings used for named placeholders, e.g. `{ val1: "Ellie", val2: 123 }`
+ * `(placeholder: string) => string` — Function that returns the right string for a named `{placeholder}`.v
  */
-export type TemplateValues = string | ImmutableArray<string> | TemplateDictionary | TemplateCallback;
+export type TemplateValues = PossibleString | ImmutableArray<PossibleString> | ImmutableDictionary<PossibleString> | ((placeholder: string) => string);
+/** The output of matching a template is a dictionary in `{ myPlaceholder: "value" }` format. */
+export type TemplateMatches = ImmutableDictionary<string>;
 /**
  * Get list of placeholders named in a template string.
  *
@@ -32,11 +30,11 @@ export declare function getPlaceholders(template: string): readonly string[];
  *
  * @return An object containing values, e.g. `{ name: "Dave", country: "UK", city: "Manchester" }`, or undefined if target didn't match the template.
  */
-export declare function matchTemplate(template: string, target: string, caller?: AnyCaller): TemplateDictionary | undefined;
+export declare function matchTemplate(template: string, target: string, caller?: AnyCaller): TemplateMatches | undefined;
 /**
  * Match multiple templates against a target string and return the first match.
  */
-export declare function matchTemplates(templates: Iterable<string> & NotString, target: string): TemplateDictionary | undefined;
+export declare function matchTemplates(templates: Iterable<string> & NotString, target: string): TemplateMatches | undefined;
 /**
  * Turn ":year-:month" and `{ year: "2016"... }` etc into "2016-06..." etc.
  *

package/util/template.js

@@ -3,6 +3,7 @@ import { ValueError } from "../error/ValueError.js";
 import { EMPTY_DICTIONARY } from "./dictionary.js";
 import { setMapItem } from "./map.js";
 import { isObject } from "./object.js";
+import { getString } from "./string.js";
 // RegExp to find named variables in several formats e.g. `:a`, `${b}`, `{{c}}` or `{d}`
 const R_PLACEHOLDERS = /(\*|:[a-z][a-z0-9]*|\$\{[a-z][a-z0-9]*\}|\{\{[a-z][a-z0-9]*\}\}|\{[a-z][a-z0-9]*\})/i;
 // Find actual name within template placeholder e.g. `${name}` → `name`
@@ -112,13 +113,18 @@ export function renderTemplate(template, values, caller = renderTemplate) {
     return output;
 }
 function _replaceTemplateKey(key, values, caller) {
-    if (typeof values === "string")
-        return values;
     if (typeof values === "function")
         return values(key);
     if (isObject(values)) {
-        const v = values[key];
-        if (typeof v === "string")
+        // Dictionary or array of values.
+        const v = getString(values[key]);
+        if (v !== undefined)
+            return v;
+    }
+    else {
+        // Single value for all placeholders.
+        const v = getString(values);
+        if (v !== undefined)
             return v;
     }
     throw new RequiredError(`Template key "${key}" must be defined`, { received: values, key, caller });