Add Arrayable type #270 (#935)

Co-authored-by: Sindre Sorhus <[email protected]>

index.d.ts

@@ -36,6 +36,7 @@ export type {UndefinedOnPartialDeep} from './source/undefined-on-partial-deep';
 export type {ReadonlyDeep} from './source/readonly-deep';
 export type {LiteralUnion} from './source/literal-union';
 export type {Promisable} from './source/promisable';
+export type {Arrayable} from './source/arrayable';
 export type {Opaque, UnwrapOpaque, Tagged, GetTagMetadata, UnwrapTagged} from './source/opaque';
 export type {InvariantOf} from './source/invariant-of';
 export type {SetOptional} from './source/set-optional';

readme.md

@@ -272,6 +272,7 @@ type ShouldBeNever = IfAny<'not any', 'not never', 'never'>;
 
 ### Array
 
+- [`Arrayable`](source/arrayable.d.ts) - Create a type that represents either the value or an array of the value.
 - [`Includes`](source/includes.d.ts) - Returns a boolean for whether the given array includes the given item.
 - [`Join`](source/join.d.ts) - Join an array of strings and/or numbers using the given string as a delimiter.
 - [`ArraySlice`](source/array-slice.d.ts) - Returns an array slice of a given range, just like `Array#slice()`.

source/arrayable.d.ts

@@ -0,0 +1,26 @@
+/**
+Create a type that represents either the value or an array of the value.
+
+@see Promisable
+
+@example
+```
+import type {Arrayable} from 'type-fest';
+
+function bundle(input: string, output: Arrayable<string>) {
+	const outputList = Array.isArray(output) ? output : [output];
+
+	// …
+
+	for (const output of outputList) {
+	  console.log(`write to: ${output}`);
+	}
+}
+
+bundle('src/index.js', 'dist/index.js');
+bundle('src/index.js', ['dist/index.cjs', 'dist/index.mjs']);
+```
+
+@category Array
+*/
+export type Arrayable<T> = T | readonly T[];

test-d/arrayable.ts

@@ -0,0 +1,9 @@
+import {expectType} from 'tsd';
+import type {Arrayable} from '../index';
+
+declare const unknown: unknown;
+
+expectType<Arrayable<string>>(unknown as string | readonly string[]);
+expectType<Arrayable<string | {foo: number}>>(unknown as (string | {foo: number}) | ReadonlyArray<string | {foo: number}>);
+expectType<Arrayable<never>>(unknown as /* never | */ readonly never[]);
+expectType<Arrayable<string[]>>(unknown as string[] | readonly string[][]);