npm package: @parallel-park/in-child-process
Description: Run code within a child process
Author: Lily Skye
Latest version: 0.3.1

# @parallel-park/in-child-process

Run code within a child process.

## Usage

`@parallel-park/in-child-process` exports one function: `inChildProcess`.

### `inChildProcess`

`inChildProcess` is a function that you pass a function into, and it spawns a separate node process to run your function in. Once your function has completed, its return/resolved value will be sent back to the node process you called `inChildProcess` from.

```ts
import { inChildProcess } from "parallel-park";

const result = await inChildProcess(() => {
  return 2 + 2;
});

console.log(result); // 4
```

Your function can also return a Promise:

```ts
// Either by returning a Promise directly...
await inChildProcess(() => {
  return Promise.resolve(2 + 2);
});

// Or by using an async function, which returns a Promise that resolves to the function's return value
await inChildProcess(async () => {
  return 2 + 2;
});
```

> ⚠️ NOTE: The return value of your function must be JSON-serializable, or else it won't make it across the gap between the parent node process and the child one.

The function you pass into `inChildProcess` will be executed in a separate node process; as such, it won't be able to access variables defined in the file calling `inChildProcess`:

```ts
const myName = "Lily";

await inChildProcess(() => {
  // Throws an error: myName is not defined
  return myName + "!";
});
```

To work around this, you can pass an object into `inChildProcess` as its first argument, before the function. When called this way, the function will receive that object:

```ts
await inChildProcess({ myName: "Lily" }, (data) => {
  const myName = data.myName;

  // No longer throws an error
  return myName + "!";
});
```

It's common to use object shorthand and destructuring syntax when passing values in:

```ts
const myName = "Lily";

await inChildProcess({ myName }, ({ myName }) => {
  return myName + "!";
});
```

> ⚠️ NOTE: The values in your input object must be JSON-serializable, or else they won't make it across the gap between the parent node process and the child one.

Because the inputs have to be JSON-serializable, you may run into an issue if trying to use an external module within the child process:

```ts
const util = require("util");

await inChildProcess({ util }, ({ util }) => {
  const someData = { something: true };
  // Throws an error: util.inspect is not a function
  return util.inspect(someData);
});
```

To work around this, call `require` inside the child process function:

```ts
await inChildProcess(() => {
  const util = require("util"); // the require is inside the function now

  const someData = { something: true };

  // No longer throws an error
  return util.inspect(someData);
});
```

If you want to use the external module both inside of the child process and outside of it, `require` it in both places:

```ts
const util = require("util");

await inChildProcess(() => {
  const util = require("util");

  const someData = { something: true };

  // No longer throws an error
  return util.inspect(someData);
});
```

The `require` inside of the child process can also be used to load stuff from your own code into the child process:

```ts
const file = "/home/lily/hello.txt";

await inChildProcess({ file }, async ({ file }) => {
  const processFile = require("./process-file");

  const results = await processFile(file);
  console.log(results);
  return results;
});
```

## License

MIT