@step-forge/step-forge 0.0.7-beta.6 → 0.0.7

package/src/given.ts

@@ -0,0 +1,102 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+import {
+  EmptyDependencies,
+  EmptyObject,
+  GetFunctionArgs,
+  isString,
+  RequiredOrOptional,
+  StepType,
+} from "./builderTypeUtils";
+import { addStep } from "./common";
+
+const givenDependencies =
+  <
+    Statement extends (...args: any[]) => string,
+    ResolvedStepType extends StepType,
+    Variables,
+    GivenState,
+  >(
+    statement: Statement,
+    stepType: ResolvedStepType
+  ) =>
+  <GivenDeps extends RequiredOrOptional<GivenState>>(dependencies: {
+    given: GivenDeps;
+  }) => {
+    type RestrictedGivenState = {
+      [K in keyof GivenState as K extends keyof GivenDeps
+        ? K
+        : never]: GivenDeps[K] extends "optional"
+        ? GivenState[K] | undefined
+        : GivenState[K];
+    };
+    type Dependencies = typeof dependencies & {
+      when: EmptyObject;
+      then: EmptyObject;
+    };
+    const fullDependencies = {
+      ...dependencies,
+      when: {},
+      then: {},
+    };
+    return {
+      step: addStep<
+        ResolvedStepType,
+        Statement,
+        Dependencies,
+        Variables,
+        GivenState,
+        never, // when state
+        never, // then state
+        RestrictedGivenState,
+        never, // restricted when state
+        never // restricted then state
+      >(statement, stepType, fullDependencies),
+    };
+  };
+
+const givenStatement =
+  <ResolvedStepType extends StepType, GivenState>(stepType: ResolvedStepType) =>
+  <Statement extends ((...args: [...any]) => string) | string>(
+    statement: Statement
+  ) => {
+    let normalizedStatement: Statement extends string
+      ? () => string
+      : Statement;
+    if (isString(statement)) {
+      normalizedStatement = (() => statement) as any;
+    } else {
+      normalizedStatement = statement as any;
+    }
+    type NormalizedStatement = typeof normalizedStatement;
+
+    type Variables = Statement extends string ? [] : GetFunctionArgs<Statement>;
+    const dependencyFunc = givenDependencies<
+      NormalizedStatement,
+      ResolvedStepType,
+      Variables,
+      GivenState
+    >(normalizedStatement, stepType);
+    const stepFunc = addStep<
+      ResolvedStepType,
+      NormalizedStatement,
+      EmptyDependencies,
+      Variables,
+      GivenState,
+      never,
+      never,
+      never,
+      never,
+      never
+    >(normalizedStatement, stepType);
+    return {
+      dependencies: dependencyFunc,
+      step: stepFunc,
+    };
+  };
+
+export const givenBuilder = <GivenState>() => {
+  return {
+    statement: givenStatement<"given", GivenState>("given"),
+  };
+};

package/src/index.ts

@@ -0,0 +1,6 @@
+import { givenBuilder } from "./given";
+import { whenBuilder } from "./when";
+import { thenBuilder } from "./then";
+import { BasicWorld } from "./world";
+
+export { givenBuilder, whenBuilder, thenBuilder, BasicWorld };

package/src/then.ts

