modal 0.3.7 → 0.3.8

package/dist/index.d.cts

@@ -0,0 +1,380 @@
+import { BinaryWriter, BinaryReader } from '@bufbuild/protobuf/wire';
+
+declare enum ParameterType {
+    PARAM_TYPE_UNSPECIFIED = 0,
+    PARAM_TYPE_STRING = 1,
+    PARAM_TYPE_INT = 2,
+    /** PARAM_TYPE_PICKLE - currently unused */
+    PARAM_TYPE_PICKLE = 3,
+    PARAM_TYPE_BYTES = 4,
+    /** PARAM_TYPE_UNKNOWN - used in schemas to signify unrecognized or un-annotated types */
+    PARAM_TYPE_UNKNOWN = 5,
+    PARAM_TYPE_LIST = 6,
+    PARAM_TYPE_DICT = 7,
+    PARAM_TYPE_NONE = 8,
+    PARAM_TYPE_BOOL = 9,
+    UNRECOGNIZED = -1
+}
+/** TODO: rename into NamedPayloadType or similar */
+interface ClassParameterSpec {
+    name: string;
+    /** TODO: deprecate - use full_type instead */
+    type: ParameterType;
+    hasDefault: boolean;
+    /** Default *values* are only registered for class parameters */
+    stringDefault?: string | undefined;
+    intDefault?: number | undefined;
+    pickleDefault?: Uint8Array | undefined;
+    bytesDefault?: Uint8Array | undefined;
+    boolDefault?: boolean | undefined;
+    /** supersedes `type` */
+    fullType: GenericPayloadType | undefined;
+}
+declare const ClassParameterSpec: MessageFns<ClassParameterSpec>;
+interface GenericPayloadType {
+    baseType: ParameterType;
+    /** sub-type for generic types like lists */
+    subTypes: GenericPayloadType[];
+}
+declare const GenericPayloadType: MessageFns<GenericPayloadType>;
+type Builtin = Date | Function | Uint8Array | string | number | boolean | undefined;
+type DeepPartial<T> = T extends Builtin ? T : T extends globalThis.Array<infer U> ? globalThis.Array<DeepPartial<U>> : T extends ReadonlyArray<infer U> ? ReadonlyArray<DeepPartial<U>> : T extends {} ? {
+    [K in keyof T]?: DeepPartial<T[K]>;
+} : Partial<T>;
+interface MessageFns<T> {
+    encode(message: T, writer?: BinaryWriter): BinaryWriter;
+    decode(input: BinaryReader | Uint8Array, length?: number): T;
+    fromJSON(object: any): T;
+    toJSON(message: T): unknown;
+    create(base?: DeepPartial<T>): T;
+    fromPartial(object: DeepPartial<T>): T;
+}
+
+/** A container image, used for starting sandboxes. */
+declare class Image {
+    readonly imageId: string;
+    /** @ignore */
+    constructor(imageId: string);
+}
+
+/**
+ * Wrapper around `ReadableStream` with convenience functions.
+ *
+ * The Stream API is a modern standard for asynchronous data streams across
+ * network and process boundaries. It allows you to read data in chunks, pipe
+ * and transform it, and handle backpressure.
+ *
+ * This wrapper adds some extra functions like `.readText()` to read the entire
+ * stream as a string, or `readBytes()` to read binary data.
+ *
+ * Background: https://developer.mozilla.org/en-US/docs/Web/API/Streams_API
+ */
+interface ModalReadStream<R = any> extends ReadableStream<R> {
+    /** Read the entire stream as a string. */
+    readText(): Promise<string>;
+    /** Read the entire stream as a byte array. */
+    readBytes(): Promise<Uint8Array>;
+}
+/**
+ * Wrapper around `WritableStream` with convenience functions.
+ *
+ * The Stream API is a modern standard for asynchronous data streams across
+ * network and process boundaries. It allows you to read data in chunks, pipe
+ * and transform it, and handle backpressure.
+ *
+ * This wrapper adds some extra functions like `.writeText()` to write a string
+ * to the stream, or `writeBytes()` to write binary data.
+ *
+ * Background: https://developer.mozilla.org/en-US/docs/Web/API/Streams_API
+ */
+interface ModalWriteStream<R = any> extends WritableStream<R> {
+    /** Write a string to the stream. Only if this is a text stream. */
+    writeText(text: string): Promise<void>;
+    /** Write a byte array to the stream. Only if this is a byte stream. */
+    writeBytes(bytes: Uint8Array): Promise<void>;
+}
+
+/**
+ * Stdin is always present, but this option allow you to drop stdout or stderr
+ * if you don't need them. The default is "pipe", matching Node.js behavior.
+ *
+ * If behavior is set to "ignore", the output streams will be empty.
+ */
+type StdioBehavior = "pipe" | "ignore";
+/**
+ * Specifies the type of data that will be read from the sandbox or container
+ * process. "text" means the data will be read as UTF-8 text, while "binary"
+ * means the data will be read as raw bytes (Uint8Array).
+ */
+type StreamMode = "text" | "binary";
+/** Options to configure a `Sandbox.exec()` operation. */
+type ExecOptions = {
+    mode?: StreamMode;
+    stdout?: StdioBehavior;
+    stderr?: StdioBehavior;
+};
+/** Sandboxes are secure, isolated containers in Modal that boot in seconds. */
+declare class Sandbox {
+    #private;
+    readonly sandboxId: string;
+    stdin: ModalWriteStream<string>;
+    stdout: ModalReadStream<string>;
+    stderr: ModalReadStream<string>;
+    /** @ignore */
+    constructor(sandboxId: string);
+    exec(command: string[], options?: ExecOptions & {
+        mode?: "text";
+    }): Promise<ContainerProcess<string>>;
+    exec(command: string[], options: ExecOptions & {
+        mode: "binary";
+    }): Promise<ContainerProcess<Uint8Array>>;
+    terminate(): Promise<void>;
+    wait(): Promise<number>;
+}
+declare class ContainerProcess<R extends string | Uint8Array = any> {
+    #private;
+    stdin: ModalWriteStream<R>;
+    stdout: ModalReadStream<R>;
+    stderr: ModalReadStream<R>;
+    returncode: number | null;
+    constructor(execId: string, options?: ExecOptions);
+    /** Wait for process completion and return the exit code. */
+    wait(): Promise<number>;
+}
+
+/** Options for `Secret.fromName()`. */
+type SecretFromNameOptions = {
+    environment?: string;
+    requiredKeys?: string[];
+};
+/** Secrets provide a dictionary of environment variables for images. */
+declare class Secret {
+    readonly secretId: string;
+    /** @ignore */
+    constructor(secretId: string);
+    /** Reference a Secret by its name. */
+    static fromName(name: string, options?: SecretFromNameOptions): Promise<Secret>;
+}
+
+/** Options for functions that find deployed Modal objects. */
+type LookupOptions = {
+    environment?: string;
+    createIfMissing?: boolean;
+};
+/** Options for deleting a named object. */
+type DeleteOptions = {
+    environment?: string;
+};
+/** Options for constructors that create a temporary, nameless object. */
+type EphemeralOptions = {
+    environment?: string;
+};
+/** Options for `App.createSandbox()`. */
+type SandboxCreateOptions = {
+    /** Reservation of physical CPU cores for the sandbox, can be fractional. */
+    cpu?: number;
+    /** Reservation of memory in MiB. */
+    memory?: number;
+    /** Timeout of the sandbox container, defaults to 10 minutes. */
+    timeout?: number;
+    /**
+     * Sequence of program arguments for the main process.
+     * Default behavior is to sleep indefinitely until timeout or termination.
+     */
+    command?: string[];
+};
+/** Represents a deployed Modal App. */
+declare class App {
+    readonly appId: string;
+    /** @ignore */
+    constructor(appId: string);
+    /** Lookup a deployed app by name, or create if it does not exist. */
+    static lookup(name: string, options?: LookupOptions): Promise<App>;
+    createSandbox(image: Image, options?: SandboxCreateOptions): Promise<Sandbox>;
+    imageFromRegistry(tag: string): Promise<Image>;
+    imageFromAwsEcr(tag: string, secret: Secret): Promise<Image>;
+}
+
+/** Options for `FunctionCall.get()`. */
+type FunctionCallGetOptions = {
+    timeout?: number;
+};
+/** Options for `FunctionCall.cancel()`. */
+type FunctionCallCancelOptions = {
+    terminateContainers?: boolean;
+};
+/**
+ * Represents a Modal FunctionCall. Function Calls are Function invocations with
+ * a given input. They can be consumed asynchronously (see `get()`) or cancelled
+ * (see `cancel()`).
+ */
+declare class FunctionCall {
+    readonly functionCallId: string;
+    /** @ignore */
+    constructor(functionCallId: string);
+    /** Create a new function call from ID. */
+    fromId(functionCallId: string): FunctionCall;
+    /** Get the result of a function call, optionally waiting with a timeout. */
+    get(options?: FunctionCallGetOptions): Promise<any>;
+    /** Cancel a running function call. */
+    cancel(options?: FunctionCallCancelOptions): Promise<void>;
+}
+
+/** Represents a deployed Modal Function, which can be invoked remotely. */
+declare class Function_ {
+    #private;
+    readonly functionId: string;
+    readonly methodName: string | undefined;
+    /** @ignore */
+    constructor(functionId: string, methodName?: string);
+    static lookup(appName: string, name: string, options?: LookupOptions): Promise<Function_>;
+    remote(args?: any[], kwargs?: Record<string, any>): Promise<any>;
+    spawn(args?: any[], kwargs?: Record<string, any>): Promise<FunctionCall>;
+}
+
+/** Represents a deployed Modal Cls. */
+declare class Cls {
+    #private;
+    /** @ignore */
+    constructor(serviceFunctionId: string, schema: ClassParameterSpec[], methodNames: string[]);
+    static lookup(appName: string, name: string, options?: LookupOptions): Promise<Cls>;
+    /** Create a new instance of the Cls with parameters. */
+    instance(params?: Record<string, any>): Promise<ClsInstance>;
+}
+/** Represents an instance of a deployed Modal Cls, optionally with parameters. */
+declare class ClsInstance {
+    #private;
+    constructor(methods: Map<string, Function_>);
+    method(name: string): Function_;
+}
+
+/** Function execution exceeds the allowed time limit. */
+declare class FunctionTimeoutError extends Error {
+    constructor(message: string);
+}
+/** An error on the Modal server, or a Python exception. */
+declare class RemoteError extends Error {
+    constructor(message: string);
+}
+/** A retryable internal error from Modal. */
+declare class InternalFailure extends Error {
+    constructor(message: string);
+}
+/** Some resource was not found. */
+declare class NotFoundError extends Error {
+    constructor(message: string);
+}
+/** A request or other operation was invalid. */
+declare class InvalidError extends Error {
+    constructor(message: string);
+}
+/** The queue is empty. */
+declare class QueueEmptyError extends Error {
+    constructor(message: string);
+}
+/** The queue is full. */
+declare class QueueFullError extends Error {
+    constructor(message: string);
+}
+
+/** Options to configure a `Queue.clear()` operation. */
+type QueueClearOptions = {
+    /** Partition to clear, uses default partition if not set. */
+    partition?: string;
+    /** Set to clear all queue partitions. */
+    all?: boolean;
+};
+/** Options to configure a `Queue.get()` or `Queue.getMany()` operation. */
+type QueueGetOptions = {
+    /** How long to wait if the queue is empty (default: indefinite). */
+    timeout?: number;
+    /** Partition to fetch values from, uses default partition if not set. */
+    partition?: string;
+};
+/** Options to configure a `Queue.put()` or `Queue.putMany()` operation. */
+type QueuePutOptions = {
+    /** How long to wait if the queue is full (default: indefinite). */
+    timeout?: number;
+    /** Partition to add items to, uses default partition if not set. */
+    partition?: string;
+    /** TTL for the partition in seconds (default: 1 day). */
+    partitionTtl?: number;
+};
+/** Options to configure a `Queue.len()` operation. */
+type QueueLenOptions = {
+    /** Partition to compute length, uses default partition if not set. */
+    partition?: string;
+    /** Return the total length across all partitions. */
+    total?: boolean;
+};
+/** Options to configure a `Queue.iterate()` operation. */
+type QueueIterateOptions = {
+    /** How long to wait between successive items before exiting iteration (default: 0). */
+    itemPollTimeout?: number;
+    /** Partition to iterate, uses default partition if not set. */
+    partition?: string;
+};
+/**
+ * Distributed, FIFO queue for data flow in Modal apps.
+ */
+declare class Queue {
+    #private;
+    readonly queueId: string;
+    /** @ignore */
+    constructor(queueId: string, ephemeral?: boolean);
+    /**
+     * Create a nameless, temporary queue.
+     * You will need to call `closeEphemeral()` to delete the queue.
+     */
+    static ephemeral(options?: EphemeralOptions): Promise<Queue>;
+    /** Delete the ephemeral queue. Only usable with `Queue.ephemeral()`. */
+    closeEphemeral(): void;
+    /**
+     * Lookup a queue by name.
+     */
+    static lookup(name: string, options?: LookupOptions): Promise<Queue>;
+    /** Delete a queue by name. */
+    static delete(name: string, options?: DeleteOptions): Promise<void>;
+    /**
+     * Remove all objects from a queue partition.
+     */
+    clear(options?: QueueClearOptions): Promise<void>;
+    /**
+     * Remove and return the next object from the queue.
+     *
+     * By default, this will wait until at least one item is present in the queue.
+     * If `timeout` is set, raises `QueueEmptyError` if no items are available
+     * within that timeout in milliseconds.
+     */
+    get(options?: QueueGetOptions): Promise<any | null>;
+    /**
+     * Remove and return up to `n` objects from the queue.
+     *
+     * By default, this will wait until at least one item is present in the queue.
+     * If `timeout` is set, raises `QueueEmptyError` if no items are available
+     * within that timeout in milliseconds.
+     */
+    getMany(n: number, options?: QueueGetOptions): Promise<any[]>;
+    /**
+     * Add an item to the end of the queue.
+     *
+     * If the queue is full, this will retry with exponential backoff until the
+     * provided `timeout` is reached, or indefinitely if `timeout` is not set.
+     * Raises `QueueFullError` if the queue is still full after the timeout.
+     */
+    put(v: any, options?: QueuePutOptions): Promise<void>;
+    /**
+     * Add several items to the end of the queue.
+     *
+     * If the queue is full, this will retry with exponential backoff until the
+     * provided `timeout` is reached, or indefinitely if `timeout` is not set.
+     * Raises `QueueFullError` if the queue is still full after the timeout.
+     */
+    putMany(values: any[], options?: QueuePutOptions): Promise<void>;
+    /** Return the number of objects in the queue. */
+    len(options?: QueueLenOptions): Promise<number>;
+    /** Iterate through items in a queue without mutation. */
+    iterate(options?: QueueIterateOptions): AsyncGenerator<any, void, unknown>;
+}
+
+export { App, Cls, ClsInstance, ContainerProcess, type DeleteOptions, type EphemeralOptions, type ExecOptions, FunctionCall, type FunctionCallCancelOptions, type FunctionCallGetOptions, FunctionTimeoutError, Function_, Image, InternalFailure, InvalidError, type LookupOptions, type ModalReadStream, type ModalWriteStream, NotFoundError, Queue, type QueueClearOptions, QueueEmptyError, QueueFullError, type QueueGetOptions, type QueueIterateOptions, type QueueLenOptions, type QueuePutOptions, RemoteError, Sandbox, type SandboxCreateOptions, Secret, type SecretFromNameOptions, type StdioBehavior, type StreamMode };