@monolayer/sdk 1.2.0-canary.4

package/dist/esm/workloads/stateful/database.js

@@ -0,0 +1,42 @@
+import { StatefulWorkloadWithClient } from "../../workloads/stateful/stateful-workload.js";
+/**
+ * Database workload.
+ *
+ * @group Abstract Classes
+ * @typeParam C - Client type
+ */
+export class Database extends StatefulWorkloadWithClient {
+    /**
+     * Database name.
+     */
+    databaseName;
+    constructor(
+    /**
+     * Database name.
+     */
+    databaseName) {
+        super(databaseName);
+        this.databaseName = databaseName;
+    }
+    /**
+     * Database ID
+     *
+     * **Note:**
+     * Alias of `ìd`.
+     */
+    get databaseId() {
+        return this.id;
+    }
+    /**
+     * @internal
+     */
+    get connStringComponents() {
+        return [
+            this.connStringPrefix(),
+            ...(this.id === this.databaseName
+                ? [this.id]
+                : [this.id, this.databaseName]),
+            "database",
+        ];
+    }
+}

package/dist/esm/workloads/stateful/postgres-database.d.ts

@@ -0,0 +1,29 @@
+import { Database } from "../../workloads/stateful/database.js";
+/**
+ * Workload for PostgreSQL databases.
+ *
+ * A `PostgresDatabase` workload is initialized with:
+ * - A valid database name.
+ *
+ * The environment variable with the connection string for the database is named after
+ * the `databaseName` and the `databaseId`. See examples.
+ *
+ * **NOTES**
+ *
+ * When launching the development or test containers with `npx monolayer start dev`, the environment
+ * variable with the connection string for the workload's Docker container
+ * will be written to the corresponding dotenv file (`.env.local` or `.env.local.test`)
+ *
+ * @example
+ * ```ts
+ * import { PostgreSQL } from "@monolayer/sdk";
+ * import pg from "pg";
+ *
+ * // Workloads on different database servers
+ * export const producstDb = new PostgresDatabase("products");
+ *
+ * export const analyticsDb = new PostgresDatabase("analytics");
+ * ```
+ */
+export declare class PostgresDatabase extends Database {
+}

package/dist/esm/workloads/stateful/postgres-database.js

@@ -0,0 +1,35 @@
+import { Database } from "../../workloads/stateful/database.js";
+/**
+ * Workload for PostgreSQL databases.
+ *
+ * A `PostgresDatabase` workload is initialized with:
+ * - A valid database name.
+ *
+ * The environment variable with the connection string for the database is named after
+ * the `databaseName` and the `databaseId`. See examples.
+ *
+ * **NOTES**
+ *
+ * When launching the development or test containers with `npx monolayer start dev`, the environment
+ * variable with the connection string for the workload's Docker container
+ * will be written to the corresponding dotenv file (`.env.local` or `.env.local.test`)
+ *
+ * @example
+ * ```ts
+ * import { PostgreSQL } from "@monolayer/sdk";
+ * import pg from "pg";
+ *
+ * // Workloads on different database servers
+ * export const producstDb = new PostgresDatabase("products");
+ *
+ * export const analyticsDb = new PostgresDatabase("analytics");
+ * ```
+ */
+export class PostgresDatabase extends Database {
+    /**
+     * @internal
+     */
+    connStringPrefix() {
+        return "pg";
+    }
+}

package/dist/esm/workloads/stateful/redis.d.ts

