# shared-space

> Node.js shared object interface for cluster workers and thread workers

Latest version **0.5.3** (published 2020-09-24) · MIT license · 0 weekly downloads

## Install

```sh
npm install shared-space
pnpm add shared-space
yarn add shared-space
bun add shared-space
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.5.3 |
| Published | 2020-09-24 |
| First published | 2020-09-23 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >= 12.10.0 |
| Dependencies | 2 |
| Unpacked size | 25.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | UNLOQ Systems |
| Maintainers | snupa |

## Links

- npm: https://www.npmjs.com/package/shared-space
- Repository: https://github.com/snupa/node-shared-space
- Homepage: https://github.com/snupa/node-shared-space#readme
- Issues: https://github.com/snupa/node-shared-space/issues
- npm.io page: https://npm.io/package/shared-space

## Dependencies (2)

- [bson](https://npm.io/package/bson.md) 4.1.0
- [dot-object](https://npm.io/package/dot-object.md) 2.1.4

## Recent versions

- 0.5.3 (latest) — 2020-09-24
- 0.5.2 — 2020-09-24
- 0.5.1 — 2020-09-23
- 0.5.0 — 2020-09-23

## README

# Shared objects for Node

This project aims to bring an easy to use interface for synchronising
objects between worker threads or process forks.

### Installation

```bash
npm install -s shared-space
```

> This library requires node version > 12.x

### Using with Node.js worker threads

```javascript
// Main thread (main.js)
const { Worker } = require('worker_threads');
const path = require('path');
const { SharedObject } = require('shared-space');
const myObject = new SharedObject({
 initial: 'data'
});
for (let i=0; i < 4; i++) {
    let worker = new Worker(path.join(__dirname, 'worker.js'));
    myObject.shareWith(worker);
}
// Change any object field with
myObject.set('my.inner.key', 'someValue');   // => {my: {inner: {key: 'someValue'}}}
// Retrieve any object field with
console.log(myObject.get('my.inner.key'));
setTimeout(() => {
  console.log('Now we have', myObject.get('my.inner.key')); // prints 'worker'
}, 100);

// Worker thread (worker.js)
const { SharedObject } = require('shared-space');
const myObject = new SharedObject();
// Retrieve its data
console.log(myObject.get('initial'));   // prints 'data'
// Change data on all worker threads and main thread.
myObject.set('my.inner.key', 'worker');
```

### Using with the Node.js cluster module

```javascript
const cluster = require('cluster');
const { SharedObject } = require('shared-space');
if(cluster.isMaster) {
    // Initiate main shared object only in master process
    let myObject = new SharedObject({
        initial: 'data'
    });
    for (let i=0; i < 4; i++) {
        let child = cluster.fork();
        myObject.shareWith(child);
    }
    // Change any object field with
    myObject.set('my.inner.key', 'someValue');   // => {my: {inner: {key: 'someValue'}}}
    // Retrieve any object field with
    console.log(myObject.get('my.inner.key'));
    setTimeout(() => {
      console.log('Now we have', myObject.get('my.inner.key')); // prints 'worker'
    }, 100);

} else {
    // We are in a forked process
    let myObject = new SharedObject();
    console.log(myObject.get());  // prints the entire data object.
    myObject.set('some.field', 'value');  // propagates value to all forked children, and the main process
}
```

### How it works
The library uses the standard Node `cluster` module (for when in cluster mode), or `worker_threads` (for when in thread mode).
In essence, it performs object synchronisation between workers, by transferring object deltas (or changes) between workers,
and merging the main data object.

Internally, when used with `threads`, it serializes the data using `bson` and sends/receives Uint8Array objects between workers.
However, when used with the `cluster` module, it sends direct object JSONs between workers.
Synchronisation is performed between all threads/processes (worker and main), with the `last-update-wins` scenario.

More examples are in the [example](https://github.com/snupa/node-shared-space/tree/master/example) folder

### API

#### instance.constructor(initialData={})
Creates a new SharedObject instance and gives it the initial data.

#### instance.get(key?)
Returns the value of a specific key in the shared object. The key can use dot notation to retrieve inner objects (eg: my.inner.field)
If no key is specified, the entire data object will be retrieved.

#### instance.set(key, value?)
Sets the given value to the specified key inside the object. The key uses dot notation, and overrides any value present in the object.
If the key itself is an object, it will be merged with the shared object's data, overriding any values.

#### instance.clear(key)
Removes the specified key from the SharedObject's data. If no key is specified, the entire data object will be reset.

#### SharedSpace.SharedParent
The Shared object parent class used in main thread/process

#### SharedSpace.SharedChild
The Shared object child class used in sub-threads/processes

#### SharedSpace.SharedObject
either the SharedParent or the SharedChild, depending on the context of the process (parent/child)

---
_Source: https://npm.io/package/shared-space · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._