@monolayer/sdk 1.2.0-canary.4

package/dist/esm/scan/workload-imports.js

@@ -0,0 +1,144 @@
+import { existsSync } from "fs";
+import fs from "fs/promises";
+import path from "node:path";
+import { cwd, exit } from "node:process";
+import color from "picocolors";
+import { workloadsConfiguration } from "../configuration.js";
+import { assertBroadcast, assertBucket, assertCron, assertPostgresDatabase, assertRedis, assertTask, } from "../workloads/assertions.js";
+export async function importWorkloads() {
+    const workloadsPath = path.join(cwd(), (await workloadsConfiguration()).workloadsPath);
+    if (!existsSync(workloadsPath)) {
+        console.log(`${color.red("error")} Workloads folder not found`);
+        console.log("Check your configuration file: ./monolayer.config.ts");
+        exit(1);
+    }
+    const files = await fs.readdir(workloadsPath);
+    const imports = new WorkloadImports();
+    for (const fileName of files) {
+        if (fileName.endsWith(".ts") && !fileName.endsWith(".d.ts")) {
+            const importPath = path.join(workloadsPath, fileName);
+            const imported = (await import(importPath));
+            for (const [, workload] of Object.entries(imported)) {
+                if (workload !== undefined) {
+                    const workloadKind = workload.constructor.name;
+                    const workloadPath = path.relative(cwd(), importPath);
+                    if (validWorkload(workloadKind)) {
+                        imports.add(workloadPath, workload);
+                    }
+                }
+            }
+        }
+    }
+    return imports;
+}
+const validConstructor = [
+    "PostgresDatabase",
+    "Redis",
+    "Bucket",
+    "Cron",
+    "Task",
+    "Broadcast",
+];
+function validWorkload(workloadConstructor) {
+    return validConstructor.includes(workloadConstructor);
+}
+export class WorkloadImports {
+    #importsByWorkload;
+    #imports = [];
+    constructor() {
+        this.#importsByWorkload = {
+            PostgresDatabase: [],
+            Bucket: [],
+            Redis: [],
+            Cron: [],
+            Task: [],
+            Broadcast: [],
+        };
+    }
+    get workloadsWithContainers() {
+        return [
+            ...this.Bucket,
+            ...this.PostgresDatabase,
+            ...this.Redis,
+            ...this.Broadcast,
+        ].map((i) => i.workload);
+    }
+    get Redis() {
+        return this.#importsByWorkload.Redis;
+    }
+    get PostgresDatabase() {
+        return this.#importsByWorkload.PostgresDatabase;
+    }
+    get Bucket() {
+        return this.#importsByWorkload.Bucket;
+    }
+    get Cron() {
+        return this.#importsByWorkload.Cron;
+    }
+    get Task() {
+        return this.#importsByWorkload.Task;
+    }
+    get Broadcast() {
+        return this.#importsByWorkload.Broadcast;
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    addBroadcast(src, workload) {
+        this.#importsByWorkload.Broadcast = [{ src, workload }];
+    }
+    add(src, workload) {
+        if (validWorkload(workload.constructor.name)) {
+            const key = workload.constructor.name;
+            if (this.#importsByWorkload[key] === undefined) {
+                this.#importsByWorkload[key] = [];
+            }
+            switch (key) {
+                case "Redis":
+                    assertRedis(workload);
+                    this.#importsByWorkload[key].push({
+                        src,
+                        workload,
+                    });
+                    break;
+                case "Bucket":
+                    assertBucket(workload);
+                    this.#importsByWorkload[key].push({
+                        src,
+                        workload,
+                    });
+                    break;
+                case "PostgresDatabase":
+                    assertPostgresDatabase(workload);
+                    this.#importsByWorkload[key].push({
+                        src,
+                        workload,
+                    });
+                    break;
+                case "Cron":
+                    assertCron(workload);
+                    this.#importsByWorkload[key].push({
+                        src,
+                        workload,
+                    });
+                    break;
+                case "Task":
+                    assertTask(workload);
+                    this.#importsByWorkload[key].push({
+                        src,
+                        workload,
+                    });
+                    break;
+                case "Broadcast":
+                    assertBroadcast(workload);
+                    this.#importsByWorkload[key].push({
+                        src,
+                        workload,
+                    });
+                    break;
+            }
+        }
+        this.#imports.push({
+            src,
+            workload,
+        });
+    }
+}

