feat(array/types): init

- `Fill` replaces array values with a given value.

- `Flat` is analogous to `Array.prototype.flat()`

- `Indices` extracts the index values of an array.

- `Index` extracts a union of indices from an array.

- `FromIndices` describes a new array from a given array and a tuple of indices.

- `Reverse` describes an array with the same elements in reverse order.

- `Zip` combines two arrays into an array of tuples. Useful for creating object entries.

- The `Tuple` namespace clusters all helper types which respect tuples, which currently includes all types. This was a preferable alternative to starting a new top-level `tuple` module just to house these typedefs.

array/mod.ts

@@ -1 +1,2 @@
 export * from "./utils.ts";
+export * from "./types.ts";

array/types.ts

@@ -0,0 +1,73 @@
+/** Represents an array whose items are replaced with `Value`.
+ *
+ * @example
+ * type A = Fill<[1, 2, 3], "a"> // ["a", "a", "a"]
+ * type B = Fill<Array<unknown>, "b"> // Array<"b"> */
+export type Fill<T extends unknown[], Value> = {
+  [K in keyof T]: Value;
+};
+
+/** Represents an array flattened one level deep, analogous to
+ * `Array.prototype.flat()`.
+ *
+ * @example
+ * const items: Flat<[1, 2, [3, [4], 5]]> = [1, 2, 3, [4], 5]; */
+export type Flat<T extends unknown[]> = T extends [infer Head, ...infer Tail]
+  ? Head extends unknown[] ? [...Head, ...Flat<Tail>]
+  : [Head, ...Flat<Tail>]
+  : [];
+
+/** Represents an array reversed, analogous to `Array.prototype.reverse()`.
+ *
+ * @example
+ * const items: Reverse<[1, 2, 3]> = [3, 2, 1] */
+export type Reverse<T extends unknown[]> = T extends [infer Head, ...infer Tail]
+  ? [...Reverse<Tail>, Head]
+  : [];
+
+type _Indices<T extends unknown[]> = T extends [unknown, ...infer Tail]
+  ? [Tail["length"], ..._Indices<Tail>]
+  : [];
+
+/** Represents a tuple of the indices of `T`.
+ *
+ * @example
+ * type A = Indices<["a", "b", "c"]> // [0, 1, 2] */
+export type Indices<T extends unknown[]> = Reverse<_Indices<T>>;
+
+/** Represents one of the indices of `T`.
+ *
+ * @example
+ * type A = Index<["a", "b", "c"]> // 0 | 1 | 2 */
+export type Index<T extends unknown[]> = Indices<T>[number];
+
+type _FromIndices<T extends unknown[], I> = I extends
+  [infer Head extends keyof T, ...infer Tail extends Array<keyof T>]
+  ? [T[Head], ..._FromIndices<T, Tail>]
+  : [];
+
+/** Represents a tuple composed from values of `T` at the indices `I`.
+ *
+ * @example
+ * type A = FromIndices<["n", "s", "o"], [1, 2, 2, 0]>
+ * // ["s", "o", "o", "n"] */
+export type FromIndices<T extends unknown[], I extends Index<T>[]> =
+  _FromIndices<T, I>;
+
+/** Represents an array of length-2 tuples comprised of two arrays zippered
+ * together.
+ *
+ * @example
+ * type A = Zip<[1, 2, 3], ["a", "b", "c"]>
+ * // [[1, "a"], [2, "b"], [3, "c"]] */
+export type Zip<A extends unknown[], B extends unknown[]> = A extends
+  [infer HeadA, ...infer TailA]
+  ? B extends [infer HeadB, ...infer TailB]
+    ? [[HeadA, HeadB], ...Zip<TailA, TailB>]
+  : []
+  : [];
+
+/** Array utility types which are designed to respect tuples. */
+export declare namespace Tuple {
+  export { Fill, Flat, FromIndices, Index, Indices, Reverse, Zip };
+}

readme.md

@@ -35,6 +35,17 @@ mapOnInterval([3, 2, 1, "go!"], 100, (item) => console.log(item));
 // 100ms later, logs: "go!"
 ```
 
+```ts
+import type { Tuple } from "https://deno.land/x/handy/array/types.ts";
+
+type Filled = Tuple.Fill<["a", "b"], 7>; // [7, 7]
+type Flattened = Tuple.Flat<[[1, 2], [3, 4]]>; // [1, 2, 3, 4]
+type Indices = Tuple.Indices<["a", "b", "c"]>; // [0, 1, 2]
+type Index = Tuple.Index<["a", "b", "c"]>; // 0 | 1 | 2
+type Reversed = Tuple.Reverse<[1, 2, 3]>; // [3, 2, 1]
+type Deed = Tuple.FromIndices<["d", "e"], [0, 1, 1, 0]>; // ["d", "e", "e", "d"]
+```
+
 ## `cli`
 
 CLI-related utilities.