feat: add validation

Author: mscolnick

examples/nestjs/package.json

@@ -20,7 +20,7 @@
     "test:e2e": "jest --config ./test/jest-e2e.json"
   },
   "dependencies": {
-    "@kinetic-io/actions-express": "^0.2.5",
+    "@kinetic-io/actions-express": "^0.3.0",
     "@nestjs/common": "^9.1.2",
     "@nestjs/core": "^9.1.2",
     "@nestjs/platform-express": "^9.1.2",

packages/actions-app/app/api/actions.ts

@@ -10,6 +10,7 @@ export interface Action {
 }
 
 export type ValidationResponse = string | true;
+export type Validator<T> = (value: T) => ValidationResponse;
 
 export type InputForm<T extends object> = {
   [P in keyof T]: FormPromise<T[P]>;
@@ -28,35 +29,31 @@ export interface InputOutput {
       helperText?: string;
       placeholder?: string;
       type?: 'text' | 'password' | 'email';
-      validation?: (value: string) => ValidationResponse;
+      validation?: Validator<string>;
     }): FormPromise<string>;
-    number(opts: {
-      label: string;
-      helperText?: string;
-      validation?: (value: number) => ValidationResponse;
-    }): FormPromise<number>;
+    number(opts: { label: string; helperText?: string; validation?: Validator<number> }): FormPromise<number>;
   };
   select: {
     radio<T>(opts: {
       label: string;
       helperText?: string;
-      validation?: (value: string) => ValidationResponse;
+      validation?: Validator<T>;
       data: T[];
       getLabel: (item: T) => string;
       getValue: (item: T) => string;
     }): FormPromise<T>;
     dropdown<T>(opts: {
       label: string;
       helperText?: string;
-      validation?: (value: string) => ValidationResponse;
+      validation?: Validator<T>;
       data: T[];
       getLabel: (item: T) => string;
       getValue: (item: T) => string;
     }): FormPromise<T>;
     table<T>(opts: {
       label: string;
       helperText?: string;
-      validation?: (value: string) => ValidationResponse;
+      validation?: Validator<T>;
       data: T[];
       headers: string[];
       initialSelection?: string;
@@ -68,23 +65,23 @@ export interface InputOutput {
     checkbox<T>(opts: {
       label: string;
       helperText?: string;
-      validation?: (value: string) => ValidationResponse;
+      validation?: Validator<T[]>;
       data: T[];
       getLabel: (item: T) => string;
       getValue: (item: T) => string;
     }): FormPromise<T[]>;
     dropdown<T>(opts: {
       label: string;
       helperText?: string;
-      validation?: (value: string) => ValidationResponse;
+      validation?: Validator<T[]>;
       data: T[];
       getLabel: (item: T) => string;
       getValue: (item: T) => string;
     }): FormPromise<T[]>;
     table<T>(opts: {
       label: string;
       helperText?: string;
-      validation?: (value: string) => ValidationResponse;
+      validation?: Validator<T[]>;
       data: T[];
       headers: string[];
       initialSelection?: string[];

packages/actions-app/app/components/forms/FormView.tsx

@@ -91,7 +91,7 @@ function renderFormField(name: string, field: IOForm<any>) {
         return (
           <FormControl isRequired>
             <FormLabel>{field.label}</FormLabel>
-            <Select backgroundColor="white" placeholder={field.placeholder} name={name}>
+            <Select backgroundColor="white" placeholder={field.placeholder} name={name} required>
               {field.data.map((option) => (
                 <option key={option.value} value={option.value}>
                   {option.label}
@@ -126,7 +126,7 @@ function renderFormField(name: string, field: IOForm<any>) {
         return (
           <FormControl isRequired>
             <FormLabel>{field.label}</FormLabel>
-            <select placeholder={field.placeholder} name={name} multiple>
+            <select placeholder={field.placeholder} name={name} multiple required>
               {field.data.map((option) => (
                 <option key={option.value} value={option.value}>
                   {option.label}
@@ -144,7 +144,7 @@ function renderFormField(name: string, field: IOForm<any>) {
             <CheckboxGroup>
               <Stack>
                 {field.data.map((option) => (
-                  <Checkbox name={name} key={option.value} value={option.value}>
+                  <Checkbox required name={name} key={option.value} value={option.value}>
                     {option.label}
                   </Checkbox>
                 ))}
@@ -180,7 +180,8 @@ function renderFormField(name: string, field: IOForm<any>) {
         </FormControl>
       );
     }
-    default:
+    default: {
       break;
+    }
   }
 }

packages/actions-app/app/models/default-actions.server.ts

@@ -14,7 +14,7 @@ export const DEFAULT_ACTIONS: Actions = {
             type: 'text',
             validation: (value) => {
               if (value.length < 3) {
-                return 'Name must be at least 3 characters';
+                return 'Name must be at least 3 characters. Got: ' + value.length;
               }
               return true;
             },
@@ -24,8 +24,8 @@ export const DEFAULT_ACTIONS: Actions = {
             helperText: 'Enter the email of the user',
             type: 'email',
             validation: (value) => {
-              if (value.length < 3) {
-                return 'Email must be at least 3 characters';
+              if (value.length < 5) {
+                return 'Email must be at least 5 characters. Got: ' + value.length;
               }
               return true;
             },
@@ -102,6 +102,6 @@ export const DEFAULT_ACTIONS: Actions = {
   },
 };
 
-function sleep(ms = 2000) {
+function sleep(ms = 10) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }

packages/actions-app/app/models/errors.ts

@@ -0,0 +1,10 @@
+export class ValidationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ValidationError';
+  }
+
+  public static is(err: unknown): err is ValidationError {
+    return err instanceof ValidationError;
+  }
+}

packages/actions-app/app/models/workflows/InputBuilder.ts

@@ -0,0 +1,76 @@
+import { Validator } from '../../api/actions';
+import { IOForm } from '../../types/response';
+import { BreadCrumb } from './bread-crumbs.server';
+import {
+  Normalizer,
+  normalizeAsString,
+  normalizeAsNumber,
+  normalizeAsArray,
+  normalizeAsSingleton,
+} from './normalizers.server';
+
+export function createInput(payload: IOForm) {
+  return new InputBuilder<unknown>(payload);
+}
+
+export interface Input<T> {
+  form: IOForm<T>;
+  normalize: Normalizer<T>;
+  validator: Validator<T>;
+  format: (value: T) => BreadCrumb[] | BreadCrumb;
+}
+
+export class InputBuilder<T> {
+  private normalize!: Normalizer<any>;
+  private validator: Validator<any> = () => true;
+  private format!: (value: T) => BreadCrumb[] | BreadCrumb;
+
+  constructor(private form: IOForm<T>) {}
+
+  public normalizeAsString(): InputBuilder<string> {
+    this.normalize = normalizeAsString as any;
+    return this as any;
+  }
+
+  public normalizeAsNumber(): InputBuilder<number> {
+    this.normalize = normalizeAsNumber as any;
+    return this as any;
+  }
+
+  public normalizeAsArray<U>(): InputBuilder<U[]> {
+    this.normalize = normalizeAsArray as any;
+    return this as any;
+  }
+
+  public normalizeAsSingleton<U>(): InputBuilder<U> {
+    this.normalize = normalizeAsSingleton as any;
+    return this as any;
+  }
+
+  public thenMap<U>(mapper: (value: T) => U): InputBuilder<U> {
+    const normalize = this.normalize;
+    this.normalize = (value) => mapper(normalize(value));
+    return this as any;
+  }
+
+  public validate(validator: Validator<T> | undefined): InputBuilder<T> {
+    if (validator) {
+      this.validator = validator;
+    }
+    return this as any;
+  }
+
+  public formatBreadcrumbs(format: (value: T) => BreadCrumb[] | BreadCrumb): InputBuilder<T> {
+    this.format = format;
+    return this as any;
+  }
+
+  public build(): Input<T> {
+    return {
+      form: this.form,
+      normalize: this.normalize,
+      validator: this.validator,
+      format: this.format,
+    };
+  }
+}

packages/actions-app/app/models/workflows/bread-crumbs.server.ts

@@ -1,6 +1,6 @@
 export interface BreadCrumb {
   key: string;
-  value: string;
+  value: string | number;
 }
 
 export class BreadCrumbs {
@@ -10,6 +10,14 @@ export class BreadCrumbs {
     this.breadcrumbs.push({ key, value });
   }
 
+  public addAll(breadcrumbs: BreadCrumb[] | BreadCrumb): void {
+    if (Array.isArray(breadcrumbs)) {
+      this.breadcrumbs.push(...breadcrumbs);
+    } else {
+      this.breadcrumbs.push(breadcrumbs);
+    }
+  }
+
   public addList(key: string, value: string[]): void {
     this.breadcrumbs.push({ key, value: value.join(', ') });
   }

packages/actions-app/app/models/workflows/client-bridge.server.ts

@@ -0,0 +1,47 @@
+import { ActionViewResponse } from '../../types/response';
+import { defer, DeferredPromise } from '../defer';
+import { ClientFormValue } from './types';
+
+/**
+ * Lives on the server-side.
+ *
+ * Wrapper around client and server communication.
+ * Very simple communication with 2 deferred promises, alternating who has the ball-in-their-court.
+ */
+export class ClientBridge {
+  private clientView: DeferredPromise<ActionViewResponse> = defer();
+  private clientResponse!: DeferredPromise<ClientFormValue>;
+
+  /**
+   * Ask the client a question, send a view.
+   */
+  public askClientQuestion(view: ActionViewResponse): void {
+    // resolve the promise
+    this.clientView.resolve(view);
+    this.clientResponse = defer();
+  }
+
+  /**
+   * Consume response from client
+   */
+  public consumeResponseFromClient(value: ClientFormValue): void {
+    // resolve the promise
+    this.clientResponse.resolve(value);
+    this.clientView = defer();
+  }
+
+  /**
+   * Promise that resolves when the workflow wants as a question.
+   */
+  public waitForWorkflowToAskAQuestion(): Promise<ActionViewResponse> {
+    return this.clientView.promise;
+  }
+
+  /**
+   * Promise that resolves when the client responds.
+   * If the client has already responded, the promise will resolve immediately.
+   */
+  public waitForResponseFromClient(): Promise<ClientFormValue> {
+    return this.clientResponse.promise;
+  }
+}

packages/actions-app/app/models/workflows/normalizers.server.ts

@@ -0,0 +1,49 @@
+import { ValidationError } from '../errors';
+import { ClientFormValue } from './types';
+
+export type Normalizer<T> = (value: ClientFormValue) => T;
+
+export const normalizeAsString: Normalizer<string> = (value) => {
+  if (typeof value === 'string') {
+    return value;
+  }
+
+  return normalizeAsSingleton(value);
+};
+
+export const normalizeAsNumber: Normalizer<number> = (value) => {
+  const str = normalizeAsString(value);
+  const num = Number(str);
+  if (Number.isNaN(num)) {
+    throw new ValidationError('Expected a number, but got ' + str);
+  }
+  return num;
+};
+
+export const normalizeAsArray: Normalizer<any> = <T>(value: T | T[] | undefined | null): T[] => {
+  if (value === undefined || value === null) {
+    return [];
+  }
+  if (Array.isArray(value)) {
+    return value;
+  }
+  return [value];
+};
+
+export const normalizeAsSingleton: Normalizer<any> = <T>(value: T | T[] | undefined | null): T => {
+  if (value === undefined || value === null) {
+    throw new ValidationError('Missing required field.');
+  }
+
+  if (Array.isArray(value)) {
+    if (value.length > 1) {
+      console.log('Expected single value, but got ' + value.length);
+    }
+    if (value.length === 0) {
+      throw new ValidationError('Missing required field.');
+    }
+    return value[0];
+  }
+
+  return value;
+};

packages/actions-app/app/models/workflows/types.ts

@@ -0,0 +1,37 @@
+import { Action } from '../../types';
+import { ActionResponse, ActionRequest } from '../../types/response';
+import { WorkflowId } from '../ids';
+import { Workflow } from './workflow.server';
+
+/**
+ * Possible form values returned by the `form` method.
+ */
+export type ClientFormValue = string | string[] | null | undefined;
+
+export interface WorkflowManager {
+  /**
+   * Get a workflow by its ID.
+   * @param workflowId The ID of the workflow to get.
+   * @returns The workflow, or `undefined` if it doesn't exist.
+   */
+  getWorkflow(workflowId: WorkflowId): Workflow | undefined;
+  /**
+   * Start a workflow.
+   * @param action The action to start the workflow with.
+   * @returns The response to the action.
+   */
+  startWorkflow(action: Action): Promise<ActionResponse>;
+  /**
+   * Pick up a workflow.
+   * @param workflowId The ID of the workflow to pick up.
+   * @returns The response to the action.
+   * @throws If the workflow doesn't exist.
+   */
+  pickUpWorkflow(workflowId: WorkflowId): Promise<ActionResponse>;
+  /**
+   * Continue a workflow.
+   * @param workflowId The ID of the workflow to continue.
+   * @param request The request to continue the workflow with.
+   */
+  continueWorkflow(workflowId: WorkflowId, request: ActionRequest): Promise<ActionResponse>;
+}