@phpsandbox/sdk 0.1.1 → 0.1.2

package/README.md

@@ -23,9 +23,9 @@ const client = PHPSandbox.realtime(token);
 // create() initializes the notebook by default
 const notebook = await client.notebook.create('php');
 
-await notebook.file.write('index.php', '<?php echo "Hello from PHPSandbox";');
+await notebook.files.write('index.php', '<?php echo "Hello from PHPSandbox";');
 
-const process = await notebook.terminal.spawn('php', ['index.php']);
+const process = await notebook.terminals.create({ command: 'php', args: ['index.php'] });
 
 const reader = process.output.getReader();
 let output = '';
@@ -39,7 +39,7 @@ try {
   reader.releaseLock();
 }
 
-await process.exit;
+await process.wait();
 console.log(output.trim());
 
 // close websocket resources when done
@@ -106,22 +106,23 @@ Notes:
 
 Each `NotebookInstance` exposes service clients:
 
-- `notebook.file` (`Filesystem`)
-- `notebook.terminal` (`Terminal`)
+- `notebook.files` (`Filesystem`)
+- `notebook.terminals` (`Terminals`)
 - `notebook.container` (`Container`)
-- `notebook.shell` (`Shell`)
 - `notebook.composer` (`Composer`)
 - `notebook.git` (`Git`)
 - `notebook.lsp` (`Lsp`)
 - `notebook.repl` (`Repl`)
 - `notebook.auth` (`Auth`)
-- `notebook.log` (`Log`)
+- `notebook.logs` (`Logs`)
+- `notebook.ports` (`Ports`)
+- `notebook.metrics` (`Metrics`)
 - `notebook.services` (`Services`)
 - `notebook.mail` (`NotebookMail`)
 
 Notes:
 
-- `terminal.spawn()` is the TTY-oriented process API; `notebook.run()` is the native non-TTY process API.
+- `terminals.create()` is the TTY-oriented process API; `notebook.exec()` and `notebook.run()` are the native non-TTY process APIs.
 - `notebook.repl.eval()` evaluates PHP without exposing the unsupported `repl.start` action.
 
 ## Common Operations
@@ -129,17 +130,26 @@ Notes:
 ### Files
 
 ```ts
-await notebook.file.write('README.md', '# App');
+await notebook.files.write('README.md', '# App');
 
-const raw = await notebook.file.readFile('README.md');
-const text = new TextDecoder().decode(raw);
+await notebook.files.write('archive.zip', byteStream);
+for await (const chunk of notebook.files.readStream('archive.zip')) {
+  consume(chunk);
+}
+
+const raw = await notebook.files.read('README.md');
+const text = await notebook.files.readText('README.md');
+const excerpt = await notebook.files.readLines('storage/logs/laravel.log', {
+  start: 100,
+  end: 200,
+});
 
-const files = await notebook.file.find('*.php', {
+const files = await notebook.files.find('*.php', {
   includes: ['app/**'],
   excludes: ['vendor/**'],
 });
 
-const [hasMore, matches] = await notebook.file.search(
+const [hasMore, matches] = await notebook.files.search(
   { pattern: 'class\\s+User', isRegExp: true },
   { maxResults: 20, includes: ['app/**'], excludes: ['vendor/**'] }
 );
@@ -148,24 +158,27 @@ const [hasMore, matches] = await notebook.file.search(
 ### Terminal
 
 ```ts
-const task = await notebook.terminal.spawn('composer', ['--version']);
+const task = await notebook.terminals.create({ command: 'composer', args: ['--version'] });
 
 task.output.getReader().read().then(({ value }) => {
   console.log(value);
 });
 
-const exitCode = await task.exit;
+const exitCode = await task.wait();
 console.log(exitCode);
 ```
 
 ### Shell
 
 ```ts
+const result = await notebook.exec('php -v');
+result.throw();
+
 const process = notebook.run('php -v', { tty: false });
 for await (const chunk of process.output) {
   console.log(chunk.source, new TextDecoder().decode(chunk.data));
 }
-(await process.exit).throw();
+(await process.wait()).throw();
 ```
 
 ### Services
@@ -184,17 +197,41 @@ const snapshot = await notebook.services.logs('redis', { tail: 50 });
 console.log(snapshot);
 
 const stream = notebook.services.logs('redis', { follow: true, tail: 25 });
-const reader = stream.output.getReader();
+const reader = stream.getReader();
 const chunk = await reader.read();
 console.log(chunk.value);
-await stream.stop();
+await reader.cancel();
+```
+
+### Runtime observability
+
+```ts
+const currentPorts = await notebook.ports.list();
+const currentMetrics = await notebook.metrics.current();
+
+for await (const sample of notebook.metrics.watch({ signal })) {
+  console.log(sample.cpu, sample.memory, sample.disk);
+}
+
+for await (const ports of notebook.ports.watch({ signal })) {
+  console.log(ports);
+}
+
+for await (const entry of notebook.logs.follow({ signal })) {
+  console.log(entry.timestamp, entry.source, entry.message);
+}
 ```
 
 ### Composer
 
 ```ts
-await notebook.composer.install({ noInteraction: true });
-await notebook.composer.require({ packages: ['monolog/monolog'] });
+const install = notebook.composer.install();
+for await (const chunk of install.output) {
+  console.log(chunk.source, new TextDecoder().decode(chunk.data));
+}
+(await install.wait()).throw();
+
+(await notebook.composer.require({ packages: ['monolog/monolog'] }).wait()).throw();
 
 const installed = await notebook.composer.packages();
 console.log(installed.map((pkg) => pkg.name));
@@ -276,7 +313,7 @@ const disposeConnect = notebook.onDidConnect(() => {
   console.log('connected');
 });
 
-const disposeFs = notebook.file.watch(
+const disposeFs = notebook.files.watch(
   '/app',
   { recursive: true, excludes: ['vendor/**', 'node_modules/**'] },
   (change) => {
@@ -295,7 +332,7 @@ disposeFs.dispose();
 import { ApiError, FilesystemError, FilesystemErrorType } from '@phpsandbox/sdk';
 
 try {
-  await notebook.file.readFile('/does-not-exist.php');
+  await notebook.files.read('/does-not-exist.php');
 } catch (error) {
   if (error instanceof FilesystemError && error.name === FilesystemErrorType.FileNotFound) {
     console.error('Missing file');