📚 Update readme, ✨ fix help option for cli

Guy7B · Guy7B · commit 9421a6fdeca5 · 2022-06-04T09:33:22.000+03:00
diff --git a/README.md b/README.md
@@ -22,7 +22,7 @@ Available as a [Serverless plugin](#serverless-plugin), [npm package](#standalon
 - Store preparation data in a private s3 bucket. [Prepare data for your data transformation](#usage-and-command-line-options)
 
 ## Quick Start
-### Serverless plugin
+### ⚡ Serverless plugin
 - Install
 ```bash
 npm install dynamo-data-transform --save-dev
@@ -34,7 +34,7 @@ plugins:
 ```
 - Run
 ```bash
-sls dynamodt list
+sls dynamodt --help
 ```
 
 ### Standalone npm package
@@ -44,11 +44,11 @@ npm install -g dynamo-data-transform
 ```
 - Run the tool
 ```bash
-dynamodt --help
+dynamodt help
 ```
 Or with the shortcut
 ```bash
-ddt --help
+ddt help
 ```
 ### Interactive CLI
 After installing the npm package, run:
@@ -85,69 +85,20 @@ sls dynamodt --help
 ```
 Standalone npm package:
 ```bash
-dynamodt list
+dynamodt help
 ```
 
 
 To list all of the options for a specific command run:
 Serverless plugin:
 ```bash
-sls dynamotdt <command> --help
+sls dynamodt <command> --help
 ```
 
 ## What happens behind the scenes
 - When a data transformation runs for the first time, a record in your table is created. This record is for tracking the executed transformations on a specific table.
 
-
-## The safe data transformation process
-The next section describes how the data transformation process looks like, and the order of each step.
-### Steps
-#### 1st Phase (Add New Resources)
-1. Update the serverless.yml resources (if needed) \
-   Reminder: we are not overriding existing data but creating new. [See some examples](#examples)
-1. Your new code should be able to write to your old and new resources which ensures that we can roll back to the previous state and prevent possible data gaps.
-1. Create a pull request and deploy it to every stage in your application
-
-#### 2nd Phase (data transformation)
-
-1. For the first time use `sls dynamodt init` it will generate a folder per table inside the root folder of your service (The name of the folder is the exact name of the table).
-A template data transformation file (v1.js) will be created in each table folder. \
-Implement these functions:
-    1. `transformUp` - transform all of the table items to the new shape (use preparationData if needed).
-    1. `transformDown` - transform all of the table items to the previous shape.
-    1. `prepare` - use this function whenever your data transformation relies on data from external resources.
-
-1. Export these functions and export the version of the current data transformation (set the sequence variable value. It should be the same number of the file name).
-
-1. Preparing data from external resources for the data transformation can be done by using `sls dynamodt prepare`
-
-    Run `sls dynamodt prepare --tNumber <transformation_number> --table <table>`\
-    The data will be stored in a S3 bucket  \
-    The data will be decrypted while running the data transformation script.
-
-1. **Final Step** Create a pull request. \
-   Note that the data transformation runs after an sls deploy command it is integrated \
-   with lifecycle of serverless `after:deploy:deploy` hook.
-
-#### 3rd Phase (Use The New Resources/Data)
-1. Adjust your code to work with the new data. \
-   For example, read from the new index instead of the old one.
-1. Create a pull request with the updated lambdas.
-
-
-#### 4th Phase (Cleanup)
-1. Clean the unused data (attributes/indexes/etc). 
-
-
-### Key Concepts 
-First of all, keep in mind that our mission is to prevent downtime while executing data transformations.
-- Don't override resources/data
-- Your code should be able to work with the old version of the data and keep it updated.
-- To be continued...
-
-
-
-### Data Transformation Script Format (e.g v1_script.js)
+## Data Transformation Script Format (e.g v1_script.js)
 ```js
 const { utils } = require('dynamo-data-transform')
 
@@ -177,12 +128,12 @@ module.exports = {
 ```
 
 
-### Examples
+## Examples
 Examples of data transformation code:
 https://github.com/jitsecurity/dynamo-data-transform/tree/main/examples/serverless-localstack/data-transformations
 
 
-#### Insert records
+### Insert records
 
 ```js
 // Seed users data transformation
@@ -210,7 +161,7 @@ module.exports = {
 };
 ```
 
-#### Add a new field to each record
+### Add a new field to each record
 ```js
 // Adding a "randomNumber" field to each item
 const { utils } = require('dynamo-data-transform');
@@ -241,7 +192,7 @@ module.exports = {
 };
 ```
 
-#### Add field using preparation data (s3 bucket)
+### Add field using preparation data (s3 bucket)
 ```js
 // Adding a new field "hasWikiPage"
 // "hasWikiPage" is a boolean field that is set to true if the item has a wiki page
diff --git a/cli/index.js b/cli/index.js
@@ -23,7 +23,7 @@ const options = parseArgs(process.argv.slice(2),{
 
 (() => {
   const [command] = options._;
-  if(command === 'list') {
+  if(command === 'help' || !command) {
     console.info('Available commands:');
     Object.entries(COMMAND_DESCRIPTION).forEach(([key, value]) => {
       console.info(`  ${key} - ${value}\n`);
diff --git a/docs/images/undraw_data_extraction_re_0rd3.svg b/docs/images/undraw_data_extraction_re_0rd3.svg
diff --git a/docs/zero_downtime_data_transformation_process.md b/docs/zero_downtime_data_transformation_process.md
@@ -0,0 +1,45 @@
+# The safe data transformation process
+The next section describes how the data transformation process looks like, and the order of each step.
+## Steps
+### 1st Phase (Add New Resources)
+1. Update the table resources if needed \
+   Reminder: we are not overriding existing data but creating new.
+1. Your new code should be able to write to your old and new resources which ensures that we can roll back to the previous state and prevent possible data gaps.
+1. Create a pull request and deploy it to every stage in your application
+
+### 2nd Phase (data transformation)
+
+1. For the first time use `sls dynamodt init` it will generate a folder per table inside the root folder of your service (The name of the folder is the exact name of the table).
+A template data transformation file (v1.js) will be created in each table folder. \
+Implement these functions:
+    1. `transformUp` - transform all of the table items to the new shape (use preparationData if needed).
+    1. `transformDown` - transform all of the table items to the previous shape.
+    1. `prepare` - use this function whenever your data transformation relies on data from external resources.
+
+1. Export these functions and export the version of the current data transformation (set the sequence variable value. It should be the same number of the file name).
+
+1. Preparing data from external resources for the data transformation can be done by using `sls dynamodt prepare`
+
+    Run `sls dynamodt prepare --tNumber <transformation_number> --table <table>`\
+    The data will be stored in a S3 bucket  \
+    The data will be decrypted while running the data transformation script.
+
+1. **Final Step** Create a pull request. \
+   Note that the data transformation runs after an sls deploy command it is integrated \
+   with lifecycle of serverless `after:deploy:deploy` hook.
+
+### 3rd Phase (Use The New Resources/Data)
+1. Adjust your code to work with the new data. \
+   For example, read from the new index instead of the old one.
+1. Create a pull request with the updated lambdas.
+
+
+### 4th Phase (Cleanup)
+1. Clean the unused data (attributes/indexes/etc). 
+
+
+### Key Concepts 
+First of all, keep in mind that our mission is to prevent downtime while executing data transformations.
+- Don't override resources/data
+- Your code should be able to work with the old version of the data and keep it updated.
+- Prefer multiple data transformations over complex one.