@@ -0,0 +1,30 @@
+import { StatefulWorkloadWithClient } from "../../workloads/stateful/stateful-workload.js";
+/**
+ * Workload for Redis API compatible servers.
+ *
+ * The `Redis` workload is initialized with:
+ * - A stable ID.
+ * - A client constructor function providing the client of your choice.
+ *   The {@link Redis.client | client } accessor will call this function and memoize its result.
+ *   The expected envirnoment variable name with the connection string is passed as an argument.
+ *
+ * **NOTES**
+ *
+ * When launching the development or test containers with `npx monolayer start dev`, the environment
+ * variable with the connection string for the workload's Docker container
+ * will be written to the corresponding dotenv file (`.env` or `.env.test`)
+ *
+ * @example
+ * ```ts
+ * import { Redis } from "@monolayer/sdk";
+ * import { Redis as IORedis } from "ioredis";
+ *
+ * const cache = new Redis("cache", (envVarName) =>
+ *   new IORedis(process.env[envVarName]!)
+ * );
+ * ```
+ *
+ * @typeParam C - Client type
+ */
+export declare class Redis extends StatefulWorkloadWithClient {
+}

package/dist/esm/workloads/stateful/redis.js

@@ -0,0 +1,36 @@
+import { StatefulWorkloadWithClient } from "../../workloads/stateful/stateful-workload.js";
+/**
+ * Workload for Redis API compatible servers.
+ *
+ * The `Redis` workload is initialized with:
+ * - A stable ID.
+ * - A client constructor function providing the client of your choice.
+ *   The {@link Redis.client | client } accessor will call this function and memoize its result.
+ *   The expected envirnoment variable name with the connection string is passed as an argument.
+ *
+ * **NOTES**
+ *
+ * When launching the development or test containers with `npx monolayer start dev`, the environment
+ * variable with the connection string for the workload's Docker container
+ * will be written to the corresponding dotenv file (`.env` or `.env.test`)
+ *
+ * @example
+ * ```ts
+ * import { Redis } from "@monolayer/sdk";
+ * import { Redis as IORedis } from "ioredis";
+ *
+ * const cache = new Redis("cache", (envVarName) =>
+ *   new IORedis(process.env[envVarName]!)
+ * );
+ * ```
+ *
+ * @typeParam C - Client type
+ */
+export class Redis extends StatefulWorkloadWithClient {
+    /**
+     * @internal
+     */
+    get connStringComponents() {
+        return ["redis", this.id];
+    }
+}

package/dist/esm/workloads/stateful/stateful-workload.d.ts

@@ -0,0 +1,25 @@
+import { Workload } from "../../workloads/workload.js";
+/**
+ * @group Abstract Classes
+ */
+export declare abstract class StatefulWorkload extends Workload {
+}
+/**
+ * @group Abstract Classes
+ * @typeParam C - Client type
+ */
+export declare abstract class StatefulWorkloadWithClient extends StatefulWorkload {
+    constructor(
+    /**
+     * Unique ID.
+     */
+    id: string);
+    /**
+     * Returns the unique environment variable name that should hold the connection string.
+     */
+    get connectionStringEnvVar(): string;
+    /**
+     * Reads the value fron environment variable name that should hold the connection string.
+     */
+    get connectionString(): string;
+}

package/dist/esm/workloads/stateful/stateful-workload.js

@@ -0,0 +1,41 @@
+import { snakeCase } from "case-anything";
+import { Workload } from "../../workloads/workload.js";
+/**
+ * @group Abstract Classes
+ */
+export class StatefulWorkload extends Workload {
+    /**
+     * @hidden
+     * @internal
+     */
+    stateful;
+}
+/**
+ * @group Abstract Classes
+ * @typeParam C - Client type
+ */
+export class StatefulWorkloadWithClient extends StatefulWorkload {
+    constructor(
+    /**
+     * Unique ID.
+     */
+    id) {
+        super(id);
+    }
+    /**
+     * Returns the unique environment variable name that should hold the connection string.
+     */
+    get connectionStringEnvVar() {
+        return snakeCase(["ml", ...this.connStringComponents, "url"].join("_")).toUpperCase();
+    }
+    /**
+     * Reads the value fron environment variable name that should hold the connection string.
+     */
+    get connectionString() {
+        const value = process.env[this.connectionStringEnvVar];
+        if (value === undefined) {
+            throw new Error(`Expected environment variable with connection string ${this.connectionStringEnvVar}`);
+        }
+        return value;
+    }
+}

package/dist/esm/workloads/stateless/broadcast/channel-data.d.ts

