Collection

Collection<K, V> extends JavaScript’s built-in Map with higher-order functional methods for querying and transforming data. All resource caches in Lunibee use Collection.

Import

TypeScript

import { Collection } from "lunibee";
// or from the sub-package:
import { Collection } from "@lunibee/collection";

JavaScript

import { Collection } from "lunibee";
// or from the sub-package:
import { Collection } from "@lunibee/collection";

Constructor

TypeScript

const col = new Collection<string, User>();
// From entries:
const col = new Collection([["id1", user1], ["id2", user2]]);

JavaScript

const col = new Collection<string, User>();
// From entries:
const col = new Collection([["id1", user1], ["id2", user2]]);

Inherited Map Methods

All standard Map methods are available: get, set, delete, has, clear, size, forEach, keys, values, entries.

Additional Methods

find(predicate)

Returns the first value matching the predicate, or undefined.

TypeScript

const admin = client.users.cache.find(u => u.username === "admin");

JavaScript

const admin = client.users.cache.find(u => u.username === "admin");

findKey(predicate)

Returns the first key matching the predicate, or undefined.

TypeScript

const adminId = client.users.cache.findKey(u => u.username === "admin");

JavaScript

const adminId = client.users.cache.findKey(u => u.username === "admin");

filter(predicate)

Returns a new Collection containing only entries where the predicate returns true.

TypeScript

const bots = client.users.cache.filter(u => u.bot);

JavaScript

const bots = client.users.cache.filter(u => u.bot);

map(fn)

Returns an array of the results of calling fn on every value.

TypeScript

const usernames = client.users.cache.map(u => u.username);
// → ["alice", "bob", "lunibee_bot", ...]

JavaScript

const usernames = client.users.cache.map(u => u.username);
// → ["alice", "bob", "lunibee_bot", ...]

flatMap(fn)

Returns a flat array from a function that returns arrays.

reduce(fn, initialValue)

Reduces the collection to a single value.

TypeScript

const totalBoosters = client.guilds.cache.reduce(
  (acc, guild) => acc + guild.premiumSubscriptionCount,
  0,
);

JavaScript

const totalBoosters = client.guilds.cache.reduce(
  (acc, guild) => acc + guild.premiumSubscriptionCount,
  0,
);

some(predicate)

Returns true if any entry matches the predicate.

TypeScript

const hasBot = client.users.cache.some(u => u.bot);

JavaScript

const hasBot = client.users.cache.some(u => u.bot);

every(predicate)

Returns true if all entries match the predicate.

first(amount?)

Returns the first value, or the first n values as an array.

TypeScript

const firstUser = client.users.cache.first();
const firstThree = client.users.cache.first(3);

JavaScript

const firstUser = client.users.cache.first();
const firstThree = client.users.cache.first(3);

last(amount?)

Returns the last value, or the last n values as an array.

firstKey(amount?) / lastKey(amount?)

Returns the first or last key(s).

at(index)

Returns the value at a numeric index (supports negative for reverse).

TypeScript

const lastUser = client.users.cache.at(-1);

JavaScript

const lastUser = client.users.cache.at(-1);

keyAt(index)

Returns the key at a numeric index.

random(amount?)

Returns a random value, or n random values as an array.

randomKey(amount?)

Returns a random key.

sweep(predicate)

Removes all entries where the predicate returns true. Returns the number removed.

TypeScript

const removed = collection.sweep(u => u.bot);

JavaScript

const removed = collection.sweep(u => u.bot);

partition(predicate)

Splits the collection into two: [matching, notMatching].

TypeScript

const [bots, humans] = client.users.cache.partition(u => u.bot);

JavaScript

const [bots, humans] = client.users.cache.partition(u => u.bot);

sorted(compareFn?)

Returns a new Collection sorted by the comparator.

TypeScript

const byName = client.guilds.cache.sorted((a, b) => a.name.localeCompare(b.name));

JavaScript

const byName = client.guilds.cache.sorted((a, b) => a.name.localeCompare(b.name));

sort(compareFn?)

Sorts the collection in place.

concat(...collections)

Returns a new Collection merging this with others.

difference(other)

Returns entries that are in this collection but not in other.

intersect(other)

Returns entries that are in both collections.

mapValues(fn)

Returns a new Collection with transformed values.

groupBy(fn, collection?)

Groups values by the return value of fn.

toJSON()

Returns an array of values.

Example

Filter and display online guild members

TypeScript

const onlineMembers = client.guilds.cache
  .filter(g => g.isCommunity)
  .map(g => g.name);

console.log("Community guilds:", onlineMembers.join(", "));

JavaScript

const onlineMembers = client.guilds.cache
  .filter(g => g.isCommunity)
  .map(g => g.name);

console.log("Community guilds:", onlineMembers.join(", "));

Get the 5 most recently joined users

TypeScript

const newest = client.users.cache
  .sorted((a, b) => b.createdAt.getTime() - a.createdAt.getTime())
  .first(5);

JavaScript

const newest = client.users.cache
  .sorted((a, b) => b.createdAt.getTime() - a.createdAt.getTime())
  .first(5);