feat(collections): compile time guarantee on pure functions

collections/associate_by.ts

@@ -1,32 +1,32 @@
 // Copyright 2018-2021 the Deno authors. All rights reserved. MIT license.
 
 /**
-  * Transforms the given array into a Record, extracting the key of each element using the given selector.
-  * If the selector produces the same key for multiple elements, the latest one will be used (overriding the
-  * ones before it).
-  *
-  * Example:
-  *
-  * ```ts
-  * import { associateBy } from "./associate_by.ts"
-  * import { assertEquals } from "../testing/asserts.ts";
-  *
-  * const users = [
-  *     { id: 'a2e', userName: 'Anna' },
-  *     { id: '5f8', userName: 'Arnold' },
-  *     { id: 'd2c', userName: 'Kim' },
-  * ]
-  * const usersById = associateBy(users, it => it.id)
-  *
-  * assertEquals(usersById, {
-  *     'a2e': { id: 'a2e', userName: 'Anna' },
-  *     '5f8': { id: '5f8', userName: 'Arnold' },
-  *     'd2c': { id: 'd2c', userName: 'Kim' },
-  * })
-  * ```
-  */
+ * Transforms the given array into a Record, extracting the key of each element using the given selector.
+ * If the selector produces the same key for multiple elements, the latest one will be used (overriding the
+ * ones before it).
+ *
+ * Example:
+ *
+ * ```ts
+ * import { associateBy } from "./associate_by.ts"
+ * import { assertEquals } from "../testing/asserts.ts";
+ *
+ * const users = [
+ *     { id: 'a2e', userName: 'Anna' },
+ *     { id: '5f8', userName: 'Arnold' },
+ *     { id: 'd2c', userName: 'Kim' },
+ * ]
+ * const usersById = associateBy(users, it => it.id)
+ *
+ * assertEquals(usersById, {
+ *     'a2e': { id: 'a2e', userName: 'Anna' },
+ *     '5f8': { id: '5f8', userName: 'Arnold' },
+ *     'd2c': { id: 'd2c', userName: 'Kim' },
+ * })
+ * ```
+ */
 export function associateBy<T>(
-  array: Array<T>,
+  array: readonly T[],
   selector: (el: T) => string,
 ): Record<string, T> {
   const ret: Record<string, T> = {};

collections/chunked.ts

@@ -19,10 +19,7 @@
  * ])
  * ```
  */
-export function chunked<T>(
-  array: Array<T>,
-  size: number,
-): Array<Array<T>> {
+export function chunked<T>(array: readonly T[], size: number): T[][] {
   if (size <= 0 || !Number.isInteger(size)) {
     throw new Error(
       `Expected size to be an integer greather than 0 but found ${size}`,

collections/deep_merge.ts

@@ -27,19 +27,19 @@ import { filterInPlace } from "./_utils.ts";
 export function deepMerge<
   T extends Record<PropertyKey, unknown>,
 >(
-  record: Partial<T>,
-  other: Partial<T>,
-  options?: DeepMergeOptions,
+  record: Partial<Readonly<T>>,
+  other: Partial<Readonly<T>>,
+  options?: Readonly<DeepMergeOptions>,
 ): T;
 
 export function deepMerge<
   T extends Record<PropertyKey, unknown>,
   U extends Record<PropertyKey, unknown>,
   Options extends DeepMergeOptions,
 >(
-  record: T,
-  other: U,
-  options?: Options,
+  record: Readonly<T>,
+  other: Readonly<U>,
+  options?: Readonly<Options>,
 ): DeepMerge<T, U, Options>;
 
 export function deepMerge<
@@ -51,9 +51,9 @@ export function deepMerge<
     maps: "merge";
   },
 >(
-  record: T,
-  other: U,
-  options?: Options,
+  record: Readonly<T>,
+  other: Readonly<U>,
+  options?: Readonly<Options>,
 ): DeepMerge<T, U, Options> {
   // Extract options
   // Clone left operand to avoid performing mutations in-place
@@ -93,14 +93,14 @@ export function deepMerge<
 }
 
 function mergeObjects(
-  left: NonNullable<object>,
-  right: NonNullable<object>,
-  options: DeepMergeOptions = {
+  left: Readonly<NonNullable<object>>,
+  right: Readonly<NonNullable<object>>,
+  options: Readonly<DeepMergeOptions> = {
     arrays: "merge",
     sets: "merge",
     maps: "merge",
   },
-): NonNullable<object> {
+): Readonly<NonNullable<object>> {
   // Recursively merge mergeable objects
   if (isMergeable(left) && isMergeable(right)) {
     return deepMerge(left, right);
@@ -151,7 +151,7 @@ function mergeObjects(
  */
 function isMergeable(
   value: NonNullable<object>,
-): boolean {
+): value is Record<PropertyKey, unknown> {
   return Object.getPrototypeOf(value) === Object.prototype;
 }
 

collections/distinct.ts

@@ -15,7 +15,7 @@
  * assertEquals(distinctNumbers, [ 3, 2, 5 ])
  * ```
  */
