@tinyfox/shapecheck

Functional runtime validation DSL for TypeScript with branded types, bigint, and composable rule constructors.

// Install with `npm i @tinyfox/shapecheck`
import * as shapecheck from '@tinyfox/shapecheck'

// Compile-time error.
const positiveNumber1: shapecheck.PositiveNumber = -1

// Runtime error.
const positiveNumber2 = shapecheck.positiveNumber(-1)

// Composable rules and guards like `object`.
const example = shapecheck.object({
  required: {
    price: shapecheck.positiveNumber,
  },
})

// Turn rules into types so you don't have to duplicate information.
type Example = shapecheck.Static<typeof example>

// Turn rules into guards so you don't have to duplicate code.
const isExample = shapecheck.guard(example)

// Use rules and/or guards to guarantee data validity.
const myExample: Example = example({ price: 12.34 })
if (isExample(myExample)) {
  // myExample.price is typed as a PositiveNumber here
}

Why shapecheck

• Functional API — every rule is just (input: unknown) => Output.
• Branded types via Static<typeof rule> — no nominal-typing tricks needed at call sites.
• Aggregated errors — object/array/tuple collect every failure in one pass instead of throwing on the first.
• First-class bigint, symbol, and constant rules.
• Plays well with NestJS pipes, Express handlers, Cloudflare Workers, and Fastify.

Built-in rules

• allowNull
• allowUndefined
• any
• array
• bigint
• boolean
  • trueRule
  • falseRule
• constant
• date
• dictionary
• enum
• literal
• number
• object
• string
• symbol
• tuple
• union
• unknown

Sized strings

Restricts string size to avoid UI overflow and database storage issues.

• nonEmptyString
• tinyText (0–255 characters)
• text (0–65,535 characters)
• mediumText (0–16,777,215 characters)

Constrained strings

Built on top of validator for well-known string formats.

• email
• iri
• iso8601Duration
• iso8601FullDate
• iso8601Timestamp
• locale
• mailto
• mimeType
• mongoId
• scormInteractionType
• semanticVersion
• sha1
• url
• uuidv4

Constrained non-strings

• integer
• negativeInteger
• negativeNumber
• positiveInteger
• positiveNumber

Sanitization

Coerces values from HTTP headers, URL params, and form bodies.

• sanitizeBooleanFromString
• sanitizeJsonFromString
• sanitizeNumberFromString
• sanitizeBasicAuthFromString
• sanitizeJWTBearerAuthFromString

Rule constructors

Build your own rules from a regex or a length window.

• regexRuleConstructor
• sizedArrayRuleConstructor

License

MIT