feat: passing callback to report progress (#191)

* feat: passing callback to report progress

* fix: add typing

* fix: change test purpose

* fix: lint errors

* fix: update docs

Co-authored-by: yshechter <yshechter@ravtech.co.il>

docs/README.md

@@ -54,6 +54,7 @@ All commands return a `Promise({object})` with stdout and stderr strings and an
   exitCode: 0, // !== 0 in case of an error
 }
 ```
+Although the return type is a `Promise`, it is still possible to get the process progres before the `Promise` resolves, by passing a callback function to the optional `callback` parameter. 
 
 ### Example
 
@@ -66,6 +67,19 @@ compose.upAll({ cwd: path.join(__dirname), log: true })
     err => { console.log('something went wrong:', err.message)}
   );
 ```
+To get process progres
+```typescript
+compose.upAll({
+   cwd: path.join(__dirname),
+   callback: (chunk: Buffer) => {
+     console.log('job in progres: ', chunk.ToString())
+      }
+   })
+  .then(
+    () => { console.log('job done')},
+    err => { console.log('something went wrong:', err.message)}
+  );
+```
 
 To execute command inside a running container
 ```javascript
@@ -82,6 +96,7 @@ compose.exec('node', 'npm install', { cwd: path.join(__dirname) })
 * `configAsString {string}`: configuration can be provided as is, instead of relying on a file. In case `configAsString` is provided `config` will be ignored.
 * `[log] {boolean}`:  optional setting to enable console logging (output of `docker-compose` `stdout`/`stderr` output)
 * `[composeOptions] string[]|Array<string|string[]`: pass optional compose options like `"--verbose"` or `[["--verbose"], ["--log-level", "DEBUG"]]` or `["--verbose", ["--loglevel", "DEBUG"]]` for *all* commands.
+* `[callback] (chunk: Buffer, sourceStream?: 'stdout' | 'stderr') => void`: optional callback function, that provides infromation about the process while it is still runing.  
 * `[commandOptions] string[]|Array<string|string[]`: pass optional command options like `"--build"` or `[["--build"], ["--timeout", "5"]]` or `["--build", ["--timeout", "5"]]` for the `up` command. Viable `commandOptions` depend on the command (`up`, `down` etc.) itself
 
 ## Running the tests

src/index.ts

@@ -11,6 +11,7 @@ export interface IDockerComposeOptions {
   composeOptions?: string[] | (string | string[])[]
   commandOptions?: string[] | (string | string[])[]
   env?: NodeJS.ProcessEnv
+  callback?: (chunk: Buffer, streamSource?: 'stdout' | 'stderr') => void
 }
 
 export type DockerComposePortResult = {
@@ -181,10 +182,12 @@ export const execCompose = (
 
     childProc.stdout.on('data', (chunk): void => {
       result.out += chunk.toString()
+      options.callback?.(chunk, 'stdout')
     })
 
     childProc.stderr.on('data', (chunk): void => {
       result.err += chunk.toString()
+      options.callback?.(chunk, 'stderr')
     })
 
     childProc.on('exit', (exitCode): void => {

test/index.test.ts

@@ -723,3 +723,14 @@ test('parse ps output', () => {
     ]
   })
 })
+
+test('ensure progress callback is called', async (): Promise<void> => {
+  const config = {
+    cwd: path.join(__dirname),
+    config: './docker-compose.yml',
+    callback: jest.fn()
+  }
+  await compose.upAll(config)
+  expect(config.callback).toBeCalled()
+  await compose.down(config)
+})