@simulacra-ai/core 0.0.1

package/dist/utils/async.js

@@ -0,0 +1,217 @@
+import EventEmitter from "node:events";
+/**
+ * Token for monitoring and responding to cancellation requests.
+ *
+ * Provides a way to check if an operation has been cancelled and to
+ * register callbacks for when cancellation occurs.
+ */
+export class CancellationToken {
+    #source;
+    /**
+     * Creates a new cancellation token.
+     *
+     * @param source - Optional source that controls this token.
+     */
+    constructor(source) {
+        this.#source = source;
+    }
+    /**
+     * Whether cancellation has been requested.
+     */
+    get is_cancellation_requested() {
+        return !!this.#source?.is_cancelled;
+    }
+    /**
+     * Registers a one-time handler for cancellation.
+     *
+     * @param event - The event name (always "cancel").
+     * @param handler - The callback to invoke when cancelled.
+     */
+    once(event, handler) {
+        this.#source?.once(event, handler);
+    }
+    /**
+     * Removes a cancellation handler.
+     *
+     * @param event - The event name (always "cancel").
+     * @param handler - The callback to remove.
+     */
+    off(event, handler) {
+        this.#source?.off(event, handler);
+    }
+    /**
+     * Throws an error if cancellation has been requested.
+     */
+    throw_if_cancellation_requested() {
+        if (this.is_cancellation_requested) {
+            throw new OperationCanceledError(this);
+        }
+    }
+    /**
+     * Creates a promise that rejects when cancellation is requested.
+     *
+     * @returns A promise that never resolves but rejects on cancellation.
+     */
+    await_cancellation() {
+        return new Promise((_, reject) => this.once("cancel", () => reject(new OperationCanceledError(this))));
+    }
+    /**
+     * Creates an empty cancellation token that can never be cancelled.
+     *
+     * @returns A new cancellation token with no source.
+     */
+    static empty() {
+        return new CancellationToken();
+    }
+}
+/**
+ * Source for creating and controlling cancellation tokens.
+ *
+ * Allows triggering cancellation for associated tokens.
+ */
+export class CancellationTokenSource {
+    #event_emitter = new EventEmitter();
+    #is_cancelled = false;
+    #is_disposed = false;
+    #token;
+    /**
+     * Disposes the cancellation token source.
+     *
+     * This method is called automatically when using the `using` keyword.
+     */
+    [Symbol.dispose]() {
+        if (this.#is_disposed) {
+            throw new Error("invalid state");
+        }
+        this.#is_disposed = true;
+        this.#event_emitter.removeAllListeners();
+    }
+    /**
+     * Gets a cancellation token associated with this source.
+     */
+    get token() {
+        if (!this.#token) {
+            this.#token = new CancellationToken(this);
+        }
+        return this.#token;
+    }
+    /**
+     * Whether cancellation has been triggered.
+     */
+    get is_cancelled() {
+        return this.#is_cancelled;
+    }
+    /**
+     * Registers a one-time handler for cancellation.
+     *
+     * @param event - The event name (always "cancel").
+     * @param handler - The callback to invoke when cancelled.
+     */
+    once(event, handler) {
+        if (this.#is_cancelled) {
+            throw new OperationCanceledError(new CancellationToken(this));
+        }
+        if (this.#is_disposed) {
+            throw new Error("invalid state");
+        }
+        this.#event_emitter.once(event, handler);
+    }
+    /**
+     * Removes a cancellation handler.
+     *
+     * @param event - The event name (always "cancel").
+     * @param handler - The callback to remove.
+     */
+    off(event, handler) {
+        this.#event_emitter.off(event, handler);
+    }
+    /**
+     * Triggers cancellation for all associated tokens.
+     */
+    cancel() {
+        if (this.#is_cancelled) {
+            throw new OperationCanceledError(new CancellationToken(this));
+        }
+        this.#is_cancelled = true;
+        this.#event_emitter.emit("cancel");
+    }
+}
+/**
+ * Error thrown when an operation is cancelled.
+ */
+export class OperationCanceledError extends Error {
+    #token;
+    /**
+     * Creates a new operation cancelled error.
+     *
+     * @param token - The cancellation token associated with this error.
+     */
+    constructor(token) {
+        super("The operation was cancelled", { cause: "cancelled" });
+        this.#token = token;
+    }
+    /**
+     * The cancellation token associated with this error.
+     */
+    get token() {
+        return this.#token;
+    }
+}
+/**
+ * Delays execution for a specified time period with cancellation support.
+ *
+ * @param ms - The number of milliseconds to sleep.
+ * @param cancellation_token - Optional token for cancelling the sleep.
+ * @returns A promise that resolves after the delay or rejects if cancelled.
+ */
+export function sleep(ms, cancellation_token) {
+    return new Promise((resolve, reject) => {
+        if (cancellation_token) {
+            const token = cancellation_token;
+            const on_cancel = () => {
+                clearTimeout(timeout);
+                reject(new OperationCanceledError(token));
+            };
+            const on_timeout = () => {
+                token.off("cancel", on_cancel);
+                resolve();
+            };
+            const timeout = setTimeout(on_timeout, ms);
+            if (token.is_cancellation_requested) {
+                clearTimeout(timeout);
+                reject(new OperationCanceledError(token));
+            }
+            else {
+                token.once("cancel", on_cancel);
+            }
+        }
+        else {
+            setTimeout(resolve, ms);
+        }
+    });
+}
+/**
+ * Peeks at the first value from an async generator without consuming it.
+ *
+ * @template T - The type of values yielded by the generator.
+ * @param generator - The async generator to peek.
+ * @returns An object containing the peeked value and a new generator that includes it.
+ */
+export async function peek_generator(generator) {
+    const iterator = generator[Symbol.asyncIterator]();
+    let result = await iterator.next();
+    const wrapper = (async function* () {
+        while (true) {
+            if (result.done) {
+                break;
+            }
+            yield result.value;
+            result = await iterator.next();
+        }
+    })();
+    return {
+        peeked_value: result.value,
+        generator: wrapper,
+    };
+}
+//# sourceMappingURL=async.js.map

