shelving 1.182.0 → 1.183.0

package/README.md

@@ -1,46 +1,41 @@
-# Shelving: toolkit for using data in JavaScript
+# Shelving
 
-[![Semantic Release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg?style=flat)](https://github.com/semantic-release/semantic-release) [![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg)](https://conventionalcommits.org) [![Prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://github.com/prettier/prettier) [![GitHub Actions](https://github.com/dhoulb/shelving/workflows/CI/badge.svg?branch=main)](https://github.com/dhoulb/shelving/actions) [![npm](https://img.shields.io/npm/dm/shelving.svg)](https://www.npmjs.com/package/shelving)
+[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg)](https://conventionalcommits.org) [![Release](https://github.com/dhoulb/shelving/actions/workflows/release.yaml/badge.svg)](https://github.com/dhoulb/shelving/actions/workflows/release.yaml) [![npm](https://img.shields.io/npm/dm/shelving.svg)](https://www.npmjs.com/package/shelving)
 
-**Shelving** is a toolkit for using data in JavaScript and TypeScript, including:
+Shelving is a TypeScript toolkit for working with typed data. At its core it is a schema validation library — every schema has a `validate()` method that returns a typed value or throws a human-readable error. On top of that it provides a database provider abstraction, an API provider abstraction, observable state stores, React integration, and a large set of typed utility functions.
 
-> Note: The `1.x` branch of Shelving is in active development and is not observing semver for breaking changes (from `2.x` onward semver will be followed).
-
-- Schemas (validation)
-- Databases (via providers including in-memory, Firestore, IndexedDB)
-- Querying (sorting, filtering, slicing)
-- Store (events and state)
-- React (hooks and state)
-- Helpers (errors, arrays, objects, strings, dates, equality, merging, diffing, cloning, debug)
+> Note: Shelving is in active development and does not yet follow semver.
 
 ## Installation
 
-Install via `npm` or `yarn`:
-
 ```sh
 npm install shelving
-yarn add shelving
 ```
 
-Import from Skypack CDN (the `?dts` enables TypeScript types in Deno):
+Shelving is an ES module. Import from the main package or from individual module subpaths:
 
-```js
-import { Database } from "https://cdn.skypack.dev/shelving";
-import { Database } from "https://cdn.skypack.dev/shelving?dts";
+```ts
+import { STRING, DataSchema } from "shelving"
+import { MemoryDBProvider } from "shelving/db"
 ```
 
-## Usage
-
-Shelving is an [ES module](https://nodejs.org/api/esm.html) supporting `import { Query } from "shelving";` syntax and can be used natively in systems/browsers that support that (e.g. Chrome 61+, Deno, Node 12+).
-
-Shelving does not include code for CommonJS `require()` imports, so using it in older projects will require transpiling.
-
 ## Modules
 
-Shelving is created from small individual modules which can be imported individually (using e.g. `import { addProp } from "shelving/util/object`). Modules marked with `✅` are also re-exported from the main `"shelving"` module.
-
-@todo Write these docs!
+| Module | Description |
+|---|---|
+| [schema](modules/schema/README.md) | Schema validation — the foundation of everything |
+| [db](modules/db/README.md) | Database provider abstraction (Collections, providers, queries) |
+| [api](modules/api/README.md) | API provider abstraction (Endpoints, providers, caching) |
+| [store](modules/store/README.md) | Observable state containers, Suspense-compatible |
+| [sequence](modules/sequence/README.md) | Async-iterable utilities (`DeferredSequence`) |
+| [react](modules/react/README.md) | React hooks for stores and sequences |
+| [error](modules/error/README.md) | Typed error classes |
+| [util](modules/util/README.md) | Typed helpers for arrays, objects, strings, data, queries, updates |
+| [markup](modules/markup/README.md) | Markdown renderer for user-facing content |
+| [cloudflare](modules/cloudflare/README.md) | Cloudflare Workers providers (KV, D1) |
+| [firestore](modules/firestore/README.md) | Firestore providers (client, lite, server) |
+| [bun](modules/bun/README.md) | Bun PostgreSQL provider |
 
 ## Changelog
 
-See [Releases](https://github.com/dhoulb/shelving/releases)
+See [Releases](https://github.com/dhoulb/shelving/releases).

package/api/provider/APIProvider.d.ts

@@ -6,8 +6,13 @@ import type { Endpoint } from "../endpoint/Endpoint.js";
 export interface APIProviderOptions {
     /** The common base URL for all rendered endpoint requests. */
     readonly url: PossibleURL;
-    /** Options used for HTTP requests created with `this.getRequest()` and `this.fetch()` */
-    readonly options?: RequestOptions;
+    /**
+     * Options used for HTTP requests created with `this.getRequest()` and `this.fetch()`
+     * - Omits `signal` because it's not relevant at the provider level.
+     */
+    readonly options?: Omit<RequestOptions, "signal">;
+    /** Timeout in milliseconds, or `undefined` for no timeout. */
+    readonly timeout?: number | undefined;
 }
 /** Provider for API endpoints rooted at a common base URL. */
 export declare class APIProvider {
@@ -15,7 +20,9 @@ export declare class APIProvider {
     readonly url: URLString;
     /** Default options used for HTTP requests created with `this.getRequest()` and `this.fetch()` */
     readonly options: RequestOptions;
-    constructor({ url, options }: APIProviderOptions);
+    /** Timeout in milliseconds, or `undefined` for no timeout. */
+    readonly timeout: number | undefined;
+    constructor({ url, options, timeout }: APIProviderOptions);
     /**
      * Render the full final URL for an API request to a given endpoint with a given payload.
      * - Includes `?query` params if this is a `HEAD` or `GET` request.
@@ -26,9 +33,19 @@ export declare class APIProvider {
     renderURL<P, R>(endpoint: Endpoint<P, R>, payload: P, caller?: AnyCaller): URL;
     /**
      * Create a `Request` that targets this endpoint with a given base URL.
-     * - Path `{placeholders}` are rendered from the payload.
-     * - For `GET` and `HEAD`, remaining payload fields are appended as `?query` params.
-     * - For all other requests, payload is sent as the body.
+     *
+     * @param payload The payload to embed into the `Request` to send to the endpoint.
+     * - Path `{placeholders}` are rendered from `payload`
+     * - For `GET` and `HEAD`, remaining `payload` fields are appended as `?query` params.
+     * - For all other requests, `payload` is sent as the body.
+     *
+     * @param options The `RequestOptions` to use when creating the `Request`
+     * - Merges `options` with `this.options` to make the final request options.
+     *
+     * @returns The created request.
+     * - Merges `options` with `this.options` to make the final request options.
+     * - Includes an `AbortSignal` based on `this.timeout` if it's set to a number in milliseconds.
+     * - The timeout `AbortSignal` is merged with any manual signal set in `
      *
      * @throws {RequiredError} if this endpoint's path has `{placeholders}` but `payload` is not a data object.
      * @throws {RequiredError} if this is a `HEAD` or `GET` request but `payload` is not a data object.

package/api/provider/APIProvider.js

@@ -11,9 +11,12 @@ export class APIProvider {
     url;
     /** Default options used for HTTP requests created with `this.getRequest()` and `this.fetch()` */
     options;
-    constructor({ url, options = {} }) {
+    /** Timeout in milliseconds, or `undefined` for no timeout. */
+    timeout;
+    constructor({ url, options = {}, timeout }) {
         this.url = requireBaseURL(url, undefined, APIProvider);
         this.options = options;
+        this.timeout = timeout;
     }
     /**
      * Render the full final URL for an API request to a given endpoint with a given payload.
@@ -36,9 +39,19 @@ export class APIProvider {
     }
     /**
      * Create a `Request` that targets this endpoint with a given base URL.
-     * - Path `{placeholders}` are rendered from the payload.
-     * - For `GET` and `HEAD`, remaining payload fields are appended as `?query` params.
-     * - For all other requests, payload is sent as the body.
+     *
+     * @param payload The payload to embed into the `Request` to send to the endpoint.
+     * - Path `{placeholders}` are rendered from `payload`
+     * - For `GET` and `HEAD`, remaining `payload` fields are appended as `?query` params.
+     * - For all other requests, `payload` is sent as the body.
+     *
+     * @param options The `RequestOptions` to use when creating the `Request`
+     * - Merges `options` with `this.options` to make the final request options.
+     *
+     * @returns The created request.
+     * - Merges `options` with `this.options` to make the final request options.
+     * - Includes an `AbortSignal` based on `this.timeout` if it's set to a number in milliseconds.
+     * - The timeout `AbortSignal` is merged with any manual signal set in `
      *
      * @throws {RequiredError} if this endpoint's path has `{placeholders}` but `payload` is not a data object.
      * @throws {RequiredError} if this is a `HEAD` or `GET` request but `payload` is not a data object.
@@ -46,17 +59,21 @@ export class APIProvider {
     getRequest(endpoint, payload, options, caller = this.getRequest) {
         // Render the path into the base URL.
         const url = this.renderURL(endpoint, payload, caller);
+        // Merge the param options with `this.options`
+        // If we have a timeout set, create an `AbortSignal` for it.
+        const signal = this.timeout ? AbortSignal.timeout(this.timeout) : null;
+        const mergedOptions = mergeRequestOptions({ signal, ...this.options }, options);
         // HEAD or GET requests have no payload because it was already rendered into the URL as `?query` params.
         if (isArrayItem(HTTP_HEAD_METHODS, endpoint.method)) {
-            return getRequest(endpoint.method, url, undefined, options);
+            return getRequest(endpoint.method, url, undefined, mergedOptions);
         }
         // Placeholders are rendered into the path so get omitted from the body payload.
         if (endpoint.placeholders.length) {
             const params = omitProps(payload, ...endpoint.placeholders); // Omit any params that were already embedded as `{placeholders}`
-            return getRequest(endpoint.method, url, params, options);
+            return getRequest(endpoint.method, url, params, mergedOptions);
         }
         // No placeholders.
-        return getRequest(endpoint.method, url, payload, options);
+        return getRequest(endpoint.method, url, payload, mergedOptions);
     }
     /**
      * Parse an HTTP `Response` for this endpoint.
@@ -71,7 +88,7 @@ export class APIProvider {
         return content;
     }
     async fetch(endpoint, payload, options, caller = this.fetch) {
-        const request = this.getRequest(endpoint, payload, mergeRequestOptions(this.options, options), caller);
+        const request = this.getRequest(endpoint, payload, options, caller);
         const response = await fetch(request);
         return this.parseResponse(endpoint, response, caller);
     }

package/api/provider/MockAPIProvider.d.ts

@@ -1,7 +1,8 @@
 import type { AnyCaller } from "../../util/function.js";
 import { type RequestHandler, type RequestOptions } from "../../util/http.js";
 import type { AnyEndpoint, Endpoint } from "../endpoint/Endpoint.js";
-import { APIProvider, type APIProviderOptions } from "./APIProvider.js";
+import { APIProvider } from "./APIProvider.js";
+import { ThroughAPIProvider } from "./ThroughAPIProvider.js";
 /** A structured log entry emitted by `MockAPIProvider` for one of its provider operations. */
 export type MockAPICall = {
     readonly type: "fetch";
@@ -13,18 +14,14 @@ export type MockAPICall = {
     readonly result: unknown;
 };
 /**
- * Construction options for a `MockAPIProvider`
- * - Same as options for a normal `APIProvider`, but with an optional URL.
+ * Provider that logs API calls without sending network requests.
+ * - Extends `ThroughAPIProvider` to delegate request building and response parsing to a source `APIProvider`.
+ * - The source provider's `fetch()` is never called — this provider intercepts all fetches and routes them through a `RequestHandler`.
  */
-export interface MockAPIProviderOptions extends Omit<APIProviderOptions, "url"> {
-    /** Optional URL, defaults to `"https://api.mock.com"` */
-    url?: APIProviderOptions["url"];
-}
-/** Provider that logs API calls without sending network requests. */
-export declare class MockAPIProvider extends APIProvider {
+export declare class MockAPIProvider extends ThroughAPIProvider {
     readonly calls: MockAPICall[];
     readonly handler: RequestHandler;
-    constructor(handler: RequestHandler, { url, ...options }?: MockAPIProviderOptions);
+    constructor(handler: RequestHandler, source?: APIProvider);
     /**
      * Log a `fetch()` call without using the network.
      * - If `getResult` is configured, its return value is returned as-is (no schema validation).

package/api/provider/MockAPIProvider.js

@@ -1,11 +1,16 @@
 import { mergeRequestOptions } from "../../util/http.js";
 import { APIProvider } from "./APIProvider.js";
-/** Provider that logs API calls without sending network requests. */
-export class MockAPIProvider extends APIProvider {
+import { ThroughAPIProvider } from "./ThroughAPIProvider.js";
+/**
+ * Provider that logs API calls without sending network requests.
+ * - Extends `ThroughAPIProvider` to delegate request building and response parsing to a source `APIProvider`.
+ * - The source provider's `fetch()` is never called — this provider intercepts all fetches and routes them through a `RequestHandler`.
+ */
+export class MockAPIProvider extends ThroughAPIProvider {
     calls = [];
     handler;
-    constructor(handler, { url = "https://api.mock.com", ...options } = {}) {
-        super({ url, ...options });
+    constructor(handler, source = new APIProvider({ url: "https://api.mock.com" })) {
+        super(source);
         this.handler = handler;
     }
     /**

package/api/provider/MockEndpointAPIProvider.d.ts

@@ -1,12 +1,6 @@
 import { type EndpointHandlers } from "../endpoint/util.js";
-import { MockAPIProvider, type MockAPIProviderOptions } from "./MockAPIProvider.js";
-/**
- * Construction options for a `MockAPIProvider`
- * - Same as options for a normal `MockAPIProviderOptions`, but with a `context` property for the endpoints.
- */
-export interface MockEndpointAPIProviderOptions<C = void> extends MockAPIProviderOptions {
-    context: C;
-}
+import type { APIProvider } from "./APIProvider.js";
+import { MockAPIProvider } from "./MockAPIProvider.js";
 /**
  * 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.
@@ -19,5 +13,5 @@ export interface MockEndpointAPIProviderOptions<C = void> extends MockAPIProvide
  *  expect(result).toBe(16);
  */
 export declare class MockEndpointAPIProvider<C> extends MockAPIProvider {
-    constructor(handlers: EndpointHandlers<C>, { context, ...options }: MockEndpointAPIProviderOptions<C>);
+    constructor(handlers: EndpointHandlers<C>, context: C, source?: APIProvider);
 }

package/api/provider/MockEndpointAPIProvider.js

@@ -12,7 +12,7 @@ import { MockAPIProvider } from "./MockAPIProvider.js";
  *  expect(result).toBe(16);
  */
 export class MockEndpointAPIProvider extends MockAPIProvider {
-    constructor(handlers, { context, ...options }) {
-        super(request => handleEndpoints(this.url, handlers, request, context), options);
+    constructor(handlers, context, source) {
+        super(request => handleEndpoints(this.url, handlers, request, context, this.fetch), source);
     }
 }

package/api/provider/ThroughAPIProvider.d.ts

@@ -11,6 +11,7 @@ export declare class ThroughAPIProvider implements APIProvider {
     readonly source: APIProvider;
     get url(): URLString;
     get options(): RequestOptions;
+    get timeout(): number | undefined;
     constructor(source: APIProvider);
     renderURL<P, R>(endpoint: Endpoint<P, R>, payload: P, caller?: AnyCaller): URL;
     getRequest<P, R>(endpoint: Endpoint<P, R>, payload: P, options?: RequestOptions, caller?: AnyCaller): Request;

package/api/provider/ThroughAPIProvider.js

@@ -10,6 +10,9 @@ export class ThroughAPIProvider {
     get options() {
         return this.source.options;
     }
+    get timeout() {
+        return this.source.timeout;
+    }
     constructor(source) {
         this.source = source;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "shelving",
-	"version": "1.182.0",
+	"version": "1.183.0",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"repository": {
 		"type": "git",
@@ -9,14 +9,14 @@
 	"main": "./index.js",
 	"module": "./index.js",
 	"devDependencies": {
-		"@biomejs/biome": "^2.4.10",
+		"@biomejs/biome": "^2.4.11",
 		"@google-cloud/firestore": "^8.3.0",
-		"@types/bun": "^1.3.11",
+		"@types/bun": "^1.3.12",
 		"@types/react": "^19.2.14",
 		"@types/react-dom": "^19.2.3",
-		"firebase": "^12.11.0",
-		"react": "^19.2.4",
-		"react-dom": "^19.2.4",
+		"firebase": "^12.12.0",
+		"react": "^19.2.5",
+		"react-dom": "^19.2.5",
 		"typescript": "^5.9.3"
 	},
 	"peerDependencies": {

package/store/Store.d.ts

@@ -12,7 +12,7 @@ export type AnyStore = Store<any>;
  * @param initial The initial value for the store, a `Promise` that resolves to the initial value, a source `Subscribable` to subscribe to, or another `Store` instance to take the initial value from and subscribe to.
  * - To set the store to be loading, use the `NONE` constant or a `Promise` value.
  * - To set the store to an explicit value, use that value or another `Store` instance with a value.
- * */
+ */
 export declare class Store<T> implements AsyncIterable<T> {
     /** Deferred sequence this store uses to issue values as they change. */
     readonly next: DeferredSequence<T>;

package/store/Store.js

@@ -11,7 +11,7 @@ import { getStarter } from "../util/start.js";
  * @param initial The initial value for the store, a `Promise` that resolves to the initial value, a source `Subscribable` to subscribe to, or another `Store` instance to take the initial value from and subscribe to.
  * - To set the store to be loading, use the `NONE` constant or a `Promise` value.
  * - To set the store to an explicit value, use that value or another `Store` instance with a value.
- * */
+ */
 export class Store {
     /** Deferred sequence this store uses to issue values as they change. */
     next = new DeferredSequence();
@@ -100,8 +100,10 @@ export class Store {
         this._starter?.start(this);
         this._iterating++;
         try {
-            if (!this.loading)
-                yield this.value;
+            if (this._reason !== undefined)
+                throw this._reason;
+            if (this._value !== NONE)
+                yield this._value;
             yield* this.next;
         }
         finally {

package/util/http.d.ts

@@ -79,8 +79,9 @@ export type RequestOptions = Pick<RequestInit, "cache" | "credentials" | "header
  * Merge provider-level and call-level request options.
  * - Scalar options from `b` override `a`.
  * - Header dictionaries are merged so call-level headers override default headers by key.
+ * - Abort signals are merged, so either abort signal will cancel the request.
  */
-export declare function mergeRequestOptions({ headers: aHeaders, ...a }?: RequestOptions, { headers: bHeaders, ...b }?: RequestOptions): RequestOptions;
+export declare function mergeRequestOptions({ headers: aHeaders, signal: aSignal, ...a }?: RequestOptions, { headers: bHeaders, signal: bSignal, ...b }?: RequestOptions): RequestOptions;
 /**
  * Create a `Request` instance with a valid content type based on the body.
  *

package/util/http.js

@@ -135,9 +135,12 @@ const REQUEST_JSON_OPTIONS = { headers: { "Content-Type": "application/json" } }
  * Merge provider-level and call-level request options.
  * - Scalar options from `b` override `a`.
  * - Header dictionaries are merged so call-level headers override default headers by key.
+ * - Abort signals are merged, so either abort signal will cancel the request.
  */
-export function mergeRequestOptions({ headers: aHeaders, ...a } = {}, { headers: bHeaders, ...b } = {}) {
-    return { ...a, ...b, headers: { ...aHeaders, ...bHeaders } };
+export function mergeRequestOptions({ headers: aHeaders, signal: aSignal, ...a } = {}, { headers: bHeaders, signal: bSignal, ...b } = {}) {
+    const headers = { ...aHeaders, ...bHeaders };
+    const signal = aSignal && bSignal ? AbortSignal.any([aSignal, bSignal]) : aSignal || bSignal || null;
+    return { ...a, ...b, signal, headers };
 }
 /**
  * Create a `Request` instance with a valid content type based on the body.