eventsourcingdb 1.9.1 → 2.0.0

package/dist/Client.js

@@ -1,485 +1,110 @@
-import { convertCloudEventToEvent } from './convertCloudEventToEvent.js';
-import { heartbeatTimeout } from './heartbeatTimeout.js';
-import { isCloudEvent } from './isCloudEvent.js';
-import { isValidServerHeader } from './isValidServerHeader.js';
-import { readNdJsonStream } from './ndjson/readNdJsonStream.js';
-import { isStreamCloudEvent } from './stream/isStreamCloudEvent.js';
-import { isStreamError } from './stream/isStreamError.js';
-import { isStreamEventType } from './stream/isStreamEventType.js';
-import { isStreamHeartbeat } from './stream/isStreamHeartbeat.js';
-import { isStreamRow } from './stream/isStreamRow.js';
-import { isStreamSubject } from './stream/isStreamSubject.js';
+import { detectApiVersion } from './detectApiVersion.js';
+import { isAbortError } from './http/isAbortError.js';
+import { waitUnlessAborted } from './http/waitUnlessAborted.js';
+import { defaultStallTimeout, maximumStallTimeout } from './stall/defaultStallTimeout.js';
 import { hasShapeOf } from './types/hasShapeOf.js';
 import { isBoolean } from './types/isBoolean.js';
