@kalyptos/bifrost 5.0.0 → 5.1.0

package/README.md

@@ -1,8 +1,9 @@
 # @kalyptos/bifrost
 
-TypeScript client for the Bifrost API. Full reference: <https://bifrost.kalyptos.io/docs>.
+TypeScript client for the Bifrost API.
 
-ESM with no runtime dependencies. It needs a global `fetch` (Node 18 or later, or a browser).
+ESM with no runtime dependencies. It uses the global `fetch` (Node 18 or later, or a browser) unless
+you pass your own.
 
 ```sh
 npm install @kalyptos/bifrost
@@ -20,8 +21,10 @@ const { matches } = await bifrost.resolve({ input: 'Rådhuspladsen 1, København
 
 `resolve`, `search` and `project` take one request and return one result, or take an array and
 return a batch. A batch item that fails is still a result: `{ input, matches: [], error }`.
-`token` is optional: a string, or a function that gives the token for each request. A response that
-is not 2xx throws `BifrostError` with `status` and `detail`.
+`token` is optional: a string, or a function that gives the token for each request. `fetch` is
+optional too: the client sends every request through it, for retries, logging or tests. Every call,
+`compose` too, takes `{ signal }` as its last argument, to cancel it. A response that is not 2xx
+throws `BifrostError` with `status` and `detail`.
 
 ## Compose
 

package/dist/client.d.ts

@@ -4,6 +4,10 @@ export type Token = string | (() => string | Promise<string>);
 export interface BifrostOptions {
     baseUrl: string;
     token?: Token;
+    fetch?: typeof fetch;
+}
+export interface CallOptions {
+    signal?: AbortSignal;
 }
 export interface ValidationIssue {
     loc: (string | number)[];
@@ -18,12 +22,12 @@ export declare class BifrostError extends Error {
 }
 export declare class Bifrost {
     #private;
-    constructor({ baseUrl, token }: BifrostOptions);
-    resolve(body: ResolveRequest): Promise<MatchResult>;
-    resolve(body: ResolveRequest[]): Promise<MatchResult[]>;
-    search<T extends SearchTarget>(body: SearchRequest<string, T>): Promise<MatchResult<SearchMatch<T>>>;
-    search<T extends SearchTarget>(body: SearchRequest<string, T>[]): Promise<MatchResult<SearchMatch<T>>[]>;
-    project(body: ProjectRequest): Promise<ProjectResult>;
-    project(body: ProjectRequest[]): Promise<ProjectResult[]>;
-    compose<S extends Shape>(fn: (q: Recorder) => S): Promise<Decoded<S>>;
+    constructor({ baseUrl, token, fetch }: BifrostOptions);
+    resolve(body: ResolveRequest, options?: CallOptions): Promise<MatchResult>;
+    resolve(body: ResolveRequest[], options?: CallOptions): Promise<MatchResult[]>;
+    search<T extends SearchTarget>(body: SearchRequest<string, T>, options?: CallOptions): Promise<MatchResult<SearchMatch<T>>>;
+    search<T extends SearchTarget>(body: SearchRequest<string, T>[], options?: CallOptions): Promise<MatchResult<SearchMatch<T>>[]>;
+    project(body: ProjectRequest, options?: CallOptions): Promise<ProjectResult>;
+    project(body: ProjectRequest[], options?: CallOptions): Promise<ProjectResult[]>;
+    compose<S extends Shape>(fn: (q: Recorder) => S, options?: CallOptions): Promise<Decoded<S>>;
 }

package/dist/client.js

@@ -12,33 +12,38 @@ export class BifrostError extends Error {
 export class Bifrost {
     #baseUrl;
     #token;
-    constructor({ baseUrl, token }) {
+    #fetch;
+    constructor({ baseUrl, token, fetch }) {
         this.#baseUrl = baseUrl.replace(/\/+$/, '');
         this.#token = token;
+        this.#fetch = fetch;
     }
-    resolve(body) {
-        return this.#post('/resolve', body);
+    resolve(body, options) {
+        return this.#post('/resolve', body, options);
     }
-    search(body) {
-        return this.#post('/search', body);
+    search(body, options) {
+        return this.#post('/search', body, options);
     }
-    project(body) {
-        return this.#post('/project', body);
+    project(body, options) {
+        return this.#post('/project', body, options);
     }
-    async compose(fn) {
+    async compose(fn, options) {
         const { steps, decode } = record(fn);
-        const outputs = (await this.#post('/compose', { steps }));
+        const outputs = (await this.#post('/compose', { steps }, options));
         return decode(outputs);
     }
-    async #post(path, body) {
+    async #post(path, body, { signal } = {}) {
         const headers = { 'content-type': 'application/json' };
         const token = typeof this.#token === 'function' ? await this.#token() : this.#token;
         if (token)
             headers.authorization = `Bearer ${token}`;
-        const res = await fetch(this.#baseUrl + path, {
+        // called unbound and looked up per call: a browser rejects fetch with a foreign this
+        const send = this.#fetch ?? globalThis.fetch;
+        const res = await send(this.#baseUrl + path, {
             method: 'POST',
             headers,
-            body: JSON.stringify(body)
+            body: JSON.stringify(body),
+            ...(signal && { signal })
         });
         if (!res.ok)
             throw new BifrostError(res.status, await detailOf(res));

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 export { Bifrost, BifrostError } from './client.js';
-export type { BifrostOptions, ErrorDetail, Token, ValidationIssue } from './client.js';
+export type { BifrostOptions, CallOptions, ErrorDetail, Token, ValidationIssue } from './client.js';
 export type { CodeSlot, Decoded, Handle, Mapped, ProjectBody, Recorder, RefHandle, Shape, Slot, Step } from './compose.js';
 export type * from './types.js';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@kalyptos/bifrost",
-	"version": "5.0.0",
+	"version": "5.1.0",
 	"description": "TypeScript client for the Bifrost Danish address API",
 	"license": "Apache-2.0",
 	"repository": {