@onivoro/server-process 22.0.2 → 24.0.1

package/README.md

@@ -0,0 +1,389 @@
+# @onivoro/server-process
+
+A lightweight Node.js process management library providing utilities for command execution, Docker container operations, PostgreSQL commands, and reactive process handling.
+
+## Installation
+
+```bash
+npm install @onivoro/server-process
+```
+
+## Features
+
+- **Promise-based Command Execution**: Simple async/await command execution
+- **Reactive Process Streams**: RxJS-based reactive command execution
+- **Docker Container Support**: Execute commands within Docker containers
+- **PostgreSQL Integration**: Execute psql commands with container support
+- **Process I/O Management**: Handle stdin/stdout streams reactively
+- **JSON Output Processing**: Parse command output as JSON
+- **Line-by-Line Processing**: Stream processing for large outputs
+
+## API Reference
+
+### Command Execution
+
+#### `execPromise(cmd, options?)`
+
+Execute a command and return a promise that resolves to stdout as a string:
+
+```typescript
+import { execPromise } from '@onivoro/server-process';
+
+// Simple command execution
+const output = await execPromise('ls -la');
+console.log(output); // stdout as string
+
+// With options
+const result = await execPromise('git status', { cwd: '/path/to/repo' });
+```
+
+**Parameters:**
+- `cmd: string` - Command to execute
+- `options?: EncodingOption & ExecOptions` - Node.js exec options
+
+**Returns:** `Promise<string>` - Command stdout
+
+#### `spawnPromise(program, args?, options?)`
+
+Spawn a process and return a promise that resolves to joined stdout:
+
+```typescript
+import { spawnPromise } from '@onivoro/server-process';
+
+// Spawn with arguments
+const output = await spawnPromise('node', ['--version']);
+console.log(output); // Node.js version
+
+// With spawn options
+const result = await spawnPromise('npm', ['install'], { 
+  cwd: '/path/to/project',
+  env: { ...process.env, NODE_ENV: 'production' }
+});
+```
+
+**Parameters:**
+- `program: string` - Program to spawn
+- `args?: string[]` - Command arguments
+- `options?: any` - Node.js spawn options
+
+**Returns:** `Promise<string>` - Joined stdout (rejects with stderr on error)
+
+### Reactive Command Execution
+
+#### `execRx(cmd, options?, emitStdErr?)`
+
+Execute a command reactively, emitting stdout (and optionally stderr):
+
+```typescript
+import { execRx } from '@onivoro/server-process';
+
+execRx('ping -c 3 google.com').subscribe({
+  next: (output) => console.log('Output:', output),
+  error: (err) => console.error('Error:', err),
+  complete: () => console.log('Command completed')
+});
+
+// Without stderr
+execRx('ls -la', undefined, false).subscribe(console.log);
+```
+
+**Parameters:**
+- `cmd: string` - Command to execute
+- `options?: EncodingOption & ExecOptions` - Node.js exec options
+- `emitStdErr?: boolean` - Include stderr in output (default: true)
+
+**Returns:** `Observable<string>` - Command output stream
+
+#### `execRxAsLines(cmd, options?, emitStdErr?)`
+
+Execute a command and emit output line by line:
+
+```typescript
+import { execRxAsLines } from '@onivoro/server-process';
+
+execRxAsLines('cat large-file.txt').subscribe({
+  next: (line) => console.log('Line:', line),
+  complete: () => console.log('File processed')
+});
+```
+
+**Parameters:**
+- `cmd: string` - Command to execute
+- `options?: ExecOptions` - Node.js exec options
+- `emitStdErr?: boolean` - Include stderr in output (default: true)
+
+**Returns:** `Observable<string>` - Stream of individual lines
+
+#### `execRxAsJson(cmd, options?, emitStdErr?)`
+
+Execute a command and parse output as JSON:
+
+```typescript
+import { execRxAsJson } from '@onivoro/server-process';
+
+execRxAsJson('docker inspect my-container').subscribe({
+  next: (json) => console.log('Container info:', json),
+  error: (err) => console.error('Failed to parse JSON:', err)
+});
+```
+
+**Parameters:**
+- `cmd: string` - Command to execute
+- `options?: ExecOptions` - Node.js exec options
+- `emitStdErr?: boolean` - Include stderr in output (default: true)
+
+**Returns:** `Observable<any>` - Stream of parsed JSON objects
+
+### Docker Class
+
+Execute commands within Docker containers:
+
+```typescript
+import { Docker } from '@onivoro/server-process';
+
+const docker = new Docker('my-postgres-container', 'psql');
+
+// Execute psql command in container
+docker.execRx('-c "SELECT version();"').subscribe({
+  next: (result) => console.log('DB Version:', result),
+  error: (err) => console.error('Query failed:', err)
+});
+```
+
+**Constructor:**
+- `containerName: string` - Name of the Docker container
+- `binaryName: string` - Binary to execute within the container
+
+**Methods:**
+- `execRx(cmd, options?, emitStdErr?)` - Execute command reactively within container
+
+### PSql Class
+
+Execute PostgreSQL commands with optional Docker container support:
+
+```typescript
+import { PSql } from '@onivoro/server-process';
+
+// Local psql
+const psql = new PSql();
+psql.execRx('SELECT COUNT(*) FROM users;', 'mydb', 'postgres').subscribe(console.log);
+
+// Container-based psql
+const containerPsql = new PSql('postgres-container');
+containerPsql.execRx('SELECT NOW();', 'mydb', 'postgres').subscribe(console.log);
+```
+
+**Constructor:**
+- `containerName?: string` - Optional Docker container name
+
+**Methods:**
+- `execRx(cmd, db, username)` - Execute psql command
+  - `cmd: string` - SQL command to execute
+  - `db: string` - Database name
+  - `username: string` - PostgreSQL username
+
+### Process I/O Management
+
+#### `listen()`
+
+Create reactive streams for process stdin/stdout:
+
+```typescript
+import { listen } from '@onivoro/server-process';
+
+const { stdout, stdin } = listen();
+
+// Handle stdin data
+stdin.subscribe((data) => {
+  console.log('Received input:', data.toString());
+});
+
+// stdin automatically completes when process.stdin closes
+```
+
+**Returns:** `{ stdout: Subject, stdin: Subject }` - Reactive streams for process I/O
+
+#### `exit(code)`
+
+Create a process exit function with specified exit code:
+
+```typescript
+import { exit } from '@onivoro/server-process';
+
+const exitWithError = exit(1);
+const exitSuccess = exit(0);
+
+// Use in error handling
+if (someErrorCondition) {
+  console.error('Fatal error occurred');
+  exitWithError();
+}
+```
+
+**Parameters:**
+- `code: number` - Exit code
+
+**Returns:** `() => never` - Function that exits the process
+
+## Usage Examples
+
+### Basic Command Execution
+
+```typescript
+import { execPromise, spawnPromise } from '@onivoro/server-process';
+
+async function deployApp() {
+  try {
+    // Check if Docker is running
+    await execPromise('docker --version');
+    
+    // Build and deploy
+    const buildOutput = await spawnPromise('docker', ['build', '-t', 'myapp', '.']);
+    console.log('Build completed:', buildOutput);
+    
+    const runOutput = await spawnPromise('docker', ['run', '-d', '-p', '3000:3000', 'myapp']);
+    console.log('Container started:', runOutput);
+  } catch (error) {
+    console.error('Deployment failed:', error);
+  }
+}
+```
+
+### Reactive Log Monitoring
+
+```typescript
+import { execRxAsLines } from '@onivoro/server-process';
+
+function monitorLogs(logFile: string) {
+  execRxAsLines(`tail -f ${logFile}`)
+    .subscribe({
+      next: (line) => {
+        if (line.includes('ERROR')) {
+          console.error('🚨 Error detected:', line);
+          // Trigger alert
+        } else if (line.includes('WARN')) {
+          console.warn('⚠️  Warning:', line);
+        }
+      },
+      error: (err) => console.error('Log monitoring failed:', err)
+    });
+}
+
+monitorLogs('/var/log/app.log');
+```
+
+### Database Operations with Docker
+
+```typescript
+import { PSql } from '@onivoro/server-process';
+
+class DatabaseManager {
+  private psql = new PSql('postgres-container');
+
+  async checkHealth() {
+    return new Promise((resolve, reject) => {
+      this.psql.execRx('SELECT 1;', 'postgres', 'admin').subscribe({
+        next: (result) => {
+          console.log('Database is healthy');
+          resolve(result);
+        },
+        error: reject
+      });
+    });
+  }
+
+  async getUserCount(database: string) {
+    return new Promise((resolve, reject) => {
+      this.psql.execRx('SELECT COUNT(*) FROM users;', database, 'admin').subscribe({
+        next: (result) => resolve(parseInt(result.trim())),
+        error: reject
+      });
+    });
+  }
+}
+```
+
+### JSON Processing
+
+```typescript
+import { execRxAsJson } from '@onivoro/server-process';
+
+interface ContainerInfo {
+  Id: string;
+  Name: string;
+  State: { Status: string };
+}
+
+function getContainerStatus(containerName: string) {
+  execRxAsJson<ContainerInfo[]>(`docker inspect ${containerName}`).subscribe({
+    next: (containers) => {
+      const container = containers[0];
+      console.log(`Container ${container.Name} is ${container.State.Status}`);
+    },
+    error: (err) => console.error('Failed to get container info:', err)
+  });
+}
+```
+
+### Process I/O Handling
+
+```typescript
+import { listen, exit } from '@onivoro/server-process';
+
+function setupInteractiveMode() {
+  const { stdin } = listen();
+  
+  console.log('Enter commands (type "exit" to quit):');
+  
+  stdin.subscribe({
+    next: (data) => {
+      const input = data.toString().trim();
+      
+      if (input === 'exit') {
+        console.log('Goodbye!');
+        exit(0)();
+      } else {
+        console.log(`You entered: ${input}`);
+      }
+    },
+    complete: () => {
+      console.log('Input stream closed');
+      exit(0)();
+    }
+  });
+}
+```
+
+## Error Handling
+
+All functions handle errors appropriately:
+
+- **Promise-based functions** reject with error details
+- **Reactive functions** emit errors through the error channel
+- **Process execution errors** include exit codes and stderr information
+
+```typescript
+import { execPromise, execRx } from '@onivoro/server-process';
+
+// Promise error handling
+try {
+  await execPromise('nonexistent-command');
+} catch (error) {
+  console.error('Command failed:', error.message);
+}
+
+// Reactive error handling
+execRx('invalid-command').subscribe({
+  next: (output) => console.log(output),
+  error: (error) => console.error('Command error:', error),
+  complete: () => console.log('Done')
+});
+```
+
+## TypeScript Support
+
+All functions are fully typed with TypeScript interfaces. The library uses Node.js built-in types for options and return values.
+
+## License
+
+This library is part of the Onivoro monorepo ecosystem.

