angel_validate 2.0.1+1

validate #

version 1.0.2+4 build status

Live Example

Validation library based on the matcher library, with Angel support. Why re-invent the wheel, when you can use the same validators you already use for tests?

This library runs both on the server, and on the client. Thus, you can use the same validation rules for forms on the server, and on the frontend.

For convenience's sake, this library also exports matcher.

Examples #

Creating a Validator #

import 'package:angel_validate/angel_validate.dart';

main() {
    var validator = new Validator({
        'username': isAlphaNum,
        'multiple,keys,with,same,rules': [isString, isNotEmpty],
        'balance': [
            greaterThanOrEqualTo(0),
            lessThan(1000000)
        ],
        'nested': [
            foo,
            [bar, baz]
        ]
    });
}

Validating data #

The Validator will filter out fields that have no validation rules. You can rest easy knowing that attackers cannot slip extra data into your applications.

main() {
    var result = validator.check(formData);

    if (!result.errors.isNotEmpty) {
        // Invalid data
    } else {
        // Safely handle filtered data
        return someSecureOperation(result.data);
    }
}

You can enforce validation rules, and throw an error if validation fails.

main() {
    try {
        // `enforce` will return the filtered data.
        var safeData = validator.enforce(formData);
    } on ValidationException catch(e) {
        print(e.errors);
    }
}

Required Fields #

Fields are optional by default.

Suffix a field name with a '*' to mark it as required, and to throw an error if it is not present.

main() {
    var validator = new Validator({
        'googleId*': isString,
        
        // You can also use `requireField`
        requireField('googleId'): isString,
    });
}

Forbidden Fields #

To prevent a field from showing up in valid data, suffix it with a '!'.

Default values #

If not present, default values will be filled in before validation. This means that they can still be used with required fields.

final Validator todo = new Validator({
    'text*': isString,
    'completed*': isBool
}, defaultValues: {
    'completed': false
});

Default values can also be parameterless, synchronous functions that return a single value.

Custom Validator Functions #

Creating a whole Matcher class is sometimes cumbersome, but if you pass a function to the constructor, it will be wrapped in a Matcher instance.

(It simply returns the value of calling predicate.)

The function must synchronously return a bool.

main() {
    var validator = new Validator({
        'key*': (key) {
            var file = new File('whitelist.txt');
            return file.readFileSync().contains(key);
        }
    });
}

Custom Error Messages #

If these are not present, angel_validate will attempt to generate a coherent error message on its own.

new Validator({
    'age': [greaterThanOrEqualTo(18)]
}, customErrorMessages: {
    'age': 'You must be an adult to see this page.'
});

The string {{value}} will be replaced inside your error message automatically.

autoParse #

Oftentimes, fields that we want to validate as numbers are passed as strings. Calling autoParse will correct this before validation.

main() {
    var parsed = autoParse({
        'age': '34',
        'weight': '135.6'
    }, ['age', 'weight']);

    validator.enforce(parsed);
}

You can also call checkParsed or enforceParsed as a shorthand.

filter #

This is a helper function to extract only the desired keys from a Map.

var inputData = {'foo': 'bar', 'a': 'b', '1': 2};
var only = filter(inputData, ['foo']);

print(only); // { foo: bar }

Extending Validators #

You can add situation-specific rules within a child validator. You can also use extend to mark fields as required or forbidden that originally were not. Default value and custom error message extension is also supported.

final Validator userValidator = new Validator({
    'username': isString,
    'age': [
        isNum,
        greaterThanOrEqualTo(18)
    ]
});

To mark a field as now optional, and no longer required, suffix its name with a '?'.

var ageIsOptional = userValidator.extend({
    'age?': [
        isNum,
        greaterThanOrEqualTo(13)
    ]
});

Note that by default, new validation rules are simply appended to the existing list. To completely overwrite existing rules, set the overwrite flag to true.

register(Map userData) {
    var teenUser = userValidator.extend({
        'age': lessThan(18)
    }, overwrite: true);    
}

Bundled Matchers #

This library includes some Matchers 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.

Nested Validators #

Very often, the data we validate contains other data within. You can pass a Validator instance to the constructor, because it extends the Matcher class.

main() {
    var bio = new Validator({
        'age*': [isInt, greaterThanOrEqualTo(0)],
        'birthYear*': isInt,
        'countryOfOrigin': isString
    });

    var book = new Validator({
        'title*': isString,
        'year*': [
            isNum,
            (year) {
                return year <= new DateTime.now().year;
            }
        ]
    });

    var author = new Validator({
        'bio*': bio,
        'books*': [
            isList,
            everyElement(book)
        ]
    }, defaultValues: {
        'books': []
    });
}

Use with Angel #

server.dart exposes seven helper middleware:

  • validate(validator): Validates and filters req.bodyAsMap, and throws an AngelHttpException.BadRequest if data is invalid.
  • validateEvent(validator): Sets e.data to the result of validation on a service event.
  • validateQuery(validator): Same as validate, but operates on req.query.
  • autoParseBody(fields): Auto-parses numbers in req.bodyAsMap.
  • autoParseQuery(fields): Same as autoParseBody, but operates on req.query.
  • filterBody(only): Filters unwanted data out of req.bodyAsMap.
  • filterQuery(only): Same as filterBody, but operates on req.query.
