+TITLE: @apparts/types

+DATE: [2019-08-26 Mon]

+AUTHOR: Philipp Uhl

This package provides functions for checking correctness of values against certain types. It also provides a set of functions for helping to build type-correct REST-APIs, to be used with [[https://www.npmjs.com/package/express][express]].

• Configuration

Under the configuration name =types-config= the following options exist:

• bugreportEmail {string} :: An email address that will be shown in case of a bug.
• idType {string} :: Can be one of
  • string
  • UUIDv4
  • int
  • A regular expression

More information on how to set this: [[https://github.com/phuhl/apparts-config][@apparts/config]].

• Types

A type is defined by an object. The object must either contain a key =type= that is an atomic type or be of the form of =object=, =array=, =oneOf=, =value= as described under "Compound types".

All types definitions can be produced by the use of functions from =schema=:

+BEGIN_SRC js

import { schema } from "@apparts/types";

+END_SRC

It is recommended, to use these functions to build type definitions, as they can also be used to infer TypeScript types.

** Atomic types:

• id (as configured)
• uuidv4
• / (catch all)
• =int=
• float
• hex
• base64
• bool
• string
• email
• array_int
• array_id
• password (alias for string)
• time
• array_time (alias for array_id)
• null

The type definition for each of the atomic types looks like: ={ type: }=.

Build a type definition for an atomic type with these functions:

+BEGIN_SRC js

import { schema } from "@apparts/types"; const intSchema = schema.int(); const floatSchema = schema.float(); const booleanSchema = schema.boolean(); const stringSchema = schema.string(); const hexSchema = schema.hex(); const uuidv4Schema = schema.uuidv4(); const base64Schema = schema.base64(); const emailSchema = schema.email(); const nillSchema = schema.nill(); // { type: "null" } const anySchema = schema.any(); // { type: "/" }

+END_SRC

Certain types only differ in semantics from other more basic types. They are created like this:

+BEGIN_SRC js

// Creating ids depends on how your Ids look like, either a string or an int const idIntSchema = schema.int().semantic("id"); // { type: "id" } const idStrSchema = schema.string().semantic("id"); // { type: "id" }

const passwordSchema = schema.string().semantic("password"); // { type: "password" } const timeSchema = schema.int().semantic("time"); // { type: "time" }

+END_SRC

** Compound types

Compound objects make it possible to check complex JSON values for validity. Any sub-type can be either an atomic type or a compound type.

• =object= :: Matches if the value is an object and all the values of the object have the types as specified by =values=, or if the specific keys of the object are known, as specified by the key in =keys=.

  • With known keys:

    +BEGIN_SRC js

    // build type schema import { schema } from "@apparts/types"; const objSchema = schema.obj({ : , : , // ... });

    const typeDefinition = { type: "object", keys: { : { type: [, optional: true]}, ... } } // = objSchema.getType();

    +END_SRC

  • With unknown keys:

    +BEGIN_SRC js

    // build type schema import { schema } from "@apparts/types"; const objSchema = schema.objValues(); const typeDefinition = { type: "object", values: } // = objSchema.getType();

    +END_SRC

• =array= :: Matches if the value is an array and all items of the array match the type, as specified by =items=.

  +BEGIN_SRC js

  // build type schema import { schema } from "@apparts/types"; const arraySchema = schema.array(); const typeDefinition = { type: "array", items: } // = arraySchema.getType();

  +END_SRC

• =oneOf= :: Matches if at least one of the alternatives matches

  +BEGIN_SRC js

  // build type schema import { schema } from "@apparts/types"; const oneOfSchema = schema.oneOf([ , , // ... ]);

  const typeDefinition = { type: "oneOf", alternatives: [ , ... ] } // = oneOfSchema.getType();

  +END_SRC

• =value= :: Matches the exact content

  +BEGIN_SRC js

  // build type schema import { schema } from "@apparts/types"; const valueSchema = schema.value();

  const typeDefinition = { value: } // = valueSchema.getType();

  +END_SRC

** Using Schemas

One can build types by hand by constructing the type definition object. This is not recommended though, as it is easy to mess up and no TypeScript types can be inferred. Instead, @apparts/types provides functions to build a type definition:

+BEGIN_SRC js

// the functions then are available through schema. import { schema } from "@apparts/types"; // or directly from the package import { int, float, boolean, string, hex, uuidv4, base64, email, nill, any, array, obj, oneOf, value, InferType } from "@apparts/types";

+END_SRC

Using a schema, one can get the type definition with the =getType= function:

+BEGIN_SRC js

const userSchema = schema.obj({ firstName: string(), lastName: string(), gender: string().optional(), }); userSchema.getType(); // returns the type definition

+END_SRC

Also, one can get a TypeScript type:

+BEGIN_SRC ts

type User = InferType;

// The resulting type looks like this: type User = { firstName: string; lastName: string; gender?: string; };

+END_SRC

** Encoding for the preparator

When requesting an API checked by @apparts/types, make sure, the following holds:

• The body is always expected to be in JSON format.
• The path parameters must never be empty (otherwise express can't route you correctly) and if the type used is an array, it must be JSON encoded.
• The param and query parameters must be URI encoded. If the =typeof= gives ="object"= on the value, the value must be JSON encoded.

• Usage

The =preparator= function provides a wrapper around express routes. It checks the types of the requests and handles errors.

The =preparator= function takes these arguments:

• =assertions