eventsourcingdb 1.10.0 → 2.0.1

package/dist/v1/V1Transport.js

@@ -0,0 +1,346 @@
+import { convertCloudEventToEvent } from '../convertCloudEventToEvent.js';
+import { DbApiError } from '../DbApiError.js';
+import { assertEventSourcingDb } from '../http/assertEventSourcingDb.js';
+import { createDbApiErrorFromResponse } from '../http/createDbApiErrorFromResponse.js';
+import { createStreamEndedError } from '../http/createStreamEndedError.js';
+import { runWrite } from '../http/runWrite.js';
+import { isCloudEvent } from '../isCloudEvent.js';
+import { getRawJsonElements } from '../json/getRawJsonElements.js';
+import { getRawJsonMember } from '../json/getRawJsonMember.js';
+import { readNdJsonStream } from '../ndjson/readNdJsonStream.js';
+import { readResponseText } from '../stall/readResponseText.js';
+import { runWithStallGuard } from '../stall/runWithStallGuard.js';
+import { streamWithStallGuard } from '../stall/streamWithStallGuard.js';
+import { hasShapeOf } from '../types/hasShapeOf.js';
+import { isBoolean } from '../types/isBoolean.js';
+import { isString } from '../types/isString.js';
+import { getV1ErrorCode } from './getV1ErrorCode.js';
+import { isV1Refusal } from './isV1Refusal.js';
+import { normalizeSubject } from './normalizeSubject.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';
+// The v1 API names an event type that has no events a phantom.
+const toEventType = ({ eventType, isPhantom, schema }) => ({
+    type: eventType,
+    hasEvents: !isPhantom,
+    ...(schema === undefined ? {} : { schema }),
+});
+// Fails unless the server answered the call of the v1 API with the status 200.
+const assertOk = async (response, stallGuard, call) => {
+    assertEventSourcingDb(response);
+    if (response.status !== 200) {
+        throw await createDbApiErrorFromResponse(response, stallGuard, (status, description) => getV1ErrorCode(call, status, description));
+    }
+};
+const getStreamBody = async (response, stallGuard, call, action) => {
+    await assertOk(response, stallGuard, call);
+    if (!response.body) {
+        throw new Error(`Failed to ${action}.`);
+    }
+    return response.body;
+};
+const createStreamError = (error) => new DbApiError({ status: 200, description: error });
+// Sends the requests through the v1 API, which EventSourcingDB 1.2.0 offers.
+class V1Transport {
+    #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/v1/ping');
+        const stallTimeout = this.#stallTimeout;
+        await runWithStallGuard({ stallTimeout, signal }, async (stallGuard) => {
+            const response = await stallGuard.send(url, {
+                method: 'GET',
+            });
+            await assertOk(response, stallGuard, 'ping');
+            const responseBody = JSON.parse(await readResponseText(response, stallGuard));
+            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 verifyApiToken(signal) {
+        const url = this.#getUrl('/api/v1/verify-api-token');
+        const stallTimeout = this.#stallTimeout;
+        await runWithStallGuard({ stallTimeout, signal }, async (stallGuard) => {
+            const response = await stallGuard.send(url, {
+                method: 'POST',
+                headers: {
+                    authorization: `Bearer ${this.#apiToken}`,
+                },
+            });
+            await assertOk(response, stallGuard, 'verifyApiToken');
+            const responseBody = JSON.parse(await readResponseText(response, stallGuard));
+            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 writeEvents(events, preconditions, signal) {
+        const url = this.#getUrl('/api/v1/write-events');
+        const stallTimeout = this.#stallTimeout;
+        const body = JSON.stringify({
+            events,
+            preconditions,
+        });
+        return await runWrite({ signal, isRefusal: isV1Refusal }, 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,
+            });
+            await assertOk(response, stallGuard, 'writeEvents');
+            const responseText = await readResponseText(response, stallGuard);
+            const responseBody = JSON.parse(responseText);
+            if (!Array.isArray(responseBody)) {
+                throw new Error('Failed to parse response.');
+            }
+            const responseItemTexts = getRawJsonElements(responseText);
+            return responseBody.map((item, index) => {
+                if (!isCloudEvent(item)) {
+                    throw new Error('Failed to parse response item.');
+                }
+                return convertCloudEventToEvent(item, responseItemTexts[index]);
+            });
+        }));
+    }
+    readEvents(subject, options, signal) {
+        const url = this.#getUrl('/api/v1/read-events');
+        const apiToken = this.#apiToken;
+        const stallTimeout = this.#stallTimeout;
+        return streamWithStallGuard({ stallTimeout, signal }, async function* (stallGuard) {
+            const response = await stallGuard.send(url, {
+                method: 'POST',
+                headers: {
+                    authorization: `Bearer ${apiToken}`,
+                    'content-type': 'application/json',
+                },
+                body: JSON.stringify({
+                    subject,
+                    options,
+                }),
+            });
+            const body = await getStreamBody(response, stallGuard, 'readEvents', 'read events');
+            for await (const { value: line, text } of readNdJsonStream(body, stallGuard.signal, stallGuard)) {
+                if (isStreamError(line)) {
+                    throw createStreamError(line.payload.error);
+                }
+                if (isStreamCloudEvent(line)) {
+                    yield convertCloudEventToEvent(line.payload, getRawJsonMember(text, 'payload'));
+                    continue;
+                }
+                throw new Error('Failed to read events.');
+            }
+        });
+    }
+    runEventQlQuery(query, signal) {
+        const url = this.#getUrl('/api/v1/run-eventql-query');
+        const apiToken = this.#apiToken;
+        const stallTimeout = this.#stallTimeout;
+        return streamWithStallGuard({ stallTimeout, signal }, async function* (stallGuard) {
+            const response = await stallGuard.send(url, {
+                method: 'POST',
+                headers: {
+                    authorization: `Bearer ${apiToken}`,
+                    'content-type': 'application/json',
+                },
+                body: JSON.stringify({ query }),
+            });
+            const body = await getStreamBody(response, stallGuard, 'runEventQlQuery', 'run EventQL query');
+            for await (const { value: line } of readNdJsonStream(body, stallGuard.signal, stallGuard)) {
+                if (isStreamHeartbeat(line)) {
+                    continue;
+                }
+                if (isStreamError(line)) {
+                    throw createStreamError(line.payload.error);
+                }
+                if (isStreamRow(line)) {
+                    yield line.payload;
+                    continue;
+                }
+                throw new Error('Failed to run EventQL query.');
+            }
+        });
+    }
+    observeEvents(subject, options, signal) {
+        const url = this.#getUrl('/api/v1/observe-events');
+        const apiToken = this.#apiToken;
+        const stallTimeout = this.#stallTimeout;
+        return streamWithStallGuard({ stallTimeout, signal }, async function* (stallGuard) {
+            const response = await stallGuard.send(url, {
+                method: 'POST',
+                headers: {
+                    authorization: `Bearer ${apiToken}`,
+                    'content-type': 'application/json',
+                },
+                body: JSON.stringify({
+                    subject,
+                    options,
+                }),
+            });
+            const body = await getStreamBody(response, stallGuard, 'observeEvents', 'observe events');
+            for await (const { value: line, text } of readNdJsonStream(body, stallGuard.signal, stallGuard)) {
+                if (isStreamHeartbeat(line)) {
+                    continue;
+                }
+                if (isStreamError(line)) {
+                    throw createStreamError(line.payload.error);
+                }
+                if (isStreamCloudEvent(line)) {
+                    yield convertCloudEventToEvent(line.payload, getRawJsonMember(text, 'payload'));
+                    continue;
+                }
+                throw new Error('Failed to observe events.');
+            }
+            // Observing never ends on its own, so a stream that ends broke off,
+            // unless the caller aborted it.
+            stallGuard.throwIfStalled();
+            if (!signal?.aborted) {
+                throw createStreamEndedError('observe events');
+            }
+        });
+    }
+    async registerEventSchema(eventType, schema, signal) {
+        const url = this.#getUrl('/api/v1/register-event-schema');
+        const stallTimeout = this.#stallTimeout;
+        const body = JSON.stringify({
+            eventType,
+            schema,
+        });
+        await runWrite({ signal, isRefusal: isV1Refusal }, 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,
+            });
+            await assertOk(response, stallGuard, 'registerEventSchema');
+        }));
+    }
+    // The v1 API always reads the subjects below the subject as well. Reading
+    // only the subject itself keeps the subject alone, which the server lists
+    // at most once, so the request ends once it arrives. The server lists it
+    // as it keeps it, so it is compared as the server keeps it, which makes
+    // '/test/' keep '/test', as the v2 API does.
+    readSubjects(subject, { recursive }, signal) {
+        const url = this.#getUrl('/api/v1/read-subjects');
+        const apiToken = this.#apiToken;
+        const stallTimeout = this.#stallTimeout;
+        // A caller without types may pass a subject that is not a string, which
+        // the server refuses with an error of its own, so the client normalizes
+        // only a string, and only to read the subject alone.
+        const normalizedSubject = !recursive && isString(subject) ? normalizeSubject(subject) : subject;
+        return streamWithStallGuard({ stallTimeout, signal }, async function* (stallGuard) {
+            const response = await stallGuard.send(url, {
+                method: 'POST',
+                headers: {
+                    authorization: `Bearer ${apiToken}`,
+                    'content-type': 'application/json',
+                },
+                body: JSON.stringify({
+                    baseSubject: subject,
+                }),
+            });
+            const body = await getStreamBody(response, stallGuard, 'readSubjects', 'read subjects');
+            for await (const { value: line } of readNdJsonStream(body, stallGuard.signal, stallGuard)) {
+                if (isStreamError(line)) {
+                    throw createStreamError(line.payload.error);
+                }
+                if (isStreamSubject(line)) {
+                    if (recursive) {
+                        yield line.payload.subject;
+                        continue;
+                    }
+                    if (line.payload.subject === normalizedSubject) {
+                        yield line.payload.subject;
+                        return;
+                    }
+                    continue;
+                }
+                throw new Error('Failed to read subjects.');
+            }
+        });
+    }
+    async readEventType(eventType, signal) {
+        const url = this.#getUrl('/api/v1/read-event-type');
+        const stallTimeout = this.#stallTimeout;
+        return await runWithStallGuard({ stallTimeout, signal }, async (stallGuard) => {
+            const response = await stallGuard.send(url, {
+                method: 'POST',
+                headers: {
+                    authorization: `Bearer ${this.#apiToken}`,
+                    'content-type': 'application/json',
+                },
+                body: JSON.stringify({
+                    eventType,
+                }),
+            });
+            await assertOk(response, stallGuard, 'readEventType');
+            const responseBody = JSON.parse(await readResponseText(response, stallGuard));
+            if (!hasShapeOf(responseBody, {
+                eventType: isString,
+                isPhantom: isBoolean,
+            })) {
+                throw new Error('Failed to parse response.');
+            }
+            return toEventType(responseBody);
+        });
+    }
+    readEventTypes(signal) {
+        const url = this.#getUrl('/api/v1/read-event-types');
+        const apiToken = this.#apiToken;
+        const stallTimeout = this.#stallTimeout;
+        return streamWithStallGuard({ stallTimeout, signal }, async function* (stallGuard) {
+            const response = await stallGuard.send(url, {
+                method: 'POST',
+                headers: {
+                    authorization: `Bearer ${apiToken}`,
+                },
+            });
+            const body = await getStreamBody(response, stallGuard, 'readEventTypes', 'read event types');
+            for await (const { value: line } of readNdJsonStream(body, stallGuard.signal, stallGuard)) {
+                if (isStreamHeartbeat(line)) {
+                    continue;
+                }
+                if (isStreamError(line)) {
+                    throw createStreamError(line.payload.error);
+                }
+                if (isStreamEventType(line)) {
+                    yield toEventType(line.payload);
+                    continue;
+                }
+                throw new Error('Failed to read event types.');
+            }
+        });
+    }
+}
+export { V1Transport };

