@fluxerjs/collection 1.0.2

package/dist/index.d.mts

@@ -0,0 +1,86 @@
+/**
+ * Extended Map with utility methods for key-value collections.
+ * Similar to discord.js Collection.
+ */
+declare class Collection<K, V> extends Map<K, V> {
+    /**
+     * Obtains the first value(s) in this collection.
+     * @param amount - Amount of values to obtain (optional)
+     */
+    first(): V | undefined;
+    first(amount: number): V[];
+    /**
+     * Obtains the last value(s) in this collection.
+     * @param amount - Amount of values to obtain (optional)
+     */
+    last(): V | undefined;
+    last(amount: number): V[];
+    /**
+     * Returns a random value from this collection.
+     * @param amount - Amount of values to randomly obtain (optional)
+     */
+    random(): V | undefined;
+    random(amount: number): V[];
+    /**
+     * Searches for a single item where the given function returns a truthy value.
+     */
+    find(fn: (value: V, key: K) => boolean): V | undefined;
+    /**
+     * Returns the key of the first item where the given function returns a truthy value.
+     */
+    findKey(fn: (value: V, key: K) => boolean): K | undefined;
+    /**
+     * Creates a new collection with all elements that pass the test implemented by the provided function.
+     */
+    filter(fn: (value: V, key: K) => boolean): Collection<K, V>;
+    /**
+     * Creates a new array with the results of calling the provided function on every element.
+     */
+    map<T>(fn: (value: V, key: K) => T): T[];
+    /**
+     * Tests whether at least one element passes the test implemented by the provided function.
+     */
+    some(fn: (value: V, key: K) => boolean): boolean;
+    /**
+     * Tests whether all elements pass the test implemented by the provided function.
+     */
+    every(fn: (value: V, key: K) => boolean): boolean;
+    /**
+     * Applies a function against an accumulator and each element to reduce the collection to a single value.
+     */
+    reduce<T>(fn: (accumulator: T, value: V, key: K) => T, initialValue: T): T;
+    /**
+     * Partitions the collection into two collections: one that passes the predicate and one that fails.
+     */
+    partition(fn: (value: V, key: K) => boolean): [Collection<K, V>, Collection<K, V>];
+    /**
+     * Invokes the given function and returns this collection (for chaining).
+     */
+    tap(fn: (collection: this) => void): this;
+    /**
+     * Creates an identical shallow copy of this collection.
+     */
+    clone(): Collection<K, V>;
+    /**
+     * Combines this collection with others into a new collection.
+     */
+    concat(...collections: ReadonlyCollection<K, V>[]): Collection<K, V>;
+    /**
+     * Sorts the collection in place and returns it.
+     */
+    sort(compareFn?: (a: V, b: V, aKey: K, bKey: K) => number): this;
+    /**
+     * Returns an array of the values in this collection.
+     */
+    toJSON(): V[];
+    /**
+     * Returns a string representation of the collection (array of values).
+     */
+    toString(): string;
+}
+/**
+ * Read-only view of a Collection (e.g. for method return types).
+ */
+type ReadonlyCollection<K, V> = Omit<Collection<K, V>, 'set' | 'delete' | 'clear'>;
+
+export { Collection, type ReadonlyCollection };

package/dist/index.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Extended Map with utility methods for key-value collections.
+ * Similar to discord.js Collection.
+ */
+declare class Collection<K, V> extends Map<K, V> {
+    /**
+     * Obtains the first value(s) in this collection.
+     * @param amount - Amount of values to obtain (optional)
+     */
+    first(): V | undefined;
+    first(amount: number): V[];
+    /**
+     * Obtains the last value(s) in this collection.
+     * @param amount - Amount of values to obtain (optional)
+     */
+    last(): V | undefined;
+    last(amount: number): V[];
+    /**
+     * Returns a random value from this collection.
+     * @param amount - Amount of values to randomly obtain (optional)
+     */
+    random(): V | undefined;
+    random(amount: number): V[];
+    /**
+     * Searches for a single item where the given function returns a truthy value.
+     */
+    find(fn: (value: V, key: K) => boolean): V | undefined;
+    /**
+     * Returns the key of the first item where the given function returns a truthy value.
+     */
+    findKey(fn: (value: V, key: K) => boolean): K | undefined;
+    /**
+     * Creates a new collection with all elements that pass the test implemented by the provided function.
+     */
+    filter(fn: (value: V, key: K) => boolean): Collection<K, V>;
+    /**
+     * Creates a new array with the results of calling the provided function on every element.
+     */
+    map<T>(fn: (value: V, key: K) => T): T[];
+    /**
+     * Tests whether at least one element passes the test implemented by the provided function.
+     */
+    some(fn: (value: V, key: K) => boolean): boolean;
+    /**
+     * Tests whether all elements pass the test implemented by the provided function.
+     */
+    every(fn: (value: V, key: K) => boolean): boolean;
+    /**
+     * Applies a function against an accumulator and each element to reduce the collection to a single value.
+     */
+    reduce<T>(fn: (accumulator: T, value: V, key: K) => T, initialValue: T): T;
+    /**
+     * Partitions the collection into two collections: one that passes the predicate and one that fails.
+     */
+    partition(fn: (value: V, key: K) => boolean): [Collection<K, V>, Collection<K, V>];
+    /**
+     * Invokes the given function and returns this collection (for chaining).
+     */
+    tap(fn: (collection: this) => void): this;
+    /**
+     * Creates an identical shallow copy of this collection.
+     */
+    clone(): Collection<K, V>;
+    /**
+     * Combines this collection with others into a new collection.
+     */
+    concat(...collections: ReadonlyCollection<K, V>[]): Collection<K, V>;
+    /**
+     * Sorts the collection in place and returns it.
+     */
+    sort(compareFn?: (a: V, b: V, aKey: K, bKey: K) => number): this;
+    /**
+     * Returns an array of the values in this collection.
+     */
+    toJSON(): V[];
+    /**
+     * Returns a string representation of the collection (array of values).
+     */
+    toString(): string;
+}
+/**
+ * Read-only view of a Collection (e.g. for method return types).
+ */
+type ReadonlyCollection<K, V> = Omit<Collection<K, V>, 'set' | 'delete' | 'clear'>;
+
+export { Collection, type ReadonlyCollection };

