@stinkycomputing/cachearoo 1.0.24

package/.github/workflows/build_and_test.yml

@@ -0,0 +1,29 @@
+name: Build and test
+
+on:
+  push:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [16.x]
+    
+    steps:
+    - uses: actions/checkout@v3
+
+    - name: Use Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v3
+      with:
+        node-version: ${{ matrix.node-version }}
+
+    - name: Build
+      run: |
+        npm install
+        npm run build
+
+    - name: Test
+      run: |
+        npm test

package/.github/workflows/npm-publish.yml

@@ -0,0 +1,30 @@
+# This workflow will run tests using node and then publish a package to GitHub Packages when a release is created
+# For more information see: https://help.github.com/actions/language-and-framework-guides/publishing-nodejs-packages
+
+name: Node.js Package
+
+on:
+  push:
+    tags:
+      - "v*"
+jobs:
+  publish-npm:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 16
+          registry-url: https://registry.npmjs.org/
+      - name: Build, test and publish
+        run: |
+          npm ci
+          npm run build
+          npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{secrets.STINKYDEV_NPM_TOKEN}}
+      - name: Release
+        uses: "marvinpinto/action-automatic-releases@latest"
+        with:
+          repo_token: "${{ secrets.GITHUB_TOKEN }}"
+          prerelease: false

package/README.md

