eventsourcingdb 1.10.0 → 2.0.0

package/dist/v2/V2Transport.js

@@ -0,0 +1,302 @@
+import { createStreamEndedError } from '../http/createStreamEndedError.js';
+import { runWrite } from '../http/runWrite.js';
+import { runWithStallGuard } from '../stall/runWithStallGuard.js';
+import { streamWithStallGuard } from '../stall/streamWithStallGuard.js';
+import { hasShapeOf } from '../types/hasShapeOf.js';
+import { isRecord } from '../types/isRecord.js';
+import { isString } from '../types/isString.js';
+import { convertV2ItemToEvent, convertV2ItemToEventType } from './convertV2Item.js';
+import { isV2Refusal } from './isV2Refusal.js';
+import { readV2Answer } from './readV2Answer.js';
+import { readV2Stream } from './readV2Stream.js';
+import { toObserveEventsBody, toReadEventsBody, toWriteEventsBody } from './toV2RequestBody.js';
+// The v2 API reads with the method QUERY of RFC 10008, which, unlike GET,
+// carries a body.
+const methodQuery = 'QUERY';
+const isEventOfType = (item, eventType) => item.type === 'event' &&
+    hasShapeOf(item.data, {
+        type: isString,
+    }) &&
+    item.data.type === eventType;
+// Reads the answer of a write, a stream that closes with an end item once the
+// write is done, and returns its items before that. Only an abort of the
+// caller ends it early without failing, which then fails with the reason of
+// the abort, since the write may have been stored nonetheless.
+const readWriteAnswer = async (response, stallGuard, { signal, action }) => {
+    const items = [];
+    for await (const item of readV2Stream(response, stallGuard, { signal, action, hasEnd: true })) {
+        if (item.type === 'end') {
+            return items;
+        }
+        items.push(item);
+    }
+    signal?.throwIfAborted();
+    throw createStreamEndedError(action);
+};
+// Sends the requests through the v2 API, which EventSourcingDB offers since
+// version 1.3.
+class V2Transport {
+    #url;
+    #apiToken;
+    #stallTimeout;
+    #getUrl(path) {
+        return new URL(path, this.#url).toString();
+    }
+    constructor({ url, apiToken, stallTimeout }) {
+        this.#url = url;
+        this.#apiToken = apiToken;
+        this.#stallTimeout = stallTimeout;
+    }
+    async ping(signal) {
+        const url = this.#getUrl('/api/v2/system/ping');
+        const stallTimeout = this.#stallTimeout;
+        await runWithStallGuard({ stallTimeout, signal }, async (stallGuard) => {
+            const response = await stallGuard.send(url, {
+                method: 'GET',
+            });
+            const item = await readV2Answer(response, stallGuard, 'ping');
+            if (!isEventOfType(item, 'io.eventsourcingdb.api.ping-received')) {
+                throw new Error('Failed to ping.');
+            }
+        });
+    }
+    async verifyApiToken(signal) {
+        const url = this.#getUrl('/api/v2/system/verify-token');
+        const stallTimeout = this.#stallTimeout;
+        await runWithStallGuard({ stallTimeout, signal }, async (stallGuard) => {
+            const response = await stallGuard.send(url, {
+                method: 'POST',
+                headers: {
+                    authorization: `Bearer ${this.#apiToken}`,
+                },
+            });
+            const item = await readV2Answer(response, stallGuard, 'verify API token');
+            if (!isEventOfType(item, 'io.eventsourcingdb.api.token-verified')) {
+                throw new Error('Failed to verify API token.');
+            }
+        });
+    }
+    async writeEvents(events, preconditions, signal) {
+        const url = this.#getUrl('/api/v2/data/write-events');
+        const stallTimeout = this.#stallTimeout;
+        const body = JSON.stringify(toWriteEventsBody(events, preconditions));
+        const action = 'write events';
+        return await runWrite({ signal, isRefusal: isV2Refusal }, async () => await runWithStallGuard({ stallTimeout, signal }, async (stallGuard) => {
+            const response = await stallGuard.send(url, {
+                method: 'POST',
+                headers: {
+                    authorization: `Bearer ${this.#apiToken}`,
+                    'content-type': 'application/json',
+                },
+                body,
+            });
+            const items = await readWriteAnswer(response, stallGuard, { signal, action });
+            return items.map(item => {
+                if (item.type !== 'event') {
+                    throw new Error(`Failed to ${action}, got an unexpected item.`);
+                }
+                return convertV2ItemToEvent(item, action);
+            });
+        }));
+    }
+    readEvents(subject, options, signal) {
+        const url = this.#getUrl('/api/v2/data/read-events');
+        const apiToken = this.#apiToken;
+        const stallTimeout = this.#stallTimeout;
+        const action = 'read events';
+        return streamWithStallGuard({ stallTimeout, signal }, async function* (stallGuard) {
+            const response = await stallGuard.send(url, {
+                method: methodQuery,
+                headers: {
+                    authorization: `Bearer ${apiToken}`,
+                    'content-type': 'application/json',
+                },
+                body: JSON.stringify(toReadEventsBody(subject, options)),
+            });
+            for await (const item of readV2Stream(response, stallGuard, {
+                signal,
+                action,
+                hasEnd: true,
+            })) {
+                if (item.type === 'end') {
+                    return;
+                }
+                if (item.type === 'event') {
+                    yield convertV2ItemToEvent(item, action);
+                    continue;
+                }
+                throw new Error(`Failed to ${action}, got an unexpected item.`);
+            }
+        });
+    }
+    runEventQlQuery(query, signal) {
+        const url = this.#getUrl('/api/v2/data/run-eventql-query');
+        const apiToken = this.#apiToken;
+        const stallTimeout = this.#stallTimeout;
+        const action = 'run EventQL query';
+        return streamWithStallGuard({ stallTimeout, signal }, async function* (stallGuard) {
+            const response = await stallGuard.send(url, {
+                method: methodQuery,
+                headers: {
+                    authorization: `Bearer ${apiToken}`,
+                    'content-type': 'application/json',
+                },
+                body: JSON.stringify({ query }),
+            });
+            for await (const item of readV2Stream(response, stallGuard, {
+                signal,
+                action,
+                hasEnd: true,
+            })) {
+                if (item.type === 'end') {
+                    return;
+                }
+                // A row wraps its value, which may be any JSON value, null included.
+                if (item.type === 'row' && isRecord(item.data) && 'value' in item.data) {
+                    yield item.data.value;
+                    continue;
+                }
+                throw new Error(`Failed to ${action}, got an unexpected item.`);
+            }
+        });
+    }
+    // Observing never ends on its own, so its stream has no end item, and fails
+    // if it ends nonetheless.
+    observeEvents(subject, options, signal) {
+        const url = this.#getUrl('/api/v2/data/observe-events');
+        const apiToken = this.#apiToken;
+        const stallTimeout = this.#stallTimeout;
+        const action = 'observe events';
+        return streamWithStallGuard({ stallTimeout, signal }, async function* (stallGuard) {
+            const response = await stallGuard.send(url, {
+                method: methodQuery,
+                headers: {
+                    authorization: `Bearer ${apiToken}`,
+                    'content-type': 'application/json',
+                },
+                body: JSON.stringify(toObserveEventsBody(subject, options)),
+            });
+            for await (const item of readV2Stream(response, stallGuard, {
+                signal,
+                action,
+                hasEnd: false,
+            })) {
+                if (item.type === 'event') {
+                    yield convertV2ItemToEvent(item, action);
+                    continue;
+                }
+                throw new Error(`Failed to ${action}, got an unexpected item.`);
+            }
+        });
+    }
+    async registerEventSchema(eventType, schema, signal) {
+        const url = this.#getUrl('/api/v2/data/register-event-schema');
+        const stallTimeout = this.#stallTimeout;
+        const body = JSON.stringify({
+            type: eventType,
+            schema,
+        });
+        const action = 'register event schema';
+        await runWrite({ signal, isRefusal: isV2Refusal }, async () => await runWithStallGuard({ stallTimeout, signal }, async (stallGuard) => {
+            const response = await stallGuard.send(url, {
+                method: 'POST',
+                headers: {
+                    authorization: `Bearer ${this.#apiToken}`,
+                    'content-type': 'application/json',
+                },
+                body,
+            });
+            const items = await readWriteAnswer(response, stallGuard, { signal, action });
+            const [item, ...otherItems] = items;
+            if (item === undefined ||
+                otherItems.length > 0 ||
+                !isEventOfType(item, 'io.eventsourcingdb.api.event-schema-registered')) {
+                throw new Error(`Failed to ${action}, got an unexpected answer.`);
+            }
+        }));
+    }
+    readSubjects(subject, { recursive }, signal) {
+        const url = this.#getUrl('/api/v2/data/read-subjects');
+        const apiToken = this.#apiToken;
+        const stallTimeout = this.#stallTimeout;
+        const action = 'read subjects';
+        return streamWithStallGuard({ stallTimeout, signal }, async function* (stallGuard) {
+            const response = await stallGuard.send(url, {
+                method: methodQuery,
+                headers: {
+                    authorization: `Bearer ${apiToken}`,
+                    'content-type': 'application/json',
+                },
+                body: JSON.stringify({
+                    subject,
+                    options: { recursive },
+                }),
+            });
+            for await (const item of readV2Stream(response, stallGuard, {
+                signal,
+                action,
+                hasEnd: true,
+            })) {
+                if (item.type === 'end') {
+                    return;
+                }
+                if (item.type === 'subject' && isRecord(item.data) && isString(item.data.subject)) {
+                    yield item.data.subject;
+                    continue;
+                }
+                throw new Error(`Failed to ${action}, got an unexpected item.`);
+            }
+        });
+    }
+    async readEventType(eventType, signal) {
+        const url = this.#getUrl('/api/v2/data/read-event-type');
+        const stallTimeout = this.#stallTimeout;
+        const action = 'read event type';
+        return await runWithStallGuard({ stallTimeout, signal }, async (stallGuard) => {
+            const response = await stallGuard.send(url, {
+                method: methodQuery,
+                headers: {
+                    authorization: `Bearer ${this.#apiToken}`,
+                    'content-type': 'application/json',
+                },
+                body: JSON.stringify({
+                    type: eventType,
+                }),
+            });
+            const item = await readV2Answer(response, stallGuard, action);
+            if (item.type !== 'eventType') {
+                throw new Error(`Failed to ${action}, got an unexpected answer.`);
+            }
+            return convertV2ItemToEventType(item, action);
+        });
+    }
+    readEventTypes(signal) {
+        const url = this.#getUrl('/api/v2/data/read-event-types');
+        const apiToken = this.#apiToken;
+        const stallTimeout = this.#stallTimeout;
+        const action = 'read event types';
+        return streamWithStallGuard({ stallTimeout, signal }, async function* (stallGuard) {
+            const response = await stallGuard.send(url, {
+                method: methodQuery,
+                headers: {
+                    authorization: `Bearer ${apiToken}`,
+                },
+            });
+            for await (const item of readV2Stream(response, stallGuard, {
+                signal,
+                action,
+                hasEnd: true,
+            })) {
+                if (item.type === 'end') {
+                    return;
+                }
+                if (item.type === 'eventType') {
+                    yield convertV2ItemToEventType(item, action);
+                    continue;
+                }
+                throw new Error(`Failed to ${action}, got an unexpected item.`);
+            }
+        });
+    }
+}
+export { V2Transport };

