Option parser with schema definition and descriptive errors:
const schema = {
port: { default: 3000, type: Number },
public: { default: "public", type: [String, Boolean] }
};
// All of these result in `{ port: 3000, public: "public" }`
optionally(schema); // Uses the defaults
optionally(schema, { port: "3000" }); // Cast to a number since it's possible
optionally(schema, {}, process.env); // `.env` is `PORT=3000`
// Clear error messages:
optionally(schema, { port: "cow" });
// TypeError: The option `port` should be a number like `{ port: 3000 }` instead of the string "cow".
The arguments for each of the options, with all of them being optional:
key | description | type |
---|---|---|
find() |
manually get the value from the params | function |
↳ env |
name of the environment variable to use | string |
↳ arg |
name of the argument to use | string |
↳ inherit |
for subtrees, get the value from parent | boolean, string |
↳ default |
value to use if none is provided | any |
parse() |
parse the previously found value | function |
↳ extend |
extend the default object with the value | boolean |
validate() |
manually check that the value is correct | function |
↳ type |
type must match (or cast) to one of these | function, string, array |
↳ required |
value must be provided and found | boolean |
↳ enum |
it has to match exactly one of these | array |
options |
define the schema of the children | object |
Internally it works in three steps, if you provide the main function then it will not perform the other actions:
find()
: usesenv
>arg
>inherit
>default
(in order) to attempt to get a value out of the arguments and environment.clean()
: usesextend
,file
andfolder
to expand the previously found value.validate()
: usestype
,required
,enum
to validate the value after cleaning.
Helpers:
__root: "abcdef"
: if a single option is provided that is not an object, it will be converted into{ abcdef: options }
. Example: accept a port as a single argument{ __root: "port" }
+server(3000)
=server({ port: 3000 })
.__mode: "strict"
: defines what to do with options that are not defined."strict"
will throw with keys that are not in the schema,"remove"
will delete these extra keys and"flexible"
will pass through any extra arguments.