From 1b073ac8f69cacce3d47279c6556141049ad3b4d Mon Sep 17 00:00:00 2001 From: Phil Kunz Date: Sat, 17 Mar 2018 17:18:53 +0100 Subject: [PATCH] update readme --- README.md | 78 +++++++++++++++++++++++++++++++++++ docs/index.md | 111 -------------------------------------------------- package.json | 2 +- yarn.lock | 19 ++++----- 4 files changed, 88 insertions(+), 122 deletions(-) delete mode 100644 docs/index.md diff --git a/README.md b/README.md index 44f8bc6..524512e 100644 --- a/README.md +++ b/README.md @@ -25,6 +25,84 @@ easy and secure websocket communication, TypeScript ready Use TypeScript for best in class instellisense. +Under the hood we use socket.io and shortid for managed data exchange. + +### Serverside + +```typescript +import * as smartsocket from 'smartsocket'; +import * as q from q; // q is a promise library + +// The "Smartsocket" listens on a port and can receive new "SocketConnection" requests. +let mySmartsocket = new smartsocket.Smartsocket({ + port: 3000 // the port smartsocket will listen on +}); + +// A "SocketRole" can be referenced by "SocketFunction"s. +// All "SocketRequest"s carry authentication data for a specific "SocketRole". +// "SocketFunction"s know which "SocketRole"s are allowed to execute them +let mySocketRole = new smartsocket.SocketRole({ + name: 'someRoleName', + passwordHash: 'someHashedString' +}); + +// A "SocketFunction" executes a referenced function and passes in any data of the corresponding "SocketRequest". +// The referenced function must return a promise and resolve with data of type any. +// Any "SocketRequest" carries a unique identifier. If the referenced function's promise resolved any passed on argument will be returned to the requesting party +let testSocketFunction1 = new smartsocket.SocketFunction({ + funcName: 'testSocketFunction1', + funcDef: data => { + console.log('testSocketFunction1 executed successfully!'); + }, + allowedRoles: [mySocketRole] // all roles that have access to a specific function +}); + +// A "Smartsocket" exposes a .clientCall() that gets +// 1. the name of the "SocketFunction" on the client side +// 2. the data to pass in +// 3. And a target "SocketConnection" (there can be multiple connections at once) +// any unique id association is done internally +mySmartsocket.clientCall('restart', data, someTargetConnection).then(responseData => {}); +``` + +#### Client side + +```typescript +import * as smartsocket from 'smartsocket'; + +// A "SmartsocketClient" is different from a "Smartsocket" in that it doesn't expose any public address. +// Thus any new "SocketConnection"s must be innitiated from a "SmartsocketClient". +let testSmartsocketClient = new smartsocket.SmartsocketClient({ + port: testConfig.port, + url: 'http://localhost', + password: 'testPassword', + alias: 'testClient1', + role: 'testRole1' +}); + +// You can .connect() and .disconnect() from a "Smartsocket" +testSmartsocketClient.connect().then(() => { + done(); +}); + +// The client can also specify "SocketFunction"s. It can also specify "SocketRole"s in case a client connects to multiple servers at once +let testSocketFunction2 = new smartsocket.SocketFunction({ + funcName: 'testSocketFunction2', + funcDef: data => {}, // the function to execute, has to return promise + allowedRoles: [] +}); + +// A "SmartsocketClient" can call functions on the serverside using .serverCall() analog to the "Smartsocket"'s .clientCall method. +mySmartsocketClient.serverCall('function', functionCallData).then(functionResponseData => { + // the functionResponseData comes from the server... awesome, right? +}); +``` + +> **NOTE:** +> you can easily chain dependent requests on either the server or client side with promises. +> `data` is always a js object that you can design for your specific needs. +> It supports buffers for large binary data network exchange. + For further information read the linked docs at the top of this README. > MIT licensed | **©** [Lossless GmbH](https://lossless.gmbh) diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index 524512e..0000000 --- a/docs/index.md +++ /dev/null @@ -1,111 +0,0 @@ -# smartsocket - -easy and secure websocket communication, TypeScript ready - -## Availabililty - -[![npm](https://pushrocks.gitlab.io/assets/repo-button-npm.svg)](https://www.npmjs.com/package/smartsocket) -[![git](https://pushrocks.gitlab.io/assets/repo-button-git.svg)](https://GitLab.com/pushrocks/smartsocket) -[![git](https://pushrocks.gitlab.io/assets/repo-button-mirror.svg)](https://github.com/pushrocks/smartsocket) -[![docs](https://pushrocks.gitlab.io/assets/repo-button-docs.svg)](https://pushrocks.gitlab.io/smartsocket/) - -## Status for master - -[![build status](https://GitLab.com/pushrocks/smartsocket/badges/master/build.svg)](https://GitLab.com/pushrocks/smartsocket/commits/master) -[![coverage report](https://GitLab.com/pushrocks/smartsocket/badges/master/coverage.svg)](https://GitLab.com/pushrocks/smartsocket/commits/master) -[![npm downloads per month](https://img.shields.io/npm/dm/smartsocket.svg)](https://www.npmjs.com/package/smartsocket) -[![Dependency Status](https://david-dm.org/pushrocks/smartsocket.svg)](https://david-dm.org/pushrocks/smartsocket) -[![bitHound Dependencies](https://www.bithound.io/github/pushrocks/smartsocket/badges/dependencies.svg)](https://www.bithound.io/github/pushrocks/smartsocket/master/dependencies/npm) -[![bitHound Code](https://www.bithound.io/github/pushrocks/smartsocket/badges/code.svg)](https://www.bithound.io/github/pushrocks/smartsocket) -[![TypeScript](https://img.shields.io/badge/TypeScript-2.x-blue.svg)](https://nodejs.org/dist/latest-v6.x/docs/api/) -[![node](https://img.shields.io/badge/node->=%206.x.x-blue.svg)](https://nodejs.org/dist/latest-v6.x/docs/api/) -[![JavaScript Style Guide](https://img.shields.io/badge/code%20style-standard-brightgreen.svg)](http://standardjs.com/) - -## Usage - -Use TypeScript for best in class instellisense. - -Under the hood we use socket.io and shortid for managed data exchange. - -### Serverside - -```typescript -import * as smartsocket from 'smartsocket'; -import * as q from q; // q is a promise library - -// The "Smartsocket" listens on a port and can receive new "SocketConnection" requests. -let mySmartsocket = new smartsocket.Smartsocket({ - port: 3000 // the port smartsocket will listen on -}); - -// A "SocketRole" can be referenced by "SocketFunction"s. -// All "SocketRequest"s carry authentication data for a specific "SocketRole". -// "SocketFunction"s know which "SocketRole"s are allowed to execute them -let mySocketRole = new smartsocket.SocketRole({ - name: 'someRoleName', - passwordHash: 'someHashedString' -}); - -// A "SocketFunction" executes a referenced function and passes in any data of the corresponding "SocketRequest". -// The referenced function must return a promise and resolve with data of type any. -// Any "SocketRequest" carries a unique identifier. If the referenced function's promise resolved any passed on argument will be returned to the requesting party -let testSocketFunction1 = new smartsocket.SocketFunction({ - funcName: 'testSocketFunction1', - funcDef: data => { - console.log('testSocketFunction1 executed successfully!'); - }, - allowedRoles: [mySocketRole] // all roles that have access to a specific function -}); - -// A "Smartsocket" exposes a .clientCall() that gets -// 1. the name of the "SocketFunction" on the client side -// 2. the data to pass in -// 3. And a target "SocketConnection" (there can be multiple connections at once) -// any unique id association is done internally -mySmartsocket.clientCall('restart', data, someTargetConnection).then(responseData => {}); -``` - -#### Client side - -```typescript -import * as smartsocket from 'smartsocket'; - -// A "SmartsocketClient" is different from a "Smartsocket" in that it doesn't expose any public address. -// Thus any new "SocketConnection"s must be innitiated from a "SmartsocketClient". -let testSmartsocketClient = new smartsocket.SmartsocketClient({ - port: testConfig.port, - url: 'http://localhost', - password: 'testPassword', - alias: 'testClient1', - role: 'testRole1' -}); - -// You can .connect() and .disconnect() from a "Smartsocket" -testSmartsocketClient.connect().then(() => { - done(); -}); - -// The client can also specify "SocketFunction"s. It can also specify "SocketRole"s in case a client connects to multiple servers at once -let testSocketFunction2 = new smartsocket.SocketFunction({ - funcName: 'testSocketFunction2', - funcDef: data => {}, // the function to execute, has to return promise - allowedRoles: [] -}); - -// A "SmartsocketClient" can call functions on the serverside using .serverCall() analog to the "Smartsocket"'s .clientCall method. -mySmartsocketClient.serverCall('function', functionCallData).then(functionResponseData => { - // the functionResponseData comes from the server... awesome, right? -}); -``` - -> **NOTE:** -> you can easily chain dependent requests on either the server or client side with promises. -> `data` is always a js object that you can design for your specific needs. -> It supports buffers for large binary data network exchange. - -For further information read the linked docs at the top of this README. - -> MIT licensed | **©** [Lossless GmbH](https://lossless.gmbh) -> | By using this npm module you agree to our [privacy policy](https://lossless.gmbH/privacy.html) - -[![repo-footer](https://pushrocks.gitlab.io/assets/repo-footer.svg)](https://push.rocks) diff --git a/package.json b/package.json index 469c59f..e000a24 100644 --- a/package.json +++ b/package.json @@ -26,7 +26,7 @@ "nodehash": "^1.0.4", "shortid": "^2.2.8", "smartdelay": "^1.0.4", - "smartq": "^1.1.6", + "smartq": "^1.1.8", "socket.io": "^2.0.4", "socket.io-client": "^2.0.4" }, diff --git a/yarn.lock b/yarn.lock index f785a7e..fcfcac4 100644 --- a/yarn.lock +++ b/yarn.lock @@ -19,8 +19,8 @@ resolved "https://registry.yarnpkg.com/@types/chai/-/chai-4.1.2.tgz#f1af664769cfb50af805431c407425ed619daa21" "@types/lodash@^4.14.55", "@types/lodash@^4.14.97": - version "4.14.104" - resolved "https://registry.yarnpkg.com/@types/lodash/-/lodash-4.14.104.tgz#53ee2357fa2e6e68379341d92eb2ecea4b11bb80" + version "4.14.105" + resolved "https://registry.yarnpkg.com/@types/lodash/-/lodash-4.14.105.tgz#9fcc4627a1f98f8f8fce79ddb2bff4afd97e959b" "@types/minimatch@^3.0.3": version "3.0.3" @@ -28,7 +28,7 @@ "@types/node@*": version "9.4.7" - resolved "https://registry.yarnpkg.com/@types/node/-/node-9.4.7.tgz#57d81cd98719df2c9de118f2d5f3b1120dcd7275" + resolved "http://registry.npmjs.org/@types/node/-/node-9.4.7.tgz#57d81cd98719df2c9de118f2d5f3b1120dcd7275" "@types/q@0.x.x": version "0.0.37" @@ -464,8 +464,8 @@ ms@2.0.0: resolved "https://registry.yarnpkg.com/ms/-/ms-2.0.0.tgz#5608aeadfc00be6c2901df5f9861788de0d597c8" nan@^2.3.2: - version "2.9.2" - resolved "https://registry.yarnpkg.com/nan/-/nan-2.9.2.tgz#f564d75f5f8f36a6d9456cca7a6c4fe488ab7866" + version "2.10.0" + resolved "https://registry.yarnpkg.com/nan/-/nan-2.10.0.tgz#96d0cd610ebd58d4b4de9cc0c6828cda99c7548f" negotiator@0.6.1: version "0.6.1" @@ -596,11 +596,10 @@ smartenv@^2.0.0: smartq "^1.1.1" typings-global "^1.0.14" -smartq@^1.1.1, smartq@^1.1.6: - version "1.1.6" - resolved "https://registry.yarnpkg.com/smartq/-/smartq-1.1.6.tgz#0c1ff4336d95e95b4f1fdd8ccd7e2c5a323b8412" +smartq@^1.1.1, smartq@^1.1.6, smartq@^1.1.8: + version "1.1.8" + resolved "https://registry.yarnpkg.com/smartq/-/smartq-1.1.8.tgz#7e2f3b9739eb5d6c9f45f2a86e339ec81e49e8d2" dependencies: - typings-global "^1.0.19" util.promisify "^1.0.0" socket.io-adapter@~1.1.0: @@ -685,7 +684,7 @@ type-detect@^4.0.0: version "4.0.8" resolved "https://registry.yarnpkg.com/type-detect/-/type-detect-4.0.8.tgz#7646fb5f18871cfbb7749e69bd39a6388eb7450c" -typings-global@^1.0.14, typings-global@^1.0.16, typings-global@^1.0.19, typings-global@^1.0.6: +typings-global@^1.0.14, typings-global@^1.0.16, typings-global@^1.0.6: version "1.0.28" resolved "https://registry.yarnpkg.com/typings-global/-/typings-global-1.0.28.tgz#e28cc965476564cbc00e438739e0aa0735d323d4"