vnopts

vnopts

validate and normalize options

Changelog

Install

# using npm
npm install --save vnopts

# using yarn
yarn add vnopts

Usage

const vnopts = require('vnopts');

const schemas = [
  vnopts.ChoiceSchema.create({
    name: 'parser',
    choices: ['babylon', 'flow', 'typescript'],
  }),
  vnopts.BooleanSchema.create({
    name: 'useFlowParser',
    deprecated: true,
    redirect: value =>
      !value ? undefined : { to: { key: 'parser', value: 'flow' } },
  }),
];

vnopts.normalize({ useFlowParser: true }, schemas);
//=> { parser: "flow" }
// warning: `useFlowParser` is deprecated, we now treat it as `{ parser: "flow" }`.

vnopts.normalize({ parser: 'none' }, schemas);
//=> error: Invalid `parser` value. Expected `"babylon", "flow" or "typescript"`, but received `"none"`.

vnopts.normalize({ parserr: 'typescript' }, schemas);
//=> {}
// warning: Ignored unknown option `{ parserr: "typescript" }`. Did you mean `parser`?

API

Normalizer

/** a shortcut for `new Normalizer(...).normalize(...)` */
function normalize(
  options: object,
  schemas: Schema[],
  opts?: NormalizerOptions,
): object;

class Normalizer {
  constructor(schemas: Schema[], opts?: NormalizerOptions);
  /** normalize the options based on schemas */
  normalize(options: object): object;
  /** clear the deprecation warning history so as to show the same warning again */
  cleanHistory(): void;
}

interface NormalizerOptions {
  logger?: Logger | false;
  descriptor?: Descriptor;
  unknown?: UnknownHandler;
  invalid?: InvalidHandler;
  deprecated?: DeprecatedHandler;
}

Logger

Defaults to console.

interface Logger {
  warn(message: string): void;
}

Descriptor

Defaults to apiDescriptor.

interface Descriptor {
  key: (key: string) => string;
  value: (value: any) => string;
  pair: (pair: { key: string; value: any }) => string;
}

UnknownHandler

Defaults to levenUnknownHandler.

type UnknownHandler = (key: string, value: any, utils: Utils) => void | object;

The returned object will be merged into the output object (and validate its value if the key is known).

InvalidHandler

Defaults to commonInvalidHandler.

type InvalidHandler = (
  key: string,
  value: OptionValue,
  utils: Utils,
) => string | Error;

Returns an error message or the error itself.

DeprecatedHandler

Defaults to commonDeprecatedHandler.

type DeprecatedHandler = (
  keyOrPair: string | { key: string; value: any },
  redirectToKeyOrPair: undefined | string | { key: string; value: any },
  utils: Utils,
) => string;

Returns a deprecation warning.

Schemas

AnySchema

interface AnySchemaParameters extends SchemaHandlers {
  name: string;
}

const schemas = [vnopts.AnySchema.create({ name: 'any' })];

vnopts.normalize({ any: 'hello world' }, schemas);
//=> { any: "hello world" }

vnopts.normalize({ unknown: 'hello world' }, schemas);
//=> {}
// warning: Ignored unknown option `{ unknown: "hello world" }`.

BooleanSchema

interface BooleanSchemaParameters extends SchemaHandlers {
  name: string;
}

const schemas = [vnopts.BooleanSchema.create({ name: 'bool' })];

vnopts.normalize({ bool: true }, schemas);
//=> { bool: true }

vnopts.normalize({ bool: 'hello world' }, schemas);
// error: Invalid `bool` value. Expected `true or false`, but received `"hello world"`.

NumberSchema

interface NumberSchemaParameters extends SchemaHandlers {
  name: string;
}

const schemas = [vnopts.NumberSchema.create({ name: 'num' })];

vnopts.normalize({ num: 1 }, schemas);
//=> { num: 1 }

vnopts.normalize({ num: null }, schemas);
// error: Invalid `num` value. Expected `a number`, but received `null`.

IntegerSchema

interface IntegerSchemaParameters extends SchemaHandlers {
  name: string;
}

const schemas = [vnopts.IntegerSchema.create({ name: 'int' })];

vnopts.normalize({ int: 1 }, schemas);
//=> { int: 1 }

vnopts.normalize({ int: 1.5 }, schemas);
// error: Invalid `int` value. Expected `an integer`, but received `1.5`.

StringSchema

interface StringSchemaParameters extends SchemaHandlers {
  name: string;
}

const schemas = [vnopts.StringSchema.create({ name: 'str' })];

vnopts.normalize({ str: 'hi' }, schemas);
//=> { str: "hi" }

vnopts.normalize({ str: true }, schemas);
// error: Invalid `str` value. Expected `a string`, but received `true`.

ChoiceSchema

interface ChoiceSchemaParameters extends SchemaHandlers {
  name: string;
  choices: Array<
    | undefined
    | null
    | boolean
    | number
    | string
    | {
        value: undefined | null | boolean | number | string;
        deprecated?: boolean;
        redirect?: /* key */ string | { key: string; value: any };
        forward?: /* key */ string | { key: string; value: any };
      }
  >;
}