@@ -0,0 +1,128 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+import {
+  EmptyDependencies,
+  GetFunctionArgs,
+  isString,
+  RequiredOrOptional,
+  StepType,
+} from "./builderTypeUtils";
+import { addStep } from "./common";
+
+const thenDependencies =
+  <
+    Statement extends (...args: any[]) => string,
+    ResolvedStepType extends StepType,
+    Variables,
+    GivenState,
+    WhenState,
+    ThenState,
+  >(
+    statement: Statement,
+    stepType: ResolvedStepType
+  ) =>
+  <
+    GivenDeps extends RequiredOrOptional<GivenState>,
+    WhenDeps extends RequiredOrOptional<WhenState>,
+    ThenDeps extends RequiredOrOptional<ThenState>,
+  >(dependencies: {
+    given?: GivenDeps;
+    when?: WhenDeps;
+    then?: ThenDeps;
+  }) => {
+    type RestrictedGivenState = {
+      [K in keyof GivenState as K extends keyof GivenDeps
+        ? K
+        : never]: GivenDeps[K] extends "optional"
+        ? GivenState[K] | undefined
+        : GivenState[K];
+    };
+    type RestrictedWhenState = {
+      [K in keyof WhenState as K extends keyof WhenDeps
+        ? K
+        : never]: WhenDeps[K] extends "optional"
+        ? WhenState[K] | undefined
+        : WhenState[K];
+    };
+    type RestrictedThenState = {
+      [K in keyof ThenState as K extends keyof ThenDeps
+        ? K
+        : never]: ThenDeps[K] extends "optional"
+        ? ThenState[K] | undefined
+        : ThenState[K];
+    };
+    type Dependencies = {
+      given: GivenDeps;
+      when: WhenDeps;
+      then: ThenDeps;
+    };
+    const fullDependencies: Dependencies = {
+      given: dependencies.given ?? ({} as GivenDeps),
+      when: dependencies.when ?? ({} as WhenDeps),
+      then: dependencies.then ?? ({} as ThenDeps),
+    };
+    return {
+      step: addStep<
+        ResolvedStepType,
+        Statement,
+        Dependencies,
+        Variables,
+        GivenState,
+        WhenState,
+        ThenState,
+        RestrictedGivenState,
+        RestrictedWhenState,
+        RestrictedThenState
+      >(statement, stepType, fullDependencies),
+    };
+  };
+
+const thenStatement =
+  <ResolvedStepType extends StepType, GivenState, WhenState, ThenState>(
+    stepType: ResolvedStepType
+  ) =>
+  <Statement extends ((...args: [...any]) => string) | string>(
+    statement: Statement
+  ) => {
+    let normalizedStatement: Statement extends string
+      ? () => string
+      : Statement;
+    if (isString(statement)) {
+      normalizedStatement = (() => statement) as any;
+    } else {
+      normalizedStatement = statement as any;
+    }
+    type NormalizedStatement = typeof normalizedStatement;
+
+    type Variables = Statement extends string ? [] : GetFunctionArgs<Statement>;
+    const dependencyFunc = thenDependencies<
+      NormalizedStatement,
+      ResolvedStepType,
+      Variables,
+      GivenState,
+      WhenState,
+      ThenState
+    >(normalizedStatement, stepType);
+    const stepFunc = addStep<
+      ResolvedStepType,
+      NormalizedStatement,
+      EmptyDependencies,
+      Variables,
+      GivenState,
+      WhenState,
+      ThenState,
+      never,
+      never,
+      never
+    >(normalizedStatement, stepType);
+    return {
+      dependencies: dependencyFunc,
+      step: stepFunc,
+    };
+  };
+
+export const thenBuilder = <GivenState, WhenState, ThenState>() => {
+  return {
+    statement: thenStatement<"then", GivenState, WhenState, ThenState>("then"),
+  };
+};

package/src/utils.ts

