@nimbus-cqrs/eventsourcingdb 2.0.0-beta.0

package/esm/deps/jsr.io/@std/ulid/1.0.0/_util.d.ts

@@ -0,0 +1,14 @@
+/** Type for a ULID generator function. */
+export type ULID = (seedTime?: number) => string;
+export declare const ENCODING = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+export declare const ENCODING_LEN: number;
+export declare const TIME_MAX: number;
+export declare const TIME_LEN = 10;
+export declare const RANDOM_LEN = 16;
+export declare const ULID_LEN: number;
+export declare function encodeTime(timestamp: number): string;
+export declare function encodeRandom(): string;
+export declare function incrementBase32(str: string): string;
+/** Generates a monotonically increasing ULID. */
+export declare function monotonicFactory(encodeRand?: typeof encodeRandom): ULID;
+//# sourceMappingURL=_util.d.ts.map

package/esm/deps/jsr.io/@std/ulid/1.0.0/_util.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_util.d.ts","sourceRoot":"","sources":["../../../../../../src/deps/jsr.io/@std/ulid/1.0.0/_util.ts"],"names":[],"mappings":"AAEA,0CAA0C;AAC1C,MAAM,MAAM,IAAI,GAAG,CAAC,QAAQ,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;AAIjD,eAAO,MAAM,QAAQ,qCAAqC,CAAC;AAC3D,eAAO,MAAM,YAAY,QAAkB,CAAC;AAC5C,eAAO,MAAM,QAAQ,QAAsB,CAAC;AAC5C,eAAO,MAAM,QAAQ,KAAK,CAAC;AAC3B,eAAO,MAAM,UAAU,KAAK,CAAC;AAC7B,eAAO,MAAM,QAAQ,QAAwB,CAAC;AAM9C,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAapD;AAED,wBAAgB,YAAY,IAAI,MAAM,CAOrC;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAkBnD;AAED,iDAAiD;AACjD,wBAAgB,gBAAgB,CAAC,UAAU,sBAAe,GAAG,IAAI,CAYhE"}

package/esm/deps/jsr.io/@std/ulid/1.0.0/_util.js

@@ -0,0 +1,65 @@
+// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
+// These values should NEVER change. If
+// they do, we're no longer making ulids!
+export const ENCODING = "0123456789ABCDEFGHJKMNPQRSTVWXYZ"; // Crockford's Base32
+export const ENCODING_LEN = ENCODING.length;
+export const TIME_MAX = Math.pow(2, 48) - 1;
+export const TIME_LEN = 10;
+export const RANDOM_LEN = 16;
+export const ULID_LEN = TIME_LEN + RANDOM_LEN;
+function replaceCharAt(str, index, char) {
+    return str.substring(0, index) + char + str.substring(index + 1);
+}
+export function encodeTime(timestamp) {
+    if (!Number.isInteger(timestamp) || timestamp < 0 || timestamp > TIME_MAX) {
+        throw new RangeError(`Time must be a positive integer less than ${TIME_MAX}`);
+    }
+    let str = "";
+    for (let len = TIME_LEN; len > 0; len--) {
+        const mod = timestamp % ENCODING_LEN;
+        str = ENCODING[mod] + str;
+        timestamp = Math.floor(timestamp / ENCODING_LEN);
+    }
+    return str;
+}
+export function encodeRandom() {
+    let str = "";
+    const bytes = crypto.getRandomValues(new Uint8Array(RANDOM_LEN));
+    for (const byte of bytes) {
+        str += ENCODING[byte % ENCODING_LEN];
+    }
+    return str;
+}
+export function incrementBase32(str) {
+    let index = str.length;
+    let char;
+    let charIndex;
+    const maxCharIndex = ENCODING_LEN - 1;
+    while (--index >= 0) {
+        char = str[index];
+        charIndex = ENCODING.indexOf(char);
+        if (charIndex === -1) {
+            throw new TypeError("Incorrectly encoded string");
+        }
+        if (charIndex === maxCharIndex) {
+            str = replaceCharAt(str, index, ENCODING[0]);
+            continue;
+        }
+        return replaceCharAt(str, index, ENCODING[charIndex + 1]);
+    }
+    throw new Error("Cannot increment this string");
+}
+/** Generates a monotonically increasing ULID. */
+export function monotonicFactory(encodeRand = encodeRandom) {
+    let lastTime = 0;
+    let lastRandom;
+    return function ulid(seedTime = Date.now()) {
+        if (seedTime <= lastTime) {
+            const incrementedRandom = (lastRandom = incrementBase32(lastRandom));
+            return encodeTime(lastTime) + incrementedRandom;
+        }
+        lastTime = seedTime;
+        const newRandom = (lastRandom = encodeRand());
+        return encodeTime(seedTime) + newRandom;
+    };
+}

