109 lines
No EOL
3.9 KiB
Markdown
109 lines
No EOL
3.9 KiB
Markdown
# validate
|
|
[](https://pub.dartlang.org/packages/angel_validate)
|
|
[](https://travis-ci.org/angel-dart/validate)
|
|
|
|
Strongly-typed form handlers and validators for Angel.
|
|
Version `3.x` is a major improvement over `2.x`, though it does include breaking changes.
|
|
|
|
`package:angel_validate` allows you to easily sanitize incoming data, and to deserialize
|
|
that data into Dart classes (usually using `package:angel_serialize`).
|
|
|
|
# Field
|
|
The basic unit is the `Field` class, which is a type-safe way to read
|
|
values from a `RequestContext`. Here is a simple example of using a
|
|
`TextField` instance to read a value from the URL query parameters:
|
|
|
|
```dart
|
|
app.get('/hello', (req, res) async {
|
|
var nameField = TextField('name');
|
|
var name = await nameField.getValue(req, query: true); // String
|
|
return 'Hello, $name!';
|
|
});
|
|
```
|
|
|
|
A `Field` can also use `Matcher` objects from `package:matcher` (which you may recognize from
|
|
its usage in `package:test`):
|
|
|
|
```dart
|
|
var positiveNumberField = IntField('pos_num').match([isPositive]);
|
|
```
|
|
|
|
A `MapField` can embed a `Form` (forms covered below), and when combined with
|
|
`Field.deserialize`, can be used to deserialize structured data as a body field:
|
|
|
|
```dart
|
|
app.post('/map_field', (req, res) async {
|
|
var form = Form(fields: [
|
|
MapField('todo', todoForm).deserialize(Todo.fromMap),
|
|
]);
|
|
|
|
var data = await form.validate(req);
|
|
print(data['todo'] is Todo);
|
|
});
|
|
```
|
|
|
|
There are several included field types:
|
|
* `TextField` - Standard text input.
|
|
* `BoolField` - Checks if a field is present; used for checkboxes.
|
|
* `NumField` - Base class that parses input as a number.
|
|
* `DoubleField` - Specialization of `NumField` for doubles.
|
|
* `IntField` - Specialization of `NumField` for integers.
|
|
* `DateTimeField` - Parses an input as an ISO-8601 date.
|
|
* `FileField` - Validates a file in `req.uploadedFiles`.
|
|
* `ImageField` - Uses `package:image` to decode an `UploadedFile` into an image.
|
|
* `MapField` - Validates a Map using a Form.
|
|
* `UriField` - Parses text input into a `Uri` object.
|
|
|
|
# Forms
|
|
The `Form` class lets you combine `Field` instances, and decode
|
|
request bodies into `Map<String, dynamic>`. Unrecognized fields are
|
|
stripped out of the body, so a `Form` is effectively a whitelist.
|
|
|
|
```dart
|
|
var todoForm = Form(fields: [
|
|
TextField('text'),
|
|
BoolField('is_complete'),
|
|
]);
|
|
|
|
// Validate a request body, and deserialize it immediately.
|
|
var todo = await todoForm.deserialize(req, TodoSerializer.fromMap);
|
|
|
|
// Same as above, but with a Codec<Todo, Map> (i.e. via `angel_serialize`).
|
|
var todo = await todoForm.decode(req, todoSerializer);
|
|
|
|
// Same as above, but returns the plain Map without any deserialization.
|
|
var todoMap = await todoForm.validate(req);
|
|
|
|
// Lower-level functionality, typically not called directly.
|
|
// Use it if you want to handle validation errors directly, without
|
|
// throwing exceptions.
|
|
var result = await todoForm.read(req);
|
|
print(result.isSuccess);
|
|
print(result.errors.length);
|
|
|
|
@serializable
|
|
class _Todo {
|
|
String text;
|
|
bool isComplete;
|
|
}
|
|
```
|
|
|
|
## Form Rendering
|
|
TODO: Docs about this
|
|
|
|
# Bundled Matchers
|
|
This library includes some `Matcher`s for common validations,
|
|
including:
|
|
|
|
* `isAlphaDash`: Asserts that a `String` is alphanumeric, but also lets it contain dashes or underscores.
|
|
* `isAlphaNum`: Asserts that a `String` is alphanumeric.
|
|
* `isBool`: Asserts that a value either equals `true` or `false`.
|
|
* `isEmail`: Asserts that a `String` complies to the RFC 5322 e-mail standard.
|
|
* `isInt`: Asserts that a value is an `int`.
|
|
* `isNum`: Asserts that a value is a `num`.
|
|
* `isString`: Asserts that a value is a `String`.
|
|
* `isNonEmptyString`: Asserts that a value is a non-empty `String`.
|
|
* `isUrl`: Asserts that a `String` is an HTTPS or HTTP URL.
|
|
|
|
The remaining functionality is
|
|
[effectively implemented by the `matcher` package](https://www.dartdocs.org/documentation/matcher/latest/matcher/matcher-library.html). |