This package has been deprecated

Author message:

deprecated name, run `npm i t-shape` instead

toa-sharp

• Installation
• Usage
  • Define a sharp
    • Primitive
    • Combinators
      • The s.Literal constructor
      • The s.Nullable constructor
      • The s.Optional constructor
      • The s.Struct constructor
      • The s.Partial constructor
      • The s.Map constructor
      • The s.Array constructor
      • The s.Tuple constructor
      • The s.Intersection constructor
      • The s.Union constructor
    • Brand
  • Assertion
• Roadmap

Installation

npm i toa-sharp

Usage

Define a sharp

const sharp = Sharp.make((s) =>
  s.Struct({
    id: s.ObjectID,
    name: s.String,
    age: s.Optional(s.Number)
    address: s.Array(s.String)
  })
)

// stands for type => {
//   id: ObjectID // string with objectId constraint
//   name: string
//   age: number | undefined
//   address: string[]
// }

Primitive

• s.Never
• s.String
• s.Number
• s.Boolean
• s.Unknown

Combinators

The s.Literal constructor

• s.Literal(null) => null
• s.Literal(undefined) => undefined
• s.Literal('ON') => 'ON'
• s.Literal('ON', 'OFF') => 'ON' | 'OFF'

The s.Nullable constructor

s.Nullable(s.String) => string | null

The s.Optional constructor

s.Optional(s.String) => string | undefined

Notice that it DOES NOT mean the key is optional (key?: string)

The s.Struct constructor

s.Struct({ id: s.String, time: s.Number }) => { id: string, time: number }

The s.Partial constructor

s.Partial({ id: s.String, time: s.Number }) => { id?: string, time?: number }

The s.Map constructor

s.Map(s.Boolean) => Record<string, boolean>

The s.Array constructor

s.Array(s.Number) => number[]

The s.Tuple constructor

s.Tuple(s.String, s.Number) => [string, number]

The s.Intersection constructor

s.Intersection(s.Struct({ name: s.String }), s.Partial({ age: s.Number })) => { name: string } & { age?: number }

The s.Union constructor

s.Union(s.String, s.Number) => string | number

The s.Enum constructor

To compatible with Typescript enum when there is no other choice, it's not well supported due to a poor design, highly recommend using s.Literal instead.

// MUST NOT be a `const enum`, otherwise it will be optimized out.
enum Toggle {
  On = "ON",
  Off = "OFF",
}

s.Enum("Toggle", Toggle); // => Toggle

// You have to specify enum type when it's a numeric enum,
// however numeric enums are unsafe in typescript, shouldn't be used anyway.
// @see https://github.com/gcanti/io-ts/issues/216#issuecomment-621615906
enum ToggleNumber {
  On,
  Off,
}

s.Enum<ToggleNumber>("ToggleNumber", ToggleNumber); // => ToggleNumber

Brand

• the s.ObjectID is string with ObjectID constraint, it can pass to string

Assertion

Say we are using koa(with body-parser), to assert body sharp you can

import { Sharp, assert } from "toa-sharp";
import { Errors } from "./errors";

const Body = Sharp.make((s) => S.Struct({ id: s.ObjectID, text: s.String }));

async function handler(ctx: Context) {
  assert(ctx.request.body, Body, new Errors.InvalidParams());
  const { id, text } = ctx.request.body; // with type { id: ObjectID, text: string }
}

The third argument can receive a Error | ErrorContructor, the Error instance will be threw directly while the ErrorContructor will receive error message as first argument. By default it's TypeError constructor.

Roadmap

• Add branded type such as Int(number), Positive(number), Email(string), Url(string), etc.