package/jest.config.ts

@@ -0,0 +1,11 @@
+/* eslint-disable */
+export default {
+  displayName: 'lib-server-process',
+  preset: '../../../jest.preset.js',
+  testEnvironment: 'node',
+  transform: {
+    '^.+\\.[tj]s$': ['ts-jest', { tsconfig: '<rootDir>/tsconfig.spec.json' }],
+  },
+  moduleFileExtensions: ['ts', 'js', 'html'],
+  coverageDirectory: '../../../coverage/libs/server/process',
+};

package/package.json

@@ -1,42 +1,10 @@
 {
-    "name": "@onivoro/server-process",
-    "version": "22.0.2",
-    "repository": {
-        "url": "git+https://github.com/onivoro/server-process.git"
-    },
-    "main": "dist/cjs/index.js",
-    "module": "dist/esm/index.js",
-    "types": "dist/types/index.d.ts",
-    "files": [
-        "dist/*"
-    ],
-    "scripts": {
-        "onx": "onx",
-        "build": "onx Build",
-        "deploy": "onx Publish",
-        "test": "onx Test",
-        "update": "onx Update"
-    },
-    "exports": {
-        ".": {
-            "types": "./dist/types/index.d.ts",
-            "require": "./dist/cjs/index.js",
-            "import": "./dist/esm/index.js",
-            "default": "./dist/esm/lib.js"
-        }
-    },
-    "onx": {
-        "platform": "server",
-        "module": "commonjs"
-    },
-    "devDependencies": {
-        "@onivoro/cli": "^22.0.8",
-        "@types/jest": "*",
-        "@types/node": "^22.8.1",
-        "typescript": "*"
-    },
-    "engines": {
-        "node": "22.10.0",
-        "npm": "10.9.0"
-    }
+  "name": "@onivoro/server-process",
+  "version": "24.0.1",
+  "type": "commonjs",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "dependencies": {
+    "tslib": "^2.3.0"
+  }
 }

