Merge pull request #7 from docker/v1.2.0

added documentation feature for schemas

README.md

@@ -7,19 +7,20 @@ Define, hydrate, and validate configurations in Node.
 - **Casting, Transforms, and Validation**: Handle config values intelligently
 - **Source Hierarchy**: Look for values from passed in configs, ENV variables, and CLI args
 - **Self Referencing**: Reference other config values via function or string interpolation
+- **Self Documenting**: Schema documentation can be generated automatically
 
 ## Getting Started
 
 Install Pulpo with `npm` by running:
 
 ```
-npm install --save @bonito/pulpo
+npm install --save pulpo
 ```
 
 Getting started is as simple as importing Pulpo and passing it a JSON object for the schema and hydrating with a config object:
 
 ```js
-import Pulpo from '@bonito/pulpo';
+import Pulpo from 'pulpo';
 
 const schema = new Pulpo({
   host: {
@@ -28,7 +29,7 @@ const schema = new Pulpo({
     default: 'localhost'
   },
   port: {
-    description: 'Port for dev server to run on'
+    description: 'Port for dev server to run on',
     type: 'int',
     default: '3000',
     env: 'PORT'
@@ -48,7 +49,7 @@ A schema is comprised of keyed properties that are used to parse and validate co
 ### Constructor
 
 ```js
-import Pulpo from '@bonito/pulpo';
+import Pulpo from 'pulpo';
 
 const schema = new Pulpo({...schema...});
 ```
@@ -66,7 +67,7 @@ const schema = new Pulpo({
       default: 'localhost'
     },
     port: {
-      description: 'Port for dev server to run on'
+      description: 'Port for dev server to run on',
       type: 'number',
       default: '3000',
       env: 'PORT'
@@ -143,7 +144,7 @@ Properties
 Properties are definitions for a given configuration key.
 
 ```js
-import Pulpo from '@bonito/pulpo';
+import Pulpo from 'pulpo';
 
 const schema = new Pulpo({
   environment: {
@@ -209,7 +210,7 @@ Types are used to validate config values. By default Pulpo comes with basic prim
 New Types can be added to Pulpo for further validation:
 
 ```js
-import Pulpo from '@bonito/pulpo';
+import Pulpo from 'pulpo';
 
 Pulpo.addType('int', {
   validate: (value) => {
@@ -233,6 +234,43 @@ const schema = new Pulpo({
 
 Types are comprised of a validation function that receives a value and returns either void or an error message to be displayed to the user and a cast method that transforms a value before validating.
 
+## Documenting
+
+Schemas can be used to provide easy documentation for anyone interacting with the configurations:
+
+```js
+const schema = new Pulpo({
+  server: {
+    host: {
+      description: 'Host for the server',
+      type: 'string',
+      default: 'localhost'
+    },
+    port: {
+      description: 'Port for dev server to run on',
+      type: 'number',
+      default: '3000',
+      env: 'PORT'
+    }
+  }
+});
+
+console.log(schema.document());
+// {
+//   "server.host": {
+//     "description": "Host for the server",
+//     "type": "string",
+//     "default": "localhost"
+//   },
+//   "server.port": {
+//     "description": "Port for dev server to run on",
+//     "type": "number",
+//     "default": "3000",
+//     "env": "PORT"
+//   }
+// }
+```
+
 ## License
 
 Pulpo is licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for the full license text.

package.json

@@ -1,9 +1,20 @@
 {
-  "name": "@bonito/pulpo",
-  "version": "1.1.2",
+  "name": "pulpo",
+  "version": "1.2.0",
   "description": "Configuration mechanism",
   "author": "Patrick Camacho <patrick.camacho@docker.com>",
-  "license": "Apache 2.0",
+  "license": "Apache",
+  "keywords": [
+    "configuration",
+    "config",
+    "env",
+    "configurator",
+    "docker",
+    "schema",
+    "setup",
+    "cast",
+    "validate"
+  ],
   "main": "lib/index.js",
   "typings": "lib/index",
   "files": [

src/schema.ts

@@ -122,6 +122,19 @@ export default class Schema {
       return config;
     }, {});
   }
+
+  document(): Object {
+    // Trace the paths and build string versions of all the property keys
+    return Object.keys(this.definition).reduce((definition, path) => {
+      definition[path] = Property.reservedKeys.reduce((obj, key) => {
+        const value = this.definition[path].definition[key];
+        if (value === undefined) return obj;
+        obj[key] = value.toString();
+        return obj;
+      }, {});
+      return definition;
+    }, {});
+  }
 }
 
 Schema.addType('number', numberType);

test/integration/document.spec.ts

@@ -0,0 +1,20 @@
+/// <reference path='../../typings/index.d.ts' />
+import Schema from '../../src/schema';
+import nestedSchema = require('../fixtures/nested-schema.json');
+
+describe('Document', () => {
+  it('creates an object of all the property descriptions', () => {
+    const schema = new Schema(nestedSchema);
+    expect(schema.document()).toEqual({
+      "baz": {
+        "description": "top level value",
+        "type": "string"
+      },
+      "foo.bar": {
+        "default": "baz",
+        "description": "nested schema key",
+        "type": "string"
+      }
+    });
+  });
+});