arm64js 0.4.0 → 0.6.0

package/README.md

@@ -121,7 +121,20 @@ A VM can be created either from a base image or your own local snapshot.
 - `image`: name of an image on the CDN ([all images](https://arm64js.com/images/)): `'alpine'` is the newest version of it, `'alpine:2'` a fixed one, `'alpine@sha256:<hash>'` an exact snapshot.
 - `snapshotId`: a snapshot id (`snap.id`, 64 hex characters) loads one of your own snapshots made previously.
 
-Additionally, you can specify an `onProgress` callback to track VM loading phases (`resolve → manifest → start → memory (repeats, with counts) → run → done`) and the number of virtual CPUs the VM will have (more is not always better).
+Additionally, you can specify an `onProgress` callback to track VM loading phases and the number of virtual CPUs the VM will have (more is not always better).
+
+onProgress gets one argument, a BootProgress object:
+
+```ts
+interface BootProgress {
+  stage: 'resolve' | 'manifest' | 'start' | 'memory' | 'run' | 'done';
+  done?: number;
+  total?: number;
+}
+```
+
+- the stages arrive in the following order: resolve → manifest → start → memory → run → done.
+- done and total are optional, they are filled in during the `memory` stage when the VM data chunks load (the slowers part of the boot for larger VMs).
 
 ### Listener: `vm.onOutput(cb)` → unsubscribe
 
@@ -164,6 +177,24 @@ It works by typing the command into the guest's serial console and reading the b
 
 Whatever the command does runs as **root** in the guest.
 
+#### Streaming the output
+
+For longer running commands it can be useful to see output as it's being generated rather waiting for command to finish. To do that you can setup `vm.onOutput` **before** running `vm.exec`:
+
+```ts
+const decoder = new TextDecoder();
+const stop = vm.onOutput((bytes, info) => {
+  if (!info.exec) return; // keep only what exec prints
+  console.log(decoder.decode(bytes));
+});
+
+try {
+  const { exitCode } = await vm.exec('apk add --no-cache php');
+} finally {
+  stop();
+}
+```
+
 ### `vm.write(data)`
 
 Send data directly into the VM console, lower level than `vm.exec`, allows sending any keyboard sequences including key presses like Ctrl-C ('\x03') or Enter ('\r').
@@ -183,6 +214,16 @@ Copies `data` (a `Blob` or `File`, bytes, or a string) into the VM as the file `
 
 The copy is kept in VM memory, so it has to fit there (`alpine` for example has 1 GiB). If you need to use a larger file, use `vm.mount` instead.
 
+Here's an example how you can load a file from the URL in to the VM:
+
+```ts
+const file = await fetch('./test.txt');
+const fileBlob = await file.blob();
+await vm.writeFile('/tmp/test.txt', fileBlob);
+const { output, exitCode } = await vm.exec('cat /tmp/test.txt');
+console.log(output);
+```
+
 **Files become part of the VM, so when a snapshot is taken those files will be present in the snapshot.**
 
 ### `vm.readFile(path, { maxBytes?, timeoutMs? })` → `Blob`
@@ -215,6 +256,18 @@ Undoes a `mount`. If nothing is mounted at `path` it does nothing. While a progr
 
 Saves the VM in browser storage (OPFS) and keeps it running. Use `meta` to store any extra info you'd like to add to the snapshot (any JSON up to 16 KiB); it is returned in `snapshots.list()`.
 
+For example to save current state and load it when page refreshes:
+
+```ts
+// load from snapshot if previously saved or alpine otherwise
+const snapshotId = localStorage.get('snapshotId');
+await Arm64JS.boot(snapshotId ? snapshotId : 'alpine');
+
+// do something to the VM, then save the snapshot again
+const newSnapshot = vm.snapshot();
+localStorage.set('snapshotId', newSnapshot.id);
+```
+
 ### `vm.dispose()`
 
 Stops the VM and frees its workers.

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.4.0";
+export declare const VERSION = "0.6.0";

package/dist/version.js

@@ -1,2 +1,2 @@
 // Generated by scripts/stamp-version.mjs from package.json. Do not edit.
-export const VERSION = "0.4.0";
+export const VERSION = "0.6.0";

package/dist/vm.d.ts

@@ -24,8 +24,9 @@ export declare class Vm {
     /** Run a shell command (one or more lines) in the guest and get its output and
      *  exit code. One at a time per VM. */
     exec(command: string, opts?: ExecOptions): Promise<ExecResult>;
-    /** The raw bytes the guest prints on its console. `info.exec` marks what an
-     *  `exec` printed (its command, output and prompts). Returns the unsubscribe. */
+    /** The raw bytes the guest prints on its console. While an `exec` runs, only
+     *  what its command prints comes through, marked `info.exec`. Returns the
+     *  unsubscribe. */
     onOutput(cb: (bytes: Uint8Array, info: OutputInfo) => void): () => void;
     /** Type into the guest's console, as a person at a terminal would. Input
      *  sent while an `exec` or `snapshot` runs is held and delivered after it. */

package/dist/vm.js

@@ -29,8 +29,9 @@ export class Vm {
         this.check();
         return withSdkErrors(this.host.exec(this.id, command, opts));
     }
-    /** The raw bytes the guest prints on its console. `info.exec` marks what an
-     *  `exec` printed (its command, output and prompts). Returns the unsubscribe. */
+    /** The raw bytes the guest prints on its console. While an `exec` runs, only
+     *  what its command prints comes through, marked `info.exec`. Returns the
+     *  unsubscribe. */
     onOutput(cb) {
         this.check();
         return this.host.onOutput(this.id, cb);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arm64js",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Run a Linux VM inside your web page. Boots Alpine from the arm64js CDN, runs commands, keeps snapshots in the browser.",
   "type": "module",
   "license": "MIT",