package/dist/esm/test-helpers/postgres.d.ts

@@ -0,0 +1,13 @@
+import type { PostgresDatabase } from "../workloads/stateful/postgres-database.js";
+/**
+ * Truncates all the tables in a {@link PostgresDatabase} workload.
+ */
+export declare function truncatePostgresTables(
+/**
+ * PostgresDatabase workload
+ */
+workload: PostgresDatabase, 
+/**
+ * Schema name (default: `public`)
+ */
+schemaName?: string): Promise<void>;

package/dist/esm/test-helpers/postgres.js

@@ -0,0 +1,26 @@
+/**
+ * Truncates all the tables in a {@link PostgresDatabase} workload.
+ */
+export async function truncatePostgresTables(
+/**
+ * PostgresDatabase workload
+ */
+workload, 
+/**
+ * Schema name (default: `public`)
+ */
+schemaName) {
+    const pg = await import("pg");
+    const pool = new pg.Pool({
+        connectionString: process.env[workload.connectionStringEnvVar],
+    });
+    const result = await pool.query(`
+		SELECT c.relname as table_name, n.nspname as schema_name
+		FROM pg_class c LEFT JOIN pg_namespace n ON n.oid = c.relnamespace
+		WHERE n.nspname = '${schemaName ?? "public"}'
+		AND c.relkind IN ('r','p');`);
+    const tables = result.rows;
+    const queries = tables.map((table) => `TRUNCATE TABLE ${table.schema_name}.${table.table_name} RESTART IDENTITY CASCADE;`);
+    await pool.query(queries.join("\n"));
+    await pool.end();
+}

package/dist/esm/test-helpers/redis.d.ts

@@ -0,0 +1,13 @@
+import type { Redis } from "../workloads/stateful/redis.js";
+/**
+ * Deletes all the keys of a {@link Redis} workload database.
+ */
+export declare function flushRedis(
+/**
+ * Redis workload
+ */
+workload: Redis, 
+/**
+ * Redis database (default: 0)
+ */
+db?: number): Promise<void>;

package/dist/esm/test-helpers/redis.js

@@ -0,0 +1,20 @@
+/**
+ * Deletes all the keys of a {@link Redis} workload database.
+ */
+export async function flushRedis(
+/**
+ * Redis workload
+ */
+workload, 
+/**
+ * Redis database (default: 0)
+ */
+db) {
+    const Redis = (await import("ioredis")).Redis;
+    const client = new Redis(process.env[workload.connectionStringEnvVar]);
+    if (db) {
+        await client.select(db);
+    }
+    await client.flushdb();
+    client.disconnect();
+}

package/dist/esm/test-helpers/task.d.ts

@@ -0,0 +1,14 @@
+import type { ExecutionId } from "../workloads/stateless/task/perform-now.js";
+import type { Task } from "../workloads/stateless/task/task.js";
+export interface PerformedTask<P> {
+    executionId: ExecutionId;
+    data: P;
+}
+/**
+ * Returns all the performed tasks for a `Task` workload.
+ */
+export declare function performedTasks<P>(task: Task<P>): PerformedTask<P>[];
+/**
+ * Deletes all the performed tasks for a `Task` workload.
+ */
+export declare function clearPerformedTasks<P>(task: Task<P>): void;

package/dist/esm/test-helpers/task.js

@@ -0,0 +1,14 @@
+import { dispatcherForTask, testDispatchers, } from "../workloads/stateless/task/local.js";
+/**
+ * Returns all the performed tasks for a `Task` workload.
+ */
+export function performedTasks(task) {
+    return dispatcherForTask(task);
+}
+/**
+ * Deletes all the performed tasks for a `Task` workload.
+ */
+export function clearPerformedTasks(task) {
+    const dispatchers = testDispatchers;
+    delete dispatchers[task.id];
+}

