validate and normalize options
npm install vnopts
import * as vnopts from '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`?
/** 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
loggerPrintWidth?: number
descriptor?: Descriptor
unknown?: UnknownHandler
invalid?: InvalidHandler
deprecated?: DeprecatedHandler
missing?: IdentifyMissing
required?: IdentifyRequired
preprocess?: (options: Options, utils: Utils) => Options
postprocess?: (
options: Options,
utils: Utils,
) => typeof VALUE_UNCHANGED | { delete?: string[]; override?: Options }
}
Defaults to console.
interface Logger {
warn(message: string): void
}
Defaults to apiDescriptor.
interface Descriptor {
key: (key: string) => string
value: (value: any) => string
pair: (pair: { key: string; value: any }) => string
}
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).
Defaults to commonInvalidHandler.
type InvalidHandler = (
key: string,
value: OptionValue,
utils: Utils,
) => string | Error
Returns an error message or the error itself.
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.
Defaults to () => false.
type IdentifyMissing = (key: string, options: Options) => boolean
Returns a boolean to indicate if key is missing in options.
(!(key in options) is always considered missing.)
Defaults to () => false.
type IdentifyRequired = (key: string) => boolean
Returns a boolean to indicate if key is required in the output.
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" }`.
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"`.
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`.
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`.
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`.
interface ChoiceSchemaParameters extends SchemaHandlers {
name: string
choices: Array<
| undefined
| null
| boolean
| number
| string
| {
value: undefined | null | boolean | number | string
deprecated?: boolean
hidden?: boolean // do not show this value in `expected`
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 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"`.
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`.
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
}
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.
type SchemaExpectedHandler =
| ExpectedResult
| ((schema: Schema, utils: Utils) => ExpectedResult)
type ExpectedResult =
| string
| { text: string }
| {
text?: string
list: {
title: string
values: ExpectedResult[]
}
}
Returns the description for the expected value in the form of text and/or list.
For example the following ExpectedResult:
{
"list": {
"title": "one of the following values",
"values": ["foo", "bar", "baz"]
}
}
will produce the following message in commonInvalidHandler:
Invalid `<key>` value. Expected `one of the following values`, but received `<value>`.
- `"foo"`
- `"bar"`
- `"baz"`
If both text and list are returned,
text will be chosen if its width is the minimum one or its width is less than loggerPrintWidth,
otherwise list.
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.
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.
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.
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.
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.
type SchemaPreprocessHandler = (
value: unknown,
schema: Schema,
utils: Utils,
) => unknown
The preprocess before passing into the validator.
type SchemaPostprocessHandler = (
value: unknown,
schema: Schema,
utils: Utils,
) => unknown
The postprocess after normalization.
# lint
pnpm run lint
# build
pnpm run build
# test
pnpm run test
MIT © Ika
2.0.0 (2023-07-15)
missing option to customize the definition of missing (#10) (2faf848)preprocess/postprocess option (#12) (b25dd66)required option to throw if the required key is missing (#11) (777e870)preprocess/postprocess to access Utils (#14) (63c3b7c)hidden field for choices (#17) (fe36ccc)postprocess for better performance (#16) (5ae46c2)<a name="1.0.2"></a>
FAQs
validate and normalize options
We found that vnopts demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.