From 118ec84ec5913f9fa7c8214f745316c4eacb4fca Mon Sep 17 00:00:00 2001 From: Phil Kunz Date: Fri, 7 Jul 2017 22:38:10 +0200 Subject: [PATCH] update docs --- README.md | 98 +++++++------------------------------------------- docs/book.json | 15 -------- docs/index.md | 59 ++++++++++++++++++++---------- 3 files changed, 54 insertions(+), 118 deletions(-) delete mode 100644 docs/book.json diff --git a/README.md b/README.md index 9a41a27..6e4d533 100644 --- a/README.md +++ b/README.md @@ -2,100 +2,28 @@ easy and secure websocket communication, TypeScript ready ## Availabililty -[![npm](https://push.rocks/assets/repo-button-npm.svg)](https://www.npmjs.com/package/smartsocket) -[![git](https://push.rocks/assets/repo-button-git.svg)](https://gitlab.com/pushrocks/smartsocket) -[![git](https://push.rocks/assets/repo-button-mirror.svg)](https://github.com/pushrocks/smartsocket) -[![docs](https://push.rocks/assets/repo-button-docs.svg)](https://pushrocks.gitlab.io/smartsocket/docs) +[![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) +[![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 -We recommend the use of TypeScript. -Under the hood we use socket.io and shortid for managed data exchange. +Use TypeScript for best in class instellisense. -### Serverside -```typescript -import * as smartsocket from "smartsocket"; -import * as q from q // q is a promise library +For further information read the linked docs at the top of this README. -// 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 -}); +> MIT licensed | **©** [Lossless GmbH](https://lossless.gmbh) +| By using this npm module you agree to our [privacy policy](https://lossless.gmbH/privacy.html) -// 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. \ No newline at end of file +[![repo-footer](https://pushrocks.gitlab.io/assets/repo-footer.svg)](https://push.rocks) diff --git a/docs/book.json b/docs/book.json deleted file mode 100644 index 2bd173f..0000000 --- a/docs/book.json +++ /dev/null @@ -1,15 +0,0 @@ -{ - "structure": { - "readme": "index.md" - }, - "plugins": [ - "tonic", - "edit-link" - ], - "pluginsConfig": { - "edit-link": { - "base": "https://gitlab.com/pushrocks/npmts/edit/master/docs/", - "label": "Edit on GitLab" - } - } -} \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index 7a39e71..246c0ff 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,47 +1,63 @@ # smartsocket -easy and secure websocket communication, Typescript ready +easy and secure websocket communication, TypeScript ready ## Availabililty -[![npm](https://push.rocks/assets/repo-button-npm.svg)](https://www.npmjs.com/package/smartsocket) -[![git](https://push.rocks/assets/repo-button-git.svg)](https://gitlab.com/pushrocks/smartsocket) -[![git](https://push.rocks/assets/repo-button-mirror.svg)](https://github.com/pushrocks/smartsocket) -[![docs](https://push.rocks/assets/repo-button-docs.svg)](https://pushrocks.gitlab.io/smartsocket/docs) +[![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) +[![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 -We recommend the use of typescript. +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) => { - - }, // the function to execute + console.log('testSocketFunction1 executed successfully!') + }, allowedRoles:[mySocketRole] // all roles that have access to a specific function }); -mySmartsocket.clientCall("","restart",data,someTargetConnection) +// 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) => { }); @@ -51,6 +67,8 @@ mySmartsocket.clientCall("","restart",data,someTargetConnection) ```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", @@ -58,24 +76,22 @@ let testSmartsocketClient = new smartsocket.SmartsocketClient({ 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:[] }); -let functionCalldata = { - funcName: "", - funcData: { - someKey:"someValue" - } -} +// 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? @@ -85,4 +101,11 @@ mySmartsocketClient.serverCall("function",functionCallData) > **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. \ No newline at end of file +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)