@@ -0,0 +1,74 @@
+import { MergeableWorld } from "./world";
+
+export const requireFromGiven = <G>(
+  keys: (keyof G)[],
+  world: MergeableWorld<G, unknown, unknown>
+) => {
+  keys.forEach(key => {
+    if (!world.given[key]) {
+      throw new Error(`Key ${String(key)} is required in given state`);
+    }
+  });
+  return keys.reduce(
+    (acc, key) => {
+      return {
+        ...acc,
+        [key]: world.given[key],
+      };
+    },
+    {} as { [key in keyof G]: G[key] }
+  );
+};
+export const requireFromWhen = <W>(
+  keys: (keyof W)[],
+  world: MergeableWorld<unknown, W, unknown>
+) => {
+  keys.forEach(key => {
+    if (!world.when[key]) {
+      throw new Error(`Key ${String(key)} is required in when state`);
+    }
+  });
+  return keys.reduce(
+    (acc, key) => {
+      return {
+        ...acc,
+        [key]: world.when[key],
+      };
+    },
+    {} as { [key in keyof W]: W[key] }
+  );
+};
+export const requireFromThen = <T>(
+  keys: (keyof T)[],
+  world: MergeableWorld<unknown, unknown, T>
+) => {
+  keys.forEach(key => {
+    if (!world.then[key]) {
+      throw new Error(`Key ${String(key)} is required in then state`);
+    }
+  });
+  return keys.reduce(
+    (acc, key) => {
+      return {
+        ...acc,
+        [key]: world.then[key],
+      };
+    },
+    {} as { [key in keyof T]: T[key] }
+  );
+};
+
+export const typeCoercer = (value: string) => {
+  // Try to parse as integer first
+  const numberValue = parseInt(value, 10);
+  if (!isNaN(numberValue)) {
+    return numberValue;
+  }
+
+  // Check for boolean values
+  if (value === "true") return true;
+  if (value === "false") return false;
+
+  // Return original string if no other type matches
+  return value;
+};

package/src/when.ts

@@ -0,0 +1,118 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+import {
+  EmptyDependencies,
+  EmptyObject,
+  GetFunctionArgs,
+  isString,
+  RequiredOrOptional,
+  StepType,
+} from "./builderTypeUtils";
+import { addStep } from "./common";
+
+const whenDependencies =
+  <
+    Statement extends (...args: any[]) => string,
+    ResolvedStepType extends StepType,
+    Variables,
+    GivenState,
+    WhenState,
+  >(
+    statement: Statement,
+    stepType: ResolvedStepType
+  ) =>
+  <
+    GivenDeps extends RequiredOrOptional<GivenState>,
+    WhenDeps extends RequiredOrOptional<WhenState>,
+  >(dependencies: {
+    given?: GivenDeps;
+    when?: WhenDeps;
+  }) => {
+    type RestrictedGivenState = {
+      [K in keyof GivenState as K extends keyof GivenDeps
+        ? K
+        : never]: GivenDeps[K] extends "optional"
+        ? GivenState[K] | undefined
+        : GivenState[K];
+    };
+    type RestrictedWhenState = {
+      [K in keyof WhenState as K extends keyof WhenDeps
+        ? K
+        : never]: WhenDeps[K] extends "optional"
+        ? WhenState[K] | undefined
+        : WhenState[K];
+    };
+    type Dependencies = {
+      given: GivenDeps;
+      when: WhenDeps;
+      then: EmptyObject;
+    };
+    const fullDependencies: Dependencies = {
+      given: dependencies.given ?? ({} as GivenDeps),
+      when: dependencies.when ?? ({} as WhenDeps),
+      then: {},
+    };
+    return {
+      step: addStep<
+        ResolvedStepType,
+        Statement,
+        Dependencies,
+        Variables,
+        GivenState,
+        WhenState,
+        never,
+        RestrictedGivenState,
+        RestrictedWhenState,
+        never
+      >(statement, stepType, fullDependencies),
+    };
+  };
+
+const whenStatement =
+  <ResolvedStepType extends StepType, GivenState, WhenState>(
+    stepType: ResolvedStepType
+  ) =>
+  <Statement extends ((...args: [...any]) => string) | string>(
+    statement: Statement
+  ) => {
+    let normalizedStatement: Statement extends string
+      ? () => string
+      : Statement;
+    if (isString(statement)) {
+      normalizedStatement = (() => statement) as any;
+    } else {
+      normalizedStatement = statement as any;
+    }
+    type NormalizedStatement = typeof normalizedStatement;
+
+    type Variables = Statement extends string ? [] : GetFunctionArgs<Statement>;
+    const dependencyFunc = whenDependencies<
+      NormalizedStatement,
+      ResolvedStepType,
+      Variables,
+      GivenState,
+      WhenState
+    >(normalizedStatement, stepType);
+    const stepFunc = addStep<
+      ResolvedStepType,
+      NormalizedStatement,
+      EmptyDependencies,
+      Variables,
+      GivenState,
+      WhenState,
+      never,
+      never,
+      never,
+      never
+    >(normalizedStatement, stepType);
+    return {
+      dependencies: dependencyFunc,
+      step: stepFunc,
+    };
+  };
+
+export const whenBuilder = <GivenState, WhenState>() => {
+  return {
+    statement: whenStatement<"when", GivenState, WhenState>("when"),
+  };
+};