package/dist/v1/getV1ErrorCode.d.ts

@@ -0,0 +1,4 @@
+import { ErrorCode } from '../ErrorCode.js';
+import type { Transport } from '../Transport.js';
+declare const getV1ErrorCode: (call: keyof Transport, status: number, description: string) => ErrorCode | undefined;
+export { getV1ErrorCode };

package/dist/v1/getV1ErrorCode.js

@@ -0,0 +1,65 @@
+import { ErrorCode } from '../ErrorCode.js';
+// The errors of the v1 API that clearly match a code of the v2 API, by the
+// status and the text that EventSourcingDB 1.2.0 sends for them.
+const mappings = [
+    {
+        call: 'writeEvents',
+        status: 409,
+        text: 'state conflict: precondition failed',
+        code: ErrorCode.preconditionViolated,
+    },
+    {
+        call: 'writeEvents',
+        status: 409,
+        text: 'state conflict: exceeded max store capacity',
+        code: ErrorCode.capacityExceeded,
+    },
+    {
+        call: 'writeEvents',
+        status: 409,
+        text: 'schema conflict: event candidate does not match schema',
+        code: ErrorCode.eventSchemaViolated,
+    },
+    {
+        call: 'registerEventSchema',
+        status: 409,
+        text: 'schema conflict: schema already exists',
+        code: ErrorCode.eventSchemaAlreadyRegistered,
+    },
+    {
+        call: 'registerEventSchema',
+        status: 409,
+        text: 'schema conflict: event with ID',
+        code: ErrorCode.eventSchemaViolated,
+    },
+    {
+        call: 'readEvents',
+        status: 409,
+        text: 'state conflict: fromLatestEvent results in an event ID greater than upperBound ID',
+        code: ErrorCode.rangeUnsatisfiable,
+    },
+    {
+        call: 'readEventType',
+        status: 404,
+        text: '',
+        code: ErrorCode.eventTypeUnknown,
+    },
+    {
+        call: undefined,
+        status: 503,
+        text: 'the current operation mode conflicts with the given request',
+        code: ErrorCode.storeReadOnly,
+    },
+    {
+        call: 'writeEvents',
+        status: 507,
+        text: '',
+        code: ErrorCode.licenseInvalid,
+    },
+];
+// Assigns the code of the v2 API to an error of the v1 API that clearly
+// matches one. Every other error of the v1 API has no code.
+const getV1ErrorCode = (call, status, description) => mappings.find(mapping => (mapping.call === undefined || mapping.call === call) &&
+    mapping.status === status &&
+    description.startsWith(mapping.text))?.code;
+export { getV1ErrorCode };

