Options
All
  • Public
  • Public/Protected
  • All
Menu

Namespace Mapper

A module for defining functional schemas to map between different types. This module is useful for parsing to or from JSON/protobufs to domain types.

Mappers support greedy validation, so all validation errors are aggregated and reported vs failing on the first invalid input.

example
import { Mapper as M } from '@vertexvis/utils';

interface Address {
  address: string;
  city: string;
  state: string;
  zip: string;
}

interface Person {
  name: string;
  addresses: Address[];
}

type AddressJson = Partial<Address>;
type PersonJson = {
  name?: string;
  addresses?: AddressJson[];
}

const mapAddress: M.Func<AddressJson, Address> = M.defineMapper(
  M.read(
    M.requireProp('address'),
    M.requireProp('city'),
    M.requireProp('state'),
    M.requireProp('zip')
  ),
  ([address, city, state, zip]) => ({
    address, city, state, zip
  })
);

const mapPerson: M.Func<PersonJson, Person> = M.defineMapper(
  M.read(
    M.requireProp('name'),
    M.mapProp(
      'addresses',
      M.compose(M.required('addresses'), M.mapArray(mapAddress))
    )
  ),
  ([name, addresses]) => ({ name, addresses })
);

const person = mapPerson({
  name: 'John',
  addresses: [{ address: '123', city: 'Ames', state: 'IA', zip: '50010' }]
});

const invalidPerson = mapPerson({
  addresses: [{ city: 'Ames', state: 'IA', zip: '50010' }]
});

// { // errors: ["Name is required.", "Address is required."] // }

Index

Classes

Interfaces

Type Aliases

Functions

Type Aliases

Func

Func<T, R>: ((input: T) => Validated<R>)

Type Parameters

  • T

  • R

Type declaration

    • A function that transforms an input into another type, or an invalid result if the input violates the schema.

      Parameters

      • input: T

      Returns Validated<R>

ThrowIfInvalidFunc

ThrowIfInvalidFunc<T, R>: ((input: T) => R)

Type Parameters

  • T

  • R

Type declaration

    • (input: T): R

    • A function that transforms an input into another type, or throws if the input is invalid.

      Parameters

      • input: T

      Returns R

Validated

Validated<T>: Invalid | T

A type that represents either a valid or invalid input.

Type Parameters

  • T

Functions

compose

defineMapper

  • defineMapper<T, V, R>(reader: Func<T, V>, builder: Func<V, R>): Func<T, R>

  • Defines a mapper that reads the values from an input and invokes a builder to transform data from one schema to another.

    example
    import { Mapper as M } from '@vertexvis/utils';

    interface Address {
      address: string;
      city: string;
      state: string;
      zip: string;
    }

    interface Person {
      name: string;
      addresses: Address[];
    }

    type AddressJson = Partial<Address>;
    type PersonJson = {
      name?: string;
      addresses?: AddressJson[];
    }

    const mapAddress: M.Func<AddressJson, Address> = M.defineMapper(
      M.read(
        M.requireProp('address'),
        M.requireProp('city'),
        M.requireProp('state'),
        M.requireProp('zip')
      ),
      ([address, city, state, zip]) => ({
        address, city, state, zip
      })
    );

    const mapPerson: M.Func<PersonJson, Person> = M.defineMapper(
      M.read(
        M.requireProp('name'),
        M.mapProp(
          'addresses',
          M.compose(M.required('addresses'), M.mapArray(mapAddress))
        )
      ),
      ([name, addresses]) => ({ name, addresses })
    )

    const person = mapPerson({
      name: 'John',
      addresses: [{ address: '123', city: 'Ames', state: 'IA', zip: '50010' }]
    })
    see

    read - a helper function to read and validate input values.

    Type Parameters

    • T

    • V

    • R

    Parameters

    • reader: Func<T, V>

      The mapper that reads values from the input an creates an intermediate format that will be passed to the builder.

    • builder: Func<V, R>

      A mapper that takes the output of reader and constructs the output format.

    Returns Func<T, R>

getProp

  • getProp<T, P>(prop: P): Func<T, T[P]>

  • Returns a mapper that extracts a property's value.

    Type Parameters

    • T

    • P extends string | number | symbol

    Parameters

    • prop: P

      The property to extract.

    Returns Func<T, T[P]>

