Collection

Collection<K, V> étend la Map<K, V> native de JavaScript avec des méthodes utilitaires inspirées des tableaux — c'est le type utilisé par le cache de tous les managers du SDK (client.guilds.cache, client.channels.cache, guild.roles.cache…) ainsi que par certains getters de structures (guild.channels).

Comme elle hérite directement de Map, toutes les méthodes standard (get, set, has, delete, clear, size, keys(), values(), entries(), itération for...of) restent disponibles telles quelles — Collection ne fait qu'ajouter des méthodes, elle n'en retire ni n'en modifie aucune.

TypeScript

import { Collection } from "bloumechat";

const collection = new Collection<string, number>();
collection.set("a", 1).set("b", 2);

JavaScript

const { Collection } = require("bloumechat");

// Pas de paramètres génériques en JS — Collection accepte n'importe quelle clé/valeur.
const collection = new Collection();
collection.set("a", 1).set("b", 2);

Constructeur hérité de Map

new Collection(entries?) accepte les mêmes arguments que new Map(entries?) — un itérable de paires [clé, valeur], ou aucun argument pour une collection vide. C'est ce que concat() et sorted() utilisent en interne pour construire leur résultat.

Méthodes

Méthode	Signature	Description
first()	() => V | undefined	Premier élément selon l'ordre d'insertion, ou undefined si vide.
last()	() => V | undefined	Dernier élément selon l'ordre d'insertion, ou undefined si vide.
random()	() => V | undefined	Élément choisi aléatoirement (distribution uniforme), ou undefined si vide.
filter(fn)	(v, k, coll) => boolean → Collection<K, V>	Nouvelle collection ne contenant que les entrées qui matchent.
map(fn)	(v, k, coll) => T → T[]	Transforme chaque entrée en un élément de tableau.
find(fn)	(v, k, coll) => boolean → V | undefined	Première valeur qui matche, ou undefined.
some(fn)	(v, k, coll) => boolean → boolean	true si au moins une entrée matche.
every(fn)	(v, k, coll) => boolean → boolean	true si toutes les entrées matchent (true sur collection vide — vérité vacueuse).
reduce(fn, initial)	(acc, v, k, coll) => T, T → T	Réduit la collection à une valeur unique, comme Array.prototype.reduce.
toArray()	() => V[]	Toutes les valeurs, en tableau, dans l'ordre d'insertion.
keyArray()	() => K[]	Toutes les clés, en tableau, dans l'ordre d'insertion.
isEmpty()	() => boolean	Équivalent à size === 0.
concat(other)	(other: Collection<K, V>) => Collection<K, V>	Nouvelle collection fusionnant this et other — ne mute ni l'une ni l'autre.
sorted(compareFn?)	(a: V, b: V) => number → Collection<K, V>	Nouvelle collection triée — ne mute pas l'originale.

first() / last() / random()

Les trois accesseurs ponctuels les plus courants. first() et last() respectent l'ordre d'insertion de la Map sous-jacente (comme un Array, pas un ordre trié). random() retourne toujours undefined sur une collection vide plutôt que de lever une erreur.

TypeScript

const anyMember = guild.members.cache.random();
const oldestRole = guild.roles.cache.first();

JavaScript

const anyMember = guild.members.cache.random();
const oldestRole = guild.roles.cache.first();

filter(fn)

fn reçoit (value, key, collection) — le troisième argument est la collection elle-même, utile pour des prédicats qui ont besoin du contexte global (taille totale, etc.). Retourne toujours une nouvelle Collection, jamais la même référence.

TypeScript

const textChannels = guild.channels.filter((c) => c.type === "TEXT");
const onlineMembers = guild.members.cache.filter((m) => m.user?.status === "online");

JavaScript

const textChannels = guild.channels.filter((c) => c.type === "TEXT");
const onlineMembers = guild.members.cache.filter((m) => m.user && m.user.status === "online");

map(fn)

Contrairement à filter/sorted, retourne un tableau simple (T[]), pas une Collection — parce que la valeur mappée n'a généralement plus de clé naturelle à conserver.

TypeScript

const names: string[] = guild.channels.map((c) => c.name);
console.log(names.join(", "));

JavaScript

const names = guild.channels.map((c) => c.name);
console.log(names.join(", "));

