modal 0.3.5 → 0.3.7

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,59 @@
 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);
 }
 
@@ -42,19 +94,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,86 +142,64 @@ declare class ContainerProcess<R extends string | Uint8Array = any> {
     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>;
 }
 
-declare enum FunctionCallInvocationType {
-    FUNCTION_CALL_INVOCATION_TYPE_UNSPECIFIED = 0,
-    FUNCTION_CALL_INVOCATION_TYPE_SYNC_LEGACY = 1,
-    FUNCTION_CALL_INVOCATION_TYPE_ASYNC_LEGACY = 2,
-    FUNCTION_CALL_INVOCATION_TYPE_ASYNC = 3,
-    FUNCTION_CALL_INVOCATION_TYPE_SYNC = 4,
-    UNRECOGNIZED = -1
-}
-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;
-}
-
+/** Options for `FunctionCall.get()`. */
 type FunctionCallGetOptions = {
     timeout?: number;
 };
+/** Options for `FunctionCall.cancel()`. */
 type FunctionCallCancelOptions = {
     terminateContainers?: boolean;
 };
@@ -166,6 +210,7 @@ type FunctionCallCancelOptions = {
  */
 declare class FunctionCall {
     readonly functionCallId: string;
+    /** @ignore */
     constructor(functionCallId: string);
     /** Create a new function call from ID. */
     fromId(functionCallId: string): FunctionCall;
@@ -177,18 +222,20 @@ declare class FunctionCall {
 
 /** 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>;
-    execFunctionCall(args?: any[], kwargs?: Record<string, any>, invocationType?: FunctionCallInvocationType): Promise<string>;
 }
 
 /** 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. */
@@ -217,5 +264,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, FunctionCall, type FunctionCallCancelOptions, type FunctionCallGetOptions, FunctionTimeoutError, Function_, Image, InternalFailure, type LookupOptions, NotFoundError, RemoteError, Sandbox, type SandboxCreateOptions, type StdioBehavior, type StreamMode };
+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 };

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/app.ts
-import { ClientError as ClientError2, Status as Status2 } from "nice-grpc";
+import { ClientError as ClientError3, Status as Status3 } from "nice-grpc";
 
 // node_modules/@bufbuild/protobuf/dist/esm/wire/varint.js
 function varint64read() {
@@ -37831,11 +37831,12 @@ function getProfile(profileName) {
     );
   }
   const profileData = profileName ? config[profileName] : {};
-  let profile2 = {
+  const profile2 = {
     serverUrl: process.env["MODAL_SERVER_URL"] || profileData.server_url || "https://api.modal.com:443",
     tokenId: process.env["MODAL_TOKEN_ID"] || profileData.token_id,
     tokenSecret: process.env["MODAL_TOKEN_SECRET"] || profileData.token_secret,
-    environment: process.env["MODAL_ENVIRONMENT"] || profileData.environment
+    environment: process.env["MODAL_ENVIRONMENT"] || profileData.environment,
+    imageBuilderVersion: process.env["MODAL_IMAGE_BUILDER_VERSION"] || profileData.imageBuilderVersion
   };
   if (!profile2.tokenId || !profile2.tokenSecret) {
     throw new Error(
@@ -37848,6 +37849,9 @@ var profile = getProfile(process.env["MODAL_PROFILE"] || void 0);
 function environmentName(environment) {
   return environment || profile.environment || "";
 }
+function imageBuilderVersion(version) {
+  return version || profile.imageBuilderVersion || "2024.10";
+}
 
 // src/client.ts
 function authMiddleware(profile2) {
@@ -37975,19 +37979,20 @@ var client = createClientFactory().use(authMiddleware(profile)).use(retryMiddlew
 // src/image.ts
 var Image2 = class {
   imageId;
+  /** @ignore */
   constructor(imageId) {
     this.imageId = imageId;
   }
 };
-async function fromRegistryInternal(appId, tag) {
+async function fromRegistryInternal(appId, tag, imageRegistryConfig) {
   const resp = await client.imageGetOrCreate({
     appId,
     image: {
-      dockerfileCommands: [`FROM ${tag}`]
+      dockerfileCommands: [`FROM ${tag}`],
+      imageRegistryConfig
     },
     namespace: 1 /* DEPLOYMENT_NAMESPACE_WORKSPACE */,
-    builderVersion: "2024.10"
-    // TODO: make this configurable
+    builderVersion: imageBuilderVersion()
   });
   let result;
   let metadata = void 0;
@@ -38013,6 +38018,7 @@ async function fromRegistryInternal(appId, tag) {
     }
     result = resultJoined;
   }
+  void metadata;
   if (result.status === 2 /* GENERIC_STATUS_FAILURE */) {
     throw new Error(
       `Image build for ${resp.imageId} failed with the exception:
@@ -38151,6 +38157,7 @@ var Sandbox2 = class {
   stdout;
   stderr;
   #taskId;
+  /** @ignore */
   constructor(sandboxId) {
     this.sandboxId = sandboxId;
     this.stdin = toModalWriteStream(inputStreamSb(sandboxId));
@@ -38381,10 +38388,57 @@ var NotFoundError = class extends Error {
     this.name = "NotFoundError";
   }
 };
+var InvalidError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "InvalidError";
+  }
+};
+var QueueEmptyError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "QueueEmptyError";
+  }
+};
+var QueueFullError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "QueueFullError";
+  }
+};
+
+// src/secret.ts
+import { ClientError as ClientError2, Status as Status2 } from "nice-grpc";
+var Secret = class _Secret {
+  secretId;
+  /** @ignore */
+  constructor(secretId) {
+    this.secretId = secretId;
+  }
+  /** Reference a Secret by its name. */
+  static async fromName(name, options) {
+    try {
+      const resp = await client.secretGetOrCreate({
+        deploymentName: name,
+        namespace: 1 /* DEPLOYMENT_NAMESPACE_WORKSPACE */,
+        environmentName: environmentName(options?.environment),
+        requiredKeys: options?.requiredKeys ?? []
+      });
+      return new _Secret(resp.secretId);
+    } catch (err) {
+      if (err instanceof ClientError2 && err.code === Status2.NOT_FOUND)
+        throw new NotFoundError(err.details);
+      if (err instanceof ClientError2 && err.code === Status2.FAILED_PRECONDITION && err.details.includes("Secret is missing key"))
+        throw new NotFoundError(err.details);
+      throw err;
+    }
+  }
+};
 
 // src/app.ts
 var App = class _App {
   appId;
+  /** @ignore */
   constructor(appId) {
     this.appId = appId;
   }
@@ -38398,7 +38452,7 @@ var App = class _App {
       });
       return new _App(resp.appId);
     } catch (err) {
-      if (err instanceof ClientError2 && err.code === Status2.NOT_FOUND)
+      if (err instanceof ClientError3 && err.code === Status3.NOT_FOUND)
         throw new NotFoundError(`App '${name}' not found`);
       throw err;
     }
@@ -38431,10 +38485,22 @@ var App = class _App {
   async imageFromRegistry(tag) {
     return await fromRegistryInternal(this.appId, tag);
   }
+  async imageFromAwsEcr(tag, secret) {
+    if (!(secret instanceof Secret)) {
+      throw new TypeError(
+        "secret must be a reference to an existing Secret, e.g. `await Secret.fromName('my_secret')`"
+      );
+    }
+    const imageRegistryConfig = {
+      registryAuthType: 1 /* REGISTRY_AUTH_TYPE_AWS */,
+      secretId: secret.secretId
+    };
+    return await fromRegistryInternal(this.appId, tag, imageRegistryConfig);
+  }
 };
 
 // src/cls.ts
-import { ClientError as ClientError4, Status as Status4 } from "nice-grpc";
+import { ClientError as ClientError5, Status as Status5 } from "nice-grpc";
 
 // src/function.ts
 import { createHash } from "node:crypto";
@@ -38442,6 +38508,7 @@ import { createHash } from "node:crypto";
 // src/function_call.ts
 var FunctionCall = class _FunctionCall {
   functionCallId;
+  /** @ignore */
   constructor(functionCallId) {
     this.functionCallId = functionCallId;
   }
@@ -38525,6 +38592,15 @@ var Reader = class {
     const hi = this.uint32LE() >>> 0;
     return hi * 2 ** 32 + lo;
   }
+  int32LE() {
+    const v = new DataView(
+      this.buf.buffer,
+      this.buf.byteOffset + this.pos,
+      4
+    ).getInt32(0, true);
+    this.pos += 4;
+    return v;
+  }
   float64BE() {
     const v = new DataView(
       this.buf.buffer,
@@ -38570,7 +38646,7 @@ function encodeValue(val, w, proto) {
       w.byte(140 /* SHORT_BINUNICODE */);
       w.byte(utf8.length);
     } else if (proto >= 4 && utf8.length > 4294967295) {
-      w.byte(138 /* BINUNICODE8 */);
+      w.byte(141 /* BINUNICODE8 */);
       w.uint64LE(utf8.length);
     } else {
       w.byte(88 /* BINUNICODE */);
@@ -38583,10 +38659,10 @@ function encodeValue(val, w, proto) {
   if (val instanceof Uint8Array) {
     const len = val.length;
     if (proto >= 4 && len < 256) {
-      w.byte(142 /* SHORT_BINBYTES */);
+      w.byte(67 /* SHORT_BINBYTES */);
       w.byte(len);
     } else if (proto >= 4 && len > 4294967295) {
-      w.byte(141 /* BINBYTES8 */);
+      w.byte(142 /* BINBYTES8 */);
       w.uint64LE(len);
     } else {
       w.byte(66 /* BINBYTES */);
@@ -38657,6 +38733,7 @@ function loads(buf) {
     const size = r.uint64LE();
     void size;
   }
+  const MARK = Symbol("pickle-mark");
   while (!r.eof()) {
     const op = r.byte();
     switch (op) {
@@ -38681,8 +38758,7 @@ function loads(buf) {
         break;
       }
       case 74 /* BININT4 */: {
-        const n = r.uint32LE();
-        push(n >>> 31 ? n - 4294967296 : n);
+        push(r.int32LE());
         break;
       }
       case 71 /* BINFLOAT */:
@@ -38698,12 +38774,12 @@ function loads(buf) {
         push(tdec.decode(r.take(n)));
         break;
       }
-      case 138 /* BINUNICODE8 */: {
+      case 141 /* BINUNICODE8 */: {
         const n = r.uint64LE();
         push(tdec.decode(r.take(n)));
         break;
       }
-      case 142 /* SHORT_BINBYTES */: {
+      case 67 /* SHORT_BINBYTES */: {
         const n = r.byte();
         push(r.take(n));
         break;
@@ -38713,7 +38789,7 @@ function loads(buf) {
         push(r.take(n));
         break;
       }
-      case 141 /* BINBYTES8 */: {
+      case 142 /* BINBYTES8 */: {
         const n = r.uint64LE();
         push(r.take(n));
         break;
@@ -38757,6 +38833,43 @@ function loads(buf) {
         const _size = r.uint64LE();
         break;
       }
+      case 40 /* MARK */:
+        push(MARK);
+        break;
+      case 101 /* APPENDS */: {
+        const markIndex = stack.lastIndexOf(MARK);
+        if (markIndex === -1) {
+          throw new PickleError("APPENDS without MARK");
+        }
+        const lst = stack[markIndex - 1];
+        if (!Array.isArray(lst)) {
+          throw new PickleError("APPENDS expects a list below MARK");
+        }
+        const items = stack.slice(markIndex + 1);
+        lst.push(...items);
+        stack.length = markIndex - 1;
+        push(lst);
+        break;
+      }
+      case 117 /* SETITEMS */: {
+        const markIndex = stack.lastIndexOf(MARK);
+        if (markIndex === -1) {
+          throw new PickleError("SETITEMS without MARK");
+        }
+        const d = stack[markIndex - 1];
+        if (typeof d !== "object" || d === null || Array.isArray(d)) {
+          throw new PickleError("SETITEMS expects a dict below MARK");
+        }
+        const items = stack.slice(markIndex + 1);
+        for (let i = 0; i < items.length; i += 2) {
+          if (i + 1 < items.length) {
+            d[items[i]] = items[i + 1];
+          }
+        }
+        stack.length = markIndex - 1;
+        push(d);
+        break;
+      }
       default:
         throw new PickleError(`Unsupported opcode 0x${op.toString(16)}`);
     }
@@ -38765,7 +38878,7 @@ function loads(buf) {
 }
 
 // src/function.ts
-import { ClientError as ClientError3, Status as Status3 } from "nice-grpc";
+import { ClientError as ClientError4, Status as Status4 } from "nice-grpc";
 var maxObjectSizeBytes = 2 * 1024 * 1024;
 var outputsTimeout = 55 * 1e3;
 function timeNowSeconds() {
@@ -38774,6 +38887,7 @@ function timeNowSeconds() {
 var Function_ = class _Function_ {
   functionId;
   methodName;
+  /** @ignore */
   constructor(functionId, methodName) {
     this.functionId = functionId;
     this.methodName = methodName;
@@ -38788,14 +38902,14 @@ var Function_ = class _Function_ {
       });
       return new _Function_(resp.functionId);
     } catch (err) {
-      if (err instanceof ClientError3 && err.code === Status3.NOT_FOUND)
+      if (err instanceof ClientError4 && err.code === Status4.NOT_FOUND)
         throw new NotFoundError(`Function '${appName}/${name}' not found`);
       throw err;
     }
   }
   // Execute a single input into a remote Function.
   async remote(args = [], kwargs = {}) {
-    const functionCallId = await this.execFunctionCall(
+    const functionCallId = await this.#execFunctionCall(
       args,
       kwargs,
       4 /* FUNCTION_CALL_INVOCATION_TYPE_SYNC */
@@ -38804,14 +38918,14 @@ var Function_ = class _Function_ {
   }
   // Spawn a single input into a remote function.
   async spawn(args = [], kwargs = {}) {
-    const functionCallId = await this.execFunctionCall(
+    const functionCallId = await this.#execFunctionCall(
       args,
       kwargs,
       4 /* FUNCTION_CALL_INVOCATION_TYPE_SYNC */
     );
     return new FunctionCall(functionCallId);
   }
-  async execFunctionCall(args = [], kwargs = {}, invocationType = 4 /* FUNCTION_CALL_INVOCATION_TYPE_SYNC */) {
+  async #execFunctionCall(args = [], kwargs = {}, invocationType = 4 /* FUNCTION_CALL_INVOCATION_TYPE_SYNC */) {
     const payload = dumps([args, kwargs]);
     let argsBlobId = void 0;
     if (payload.length > maxObjectSizeBytes) {
@@ -38952,6 +39066,7 @@ var Cls = class _Cls {
   #serviceFunctionId;
   #schema;
   #methodNames;
+  /** @ignore */
   constructor(serviceFunctionId, schema, methodNames) {
     this.#serviceFunctionId = serviceFunctionId;
     this.#schema = schema;
@@ -38985,7 +39100,7 @@ var Cls = class _Cls {
       }
       return new _Cls(serviceFunction.functionId, schema, methodNames);
     } catch (err) {
-      if (err instanceof ClientError4 && err.code === Status4.NOT_FOUND)
+      if (err instanceof ClientError5 && err.code === Status5.NOT_FOUND)
         throw new NotFoundError(`Class '${appName}/${name}' not found`);
       throw err;
     }
@@ -39082,16 +39197,269 @@ var ClsInstance = class {
     return method;
   }
 };
+
+// src/queue.ts
+import { ClientError as ClientError6, Status as Status6 } from "nice-grpc";
+var ephemeralObjectHeartbeatSleep = 3e5;
+var queueInitialPutBackoff = 100;
+var queueDefaultPartitionTtl = 24 * 3600 * 1e3;
+var Queue = class _Queue {
+  queueId;
+  #ephemeral;
+  #abortController;
+  /** @ignore */
+  constructor(queueId, ephemeral = false) {
+    this.queueId = queueId;
+    this.#ephemeral = ephemeral;
+    this.#abortController = ephemeral ? new AbortController() : void 0;
+  }
+  static #validatePartitionKey(partition) {
+    if (partition) {
+      const partitionKey = new TextEncoder().encode(partition);
+      if (partitionKey.length === 0 || partitionKey.length > 64) {
+        throw new InvalidError(
+          "Queue partition key must be between 1 and 64 bytes."
+        );
+      }
+      return partitionKey;
+    }
+    return new Uint8Array();
+  }
+  /**
+   * Create a nameless, temporary queue.
+   * You will need to call `closeEphemeral()` to delete the queue.
+   */
+  static async ephemeral(options = {}) {
+    const resp = await client.queueGetOrCreate({
+      objectCreationType: 5 /* OBJECT_CREATION_TYPE_EPHEMERAL */,
+      environmentName: environmentName(options.environment)
+    });
+    const queue = new _Queue(resp.queueId, true);
+    const signal = queue.#abortController.signal;
+    (async () => {
+      while (true) {
+        await client.queueHeartbeat({ queueId: resp.queueId });
+        await Promise.race([
+          new Promise(
+            (resolve) => setTimeout(resolve, ephemeralObjectHeartbeatSleep)
+          ),
+          new Promise((resolve) => {
+            signal.addEventListener("abort", resolve, { once: true });
+          })
+        ]);
+      }
+    })();
+    return queue;
+  }
+  /** Delete the ephemeral queue. Only usable with `Queue.ephemeral()`. */
+  closeEphemeral() {
+    if (this.#ephemeral) {
+      this.#abortController.abort();
+    } else {
+      throw new InvalidError("Queue is not ephemeral.");
+    }
+  }
+  /**
+   * Lookup a queue by name.
+   */
+  static async lookup(name, options = {}) {
+    const resp = await client.queueGetOrCreate({
+      deploymentName: name,
+      objectCreationType: options.createIfMissing ? 1 /* OBJECT_CREATION_TYPE_CREATE_IF_MISSING */ : void 0,
+      namespace: 1 /* DEPLOYMENT_NAMESPACE_WORKSPACE */,
+      environmentName: environmentName(options.environment)
+    });
+    return new _Queue(resp.queueId);
+  }
+  /** Delete a queue by name. */
+  static async delete(name, options = {}) {
+    const queue = await _Queue.lookup(name, options);
+    await client.queueDelete({ queueId: queue.queueId });
+  }
+  /**
+   * Remove all objects from a queue partition.
+   */
+  async clear(options = {}) {
+    if (options.partition && options.all) {
+      throw new InvalidError(
+        "Partition must be null when requesting to clear all."
+      );
+    }
+    await client.queueClear({
+      queueId: this.queueId,
+      partitionKey: _Queue.#validatePartitionKey(options.partition),
+      allPartitions: options.all
+    });
+  }
+  async #get(n, partition, timeout) {
+    const partitionKey = _Queue.#validatePartitionKey(partition);
+    const startTime = Date.now();
+    let pollTimeout = 5e4;
+    if (timeout !== void 0) {
+      pollTimeout = Math.min(pollTimeout, timeout);
+    }
+    while (true) {
+      const response = await client.queueGet({
+        queueId: this.queueId,
+        partitionKey,
+        timeout: pollTimeout / 1e3,
+        nValues: n
+      });
+      if (response.values && response.values.length > 0) {
+        return response.values.map((value) => loads(value));
+      }
+      if (timeout !== void 0) {
+        const remaining = timeout - (Date.now() - startTime);
+        if (remaining <= 0) {
+          const message = `Queue ${this.queueId} did not return values within ${timeout}ms.`;
+          throw new QueueEmptyError(message);
+        }
+        pollTimeout = Math.min(pollTimeout, remaining);
+      }
+    }
+  }
+  /**
+   * 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.
+   */
+  async get(options = {}) {
+    const values = await this.#get(1, options.partition, options.timeout);
+    return values[0];
+  }
+  /**
+   * 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.
+   */
+  async getMany(n, options = {}) {
+    return await this.#get(n, options.partition, options.timeout);
+  }
+  async #put(values, timeout, partition, partitionTtl) {
+    const valuesEncoded = values.map((v) => dumps(v));
+    const partitionKey = _Queue.#validatePartitionKey(partition);
+    let delay = queueInitialPutBackoff;
+    const deadline = timeout ? Date.now() + timeout : void 0;
+    while (true) {
+      try {
+        await client.queuePut({
+          queueId: this.queueId,
+          values: valuesEncoded,
+          partitionKey,
+          partitionTtlSeconds: (partitionTtl || queueDefaultPartitionTtl) / 1e3
+        });
+        break;
+      } catch (e) {
+        if (e instanceof ClientError6 && e.code === Status6.RESOURCE_EXHAUSTED) {
+          delay = Math.min(delay * 2, 3e4);
+          if (deadline !== void 0) {
+            const remaining = deadline - Date.now();
+            if (remaining <= 0)
+              throw new QueueFullError(`Put failed on ${this.queueId}.`);
+            delay = Math.min(delay, remaining);
+          }
+          await new Promise((resolve) => setTimeout(resolve, delay));
+        } else {
+          throw e;
+        }
+      }
+    }
+  }
+  /**
+   * 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.
+   */
+  async put(v, options = {}) {
+    await this.#put(
+      [v],
+      options.timeout,
+      options.partition,
+      options.partitionTtl
+    );
+  }
+  /**
+   * 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.
+   */
+  async putMany(values, options = {}) {
+    await this.#put(
+      values,
+      options.timeout,
+      options.partition,
+      options.partitionTtl
+    );
+  }
+  /** Return the number of objects in the queue. */
+  async len(options = {}) {
+    if (options.partition && options.total) {
+      throw new InvalidError(
+        "Partition must be null when requesting total length."
+      );
+    }
+    const resp = await client.queueLen({
+      queueId: this.queueId,
+      partitionKey: _Queue.#validatePartitionKey(options.partition),
+      total: options.total
+    });
+    return resp.len;
+  }
+  /** Iterate through items in a queue without mutation. */
+  async *iterate(options = {}) {
+    const { partition, itemPollTimeout = 0 } = options;
+    let lastEntryId = void 0;
+    const validatedPartitionKey = _Queue.#validatePartitionKey(partition);
+    let fetchDeadline = Date.now() + itemPollTimeout;
+    const maxPollDuration = 3e4;
+    while (true) {
+      const pollDuration = Math.max(
+        0,
+        Math.min(maxPollDuration, fetchDeadline - Date.now())
+      );
+      const request = {
+        queueId: this.queueId,
+        partitionKey: validatedPartitionKey,
+        itemPollTimeout: pollDuration / 1e3,
+        lastEntryId: lastEntryId || ""
+      };
+      const response = await client.queueNextItems(request);
+      if (response.items && response.items.length > 0) {
+        for (const item of response.items) {
+          yield loads(item.value);
+          lastEntryId = item.entryId;
+        }
+        fetchDeadline = Date.now() + itemPollTimeout;
+      } else if (Date.now() > fetchDeadline) {
+        break;
+      }
+    }
+  }
+};
 export {
   App,
   Cls,
   ClsInstance,
+  ContainerProcess,
   FunctionCall,
   FunctionTimeoutError,
   Function_,
   Image2 as Image,
   InternalFailure,
+  InvalidError,
   NotFoundError,
+  Queue,
+  QueueEmptyError,
+  QueueFullError,
   RemoteError,
-  Sandbox2 as Sandbox
+  Sandbox2 as Sandbox,
+  Secret
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "modal",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "description": "Modal client library for JavaScript",
   "license": "MIT",
   "homepage": "https://modal.com/docs",
@@ -23,10 +23,16 @@
   "scripts": {
     "build": "tsup",
     "check": "tsc",
+    "docs": "typedoc src/index.ts --treatWarningsAsErrors",
+    "docs:serve": "npm run docs && http-server ./docs",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
+    "lint": "eslint",
     "prepare": "scripts/gen-proto.sh",
-    "test": "vitest"
+    "test": "vitest",
+    "preversion": "(git update-index --really-refresh && git diff-index --quiet HEAD) || (echo 'You must commit all changes before running npm version' && exit 1)",
+    "version": "npm run build && git add package.json package-lock.json && git commit -m \"modal-js/v$npm_package_version\" && git tag modal-js/v$npm_package_version",
+    "postversion": "git push && git push --tags && npm publish"
   },
   "dependencies": {
     "long": "^5.3.1",
@@ -36,14 +42,20 @@
     "uuid": "^11.1.0"
   },
   "devDependencies": {
+    "@eslint/js": "^9.28.0",
     "@types/node": "^22.15.2",
+    "eslint": "^9.28.0",
+    "globals": "^16.2.0",
     "grpc-tools": "^1.13.0",
+    "http-server": "^14.1.1",
     "p-queue": "^8.1.0",
     "prettier": "^3.5.3",
     "ts-proto": "^2.7.0",
     "tsup": "^8.4.0",
     "tsx": "^4.19.3",
+    "typedoc": "^0.28.5",
     "typescript": "~5.8.3",
+    "typescript-eslint": "^8.33.1",
     "vitest": "^3.1.2"
   }
 }