package/dist/esm/test-helpers.d.ts

@@ -0,0 +1,3 @@
+export { truncatePostgresTables } from "./test-helpers/postgres.js";
+export { flushRedis } from "./test-helpers/redis.js";
+export { clearPerformedTasks, performedTasks, type PerformedTask, } from "./test-helpers/task.js";

package/dist/esm/test-helpers.js

@@ -0,0 +1,3 @@
+export { truncatePostgresTables } from "./test-helpers/postgres.js";
+export { flushRedis } from "./test-helpers/redis.js";
+export { clearPerformedTasks, performedTasks, } from "./test-helpers/task.js";

package/dist/esm/workloads/app-lifecycle/after-rollout.d.ts

@@ -0,0 +1,22 @@
+import { LifecycleWorkload, type LifecycleWorkloadOptions } from "../../workloads/app-lifecycle/lifecycle-workload.js";
+/**
+ * Workload for defining an npm script to run after rolling out a new application version.
+ *
+ * @example
+ * ```ts
+ * import { AfterRollout } from "@monolayer/sdk";
+ *
+ * const rollout = new AfterRollout("after-rollout-1",{
+ *   script: "notify",
+ * });
+ *
+ * export rollout;
+ * ```
+ */
+export declare class AfterRollout extends LifecycleWorkload {
+    constructor(
+    /**
+     * Unique ID
+     */
+    id: string, options: LifecycleWorkloadOptions);
+}

package/dist/esm/workloads/app-lifecycle/after-rollout.js

@@ -0,0 +1,24 @@
+import { LifecycleWorkload, } from "../../workloads/app-lifecycle/lifecycle-workload.js";
+/**
+ * Workload for defining an npm script to run after rolling out a new application version.
+ *
+ * @example
+ * ```ts
+ * import { AfterRollout } from "@monolayer/sdk";
+ *
+ * const rollout = new AfterRollout("after-rollout-1",{
+ *   script: "notify",
+ * });
+ *
+ * export rollout;
+ * ```
+ */
+export class AfterRollout extends LifecycleWorkload {
+    constructor(
+    /**
+     * Unique ID
+     */
+    id, options) {
+        super(id, options);
+    }
+}

package/dist/esm/workloads/app-lifecycle/before-rollout.d.ts

@@ -0,0 +1,22 @@
+import { LifecycleWorkload, type LifecycleWorkloadOptions } from "../../workloads/app-lifecycle/lifecycle-workload.js";
+/**
+ * Workload for defining an npm script to run before rolling out a new application version.
+ *
+ * @example
+ * ```ts
+ * import { BeforeRollout } from "@monolayer/sdk";
+ *
+ * const rollout = new BeforeRollout("before-1", {
+ *   script: "db:migrate",
+ * });
+ *
+ * export default rollout;
+ * ```
+ */
+export declare class BeforeRollout extends LifecycleWorkload {
+    constructor(
+    /**
+     * Unique ID
+     */
+    id: string, options: LifecycleWorkloadOptions);
+}

package/dist/esm/workloads/app-lifecycle/before-rollout.js

@@ -0,0 +1,24 @@
+import { LifecycleWorkload, } from "../../workloads/app-lifecycle/lifecycle-workload.js";
+/**
+ * Workload for defining an npm script to run before rolling out a new application version.
+ *
+ * @example
+ * ```ts
+ * import { BeforeRollout } from "@monolayer/sdk";
+ *
+ * const rollout = new BeforeRollout("before-1", {
+ *   script: "db:migrate",
+ * });
+ *
+ * export default rollout;
+ * ```
+ */
+export class BeforeRollout extends LifecycleWorkload {
+    constructor(
+    /**
+     * Unique ID
+     */
+    id, options) {
+        super(id, options);
+    }
+}

package/dist/esm/workloads/app-lifecycle/bootstrap.d.ts

