@vsaas/loopback-datasource-juggler 10.0.0

package/types/validation-mixin.d.ts

@@ -0,0 +1,287 @@
+// Copyright IBM Corp. 2018. All Rights Reserved.
+// Node module: loopback-datasource-juggler
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+import { Callback, Options, PromiseOrVoid } from './common';
+
+/**
+ * This class provides methods that add validation cababilities to models.
+ * Each of the validations runs when the `obj.isValid()` method is called.
+ *
+ * All of the methods have an options object parameter that has a
+ * `message` property.  When there is only a single error message, this
+ * property is just a string;
+ * for example: `Post.validatesPresenceOf('title', { message: 'can not be blank' });`
+ *
+ * In more complicated cases it can be a set of messages, for each possible
+ * error condition; for example:
+ * `User.validatesLengthOf('password', { min: 6, max: 20, message: {min: 'too short', max: 'too long'}});`
+ *
+ */
+export interface Validatable {
+  /**
+   * Validate presence of one or more specified properties.
+   *
+   * Requires a model to include a property to be considered valid; fails when validated field is blank.
+   *
+   * For example, validate presence of title
+   * ```
+   * Post.validatesPresenceOf('title');
+   * ```
+   * Validate that model has first, last, and age properties:
+   * ```
+   * User.validatesPresenceOf('first', 'last', 'age');
+   * ```
+   * Example with custom message
+   * ```
+   * Post.validatesPresenceOf('title', {message: 'Cannot be blank'});
+   * ```
+   *
+   * @param {String} propertyName  One or more property names.
+   * @options {Object} options Configuration parameters; see below.
+   * @property {String} message Error message to use instead of default.
+   * @property {String} if Validate only if `if` exists.
+   * @property {String} unless Validate only if `unless` exists.
+   */
+  validatesPresenceOf(...propertyNames: string[]): void;
+  validatesPresenceOf(propertyName: string, options?: Options): void;
+
+  /**
+   * Validate absence of one or more specified properties.
+   *
+   * A model should not include a property to be considered valid; fails when validated field is not blank.
+   *
+   * For example, validate absence of reserved
+   * ```
+   * Post.validatesAbsenceOf('reserved', { unless: 'special' });
+   * ```
+   *
+   * @param {String} propertyName  One or more property names.
+   * @options {Object} options Configuration parameters; see below.
+   * @property {String} message Error message to use instead of default.
+   * @property {String} if Validate only if `if` exists.
+   * @property {String} unless Validate only if `unless` exists.
+   */
+  validatesAbsenceOf(...propertyNames: string[]): void;
+  validatesAbsenceOf(propertyName: string, options?: Options): void;
+
+  /**
+   * Validate length.
+   *
+   * Require a property length to be within a specified range.
+   *
+   * There are three kinds of validations: min, max, is.
+   *
+   * Default error messages:
+   *
+   * - min: too short
+   * - max: too long
+   * - is: length is wrong
+   *
+   * Example: length validations
+   * ```
+   * User.validatesLengthOf('password', {min: 7});
+   * User.validatesLengthOf('email', {max: 100});
+   * User.validatesLengthOf('state', {is: 2});
+   * User.validatesLengthOf('nick', {min: 3, max: 15});
+   * ```
+   * Example: length validations with custom error messages
+   * ```
+   * User.validatesLengthOf('password', {min: 7, message: {min: 'too weak'}});
+   * User.validatesLengthOf('state', {is: 2, message: {is: 'is not valid state name'}});
+   * ```
+   *
+   * @param {String} propertyName  Property name to validate.
+   * @options {Object} options Configuration parameters; see below.
+   * @property {Number} is Value that property must equal to validate.
+   * @property {Number} min Value that property must be less than to be valid.
+   * @property {Number} max Value that property must be less than to be valid.
+   * @property {Object} message Optional object with string properties for custom error message for each validation: is, min, or max.
+   */
+  validatesLengthOf(propertyName: string, options?: Options): void;
+
+  /**
+   * Validate numericality.
+   *
+   * Requires a value for property to be either an integer or number.
+   *
+   * Example
+   * ```
+   * User.validatesNumericalityOf('age', { message: { number: 'is not a number' }});
+   * User.validatesNumericalityOf('age', {int: true, message: { int: 'is not an integer' }});
+   * ```
+   *
+   * @param {String} propertyName  Property name to validate.
+   * @options {Object} options Configuration parameters; see below.
+   * @property {Boolean} int If true, then property must be an integer to be valid.
+   * @property {Boolean} allowBlank Allow property to be blank.
+   * @property {Boolean} allowNull Allow property to be null.
+   * @property {Object} message Optional object with string properties for 'int' for integer validation. Default error messages:
+   * - number: is not a number
+   * - int: is not an integer
+   */
+  validatesNumericalityOf(propertyName: string, options?: Options): void;
+
+  /**
+   * Validate inclusion in set.
+   *
+   * Require a value for property to be in the specified array.
+   *
+   * Example:
+   * ```
+   * User.validatesInclusionOf('gender', {in: ['male', 'female']});
+   * User.validatesInclusionOf('role', {
+   *     in: ['admin', 'moderator', 'user'], message: 'is not allowed'
+   * });
+   * ```
+   *
+   * @param {String} propertyName  Property name to validate.
+   * @options {Object} options Configuration parameters; see below.
+   * @property {Array} in Property must match one of the values in the array to be valid.
+   * @property {String} message Optional error message if property is not valid.
+   * Default error message: "is not included in the list".
+   * @property {Boolean} allowNull Whether null values are allowed.
+   */
+  validatesInclusionOf(propertyName: string, options?: Options): void;
+
+  /**
+   * Validate exclusion in a set.
+   *
+   * Require a property value not be in the specified array.
+   *
+   * Example: `Company.validatesExclusionOf('domain', {in: ['www', 'admin']});`
+   *
+   * @param {String} propertyName  Property name to validate.
+   * @options {Object} options Configuration parameters; see below.
+   * @property {Array} in Property must not match any of the values in the array to be valid.
+   * @property {String} message Optional error message if property is not valid. Default error message: "is reserved".
+   * @property {Boolean} allowNull Whether null values are allowed.
+   */
+  validatesExclusionOf(propertyName: string, options?: Options): void;
+
+  /**
+   * Validate format.
+   *
+   * Require a model to include a property that matches the given format.
+   *
+   * Example: `User.validatesFormatOf('name', {with: /\w+/});`
+   *
+   * @param {String} propertyName  Property name to validate.
+   * @options {Object} options Configuration parameters; see below.
+   * @property {RegExp} with Regular expression to validate format.
+   * @property {String} message Optional error message if property is not valid. Default error message: " is invalid".
+   * @property {Boolean} allowNull Whether null values are allowed.
+   */
+  validatesFormatOf(propertyName: string, options?: Options): void;
+
+  /**
+   * Validate using custom validation function.
+   *
+   * Example:
+   *```javascript
+   *     User.validate('name', customValidator, {message: 'Bad name'});
+   *     function customValidator(err) {
+   *         if (this.name === 'bad') err();
+   *     });
+   *     var user = new User({name: 'Peter'});
+   *     user.isValid(); // true
+   *     user.name = 'bad';
+   *     user.isValid(); // false
+   * ```
+   *
+   * @param {String} propertyName  Property name to validate.
+   * @param {Function} validatorFn Custom validation function.
+   * @options {Object} options Configuration parameters; see below.
+   * @property {String} message Optional error message if property is not valid. Default error message: " is invalid".
+   * @property {Boolean} allowNull Whether null values are allowed.
+   */
+  validate(propertyName: string, validatorFn: Function, options?: Options): void;
+
+  /**
+   * Validate using custom asynchronous validation function.
+   *
+   * Example:
+   *```js
+   *     User.validateAsync('name', customValidator, {message: 'Bad name'});
+   *     function customValidator(err, done) {
+   *         process.nextTick(function () {
+   *             if (this.name === 'bad') err();
+   *             done();
+   *         });
+   *     });
+   *     var user = new User({name: 'Peter'});
+   *     user.isValid(); // false (because async validation setup)
+   *     user.isValid(function (isValid) {
+   *         isValid; // true
+   *     })
+   *     user.name = 'bad';
+   *     user.isValid(); // false
+   *     user.isValid(function (isValid) {
+   *         isValid; // false
+   *     })
+   * ```
+   *
+   * @param {String} propertyName  Property name to validate.
+   * @param {Function} validatorFn Custom validation function.
+   * @options {Object} options Configuration parameters; see below.
+   * @property {String} message Optional error message if property is not valid. Default error message: " is invalid".
+   * @property {Boolean} allowNull Whether null values are allowed.
+   */
+  validateAsync(propertyName: string, validatorFn: Function, options?: Options): void;
+
+  /**
+   * Validate uniqueness of the value for a property in the collection of models.
+   *
+   * Not available for all connectors. Currently supported with these connectors:
+   *  - In Memory
+   *  - Oracle
+   *  - MongoDB
+   *
+   * ```
+   * // The login must be unique across all User instances.
+   * User.validatesUniquenessOf('login');
+   *
+   * // Assuming SiteUser.belongsTo(Site)
+   * // The login must be unique within each Site.
+   * SiteUser.validateUniquenessOf('login', { scopedTo: ['siteId'] });
+   * ```
+   *
+   * @param {String} propertyName  Property name to validate.
+   * @options {Object} options Configuration parameters; see below.
+   * @property {RegExp} with Regular expression to validate format.
+   * @property {Array.<String>} scopedTo List of properties defining the scope.
+   * @property {String} message Optional error message if property is not valid. Default error message: "is not unique".
+   * @property {Boolean} allowNull Whether null values are allowed.
+   * @property {String} ignoreCase Make the validation case insensitive.
+   * @property {String} if Validate only if `if` exists.
+   * @property {String} unless Validate only if `unless` exists.
+   */
+  validatesUniquenessOf(propertyName: string, validatorFn: Function, options?: Options): void;
+
+  /**
+   * Validate if a value for a property is a Date.
+   *
+   * Example
+   * ```
+   * User.validatesDateOf('today', {message: 'today is not a date!'});
+   * ```
+   *
+   * @param {String} propertyName  Property name to validate.
+   * @options {Object} options Configuration parameters; see below.
+   * @property {String} message Error message to use instead of default.
+   */
+  validatesDateOf(propertyName: string, validatorFn: Function, options?: Options): void;
+}
+
+/**
+ * ValidationError
+ */
+export declare class ValidationError extends Error {
+  statusCode?: number;
+  details: {
+    context: any;
+    codes: string[];
+    messages: string[];
+  };
+}