modal 0.3.1 → 0.3.3

package/README.md

@@ -1,19 +1,25 @@
-# modal-js development
+# Modal JavaScript Library
 
-Setup after cloning the repo with submodules:
+[![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)
 
-```bash
-npm install
-```
+The [Modal](https://modal.com/) JavaScript SDK allows you to run Modal Functions and Sandboxes from server-side JavaScript applications.
 
-Then run a script with:
+It comes with built-in TypeScript type definitions.
 
-```bash
-node --import tsx path/to/script.ts
-```
+## Documentation
+
+See the [documentation and examples](https://github.com/modal-labs/libmodal?tab=readme-ov-file#javascript-modal-js) on GitHub.
 
-## gRPC support
+## Requirements
 
-We're using `nice-grpc` because the `@grpc/grpc-js` library doesn't support promises and is difficult to customize with types.
+Node 22 or higher, in [ES modules](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c) mode.
 
-This gRPC library depends on the `protobuf-ts` package, which is not compatible with tree shaking because `ModalClientDefinition` transitively references every type. However, since `modal-js` is a server-side package, having a larger bundled library is not a huge issue.
+## Installation
+
+Install the package with
+
+```bash
+npm install modal
+```

package/dist/index.d.ts

@@ -93,4 +93,25 @@ declare class App {
     imageFromRegistry(tag: string): Promise<Image>;
 }
 
-export { App, Image, type LookupOptions, Sandbox, type SandboxCreateOptions, type StdioBehavior, type StreamMode };
+/** Function execution exceeds the allowed time limit. */
+declare class TimeoutError 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);
+}
+
+/** Represents a deployed Modal Function, which can be invoked remotely. */
+declare class Function_ {
+    readonly functionId: string;
+    constructor(functionId: string);
+    static lookup(appName: string, name: string, options?: LookupOptions): Promise<Function_>;
+    remote(args?: any[], kwargs?: Record<string, any>): Promise<any>;
+}
+
+export { App, Function_, Image, InternalFailure, type LookupOptions, RemoteError, Sandbox, type SandboxCreateOptions, type StdioBehavior, type StreamMode, TimeoutError };

package/dist/index.js

@@ -20247,6 +20247,57 @@ var GPUConfig = {
     return message;
   }
 };
+function createBaseGeneratorDone() {
+  return { itemsTotal: 0 };
+}
+var GeneratorDone = {
+  encode(message, writer = new BinaryWriter()) {
+    if (message.itemsTotal !== 0) {
+      writer.uint32(8).uint64(message.itemsTotal);
+    }
+    return writer;
+  },
+  decode(input, length) {
+    const reader = input instanceof BinaryReader ? input : new BinaryReader(input);
+    let end = length === void 0 ? reader.len : reader.pos + length;
+    const message = createBaseGeneratorDone();
+    while (reader.pos < end) {
+      const tag = reader.uint32();
+      switch (tag >>> 3) {
+        case 1: {
+          if (tag !== 8) {
+            break;
+          }
+          message.itemsTotal = longToNumber(reader.uint64());
+          continue;
+        }
+      }
+      if ((tag & 7) === 4 || tag === 0) {
+        break;
+      }
+      reader.skip(tag & 7);
+    }
+    return message;
+  },
+  fromJSON(object) {
+    return { itemsTotal: isSet3(object.itemsTotal) ? globalThis.Number(object.itemsTotal) : 0 };
+  },
+  toJSON(message) {
+    const obj = {};
+    if (message.itemsTotal !== 0) {
+      obj.itemsTotal = Math.round(message.itemsTotal);
+    }
+    return obj;
+  },
+  create(base) {
+    return GeneratorDone.fromPartial(base ?? {});
+  },
+  fromPartial(object) {
+    const message = createBaseGeneratorDone();
+    message.itemsTotal = object.itemsTotal ?? 0;
+    return message;
+  }
+};
 function createBaseGenericPayloadType() {
   return { baseType: 0, subTypes: [] };
 }
@@ -37167,8 +37218,469 @@ var App = class _App {
     return await fromRegistryInternal(this.appId, tag);
   }
 };
