@procedures/node 0.2.3 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,72 @@
 # @procedures/node
 
+## 0.4.0
+
+### Minor Changes
+
+- 4c51727: The process registry of `@procedures/shell/command` gives the output of a process after a time. `processes.subscribe(id, { output, end })` calls `output` with each new piece of output and its stream, and `end` with the record at the end of the process. `processes.follow(id, { backlog, signal, maxBufferedBytes })` gives the output as an async stream: the kept output without a gap, the new pieces in UTF-8, a `dropped` item for a slow reader, and an `end` item. The end of the process removes each subscriber, and a follow that ends removes its subscriber.
+  
+  `node.logs` has the option `follow` (short `-f`). With it, the result is a stream: the kept output as `output` lines (`lines` limits them), each new line of stdout and stderr, and an `exit` item at the end of the process. The stream ends at the end of the process, at an abort of the caller and when the reader stops. `node.logs` declares `stream: { unbounded: true }`.
+
+### Patch Changes
+
+- Updated dependencies [d919678]
+- Updated dependencies [057d69a]
+- Updated dependencies [b2a1a1e]
+- Updated dependencies [057d69a]
+- Updated dependencies [057d69a]
+- Updated dependencies [057d69a]
+- Updated dependencies [057d69a]
+- Updated dependencies [057d69a]
+- Updated dependencies [afd6a19]
+- Updated dependencies [057d69a]
+- Updated dependencies [4c51727]
+- Updated dependencies [4e751da]
+  - @procedures/client@0.4.0
+  - @procedures/shell@0.4.0
+
+## 0.3.0
+
+### Minor Changes
+
+- 04cfef8: `node.logs` (roadmap R44) gives the output of a process that `node.spawn` started: the last 64 KiB of stdout and stderr that the process registry of `client-shell` keeps. With `lines`, it gives only the last lines. With `stripAnsi`, it removes the colors. It works also after the process ended, and it only reads (`reads: ["jobs"]`).
+
+### Patch Changes
+
+- Updated dependencies [ddea529]
+- Updated dependencies [b2a3e3a]
+- Updated dependencies [a8c47f1]
+- Updated dependencies [381ce3a]
+- Updated dependencies [0c627f8]
+- Updated dependencies [ae7f05f]
+- Updated dependencies [7873940]
+- Updated dependencies [a70d445]
+- Updated dependencies [bc70357]
+- Updated dependencies [07cc998]
+- Updated dependencies [a6b01a9]
+- Updated dependencies [c799cdd]
+- Updated dependencies [540f8d9]
+- Updated dependencies [b6daaec]
+- Updated dependencies [5b9264e]
+- Updated dependencies [956e88b]
+- Updated dependencies [ff62281]
+- Updated dependencies [d81d0ed]
+- Updated dependencies [aa67cc7]
+- Updated dependencies [061fa22]
+- Updated dependencies [cfb9d69]
+- Updated dependencies [43f7de5]
+- Updated dependencies [b07bb50]
+- Updated dependencies [4a3bfa1]
+- Updated dependencies [bd0b626]
+- Updated dependencies [a6be873]
+- Updated dependencies [fb30718]
+- Updated dependencies [c5528e4]
+- Updated dependencies [fee5d9c]
+- Updated dependencies [21f7743]
+- Updated dependencies [31a0b46]
+  - @procedures/client@0.3.0
+  - @procedures/shell@0.3.0
+
 ## 0.2.3
 
 ### Patch Changes

package/README.md

@@ -14,6 +14,7 @@ Node.js process management procedures for the client ecosystem. Provides procedu
 │   await client.exec(["node", "spawn"], { script: "server.js" })             │
 │   await client.exec(["node", "kill"], { processId: "abc123" })              │
 │   await client.exec(["node", "status"], {})                                 │
+│   await client.exec(["node", "logs"], { processId: "abc123", lines: 50 })   │
 │                                                                              │
 └─────────────────────────────────┬───────────────────────────────────────────┘
                                   │
@@ -62,6 +63,8 @@ pnpm add @procedures/node
 
 ## Procedures
 
+The package has 5 procedures. Its register entry (`import "@procedures/node/register"`) registers them: `node.run`, `node.spawn`, `node.kill`, `node.status`, `node.logs`.
+
 ### node.run
 
 Run a Node.js script to completion and return the output.
@@ -217,6 +220,51 @@ for (const proc of result.processes) {
 | `status` | `"running" \| "stopped"` | Process status |
 | `startedAt` | `string` | ISO timestamp when started |
 
+### node.logs
+
+The procedure gives the output of one process that `node.spawn` started. The process registry of `client-shell` reads the output of each process and keeps its end: the last 64 KiB of stdout and stderr together. Thus the procedure gives that end, also after the process ended. The registry keeps the records of the last 50 ended processes.
+
+```typescript
+const { status, exitCode, output } = await client.exec(["node", "logs"], {
+  processId: "node-abc123-1",
+  lines: 50,
+  stripAnsi: true,
+});
+```
+
+The input has these fields:
+
+- `processId` (necessary): the process ID that `node.spawn` gave.
+- `lines`: give only the last lines of the output.
+- `stripAnsi`: remove the ANSI escape codes (colors) from the output.
+- `follow`: give a stream of lines (see below).
+
+The output has the `processId`, the `status` (`running`, `exited` or `error`), the `exitCode` of an ended process and the `output`.
+
+The procedure knows only the processes of its host. The process writes to two pipes, stdout and stderr. Thus `output` has their lines in the order of their arrival. A process that `node.spawn` did not start is an error.
+
+#### `follow`: a stream of the lines
+
+With `follow: true`, the result is a stream. It uses `processes.follow` of `@procedures/shell/command`.
+
+```typescript
+for await (const item of client.stream(["node", "logs"], { processId, follow: true, lines: 20 })) {
+  if (item.type === "exit") break;
+  console.log(item.type, item.line);
+}
+```
+
+| Item | Meaning |
+|---|---|
+| `{ type: "output", line }` | A line of the kept output. `lines` limits these lines. The kept output has stdout and stderr together. |
+| `{ type: "stdout" \| "stderr", line }` | A new line of the process, without its line end. |
+| `{ type: "dropped", bytes }` | The reader was slow, and the stream dropped this many bytes of output. |
+| `{ type: "exit", status, exitCode, signal }` | The end of the process. It is the last item. |
+
+- The stream ends at the end of the process, at an abort of the caller, and when the reader stops. Each end removes the subscription from the process registry.
+- A line without a line end at the end of the process is the last line of its stream.
+- The procedure declares `stream: { unbounded: true }`, because a process can run without an end.
+
 ## Process Lifecycle
 
 ```