package/esm/deps/jsr.io/@std/ulid/1.0.0/decode_time.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Extracts the number of milliseconds since the Unix epoch that had passed when
+ * the ULID was generated. If the ULID is malformed, an error will be thrown.
+ *
+ * @example Decode the time from a ULID
+ * ```ts
+ * import { decodeTime, ulid } from "@std/ulid";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const timestamp = 150_000;
+ * const ulidString = ulid(timestamp);
+ *
+ * assertEquals(decodeTime(ulidString), timestamp);
+ * ```
+ *
+ * @param ulid The ULID to extract the timestamp from.
+ * @returns The number of milliseconds since the Unix epoch that had passed when the ULID was generated.
+ */
+export declare function decodeTime(ulid: string): number;
+//# sourceMappingURL=decode_time.d.ts.map

package/esm/deps/jsr.io/@std/ulid/1.0.0/decode_time.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decode_time.d.ts","sourceRoot":"","sources":["../../../../../../src/deps/jsr.io/@std/ulid/1.0.0/decode_time.ts"],"names":[],"mappings":"AAaA;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAqB/C"}

package/esm/deps/jsr.io/@std/ulid/1.0.0/decode_time.js

@@ -0,0 +1,43 @@
+// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
+// Copyright 2023 Yoshiya Hinosawa. All rights reserved. MIT license.
+// Copyright 2017 Alizain Feerasta. All rights reserved. MIT license.
+// This module is browser compatible.
+import { ENCODING, ENCODING_LEN, TIME_LEN, TIME_MAX, ULID_LEN, } from "./_util.js";
+/**
+ * Extracts the number of milliseconds since the Unix epoch that had passed when
+ * the ULID was generated. If the ULID is malformed, an error will be thrown.
+ *
+ * @example Decode the time from a ULID
+ * ```ts
+ * import { decodeTime, ulid } from "@std/ulid";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const timestamp = 150_000;
+ * const ulidString = ulid(timestamp);
+ *
+ * assertEquals(decodeTime(ulidString), timestamp);
+ * ```
+ *
+ * @param ulid The ULID to extract the timestamp from.
+ * @returns The number of milliseconds since the Unix epoch that had passed when the ULID was generated.
+ */
+export function decodeTime(ulid) {
+    if (ulid.length !== ULID_LEN) {
+        throw new Error(`ULID must be exactly ${ULID_LEN} characters long`);
+    }
+    const time = ulid
+        .substring(0, TIME_LEN)
+        .split("")
+        .reverse()
+        .reduce((carry, char, index) => {
+        const encodingIndex = ENCODING.indexOf(char);
+        if (encodingIndex === -1) {
+            throw new Error(`Invalid ULID character found: ${char}`);
+        }
+        return (carry += encodingIndex * Math.pow(ENCODING_LEN, index));
+    }, 0);
+    if (time > TIME_MAX) {
+        throw new RangeError(`ULID timestamp component exceeds maximum value of ${TIME_MAX}`);
+    }
+    return time;
+}