const schemas = [
  vnopts.ChoiceSchema.create({ name: 'choice', choices: [2, false, 'hey'] }),
];

vnopts.normalize({ choice: 2 }, schemas);
//=> { choice: 2 }

vnopts.normalize({ choice: true }, schemas);
// error: Invalid `choice` value. Expected `false, 2 or "hey"`, but received `true`.

AliasSchema

AliasSchema validates values using the validator from the source schema and redirects all the value to the source key.

interface AliasSchemaParameters extends SchemaHandlers {
  name: string;
  /** the name of the source schema */
  sourceName: string;
}

const schemas = [
  vnopts.BooleanSchema.create({ name: 'source' }),
  vnopts.AliasSchema.create({ name: 'alias', sourceName: 'source' }),
];

vnopts.normalize({ alias: true }, schemas);
//=> { source: true }

vnopts.normalize({ alias: 'invalid' }, schemas);
//=> error: Invalid `alias` value. Expected `true or false`, but received `"invalid"`.

ArraySchema

AliasSchema validates values using the validator from the source schema and redirects all the value to the source key.

interface ArraySchemaParameters extends SchemaHandlers {
  /** defaults to valueSchema's name */
  name?: string;
  valueSchema: Schema;
}

const schemas = [
  vnopts.ArraySchema.create({
    valueSchema: vnopts.ChoiceSchema.create({
      name: 'choices',
      choices: [1, true, 'foo'],
    }),
  }),
];

vnopts.normalize({ choices: [1, 'foo'] }, schemas);
//=> { choices: [1, "foo"] }

vnopts.normalize({ choices: 1 }, schemas);
//=> error: Invalid `choices` value. Expected `an array of true, 1 or "foo"`, but received `1`.

Handlers

Every schema has its own handlers but you can still override/extend them.

interface SchemaHandlers {
  default?: SchemaDefaultHandler;
  expected?: SchemaExpectedHandler;
  validate?: SchemaValidateHandler;
  deprecated?: SchemaDeprecateHandler;
  forward?: SchemaForwardHandler;
  redirect?: SchemaRedirectHandler;
  overlap?: SchemaOverlapHandler;
  preprocess?: SchemaPreprocessHandler;
  postprocess?: SchemaPostprocessHandler;
}

default

type SchemaDefaultHandler =
  | DefaultResult
  | ((schema: Schema, utils: Utils) => DefaultResult);

type DefaultResult = undefined | { value?: any };

undefined represents no default value, default values are wrapped in an object's value field to avoid the ambiguity between missing and undefined.

expected

type SchemaExpectedHandler =
  | ExpectedResult
  | (((schema: Schema, utils: Utils) => ExpectedResult));

type ExpectedResult = string;

Returns the description for the expected value.

validate

type SchemaValidateHandler =
  | ValidateResult
  | ((value: unknown, schema: Schema, utils: Utils) => ValidateResult);

type ValidateResult = boolean | { value: unknown };

Returns a boolean represents if the entire value is valid, or put the invalid value in an object's value field if only part of the value is invalid, this is useful for collection schema like ArraySchema.

deprecated

type SchemaDeprecatedHandler =
  | DeprecatedResult
  | ((value: unknown, schema: Schema, utils: Utils) => DeprecatedResult);

type DeprecatedResult = boolean | { value: any } | Array<{ value: any }>;

Returns true if the entire key is deprecated, false if it's not deprecated, or (an array of) an object with value field if only part of the value is deprecated, one object corresponds to one deprecation warning.

forward

type SchemaForwardHandler =
  | ForwardResult
  | ((value: any, schema: Schema, utils: Utils) => ForwardResult);

type TransferTo = /* key */ string | { key: string; value: any };
type TransferResult = TransferTo | { from?: /* value */ any; to: TransferTo };
type ForwardResult = undefined | TransferResult | Array<TransferResult>;

Returns a key or a key-value pair if the entire value needs to be forwarded there, or (an array of) an object with from/to field if only part of the value needs to be forwarded.

redirect

type SchemaRedirectHandler =
  | RedirectResult
  | ((value: any, schema: Schema, utils: Utils) => RedirectResult);

type RedirectResult =
  | ForwardResult
  | {
      remain?: any;
      redirect: ForwardResult;
    };

Similar to forward but returns an object with remain/redirect field if not the entire value needs to be redirected.

overlap

type SchemaOverlapHandler = (
  currentValue: any,
  newValue: any,
  schema: Schema,
  utils: Utils,
) => any;

Describes what should the normalizer do if there're multiple values assigned to the same key.

preprocess

type SchemaPreprocessHandler = (
  value: unknown,
  schema: Schema,
  utils: Utils,
) => unknown;

The preprocess before passing into the validator.

postprocess

type SchemaPostprocessHandler = (
  value: unknown,
  schema: Schema,
  utils: Utils,
) => unknown;

The postprocess after normalization.

Development

# lint
yarn run lint

# build
yarn run build

# test
yarn run test

License

MIT © Ika

Changelog

1.0.1 (2018-08-29)

Documentations

• tweak wording for commonDeprecatedHandler (#4) (38c25f2)

<a name="1.0.0"></a>