Core Collection Methods

/**
 * Obtains the value of the given key if it exists, otherwise sets and returns the value provided by the default value generator
 * @param key - The key to get if it exists, or set otherwise
 * @param defaultValueGenerator - A function that generates the default value
 * @returns The existing value or the newly generated default value
 */
ensure(key: Key, defaultValueGenerator: (key: Key, collection: this) => Value): Value;

import { Collection } from "@discordjs/collection";

const guildConfigs = new Collection<string, GuildConfig>();

// Get existing config or create default
const config = guildConfigs.ensure(guildId, () => ({
  prefix: "!",
  welcomeChannel: null,
  modRole: null
}));

/**
 * Checks if all of the elements exist in the collection
 * @param keys - The keys of the elements to check for
 * @returns true if all of the elements exist, false if at least one does not exist
 */
hasAll(...keys: Key[]): boolean;

/**
 * Checks if any of the elements exist in the collection
 * @param keys - The keys of the elements to check for
 * @returns true if any of the elements exist, false if none exist
 */
hasAny(...keys: Key[]): boolean;

const collection = new Collection([
  ["a", 1], ["b", 2], ["c", 3]
]);

// Check if all keys exist
console.log(collection.hasAll("a", "b")); // true
console.log(collection.hasAll("a", "d")); // false

// Check if any keys exist
console.log(collection.hasAny("a", "d")); // true
console.log(collection.hasAny("x", "y")); // false

/**
 * Obtains the first value(s) in this collection
 * @param amount - Amount of values to obtain from the beginning
 * @returns A single value if no amount is provided or an array of values, starting from the end if amount is negative
 */
first(): Value | undefined;
first(amount: number): Value[];

/**
 * Obtains the first key(s) in this collection
 * @param amount - Amount of keys to obtain from the beginning
 * @returns A single key if no amount is provided or an array of keys, starting from the end if amount is negative
 */
firstKey(): Key | undefined;
firstKey(amount: number): Key[];

/**
 * Obtains the last value(s) in this collection
 * @param amount - Amount of values to obtain from the end
 * @returns A single value if no amount is provided or an array of values, starting from the start if amount is negative
 */
last(): Value | undefined;
last(amount: number): Value[];

/**
 * Obtains the last key(s) in this collection
 * @param amount - Amount of keys to obtain from the end
 * @returns A single key if no amount is provided or an array of keys, starting from the start if amount is negative
 */
lastKey(): Key | undefined;
lastKey(amount: number): Key[];

const users = new Collection([
  ["alice", { name: "Alice", age: 25 }],
  ["bob", { name: "Bob", age: 30 }],
  ["charlie", { name: "Charlie", age: 35 }]
]);

// Get single items
const firstUser = users.first(); // { name: "Alice", age: 25 }
const lastUserId = users.lastKey(); // "charlie"

// Get multiple items
const firstTwoUsers = users.first(2); // [{ name: "Alice", age: 25 }, { name: "Bob", age: 30 }]
const lastTwoKeys = users.lastKey(2); // ["bob", "charlie"]

// Negative amounts work from the opposite end
const lastTwo = users.first(-2); // [{ name: "Bob", age: 30 }, { name: "Charlie", age: 35 }]

/**
 * Returns the item at a given index, allowing for positive and negative integers
 * Negative integers count back from the last item in the collection
 * @param index - The index of the element to obtain
 * @returns The value at the specified index or undefined if out of bounds
 */
at(index: number): Value | undefined;

/**
 * Returns the key at a given index, allowing for positive and negative integers
 * Negative integers count back from the last item in the collection
 * @param index - The index of the key to obtain
 * @returns The key at the specified index or undefined if out of bounds
 */
keyAt(index: number): Key | undefined;

const collection = new Collection([
  ["a", 1], ["b", 2], ["c", 3]
]);

// Positive indices
console.log(collection.at(0)); // 1
console.log(collection.keyAt(1)); // "b"

// Negative indices (count from end)
console.log(collection.at(-1)); // 3
console.log(collection.keyAt(-2)); // "b"

// Out of bounds
console.log(collection.at(10)); // undefined
console.log(collection.keyAt(10)); // undefined

/**
 * Obtains unique random value(s) from this collection
 * @param amount - Amount of values to obtain randomly
 * @returns A single value if no amount is provided or an array of values
 */
random(): Value | undefined;
random(amount: number): Value[];

/**
 * Obtains unique random key(s) from this collection
 * @param amount - Amount of keys to obtain randomly
 * @returns A single key if no amount is provided or an array
 */
randomKey(): Key | undefined;
randomKey(amount: number): Key[];

const prizes = new Collection([
  ["gold", { name: "Gold Medal", value: 100 }],
  ["silver", { name: "Silver Medal", value: 50 }],
  ["bronze", { name: "Bronze Medal", value: 25 }],
  ["participation", { name: "Participation Trophy", value: 1 }]
]);

// Get random single item
const randomPrize = prizes.random(); // One random prize
const randomPrizeId = prizes.randomKey(); // One random key

// Get multiple random items (unique)
const threePrizes = prizes.random(3); // Array of 3 unique random prizes
const twoKeys = prizes.randomKey(2); // Array of 2 unique random keys

// If amount exceeds collection size, returns all items in random order
const allRandom = prizes.random(10); // All 4 prizes in random order