validate-value - npm Package Compare versions

Comparing version 8.9.29 to 9.0.0-internal.1

build/lib/index.d.ts

 import { isOfType } from './isOfType';
-import { Value } from './Value';
-import { values } from './values';
-export { isOfType, Value, values };
+import { JSONSchema7 as JsonSchema } from 'json-schema';
+import { parse } from './parse';
+import { Parser } from './Parser';
+export type { JsonSchema };
+export { isOfType, parse, Parser };

build/lib/index.js

 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.values = exports.Value = exports.isOfType = void 0;
+exports.Parser = exports.parse = exports.isOfType = void 0;
 const isOfType_1 = require("./isOfType");
 Object.defineProperty(exports, "isOfType", { enumerable: true, get: function () { return isOfType_1.isOfType; } });
-const Value_1 = require("./Value");
-Object.defineProperty(exports, "Value", { enumerable: true, get: function () { return Value_1.Value; } });
-const values_1 = require("./values");
-Object.defineProperty(exports, "values", { enumerable: true, get: function () { return values_1.values; } });
+const parse_1 = require("./parse");
+Object.defineProperty(exports, "parse", { enumerable: true, get: function () { return parse_1.parse; } });
+const Parser_1 = require("./Parser");
+Object.defineProperty(exports, "Parser", { enumerable: true, get: function () { return Parser_1.Parser; } });

build/lib/isOfType.js

 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isOfType = void 0;
-const Value_1 = require("./Value");
+const Parser_1 = require("./Parser");
 const isOfType = function (data, schema) {
-    const value = new Value_1.Value(schema);
-    return value.isValid(data);
+    const parser = new Parser_1.Parser(schema);
+    return parser.isValid(data);
 };
 exports.isOfType = isOfType;

lib/index.ts

 import { isOfType } from './isOfType';
-import { Value } from './Value';
-import { values } from './values';
+import { JSONSchema7 as JsonSchema } from 'json-schema';
+import { parse } from './parse';
+import { Parser } from './Parser';
 
-export { isOfType, Value, values };
+export type { JsonSchema };
+export { isOfType, parse, Parser };

lib/isOfType.ts

 import { JSONSchema7 } from 'json-schema';
-import { Value } from './Value';
+import { Parser } from './Parser';
 
