Comments & README

- refactored WorkflowValidator.validationErrors as errors to keep
  consistancy with the underlying validator and other validators
- added missing comments
- fixed README `Add as dependency to your project`, used the scoped name
- added imports in README examples
- added 'validate parts of a workflow' example in README

Signed-off-by: JBBianchi <[email protected]>

Author: JBBianchi

README.md

@@ -24,7 +24,7 @@ npm install && npm run update-code-base && npm run test
 
 
 ### Add as dependency to your project
-You can use [npm link](https://docs.npmjs.com/cli/v7/commands/npm-link) to add the `sdk-typescript` 
+You can use [npm link](https://docs.npmjs.com/cli/v7/commands/npm-link) to add the `@severlessworkflow/sdk-typescript` 
 as dependency in your project.
 
 - Clone the `sdk-typescript` project and build it:
@@ -34,38 +34,40 @@ cd sdk-typescript
 npm install && npm run build
 ```
 
-- Make the package visible globally to npm. Inside the `sdk-typescript` project folder run: 
+- Make the package visible globally to npm. Inside the `sdk-typescript\dist` project folder run: 
 ```sh
 npm link
 ```
 
 - Navigate to the folder/project in which you want to use the sdk, and run the following command: 
 ```sh
-npm link sdk-typescript
+npm link @severlessworkflow/sdk-typescript
 ```
 
-It will create a symbolic link from globally-installed `sdk-typescript` to `node_modules/` of the current folder.
+It will create a symbolic link from globally-installed `@severlessworkflow/sdk-typescript` to `node_modules/` of the current folder.
 
 
 ### How to use
 
 #### Create Workflow using builder API
 
 ```typescript
+import { workflowBuilder, injectstateBuilder, Specification } from '@severlessworkflow/sdk-typescript';
 
 const workflow: Specification.Workflow = workflowBuilder()
   .id("helloworld")
   .version("1.0")
   .name("Hello World Workflow")
   .description("Inject Hello World")
   .start("Hello State")
-  .states([injectstateBuilder()
-    .name("Hello State")
-    .data({
-        "result": "Hello World!"
-    })
-    .end(true)
-    .build()
+  .states([
+    injectstateBuilder()
+      .name("Hello State")
+      .data({
+          "result": "Hello World!"
+      })
+      .end(true)
+      .build()
   ])
   .build();
 ```
@@ -74,6 +76,8 @@ const workflow: Specification.Workflow = workflowBuilder()
 #### Create Workflow using object literals
 
 ```typescript
+import { Specification } from '@severlessworkflow/sdk-typescript';
+
 const workflow: Specification.Workflow = {
   id: 'helloworld',
   version: '1.0',
@@ -97,7 +101,9 @@ const workflow: Specification.Workflow = {
 #### Load a file JSON/YAML to a Workflow instance
 
 ```typescript
-    const workflow = WorkflowConverter.fromString(source)
+import { Specification, WorkflowConverter } from '@severlessworkflow/sdk-typescript';
+
+const workflow: Specification.Workflow = WorkflowConverter.fromString(source);
 ```
 Where `source` is a JSON or a YAML string.
 
@@ -107,19 +113,22 @@ Where `source` is a JSON or a YAML string.
 Having the following workflow instance:
 
 ```typescript
-const workflow = workflowBuilder()
+import { workflowBuilder, injectstateBuilder, Specification } from '@severlessworkflow/sdk-typescript';
+
+const workflow: Specification.Workflow = workflowBuilder()
   .id("helloworld")
   .version("1.0")
   .name("Hello World Workflow")
   .description("Inject Hello World")
   .start("Hello State")
-  .states([injectstateBuilder()
-    .name("Hello State")
-    .data({
-      "result": "Hello World!"
-    })
-    .end(true)
-    .build()
+  .states([
+    injectstateBuilder()
+      .name("Hello State")
+      .data({
+        "result": "Hello World!"
+      })
+      .end(true)
+      .build()
   ])
   .build();
 ```
@@ -128,11 +137,15 @@ You can convert it to its string representation in JSON or YAML format
 by using the static methods `toJson` or `toYaml` respectively:
 
 ```typescript
-    const workflowAsJson = WorkflowConverter.toJson(workflow);
+import { WorkflowConverter } from '@severlessworkflow/sdk-typescript';
+
+const workflowAsJson: string = WorkflowConverter.toJson(workflow);
 ```
 
 ```typescript
-    const workflowAsYaml = WorkflowConverter.toYaml(workflow);
+import { WorkflowConverter } from '@severlessworkflow/sdk-typescript';
+
+const workflowAsYaml: string = WorkflowConverter.toYaml(workflow);
 ```
 
 
@@ -145,8 +158,40 @@ The sdk provides a way to validate if a workflow object is compliant with the se
 - `validate(): boolean`
 
 ```typescript
-const workflowValidator = new WorkflowValidator(workflow);
+import { WorkflowValidator, Specification } from '@severlessworkflow/sdk-typescript';
+
+const workflow: Specification.Workflow = {
+  id: 'helloworld',
+  version: '1.0',
+  name: 'Hello World Workflow',
+  description: 'Inject Hello World',
+  start: 'Hello State',
+  states: [
+    {
+      type: 'inject',
+      name: 'Hello State',
+      end: true,
+      data: {
+        result: "Hello World!"
+      }
+    } as Specification.Injectstate
+  ]
+};
+const workflowValidator: WorkflowValidator = new WorkflowValidator(workflow);
 if (!workflowValidator.validate()) {
-  workflowValidator.validationErrors.forEach(error => console.error(error.message));
+  workflowValidator.errors.forEach(error => console.error(error.message));
+}
+```
+
+You can also validate parts of a workflow using `validators`:
+
+```typescript
+import { ValidateFunction } from 'ajv';
+import { validators, Specification } from '@severlessworkflow/sdk-typescript';
+
+const injectionState: Specification.Injectstate = workflow.states[0];
+const injectionStateValidator: ValidateFunction<Specification.Injectstate> = validators.get('Injectstate');
+if (!injectionStateValidator(injectionState)) {
+  injectionStateValidator.errors.forEach(error => console.error(error.message));
 }
 ```

src/lib/builder.ts

@@ -1,11 +1,14 @@
+/**
+ * Represents a builder proxy
+ */
 export type Builder<T> = {
   build: () => T
 } & {
   [k in keyof T]-?: (arg: T[k]) => Builder<T>
 };
 
 /**
- * A builder factory to proxy properties assignations and validate against schema on build
+ * A factory for builders that proxy properties assignations and validate against schema on build
  * @param {Function} validatorFn The function used to validated and produce the object on build()
  * @returns {Builder} A builder proxy
  */

src/lib/builders/action-builder.ts

@@ -3,6 +3,11 @@ import { Builder, builder } from '../builder';
 import { Specification } from '../definitions';
 import { validators } from '../validators';
 
+/**
+ * The internal function used by the builder proxy to validate and return its underlying object
+ * @param {Specification.Action} data The underlying object
+ * @returns {Specification.Action} The validated underlying object
+ */
 export function actionValidator(data: Specification.Action): (() => Specification.Action) {
   return () => {
     const validate = validators.get('Action');
@@ -17,6 +22,10 @@ export function actionValidator(data: Specification.Action): (() => Specificatio
   };
 }
 
+/**
+ * A factory to create a builder proxy for the type `Specification.Action`
+ * @returns {Specification.Action} A builder for `Specification.Action`
+ */
 export function actionBuilder(): Builder<Specification.Action> {
   return builder<Specification.Action>(actionValidator);
 }

src/lib/builders/actiondatafilter-builder.ts

@@ -3,6 +3,11 @@ import { Builder, builder } from '../builder';
 import { Specification } from '../definitions';
 import { validators } from '../validators';
 
+/**
+ * The internal function used by the builder proxy to validate and return its underlying object
+ * @param {Specification.Actiondatafilter} data The underlying object
+ * @returns {Specification.Actiondatafilter} The validated underlying object
+ */
 export function actiondatafilterValidator(data: Specification.Actiondatafilter): (() => Specification.Actiondatafilter) {
   return () => {
     const validate = validators.get('Actiondatafilter');
@@ -17,6 +22,10 @@ export function actiondatafilterValidator(data: Specification.Actiondatafilter):
   };
 }
 
+/**
+ * A factory to create a builder proxy for the type `Specification.Actiondatafilter`
+ * @returns {Specification.Actiondatafilter} A builder for `Specification.Actiondatafilter`
+ */
 export function actiondatafilterBuilder(): Builder<Specification.Actiondatafilter> {
   return builder<Specification.Actiondatafilter>(actiondatafilterValidator);
 }

src/lib/builders/branch-builder.ts

@@ -3,6 +3,11 @@ import { Builder, builder } from '../builder';
 import { Specification } from '../definitions';
 import { validators } from '../validators';
 
+/**
+ * The internal function used by the builder proxy to validate and return its underlying object
+ * @param {Specification.Branch} data The underlying object
+ * @returns {Specification.Branch} The validated underlying object
+ */
 export function branchValidator(data: Specification.Branch): (() => Specification.Branch) {
   return () => {
     const validate = validators.get('Branch');
@@ -17,6 +22,10 @@ export function branchValidator(data: Specification.Branch): (() => Specificatio
   };
 }
 
+/**
+ * A factory to create a builder proxy for the type `Specification.Branch`
+ * @returns {Specification.Branch} A builder for `Specification.Branch`
+ */
 export function branchBuilder(): Builder<Specification.Branch> {
   return builder<Specification.Branch>(branchValidator);
 }

src/lib/builders/callbackstate-builder.ts

@@ -3,6 +3,11 @@ import { Builder, builder } from '../builder';
 import { Specification } from '../definitions';
 import { validators } from '../validators';
 
+/**
+ * The internal function used by the builder proxy to validate and return its underlying object
+ * @param {Specification.Callbackstate} data The underlying object
+ * @returns {Specification.Callbackstate} The validated underlying object
+ */
 export function callbackstateValidator(data: Specification.Callbackstate): (() => Specification.Callbackstate) {
   return () => {
     data.type = 'callback';
@@ -18,6 +23,10 @@ export function callbackstateValidator(data: Specification.Callbackstate): (() =
   };
 }
 
+/**
+ * A factory to create a builder proxy for the type `Specification.Callbackstate`
+ * @returns {Specification.Callbackstate} A builder for `Specification.Callbackstate`
+ */
 export function callbackstateBuilder(): Builder<Specification.Callbackstate> {
   return builder<Specification.Callbackstate>(callbackstateValidator);
 }

src/lib/builders/correlation-def-builder.ts

@@ -3,6 +3,11 @@ import { Builder, builder } from '../builder';
 import { Specification } from '../definitions';
 import { validators } from '../validators';
 
+/**
+ * The internal function used by the builder proxy to validate and return its underlying object
+ * @param {Specification.CorrelationDef} data The underlying object
+ * @returns {Specification.CorrelationDef} The validated underlying object
+ */
 export function correlationDefValidator(data: Specification.CorrelationDef): (() => Specification.CorrelationDef) {
   return () => {
     const validate = validators.get('CorrelationDef');
@@ -17,6 +22,10 @@ export function correlationDefValidator(data: Specification.CorrelationDef): (()
   };
 }
 
+/**
+ * A factory to create a builder proxy for the type `Specification.CorrelationDef`
+ * @returns {Specification.CorrelationDef} A builder for `Specification.CorrelationDef`
+ */
 export function correlationDefBuilder(): Builder<Specification.CorrelationDef> {
   return builder<Specification.CorrelationDef>(correlationDefValidator);
 }

src/lib/builders/crondef-builder.ts

@@ -3,6 +3,11 @@ import { Builder, builder } from '../builder';
 import { Specification } from '../definitions';
 import { validators } from '../validators';
 
+/**
+ * The internal function used by the builder proxy to validate and return its underlying object
+ * @param {Specification.Crondef} data The underlying object
+ * @returns {Specification.Crondef} The validated underlying object
+ */
 export function crondefValidator(data: Specification.Crondef): (() => Specification.Crondef) {
   return () => {
     const validate = validators.get('Crondef');
@@ -17,6 +22,10 @@ export function crondefValidator(data: Specification.Crondef): (() => Specificat
   };
 }
 
+/**
+ * A factory to create a builder proxy for the type `Specification.Crondef`
+ * @returns {Specification.Crondef} A builder for `Specification.Crondef`
+ */
 export function crondefBuilder(): Builder<Specification.Crondef> {
   return builder<Specification.Crondef>(crondefValidator);
 }

src/lib/builders/databasedswitch-builder.ts

@@ -3,6 +3,11 @@ import { Builder, builder } from '../builder';
 import { Specification } from '../definitions';
 import { validators } from '../validators';
 
+/**
+ * The internal function used by the builder proxy to validate and return its underlying object
+ * @param {Specification.Databasedswitch} data The underlying object
+ * @returns {Specification.Databasedswitch} The validated underlying object
+ */
 export function databasedswitchValidator(data: Specification.Databasedswitch): (() => Specification.Databasedswitch) {
   return () => {
     data.type = 'switch';
@@ -18,6 +23,10 @@ export function databasedswitchValidator(data: Specification.Databasedswitch): (
   };
 }
 
+/**
+ * A factory to create a builder proxy for the type `Specification.Databasedswitch`
+ * @returns {Specification.Databasedswitch} A builder for `Specification.Databasedswitch`
+ */
 export function databasedswitchBuilder(): Builder<Specification.Databasedswitch> {
   return builder<Specification.Databasedswitch>(databasedswitchValidator);
 }

src/lib/builders/datacondition-builder.ts

@@ -3,6 +3,11 @@ import { Builder, builder } from '../builder';
 import { Specification } from '../definitions';
 import { validators } from '../validators';
 
+/**
+ * The internal function used by the builder proxy to validate and return its underlying object
+ * @param {Specification.Datacondition} data The underlying object
+ * @returns {Specification.Datacondition} The validated underlying object
+ */
 export function dataconditionValidator(data: Specification.Datacondition): (() => Specification.Datacondition) {
   return () => {
     const validate = validators.get('Datacondition');
@@ -17,6 +22,10 @@ export function dataconditionValidator(data: Specification.Datacondition): (() =
   };
 }
 
+/**
+ * A factory to create a builder proxy for the type `Specification.Datacondition`
+ * @returns {Specification.Datacondition} A builder for `Specification.Datacondition`
+ */
 export function dataconditionBuilder(): Builder<Specification.Datacondition> {
   return builder<Specification.Datacondition>(dataconditionValidator);
 }