@@ -0,0 +1,3 @@
+export declare class ChannelData<D> {
+    _data: D;
+}

package/dist/esm/workloads/stateless/broadcast/channel-data.js

@@ -0,0 +1,2 @@
+export class ChannelData {
+}

package/dist/esm/workloads/stateless/broadcast/client/app-sync-client.d.ts

@@ -0,0 +1,78 @@
+/**
+ * @module AppSyncEventsClient
+ * The main entry point for the AWS AppSync Events WebSocket client library.
+ */
+import type { ChannelData } from "../channel-data.js";
+import type { RouteParams, ValidateUniqueParams } from "../types.js";
+import { EventEmitter } from "./eventEmitter.js";
+/**
+ * Configuration options for the BroadcastClient.
+ */
+export interface BroadcastClientConfig {
+    url: string;
+    authorization: object;
+}
+/**
+ * A client for interacting with the AWS AppSync Events WebSocket API.
+ * This client handles connection management, authentication, and provides
+ * an interface for subscribing to and publishing events.
+ */
+export declare class BroadcastClient<C extends Record<string, ChannelData<any>>> {
+    private _channels;
+    private connectionManager;
+    private subscriptionManager;
+    eventEmitter: EventEmitter;
+    private readonly url;
+    private readonly host;
+    connected: boolean;
+    /**
+     * Creates an instance of AppSyncEventsClient.
+     * @param url The WebSocket URL for the AWS AppSync Events API.
+     * @param authorization The authorization object required for the WebSocket connection.
+     */
+    constructor(opts: {
+        url: string;
+        host: string;
+    });
+    /**
+     * Establishes a connection to the AWS AppSync Events WebSocket API.
+     * @returns A Promise that resolves when the connection is successfully established.
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnects from the AWS AppSync Events WebSocket API.
+     */
+    disconnect(): void;
+    /**
+     * Subscribes to a specified channel to receive real-time events.
+     * @param channel The channel path to subscribe to.
+     * @param authorization The authorization object for the subscription.
+     * @returns The ID of the created subscription.
+     */
+    subscribe(channel: string, authorization: object, callback: (payload: any) => void): string;
+    subscribeTo<T extends keyof C & string>(channelName: ValidateUniqueParams<T>, params: RouteParams<T>, callback: (data: C[T] extends ChannelData<infer P> ? P : never) => void): string | undefined;
+    /**
+     * Unsubscribes from a previously subscribed channel.
+     * @param subscriptionId The ID of the subscription to unsubscribe from.
+     */
+    unsubscribe(subscriptionId: string): void;
+    /**
+     * Publishes events to a specified channel.
+     * @param channel The channel path to publish to.
+     * @param events An array of stringified JSON events to be published.
+     * @param authorization The authorization object for the publish operation.
+     */
+    publish(channel: string, events: string[], authorization: object): void;
+    /**
+     * Registers a listener for a specific event emitted by the client.
+     * @param eventName The name of the event to listen for (e.g., 'message', 'connected', 'disconnected').
+     * @param listener The callback function to be invoked when the event is emitted.
+     */
+    on(eventName: string, listener: (...args: any[]) => void): void;
+    /**
+     * Removes a registered listener for a specific event.
+     * @param eventName The name of the event to remove the listener from.
+     * @param listener The callback function to be removed.
+     */
+    off(eventName: string, listener: (...args: any[]) => void): void;
+}

package/dist/esm/workloads/stateless/broadcast/client/app-sync-client.js

