unique

function unique<T, K = T>(array: T[], iteratee?: (value: T) => K): T[];

Values are compared with SameValueZero, the rule a Set uses: NaN deduplicates against NaN, which === never does, and -0 collapses with 0. Order is the order of first appearance, and the input is not modified.

Objects are compared by identity, so two objects with the same contents are two values. The optional iteratee produces the key each value is compared by, which is how records are deduplicated by an id rather than by identity. When keys collide, the earlier value wins.

Parameters

Parameter	Type	Description
`array`	`T[]`	The array to deduplicate. Left untouched.
`iteratee` (optional)	`(value: T) => K`	Produces the key a value is compared by. Values compare by themselves when omitted.

Returns

T[] — a new array without duplicates, in the order of first appearance.

Throws

Exception	Condition
`TypeError`	`array` is not an array.

Examples

Deduplicating values

unique([1, 2, 2, 3]); // => [1, 2, 3]
unique(["a", "b", "a"]); // => ["a", "b"]
unique([NaN, NaN]); // => [NaN]
unique([0, -0]); // => [0]

Deduplicating records by a key

import { unique } from "apps-script-utils";

const rows = [
  { id: 1, name: "first" },
  { id: 1, name: "second" },
  { id: 2, name: "third" }
];

unique(rows, (row) => row.id); // => [{ id: 1, name: "first" }, { id: 2, name: "third" }]

Collecting the distinct values of a column

/**
 * Lists every status used in a column, each one once, in the order they first
 * appear.
 */
export function listStatuses(sheet: GoogleAppsScript.Spreadsheet.Sheet): string[] {
  const column = sheet.getRange("C2:C").getValues().flat() as string[];

  return unique(column.filter((status: string): boolean => status !== ""));
}

function listStatuses(sheet) {
  const column = sheet.getRange("C2:C").getValues().flat();
  return unique(column.filter((status) => status !== ""));
}

Source

src/lang/array/unique.ts

23 September 2026

This documentation was generated with AI (Claude) from the library's source code.

apps-script-utils 2.1.1 Help