package/dist/utils/async.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"async.js","sourceRoot":"","sources":["../../src/utils/async.ts"],"names":[],"mappings":"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"}

package/dist/utils/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./async.ts";
+export * from "./object.ts";
+export * from "./types.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/utils/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC"}

package/dist/utils/index.js

@@ -0,0 +1,4 @@
+export * from "./async.js";
+export * from "./object.js";
+export * from "./types.js";
+//# sourceMappingURL=index.js.map

package/dist/utils/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC"}

package/dist/utils/object.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Gets all keys from an object where the value is not undefined.
+ *
+ * @param obj - The object to examine.
+ * @returns An array of keys with defined values.
+ */
+export declare function defined_keys(obj: Record<string, unknown>): string[];
+/**
+ * Checks whether an object has any defined properties.
+ *
+ * @param obj - The object to examine.
+ * @returns True if the object has at least one defined property.
+ */
+export declare function has_data(obj: Record<string, unknown>): boolean;
+/**
+ * Returns undefined if the value is empty (empty array or object with no defined keys).
+ *
+ * @template T - The type of the value.
+ * @param obj - The value to check.
+ * @returns The value if non-empty, otherwise undefined.
+ */
+export declare function undefined_if_empty<T = unknown>(obj: T): T | undefined;
+/**
+ * Recursively merges two values together.
+ *
+ * For objects, properties are merged recursively. For arrays, elements are concatenated.
+ * For primitives, the supplemental value replaces the original.
+ *
+ * @template T - The type of values being merged.
+ * @param original - The original value.
+ * @param supplemental - The value to merge in.
+ * @returns The merged result.
+ */
+export declare function deep_merge<T = unknown>(original: T, supplemental: T): T;
+/**
+ * Copies a property from source to destination only if it is defined.
+ *
+ * @template TKey - The key type.
+ * @template TSource - The source object type.
+ * @param key - The property key to copy.
+ * @param source - The source object.
+ * @param destination - The destination object.
+ */
+export declare function copy_if_defined<TKey extends keyof TSource, TSource extends object>(key: TKey, source: TSource, destination: Partial<Pick<TSource, TKey>>): void;
+/**
+ * Type guard that checks if an object contains a specific key.
+ *
+ * @template T - The object type.
+ * @template K - The key type.
+ * @param obj - The object to check.
+ * @param key - The key to look for.
+ * @returns True if the object contains the key.
+ */
+export declare function contains_key<T extends object, K extends string | number>(obj: T, key: K): obj is T & Record<K, unknown>;
+/**
+ * Gets a value from a nested object path.
+ *
+ * @param node - The object to traverse.
+ * @param key_path - The path to the value (dot-separated string or array of keys).
+ * @returns The value at the path, or undefined if not found.
+ */
+export declare function get_nested_value(node: unknown, key_path: string | (string | number)[]): unknown;
+/**
+ * Sets a value at a nested object path.
+ *
+ * Creates intermediate objects/arrays as needed.
+ *
+ * @param node - The object to modify.
+ * @param key_path - The path to set (dot-separated string or array of keys).
+ * @param value - The value to set.
+ */
+export declare function set_nested_value(node: unknown, key_path: string | (string | number)[], value: unknown): void;
+/**
+ * Deletes a value at a nested object path.
+ *
+ * @param node - The object to modify.
+ * @param key_path - The path to delete (dot-separated string or array of keys).
+ */
+export declare function delete_nested_value(node: unknown, key_path: string | (string | number)[]): void;
+//# sourceMappingURL=object.d.ts.map