+
+// src/errors.ts
+var TimeoutError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "TimeoutError";
+  }
+};
+var RemoteError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "RemoteError";
+  }
+};
+var InternalFailure = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "InternalFailure";
+  }
+};
+
+// src/function.ts
+import { createHash } from "node:crypto";
+
+// src/pickle.ts
+var PickleError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "PickleError";
+  }
+};
+var Writer = class {
+  out = [];
+  byte(b) {
+    this.out.push(b & 255);
+  }
+  bytes(arr) {
+    for (const b of arr) this.byte(b);
+  }
+  uint32LE(x) {
+    this.byte(x);
+    this.byte(x >>> 8);
+    this.byte(x >>> 16);
+    this.byte(x >>> 24);
+  }
+  uint64LE(n) {
+    let v = BigInt(n);
+    for (let i = 0; i < 8; i++) {
+      this.byte(Number(v & 0xffn));
+      v >>= 8n;
+    }
+  }
+  float64BE(v) {
+    const dv = new DataView(new ArrayBuffer(8));
+    dv.setFloat64(0, v, false);
+    this.bytes(new Uint8Array(dv.buffer));
+  }
+  toUint8() {
+    return new Uint8Array(this.out);
+  }
+};
+var Reader = class {
+  constructor(buf, pos = 0) {
+    this.buf = buf;
+    this.pos = pos;
+  }
+  eof() {
+    return this.pos >= this.buf.length;
+  }
+  byte() {
+    return this.buf[this.pos++];
+  }
+  take(n) {
+    const s = this.buf.subarray(this.pos, this.pos + n);
+    this.pos += n;
+    return s;
+  }
+  uint32LE() {
+    const b0 = this.byte(), b1 = this.byte(), b2 = this.byte(), b3 = this.byte();
+    return b0 | b1 << 8 | b2 << 16 | b3 << 24;
+  }
+  uint64LE() {
+    const lo = this.uint32LE() >>> 0;
+    const hi = this.uint32LE() >>> 0;
+    return hi * 2 ** 32 + lo;
+  }
+  float64BE() {
+    const v = new DataView(
+      this.buf.buffer,
+      this.buf.byteOffset + this.pos,
+      8
+    ).getFloat64(0, false);
+    this.pos += 8;
+    return v;
+  }
+};
+function encodeValue(val, w, proto) {
+  if (val === null || val === void 0) {
+    w.byte(78 /* NONE */);
+    return;
+  }
+  if (typeof val === "boolean") {
+    w.byte(val ? 136 /* NEWTRUE */ : 137 /* NEWFALSE */);
+    return;
+  }
+  if (typeof val === "number") {
+    if (Number.isInteger(val)) {
+      if (val >= 0 && val <= 255) {
+        w.byte(75 /* BININT1 */);
+        w.byte(val);
+      } else if (val >= -32768 && val <= 32767) {
+        w.byte(77 /* BININT2 */);
+        w.byte(val & 255);
+        w.byte(val >> 8 & 255);
+      } else {
+        w.byte(74 /* BININT4 */);
+        w.uint32LE(val >>> 0);
+      }
+    } else {
+      w.byte(71 /* BINFLOAT */);
+      w.float64BE(val);
+    }
+    maybeMemoize(w, proto);
+    return;
+  }
+  if (typeof val === "string") {
+    const utf8 = new TextEncoder().encode(val);
+    if (proto >= 4 && utf8.length < 256) {
+      w.byte(140 /* SHORT_BINUNICODE */);
+      w.byte(utf8.length);
+    } else if (proto >= 4 && utf8.length > 4294967295) {
+      w.byte(138 /* BINUNICODE8 */);
+      w.uint64LE(utf8.length);
+    } else {
+      w.byte(88 /* BINUNICODE */);
+      w.uint32LE(utf8.length);
+    }
+    w.bytes(utf8);
+    maybeMemoize(w, proto);
+    return;
+  }
+  if (val instanceof Uint8Array) {
+    const len = val.length;
+    if (proto >= 4 && len < 256) {
+      w.byte(142 /* SHORT_BINBYTES */);
+      w.byte(len);
+    } else if (proto >= 4 && len > 4294967295) {
+      w.byte(141 /* BINBYTES8 */);
+      w.uint64LE(len);
+    } else {
+      w.byte(66 /* BINBYTES */);
+      w.uint32LE(len);
+    }
+    w.bytes(val);
+    maybeMemoize(w, proto);
+    return;
+  }
+  if (Array.isArray(val)) {
+    w.byte(93 /* EMPTY_LIST */);
+    maybeMemoize(w, proto);
+    for (const item of val) {
+      encodeValue(item, w, proto);
+      w.byte(97 /* APPEND */);
+    }
+    return;
+  }
+  if (typeof val === "object") {
+    w.byte(125 /* EMPTY_DICT */);
+    maybeMemoize(w, proto);
+    for (const [k, v] of Object.entries(val)) {
+      encodeValue(k, w, proto);
+      encodeValue(v, w, proto);
+      w.byte(115 /* SETITEM */);
+    }
+    return;
+  }
+  throw new PickleError(`Unsupported type in dumps(): ${typeof val}`);
+}
+function maybeMemoize(w, proto) {
+  if (proto >= 4) {
+    w.byte(148 /* MEMOIZE */);
+  }
+}
+function dumps(obj, protocol = 4) {
+  if (![3, 4, 5].includes(protocol))
+    throw new PickleError("Protocol must be 3, 4, or 5");
+  const w = new Writer();
+  w.byte(128 /* PROTO */);
+  w.byte(protocol);
+  if (protocol === 5) {
+    w.byte(149 /* FRAME */);
+    w.uint64LE(0);
+  }
+  encodeValue(obj, w, protocol);
+  w.byte(46 /* STOP */);
+  return w.toUint8();
+}
+function loads(buf) {
+  const r = new Reader(buf);
+  const op0 = r.byte();
+  if (op0 !== 128 /* PROTO */) throw new PickleError("pickle missing PROTO header");
+  const proto = r.byte();
+  if (!(proto === 3 || proto === 4 || proto === 5))
+    throw new PickleError(`Unsupported protocol ${proto}`);
+  const stack = [];
+  const memo = [];
+  const tdec = new TextDecoder();
+  function push(v) {
+    stack.push(v);
+  }
+  function pop() {
+    return stack.pop();
+  }
+  if (proto === 5 && buf[r["pos"]] === 149 /* FRAME */) {
+    r.byte();
+    const size = r.uint64LE();
+    void size;
+  }
+  while (!r.eof()) {
+    const op = r.byte();
+    switch (op) {
+      case 46 /* STOP */:
+        return stack.pop();
+      case 78 /* NONE */:
+        push(null);
+        break;
+      case 136 /* NEWTRUE */:
+        push(true);
+        break;
+      case 137 /* NEWFALSE */:
+        push(false);
+        break;
+      case 75 /* BININT1 */:
+        push(r.byte());
+        break;
+      case 77 /* BININT2 */: {
+        const lo = r.byte(), hi = r.byte();
+        const n = hi << 8 | lo;
+        push(n & 32768 ? n - 65536 : n);
+        break;
+      }
+      case 74 /* BININT4 */: {
+        const n = r.uint32LE();
+        push(n >>> 31 ? n - 4294967296 : n);
+        break;
+      }
+      case 71 /* BINFLOAT */:
+        push(r.float64BE());
+        break;
+      case 140 /* SHORT_BINUNICODE */: {
+        const n = r.byte();
+        push(tdec.decode(r.take(n)));
+        break;
+      }
+      case 88 /* BINUNICODE */: {
+        const n = r.uint32LE();
+        push(tdec.decode(r.take(n)));
+        break;
+      }
+      case 138 /* BINUNICODE8 */: {
+        const n = r.uint64LE();
+        push(tdec.decode(r.take(n)));
+        break;
+      }
+      case 142 /* SHORT_BINBYTES */: {
+        const n = r.byte();
+        push(r.take(n));
+        break;
+      }
+      case 66 /* BINBYTES */: {
+        const n = r.uint32LE();
+        push(r.take(n));
+        break;
+      }
+      case 141 /* BINBYTES8 */: {
+        const n = r.uint64LE();
+        push(r.take(n));
+        break;
+      }
+      case 93 /* EMPTY_LIST */:
+        push([]);
+        break;
+      case 97 /* APPEND */: {
+        const v = pop();
+        const lst = pop();
+        lst.push(v);
+        push(lst);
+        break;
+      }
+      case 125 /* EMPTY_DICT */:
+        push({});
+        break;
+      case 115 /* SETITEM */: {
+        const v = pop(), k = pop(), d = pop();
+        d[k] = v;
+        push(d);
+        break;
+      }
+      // Memo handling ----------------------------------------
+      case 148 /* MEMOIZE */:
+        memo.push(stack[stack.length - 1]);
+        break;
+      case 113 /* BINPUT */:
+        memo[r.byte()] = stack[stack.length - 1];
+        break;
+      case 114 /* LONG_BINPUT */:
+        memo[r.uint32LE()] = stack[stack.length - 1];
+        break;
+      case 104 /* BINGET */:
+        push(memo[r.byte()]);
+        break;
+      case 106 /* LONG_BINGET */:
+        push(memo[r.uint32LE()]);
+        break;
+      case 149 /* FRAME */: {
+        const _size = r.uint64LE();
+        break;
+      }
+      default:
+        throw new PickleError(`Unsupported opcode 0x${op.toString(16)}`);
+    }
+  }
+  throw new PickleError("pickle stream ended without STOP");
+}
+
+// src/function.ts
+var maxObjectSizeBytes = 2 * 1024 * 1024;
+function timeNow() {
+  return Date.now() / 1e3;
+}
+var Function_ = class _Function_ {
+  functionId;
+  constructor(functionId) {
+    this.functionId = functionId;
+  }
+  static async lookup(appName, name, options = {}) {
+    const resp = await client.functionGet({
+      appName,
+      objectTag: name,
+      namespace: 1 /* DEPLOYMENT_NAMESPACE_WORKSPACE */,
+      environmentName: environmentName(options.environment)
+    });
+    return new _Function_(resp.functionId);
+  }
+  // Execute a single input into a remote Function.
+  async remote(args = [], kwargs = {}) {
+    const payload = dumps([args, kwargs]);
+    let argsBlobId = void 0;
+    if (payload.length > maxObjectSizeBytes) {
+      argsBlobId = await blobUpload(payload);
+    }
+    const functionMapResponse = await client.functionMap({
+      functionId: this.functionId,
+      functionCallType: 1 /* FUNCTION_CALL_TYPE_UNARY */,
+      functionCallInvocationType: 4 /* FUNCTION_CALL_INVOCATION_TYPE_SYNC */,
+      pipelinedInputs: [
+        {
+          idx: 0,
+          input: {
+            args: argsBlobId ? void 0 : payload,
+            argsBlobId,
+            dataFormat: 1 /* DATA_FORMAT_PICKLE */
+          }
+        }
+      ]
+    });
+    while (true) {
+      const response = await client.functionGetOutputs({
+        functionCallId: functionMapResponse.functionCallId,
+        maxValues: 1,
+        timeout: 55,
+        lastEntryId: "0-0",
+        clearOnSuccess: true,
+        requestedAt: timeNow()
+      });
+      const outputs = response.outputs;
+      if (outputs.length > 0) {
+        return await processResult(outputs[0].result, outputs[0].dataFormat);
+      }
+    }
+  }
+};
+async function processResult(result, dataFormat) {
+  if (!result) {
+    throw new Error("Received null result from invocation");
+  }
+  let data = new Uint8Array();
+  if (result.data !== void 0) {
+    data = result.data;
+  } else if (result.dataBlobId) {
+    data = await blobDownload(result.dataBlobId);
+  }
+  switch (result.status) {
+    case 4 /* GENERIC_STATUS_TIMEOUT */:
+      throw new TimeoutError(`Timeout: ${result.exception}`);
+    case 6 /* GENERIC_STATUS_INTERNAL_FAILURE */:
+      throw new InternalFailure(`Internal failure: ${result.exception}`);
+    case 1 /* GENERIC_STATUS_SUCCESS */:
+      break;
+    default:
+      throw new RemoteError(`Remote error: ${result.exception}`);
+  }
+  return deserializeDataFormat(data, dataFormat);
+}
+async function blobUpload(data) {
+  const contentMd5 = createHash("md5").update(data).digest("base64");
+  const contentSha256 = createHash("sha256").update(data).digest("base64");
+  const resp = await client.blobCreate({
+    contentMd5,
+    contentSha256Base64: contentSha256,
+    contentLength: data.length
+  });
+  if (resp.multipart) {
+    throw new Error(
+      "Function input size exceeds multipart upload threshold, unsupported by this SDK version"
+    );
+  } else if (resp.uploadUrl) {
+    const uploadResp = await fetch(resp.uploadUrl, {
+      method: "PUT",
+      headers: {
+        "Content-Type": "application/octet-stream",
+        "Content-MD5": contentMd5
+      },
+      body: data
+    });
+    if (uploadResp.status < 200 || uploadResp.status >= 300) {
+      throw new Error(`Failed blob upload: ${uploadResp.statusText}`);
+    }
+    return resp.blobId;
+  } else {
+    throw new Error("Missing upload URL in BlobCreate response");
+  }
+}
+async function blobDownload(blobId) {
+  const resp = await client.blobGet({ blobId });
+  const s3resp = await fetch(resp.downloadUrl);
+  if (!s3resp.ok) {
+    throw new Error(`Failed to download blob: ${s3resp.statusText}`);
+  }
+  const buf = await s3resp.arrayBuffer();
+  return new Uint8Array(buf);
+}
+function deserializeDataFormat(data, dataFormat) {
+  if (!data) {
+    return null;
+  }
+  switch (dataFormat) {
+    case 1 /* DATA_FORMAT_PICKLE */:
+      return loads(data);
+    case 2 /* DATA_FORMAT_ASGI */:
+      throw new Error("ASGI data format is not supported in Go");
+    case 3 /* DATA_FORMAT_GENERATOR_DONE */:
+      return GeneratorDone.decode(data);
+    default:
+      throw new Error(`Unsupported data format: ${dataFormat}`);
+  }
+}
 export {
   App,
+  Function_,
   Image2 as Image,
-  Sandbox2 as Sandbox
+  InternalFailure,
+  RemoteError,
+  Sandbox2 as Sandbox,
+  TimeoutError
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "modal",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "Modal client library for JavaScript",
   "license": "MIT",
   "homepage": "https://modal.com/docs",