node-oas-valexp

    0.0.4 • Public • Published

    node-oas-valexp

    The node-oas-valexp is a value validator using OAS (OpenAPI Specification) Parameter object. The design is inspired by the RegExp object.

    Note that this module is not a OAS syntax validator. Though it actually validates the syntax internally, its purpose is validating a value following the specified OAS Parameter Object.

    Dependencies

    Installation

    $ cd ~
    $ npm install node-oas-valexp
    

    Table of Contents


    Quick Start

    In the sample code below, the function howOldAreYou() takes an argument which means your age. It must be an integer in the range of 0 to 120. If 35 is passed to the function, this code will output Thank you.

    const ValExp = require('node-oas-valexp');
     
    howOldAreYou(35);
     
    function howOldAreYou(age) {
      const valexp = new ValExp({
        name: 'age',
        required: true,
        schema: {
          type: 'integer',
          mininum: 0,
          maximum: 120
        }
      });
     
      if (valexp.test(age)) {
        console.log('Thank you.');
      } else {
        console.log(valexp.error.message);
      }
    }

    As you can see in the code above, a ValExp object (variable valexp) is created using the OAS Parameter Object. Then the value passed to the function (variable age) is checked by the test() method of the ValExp object. The test() method returns true if the value is valid. Otherwise, it returns false.

    If 121 is passed to the function, the code above will output the result as follows:

    The `age` must be less than or equal to 120.
    

    If the validation check is failed, you can get the Error object from the valexp.error. The object is actually a ValExpError object inherited from the Error object.

    If you need not only to check the validity but also to get the validated value, you can use the exec() method of the ValExp object. You might wonder how it is going to help. See the scenario below:

    const ValExp = require('node-oas-valexp');
     
    tellYourProfile({ age: 35 });
     
    function tellYourProfile(profile) {
      const valexp = new ValExp({
        name: 'profile',
        required: true,
        schema: {
          type: 'object',
          properties: {
            age: {
              type: 'integer',
              mininum: 0,
              maximum: 120
            },
            gender: {
              type: 'string',
              enum: ['male', 'female', 'other'],
              default: 'other'
            }
          }
        }
      });
     
      let res = valexp.exec(profile);
      if(res) {
        console.log('Thank you.');
        console.log(res[0]);
      } else {
        console.log(valexp.error.message);
      }
    }

    In the code above, the function tellYourProfile() expects your age and gender. In the Parameter Object, the default value for the gender is defined. If the gender is not passed to the function, the exec() method will automatically set the default value and returns the complete value set. Besides, the returned value is not the reference of the original value, but a newly created value (object).

    If the validity check is passed, the exec() method returns a ValExpExecResult object (the variable res in the code above). Otherwise, it returns null.


    ValExp object

    Creating ValExp object

    In order to use this module , you have to get the ValExp constructor loading this module as follows:

    const ValExp = require('node-oas-valexp');

    In the code snippet above, the variable ValExp is a ValExp constructor.

    In order to check the validity of a value, you have to create a ValExp object from the constructor as follows:

    const valexp = new ValExp({
      name: 'age',
      schema: { type: 'integer' }
    });

    The constructor takes a OAS Parameter Object. In the code snippet above, the variable valexp is a ValExp object. If the specified Parameter Object is invalid, the constructor will throw an error. The thrown error is an ValExpError object.

    For now, the ValExp constructor does not support JSON/YAML string. You have to parse such string in advance.

    Properties

    The ValExp object supports some properties as follows:

    Property Type Description
    source String JSON string representing the specified OAS Parameter Object
    error Object ValExpError object or null
    const valexp = new ValExp({
      name: 'age',
      schema: { type: 'integer' }
    });
    console.log(valexp.source);

    The code above will output the result as follows:

    {"name":"age","required":false,"schema":{"type":"integer"}}
    

    As you can see the result above, the source is not as same as the specified Parameter Object. This module parses the specified Parameter Object and rebuilds an object internally.

    The error is set to null initially. When the test() or exec() is called, it will be set to the ValExpError object if an validation error occurred.

    toString() method

    The toString() method returns a JSON string representing the specified Parameter Object. Actually, calling this method is as same as accessing the source property.

    test() method

    The test() method validates the specified value following the Parameter Object, then returns the result. If the validation check is passed, it returns true. Otherwise, it returns false.

    See the Quick Start for more details.

    exec() method

    The exec() method validates the specified value following the Parameter Object, then returns the result. If the validation check is passed, it returns a ValExpExecResult object. Otherwise, it returns null.

    See the Quick Start for more details.


    ValExpExecResult object

    The ValExpExecResult object has the properties as follows:

    Property Type Description
    0 Any The value after the validation
    input Any The value before the validation

    This object is similar to the result of the RegExp.prototype.exec() of JavaScript. The ValExpExecResult object is actually an object inherited from the Array.

    const valexp = new ValExp({
      name: 'profile',
      required: true,
      schema: {
        type: 'object',
        properties: {
          age: {
            type: 'integer',
            mininum: 0,
            maximum: 120
          },
          gender: {
            type: 'string',
            enum: ['male', 'female', 'other'],
            default: 'other'
          }
        }
      }
    });
     
    let res = valexp.exec({age: 35});
    console.log('- Before: ' + JSON.stringify(res.input));
    console.log('- After : ' + JSON.stringify(res[0]));

    The code above will output the result as follows:

    - Before: {"age":35}
    - After : {"age":35,"gender":"other"}
    

    ValExpError object

    The ValExpError is an object inherited from the Error object. The ValExpError supports the additional properties as follows:

    Property Type Description
    valExpName String Target name whose value has a validation error
    valExpCode String Error code representing what type of error was found.
    const ValExp = require('node-oas-valexp');
    const valexp = new ValExp({
      name: 'age',
      required: true,
      schema: {
        type: 'integer',
        mininum: 0,
        maximum: 120
      }
    });
     
    valexp.test(121); // This couses an validation error
     
    console.log('- valExpName: ' + valexp.error.valExpName);
    console.log('- valExpCode: ' + valexp.error.valExpCode);
    console.log('- messsage  : ' + valexp.error.message);

    The code above will output the result as follows:

    - valExpName: age
    - valExpCode: ERR_VALUE_INTEGER_MAXIMUM
    - messsage  : The `age` must be less than or equal to 120.
    

    The valExpCode and the corresponding message are pre-defined in this module. See the lib/errors/en.json for details.

    For now, this module also supports Japanese error message. If you want to change to Japanese, set the environment variable process.env.NODE_OAS_VALEXP_LANG to "ja" before loading this module calling the require():

    process.env.NODE_OAS_VALEXP_LANG = 'ja';
    const ValExp = require('node-oas-valexp');
    ...

    The code above will output the result as follows:

    - valExpName: age
    - valExpCode: ERR_VALUE_INTEGER_MAXIMUM
    - messsage  : `age` は 120 以下でなければいけません。
    

    Supported keywords

    Parameter object

    Property Type Required Description
    name String Required Parameter name
    required Boolean Optional true: Required, false: Optional (Default)
    schema Object Optional Schema object

    Schema object

    Common keywords

    Property Type Required Description
    oneOf Array Optional List of Schema object
    anyOf Array Optional List of Schema object
    allOf Array Optional List of Schema object
    type String Required "string", "number", "integer", "boolean", "array", or "object"
    nullable Boolean Optional true: null is acceptable, false: null is not acceptable (default)

    Note that if oneOf, anyOf, or allOf is set, other keywords must not be set.

    Keywords for "string"

    Property Type Required Description
    default String Optional Default value
    minLength Integer Optional It must be grater than 0.
    maxLength Integer Optional It must be grater than 0.
    format String Optional "date-time", "date", "time", or "byte"
    pattern String Optional Regular expression
      RegExp    

    The format example:

    format Expected values
    date-time "2020-04-05T08:30:00.000Z", "2020-04-05T08:30:00.000+09:00"
    date "2020-04-05"
    time "08:30:00", "08:30:00.000"

    The date-time and date check if the date actually exists. For example, "2021-02-29" will be rejected.

    The format does not support "binary" for now. If the format is "byte", it is expected that the validated value is a base64 string.

    The pattern allows both of a Regular expression string and a RegExp object. The two codes are identical:

    pattern: '^\\d{3}\\-\\d{4}$'
    pattern: /^\d{3}\-\d{4}$/

    Keywords for "number"

    Property Type Required Description
    default Number Optional Default value
    minimum Number Optional  
    exclusiveMinimum Boolean Optional The default value is false
    maximum Number Optional  
    exclusiveMaximum Boolean Optional The default value is false
    multipleOf Number Optional It must be grater than 0.

    Keywords for "integer"

    Property Type Required Description
    default Integer Optional Default value
    minimum Number Optional  
    exclusiveMinimum Boolean Optional The default value is false
    maximum Number Optional  
    exclusiveMaximum Boolean Optional The default value is false
    multipleOf Number Optional It must be grater than 0.
    format String Optional "int32" or "int64"

    If the format is "int32", it is expected that the validated value is in the range of -2147483648 to 2147483647.

    If the format is "int64", it is expected that the validated value is in the range of Number.MIN_SAFE_INTEGER (-9007199254740991) to Number.MAX_SAFE_INTEGER (9007199254740991). This module does not support the BigInt for now.

    Keywords for "boolean"

    Property Type Required Description
    default Boolean Optional Default value

    Keywords for "array"

    Property Type Required Description
    default Array Optional Default value
    minItems Integer Optional It must be equal to or greater than 0.
    maxItems Integer Optional It must be equal to or greater than 0.
    uniqueItems Boolean Optional The default value is false.
    items Object Required Schema object for elements in the array.

    Keywords for "object"

    Property Type Required Description
    default Object Optional Default value
    minProperties Integer Optional It must be grater than 0.
    maxProperties Integer Optional It must be grater than 0.
    required Array Optional The number of elements must be grater than 0.
    properties Object Optional  
    additionalProperties Boolean Optional  
      Object    

    Release Note

    • v0.0.4 (2020-04-10)
      • Fixed the repository url in the package.json
    • v0.0.3 (2020-04-09)
      • Fixed a bug that the value undefined was determined to be invalid even though the required in the Parameter Object is set to false or not specified
    • v0.0.2 (2020-04-05)
      • First public release

    References


    License

    The MIT License (MIT)

    Copyright (c) 2020 Futomi Hatano

    Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

    The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

    Install

    npm i node-oas-valexp

    DownloadsWeekly Downloads

    6

    Version

    0.0.4

    License

    MIT

    Unpacked Size

    67.6 kB

    Total Files

    9

    Last publish

    Collaborators

    • futomi