@modulify/validator 0.0.1 → 0.1.0

package/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+## [0.1.0](https://github.com/modulify/validator/compare/v0.0.2...v0.1.0) (2024-12-22)
+
+
+### ⚠ BREAKING CHANGES
+
+* validator object replaced with validate function, containing sub method sync for synchronous validation
+* Length constraint replaced with HasLength functional assertion
+* Exists constraint replaced with IsDefined functional assertion
+* Each object replaced with Each runner
+* Collection object replaced with HasProperties runner
+* Type "Key" replaced with in-box "PropertyKey"
+* ConstraintCollection type was removed
+* ConstraintValidator was renamed to Validator
+* ConstraintViolation was renamed to Violation
+* d.ts files for exported logic units are now generated and available in dist catalogue
+
+### Features
+
+* Logic redesign and simplification ([b829a1e](https://github.com/modulify/validator/commit/b829a1eb0373cc6069451eb1cdf4767accbe2ee3))
+
+
+### Fixes
+
+* Removed sourcemap ([7e469d0](https://github.com/modulify/validator/commit/7e469d0ca60d854c62a79c54e9b3dba1d3b72657))
+* test coverage ([84912c4](https://github.com/modulify/validator/commit/84912c4a33d58b385a1e0c764c57b3806d658613))
+
+### [0.0.2](https://github.com/modulify/validator/compare/v0.0.1...v0.0.2) (2024-02-05)
+
 ### 0.0.1 (2024-02-05)
 
 

package/README.md

@@ -1,52 +1,60 @@
-# `@modulify/validator`
+# <img src="./logo.png" alt="Logo" width="36" /> `@modulify/validator`
 
 [![codecov](https://codecov.io/gh/modulify/validator/branch/main/graph/badge.svg)](https://codecov.io/gh/modulify/validator)
 [![Tests Status](https://github.com/modulify/validator/actions/workflows/tests.yml/badge.svg)](https://github.com/modulify/validator/actions)
 [![npm version](https://badge.fury.io/js/%40modulify%2Fvalidator.svg)](https://www.npmjs.com/package/@modulify/validator)
 
+This library provides a declarative validation utility.
 
-This library provides a declarative validation util.
-
-The util does not provide any text messages in the constraints produced and gives only metadata that can
+The utility does not include text messages in the generated violations but instead provides metadata that can
 be used to create a custom view for them.
 
 ## Installation
 
-No installation yet
+Using `yarn`:
+
+```
+yarn add @modulify/validator
+```
+
+or, using `npm`:
+
+```
+npm install @modulify/validator --save
+```
 
 ## Usage
 
 ```typescript
 import {
-  Collection,
-  Exists,
-  Length,
-  createValidator,
+  HasLength,
+  HasProperties,
+  IsDefined,
+  IsString,
+  validate,
 } from '@modulify/validator'
 
-const validator = createValidator()
-
-const violations = validator.validate({
+const violations = await validate({
   form: {
     nickname: '',
     password: '',
   },
-}, new Collection({
+}, HasProperties({
   form: [
-    new Exists(),
-    new Collection({
-      nickname: new Length({ min: 4 }),
-      password: new Length({ min: 6 }),
+    IsDefined(),
+    HasProperties({
+      nickname: IsString.That(HasLength({ min: 4 })),
+      password: IsString.That(HasLength({ min: 6 })),
     }),
   ],
-}), /* do not set or set to true for async validation */ false) /* [{
-  by: '@modulify/validator/Length',
+})) /* [{
+  by: '@modulify/validator/IsString',
   value: '',
   path: ['form', 'nickname'],
   reason: 'min',
   meta: 4,
 }, {
-  by: '@modulify/validator/Length',
+  by: '@modulify/validator/IsString',
   value: '',
   path: ['form', 'password'],
   reason: 'min',
@@ -54,124 +62,90 @@ const violations = validator.validate({
 }] */
 ```
 
-### Constraints
-
-Constraints provide information of how the value should be validated.
-
-Available from the box:
-
-* `Collection` &ndash; used for validating objects' structure;
-* `Each` &ndash; used for validating arrays' elements; applies specified constraints to each element of an array;
-* `Exists` &ndash; used for checking if a value is defined; useful for finding missing keys;
-* `Length` &ndash; used for checking arrays' and string's length, available settings (all optional) are:
-  * `exact` &ndash; `number`, array or string should have exactly specified count of elements or characters;
-  * `max` &ndash; `number`, maximum elements in array or maximum characters in string;
-  * `min` &ndash; `number`, minimum elements in array or minimum characters in string;
-* `OneOf` &ndash; used for restricting which values can be used.
-
-There is no any basic constraint class to extend, but they should follow signature
-described in `types/index.d.ts` &ndash; `Constraint`.
-
-### Validators
-
-Validators provide validation logic that relies on information provided by constraints.
-
-There is no any basic validator class to extend, but they should follow signature
-described in `types/index.d.ts` &ndash; `ConstraintValidator`.
-
-### Provider
-
-Provider is used to bind constraints with their validators, provides a validator for a constraint.
-
-All providers should follow signature described in `types/index.d.ts` &ndash; `Provider`.
-
-This feature is responsible for extending validation capabilities. Custom provider can be passed into
-`createValidator` function or `override` method of `Validator` instance.
-
-There is a built-in provider &ndash; `ProviderChain`. It allows to "chain" providers &ndash; if
-suitable validator was not found in currently used provider, it will try to find it in previous provider that was
-overridden by `override` method.
+or (for synchronous validation):
 
 ```typescript
-import type {
-  Constraint,
-  ConstraintValidator,
-  ConstraintViolation,
-  Key,
-  Provider,
-} from '@modulify/validator'
-
-import {
-  ProviderChain,
-  createValidator,
-} from '@modulify/validator'
-
-class Email implements Constraint {
-  public readonly name = '@app/validator/Email'
-
-  toViolation (value: unknown, path: Key[]): ConstraintViolation {
-    return {
-      by: this.name,
-      value,
-      path,
-    }
-  }
-}
-
-class EmailValidator implements ConstraintValidator {
-  private readonly _constraint: Email
-
-  constructor (constraint: Email) {
-    this._constraint = constraint
-  }
-
-  validate (value: unknown, path?: Key[]): ConstraintViolation | null {
-    if (!(typeof value === 'string') || !/\S+@\S+\.\S+/.test(value)) {
-      return this._constraint.toViolation(value, path)
-    }
-
-    return null
-  }
-}
-```
-
-then
-
-```typescript
-const provider = new ProviderChain(new class implements Provider {
-  get (constraint: Constraint) {
-    return constraint instanceof Email ? new EmailValidator(constraint) : null
-  }
-
-  override (provider: Provider): Provider {
-    return new ProviderChain(provider, this)
-  }
-})
-```
-
-or
-
-```typescript
-const provider = new class implements Provider {
-  get (constraint: Constraint) {
-    return constraint instanceof Email ? new EmailValidator(constraint) : null
-  }
-
-  override (provider: Provider): Provider {
-    return new ProviderChain(provider, this)
-  }
-}
-```
-
-and then
-
-```typescript
-const validator = createValidator(provider)
+const violations = validate.sync({
+  form: {
+    nickname: '',
+    password: '',
+  },
+}, HasProperties({
+  form: [
+    IsDefined(),
+    HasProperties({
+      nickname: IsString.That(HasLength({ min: 4 })),
+      password: IsString.That(HasLength({ min: 6 })),
+    }),
+  ],
+}))
 ```
 
-or
-
-```typescript
-const validator = createValidator()
-const overridden = validator.override(provider) // it creates new validator instance, so validator !== overridden
-```
+## Exported types
+
+* `Violation` – an object that contains information about a value – why it violates one or more constraints;
+  includes following fields:
+  * `value` – value that violates something;
+  * `path` – path to the value, an empty array for scalar values and represents full path to the value in a complex
+    object;
+  * `violates` – indicator of the violated constraint;
+  * `reason` – indicator of the reason why the constraint is violated;
+  * `meta` – some data to describe the reason – what exactly the boundaries were not met;
+  ```typescript
+  import type { Violation } from '@modulify/validator/types'
+  ```
+* `Predicate` – function that accepts a value and returns `true` or `false`; logical unit that is used for checking
+  multiple things: type or if the value satisfies certain criteria; accepts generic argument `T` to specify
+  the type of the value, if predicate returns `true`;
+  ```typescript
+  import type { Predicate } from '@modulify/validator/types'
+  ```
+* `Assertion` – extension of the `Predicate` type that includes:
+  * `fqn` – field – some predefined name that will be used as a value for the `violates` field of `Violation`;
+  * `bail` – field – flag that interrupts further validation if the assertion fails;
+  * `reason` – field, optional – string or symbol that is used to indicate, why assertion has failed;
+    always added to a violation object, if present;
+  * `meta` – field, optional – some metadata to use in further analysis; always added to a violation object, if present;
+  * `That` – method – used to extend assertion with other assertions;
+  * `also` – field – readonly array of other assertions that was attached by `That` method;
+  ```typescript
+  import type { Assertion } from '@modulify/validator/types'
+  ```
+
+## Exported members
+
+* `validate` – function that accepts a value for validation as the first argument, constraints as the second,
+  and path to a value as the third (that is optional and used mostly for internal purposes, as validation is recursive);
+  includes method `sync` that has the same arguments set but performs validation synchronously and throws error when
+  finds an asynchronous constraint;
+
+* `Assert` – creates assertion from logical predicate:
+  ```typescript
+  const IsSomething = Assert(isSomething, {
+    fqn: 'Some fqn',
+    bail: true,
+  })
+  ```
+  Arguments:
+  * Logical predicate
+  * Options, that includes `fqn`, `bail`, `reason` (optional), and `meta` (optional);
+* `HasLength` – checks length property of the specified string or array; can be configured with options:
+  * `exact` – if the length should be exactly equal the specified value;
+  * `max` – if the length should be equal or less than the specified value;
+  * `min` – if the length should be equal or greater than the specified value;
+  * `bail` – set this to true if you need to interrupt further validation if the assertion fails;
+* `IsBoolean` – checks if the value is **boolean**; interrupts further validation if fails;
+* `IsDate` – checks if the value is Date **object**; interrupts further validation if fails;
+* `IsDefined` – checks if the value is **not undefined**; interrupts further validation if fails;
+* `IsEmail` – checks if the value is a **valid email**; interrupts further validation if fails;
+* `IsNull` – checks if the value is **null**; interrupts further validation if fails;
+* `IsNumber` – checks if the value is **number**; interrupts further validation if fails;
+* `IsString` – checks if the value is **string**; interrupts further validation if fails;
+* `IsSymbol` – checks if the value is a **symbol**; interrupts further validation if fails;
+* `OneOf` – checks if the value equal to one of the specified values; can be configured with:
+  * `equalTo` – predicate f(a, b) that checks if two values are equal or not;
+  by default the strict `===` comparison is used
+  * `bail` – set this to true if you need to interrupt further validation if the assertion fails;
+
+* `Each` – a runner that runs validation for each element in array;
+* `HasProperties` – a runner that runs object's structure check.

package/dist/assertions/Assert.d.ts

@@ -0,0 +1,2 @@
+import { Assertion, Meta, Predicate } from '../../types';
+export declare const Assert: <T = unknown, M = unknown>(predicate: Predicate<T>, options: Meta<M>) => Assertion<T, M>;

package/dist/assertions/HasLength.d.ts

@@ -0,0 +1,7 @@
+import { Assertion } from '../../types';
+export declare const HasLength: ({ exact, max, min, bail, }: {
+    exact?: number | null;
+    max?: number | null;
+    min?: number | null;
+    bail?: boolean;
+}) => Assertion<string | unknown[], unknown>;

package/dist/assertions/check.d.ts

@@ -0,0 +1,3 @@
+import { Assertion, Violation } from '../../types';
+declare const check: <T = unknown, M = unknown>(assert: Assertion<T, M>, value: unknown, path?: PropertyKey[]) => null | Violation<M>;
+export default check;

package/dist/assertions/index.d.ts

@@ -0,0 +1,16 @@
+import { Assert } from './Assert';
+import { Assertion } from '../../types';
+export { Assert };
+export { HasLength } from './HasLength';
+export declare const IsBoolean: Assertion<boolean, unknown>;
+export declare const IsDate: Assertion<Date, unknown>;
+export declare const IsDefined: Assertion<unknown, unknown>;
+export declare const IsEmail: Assertion<string, unknown>;
+export declare const IsNull: Assertion<null, unknown>;
+export declare const IsNumber: Assertion<number, unknown>;
+export declare const IsString: Assertion<string, unknown>;
+export declare const IsSymbol: Assertion<symbol, unknown>;
+export declare const OneOf: <Actual = unknown>(values: Actual[] | Record<string, Actual>, { equalTo, bail, }?: {
+    equalTo?: (a: Actual, b: unknown) => boolean;
+    bail?: boolean;
+}) => Assertion<Actual, Actual[]>;

package/dist/assertions.cjs

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const predicates = require("./predicates.cjs");
+const delegate = (p) => {
+  return (value) => p(value);
+};
+const Assert = (predicate, options) => {
+  const extender = (asserts = []) => {
+    return {
+      That(...asserts2) {
+        return Object.assign(delegate(predicate), options, extender(asserts2));
+      },
+      get also() {
+        return asserts;
+      }
+    };
+  };
+  return Object.assign(delegate(predicate), options, extender());
+};
+const isGTE = (min) => (x) => predicates.isNumber(x) && x >= min;
+const isLTE = (max) => (x) => predicates.isNumber(x) && x <= max;
+const IsEqual = (exact) => Assert((x) => predicates.isExact(exact)(x.length), {
+  fqn: "@modulify/validator/HasLength[exact]",
+  bail: false,
+  reason: "exact",
+  meta: exact
+});
+const IsGTE = (min) => Assert((x) => isGTE(min)(x.length), {
+  fqn: "@modulify/validator/HasLength[min]",
+  bail: false,
+  reason: "min",
+  meta: min
+});
+const IsLTE = (max) => Assert((x) => isLTE(max)(x.length), {
+  fqn: "@modulify/validator/HasLength[max]",
+  bail: false,
+  reason: "max",
+  meta: max
+});
+const HasLength = ({
+  exact = null,
+  max = null,
+  min = null,
+  bail = false
+}) => Assert(predicates.Or(predicates.isString, predicates.isArray), {
+  fqn: "@modulify/validator/HasLength",
+  bail,
+  reason: "unsupported"
+}).That(
+  ...exact !== null ? [IsEqual(exact)] : [],
+  ...max !== null ? [IsLTE(max)] : [],
+  ...min !== null ? [IsGTE(min)] : []
+);
+const IsBoolean = Assert(predicates.isBoolean, {
+  fqn: "@modulify/validator/IsBoolean",
+  bail: true
+});
+const IsDate = Assert(predicates.isDate, {
+  fqn: "@modulify/validator/IsDate",
+  bail: true
+});
+const IsDefined = Assert(predicates.Not(predicates.isUndefined), {
+  fqn: "@modulify/validator/IsDefined",
+  bail: true,
+  reason: "undefined"
+});
+const IsEmail = Assert(predicates.isEmail, {
+  fqn: "@modulify/validator/IsEmail",
+  bail: true
+});
+const IsNull = Assert(predicates.isNull, {
+  fqn: "@modulify/validator/IsNull",
+  bail: true
+});
+const IsNumber = Assert(predicates.isNumber, {
+  fqn: "@modulify/validator/IsNumber",
+  bail: true
+});
+const IsString = Assert(predicates.isString, {
+  fqn: "@modulify/validator/IsString",
+  bail: true
+});
+const IsSymbol = Assert(predicates.isSymbol, {
+  fqn: "@modulify/validator/IsSymbol",
+  bail: true
+});
+const OneOf = (values, {
+  equalTo = (a, b) => a === b,
+  bail = false
+} = {}) => {
+  const haystack = predicates.isArray(values) ? values : Object.values(values);
+  const oneOf = (value) => haystack.some((allowed) => equalTo(allowed, value));
+  return Assert(oneOf, {
+    fqn: "@modulify/validator/OneOf",
+    bail,
+    meta: haystack
+  });
+};
+exports.Assert = Assert;
+exports.HasLength = HasLength;
+exports.IsBoolean = IsBoolean;
+exports.IsDate = IsDate;
+exports.IsDefined = IsDefined;
+exports.IsEmail = IsEmail;
+exports.IsNull = IsNull;
+exports.IsNumber = IsNumber;
+exports.IsString = IsString;
+exports.IsSymbol = IsSymbol;
+exports.OneOf = OneOf;

package/dist/assertions.d.ts

@@ -0,0 +1,2 @@
+export * from './assertions/index'
+export {}

package/dist/assertions.mjs

@@ -0,0 +1,109 @@
+import { Or, isArray, isString, isExact, isNumber, isBoolean, isDate, Not, isUndefined, isEmail, isNull, isSymbol } from "./predicates.mjs";
+const delegate = (p) => {
+  return (value) => p(value);
+};
+const Assert = (predicate, options) => {
+  const extender = (asserts = []) => {
+    return {
+      That(...asserts2) {
+        return Object.assign(delegate(predicate), options, extender(asserts2));
+      },
+      get also() {
+        return asserts;
+      }
+    };
+  };
+  return Object.assign(delegate(predicate), options, extender());
+};
+const isGTE = (min) => (x) => isNumber(x) && x >= min;
+const isLTE = (max) => (x) => isNumber(x) && x <= max;
+const IsEqual = (exact) => Assert((x) => isExact(exact)(x.length), {
+  fqn: "@modulify/validator/HasLength[exact]",
+  bail: false,
+  reason: "exact",
+  meta: exact
+});
+const IsGTE = (min) => Assert((x) => isGTE(min)(x.length), {
+  fqn: "@modulify/validator/HasLength[min]",
+  bail: false,
+  reason: "min",
+  meta: min
+});
+const IsLTE = (max) => Assert((x) => isLTE(max)(x.length), {
+  fqn: "@modulify/validator/HasLength[max]",
+  bail: false,
+  reason: "max",
+  meta: max
+});
+const HasLength = ({
+  exact = null,
+  max = null,
+  min = null,
+  bail = false
+}) => Assert(Or(isString, isArray), {
+  fqn: "@modulify/validator/HasLength",
+  bail,
+  reason: "unsupported"
+}).That(
+  ...exact !== null ? [IsEqual(exact)] : [],
+  ...max !== null ? [IsLTE(max)] : [],
+  ...min !== null ? [IsGTE(min)] : []
+);
+const IsBoolean = Assert(isBoolean, {
+  fqn: "@modulify/validator/IsBoolean",
+  bail: true
+});
+const IsDate = Assert(isDate, {
+  fqn: "@modulify/validator/IsDate",
+  bail: true
+});
+const IsDefined = Assert(Not(isUndefined), {
+  fqn: "@modulify/validator/IsDefined",
+  bail: true,
+  reason: "undefined"
+});
+const IsEmail = Assert(isEmail, {
+  fqn: "@modulify/validator/IsEmail",
+  bail: true
+});
+const IsNull = Assert(isNull, {
+  fqn: "@modulify/validator/IsNull",
+  bail: true
+});
+const IsNumber = Assert(isNumber, {
+  fqn: "@modulify/validator/IsNumber",
+  bail: true
+});
+const IsString = Assert(isString, {
+  fqn: "@modulify/validator/IsString",
+  bail: true
+});
+const IsSymbol = Assert(isSymbol, {
+  fqn: "@modulify/validator/IsSymbol",
+  bail: true
+});
+const OneOf = (values, {
+  equalTo = (a, b) => a === b,
+  bail = false
+} = {}) => {
+  const haystack = isArray(values) ? values : Object.values(values);
+  const oneOf = (value) => haystack.some((allowed) => equalTo(allowed, value));
+  return Assert(oneOf, {
+    fqn: "@modulify/validator/OneOf",
+    bail,
+    meta: haystack
+  });
+};
+export {
+  Assert,
+  HasLength,
+  IsBoolean,
+  IsDate,
+  IsDefined,
+  IsEmail,
+  IsNull,
+  IsNumber,
+  IsString,
+  IsSymbol,
+  OneOf
+};