modal 0.2.0 → 0.3.1

package/README.md

@@ -0,0 +1,19 @@
+# modal-js development
+
+Setup after cloning the repo with submodules:
+
+```bash
+npm install
+```
+
+Then run a script with:
+
+```bash
+node --import tsx path/to/script.ts
+```
+
+## gRPC support
+
+We're using `nice-grpc` because the `@grpc/grpc-js` library doesn't support promises and is difficult to customize with types.
+
+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.

package/dist/index.d.ts

@@ -0,0 +1,96 @@
+declare class Image {
+    readonly imageId: string;
+    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>;
+}
+
+type StdioBehavior = "pipe" | "ignore";
+type StreamMode = "text" | "binary";
+type ExecOptions = {
+    mode?: StreamMode;
+    stdout?: StdioBehavior;
+    stderr?: StdioBehavior;
+};
+declare class Sandbox {
+    #private;
+    readonly sandboxId: string;
+    stdin: ModalWriteStream<string>;
+    stdout: ModalReadStream<string>;
+    stderr: ModalReadStream<string>;
+    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>;
+}
+
+type LookupOptions = {
+    environment?: string;
+    createIfMissing?: boolean;
+};
+type SandboxCreateOptions = {
+    cpu?: number;
+    memory?: number;
+    timeout?: number;
+    command?: string[];
+};
+declare class App {
+    readonly appId: string;
+    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>;
+}
+
+export { App, Image, type LookupOptions, Sandbox, type SandboxCreateOptions, type StdioBehavior, type StreamMode };