ifDefined

  • ifDefined<T, R>(mapper: Func<T, undefined | null | R>): Func<T | null | undefined, R | null | undefined>

  • Returns a mapper that invokes a function if the input is not null or not undefined.

    Type Parameters

    • T

    • R

    Parameters

    • mapper: Func<T, undefined | null | R>

      A mapping function.

    Returns Func<T | null | undefined, R | null | undefined>

ifInvalidThrow

isInvalid

  • isInvalid(obj: unknown): obj is Invalid

mapArray

  • mapArray<T, R>(mapper: Func<T, R>): Func<T[], R[]>

  • Returns a mapper that will invoke a mapper over each value in the input array. Returns Invalid containing errors for all invalid values in the array.

    Type Parameters

    • T

    • R

    Parameters

    • mapper: Func<T, R>

      A function that will be invoked with each array value.

    Returns Func<T[], R[]>

mapProp

  • mapProp<T, P, R>(prop: P, mapper: Func<T[P], R>): Func<T, R>

  • Returns a mapper that will invoke a mapping function on an input's property.

    Type Parameters

    • T

    • P extends string | number | symbol

    • R

    Parameters

    • prop: P

      The name of the property to map over.

    • mapper: Func<T[P], R>

      A function that will be invoked with the property's value.

    Returns Func<T, R>

mapRequiredProp

  • mapRequiredProp<T, P, R>(prop: P, mapper: Func<NonNullable<T[P]>, R>): Func<T, R>

  • Returns a mapper that will check if the given property is defined, and if so invoke the given mapping function.

    Type Parameters

    • T

    • P extends string | number | symbol

    • R

    Parameters

    • prop: P

      The name of the property to map over.

    • mapper: Func<NonNullable<T[P]>, R>

      A function that will be invoked with the property's value if the property is defined.

    Returns Func<T, R>

pickFirst

  • pickFirst<T, A, B>(a: Func<T, undefined | A>, b: Func<T, undefined | B>): Func<T, A | B | undefined>
  • pickFirst<T, A, B, C>(a: Func<T, undefined | A>, b: Func<T, undefined | B>, c: Func<T, undefined | C>): Func<T, A | B | C | undefined>
  • pickFirst<T, A, B, C, D>(a: Func<T, undefined | A>, b: Func<T, undefined | B>, c: Func<T, undefined | C>, d: Func<T, undefined | D>): Func<T, A | B | C | undefined>
  • pickFirst<T, A, B, C, D, E>(a: Func<T, undefined | A>, b: Func<T, undefined | B>, c: Func<T, undefined | C>, d: Func<T, undefined | D>, e: Func<T, undefined | E>): Func<T, A | B | C | D | E | undefined>
  • pickFirst<T, A, B, C, D, E, F>(a: Func<T, undefined | A>, b: Func<T, undefined | B>, c: Func<T, undefined | C>, d: Func<T, undefined | D>, e: Func<T, undefined | E>, f: Func<T, undefined | F>): Func<T, A | B | C | D | E | F | undefined>
  • pickFirst<T, A, B, C, D, E, F, G>(a: Func<T, undefined | A>, b: Func<T, undefined | B>, c: Func<T, undefined | C>, d: Func<T, undefined | D>, e: Func<T, undefined | E>, f: Func<T, undefined | F>, g: Func<T, undefined | G>): Func<T, A | B | C | D | E | F | G | undefined>
  • pickFirst<T, A, B, C, D, E, F, G, H>(a: Func<T, undefined | A>, b: Func<T, undefined | B>, c: Func<T, undefined | C>, d: Func<T, undefined | D>, e: Func<T, undefined | E>, f: Func<T, undefined | F>, g: Func<T, undefined | G>, h: Func<T, undefined | H>): Func<T, A | B | C | D | E | F | G | H | undefined>
  • pickFirst<T, A, B, C, D, E, F, G, H, I>(a: Func<T, undefined | A>, b: Func<T, undefined | B>, c: Func<T, undefined | C>, d: Func<T, undefined | D>, e: Func<T, undefined | E>, f: Func<T, undefined | F>, g: Func<T, undefined | G>, h: Func<T, undefined | H>, i: Func<T, undefined | I>): Func<T, A | B | C | D | E | F | G | H | I | undefined>
  • pickFirst<T, A, B, C, D, E, F, G, H, I, J>(a: Func<T, undefined | A>, b: Func<T, undefined | B>, c: Func<T, undefined | C>, d: Func<T, undefined | D>, e: Func<T, undefined | E>, f: Func<T, undefined | F>, g: Func<T, undefined | G>, h: Func<T, undefined | H>, i: Func<T, undefined | I>, j: Func<T, undefined | J>): Func<T, A | B | C | D | E | F | G | H | I | J | undefined>