package/dist/v1/isV1Refusal.d.ts

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

package/dist/v1/isV1Refusal.js

@@ -0,0 +1,8 @@
+const statusServiceUnavailable = 503;
+const statusInsufficientStorage = 507;
+// Tells whether the v1 API refused a write before storing anything, which it
+// does with a status of 4xx, 503, or 507.
+const isV1Refusal = (error) => (error.status >= 400 && error.status < 500) ||
+    error.status === statusServiceUnavailable ||
+    error.status === statusInsufficientStorage;
+export { isV1Refusal };

package/dist/v1/normalizeSubject.d.ts

@@ -0,0 +1,2 @@
+declare const normalizeSubject: (subject: string) => string;
+export { normalizeSubject };

package/dist/v1/normalizeSubject.js

@@ -0,0 +1,6 @@
+const leadingAndTrailingSlashes = /^\/+|\/+$/gu;
+// Returns the subject as the server keeps it, which is a slash followed by
+// the subject without its leading and trailing slashes, so '/test/' becomes
+// '/test', and '/' stays '/'.
+const normalizeSubject = (subject) => `/${subject.replaceAll(leadingAndTrailingSlashes, '')}`;
+export { normalizeSubject };

package/dist/v1/stream/StreamRow.js

@@ -0,0 +1 @@
+export {};