package/dist/utils/object.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"object.d.ts","sourceRoot":"","sources":["../../src/utils/object.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,YAExD;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,WAEpD;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,CAAC,iBAWrD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,CAAC,GAAG,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,YAAY,EAAE,CAAC,GAAG,CAAC,CAmCvE;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,IAAI,SAAS,MAAM,OAAO,EAAE,OAAO,SAAS,MAAM,EAChF,GAAG,EAAE,IAAI,EACT,MAAM,EAAE,OAAO,EACf,WAAW,EAAE,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,QAK1C;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM,EACtE,GAAG,EAAE,CAAC,EACN,GAAG,EAAE,CAAC,GACL,GAAG,IAAI,CAAC,GAAG,MAAM,CAAC,CAAC,EAAE,OAAO,CAAC,CAE/B;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,GAAG,OAAO,CAa/F;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,OAAO,EACb,QAAQ,EAAE,MAAM,GAAG,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,EACtC,KAAK,EAAE,OAAO,QAwBf;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,QAwBxF"}

package/dist/utils/object.js

@@ -0,0 +1,189 @@
+/**
+ * Gets all keys from an object where the value is not undefined.
+ *
+ * @param obj - The object to examine.
+ * @returns An array of keys with defined values.
+ */
+export function defined_keys(obj) {
+    return Object.keys(obj).filter((key) => obj[key] !== undefined);
+}
+/**
+ * Checks whether an object has any defined properties.
+ *
+ * @param obj - The object to examine.
+ * @returns True if the object has at least one defined property.
+ */
+export function has_data(obj) {
+    return defined_keys(obj).length > 0;
+}
+/**
+ * Returns undefined if the value is empty (empty array or object with no defined keys).
+ *
+ * @template T - The type of the value.
+ * @param obj - The value to check.
+ * @returns The value if non-empty, otherwise undefined.
+ */
+export function undefined_if_empty(obj) {
+    if (!obj) {
+        return obj;
+    }
+    if (Array.isArray(obj)) {
+        return obj.length === 0 ? undefined : obj;
+    }
+    if (typeof obj === "object") {
+        return defined_keys(obj).length === 0 ? undefined : obj;
+    }
+    return obj;
+}
+/**
+ * Recursively merges two values together.
+ *
+ * For objects, properties are merged recursively. For arrays, elements are concatenated.
+ * For primitives, the supplemental value replaces the original.
+ *
+ * @template T - The type of values being merged.
+ * @param original - The original value.
+ * @param supplemental - The value to merge in.
+ * @returns The merged result.
+ */
+export function deep_merge(original, supplemental) {
+    if (supplemental === undefined || supplemental === null) {
+        return original;
+    }
+    if (original === undefined || original === null) {
+        return supplemental;
+    }
+    if (typeof original === "object" && typeof supplemental === "object") {
+        if (Array.isArray(original)) {
+            if (!Array.isArray(supplemental)) {
+                throw new Error("type mismatch");
+            }
+            return [...original, ...supplemental];
+        }
+        else {
+            if (Array.isArray(supplemental)) {
+                throw new Error("type mismatch");
+            }
+            const result = { ...original };
+            for (const [key, value] of Object.entries(supplemental)) {
+                result[key] = deep_merge(result[key], value);
+            }
+            return result;
+        }
+    }
+    if (typeof supplemental !== typeof original) {
+        throw new Error("type mismatch");
+    }
+    if (typeof supplemental === "string" ||
+        typeof supplemental === "number" ||
+        typeof supplemental === "boolean") {
+        return supplemental;
+    }
+    throw new Error("unsupported type");
+}
+/**
+ * Copies a property from source to destination only if it is defined.
+ *
+ * @template TKey - The key type.
+ * @template TSource - The source object type.
+ * @param key - The property key to copy.
+ * @param source - The source object.
+ * @param destination - The destination object.
+ */
+export function copy_if_defined(key, source, destination) {
+    if (source[key] !== undefined) {
+        destination[key] = source[key];
+    }
+}
+/**
+ * Type guard that checks if an object contains a specific key.
+ *
+ * @template T - The object type.
+ * @template K - The key type.
+ * @param obj - The object to check.
+ * @param key - The key to look for.
+ * @returns True if the object contains the key.
+ */
+export function contains_key(obj, key) {
+    return key in obj;
+}
+/**
+ * Gets a value from a nested object path.
+ *
+ * @param node - The object to traverse.
+ * @param key_path - The path to the value (dot-separated string or array of keys).
+ * @returns The value at the path, or undefined if not found.
+ */
+export function get_nested_value(node, key_path) {
+    if (typeof key_path === "string") {
+        return get_nested_value(node, key_path.split("."));
+    }
+    const [key, ...rest] = key_path;
+    if (typeof node !== "object" || node === null || key === undefined) {
+        return node;
+    }
+    if (!contains_key(node, key)) {
+        return undefined;
+    }
+    return get_nested_value(node[key], rest);
+}
+/**
+ * Sets a value at a nested object path.
+ *
+ * Creates intermediate objects/arrays as needed.
+ *
+ * @param node - The object to modify.
+ * @param key_path - The path to set (dot-separated string or array of keys).
+ * @param value - The value to set.
+ */
+export function set_nested_value(node, key_path, value) {
+    if (typeof key_path === "string") {
+        set_nested_value(node, key_path.split("."), value);
+        return;
+    }
+    const [key, next_key, ...rest] = key_path;
+    if (key === undefined) {
+        throw new Error("invalid object key");
+    }
+    if (typeof node !== "object" || node === null) {
+        throw new Error("invalid object value");
+    }
+    const obj = node;
+    if (next_key === undefined || next_key === null) {
+        obj[key] = value;
+        return;
+    }
+    if (obj[key] === undefined || obj[key] === null) {
+        obj[key] = typeof next_key === "number" || /^\d+$/.test(String(next_key)) ? [] : {};
+    }
+    set_nested_value(obj[key], [next_key, ...rest], value);
+}
+/**
+ * Deletes a value at a nested object path.
+ *
+ * @param node - The object to modify.
+ * @param key_path - The path to delete (dot-separated string or array of keys).
+ */
+export function delete_nested_value(node, key_path) {
+    if (typeof key_path === "string") {
+        delete_nested_value(node, key_path.split("."));
+        return;
+    }
+    const [key, next_key, ...rest] = key_path;
+    if (key === undefined) {
+        return;
+    }
+    if (typeof node !== "object" || node === null) {
+        return;
+    }
+    const obj = node;
+    if (!contains_key(obj, key)) {
+        return;
+    }
+    if (next_key === undefined) {
+        delete obj[key];
+        return;
+    }
+    delete_nested_value(obj[key], [next_key, ...rest]);
+}
+//# sourceMappingURL=object.js.map

