modal 0.3.4 → 0.3.6

package/README.md

@@ -1,5 +1,6 @@
 # Modal JavaScript Library
 
+[![Documentation](https://img.shields.io/badge/docs-reference-blue)](https://modal-labs.github.io/libmodal/)
 [![Version](https://img.shields.io/npm/v/modal.svg)](https://www.npmjs.org/package/modal)
 [![Build Status](https://github.com/modal-labs/libmodal/actions/workflows/ci.yaml/badge.svg?branch=main)](https://github.com/modal-labs/libmodal/actions?query=branch%3Amain)
 [![Downloads](https://img.shields.io/npm/dm/modal.svg)](https://www.npmjs.com/package/modal)

package/dist/index.d.ts

@@ -1,7 +1,9 @@
 import { BinaryWriter, BinaryReader } from '@bufbuild/protobuf/wire';
 
+/** A container image, used for starting sandboxes. */
 declare class Image {
     readonly imageId: string;
+    /** @ignore */
     constructor(imageId: string);
 }
 
@@ -42,19 +44,33 @@ interface ModalWriteStream<R = any> extends WritableStream<R> {
     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";
@@ -76,18 +92,37 @@ declare class ContainerProcess<R extends string | Uint8Array = any> {
     wait(): Promise<number>;
 }
 
+/** 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>;
@@ -145,18 +180,47 @@ interface MessageFns<T> {
     fromPartial(object: DeepPartial<T>): T;
 }
 
+/** 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. */
@@ -170,7 +234,7 @@ declare class ClsInstance {
 }
 
 /** Function execution exceeds the allowed time limit. */
-declare class TimeoutError extends Error {
+declare class FunctionTimeoutError extends Error {
     constructor(message: string);
 }
 /** An error on the Modal server, or a Python exception. */
@@ -185,5 +249,117 @@ declare class InternalFailure extends Error {
 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, Function_, Image, InternalFailure, type LookupOptions, NotFoundError, RemoteError, Sandbox, type SandboxCreateOptions, type StdioBehavior, type StreamMode, TimeoutError };
+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, type StdioBehavior, type StreamMode };