shelving 1.141.0 → 1.143.0

package/api/util.d.ts

@@ -6,8 +6,12 @@ import type { Endpoint } from "./Endpoint.js";
  * - Payload is validated by the payload validator for the `Endpoint`.
  * - If the body of the `Request` is a data object (i.e. a plain object), then body data is merged with the path and query parameters to form a single flat object.
  * - If payload is _not_ a data object (i.e. it's another JSON type like `string` or `number`) then the payload include the path and query parameters, and a key called `content` that contains the body of the request.
+ *
+ * @param request The raw `Request` object in case it needs any additional processing.
+ *
+ * @returns The correct `Result` type for the `Endpoint`, or a raw `Response` object if you wish to return a custom response.
  */
-export type EndpointCallback<P, R> = (payload: P, request: Request) => R | Promise<R>;
+export type EndpointCallback<P, R> = (payload: P, request: Request) => R | Response | Promise<R | Response>;
 /**
  * Object combining an abstract `Endpoint` and an `EndpointCallback` implementation.
  */
@@ -24,7 +28,11 @@ export type AnyEndpointHandler = EndpointHandler<any, any>;
  */
 export type EndpointHandlers = ReadonlyArray<AnyEndpointHandler>;
 /**
- * Handler a `Request` with the first matching `OptionalHandler` in a `Handlers` array.
+ * Handler a `Request` with the first matching `EndpointHandlers`.
+ *
+ * 1. Define your `Endpoint` objects with a method, path, payload and result validators, e.g. `GET("/test/{id}", PAYLOAD, STRING)`
+ * 2. Make an array of `EndpointHandler` objects combining an `Endpoint` with a `callback` function
+ * -
  *
  * @returns The resulting `Response` from the first handler that matches the `Request`.
  * @throws `NotFoundError` if no handler matches the `Request`.

package/api/util.js

@@ -7,7 +7,11 @@ import { matchTemplate } from "../util/template.js";
 import { getURL } from "../util/url.js";
 import { getValid } from "../util/validate.js";
 /**
- * Handler a `Request` with the first matching `OptionalHandler` in a `Handlers` array.
+ * Handler a `Request` with the first matching `EndpointHandlers`.
+ *
+ * 1. Define your `Endpoint` objects with a method, path, payload and result validators, e.g. `GET("/test/{id}", PAYLOAD, STRING)`
+ * 2. Make an array of `EndpointHandler` objects combining an `Endpoint` with a `callback` function
+ * -
  *
  * @returns The resulting `Response` from the first handler that matches the `Request`.
  * @throws `NotFoundError` if no handler matches the `Request`.
@@ -28,14 +32,15 @@ export function handleEndpoints(request, endpoints) {
         const pathParams = matchTemplate(endpoint.path, pathname, handleEndpoints);
         if (!pathParams)
             continue;
-        // Merge the search params and path params.
+        // 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;
         // Get the response by calling the callback.
-        return _getResponse(endpoint, callback, params, request);
+        return getEndpointResponse(endpoint, callback, params, request);
     }
+    // No handler matched the request.
     throw new NotFoundError("Not found", { request, caller: handleEndpoints });
 }
-async function _getResponse(endpoint, callback, params, request) {
+async function getEndpointResponse(endpoint, callback, params, request) {
     // Extract a data object from the request body and validate it against the endpoint's payload type.
     const content = await getRequestContent(request, handleEndpoints);
     // If content is undefined, it means the request has no body, so params are the only payload.
@@ -43,11 +48,14 @@ async function _getResponse(endpoint, callback, params, request) {
     // If the content is not a data object (e.g. string, number, array), set a single `content` property and merge it with the params.
     const unsafePayload = content === undefined ? params : isData(content) ? { ...content, ...params } : { content, ...params };
     const payload = endpoint.prepare(unsafePayload);
-    // Call the handler with the validated payload to get the result.
-    const unsafeResult = await callback(payload, request);
-    // Validate the result against the endpoint's result type.
+    // Call the callback with the validated payload to get the result.
+    const returned = await callback(payload, request);
+    // If the callback returned a `Response`, return it directly.
+    if (returned instanceof Response)
+        return returned;
+    // Otherwise validate the result against the endpoint's result type.
     // Throw a `ValueError` if the result is not valid, which indicates an internal error in the callback implementation.
-    const result = getValid(unsafeResult, endpoint, ValueError, handleEndpoints);
+    const result = getValid(returned, endpoint, ValueError, handleEndpoints);
     // Return a new `Response` with a 200 status and the validated result data.
     return Response.json(result);
 }

package/markup/util/internal.js

@@ -1,2 +1,2 @@
 /** React security symbol — see https://github.com/facebook/react/pull/4832 */
-export const REACT_ELEMENT_TYPE = Symbol.for("react.element");
+export const REACT_ELEMENT_TYPE = Symbol.for("react.transitional.element");

package/package.json

@@ -11,7 +11,7 @@
 		"state-management",
 		"query-builder"
 	],