package/dist/v2/convertV2Item.d.ts

@@ -0,0 +1,6 @@
+import type { Event } from '../Event.js';
+import type { EventType } from '../EventType.js';
+import type { V2Item } from './V2Item.js';
+declare const convertV2ItemToEvent: (item: V2Item, action: string) => Event;
+declare const convertV2ItemToEventType: (item: V2Item, action: string) => EventType;
+export { convertV2ItemToEvent, convertV2ItemToEventType };

package/dist/v2/convertV2Item.js

@@ -0,0 +1,52 @@
+import { convertCloudEventToEvent } from '../convertCloudEventToEvent.js';
+import { getRawJsonMember } from '../json/getRawJsonMember.js';
+import { hasShapeOf } from '../types/hasShapeOf.js';
+import { isBoolean } from '../types/isBoolean.js';
+import { isRecord } from '../types/isRecord.js';
+import { isString } from '../types/isString.js';
+import { isStringOrNull } from '../types/isStringOrNull.js';
+const isV2Event = (value) => hasShapeOf(value, {
+    specversion: isString,
+    id: isString,
+    time: isString,
+    source: isString,
+    subject: isString,
+    type: isString,
+    datacontenttype: isString,
+    data: isRecord,
+    hash: isString,
+    predecessorhash: isString,
+    traceparent: isStringOrNull,
+    tracestate: isStringOrNull,
+    signature: isStringOrNull,
+});
+const isV2EventType = (value) => hasShapeOf(value, {
+    type: isString,
+    hasEvents: isBoolean,
+    schema: (schema) => schema === null || isRecord(schema),
+});
+// The hash of an event covers its data exactly as the server sent it, so the
+// event keeps the text of its data from the text of the item.
+const convertV2ItemToEvent = (item, action) => {
+    if (!isV2Event(item.data)) {
+        throw new Error(`Failed to ${action}, got an unexpected event.`);
+    }
+    const { traceparent, tracestate, ...cloudEvent } = item.data;
+    return convertCloudEventToEvent({
+        ...cloudEvent,
+        ...(traceparent === null ? {} : { traceparent }),
+        ...(tracestate === null ? {} : { tracestate }),
+    }, getRawJsonMember(item.text, 'data'));
+};
+const convertV2ItemToEventType = (item, action) => {
+    if (!isV2EventType(item.data)) {
+        throw new Error(`Failed to ${action}, got an unexpected event type.`);
+    }
+    const { type, hasEvents, schema } = item.data;
+    return {
+        type,
+        hasEvents,
+        ...(schema === null ? {} : { schema }),
+    };
+};
+export { convertV2ItemToEvent, convertV2ItemToEventType };