@@ -0,0 +1,130 @@
+/**
+ * @module AppSyncEventsClient
+ * The main entry point for the AWS AppSync Events WebSocket client library.
+ */
+import { v4 as uuidv4 } from "uuid";
+import { ConnectionManager } from "./connectionManager.js";
+import { EventEmitter } from "./eventEmitter.js";
+import { buildPublishMessage } from "./messageBuilder.js";
+import { SubscriptionManager } from "./subscriptionManager.js";
+/**
+ * A client for interacting with the AWS AppSync Events WebSocket API.
+ * This client handles connection management, authentication, and provides
+ * an interface for subscribing to and publishing events.
+ */
+export class BroadcastClient {
+    connectionManager;
+    subscriptionManager;
+    eventEmitter;
+    url;
+    host;
+    connected;
+    /**
+     * Creates an instance of AppSyncEventsClient.
+     * @param url The WebSocket URL for the AWS AppSync Events API.
+     * @param authorization The authorization object required for the WebSocket connection.
+     */
+    constructor(opts) {
+        this.url = opts.url;
+        this.host = opts.host;
+        this.connectionManager = new ConnectionManager(this.url);
+        this.eventEmitter = new EventEmitter();
+        this.subscriptionManager = new SubscriptionManager(this.connectionManager, this.eventEmitter);
+        this.connected = false;
+        // Register a handler for incoming messages from the ConnectionManager
+        this.connectionManager.onMessage((message) => {
+            switch (message.type) {
+                case "subscribe_error":
+                case "publish_error":
+                case "broadcast_error":
+                    this.eventEmitter.emit("error", message);
+                    break;
+                default:
+                    this.eventEmitter.emit("message", message);
+                    break;
+            }
+        });
+        // Register a handler for connection close events from the ConnectionManager
+        this.connectionManager.onClose(() => {
+            this.connected = false;
+            this.eventEmitter.emit("disconnected");
+        });
+    }
+    /**
+     * Establishes a connection to the AWS AppSync Events WebSocket API.
+     * @returns A Promise that resolves when the connection is successfully established.
+     */
+    async connect() {
+        await this.connectionManager.connect();
+        this.connected = true;
+        this.eventEmitter.emit("connected");
+    }
+    /**
+     * Disconnects from the AWS AppSync Events WebSocket API.
+     */
+    disconnect() {
+        this.connected = false;
+        this.connectionManager.disconnect();
+    }
+    /**
+     * Subscribes to a specified channel to receive real-time events.
+     * @param channel The channel path to subscribe to.
+     * @param authorization The authorization object for the subscription.
+     * @returns The ID of the created subscription.
+     */
+    subscribe(channel, authorization, 
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    callback) {
+        return this.subscriptionManager.subscribe(channel, authorization, callback); // Add a dummy callback
+    }
+    subscribeTo(channelName, params, callback) {
+        const path = channelName.replace(/\[([^\]]+)\]/g, (match, key) => {
+            return params[key] || match; // If key is not found, keep the placeholder
+        });
+        // Construct the final URL
+        return this.subscriptionManager.subscribe(`default${path}`, {
+            clientId: this.connectionManager.clientId,
+            host: this.host,
+            Authorization: "--",
+        }, 
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        callback); // Add a dummy callback
+        return;
+    }
+    /**
+     * Unsubscribes from a previously subscribed channel.
+     * @param subscriptionId The ID of the subscription to unsubscribe from.
+     */
+    unsubscribe(subscriptionId) {
+        this.subscriptionManager.unsubscribe(subscriptionId);
+    }
+    /**
+     * Publishes events to a specified channel.
+     * @param channel The channel path to publish to.
+     * @param events An array of stringified JSON events to be published.
+     * @param authorization The authorization object for the publish operation.
+     */
+    publish(channel, events, authorization) {
+        const id = uuidv4();
+        const publishMessage = buildPublishMessage(id, channel, events, authorization);
+        this.connectionManager.send(JSON.stringify(publishMessage));
+    }
+    /**
+     * Registers a listener for a specific event emitted by the client.
+     * @param eventName The name of the event to listen for (e.g., 'message', 'connected', 'disconnected').
+     * @param listener The callback function to be invoked when the event is emitted.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    on(eventName, listener) {
+        this.eventEmitter.on(eventName, listener);
+    }
+    /**
+     * Removes a registered listener for a specific event.
+     * @param eventName The name of the event to remove the listener from.
+     * @param listener The callback function to be removed.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    off(eventName, listener) {
+        this.eventEmitter.off(eventName, listener);
+    }
+}

package/dist/esm/workloads/stateless/broadcast/client/app-sync-publisher.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @module AppSyncEventsClient
+ * The main entry point for the AWS AppSync Events WebSocket client library.
+ */
+import type { ChannelData } from "../channel-data.js";
+import type { RouteParams, ValidateUniqueParams } from "../types.js";
+/**
+ * Configuration options for the BroadcastPublisher.
+ */
+export interface BroadcastPublisherConfig {
+    url: string;
+    authorization: object;
+}
+/**
+ * Publisher.
+ * Handles connection management, authentication, and provides
+ * an interface for publishing events.
+ */
+export declare class BroadcastPublisher<C extends Record<string, ChannelData<any>>> {
+    private _channels;
+    private connectionManager;
+    private eventEmitter;
+    constructor();
+    /**
+     * Establishes a connection to the AWS AppSync Events WebSocket API.
+     * @returns A Promise that resolves when the connection is successfully established.
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnects from the AWS AppSync Events WebSocket API.
+     */
+    disconnect(): void;
+    publishTo<T extends keyof C & string>(channelName: ValidateUniqueParams<T>, params: RouteParams<T>, data: C[T] extends ChannelData<infer P> ? P[] : never): Promise<boolean>;
+}

