lunibee 0.2.3 → 0.3.0

package/dist/collection/index.js

@@ -1,64 +1,39 @@
 // @bun
 // packages/collection/src/cache.ts
 class Cache {
-  #entries = new Collection;
-  #maxSize;
-  #ttl;
-  #timer;
+  #entries;
   constructor(options = {}) {
-    this.#maxSize = options.maxSize ?? Infinity;
-    this.#ttl = options.ttl ?? 0;
-    if (!Number.isInteger(this.#maxSize) && this.#maxSize !== Infinity || this.#maxSize < 1)
+    const maxSize = options.maxSize ?? Infinity;
+    const ttl = options.ttl ?? 0;
+    if (!Number.isInteger(maxSize) && maxSize !== Infinity || maxSize < 1)
       throw new RangeError("Cache maxSize must be a positive integer.");
-    if (!Number.isFinite(this.#ttl) || this.#ttl < 0)
+    if (!Number.isFinite(ttl) || ttl < 0)
       throw new RangeError("Cache ttl must be a non-negative finite number.");
-    if (this.#ttl > 0) {
-      const interval = options.sweepInterval ?? Math.min(this.#ttl, 60000);
+    if (!((options.jitter ?? 0) >= 0 && (options.jitter ?? 0) <= 1))
+      throw new RangeError("Cache jitter must be between 0 and 1.");
+    if (ttl > 0) {
+      const interval = options.sweepInterval ?? Math.min(ttl, 60000);
       if (!Number.isFinite(interval) || interval < 1)
         throw new RangeError("Cache sweepInterval must be positive.");
-      this.#timer = setInterval(() => this.sweep(), interval);
-      this.#timer.unref?.();
     }
+    this.#entries = new Collection(null, {
+      ttl: ttl > 0 ? ttl : undefined,
+      jitter: options.jitter,
+      maxSize: maxSize === Infinity ? undefined : maxSize,
+      slide: false
+    });
   }
   get size() {
-    this.#sweepExpired();
     return this.#entries.size;
   }
   get(key) {
-    const entry = this.#entries.get(key);
-    if (!entry)
-      return;
-    if (entry.expiresAt > 0 && entry.expiresAt <= Date.now()) {
-      this.#entries.delete(key);
-      return;
-    }
-    this.#entries.delete(key);
-    this.#entries.set(key, entry);
-    return entry.value;
+    return this.#entries.get(key);
   }
   has(key) {
-    const entry = this.#entries.get(key);
-    if (!entry)
-      return false;
-    if (entry.expiresAt > 0 && entry.expiresAt <= Date.now()) {
-      this.#entries.delete(key);
-      return false;
-    }
-    return true;
+    return this.#entries.has(key);
   }
   set(key, value) {
-    const expiresAt = this.#ttl > 0 ? Date.now() + this.#ttl : 0;
-    this.#entries.delete(key);
-    this.#entries.set(key, { value, expiresAt });
-    if (this.#maxSize !== Infinity) {
-      while (this.#entries.size > this.#maxSize) {
-        const oldest = this.#entries.firstKey();
-        if (oldest !== undefined)
-          this.#entries.delete(oldest);
-        else
-          break;
-      }
-    }
+    this.#entries.set(key, value);
     return this;
   }
   delete(key) {
@@ -68,95 +43,53 @@ class Cache {
     this.#entries.clear();
   }
   invalidate(predicate) {
-    return this.#entries.sweep((entry, key) => predicate(entry.value, key));
+    return this.#entries.sweep(predicate);
   }
   sweep() {
-    return this.#entries.sweep((entry) => this.#expired(entry));
-  }
-  dispose() {
-    if (this.#timer)
-      clearInterval(this.#timer);
-    this.#timer = undefined;
+    return this.#entries.purge();
   }
+  dispose() {}
   values() {
-    this.#sweepExpired();
-    return this.#entries.map((entry) => entry.value);
+    return [...this.#entries.values()];
   }
   entries() {
-    this.#sweepExpired();
-    return this.#entries.map((entry, key) => [key, entry.value]);
-  }
-  #expired(entry) {
-    return entry.expiresAt > 0 && entry.expiresAt <= Date.now();
-  }
-  #sweepExpired() {
-    if (this.#ttl > 0)
-      this.sweep();
+    return [...this.#entries.entries()];
   }
 }
 
 // packages/collection/src/index.ts
-class RecencyList {
-  #nodes = new Map;
-  #oldest;
-  #newest;
-  get size() {
-    return this.#nodes.size;
-  }
-  oldest() {
-    return this.#oldest?.key;
-  }
-  touch(key) {
-    const node = this.#nodes.get(key);
-    if (node)
-      return this.#moveNewest(node);
-    const created = { key, older: this.#newest };
-    if (this.#newest)
-      this.#newest.newer = created;
-    else
-      this.#oldest = created;
-    this.#newest = created;
-    this.#nodes.set(key, created);
-  }
-  promote(key) {
-    const node = this.#nodes.get(key);
-    if (node)
-      this.#moveNewest(node);
-  }
-  delete(key) {
-    const node = this.#nodes.get(key);
-    if (!node)
-      return false;
-    this.#unlink(node);
-    this.#nodes.delete(key);
-    return true;
-  }
-  clear() {
-    this.#nodes.clear();
-    this.#oldest = this.#newest = undefined;
-  }
-  #unlink(node) {
-    if (node.older)
-      node.older.newer = node.newer;
-    else
-      this.#oldest = node.newer;
-    if (node.newer)
-      node.newer.older = node.older;
-    else
-      this.#newest = node.older;
-    node.older = node.newer = undefined;
-  }
-  #moveNewest(node) {
-    if (node === this.#newest)
-      return;
-    this.#unlink(node);
-    node.older = this.#newest;
-    if (this.#newest)
-      this.#newest.newer = node;
-    else
-      this.#oldest = node;
-    this.#newest = node;
-  }
+function newPolicy(options = {}) {
+  return {
+    ttl: options.ttl,
+    jitter: options.jitter ?? 0,
+    maxSize: options.maxSize,
+    slide: options.slide ?? true,
+    onEvict: options.onEvict,
+    expired: 0,
+    evicted: 0,
+    entries: new Map,
+    oldest: undefined,
+    newest: undefined,
+    lruSize: 0,
+    heap: [],
+    armedFor: Infinity
+  };
+}
+function peekOf(collection, key) {
+  return collection instanceof Map ? Map.prototype.get.call(collection, key) : collection.get(key);
+}
+var mapGet = Map.prototype.get;
+var mapHas = Map.prototype.has;
+function sample(items, amount) {
+  if (!Number.isInteger(amount) || amount < 0)
+    throw new RangeError("amount must be a non-negative integer.");
+  const count = Math.min(amount, items.length);
+  for (let i = 0;i < count; i++) {
+    const j = i + Math.floor(Math.random() * (items.length - i));
+    [items[i], items[j]] = [items[j], items[i]];
+  }
+  items.length = count;
+  return items;
 }
 function assertTTL(ttl) {
   if (ttl !== undefined && (!Number.isFinite(ttl) || ttl <= 0))
@@ -164,81 +97,95 @@ function assertTTL(ttl) {
 }
 
 class Collection extends Map {
-  #ttl;
-  #maxSize;
-  #onEvict;
-  #expiry = new Map;
-  #lru = new RecencyList;
-  #stats = {
-    hits: 0,
-    misses: 0,
-    expired: 0,
-    evicted: 0
-  };
-  #heap = [];
-  #timer;
-  #armedFor = Infinity;
+  #policy;
+  #hits = 0;
+  #misses = 0;
   constructor(entries, options = {}) {
     super();
     assertTTL(options.ttl);
+    if (options.jitter !== undefined && !(options.jitter >= 0 && options.jitter <= 1))
+      throw new RangeError("jitter must be between 0 and 1.");
     if (options.maxSize !== undefined && (!Number.isInteger(options.maxSize) || options.maxSize <= 0))
       throw new RangeError("maxSize must be a positive integer.");
-    this.#ttl = options.ttl;
-    this.#maxSize = options.maxSize;
-    this.#onEvict = options.onEvict;
+    if (options.ttl !== undefined || options.jitter !== undefined || options.maxSize !== undefined || options.slide !== undefined || options.onEvict !== undefined)
+      this.#policy = newPolicy(options);
     if (entries)
       for (const [key, value] of entries)
         this.set(key, value);
   }
   set(key, value, ttl) {
+    if (ttl === undefined && this.#policy === undefined)
+      return super.set(key, value);
     assertTTL(ttl);
-    const window = ttl ?? this.#ttl;
-    if (this.#maxSize !== undefined) {
-      this.#lru.touch(key);
-    }
-    super.set(key, value);
+    let window = ttl ?? this.#policy?.ttl;
+    const jitter = this.#policy?.jitter ?? 0;
+    if (window !== undefined && jitter > 0)
+      window = Math.max(1, window * (1 - jitter * Math.random()));
     if (window !== undefined)
-      this.#schedule(key, window);
-    else if (this.#expiry.size > 0)
-      this.#expiry.delete(key);
+      this.#policy ??= newPolicy();
+    if (!this.#policy)
+      return super.set(key, value);
+    const before = super.size;
+    super.set(key, value);
+    this.#track(key, value, window, super.size !== before);
     this.#enforceCap();
     return this;
   }
   setWithoutTTL(key, value) {
-    if (this.#expiry.size > 0)
-      this.#expiry.delete(key);
-    if (this.#lru.size > 0)
-      this.#lru.delete(key);
+    if (this.#policy)
+      this.#forget(key);
     super.set(key, value);
     return this;
   }
   get(key) {
-    if (this.#expireIfDue(key)) {
-      this.#stats.misses++;
+    const policy = this.#policy;
+    const entry = policy?.entries.get(key);
+    if (entry === undefined) {
+      const value = mapGet.call(this, key);
+      if (value !== undefined || mapHas.call(this, key)) {
+        this.#hits++;
+        return value;
+      }
+      this.#misses++;
       return;
     }
-    const value = super.get(key);
-    if (value === undefined && !super.has(key)) {
-      this.#stats.misses++;
+    const timed = entry.window !== 0;
+    const now = timed ? Date.now() : 0;
+    if (timed && entry.deadline <= now) {
+      this.#expire(entry);
+      this.#misses++;
       return;
     }
-    this.#stats.hits++;
-    const expiry = this.#expiry.get(key);
-    if (expiry)
-      expiry.deadline = Date.now() + expiry.window;
-    this.#lru.promote(key);
-    return value;
+    this.#hits++;
+    if (timed && policy.slide)
+      entry.deadline = now + entry.window;
+    if (entry.inLru)
+      this.#promote(policy, entry);
+    return entry.value;
+  }
+  ensure(key, factory, ttl) {
+    const existing = this.get(key);
+    if (existing !== undefined || super.has(key))
+      return existing;
+    const created = factory(key, this);
+    this.set(key, created, ttl);
+    return created;
   }
   peek(key) {
     if (!this.#expireIfDue(key) && super.has(key)) {
-      this.#stats.hits++;
+      this.#hits++;
       return super.get(key);
     }
-    this.#stats.misses++;
+    this.#misses++;
     return;
   }
   get stats() {
-    return { ...this.#stats };
+    return {
+      hits: this.#hits,
+      misses: this.#misses,
+      expired: this.#policy?.expired ?? 0,
+      evicted: this.#policy?.evicted ?? 0
+    };
   }
   has(key) {
     return !this.#expireIfDue(key) && super.has(key);
@@ -246,19 +193,23 @@ class Collection extends Map {
   delete(key) {
     if (this.#expireIfDue(key))
       return false;
-    this.#expiry.delete(key);
-    this.#lru.delete(key);
+    if (this.#policy)
+      this.#forget(key);
     return super.delete(key);
   }
   clear() {
     super.clear();
-    this.#expiry.clear();
-    this.#lru.clear();
-    this.#heap.length = 0;
-    if (this.#timer)
-      clearTimeout(this.#timer);
-    this.#timer = undefined;
-    this.#armedFor = Infinity;
+    const policy = this.#policy;
+    if (!policy)
+      return;
+    policy.entries.clear();
+    policy.oldest = policy.newest = undefined;
+    policy.lruSize = 0;
+    policy.heap.length = 0;
+    if (policy.timer)
+      clearTimeout(policy.timer);
+    policy.timer = undefined;
+    policy.armedFor = Infinity;
   }
   get size() {
     this.purge();
@@ -286,11 +237,11 @@ class Collection extends Map {
   ttlRemaining(key) {
     if (this.#expireIfDue(key))
       return;
-    const expiry = this.#expiry.get(key);
-    return expiry && Math.max(0, expiry.deadline - Date.now());
+    const entry = this.#policy?.entries.get(key);
+    return entry && entry.window !== 0 ? Math.max(0, entry.deadline - Date.now()) : undefined;
   }
   purge() {
-    if (this.#expiry.size === 0)
+    if (!this.#policy || this.#policy.heap.length === 0)
       return 0;
     const now = Date.now();
     let removed = 0;
@@ -301,133 +252,255 @@ class Collection extends Map {
       this.#remove(due.key);
       removed++;
     }
-    this.#stats.expired += removed;
+    this.#policy.expired += removed;
     this.#rearm();
     for (const [key, value] of dropped)
       this.#notify(key, value, "expired");
     return removed;
   }
   #expireIfDue(key) {
-    const expiry = this.#expiry.get(key);
-    if (!expiry || expiry.deadline > Date.now())
+    const entry = this.#policy?.entries.get(key);
+    if (!entry || entry.window === 0 || entry.deadline > Date.now())
       return false;
-    const value = super.get(key);
-    this.#remove(key);
-    this.#stats.expired++;
-    this.#notify(key, value, "expired");
+    this.#expire(entry);
     return true;
   }
+  #expire(entry) {
+    const value = super.get(entry.key);
+    this.#remove(entry.key);
+    this.#policy.expired++;
+    this.#notify(entry.key, value, "expired");
+  }
   #remove(key) {
-    this.#expiry.delete(key);
-    this.#lru.delete(key);
+    this.#forget(key);
     super.delete(key);
   }
+  #forget(key) {
+    const policy = this.#policy;
+    const entry = policy.entries.get(key);
+    if (!entry)
+      return;
+    if (entry.inLru)
+      this.#unlink(policy, entry);
+    policy.entries.delete(key);
+  }
+  #track(key, value, window, isNew) {
+    const policy = this.#policy;
+    const lru = policy.maxSize !== undefined;
+    let entry = isNew ? undefined : policy.entries.get(key);
+    if (entry)
+      entry.value = value;
+    if (window === undefined) {
+      if (entry && entry.window !== 0) {
+        if (lru)
+          entry = this.#replace(policy, entry, 0, 0);
+        else {
+          this.#forget(key);
+          return;
+        }
+      }
+      if (!entry && lru) {
+        entry = this.#create(key, value, 0, 0);
+        policy.entries.set(key, entry);
+      }
+      if (entry)
+        this.#promote(policy, entry);
+      return;
+    }
+    const deadline = Date.now() + window;
+    if (entry && entry.window !== 0) {
+      entry.deadline = deadline;
+      entry.window = window;
+      if (deadline < entry.filed)
+        entry = this.#replace(policy, entry, window, deadline);
+      else {
+        if (entry.inLru)
+          this.#promote(policy, entry);
+        return;
+      }
+    } else if (entry) {
+      entry.window = window;
+      entry.deadline = entry.filed = deadline;
+    } else {
+      entry = this.#create(key, value, window, deadline);
+      policy.entries.set(key, entry);
+    }
+    if (lru)
+      this.#promote(policy, entry);
+    this.#heapPush(entry);
+    if (policy.heap.length > 2 * policy.entries.size + 8)
+      this.#compact();
+    if (policy.timer === undefined || deadline < policy.armedFor)
+      this.#rearm();
+  }
+  #create(key, value, window, deadline) {
+    return {
+      key,
+      value,
+      older: undefined,
+      newer: undefined,
+      inLru: false,
+      window,
+      deadline,
+      filed: deadline
+    };
+  }
+  #replace(policy, old, window, deadline) {
+    const entry = {
+      ...old,
+      window,
+      deadline,
+      filed: deadline
+    };
+    if (old.inLru) {
+      if (old.older)
+        old.older.newer = entry;
+      else
+        policy.oldest = entry;
+      if (old.newer)
+        old.newer.older = entry;
+      else
+        policy.newest = entry;
+    }
+    policy.entries.set(old.key, entry);
+    return entry;
+  }
+  #promote(policy, entry) {
+    if (entry === policy.newest)
+      return;
+    if (entry.inLru)
+      this.#unlink(policy, entry, true);
+    else {
+      entry.inLru = true;
+      policy.lruSize++;
+    }
+    entry.older = policy.newest;
+    entry.newer = undefined;
+    if (policy.newest)
+      policy.newest.newer = entry;
+    else
+      policy.oldest = entry;
+    policy.newest = entry;
+  }
+  #unlink(policy, entry, keepCount = false) {
+    if (entry.older)
+      entry.older.newer = entry.newer;
+    else
+      policy.oldest = entry.newer;
+    if (entry.newer)
+      entry.newer.older = entry.older;
+    else
+      policy.newest = entry.older;
+    entry.older = entry.newer = undefined;
+    if (!keepCount) {
+      entry.inLru = false;
+      policy.lruSize--;
+    }
+  }
+  #derived() {
+    const Species = this.constructor[Symbol.species] ?? Collection;
+    return new Species;
+  }
   #notify(key, value, reason) {
-    if (!this.#onEvict)
+    const onEvict = this.#policy?.onEvict;
+    if (!onEvict)
       return;
     try {
-      this.#onEvict(key, value, reason);
+      onEvict(key, value, reason);
     } catch {}
   }
   #enforceCap() {
-    if (this.#maxSize === undefined)
+    const policy = this.#policy;
+    const max = policy.maxSize;
+    if (max === undefined)
       return;
-    while (this.#lru.size > this.#maxSize) {
-      const oldest = this.#lru.oldest();
-      const value = super.get(oldest);
-      this.#remove(oldest);
-      this.#stats.evicted++;
-      this.#notify(oldest, value, "evicted");
+    if (policy.lruSize > max && policy.heap.length > 0 && policy.heap[0].filed <= Date.now())
+      this.purge();
+    while (policy.lruSize > max) {
+      const oldest = policy.oldest;
+      const value = policy.onEvict ? super.get(oldest.key) : undefined;
+      this.#unlink(policy, oldest);
+      policy.entries.delete(oldest.key);
+      super.delete(oldest.key);
+      policy.evicted++;
+      this.#notify(oldest.key, value, "evicted");
     }
   }
-  #schedule(key, window) {
-    const deadline = Date.now() + window;
-    const expiry = this.#expiry.get(key);
-    if (expiry) {
-      expiry.deadline = deadline;
-      expiry.window = window;
-      if (deadline >= expiry.filed)
-        return;
-      expiry.filed = deadline;
-    } else
-      this.#expiry.set(key, { deadline, window, filed: deadline });
-    this.#heapPush({ key, deadline });
-    if (this.#heap.length > 2 * this.#expiry.size + 8)
-      this.#compact();
-    this.#rearm();
-  }
   #nextDeadline() {
+    const policy = this.#policy;
     for (;; ) {
-      const top = this.#heap[0];
+      const top = policy.heap[0];
       if (top === undefined)
         return Infinity;
-      const expiry = this.#expiry.get(top.key);
-      if (!expiry || expiry.filed !== top.deadline) {
+      if (policy.entries.get(top.key) !== top) {
         this.#heapPop();
         continue;
       }
-      if (expiry.deadline === top.deadline)
-        return top.deadline;
+      if (top.deadline === top.filed)
+        return top.filed;
       this.#heapPop();
-      expiry.filed = expiry.deadline;
-      this.#heapPush({ key: top.key, deadline: expiry.deadline });
+      top.filed = top.deadline;
+      this.#heapPush(top);
     }
   }
   #compact() {
-    const live = this.#heap.filter((record) => this.#expiry.get(record.key)?.filed === record.deadline);
-    this.#heap.length = 0;
-    for (const record of live)
-      this.#heapPush(record);
+    const policy = this.#policy;
+    const live = policy.heap.filter((entry) => policy.entries.get(entry.key) === entry);
+    policy.heap.length = 0;
+    for (const entry of live)
+      this.#heapPush(entry);
   }
   #rearm() {
+    const p = this.#policy;
     const deadline = this.#nextDeadline();
-    if (this.#timer !== undefined && deadline >= this.#armedFor)
+    if (p.timer !== undefined && deadline >= p.armedFor)
       return;
-    if (this.#timer)
-      clearTimeout(this.#timer);
-    this.#timer = undefined;
-    this.#armedFor = deadline;
+    if (p.timer)
+      clearTimeout(p.timer);
+    p.timer = undefined;
+    p.armedFor = deadline;
     if (deadline === Infinity)
       return;
-    this.#timer = setTimeout(() => {
-      this.#timer = undefined;
-      this.#armedFor = Infinity;
+    p.timer = setTimeout(() => {
+      p.timer = undefined;
+      p.armedFor = Infinity;
       this.purge();
     }, Math.max(0, deadline - Date.now()));
-    this.#timer.unref?.();
+    p.timer.unref?.();
   }
-  #heapPush(record) {
-    const heap = this.#heap;
-    heap.push(record);
-    let i = heap.length - 1;
+  #heapPush(entry) {
+    const heap = this.#policy.heap;
+    let i = heap.length;
+    heap.push(entry);
     while (i > 0) {
       const parent = i - 1 >> 1;
-      if (heap[parent].deadline <= heap[i].deadline)
+      const above = heap[parent];
+      if (above.filed <= entry.filed)
         break;
-      [heap[parent], heap[i]] = [heap[i], heap[parent]];
+      heap[i] = above;
       i = parent;
     }
+    heap[i] = entry;
   }
   #heapPop() {
-    const heap = this.#heap;
+    const heap = this.#policy.heap;
     const top = heap[0];
     const last = heap.pop();
     if (top === undefined || heap.length === 0)
       return top;
-    heap[0] = last;
-    for (let i = 0;; ) {
-      const left = 2 * i + 1;
-      const right = left + 1;
-      let smallest = i;
-      if (left < heap.length && heap[left].deadline < heap[smallest].deadline)
-        smallest = left;
-      if (right < heap.length && heap[right].deadline < heap[smallest].deadline)
-        smallest = right;
-      if (smallest === i)
+    let i = 0;
+    for (;; ) {
+      let child = 2 * i + 1;
+      if (child >= heap.length)
         break;
-      [heap[smallest], heap[i]] = [heap[i], heap[smallest]];
-      i = smallest;
+      if (child + 1 < heap.length && heap[child + 1].filed < heap[child].filed)
+        child++;
+      if (heap[child].filed >= last.filed)
+        break;
+      heap[i] = heap[child];
+      i = child;
     }
+    heap[i] = last;
     return top;
   }
   first() {
@@ -459,19 +532,35 @@ class Collection extends Map {
     }
     return;
   }
+  findLast(predicate) {
+    const keys = this.keyArray();
+    const values = this.array();
+    for (let i = values.length - 1;i >= 0; i--)
+      if (predicate(values[i], keys[i], this))
+        return values[i];
+    return;
+  }
+  findLastKey(predicate) {
+    const keys = this.keyArray();
+    const values = this.array();
+    for (let i = values.length - 1;i >= 0; i--)
+      if (predicate(values[i], keys[i], this))
+        return keys[i];
+    return;
+  }
   filter(predicate) {
-    const result = new Collection;
-    for (const [key, value] of this) {
+    const result = this.#derived();
+    this.forEach((value, key) => {
       if (predicate(value, key, this))
         result.set(key, value);
-    }
+    });
     return result;
   }
   map(transform) {
     const result = [];
-    for (const [key, value] of this) {
+    this.forEach((value, key) => {
       result.push(transform(value, key, this));
-    }
+    });
     return result;
   }
   some(predicate) {
@@ -489,9 +578,9 @@ class Collection extends Map {
     return true;
   }
   each(callback) {
-    for (const [key, value] of this) {
+    this.forEach((value, key) => {
       callback(value, key, this);
-    }
+    });
     return this;
   }
   array() {
@@ -504,9 +593,10 @@ class Collection extends Map {
     return [...this.entries()];
   }
   clone() {
-    const copy = new Collection;
-    for (const [key, value] of this)
+    const copy = this.#derived();
+    this.forEach((value, key) => {
       copy.set(key, value);
+    });
     return copy;
   }
   hasAll(...keys) {
@@ -559,7 +649,7 @@ class Collection extends Map {
     return result;
   }
   intersection(other) {
-    const result = new Collection;
+    const result = this.#derived();
     for (const [key, value] of this) {
       if (other.has(key))
         result.set(key, value);
@@ -567,7 +657,7 @@ class Collection extends Map {
     return result;
   }
   difference(other) {
-    const result = new Collection;
+    const result = this.#derived();
     for (const [key, value] of this) {
       if (!other.has(key))
         result.set(key, value);
@@ -575,8 +665,8 @@ class Collection extends Map {
     return result;
   }
   partition(predicate) {
-    const pass = new Collection;
-    const fail = new Collection;
+    const pass = this.#derived();
+    const fail = this.#derived();
     for (const [key, value] of this) {
       if (predicate(value, key, this))
         pass.set(key, value);
@@ -585,6 +675,81 @@ class Collection extends Map {
     }
     return [pass, fail];
   }
+  symmetricDifference(other) {
+    const result = this.#derived();
+    for (const [key, value] of this)
+      if (!other.has(key))
+        result.set(key, value);
+    for (const [key, value] of other)
+      if (!this.has(key))
+        result.set(key, value);
+    return result;
+  }
+  concat(...collections) {
+    const result = this.clone();
+    for (const collection of collections)
+      for (const [key, value] of collection)
+        result.set(key, value);
+    return result;
+  }
+  merge(other, whenInSelf, whenInOther, whenInBoth) {
+    const result = this.#derived();
+    const decide = (key, kept) => {
+      if (kept.keep)
+        result.set(key, kept.value);
+    };
+    for (const [key, value] of this) {
+      decide(key, other.has(key) ? whenInBoth(value, peekOf(other, key), key) : whenInSelf(value, key));
+    }
+    for (const [key, value] of other)
+      if (!this.has(key))
+        decide(key, whenInOther(value, key));
+    return result;
+  }
+  equals(other) {
+    if (!other)
+      return false;
+    if (other === this)
+      return true;
+    if (this.size !== other.size)
+      return false;
+    for (const [key, value] of this) {
+      if (!other.has(key))
+        return false;
+      if (value !== peekOf(other, key))
+        return false;
+    }
+    return true;
+  }
+  mapValues(transform) {
+    const result = this.#derived();
+    for (const [key, value] of this)
+      result.set(key, transform(value, key, this));
+    return result;
+  }
+  toReversed() {
+    const result = this.#derived();
+    const entries = [...this];
+    for (let i = entries.length - 1;i >= 0; i--)
+      result.set(entries[i][0], entries[i][1]);
+    return result;
+  }
+  toSorted(comparator) {
+    return this.sorted(comparator);
+  }
+  static groupBy(items, keySelector) {
+    const groups = new Collection;
+    let index = 0;
+    for (const item of items)
+      groups.ensure(keySelector(item, index++), () => []).push(item);
+    return groups;
+  }
+  static combineEntries(entries, combine) {
+    const result = new Collection;
+    for (const [key, value] of entries)
+      result.set(key, result.has(key) ? combine(result.get(key), value, key) : value);
+    return result;
+  }
   tap(fn) {
     fn(this);
     return this;
@@ -603,6 +768,13 @@ class Collection extends Map {
       acc = fn(acc, value, key, this);
     return acc;
   }
+  reduceRight(fn, initialValue) {
+    const entries = [...this];
+    let acc = initialValue;
+    for (let i = entries.length - 1;i >= 0; i--)
+      acc = fn(acc, entries[i][1], entries[i][0], this);
+    return acc;
+  }
   sorted(comparator) {
     const decorated = [...this.entries()].map((entry, index) => ({
       entry,
@@ -613,32 +785,52 @@ class Collection extends Map {
         const comparison = comparator(x.entry[1], y.entry[1], x.entry[0], y.entry[0]);
         return comparison !== 0 ? comparison : x.index - y.index;
       });
-    const result = new Collection;
+    const result = this.#derived();
     for (const { entry } of decorated)
       result.set(entry[0], entry[1]);
     return result;
   }
-  random() {
-    const arr = [...this.values()];
-    if (!arr.length)
+  random(amount) {
+    if (amount !== undefined)
+      return sample([...this.values()], amount);
+    const size = this.size;
+    if (size === 0)
       return;
-    return arr[Math.floor(Math.random() * arr.length)];
+    let index = Math.floor(Math.random() * size);
+    for (const value of this.values())
+      if (index-- === 0)
+        return value;
+    return;
   }
-  randomKey() {
-    const arr = [...this.keys()];
-    if (!arr.length)
+  randomKey(amount) {
+    if (amount !== undefined)
+      return sample([...this.keys()], amount);
+    const size = this.size;
+    if (size === 0)
       return;
-    return arr[Math.floor(Math.random() * arr.length)];
+    let index = Math.floor(Math.random() * size);
+    for (const key of this.keys())
+      if (index-- === 0)
+        return key;
+    return;
   }
   at(index) {
-    const arr = [...this.values()];
-    const i = index < 0 ? arr.length + index : index;
-    return arr[i];
+    let remaining = index < 0 ? this.size + index : index;
+    if (remaining < 0)
+      return;
+    for (const value of this.values())
+      if (remaining-- === 0)
+        return value;
+    return;
   }
   keyAt(index) {
-    const arr = [...this.keys()];
-    const i = index < 0 ? arr.length + index : index;
-    return arr[i];
+    let remaining = index < 0 ? this.size + index : index;
+    if (remaining < 0)
+      return;
+    for (const key of this.keys())
+      if (remaining-- === 0)
+        return key;
+    return;
   }
   toJSON() {
     return [...this.entries()];
@@ -649,4 +841,4 @@ export {
   Collection
 };
 
-//# debugId=4109A00736CB03B064756E2164756E21
+//# debugId=44902D8F098C340964756E2164756E21