Skip to content

Commit

Permalink
docs: add jsdoc examples to main exports
Browse files Browse the repository at this point in the history
  • Loading branch information
ealush committed Dec 22, 2021
1 parent 0842334 commit bd0c831
Show file tree
Hide file tree
Showing 9 changed files with 82 additions and 4 deletions.
13 changes: 13 additions & 0 deletions packages/vest/src/core/isolate/isolates/each.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
8 changes: 7 additions & 1 deletion packages/vest/src/core/isolate/isolates/group.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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)) {
Expand Down
9 changes: 9 additions & 0 deletions packages/vest/src/core/isolate/isolates/omitWhen.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
9 changes: 9 additions & 0 deletions packages/vest/src/core/isolate/isolates/skipWhen.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
11 changes: 11 additions & 0 deletions packages/vest/src/core/suite/create.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 3 additions & 1 deletion packages/vest/src/core/test/test.memo.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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[]]
Expand Down
9 changes: 9 additions & 0 deletions packages/vest/src/core/test/test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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),
});
Expand Down
12 changes: 10 additions & 2 deletions packages/vest/src/hooks/exclusive.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand All @@ -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);
Expand Down
11 changes: 11 additions & 0 deletions packages/vest/src/hooks/optionalTests.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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();

Expand Down

0 comments on commit bd0c831

Please sign in to comment.