shelving 1.180.0 → 1.181.0

package/api/endpoint/Endpoint.d.ts

@@ -5,7 +5,7 @@ import type { AnyCaller } from "../../util/function.js";
 import type { RequestMethod, RequestParams } from "../../util/http.js";
 import type { AbsolutePath } from "../../util/path.js";
 import { type TemplatePlaceholders } from "../../util/template.js";
-import type { EndpointCallback, EndpointContext, EndpointHandler } from "./util.js";
+import type { EndpointCallback, EndpointHandler } from "./util.js";
 /**
  * An abstract API resource definition, used to specify types for e.g. serverless functions.
  *
@@ -44,7 +44,7 @@ export declare class Endpoint<P, R> {
      * @param callback The callback function that implements the logic for this endpoint by receiving the payload and returning the response.
      * @returns An `EndpointHandler` object combining this endpoint and the callback into a single typed object.
      */
-    handler<C extends EndpointContext>(callback: EndpointCallback<P, R, C>): EndpointHandler<P, R, C>;
+    handler<C>(callback: EndpointCallback<P, R, C>): EndpointHandler<P, R, C>;
     /** Convert to string, e.g. `GET /user/{id}` */
     toString(): string;
 }

package/api/endpoint/util.d.ts

@@ -1,32 +1,26 @@
 import type { AnyCaller } from "../../util/function.js";
 import { type PossibleURL } from "../../util/url.js";
 import type { Endpoint } from "./Endpoint.js";
-/**
- * The second argument to an `EndpointCallback` is its context.
- * This must contain the `Request` that triggered the callback, but may contain additional details too. */
-export interface EndpointContext {
-    readonly request: Request;
-}
 /**
  * A function that handles an endpoint request, with a payload and returns a result.
  *
  * @param payload The payload for the callback combining the `{placeholders}`, `?search` params, and body content (this has been validated against the Endpoint's payload schema).
  * @param request The original incoming request object.
- * @param args Any additional arguments to pass into the endpoint callback
+ * @param context An additional context argument that can be passed into the callback.
  *
  * @returns {Response} Returning a `Response` object (this will pass back to the client without validation).
  * @returns {R} Returning the return type of the handler (this will be validated against the Endpoint's result schema).
  */
-export type EndpointCallback<P, R, C extends EndpointContext> = (payload: P, context: C) => R | Response | Promise<R | Response>;
+export type EndpointCallback<P, R, C = void> = (payload: P, request: Request, context: C) => R | Response | Promise<R | Response>;
 /** A typed endpoint definition paired with its implementation callback. */
