Feature/clearlink (#16)

* POC version created, needs work

* added debug logging for the clearlink

* add some documentation

* version bump for publishing

.vscode/settings.json

@@ -1,3 +1,4 @@
 {
-  "svg.preview.background": "black"
+  "svg.preview.background": "black",
+  "cSpell.words": ["clearlink", "gorgonjs"]
 }

README.md

@@ -19,12 +19,15 @@ npm install @gorgonjs/gorgon
 Having trouble? [join our discord](https://discord.gg/54Z2GscCJr)
 
 ## Directory
-| Package | Version |
-|---------|---------|
-|@gorgonjs/gorgon|![gorgon version](https://img.shields.io/npm/v/@gorgonjs/gorgon.svg?label=%20)|
-|@gorgonjs/react|![gorgon react version](https://img.shields.io/npm/v/@gorgonjs/react.svg?label=%20)|
-|@gorgonjs/file-provider|![gorgon file provider](https://img.shields.io/npm/v/@gorgonjs/file-provider.svg?label=%20)|
+
+| Package                 | Version                                                                                     |
+| ----------------------- | ------------------------------------------------------------------------------------------- |
+| @gorgonjs/gorgon        | ![gorgon version](https://img.shields.io/npm/v/@gorgonjs/gorgon.svg?label=%20)              |
+| @gorgonjs/react         | ![gorgon react version](https://img.shields.io/npm/v/@gorgonjs/react.svg?label=%20)         |
+| @gorgonjs/file-provider | ![gorgon file provider](https://img.shields.io/npm/v/@gorgonjs/file-provider.svg?label=%20) |
+| @gorgonjs/clearlink     | ![gorgon clear link](https://img.shields.io/npm/v/@gorgonjs/clearlink.svg?label=%20)        |
 
 ## Links
+
 - [Official website](http://gorgonjs.dev)
 - [MIT license]('./LICENSE)

clients/react/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gorgonjs/react",
-  "version": "1.5.0",
+  "version": "1.5.1",
   "description": "A simple React caching library for async functions",
   "homepage": "https://gorgonjs.dev",
   "main": "dist/index.umd.js",

examples/clearlink/linkserver.ts

@@ -0,0 +1,4 @@
+import { server } from '@gorgonjs/clearlink';
+console.log('Path: examples/clearlink/linkserver.ts');
+
+server.init({ port: 8686 });

examples/clearlink/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "clearlink-example",
+  "private": true,
+  "version": "0.0.0",
+  "scripts": {
+    "server1": "ts-node server1.ts",
+    "server2": "ts-node server2.ts",
+    "linkserver": "ts-node linkserver.ts"
+  },
+  "dependencies": {
+    "@gorgonjs/clearlink": "workspace:*",
+    "@gorgonjs/gorgon": "workspace:*",
+    "ts-node": "^10.9.1",
+    "ws": "^8.14.1"
+  },
+  "devDependencies": {
+    "@types/node": "^18.11.9",
+    "tslib": "^2.6.2",
+    "typescript": "^4.6.4"
+  }
+}

examples/clearlink/server1.ts

@@ -0,0 +1,10 @@
+import Gorgon from '@gorgonjs/gorgon';
+import { client } from '@gorgonjs/clearlink';
+
+console.log('Path: examples/clearlink/server1.ts');
+client.connect('ws://127.0.0.1:8686');
+client.apply(Gorgon, true);
+
+setInterval(() => {
+  Gorgon.clear('hithereguy');
+}, 8000);

examples/clearlink/server2.ts

@@ -0,0 +1,10 @@
+import Gorgon from '@gorgonjs/gorgon';
+import { client } from '@gorgonjs/clearlink';
+
+console.log('Path: examples/clearlink/server2.ts');
+client.connect('ws://127.0.0.1:8686');
+client.apply(Gorgon, true);
+
+setInterval(() => {
+  Gorgon.clear('otherkeys');
+}, 10000);

examples/clearlink/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "es6",
+    "useDefineForClassFields": true,
+    "allowJs": false,
+    "skipLibCheck": true,
+    "esModuleInterop": false,
+    "allowSyntheticDefaultImports": true,
+    "strict": true,
+    "forceConsistentCasingInFileNames": true,
+    "module": "commonjs",
+    "moduleResolution": "Node",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "composite": true
+  }
+}

library/CHANGELOG.md

@@ -7,16 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.5.0] - 2023-09-11
+
+### Added
+
+- Added a hook system to the cache
+
 ## [1.4.0] - 2022-11-19
 
 ### Added
+
 - added a file provider at @gorgon/file-provider
+
 ### Fixed
+
 - fixed a bug where when you cached something permanently (false) with the non default cache it would use the default provider
 
 ## [1.3.1] - 2022-11-14
 
 ### Added
+
 - added more library type support for older require syntax
 
 ## [1.3.0] - 2022-11-13
@@ -34,5 +44,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [1.2.0] - 2022-11-12
 
 ### Added
+
 - initial release to the public; migrated from @mikevalstar/gorgon
 - code is based off of medusa.js

library/index.ts

@@ -154,10 +154,10 @@ const Gorgon = (() => {
     },
 
     // Clear one or all items in the cache
-    clear: async (key: string, provider?: string) => {
+    clear: async (key: string, provider?: string, hookIdentifier?: string) => {
       var prov = gorgonCore.providers[provider || settings.defaultProvider];
 
-      gorgonCore._callHooks('clear', { key, provider });
+      gorgonCore._callHooks('clear', { key, provider, identifier: hookIdentifier });
 
       // Clear a wildcard search of objects
       if (key && key.indexOf('*') > -1) {
@@ -179,10 +179,10 @@ const Gorgon = (() => {
     },
 
     // Clear all keys/values in the cache
-    clearAll: async (provider?: string) => {
+    clearAll: async (provider?: string, hookIdentifier?: string) => {
       var prov = gorgonCore.providers[provider || settings.defaultProvider];
 
-      gorgonCore._callHooks('clearAll', { provider });
+      gorgonCore._callHooks('clearAll', { provider, identifier: hookIdentifier });
 
       return prov.clear();
     },

library/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gorgonjs/gorgon",
-  "version": "1.5.0",
+  "version": "1.5.1",
   "description": "A simple caching library for async functions",
   "homepage": "https://gorgonjs.dev",
   "main": "./dist/index.umd.js",

plugins/clearlink/LICENCE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Mike Valstar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

plugins/clearlink/README.md

@@ -0,0 +1,48 @@
+# Gorgon ClearLink Plugin
+
+This library implements a link between multiple servers using [@gorgonjs/gorgon](https://www.npmjs.com/package/@gorgonjs/gorgon), please refer to the documentation on https://gorgonjs.dev for full documentation.
+
+Once linked clear commands from one server will be sent to all other servers. Cache invalidation across multiple servers allows you to load balance your application across multiple servers without having to worry about complicated cache invalidation.
+
+WARNING: items are only cleared when manually cleared, auto cleared items (reaching their timeout) or manually replaced items are not cleared.
+
+_Check out a simple example here: https://github.com/mikevalstar/gorgon/tree/main/examples/clearlink_
+
+## Installation
+
+    npm install @gorgonjs/file-clearlink @gorgonjs/gorgon
+
+    yarn add @gorgonjs/file-clearlink @gorgonjs/gorgon
+
+    pnpm add @gorgonjs/file-clearlink @gorgonjs/gorgon
+
+## Example Usage (Client application)
+
+```ts
+import Gorgon from '@gorgonjs/gorgon';
+import { client } from '@gorgonjs/clearlink';
+
+client.connect('ws://127.0.0.1:8686');
+client.apply(Gorgon, true); // debug logging on
+
+setInterval(() => {
+  Gorgon.clear('clearthis');
+}, 8000);
+```
+
+In this example `clearthis` will be cleared on all servers every 8 seconds.
+
+## Example Usage (Server)
+
+The server is designed to run standalone and to simply relay the messages to the clients. It is best if created simply and setup to auto restart.
+
+```ts
+import { server } from '@gorgonjs/clearlink';
+server.init({ port: 8686 });
+```
+
+## Limitations
+
+This plugin does not currently queue up requests when the server is offline. It will simply fail to send the request. This is a planned feature, along with supporting multiple servers for additional redundancy.
+
+Items are only cleared when manually cleared, auto cleared items (reaching their timeout) or manually replaced items (put) are not cleared. put clearing is a planned optional feature.

plugins/clearlink/client.ts

@@ -0,0 +1,62 @@
+import type Gorgon from '@gorgonjs/gorgon';
+import WebSocket from 'ws';
+
+let connection = null as WebSocket | null;
+let gorg = null as typeof Gorgon | null;
+let debug = false;
+
+const client = {
+  connect: (connectionString: string, options?: WebSocket.ClientOptions) => {
+    connection = new WebSocket(connectionString, options);
+    connection.on('error', (...args) => {
+      console.error('Gorgon ClearLink: lost connection: ', ...args);
+    });
+    connection.on('close', () => {
+      console.warn('Gorgon ClearLink: server closed reconnecting in 10 seconds...');
+      setTimeout(() => {
+        client.connect(connectionString, options);
+      }, 10000);
+    });
+    connection.on('open', () => {
+      console.info('Gorgon ClearLink: connected so server: ', connectionString);
+    });
+    connection.on('message', (data: string) => {
+      if (debug) {
+        console.info('Gorgon ClearLink: received: %s %s', data);
+      }
+
+      if (!gorg) {
+        // Not applied yet
+        return;
+      }
+      if (data.slice(0, 6).toString() === 'clear:') {
+        gorg.clear(data.slice(6), undefined, 'clearlink');
+      } else if (data.toString() === 'clearAll') {
+        gorg.clearAll(undefined, 'clearlink');
+      }
+    });
+  },
+  apply: (gorgon: typeof Gorgon, debugLogging = false) => {
+    gorg = gorgon;
+    debug = debugLogging;
+
+    if (debug) {
+      console.info('Gorgon ClearLink: applied');
+      console.info('Gorgon ClearLink: debug logging enabled');
+    }
+
+    gorgon.addHook('clear', (key, input, output) => {
+      if (connection && input.identifier !== 'clearlink') {
+        connection.send('clear:' + input.key);
+      }
+    });
+
+    gorgon.addHook('clearAll', (key, input, output) => {
+      if (connection && input.identifier !== 'clearlink') {
+        connection.send('clearAll');
+      }
+    });
+  },
+};
+
+export default client;

plugins/clearlink/index.ts

@@ -0,0 +1,5 @@
+import client from './client';
+import server from './server';
+
+export { client };
+export { server };

plugins/clearlink/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@gorgonjs/clearlink",
+  "version": "1.5.1",
+  "description": "A simple system cache clearing for Gorgon JS",
+  "homepage": "https://gorgonjs.dev",
+  "main": "dist/index.umd.js",
+  "module": "dist/index.es.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.es.js",
+      "require": "./dist/index.umd.js"
+    }
+  },
+  "scripts": {
+    "test": "vitest",
+    "coverage": "vitest run --coverage",
+    "build": "vite build",
+    "prepublish": "vite build",
+    "tscheck": "tsc --noEmit"
+  },
+  "repository": {
+    "type": "git",
+    "url": "[email protected]:mikevalstar/gorgon.git"
+  },
+  "keywords": [
+    "cache",
+    "promise",
+    "async",
+    "typescript",
+    "bridge"
+  ],
+  "author": "Mike Valstar <[email protected]>",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/mikevalstar/gorgon/issues"
+  },
+  "devDependencies": {
+    "@gorgonjs/gorgon": "^1.5.0",
+    "@types/node": "^18.11.9",
+    "@types/ws": "^8.5.5",
+    "@vitest/coverage-c8": "^0.25.0",
+    "eslint": "^8.11.0",
+    "jest": "^27.5.1",
+    "typescript": "^5.1.6",
+    "vite": "^4.4.4",
+    "vite-plugin-dts": "^3.3.0",
+    "vitest": "^0.33.0"
+  },
+  "jest": {
+    "collectCoverage": true,
+    "timers": "fake"
+  },
+  "dependencies": {
+    "ws": "^8.14.1"
+  }
+}

plugins/clearlink/server.ts

@@ -0,0 +1,24 @@
+import WebSocket, { WebSocketServer, ServerOptions } from 'ws';
+
+const server = {
+  init: (options: ServerOptions) => {
+    const wss = new WebSocketServer(options);
+
+    wss.on('connection', function connection(ws) {
+      ws.on('error', console.error);
+
+      ws.on('message', function message(data) {
+        console.log('received: %s', data);
+
+        wss.clients.forEach(function each(client) {
+          // Send to all open connections except itself
+          if (client.readyState === WebSocket.OPEN && client !== ws) {
+            client.send(data);
+          }
+        });
+      });
+    });
+  },
+};
+
+export default server;