package/dist/v2/isV2Refusal.d.ts

@@ -0,0 +1,3 @@
+import type { DbApiError } from '../DbApiError.js';
+declare const isV2Refusal: (error: DbApiError) => boolean;
+export { isV2Refusal };

package/dist/v2/isV2Refusal.js

@@ -0,0 +1,12 @@
+import { ErrorCode } from '../ErrorCode.js';
+// The statuses with which the v2 API refuses a request before handling it.
+const refusingStatuses = new Set([400, 401, 408, 413, 429, 503]);
+// Tells whether the v2 API refused a write before storing anything. It does so
+// with every error item, except for a failed store, and with some statuses.
+const isV2Refusal = (error) => {
+    if (error.status === 200) {
+        return error.code !== ErrorCode.storeFailed;
+    }
+    return refusingStatuses.has(error.status);
+};
+export { isV2Refusal };

package/dist/v2/parseV2Item.d.ts

@@ -0,0 +1,3 @@
+import type { V2Item } from './V2Item.js';
+declare const parseV2Item: (value: unknown, text: string, action: string) => V2Item;
+export { parseV2Item };

package/dist/v2/parseV2Item.js

@@ -0,0 +1,30 @@
+import { DbApiError } from '../DbApiError.js';
+import { hasShapeOf } from '../types/hasShapeOf.js';
+import { isRecord } from '../types/isRecord.js';
+import { isString } from '../types/isString.js';
+const isV2Envelope = (value) => hasShapeOf(value, {
+    type: isString,
+    data: (data) => data !== undefined,
+});
+const isV2ErrorData = (value) => hasShapeOf(value, {
+    code: isString,
+    description: isString,
+    details: isRecord,
+});
+// Parses an answer or an item of a stream of the v2 API, each of which wraps
+// its data in an envelope that names its type. An error item fails with the
+// error that it describes, which the server reports at the status 200.
+const parseV2Item = (value, text, action) => {
+    if (!isV2Envelope(value)) {
+        throw new Error(`Failed to ${action}, got an unexpected answer.`);
+    }
+    if (value.type === 'error') {
+        if (!isV2ErrorData(value.data)) {
+            throw new Error(`Failed to ${action}, got an unexpected error.`);
+        }
+        const { code, description, details } = value.data;
+        throw new DbApiError({ status: 200, code, description, details });
+    }
+    return { type: value.type, data: value.data, text };
+};
+export { parseV2Item };

