Dockyard

Convert yup validation schemas into human-readable documentation objects.

Installation

NPM

npm install @availity/dockyard

Yarn

yarn add @availity/dockyard

Usage

import getRules from '@availity/dockyard';
import * as yup from 'yup';

const schema = yup.object({
  name: yup.string().max(100).required(),
  email: yup.string().email().required(),
  age: yup.number().min(18).max(120),
});

const docs = getRules(schema);
// {
//   name: 'Rules: string, max 100 chars, required.',
//   email: 'Rules: string, email, required.',
//   age: 'Rules: number, min 18, max 120.'
// }

API

getRules(validation, options?)

Converts a yup schema into an object where each key maps to a human-readable string describing the field's validation rules.

Parameters

• validation - A yup schema (typically yup.object())
• options - object. Optional configuration.
  • compileRequiredFields - boolean. Default: false. When true, removes "required" from rule descriptions and adds a requiredFields array to the output listing all required field paths.
  • excludeOneOf - boolean. Default: false. When true, excludes oneOf constraints from the descriptions.
  • excludeTypes - boolean. Default: false. When true, excludes the field type (string, number, etc.) from the descriptions.

Return Value

An object mirroring the schema structure. Each field is a string like "Rules: string, max 100 chars, required.".

For nested objects, the structure includes a _fieldName key with the object-level rules:

docs.address._address; // "Rules: object, required."
docs.address.street; // "Rules: string, max 200 chars."

When compileRequiredFields is true, the returned object also includes a requiredFields array:

{
  requiredFields: ['name', 'email', 'address.street'];
}

Examples

Basic Schema Documentation

import getRules from '@availity/dockyard';
import * as yup from 'yup';

const schema = yup.object({
  name: yup.string().matches('/^[w-]*$/').required(),
  role: yup.string().max(250).oneOf(['admin', 'user', 'guest']),
  tags: yup.array(yup.string().max(50)).max(10),
});

const docs = getRules(schema);
// docs.name => "Rules: string, matches regex /^[w-]*$/, required."
// docs.role => "Rules: string, one of: [admin, user, guest], max 250 chars."
// docs.tags._tags => "Rules: array, max 10."
// docs.tags.* values follow array item schema

With compileRequiredFields

const docs = getRules(schema, { compileRequiredFields: true });
// docs.name => "Rules: string, matches regex /^[w-]*$/."
// docs.requiredFields => ['name']

With excludeOneOf

const docs = getRules(schema, { excludeOneOf: true });
// docs.role => "Rules: string, max 250 chars."
// (the oneOf constraint is excluded)

With excludeTypes

const docs = getRules(schema, { excludeTypes: true });
// docs.name => "Rules: matches regex /^[w-]*$/, required."
// (the "string" type is excluded)

Nested Objects

import getRules from '@availity/dockyard';
import * as yup from 'yup';

const schema = yup.object({
  user: yup
    .object({
      name: yup.string().required(),
      profile: yup.object({
        bio: yup.string().max(500),
      }),
    })
    .required(),
});

const docs = getRules(schema);
// docs.user._user => "Rules: object, required."
// docs.user.name => "Rules: string, required."
// docs.user.profile._profile => "Rules: object."
// docs.user.profile.bio => "Rules: string, max 500 chars."