find(fn)

S'arrête au premier élément qui matche (pas de parcours complet inutile). Retourne undefined si rien ne matche — vérifiez toujours le résultat avant de l'utiliser.

TypeScript

const general = guild.channels.find((c) => c.name === "général");
if (general) await general.send("Bonjour !");

JavaScript

const general = guild.channels.find((c) => c.name === "général");
if (general) await general.send("Bonjour !");

some(fn) / every(fn)

Utiles pour des vérifications booléennes sans construire de tableau intermédiaire. every() renvoie true sur une collection vide (vérité vacueuse — comme Array.prototype.every).

TypeScript

const hasAdmin = guild.members.cache.some((m) => m.hasPermission(PermissionFlags.ADMINISTRATOR));
const allBots = guild.members.cache.every((m) => m.user?.bot === true);

JavaScript

const hasAdmin = guild.members.cache.some((m) => m.hasPermission(PermissionFlags.ADMINISTRATOR));
const allBots = guild.members.cache.every((m) => m.user && m.user.bot === true);

reduce(fn, initialValue)

Signature identique à Array.prototype.reduce, avec (key, collection) en arguments supplémentaires.

TypeScript

const totalMembers = client.guilds.cache.reduce(
  (sum, guild) => sum + guild.memberCount,
  0
);

JavaScript

const totalMembers = client.guilds.cache.reduce(
  (sum, guild) => sum + guild.memberCount,
  0
);

toArray() / keyArray()

Équivalents pratiques à Array.from(collection.values()) et Array.from(collection.keys()).

TypeScript

const allGuildIds: string[] = client.guilds.cache.keyArray();
const allGuilds = client.guilds.cache.toArray();

JavaScript

const allGuildIds = client.guilds.cache.keyArray();
const allGuilds = client.guilds.cache.toArray();

isEmpty()

TypeScript

if (guild.roles.cache.isEmpty()) {
  await guild.roles.create({ name: "Membres" });
}

JavaScript

if (guild.roles.cache.isEmpty()) {
  await guild.roles.create({ name: "Membres" });
}

concat(other)

Fusionne deux collections du même type <K, V> en une nouvelle collection. En cas de clé en conflit, la valeur de other écrase celle de this — l'ordre des arguments compte.

TypeScript

const merged = guild1.channels.concat(guild2.channels);

JavaScript

const merged = guild1.channels.concat(guild2.channels);

sorted(compareFn?)

Trie par valeur (pas par clé) et retourne une nouvelle Collection — l'originale n'est jamais mutée. Sans compareFn, l'ordre relatif des éléments est indéterminé (le tri interne utilise un comparateur qui renvoie toujours 0) : fournissez toujours un comparateur explicite si l'ordre compte pour vous.

TypeScript

const sortedByName = guild.channels.sorted((a, b) => a.name.localeCompare(b.name));
const sortedByPosition = guild.roles.cache.sorted((a, b) => b.position - a.position);

JavaScript

const sortedByName = guild.channels.sorted((a, b) => a.name.localeCompare(b.name));
const sortedByPosition = guild.roles.cache.sorted((a, b) => b.position - a.position);

Exemple combiné

TypeScript

const textChannels = guild.channels
  .filter((c) => c.type === "TEXT")
  .sorted((a, b) => a.name.localeCompare(b.name));

console.log(textChannels.map((c) => c.name).join(", "));

const generalChannel = guild.channels.find((c) => c.name === "général");

// Comme c'est une Map standard sous le capot, l'itération directe fonctionne aussi
for (const [id, channel] of guild.channels) {
  console.log(id, channel.name);
}

JavaScript

const textChannels = guild.channels
  .filter((c) => c.type === "TEXT")
  .sorted((a, b) => a.name.localeCompare(b.name));

console.log(textChannels.map((c) => c.name).join(", "));

const generalChannel = guild.channels.find((c) => c.name === "général");

// Comme c'est une Map standard sous le capot, l'itération directe fonctionne aussi
for (const [id, channel] of guild.channels) {
  console.log(id, channel.name);
}

Voir aussi

• BaseManager — expose cache: Collection<K, V>, la propriété la plus courante qui retourne une Collection.
• GuildManager, ChannelManager, RoleManager — managers dont le .cache est une Collection.