From 9103e887387559d5d273036fa0788e67e210a322 Mon Sep 17 00:00:00 2001 From: gcanti Date: Sat, 3 Dec 2022 04:03:15 +0100 Subject: [PATCH] add refinement overload to allow custom branding, closes #373 --- CHANGELOG.md | 1 + docs/modules/index.ts.md | 398 +++++++++++++++++++-------------------- dtslint/ts3.5/index.ts | 12 +- src/index.ts | 8 +- 4 files changed, 215 insertions(+), 204 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4a4c19b2..fce0de42 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,6 +20,7 @@ - undeprecate `NeverType`, `NeverC`, `never` - undeprecate `AnyType`, `AnyC`, `any` - undeprecate `RefinementC`, `refinement`, `Integer` +- add refinement overload to allow custom branding, closes #373 # 2.2.19 diff --git a/docs/modules/index.ts.md b/docs/modules/index.ts.md index 33f37940..280da15e 100644 --- a/docs/modules/index.ts.md +++ b/docs/modules/index.ts.md @@ -45,6 +45,7 @@ Added in v1.0.0 - [readonlyArray](#readonlyarray) - [record](#record) - [recursion](#recursion) + - [refinement](#refinement) - [strict](#strict) - [tuple](#tuple) - [type](#type) @@ -53,17 +54,20 @@ Added in v1.0.0 - [~~clean~~](#clean) - [~~dictionary~~](#dictionary) - [~~interface~~](#interface) - - [~~refinement~~](#refinement) - [~~taggedUnion~~](#taggedunion) - [constructors](#constructors) - [keyof](#keyof) - [literal](#literal) - [primitives](#primitives) + - [Function](#function) - [Int](#int) + - [Integer](#integer) - [UnknownArray](#unknownarray) - [UnknownRecord](#unknownrecord) + - [any](#any) - [bigint](#bigint) - [boolean](#boolean) + - [never](#never) - [null](#null) - [nullType](#nulltype) - [number](#number) @@ -74,37 +78,39 @@ Added in v1.0.0 - [voidType](#voidtype) - [~~Array~~](#array) - [~~Dictionary~~](#dictionary) - - [~~Function~~](#function) - - [~~Integer~~](#integer) - - [~~any~~](#any) - - [~~never~~](#never) - [~~object~~](#object) - [utils](#utils) - [Any (interface)](#any-interface) - [AnyArrayType (class)](#anyarraytype-class) - [\_tag (property)](#_tag-property) + - [AnyC (interface)](#anyc-interface) - [AnyDictionaryType (class)](#anydictionarytype-class) - [\_tag (property)](#_tag-property-1) - [AnyProps (interface)](#anyprops-interface) + - [AnyType (class)](#anytype-class) + - [\_tag (property)](#_tag-property-2) - [ArrayC (interface)](#arrayc-interface) - [ArrayType (class)](#arraytype-class) - - [\_tag (property)](#_tag-property-2) + - [\_tag (property)](#_tag-property-3) - [BigIntC (interface)](#bigintc-interface) - [BigIntType (class)](#biginttype-class) - - [\_tag (property)](#_tag-property-3) + - [\_tag (property)](#_tag-property-4) - [BooleanC (interface)](#booleanc-interface) - [BooleanType (class)](#booleantype-class) - - [\_tag (property)](#_tag-property-4) + - [\_tag (property)](#_tag-property-5) - [Brand (interface)](#brand-interface) - [BrandC (interface)](#brandc-interface) - [Branded (type alias)](#branded-type-alias) - [Decode (type alias)](#decode-type-alias) - [DictionaryType (class)](#dictionarytype-class) - - [\_tag (property)](#_tag-property-5) + - [\_tag (property)](#_tag-property-6) - [Encode (type alias)](#encode-type-alias) - [ExactC (interface)](#exactc-interface) - [ExactType (class)](#exacttype-class) - - [\_tag (property)](#_tag-property-6) + - [\_tag (property)](#_tag-property-7) + - [FunctionC (interface)](#functionc-interface) + - [FunctionType (class)](#functiontype-class) + - [\_tag (property)](#_tag-property-8) - [HasProps (type alias)](#hasprops-type-alias) - [HasPropsIntersection (interface)](#haspropsintersection-interface) - [HasPropsReadonly (interface)](#haspropsreadonly-interface) @@ -112,88 +118,82 @@ Added in v1.0.0 - [Int (type alias)](#int-type-alias) - [IntBrand (interface)](#intbrand-interface) - [InterfaceType (class)](#interfacetype-class) - - [\_tag (property)](#_tag-property-7) + - [\_tag (property)](#_tag-property-9) - [IntersectionC (interface)](#intersectionc-interface) - [IntersectionType (class)](#intersectiontype-class) - - [\_tag (property)](#_tag-property-8) + - [\_tag (property)](#_tag-property-10) - [Is (type alias)](#is-type-alias) - [KeyofC (interface)](#keyofc-interface) - [KeyofType (class)](#keyoftype-class) - - [\_tag (property)](#_tag-property-9) + - [\_tag (property)](#_tag-property-11) - [LiteralC (interface)](#literalc-interface) - [LiteralType (class)](#literaltype-class) - - [\_tag (property)](#_tag-property-10) + - [\_tag (property)](#_tag-property-12) - [Mixed (interface)](#mixed-interface) + - [NeverC (interface)](#neverc-interface) + - [NeverType (class)](#nevertype-class) + - [\_tag (property)](#_tag-property-13) - [NullC (interface)](#nullc-interface) - [NullType (class)](#nulltype-class) - - [\_tag (property)](#_tag-property-11) + - [\_tag (property)](#_tag-property-14) - [NumberC (interface)](#numberc-interface) - [NumberType (class)](#numbertype-class) - - [\_tag (property)](#_tag-property-12) + - [\_tag (property)](#_tag-property-15) - [OutputOfDictionary (type alias)](#outputofdictionary-type-alias) - [OutputOfPartialProps (type alias)](#outputofpartialprops-type-alias) - [OutputOfProps (type alias)](#outputofprops-type-alias) - [PartialC (interface)](#partialc-interface) - [PartialType (class)](#partialtype-class) - - [\_tag (property)](#_tag-property-13) + - [\_tag (property)](#_tag-property-16) - [Props (interface)](#props-interface) - [ReadonlyArrayC (interface)](#readonlyarrayc-interface) - [ReadonlyArrayType (class)](#readonlyarraytype-class) - - [\_tag (property)](#_tag-property-14) + - [\_tag (property)](#_tag-property-17) - [ReadonlyC (interface)](#readonlyc-interface) - [ReadonlyType (class)](#readonlytype-class) - - [\_tag (property)](#_tag-property-15) + - [\_tag (property)](#_tag-property-18) - [RecordC (interface)](#recordc-interface) - [RecursiveType (class)](#recursivetype-class) - - [\_tag (property)](#_tag-property-16) + - [\_tag (property)](#_tag-property-19) - [type (property)](#type-property) + - [RefinementC (interface)](#refinementc-interface) - [RefinementType (class)](#refinementtype-class) - - [\_tag (property)](#_tag-property-17) + - [\_tag (property)](#_tag-property-20) - [StringC (interface)](#stringc-interface) - [StringType (class)](#stringtype-class) - - [\_tag (property)](#_tag-property-18) + - [\_tag (property)](#_tag-property-21) - [TupleC (interface)](#tuplec-interface) - [TupleType (class)](#tupletype-class) - - [\_tag (property)](#_tag-property-19) + - [\_tag (property)](#_tag-property-22) - [TypeC (interface)](#typec-interface) - [TypeOfDictionary (type alias)](#typeofdictionary-type-alias) - [TypeOfPartialProps (type alias)](#typeofpartialprops-type-alias) - [TypeOfProps (type alias)](#typeofprops-type-alias) - [UndefinedC (interface)](#undefinedc-interface) - [UndefinedType (class)](#undefinedtype-class) - - [\_tag (property)](#_tag-property-20) + - [\_tag (property)](#_tag-property-23) - [UnionC (interface)](#unionc-interface) - [UnionType (class)](#uniontype-class) - - [\_tag (property)](#_tag-property-21) + - [\_tag (property)](#_tag-property-24) - [UnknownArrayC (interface)](#unknownarrayc-interface) - [UnknownC (interface)](#unknownc-interface) - [UnknownRecordC (interface)](#unknownrecordc-interface) - [UnknownType (class)](#unknowntype-class) - - [\_tag (property)](#_tag-property-22) + - [\_tag (property)](#_tag-property-25) - [Validate (type alias)](#validate-type-alias) - [VoidC (interface)](#voidc-interface) - [VoidType (class)](#voidtype-class) - - [\_tag (property)](#_tag-property-23) + - [\_tag (property)](#_tag-property-26) - [appendContext](#appendcontext) - [getContextEntry](#getcontextentry) - [getFunctionName](#getfunctionname) - [identity](#identity) - - [~~AnyC~~ (interface)](#anyc-interface) - - [~~AnyType~~ (class)](#anytype-class) - - [\_tag (property)](#_tag-property-24) - [~~Compact~~ (type alias)](#compact-type-alias) - [~~Exact~~ (type alias)](#exact-type-alias) - - [~~FunctionC~~ (interface)](#functionc-interface) - - [~~FunctionType~~ (class)](#functiontype-class) - - [\_tag (property)](#_tag-property-25) - - [~~NeverC~~ (interface)](#neverc-interface) - - [~~NeverType~~ (class)](#nevertype-class) - - [\_tag (property)](#_tag-property-26) - [~~ObjectC~~ (interface)](#objectc-interface) - [~~ObjectType~~ (class)](#objecttype-class) - [\_tag (property)](#_tag-property-27) - [~~PropsOf~~ (type alias)](#propsof-type-alias) - - [~~RefinementC~~ (interface)](#refinementc-interface) - [~~StrictC~~ (interface)](#strictc-interface) - [~~StrictType~~ (class)](#stricttype-class) - [\_tag (property)](#_tag-property-28) @@ -583,6 +583,25 @@ export declare function recursion Added in v1.0.0 +## refinement + +**Signature** + +```ts +export declare function refinement>( + codec: C, + refinement: Refinement, B>, + name?: string +): RefinementC +export declare function refinement( + codec: C, + predicate: Predicate>, + name?: string +): RefinementC +``` + +Added in v1.0.0 + ## strict Strips additional properties, equivalent to `exact(type(props))`. @@ -699,23 +718,6 @@ export declare const interface: typeof type Added in v1.0.0 -## ~~refinement~~ - -Use `brand` instead. - -**Signature** - -```ts -export declare function refinement( - codec: C, - predicate: Predicate>, - name = `(${codec.name} | ${getFunctionName(predicate)})` -): // tslint:disable-next-line: deprecation -RefinementC -``` - -Added in v1.0.0 - ## ~~taggedUnion~~ Use `union` instead. @@ -761,6 +763,16 @@ Added in v1.0.0 # primitives +## Function + +**Signature** + +```ts +export declare const Function: FunctionC +``` + +Added in v1.0.0 + ## Int A branded codec representing an integer @@ -773,6 +785,16 @@ export declare const Int: BrandC Added in v1.8.1 +## Integer + +**Signature** + +```ts +export declare const Integer: RefinementC +``` + +Added in v1.0.0 + ## UnknownArray **Signature** @@ -793,6 +815,16 @@ export declare const UnknownRecord: UnknownRecordC Added in v1.7.1 +## any + +**Signature** + +```ts +export declare const any: AnyC +``` + +Added in v1.0.0 + ## bigint **Signature** @@ -813,6 +845,16 @@ export declare const boolean: BooleanC Added in v1.0.0 +## never + +**Signature** + +```ts +export declare const never: NeverC +``` + +Added in v1.0.0 + ## null **Signature** @@ -917,80 +959,68 @@ export declare const Dictionary: UnknownRecordC Added in v1.0.0 -## ~~Function~~ - -**Signature** - -```ts -export declare const Function: FunctionC -``` - -Added in v1.0.0 - -## ~~Integer~~ +## ~~object~~ -Use `Int` instead. +Use `UnknownRecord` instead. **Signature** ```ts -export declare const Integer: RefinementC +export declare const object: ObjectC ``` Added in v1.0.0 -## ~~any~~ +# utils -Use `unknown` instead. +## Any (interface) **Signature** ```ts -export declare const any: AnyC +export interface Any extends Type {} ``` Added in v1.0.0 -## ~~never~~ +## AnyArrayType (class) **Signature** ```ts -export declare const never: NeverC +export declare class AnyArrayType { + constructor() +} ``` Added in v1.0.0 -## ~~object~~ - -Use `UnknownRecord` instead. +### \_tag (property) **Signature** ```ts -export declare const object: ObjectC +readonly _tag: "AnyArrayType" ``` Added in v1.0.0 -# utils - -## Any (interface) +## AnyC (interface) **Signature** ```ts -export interface Any extends Type {} +export interface AnyC extends AnyType {} ``` -Added in v1.0.0 +Added in v1.5.3 -## AnyArrayType (class) +## AnyDictionaryType (class) **Signature** ```ts -export declare class AnyArrayType { +export declare class AnyDictionaryType { constructor() } ``` @@ -1002,41 +1032,41 @@ Added in v1.0.0 **Signature** ```ts -readonly _tag: "AnyArrayType" +readonly _tag: "AnyDictionaryType" ``` Added in v1.0.0 -## AnyDictionaryType (class) +## AnyProps (interface) **Signature** ```ts -export declare class AnyDictionaryType { - constructor() +export interface AnyProps { + [key: string]: Any } ``` Added in v1.0.0 -### \_tag (property) +## AnyType (class) **Signature** ```ts -readonly _tag: "AnyDictionaryType" +export declare class AnyType { + constructor() +} ``` Added in v1.0.0 -## AnyProps (interface) +### \_tag (property) **Signature** ```ts -export interface AnyProps { - [key: string]: Any -} +readonly _tag: "AnyType" ``` Added in v1.0.0 @@ -1262,6 +1292,38 @@ readonly _tag: "ExactType" Added in v1.0.0 +## FunctionC (interface) + +**Signature** + +```ts +export interface FunctionC extends FunctionType {} +``` + +Added in v1.5.3 + +## FunctionType (class) + +**Signature** + +```ts +export declare class FunctionType { + constructor() +} +``` + +Added in v1.0.0 + +### \_tag (property) + +**Signature** + +```ts +readonly _tag: "FunctionType" +``` + +Added in v1.0.0 + ## HasProps (type alias) **Signature** @@ -1515,6 +1577,38 @@ export interface Mixed extends Type {} Added in v1.0.0 +## NeverC (interface) + +**Signature** + +```ts +export interface NeverC extends NeverType {} +``` + +Added in v1.5.3 + +## NeverType (class) + +**Signature** + +```ts +export declare class NeverType { + constructor() +} +``` + +Added in v1.0.0 + +### \_tag (property) + +**Signature** + +```ts +readonly _tag: "NeverType" +``` + +Added in v1.0.0 + ## NullC (interface) **Signature** @@ -1787,6 +1881,16 @@ readonly type: C Added in v1.0.0 +## RefinementC (interface) + +**Signature** + +```ts +export interface RefinementC> extends RefinementType, InputOf> {} +``` + +Added in v1.5.3 + ## RefinementType (class) **Signature** @@ -2158,38 +2262,6 @@ export declare const identity: (a: A) => A Added in v1.0.0 -## ~~AnyC~~ (interface) - -**Signature** - -```ts -export interface AnyC extends AnyType {} -``` - -Added in v1.5.3 - -## ~~AnyType~~ (class) - -**Signature** - -```ts -export declare class AnyType { - constructor() -} -``` - -Added in v1.0.0 - -### \_tag (property) - -**Signature** - -```ts -readonly _tag: "AnyType" -``` - -Added in v1.0.0 - ## ~~Compact~~ (type alias) **Signature** @@ -2211,70 +2283,6 @@ export type Exact = T & Added in v1.1.0 -## ~~FunctionC~~ (interface) - -**Signature** - -```ts -export interface FunctionC extends FunctionType {} -``` - -Added in v1.5.3 - -## ~~FunctionType~~ (class) - -**Signature** - -```ts -export declare class FunctionType { - constructor() -} -``` - -Added in v1.0.0 - -### \_tag (property) - -**Signature** - -```ts -readonly _tag: "FunctionType" -``` - -Added in v1.0.0 - -## ~~NeverC~~ (interface) - -**Signature** - -```ts -export interface NeverC extends NeverType {} -``` - -Added in v1.5.3 - -## ~~NeverType~~ (class) - -**Signature** - -```ts -export declare class NeverType { - constructor() -} -``` - -Added in v1.0.0 - -### \_tag (property) - -**Signature** - -```ts -readonly _tag: "NeverType" -``` - -Added in v1.0.0 - ## ~~ObjectC~~ (interface) **Signature** @@ -2317,18 +2325,6 @@ export type PropsOf = T['props'] Added in v1.0.0 -## ~~RefinementC~~ (interface) - -Use `BrandC` instead. - -**Signature** - -```ts -export interface RefinementC extends RefinementType, OutputOf, InputOf> {} -``` - -Added in v1.5.3 - ## ~~StrictC~~ (interface) **Signature** diff --git a/dtslint/ts3.5/index.ts b/dtslint/ts3.5/index.ts index 97f7ff97..bdb9953c 100644 --- a/dtslint/ts3.5/index.ts +++ b/dtslint/ts3.5/index.ts @@ -63,14 +63,22 @@ type Keyof1OutputTest = t.OutputOf // $ExpectType "a" | "b" // refinement // -const Refinement1 = t.refinement(t.number, (n) => n % 2 === 0) // $ExpectType RefinementC +const Refinement1 = t.refinement(t.number, (n) => n % 2 === 0) // $ExpectType RefinementC type Refinement1TypeTest = t.TypeOf // $ExpectType number type Refinement1OutputTest = t.OutputOf // $ExpectType number -const Refinement2 = t.refinement(NumberFromString, (n) => n % 2 === 0) // $ExpectType RefinementC> +const Refinement2 = t.refinement(NumberFromString, (n) => n % 2 === 0) // $ExpectType RefinementC, number> type Refinement2TypeTest = t.TypeOf // $ExpectType number type Refinement2OutputTest = t.OutputOf // $ExpectType string +type Int = number & { __brand__: 'Int' } + +// $ExpectType RefinementC +t.refinement(t.number, (n): n is Int => Number.isInteger(n), 'Int') + +// $ExpectType RefinementC +t.refinement(t.number, Number.isInteger, 'Integer') + // // array // diff --git a/src/index.ts b/src/index.ts index 364b7724..951f8e52 100644 --- a/src/index.ts +++ b/src/index.ts @@ -2064,12 +2064,18 @@ export const any: AnyC = new AnyType() /** * @since 1.5.3 */ -export interface RefinementC extends RefinementType, OutputOf, InputOf> {} +export interface RefinementC> extends RefinementType, InputOf> {} /** * @category combinators * @since 1.0.0 */ +export function refinement>( + codec: C, + refinement: Refinement, B>, + name?: string +): RefinementC +export function refinement(codec: C, predicate: Predicate>, name?: string): RefinementC export function refinement( codec: C, predicate: Predicate>,