modal 0.3.19 → 0.3.21

package/dist/index.d.cts

@@ -69,7 +69,7 @@ type SecretFromNameOptions = {
     environment?: string;
     requiredKeys?: string[];
 };
-/** Secrets provide a dictionary of environment variables for images. */
+/** Secrets provide a dictionary of environment variables for Images. */
 declare class Secret {
     readonly secretId: string;
     readonly name?: string;
@@ -83,51 +83,55 @@ declare class Secret {
     }): Promise<Secret>;
 }
 
-/** A container image, used for starting sandboxes. */
+/** Options for deleting an Image. */
+type ImageDeleteOptions = Record<never, never>;
+/** A container image, used for starting Sandboxes. */
 declare class Image {
     #private;
     /** @ignore */
     constructor(imageId: string, tag: string, imageRegistryConfig?: ImageRegistryConfig);
     get imageId(): string;
     /**
-     * Creates an `Image` instance from an image id
+     * Creates an Image from an Image ID
      *
-     * @param imageId - Image id.
+     * @param imageId - Image ID.
      */
-    static fromId(imageId: string): Image;
+    static fromId(imageId: string): Promise<Image>;
     /**
-     * Creates an `Image` instance from a raw registry tag, optionally using a secret for authentication.
+     * Creates an Image from a raw registry tag, optionally using a Secret for authentication.
      *
-     * @param tag - The registry tag for the image.
-     * @param secret - Optional. A `Secret` instance containing credentials for registry authentication.
+     * @param tag - The registry tag for the Image.
+     * @param secret - Optional. A Secret containing credentials for registry authentication.
      */
     static fromRegistry(tag: string, secret?: Secret): Image;
     /**
-     * Creates an `Image` instance from a raw registry tag, optionally using a secret for authentication.
+     * Creates an Image from a raw registry tag, optionally using a Secret for authentication.
      *
-     * @param tag - The registry tag for the image.
-     * @param secret - A `Secret` instance containing credentials for registry authentication.
+     * @param tag - The registry tag for the Image.
+     * @param secret - A Secret containing credentials for registry authentication.
      */
     static fromAwsEcr(tag: string, secret: Secret): Image;
     /**
-     * Creates an `Image` instance from a raw registry tag, optionally using a secret for authentication.
+     * Creates an Image from a raw registry tag, optionally using a Secret for authentication.
      *
-     * @param tag - The registry tag for the image.
-     * @param secret - A `Secret` instance containing credentials for registry authentication.
+     * @param tag - The registry tag for the Image.
+     * @param secret - A Secret containing credentials for registry authentication.
      */
     static fromGcpArtifactRegistry(tag: string, secret: Secret): Image;
     /**
-     * Eagerly builds an `Image` on Modal.
+     * Eagerly builds an Image on Modal.
      *
-     * @param app - App to use to build image.
+     * @param app - App to use to build the Image.
      */
     build(app: App): Promise<Image>;
+    /** Delete an Image by ID. Warning: This removes an *entire Image*, and cannot be undone. */
+    static delete(imageId: string, _?: ImageDeleteOptions): Promise<void>;
 }
 
 /** File open modes supported by the filesystem API. */
 type SandboxFileMode = "r" | "w" | "a" | "r+" | "w+" | "a+";
 /**
- * SandboxFile represents an open file in the sandbox filesystem.
+ * SandboxFile represents an open file in the Sandbox filesystem.
  * Provides read/write operations similar to Node.js `fsPromises.FileHandle`.
  */
 declare class SandboxFile {
@@ -199,16 +203,16 @@ interface ModalWriteStream<R = any> extends WritableStream<R> {
  */
 type StdioBehavior = "pipe" | "ignore";
 /**
- * Specifies the type of data that will be read from the sandbox or container
+ * 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 for `Sandbox.list()`. */
 type SandboxListOptions = {
-    /** Filter sandboxes for a specific app. */
+    /** Filter Sandboxes for a specific App. */
     appId?: string;
-    /** Only return sandboxes that include all specified tags. */
+    /** Only return Sandboxes that include all specified tags. */
     tags?: Record<string, string>;
     /** Override environment for the request; defaults to current profile. */
     environment?: string;
@@ -228,7 +232,7 @@ type ExecOptions = {
     /** Secrets with environment variables for the command. */
     secrets?: Secret[];
 };
-/** A port forwarded from within a running Modal sandbox. */
+/** A port forwarded from within a running Modal Sandbox. */
 declare class Tunnel {
     host: string;
     port: number;
@@ -264,14 +268,14 @@ declare class Sandbox {
      * Raises a NotFoundError if no running Sandbox is found with the given name.
      * A Sandbox's name is the `name` argument passed to `App.createSandbox`.
      *
-     * @param appName - Name of the deployed app
-     * @param name - Name of the sandbox
+     * @param appName - Name of the deployed App
+     * @param name - Name of the Sandbox
      * @param environment - Optional override for the environment
      * @returns Promise that resolves to a Sandbox
      */
     static fromName(appName: string, name: string, environment?: string): Promise<Sandbox>;
     /**
-     * Open a file in the sandbox filesystem.
+     * Open a file in the Sandbox filesystem.
      * @param path - Path to the file to open
      * @param mode - File open mode (r, w, a, r+, w+, a+)
      * @returns Promise that resolves to a SandboxFile
@@ -285,7 +289,7 @@ declare class Sandbox {
     }): Promise<ContainerProcess<Uint8Array>>;
     terminate(): Promise<void>;
     wait(): Promise<number>;
-    /** Get Tunnel metadata for the sandbox.
+    /** Get Tunnel metadata for the Sandbox.
      *
      * Raises `SandboxTimeoutError` if the tunnels are not available after the timeout.
      *
@@ -338,7 +342,7 @@ type VolumeFromNameOptions = {
     environment?: string;
     createIfMissing?: boolean;
 };
-/** Volumes provide persistent storage that can be mounted in Modal functions. */
+/** Volumes provide persistent storage that can be mounted in Modal Functions. */
 declare class Volume {
     #private;
     readonly volumeId: string;
@@ -351,11 +355,11 @@ declare class Volume {
     readOnly(): Volume;
     get isReadOnly(): boolean;
     /**
-     * Create a nameless, temporary volume.
-     * You will need to call `closeEphemeral()` to delete the volume.
+     * Create a nameless, temporary Volume.
+     * You will need to call `closeEphemeral()` to delete the Volume.
      */
     static ephemeral(options?: EphemeralOptions): Promise<Volume>;
-    /** Delete the ephemeral volume. Only usable with `Volume.ephemeral()`. */
+    /** Delete the ephemeral Volume. Only usable with `Volume.ephemeral()`. */
     closeEphemeral(): void;
 }
 
@@ -372,7 +376,7 @@ declare class Proxy {
     static fromName(name: string, options?: ProxyFromNameOptions): Promise<Proxy>;
 }
 
-/** Cloud bucket mounts provide access to cloud storage buckets within Modal functions. */
+/** Cloud Bucket Mounts provide access to cloud storage buckets within Modal Functions. */
 declare class CloudBucketMount {
     readonly bucketName: string;
     readonly secret?: Secret;
@@ -406,46 +410,48 @@ type EphemeralOptions = {
 };
 /** Options for `App.createSandbox()`. */
 type SandboxCreateOptions = {
-    /** Reservation of physical CPU cores for the sandbox, can be fractional. */
+    /** Reservation of physical CPU cores for the Sandbox, can be fractional. */
     cpu?: number;
     /** Reservation of memory in MiB. */
     memory?: number;
-    /** GPU reservation for the sandbox (e.g. "A100", "T4:2", "A100-80GB:4"). */
+    /** GPU reservation for the Sandbox (e.g. "A100", "T4:2", "A100-80GB:4"). */
     gpu?: string;
-    /** Timeout of the sandbox container, defaults to 10 minutes. */
+    /** Timeout of the Sandbox container, defaults to 10 minutes. */
     timeout?: number;
-    /** Working directory of the sandbox. */
+    /** The amount of time in milliseconds that a sandbox can be idle before being terminated. */
+    idleTimeout?: number;
+    /** Working directory of the Sandbox. */
     workdir?: string;
     /**
      * Sequence of program arguments for the main process.
      * Default behavior is to sleep indefinitely until timeout or termination.
      */
     command?: string[];
-    /** Secrets to inject into the sandbox. */
+    /** Secrets to inject into the Sandbox. */
     secrets?: Secret[];
     /** Mount points for Modal Volumes. */
     volumes?: Record<string, Volume>;
     /** Mount points for cloud buckets. */
     cloudBucketMounts?: Record<string, CloudBucketMount>;
-    /** List of ports to tunnel into the sandbox. Encrypted ports are tunneled with TLS. */
+    /** List of ports to tunnel into the Sandbox. Encrypted ports are tunneled with TLS. */
     encryptedPorts?: number[];
-    /** List of encrypted ports to tunnel into the sandbox, using HTTP/2. */
+    /** List of encrypted ports to tunnel into the Sandbox, using HTTP/2. */
     h2Ports?: number[];
-    /** List of ports to tunnel into the sandbox without encryption. */
+    /** List of ports to tunnel into the Sandbox without encryption. */
     unencryptedPorts?: number[];
-    /** Whether to block all network access from the sandbox. */
+    /** Whether to block all network access from the Sandbox. */
     blockNetwork?: boolean;
-    /** List of CIDRs the sandbox is allowed to access. If None, all CIDRs are allowed. Cannot be used with blockNetwork. */
+    /** List of CIDRs the Sandbox is allowed to access. If None, all CIDRs are allowed. Cannot be used with blockNetwork. */
     cidrAllowlist?: string[];
-    /** Cloud provider to run the sandbox on. */
+    /** Cloud provider to run the Sandbox on. */
     cloud?: string;
-    /** Region(s) to run the sandbox on. */
+    /** Region(s) to run the Sandbox on. */
     regions?: string[];
     /** Enable verbose logging. */
     verbose?: boolean;
     /** Reference to a Modal Proxy to use in front of this Sandbox. */
     proxy?: Proxy;
-    /** Optional name for the sandbox. Unique within an app. */
+    /** Optional name for the Sandbox. Unique within an App. */
     name?: string;
 };
 /** Represents a deployed Modal App. */
@@ -454,7 +460,7 @@ declare class App {
     readonly name?: string;
     /** @ignore */
     constructor(appId: string, name?: string);
-    /** Lookup a deployed app by name, or create if it does not exist. */
+    /** 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>;
     /**
@@ -502,11 +508,11 @@ declare class FunctionCall {
     readonly functionCallId: string;
     /** @ignore */
     constructor(functionCallId: string);
-    /** Create a new function call from ID. */
+    /** Create a new Function call from ID. */
     fromId(functionCallId: string): FunctionCall;
-    /** Get the result of a function call, optionally waiting with a timeout. */
+    /** Get the result of a Function call, optionally waiting with a timeout. */
     get(options?: FunctionCallGetOptions): Promise<any>;
-    /** Cancel a running function call. */
+    /** Cancel a running Function call. */
     cancel(options?: FunctionCallCancelOptions): Promise<void>;
 }
 
@@ -536,7 +542,7 @@ declare class Function_ {
     updateAutoscaler(options: UpdateAutoscalerOptions): Promise<void>;
     /**
      * URL of a Function running as a web endpoint.
-     * @returns The web URL if this function is a web endpoint, otherwise undefined
+     * @returns The web URL if this Function is a web endpoint, otherwise undefined
      */
     getWebUrl(): Promise<string | undefined>;
 }
@@ -627,11 +633,11 @@ declare class AlreadyExistsError extends Error {
 declare class InvalidError extends Error {
     constructor(message: string);
 }
-/** The queue is empty. */
+/** The Queue is empty. */
 declare class QueueEmptyError extends Error {
     constructor(message: string);
 }
-/** The queue is full. */
+/** The Queue is full. */
 declare class QueueFullError extends Error {
     constructor(message: string);
 }
@@ -644,19 +650,19 @@ declare class SandboxTimeoutError extends Error {
 type QueueClearOptions = {
     /** Partition to clear, uses default partition if not set. */
     partition?: string;
-    /** Set to clear all queue partitions. */
+    /** 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). */
+    /** 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). */
+    /** 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;
@@ -678,7 +684,7 @@ type QueueIterateOptions = {
     partition?: string;
 };
 /**
- * Distributed, FIFO queue for data flow in Modal apps.
+ * Distributed, FIFO queue for data flow in Modal Apps.
  */
 declare class Queue {
     #private;
@@ -687,58 +693,58 @@ declare class Queue {
     /** @ignore */
     constructor(queueId: string, name?: string, ephemeralHbManager?: EphemeralHeartbeatManager);
     /**
-     * Create a nameless, temporary queue.
-     * You will need to call `closeEphemeral()` to delete the queue.
+     * 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()`. */
+    /** Delete the ephemeral Queue. Only usable with `Queue.ephemeral()`. */
     closeEphemeral(): void;
     /**
-     * Lookup a queue by name.
+     * Lookup a Queue by name.
      */
     static lookup(name: string, options?: LookupOptions): Promise<Queue>;
-    /** Delete a queue by name. */
+    /** Delete a Queue by name. */
     static delete(name: string, options?: DeleteOptions): Promise<void>;
     /**
-     * Remove all objects from a queue partition.
+     * Remove all objects from a Queue partition.
      */
     clear(options?: QueueClearOptions): Promise<void>;
     /**
-     * Remove and return the next object from the queue.
+     * Remove and return the next object from the Queue.
      *
-     * By default, this will wait until at least one item is present in 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.
+     * 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.
+     * 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.
+     * Add an item to the end of the Queue.
      *
-     * If the queue is full, this will retry with exponential backoff until the
+     * 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.
+     * 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.
+     * Add several items to the end of the Queue.
      *
-     * If the queue is full, this will retry with exponential backoff until the
+     * 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.
+     * 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. */
+    /** Return the number of objects in the Queue. */
     len(options?: QueueLenOptions): Promise<number>;
-    /** Iterate through items in a queue without mutation. */
+    /** Iterate through items in a Queue without mutation. */
     iterate(options?: QueueIterateOptions): AsyncGenerator<any, void, unknown>;
 }
 
-export { AlreadyExistsError, App, type ClientOptions, CloudBucketMount, Cls, type ClsBatchingOptions, type ClsConcurrencyOptions, ClsInstance, type ClsOptions, ContainerProcess, type DeleteOptions, type EphemeralOptions, type ExecOptions, FunctionCall, type FunctionCallCancelOptions, type FunctionCallGetOptions, type FunctionStats, FunctionTimeoutError, Function_, Image, InternalFailure, InvalidError, type LookupOptions, type ModalReadStream, type ModalWriteStream, NotFoundError, Proxy, type ProxyFromNameOptions, Queue, type QueueClearOptions, QueueEmptyError, QueueFullError, type QueueGetOptions, type QueueIterateOptions, type QueueLenOptions, type QueuePutOptions, RemoteError, Retries, Sandbox, type SandboxCreateOptions, SandboxFile, type SandboxFileMode, type SandboxListOptions, SandboxTimeoutError, Secret, type SecretFromNameOptions, type StdioBehavior, type StreamMode, Tunnel, type UpdateAutoscalerOptions, Volume, type VolumeFromNameOptions, initializeClient };
+export { AlreadyExistsError, App, type ClientOptions, CloudBucketMount, Cls, type ClsBatchingOptions, type ClsConcurrencyOptions, ClsInstance, type ClsOptions, ContainerProcess, type DeleteOptions, type EphemeralOptions, type ExecOptions, FunctionCall, type FunctionCallCancelOptions, type FunctionCallGetOptions, type FunctionStats, FunctionTimeoutError, Function_, Image, type ImageDeleteOptions, InternalFailure, InvalidError, type LookupOptions, type ModalReadStream, type ModalWriteStream, NotFoundError, Proxy, type ProxyFromNameOptions, Queue, type QueueClearOptions, QueueEmptyError, QueueFullError, type QueueGetOptions, type QueueIterateOptions, type QueueLenOptions, type QueuePutOptions, RemoteError, Retries, Sandbox, type SandboxCreateOptions, SandboxFile, type SandboxFileMode, type SandboxListOptions, SandboxTimeoutError, Secret, type SecretFromNameOptions, type StdioBehavior, type StreamMode, Tunnel, type UpdateAutoscalerOptions, Volume, type VolumeFromNameOptions, initializeClient };