package/dist/v2/readV2Answer.d.ts

@@ -0,0 +1,4 @@
+import type { StallGuard } from '../stall/StallGuard.js';
+import type { V2Item } from './V2Item.js';
+declare const readV2Answer: (response: Response, stallGuard: StallGuard, action: string) => Promise<V2Item>;
+export { readV2Answer };

package/dist/v2/readV2Answer.js

@@ -0,0 +1,14 @@
+import { assertEventSourcingDb } from '../http/assertEventSourcingDb.js';
+import { createDbApiErrorFromResponse } from '../http/createDbApiErrorFromResponse.js';
+import { readResponseText } from '../stall/readResponseText.js';
+import { parseV2Item } from './parseV2Item.js';
+// Reads the single answer of a request to the v2 API.
+const readV2Answer = async (response, stallGuard, action) => {
+    assertEventSourcingDb(response);
+    if (response.status !== 200) {
+        throw await createDbApiErrorFromResponse(response, stallGuard);
+    }
+    const text = await readResponseText(response, stallGuard);
+    return parseV2Item(JSON.parse(text), text, action);
+};
+export { readV2Answer };

package/dist/v2/readV2Stream.d.ts

@@ -0,0 +1,8 @@
+import type { StallGuard } from '../stall/StallGuard.js';
+import type { V2Item } from './V2Item.js';
+declare const readV2Stream: (response: Response, stallGuard: StallGuard, { signal, action, hasEnd }: {
+    signal?: AbortSignal;
+    action: string;
+    hasEnd: boolean;
+}) => AsyncGenerator<V2Item, void, void>;
+export { readV2Stream };

