@monolayer/sdk 1.2.0-canary.4

package/dist/cjs/workloads/assertions.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertRedis = assertRedis;
+exports.assertPostgresDatabase = assertPostgresDatabase;
+exports.assertBucket = assertBucket;
+exports.assertCron = assertCron;
+exports.assertTask = assertTask;
+exports.assertBroadcast = assertBroadcast;
+function assertRedis(workload) { }
+function assertPostgresDatabase(workload) { }
+function assertBucket(workload) { }
+function assertCron(workload) { }
+function assertTask(workload) { }
+function assertBroadcast(workload) { }

package/dist/cjs/workloads/stateful/bucket.d.ts

@@ -0,0 +1,82 @@
+import { StatefulWorkload } from "../../workloads/stateful/stateful-workload.js";
+/**
+ * Workload for an AWS S3 compatible storage.
+ *
+ * The `Bucket` workload is initialized with:
+ * - A valid bucket name.
+ *
+ * **NOTES**
+ *
+ * Launching the development or test containers with `npx monolayer start dev` will write the environment
+ * variable `ML_AWS_ENDPOINT_URL` will be written to the corresponding dotenv file (`.env` or `.env.test`)
+ *
+ * When initializing the S3 client, you need to configure `forcePathStyle` and `endpoint`
+ * if the dev or test container is running (*check for the `ML_AWS_ENDPOINT_URL` environment
+ * variable*). See the example.
+ *
+ * @example
+ * ```ts
+ * import { Bucket } from "@monolayer/sdk";
+ *
+ * const documents = new Bucket("documents");
+ *
+ * export default documents;
+ *
+ * // Client configuration
+ *
+ * import { S3Client } from "@aws-sdk/client-s3";
+ * import { bucketLocalConfiguration } from "@monolayer/sdk";
+ * export const s3Client = new S3Client({
+ *   ...bucketLocalConfiguration(),
+ * });
+ *
+ * // Get Object
+ *
+ * const response = await s3Client.send(
+ *   new GetObjectCommand({
+ *     Bucket: documents.name,
+ *     Key: "README.md",
+ *   }),
+ * );
+ *
+ * ```
+ */
+export declare class Bucket extends StatefulWorkload {
+    /**
+     * Defines public access permissions for specific paths within the bucket.
+     * This allows anonymous users to perform actions on objects matching the specified path patterns.
+     */
+    publicAccess: PublicAccess;
+    constructor(
+    /**
+     * Bucket ID.
+     */
+    id: string, 
+    /**
+     * Bucket options
+     */
+    options?: BucketOptions);
+    get name(): string;
+}
+export declare function bucketLocalConfiguration(): {
+    forcePathStyle?: undefined;
+    endpoint?: undefined;
+    credentials?: undefined;
+} | {
+    forcePathStyle: boolean;
+    endpoint: string | undefined;
+    credentials: {
+        accessKeyId: string;
+        secretAccessKey: string;
+    };
+};
+export type AccessGrant = "get" | "list" | "write" | "delete";
+export type PublicAccess = Record<string, AccessGrant[]>;
+export interface BucketOptions {
+    /**
+     * Defines public access permissions for specific paths within the bucket.
+     * This allows anonymous users to perform actions like 'get', 'list', 'write', or 'delete'
+     * on objects matching the specified path patterns.
+     */
+    publicAccess?: PublicAccess;
+}

