arm64js 0.5.0 → 0.6.0

package/README.md

@@ -177,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').
@@ -238,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.5.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.5.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.5.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",