read

  • read<T, R1>(a: Func<T, R1>): Func<T, [R1]>
  • read<T, R1, R2>(a: Func<T, R1>, b: Func<T, R2>): Func<T, [R1, R2]>
  • read<T, R1, R2, R3>(a: Func<T, R1>, b: Func<T, R2>, c: Func<T, R3>): Func<T, [R1, R2, R3]>
  • read<T, R1, R2, R3, R4>(a: Func<T, R1>, b: Func<T, R2>, c: Func<T, R3>, d: Func<T, R4>): Func<T, [R1, R2, R3, R4]>
  • read<T, R1, R2, R3, R4, R5>(a: Func<T, R1>, b: Func<T, R2>, c: Func<T, R3>, d: Func<T, R4>, e: Func<T, R5>): Func<T, [R1, R2, R3, R4, R5]>
  • read<T, R1, R2, R3, R4, R5, R6>(a: Func<T, R1>, b: Func<T, R2>, c: Func<T, R3>, d: Func<T, R4>, e: Func<T, R5>, f: Func<T, R6>): Func<T, [R1, R2, R3, R4, R5, R6]>
  • read<T, R1, R2, R3, R4, R5, R6, R7>(a: Func<T, R1>, b: Func<T, R2>, c: Func<T, R3>, d: Func<T, R4>, e: Func<T, R5>, f: Func<T, R6>, g: Func<T, R7>): Func<T, [R1, R2, R3, R4, R5, R6, R7]>
  • read<T, R1, R2, R3, R4, R5, R6, R7, R8>(a: Func<T, R1>, b: Func<T, R2>, c: Func<T, R3>, d: Func<T, R4>, e: Func<T, R5>, f: Func<T, R6>, g: Func<T, R7>, h: Func<T, R8>): Func<T, [R1, R2, R3, R4, R5, R6, R7, R8]>
  • read<T, R1, R2, R3, R4, R5, R6, R7, R8, R9>(a: Func<T, R1>, b: Func<T, R2>, c: Func<T, R3>, d: Func<T, R4>, e: Func<T, R5>, f: Func<T, R6>, g: Func<T, R7>, h: Func<T, R8>, i: Func<T, R9>): Func<T, [R1, R2, R3, R4, R5, R6, R7, R8, R9]>
  • read<T, R1, R2, R3, R4, R5, R6, R7, R8, R9, R10>(a: Func<T, R1>, b: Func<T, R2>, c: Func<T, R3>, d: Func<T, R4>, e: Func<T, R5>, f: Func<T, R6>, g: Func<T, R7>, h: Func<T, R8>, i: Func<T, R9>, j: Func<T, R10>): Func<T, [R1, R2, R3, R4, R5, R6, R7, R8, R9, R10]>

required

  • required<T>(name: string): Func<T | null | undefined, NonNullable<T>>

  • Returns a mapper that asserts the input is not null or not undefined.

    Type Parameters

    • T

    Parameters

    • name: string

      A name to report when invalid.

    Returns Func<T | null | undefined, NonNullable<T>>

requiredProp

  • requiredProp<T, P>(prop: P): Func<T, NonNullable<T[P]>>

  • Returns a mapper that asserts a property on the input is not null or not defined.

    Type Parameters

    • T

    • P extends string | number | symbol

    Parameters

    • prop: P

      The prop to assert.

    Returns Func<T, NonNullable<T[P]>>

    A mapper that returns the property's value.