-	"version": "1.141.0",
+	"version": "1.143.0",
 	"repository": "https://github.com/dhoulb/shelving",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"license": "0BSD",
@@ -57,19 +57,19 @@
 		"build:test:unit": "bun test ./dist/**/*.test.js --bail"
 	},
 	"devDependencies": {
-		"@biomejs/biome": "^1.8.3",
-		"@google-cloud/firestore": "^7.9.0",
-		"@types/bun": "^1.1.6",
-		"@types/react": "^18.3.3",
-		"@types/react-dom": "^18.3.0",
-		"firebase": "^10.12.5",
-		"react": "^18.3.1",
-		"react-dom": "^18.3.1",
-		"typescript": "^5.8.2"
+		"@biomejs/biome": "^1.9.4",
+		"@google-cloud/firestore": "^7.11.3",
+		"@types/bun": "^1.2.18",
+		"@types/react": "^19.1.8",
+		"@types/react-dom": "^19.1.6",
+		"firebase": "^11.10.0",
+		"react": "^19.1.0",
+		"react-dom": "^19.1.0",
+		"typescript": "^5.8.3"
 	},
 	"peerDependencies": {
-		"@google-cloud/firestore": ">=4.0.0",
-		"firebase": ">=9.0.0",
-		"react": ">=17.0.0"
+		"@google-cloud/firestore": ">=7.0.0",
+		"firebase": ">=11.0.0",
+		"react": ">=19.0.0"
 	}
 }

package/react/createCacheContext.js

@@ -1,21 +1,22 @@
-import { createContext, createElement, useContext, useRef } from "react";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext } from "react";
 import { UnexpectedError } from "../error/UnexpectedError.js";
+import { useMap } from "./useMap.js";
 /**
  * Create a cache context that can be provided to React elements and allows them to call `useCache()`
  * - Cache is a `Map` indexed by strings that can be used to store any value.
  */
 export function createCacheContext() {
-    const context = createContext(undefined);
+    const Context = createContext(undefined);
     const useCache = () => {
-        const cache = useContext(context);
+        const cache = useContext(Context);
         if (!cache)
-            throw new UnexpectedError("useCache() must be used inside <Cache>", { caller: useCache });
+            throw new UnexpectedError("useCache() must be used inside <CacheContext>", { caller: useCache });
         return cache;
     };
     const CacheContext = ({ children }) => {
-        // biome-ignore lint/suspicious/noAssignInExpressions: This is the most efficient way to do this.
-        const cache = (useRef().current ||= new Map());
-        return createElement(context.Provider, { children, value: cache });
+        const cache = useMap();
+        return _jsx(Context, { value: cache, children: children });
     };
     return { useCache, CacheContext };
 }

package/react/index.d.ts

@@ -1,6 +1,7 @@
 export * from "./createCacheContext.js";
 export * from "./createDataContext.js";
-export * from "./useInstance.js";
+export * from "./useProps.js";
+export * from "./useMap.js";
 export * from "./useLazy.js";
 export * from "./useReduce.js";
 export * from "./useSequence.js";

package/react/index.js

@@ -1,6 +1,7 @@
 export * from "./createCacheContext.js";
 export * from "./createDataContext.js";
-export * from "./useInstance.js";
+export * from "./useProps.js";
+export * from "./useMap.js";
 export * from "./useLazy.js";
 export * from "./useReduce.js";
 export * from "./useSequence.js";

package/react/useInstance.js

@@ -1,17 +1,16 @@
 import { isArrayEqual } from "../util/equal.js";
