lakutata 2.0.11 → 2.0.13

package/helper.d.ts

@@ -1,12 +1,12 @@
 /// <reference types="node" />
 import './vendor/TypeDef.2.js';
-import { PathLike, Dirent, Stats } from 'fs';
+import { PathLike } from 'fs';
 import { I as IConstructor } from './vendor/TypeDef.10.js';
-import { PathLike as PathLike$1 } from 'node:fs';
+import { PathLike as PathLike$1, Dirent, Stats } from 'node:fs';
 import { ReadableOptions, Readable } from 'node:stream';
-import { win32, posix } from 'path';
-import { EventEmitter } from 'events';
-import { StringDecoder } from 'string_decoder';
+import { win32, posix } from 'node:path';
+import { EventEmitter } from 'node:events';
+import { StringDecoder } from 'node:string_decoder';
 
 /**
  * Convert Array to Set
@@ -654,7 +654,7 @@ declare namespace Minipass {
     /**
      * Utility type to determine allowed options based on read type
      */
-    export type Options<T> = T extends string ? EncodingOptions | ObjectModeOptions : T extends Buffer ? BufferOptions | ObjectModeOptions : SharedOptions;
+    export type Options<T> = ObjectModeOptions | (T extends string ? EncodingOptions : T extends Buffer ? BufferOptions : SharedOptions);
     export {  };
 }
 /**
@@ -702,7 +702,7 @@ declare class Minipass<RType extends unknown = Buffer, WType extends unknown = R
      * {@link Minipass.SharedOptions.objectMode} or
      * {@link Minipass.SharedOptions.encoding}, as appropriate.
      */
-    constructor(...args: RType extends Buffer ? [] | [Minipass.Options<RType>] : [Minipass.Options<RType>]);
+    constructor(...args: [Minipass.ObjectModeOptions] | (RType extends Buffer ? [] | [Minipass.Options<RType>] : [Minipass.Options<RType>]));
     /**
      * The amount of data stored in the buffer waiting to be read.
      *
@@ -1037,8 +1037,18 @@ declare namespace LRUCache {
     /**
      * The reason why an item was removed from the cache, passed
      * to the {@link Disposer} methods.
+     *
+     * - `evict`: The item was evicted because it is the least recently used,
+     *   and the cache is full.
+     * - `set`: A new value was set, overwriting the old value being disposed.
+     * - `delete`: The item was explicitly deleted, either by calling
+     *   {@link LRUCache#delete}, {@link LRUCache#clear}, or
+     *   {@link LRUCache#set} with an undefined value.
+     * - `expire`: The item was removed due to exceeding its TTL.
+     * - `fetch`: A {@link OptionsBase#fetchMethod} operation returned
+     *   `undefined` or was aborted, causing the item to be deleted.
      */
-    type DisposeReason = 'evict' | 'set' | 'delete';
+    type DisposeReason = 'evict' | 'set' | 'delete' | 'expire' | 'fetch';
     /**
      * A method called upon item removal, passed as the
      * {@link OptionsBase.dispose} and/or
@@ -1064,8 +1074,14 @@ declare namespace LRUCache {
         context: FC;
     }
     /**
-     * Status object that may be passed to {@link LRUCache#fetch},
-     * {@link LRUCache#get}, {@link LRUCache#set}, and {@link LRUCache#has}.
+     * Occasionally, it may be useful to track the internal behavior of the
+     * cache, particularly for logging, debugging, or for behavior within the
+     * `fetchMethod`. To do this, you can pass a `status` object to the
+     * {@link LRUCache#fetch}, {@link LRUCache#get}, {@link LRUCache#set},
+     * {@link LRUCache#memo}, and {@link LRUCache#has} methods.
+     *
+     * The `status` option should be a plain JavaScript object. The following
+     * fields will be set on it appropriately, depending on the situation.
      */
     interface Status<V> {
         /**
@@ -1125,7 +1141,8 @@ declare namespace LRUCache {
          * various states.
          *
          * - inflight: there is another fetch() for this key which is in process
-         * - get: there is no fetchMethod, so {@link LRUCache#get} was called.
+         * - get: there is no {@link OptionsBase.fetchMethod}, so
+         *   {@link LRUCache#get} was called.
          * - miss: the item is not in cache, and will be fetched.
          * - hit: the item is in the cache, and was resolved immediately.
          * - stale: the item is in the cache, but stale.
@@ -1234,6 +1251,67 @@ declare namespace LRUCache {
     interface FetchOptionsNoContext<K, V> extends FetchOptions<K, V, undefined> {
         context?: undefined;
     }
+    interface MemoOptions<K, V, FC = unknown> extends Pick<OptionsBase<K, V, FC>, 'allowStale' | 'updateAgeOnGet' | 'noDeleteOnStaleGet' | 'sizeCalculation' | 'ttl' | 'noDisposeOnSet' | 'noUpdateTTL' | 'noDeleteOnFetchRejection' | 'allowStaleOnFetchRejection' | 'ignoreFetchAbort' | 'allowStaleOnFetchAbort'> {
+        /**
+         * Set to true to force a re-load of the existing data, even if it
+         * is not yet stale.
+         */
+        forceRefresh?: boolean;
+        /**
+         * Context provided to the {@link OptionsBase.memoMethod} as
+         * the {@link MemoizerOptions.context} param.
+         *
+         * If the FC type is specified as unknown (the default),
+         * undefined or void, then this is optional.  Otherwise, it will
+         * be required.
+         */
+        context?: FC;
+        status?: Status<V>;
+    }
+    /**
+     * Options provided to {@link LRUCache#memo} when the FC type is something
+     * other than `unknown`, `undefined`, or `void`
+     */
+    interface MemoOptionsWithContext<K, V, FC> extends MemoOptions<K, V, FC> {
+        context: FC;
+    }
+    /**
+     * Options provided to {@link LRUCache#memo} when the FC type is
+     * `undefined` or `void`
+     */
+    interface MemoOptionsNoContext<K, V> extends MemoOptions<K, V, undefined> {
+        context?: undefined;
+    }
+    /**
+     * Options provided to the
+     * {@link OptionsBase.memoMethod} function.
+     */
+    interface MemoizerOptions<K, V, FC = unknown> {
+        options: MemoizerMemoOptions<K, V, FC>;
+        /**
+         * Object provided in the {@link MemoOptions.context} option to
+         * {@link LRUCache#memo}
+         */
+        context: FC;
+    }
+    /**
+     * options which override the options set in the LRUCache constructor
+     * when calling {@link LRUCache#memo}.
+     *
+     * This is the union of {@link GetOptions} and {@link SetOptions}, plus
+     * {@link MemoOptions.forceRefresh}, and
+     * {@link MemoOptions.context}
+     *
+     * Any of these may be modified in the {@link OptionsBase.memoMethod}
+     * function, but the {@link GetOptions} fields will of course have no
+     * effect, as the {@link LRUCache#get} call already happened by the time
+     * the memoMethod is called.
+     */
+    interface MemoizerMemoOptions<K, V, FC = unknown> extends Pick<OptionsBase<K, V, FC>, 'allowStale' | 'updateAgeOnGet' | 'noDeleteOnStaleGet' | 'sizeCalculation' | 'ttl' | 'noDisposeOnSet' | 'noUpdateTTL'> {
+        status?: Status<V>;
+        size?: Size;
+        start?: Milliseconds;
+    }
     /**
      * Options that may be passed to the {@link LRUCache#has} method.
      */
