Fixed builders output type

- Fixed the builders output type - Added more samples Signed-off-by: Jean-Baptiste Bianchi <[email protected]>
serverlessworkflow · Jan 13, 2025 · 9760570 · 9760570
1 parent fc5defd
commit 9760570
Show file tree

Hide file tree

Showing 177 changed files with 1,912 additions and 1,090 deletions.
diff --git a/README.md b/README.md
@@ -49,6 +49,8 @@ The fluent builders wrap the core classes and provide a fluent API for construct
 
 The fluent builders are directly exported as `*<desired-type>*Builder`, e.g., `workflowBuilder`.
 
+By default, built objects are self-validated and self-normalized. `BuildOptions` can be passed to the `build()` method to disable validation or normalization.
+
 ### Validation Function
 The SDK includes a validation function to check if objects conform to the expected schema. This function ensures that your workflow objects are correctly structured and meet the required specifications.
 

diff --git a/examples/browser/index.html → examples/browser/using-class.html b/examples/browser/index.html → examples/browser/using-class.html
@@ -9,15 +9,15 @@
 </head>
 
 <body>
-  <div id="output"></div>
+  <pre id="output"></pre>
   <script src="../../dist/umd/index.umd.js"></script>
   <script type="text/javascript">
     (() => {
       const { Classes: { Workflow } } = serverWorkflowSdk;
       const workflow = new Workflow({
         document: {
           dsl: '1.0.0-alpha5',
-          name: 'test',
+          name: 'using-class',
           version: '1.0.0',
           namespace: 'default',
         },
@@ -33,7 +33,7 @@
       });
       try {
         workflow.validate();
-        document.getElementById('output').innerHTML = workflow.serialize('json');
+        document.getElementById('output').innerHTML = `--- YAML ---\n${workflow.serialize()}\n\n--- JSON ---\n${workflow.serialize('json')}`;
       } catch (ex) {
         console.error('Invalid workflow', ex);
       }

diff --git a/examples/browser/using-fluent-api.html b/examples/browser/using-fluent-api.html
@@ -0,0 +1,36 @@
+<!doctype html>
+<html lang="en">
+
+<head>
+  <meta charset="utf-8">
+  <title>Serveless Workflow</title>
+  <base href="/">
+  <meta content="width=device-width, initial-scale=1" name="viewport">
+</head>
+
+<body>
+  <pre id="output"></pre>
+  <script src="../../dist/umd/index.umd.js"></script>
+  <script type="text/javascript">
+    (() => {
+      const { workflowBuilder, documentBuilder, taskListBuilder, setTaskBuilder } = serverWorkflowSdk;
+      try {
+        const workflow = workflowBuilder()
+          .document(documentBuilder().dsl('1.0.0-alpha5').name('using-fluent-api').version('1.0.0').namespace('default').build())
+          .do(
+            taskListBuilder()
+              .push({
+                step1: setTaskBuilder().set({ foo: 'bar' }).build(),
+              })
+              .build(),
+          )
+          .build();
+        document.getElementById('output').innerHTML = `--- YAML ---\n${workflow.serialize()}\n\n--- JSON ---\n${workflow.serialize('json')}`;
+      } catch (ex) {
+        console.error('Invalid workflow', ex);
+      }
+    })();
+  </script>
+</body>
+
+</html>
diff --git a/examples/browser/using-json.html b/examples/browser/using-json.html
@@ -0,0 +1,40 @@
+<!doctype html>
+<html lang="en">
+
+<head>
+  <meta charset="utf-8">
+  <title>Serveless Workflow</title>
+  <base href="/">
+  <meta content="width=device-width, initial-scale=1" name="viewport">
+</head>
+
+<body>
+  <pre id="output"></pre>
+  <script src="../../dist/umd/index.umd.js"></script>
+  <script type="text/javascript">
+    (() => {
+      const { Classes: { Workflow } } = serverWorkflowSdk;
+      const myJsonWorkflow = `{
+        "document": {
+          "dsl": "1.0.0-alpha5",
+          "name": "using-json",
+          "version": "1.0.0",
+          "namespace": "default"
+        },
+        "do": [
+          {
+            "step1": {
+              "set": {
+                "variable": "my first workflow"
+              }
+            }
+          }
+        ]
+      }`;
+      const workflow = Workflow.deserialize(myJsonWorkflow);
+      document.getElementById('output').innerHTML = `--- YAML ---\n${workflow.serialize()}\n\n--- JSON ---\n${workflow.serialize('json')}`;
+    })();
+  </script>
+</body>
+
+</html>
diff --git a/examples/browser/using-plain-object.html b/examples/browser/using-plain-object.html
@@ -0,0 +1,45 @@
+<!doctype html>
+<html lang="en">
+
+<head>
+  <meta charset="utf-8">
+  <title>Serveless Workflow</title>
+  <base href="/">
+  <meta content="width=device-width, initial-scale=1" name="viewport">
+</head>
+
+<body>
+  <pre id="output"></pre>
+  <script src="../../dist/umd/index.umd.js"></script>
+  <script type="text/javascript">
+    (() => {
+      const { Classes, Specification, validate } = serverWorkflowSdk;
+      const workflowDefinition = {
+        document: {
+          dsl: '1.0.0-alpha5',
+          name: 'using-plain-object',
+          version: '1.0.0',
+          namespace: 'default',
+        },
+        do: [
+          {
+            step1: {
+              set: {
+                variable: 'my first workflow',
+              },
+            },
+          },
+        ],
+      }/* as Specification.Workflow // <-- If you're using TypeScript*/;
+      try {
+        validate('Workflow', workflowDefinition);
+        document.getElementById('output').innerHTML = `--- YAML ---\n${Classes.Workflow.serialize(workflowDefinition)}\n\n--- JSON ---\n${Classes.Workflow.serialize(workflowDefinition, 'json')}`;
+      }
+      catch (ex) {
+        console.error('Invalid workflow', ex);
+      }
+    })();
+  </script>
+</body>
+
+</html>
diff --git a/examples/node/index.ts → examples/node/using-class.ts b/examples/node/index.ts → examples/node/using-class.ts
@@ -13,13 +13,13 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { Classes } from '../../dist';
+import { Classes } from /*'@serverlessworkflow/sdk';*/ '../../dist';
 const { Workflow } = Classes;
 
 const workflow = new Workflow({
   document: {
     dsl: '1.0.0-alpha5',
-    name: 'test',
+    name: 'using-class',
     version: '1.0.0',
     namespace: 'default',
   },
@@ -36,7 +36,7 @@ const workflow = new Workflow({
 
 try {
   workflow.validate();
-  console.log(workflow.serialize('json'));
+  console.log(`--- YAML ---\n${workflow.serialize()}\n\n--- JSON ---\n${workflow.serialize('json')}`);
 } catch (ex) {
   console.error('Invalid workflow', ex);
 }
diff --git a/examples/node/using-fluent-api.ts b/examples/node/using-fluent-api.ts
@@ -0,0 +1,39 @@
+/*
+ * Copyright 2021-Present The Serverless Workflow Specification Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import {
+  documentBuilder,
+  setTaskBuilder,
+  taskListBuilder,
+  workflowBuilder,
+} from /*'@serverlessworkflow/sdk';*/ '../../dist';
+
+try {
+  const workflow = workflowBuilder()
+    .document(
+      documentBuilder().dsl('1.0.0-alpha5').name('using-fluent-api').version('1.0.0').namespace('default').build(),
+    )
+    .do(
+      taskListBuilder()
+        .push({
+          step1: setTaskBuilder().set({ foo: 'bar' }).build(),
+        })
+        .build(),
+    )
+    .build();
+  console.log(`--- YAML ---\n${workflow.serialize()}\n\n--- JSON ---\n${workflow.serialize('json')}`);
+} catch (ex) {
+  console.error('Invalid workflow', ex);
+}
diff --git a/examples/node/using-json.ts b/examples/node/using-json.ts
@@ -0,0 +1,22 @@
+import { Classes } from /*'@serverlessworkflow/sdk';*/ '../../dist';
+
+const myJsonWorkflow = `
+{
+  "document": {
+    "dsl": "1.0.0-alpha5",
+    "name": "using-json",
+    "version": "1.0.0",
+    "namespace": "default"
+  },
+  "do": [
+    {
+      "step1": {
+        "set": {
+          "variable": "my first workflow"
+        }
+      }
+    }
+  ]
+}`;
+const workflow = Classes.Workflow.deserialize(myJsonWorkflow);
+console.log(`--- YAML ---\n${workflow.serialize()}\n\n--- JSON ---\n${workflow.serialize('json')}`);
diff --git a/examples/node/using-plain-object.ts b/examples/node/using-plain-object.ts
@@ -0,0 +1,27 @@
+import { Classes, Specification, validate } from /*'@serverlessworkflow/sdk';*/ '../../dist';
+
+const workflowDefinition = {
+  document: {
+    dsl: '1.0.0-alpha5',
+    name: 'using-plain-object',
+    version: '1.0.0',
+    namespace: 'default',
+  },
+  do: [
+    {
+      step1: {
+        set: {
+          variable: 'my first workflow',
+        },
+      },
+    },
+  ],
+} as Specification.Workflow;
+try {
+  validate('Workflow', workflowDefinition);
+  console.log(
+    `--- YAML ---\n${Classes.Workflow.serialize(workflowDefinition)}\n\n--- JSON ---\n${Classes.Workflow.serialize(workflowDefinition, 'json')}`,
+  );
+} catch (ex) {
+  console.error('Invalid workflow', ex);
+}
diff --git a/src/lib/builder.ts b/src/lib/builder.ts
@@ -32,28 +32,28 @@ export type BuildOptions = {
 /**
  * The type of the underlying function called on `build()` for objects
  */
-export type BuildingFunction<T> = (model: Partial<T>, options: BuildOptions) => T;
+export type BuildingFunction<TSpec, TBuilt> = (model: Partial<TSpec>, options: BuildOptions) => TBuilt;
 
 /**
  * The type of the underlying function called on `build()` for arrays
  */
-export type ArrayBuildingFunction<T> = (model: Array<T>, options: BuildOptions) => Array<T>;
+export type ArrayBuildingFunction<TSpec, TBuilt> = (model: Array<TSpec>, options: BuildOptions) => TBuilt;
 
 /**
  * Represents a fluent builder proxy for an object
  */
-export type Builder<T> = {
-  build: (option?: BuildOptions) => T;
+export type Builder<TSpec, TBuilt = TSpec> = {
+  build: (option?: BuildOptions) => TBuilt;
 } & {
-  [K in keyof T]-?: (arg: T[K]) => Builder<T>;
+  [K in keyof TSpec]-?: (arg: TSpec[K]) => Builder<TSpec, TBuilt>;
 };
 
 /**
  * Represents a fluent builder proxy for an array
  */
-export type ArrayBuilder<T> = {
-  push: (item: T) => ArrayBuilder<T>;
-  build: (option?: BuildOptions) => Array<T>;
+export type ArrayBuilder<TSpec, TBuilt> = {
+  push: (item: TSpec) => ArrayBuilder<TSpec, TBuilt>;
+  build: (option?: BuildOptions) => TBuilt;
 };
 
 /**
@@ -62,24 +62,27 @@ export type ArrayBuilder<T> = {
  * @param options The build options
  * @returns
  */
-function defaultBuildingFn<T>(model: Partial<T>, options: BuildOptions): T {
+function defaultBuildingFn<TSpec, TBuilt = TSpec>(model: Partial<TSpec>, options: BuildOptions): TBuilt {
   // prevents @typescript-eslint/no-unused-vars ...
   if (options.validate == null) {
     options.validate = true;
   }
   if (options.normalize == null) {
     options.normalize = true;
   }
-  return model as T;
+  return model as TBuilt;
 }
 
 /**
  * A factory for fluent builders that proxy properties assignations and can validate against schema on build()
  * @param buildingFn The function used to validate and produce the object on build()
  * @returns A fluent builder
  */
-export function builder<T>(model: Partial<T> = {}, buildingFn: BuildingFunction<T> = defaultBuildingFn): Builder<T> {
-  const proxy = new Proxy({} as Builder<T>, {
+export function builder<TSpec, TBuilt = TSpec>(
+  model: Partial<TSpec> = {},
+  buildingFn: BuildingFunction<TSpec, TBuilt> = defaultBuildingFn,
+): Builder<TSpec, TBuilt> {
+  const proxy = new Proxy({} as Builder<TSpec, TBuilt>, {
     get: (_, prop) => {
       if (prop === 'build') {
         return (options?: BuildOptions) => {
@@ -93,7 +96,7 @@ export function builder<T>(model: Partial<T> = {}, buildingFn: BuildingFunction<
           return buildingFn(model, options);
         };
       }
-      return (value: unknown): Builder<T> => {
+      return (value: unknown): Builder<TSpec, TBuilt> => {
         (model as any)[prop.toString()] = value;
         return proxy;
       };
@@ -110,14 +113,14 @@ export function builder<T>(model: Partial<T> = {}, buildingFn: BuildingFunction<
  * @param buildingFn The function used to validate and produce the object on build()
  * @returns A fluent builder
  */
-export function arrayBuilder<T>(
-  model: Array<T> = [],
-  buildingFn: ArrayBuildingFunction<T> = defaultBuildingFn,
-): ArrayBuilder<T> {
+export function arrayBuilder<TSpec, TBuilt>(
+  model: Array<TSpec> = [],
+  buildingFn: ArrayBuildingFunction<TSpec, TBuilt> = defaultBuildingFn,
+): ArrayBuilder<TSpec, TBuilt> {
   if (model != null && !Array.isArray(model)) {
     throw new Error(`The provided model should be an array`);
   }
-  const proxy = new Proxy({} as ArrayBuilder<T>, {
+  const proxy = new Proxy({} as ArrayBuilder<TSpec, TBuilt>, {
     get: (_, prop) => {
       if (prop === 'build') {
         return (options?: BuildOptions) => {
@@ -132,7 +135,7 @@ export function arrayBuilder<T>(
         };
       }
       if (prop === 'push') {
-        return (value: T): ArrayBuilder<T> => {
+        return (value: TSpec): ArrayBuilder<TSpec, TBuilt> => {
           model.push(value);
           return proxy;
         };