package/src/world.ts

@@ -0,0 +1,90 @@
+import _ from "lodash";
+
+export type WorldState<State> = {
+  readonly [K in keyof State]?: State[K];
+};
+
+export type MergeableWorldState<T> = WorldState<T> & {
+  merge: (newState: Partial<T>) => void;
+};
+
+function mergeCustomizer(objValue: unknown, srcValue: unknown) {
+  if (_.isArray(objValue)) {
+    return objValue.concat(srcValue);
+  } else if (objValue && !_.isPlainObject(objValue) && objValue !== srcValue) {
+    throw new Error(
+      `Merge would have destroyed previous value ${objValue} with ${srcValue}`
+    );
+  }
+  return objValue;
+}
+
+export const createMergeableState = <T>(
+  state: WorldState<T>
+): MergeableWorldState<T> => {
+  return {
+    ...state,
+    merge: (newState: Partial<T>) => {
+      state = _.merge({ ...state }, newState, mergeCustomizer);
+    },
+  };
+};
+
+export type MergeableWorld<Given, When, Then> = {
+  given: MergeableWorldState<Given>;
+  when: MergeableWorldState<When>;
+  then: MergeableWorldState<Then>;
+};
+
+export class BasicWorld<Given, When, Then> {
+  private givenState: WorldState<Given> = {};
+  private whenState: WorldState<When> = {};
+  private thenState: WorldState<Then> = {};
+
+  public get given(): MergeableWorldState<Given> {
+    return {
+      ...this.givenState,
+      merge: (newState: Partial<Given>) => {
+        this.givenState = _.merge(
+          { ...this.givenState },
+          newState,
+          mergeCustomizer
+        );
+      },
+    };
+  }
+
+  public get when(): MergeableWorldState<When> {
+    return {
+      ...this.whenState,
+      merge: (newState: Partial<When>) => {
+        this.whenState = _.merge(
+          { ...this.whenState },
+          newState,
+          mergeCustomizer
+        );
+      },
+    };
+  }
+
+  public get then(): MergeableWorldState<Then> {
+    return {
+      ...this.thenState,
+      merge: (newState: Partial<Then>) => {
+        this.thenState = _.merge(
+          { ...this.thenState },
+          newState,
+          mergeCustomizer
+        );
+      },
+    };
+  }
+}
+
+export const createBasicWorld = <Given, When, Then>(): MergeableWorld<
+  Given,
+  When,
+  Then
+> => {
+  return new BasicWorld<Given, When, Then>();
+};

package/test/givenCompilationTests.ts

