@monolayer/sdk 1.2.0-canary.4

package/dist/esm/workloads/stateless/cron.d.ts

@@ -0,0 +1,49 @@
+import { StatelessWorkload } from "../../workloads/stateless/stateless-workload.js";
+export interface CronOptions {
+    /**
+     * Function with the code that will be executed.
+     */
+    run: () => Promise<void>;
+    /**
+     * Schedule in crontab format.
+     */
+    schedule: string;
+}
+/**
+ * Workload for recurring tasks.
+ *
+ * A Cron workload is initialized with a unique id and the following options:
+ *
+ * - `schedule` in [unix-cron](https://man7.org/linux/man-pages/man5/crontab.5.html)
+ * format to specify when it should run.
+ *
+ * - `run` function with the code that will be executed.
+ *
+ * @example
+ * ```ts
+ * import { Cron } from "@monolayer/sdk";
+ *
+ * const reports = new Cron("reports", {
+ *   schedule: "* * * * *",
+ *   run: async () => {
+ *     // Do something;
+ *   },
+ * });
+ *
+ * export default reports;
+ * ```
+ */
+export declare class Cron extends StatelessWorkload {
+    /**
+     * Unique ID
+     */
+    id: string;
+    options: CronOptions;
+    run: () => Promise<void>;
+    schedule: string;
+    constructor(
+    /**
+     * Unique ID
+     */
+    id: string, options: CronOptions);
+}

package/dist/esm/workloads/stateless/cron.js

@@ -0,0 +1,52 @@
+import cronParser from "cron-parser";
+import { StatelessWorkload } from "../../workloads/stateless/stateless-workload.js";
+/**
+ * Workload for recurring tasks.
+ *
+ * A Cron workload is initialized with a unique id and the following options:
+ *
+ * - `schedule` in [unix-cron](https://man7.org/linux/man-pages/man5/crontab.5.html)
+ * format to specify when it should run.
+ *
+ * - `run` function with the code that will be executed.
+ *
+ * @example
+ * ```ts
+ * import { Cron } from "@monolayer/sdk";
+ *
+ * const reports = new Cron("reports", {
+ *   schedule: "* * * * *",
+ *   run: async () => {
+ *     // Do something;
+ *   },
+ * });
+ *
+ * export default reports;
+ * ```
+ */
+export class Cron extends StatelessWorkload {
+    id;
+    options;
+    run;
+    schedule;
+    constructor(
+    /**
+     * Unique ID
+     */
+    id, options) {
+        super(id);
+        this.id = id;
+        this.options = options;
+        this.run = options.run;
+        this.schedule = parseSchedule(options.schedule);
+    }
+}
+function parseSchedule(schedule) {
+    try {
+        const parsed = cronParser.parseExpression(schedule);
+        return parsed.stringify();
+    }
+    catch {
+        throw new Error(`Failed to parse schedule: ${schedule}`);
+    }
+}

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

@@ -0,0 +1,3 @@
+import { Workload } from "../../workloads/workload.js";
+export declare class StatelessWorkload extends Workload {
+}

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

@@ -0,0 +1,8 @@
+import { Workload } from "../../workloads/workload.js";
+export class StatelessWorkload extends Workload {
+    /**
+     * @hidden
+     * @internal
+     */
+    stateless;
+}

package/dist/esm/workloads/stateless/task/backoffs.d.ts

@@ -0,0 +1,9 @@
+export interface ConstantBackoff {
+    type: "constant";
+    delay: number;
+}
+export interface ExponentialBackoff {
+    type: "exponential";
+    delay: number;
+}
+export declare function computeBackoff(attemptsMade: number, backoff?: ExponentialBackoff | ConstantBackoff): number;

package/dist/esm/workloads/stateless/task/backoffs.js

@@ -0,0 +1,14 @@
+export function computeBackoff(attemptsMade, backoff) {
+    if (backoff !== undefined) {
+        switch (backoff.type) {
+            case "constant":
+                return backoff.delay;
+            case "exponential":
+                if (backoff.delay < 0 || attemptsMade < 0) {
+                    throw new Error("Retry number cannot be less that 0");
+                }
+                return Math.round(Math.pow(2, attemptsMade) * backoff.delay);
+        }
+    }
+    return 0;
+}

package/dist/esm/workloads/stateless/task/dispatcher.d.ts

@@ -0,0 +1,3 @@
+import { developmentDispatch } from "../../../workloads/stateless/task/local.js";
+export declare const dispatcherAdapterSymbol: unique symbol;
+export declare function dispatcher(): Promise<typeof developmentDispatch>;

package/dist/esm/workloads/stateless/task/dispatcher.js