package/esm/deps/jsr.io/@std/ulid/1.0.0/mod.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Utilities for generating and working with
+ * {@link https://github.com/ulid/spec | Universally Unique Lexicographically Sortable Identifiers (ULIDs)}.
+ *
+ * To generate a ULID use the {@linkcode ulid} function. This will generate a
+ * ULID based on the current time.
+ *
+ * ```ts no-assert
+ * import { ulid } from "@std/ulid";
+ *
+ * ulid(); // 01HYFKMDF3HVJ4J3JZW8KXPVTY
+ * ```
+ *
+ * {@linkcode ulid} does not guarantee that the ULIDs will be strictly
+ * increasing for the same current time. If you need to guarantee that the ULIDs
+ * will be strictly increasing, even for the same current time, use the
+ * {@linkcode monotonicUlid} function.
+ *
+ * ```ts no-assert
+ * import { monotonicUlid } from "@std/ulid";
+ *
+ * monotonicUlid(); // 01HYFKHG5F8RHM2PM3D7NSTDAS
+ * monotonicUlid(); // 01HYFKHG5F8RHM2PM3D7NSTDAT
+ * ```
+ *
+ * Because each ULID encodes the time it was generated, you can extract the
+ * timestamp from a ULID using the {@linkcode decodeTime} function.
+ *
+ * ```ts
+ * import { decodeTime, ulid } from "@std/ulid";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const timestamp = 150_000;
+ * const ulidString = ulid(timestamp);
+ *
+ * assertEquals(decodeTime(ulidString), timestamp);
+ * ```
+ *
+ * @module
+ */
+export * from "./decode_time.js";
+export * from "./monotonic_ulid.js";
+export * from "./ulid.js";
+//# sourceMappingURL=mod.d.ts.map

package/esm/deps/jsr.io/@std/ulid/1.0.0/mod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../../../../../../src/deps/jsr.io/@std/ulid/1.0.0/mod.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,WAAW,CAAC"}

package/esm/deps/jsr.io/@std/ulid/1.0.0/mod.js

@@ -0,0 +1,47 @@
+// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
+// Copyright 2023 Yoshiya Hinosawa. All rights reserved. MIT license.
+// Copyright 2017 Alizain Feerasta. All rights reserved. MIT license.
+// This module is browser compatible.
+/**
+ * Utilities for generating and working with
+ * {@link https://github.com/ulid/spec | Universally Unique Lexicographically Sortable Identifiers (ULIDs)}.
+ *
+ * To generate a ULID use the {@linkcode ulid} function. This will generate a
+ * ULID based on the current time.
+ *
+ * ```ts no-assert
+ * import { ulid } from "@std/ulid";
+ *
+ * ulid(); // 01HYFKMDF3HVJ4J3JZW8KXPVTY
+ * ```
+ *
+ * {@linkcode ulid} does not guarantee that the ULIDs will be strictly
+ * increasing for the same current time. If you need to guarantee that the ULIDs
+ * will be strictly increasing, even for the same current time, use the
+ * {@linkcode monotonicUlid} function.
+ *
+ * ```ts no-assert
+ * import { monotonicUlid } from "@std/ulid";
+ *
+ * monotonicUlid(); // 01HYFKHG5F8RHM2PM3D7NSTDAS
+ * monotonicUlid(); // 01HYFKHG5F8RHM2PM3D7NSTDAT
+ * ```
+ *
+ * Because each ULID encodes the time it was generated, you can extract the
+ * timestamp from a ULID using the {@linkcode decodeTime} function.
+ *
+ * ```ts
+ * import { decodeTime, ulid } from "@std/ulid";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const timestamp = 150_000;
+ * const ulidString = ulid(timestamp);
+ *
+ * assertEquals(decodeTime(ulidString), timestamp);
+ * ```
+ *
+ * @module
+ */
+export * from "./decode_time.js";
+export * from "./monotonic_ulid.js";
+export * from "./ulid.js";

package/esm/deps/jsr.io/@std/ulid/1.0.0/monotonic_ulid.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Generate a ULID that monotonically increases even for the same millisecond,
+ * optionally passing the current time. If the current time is not passed, it
+ * will default to `Date.now()`.
+ *
+ * Unlike the {@linkcode ulid} function, this function is guaranteed to return
+ * strictly increasing ULIDs, even for the same seed time, but only if the seed
+ * time only ever increases. If the seed time ever goes backwards, the ULID will
+ * still be generated, but it will not be guaranteed to be monotonic with
+ * previous ULIDs for that same seed time.
+ *
+ * @example Generate a monotonic ULID
+ * ```ts no-assert
+ * import { monotonicUlid } from "@std/ulid";
+ *
+ * monotonicUlid(); // 01HYFKHG5F8RHM2PM3D7NSTDAS
+ * monotonicUlid(); // 01HYFKHG5F8RHM2PM3D7NSTDAT
+ * monotonicUlid(); // 01HYFKHHX8H4BRY8BYHAV1BZ2T
+ * ```
+ *
+ * @example Generate a monotonic ULID with a seed time
+ * ```ts no-assert
+ * import { monotonicUlid } from "@std/ulid";
+ *
+ * // Strict ordering for the same timestamp, by incrementing the least-significant random bit by 1
+ * monotonicUlid(150000); // 0000004JFHJJ2Z7X64FN2B4F1Q
+ * monotonicUlid(150000); // 0000004JFHJJ2Z7X64FN2B4F1R
+ * monotonicUlid(150000); // 0000004JFHJJ2Z7X64FN2B4F1S
+ * monotonicUlid(150000); // 0000004JFHJJ2Z7X64FN2B4F1T
+ * monotonicUlid(150000); // 0000004JFHJJ2Z7X64FN2B4F1U
+ *
+ * // A different timestamp will reset the random bits
+ * monotonicUlid(150001); // 0000004JFHJJ2Z7X64FN2B4F1P
+ *
+ * // A previous seed time will not guarantee ordering, and may result in a
+ * // ULID lower than one with the same seed time generated previously
+ * monotonicUlid(150000); // 0000004JFJ7XF6D76ES95SZR0X
+ * ```
+ *
+ * @param seedTime The time to base the ULID on, in milliseconds since the Unix epoch. Defaults to `Date.now()`.
+ * @returns A ULID that is guaranteed to be strictly increasing for the same seed time.
+ */
+export declare function monotonicUlid(seedTime?: number): string;
+//# sourceMappingURL=monotonic_ulid.d.ts.map

package/esm/deps/jsr.io/@std/ulid/1.0.0/monotonic_ulid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"monotonic_ulid.d.ts","sourceRoot":"","sources":["../../../../../../src/deps/jsr.io/@std/ulid/1.0.0/monotonic_ulid.ts"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,wBAAgB,aAAa,CAAC,QAAQ,GAAE,MAAmB,GAAG,MAAM,CAEnE"}

package/esm/deps/jsr.io/@std/ulid/1.0.0/monotonic_ulid.js

@@ -0,0 +1,51 @@
+// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
+// Copyright 2023 Yoshiya Hinosawa. All rights reserved. MIT license.
+// Copyright 2017 Alizain Feerasta. All rights reserved. MIT license.
+// This module is browser compatible.
+import { monotonicFactory } from "./_util.js";
+const defaultMonotonicUlid = monotonicFactory();
+/**
+ * Generate a ULID that monotonically increases even for the same millisecond,
+ * optionally passing the current time. If the current time is not passed, it
+ * will default to `Date.now()`.
+ *
+ * Unlike the {@linkcode ulid} function, this function is guaranteed to return
+ * strictly increasing ULIDs, even for the same seed time, but only if the seed
+ * time only ever increases. If the seed time ever goes backwards, the ULID will
+ * still be generated, but it will not be guaranteed to be monotonic with
+ * previous ULIDs for that same seed time.
+ *
+ * @example Generate a monotonic ULID
+ * ```ts no-assert
+ * import { monotonicUlid } from "@std/ulid";
+ *
+ * monotonicUlid(); // 01HYFKHG5F8RHM2PM3D7NSTDAS
+ * monotonicUlid(); // 01HYFKHG5F8RHM2PM3D7NSTDAT
+ * monotonicUlid(); // 01HYFKHHX8H4BRY8BYHAV1BZ2T
+ * ```
+ *
+ * @example Generate a monotonic ULID with a seed time
+ * ```ts no-assert
+ * import { monotonicUlid } from "@std/ulid";
+ *
+ * // Strict ordering for the same timestamp, by incrementing the least-significant random bit by 1
+ * monotonicUlid(150000); // 0000004JFHJJ2Z7X64FN2B4F1Q
+ * monotonicUlid(150000); // 0000004JFHJJ2Z7X64FN2B4F1R
+ * monotonicUlid(150000); // 0000004JFHJJ2Z7X64FN2B4F1S
+ * monotonicUlid(150000); // 0000004JFHJJ2Z7X64FN2B4F1T
+ * monotonicUlid(150000); // 0000004JFHJJ2Z7X64FN2B4F1U
+ *
+ * // A different timestamp will reset the random bits
+ * monotonicUlid(150001); // 0000004JFHJJ2Z7X64FN2B4F1P
+ *
+ * // A previous seed time will not guarantee ordering, and may result in a
+ * // ULID lower than one with the same seed time generated previously
+ * monotonicUlid(150000); // 0000004JFJ7XF6D76ES95SZR0X
+ * ```
+ *
+ * @param seedTime The time to base the ULID on, in milliseconds since the Unix epoch. Defaults to `Date.now()`.
+ * @returns A ULID that is guaranteed to be strictly increasing for the same seed time.
+ */
+export function monotonicUlid(seedTime = Date.now()) {
+    return defaultMonotonicUlid(seedTime);
+}

package/esm/deps/jsr.io/@std/ulid/1.0.0/ulid.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Generate a ULID, optionally based on a given timestamp. If the timestamp is
+ * not passed, it will default to `Date.now()`.
+ *
+ * Multiple calls to this function with the same seed time will not guarantee
+ * that the ULIDs will be strictly increasing, even if the seed time is the
+ * same. For that, use the {@linkcode monotonicUlid} function.
+ *
+ * @example Generate a ULID
+ * ```ts no-assert
+ * import { ulid } from "@std/ulid";
+ *
+ * ulid(); // 01HYFKMDF3HVJ4J3JZW8KXPVTY
+ * ulid(); // 01HYFKMDF3D2P7G502B9Z2VKV0
+ * ulid(); // 01HYFKMDZQ7JD17CRKDXQSZ3Z4
+ * ```
+ *
+ * @example Generate a ULID with a seed time
+ * ```ts no-assert
+ * import { ulid } from "@std/ulid";
+ *
+ * ulid(150000); // 0000004JFG3EKDRE04TVVDJW7K
+ * ulid(150000); // 0000004JFGN0KHBH0447AK895X
+ * ulid(150000); // 0000004JFGMRDH0PN7SM8BZN06
+ * ```
+ *
+ * @param seedTime The time to base the ULID on, in milliseconds since the Unix epoch. Defaults to `Date.now()`.
+ * @returns A ULID.
+ */
+export declare function ulid(seedTime?: number): string;
+//# sourceMappingURL=ulid.d.ts.map

package/esm/deps/jsr.io/@std/ulid/1.0.0/ulid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ulid.d.ts","sourceRoot":"","sources":["../../../../../../src/deps/jsr.io/@std/ulid/1.0.0/ulid.ts"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,IAAI,CAAC,QAAQ,GAAE,MAAmB,GAAG,MAAM,CAE1D"}

package/esm/deps/jsr.io/@std/ulid/1.0.0/ulid.js

@@ -0,0 +1,37 @@
+// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
+// Copyright 2023 Yoshiya Hinosawa. All rights reserved. MIT license.
+// Copyright 2017 Alizain Feerasta. All rights reserved. MIT license.
+// This module is browser compatible.
+import { encodeRandom, encodeTime } from "./_util.js";
+/**
+ * Generate a ULID, optionally based on a given timestamp. If the timestamp is
+ * not passed, it will default to `Date.now()`.
+ *
+ * Multiple calls to this function with the same seed time will not guarantee
+ * that the ULIDs will be strictly increasing, even if the seed time is the
+ * same. For that, use the {@linkcode monotonicUlid} function.
+ *
+ * @example Generate a ULID
+ * ```ts no-assert
+ * import { ulid } from "@std/ulid";
+ *
+ * ulid(); // 01HYFKMDF3HVJ4J3JZW8KXPVTY
+ * ulid(); // 01HYFKMDF3D2P7G502B9Z2VKV0
+ * ulid(); // 01HYFKMDZQ7JD17CRKDXQSZ3Z4
+ * ```
+ *
+ * @example Generate a ULID with a seed time
+ * ```ts no-assert
+ * import { ulid } from "@std/ulid";
+ *
+ * ulid(150000); // 0000004JFG3EKDRE04TVVDJW7K
+ * ulid(150000); // 0000004JFGN0KHBH0447AK895X
+ * ulid(150000); // 0000004JFGMRDH0PN7SM8BZN06
+ * ```
+ *
+ * @param seedTime The time to base the ULID on, in milliseconds since the Unix epoch. Defaults to `Date.now()`.
+ * @returns A ULID.
+ */
+export function ulid(seedTime = Date.now()) {
+    return encodeTime(seedTime) + encodeRandom();
+}

package/esm/index.d.ts

@@ -0,0 +1,6 @@
+export * from './lib/client.js';
+export * from './lib/eventMapping.js';
+export * from './lib/eventObserver.js';
+export * from './lib/readEvents.js';
+export * from './lib/writeEvents.js';
+//# sourceMappingURL=index.d.ts.map

package/esm/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,wBAAwB,CAAC;AACvC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC"}

package/esm/index.js

@@ -0,0 +1,5 @@
+export * from './lib/client.js';
+export * from './lib/eventMapping.js';
+export * from './lib/eventObserver.js';
+export * from './lib/readEvents.js';
+export * from './lib/writeEvents.js';

package/esm/lib/client.d.ts

@@ -0,0 +1,90 @@
+import { Client } from 'eventsourcingdb';
+import { type EventObserver } from './eventObserver.js';
+/**
+ * Configuration options for setting up the EventSourcingDB client.
+ */
+export type SetupEventSourcingDBClientInput = {
+    /**
+     * The URL of the EventSourcingDB server.
+     */
+    url: URL;
+    /**
+     * The API token for authenticating with EventSourcingDB.
+     */
+    apiToken: string;
+    /**
+     * An optional array of event observers to observe events.
+     */
+    eventObservers?: EventObserver[];
+};
+/**
+ * Initialize and configure the EventSourcingDB client.
+ *
+ * This function creates a singleton client instance, verifies connectivity by pinging
+ * the server, and validates the provided API token. It should be called once at
+ * application startup before using {@link getEventSourcingDBClient}.
+ *
+ * Optionally, you can provide event observers that will start observing events
+ * in the background after the client is initialized.
+ *
+ * @param {SetupEventSourcingDBClientInput} options - The configuration options
+ * @param {URL} options.url - The URL of the EventSourcingDB server
+ * @param {string} options.apiToken - The API token for authentication
+ * @param {EventObserver[]} [options.eventObservers] - Optional array of event observers
+ *
+ * @throws {GenericException} If the connection to EventSourcingDB fails
+ * @throws {GenericException} If the API token is invalid
+ *
+ * @example
+ * ```ts
+ * import { setupEventSourcingDBClient } from '@nimbus/eventsourcingdb';
+ * import type { Event } from 'eventsourcingdb';
+ *
+ * await setupEventSourcingDBClient({
+ *     url: new URL(process.env.ESDB_URL ?? ''),
+ *     apiToken: process.env.ESDB_API_TOKEN ?? '',
+ *     eventObservers: [
+ *         {
+ *             subject: '/users',
+ *             recursive: true,
+ *             lowerBound: {
+ *                 id: 'last-processed-event-id',
+ *                 type: 'exclusive',
+ *             },
+ *             fromLatestEvent: {
+ *                 subject: '/users',
+ *                 type: 'io.nimbus.users.invited',
+ *                 ifEventIsMissing: 'read-everything',
+ *             },
+ *             eventHandler: async (event: Event) => {
+ *                 console.log('Received event:', event);
+ *             },
+ *             retryOptions: {
+ *                 maxRetries: 3,
+ *                 initialRetryDelayMs: 3000,
+ *             },
+ *         },
+ *     ],
+ * });
+ * ```
+ */
+export declare const setupEventSourcingDBClient: ({ url, apiToken, eventObservers }: SetupEventSourcingDBClientInput) => Promise<void>;
+/**
+ * Get the EventSourcingDB client instance.
+ *
+ * Returns the singleton client instance that was created by {@link setupEventSourcingDBClient}.
+ * This function must be called after the client has been initialized.
+ *
+ * @returns {Client} The EventSourcingDB client instance
+ *
+ * @throws {GenericException} If the client has not been initialized via setupEventSourcingDBClient
+ *
+ * @example
+ * ```ts
+ * import { getEventSourcingDBClient } from '@nimbus/eventsourcingdb';
+ *
+ * const client = getEventSourcingDBClient();
+ * ```
+ */
+export declare const getEventSourcingDBClient: () => Client;
+//# sourceMappingURL=client.d.ts.map

package/esm/lib/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/lib/client.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AACzC,OAAO,EAAE,KAAK,aAAa,EAAqB,MAAM,oBAAoB,CAAC;AAI3E;;GAEG;AACH,MAAM,MAAM,+BAA+B,GAAG;IAC1C;;OAEG;IACH,GAAG,EAAE,GAAG,CAAC;IACT;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB;;OAEG;IACH,cAAc,CAAC,EAAE,aAAa,EAAE,CAAC;CACpC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,eAAO,MAAM,0BAA0B,GACnC,mCAAmC,+BAA+B,KACnE,OAAO,CAAC,IAAI,CA0Cd,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,wBAAwB,QAAO,MAQ3C,CAAC"}

package/esm/lib/client.js

@@ -0,0 +1,112 @@
+import { GenericException, getLogger } from '../deps/jsr.io/@nimbus/core/2.0.0/src/index.js';
+import { Client } from 'eventsourcingdb';
+import { initEventObserver } from './eventObserver.js';
+let eventSourcingDBClient = null;
+/**
+ * Initialize and configure the EventSourcingDB client.
+ *
+ * This function creates a singleton client instance, verifies connectivity by pinging
+ * the server, and validates the provided API token. It should be called once at
+ * application startup before using {@link getEventSourcingDBClient}.
+ *
+ * Optionally, you can provide event observers that will start observing events
+ * in the background after the client is initialized.
+ *
+ * @param {SetupEventSourcingDBClientInput} options - The configuration options
+ * @param {URL} options.url - The URL of the EventSourcingDB server
+ * @param {string} options.apiToken - The API token for authentication
+ * @param {EventObserver[]} [options.eventObservers] - Optional array of event observers
+ *
+ * @throws {GenericException} If the connection to EventSourcingDB fails
+ * @throws {GenericException} If the API token is invalid
+ *
+ * @example
+ * ```ts
+ * import { setupEventSourcingDBClient } from '@nimbus/eventsourcingdb';
+ * import type { Event } from 'eventsourcingdb';
+ *
+ * await setupEventSourcingDBClient({
+ *     url: new URL(process.env.ESDB_URL ?? ''),
+ *     apiToken: process.env.ESDB_API_TOKEN ?? '',
+ *     eventObservers: [
+ *         {
+ *             subject: '/users',
+ *             recursive: true,
+ *             lowerBound: {
+ *                 id: 'last-processed-event-id',
+ *                 type: 'exclusive',
+ *             },
+ *             fromLatestEvent: {
+ *                 subject: '/users',
+ *                 type: 'io.nimbus.users.invited',
+ *                 ifEventIsMissing: 'read-everything',
+ *             },
+ *             eventHandler: async (event: Event) => {
+ *                 console.log('Received event:', event);
+ *             },
+ *             retryOptions: {
+ *                 maxRetries: 3,
+ *                 initialRetryDelayMs: 3000,
+ *             },
+ *         },
+ *     ],
+ * });
+ * ```
+ */
+export const setupEventSourcingDBClient = async ({ url, apiToken, eventObservers }) => {
+    eventSourcingDBClient = new Client(url, apiToken);
+    try {
+        await eventSourcingDBClient.ping();
+    }
+    catch (error) {
+        getLogger().critical({
+            category: 'Nimbus',
+            message: 'Could not connect to EventSourcingDB',
+            error: error,
+        });
+        throw new GenericException('Could not connect to EventSourcingDB');
+    }
+    try {
+        await eventSourcingDBClient.verifyApiToken();
+    }
+    catch (error) {
+        getLogger().error({
+            category: 'Nimbus',
+            message: 'Invalid API token. Please check your API token.',
+            error: error,
+        });
+        throw new GenericException('Invalid API token. Please check your API token.');
+    }
+    getLogger().info({
+        category: 'Nimbus',
+        message: 'EventSourcingDB client initialized successfully',
+    });
+    if (eventObservers?.length) {
+        for (const eventObserver of eventObservers) {
+            initEventObserver(eventObserver);
+        }
+    }
+};
+/**
+ * Get the EventSourcingDB client instance.
+ *
+ * Returns the singleton client instance that was created by {@link setupEventSourcingDBClient}.
+ * This function must be called after the client has been initialized.
+ *
+ * @returns {Client} The EventSourcingDB client instance
+ *
+ * @throws {GenericException} If the client has not been initialized via setupEventSourcingDBClient
+ *
+ * @example
+ * ```ts
+ * import { getEventSourcingDBClient } from '@nimbus/eventsourcingdb';
+ *
+ * const client = getEventSourcingDBClient();
+ * ```
+ */
+export const getEventSourcingDBClient = () => {
+    if (!eventSourcingDBClient) {
+        throw new GenericException('EventSourcingDB client not yet initialized. Please call setupEventSourcingDBClient() first.');
+    }
+    return eventSourcingDBClient;
+};