package/dist/index.js

@@ -0,0 +1,184 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Collection: () => Collection
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/Collection.ts
+var Collection = class _Collection extends Map {
+  first(amount) {
+    if (amount === void 0) return this.values().next().value;
+    const arr = this.toJSON();
+    if (amount <= 0) return [];
+    return arr.slice(0, amount);
+  }
+  last(amount) {
+    const arr = this.toJSON();
+    if (amount === void 0) return arr[arr.length - 1];
+    if (amount <= 0) return [];
+    return arr.slice(-amount);
+  }
+  random(amount) {
+    const arr = this.toJSON();
+    if (arr.length === 0) return amount === void 0 ? void 0 : [];
+    if (amount === void 0) return arr[Math.floor(Math.random() * arr.length)];
+    const copy = [...arr];
+    const result = [];
+    for (let i = 0; i < Math.min(amount, arr.length); i++) {
+      const index = Math.floor(Math.random() * copy.length);
+      result.push(copy.splice(index, 1)[0]);
+    }
+    return result;
+  }
+  /**
+   * Searches for a single item where the given function returns a truthy value.
+   */
+  find(fn) {
+    for (const [key, value] of this) {
+      if (fn(value, key)) return value;
+    }
+    return void 0;
+  }
+  /**
+   * Returns the key of the first item where the given function returns a truthy value.
+   */
+  findKey(fn) {
+    for (const [key, value] of this) {
+      if (fn(value, key)) return key;
+    }
+    return void 0;
+  }
+  /**
+   * Creates a new collection with all elements that pass the test implemented by the provided function.
+   */
+  filter(fn) {
+    const result = new _Collection();
+    for (const [key, value] of this) {
+      if (fn(value, key)) result.set(key, value);
+    }
+    return result;
+  }
+  /**
+   * Creates a new array with the results of calling the provided function on every element.
+   */
+  map(fn) {
+    const result = [];
+    for (const [key, value] of this) {
+      result.push(fn(value, key));
+    }
+    return result;
+  }
+  /**
+   * Tests whether at least one element passes the test implemented by the provided function.
+   */
+  some(fn) {
+    for (const [key, value] of this) {
+      if (fn(value, key)) return true;
+    }
+    return false;
+  }
+  /**
+   * Tests whether all elements pass the test implemented by the provided function.
+   */
+  every(fn) {
+    for (const [key, value] of this) {
+      if (!fn(value, key)) return false;
+    }
+    return true;
+  }
+  /**
+   * Applies a function against an accumulator and each element to reduce the collection to a single value.
+   */
+  reduce(fn, initialValue) {
+    let acc = initialValue;
+    for (const [key, value] of this) {
+      acc = fn(acc, value, key);
+    }
+    return acc;
+  }
+  /**
+   * Partitions the collection into two collections: one that passes the predicate and one that fails.
+   */
+  partition(fn) {
+    const pass = new _Collection();
+    const fail = new _Collection();
+    for (const [key, value] of this) {
+      if (fn(value, key)) pass.set(key, value);
+      else fail.set(key, value);
+    }
+    return [pass, fail];
+  }
+  /**
+   * Invokes the given function and returns this collection (for chaining).
+   */
+  tap(fn) {
+    fn(this);
+    return this;
+  }
+  /**
+   * Creates an identical shallow copy of this collection.
+   */
+  clone() {
+    return new _Collection(this);
+  }
+  /**
+   * Combines this collection with others into a new collection.
+   */
+  concat(...collections) {
+    const result = this.clone();
+    for (const coll of collections) {
+      for (const [key, value] of coll) result.set(key, value);
+    }
+    return result;
+  }
+  /**
+   * Sorts the collection in place and returns it.
+   */
+  sort(compareFn) {
+    const entries = [...this.entries()].sort((a, b) => {
+      if (compareFn) return compareFn(a[1], b[1], a[0], b[0]);
+      return 0;
+    });
+    this.clear();
+    for (const [key, value] of entries) {
+      this.set(key, value);
+    }
+    return this;
+  }
+  /**
+   * Returns an array of the values in this collection.
+   */
+  toJSON() {
+    return [...this.values()];
+  }
+  /**
+   * Returns a string representation of the collection (array of values).
+   */
+  toString() {
+    return `Collection(${this.size})`;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Collection
+});