package/dist/esm/workloads/stateless/broadcast/client/app-sync-publisher.js

@@ -0,0 +1,76 @@
+/**
+ * @module AppSyncEventsClient
+ * The main entry point for the AWS AppSync Events WebSocket client library.
+ */
+import { v4 as uuidv4 } from "uuid";
+import { ConnectionManager } from "./connectionManager.js";
+import { EventEmitter } from "./eventEmitter.js";
+import { buildPublishMessage } from "./messageBuilder.js";
+/**
+ * Publisher.
+ * Handles connection management, authentication, and provides
+ * an interface for publishing events.
+ */
+export class BroadcastPublisher {
+    connectionManager;
+    eventEmitter;
+    constructor() {
+        const urlFromEnv = process.env.ML_BROADCAST_URL ?? "ws://localhost:9311";
+        this.connectionManager = new ConnectionManager(urlFromEnv);
+        this.eventEmitter = new EventEmitter();
+        // Register a handler for incoming messages from the ConnectionManager
+        this.connectionManager.onMessage((message) => {
+            switch (message.type) {
+                case "subscribe_error":
+                case "publish_error":
+                case "broadcast_error":
+                    this.eventEmitter.emit("error", message);
+                    break;
+                default:
+                    this.eventEmitter.emit("message", message);
+                    break;
+            }
+        });
+        // Register a handler for connection close events from the ConnectionManager
+        this.connectionManager.onClose(() => {
+            this.eventEmitter.emit("disconnected");
+        });
+    }
+    /**
+     * Establishes a connection to the AWS AppSync Events WebSocket API.
+     * @returns A Promise that resolves when the connection is successfully established.
+     */
+    async connect() {
+        await this.connectionManager.connect();
+        this.eventEmitter.emit("connected");
+    }
+    /**
+     * Disconnects from the AWS AppSync Events WebSocket API.
+     */
+    disconnect() {
+        this.connectionManager.disconnect();
+    }
+    async publishTo(channelName, params, data) {
+        try {
+            const path = channelName.replace(/\[([^\]]+)\]/g, (match, key) => {
+                return params[key] || match; // If key is not found, keep the placeholder
+            });
+            await this.connect();
+            for (const payload of data) {
+                const events = JSON.stringify(payload);
+                const publishMessage = buildPublishMessage(uuidv4(), `default${path}`, [events], {
+                    clientId: this.connectionManager.clientId,
+                    host: process.env.ML_BROADCAST_HOST ?? "localhost",
+                    Authorization: "--",
+                });
+                this.connectionManager.send(JSON.stringify(publishMessage));
+            }
+            this.disconnect();
+        }
+        catch (e) {
+            console.error(e);
+            return false;
+        }
+        return true;
+    }
+}