package/project.json

@@ -0,0 +1,23 @@
+{
+  "name": "lib-server-process",
+  "$schema": "../../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "libs/server/process/src",
+  "projectType": "library",
+  "targets": {
+    "build": {
+      "executor": "@nx/js:tsc",
+      "outputs": ["{options.outputPath}"],
+      "options": {
+        "outputPath": "dist/libs/server/process",
+        "main": "libs/server/process/src/index.ts",
+        "tsConfig": "libs/server/process/tsconfig.lib.json",
+        "assets": [
+          "libs/server/process/README.md",
+          "libs/server/process/package.json"
+        ],
+        "declaration": true
+      }
+    }
+  },
+  "tags": []
+}

package/src/lib/docker.ts

@@ -0,0 +1,14 @@
+import { ExecOptions } from "child_process";
+import { EncodingOption } from "fs";
+import { execRx } from "./exec-rx";
+
+export class Docker {
+  constructor(
+    public readonly containerName: string,
+    public readonly binaryName: string,
+  ) { }
+
+  execRx(cmd: string, options?: EncodingOption & ExecOptions, emitStdErr=true) {
+    return execRx(`docker exec ${this.containerName} ${this.binaryName} ${cmd}`, options, emitStdErr);
+  }
+}

package/src/lib/exec-promise.spec.ts

