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

any-ts

v0.48.1

Published

a small set of TypeScript namespaces that overload built-in names (like any) to make them extensible

Downloads

172

Readme

NPM Package

any-ts is a small set of TypeScript namespaces that overload built-in names (like any) to make them extensible.

[!NOTE] Currently, any-ts is BYOI: "bring your own implementation". With the exception of the ANY_TS_VERSION constant, any-ts only ships type declarations.

Requirements

What problem does any-ts solve?

The reason any-ts exists is because TypeScript types are hard to get right.

The TypeScript team has invested a lot of time into making their syntax beginner friendly, and easy to use.

The problem, as anyone who's used TypeScript for some time knows, is that while the type system is incredibly powerful, it's also incredibly 🦄 magical 🌈.

I think most TS users would agree:

While TypeScript is, in some ways, "easy" to use, it's not simple.

Some of this complexity, we feel, is avoidable. Let's look at an example.

Let's say you're writing a small library of helper functions:

/**
 * `identity` is a function that takes any arbitrary input, captures as much type
 * information as possible, and returns it to you:
 */
const identity = <const type>(term: type): type => term

/** `flatten` is a variadic function that takes a list of arrays and... well, flattens them. */
const flatten = <const T extends Array<Array<any>>>(...arrays: T) => arrays.flat()

You write some tests, everything works as expected, so you ship it. Nice work!

But before long, someone creates an issue. Here's what they tried to do:

import { identity, flatten } from "helpful-helpers"

const arr1 = identity([0, 1, 2, 3])
const arr2 = identity([4, 5, 6, 7])

const arr3 = flatten(arr1, arr2)
//                   ^^^^ 🚫 TypeError

Can you spot the problem?

The problem here is that arr1 has the type readonly [1, 2, 3], and flatten only accepts mutable arrays.

You do some research and find it that every ReadonlyArray, despite having the longer, more "qualified" name, does not extend Array.

In fact, it's actually the other way around: every Array is a structural subtype of ReadonlyArray.

Here's how any-ts solves this problem:

import type { any } from "any-ts"

const identity = <const type>(term: type): type => term

const flatten = <const T extends any.array<any.array>>(...arrays: T) => arrays.flat()

const arr1 = identity([0, 1, 2, 3])
const arr2 = identity([4, 5, 6, 7])

flatten(arr1, arr2)
// no type error

What's happening?

If you're troubled by the any.array<any.array> syntax, don't worry: it's not as cursed as it might sound.

But how are you adding properties to any, as if it were an object?

The short answer is that types and namespaces can share identifiers. This has been the case for years. And unlike objects, namespace can export types.

All we've done is overload any, which allows us to piggyback on its semantics. any is still any, and any.array is a type that absorbs the complexity (and verbosity) of readonly unknown[].

But what if I want an array of strings?

import type { any } from "any-ts"

type myStringArray = any.array<string>
//   readonly string[]

But what if I want a mutable array?

With any-ts, your intent is explicit:

import type { any, mut } from "any-ts"

type myMutableArray = mut.array
//   ^? type myMutableArray = unknown[]
type myMutableStringArray = mut.array<string>
//   ^? type myMutableStringArray = string[]

// or, if you prefer not importing both:
type myOtherArray = any.mut.array
//   ^? type myOtherArray = unknown[]

type myOtherStringArray = any.mut.array<string>
//   ^? type myOtherStringArray = string[]

But what if I want to express more advanced types?

In our opinion, this is where any-ts really shines.

If you're a power user, you can do some pretty cool things with any-ts. Let's continue using any.array, even though it's one of the simplest types the library implements.

What if you wanted to extract (or pattern-match) the type that an array holds?

declare namespace Dictionary {
  type fromArray<xs extends any.array> 
    = xs extends any.array<infer x> ? Record<string, x> : never;
}

type featureFlags = Dictionary.fromArray<boolean[]>
//   ^? type featureFlags = Record<string, boolean>

Of the hundreds of types that any-ts ships, almost all of them can be used in matching position, like above.

If you're looking for more examples, you can find more in the examples directory (WIP).

Looking for something that we don't ship yet? Raise an issue -- we'd love to try to help!

Namespaces