Add `NonEmptyArray` to `lib` (but **not** `length > 0` narrowing)

[Rudxain]

⚙ Compilation target

ES2023

⚙ Library

ES2023

Missing / Incorrect Definition

type NonEmptyArray<T> = [T, ...T[]]
type ReadonlyNonEmptyArray<T> = readonly [T, ...readonly T[]]

Sample Code

const is_non_empty = <T>(a: ReadonlyArray<T>): a is ReadonlyNonEmptyArray<T> =>
    a.length > 0

function sum(a: ReadonlyNonEmptyArray<number>): number
function sum(a: ReadonlyNonEmptyArray<bigint>): bigint
function sum(a:
    ReadonlyNonEmptyArray<number> |
    ReadonlyNonEmptyArray<bigint>
) {
    //@ts-expect-error
    return a.reduce((acc, x) => acc + x)
}

Documentation Link

There's no docs that I'm aware of. However, there are multiple issues using this boilerplate.

Here's a WIP example implementations of sum. The sample code is a simplified version of that. More info here

[jcalz]

I'm confused by this; is the suggestion that a NonEmptyArray utility type be added... to... the TS libraries for ES2023? Why that version of JavaScript in particular? What functionality from ES2023 is that needed for?

The new issue template for "library change" doesn't mention it, but the "new feature" template has a rule that

• [x] This isn't a request to add a new utility type: https://github.com/microsoft/TypeScript/wiki/No-New-Utility-Types

So I don't see how or why this would be added to TypeScript. @RyanCavanaugh, could you clarify why this is awaiting more feedback instead of just declined? Thanks!

[Rudxain]

Why that version of JavaScript in particular?

https://github.com/microsoft/TypeScript/blob/b58ac4abf2d58d6309274c22762e2196789476d9/.github/ISSUE_TEMPLATE/lib_change.yml?plain=1#L26

https://github.com/microsoft/TypeScript/blob/b58ac4abf2d58d6309274c22762e2196789476d9/.github/ISSUE_TEMPLATE/lib_change.yml?plain=1#L33

I've considered specifying ESNext, but I felt it was more honest to answer with the stable version.

https://github.com/microsoft/TypeScript/wiki/No-New-Utility-Types

I'm unsure if this counts as a utility, as it's not a "type of types" but a more concrete (while still generic) "array of 1 or more things"

[mkantor]

I'm unsure if this counts as a utility, as it's not a "type of types" but a more concrete (while still generic) "array of 1 or more things"

It's a generic type whose instantiation is a concrete type, which is the case for all generic types in TypeScript (the language doesn't support higher-kinded types).

[Rudxain]

It's a generic type whose instantiation is a concrete type, which is the case for all generic types

Correct! I should've said something like: """ Unlike Exclude, Pick, Omit, etc... NonEmptyArray is not a "type-level function" as it doesn't map a type to another. """ But if we go to the "everything is a function" route, NonEmptyArray<T> actually is a type-fn that maps T to a "tuple of 1 or more Ts". Which, I guess it's technically correct? I mean, there are functions that return concrete constants (this is true for many languages), which can be thought of as "A lambda that maps a Unit-type to a unit from another type" (this is true if the lambda is pure)

doesn't support higher-kinded types

I beg to differ: #55280 (see the namespaces section). TBF, it isn't an actual HKT, but it does have some features in common

[jcalz]

Hmm, I really wish someone from the TS team would re-review this, otherwise this is apparently going to remain unresolved.

Your suggested types are still utility types (type NonNullable<T> = T & {} is a utility type, which is arguably less of a "mapping" than [T, ...T[]]) and runs into all the problems as mentioned in https://github.com/microsoft/TypeScript/wiki/No-New-Utility-Types: you're using up the name NonEmptyArray in the global scope, with a specific definition you prefer, but what if I prefer type NonEmptyArray<T> = [...T[], T] or type NonEmptyArray<T> = T[] & {0: any}? Or something completely different? What good does it do for TypeScript itself to make this choice for people?

As for ES2023, the library change feature is supposed to be something like #59162: some particular JS feature that was introduced with ES2023 is either missing or incorrect in the TS library. You're not talking about any JS feature at all, in any version of JS. That's why you balked at the documentation link. Utility types tend to go in the ES5 library, since it would be quite strange for someone targeting ES2018 to not have NonEmptyArray<T> in scope. But it's still not an ES5 "library change" request, per se. This really looks like a misfiled feature request.

I've made an attempt to explain what's going on, but I am not a member of the TS team, so I cannot speak authoritatively about this. At this point I'm in danger of merely repeating myself (maybe I already have?) so I'll disengage until and unless more definitive happens.

[Rudxain]

what if I prefer type NonEmptyArray<T> = [...T[], T] or type NonEmptyArray<T> = T[] & {0: any}?

Also a Zipper list:

type NonEmptyList<T> = [T] | [T, NonEmptyList<T>]

What good does it do for TypeScript itself to make this choice for people?

In that case, an alternative would be to declare all those types, with different names (but more accurate, such as NonEmptyTuple). But that causes fragmentation through lack of standardization (such as "Linux in ye olden days"), and a lot more burden to maintainers, so either approach seems undesirable.

That's why I've opened an unofficial "stage -1" TC39 proposal

You're not talking about any JS feature at all, in any version of JS

I thought feature-requests were for the TS lang itself, not the lib 😅. That's why I've chosen lib-change.

I've made an attempt to explain what's going on. [...] At this point I'm in danger of merely repeating myself (maybe I already have?) so I'll disengage until and unless more definitive happens.

@jcalz Thank you for the guidance! And I'm sorry for any inconveniences and misunderstandings I may have caused to everyone in this thread