npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

ts-xor

v1.3.0

Published

Compose custom types containing mutually exclusive keys, using this generic Typescript helper type.

Downloads

488,499

Readme

npm version Licence

Downloads per week Downloads per week Repos depending on ts-xor Github stars

Minified and gzipped size 0 Dependencies

ts-xor

The tiny npm package ts-xor introduces the new mapped type XOR that helps you compose your own custom TypeScript types containing mutually exclusive keys for zero runtime overhead.

Description

TL;DR

ts-xor implements the well-known exclusive or (a.k.a. XOR) logical operator from boolean algebra:

| A | B | XOR | union operator (\|) | ts-xor | | :-: | :-: | :-: | :-: | :-: | | 0 | 0 | 0 | 0 ✅ | 0 ✅ | | 0 | 1 | 1 | 1 ✅ | 1 ✅ | | 1 | 0 | 1 | 1 ✅ | 1 ✅ | | 1 | 1 | 0 | 1 ❌ | 0 ✅ |

Why isn't TypeScript's built-in union operator (|) enough?

Typescript's union operator allows combining two object types A and B, into a superset type C which can contain all the keys of both A and B.

But sometimes the requirements dictate that we combine two types with mutually exclusive keys.

For example: assume two objects with with keys A.a and B.b. Given type C = A | B then we want to impose the restriction that we can set either C.a or C.b but never both AND always at least one of the two!

Typescript does not have this feature built-in.

Explained by example

If we use the union operator

type A_OR_B = A | B

then the derived type is shown in VS Code like so:

Resulting type when using the union operator

Whereas if we use XOR:

type A_XOR_B = XOR<A, B>

then the derived type is shown quite differently in VS Code:

Resulting type when using the XOR mapped type

How it works

Notice in the example above, that when using XOR, each union branch of the resulting type contains all keys of one source type plus all keys of the other. At the same time, in each variant, those keys of the other type are defined as optional while additionally they are also typed as undefined.

This trick will not only forbid having keys of both source types defined at the same time (since the type of each key is explicitly undefined), but also allow us to not need to define all keys all of the time since each set of keys is optional on each variant.

Fun fact: The actual TypeScript code for XOR is generated programmatically using the TypeScript Compiler API. 🦾

Installation

In your typescript powered, npm project, run:

npm install -D ts-xor

Usage

import type { XOR } from 'ts-xor'

interface A { a: string }
interface B { b: string }

let test: XOR<A, B>

test = { a: '' }         // OK
test = { b: '' }         // OK
test = { a: '', b: '' }  // error
test = {}                // error

XORing more than two types

If you want to create a type as the product of the logical XOR operation between multiple types (more than two and even up to 200), then just pass them as additional comma-separated generic params.

let test: XOR<A, B, C, D, E, F>

ts-xor can easily handle up to 200 generic params. 💯

Pattern 1: Typing a fetcher returning data XOR error

Using XOR we can type a function that returns either the data requested from an API or a response object like so:

type FetchResult<P extends object> = XOR<
  { data: P },
  { error: FetchError<P> },
>

Now TypeScript has all the necessary information to infer if the FetchResult contains a data or error key at compile time which results in very clean, yet strictly typed, handling code.

data or error intellisense demo

Pattern 2: Typing an API's response shape

Let's assume that we have the following spec for a weather forecast API's response:

  1. A weather forecast object always contains the id and station members
  2. A weather forecast object always contains either a member rain or a member snow, but never both at the same time.
  3. The rain, snow members are objects containing additional forecast accuracy data
  4. The rain, snow members always contain either a member 1h or a member 3h with a number value, but never both keys at the same time.
type ForecastAccuracy = XOR<{ '1h': number }, { '3h': number }>

interface WeatherForecastBase {
  id: number
  station: string
}

interface WeatherForecastWithRain extends WeatherForecastBase {
  rain: ForecastAccuracy
}

interface WeatherForecastWithSnow extends WeatherForecastBase {
  snow: ForecastAccuracy
}

type WeatherForecast = XOR<WeatherForecastWithRain, WeatherForecastWithSnow>

const test: WeatherForecast = {
  id: 1,
  station: 'Acropolis',
  // rain: { '1h': 1 },           // OK
  // rain: { '2h': 1 },           // error
  // rain: { '3h': 1 },           // OK
  // rain: {},                    // error
  // rain: { '1h': 1 , '3h': 3 }, // error
  // lel: { '3h': 1 },            // error
  // rain: { '3h': 1, lel: 1 },   // error
  // snow: { '3h': 1 },           // OK
                                  // error when BOTH `rain` AND `snow` keys are defined at the same time
}

Tests and coverage

The library ts-xor is fully covered with smoke, acceptance and mutation tests against the typescript compiler itself. The tests can be found inside the test folder.

To run all tests locally, execute the following command inside your git-cloned ts-xor folder:

npm run test

NPM

This library is published on NPM.

Licence

Distributed under the MIT license. See LICENSE.md for more information.

Contributing

This project's commits comply with the Conventional Commits guidelines.

  1. Fork it (https://github.com/maninak/ts-xor/fork)
  2. Create your feature/fix branch (git checkout -b feat/foobar)
  3. Commit your changes (git commit -am 'feat(foobar): add support for foobar tricks')
  4. Push to the branch (git push origin feat/fooBar)
  5. Create a new Pull Request