package/dist/index.mjs

@@ -0,0 +1,157 @@
+// src/Collection.ts
+var Collection = class _Collection extends Map {
+  first(amount) {
+    if (amount === void 0) return this.values().next().value;
+    const arr = this.toJSON();
+    if (amount <= 0) return [];
+    return arr.slice(0, amount);
+  }
+  last(amount) {
+    const arr = this.toJSON();
+    if (amount === void 0) return arr[arr.length - 1];
+    if (amount <= 0) return [];
+    return arr.slice(-amount);
+  }
+  random(amount) {
+    const arr = this.toJSON();
+    if (arr.length === 0) return amount === void 0 ? void 0 : [];
+    if (amount === void 0) return arr[Math.floor(Math.random() * arr.length)];
+    const copy = [...arr];
+    const result = [];
+    for (let i = 0; i < Math.min(amount, arr.length); i++) {
+      const index = Math.floor(Math.random() * copy.length);
+      result.push(copy.splice(index, 1)[0]);
+    }
+    return result;
+  }
+  /**
+   * Searches for a single item where the given function returns a truthy value.
+   */
+  find(fn) {
+    for (const [key, value] of this) {
+      if (fn(value, key)) return value;
+    }
+    return void 0;
+  }
+  /**
+   * Returns the key of the first item where the given function returns a truthy value.
+   */
+  findKey(fn) {
+    for (const [key, value] of this) {
+      if (fn(value, key)) return key;
+    }
+    return void 0;
+  }
+  /**
+   * Creates a new collection with all elements that pass the test implemented by the provided function.
+   */
+  filter(fn) {
+    const result = new _Collection();
+    for (const [key, value] of this) {
+      if (fn(value, key)) result.set(key, value);
+    }
+    return result;
+  }
+  /**
+   * Creates a new array with the results of calling the provided function on every element.
+   */
+  map(fn) {
+    const result = [];
+    for (const [key, value] of this) {
+      result.push(fn(value, key));
+    }
+    return result;
+  }
+  /**
+   * Tests whether at least one element passes the test implemented by the provided function.
+   */
+  some(fn) {
+    for (const [key, value] of this) {
+      if (fn(value, key)) return true;
+    }
+    return false;
+  }
+  /**
+   * Tests whether all elements pass the test implemented by the provided function.
+   */
+  every(fn) {
+    for (const [key, value] of this) {
+      if (!fn(value, key)) return false;
+    }
+    return true;
+  }
+  /**
+   * Applies a function against an accumulator and each element to reduce the collection to a single value.
+   */
+  reduce(fn, initialValue) {
+    let acc = initialValue;
+    for (const [key, value] of this) {
+      acc = fn(acc, value, key);
+    }
+    return acc;
+  }
+  /**
+   * Partitions the collection into two collections: one that passes the predicate and one that fails.
+   */
+  partition(fn) {
+    const pass = new _Collection();
+    const fail = new _Collection();
+    for (const [key, value] of this) {
+      if (fn(value, key)) pass.set(key, value);
+      else fail.set(key, value);
+    }
+    return [pass, fail];
+  }
+  /**
+   * Invokes the given function and returns this collection (for chaining).
+   */
+  tap(fn) {
+    fn(this);
+    return this;
+  }
+  /**
+   * Creates an identical shallow copy of this collection.
+   */
+  clone() {
+    return new _Collection(this);
+  }
+  /**
+   * Combines this collection with others into a new collection.
+   */
+  concat(...collections) {
+    const result = this.clone();
+    for (const coll of collections) {
+      for (const [key, value] of coll) result.set(key, value);
+    }
+    return result;
+  }
+  /**
+   * Sorts the collection in place and returns it.
+   */
+  sort(compareFn) {
+    const entries = [...this.entries()].sort((a, b) => {
+      if (compareFn) return compareFn(a[1], b[1], a[0], b[0]);
+      return 0;
+    });
+    this.clear();
+    for (const [key, value] of entries) {
+      this.set(key, value);
+    }
+    return this;
+  }
+  /**
+   * Returns an array of the values in this collection.
+   */
+  toJSON() {
+    return [...this.values()];
+  }
+  /**
+   * Returns a string representation of the collection (array of values).
+   */
+  toString() {
+    return `Collection(${this.size})`;
+  }
+};
+export {
+  Collection
+};

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@fluxerjs/collection",
+  "publishConfig": {
+    "access": "public"
+  },
+  "version": "1.0.2",
+  "description": "Extended Map with utility methods for @fluxerjs/core",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "clean": "rm -rf dist"
+  }
+}