lunibee 0.2.3 → 0.3.0

package/dist/collection/cache.d.ts

@@ -4,21 +4,30 @@ export interface CacheOptions {
     maxSize?: number;
     /** Time-to-live in milliseconds. Omit to disable expiration. */
     ttl?: number;
-    /** Sweep interval in milliseconds. */
+    /** Fraction (0-1) of `ttl` randomly shaved off each entry's lifetime. Default `0`. */
+    jitter?: number;
+    /**
+     * Accepted for compatibility and still validated. Expired entries are now
+     * dropped at their deadline, so no periodic sweep is needed.
+     */
     sweepInterval?: number;
 }
-/** Bounded cache with TTL expiration and explicit invalidation support. */
+/**
+ * Bounded cache with a fixed TTL, least-recently-used eviction and explicit
+ * invalidation. A thin policy layer over {@link Collection}: reads promote an
+ * entry but do not extend its TTL.
+ */
 export declare class Cache<K, V> {
     #private;
     /** Creates a cache using the supplied retention policy. */
     constructor(options?: CacheOptions);
     /** Number of currently live entries. */
     get size(): number;
-    /** Reads a live entry. */
+    /** Reads a live entry and marks it most recently used. */
     get(key: K): V | undefined;
     /** Returns whether a live entry exists. */
     has(key: K): boolean;
-    /** Stores an entry and evicts the oldest entries when the bound is exceeded. */
+    /** Stores an entry and evicts the least recently used ones when the bound is exceeded. */
     set(key: K, value: V): this;
     /** Invalidates one key. */
     delete(key: K): boolean;
@@ -26,9 +35,9 @@ export declare class Cache<K, V> {
     clear(): void;
     /** Invalidates every entry matching a predicate. */
     invalidate(predicate: (value: V, key: K) => boolean): number;
-    /** Removes expired entries and returns the number removed. */
+    /** Removes expired entries now and returns the number removed. */
     sweep(): number;
-    /** Stops the background sweeper and releases its timer. */
+    /** Kept for compatibility: there is no background sweeper to stop. */
     dispose(): void;
     /** Returns live cached values. */
     values(): V[];

package/dist/collection/index.d.ts

@@ -2,8 +2,12 @@
 export interface CollectionOptions<K = unknown, V = unknown> {
     /** Default sliding TTL in ms for `set()`. Omit for no expiry. */
     ttl?: number;
+    /** Fraction (0-1) of each entry's TTL randomly shaved off when it is set, so entries stored together do not expire together. Default `0`. */
+    jitter?: number;
     /** Maximum entries stored with `set()`; least-recently-used are evicted past it. `setWithoutTTL()` entries are never counted or evicted. */
     maxSize?: number;
+    /** Whether a read restarts a TTL entry's window. Default `true`; with `false` an entry lapses a fixed time after it was set, and reads only mark it recently used. */
+    slide?: boolean;
     /** Called after an entry is removed automatically, with why. Exceptions are swallowed. */
     onEvict?: (key: K, value: V, reason: EvictionReason) => void;
 }
@@ -11,11 +15,27 @@ export interface CollectionOptions<K = unknown, V = unknown> {
 export type EvictionReason = "expired" | "evicted";
 /** Cumulative counters from {@link Collection.stats}. */
 export interface CollectionStats {
-    /** `get`/`peek` calls that found a value. */ hits: number;
-    /** `get`/`peek` calls that found nothing. */ misses: number;
-    /** Entries removed because their TTL lapsed. */ expired: number;
-    /** Entries removed to stay within `maxSize`. */ evicted: number;
+    /** `get`/`peek` calls that found a value. */
+    hits: number;
+    /** `get`/`peek` calls that found nothing. */
+    misses: number;
+    /** Entries removed because their TTL lapsed. */
+    expired: number;
+    /** Entries removed to stay within `maxSize`. */
+    evicted: number;
 }
+/** What `merge()` does with one entry: keep it with `value`, or drop it. */
+export type Keep<V> = {
+    keep: true;
+    value: V;
+} | {
+    keep: false;
+};
+/**
+ * A `Collection` seen read-only: every method that does not change it. Pass it
+ * where you only read, so a function cannot add to or remove from the cache.
+ */
+export type ReadonlyCollection<K, V> = Omit<Collection<K, V>, "set" | "setWithoutTTL" | "delete" | "clear" | "ensure" | "forEach" | "get" | "sweep" | "purge"> & ReadonlyMap<K, V>;
 /**
  * A keyed collection for Lunibee resource and application state.
  *
@@ -50,6 +70,14 @@ export declare class Collection<K, V> extends Map<K, V> {
     setWithoutTTL(key: K, value: V): this;
     /** Reads a value; restarts a TTL entry's window and promotes it. */
     get(key: K): V | undefined;
+    /**
+     * Returns the value for `key`, or stores and returns what `factory`
+     * makes. Reading counts as a `get()` (restarts the TTL, marks it recently
+     * used); creating stores with `set()`, so `ttl` applies.
+     * @param factory Called with the key and this collection only when the key is missing; if it throws, nothing is stored.
+     * @param ttl TTL in ms for a created entry; defaults to the collection's.
+     */
+    ensure(key: K, factory: (key: K, collection: this) => V, ttl?: number): V;
     /** Reads a value without restarting its TTL or promoting it. */
     peek(key: K): V | undefined;
     /** Cumulative hit, miss, expiry and eviction counters (a copy). */
@@ -77,8 +105,12 @@ export declare class Collection<K, V> extends Map<K, V> {
     lastKey(): K | undefined;
     /** Finds the first value matching a predicate. */
     find(predicate: (value: V, key: K, collection: this) => boolean): V | undefined;
+    /** Finds the last value (in insertion order) matching a predicate. */
+    findLast(predicate: (value: V, key: K, collection: this) => boolean): V | undefined;
+    /** Finds the key of the last entry (in insertion order) matching a predicate. */
+    findLastKey(predicate: (value: V, key: K, collection: this) => boolean): K | undefined;
     /** Returns all values matching a predicate. */
-    filter(predicate: (value: V, key: K, collection: this) => boolean): Collection<K, V>;
+    filter(predicate: (value: V, key: K, collection: this) => boolean): this;
     /** Transforms every stored value into an array. */
     map<T>(transform: (value: V, key: K, collection: this) => T): T[];
     /** Returns whether at least one stored value satisfies a predicate. */
@@ -94,7 +126,7 @@ export declare class Collection<K, V> extends Map<K, V> {
     /** Returns a plain array of entries. */
     entriesArray(): [K, V][];
     /** Returns a new collection with the same entries. */
-    clone(): Collection<K, V>;
+    clone(): this;
     /** Returns whether all supplied keys are present. */
     hasAll(...keys: K[]): boolean;
     /** Returns whether at least one supplied key is present. */
@@ -110,15 +142,46 @@ export declare class Collection<K, V> extends Map<K, V> {
     /** Returns the collection's last matching entry as a tuple. */
     lastEntry(): [K, V] | undefined;
     /** Returns a new Collection containing elements from both collections. */
-    union(other: Collection<K, V>): Collection<K, V>;
+    union(other: ReadonlyCollection<K, V>): this;
     /** Returns a new Collection containing only elements present in both collections. */
-    intersection(other: Collection<K, V>): Collection<K, V>;
+    intersection(other: ReadonlyCollection<K, V>): this;
     /** Returns a new Collection containing elements present in this collection but not the other. */
-    difference(other: Collection<K, V>): Collection<K, V>;
+    difference(other: ReadonlyCollection<K, V>): this;
     /** Splits the collection into two collections based on a predicate.
      * @returns `[passing, failing]` — entries satisfying the predicate, then those that don't.
      */
-    partition(predicate: (value: V, key: K, collection: this) => boolean): [Collection<K, V>, Collection<K, V>];
+    partition(predicate: (value: V, key: K, collection: this) => boolean): [this, this];
+    /** Returns the entries of both collections that are in only one of them. */
+    symmetricDifference(other: ReadonlyCollection<K, V>): this;
+    /** Returns a new Collection with this one's entries followed by each of `collections`'; a later collection wins a shared key. */
+    concat(...collections: ReadonlyCollection<K, V>[]): this;
+    /**
+     * Combines this collection with `other`, deciding per key what to keep.
+     * @param whenInSelf Called for a key only in this collection.
+     * @param whenInOther Called for a key only in `other`.
+     * @param whenInBoth Called for a key in both.
+     * @returns A new collection of the entries the callbacks kept, in this collection's order, then `other`'s new keys.
+     */
+    merge<T, R>(other: ReadonlyCollection<K, T>, whenInSelf: (value: V, key: K) => Keep<R>, whenInOther: (valueOther: T, key: K) => Keep<R>, whenInBoth: (value: V, valueOther: T, key: K) => Keep<R>): Collection<K, R>;
+    /** Returns whether `other` holds the same keys with `===` equal values. Neither side's TTL or recency is touched. */
+    equals(other: ReadonlyCollection<K, V> | null | undefined): boolean;
+    /** Returns a new collection with the same keys and each value passed through `transform`. */
+    mapValues<T>(transform: (value: V, key: K, collection: this) => T): Collection<K, T>;
+    /** Returns a new collection with the entries in reverse order. */
+    toReversed(): this;
+    /** Same as {@link sorted}, under the name the standard `Array` uses. */
+    toSorted(comparator?: (a: V, b: V, aKey: K, bKey: K) => number): this;
+    /**
+     * Groups `items` by the key `keySelector` returns for each.
+     * @param keySelector Called with each item and its index.
+     * @returns A new collection from each key to its items, in input order.
+     */
+    static groupBy<K, V>(items: Iterable<V>, keySelector: (item: V, index: number) => K): Collection<K, V[]>;
+    /**
+     * Builds a collection from `entries`, merging values that share a key.
+     * @param combine Called with the value stored so far, the new one and the key; its result is stored.
+     */
+    static combineEntries<K, V>(entries: Iterable<readonly [K, V]>, combine: (firstValue: V, secondValue: V, key: K) => V): Collection<K, V>;
     /** Calls `fn` with this collection and returns the collection unchanged.
      * Useful for inserting debug side-effects in a chain without breaking the flow.
      */
@@ -127,18 +190,30 @@ export declare class Collection<K, V> extends Map<K, V> {
     flatMap<T>(transform: (value: V, key: K, collection: this) => T[]): T[];
     /** Reduces the collection to a single value. */
     reduce<T>(fn: (accumulator: T, value: V, key: K, collection: this) => T, initialValue: T): T;
+    /** Like {@link reduce}, but from the last entry to the first. */
+    reduceRight<T>(fn: (accumulator: T, value: V, key: K, collection: this) => T, initialValue: T): T;
     /** Returns a new Collection with entries sorted by comparator (non-mutating).
      * Defaults to insertion order if no comparator is provided.
      */
-    sorted(comparator?: (a: V, b: V, aKey: K, bKey: K) => number): Collection<K, V>;
-    /** Returns a random value from the collection, or `undefined` if empty.
-     * Uses `Math.random()` (fast, non-cryptographic) — do not use for security-sensitive
-     * selection such as tokens or secrets. */
+    sorted(comparator?: (a: V, b: V, aKey: K, bKey: K) => number): this;
+    /**
+     * Returns a random value, or `undefined` if empty. With `amount`, returns
+     * that many different values (all of them, shuffled, when `amount` is at
+     * least the size).
+     * Uses `Math.random()` (fast, non-cryptographic): do not use it for
+     * security-sensitive selection such as tokens or secrets.
+     * @param amount How many values to pick.
+     * @throws {RangeError} If `amount` is not a non-negative integer.
+     */
     random(): V | undefined;
-    /** Returns a random key from the collection, or `undefined` if empty.
-     * Uses `Math.random()` (fast, non-cryptographic) — do not use for security-sensitive
-     * selection such as tokens or secrets. */
+    random(amount: number): V[];
+    /**
+     * Returns a random key, or `undefined` if empty. With `amount`, returns
+     * that many different keys. Same randomness and errors as {@link random}.
+     * @param amount How many keys to pick.
+     */
     randomKey(): K | undefined;
+    randomKey(amount: number): K[];
     /** Returns the value at a given insertion-order index (supports negative indices). */
     at(index: number): V | undefined;
     /** Returns the key at a given insertion-order index (supports negative indices). */