package/dist/v2/readV2Stream.js

@@ -0,0 +1,34 @@
+import { assertEventSourcingDb } from '../http/assertEventSourcingDb.js';
+import { createDbApiErrorFromResponse } from '../http/createDbApiErrorFromResponse.js';
+import { createStreamEndedError } from '../http/createStreamEndedError.js';
+import { readNdJsonStream } from '../ndjson/readNdJsonStream.js';
+import { parseV2Item } from './parseV2Item.js';
+// Reads the items of a stream of the v2 API. It skips heartbeats and fails
+// with the error of an error item. A stream that has an end closes with an
+// end item, which it yields as well, and a stream that has none, such as
+// observing events, never ends on its own. So a stream that ends otherwise
+// broke off and fails, unless the caller aborted it.
+const readV2Stream = async function* (response, stallGuard, { signal, action, hasEnd }) {
+    assertEventSourcingDb(response);
+    if (response.status !== 200) {
+        throw await createDbApiErrorFromResponse(response, stallGuard);
+    }
+    if (!response.body) {
+        throw new Error(`Failed to ${action}.`);
+    }
+    for await (const { value, text } of readNdJsonStream(response.body, stallGuard.signal, stallGuard)) {
+        const item = parseV2Item(value, text, action);
+        if (item.type === 'heartbeat') {
+            continue;
+        }
+        yield item;
+        if (hasEnd && item.type === 'end') {
+            return;
+        }
+    }
+    stallGuard.throwIfStalled();
+    if (!signal?.aborted) {
+        throw createStreamEndedError(action);
+    }
+};
+export { readV2Stream };

