types: add Maybe utility type

packages/context/src/context.ts

@@ -1,4 +1,4 @@
-import type { CB } from 'vest-utils';
+import type { CB, Maybe } from 'vest-utils';
 import {
   assign,
   defaultTo,
@@ -55,7 +55,7 @@ export function createContext<T>(defaultContextValue?: T): CtxApi<T> {
  * When nesting context runs, the the values of the current layer merges with the layers above it.
  */
 export function createCascade<T extends Record<string, unknown>>(
-  init?: (value: Partial<T>, parentContext: T | void) => Nullable<T>
+  init?: (value: Partial<T>, parentContext: Maybe<T>) => Nullable<T>
 ): CtxCascadeApi<T> {
   const ctx = createContext<T>();
 

packages/n4s/src/runtime/enforceEager.ts

@@ -1,4 +1,4 @@
-import { invariant, StringObject, isNullish } from 'vest-utils';
+import { invariant, StringObject, isNullish, Maybe } from 'vest-utils';
 
 import { ctx } from 'enforceContext';
 import { getRule, RuleValue, Args, RuleBase } from 'runtimeRules';
@@ -16,7 +16,7 @@ export default function enforceEager(value: RuleValue): EnforceEagerReturn {
   const target = {
     message,
   } as EnforceEagerReturn;
-  let customMessage: string | undefined = undefined;
+  let customMessage: Maybe<string> = undefined;
 
   // We create a proxy intercepting access to the target object (which is empty).
   const proxy: EnforceEagerReturn = new Proxy(target, {

packages/n4s/src/runtime/genEnforceLazy.ts

@@ -1,4 +1,10 @@
-import { mapFirst, optionalFunctionValue, CB, Stringable } from 'vest-utils';
+import {
+  mapFirst,
+  optionalFunctionValue,
+  CB,
+  Stringable,
+  Maybe,
+} from 'vest-utils';
 
 import { ctx } from 'enforceContext';
 import ruleReturn, { defaultToPassing, RuleDetailedResult } from 'ruleReturn';
@@ -8,7 +14,7 @@ import { transformResult } from 'transformResult';
 // eslint-disable-next-line max-lines-per-function
 export default function genEnforceLazy(key: string) {
   const registeredRules: RegisteredRules = [];
-  let lazyMessage: void | LazyMessage;
+  let lazyMessage: Maybe<LazyMessage>;
 
   return addLazyRule(key);
 

packages/vast/src/vast.ts

@@ -1,4 +1,4 @@
-import { isFunction, optionalFunctionValue } from 'vest-utils';
+import { Maybe, isFunction, optionalFunctionValue } from 'vest-utils';
 
 // eslint-disable-next-line max-lines-per-function
 export function createState(
@@ -53,7 +53,7 @@ export function createState(
   function initKey<S>(
     key: number,
     initialState?: StateInput<S>,
-    prevState?: S | undefined
+    prevState?: Maybe<S>
   ) {
     current().push();
     set(key, optionalFunctionValue(initialState, prevState));
@@ -97,7 +97,7 @@ export type UseState<S> = () => StateHandlerReturn<S>;
 type CreateStateReturn = {
   reset: () => void;
   registerStateKey: <S>(
-    initialState?: StateInput<S> | undefined,
-    onUpdate?: (() => void) | undefined
+    initialState?: Maybe<StateInput<S>>,
+    onUpdate?: Maybe<() => void>
   ) => () => StateHandlerReturn<S>;
 };

packages/vest-utils/src/utilityTypes.ts

@@ -8,6 +8,8 @@ export type CB = (...args: any[]) => any;
 
 export type ValueOf<T> = T[keyof T];
 
-export type Nullish<T = void> = Nullable<T> | undefined;
+export type Nullish<T = void> = Nullable<T> | Maybe<T>;
 
 export type Nullable<T> = T | null;
+
+export type Maybe<T> = T | undefined;

packages/vest-utils/src/vest-utils.ts

@@ -43,4 +43,5 @@ export type {
   ValueOf,
   Nullish,
   Nullable,
+  Maybe,
 } from 'utilityTypes';

packages/vest/src/core/Runtime.ts

@@ -1,4 +1,4 @@
-import { CacheApi, TinyState, cache, seq, tinyState } from 'vest-utils';
+import { CacheApi, Maybe, TinyState, cache, seq, tinyState } from 'vest-utils';
 import { VestRuntime } from 'vestjs-runtime';
 
 import {
@@ -15,7 +15,7 @@ type DoneCallbacks = Array<DoneCallback>;
 type StateExtra = {
   doneCallbacks: TinyState<DoneCallbacks>;
   fieldCallbacks: TinyState<FieldCallbacks>;
-  suiteName: string | undefined;
+  suiteName: Maybe<string>;
   suiteId: string;
   suiteResultCache: CacheApi<SuiteResult<TFieldName, TGroupName>>;
 };

packages/vest/src/core/isolate/IsolateTest/IsolateTestReconciler.ts

@@ -1,4 +1,4 @@
-import { Nullable, deferThrow, isNullish, text } from 'vest-utils';
+import { Maybe, Nullable, deferThrow, isNullish, text } from 'vest-utils';
 import { IsolateInspector, Reconciler } from 'vestjs-runtime';
 import type { Isolate } from 'vestjs-runtime';
 
@@ -110,7 +110,7 @@ function cancelOverriddenPendingTestOnTestReRun(
 
 function throwTestOrderError(
   newNode: IsolateTest,
-  prevNode: Isolate | undefined
+  prevNode: Maybe<Isolate>
 ): void {
   if (IsolateInspector.shouldAllowReorder(newNode)) {
     return;

packages/vest/src/core/test/TestTypes.ts

@@ -1,8 +1,10 @@
+import { Maybe } from 'vest-utils';
+
 import { TFieldName } from 'SuiteResultTypes';
 
 export type TestFn = () => TestResult;
-export type AsyncTest = Promise<string | void | false>;
-export type TestResult = AsyncTest | boolean | void;
+export type AsyncTest = Promise<string | false>;
+export type TestResult = Maybe<AsyncTest | boolean>;
 
 export type WithFieldName<F extends TFieldName = TFieldName> = {
   fieldName: F;

packages/vest/src/core/test/helpers/matchingFieldName.ts

@@ -1,16 +1,18 @@
+import { Maybe } from 'vest-utils';
+
 import { TFieldName } from 'SuiteResultTypes';
 import { WithFieldName } from 'TestTypes';
 
 export function nonMatchingFieldName(
   WithFieldName: WithFieldName<TFieldName>,
-  fieldName?: TFieldName | void
+  fieldName?: Maybe<TFieldName>
 ): boolean {
   return !!fieldName && !matchingFieldName(WithFieldName, fieldName);
 }
 
 export default function matchingFieldName(
   WithFieldName: WithFieldName<TFieldName>,
-  fieldName?: TFieldName | void
+  fieldName?: Maybe<TFieldName>
 ): boolean {
   return !!(fieldName && WithFieldName.fieldName === fieldName);
 }

packages/vest/src/core/test/helpers/matchingGroupName.ts

@@ -1,4 +1,4 @@
-import { bindNot } from 'vest-utils';
+import { Maybe, bindNot } from 'vest-utils';
 
 import { IsolateTest } from 'IsolateTest';
 import { TGroupName } from 'SuiteResultTypes';
@@ -7,7 +7,7 @@ export const nonMatchingGroupName = bindNot(matchingGroupName);
 
 export function matchingGroupName(
   testObject: IsolateTest,
-  groupName: TGroupName | void
+  groupName: Maybe<TGroupName>
 ): boolean {
   return testObject.groupName === groupName;
 }

packages/vest/src/core/test/helpers/shouldUseErrorMessage.ts

@@ -1,9 +1,9 @@
-import { isStringValue, isUndefined } from 'vest-utils';
+import { Maybe, isStringValue, isUndefined } from 'vest-utils';
 
 export function shouldUseErrorAsMessage(
-  message: string | void,
+  message: Maybe<string>,
   error: unknown
-): error is string {
+): error is Maybe<string> {
   // kind of cheating with this safe guard, but it does the job
   return isUndefined(message) && isStringValue(error);
 }

packages/vest/src/core/test/test.ts

@@ -1,4 +1,11 @@
-import { assign, invariant, isFunction, isStringValue, text } from 'vest-utils';
+import {
+  Maybe,
+  assign,
+  invariant,
+  isFunction,
+  isStringValue,
+  text,
+} from 'vest-utils';
 import { Bus, IsolateKey } from 'vestjs-runtime';
 
 import { Events } from 'BusEvents';
@@ -38,7 +45,7 @@ function vestTest<F extends TFieldName>(
 ): IsolateTest {
   const [message, testFn, key] = (
     isFunction(args[1]) ? args : [undefined, ...args]
-  ) as [string | undefined, TestFn, IsolateKey];
+  ) as [Maybe<string>, TestFn, IsolateKey];
 
   validateTestParams(fieldName, testFn);
 

packages/vest/src/hooks/exclusive.ts

@@ -3,6 +3,7 @@ import {
   asArray,
   hasOwnProperty,
   optionalFunctionValue,
+  Maybe,
 } from 'vest-utils';
 
 import { ErrorStrings } from 'ErrorStrings';
@@ -11,9 +12,9 @@ import { TExclusion, useExclusion, useInclusion } from 'SuiteContext';
 import { TFieldName, TGroupName } from 'SuiteResultTypes';
 import { useIsExcludedIndividually } from 'skipWhen';
 
-export type ExclusionItem = string | string[] | undefined;
-export type FieldExclusion<F extends TFieldName> = F | F[] | undefined;
-export type GroupExclusion<G extends TGroupName> = G | G[] | undefined;
+export type ExclusionItem = Maybe<string | string[]>;
+export type FieldExclusion<F extends TFieldName> = Maybe<F | F[]>;
+export type GroupExclusion<G extends TGroupName> = Maybe<G | G[]>;
 
 /**
  * Adds a field or a list of fields into the inclusion list

packages/vest/src/suiteResult/SuiteResultTypes.ts

@@ -1,3 +1,5 @@
+import { Maybe } from 'vest-utils';
+
 import { Severity } from 'Severity';
 import { SummaryFailure } from 'SummaryFailure';
 import { Done } from 'suiteRunResult';
@@ -54,7 +56,7 @@ export type SuiteRunResult<
   done: Done<F, G>;
 };
 
-export type SuiteName = string | undefined;
+export type SuiteName = Maybe<string>;
 
 export type TFieldName<T extends string = string> = T;
 export type TGroupName<G extends string = string> = G;

packages/vest/src/suiteResult/SummaryFailure.ts

@@ -1,3 +1,5 @@
+import { Maybe } from 'vest-utils';
+
 import { IsolateTest } from 'IsolateTest';
 import { TFieldName, TGroupName } from 'SuiteResultTypes';
 import { WithFieldName } from 'TestTypes';
@@ -7,8 +9,8 @@ export class SummaryFailure<F extends TFieldName, G extends TGroupName>
 {
   constructor(
     public fieldName: F,
-    public message: string | undefined,
-    public groupName: G | undefined
+    public message: Maybe<string>,
+    public groupName: Maybe<G>
   ) {}
 
   static fromTestObject<F extends TFieldName, G extends TGroupName>(

packages/vest/src/suiteResult/done/shouldSkipDoneRegistration.ts

@@ -2,7 +2,7 @@
  * DONE is here and not in its own module to prevent circular dependency issues.
  */
 
-import { isFunction, numberEquals } from 'vest-utils';
+import { Maybe, isFunction, numberEquals } from 'vest-utils';
 
 import {
   SuiteResult,
@@ -17,7 +17,7 @@ export function shouldSkipDoneRegistration<
 >(
   callback: (res: SuiteResult<F, G>) => void,
 
-  fieldName: F | undefined,
+  fieldName: Maybe<F>,
   output: SuiteRunResult<F, G>
 ): boolean {
   // If we do not have any test runs for the current field

packages/vest/src/suiteResult/selectors/produceSuiteSummary.ts

@@ -1,4 +1,4 @@
-import { assign, defaultTo } from 'vest-utils';
+import { Maybe, assign, defaultTo } from 'vest-utils';
 
 import { IsolateTest } from 'IsolateTest';
 import { countKeyBySeverity, Severity } from 'Severity';
@@ -136,7 +136,7 @@ function countFailures<F extends TFieldName, G extends TGroupName>(
  * functions as it is really the same, with the difference of "valid" missing in groups
  */
 function appendTestObject(
-  summaryKey: SingleTestSummary | undefined,
+  summaryKey: Maybe<SingleTestSummary>,
   testObject: IsolateTest
 ): SingleTestSummary {
   const { message } = testObject;

packages/vest/src/suiteResult/selectors/suiteSelectors.ts

@@ -1,4 +1,4 @@
-import { isPositive } from 'vest-utils';
+import { Maybe, isPositive } from 'vest-utils';
 
 import { Severity, SeverityCount } from 'Severity';
 import {
@@ -47,7 +47,7 @@ export function bindSuiteSelectors<F extends TFieldName, G extends TGroupName>(
     isValidByGroup: (
       ...args: Parameters<SuiteSelectors<F, G>['isValidByGroup']>
     ) => get().isValidByGroup(...args),
-  } as unknown as SuiteSelectors<F, G>;
+  } as SuiteSelectors<F, G>;
 }
 
 // eslint-disable-next-line max-lines-per-function, max-statements
@@ -136,7 +136,7 @@ export function suiteSelectors<F extends TFieldName, G extends TGroupName>(
     return getFailures(summary, Severity.WARNINGS, fieldName);
   }
 
-  function getWarning(fieldName?: F): void | string | SummaryFailure<F, G> {
+  function getWarning(fieldName?: F): Maybe<string | SummaryFailure<F, G>> {
     return getFailure<F, G>(Severity.WARNINGS, summary, fieldName as F);
   }
 
@@ -146,7 +146,7 @@ export function suiteSelectors<F extends TFieldName, G extends TGroupName>(
     return getFailures(summary, Severity.ERRORS, fieldName);
   }
 
-  function getError(fieldName?: F): void | string | SummaryFailure<F, G> {
+  function getError(fieldName?: F): Maybe<string | SummaryFailure<F, G>> {
     return getFailure<F, G>(Severity.ERRORS, summary, fieldName as F);
   }
 
@@ -167,8 +167,8 @@ export function suiteSelectors<F extends TFieldName, G extends TGroupName>(
 }
 
 export interface SuiteSelectors<F extends TFieldName, G extends TGroupName> {
-  getWarning(fieldName?: F): void | string | SummaryFailure<F, G>;
-  getError(fieldName?: F): void | string | SummaryFailure<F, G>;
+  getWarning(fieldName?: F): Maybe<string | SummaryFailure<F, G>>;
+  getError(fieldName?: F): Maybe<string | SummaryFailure<F, G>>;
   getErrors(fieldName: F): string[];
   getErrors(): FailureMessages;
   getWarnings(): FailureMessages;
@@ -266,17 +266,17 @@ function hasFailures(
 function getFailure<F extends TFieldName, G extends TGroupName>(
   severity: Severity,
   summary: SuiteSummary<F, G>
-): SummaryFailure<F, G> | undefined;
+): Maybe<SummaryFailure<F, G>>;
 function getFailure<F extends TFieldName, G extends TGroupName>(
   severity: Severity,
   summary: SuiteSummary<F, G>,
   fieldName: F
-): string | undefined;
+): Maybe<string>;
 function getFailure<F extends TFieldName, G extends TGroupName>(
   severity: Severity,
   summary: SuiteSummary<F, G>,
   fieldName?: F
-): SummaryFailure<F, G> | string | undefined {
+): Maybe<SummaryFailure<F, G> | string> {
   const summaryKey = summary[severity];
 
   if (!fieldName) {