@@ -0,0 +1,17 @@
+import { parse } from 'path';
+import { execPromise } from './exec-promise';
+
+describe('execPromise', () => {
+    it('resolves with stdout', async () => {
+        const result = await execPromise(`ls ${__dirname}`);
+        expect(result).toContain(parse(__filename).base);
+    });
+
+    it('rejects with stderr', async () => {
+        try {
+            await execPromise(`ls 'no way jose'`);
+        } catch (e) {
+            expect(e.message.replace(/\n/g, ' ')).toContain('No such file or directory');
+        }
+    });
+});

package/src/lib/exec-promise.ts

@@ -0,0 +1,14 @@
+import { exec, ExecOptions } from "child_process";
+import { EncodingOption } from "fs";
+
+export function execPromise(cmd: string, options?: EncodingOption & ExecOptions): Promise<any> {
+    return new Promise((resolve, reject) => {
+        exec(cmd, options, (err, stdout) => {
+            if (err) {
+                reject(err);
+            } else {
+                resolve(stdout.toString());
+            }
+        });
+    });
+}

package/src/lib/exec-rx-as-json.ts

@@ -0,0 +1,9 @@
+import { ExecOptions } from 'child_process';
+import { map } from 'rxjs/operators';
+import { execRx } from './exec-rx';
+
+export const execRxAsJson = (cmd: string, options?: ExecOptions, emitStdErr = true) => {
+  return execRx(cmd, options, emitStdErr).pipe(
+    map((s: string) => JSON.parse(s)),
+  )
+};

package/src/lib/exec-rx-as-lines.ts

@@ -0,0 +1,10 @@
+import { ExecOptions } from 'child_process';
+import { from } from 'rxjs';
+import { concatMap } from 'rxjs/operators';
+import { execRx } from './exec-rx';
+
+export const execRxAsLines = (cmd: string, options?: ExecOptions, emitStdErr = true) => {
+  return execRx(cmd, options, emitStdErr).pipe(
+    concatMap((s: string) => from(s.split('\n'))),
+  )
+};

package/src/lib/exec-rx.spec.ts

