Create README.md

Author: drinking-code

README.md

@@ -0,0 +1,127 @@
+# Inter Process Object Sharing [IPOS]
+
+_Share objects across different Node.js processes. Write and read on both sides._  
+This package manages objects via IPC for you. When you create an object, it creates an equivalent on connected
+processes. When you update that object, it updates the equivalent accordingly. And if you delete the object, it will
+also delete the equivalent. This works both ways, so if you change the equivalent object in a subprocess, the original
+will be changes as well.
+
+# Install
+
+```shell
+npm i ipos
+```
+
+# Usage
+
+In the main process:
+
+```javascript
+import child_process from 'child_process'
+import IPOS from 'ipos'
+
+// create a shared object instance
+const sharedObject = IPOS.new()
+// spawn a subprocess
+// the ipc channel (4th stdio argument) is important
+const subProcess = child_process.spawn('node', ['sub-process.js'], {
+    stdio: ['inherit', 'inherit', 'inherit', 'ipc']
+})
+// register the subprocess with IPOS
+// await: to wait for the connection to be established
+await sharedObject.addProcess(subProcess)
+```
+
+In the subprocess:
+
+```javascript
+import IPOS from 'ipos'
+
+// await: to wait for the connection to be established (await only in subprocess)
+const sharedObject = await IPOS.new()
+```
+
+See [`example/main-process.js`](https://github.com/drinking-code/inter-process-object-sharing/blob/main/example/main-process.js)
+and [`example/sub-process.js`](https://github.com/drinking-code/inter-process-object-sharing/blob/main/example/sub-process.js)
+.
+
+## `IPOS()`
+
+The main class. Don't use the `new` keyword (when creating an instance in a subprocess). Instead, use the
+static [`IPOS.new()`](#static-iposnew-ipos--promiseipos) method to create an instance.
+
+### `static IPOS.new(): IPOS | Promise<IPOS>`
+
+Creates a new instance. Multiple instances are not yet supported, so only create one instance per process.
+
+**Returns:**
+
+- `<IPOS>` instance, if called in a normal process
+- `Promise<IPOS>`, if called in a subprocess.  
+  Use await to wait for the connection to the main process to be established.
+
+### `ipos.addProcess(process: ChildProcess): Promise<void>`
+
+Connect a subprocess to the IPOS instance. The subprocess must also
+call [`IPOS.new()`](#static-iposnew-ipos--promiseipos) for the two processes' IPOS to connect.
+
+**Parameters:**
+
+- `process: ChildProcess` The object of a subprocess IPOS should connect with. What gets returned
+  by `child_process.exec()`, `child_process.execFile()`, `child_process.fork()`, or `child_process.spawn()`
+
+**Returns:** `Promise<void>`. Use await to wait for the connection to the subprocess to be established.
+
+### `ipos.create(key: string, value: any)`
+
+Create a field on the IPOS instance. This value can later be accessed or updated (See
+[`ipos.get()`](#iposgetkey-string-any)). After creating a field, you can access and update it (even change the type)
+with `ipos[key: string] = value`. See:
+
+```javascript
+sharedObject.create('myValue', 23)
+sharedObject.myValue = 'foo'
+console.log(sharedObject.myValue) // -> 'foo'
+```
+
+`ipos.create()` can be called multiple times with the same key. Each time the old value will be overwritten.
+
+**Parameters:**
+
+- `key: string` A unique key.
+- `value: any` The value to be stored.
+
+### `ipos.get(key: string): any`
+
+Get an already created field from the IPOS instance. You can also use `ipos[key: string]` to access the value. If you
+use a method on the value that changes the value, this change will also be reflected in the connected IPOS instances.
+See:
+
+```javascript
+sharedObject.create('myArray', [])
+sharedObject.myArray.push('myString')
+console.log(sharedObject.get('myArray')) // -> ['myString']
+console.log(sharedObject.myArray) // -> ['myString']
+```
+
+And in a connected process, after `'myString'` was pushed:
+
+```javascript
+console.log(sharedObject.myArray) // -> ['myString']
+```
+
+**Parameters:**
+
+- `key: string` A unique key of an already created field.
+
+**Returns:** `any`. The stored value.
+
+### `ipos.delete(key: string): boolean`
+
+Deletes the field with the specified key.
+
+**Parameters:**
+
+- `key: string` A unique key of an already created field.
+
+**Returns:** `boolean`. `true` if a field existed and has been removed, or `false` if the element does not exist.