@@ -0,0 +1,130 @@
+import { givenBuilder } from "../src/given";
+import { SampleGivenState } from "./testUtils";
+
+// Simplest possible example
+givenBuilder<SampleGivenState>()
+  .statement("Given a user")
+  .step(() => {
+    return {
+      a: "user",
+    };
+  });
+
+// Simple dependency example
+givenBuilder<SampleGivenState>()
+  .statement("Given a user")
+  .dependencies({
+    given: {
+      a: "required",
+    },
+  })
+  .step(({ given }) => {
+    return {
+      b: `I love ${given.a}`,
+    };
+  });
+
+// Simple variables example
+givenBuilder<SampleGivenState>()
+  .statement((v1: string, v2: number) => `Given a user ${v1} ${v2}`)
+  .step(({ variables: [v1, v2] }) => {
+    return {
+      b: `I love ${v1} ${v2}`,
+    };
+  });
+
+// Complex example
+givenBuilder<SampleGivenState>()
+  .statement((v1: string, v2: number) => `Given a user ${v1} ${v2}`)
+  .dependencies({
+    given: {
+      a: "required",
+      b: "optional",
+      c: "required",
+    },
+  })
+  .step(({ variables: [v1, v2], given: { a, b, c } }) => {
+    return {
+      b: `I love ${v1} ${v2} ${a} ${b} ${c}`,
+    };
+  });
+
+// ----- Should not compile section ----
+
+// @ts-expect-error - Should not compile without a statement
+givenBuilder<SampleGivenState>().step(() => {
+  return {
+    a: "user",
+  };
+});
+
+givenBuilder<SampleGivenState>()
+  .statement(() => "Given a user")
+  // @ts-expect-error - Should not compile since no variables are declared
+  .step(({ variables: [v1, v2] }) => {
+    return {
+      a: `I love ${v1} ${v2}`,
+    };
+  });
+
+// TODO: Currently resolves variables to `any[]` which is incorrect
+givenBuilder<SampleGivenState>()
+  .statement("Given a user")
+  // @ts-expect-error - Should not compile since no variables are declared
+  .step(({ variables: [v1, v2] }) => {
+    return {
+      a: `I love ${v1} ${v2}`,
+    };
+  });
+
+givenBuilder<SampleGivenState>()
+  .statement(
+    (v1: string, v2: number, v3: boolean) => `Given a user ${v1} ${v2} ${v3}`
+  )
+  // @ts-expect-error - Should not compile since the number of variables exceeds the number declared
+  .step(({ variables: [v1, v2, v3, v4] }) => {
+    return {
+      a: `I love ${v1} ${v2} ${v3} ${v4}`,
+    };
+  });
+
+givenBuilder<SampleGivenState>()
+  .statement("Given a user")
+  .dependencies({ given: { a: "required" } })
+  .step(({ given }) => {
+    return {
+      // @ts-expect-error - Should not compile if we attempt to access a part of state that was not declared as a dependency
+      b: `I love ${given.b}`,
+    };
+  });
+
+givenBuilder<SampleGivenState>()
+  .statement("a user")
+  // @ts-expect-error - Should not compile if we attempt to access a part of state that was not declared as a dependency
+  .dependencies({ when: { a: "required" } })
+  .step(({ when }) => {
+    return {
+      // @ts-expect-error - Should not compile if we attempt to access a part of state that was not declared as a dependency
+      b: `I love ${when.c}`,
+    };
+  });
+
+givenBuilder<SampleGivenState>()
+  .statement("Given a user")
+  .dependencies({ given: { a: "optional" } })
+  .step(({ given }) => {
+    // @ts-expect-error - Should not compile since a is optional and can be undefined
+    const strictA: string = given.a;
+    return {
+      b: `I love ${strictA}`,
+    };
+  });
+
+givenBuilder<SampleGivenState>()
+  .statement("Given a user")
+  // @ts-expect-error - Should not compile since the return type is not a partial of given state
+  .step(() => {
+    return {
+      f: "hello",
+    };
+  });

package/test/testUtils.ts

@@ -0,0 +1,30 @@
+import { createBasicWorld } from "../src/world";
+
+export const sampleGivenState = {
+  a: "stuff",
+  b: "things",
+  c: 3,
+};
+export type SampleGivenState = typeof sampleGivenState;
+
+export const sampleWhenState = {
+  d: 1,
+  e: "other stuff",
+  f: [3, 4, 5],
+};
+export type SampleWhenState = typeof sampleWhenState;
+
+export const sampleThenState = {
+  g: 1,
+  h: 2,
+  i: { j: "k" },
+};
+export type SampleThenState = typeof sampleThenState;
+
+export const sampleWorld = createBasicWorld<
+  SampleGivenState,
+  SampleWhenState,
+  SampleThenState
+>();
+
+export type SampleWorld = typeof sampleWorld;