import 'package:angel_framework/angel_framework.dart';
import 'package:angel_validate/server.dart';

final Validator echo = new Validator({
    'message*': (String message) => message.length >= 5
});

final Validator todo = new Validator({
    'text*': isString,
    'completed*': isBool
}, defaultValues: {
    'completed': false
});

main() async {
    var app = new Angel();

    app.chain([validate(echo)]).post('/echo', (req, res) async {
        res.write('You said: "${req.bodyAsMap["message"]}"');
    });

    app.service('api/todos')
        ..beforeCreated.listen(validateEvent(todo))
        ..beforeUpdated.listen(validateEvent(todo));

    await app.startServer();
}

2.0.1+1 #

  • Fix bug in the implementation of maxLength.

2.0.1 #

  • Patch for updated body parsing.

2.0.0 #

  • Finish update for Angel 2.

2.0.0-alpha.1 #

  • Update for Angel 2.

1.0.5-beta #

  • Use wrapMatcher on explicit values instead of throwing.
  • Add async matchers.
  • Add context-aware matchers.

1.0.4 #

  • isNonEmptyString trims strings.
  • ValidationException extends AngelHttpException.
  • Added requireField and requireFields.

example/main.dart

import 'package:angel_validate/angel_validate.dart';

main() {
  var bio = new Validator({
    'age*': [isInt, greaterThanOrEqualTo(0)],
    'birthYear*': isInt,
    'countryOfOrigin': isString
  });

  var book = new Validator({
    'title*': isString,
    'year*': [
      isNum,
      (year) {
        return year <= new DateTime.now().year;
      }
    ]
  });

  // ignore: unused_local_variable
  var author = new Validator({
    'bio*': bio,
    'books*': [isList, everyElement(book)]
  }, defaultValues: {
    'books': []
  });
}

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  angel_validate: ^2.0.1+1

2. Install it

You can install packages from the command line:

with pub:


$ pub get

with Flutter:


$ flutter pub get

Alternatively, your editor might support pub get or flutter pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:angel_validate/angel_validate.dart';
  
Popularity:
Describes how popular the package is relative to other packages. [more]
80
Health:
Code health derived from static analysis. [more]
90
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
100
Overall:
Weighted score of the above. [more]
87
Learn more about scoring.

We analyzed this package on Aug 21, 2019, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.4.0
  • pana: 0.12.19

Platforms

Detected platforms: Flutter, web, other

No platform restriction found in primary library package:angel_validate/angel_validate.dart.

Health suggestions

Fix lib/src/validator.dart. (-7.71 points)

Analysis of lib/src/validator.dart reported 16 hints, including:

line 88 col 13: DO use curly braces for all flow control structures.

line 90 col 13: DO use curly braces for all flow control structures.

line 111 col 42: Use = to separate a named parameter from its default value.

line 112 col 47: Use = to separate a named parameter from its default value.

line 137 col 11: DO use curly braces for all flow control structures.

Fix lib/server.dart. (-1.49 points)

Analysis of lib/server.dart reported 3 hints:

line 55 col 25: Use = to separate a named parameter from its default value.

line 76 col 25: Use = to separate a named parameter from its default value.

line 97 col 25: Use = to separate a named parameter from its default value.

Fix lib/src/async.dart. (-0.50 points)

Analysis of lib/src/async.dart reported 1 hint:

line 59 col 20: Use = to separate a named parameter from its default value.

Fix lib/src/context_aware.dart. (-0.50 points)

Analysis of lib/src/context_aware.dart reported 1 hint:

line 13 col 5: DO use curly braces for all flow control structures.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.0.0-dev <3.0.0
angel_framework ^2.0.0-alpha 2.0.4+1
angel_http_exception ^1.0.0 1.1.0
matcher ^0.12.0 0.12.5
Transitive dependencies
angel_container 1.0.4
angel_model 1.0.3
angel_route 3.0.6
charcode 1.1.2
code_buffer 1.0.1
collection 1.14.12
combinator 1.1.0
convert 2.1.1
crypto 2.1.2
dart2_constant 1.0.2+dart2
file 5.0.8+1
http2 1.0.0
http_parser 3.1.3
http_server 0.9.8+3
intl 0.15.8
merge_map 1.0.2
meta 1.1.7
mime 0.9.6+3
path 1.6.4
pedantic 1.8.0+1
quiver 2.0.5
quiver_hashcode 2.0.0
source_span 1.5.5
stack_trace 1.9.3
string_scanner 1.0.5
term_glyph 1.1.0
tuple 1.0.2
typed_data 1.1.6
uuid 2.0.2
Dev dependencies
angel_test ^2.0.0-alpha
build_runner ^0.10.0
build_web_compilers ^0.4.0
logging ^0.11.0 0.11.3+2
mock_request any 1.0.6
test ^1.0.0