schemaglobin - npm Package Compare versions

Comparing version 1.0.0 to 1.0.1

.prettierrc.json

@@ -5,3 +5,2 @@ {
 	"printWidth": 120,
-	"proseWrap": "never",
 	"trailingComma": "all",
@@ -12,8 +11,2 @@ "endOfLine": "lf",
 		{
-			"files": ["*.html"],
-			"options": {
-				"printWidth": 2000
-			}
-		},
-		{
 			"files": ["*.yml", "*.yaml", ".*.yml", ".*.yaml"],
@@ -20,0 +13,0 @@ "options": {

LICENSE.md

@@ -1,3 +0,12 @@
-Copyright (C) 2017 by Dave Houlbrooke <[e-mail]> Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted.
+Copyright (C) 2017 by Dave Houlbrooke <[e-mail]>
+Permission to use, copy, modify, and/or distribute this software
+for any purpose with or without fee is hereby granted.
 
-THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
+WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
+THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR
+CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
+NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
+CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package.json

 {
 	"name": "schemaglobin",
 	"description": "Validate user-entered data.",
-	"version": "1.0.0",
+	"version": "1.0.1",
 	"repository": "https://github.com/dhoulb/schemaglobin",
@@ -12,3 +12,3 @@ "author": "Dave Houlbrooke <[e-mail]>",
 	"engines": {
-		"node": ">=8.0.0"
+		"node": ">=10.0.0"
 	},
@@ -29,3 +29,3 @@ "scripts": {
 		"@types/jest": "^24.0.23",
-		"@typescript-eslint/eslint-plugin": "^2.9.0",
+		"@typescript-eslint/eslint-plugin": "2.9.0",
 		"@typescript-eslint/parser": "^2.9.0",
@@ -38,3 +38,2 @@ "eslint": "^6.7.1",
 		"prettier": "^1.19.1",
-		"semantic-release": "^15.13.31",
 		"ts-jest": "^24.2.0",
@@ -41,0 +40,0 @@ "typescript": "^3.7.2"

README.md

 # Schemaglobin: Validate unknown user input against schemas
 
-[![Semantic Release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg?style=flat)](https://github.com/semantic-release/semantic-release) [![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg)](https://conventionalcommits.org) [![Prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://github.com/prettier/prettier) [![GitHub Actions](https://img.shields.io/github/workflow/status/dhoulb/schemaglobin/test/master)](https://github.com/dhoulb/schemaglobin/actions) [![npm](https://img.shields.io/npm/dm/schemaglobin.svg)](https://www.npmjs.com/package/schemaglobin)
+[![Semantic Release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg?style=flat)](https://github.com/semantic-release/semantic-release)
+[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg)](https://conventionalcommits.org)
+[![Prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://github.com/prettier/prettier)
+[![GitHub Actions](https://img.shields.io/github/workflow/status/dhoulb/schemaglobin/CI/master)](https://github.com/dhoulb/schemaglobin/actions)
+[![npm](https://img.shields.io/npm/dm/schemaglobin.svg)](https://www.npmjs.com/package/schemaglobin)
+[![Greenkeeper badge](https://badges.greenkeeper.io/dhoulb/schemaglobin.svg)](https://greenkeeper.io/)
 
@@ -43,5 +48,10 @@ **Schemaglobin** is a schema validator for user input written for JavaScript and TypeScript with special attention paid to TypeScript types.
 
+	// Note that the TypeScript type of data is:
+	// { name: string, age: number, status: boolean } | Invalid
+
 	// The data was invalid. Throw an error.
 	if (data instanceof Invalid) throw new ServerError("Invalid input: " + data.message);
 
+	// Note: Now that we've filtered out Invalid we know the type is just the expect data object.
+
 	// The data is valid. Now we can save it to the database safely.
@@ -55,2 +65,86 @@ const status = saveToDatabase(data);
 
+### Invalid values
+
+Is you pass an invalid value into `validate()` then two things might happen: 1) If the invalid value can be trivially converted to a valid value without data loss, it will be converted and returned, or 2) An instance of `Invalid` will be returned:
+
+```ts
+import { string, number, email, url, boolean, Invalid } from "schemaglobin";
+
+// Trivial conversion.
+boolean().validate("abc"); // Returns `true`
+boolean().validate(""); // Returns `false`
+string().validate(123); // Returns "123" string.
+number().validate("123.456"); // Returns 123.456 number.
+
+// Fully invalid values.
+string().validate(true); // Returns Invalid("Must be string")
+number().validate("abc"); // Returns Invalid("Must be number or null")
+email().validate("abc"); // Returns Invalid("Invalid email format")
+url().validate("abc"); // Returns Invalid("Invalid URL format")
+```
+
+With object schemas, `options.props` is used to fill (and trivially convert) missing object props:
+
+```ts
+import { object, number, string } from "schemaglobin";
+
+// Make an object schema.
+const schema = object({
+	props: {
+		name: string({ value: "DEFAULT" }),
+		age: number(),
+	},
+});
+
+// Returns { name: "DEFAULT", age: 123 }
+schema.validate({ age: "123" });
+
+// Returns { name: "Dave", age: null }
+schema.validate({ name: "Dave" });
+```
+
+Instances of `Invalid` contain a string `.message` property describing the issue:
+
+```ts
+const invalid = url().validate("abc");
+console.error(invalid.message); // Logs "Invalid URL format"
+```
+
+When validating an object, it's possible the _contents_ might be invalid. In this situation `Invalid` also has a `.messages` object specifying where, within the object, the data was invalid.
+
+```ts
+import { object, string, number } from "schemaglobin"
+
+// Make an object schema with `options.props`
+const schema = object({
+	props: {
+		name: string({ required: true }),
+		age: number({ min 0, max: 200 }),
+	}
+});
+
+// Validate an invalid value.
+const invalid = schema.validate({ age: 900 });
+
+console.log(invalid.message); // "Invalid format"
+console.log(invalid.messages); // { name: "Required", age: "Maximum 200" }
+```
+
+This also works for arrays. The keys in `.messages` will be numeric strings:
+
+```ts
+import { array, string } from "schemaglobin";
+
+// Make an array schema with `options.items`
+const schema = array({
+	items: string({ required: true }),
+});
+
+// Validate an invalid value.
+const invalid = schema.validate([123, true, ""]);
+
+console.log(invalid.message); // "Invalid format"
+console.log(invalid.messages); // { "1": "Must be string", "2": "Required" }
+```
+
 ### Validating different types
@@ -130,7 +224,13 @@
 
-If you're a TypeScript user, Schemaglobin pays special attention to the type of the value returned by `validate()`, for example:
+Schemaglobin pays special attention to the TypeScript type of values returned by `validate()`, for example:
 
-- `NumberSchema.validate()` normally returns `number | null | Invalid`, but if `options.required` is truthy the value will never be `null` (as that would be invalid) so it only returns `number | Invalid`
-- `StringSchema.validate()` normally returns `string | Invalid`, but if `options.options` is set it will return a more specific type, e.g. `"a" | "b" | "" | Invalid`
-- `ObjectSchema.validate()` normally returns `{}, but if`options.props`a more specific type will be returned, e.g.`{ a: string, b: number }`
+- `NumberSchema.validate()`
+  - Normally returns `number | null | Invalid`
+  - If `options.required` is truthy the value will never be `null` (as that would be invalid) so it only returns `number | Invalid`
+- `StringSchema.validate()`
+  - Normally returns `string | Invalid`
+  - If `options.options` is set it can return a more specific type, e.g. `"a" | "b" | "" | Invalid`
+- `ObjectSchema.validate()`
+  - Normally returns `{}`
+  - If `options.props` is set it can return a more specific type, e.g.`{ a: string, b: number }`
 
@@ -157,3 +257,5 @@ ```ts
 });
-const obj = objectSchema.validate(undefined); // Has type `{ num: number | null, str: string, bool: true } | Invalid`
+
+// Validated value has type `{ num: number | null, str: string, bool: true } | Invalid`
+const obj = objectSchema.validate(undefined);
 if (!(obj instanceof Invalid)) {
@@ -166,3 +268,3 @@ const num: number | null = obj.num; // No error.
 
-Schemaglobin also provides the `SchemaType<Schema>` and `SchemaRequired<Schema>` helper type, which allow you to extract the type of a schema and whether or not it is required.
+Schemaglobin also provides the `SchemaType<Schema>` and `SchemaRequired<Schema>` helper type, which allow you to extract the type of a schema and whether or not it is required:
 
@@ -183,2 +285,6 @@ ```ts
 type OptionalEnumType = SchemaType<typeof optionalEnumSchema>; // "a" | "b" | ""
+
+// Object type can be inferred from `options.props`
+const objectSchema = object({ props: { str: string(), num: number() } });
+type ObjectType = Schematype<typeof objectSchema>; // { str: string, num: number | null }
 ```
@@ -343,1 +449,5 @@
 - `options.items: Schema = null` - Schema that will be used to validate any additional properties in the object.
+
+## Changelog
+
+See [Releases](https://github.com/dhoulb/blork/releases)

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

186841

increased by1.76%

Dev dependency count

11

decreased by-8.33%

Number of lines in readme file

447

increased by32.64%

Worsened metrics

Lines of code

3985

decreased by-0.18%

No dependency changes