diff --git a/.gitignore b/.gitignore index b35e7eb..8be06b1 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,7 @@ +.DS_Store + # Test Output -test-ts.js +examples-typescript.js # Logs logs diff --git a/.npmignore b/.npmignore new file mode 100644 index 0000000..ff6f3e4 --- /dev/null +++ b/.npmignore @@ -0,0 +1,12 @@ +.DS_Store +.gitignore +.eslintrc +npm-debug.log +build.js +examples-typescript.js +examples-typescript.ts +index.browser.js +pre-push.js +test.js +*.test.js +tsconfig.json diff --git a/README.md b/README.md index 14bd9fb..9c0666a 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,20 @@ @polyn/blueprint ================ -@polyn/blueprint is an easy to use, flexible, and powerful validation library for nodejs and browsers +@polyn/blueprint is an easy to use, extensible, and powerful validation library for nodejs and browsers. + +While @polyn/blueprint can be used on it's own, it really shines when you use it with [@polyn/immutable](https://github.com/losandes/polyn-immutable). + +* [Getting Started with Node](#node) +* [Getting Started with the Browser](#browser) +* [Types / Validators](#types-validators) +* [Custom Validators](#custom-validators) + * [Inline Custom Validators](#inline-custom-validators) + * [Registering Validators](#registering-validators) + * [Registering Types](#registering-types) + * [Registering Regular Expressions](#registering-regular-expressions) + * [Registering Blueprints](#registering-blueprints) + * [Intercepting Values](#intercepting-values) +* [TypeScript Support](#typescript-support) ## Usage @@ -171,11 +185,11 @@ const allTheTypes = blueprint('allTheTypes', { ## Custom Validators Blueprint supports multiple ways for defining your own validators. -* Inline custom validators -* Registered validators -* Registered types -* Registered expressions -* Registered blueprints +* [Inline Custom Validators](#inline-custom-validators) +* [Registered validators](#registering-validators) +* [Registered types](#registering-types) +* [Registered expressions](#registering-regular-expressions) +* [Registered blueprints](#registering-blueprints) ### Custom Validator Return Values _Inline custom validators_, _registered validators_, and _registered types_ support passing your own function to perform the validation. Your functions must return one of two types to work. The following examples will use inline custom validators for the example, but the same approach can be used when registering validators, or types. @@ -250,6 +264,7 @@ const product = blueprint('product', { // require the ISBN if the productType is 'book' ISBN: ({ key, value, input, root }) => root.productType === 'book' && typeof value === 'string' && value.length +}) ``` > @alsosee [Custom Validator Return Values](#custom-validator-return-values) for information on supported return values @@ -280,7 +295,7 @@ assert.strictEqual(actual.value.age, 20) > @alsosee [Custom Validator Return Values](#custom-validator-return-values) for information on supported return values -#### Registering Types +### Registering Types If you want to support nulls and arrays for the validator you are registering, use `registerTypes` instead. For instance, to register the following: ``` @@ -309,7 +324,7 @@ const actual = blueprint('requestBody', { > @alsosee [Custom Validator Return Values](#custom-validator-return-values) for information on supported return values -#### Registering Regular Expressions +### Registering Regular Expressions Registering regular expressions works similarly to registering types, except you pass in a RegExp, or string expression as the second argument. ```JavaScript @@ -331,7 +346,7 @@ const actual = blueprint('requestBody', { }) ``` -#### Registering Blueprints +### Registering Blueprints Sometimes it's useful to register another blueprint as a validator. `registerBlueprint` accepts the same arguments as constructing one, and stores the blueprint as a validator, so it can be used like a type. It includes support for nulls and arrays. ```JavaScript @@ -373,7 +388,7 @@ assert.strictEqual(actual.value.person.lastName, 'Doe') // ... ``` -#### Intercepting Values +### Intercepting Values _Inline custom validators_, _registered validators_, and _registered types_ provide the ability to intercept/modify the values that are returned by blueprint.validate. Both of these examples trim the strings that are written to the `value` property @@ -428,7 +443,32 @@ console.log( // } ``` +## TypeScript Support +This library exports types. A brief example is shown here. If you'd like to see more, there are several examples in [examples-typescript.ts](./examples-typescript.ts). + +```TypeScript +const { blueprint, gt } = require('@polyn/blueprint') + +const personBlueprint: IBlueprint = blueprint('Person', { + firstName: 'string', + lastName: 'string', + age: gt(0) +}) + +const result: IValueOrError = personBlueprint.validate({ + firstName: 'John', + lastName: 'Doe', + age: 21 +}) + +console.log(result.err) +// prints null + +console.log(result.value) +// prints { firstName: 'John', lastName: 'Doe', age: 21 } +``` + ## Why @polyn/blueprint? Why not JSON Schema -There's noting wrong with JSON Schema. In many cases it makes more sense to use that, particularly in cases where the schema is meant to be shared across organizational boundaries. I started writing this library years ago when JSON Schema was in it's infancy. So why keep improving and maintaining it? +There's nothing wrong with JSON Schema. In many cases it makes more sense to use that, particularly in cases where the schema is meant to be shared across organizational boundaries. I started writing this library years ago when JSON Schema was in it's infancy. So why keep improving and maintaining it? -It's simple. It's less verbose than JSON Schema. It's functional (we write validators as functions, instead of configurations). Because of that it's easily extensible, and it's easy to write complex/dependency-based validations (i.e. _isbn is required if productType === 'book'_). +It's simple. It's less verbose than JSON Schema. It's functional (we can write validators as functions, instead of configurations). Because of that it's easily extensible, and it's easy to write complex/dependency-based validations (i.e. _isbn is required if productType === 'book'_). diff --git a/test-ts.ts b/examples-typescript.ts similarity index 98% rename from test-ts.ts rename to examples-typescript.ts index 9a8d9ae..6ee2e82 100644 --- a/test-ts.ts +++ b/examples-typescript.ts @@ -104,4 +104,4 @@ const result: IValueOrError = myModelBp.validate({ }) expect(result.err).to.be.null -console.log('ALL TYPESCRIPT TESTS PASSED') +console.log('ALL TYPESCRIPT EXAMPLES PASSED\n') diff --git a/package-lock.json b/package-lock.json index 28efe6c..95f085a 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,6 +1,6 @@ { "name": "@polyn/blueprint", - "version": "2.0.1", + "version": "2.0.4", "lockfileVersion": 1, "requires": true, "dependencies": { @@ -1048,12 +1048,6 @@ "node-releases": "^1.1.17" } }, - "buffer-from": { - "version": "1.1.1", - "resolved": "https://registry.npmjs.org/buffer-from/-/buffer-from-1.1.1.tgz", - "integrity": "sha512-MQcXEUbCKtEo7bhqEs6560Hyd4XaovZlO/k9V3hjVUF/zwW7KBVdSK4gIt/bzwS9MbR5qob+F5jusZsb0YQK2A==", - "dev": true - }, "cache-base": { "version": "1.0.1", "resolved": "https://registry.npmjs.org/cache-base/-/cache-base-1.0.1.tgz", @@ -1239,18 +1233,6 @@ "integrity": "sha1-2Klr13/Wjfd5OnMDajug1UBdR3s=", "dev": true }, - "concat-stream": { - "version": "1.6.2", - "resolved": "https://registry.npmjs.org/concat-stream/-/concat-stream-1.6.2.tgz", - "integrity": "sha512-27HBghJxjiZtIk3Ycvn/4kbJk/1uZuJFfuPEns6LaEvpvG1f0hTea8lilrouyo9mVc2GWdcEZ8OLoGmSADlrCw==", - "dev": true, - "requires": { - "buffer-from": "^1.0.0", - "inherits": "^2.0.3", - "readable-stream": "^2.2.2", - "typedarray": "^0.0.6" - } - }, "configstore": { "version": "3.1.2", "resolved": "https://registry.npmjs.org/configstore/-/configstore-3.1.2.tgz", @@ -3586,12 +3568,6 @@ "wordwrap": "~1.0.0" } }, - "os-shim": { - "version": "0.1.3", - "resolved": "https://registry.npmjs.org/os-shim/-/os-shim-0.1.3.tgz", - "integrity": "sha1-a2LDeRz3kJ6jXtRuF2WLtBfLORc=", - "dev": true - }, "os-tmpdir": { "version": "1.0.2", "resolved": "https://registry.npmjs.org/os-tmpdir/-/os-tmpdir-1.0.2.tgz", @@ -3736,39 +3712,6 @@ "integrity": "sha1-AerA/jta9xoqbAL+q7jB/vfgDqs=", "dev": true }, - "pre-commit": { - "version": "1.2.2", - "resolved": "https://registry.npmjs.org/pre-commit/-/pre-commit-1.2.2.tgz", - "integrity": "sha1-287g7p3nI15X95xW186UZBpp7sY=", - "dev": true, - "requires": { - "cross-spawn": "^5.0.1", - "spawn-sync": "^1.0.15", - "which": "1.2.x" - }, - "dependencies": { - "cross-spawn": { - "version": "5.1.0", - "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-5.1.0.tgz", - "integrity": "sha1-6L0O/uWPz/b4+UUQoKVUu/ojVEk=", - "dev": true, - "requires": { - "lru-cache": "^4.0.1", - "shebang-command": "^1.2.0", - "which": "^1.2.9" - } - }, - "which": { - "version": "1.2.14", - "resolved": "https://registry.npmjs.org/which/-/which-1.2.14.tgz", - "integrity": "sha1-mofEN48D6CfOyvGs31bHNsAcFOU=", - "dev": true, - "requires": { - "isexe": "^2.0.0" - } - } - } - }, "pre-push": { "version": "0.1.1", "resolved": "https://registry.npmjs.org/pre-push/-/pre-push-0.1.1.tgz", @@ -4321,16 +4264,6 @@ "integrity": "sha1-PpNdfd1zYxuXZZlW1VEo6HtQhKM=", "dev": true }, - "spawn-sync": { - "version": "1.0.15", - "resolved": "https://registry.npmjs.org/spawn-sync/-/spawn-sync-1.0.15.tgz", - "integrity": "sha1-sAeZVX63+wyDdsKdROih6mfldHY=", - "dev": true, - "requires": { - "concat-stream": "^1.4.7", - "os-shim": "^0.1.2" - } - }, "spdx-correct": { "version": "3.1.0", "resolved": "https://registry.npmjs.org/spdx-correct/-/spdx-correct-3.1.0.tgz", @@ -4509,6 +4442,15 @@ "execa": "^0.7.0" } }, + "terminal-adventure": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/terminal-adventure/-/terminal-adventure-1.0.2.tgz", + "integrity": "sha1-n5uxg7plG0KjL6O62V+fJU4yNAY=", + "dev": true, + "requires": { + "chalk": "^2.1.0" + } + }, "text-table": { "version": "0.2.0", "resolved": "https://registry.npmjs.org/text-table/-/text-table-0.2.0.tgz", @@ -4620,12 +4562,6 @@ "integrity": "sha512-0fr/mIH1dlO+x7TlcMy+bIDqKPsw/70tVyeHW787goQjhmqaZe10uwLujubK9q9Lg6Fiho1KUKDYz0Z7k7g5/g==", "dev": true }, - "typedarray": { - "version": "0.0.6", - "resolved": "https://registry.npmjs.org/typedarray/-/typedarray-0.0.6.tgz", - "integrity": "sha1-hnrHTjhkGHsdPUfZlqeOxciDB3c=", - "dev": true - }, "typescript": { "version": "3.4.5", "resolved": "https://registry.npmjs.org/typescript/-/typescript-3.4.5.tgz", diff --git a/package.json b/package.json index def6791..02e9d90 100644 --- a/package.json +++ b/package.json @@ -1,21 +1,17 @@ { "name": "@polyn/blueprint", - "version": "2.0.2", + "version": "2.0.4", "description": "An easy to use, flexible, and powerful validation library for nodejs and browsers", "main": "index.js", "types": "index.d.ts", "scripts": { "build": "node build.js", + "pre-push": "npm test && node pre-push.js", "test": "node test.js && npm run test:ts", - "test:ts": "tsc -p ./tsconfig.json && node test-ts.js", + "test:ts": "tsc -p ./tsconfig.json && node examples-typescript.js", "watch": "nodemon -e js --exec 'node test.js --tap | tap-nyan'" }, - "pre-commit": [ - "build" - ], - "pre-push": [ - "test" - ], + "pre-push": ["pre-push"], "repository": { "type": "git", "url": "git+https://github.com/losandes/polyn-blueprint.git" @@ -45,9 +41,9 @@ "eslint-plugin-promise": "~4.1.1", "eslint-plugin-standard": "~4.0.0", "nodemon": "~1.19.0", - "pre-commit": "~1.2.2", "pre-push": "~0.1.1", "supposed": "~0.2.0", + "terminal-adventure": "~1.0.2", "typescript": "~3.4.5" }, "dependencies": {} diff --git a/pre-push.js b/pre-push.js new file mode 100644 index 0000000..3f0fa43 --- /dev/null +++ b/pre-push.js @@ -0,0 +1,3 @@ +const FORMAT = '\x1b[33m\x1b[5m%s\x1b[0m' +console.log(FORMAT, 'Did you build the browser distribution?') +console.log(FORMAT, 'Did you update the package number?\n') diff --git a/tsconfig.json b/tsconfig.json index 9cb9bfb..68f07f7 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -7,6 +7,6 @@ "sourceMap": false, "strict": true }, - "include": ["./test-ts.ts"], + "include": ["examples-typescript.ts"], "exclude": [] }