Add new method 'defineFunctionProperties' to 'ConfigSchemaHandler'

Author: luislhl

docs/providers/aws/guide/plugins.md

@@ -417,9 +417,9 @@ Command names need to be unique. If we load two commands and both want to specif
 
 If your plugin adds support for additional params in `serverless.yaml` file, you should also add validation rules to the Framework's schema. Otherwise, the Framework may place validation errors to command output about your params.
 
-The Framework uses JSON-schema validation backed by [AJV](https://github.com/ajv-validator/ajv). You can extend [initial schema](/lib/configSchema/index.js) inside your plugin constuctor by using `defineCustomProperties`, `defineCustomEvent` or `defineProvider` helplers.
+The Framework uses JSON-schema validation backed by [AJV](https://github.com/ajv-validator/ajv). You can extend [initial schema](/lib/configSchema/index.js) inside your plugin constuctor by using `defineCustomProperties`, `defineFunctionEvent`, `defineFunctionProperties` or `defineProvider` helpers.
 
-We'll walk though those heplers. You may also want to check out examples from [helpers tests](tests/fixtures/configSchemaExtensions/test-plugin.js)
+We'll walk though those helpers. You may also want to check out examples from [helpers tests](tests/fixtures/configSchemaExtensions/test-plugin.js)
 
 #### `defineCustomProperties` helper
 
@@ -510,6 +510,55 @@ This way, if user sets `anotherProp` by mistake to `some-string`, the Framework
 Serverless: Configuration error: functions.someFunc.events[0].yourPluginEvent.anotherProp should be number
 ```
 
+#### `defineFunctionProperties` helper
+
+Let's say your plugin adds support to a new `someProperty` function property. To use this property, a user would need to have `serverless.yaml` file like this:
+
+```
+// serverless.yaml
+
+functions:
+  someFunc:
+    handler: handler.main
+    someProperty: my-property-value
+```
+
+In this case your plugin should add validation rules inside your plugin constructor. Otherwise, the Framework would display an error message saying that your property is not supported:
+
+```
+ServerlessError: Configuration error:
+at 'functions.someFunc': unrecognized property 'someProperty'
+```
+
+To fix this error and more importantly to provide validation rules for your property, modify your plugin constructor with code like this:
+
+```javascript
+class NewEventPlugin {
+  constructor(serverless) {
+    this.serverless = serverless;
+
+    // Create schema for your properties. For reference use https://github.com/ajv-validator/ajv
+    serverless.configSchemaHandler.defineFunctionProperties('providerName', {
+      type: 'object',
+      properties: {
+        someProperty: { type: 'string' },
+        anotherProperty: { type: 'number' },
+      },
+      required: ['someProperty'],
+      additionalProperties: false,
+    });
+  }
+}
+```
+
+This way, if user sets `anotherProperty` by mistake to `hello`, the Framework would display an error:
+
+```
+ServerlessError: Configuration error at 'functions.someFunc.anotherProperty': should be number
+```
+
+Note, however, that if the user sets `someProperty` to a number, it will just be treated as a string.
+
 #### `defineProvider` helper
 
 In case your plugin provides support for new provider, you would want to adjust validation schema. Here is example:

lib/classes/ConfigSchemaHandler/index.js

@@ -216,6 +216,17 @@ class ConfigSchemaHandler {
     });
   }
 
+  defineFunctionProperties(providerName, configSchema) {
+    if (this.serverless.service.provider.name !== providerName) {
+      return;
+    }
+
+    addPropertiesToSchema(
+      this.schema.properties.functions.patternProperties[FUNCTION_NAME_PATTERN],
+      configSchema
+    );
+  }
+
   relaxProviderSchema() {
     // provider
     this.schema.properties.provider.additionalProperties = true;

lib/classes/ConfigSchemaHandler/index.test.js

@@ -3,6 +3,8 @@
 const expect = require('chai').expect;
 const runServerless = require('../../../test/utils/run-serverless');
 
+const FUNCTION_NAME_PATTERN = '^[a-zA-Z0-9-_]+$';
+
 describe('ConfigSchemaHandler', () => {
   describe('#constructor', () => {
     it('should freeze parts of schema for service', () => {
@@ -97,16 +99,40 @@ describe('ConfigSchemaHandler', () => {
 
         expect(
           serverless.serverless.configSchemaHandler.schema.properties.functions.patternProperties[
-            '^[a-zA-Z0-9-_]+$'
+            FUNCTION_NAME_PATTERN
           ].properties.events.items.anyOf[1]
         ).to.deep.equal(expectedPieceOfSchema);
         return;
       });
     });
   });
 
-  describe('#defineCustomProperty', () => {
-    it('should extend schema with defineCustomProperty method', () => {
+  describe('#defineFunctionProperties', () => {
+    it('should extend schema with defineFunctionProperties method', () => {
+      return runServerless({
+        fixture: 'configSchemaExtensions',
+        cliArgs: ['info'],
+      }).then(serverless => {
+        const actualFunctionProperties =
+          serverless.serverless.configSchemaHandler.schema.properties.functions.patternProperties[
+            FUNCTION_NAME_PATTERN
+          ].properties;
+
+        expect(actualFunctionProperties).to.have.deep.property('someFunctionStringProp', {
+          type: 'string',
+        });
+
+        expect(actualFunctionProperties).to.have.deep.property('someRequiredFunctionNumberProp', {
+          type: 'number',
+        });
+
+        return;
+      });
+    });
+  });
+
+  describe('#defineCustomProperties', () => {
+    it('should extend schema with defineCustomProperties method', () => {
       return runServerless({
         fixture: 'configSchemaExtensions',
         cliArgs: ['info'],
@@ -163,7 +189,7 @@ describe('ConfigSchemaHandler', () => {
         const expectedHandlerPieceOfSchema = { type: 'string' };
         expect(
           serverless.serverless.configSchemaHandler.schema.properties.functions.patternProperties[
-            '^[a-zA-Z0-9-_]+$'
+            FUNCTION_NAME_PATTERN
           ].properties.handler
         ).to.deep.equal(expectedHandlerPieceOfSchema);
         return;

lib/configSchema.test.js

@@ -71,6 +71,7 @@ describe('#configSchema', () => {
             events: [],
             handler: 'someHandler',
             name: 'some-service-dev-someFunc',
+            someRequiredFunctionNumberProp: 123,
           },
         },
       },

test/fixtures/configSchemaExtensions/serverless.yml

@@ -17,6 +17,8 @@ custom:
 
 functions:
   someFunction:
+    someFunctionStringProp: function-string-prop
+    someRequiredFunctionNumberProp: 321
     events:
       - someEvent:
           someRequiredStringProp: some string

test/fixtures/configSchemaExtensions/test-plugin.js

@@ -27,6 +27,16 @@ class TestPlugin {
       additionalProperties: false,
     });
 
+    serverless.configSchemaHandler.defineFunctionProperties('someProvider', {
+      type: 'object',
+      properties: {
+        someFunctionStringProp: { type: 'string' },
+        someRequiredFunctionNumberProp: { type: 'number' },
+      },
+      required: ['someRequiredFunctionNumberProp'],
+      additionalProperties: false,
+    });
+
     serverless.configSchemaHandler.defineTopLevelProperty('top', {
       type: 'string',
     });