package/dist/utils/object.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"object.js","sourceRoot":"","sources":["../../src/utils/object.ts"],"names":[],"mappings":"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"}

package/dist/utils/types.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Makes all properties of an object and their nested properties optional.
+ *
+ * @template T - The object type to make deeply partial.
+ */
+export type DeepPartial<T> = Partial<{
+    [K in keyof T]: Partial<T[K]>;
+}>;
+/**
+ * Flattens intersection types for better IDE display.
+ *
+ * @template T - The type to prettify.
+ */
+export type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+//# sourceMappingURL=types.d.ts.map

package/dist/utils/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/utils/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,OAAO,CAAC;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAAE,CAAC,CAAC;AAExE;;;;GAIG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CAAE,GAAG,EAAE,CAAC"}

package/dist/utils/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/utils/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/utils/types.ts"],"names":[],"mappings":""}

package/dist/workflows/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./types.ts";
+export * from "./workflow.ts";
+export * from "./workflow-manager.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/workflows/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/workflows/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,uBAAuB,CAAC"}

package/dist/workflows/index.js

@@ -0,0 +1,4 @@
+export * from "./types.js";
+export * from "./workflow.js";
+export * from "./workflow-manager.js";
+//# sourceMappingURL=index.js.map

package/dist/workflows/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/workflows/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,uBAAuB,CAAC"}

