docs: add jsdoc examples to main exports

packages/vest/src/core/isolate/isolates/each.ts

@@ -4,6 +4,19 @@ import throwError from 'throwError';
 import { IsolateTypes } from 'IsolateTypes';
 import { isolate } from 'isolate';
 
+/**
+ * Iterates over an array of items, allowing to run tests individually per item.
+ *
+ * Requires setting a "key" property on each item tested.
+ *
+ * @example
+ *
+ * each(itemsArray, (item) => {
+ *  test(item.name, 'Item value must not be empty', () => {
+ *    enforce(item.value).isNotEmpty();
+ *  }, item.id)
+ * })
+ */
 export default function each<T>(
   list: T[],
   callback: (arg: T, index: number) => void

packages/vest/src/core/isolate/isolates/group.ts

@@ -7,7 +7,13 @@ import context from 'ctx';
 import { isolate } from 'isolate';
 
 /**
- * Runs a group callback.
+ * Runs tests within a group so that they can be controlled or queried separately.
+ *
+ * @example
+ *
+ * group('group_name', () => {
+ *  // Tests go here
+ * });
  */
 export default function group(groupName: string, tests: () => void): void {
   if (!isStringValue(groupName)) {

packages/vest/src/core/isolate/isolates/omitWhen.ts

@@ -5,6 +5,15 @@ import ctx from 'ctx';
 import { isolate } from 'isolate';
 import { produceDraft, TDraftResult } from 'produceDraft';
 
+/**
+ * Conditionally omits tests from the suite.
+ *
+ * @example
+ *
+ * omitWhen(res => res.hasErrors('username'), () => {
+ *  test('username', 'User already taken', async () => await doesUserExist(username)
+ * });
+ */
 export default function omitWhen(
   conditional: boolean | ((draft: TDraftResult) => boolean),
   callback: (...args: any[]) => void

packages/vest/src/core/isolate/isolates/skipWhen.ts

@@ -5,6 +5,15 @@ import ctx from 'ctx';
 import { isolate } from 'isolate';
 import { produceDraft, TDraftResult } from 'produceDraft';
 
+/**
+ * Conditionally skips running tests within the callback.
+ *
+ * @example
+ *
+ * skipWhen(res => res.hasErrors('username'), () => {
+ *  test('username', 'User already taken', async () => await doesUserExist(username)
+ * });
+ */
 export default function skipWhen(
   conditional: boolean | ((draft: TDraftResult) => boolean),
   callback: (...args: any[]) => void

packages/vest/src/core/suite/create.ts

@@ -24,6 +24,17 @@ type SuiteReturnType<T extends CB> = {
   (...args: Parameters<T>): IVestResult;
 } & CreateProperties;
 
+/**
+ * Creates a new validation suite
+ *
+ * @example
+ *
+ * const suite = create((data = {}) => {
+ *  test("username", "Username is required", () => {
+ *    enforce(data.username).isNotBlank();
+ *  });
+ * });
+ */
 function create<T extends CB>(
   suiteName: string,
   suiteCallback: T

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

@@ -18,7 +18,9 @@ export default function bindTestMemo(test: TTestBase): {
 } {
   const cache = createCache(100); // arbitrary cache size
 
-  // Caches, or returns an already cached test call
+  /**
+   * Caches a test result based on the test's dependencies.
+   */
   function memo(
     fieldName: string,
     ...args: [test: TTestFn, deps: unknown[]]

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

@@ -47,6 +47,15 @@ function testBase(
   return registerPrevRunTest(testObject);
 }
 
+/**
+ * Represents a single case in a validation suite.
+ *
+ * @example
+ *
+ * test("username", "Username is required", () => {
+ *  enforce(data.username).isNotBlank();
+ * });
+ */
 export default assign(testBase, {
   memo: bindTestMemo(testBase),
 });

packages/vest/src/hooks/exclusive.ts

@@ -9,7 +9,11 @@ import { ERROR_HOOK_CALLED_OUTSIDE } from 'hookErrors';
 type TExclusionItem = string | string[] | undefined;
 
 /**
- * Adds a field or multiple fields to inclusion group.
+ * Adds a field or a list of fields into the inclusion list
+ *
+ * @example
+ *
+ * only('username');
  */
 export function only(item: TExclusionItem): void {
   return addTo(ExclusionGroup.ONLY, 'tests', item);
@@ -19,7 +23,11 @@ only.group = (item: TExclusionItem) =>
   addTo(ExclusionGroup.ONLY, 'groups', item);
 
 /**
- * Adds a field or multiple fields to exclusion group.
+ * Adds a field or a list of fields into the exclusion list
+ *
+ * @example
+ *
+ * skip('username');
  */
 export function skip(item: TExclusionItem): void {
   return addTo(ExclusionGroup.SKIP, 'tests', item);

packages/vest/src/hooks/optionalTests.ts

@@ -4,6 +4,17 @@ import { isStringValue } from 'isStringValue';
 
 import { useOptionalFields } from 'stateHooks';
 
+/**
+ * Marks a field as optional, either just by name, or by a given condition.
+ *
+ * @example
+ *
+ * optional('field_name');
+ *
+ * optional({
+ *  username: () => allowUsernameEmpty,
+ * });
+ */
 export default function optional(optionals: TOptionalsInput): void {
   const [, setOptionalFields] = useOptionalFields();