-import { useInternals } from "./useInternals.js";
+import { useProps } from "./useProps.js";
 /**
  * Use a memoised class instance.
  * - Creates a new instance of `Constructor` using `args`
  * - Returns same instance for as long as `args` is equal to previous `args`.
  */
 export function useInstance(Constructor, ...args) {
-    const internals = useInternals();
+    const internals = useProps();
     // Update `internals` if `args` changes or `instance` is not set.
-    if (!internals.args || !isArrayEqual(args, internals.args)) {
+    if (!internals.args || !internals.instance || !isArrayEqual(args, internals.args)) {
         internals.instance = new Constructor(...args);
         internals.args = args;
     }
-    // biome-ignore lint/style/noNonNullAssertion: We know this is set.
     return internals.instance;
 }

package/react/useLazy.js

@@ -1,13 +1,12 @@
 import { isArrayEqual } from "../util/equal.js";
 import { getLazy } from "../util/lazy.js";
-import { useInternals } from "./useInternals.js";
+import { useProps } from "./useProps.js";
 export function useLazy(value, ...args) {
-    const internals = useInternals();
+    const internals = useProps();
     // Update `internals` if `args` changes.
-    if (internals.args === undefined || !isArrayEqual(args, internals.args)) {
+    if (!internals.args || !isArrayEqual(args, internals.args)) {
         internals.value = getLazy(value, ...args);
         internals.args = args;
     }
-    // biome-ignore lint/style/noNonNullAssertion: We know this is set.
     return internals.value;
 }

package/react/useMap.d.ts

@@ -0,0 +1,2 @@
+/** Create a mutable Map that persist for the lifetime of the component. */
+export declare function useMap<K, V>(): Map<K, V>;

package/react/useMap.js

@@ -0,0 +1,8 @@
+import { useRef } from "react";
+/** Create a mutable Map that persist for the lifetime of the component. */
+export function useMap() {
+    const ref = useRef(undefined);
+    if (!ref.current)
+        ref.current = new Map();
+    return ref.current;
+}

package/react/useProps.d.ts

@@ -0,0 +1,6 @@
+type Mutable<T> = {
+    -readonly [K in keyof T]: T[K];
+};
+/** Create an object that persist for the lifetime of the component. */
+export declare function useProps<T>(): Partial<Mutable<T>>;
+export {};

package/react/useProps.js

@@ -0,0 +1,5 @@
+import { useRef } from "react";
+/** Create an object that persist for the lifetime of the component. */
+export function useProps() {
+    return useRef(undefined);
+}

package/react/useStore.js

@@ -2,17 +2,16 @@ import { useSyncExternalStore } from "react";
 import { NONE } from "../util/constants.js";
 import { BLACKHOLE } from "../util/function.js";
 import { runSequence } from "../util/sequence.js";
-import { useInternals } from "./useInternals.js";
+import { useProps } from "./useProps.js";
 export function useStore(store) {
     // Store memoized versions of `subscribe()` and `getSnapshot()` so `useSyncExternalStore()` doesn't re-subscribe on every render.
-    const internals = useInternals();
+    const internals = useProps();
     // Update `internals` if `store` changes.
-    if (store !== internals.store) {
+    if (store !== internals.store || !internals.subscribe || !internals.getSnapshot) {
         internals.subscribe = onStoreChange => (store ? runSequence(store, onStoreChange, onStoreChange) : BLACKHOLE);
         internals.getSnapshot = () => (!store ? undefined : store.loading ? NONE : store.value);
         internals.store = store;
     }
-    // biome-ignore lint/style/noNonNullAssertion: We know these are set.
     useSyncExternalStore(internals.subscribe, internals.getSnapshot);
     return store;
 }

package/util/http.d.ts

@@ -2,7 +2,7 @@ import type { AnyCaller } from "../error/BaseError.js";
 import { RequestError } from "../error/RequestError.js";
 import { ResponseError } from "../error/ResponseError.js";
 /** A handler function takes a `Request` and returns a `Response` (possibly asynchronously). */
-export type Handler = (request: Request) => Response | Promise<Response>;
+export type RequestHandler = (request: Request) => Response | Promise<Response>;
 export declare function _getMessageJSON(message: Request | Response, MessageError: typeof RequestError | typeof ResponseError, caller: AnyCaller): Promise<unknown>;
 export declare function _getMessageFormData(message: Request | Response, MessageError: typeof RequestError | typeof ResponseError, caller: AnyCaller): Promise<unknown>;
 export declare function _getMessageContent(message: Request | Response, MessageError: typeof RequestError | typeof ResponseError, caller: AnyCaller): Promise<unknown>;

package/util/source.d.ts

@@ -1,3 +1,4 @@
+import type { AnyCaller } from "../error/BaseError.js";
 import type { Class } from "./class.js";
 /** Something that has a source of a specified type. */
 export interface Sourceable<T> {
@@ -6,4 +7,4 @@ export interface Sourceable<T> {
 /** Recurse through `Sourceable` objects and return the first one that is an instance of `type`, or `undefined` if no source object matches. */
 export declare function getSource<T>(type: Class<T>, value: unknown): T | undefined;
 /** Recurse through `Sourceable` objects and return the first one that is an instance of `type`, or throw `RequiredError` if no source object matches. */
-export declare function requireSource<T>(type: Class<T>, data: unknown): T;
+export declare function requireSource<T>(type: Class<T>, data: unknown, caller?: AnyCaller): T;

package/util/source.js

@@ -10,9 +10,9 @@ export function getSource(type, value) {
     }
 }
 /** Recurse through `Sourceable` objects and return the first one that is an instance of `type`, or throw `RequiredError` if no source object matches. */
-export function requireSource(type, data) {
+export function requireSource(type, data, caller = requireSource) {
     const source = getSource(type, data);
     if (!source)
-        throw new RequiredError(`Source "${type.name}" not found`, { received: data, expected: type, caller: requireSource });
+        throw new RequiredError(`Source "${type.name}" not found`, { received: data, expected: type, caller });
     return source;
 }

package/react/useInternals.d.ts

@@ -1,5 +0,0 @@
-import type { Data } from "../util/data.js";
-/** Store internal implementation details for a hook that persist for the lifetime of the component. */
-export declare const useInternals: <T extends Data>() => T | {
-    [K in keyof T]: undefined;
-};

package/react/useInternals.js

@@ -1,3 +0,0 @@
-import { useRef } from "react";
-/** Store internal implementation details for a hook that persist for the lifetime of the component. */
-export const useInternals = useRef;