@@ -0,0 +1,18 @@
+import { developmentDispatch, testDispatch, } from "../../../workloads/stateless/task/local.js";
+export const dispatcherAdapterSymbol = Symbol.for("@monolayer/sdk-task-dispacher");
+const TASK_DISPATCHER_SYMBOL = Symbol.for("@monolayer/sdk/task-dispatcher");
+export async function dispatcher() {
+    if (process.env.NODE_ENV === "production") {
+        // @ts-expect-error defined at runtime
+        const dispatcher = globalThis[TASK_DISPATCHER_SYMBOL];
+        if (dispatcher === undefined)
+            throw new Error(`undefined dispatcher`);
+        return dispatcher;
+    }
+    else {
+        if (process.env.NODE_ENV === "test") {
+            return testDispatch;
+        }
+        return developmentDispatch;
+    }
+}

package/dist/esm/workloads/stateless/task/local.d.ts

@@ -0,0 +1,14 @@
+import { type ExecutionId } from "../../../workloads/stateless/task/perform-now.js";
+import type { PerformOptions, Task } from "../../../workloads/stateless/task/task.js";
+export declare function developmentDispatch<P>(task: Task<P>, data: P | P[], options?: PerformOptions): Promise<ExecutionId | ExecutionId[]>;
+export declare function testDispatch<P>(task: Task<P>, data: P | P[], options?: PerformOptions): Promise<ExecutionId | ExecutionId[]>;
+export declare const testDispatchers: Record<string, {
+    executionId: ExecutionId;
+    data: unknown;
+}[]>;
+export declare function dispatcherForTask<P>(task: Task<P>): DispatcherTask<P>[];
+interface DispatcherTask<P> {
+    executionId: ExecutionId;
+    data: P;
+}
+export {};

package/dist/esm/workloads/stateless/task/local.js

@@ -0,0 +1,48 @@
+import { remember } from "@epic-web/remember";
+import { randomUUID } from "crypto";
+import { performNow, } from "../../../workloads/stateless/task/perform-now.js";
+export async function developmentDispatch(task, data, 
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+options) {
+    if (Array.isArray(data)) {
+        const executionId = [];
+        for (const single of data) {
+            await performNow(task, single);
+            executionId.push(randomUUID());
+        }
+        return executionId;
+    }
+    await performNow(task, data);
+    return randomUUID();
+}
+export async function testDispatch(task, data, 
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+options) {
+    const testDispather = dispatcherForTask(task);
+    if (Array.isArray(data)) {
+        const executionIds = [];
+        const executionId = randomUUID();
+        for (const single of data) {
+            testDispather.push({
+                executionId,
+                data: single,
+            });
+            executionIds.push(executionId);
+        }
+        return executionIds;
+    }
+    const executionId = randomUUID();
+    testDispather.push({
+        executionId: executionId,
+        data: data,
+    });
+    return executionId;
+}
+export const testDispatchers = remember("TestDispatchers", () => ({}));
+export function dispatcherForTask(task) {
+    const queueKey = task.id;
+    if (testDispatchers[queueKey] === undefined) {
+        testDispatchers[queueKey] = [];
+    }
+    return testDispatchers[queueKey];
+}

package/dist/esm/workloads/stateless/task/perform-later.d.ts

@@ -0,0 +1,2 @@
+import type { PerformOptions, Task } from "../../../workloads/stateless/task/task.js";
+export declare function performLater<P>(task: Task<P>, data: P | P[], options?: PerformOptions): Promise<import("./perform-now.js").ExecutionId | import("./perform-now.js").ExecutionId[]>;

package/dist/esm/workloads/stateless/task/perform-later.js

@@ -0,0 +1,4 @@
+import { dispatcher } from "../../../workloads/stateless/task/dispatcher.js";
+export async function performLater(task, data, options) {
+    return await (await dispatcher())(task, data, options);
+}

package/dist/esm/workloads/stateless/task/perform-now.d.ts

@@ -0,0 +1,5 @@
+import type { Task } from "../../../workloads/stateless/task/task.js";
+export declare function performNow<P>(task: Task<P>, data: P | P[]): Promise<ExecutionId | ExecutionId[]>;
+export type ExecutionId = string & {
+    _brand: "ExecutionId";
+};

package/dist/esm/workloads/stateless/task/perform-now.js

@@ -0,0 +1,18 @@
+import { randomUUID } from "crypto";
+import workAndHandleError from "../../../workloads/stateless/task/perform.js";
+export async function performNow(task, data) {
+    if (!Array.isArray(data)) {
+        const taskId = randomUUID();
+        await workAndHandleError({ task, taskId, data });
+        return taskId;
+    }
+    else {
+        const taskIds = [];
+        for (const singlePayload of data) {
+            const taskId = randomUUID();
+            await workAndHandleError({ task, taskId, data: singlePayload });
+            taskIds.push(taskId);
+        }
+        return taskIds;
+    }
+}