package/dist/cjs/workloads/stateful/bucket.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Bucket = void 0;
+exports.bucketLocalConfiguration = bucketLocalConfiguration;
+const case_anything_1 = require("case-anything");
+const stateful_workload_js_1 = require("../../workloads/stateful/stateful-workload.js");
+/**
+ * Workload for an AWS S3 compatible storage.
+ *
+ * The `Bucket` workload is initialized with:
+ * - A valid bucket name.
+ *
+ * **NOTES**
+ *
+ * Launching the development or test containers with `npx monolayer start dev` will write the environment
+ * variable `ML_AWS_ENDPOINT_URL` will be written to the corresponding dotenv file (`.env` or `.env.test`)
+ *
+ * When initializing the S3 client, you need to configure `forcePathStyle` and `endpoint`
+ * if the dev or test container is running (*check for the `ML_AWS_ENDPOINT_URL` environment
+ * variable*). See the example.
+ *
+ * @example
+ * ```ts
+ * import { Bucket } from "@monolayer/sdk";
+ *
+ * const documents = new Bucket("documents");
+ *
+ * export default documents;
+ *
+ * // Client configuration
+ *
+ * import { S3Client } from "@aws-sdk/client-s3";
+ * import { bucketLocalConfiguration } from "@monolayer/sdk";
+ * export const s3Client = new S3Client({
+ *   ...bucketLocalConfiguration(),
+ * });
+ *
+ * // Get Object
+ *
+ * const response = await s3Client.send(
+ *   new GetObjectCommand({
+ *     Bucket: documents.name,
+ *     Key: "README.md",
+ *   }),
+ * );
+ *
+ * ```
+ */
+class Bucket extends stateful_workload_js_1.StatefulWorkload {
+    constructor(
+    /**
+     * Bucket ID.
+     */
+    id, 
+    /**
+     * Bucket options
+     */
+    options) {
+        super(id);
+        this.publicAccess = options?.publicAccess ?? {};
+    }
+    get name() {
+        if (process.env.NODE_ENV === "production") {
+            const envVarName = (0, case_anything_1.snakeCase)(["ml", this.id, "bucket", "name"].join("-")).toUpperCase();
+            const bucketName = process.env[envVarName];
+            if (bucketName === undefined) {
+                throw new Error(`Undefined bucket name for Bucket ${this.id}. ${envVarName} not set.`);
+            }
+            return bucketName;
+        }
+        else {
+            return [this.id, process.env.NODE_ENV].join("-");
+        }
+    }
+    /**
+     * @internal
+     */
+    get connectionStringEnvVar() {
+        return bucketEndPointEnvVarName;
+    }
+}
+exports.Bucket = Bucket;
+function bucketLocalConfiguration() {
+    if (process.env.NODE_ENV === "production")
+        return {};
+    return {
+        forcePathStyle: true,
+        endpoint: process.env[bucketEndPointEnvVarName],
+        credentials: {
+            accessKeyId: "minioadmin",
+            secretAccessKey: "minioadmin",
+        },
+    };
+}
+const bucketEndPointEnvVarName = "ML_BUCKET_ENDPOINT";

package/dist/cjs/workloads/stateful/database.d.ts

@@ -0,0 +1,25 @@
+import { StatefulWorkloadWithClient } from "../../workloads/stateful/stateful-workload.js";
+/**
+ * Database workload.
+ *
+ * @group Abstract Classes
+ * @typeParam C - Client type
+ */
+export declare abstract class Database extends StatefulWorkloadWithClient {
+    /**
+     * Database name.
+     */
+    readonly databaseName: string;
+    constructor(
+    /**
+     * Database name.
+     */
+    databaseName: string);
+    /**
+     * Database ID
+     *
+     * **Note:**
+     * Alias of `ìd`.
+     */
+    get databaseId(): string;
+}

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

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Database = void 0;
+const stateful_workload_js_1 = require("../../workloads/stateful/stateful-workload.js");
+/**
+ * Database workload.
+ *
+ * @group Abstract Classes
+ * @typeParam C - Client type
+ */
+class Database extends stateful_workload_js_1.StatefulWorkloadWithClient {
+    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",
+        ];
+    }
+}
+exports.Database = Database;

package/dist/cjs/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/cjs/workloads/stateful/postgres-database.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PostgresDatabase = void 0;
+const database_js_1 = require("../../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");
+ * ```
+ */
+class PostgresDatabase extends database_js_1.Database {
+    /**
+     * @internal
+     */
+    connStringPrefix() {
+        return "pg";
+    }
+}
+exports.PostgresDatabase = PostgresDatabase;

package/dist/cjs/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/cjs/workloads/stateful/redis.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Redis = void 0;
+const stateful_workload_js_1 = require("../../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
+ */
+class Redis extends stateful_workload_js_1.StatefulWorkloadWithClient {
+    /**
+     * @internal
+     */
+    get connStringComponents() {
+        return ["redis", this.id];
+    }
+}
+exports.Redis = Redis;

package/dist/cjs/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/cjs/workloads/stateful/stateful-workload.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StatefulWorkloadWithClient = exports.StatefulWorkload = void 0;
+const case_anything_1 = require("case-anything");
+const workload_js_1 = require("../../workloads/workload.js");
+/**
+ * @group Abstract Classes
+ */
+class StatefulWorkload extends workload_js_1.Workload {
+}
+exports.StatefulWorkload = StatefulWorkload;
+/**
+ * @group Abstract Classes
+ * @typeParam C - Client type
+ */
+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 (0, case_anything_1.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;
+    }
+}
+exports.StatefulWorkloadWithClient = StatefulWorkloadWithClient;

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

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

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

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ChannelData = void 0;
+class ChannelData {
+}
+exports.ChannelData = ChannelData;

package/dist/cjs/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;
+}