package/dist/esm/workloads/stateless/broadcast/client/authenticator.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @module authenticator
+ * This module provides functions for handling the specific authentication
+ * handshake required by the AWS AppSync Events WebSocket protocol.
+ */
+/**
+ * Encodes a JSON authorization object into a Base64URL string.
+ *
+ * The AWS AppSync WebSocket protocol requires authorization credentials to be
+ * passed in a custom subprotocol header. This function takes the authorization
+ * object, stringifies it, and then encodes it into a URL-safe Base64 format
+ * by replacing `+` with `-`, `/` with `_`, and removing padding.
+ *
+ * @param authorization The authorization object to encode.
+ * @returns A Base64URL encoded string representing the authorization object.
+ */
+export declare function encodeAuthorization(authorization: object): string;
+/**
+ * Generates the full WebSocket subprotocol string for authorization.
+ *
+ * This function takes an authorization object, encodes it using `encodeAuthorization`,
+ * and then prepends the `header-` prefix as required by the AWS AppSync Events
+ * WebSocket protocol for the subprotocol header.
+ *
+ * @param authorization The authorization object to use for generating the protocol string.
+ * @returns The complete authorization subprotocol string (e.g., `header-encodedAuthString`).
+ */
+export declare function getAuthProtocol(authorization: object): string;

package/dist/esm/workloads/stateless/broadcast/client/authenticator.js

@@ -0,0 +1,39 @@
+/**
+ * @module authenticator
+ * This module provides functions for handling the specific authentication
+ * handshake required by the AWS AppSync Events WebSocket protocol.
+ */
+/**
+ * Encodes a JSON authorization object into a Base64URL string.
+ *
+ * The AWS AppSync WebSocket protocol requires authorization credentials to be
+ * passed in a custom subprotocol header. This function takes the authorization
+ * object, stringifies it, and then encodes it into a URL-safe Base64 format
+ * by replacing `+` with `-`, `/` with `_`, and removing padding.
+ *
+ * @param authorization The authorization object to encode.
+ * @returns A Base64URL encoded string representing the authorization object.
+ */
+export function encodeAuthorization(authorization) {
+    const jsonString = JSON.stringify(authorization);
+    // Note: Using the browser's btoa function for simplicity. In a Node.js
+    // environment, this would be replaced with Buffer.from(str).toString('base64').
+    // However, for the purpose of this library, we assume a browser-like environment
+    // or a polyfill for btoa.
+    const base64 = btoa(jsonString);
+    return base64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+/**
+ * Generates the full WebSocket subprotocol string for authorization.
+ *
+ * This function takes an authorization object, encodes it using `encodeAuthorization`,
+ * and then prepends the `header-` prefix as required by the AWS AppSync Events
+ * WebSocket protocol for the subprotocol header.
+ *
+ * @param authorization The authorization object to use for generating the protocol string.
+ * @returns The complete authorization subprotocol string (e.g., `header-encodedAuthString`).
+ */
+export function getAuthProtocol(authorization) {
+    const encodedHeader = encodeAuthorization(authorization);
+    return `header-${encodedHeader}`;
+}

package/dist/esm/workloads/stateless/broadcast/client/broadcast-provider.d.ts

@@ -0,0 +1,17 @@
+import { type ReactNode } from "react";
+import type { ChannelData } from "../../../../workloads/stateless/broadcast/channel-data.js";
+import { BroadcastClient } from "./app-sync-client.js";
+export type BroadcastContext = {
+    ws: BroadcastClient<any>;
+    connected: boolean;
+} | null;
+export declare const BroadcastProvider: import("react").Context<BroadcastContext>;
+export interface BroadcastContextProviderProps {
+    urlAndHost: {
+        url: string;
+        host: string;
+    };
+    children: ReactNode;
+}
+export declare function BroadcastContextProvider({ urlAndHost, children, }: BroadcastContextProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare function useWebSocket<T extends Record<string, ChannelData<any>>>(): BroadcastClient<T>;