package/dist/esm/workloads/stateless/task/perform.d.ts

@@ -0,0 +1,7 @@
+import { type Task } from "../../../workloads/stateless/task/task.js";
+declare const _default: <P>({ task, taskId, data, }: {
+    task: Task<P>;
+    taskId: string;
+    data: P;
+}) => Promise<void>;
+export default _default;

package/dist/esm/workloads/stateless/task/perform.js

@@ -0,0 +1,8 @@
+export default async ({ task, taskId, data, }) => {
+    try {
+        await task.work({ taskId, data });
+    }
+    catch (error) {
+        task.handleError(error, data, taskId);
+    }
+};

package/dist/esm/workloads/stateless/task/task.d.ts

@@ -0,0 +1,88 @@
+import type { ConstantBackoff, ExponentialBackoff } from "../../../workloads/stateless/task/backoffs.js";
+import { Workload } from "../../../workloads/workload.js";
+export declare class Task<P> extends Workload {
+    /**
+     * Name of the task.
+     */
+    name: string;
+    /**
+     * Function that processes a task.
+     */
+    work: (task: {
+        taskId: string;
+        data: P;
+    }) => Promise<void>;
+    options?: TaskOptions<P> | undefined;
+    constructor(
+    /**
+     * Name of the task.
+     */
+    name: string, 
+    /**
+     * Function that processes a task.
+     */
+    work: (task: {
+        taskId: string;
+        data: P;
+    }) => Promise<void>, options?: TaskOptions<P> | undefined);
+    /**
+     * Performs the task immediately in the current processs.
+     */
+    performNow(data: P | P[]): Promise<void>;
+    /**
+     * Performs the task later, dispatching the task to a queue.
+     *
+     * **NOTES**
+     *
+     * In development, the task will be performed immediately.
+     *
+     * In test, the task will collected ans can be retrieved with the `performedTasks` test helper.
+     */
+    performLater(data: P | P[], options?: PerformOptions): Promise<import("../../../workloads/stateless/task/perform-now.js").ExecutionId | import("../../../workloads/stateless/task/perform-now.js").ExecutionId[]>;
+    handleError(error?: unknown, data?: P, executionId?: string): void;
+}
+export interface TaskOptions<P> {
+    onError?: (error: TaskError<P>) => void;
+    retry?: RetryOptions;
+}
+export declare class TaskError<P> extends Error {
+    cause: TaskErrorCause<P>;
+    constructor(message: string, cause: TaskErrorCause<P>);
+}
+export type TaskErrorCause<P> = {
+    task: string;
+    executionId?: string;
+    data?: P;
+    error: unknown;
+};
+export interface RetryOptions {
+    /**
+     * The total number of attempts to try the job until it completes.
+     * @defaultValue 0
+     */
+    times: number;
+    /**
+     * Backoff setting for automatic retries if the job fails.
+     *
+     * **Important**
+     *
+     * This setting does not have any effect on Tasks backed by an `SQS` queue in production.
+     *
+     * Retries will happen after the `VisibilityTimeout` of the message expires (30 seconds by default).
+     * See: https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-visibility-timeout.html#consumer-fails-to-process-message
+     *
+     * You can to implement an custom backoff strategy using a dead-letter queue to handle retries
+     * and a Lambda function.
+     *
+     * @defaultValue { type: "constant", delay: 0 }
+     */
+    backoff?: ExponentialBackoff | ConstantBackoff;
+}
+export interface PerformOptions {
+    /**
+     * Amount in milliseconds to wait until this task can be processed.
+     *
+     * @defaultValue 0
+     */
+    delay?: number;
+}

package/dist/esm/workloads/stateless/task/task.js

@@ -0,0 +1,59 @@
+import { kebabCase } from "case-anything";
+import { performLater } from "../../../workloads/stateless/task/perform-later.js";
+import { performNow } from "../../../workloads/stateless/task/perform-now.js";
+import { Workload } from "../../../workloads/workload.js";
+export class Task extends Workload {
+    name;
+    work;
+    options;
+    constructor(
+    /**
+     * Name of the task.
+     */
+    name, 
+    /**
+     * Function that processes a task.
+     */
+    work, options) {
+        super(kebabCase(name));
+        this.name = name;
+        this.work = work;
+        this.options = options;
+    }
+    /**
+     * Performs the task immediately in the current processs.
+     */
+    async performNow(data) {
+        await performNow(this, data);
+    }
+    /**
+     * Performs the task later, dispatching the task to a queue.
+     *
+     * **NOTES**
+     *
+     * In development, the task will be performed immediately.
+     *
+     * In test, the task will collected ans can be retrieved with the `performedTasks` test helper.
+     */
+    async performLater(data, options) {
+        return await performLater(this, data, options);
+    }
+    handleError(error, data, executionId) {
+        if (this.options?.onError) {
+            this.options?.onError(new TaskError("Error while performing tasks", {
+                task: this.id,
+                executionId,
+                data,
+                error,
+            }));
+        }
+        else {
+            console.log(`An error was thrown in ${this.id} and the onError callback function is undefined.`);
+        }
+    }
+}
+export class TaskError extends Error {
+    constructor(message, cause) {
+        super(message, { cause });
+    }
+}