-import { isString } from './types/isString.js';
+import { V1Transport } from './v1/V1Transport.js';
+import { V2Transport } from './v2/V2Transport.js';
+// Reads a stream through the transport, unless the caller aborts while the
+// client finds out which one to use, which ends the stream, as aborting it
+// does at any other time.
+const streamThrough = async function* (getTransport, stream) {
+    let transport;
+    try {
+        transport = await getTransport();
+    }
+    catch (error) {
+        if (isAbortError(error)) {
+            return;
+        }
+        throw error;
+    }
+    yield* stream(transport);
+};
 class Client {
-    #url;
-    #apiToken;
-    #getUrl(path) {
-        return new URL(path, this.#url).toString();
+    #transportOptions;
+    #transport;
+    #detection;
+    constructor(url, apiToken, options = {}) {
+        const stallTimeout = options.stallTimeout ?? defaultStallTimeout;
+        if (!(stallTimeout >= 1 && stallTimeout <= maximumStallTimeout)) {
+            throw new Error(`Stall timeout must be between 1 and ${maximumStallTimeout} milliseconds, got '${stallTimeout}'.`);
+        }
+        this.#transportOptions = { url, apiToken, stallTimeout };
     }
-    constructor(url, apiToken) {
-        this.#url = url;
-        this.#apiToken = apiToken;
+    // This is the one place that chooses between the APIs. The first request of
+    // a client finds out which API the server offers, and the client keeps the
+    // answer. Requests that start meanwhile wait for the same answer. If the
+    // client fails to find out, the request fails, and the next one tries again.
+    async #getTransport(signal) {
+        if (this.#transport !== undefined) {
+            return this.#transport;
+        }
+        signal?.throwIfAborted();
+        if (this.#detection === undefined) {
+            const detection = detectApiVersion(this.#transportOptions).then(apiVersion => {
+                this.#transport =
+                    apiVersion === 'v2'
+                        ? new V2Transport(this.#transportOptions)
+                        : new V1Transport(this.#transportOptions);
+                return this.#transport;
+            });
+            const forget = () => {
+                if (this.#detection === detection) {
+                    this.#detection = undefined;
+                }
+            };
+            detection.then(forget, forget);
+            this.#detection = detection;
+        }
+        return await waitUnlessAborted(this.#detection, signal);
     }
-    async ping() {
-        const url = this.#getUrl('/api/v1/ping');
-        const response = await fetch(url, {
-            method: 'get',
-        });
-        if (!isValidServerHeader(response)) {
-            throw new Error('Server must be EventSourcingDB.');
-        }
-        if (response.status !== 200) {
-            throw new Error(`Failed to ping, got HTTP status code '${response.status}', expected '200'.`);
-        }
-        const responseBody = await response.json();
-        if (!hasShapeOf(responseBody, {
-            type: isString,
-        })) {
-            throw new Error('Failed to parse response.');
-        }
-        const eventType = 'io.eventsourcingdb.api.ping-received';
-        if (responseBody.type !== eventType) {
-            throw new Error('Failed to ping.');
-        }
+    async ping(signal) {
+        const transport = await this.#getTransport(signal);
+        await transport.ping(signal);
     }
-    async verifyApiToken() {
-        const url = this.#getUrl('/api/v1/verify-api-token');
-        const response = await fetch(url, {
-            method: 'post',
-            headers: {
-                authorization: `Bearer ${this.#apiToken}`,
-            },
-        });
-        if (!isValidServerHeader(response)) {
-            throw new Error('Server must be EventSourcingDB.');
-        }
-        if (response.status !== 200) {
-            throw new Error(`Failed to verify API token, got HTTP status code '${response.status}', expected '200'.`);
-        }
-        const responseBody = await response.json();
-        if (!hasShapeOf(responseBody, {
-            type: isString,
-        })) {
-            throw new Error('Failed to parse response.');
-        }
-        const eventType = 'io.eventsourcingdb.api.api-token-verified';
-        if (responseBody.type !== eventType) {
-            throw new Error('Failed to verify API token.');
-        }
+    async verifyApiToken(signal) {
+        const transport = await this.#getTransport(signal);
+        await transport.verifyApiToken(signal);
     }
-    async writeEvents(events, preconditions = []) {
-        const url = this.#getUrl('/api/v1/write-events');
-        const response = await fetch(url, {
-            method: 'post',
-            headers: {
-                authorization: `Bearer ${this.#apiToken}`,
-                'content-type': 'application/json',
-            },
-            body: JSON.stringify({
-                events,
-                preconditions,
-            }),
-        });
-        if (!isValidServerHeader(response)) {
-            throw new Error('Server must be EventSourcingDB.');
-        }
-        if (response.status !== 200) {
-            throw new Error(`Failed to write events, got HTTP status code '${response.status}', expected '200'.`);
-        }
-        const responseBody = await response.json();
-        if (!Array.isArray(responseBody)) {
-            throw new Error('Failed to parse response.');
-        }
-        const writtenEvents = responseBody.map(item => {
-            if (!isCloudEvent(item)) {
-                throw new Error('Failed to parse response item.');
-            }
-            const event = convertCloudEventToEvent(item);
-            return event;
-        });
-        return writtenEvents;
+    // A write that fails once it may have reached the server fails with an
+    // OutcomeUnknownError, since it may have been stored nonetheless. This
+    // includes aborting the signal once the write has been sent.
+    async writeEvents(events, preconditions = [], signal) {
+        const transport = await this.#getTransport(signal);
+        return await transport.writeEvents(events, preconditions, signal);
     }
     readEvents(subject, options, signal) {
-        const url = this.#getUrl('/api/v1/read-events');
-        const apiToken = this.#apiToken;
-        return (async function* () {
-            const internalAbortController = new AbortController();
-            const combinedSignal = signal ?? internalAbortController.signal;
-            const shouldAbortInternally = !signal;
-            let removeAbortListener;
-            if (signal && !signal.aborted) {
-                const onAbort = () => internalAbortController.abort();
-                signal.addEventListener('abort', onAbort, { once: true });
-                removeAbortListener = () => signal.removeEventListener('abort', onAbort);
-            }
-            try {
-                const response = await fetch(url, {
-                    method: 'post',
-                    headers: {
-                        authorization: `Bearer ${apiToken}`,
-                        'content-type': 'application/json',
-                    },
-                    body: JSON.stringify({
-                        subject,
-                        options,
-                    }),
-                    signal: combinedSignal,
-                });
-                if (!isValidServerHeader(response)) {
-                    const serverHeader = response.headers.get('Server');
-                    if (!serverHeader) {
-                        throw new Error('Server must be EventSourcingDB, but Server header is missing.');
-                    }
-                    throw new Error(`Server must be EventSourcingDB, got Server header: '${serverHeader}'.`);
-                }
-                if (response.status !== 200) {
-                    throw new Error(`Failed to read events, got HTTP status code '${response.status}', expected '200'.`);
-                }
-                if (!response.body) {
-                    throw new Error('Failed to read events.');
-                }
-                for await (const line of readNdJsonStream(response.body, combinedSignal)) {
-                    if (isStreamError(line)) {
-                        throw new Error(`${line.payload.error}.`);
-                    }
-                    if (isStreamCloudEvent(line)) {
-                        const event = convertCloudEventToEvent(line.payload);
-                        yield event;
-                        continue;
-                    }
-                    throw new Error('Failed to read events.');
-                }
-            }
-            catch (error) {
-                if (error instanceof DOMException && error.name === 'AbortError') {
-                    return;
-                }
-                throw error;
-            }
-            finally {
-                if (removeAbortListener) {
-                    removeAbortListener();
-                }
-                if (shouldAbortInternally) {
-                    internalAbortController.abort();
-                }
-            }
-        })();
+        return streamThrough(async () => await this.#getTransport(signal), transport => transport.readEvents(subject, options, signal));
     }
     runEventQlQuery(query, signal) {
-        const url = this.#getUrl('/api/v1/run-eventql-query');
-        const apiToken = this.#apiToken;
-        return (async function* () {
-            const internalAbortController = new AbortController();
-            const combinedSignal = signal ?? internalAbortController.signal;
-            const shouldAbortInternally = !signal;
-            let removeAbortListener;
-            if (signal && !signal.aborted) {
-                const onAbort = () => internalAbortController.abort();
-                signal.addEventListener('abort', onAbort, { once: true });
-                removeAbortListener = () => signal.removeEventListener('abort', onAbort);
-            }
-            try {
-                const response = await fetch(url, {
-                    method: 'post',
-                    headers: {
-                        authorization: `Bearer ${apiToken}`,
-                        'content-type': 'application/json',
-                    },
-                    body: JSON.stringify({ query }),
-                    signal: combinedSignal,
-                });
-                if (!isValidServerHeader(response)) {
-                    const serverHeader = response.headers.get('Server');
-                    if (!serverHeader) {
-                        throw new Error('Server must be EventSourcingDB, but Server header is missing.');
-                    }
-                    throw new Error(`Server must be EventSourcingDB, got Server header: '${serverHeader}'.`);
-                }
-                if (response.status !== 200) {
-                    throw new Error(`Failed to run EventQL query, got HTTP status code '${response.status}', expected '200'.`);
-                }
-                if (!response.body) {
-                    throw new Error('Failed to run EventQL query.');
-                }
-                for await (const line of readNdJsonStream(response.body, combinedSignal, heartbeatTimeout.milliseconds)) {
-                    if (isStreamHeartbeat(line)) {
-                        continue;
-                    }
-                    if (isStreamError(line)) {
-                        throw new Error(`${line.payload.error}.`);
-                    }
-                    if (isStreamRow(line)) {
-                        const row = line.payload;
-                        yield row;
-                        continue;
-                    }
-                    throw new Error('Failed to run EventQL query.');
-                }
-            }
-            catch (error) {
-                if (error instanceof DOMException && error.name === 'AbortError') {
-                    return;
-                }
-                throw error;
-            }
-            finally {
-                if (removeAbortListener) {
-                    removeAbortListener();
-                }
-                if (shouldAbortInternally) {
-                    internalAbortController.abort();
-                }
-            }
-        })();
+        return streamThrough(async () => await this.#getTransport(signal), transport => transport.runEventQlQuery(query, signal));
     }
     observeEvents(subject, options, signal) {
-        const url = this.#getUrl('/api/v1/observe-events');
-        const apiToken = this.#apiToken;
-        return (async function* () {
-            const internalAbortController = new AbortController();
-            const combinedSignal = signal ?? internalAbortController.signal;
-            const shouldAbortInternally = !signal;
-            let removeAbortListener;
-            if (signal && !signal.aborted) {
-                const onAbort = () => internalAbortController.abort();
-                signal.addEventListener('abort', onAbort, { once: true });
-                removeAbortListener = () => signal.removeEventListener('abort', onAbort);
-            }
-            try {
-                const response = await fetch(url, {
-                    method: 'post',
-                    headers: {
-                        authorization: `Bearer ${apiToken}`,
-                        'content-type': 'application/json',
-                    },
-                    body: JSON.stringify({
-                        subject,
-                        options,
-                    }),
-                    signal: combinedSignal,
-                });
-                if (!isValidServerHeader(response)) {
-                    const serverHeader = response.headers.get('Server');
-                    if (!serverHeader) {
-                        throw new Error('Server must be EventSourcingDB, but Server header is missing.');
-                    }
-                    throw new Error(`Server must be EventSourcingDB, got Server header: '${serverHeader}'.`);
-                }
-                if (response.status !== 200) {
-                    throw new Error(`Failed to observe events, got HTTP status code '${response.status}', expected '200'.`);
-                }
-                if (!response.body) {
-                    throw new Error('Failed to observe events.');
-                }
-                for await (const line of readNdJsonStream(response.body, combinedSignal, heartbeatTimeout.milliseconds)) {
-                    if (isStreamHeartbeat(line)) {
-                        continue;
-                    }
-                    if (isStreamError(line)) {
-                        throw new Error(`${line.payload.error}.`);
-                    }
-                    if (isStreamCloudEvent(line)) {
-                        const event = convertCloudEventToEvent(line.payload);
-                        yield event;
-                        continue;
-                    }
-                    throw new Error('Failed to observe events.');
-                }
-            }
-            catch (error) {
-                if (error instanceof DOMException && error.name === 'AbortError') {
-                    return;
-                }
-                throw error;
-            }
-            finally {
-                if (removeAbortListener) {
-                    removeAbortListener();
-                }
-                if (shouldAbortInternally) {
-                    internalAbortController.abort();
-                }
-            }
-        })();
+        return streamThrough(async () => await this.#getTransport(signal), transport => transport.observeEvents(subject, options, signal));
     }
-    async registerEventSchema(eventType, schema) {
-        const url = this.#getUrl('/api/v1/register-event-schema');
-        const response = await fetch(url, {
-            method: 'post',
-            headers: {
-                authorization: `Bearer ${this.#apiToken}`,
-                'content-type': 'application/json',
-            },
-            body: JSON.stringify({
-                eventType,
-                schema,
-            }),
-        });
-        if (!isValidServerHeader(response)) {
-            throw new Error('Server must be EventSourcingDB.');
-        }
-        if (response.status !== 200) {
-            throw new Error(`Failed to register event schema, got HTTP status code '${response.status}', expected '200'.`);
-        }
+    // Registering an event schema is a write, so it fails like writeEvents does.
+    async registerEventSchema(eventType, schema, signal) {
+        const transport = await this.#getTransport(signal);
+        await transport.registerEventSchema(eventType, schema, signal);
     }
-    readSubjects(baseSubject, signal) {
-        const url = this.#getUrl('/api/v1/read-subjects');
-        const apiToken = this.#apiToken;
-        return (async function* () {
-            const internalAbortController = new AbortController();
-            const combinedSignal = signal ?? internalAbortController.signal;
-            const shouldAbortInternally = !signal;
-            let removeAbortListener;
-            if (signal && !signal.aborted) {
-                const onAbort = () => internalAbortController.abort();
-                signal.addEventListener('abort', onAbort, { once: true });
-                removeAbortListener = () => signal.removeEventListener('abort', onAbort);
-            }
-            try {
-                const response = await fetch(url, {
-                    method: 'post',
-                    headers: {
-                        authorization: `Bearer ${apiToken}`,
-                        'content-type': 'application/json',
-                    },
-                    body: JSON.stringify({
-                        baseSubject,
-                    }),
-                    signal: combinedSignal,
-                });
-                if (!isValidServerHeader(response)) {
-                    const serverHeader = response.headers.get('Server');
-                    if (!serverHeader) {
-                        throw new Error('Server must be EventSourcingDB, but Server header is missing.');
-                    }
-                    throw new Error(`Server must be EventSourcingDB, got Server header: '${serverHeader}'.`);
-                }
-                if (response.status !== 200) {
-                    throw new Error(`Failed to read subjects, got HTTP status code '${response.status}', expected '200'.`);
-                }
-                if (!response.body) {
-                    throw new Error('Failed to read subjects.');
-                }
-                for await (const line of readNdJsonStream(response.body, combinedSignal)) {
-                    if (isStreamError(line)) {
-                        throw new Error(`${line.payload.error}.`);
-                    }
-                    if (isStreamSubject(line)) {
-                        yield line.payload.subject;
-                        continue;
-                    }
-                    throw new Error('Failed to read subjects.');
-                }
-            }
-            catch (error) {
-                if (error instanceof DOMException && error.name === 'AbortError') {
-                    return;
-                }
-                throw error;
-            }
-            finally {
-                if (removeAbortListener) {
-                    removeAbortListener();
-                }
-                if (shouldAbortInternally) {
-                    internalAbortController.abort();
-                }
-            }
-        })();
+    readSubjects(subject, options, signal) {
+        // The option decides whether to read the subject alone or with all the
+        // subjects below it, so it has no default, and a caller without types has
+        // to set it as well.
+        if (!hasShapeOf(options, { recursive: isBoolean })) {
+            throw new Error("Option 'recursive' must be set to true or false.");
+        }
+        const { recursive } = options;
+        return streamThrough(async () => await this.#getTransport(signal), transport => transport.readSubjects(subject, { recursive }, signal));
     }
-    async readEventType(eventType) {
-        const url = this.#getUrl('/api/v1/read-event-type');
-        const response = await fetch(url, {
-            method: 'post',
-            headers: {
-                authorization: `Bearer ${this.#apiToken}`,
-                'content-type': 'application/json',
-            },
-            body: JSON.stringify({
-                eventType,
-            }),
-        });
-        if (!isValidServerHeader(response)) {
-            throw new Error('Server must be EventSourcingDB.');
-        }
-        if (response.status !== 200) {
-            throw new Error(`Failed to read event type, got HTTP status code '${response.status}', expected '200'.`);
-        }
-        const responseBody = await response.json();
-        if (!hasShapeOf(responseBody, {
-            eventType: isString,
-            isPhantom: isBoolean,
-        })) {
-            throw new Error('Failed to parse response.');
-        }
-        return responseBody;
+    async readEventType(eventType, signal) {
+        const transport = await this.#getTransport(signal);
+        return await transport.readEventType(eventType, signal);
     }
     readEventTypes(signal) {
-        const url = this.#getUrl('/api/v1/read-event-types');
-        const apiToken = this.#apiToken;
-        return (async function* () {
-            const internalAbortController = new AbortController();
-            const combinedSignal = signal ?? internalAbortController.signal;
-            const shouldAbortInternally = !signal;
-            let removeAbortListener;
-            if (signal && !signal.aborted) {
-                const onAbort = () => internalAbortController.abort();
-                signal.addEventListener('abort', onAbort, { once: true });
-                removeAbortListener = () => signal.removeEventListener('abort', onAbort);
-            }
-            try {
-                const response = await fetch(url, {
-                    method: 'post',
-                    headers: {
-                        authorization: `Bearer ${apiToken}`,
-                    },
-                    signal: combinedSignal,
-                });
-                if (!isValidServerHeader(response)) {
-                    const serverHeader = response.headers.get('Server');
-                    if (!serverHeader) {
-                        throw new Error('Server must be EventSourcingDB, but Server header is missing.');
-                    }
-                    throw new Error(`Server must be EventSourcingDB, got Server header: '${serverHeader}'.`);
-                }
-                if (response.status !== 200) {
-                    throw new Error(`Failed to read event types, got HTTP status code '${response.status}', expected '200'.`);
-                }
-                if (!response.body) {
-                    throw new Error('Failed to read event types.');
-                }
-                for await (const line of readNdJsonStream(response.body, combinedSignal)) {
-                    if (isStreamHeartbeat(line)) {
-                        continue;
-                    }
-                    if (isStreamError(line)) {
-                        throw new Error(`${line.payload.error}.`);
-                    }
-                    if (isStreamEventType(line)) {
-                        yield line.payload;
-                        continue;
-                    }
-                    throw new Error('Failed to read event types.');
-                }
-            }
-            catch (error) {
-                if (error instanceof DOMException && error.name === 'AbortError') {
-                    return;
-                }
-                throw error;
-            }
-            finally {
-                if (removeAbortListener) {
-                    removeAbortListener();
-                }
-                if (shouldAbortInternally) {
-                    internalAbortController.abort();
-                }
-            }
-        })();
+        return streamThrough(async () => await this.#getTransport(signal), transport => transport.readEventTypes(signal));
     }
 }
 export { Client };

package/dist/ClientOptions.d.ts

@@ -0,0 +1,4 @@
+interface ClientOptions {
+    stallTimeout?: number;
+}
+export type { ClientOptions };

package/dist/ConnectionStalledError.d.ts

@@ -0,0 +1,4 @@
+declare class ConnectionStalledError extends TypeError {
+    constructor(stallTimeout?: number, options?: ErrorOptions);
+}
+export { ConnectionStalledError };

package/dist/ConnectionStalledError.js

@@ -0,0 +1,13 @@
+import { defaultStallTimeout } from './stall/defaultStallTimeout.js';
+import { formatDuration } from './stall/formatDuration.js';
+// Extends TypeError, since fetch fails with a TypeError if a request stalls
+// for longer than its own timeouts allow, so code that catches that keeps
+// working. For the same reason, its cause carries the code of the timeout
+// error of fetch for the same situation.
+class ConnectionStalledError extends TypeError {
+    constructor(stallTimeout = defaultStallTimeout, options) {
+        super(`Nothing arrived from the server for ${formatDuration(stallTimeout)}.`, options);
+        this.name = 'ConnectionStalledError';
+    }
+}
+export { ConnectionStalledError };

package/dist/DbApiError.d.ts

@@ -0,0 +1,17 @@
+interface DbApiErrorOptions {
+    status: number;
+    description: string;
+    code?: string;
+    details?: Record<string, unknown>;
+    retryAfter?: number;
+}
+declare class DbApiError extends Error {
+    readonly code: string | undefined;
+    readonly description: string;
+    readonly details: Record<string, unknown>;
+    readonly status: number;
+    readonly retryAfter: number | undefined;
+    constructor({ status, description, code, details, retryAfter }: DbApiErrorOptions);
+}
+export type { DbApiErrorOptions };
+export { DbApiError };

package/dist/DbApiError.js

@@ -0,0 +1,24 @@
+// An error that the server reports, whether as an error item of the v2 API, as
+// a status other than 200 with a text, or as an error of the v1 API.
+class DbApiError extends Error {
+    // The URL that names the error, exactly as the server sends it, which the
+    // constants of ErrorCode hold. It is undefined for an error without a code.
+    code;
+    description;
+    details;
+    // The HTTP status of the response, which is 200 for an error item.
+    status;
+    // The seconds after which the server accepts requests again, which only a
+    // response with the status 429 may name.
+    retryAfter;
+    constructor({ status, description, code, details = {}, retryAfter }) {
+        super(description === '' ? `The server answered with HTTP status code '${status}'.` : description);
+        this.name = 'DbApiError';
+        this.code = code;
+        this.description = description;
+        this.details = details;
+        this.status = status;
+        this.retryAfter = retryAfter;
+    }
+}
+export { DbApiError };