-const isOfType = function <T>(data: unknown, schema: JSONSchema7): data is T {
-  const value = new Value(schema);
+const isOfType = function <T>(
+  data: unknown,
+  schema: JSONSchema7
+): data is T {
+  const parser = new Parser(schema);
 
-  return value.isValid(data);
+  return parser.isValid(data);
 };
 
-export { isOfType };
+export {
+  isOfType
+};

package.json

 {
   "name": "validate-value",
-  "version": "8.9.29",
+  "version": "9.0.0-internal.1",
   "description": "validate-value validates values against JSON schemas.",
@@ -28,3 +28,5 @@ "contributors": [
     "ajv-formats": "2.1.0",
-    "json-schema": "0.3.0"
+    "defekt": "7.1.0",
+    "json-schema": "0.3.0",
+    "typedescriptor": "4.0.2"
   },
@@ -31,0 +33,0 @@ "devDependencies": {

README.md

@@ -21,2 +21,29 @@ # validate-value
 
+## Philosophy
+
+The rewrite of `validate-value` in version 9.0.0 follows the infamous quote "parse, don't validate"<sup>[1](#footnote-1)</sup>. The quote asserts that parsing data is more valuable than validating it. This is very obvious when comparing the two approaches in TypeScript:
+
+```typescript
+const doThingsWithValidation = async function (options: unknown): Promise<void> {
+    // This throws, if the options are not valid.
+    validateOptions(options);
+
+    const typedOptions = options as Options;
+
+    doSomethingWithAnOption(typedOptions.someOption);
+};
+
+const doThingsWithParsing = async function (options: unknown): Promise<Result<void, Error>> {
+    // This parses the options and unwraps them, throwing if they were invalid.
+    // If invalid options were something our program could handle, we would not
+    // want to throw here and instead handle the error appropriately.
+    // In this example we want the program to crash, if the options are invalid.
+    const typedOptions = parseOptions(options).unwrapOrThrow();
+
+    doSomethingWithAnOption(typedOptions.someOption);
+}
+```
+
+In the second example, the typedOptions contained in the `Result` returned from the `parseOptions` call already have the type that we expect them to have and we don't have to assert them or assign them to a new variable in any way. This combines better support from the TypeScript compiler with better error handling from [`defekt`](https://github.com/thenativeweb/defekt/).
+
 ## Quick start
@@ -27,3 +54,3 @@
 ```javascript
-const { Value, isOfType } = require('validate-value');
+const { isValid, parse, Parser } = require('validate-value');
 ```
@@ -34,9 +61,9 @@
 ```typescript
-import { Value, isOfType } from 'validate-value';
+import { isValid, parse, Parser } from 'validate-value';
 ```
 
-Then, create a new instance and provide a [JSON schema](https://json-schema.org/learn/getting-started-step-by-step.html) that you would like to use for validation:
+Then, create a new instance and provide a [JSON schema](https://json-schema.org/learn/getting-started-step-by-step.html) that you would like to use for parsing:
 
 ```javascript
-const value = new Value({
+const parser = new Parser({
   type: 'object',
@@ -52,4 +79,23 @@ properties: {
 
-Afterwards, you may use the `validate` function to validate a value:
+If you are using typescript, you will want to provide a type for the parsed value:
 
+```typescript
+interface User {
+  username: string;
+  password: string;
+}
+
+const parser = new Parser<User>({
+  type: 'object',
+  properties: {
+    username: { type: 'string' },
+    password: { type: 'string' }
+  },
+  additionalProperties: false,
+  required: [ 'username', 'password' ]
+});
+```
+
+Afterwards, you may use the `parse` function to parse a value:
+
 ```javascript
@@ -61,11 +107,12 @@ const user = {
 
-try {
-  value.validate(user);
-} catch (ex) {
-  // ...
-}
+const result = parser.parse(user);
+const parsedValue = result.unwrapOrThrow();
 ```
 
-By default, the error message uses `value` as identifier and `.` as the separator for the object that is validated, but sometimes you may want to change this. Therefor, provide the desired identifier and separator as second parameter to the `validate` function:
+After parsing, `parsedValue` will have the type `User`, since it was passed to the Parser upon construction.
 
+## Configuring the parser
+
+By default, the error message uses `value` as identifier and `.` as the separator for the object that is parsed, but sometimes you may want to change this. Therefor, provide the desired identifier and separator as second parameter to the `parse` function:
+
 ```javascript
@@ -77,19 +124,21 @@ const user = {
 
-try {
-  value.validate(user, { valueName: 'person', separator: '/' });
-} catch (ex) {
-  // ...
-}
+value.parse(user, { valueName: 'person', separator: '/' });
 ```
 
-From time to time, you may not be interested in the actual error, but only in the fact whether the given object is valid or not. For these cases, use the `isValid` function:
+## Parsing without a parser instance
 
+For convenience, there is also the `parse` function, which skips the creation of a parser instance. You can use this if you're only going to use a schema for validation once. Otherwise, it is recommended to first create a parser instance, since then the json schema is only compiled once.
+
 ```javascript
-const user = {
-  username: 'Jane Doe',
-  password: 'secret'
-};
+const { parse } = require('validate-value');
 
-console.log(value.isValid(user));
-// => true
+parse(user, {
+  type: 'object',
+  properties: {
+    username: { type: 'string' },
+    password: { type: 'string' }
+  },
+  additionalProperties: false,
+  required: [ 'username', 'password' ]
+})
 ```
@@ -102,3 +151,3 @@
 ```javascript
-const { isTypeOf } = require('validate-value');
+const { isOfType } = require('validate-value');
 
@@ -125,6 +174,6 @@ const user = {
 
-When using TypeScript, you may even specify a generic type parameter, and use the function as a type guard. Also it is recommended to use the constant values exported by validate-value instead of the string literals as above, as they are the type-safe versions of these literals:
+When using TypeScript, you may even specify a generic type parameter, and use the function as a type guard.
 
 ```typescript
-import { isTypeOf, value as v }
+import { isOfType, JsonSchema } from 'validate-value';
 
@@ -141,7 +190,7 @@ interface User {
 
-const schema = {
-  type: v.object,
+const schema: JsonSchema = {
+  type: 'object',
   properties: {
-    username: { type: v.string },
-    password: { type: v.string }
+    username: { type: 'string' },
+    password: { type: 'string' }
   },
@@ -157,2 +206,6 @@ additionalProperties: false,
 
+## Resources
+
+<a name="footnote-1">1:</a> ["Parse, don't validate", Alexis King, 2019](https://lexi-lambda.github.io/blog/2019/11/05/parse-don-t-validate/).
+
 ## Running quality assurance
@@ -159,0 +212,0 @@

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

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

New author

Supply chain risk

A new npm collaborator published a version of the package for the first time. New collaborators are usually benign additions to a project, but do indicate a change to the security surface area of a package.

Found 1 instance in 1 package

No v1

Quality

Package is not semver >=1. This means it is not stable and does not support ^ ranges.

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

11699907

increased by32827.8%

Number of package files

35

increased by40%

Lines of code

428

increased by7.27%

Number of lines in readme file

208

increased by34.19%

Worsened metrics

Dependency count

5

increased by66.67%

Number of low quality alerts

2

increased by100%

Number of medium supply chain risk alerts

2

increased byInfinity%

Dependency changes

• + Addeddefekt@7.1.0

• + Addedtypedescriptor@4.0.2

• + Addeddefekt@7.1.07.1.1(transitive)

• + Addedtypedescriptor@4.0.2(transitive)