Tag types for Typescript
taghiro is a library for tag types in Typescript. Our mission is to prevent bugs and make code more readable to developers. Tag types are types with which you can tag other types.
taghiro implements them as intersection types in Typescript. For example NotZero
is a tag type preventing b
to be 0
.
function divide(a:number, b:number & NotZero) {
....
}
For an introduction on tag types see here.
npm install taghiro
npm test
Lets look at an example where we send emails
function sendEmails(to:Array<string>, html:string) {
....
}
Here several things could go wrong. First the to
array could be empty. Second the html
could be empty, not contain any HTML or contain unsafe HTML. With tag types we can make sure the paramaters are save.
import { NonEmpty, isNotEmpty } from 'taghiro';
function sendEmails(to:Array<string> & NonEmpty, html:string & NonEmpty) {
....
}
Now the caller needs to ensure that the paramater satisfy the tag types. taghiro implements this with Typescript type guards.
import { NonEmpty, isNotEmpty } from 'taghiro';
if (isNotEmpty(emails) && isNotEmpty(html)) {
sendEmails(emails, html);
}
You can write your own Tags. With leveraging libraries to checking emails and HTML we can easily implement Email
and SafeHtml
. With those we can make our method even safer.
function sendEmails(
to:Array<string @ Email> & NonEmpty,
html:string & SafeHtml
) {
....
}
For an extension with an Email
tag see taghiro-validator. For implementing SafeHtml
we could use sanitize-html.
There are many different use cases for tag types. At least three use case groups for tag types are
- Constraint (like MinSize, Positive)
- State (like Empty, LoggedIn)
- Semantic (like Netto, CustomerID)
taghiro brings ready to use tag types. The supplied tag types are inspired by the excellent refined library.
- Size
- MinSize
- MaxSize
- Empty
- NonEmpty
- Sorted
- Unsorted
- IntervalOpen
- IntervalOpenClosed
- IntervalClosedOpen
- IntervalClosed
- Less
- LessEqual
- Greater
- GreaterEqual
- Positive
- NonPositive
- Negative
- NonNegative
- Modulo
- Divisable
- NonDivisable
- Even
- Odd
- NotZero
- Ascii
- Regex
- Digits
- Letters
- LettersOrDigits
- LowerCase
- UpperCase
- Trimmed
- EndsWith
- StartsWith
- Url
- Uuid
- Json
- Base64
Tag types can be used to define custom domain concepts. One example is id. Here is an example based on string Uuid ids.
import { Tag, isUuid } from 'taghiro';
export type CustomerId = Tag<'customer-id'>;
export function isCustomerId(value: string): value is string & CustomerId {
return isUuid(value);
}
One can define a custom Tag type to define more than one id tag.
import { isUuid } from 'taghiro';
export interface Id<T extends string> {
readonly __id: T;
}
export type CustomerId = Id<'customer'>;
export function isCustomerId(value: string): value is string & CustomerId {
return isUuid(value);
}
export type AccountId = Id<'account'>;
export function isAccountId(value: string): value is string & AccountId {
return isUuid(value);
}
taghiro is easy to integrate with more validation libraries for example Validator.
import { isEmail } from 'validator';
import { Tag } from 'taghiro';
export type Email = Tag<'email'>;
export function isEmail(value: string): value is string & Email {
return isEmail(value);
}
For a library that implements taghiro tag types with Validator see taghiro-validator.
The introduction of generics prevented ClassCastException, replacing null with Option types prevents NullPointerexceptions and the introduction of tag types prevent IllegalArgumentExceptions.
Method validation | Tag types | |
Call site |
sendEmail(
'[email protected]',
'Important'
)
// 1. user/validation error handling
// 2. IO mail error handling |
const email = '[email protected]';
const body = 'Important';
if (isEmail(email) && isSafeHtml(body)) {
sendEmail(email, body);
// IO mail error handling
} else {
// show user error
} |
Method site |
function sendEmail(to: string, body: string) {
if (isEmail(to), isHtml(body)) {
// send email
} else {
// what to do here?
// throw Exception?
// return error code?
}
} |
function sendEmail(
to: string & Email,
body: string & SafeHtml
) {
// send email
} |
Copyright (c) 2019 Stephan Schmidt
Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:
The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.