justus 0.0.2 → 0.0.6

package/src/index.ts

@@ -9,16 +9,17 @@ export * from './types'
 export * from './utilities'
 
 // Validators
-export { allOf, oneOf, AllOfValidator, OneOfValidator } from './validators/union'
+export { allOf, oneOf, AllOfValidator, InferAllOfValidationType, InferOneOfValidationType, OneOfValidator, UnionArguments } from './validators/union'
 export { any, AnyValidator } from './validators/any'
-export { array, arrayOf, AnyArrayValidator, ArrayValidator } from './validators/array'
+export { _array, array, arrayOf, AnyArrayValidator, ArrayConstraints, ArrayValidator } from './validators/array'
 export { boolean, BooleanValidator } from './validators/boolean'
 export { constant, ConstantValidator } from './validators/constant'
-export { date, DateValidator } from './validators/date'
-export { number, AnyNumberValidator, NumberValidator } from './validators/number'
-export { object, AnyObjectValidator, ObjectValidator } from './validators/object'
-export { string, AnyStringValidator, StringValidator } from './validators/string'
-export { tuple, TupleValidator } from './validators/tuple'
+export { _date, date, DateConstraints, DateValidator } from './validators/date'
+export { _number, number, AnyNumberValidator, BrandedNumberConstraints, NumberConstraints, NumberValidator } from './validators/number'
+export { _object, object, AnyObjectValidator, ObjectProperty, ObjectValidator } from './validators/object'
+export { _string, string, AnyStringValidator, BrandedStringConstraints, StringConstraints, StringValidator } from './validators/string'
+export { tuple, TupleMember, TupleValidator } from './validators/tuple'
+export { _url, url, URLConstraints, URLValidator } from './validators/url'
 
 /* ========================================================================== *
  * VALIDATE FUNCTION (our main entry point)                                   *
@@ -32,7 +33,12 @@ export type ValidateOptions = {
   -readonly [ key in keyof ValidationOptions ]?: ValidationOptions[key] | undefined
 }
 
-/** Validate a _value_ using the specified `Validation` */
+/**
+ * Validate a _value_ using the specified `Validation`.
+ *
+ * By default additional and forbidden properties will _not_ be stripped and
+ * reported as an error.
+ */
 export function validate<V extends Validation>(
     validation: V,
     value: any,
@@ -41,6 +47,36 @@ export function validate<V extends Validation>(
   const opts: ValidationOptions = {
     stripAdditionalProperties: false,
     stripForbiddenProperties: false,
+    stripOptionalNulls: false,
+    ...options,
+  }
+
+  return getValidator(validation).validate(value, opts)
+}
+
+/**
+ * Validate a _value_ using the specified `Validation`, automatically stripping
+ * additional properties and optional `null`s (but not forbidden ones).
+ *
+ * This is equivalent to:
+ *
+ * ```
+ * validate(validation, value, {
+ *   stripAdditionalProperties: true,
+ *   stripForbiddenProperties: false,
+ *   stripOptionalNulls: true,
+ * })
+ * ```
+ */
+export function strip<V extends Validation>(
+    validation: V,
+    value: any,
+    options: ValidateOptions = {},
+): InferValidation<V> {
+  const opts: ValidationOptions = {
+    stripAdditionalProperties: true,
+    stripForbiddenProperties: false,
+    stripOptionalNulls: true,
     ...options,
   }
 

package/src/schema.ts

@@ -19,12 +19,12 @@ import {
  * ========================================================================== */
 
 /** Internal definition of `allowAdditionalProperties(...)` */
-function _allowAdditionalProperties(): AdditionalProperties<Validator<any>>
-function _allowAdditionalProperties(allow: true): AdditionalProperties<Validator<any>>
-function _allowAdditionalProperties(allow: false): AdditionalProperties<false>
-function _allowAdditionalProperties<V extends Validation>(validation: V): AdditionalProperties<Validator<InferValidation<V>>>
+export function _allowAdditionalProperties(): AdditionalProperties<Validator<any>>
+export function _allowAdditionalProperties(allow: true): AdditionalProperties<Validator<any>>
+export function _allowAdditionalProperties(allow: false): AdditionalProperties<false>
+export function _allowAdditionalProperties<V extends Validation>(validation: V): AdditionalProperties<Validator<InferValidation<V>>>
 
-function _allowAdditionalProperties(options?: Validation | boolean): AdditionalProperties<Validator | false> {
+export function _allowAdditionalProperties(options?: Validation | boolean): AdditionalProperties<Validator | false> {
   if (options === false) return { [additionalValidator]: false }
   if (options === true) return { [additionalValidator]: any }
 
@@ -49,7 +49,7 @@ allowAdditionalProperties[additionalValidator] = any
  * SCHEMA KEYS MODIFIERS                                                      *
  * ========================================================================== */
 
-type CombineModifiers<M1 extends Modifier, M2 extends Modifier> =
+export type CombineModifiers<M1 extends Modifier, M2 extends Modifier> =
   M1 extends ReadonlyModifier ?
     M2 extends ReadonlyModifier<infer V> ? ReadonlyModifier<V> :
     M2 extends OptionalModifier<infer V> ? CombinedModifier<V> :

package/src/types.ts

@@ -27,6 +27,8 @@ export const never = Symbol.for('justus.never')
 export interface ValidationOptions {
   /** Strip additional, undeclared properties from objects */
   readonly stripAdditionalProperties: boolean,
+  /** Strip `null`s from an object when associated with an optional key */
+  readonly stripOptionalNulls: boolean,
   /** Ignore and strip forbidden (`never`) properties from objects */
   readonly stripForbiddenProperties: boolean,
 }
@@ -115,7 +117,7 @@ export type InferValidation<V> =
  * ========================================================================== */
 
 /** Infer the type validated by a `Validation` or `TupleRestParameter` */
-type InferValidationOrTupleRest<T> =
+export type InferValidationOrTupleRest<T> =
   T extends TupleRestParameter<infer X> ? X :
   T extends Validation ? InferValidation<T> :
   never
@@ -237,7 +239,7 @@ export type InferSchema<S extends Schema> =
 /* -------------------------------------------------------------------------- */
 
 /** Infer the type of keys associated with `Validation`s */
-type InferRequired<S extends Schema> = {
+export type InferRequired<S extends Schema> = {
   [ key in keyof S as
       key extends string ?
         S[key] extends Validation ? key :
@@ -251,7 +253,7 @@ type InferRequired<S extends Schema> = {
 /* -------------------------------------------------------------------------- */
 
 /** Infer the type of _read only_ `Schema` properties  */
-type InferReadonlyModifiers<S extends Schema> = {
+export type InferReadonlyModifiers<S extends Schema> = {
   readonly [ key in keyof S as
     key extends string ?
       S[key] extends OptionalModifier<Validator> ? never :
@@ -263,7 +265,7 @@ type InferReadonlyModifiers<S extends Schema> = {
 }
 
 /** Infer the type of _optional_ `Schema` properties  */
-type InferOptionalModifiers<S extends Schema> = {
+export type InferOptionalModifiers<S extends Schema> = {
   [ key in keyof S as
     key extends string ?
       S[key] extends ReadonlyModifier<Validator> ? never :
@@ -275,7 +277,7 @@ type InferOptionalModifiers<S extends Schema> = {
 }
 
 /** Infer the type of  _read only_ **and** _optional_ `Schema` properties  */
-type InferCombinedModifiers<S extends Schema> = {
+export type InferCombinedModifiers<S extends Schema> = {
   readonly [ key in keyof S as
     key extends string ?
       S[key] extends CombinedModifier ? key :
@@ -288,7 +290,7 @@ type InferCombinedModifiers<S extends Schema> = {
 /* -------------------------------------------------------------------------- */
 
 /** Ensure that we properly type `never` properties */
-type InferNever<S extends Schema> =
+export type InferNever<S extends Schema> =
   { [ key in keyof S as
       key extends string ?
         S[key] extends typeof never ? key :

package/src/validators/array.ts

@@ -91,10 +91,10 @@ const anyArrayValidator = new AnyArrayValidator()
 
 /* -------------------------------------------------------------------------- */
 
-function _array(): Validator<any[]>
-function _array<V extends Validation>(constraints: ArrayConstraints<V>): ArrayValidator<InferValidation<V>>
+export function _array(): Validator<any[]>
+export function _array<V extends Validation>(constraints: ArrayConstraints<V>): ArrayValidator<InferValidation<V>>
 
-function _array(options?: ArrayConstraints<Validation>): Validator<any[]> {
+export function _array(options?: ArrayConstraints<Validation>): Validator<any[]> {
   if (! options) return anyArrayValidator
 
   const items = getValidator(options.items)

package/src/validators/date.ts

@@ -67,10 +67,10 @@ export class DateValidator extends Validator<Date> {
 
 const anyDateValidator = new DateValidator()
 
-function _date(): DateValidator
-function _date(constraints: DateConstraints): DateValidator
+export function _date(): DateValidator
+export function _date(constraints: DateConstraints): DateValidator
 
-function _date(constraints?: DateConstraints): DateValidator {
+export function _date(constraints?: DateConstraints): DateValidator {
   return constraints ? new DateValidator(constraints) : anyDateValidator
 }
 

package/src/validators/number.ts

@@ -150,12 +150,12 @@ export class NumberValidator<N extends number = number> extends Validator<N> {
 
 const anyNumberValidator = new AnyNumberValidator()
 
-function _number(): Validator<number>
-function _number(constraints?: NumberConstraints): NumberValidator<number>
-function _number<N extends number>(constraints?: NumberConstraints): NumberValidator<N>
-function _number<B extends string>(constraints: BrandedNumberConstraints<B>): NumberValidator<number & Branding<B>>
+export function _number(): Validator<number>
+export function _number(constraints?: NumberConstraints): NumberValidator<number>
+export function _number<N extends number>(constraints?: NumberConstraints): NumberValidator<N>
+export function _number<B extends string>(constraints: BrandedNumberConstraints<B>): NumberValidator<number & Branding<B>>
 
-function _number(constraints?: NumberConstraints): Validator<number> {
+export function _number(constraints?: NumberConstraints): Validator<number> {
   return constraints ? new NumberValidator(constraints) : anyNumberValidator
 }
 

package/src/validators/object.ts

@@ -19,7 +19,7 @@ import { makeTupleRestIterable } from './tuple'
  * OBJECT VALIDATOR                                                           *
  * ========================================================================== */
 
-type ObjectProperty = {
+export type ObjectProperty = {
   validator: Validator,
   readonly?: true,
   optional?: true,
@@ -70,6 +70,8 @@ export class ObjectValidator<S extends Schema> extends Validator<InferSchema<S>>
     assertValidation(typeof value === 'object', 'Value is not an "object"')
     assertValidation(value !== null, 'Value is "null"')
 
+    const { stripAdditionalProperties, stripForbiddenProperties, stripOptionalNulls } = options
+
     const record: { [ k in string | number | symbol ]?: unknown } = value
     const builder = new ValidationErrorBuilder()
     const clone: Record<string, any> = {}
@@ -80,7 +82,7 @@ export class ObjectValidator<S extends Schema> extends Validator<InferSchema<S>>
       // no validator? this is "never" (forbidden)
       if (! validator) {
         if (record[key] === undefined) continue
-        if (options.stripForbiddenProperties) continue
+        if (stripForbiddenProperties) continue
         builder.record('Forbidden property', key)
         continue
       }
@@ -91,6 +93,11 @@ export class ObjectValidator<S extends Schema> extends Validator<InferSchema<S>>
         continue
       }
 
+      // strip any optional "null" value if told to do so
+      if (stripOptionalNulls && optional && (record[key] === null)) {
+        continue
+      }
+
       // all the rest gets validated normally
       try {
         clone[key] = validator.validate(record[key], options)
@@ -111,7 +118,7 @@ export class ObjectValidator<S extends Schema> extends Validator<InferSchema<S>>
           builder.record(error, key)
         }
       })
-    } else if (! options.stripAdditionalProperties) {
+    } else if (! stripAdditionalProperties) {
       additionalKeys.forEach((key) => {
         if (record[key] !== undefined) builder.record('Unknown property', key)
       })
@@ -123,11 +130,11 @@ export class ObjectValidator<S extends Schema> extends Validator<InferSchema<S>>
 
 const anyObjectValidator = new AnyObjectValidator()
 
-function _object(): Validator<Record<string, any>>
-function _object<S extends Schema>(schema: S): S & {
+export function _object(): Validator<Record<string, any>>
+export function _object<S extends Schema>(schema: S): S & {
   [Symbol.iterator](): Generator<TupleRestParameter<InferSchema<S>>>
 }
-function _object(schema?: Schema): Validator<Record<string, any>> | Schema {
+export function _object(schema?: Schema): Validator<Record<string, any>> | Schema {
   if (! schema) return anyObjectValidator
 
   const validator = new ObjectValidator(schema)

package/src/validators/string.ts

@@ -71,12 +71,12 @@ export class StringValidator<S extends string = string> extends Validator<S> {
 
 const anyStringValidator = new AnyStringValidator()
 
-function _string(): Validator<string>
-function _string(constraints?: StringConstraints): StringValidator<string>
-function _string<S extends string>(constraints?: StringConstraints): StringValidator<S>
-function _string<B extends string>(constraints: BrandedStringConstraints<B>): StringValidator<string & Branding<B>>
+export function _string(): Validator<string>
+export function _string(constraints?: StringConstraints): StringValidator<string>
+export function _string<S extends string>(constraints?: StringConstraints): StringValidator<S>
+export function _string<B extends string>(constraints: BrandedStringConstraints<B>): StringValidator<string & Branding<B>>
 
-function _string(constraints?: StringConstraints): Validator<string> {
+export function _string(constraints?: StringConstraints): Validator<string> {
   return constraints ? new StringValidator(constraints) : anyStringValidator
 }
 

package/src/validators/tuple.ts

@@ -4,7 +4,7 @@ import { assertValidation, ValidationError } from '../errors'
 import { getValidator } from '../utilities'
 import { nullValidator } from './constant'
 
-interface TupleMember { single: boolean, validator: Validator }
+export interface TupleMember { single: boolean, validator: Validator }
 
 /** A `Validator` for _tuples_. */
 export class TupleValidator<T extends Tuple> extends Validator<InferTuple<T>> {

package/src/validators/union.ts

@@ -7,11 +7,11 @@ import {
   Validator,
 } from '../types'
 
-type UnionArguments = readonly [ Validation, ...Validation[] ]
+export type UnionArguments = readonly [ Validation, ...Validation[] ]
 
 /* -------------------------------------------------------------------------- */
 
-type InferOneOfValidationType<A extends UnionArguments> =
+export type InferOneOfValidationType<A extends UnionArguments> =
   A extends readonly [ infer First, ...infer Rest ] ?
     First extends Validation ?
       Rest extends UnionArguments ?
@@ -49,7 +49,7 @@ export function oneOf<A extends UnionArguments>(...args: A): OneOfValidator<A> {
 
 /* -------------------------------------------------------------------------- */
 
-type InferAllOfValidationType<A extends UnionArguments> =
+export type InferAllOfValidationType<A extends UnionArguments> =
   A extends readonly [ infer First, ...infer Rest ] ?
     First extends Validation ?
       Rest extends UnionArguments ?

package/src/validators/url.ts

@@ -0,0 +1,141 @@
+import { ConstantValidator } from './constant'
+import { ValidationError, ValidationErrorBuilder } from '../errors'
+import { Schema, Validator } from '../types'
+import { makeTupleRestIterable } from './tuple'
+import { ObjectValidator, ValidationOptions } from '..'
+
+const KEYS: Exclude<keyof URLConstraints, 'searchParams'>[] = [
+  'href',
+  'origin',
+  'protocol',
+  'username',
+  'password',
+  'host',
+  'hostname',
+  'port',
+  'pathname',
+  'search',
+  'hash',
+]
+
+const OPTIONS: ValidationOptions = {
+  stripAdditionalProperties: false,
+  stripForbiddenProperties: false,
+  stripOptionalNulls: false,
+}
+
+/** Constraints to validate a `URL` with. */
+export interface URLConstraints {
+  /** Constraint to validate the `href` component of the `URL`. */
+  href?: string | Validator<string>,
+  /** Constraint to validate the `origin` component of the `URL`. */
+  origin?: string | Validator<string>,
+  /** Constraint to validate the `protocol` component of the `URL`. */
+  protocol?: string | Validator<string>,
+  /** Constraint to validate the `username` component of the `URL`. */
+  username?: string | Validator<string>,
+  /** Constraint to validate the `password` component of the `URL`. */
+  password?: string | Validator<string>,
+  /** Constraint to validate the `host` (`hostname:port`) component of the `URL`. */
+  host?: string | Validator<string>,
+  /** Constraint to validate the `hostname` component of the `URL`. */
+  hostname?: string | Validator<string>,
+  /** Constraint to validate the `port` component of the `URL`. */
+  port?: string | Validator<string>,
+  /** Constraint to validate the `pathname` component of the `URL`. */
+  pathname?: string | Validator<string>,
+  /** Constraint to validate the `search` component of the `URL` as a string. */
+  search?: string | Validator<string>,
+  /** Constraint to validate the `hash` component of the `URL`. */
+  hash?: string | Validator<string>,
+  /**
+   * Schema used to validate the `searchParams` component of the `URL`.
+   *
+   * The `searchParams` will be normalized in a `Record<string, string>`, where
+   * only the _first_ value associated with a search parameter will be checked.
+   */
+  searchParams?: Schema,
+}
+
+/** A `Validator` validating URLs and converting them to `URL` instances. */
+export class URLValidator extends Validator<URL> {
+  readonly href?: Validator<string>
+  readonly origin?: Validator<string>
+  readonly protocol?: Validator<string>
+  readonly username?: Validator<string>
+  readonly password?: Validator<string>
+  readonly host?: Validator<string>
+  readonly hostname?: Validator<string>
+  readonly port?: Validator<string>
+  readonly pathname?: Validator<string>
+  readonly search?: Validator<string>
+  readonly hash?: Validator<string>
+
+  readonly searchParams?: ObjectValidator<Schema>
+
+  constructor(constraints: URLConstraints = {}) {
+    super()
+
+    for (const key of KEYS) {
+      const constraint = constraints[key]
+      if (typeof constraint === 'string') {
+        this[key] = new ConstantValidator(constraint)
+      } else if (constraint) {
+        this[key] = constraint
+      }
+    }
+
+    if (constraints.searchParams) {
+      this.searchParams = new ObjectValidator(constraints.searchParams)
+    }
+  }
+
+  validate(value: unknown): URL {
+    let url: URL
+    try {
+      url = value instanceof URL ? value : new URL(value as any)
+    } catch (error) {
+      throw new ValidationError('Value could not be converted to a "URL"')
+    }
+
+    const builder = new ValidationErrorBuilder()
+
+    for (const key of KEYS) {
+      const validator = this[key]
+      if (validator) {
+        try {
+          validator.validate(url[key], OPTIONS)
+        } catch (error) {
+          builder.record(error, key)
+        }
+      }
+    }
+
+    if (this.searchParams) {
+      const parameters: Record<string, string> = {}
+      for (const param of url.searchParams.keys()) {
+        parameters[param] = url.searchParams.get(param) as string
+      }
+
+      try {
+        this.searchParams.validate(parameters, OPTIONS)
+      } catch (error) {
+        builder.record(error, 'searchParams')
+      }
+    }
+
+    return builder.assert(url)
+  }
+}
+
+const anyURLValidator = new URLValidator()
+
+export function _url(): URLValidator
+export function _url(constraints: URLConstraints): URLValidator
+
+export function _url(constraints?: URLConstraints): URLValidator {
+  return constraints ? new URLValidator(constraints) : anyURLValidator
+}
+
+/** Validate URLs and convert them to `URL` instances. */
+export const url = makeTupleRestIterable(_url)