@@ -0,0 +1,400 @@
+![main branch](https://github.com/regodev/cachearoo-js/actions/workflows/build_and_test.yml/badge.svg)
+
+Tags starting with "v" are automatically published to npm
+
+### Install
+```js
+npm install cachearoo
+```
+
+# Cachearoo
+
+```js
+const Cachearoo = require('cachearoo').Cachearoo;
+```
+
+Communicates with Cachearoo server, maintains a persistent connection, handles data store operations and event signaling. If the persistent connection (websocket) is not connected, REST will be used. Events can be registered without having the connection active, the client will automatically register them with the server when connection is established. Works with node.js and in browser.
+
+## Constructor
+
+```js
+new Cachearoo(options);
+```
+
+### Cachearoo Options
+
+| Property     | Type    | Default   | Description                                        |
+|--------------|---------|-----------|----------------------------------------------------|
+| host         | string  | 127.0.0.1 | Cachearoo Server host or ip                      |
+| port         | number  | 4300      | Cachearoo Server port                            |
+| path         | string  |           | Path to api if behind proxy                        |
+| apiKey       | string  |           | Secret key to access API (if set in server)        |
+| secure       | boolean | false     | Use TLS                                            |
+| enablePing   | boolean | false     |                                                    |
+| pingInterval | number  | 5000      | Time in milliseconds                                       |
+| clientId     | string  |           | Name of client, visible in admin UI status section |
+| bucket       | string  |           | Default bucket for operations                      |
+
+## Methods
+
+
+### read(key, [opts])
+Returns promise with read object. If empty string is passed as key, an array of all objects in bucket will be returned.
+
+***options (optional)***
+
+| Property  | Type    | Default | Description                            |
+|-----------|---------|---------|----------------------------------------|
+| bucket    | string  | null    | Optionally override default bucket     |
+| forceHttp | boolean | false   | Force request to be sent over REST api |
+| async     | boolean | true    |                                        |
+
+***Example***
+
+```js
+const cro = new Cachearoo({ bucket: 'myBucket' });
+cro.read('myKey')
+  .then(value => console.log(value));
+```
+
+### list([opts])
+List objects in bucket. Returns promise with array.
+
+***options (optional)***
+
+| Property  | Type    | Default | Description                            |
+|-----------|---------|---------|----------------------------------------|
+| bucket    | string  | null    | Optionally override default bucket     |
+| keysOnly  | boolean | true    | Set to false to retrieve object content     |
+| forceHttp | boolean | false   | Force request to be sent over REST api |
+| async     | boolean | true    |                                        |
+
+***Example***
+
+```js
+const cro = new Cachearoo({ bucket: 'myBucket' });
+cro.list()
+  .then(objects => console.log(objects));
+```
+
+### write(key, data, [opts])
+Returns promise
+
+***options (optional)***
+
+| Property     | Type    | Default | Description                                                                                   |
+|--------------|---------|---------|-----------------------------------------------------------------------------------------------|
+| bucket       | string  | null    | Optionally override default bucket                                                            |
+| forceHttp    | boolean | false   | Force request to be sent over REST api                                                        |
+| async        | boolean | true    |                                                                                               |
+| failIfExists | boolean | false   | Operation will fail if key already exists in data store                                       |
+| expire       | string  |         | Set expiration for object, possible values: 'session' - Delete object when client disconnects |
+
+***Example***
+
+```js
+const cro = new Cachearoo({ bucket: 'myBucket' });
+cro.write('myKey', { text: 'hello!' })
+  .then(() => console.log('Written!');
+```
+
+### patch(key, patch, [opts])
+Returns promise. [JSON patch](http://jsonpatch.com/) existing object.
+
+***options (optional)***
+
+| Property     | Type    | Default | Description                                                                                   |
+|--------------|---------|---------|-----------------------------------------------------------------------------------------------|
+| bucket       | string  | null    | Optionally override default bucket                                                            |
+| removeDataFromReply       | boolean  | false    | Optionally remove patch result from reply                                                            |
+| forceHttp    | boolean | false   | Force request to be sent over REST api                                                        |
+| async        | boolean | true    |                                                                                                                                   |
+
+
+***Example***
+
+```js
+const cro = new Cachearoo({ bucket: 'myBucket' });
+cro.patch('myKey', [{ op: 'replace', path: '/text', value: 'hey!' }])
+  .then(() => console.log('Patched!');
+```
+
+### remove(key, [opts])
+Returns promise. Removes an object from data store.
+
+***options (optional)***
+
+| Property     | Type    | Default | Description                                                                                   |
+|--------------|---------|---------|-----------------------------------------------------------------------------------------------|
+| bucket       | string  | null    | Optionally override default bucket                                                            |
+| forceHttp    | boolean | false   | Force request to be sent over REST api                                                        |
+| async        | boolean | true    |                                                                                                                                   |
+
+
+***Example***
+
+```js
+const cro = new Cachearoo({ bucket: 'myBucket' });
+cro.remove('myKey')
+  .then(() => console.log('Removed!');
+```
+### Properties
+
+Connection: PersistentConnection 
+
+# PersistentConnection
+PersistentConnection is automatically created in the Cachearoo instance as property `connection`
+
+## Methods
+
+### addListener(bucket, key, sendValues, callbackFn(eventObject))
+Add listener for specific bucket and key. Wildcard * can be used to listen to all events in a bucket. If * is used for bucket, events will be triggered for all buckets.
+
+**eventObject**
+
+| Property | Type   | Description                                              |
+|----------|--------|----------------------------------------------------------|
+| bucket   | string | bucket of event origin                                   |
+| key      | string | key of event origin                                      |
+| value    | object | written object if sendEvent was true in addListener call |
+
+
+***Example***
+
+```js
+const cro = new Cachearoo({ bucket: 'myBucket' });
+cro.connection.addListener('myBucket', 'myKey', true, (event) => {
+  console.log(`Event received for 
+    key ${event.key} in
+    bucket ${event.bucket},
+    value=${event.value}`); 
+});
+```
+
+
+### signalEvent(bucket, key, value)
+Send data to Cachearoo only to be propagated as an event to other clients.
+
+***Example***
+
+```js
+const cro = new Cachearoo({ bucket: 'myBucket' });
+cro.connection.signalEvent(
+  'myEventBucket',
+  'myEventKey',
+  { message: 'hello yall!' }
+});
+```
+
+## Events (callbacks)
+### onConnect(persistentConnection)
+Callback triggered when connection is established.
+
+***Example***
+
+```js
+const cro = new Cachearoo({ bucket: 'myBucket' });
+cro.connection.onConnect = (serverId) => {
+  console.log(`Client connected to server with id ${serverId}`);
+};
+```
+
+### onDisconnect()
+Callback triggered when connection is closed.
+
+***Example***
+
+```js
+const cro = new Cachearoo({ bucket: 'myBucket' });
+cro.connection.onDisconnect = () => {
+  console.log('Client disconnected');
+};
+```
+
+### onPong()
+Callback triggered when pong packet is received from server.
+
+***Example***
+
+```js
+const cro = new Cachearoo({ bucket: 'myBucket' });
+cro.connection.onPong = () => {
+  console.log('Server is responding!');
+};
+```
+
+# Messaging.RequestReply
+```js
+const RequestReply = require('cachearoo').Messaging.RequestReply;
+```
+Thin abstraction for sending and receiving messages between two clients connected to same Cachearoo. Cachearoo messaging is using the signalEvent method of PersistentConnection.
+
+# Requestor
+Requestor is used to send messages to a receiver. Request will fail if no response is received within timeoutInMs or if no progress update is received within progressTimeoutInMs.
+
+## Constructor
+
+```js
+new RequestReply.Requestor(CachearooInstance, channel, timeoutInMs, progressTimeoutInMs);
+```
+
+## Methods
+
+### request(msg)
+Returns promise with reply.
+
+***Example***
+
+```js
+const cro = new Cachearoo();
+
+// We cannot send request before we are connected
+cro.connection.onConnect = (serverId) => {
+  // fail if response > 30 sec or if progress is not received < every 3 sec
+  const requestor = new Requestor(bap, 'my-channel', 30000, 3000);
+  requestor.request({ msg: 'hello?' })
+  .then(reply => console.log(`Got reply! ${reply}`);
+  .catch(err => console.error(err));
+};
+```
+
+# Replier
+Replier is used to receive and reply to messages.
+
+## Constructor
+
+```js
+new RequestReply.Replier(CachearooInstance, channel);
+```
+
+## Events
+
+### onMessage(msg, replyFn(err, obj), progressFn(obj))
+Called when a message is received. Reply is sent by calling replyFn with either an error or some data. In case of lengthy processing before reply can be sent, replier can call progressFn to avoid timeout in requestor.
+
+***Example***
+
+```js
+const cro = new Cachearoo();
+
+const replier = new Replier(bap, 'my-channel');
+replier.onMessage = (msg, reply, progress) => {
+  console.log(`Got request: ${msg}`);
+  // send progress after 2 sec, and reply after 5 sec
+  setTimeout(() => progress({ someprop: 'some value' }), 2000);
+  setTimeout(() => reply(null, { someProperty: 'some value' }), 5000);
+};
+```
+
+# Messaging.CompetingConsumers
+```js
+const CompetingConsumers = require('cachearoo').Messaging.CompetingConsumers;
+```
+This pattern is used when one producer generates jobs that many listening consumers can claim. Only one of the consumers can claim each job.
+
+#Producer
+Producer creates jobs.
+
+## Constructor
+
+```js
+new CompetingConsumers.Producer(CachearooInstance, channel, timeoutInMs, progressTimeoutInMs);
+```
+
+## Methods
+
+### addJob(job, progressFn?, timoutInMs?, progressTimeoutInMs?)
+Returns promise, resolved if consumer processed it successfully. Consumer can optionally call a progress callback (passed in progressFn) during its job processing.
+
+***Example***
+
+```js
+const cro = new Cachearoo();
+
+const producer = new Producer(bap, 'render-jobs', 10000);
+cro.connection.onConnect = (serverId) => {
+  producer.addJob({ someProperty: 'value' }, (progress) => console.log(progress))
+  .then((data) => {
+    console.log(`Job done: ${data.result}`);
+  })
+  .catch(err => console.error(err));
+}
+```
+
+# CompetingConsumer
+Consumer of jobs.
+
+## Constructor
+
+```js
+new CompetingConsumers.CompetingConsumer(CachearooInstance, channel);
+```
+
+## Events
+
+### onJobQuery(job, callback(errno, worker))
+Called when a job is requested by producer. errno should have one of values:
+
+```js
+const JOB_NOT_SUPPORTED = 100;
+const NO_WORKER_AVAILABLE = 200;
+const JOB_OK = null;
+```
+
+Worker object must implement following:
+
+```js
+class Worker {
+  constructor(id) {
+    this.id = id;
+    this.available = true;
+  }
+
+  work(job, done, progress) {
+    // do things
+    // signal progress with progress();
+    done(err, result);
+  }
+  
+  release() {
+    this.available = true;
+  }
+}
+```
+
+
+***Example***
+
+```js
+class MyWorker {
+  constructor(id) {
+  this.id = id;
+  this.available = true;
+  }
+
+  work(job, done, progress) {
+    console.log('working..');
+    // send progress every sec
+    setTimeout(() => progress({ someProperty: 'value' }), 1000);
+    // signal done after 10 sec
+    setTimeout(() => done(null, { someProperty: 'value' }), 10000);
+  }
+  
+  release() {
+    this.available = true;
+  }
+}
+
+const de = new Cachearoo();
+
+const consumer = new CompetingConsumer(de, 'my-channel');
+const worker = new MyWorker('myworker1');
+
+consumer.onJobQuery = (job, callback) => {
+  if (worker.available) {
+    callback(null, worker);
+  } else {
+    callback(200); // no worker available
+  }
+};
+```

package/dist/cachearoo-node.d.ts

@@ -0,0 +1,19 @@
+import { Cachearoo, CachearooSettings, RequestOptions } from './libs/cro';
+import { CompetingConsumer, Producer } from './libs/cro.msg.competing-consumers';
+import { Requestor, Replier } from './libs/cro.msg.request-reply';
+export declare namespace Messaging {
+    const RequestReply: {
+        Requestor: typeof Requestor;
+        Replier: typeof Replier;
+    };
+    const CompetingConsumers: {
+        CompetingConsumer: typeof CompetingConsumer;
+        Producer: typeof Producer;
+    };
+    const Errors: {
+        JOB_NOT_SUPPORTED: number;
+        NO_WORKER_AVAILABLE: number;
+    };
+}
+export { Requestor, Replier } from './libs/cro.msg.request-reply';
+export { Cachearoo, CachearooSettings, RequestOptions };

package/dist/cachearoo-node.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RequestOptions = exports.CachearooSettings = exports.Cachearoo = exports.Replier = exports.Requestor = exports.Messaging = void 0;
+const fetch = require("node-fetch-commonjs");
+global.fetch = fetch;
+const cro_1 = require("./libs/cro");
+Object.defineProperty(exports, "Cachearoo", { enumerable: true, get: function () { return cro_1.Cachearoo; } });
+Object.defineProperty(exports, "CachearooSettings", { enumerable: true, get: function () { return cro_1.CachearooSettings; } });
+Object.defineProperty(exports, "RequestOptions", { enumerable: true, get: function () { return cro_1.RequestOptions; } });
+const cro_msg_competing_consumers_1 = require("./libs/cro.msg.competing-consumers");
+const cro_msg_request_reply_1 = require("./libs/cro.msg.request-reply");
+const cro_msg_competing_consumers_2 = require("./libs/cro.msg.competing-consumers");
+var Messaging;
+(function (Messaging) {
+    Messaging.RequestReply = {
+        Requestor: cro_msg_request_reply_1.Requestor,
+        Replier: cro_msg_request_reply_1.Replier,
+    };
+    Messaging.CompetingConsumers = {
+        CompetingConsumer: cro_msg_competing_consumers_1.CompetingConsumer,
+        Producer: cro_msg_competing_consumers_1.Producer,
+    };
+    Messaging.Errors = {
+        JOB_NOT_SUPPORTED: cro_msg_competing_consumers_2.JOB_NOT_SUPPORTED,
+        NO_WORKER_AVAILABLE: cro_msg_competing_consumers_2.NO_WORKER_AVAILABLE,
+    };
+})(Messaging = exports.Messaging || (exports.Messaging = {}));
+;
+var cro_msg_request_reply_2 = require("./libs/cro.msg.request-reply");
+Object.defineProperty(exports, "Requestor", { enumerable: true, get: function () { return cro_msg_request_reply_2.Requestor; } });
+Object.defineProperty(exports, "Replier", { enumerable: true, get: function () { return cro_msg_request_reply_2.Replier; } });

package/dist/cachearoo.d.ts

@@ -0,0 +1,19 @@
+import { Cachearoo, CachearooSettings, RequestOptions } from './libs/cro';
+import { CompetingConsumer, Producer } from './libs/cro.msg.competing-consumers';
+import { Requestor, Replier } from './libs/cro.msg.request-reply';
+export declare namespace Messaging {
+    const RequestReply: {
+        Requestor: typeof Requestor;
+        Replier: typeof Replier;
+    };
+    const CompetingConsumers: {
+        CompetingConsumer: typeof CompetingConsumer;
+        Producer: typeof Producer;
+    };
+    const Errors: {
+        JOB_NOT_SUPPORTED: number;
+        NO_WORKER_AVAILABLE: number;
+    };
+}
+export { Requestor, Replier } from './libs/cro.msg.request-reply';
+export { Cachearoo, CachearooSettings, RequestOptions };