package/dist/workflows/types.d.ts

@@ -0,0 +1,70 @@
+import { ChangeEvent, type LifecycleErrorEvent } from "../conversations/index.ts";
+import { WorkflowManager } from "./workflow-manager.ts";
+import { Workflow } from "./workflow.ts";
+/**
+ * Possible states of a workflow.
+ */
+export type WorkflowState = "idle" | "busy" | "disposed";
+/**
+ * Event data describing why a workflow ended.
+ */
+export type WorkflowEndEvent = {
+    reason: "complete" | "cancel" | "error";
+};
+/**
+ * Events emitted by a Workflow instance.
+ */
+export interface WorkflowEvents {
+    /** Emitted when the workflow state changes. */
+    state_change: [ChangeEvent<WorkflowState>, Workflow];
+    /** Emitted when the workflow is updated with new messages. */
+    workflow_update: [Workflow];
+    /** Emitted when the workflow ends. */
+    workflow_end: [WorkflowEndEvent, Workflow];
+    /** Emitted when a child workflow is created. */
+    child_workflow_begin: [Workflow, Workflow];
+    /** Emitted when a child workflow emits an event. */
+    child_workflow_event: [
+        {
+            [E in keyof WorkflowEvents]: {
+                event_name: E;
+                event_args: WorkflowEvents[E];
+            };
+        }[keyof WorkflowEvents],
+        Workflow
+    ];
+    /** Emitted when a message is added to the queue. */
+    message_queued: [string, Workflow];
+    /** Emitted when a message is removed from the queue for sending. */
+    message_dequeued: [string, Workflow];
+    /** Emitted when the message queue is cleared. */
+    queue_cleared: [Workflow];
+    /** Emitted when an infrastructure or lifecycle operation fails. */
+    lifecycle_error: [LifecycleErrorEvent, Workflow];
+    /** Emitted when the workflow is disposed. */
+    dispose: [Workflow];
+}
+/**
+ * Events emitted by a WorkflowManager instance.
+ */
+export interface WorkflowManagerEvents {
+    /** Emitted when the workflow manager state changes. */
+    state_change: [ChangeEvent<WorkflowState>, WorkflowManager];
+    /** Emitted when a new workflow begins. */
+    workflow_begin: [Workflow, WorkflowManager];
+    /** Emitted when a managed workflow emits an event. */
+    workflow_event: [
+        {
+            [E in keyof WorkflowEvents]: {
+                event_name: E;
+                event_args: WorkflowEvents[E];
+            };
+        }[keyof WorkflowEvents],
+        WorkflowManager
+    ];
+    /** Emitted when an infrastructure or lifecycle operation fails. */
+    lifecycle_error: [LifecycleErrorEvent, WorkflowManager];
+    /** Emitted when the workflow manager is disposed. */
+    dispose: [WorkflowManager];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/workflows/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/workflows/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,KAAK,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAClF,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEzC;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,MAAM,GAAG,UAAU,CAAC;AAEzD;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAAE,MAAM,EAAE,UAAU,GAAG,QAAQ,GAAG,OAAO,CAAA;CAAE,CAAC;AAE3E;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,+CAA+C;IAC/C,YAAY,EAAE,CAAC,WAAW,CAAC,aAAa,CAAC,EAAE,QAAQ,CAAC,CAAC;IACrD,8DAA8D;IAC9D,eAAe,EAAE,CAAC,QAAQ,CAAC,CAAC;IAC5B,sCAAsC;IACtC,YAAY,EAAE,CAAC,gBAAgB,EAAE,QAAQ,CAAC,CAAC;IAC3C,gDAAgD;IAChD,oBAAoB,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAC3C,oDAAoD;IACpD,oBAAoB,EAAE;QACpB;aACG,CAAC,IAAI,MAAM,cAAc,GAAG;gBAC3B,UAAU,EAAE,CAAC,CAAC;gBACd,UAAU,EAAE,cAAc,CAAC,CAAC,CAAC,CAAC;aAC/B;SACF,CAAC,MAAM,cAAc,CAAC;QACvB,QAAQ;KACT,CAAC;IACF,oDAAoD;IACpD,cAAc,EAAE,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IACnC,oEAAoE;IACpE,gBAAgB,EAAE,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IACrC,iDAAiD;IACjD,aAAa,EAAE,CAAC,QAAQ,CAAC,CAAC;IAC1B,mEAAmE;IACnE,eAAe,EAAE,CAAC,mBAAmB,EAAE,QAAQ,CAAC,CAAC;IACjD,6CAA6C;IAC7C,OAAO,EAAE,CAAC,QAAQ,CAAC,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,uDAAuD;IACvD,YAAY,EAAE,CAAC,WAAW,CAAC,aAAa,CAAC,EAAE,eAAe,CAAC,CAAC;IAC5D,0CAA0C;IAC1C,cAAc,EAAE,CAAC,QAAQ,EAAE,eAAe,CAAC,CAAC;IAC5C,sDAAsD;IACtD,cAAc,EAAE;QACd;aACG,CAAC,IAAI,MAAM,cAAc,GAAG;gBAC3B,UAAU,EAAE,CAAC,CAAC;gBACd,UAAU,EAAE,cAAc,CAAC,CAAC,CAAC,CAAC;aAC/B;SACF,CAAC,MAAM,cAAc,CAAC;QACvB,eAAe;KAChB,CAAC;IACF,mEAAmE;IACnE,eAAe,EAAE,CAAC,mBAAmB,EAAE,eAAe,CAAC,CAAC;IACxD,qDAAqD;IACrD,OAAO,EAAE,CAAC,eAAe,CAAC,CAAC;CAC5B"}

package/dist/workflows/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/workflows/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/workflows/types.ts"],"names":[],"mappings":""}