package/dist/v2/toV2RequestBody.d.ts

@@ -0,0 +1,8 @@
+import type { EventCandidate } from '../EventCandidate.js';
+import type { ObserveEventsOptions } from '../ObserveEventsOptions.js';
+import type { Precondition } from '../Precondition.js';
+import type { ReadEventsOptions } from '../ReadEventsOptions.js';
+declare const toWriteEventsBody: (events: EventCandidate[], preconditions: Precondition[]) => Record<string, unknown>;
+declare const toReadEventsBody: (subject: string, options: ReadEventsOptions) => Record<string, unknown>;
+declare const toObserveEventsBody: (subject: string, options: ObserveEventsOptions) => Record<string, unknown>;
+export { toObserveEventsBody, toReadEventsBody, toWriteEventsBody };

package/dist/v2/toV2RequestBody.js

@@ -0,0 +1,46 @@
+// The v2 API refuses unknown fields and null, so these build the bodies of its
+// requests from the fields it knows, and leave out the ones without a value.
+// JSON.stringify leaves out a field whose value is undefined.
+const toBound = (bound) => bound ? { id: bound.id, type: bound.type } : undefined;
+const toFromLatestEvent = (fromLatestEvent) => fromLatestEvent
+    ? {
+        subject: fromLatestEvent.subject,
+        type: fromLatestEvent.type,
+        ifEventIsMissing: fromLatestEvent.ifEventIsMissing,
+    }
+    : undefined;
+const toWriteEventsBody = (events, preconditions) => ({
+    events: events.map(event => ({
+        source: event.source,
+        subject: event.subject,
+        type: event.type,
+        data: event.data,
+        traceparent: event.traceparent ?? undefined,
+        tracestate: event.tracestate ?? undefined,
+    })),
+    preconditions: preconditions.length === 0
+        ? undefined
+        : preconditions.map(precondition => ({
+            type: precondition.type,
+            payload: precondition.payload,
+        })),
+});
+const toReadEventsBody = (subject, options) => ({
+    subject,
+    options: {
+        recursive: options.recursive,
+        order: options.order ?? undefined,
+        lowerBound: toBound(options.lowerBound),
+        upperBound: toBound(options.upperBound),
+        fromLatestEvent: toFromLatestEvent(options.fromLatestEvent),
+    },
+});
+const toObserveEventsBody = (subject, options) => ({
+    subject,
+    options: {
+        recursive: options.recursive,
+        lowerBound: toBound(options.lowerBound),
+        fromLatestEvent: toFromLatestEvent(options.fromLatestEvent),
+    },
+});
+export { toObserveEventsBody, toReadEventsBody, toWriteEventsBody };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eventsourcingdb",
-  "version": "1.10.0",
+  "version": "2.0.0",
   "description": "The official JavaScript client SDK for EventSourcingDB.",
   "author": {
     "name": "the native web GmbH",

package/dist/HeartbeatTimeoutError.d.ts

@@ -1,4 +0,0 @@
-declare class HeartbeatTimeoutError extends Error {
-    constructor(stallTimeout?: number);
-}
-export { HeartbeatTimeoutError };

package/dist/HeartbeatTimeoutError.js

@@ -1,9 +0,0 @@
-import { defaultStallTimeout } from './stall/defaultStallTimeout.js';
-import { formatDuration } from './stall/formatDuration.js';
-class HeartbeatTimeoutError extends Error {
-    constructor(stallTimeout = defaultStallTimeout) {
-        super(`No event and no heartbeat arrived for ${formatDuration(stallTimeout)}.`);
-        this.name = 'HeartbeatTimeoutError';
-    }
-}
-export { HeartbeatTimeoutError };