package/dist/v1/stream/StreamSubject.js

@@ -0,0 +1 @@
+export {};

package/dist/{stream → v1/stream}/isStreamCloudEvent.js

@@ -1,8 +1,8 @@
-import { hasShapeOf } from '../types/hasShapeOf.js';
-import { isRecord } from '../types/isRecord.js';
-import { isString } from '../types/isString.js';
-import { isStringOrNull } from '../types/isStringOrNull.js';
-import { isStringOrUndefined } from '../types/isStringOrUndefined.js';
+import { hasShapeOf } from '../../types/hasShapeOf.js';
+import { isRecord } from '../../types/isRecord.js';
+import { isString } from '../../types/isString.js';
+import { isStringOrNull } from '../../types/isStringOrNull.js';
+import { isStringOrUndefined } from '../../types/isStringOrUndefined.js';
 const isStreamCloudEvent = (line) => hasShapeOf(line, {
     type: (value) => value === 'event',
     payload: {

package/dist/{stream → v1/stream}/isStreamError.js

@@ -1,5 +1,5 @@
-import { hasShapeOf } from '../types/hasShapeOf.js';
-import { isString } from '../types/isString.js';
+import { hasShapeOf } from '../../types/hasShapeOf.js';
+import { isString } from '../../types/isString.js';
 const isStreamError = (line) => hasShapeOf(line, {
     type: (value) => value === 'error',
     payload: {

package/dist/{stream → v1/stream}/isStreamEventType.js

@@ -1,6 +1,6 @@
-import { hasShapeOf } from '../types/hasShapeOf.js';
-import { isBoolean } from '../types/isBoolean.js';
-import { isString } from '../types/isString.js';
+import { hasShapeOf } from '../../types/hasShapeOf.js';
+import { isBoolean } from '../../types/isBoolean.js';
+import { isString } from '../../types/isString.js';
 const isStreamEventType = (line) => hasShapeOf(line, {
     type: (value) => value === 'eventType',
     payload: {

package/dist/{stream → v1/stream}/isStreamHeartbeat.js

@@ -1,4 +1,4 @@
-import { hasShapeOf } from '../types/hasShapeOf.js';
+import { hasShapeOf } from '../../types/hasShapeOf.js';
 const isStreamHeartbeat = (line) => hasShapeOf(line, {
     type: (value) => value === 'heartbeat',
 });

package/dist/{stream → v1/stream}/isStreamRow.js

@@ -1,4 +1,4 @@
-import { hasShapeOf } from '../types/hasShapeOf.js';
+import { hasShapeOf } from '../../types/hasShapeOf.js';
 const isStreamRow = (line) => hasShapeOf(line, {
     type: (value) => value === 'row',
     payload: (value) => value !== undefined,

package/dist/{stream → v1/stream}/isStreamSubject.js

@@ -1,5 +1,5 @@
-import { hasShapeOf } from '../types/hasShapeOf.js';
-import { isString } from '../types/isString.js';
+import { hasShapeOf } from '../../types/hasShapeOf.js';
+import { isString } from '../../types/isString.js';
 const isStreamSubject = (line) => hasShapeOf(line, {
     type: (value) => value === 'subject',
     payload: {

package/dist/v2/V2Event.d.ts

@@ -0,0 +1,16 @@
+interface V2Event {
+    specversion: string;
+    id: string;
+    time: string;
+    source: string;
+    subject: string;
+    type: string;
+    datacontenttype: string;
+    data: Record<string, unknown>;
+    hash: string;
+    predecessorhash: string;
+    traceparent: string | null;
+    tracestate: string | null;
+    signature: string | null;
+}
+export type { V2Event };

package/dist/v2/V2Event.js

@@ -0,0 +1 @@
+export {};

package/dist/v2/V2Item.d.ts

@@ -0,0 +1,6 @@
+interface V2Item {
+    type: string;
+    data: unknown;
+    text: string;
+}
+export type { V2Item };

package/dist/v2/V2Item.js

@@ -0,0 +1 @@
+export {};

package/dist/v2/V2Transport.d.ts

@@ -0,0 +1,23 @@
+import type { Event } from '../Event.js';
+import type { EventCandidate } from '../EventCandidate.js';
+import type { EventType } from '../EventType.js';
+import type { ObserveEventsOptions } from '../ObserveEventsOptions.js';
+import type { Precondition } from '../Precondition.js';
+import type { ReadEventsOptions } from '../ReadEventsOptions.js';
+import type { ReadSubjectsOptions } from '../ReadSubjectsOptions.js';
+import type { Transport, TransportOptions } from '../Transport.js';
+declare class V2Transport implements Transport {
+    #private;
+    constructor({ url, apiToken, stallTimeout }: TransportOptions);
+    ping(signal?: AbortSignal): Promise<void>;
+    verifyApiToken(signal?: AbortSignal): Promise<void>;
+    writeEvents(events: EventCandidate[], preconditions: Precondition[], signal?: AbortSignal): Promise<Event[]>;
+    readEvents(subject: string, options: ReadEventsOptions, signal?: AbortSignal): AsyncGenerator<Event, void, void>;
+    runEventQlQuery(query: string, signal?: AbortSignal): AsyncGenerator<unknown, void, void>;
+    observeEvents(subject: string, options: ObserveEventsOptions, signal?: AbortSignal): AsyncGenerator<Event, void, void>;
+    registerEventSchema(eventType: string, schema: Record<string, unknown>, signal?: AbortSignal): Promise<void>;
+    readSubjects(subject: string, { recursive }: ReadSubjectsOptions, signal?: AbortSignal): AsyncGenerator<string, void, void>;
+    readEventType(eventType: string, signal?: AbortSignal): Promise<EventType>;
+    readEventTypes(signal?: AbortSignal): AsyncGenerator<EventType, void, void>;
+}
+export { V2Transport };