@@ -0,0 +1,22 @@
+import { execRx } from './exec-rx';
+import { of } from 'rxjs';
+import { catchError } from 'rxjs/operators';
+
+describe(execRx.name, () => {
+    describe('GIVEN command succeeds', () => {
+        it('returns the stdout', (done) => {
+            execRx(`cat ${__filename}`).subscribe((d) => {
+                expect(d).toEqual(expect.stringContaining('execRx worx!'));
+                done();
+            }, () => { throw new Error("fail") }
+            );
+        });
+    });
+
+    describe('GIVEN command fails', () => {
+        it('emits error', (done) => {
+            execRx(`cat ${__filename + 'blah'}`).pipe(catchError(() => of(done())))
+                .subscribe();
+        });
+    });
+});

package/src/lib/exec-rx.ts

@@ -0,0 +1,16 @@
+import { exec, ExecOptions } from "child_process";
+import { EncodingOption } from "fs";
+import { Observable } from "rxjs";
+
+export function execRx(cmd: string, options?: EncodingOption & ExecOptions, emitStdErr=true): Observable<any> {
+    return new Observable((observer) => {
+        exec(cmd, options, (err, stdout, stderr) => {
+            if (err) {
+                observer.error(err);
+            } else {
+                observer.next(`${stdout}${emitStdErr && ` ${stderr}`}`);
+                observer.complete();
+            }
+        });
+    });
+}

package/src/lib/exit.ts

@@ -0,0 +1 @@
+export const exit = (code: number) => process.exit.bind(process, code);

package/src/lib/listen.ts

@@ -0,0 +1,12 @@
+import { Subject } from 'rxjs';
+
+const stdin = new Subject();
+const stdout = new Subject();
+
+export const listen = () => {
+
+    process.stdin.on('data', d => stdin.next(d));
+    process.stdin.on('close', () => stdin.complete());
+
+    return { stdout, stdin };
+}

package/src/lib/psql.ts

@@ -0,0 +1,16 @@
+import { Docker } from "./docker";
+import { execRx } from "./exec-rx";
+
+const binaryName = 'psql';
+
+export class PSql {
+  constructor(public readonly containerName: string = '') { }
+
+  execRx(cmd: string, db: string, username: string) {
+    const dbOptions = db ? ['-d', db] : [];
+    const commonArgs = ['-qtAX', '-U', username, ...dbOptions, '-c'].join(' ') + cmd;
+    return this.containerName
+      ? (new Docker(this.containerName, binaryName)).execRx(commonArgs)
+      : execRx([binaryName, commonArgs].join(' '));
+  }
+}

package/src/lib/spawn-promise.spec.ts

@@ -0,0 +1,17 @@
+import { parse } from 'path';
+import { spawnPromise } from './spawn-promise';
+
+describe('spawnPromise', () => {
+    it('resolves with stdout', async () => {
+        const result = await spawnPromise(`ls`, [__dirname]);
+        expect(result).toContain(parse(__filename).base);
+    });
+
+    it('rejects with stderr', async () => {
+        try {
+            await spawnPromise(`ls`, ['no way jose']);
+        } catch (e) {
+            expect(e).toContain('No such file or directory');
+        }
+    });
+});

package/src/lib/spawn-promise.ts

@@ -0,0 +1,31 @@
+import { spawn } from "child_process";
+
+const data = 'data';
+
+export function spawnPromise(program: string, args?: string[], options?: any) {
+    return new Promise((res, rej) => {
+        let stdout: string[] = [];
+        let stderr: string[] = [];
+
+        const proc = spawn(program, args, options);
+
+        proc.stdout.on(data, (data) => {
+            stdout.push(`${data}`);
+        });
+
+        proc.stderr.on(data, (data) => {
+            stderr.push(`${data}`);
+        });
+
+        proc.on('close', (code) => {
+            if (code) {
+                rej(stderr.join(' '));
+            } else {
+                res(stdout.join(' '));
+            }
+ 
+            stdout = undefined as any;
+            stderr = undefined as any;
+        });
+    });
+}

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "extends": "../../../tsconfig.server.json",
+  "compilerOptions": {
+    "outDir": "../../../dist/out-tsc"
+  },
+  "files": [],
+  "include": [],
+  "references": [
+    {
+      "path": "./tsconfig.lib.json"
+    },
+    {
+      "path": "./tsconfig.spec.json"
+    }
+  ]
+}