From 0c39837bb56c374bd14b20767677db2e64810ac6 Mon Sep 17 00:00:00 2001 From: devlinjunker Date: Sun, 22 Mar 2020 11:23:41 -0700 Subject: [PATCH] updated readmes more and added .madgerc --- .madgerc | 3 +++ README.logging.md | 14 +++++----- README.setup.md | 7 ++--- package-lock.json | 8 +++--- package.json | 2 +- scripts/hooks/README.hooks.md | 10 +++++++- src/dataservices/README.dataservices.md | 31 +++++++++------------- src/helpers/README.helpers.md | 34 ++++++++++++++++++------- 8 files changed, 66 insertions(+), 43 deletions(-) create mode 100644 .madgerc diff --git a/.madgerc b/.madgerc new file mode 100644 index 0000000..d3397ec --- /dev/null +++ b/.madgerc @@ -0,0 +1,3 @@ +{ + "excludeRegExp": [".*\\.spec\\.js", "package\\.json"] +} diff --git a/README.logging.md b/README.logging.md index 29b8912..f9b1f26 100644 --- a/README.logging.md +++ b/README.logging.md @@ -2,7 +2,7 @@ We are currently using pino for logging. Pino logs objects/messages directly to streams so other processes can actually handle formatting or other log actions (this is because Node is single threaded, so smarter to create -another process to manage the logs). We store all of these files in `/pino.log` +another process to manage the logs). We store all of these logs in `/pino.log` ## Configurations @@ -39,12 +39,12 @@ controller({ params, logger }: HapiRequest) { ## Other processes -Other node processes should be spawned (in production and development), here are some examples of processes -we recommend: +By design, pino just outputs logs to be used by other "transporters" (other node processes spawned in +production and development) for reacting to, and viewing these logs. here are some examples of processes +we recommend implementing: ### Logrotate -By design, pino just outputs logs to be used by other "transporters". Log Rotation should be handled via -another service as described in the [pino documention](http://getpino.io/#/docs/help?id=log-rotation) +Log Rotation on production servers should be handled via another service as described in the [pino documention](http://getpino.io/#/docs/help?id=log-rotation) ### Pino-Pretty Displays the logs in a prettier format that makes it easier to see the data, however takes up more space. @@ -97,8 +97,10 @@ e.g. ## Notes/Ideas -- Log Helper for use in the dataservices +- Trace logging any external requests/responses +- Logger Helper for use in the dataservices - goaccess? - websocket? endpoint that shows logs in real time - docs page for logs (searching?) - Elasticsearch/Logstash/Kibana +- logrotate on production diff --git a/README.setup.md b/README.setup.md index 9bf6fcd..f16fc7a 100644 --- a/README.setup.md +++ b/README.setup.md @@ -5,7 +5,7 @@ manage node versions is by using the [Node Version Manager](https://github.com/n in the project to help reference this minimum node version. Use `nvm use 10` to switch node versions after installing a new Node version. **Then you should install all -project dependencies**([github](https://github.com/devlinjunker/template.node.hapi/blob/master/package.json#L30)) +project dependencies**([github](https://github.com/devlinjunker/template.node.hapi/blob/master/package.json#L30)) with `npm install` (or `npm install -D` if development work is planned). This should install the Hapi Server Framework, MariaDB and other libraries used in this project. @@ -30,7 +30,7 @@ and create Postman test suites based on these files) ## Webpack Webpack config file([github](https://github.com/devlinjunker/template.node.hapi/blob/master/webpack.config.js)) -is used to manage our webpack build to compile the application. +is used to manage our webpack build to compile the application. In this file we: - designate the files that will be created with the build @@ -52,7 +52,7 @@ The Dependency Graph is created with [Madge](https://github.com/pahen/madge) and install both in order to update the dependency graph. I didn't include these in the package.json dependencies because I felt this is more than is needed to develop a working app or even write basic documentation. -Install madge with `npm install madge` and install graphviz with `brew install graphviz` or +Install madge with `npm install -g madge` and install graphviz with `brew install graphviz` or `port install graphviz` (for OSX) I split this out to a separate npm script: `npm run doc-image` @@ -60,3 +60,4 @@ I split this out to a separate npm script: `npm run doc-image` ## Notes/Ideas - **IDEA:** init scripts with installation and SQL setup + - Explore madge options: https://www.npmjs.com/package/madge#configuration diff --git a/package-lock.json b/package-lock.json index 9289388..615522c 100644 --- a/package-lock.json +++ b/package-lock.json @@ -2650,7 +2650,7 @@ "args": { "version": "5.0.1", "resolved": "https://registry.npmjs.org/args/-/args-5.0.1.tgz", - "integrity": "sha512-1kqmFCFsPffavQFGt8OxJdIcETti99kySRUPMpOhaGjL6mRJn8HFU1OxKY5bMqfZKUwTQc1mZkAjmGYaVOHFtQ==", + "integrity": "sha1-S/KY35CkeZoJUhNixXknjML912E=", "requires": { "camelcase": "5.0.0", "chalk": "2.4.2", @@ -4289,7 +4289,7 @@ "dateformat": { "version": "3.0.3", "resolved": "https://registry.npmjs.org/dateformat/-/dateformat-3.0.3.tgz", - "integrity": "sha512-jyCETtSl3VMZMWeRo7iY1FL19ges1t55hMo5yaam4Jrsm5EPL89UQkoQRyiI+Yf4k8r2ZpdngkV8hr1lIdjb3Q==" + "integrity": "sha1-puN0maTZqc+F71hyBE1ikByYia4=" }, "debug": { "version": "2.6.9", @@ -8830,7 +8830,7 @@ "mri": { "version": "1.1.4", "resolved": "https://registry.npmjs.org/mri/-/mri-1.1.4.tgz", - "integrity": "sha512-6y7IjGPm8AzlvoUrwAaw1tLnUBudaS3752vcd8JtrpGGQn+rXIe63LFVHm/YMwtqAuh+LJPCFdlLYPWM1nYn6w==" + "integrity": "sha1-fLHdG5tAkF8frAU6viW2cg9EdEo=" }, "ms": { "version": "2.0.0", @@ -11227,7 +11227,7 @@ "split2": { "version": "3.1.1", "resolved": "https://registry.npmjs.org/split2/-/split2-3.1.1.tgz", - "integrity": "sha512-emNzr1s7ruq4N+1993yht631/JH+jaj0NYBosuKmLcq+JkGQ9MmTw1RB1fGaTCzUuseRIClrlSLHRNYGwWQ58Q==", + "integrity": "sha1-xR8Y8+BqjERpqqtIdofY2VYWC7Y=", "requires": { "readable-stream": "^3.0.0" }, diff --git a/package.json b/package.json index e5818d3..2634866 100644 --- a/package.json +++ b/package.json @@ -25,7 +25,7 @@ "build": "./node_modules/.bin/webpack", "clean": "rm -rf ./dist", "help": "echo \"$(cat help.txt)\"", - "doc-image": "./node_modules/madge/bin/cli.js ./src -x '.*\\.spec\\.js' -i docs/image/dependency.png & npm run doc" + "doc-image": "madge ./src -i docs/image/dependency.png & npm run doc" }, "husky": { "hooks": { diff --git a/scripts/hooks/README.hooks.md b/scripts/hooks/README.hooks.md index dcdcad6..29f50b6 100644 --- a/scripts/hooks/README.hooks.md +++ b/scripts/hooks/README.hooks.md @@ -1,4 +1,4 @@ -# Git Hooks +# Git Hooks/Workflow We use githooks([github](https://github.com/devlinjunker/template.node.hapi/tree/master/scripts/hooks)) to help clean up and enforce the workflow for developers. This is done with Husky. @@ -12,3 +12,11 @@ Process: 1. Stash uncommited changes 2. Run linting/flow/compliation and tests with npm/webpack 3. Pop uncommitted changes + + +## Github Actions + +We setup github actions on this project so we can attempt to build and run the tests for every PR submitted +against master. + +More to come... diff --git a/src/dataservices/README.dataservices.md b/src/dataservices/README.dataservices.md index 2aa5a5d..c2d3f43 100644 --- a/src/dataservices/README.dataservices.md +++ b/src/dataservices/README.dataservices.md @@ -1,27 +1,20 @@ # Dataservices -Dataservices communicate with storage systems or external APIs to fetch/store data. +Dataservices abstract the communication with storage systems or external APIs to fetch/store data related to a +topic or for a specific UI component. +## Examples -## Hello World - -Simple example of Hello World endpoint plus example with random value and input from path parameter - -## Note Dataservice - +### Note Dataservice Create/Read Note objects out of a mariadb/mysql database ## Notes/Ideas - - RDBMS vs Document store - - CAP theorem stands for C – Consistency, A — Availability, P — Partitioning (or Scalability) and states that having all three properties at the same time is not possible, - - https://medium.com/statuscode/three-reasons-to-use-a-nosql-document-store-for-your-next-web-application-6b9eabffc8d8 - - Document Store: - - use for settings data and where schema will be changed often - - when changes are small crud, based on users interactions? - - when count and aggregate data is useful to end user - - RDBMS: - - less duplicated data, normalized and stored in specific tables - - useful when data changes often - - seems like more useful for storing fact data in ETL processes? - - Q: phoenix? +- Quick storage dataservice (abstracted away from specific object?) + - takes object from post/put request and places in mongodb + - objects indexed by another param + - automatically assigned id + - retrieves with get request + - delete request + - takes multiple object ids + - search/or retrieve by property? diff --git a/src/helpers/README.helpers.md b/src/helpers/README.helpers.md index 91f6283..f78dd38 100644 --- a/src/helpers/README.helpers.md +++ b/src/helpers/README.helpers.md @@ -1,23 +1,39 @@ # Helpers -Helpers are classes that wrap some functionality not associated with an external service +Helpers are classes that modularize some functionality that is useful in the server. -## MariaDB - - connecting with mariadb server +## Examples + +### MariaDB +Helper class for connecting with mariadb server and saving/retrieving rows from tables - query - insert - fetch - fetchOne -## Config - - reading properties from [config file](https://github.com/devlinjunker/template.node.hapi/blob/master/conf/config.yaml#L3) - -## Healthcheck - - Make simple requests to configured DB/External Services to see if available +### Config +Helper class for reading properties from [config file](https://github.com/devlinjunker/template.node.hapi/blob/master/conf/config.yaml#L3) + - provides a typed interface of these properties +### Healthcheck +Helper for building the healthcheck response that is displayed at `` endpoint. + - Determines version/branch and if the server is running properly + - Makes simple requests to configured dependency DB/External Services to see if they are available ## Notes/Ideas + - **IDEA:** Should healthcheck read log file for past minute to see if any errors? - Do we want/need to worry about Dependency Injection/Singletons? - - **IDEA:** Move Server into helpers as `server.helper.js`? + - RDBMS vs Document store + - CAP theorem stands for C – Consistency, A — Availability, P — Partitioning (or Scalability) and states that having all three properties at the same time is not possible, + - https://medium.com/statuscode/three-reasons-to-use-a-nosql-document-store-for-your-next-web-application-6b9eabffc8d8 + - Document Store: + - use for settings data and where schema will be changed often + - when changes are small crud, based on users interactions? + - when count and aggregate data is useful to end user + - RDBMS: + - less duplicated data, normalized and stored in specific tables + - useful when data changes often + - seems like more useful for storing fact data in ETL processes? + - Q: phoenix?