@@ -1276,6 +1354,10 @@ declare namespace LRUCache {
      * The type signature for the {@link OptionsBase.fetchMethod} option.
      */
     type Fetcher<K, V, FC = unknown> = (key: K, staleValue: V | undefined, options: FetcherOptions<K, V, FC>) => Promise<V | undefined | void> | V | undefined | void;
+    /**
+     * the type signature for the {@link OptionsBase.memoMethod} option.
+     */
+    type Memoizer<K, V, FC = unknown> = (key: K, staleValue: V | undefined, options: MemoizerOptions<K, V, FC>) => V;
     /**
      * Options which may be passed to the {@link LRUCache} constructor.
      *
@@ -1290,6 +1372,14 @@ declare namespace LRUCache {
      * (and in fact required by the type definitions here) that the cache
      * also set {@link OptionsBase.ttlAutopurge}, to prevent potentially
      * unbounded storage.
+     *
+     * All options are also available on the {@link LRUCache} instance, making
+     * it safe to pass an LRUCache instance as the options argumemnt to
+     * make another empty cache of the same type.
+     *
+     * Some options are marked as read-only, because changing them after
+     * instantiation is not safe. Changing any of the other options will of
+     * course only have an effect on subsequent method calls.
      */
     interface OptionsBase<K, V, FC> {
         /**
@@ -1303,20 +1393,44 @@ declare namespace LRUCache {
          * Note that significantly fewer items may be stored, if
          * {@link OptionsBase.maxSize} and/or {@link OptionsBase.ttl} are also
          * set.
+         *
+         * **It is strongly recommended to set a `max` to prevent unbounded growth
+         * of the cache.**
          */
         max?: Count;
         /**
          * Max time in milliseconds for items to live in cache before they are
-         * considered stale.  Note that stale items are NOT preemptively removed
-         * by default, and MAY live in the cache long after they have expired.
+         * considered stale.  Note that stale items are NOT preemptively removed by
+         * default, and MAY live in the cache, contributing to its LRU max, long
+         * after they have expired, unless {@link OptionsBase.ttlAutopurge} is
+         * set.
+         *
+         * If set to `0` (the default value), then that means "do not track
+         * TTL", not "expire immediately".
          *
          * Also, as this cache is optimized for LRU/MRU operations, some of
          * the staleness/TTL checks will reduce performance, as they will incur
          * overhead by deleting items.
          *
-         * Must be an integer number of ms. If set to 0, this indicates "no TTL"
+         * This is not primarily a TTL cache, and does not make strong TTL
+         * guarantees. There is no pre-emptive pruning of expired items, but you
+         * _may_ set a TTL on the cache, and it will treat expired items as missing
+         * when they are fetched, and delete them.
+         *
+         * Optional, but must be a non-negative integer in ms if specified.
+         *
+         * This may be overridden by passing an options object to `cache.set()`.
+         *
+         * At least one of `max`, `maxSize`, or `TTL` is required. This must be a
+         * positive integer if set.
+         *
+         * Even if ttl tracking is enabled, **it is strongly recommended to set a
+         * `max` to prevent unbounded growth of the cache.**
          *
-         * @default 0
+         * If ttl tracking is enabled, and `max` and `maxSize` are not set,
+         * and `ttlAutopurge` is not set, then a warning will be emitted
+         * cautioning about the potential for unbounded memory consumption.
+         * (The TypeScript definitions will also discourage this.)
          */
         ttl?: Milliseconds;
         /**
@@ -1336,54 +1450,95 @@ declare namespace LRUCache {
         ttlResolution?: Milliseconds;
         /**
          * Preemptively remove stale items from the cache.
-         * Note that this may significantly degrade performance,
-         * especially if the cache is storing a large number of items.
-         * It is almost always best to just leave the stale items in
-         * the cache, and let them fall out as new items are added.
+         *
+         * Note that this may *significantly* degrade performance, especially if
+         * the cache is storing a large number of items. It is almost always best
+         * to just leave the stale items in the cache, and let them fall out as new
+         * items are added.
          *
          * Note that this means that {@link OptionsBase.allowStale} is a bit
          * pointless, as stale items will be deleted almost as soon as they
          * expire.
          *
-         * @default false
+         * Use with caution!
          */
         ttlAutopurge?: boolean;
         /**
-         * Update the age of items on {@link LRUCache#get}, renewing their TTL
+         * When using time-expiring entries with `ttl`, setting this to `true` will
+         * make each item's age reset to 0 whenever it is retrieved from cache with
+         * {@link LRUCache#get}, causing it to not expire. (It can still fall out
+         * of cache based on recency of use, of course.)
          *
          * Has no effect if {@link OptionsBase.ttl} is not set.
          *
-         * @default false
+         * This may be overridden by passing an options object to `cache.get()`.
          */
         updateAgeOnGet?: boolean;
         /**
-         * Update the age of items on {@link LRUCache#has}, renewing their TTL
+         * When using time-expiring entries with `ttl`, setting this to `true` will
+         * make each item's age reset to 0 whenever its presence in the cache is
+         * checked with {@link LRUCache#has}, causing it to not expire. (It can
+         * still fall out of cache based on recency of use, of course.)
          *
          * Has no effect if {@link OptionsBase.ttl} is not set.
-         *
-         * @default false
          */
         updateAgeOnHas?: boolean;
         /**
          * Allow {@link LRUCache#get} and {@link LRUCache#fetch} calls to return
          * stale data, if available.
+         *
+         * By default, if you set `ttl`, stale items will only be deleted from the
+         * cache when you `get(key)`. That is, it's not preemptively pruning items,
+         * unless {@link OptionsBase.ttlAutopurge} is set.
+         *
+         * If you set `allowStale:true`, it'll return the stale value *as well as*
+         * deleting it. If you don't set this, then it'll return `undefined` when
+         * you try to get a stale entry.
+         *
+         * Note that when a stale entry is fetched, _even if it is returned due to
+         * `allowStale` being set_, it is removed from the cache immediately. You
+         * can suppress this behavior by setting
+         * {@link OptionsBase.noDeleteOnStaleGet}, either in the constructor, or in
+         * the options provided to {@link LRUCache#get}.
+         *
+         * This may be overridden by passing an options object to `cache.get()`.
+         * The `cache.has()` method will always return `false` for stale items.
+         *
+         * Only relevant if a ttl is set.
          */
         allowStale?: boolean;
         /**
-         * Function that is called on items when they are dropped from the cache.
-         * This can be handy if you want to close file descriptors or do other
-         * cleanup tasks when items are no longer accessible. Called with `key,
-         * value`.  It's called before actually removing the item from the
-         * internal cache, so it is *NOT* safe to re-add them.
-         *
-         * Use {@link OptionsBase.disposeAfter} if you wish to dispose items after
-         * they have been full removed, when it is safe to add them back to the
-         * cache.
+         * Function that is called on items when they are dropped from the
+         * cache, as `dispose(value, key, reason)`.
+         *
+         * This can be handy if you want to close file descriptors or do
+         * other cleanup tasks when items are no longer stored in the cache.
+         *
+         * **NOTE**: It is called _before_ the item has been fully removed
+         * from the cache, so if you want to put it right back in, you need
+         * to wait until the next tick. If you try to add it back in during
+         * the `dispose()` function call, it will break things in subtle and
+         * weird ways.
+         *
+         * Unlike several other options, this may _not_ be overridden by
+         * passing an option to `set()`, for performance reasons.
+         *
+         * The `reason` will be one of the following strings, corresponding
+         * to the reason for the item's deletion:
+         *
+         * - `evict` Item was evicted to make space for a new addition
+         * - `set` Item was overwritten by a new value
+         * - `expire` Item expired its TTL
+         * - `fetch` Item was deleted due to a failed or aborted fetch, or a
+         *   fetchMethod returning `undefined.
+         * - `delete` Item was removed by explicit `cache.delete(key)`,
+         *   `cache.clear()`, or `cache.set(key, undefined)`.
          */
         dispose?: Disposer<K, V>;
         /**
          * The same as {@link OptionsBase.dispose}, but called *after* the entry
          * is completely removed and the cache is once again in a clean state.
+         *
          * It is safe to add an item right back into the cache at this point.
          * However, note that it is *very* easy to inadvertently create infinite
          * recursion this way.
@@ -1393,26 +1548,43 @@ declare namespace LRUCache {
          * Set to true to suppress calling the
          * {@link OptionsBase.dispose} function if the entry key is
          * still accessible within the cache.
+         *
          * This may be overridden by passing an options object to
          * {@link LRUCache#set}.
+         *
+         * Only relevant if `dispose` or `disposeAfter` are set.
          */
         noDisposeOnSet?: boolean;
         /**
-         * Boolean flag to tell the cache to not update the TTL when
-         * setting a new value for an existing key (ie, when updating a value
-         * rather than inserting a new value).  Note that the TTL value is
-         * _always_ set (if provided) when adding a new entry into the cache.
+         * Boolean flag to tell the cache to not update the TTL when setting a new
+         * value for an existing key (ie, when updating a value rather than
+         * inserting a new value).  Note that the TTL value is _always_ set (if
+         * provided) when adding a new entry into the cache.
          *
          * Has no effect if a {@link OptionsBase.ttl} is not set.
+         *
+         * May be passed as an option to {@link LRUCache#set}.
          */
         noUpdateTTL?: boolean;
         /**
-         * If you wish to track item size, you must provide a maxSize
-         * note that we still will only keep up to max *actual items*,
-         * if max is set, so size tracking may cause fewer than max items
-         * to be stored.  At the extreme, a single item of maxSize size
-         * will cause everything else in the cache to be dropped when it
-         * is added.  Use with caution!
+         * Set to a positive integer to track the sizes of items added to the
+         * cache, and automatically evict items in order to stay below this size.
+         * Note that this may result in fewer than `max` items being stored.
+         *
+         * Attempting to add an item to the cache whose calculated size is greater
+         * that this amount will be a no-op. The item will not be cached, and no
+         * other items will be evicted.
+         *
+         * Optional, must be a positive integer if provided.
+         *
+         * Sets `maxEntrySize` to the same value, unless a different value is
+         * provided for `maxEntrySize`.
+         *
+         * At least one of `max`, `maxSize`, or `TTL` is required. This must be a
+         * positive integer if set.
+         *
+         * Even if size tracking is enabled, **it is strongly recommended to set a
+         * `max` to prevent unbounded growth of the cache.**
          *
          * Note also that size tracking can negatively impact performance,
          * though for most cases, only minimally.
@@ -1422,13 +1594,22 @@ declare namespace LRUCache {
          * The maximum allowed size for any single item in the cache.
          *
          * If a larger item is passed to {@link LRUCache#set} or returned by a
-         * {@link OptionsBase.fetchMethod}, then it will not be stored in the
-         * cache.
+         * {@link OptionsBase.fetchMethod} or {@link OptionsBase.memoMethod}, then
+         * it will not be stored in the cache.
+         *
+         * Attempting to add an item whose calculated size is greater than
+         * this amount will not cache the item or evict any old items, but
+         * WILL delete an existing value if one is already present.
+         *
+         * Optional, must be a positive integer if provided. Defaults to
+         * the value of `maxSize` if provided.
          */
         maxEntrySize?: Size;
         /**
          * A function that returns a number indicating the item's size.
          *
+         * Requires {@link OptionsBase.maxSize} to be set.
+         *
          * If not provided, and {@link OptionsBase.maxSize} or
          * {@link OptionsBase.maxEntrySize} are set, then all
          * {@link LRUCache#set} calls **must** provide an explicit
@@ -1437,8 +1618,41 @@ declare namespace LRUCache {
         sizeCalculation?: SizeCalculator<K, V>;
         /**
          * Method that provides the implementation for {@link LRUCache#fetch}
+         *
+         * ```ts
+         * fetchMethod(key, staleValue, { signal, options, context })
+         * ```
+         *
+         * If `fetchMethod` is not provided, then `cache.fetch(key)` is equivalent
+         * to `Promise.resolve(cache.get(key))`.
+         *
+         * If at any time, `signal.aborted` is set to `true`, or if the
+         * `signal.onabort` method is called, or if it emits an `'abort'` event
+         * which you can listen to with `addEventListener`, then that means that
+         * the fetch should be abandoned. This may be passed along to async
+         * functions aware of AbortController/AbortSignal behavior.
+         *
+         * The `fetchMethod` should **only** return `undefined` or a Promise
+         * resolving to `undefined` if the AbortController signaled an `abort`
+         * event. In all other cases, it should return or resolve to a value
+         * suitable for adding to the cache.
+         *
+         * The `options` object is a union of the options that may be provided to
+         * `set()` and `get()`. If they are modified, then that will result in
+         * modifying the settings to `cache.set()` when the value is resolved, and
+         * in the case of
+         * {@link OptionsBase.noDeleteOnFetchRejection} and
+         * {@link OptionsBase.allowStaleOnFetchRejection}, the handling of
+         * `fetchMethod` failures.
+         *
+         * For example, a DNS cache may update the TTL based on the value returned
+         * from a remote DNS server by changing `options.ttl` in the `fetchMethod`.
          */
         fetchMethod?: Fetcher<K, V, FC>;
+        /**
+         * Method that provides the implementation for {@link LRUCache#memo}
+         */
+        memoMethod?: Memoizer<K, V, FC>;
         /**
          * Set to true to suppress the deletion of stale data when a
          * {@link OptionsBase.fetchMethod} returns a rejected promise.
@@ -1450,6 +1664,18 @@ declare namespace LRUCache {
          *
          * Note that the `get` return value will still be `undefined`
          * unless {@link OptionsBase.allowStale} is true.
+         *
+         * When using time-expiring entries with `ttl`, by default stale
+         * items will be removed from the cache when the key is accessed
+         * with `cache.get()`.
+         *
+         * Setting this option will cause stale items to remain in the cache, until
+         * they are explicitly deleted with `cache.delete(key)`, or retrieved with
+         * `noDeleteOnStaleGet` set to `false`.
+         *
+         * This may be overridden by passing an options object to `cache.get()`.
+         *
+         * Only relevant if a ttl is used.
          */
         noDeleteOnStaleGet?: boolean;
         /**
@@ -1458,14 +1684,24 @@ declare namespace LRUCache {
          * promise.
          *
          * This differs from using {@link OptionsBase.allowStale} in that stale
-         * data will ONLY be returned in the case that the
-         * {@link LRUCache#fetch} fails, not any other times.
+         * data will ONLY be returned in the case that the {@link LRUCache#fetch}
+         * fails, not any other times.
+         *
+         * If a `fetchMethod` fails, and there is no stale value available, the
+         * `fetch()` will resolve to `undefined`. Ie, all `fetchMethod` errors are
+         * suppressed.
+         *
+         * Implies `noDeleteOnFetchRejection`.
+         *
+         * This may be set in calls to `fetch()`, or defaulted on the constructor,
+         * or overridden by modifying the options object in the `fetchMethod`.
          */
         allowStaleOnFetchRejection?: boolean;
         /**
          * Set to true to return a stale value from the cache when the
-         * `AbortSignal` passed to the {@link OptionsBase.fetchMethod} dispatches an `'abort'`
-         * event, whether user-triggered, or due to internal cache behavior.
+         * `AbortSignal` passed to the {@link OptionsBase.fetchMethod} dispatches
+         * an `'abort'` event, whether user-triggered, or due to internal cache
+         * behavior.
          *
          * Unless {@link OptionsBase.ignoreFetchAbort} is also set, the underlying
          * {@link OptionsBase.fetchMethod} will still be considered canceled, and
@@ -1501,9 +1737,9 @@ declare namespace LRUCache {
          * object passed to {@link OptionsBase.fetchMethod}, and still cache the
          * resulting resolution value, as long as it is not `undefined`.
          *
-         * When used on its own, this means aborted {@link LRUCache#fetch} calls are not
-         * immediately resolved or rejected when they are aborted, and instead
-         * take the full time to await.
+         * When used on its own, this means aborted {@link LRUCache#fetch} calls
+         * are not immediately resolved or rejected when they are aborted, and
+         * instead take the full time to await.
          *
          * When used with {@link OptionsBase.allowStaleOnFetchAbort}, aborted
          * {@link LRUCache#fetch} calls will resolve immediately to their stale
@@ -1512,6 +1748,26 @@ declare namespace LRUCache {
          * not `undefined`, thus supporting a "return stale on timeout while
          * refreshing" mechanism by passing `AbortSignal.timeout(n)` as the signal.
          *
+         * For example:
+         *
+         * ```ts
+         * const c = new LRUCache({
+         *   ttl: 100,
+         *   ignoreFetchAbort: true,
+         *   allowStaleOnFetchAbort: true,
+         *   fetchMethod: async (key, oldValue, { signal }) => {
+         *     // note: do NOT pass the signal to fetch()!
+         *     // let's say this fetch can take a long time.
+         *     const res = await fetch(`https://slow-backend-server/${key}`)
+         *     return await res.json()
+         *   },
+         * })
+         *
+         * // this will return the stale value after 100ms, while still
+         * // updating in the background for next time.
+         * const val = await c.fetch('key', { signal: AbortSignal.timeout(100) })
+         * ```
+         *
          * **Note**: regardless of this setting, an `abort` event _is still
          * emitted on the `AbortSignal` object_, so may result in invalid results
          * when passed to other underlying APIs that use AbortSignals.
@@ -1549,13 +1805,19 @@ declare namespace LRUCache {
 /**
  * Default export, the thing you're using this module to get.
  *
- * All properties from the options object (with the exception of
- * {@link OptionsBase.max} and {@link OptionsBase.maxSize}) are added as
- * normal public members. (`max` and `maxBase` are read-only getters.)
- * Changing any of these will alter the defaults for subsequent method calls,
- * but is otherwise safe.
+ * The `K` and `V` types define the key and value types, respectively. The
+ * optional `FC` type defines the type of the `context` object passed to
+ * `cache.fetch()` and `cache.memo()`.
+ *
+ * Keys and values **must not** be `null` or `undefined`.
+ *
+ * All properties from the options object (with the exception of `max`,
+ * `maxSize`, `fetchMethod`, `memoMethod`, `dispose` and `disposeAfter`) are
+ * added as normal public members. (The listed options are read-only getters.)
+ *
+ * Changing any of these will alter the defaults for subsequent method calls.
  */
-declare class LRUCache<K extends {}, V extends {}, FC = unknown> implements Map<K, V> {
+declare class LRUCache<K extends {}, V extends {}, FC = unknown> {
     #private;
     /**
      * {@link LRUCache.OptionsBase.ttl}
@@ -1638,7 +1900,7 @@ declare class LRUCache<K extends {}, V extends {}, FC = unknown> implements Map<
         readonly head: Index;
         readonly tail: Index;
         free: StackLike;
-        isBackgroundFetch: (p: any) => boolean;
+        isBackgroundFetch: (p: any) => p is BackgroundFetch<V>;
         backgroundFetch: (k: K, index: number | undefined, options: LRUCache.FetchOptions<K, V, FC>, context: any) => BackgroundFetch<V>;
         moveToTail: (index: number) => void;
         indexes: (options?: {
@@ -1669,6 +1931,7 @@ declare class LRUCache<K extends {}, V extends {}, FC = unknown> implements Map<
      * {@link LRUCache.OptionsBase.fetchMethod} (read-only)
      */
     get fetchMethod(): LRUCache.Fetcher<K, V, FC> | undefined;
+    get memoMethod(): LRUCache.Memoizer<K, V, FC> | undefined;
     /**
      * {@link LRUCache.OptionsBase.dispose} (read-only)
      */
@@ -1679,7 +1942,8 @@ declare class LRUCache<K extends {}, V extends {}, FC = unknown> implements Map<
     get disposeAfter(): LRUCache.Disposer<K, V> | undefined;
     constructor(options: LRUCache.Options<K, V, FC> | LRUCache<K, V, FC>);
     /**
-     * Return the remaining TTL time for a given entry key
+     * Return the number of ms left in the item's TTL. If item is not in cache,
+     * returns `0`. Returns `Infinity` if item is in cache without a defined TTL.
      */
     getRemainingTTL(key: K): number;
     /**
@@ -1693,7 +1957,7 @@ declare class LRUCache<K extends {}, V extends {}, FC = unknown> implements Map<
      * Return a generator yielding `[key, value]` pairs,
      * in order from least recently used to most recently used.
      */
-    rentries(): Generator<(K | V | BackgroundFetch<V> | undefined)[], void, unknown>;
+    rentries(): Generator<(K | V)[], void, unknown>;
     /**
      * Return a generator yielding the keys in the cache,
      * in order from most recently used to least recently used.
@@ -1717,27 +1981,33 @@ declare class LRUCache<K extends {}, V extends {}, FC = unknown> implements Map<
      * Return a generator yielding the values in the cache,
      * in order from least recently used to most recently used.
      */
-    rvalues(): Generator<V | BackgroundFetch<V> | undefined, void, unknown>;
+    rvalues(): Generator<V | undefined, void, unknown>;
     /**
      * Iterating over the cache itself yields the same results as
      * {@link LRUCache.entries}
      */
     [Symbol.iterator](): Generator<[K, V], void, unknown>;
     /**
-     * A String value that is used in the creation of the default string description of an object.
-     * Called by the built-in method Object.prototype.toString.
+     * A String value that is used in the creation of the default string
+     * description of an object. Called by the built-in method
+     * `Object.prototype.toString`.
      */
     [Symbol.toStringTag]: string;
     /**
      * Find a value for which the supplied fn method returns a truthy value,
-     * similar to Array.find().  fn is called as fn(value, key, cache).
+     * similar to `Array.find()`. fn is called as `fn(value, key, cache)`.
      */
     find(fn: (v: V, k: K, self: LRUCache<K, V, FC>) => boolean, getOptions?: LRUCache.GetOptions<K, V, FC>): V | undefined;
     /**
-     * Call the supplied function on each item in the cache, in order from
-     * most recently used to least recently used.  fn is called as
-     * fn(value, key, cache).  Does not update age or recenty of use.
-     * Does not iterate over stale values.
+     * Call the supplied function on each item in the cache, in order from most
+     * recently used to least recently used.
+     *
+     * `fn` is called as `fn(value, key, cache)`.
+     *
+     * If `thisp` is provided, function will be called in the `this`-context of
+     * the provided object, or the cache if no `thisp` object is provided.
+     *
+     * Does not update age or recenty of use, or iterate over stale values.
      */
     forEach(fn: (v: V, k: K, self: LRUCache<K, V, FC>) => any, thisp?: any): void;
     /**
@@ -1752,20 +2022,39 @@ declare class LRUCache<K extends {}, V extends {}, FC = unknown> implements Map<
     purgeStale(): boolean;
     /**
      * Get the extended info about a given entry, to get its value, size, and
-     * TTL info simultaneously. Like {@link LRUCache#dump}, but just for a
-     * single key. Always returns stale values, if their info is found in the
-     * cache, so be sure to check for expired TTLs if relevant.
+     * TTL info simultaneously. Returns `undefined` if the key is not present.
+     *
+     * Unlike {@link LRUCache#dump}, which is designed to be portable and survive
+     * serialization, the `start` value is always the current timestamp, and the
+     * `ttl` is a calculated remaining time to live (negative if expired).
+     *
+     * Always returns stale values, if their info is found in the cache, so be
+     * sure to check for expirations (ie, a negative {@link LRUCache.Entry#ttl})
+     * if relevant.
      */
     info(key: K): LRUCache.Entry<V> | undefined;
     /**
      * Return an array of [key, {@link LRUCache.Entry}] tuples which can be
-     * passed to cache.load()
+     * passed to {@link LRUCache#load}.
+     *
+     * The `start` fields are calculated relative to a portable `Date.now()`
+     * timestamp, even if `performance.now()` is available.
+     *
+     * Stale entries are always included in the `dump`, even if
+     * {@link LRUCache.OptionsBase.allowStale} is false.
+     *
+     * Note: this returns an actual array, not a generator, so it can be more
+     * easily passed around.
      */
     dump(): [K, LRUCache.Entry<V>][];
     /**
      * Reset the cache and load in the items in entries in the order listed.
-     * Note that the shape of the resulting cache may be different if the
-     * same options are not used in both caches.
+     *
+     * The shape of the resulting cache may be different if the same options are
+     * not used in both caches.
+     *
+     * The `start` fields are assumed to be calculated relative to a portable
+     * `Date.now()` timestamp, even if `performance.now()` is available.
      */
     load(arr: [K, LRUCache.Entry<V>][]): void;
     /**
@@ -1773,6 +2062,30 @@ declare class LRUCache<K extends {}, V extends {}, FC = unknown> implements Map<
      *
      * Note: if `undefined` is specified as a value, this is an alias for
      * {@link LRUCache#delete}
+     *
+     * Fields on the {@link LRUCache.SetOptions} options param will override
+     * their corresponding values in the constructor options for the scope
+     * of this single `set()` operation.
+     *
+     * If `start` is provided, then that will set the effective start
+     * time for the TTL calculation. Note that this must be a previous
+     * value of `performance.now()` if supported, or a previous value of
+     * `Date.now()` if not.
+     *
+     * Options object may also include `size`, which will prevent
+     * calling the `sizeCalculation` function and just use the specified
+     * number if it is a positive integer, and `noDisposeOnSet` which
+     * will prevent calling a `dispose` function in the case of
+     * overwrites.
+     *
+     * If the `size` (or return value of `sizeCalculation`) for a given
+     * entry is greater than `maxEntrySize`, then the item will not be
+     * added to the cache.
+     *
+     * Will update the recency of the entry.
+     *
+     * If the value is `undefined`, then this is an alias for
+     * `cache.delete(key)`. `undefined` is never stored in the cache.
      */
     set(k: K, v: V | BackgroundFetch<V> | undefined, setOptions?: LRUCache.SetOptions<K, V, FC>): this;
     /**
@@ -1785,6 +2098,14 @@ declare class LRUCache<K extends {}, V extends {}, FC = unknown> implements Map<
      * Will return false if the item is stale, even though it is technically
      * in the cache.
      *
+     * Check if a key is in the cache, without updating the recency of
+     * use. Age is updated if {@link LRUCache.OptionsBase.updateAgeOnHas} is set
+     * to `true` in either the options or the constructor.
+     *
+     * Will return `false` if the item is stale, even though it is technically in
+     * the cache. The difference can be determined (if it matters) by using a
+     * `status` argument, and inspecting the `has` field.
+     *
      * Will not update item age unless
      * {@link LRUCache.OptionsBase.updateAgeOnHas} is set.
      */
@@ -1801,6 +2122,25 @@ declare class LRUCache<K extends {}, V extends {}, FC = unknown> implements Map<
      * Make an asynchronous cached fetch using the
      * {@link LRUCache.OptionsBase.fetchMethod} function.
      *
+     * If the value is in the cache and not stale, then the returned
+     * Promise resolves to the value.
+     *
+     * If not in the cache, or beyond its TTL staleness, then
+     * `fetchMethod(key, staleValue, { options, signal, context })` is
+     * called, and the value returned will be added to the cache once
+     * resolved.
+     *
+     * If called with `allowStale`, and an asynchronous fetch is
+     * currently in progress to reload a stale value, then the former
+     * stale value will be returned.
+     *
+     * If called with `forceRefresh`, then the cached item will be
+     * re-fetched, even if it is not stale. However, if `allowStale` is also
+     * set, then the old value will still be returned. This is useful
+     * in cases where you want to force a reload of a cached value. If
+     * a background fetch is already in progress, then `forceRefresh`
+     * has no effect.
+     *
      * If multiple fetches for the same key are issued, then they will all be
      * coalesced into a single call to fetchMethod.
      *
@@ -1813,9 +2153,89 @@ declare class LRUCache<K extends {}, V extends {}, FC = unknown> implements Map<
      * This is a known (fixable) shortcoming which will be addresed on when
      * someone complains about it, as the fix would involve added complexity and
      * may not be worth the costs for this edge case.
+     *
+     * If {@link LRUCache.OptionsBase.fetchMethod} is not specified, then this is
+     * effectively an alias for `Promise.resolve(cache.get(key))`.
+     *
+     * When the fetch method resolves to a value, if the fetch has not
+     * been aborted due to deletion, eviction, or being overwritten,
+     * then it is added to the cache using the options provided.
+     *
+     * If the key is evicted or deleted before the `fetchMethod`
+     * resolves, then the AbortSignal passed to the `fetchMethod` will
+     * receive an `abort` event, and the promise returned by `fetch()`
+     * will reject with the reason for the abort.
+     *
+     * If a `signal` is passed to the `fetch()` call, then aborting the
+     * signal will abort the fetch and cause the `fetch()` promise to
+     * reject with the reason provided.
+     *
+     * **Setting `context`**
+     *
+     * If an `FC` type is set to a type other than `unknown`, `void`, or
+     * `undefined` in the {@link LRUCache} constructor, then all
+     * calls to `cache.fetch()` _must_ provide a `context` option. If
+     * set to `undefined` or `void`, then calls to fetch _must not_
+     * provide a `context` option.
+     *
+     * The `context` param allows you to provide arbitrary data that
+     * might be relevant in the course of fetching the data. It is only
+     * relevant for the course of a single `fetch()` operation, and
+     * discarded afterwards.
+     *
+     * **Note: `fetch()` calls are inflight-unique**
+     *
+     * If you call `fetch()` multiple times with the same key value,
+     * then every call after the first will resolve on the same
+     * promise<sup>1</sup>,
+     * _even if they have different settings that would otherwise change
+     * the behavior of the fetch_, such as `noDeleteOnFetchRejection`
+     * or `ignoreFetchAbort`.
+     *
+     * In most cases, this is not a problem (in fact, only fetching
+     * something once is what you probably want, if you're caching in
+     * the first place). If you are changing the fetch() options
+     * dramatically between runs, there's a good chance that you might
+     * be trying to fit divergent semantics into a single object, and
+     * would be better off with multiple cache instances.
+     *
+     * **1**: Ie, they're not the "same Promise", but they resolve at
+     * the same time, because they're both waiting on the same
+     * underlying fetchMethod response.
      */
     fetch(k: K, fetchOptions: unknown extends FC ? LRUCache.FetchOptions<K, V, FC> : FC extends undefined | void ? LRUCache.FetchOptionsNoContext<K, V> : LRUCache.FetchOptionsWithContext<K, V, FC>): Promise<undefined | V>;
     fetch(k: unknown extends FC ? K : FC extends undefined | void ? K : never, fetchOptions?: unknown extends FC ? LRUCache.FetchOptions<K, V, FC> : FC extends undefined | void ? LRUCache.FetchOptionsNoContext<K, V> : never): Promise<undefined | V>;
+    /**
+     * In some cases, `cache.fetch()` may resolve to `undefined`, either because
+     * a {@link LRUCache.OptionsBase#fetchMethod} was not provided (turning
+     * `cache.fetch(k)` into just an async wrapper around `cache.get(k)`) or
+     * because `ignoreFetchAbort` was specified (either to the constructor or
+     * in the {@link LRUCache.FetchOptions}). Also, the
+     * {@link LRUCache.OptionsBase.fetchMethod} may return `undefined` or `void`, making
+     * the test even more complicated.
+     *
+     * Because inferring the cases where `undefined` might be returned are so
+     * cumbersome, but testing for `undefined` can also be annoying, this method
+     * can be used, which will reject if `this.fetch()` resolves to undefined.
+     */
+    forceFetch(k: K, fetchOptions: unknown extends FC ? LRUCache.FetchOptions<K, V, FC> : FC extends undefined | void ? LRUCache.FetchOptionsNoContext<K, V> : LRUCache.FetchOptionsWithContext<K, V, FC>): Promise<V>;
+    forceFetch(k: unknown extends FC ? K : FC extends undefined | void ? K : never, fetchOptions?: unknown extends FC ? LRUCache.FetchOptions<K, V, FC> : FC extends undefined | void ? LRUCache.FetchOptionsNoContext<K, V> : never): Promise<V>;
+    /**
+     * If the key is found in the cache, then this is equivalent to
+     * {@link LRUCache#get}. If not, in the cache, then calculate the value using
+     * the {@link LRUCache.OptionsBase.memoMethod}, and add it to the cache.
+     *
+     * If an `FC` type is set to a type other than `unknown`, `void`, or
+     * `undefined` in the LRUCache constructor, then all calls to `cache.memo()`
+     * _must_ provide a `context` option. If set to `undefined` or `void`, then
+     * calls to memo _must not_ provide a `context` option.
+     *
+     * The `context` param allows you to provide arbitrary data that might be
+     * relevant in the course of fetching the data. It is only relevant for the
+     * course of a single `memo()` operation, and discarded afterwards.
+     */
+    memo(k: K, memoOptions: unknown extends FC ? LRUCache.MemoOptions<K, V, FC> : FC extends undefined | void ? LRUCache.MemoOptionsNoContext<K, V> : LRUCache.MemoOptionsWithContext<K, V, FC>): V;
+    memo(k: unknown extends FC ? K : FC extends undefined | void ? K : never, memoOptions?: unknown extends FC ? LRUCache.MemoOptions<K, V, FC> : FC extends undefined | void ? LRUCache.MemoOptionsNoContext<K, V> : never): V;
     /**
      * Return a value from the cache. Will update the recency of the cache
      * entry found.
@@ -1825,6 +2245,7 @@ declare class LRUCache<K extends {}, V extends {}, FC = unknown> implements Map<
     get(k: K, getOptions?: LRUCache.GetOptions<K, V, FC>): V | undefined;
     /**
      * Deletes a key out of the cache.
+     *
      * Returns true if the key was deleted, false otherwise.
      */
     delete(k: K): boolean;
@@ -1973,6 +2394,11 @@ declare abstract class PathBase implements Dirent {
      * @internal
      */
     nocase: boolean;
+    /**
+     * boolean indicating that this path is the current working directory
+     * of the PathScurry collection that contains it.
+     */
+    isCWD: boolean;
     /**
      * the string or regexp used to split paths. On posix, it is `'/'`, and on
      * windows it is a RegExp matching either `'/'` or `'\\'`
@@ -2002,10 +2428,16 @@ declare abstract class PathBase implements Dirent {
     get birthtime(): Date | undefined;
     /**
      * This property is for compatibility with the Dirent class as of
-     * Node v20, where Dirent['path'] refers to the path of the directory
-     * that was passed to readdir.  So, somewhat counterintuitively, this
-     * property refers to the *parent* path, not the path object itself.
-     * For root entries, it's the path to the entry itself.
+     * Node v20, where Dirent['parentPath'] refers to the path of the
+     * directory that was passed to readdir. For root entries, it's the path
+     * to the entry itself.
+     */
+    get parentPath(): string;
+    /**
+     * Deprecated alias for Dirent['parentPath'] Somewhat counterintuitively,
+     * this property refers to the *parent* path, not the path object itself.
+     *
+     * @deprecated
      */
     get path(): string;
     /**
@@ -2435,7 +2867,7 @@ declare abstract class PathScurryBase {
      *
      * @internal
      */
-    constructor(cwd: string | URL | undefined, pathImpl: typeof win32 | typeof posix, sep: string | RegExp, { nocase, childrenCacheSize, fs, }?: PathScurryOpts);
+    constructor(cwd: (URL | string) | undefined, pathImpl: typeof win32 | typeof posix, sep: string | RegExp, { nocase, childrenCacheSize, fs, }?: PathScurryOpts);
     /**
      * Get the depth of a provided path, string, or the cwd
      */
@@ -2929,6 +3361,7 @@ type PathScurry = PathScurryBase | InstanceType<typeof PathScurry>;
 interface IgnoreLike {
     ignored?: (p: Path) => boolean;
     childrenIgnored?: (p: Path) => boolean;
+    add?: (ignore: string) => void;
 }
 
 /**
@@ -2999,7 +3432,7 @@ interface GlobOptions {
      */
     follow?: boolean;
     /**
-     * string or string[], or an object with `ignore` and `ignoreChildren`
+     * string or string[], or an object with `ignored` and `childrenIgnored`
      * methods.
      *
      * If a string or string[] is provided, then this is treated as a glob
@@ -3172,6 +3605,50 @@ interface GlobOptions {
      * `'//?/C:/foo/bar'`
      */
     posix?: boolean;
+    /**
+     * Do not match any children of any matches. For example, the pattern
+     * `**\/foo` would match `a/foo`, but not `a/foo/b/foo` in this mode.
+     *
+     * This is especially useful for cases like "find all `node_modules`
+     * folders, but not the ones in `node_modules`".
+     *
+     * In order to support this, the `Ignore` implementation must support an
+     * `add(pattern: string)` method. If using the default `Ignore` class, then
+     * this is fine, but if this is set to `false`, and a custom `Ignore` is
+     * provided that does not have an `add()` method, then it will throw an
+     * error.
+     *
+     * **Caveat** It *only* ignores matches that would be a descendant of a
+     * previous match, and only if that descendant is matched *after* the
+     * ancestor is encountered. Since the file system walk happens in
+     * indeterminate order, it's possible that a match will already be added
+     * before its ancestor, if multiple or braced patterns are used.
+     *
+     * For example:
+     *
+     * ```ts
+     * const results = await glob([
+     *   // likely to match first, since it's just a stat
+     *   'a/b/c/d/e/f',
+     *
+     *   // this pattern is more complicated! It must to various readdir()
+     *   // calls and test the results against a regular expression, and that
+     *   // is certainly going to take a little bit longer.
+     *   //
+     *   // So, later on, it encounters a match at 'a/b/c/d/e', but it's too
+     *   // late to ignore a/b/c/d/e/f, because it's already been emitted.
+     *   'a/[bdf]/?/[a-z]/*',
+     * ], { includeChildMatches: false })
+     * ```
+     *
+     * It's best to only set this to `false` if you can be reasonably sure that
+     * no components of the pattern will potentially match one another's file
+     * system descendants, or if the occasional included child entry will not
+     * cause problems.
+     *
+     * @default true
+     */
+    includeChildMatches?: boolean;
 }
 type GlobOptionsWithFileTypesTrue = GlobOptions & {
     withFileTypes: true;