-export interface EndpointHandler<P, R, C extends EndpointContext> {
+export interface EndpointHandler<P, R, C = void> {
     readonly endpoint: Endpoint<P, R>;
     readonly callback: EndpointCallback<P, R, C>;
 }
 /** Any endpoint handler. */
-export type AnyEndpointHandler<C extends EndpointContext = EndpointContext> = EndpointHandler<any, any, C>;
+export type AnyEndpointHandler<C = any> = EndpointHandler<any, any, C>;
 /** A collection of endpoint handlers that can be matched and invoked by `handleEndpoints()`. */
-export type EndpointHandlers<C extends EndpointContext = EndpointContext> = Iterable<AnyEndpointHandler<C>>;
+export type EndpointHandlers<C = void> = Iterable<AnyEndpointHandler<C>>;
 /**
  * Handle a `Request` with the first matching endpoint handler after stripping any base-path prefix from the request pathname.
  * - The original `Request` object is passed through to the callback unchanged.
@@ -37,4 +31,5 @@ export type EndpointHandlers<C extends EndpointContext = EndpointContext> = Iter
  * @param base The base URL for the API, e.g. `https://myapi.com/a/b`
  * - `pathname` of this URL gets trimmed from `request.path` to form the target path when matching against endpoints, e.g. `/a/b/c/d` will produce `/c/d` for matching.
  */
-export declare function handleEndpoints<C extends EndpointContext>(base: PossibleURL, handlers: EndpointHandlers<C>, context: C, caller?: AnyCaller): Promise<Response>;
+export declare function handleEndpoints<C>(base: PossibleURL, handlers: EndpointHandlers<C>, request: Request, context: C, caller?: AnyCaller): Promise<Response>;
+export declare function handleEndpoints(base: PossibleURL, handlers: EndpointHandlers<void>, request: Request, context?: undefined, caller?: AnyCaller): Promise<Response>;

package/api/endpoint/util.js

@@ -4,18 +4,8 @@ import { getDictionary } from "../../util/dictionary.js";
 import { getRequestContent, getResponse, isRequestMethod } from "../../util/http.js";
 import { isPlainObject } from "../../util/object.js";
 import { requireURL } from "../../util/url.js";
-/**
- * Handle a `Request` with the first matching endpoint handler after stripping any base-path prefix from the request pathname.
- * - The original `Request` object is passed through to the callback unchanged.
- * - Path params and query params are merged before payload validation.
- *
- * @param request The input request to handle.
- *
- * @param base The base URL for the API, e.g. `https://myapi.com/a/b`
- * - `pathname` of this URL gets trimmed from `request.path` to form the target path when matching against endpoints, e.g. `/a/b/c/d` will produce `/c/d` for matching.
- */
-export function handleEndpoints(base, handlers, context, caller = handleEndpoints) {
-    const { url, method } = context.request;
+export function handleEndpoints(base, handlers, request, context, caller = handleEndpoints) {
+    const { url, method } = request;
     if (!isRequestMethod(method))
         throw new MethodNotAllowedError("Unsupported request method", { received: method, caller });
     const { origin: baseOrigin, pathname: basePath } = requireURL(base, undefined, caller);
@@ -30,7 +20,7 @@ export function handleEndpoints(base, handlers, context, caller = handleEndpoint
         if (!pathParams)
             continue;
         const params = searchParams.size ? { ...getDictionary(searchParams), ...pathParams } : pathParams;
-        return _handleEndpoint(handler, params, context, handleEndpoints);
+        return _handleEndpoint(handler, params, request, context, handleEndpoints);
     }
     throw new NotFoundError("No matching endpoint", { received: targetPath, caller });
 }
@@ -39,11 +29,11 @@ export function handleEndpoints(base, handlers, context, caller = handleEndpoint
  */
 async function _handleEndpoint({ endpoint, callback }, 
 /** Params we already matched/parsed from the URL. */
-params, context, caller) {
-    const content = await getRequestContent(context.request, caller);
+params, request, context, caller) {
+    const content = await getRequestContent(request, caller);
     const unsafePayload = content === undefined ? params : isPlainObject(content) ? { ...content, ...params } : content;
     const payload = endpoint.payload.validate(unsafePayload);
-    const unsafeResult = await callback(payload, context);
+    const unsafeResult = await callback(payload, request, context);
     if (unsafeResult instanceof Response)
         return unsafeResult;
     try {

package/api/index.d.ts

@@ -6,7 +6,7 @@ export * from "./provider/APIProvider.js";
 export * from "./provider/ClientAPIProvider.js";
 export * from "./provider/DebugAPIProvider.js";
 export * from "./provider/MockAPIProvider.js";
-export * from "./provider/MockEnpdointAPIProvider.js";
+export * from "./provider/MockEndpointAPIProvider.js";
 export * from "./provider/ThroughAPIProvider.js";
 export * from "./provider/ValidationAPIProvider.js";
 export * from "./store/EndpointStore.js";

package/api/index.js

@@ -6,7 +6,7 @@ export * from "./provider/APIProvider.js";
 export * from "./provider/ClientAPIProvider.js";
 export * from "./provider/DebugAPIProvider.js";
 export * from "./provider/MockAPIProvider.js";
-export * from "./provider/MockEnpdointAPIProvider.js";
+export * from "./provider/MockEndpointAPIProvider.js";
 export * from "./provider/ThroughAPIProvider.js";
 export * from "./provider/ValidationAPIProvider.js";
 export * from "./store/EndpointStore.js";

package/api/provider/{MockEnpdointAPIProvider.d.ts → MockEndpointAPIProvider.d.ts}

@@ -1,5 +1,8 @@
-import { type EndpointContext, type EndpointHandlers } from "../endpoint/util.js";
+import { type EndpointHandlers } from "../endpoint/util.js";
 import { MockAPIProvider, type MockAPIProviderOptions } from "./MockAPIProvider.js";
+export interface MockEndpointAPIProviderOptions<C> extends MockAPIProviderOptions {
+    context: C;
+}
 /**
  * Provider that mocks an API that calls and matches an array of `EndpointHandler` objects returned from `Endpoint.handler()`
  * - Used to test server-side API code, calls against an API made up of multiple `Endpoint` instances.
@@ -11,6 +14,6 @@ import { MockAPIProvider, type MockAPIProviderOptions } from "./MockAPIProvider.
  *  const result = await api.fetch(endpoint, 4); // Mock a call to the endpoint through the provider.
  *  expect(result).toBe(16);
  */
-export declare class MockEnpdointAPIProvider<C extends EndpointContext> extends MockAPIProvider {
-    constructor(handlers: EndpointHandlers<C>, c: Omit<EndpointContext, "request">, options: MockAPIProviderOptions);
+export declare class MockEndpointAPIProvider<C> extends MockAPIProvider {
+    constructor(handlers: EndpointHandlers<C>, { context, ...options }: MockEndpointAPIProviderOptions<C>);
 }

package/api/provider/{MockEnpdointAPIProvider.js → MockEndpointAPIProvider.js}

@@ -11,8 +11,8 @@ import { MockAPIProvider } from "./MockAPIProvider.js";
  *  const result = await api.fetch(endpoint, 4); // Mock a call to the endpoint through the provider.
  *  expect(result).toBe(16);
  */
-export class MockEnpdointAPIProvider extends MockAPIProvider {
-    constructor(handlers, c, options) {
-        super(request => handleEndpoints(this.url, handlers, { ...c, request }), options);
+export class MockEndpointAPIProvider extends MockAPIProvider {
+    constructor(handlers, { context, ...options }) {
+        super(request => handleEndpoints(this.url, handlers, request, context), options);
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "shelving",
-	"version": "1.180.0",
+	"version": "1.181.0",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"repository": {
 		"type": "git",