package/dist/esm/workloads/stateless/task/validate-data-size.d.ts

@@ -0,0 +1 @@
+export declare function validateJsonStringified<P>(data: P, max?: number): void;

package/dist/esm/workloads/stateless/task/validate-data-size.js

@@ -0,0 +1,7 @@
+export function validateJsonStringified(data, max = 256000) {
+    const dataString = JSON.stringify(typeof data === "undefined" ? {} : data);
+    const byteLength = Buffer.byteLength(dataString, "utf8");
+    if (byteLength > max) {
+        throw new Error(`Data size exceeds the limit (${max} bytes)`);
+    }
+}

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

@@ -0,0 +1,14 @@
+/**
+ * @group Abstract Classes
+ */
+export declare abstract class Workload {
+    /**
+     * Unique ID
+     */
+    readonly id: string;
+    constructor(
+    /**
+     * Unique ID.
+     */
+    id: string);
+}

package/dist/esm/workloads/workload.js

@@ -0,0 +1,16 @@
+/**
+ * @group Abstract Classes
+ */
+export class Workload {
+    /**
+     * Unique ID
+     */
+    id;
+    constructor(
+    /**
+     * Unique ID.
+     */
+    id) {
+        this.id = id;
+    }
+}

package/dist/esm/workloads.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @module main
+ */
+export { ContainerConfig, type Configuration, } from "./configuration.js";
+export { AfterRollout } from "./workloads/app-lifecycle/after-rollout.js";
+export { BeforeRollout } from "./workloads/app-lifecycle/before-rollout.js";
+export { Bootstrap } from "./workloads/app-lifecycle/bootstrap.js";
+export { type LifecycleWorkload } from "./workloads/app-lifecycle/lifecycle-workload.js";
+export { Bucket, BucketOptions, bucketLocalConfiguration, type AccessGrant, type PublicAccess, } from "./workloads/stateful/bucket.js";
+export type { Database } from "./workloads/stateful/database.js";
+export { PostgresDatabase } from "./workloads/stateful/postgres-database.js";
+export { Redis } from "./workloads/stateful/redis.js";
+export type { StatefulWorkload, StatefulWorkloadWithClient, } from "./workloads/stateful/stateful-workload.js";
+export { ChannelData } from "./workloads/stateless/broadcast/channel-data.js";
+export { broadcastClient } from "./workloads/stateless/broadcast/client/client.js";
+export { Broadcast } from "./workloads/stateless/broadcast/router.js";
+export type { StatelessWorkload } from "./workloads/stateless/stateless-workload.js";
+export { Task, type RetryOptions, type TaskOptions, } from "./workloads/stateless/task/task.js";
+export type { Workload } from "./workloads/workload.js";
+export { Cron, type CronOptions } from "./workloads/stateless/cron.js";
+export { BroadcastPublisher } from "./workloads/stateless/broadcast/client/app-sync-publisher.js";
+export { Broadcast as BroadcastProvider } from "./workloads/stateless/broadcast/client/provider.js";

package/dist/esm/workloads.js

@@ -0,0 +1,13 @@
+export { AfterRollout } from "./workloads/app-lifecycle/after-rollout.js";
+export { BeforeRollout } from "./workloads/app-lifecycle/before-rollout.js";
+export { Bootstrap } from "./workloads/app-lifecycle/bootstrap.js";
+export { Bucket, bucketLocalConfiguration, } from "./workloads/stateful/bucket.js";
+export { PostgresDatabase } from "./workloads/stateful/postgres-database.js";
+export { Redis } from "./workloads/stateful/redis.js";
+export { ChannelData } from "./workloads/stateless/broadcast/channel-data.js";
+export { broadcastClient } from "./workloads/stateless/broadcast/client/client.js";
+export { Broadcast } from "./workloads/stateless/broadcast/router.js";
+export { Task, } from "./workloads/stateless/task/task.js";
+export { Cron } from "./workloads/stateless/cron.js";
+export { BroadcastPublisher } from "./workloads/stateless/broadcast/client/app-sync-publisher.js";
+export { Broadcast as BroadcastProvider } from "./workloads/stateless/broadcast/client/provider.js";