-export function distinct<T>(array: Array<T>): Array<T> {
+export function distinct<T>(array: readonly T[]): T[] {
   const set = new Set(array);
 
   return Array.from(set);

collections/distinct_by.ts

@@ -16,11 +16,11 @@
  * ```
  */
 export function distinctBy<T, D>(
-  array: Array<T>,
+  array: readonly T[],
   selector: (el: T) => D,
-): Array<T> {
+): T[] {
   const selectedValues = new Set<D>();
-  const ret = new Array<T>();
+  const ret: T[] = [];
 
   for (const element of array) {
     const currentSelectedValue = selector(element);

collections/filter_entries.ts

@@ -24,7 +24,7 @@
  * ```
  */
 export function filterEntries<T>(
-  record: Record<string, T>,
+  record: Readonly<Record<string, T>>,
   predicate: (entry: [string, T]) => boolean,
 ): Record<string, T> {
   const ret: Record<string, T> = {};

collections/filter_keys.ts

@@ -23,7 +23,7 @@
  * ```
  */
 export function filterKeys<T>(
-  record: Record<string, T>,
+  record: Readonly<Record<string, T>>,
   predicate: (key: string) => boolean,
 ): Record<string, T> {
   const ret: Record<string, T> = {};

collections/filter_values.ts

@@ -25,7 +25,7 @@
  * ```
  */
 export function filterValues<T>(
-  record: Record<string, T>,
+  record: Readonly<Record<string, T>>,
   predicate: (value: T) => boolean,
 ): Record<string, T> {
   const ret: Record<string, T> = {};

collections/find_last.ts

@@ -16,7 +16,7 @@
  * ```
  */
 export function findLast<T>(
-  array: Array<T>,
+  array: readonly T[],
   predicate: (el: T) => boolean,
 ): T | undefined {
   for (let i = array.length - 1; i >= 0; i -= 1) {

collections/find_last_index.ts

@@ -16,7 +16,7 @@
  * ```
  */
 export function findLastIndex<T>(
-  array: Array<T>,
+  array: readonly T[],
   predicate: (el: T) => boolean,
 ): number {
   for (let i = array.length - 1; i >= 0; i -= 1) {

collections/group_by.ts

@@ -28,10 +28,10 @@
  * ```
  */
 export function groupBy<T>(
-  array: Array<T>,
+  array: readonly T[],
   selector: (el: T) => string,
-): Record<string, Array<T>> {
-  const ret: { [key: string]: Array<T> } = {};
+): Record<string, T[]> {
+  const ret: Record<string, T[]> = {};
 
   for (const element of array) {
     const key = selector(element);

collections/intersect.ts

@@ -18,7 +18,7 @@ import { filterInPlace } from "./_utils.ts";
  * assertEquals(commonInterests, [ 'Cooking', 'Music' ])
  * ```
  */
-export function intersect<T>(...arrays: Array<Array<T>>): Array<T> {
+export function intersect<T>(...arrays: (readonly T[])[]): T[] {
   if (arrays.length === 0) {
     return [];
   }

collections/map_entries.ts

@@ -27,7 +27,7 @@
  * ```
  */
 export function mapEntries<T, O>(
-  record: Record<string, T>,
+  record: Readonly<Record<string, T>>,
   transformer: (entry: [string, T]) => [string, O],
 ): Record<string, O> {
   const ret: Record<string, O> = {};

collections/map_keys.ts

@@ -22,7 +22,7 @@
  * ```
  */
 export function mapKeys<T>(
-  record: Record<string, T>,
+  record: Readonly<Record<string, T>>,
   transformer: (key: string) => string,
 ): Record<string, T> {
   const ret: Record<string, T> = {};

collections/map_not_nullish.ts

@@ -22,10 +22,10 @@
  * ```
  */
 export function mapNotNullish<T, O>(
-  array: Array<T>,
+  array: readonly T[],
   transformer: (el: T) => O,
-): Array<NonNullable<O>> {
-  const ret = new Array<NonNullable<O>>();
+): NonNullable<O>[] {
+  const ret: NonNullable<O>[] = [];
 
   for (const element of array) {
     const transformedElement = transformer(element);

collections/map_values.ts

@@ -23,7 +23,7 @@
  * ```
  */
 export function mapValues<T, O>(
-  record: Record<string, T>,
+  record: Readonly<Record<string, T>>,
   transformer: (value: T) => O,
 ): Record<string, O> {
   const ret: Record<string, O> = {};

collections/partition.ts

@@ -18,9 +18,9 @@
  * ```
  */
 export function partition<T>(
-  array: Array<T>,
+  array: readonly T[],
   predicate: (el: T) => boolean,
-): [Array<T>, Array<T>] {
+): [T[], T[]] {
   const matches: Array<T> = [];
   const rest: Array<T> = [];
 

collections/permutations.ts

@@ -20,15 +20,15 @@
  * ])
  * ```
  */
-export function permutations<T>(array: Array<T>): Array<Array<T>> {
-  const ret: Array<Array<T>> = [];
+export function permutations<T>(array: readonly T[]): T[][] {
+  const ret: T[][] = [];
 
   if (array.length === 0) {
     return ret;
   }
 
   // Heap Algorithm
-  function heapPermutations(k: number, array: Array<T>) {
+  function heapPermutations(k: number, array: T[]) {
     const c = new Array<number>(k).fill(0);
 
     ret.push([...array]);

collections/sort_by.ts

@@ -24,13 +24,13 @@
  * ```
  */
 export function sortBy<T>(
-  array: Array<T>,
+  array: readonly T[],
   selector:
     | ((el: T) => number)
     | ((el: T) => string)
     | ((el: T) => bigint)
     | ((el: T) => Date),
-): Array<T> {
+): T[] {
   return Array.from(array).sort((a, b) => {
     const selectedA = selector(a);
     const selectedB = selector(b);

collections/sum_of.ts

@@ -20,7 +20,7 @@
  * ```
  */
 export function sumOf<T>(
-  array: Array<T>,
+  array: readonly T[],
   selector: (el: T) => number,
 ): number {
   let sum = 0;

collections/union.ts

@@ -16,7 +16,7 @@
  * assertEquals(shoppingList, [ 'Pepper', 'Carrots', 'Leek', 'Radicchio' ])
  * ```
  */
-export function union<T>(...arrays: Array<Array<T>>): Array<T> {
+export function union<T>(...arrays: (readonly T[])[]): T[] {
   const set = new Set<T>();
 
   for (const array of arrays) {

collections/unzip.ts

@@ -22,9 +22,9 @@
  * assertEquals(moms, [ 'Jeff', 'Kim', 'Leroy' ])
  * ```
  */
-export function unzip<T, U>(pairs: Array<[T, U]>): [Array<T>, Array<U>] {
+export function unzip<T, U>(pairs: readonly [T, U][]): [T[], U[]] {
   const { length } = pairs;
-  const ret: [Array<T>, Array<U>] = [
+  const ret: [T[], U[]] = [
     new Array(length),
     new Array(length),
   ];

collections/zip.ts

@@ -22,21 +22,15 @@
  * ```
  */
 export function zip<T, U>(
-  array: Array<T>,
-  withArray: Array<U>,
-): Array<[T, U]> {
-  const returnLength = Math.min(
-    array.length,
-    withArray.length,
-  );
+  array: readonly T[],
+  withArray: readonly U[],
+): [T, U][] {
+  const returnLength = Math.min(array.length, withArray.length);
 
-  const ret: Array<[T, U]> = [];
+  const ret = new Array<[T, U]>(returnLength);
 
   for (let i = 0; i < returnLength; i += 1) {
-    ret.push([
-      array[i],
-      withArray[i],
-    ]);
+    ret[i] = [array[i], withArray[i]];
   }
 
   return ret;