@prelude/refute · v2.0.1

SourceAPI referenceChangelognpm

Refute module

• and: <Ts extends (Primitive | Refute<unknown>)[]>(...as: Ts) => Refute<IntersectionOfUnion<Lifted<Ts[number]>>>

• array: <T>(a: Refute<T>) => (values: unknown) => Result<T[]>

  Combinator over an array.

• assert: <T>(a: Refute<T>) => (value: unknown) => T

  Combinator returning refute as assertion.

• bigint: Refute<bigint>

  Returns refute for bigint type.

• boolean: Refute<boolean>

  Returns refute for boolean type.

• defined: <T>(value: T) => Result<Exclude<T, undefined>>

  Returns refute for defined value type.

• exact: <T extends Record<string, Primitive | Refute<unknown>>>(kvs: T) => (value: unknown) => Result<{ [k in keyof T]: Lifted<T[k]>; }>

  Refute combinator over an exact object.

  See object

  See partial

  See exactPartial

• exactPartial: <T extends Record<string, Primitive | Refute<unknown>>>(kvs: T) => (value: unknown) => Result<{ [k in keyof T]?: Lifted<T[k]>; }>

  Refute combinator over an exact, partial object.

  See object

  See partial

  See exact

• finite: (value: unknown) => Result<number>

  Returns failure if value is not a finite number.

• lift: <T extends Primitive | Refute<unknown>>(a: T) => Refute<Lifted<T>>

• null: Refute<null>

  Returns refute for null type.

• nullishOr: <T>(a: Refute<T>) => Refute<T>

• nullOr: <T>(a: Refute<T>) => Refute<T>

• number: Refute<number>

  Returns refute for number type.

• object: <T extends Record<string, Primitive | Refute<unknown>>>(kvs: T) => (value: unknown) => Result<{ [k in keyof T]: Lifted<T[k]>; }>

  Refute combinator over an inexact object.

  See partial

  See `exact

  See exactPartial

• oneOf: <T extends Primitive>(...values: readonly T[]) => Refute<T>

  Returns failure if value doesn't strictly equal any of provided values.

• or: <Ts extends (Primitive | Refute<unknown>)[]>(...as: Ts) => Refute<Lifted<Ts[number]>>

• partial: <T extends Record<string, Primitive | Refute<unknown>>>(kvs: T) => (value: unknown) => Result<{ [k in keyof T]?: Lifted<T[k]>; }>

• positive: Refute<number>

  Returns confirms positive number.

• predicate: <T>(a: Refute<T>) => (value: unknown) => value is T

  Combinator returning refute result as predicate.

• reason: <T>(a: Refute<T>) => (value: unknown) => string

  Combinator returning refute reason or undefined.

• record: <K extends string | number | symbol, V>(k: Refute<K>, v: Refute<V>) => Refute<Record<K, V>>

• regexp: (re: RegExp) => Refute<string>

• safeInteger: Refute<number>

  Returns confirms safe integer.

• safeReason: <T>(a: Refute<T>) => (value: unknown) => string

  Combinator returning refute reason without interpolating value or undefined.

• strftime: (f: string) => Refute<string>

• string: Refute<string>

  Returns refute for string type.

• symbol: Refute<symbol>

  Returns refute for symbol type.

• tuple: <T extends Refute<unknown>[]>(...as: T) => Refute<{ [I in keyof T]: Refuted<T[I]>; }>

• undefined: Refute<undefined>

  Returns refute for undefined type.

• undefinedOr: <T>(a: Refute<T>) => Refute<T>

• unique: <T>(a: Refute<T>, f?: (value: T) => Primitive) => (values: unknown) => Result<T[]>

  Returns confirmation of an unique array.

Usage

npm i -E @prelude/refute

import * as $ from '@prelude/refute'

const refute = $.object({
  foo: $.string,
  bar: $.number
})

const predicate = $.predicate(refute)

const assert = $.assert(refute)

const value = JSON.parse('...')
if (predicate(value)) {
  // value is { foo: string, bar: number }
}

const value_ = assert(value)
// value_ is { foo: string, bar: number }
// throws if not.

console.log($.reason(refute)({ bar: 'a' }))
// Invalid value at key bar, expected number, got a.

Shared core and deliberate differences

Every check is implemented once in @prelude/validation and shared with @prelude/assert and @prelude/predicate; this package renders the structured failure into Fail { status: 'refuted', reason, received }, where reason spells the path (at key a, at index 1, expected number) and received is the innermost failing value. predicate, assert, reason and safeReason interpret a refute in the other modes. Built-in refutes carry their core validator, so containers compose structurally; a hand-written Refute is adapted from its Fail.

The three packages accept exactly the same values (packages/refute/src/matrix.test.ts checks that). Where they describe a failure differently, it is deliberate and kept for compatibility:

• a duplicate in unique is duplicate value at index 1 here, .1 ... a unique value in assert;
• extra keys are named in words (has unexpected extra key b, unexpected key b for exactPartial), assert puts the first one in the path (.b ... no extra keys);
• a failing record key is key, expected ..., assert names it (.a1 ...);
• nullOr/undefinedOr/nullishOr prefix was not null, here and suffix or null in assert (only for a top-level failure there);
• strftime reports received: { value, index };
• predicate takes the value first in record.

License

This package is dedicated to the public domain under CC0 1.0.