source: trip-planner-front/node_modules/aproba/README.md

Last change on this file was 6a3a178, checked in by Ema <ema_spirova@…>, 3 years ago

initial commit

  • Property mode set to 100644
File size: 2.7 KB
Line 
1aproba
2======
3
4A ridiculously light-weight function argument validator
5
6```
7var validate = require("aproba")
8
9function myfunc(a, b, c) {
10 // `a` must be a string, `b` a number, `c` a function
11 validate('SNF', arguments) // [a,b,c] is also valid
12}
13
14myfunc('test', 23, function () {}) // ok
15myfunc(123, 23, function () {}) // type error
16myfunc('test', 23) // missing arg error
17myfunc('test', 23, function () {}, true) // too many args error
18
19```
20
21Valid types are:
22
23| type | description
24| :--: | :----------
25| * | matches any type
26| A | `Array.isArray` OR an `arguments` object
27| S | typeof == string
28| N | typeof == number
29| F | typeof == function
30| O | typeof == object and not type A and not type E
31| B | typeof == boolean
32| E | `instanceof Error` OR `null` **(special: see below)**
33| Z | == `null`
34
35Validation failures throw one of three exception types, distinguished by a
36`code` property of `EMISSINGARG`, `EINVALIDTYPE` or `ETOOMANYARGS`.
37
38If you pass in an invalid type then it will throw with a code of
39`EUNKNOWNTYPE`.
40
41If an **error** argument is found and is not null then the remaining
42arguments are optional. That is, if you say `ESO` then that's like using a
43non-magical `E` in: `E|ESO|ZSO`.
44
45### But I have optional arguments?!
46
47You can provide more than one signature by separating them with pipes `|`.
48If any signature matches the arguments then they'll be considered valid.
49
50So for example, say you wanted to write a signature for
51`fs.createWriteStream`. The docs for it describe it thusly:
52
53```
54fs.createWriteStream(path[, options])
55```
56
57This would be a signature of `SO|S`. That is, a string and and object, or
58just a string.
59
60Now, if you read the full `fs` docs, you'll see that actually path can ALSO
61be a buffer. And options can be a string, that is:
62```
63path <String> | <Buffer>
64options <String> | <Object>
65```
66
67To reproduce this you have to fully enumerate all of the possible
68combinations and that implies a signature of `SO|SS|OO|OS|S|O`. The
69awkwardness is a feature: It reminds you of the complexity you're adding to
70your API when you do this sort of thing.
71
72
73### Browser support
74
75This has no dependencies and should work in browsers, though you'll have
76noisier stack traces.
77
78### Why this exists
79
80I wanted a very simple argument validator. It needed to do two things:
81
821. Be more concise and easier to use than assertions
83
842. Not encourage an infinite bikeshed of DSLs
85
86This is why types are specified by a single character and there's no such
87thing as an optional argument.
88
89This is not intended to validate user data. This is specifically about
90asserting the interface of your functions.
91
92If you need greater validation, I encourage you to write them by hand or
93look elsewhere.
94
Note: See TracBrowser for help on using the repository browser.