@@ -0,0 +1,22 @@
+import { LifecycleWorkload, type LifecycleWorkloadOptions } from "../../workloads/app-lifecycle/lifecycle-workload.js";
+/**
+ * Workload for defining bootstrap an npm script to run when rolling out a fresh application.
+ *
+ * @example
+ * ```ts
+ * import { Bootstrap } from "@monolayer/sdk";
+ *
+ * const bootstrap = new Bootstrap("bootstrap", {
+ *   script: "db:create",
+ * });
+ *
+ * export default bootstrap;
+ * ```
+ */
+export declare class Bootstrap extends LifecycleWorkload {
+    constructor(
+    /**
+     * Unique ID
+     */
+    id: string, options: LifecycleWorkloadOptions);
+}

package/dist/esm/workloads/app-lifecycle/bootstrap.js

@@ -0,0 +1,24 @@
+import { LifecycleWorkload, } from "../../workloads/app-lifecycle/lifecycle-workload.js";
+/**
+ * Workload for defining bootstrap an npm script to run when rolling out a fresh application.
+ *
+ * @example
+ * ```ts
+ * import { Bootstrap } from "@monolayer/sdk";
+ *
+ * const bootstrap = new Bootstrap("bootstrap", {
+ *   script: "db:create",
+ * });
+ *
+ * export default bootstrap;
+ * ```
+ */
+export class Bootstrap extends LifecycleWorkload {
+    constructor(
+    /**
+     * Unique ID
+     */
+    id, options) {
+        super(id, options);
+    }
+}

package/dist/esm/workloads/app-lifecycle/lifecycle-workload.d.ts

@@ -0,0 +1,11 @@
+import { Workload } from "../../workloads/workload.js";
+export interface LifecycleWorkloadOptions {
+    /**
+     * Array of script names defined in `package.json`.
+     */
+    script: string;
+}
+export declare abstract class LifecycleWorkload extends Workload {
+    script: LifecycleWorkloadOptions["script"];
+    constructor(id: string, options: LifecycleWorkloadOptions);
+}

package/dist/esm/workloads/app-lifecycle/lifecycle-workload.js

@@ -0,0 +1,7 @@
+import { Workload } from "../../workloads/workload.js";
+export class LifecycleWorkload extends Workload {
+    constructor(id, options) {
+        super(id);
+        this.script = options.script;
+    }
+}

package/dist/esm/workloads/assertions.d.ts

@@ -0,0 +1,13 @@
+import type { Bucket } from "../workloads/stateful/bucket.js";
+import type { PostgresDatabase } from "../workloads/stateful/postgres-database.js";
+import type { Redis } from "../workloads/stateful/redis.js";
+import type { Cron } from "../workloads/stateless/cron.js";
+import type { Task } from "../workloads/stateless/task/task.js";
+import type { Workload } from "../workloads/workload.js";
+import type { AnyBroadcast } from "./stateless/broadcast/router.js";
+export declare function assertRedis(workload: Workload): asserts workload is Redis;
+export declare function assertPostgresDatabase(workload: Workload): asserts workload is PostgresDatabase;
+export declare function assertBucket(workload: Workload): asserts workload is Bucket;
+export declare function assertCron(workload: Workload): asserts workload is Cron;
+export declare function assertTask(workload: Workload): asserts workload is Task<unknown>;
+export declare function assertBroadcast(workload: Workload): asserts workload is AnyBroadcast;

package/dist/esm/workloads/assertions.js

@@ -0,0 +1,6 @@
+export function assertRedis(workload) { }
+export function assertPostgresDatabase(workload) { }
+export function assertBucket(workload) { }
+export function assertCron(workload) { }
+export function assertTask(workload) { }
+export function assertBroadcast(workload) { }

package/dist/esm/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/esm/workloads/stateful/bucket.js

@@ -0,0 +1,95 @@
+import { snakeCase } from "case-anything";
+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 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;
+    constructor(
+    /**
+     * Bucket ID.
+     */
+    id, 
+    /**
+     * Bucket options
+     */
+    options) {
+        super(id);
+        this.publicAccess = options?.publicAccess ?? {};
+    }
+    get name() {
+        if (process.env.NODE_ENV === "production") {
+            const envVarName = 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;
+    }
+}
+export 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/esm/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;
+}