keyv 6.0.0-alpha.2 → 6.0.0-beta.1

package/dist/index.d.cts

@@ -1,386 +1,1351 @@
-type EventListener = (...arguments_: any[]) => void;
-declare class EventManager {
-    _eventListeners: Map<string, EventListener[]>;
-    _maxListeners: number;
-    constructor();
-    maxListeners(): number;
-    addListener(event: string, listener: EventListener): void;
-    on(event: string, listener: EventListener): this;
-    removeListener(event: string, listener: EventListener): void;
-    off(event: string, listener: EventListener): void;
-    once(event: string, listener: EventListener): void;
-    emit(event: string, ...arguments_: any[]): void;
-    listeners(event: string): EventListener[];
-    removeAllListeners(event?: string): void;
-    setMaxListeners(n: number): void;
-}
-
-type HookHandler = (...arguments_: any[]) => void;
-declare class HooksManager extends EventManager {
-    _hookHandlers: Map<string, HookHandler[]>;
-    constructor();
-    addHandler(event: string, handler: HookHandler): void;
-    removeHandler(event: string, handler: HookHandler): void;
-    trigger(event: string, data: any): void;
-    get handlers(): Map<string, HookHandler[]>;
-}
+import { Hookified, IEventEmitter } from "hookified";
 
-declare class StatsManager extends EventManager {
-    enabled: boolean;
-    hits: number;
-    misses: number;
-    sets: number;
-    deletes: number;
-    errors: number;
-    constructor(enabled?: boolean);
-    hit(): void;
-    miss(): void;
-    set(): void;
-    delete(): void;
-    hitsOrMisses<T>(array: Array<T | undefined>): void;
-    reset(): void;
+//#region src/capabilities.d.ts
+type MethodType = "sync" | "async" | "none";
+type KeyvStorageMethod = {
+  exists: boolean;
+  methodType: MethodType;
+};
+declare const keyvMethodNames: readonly ["get", "set", "delete", "clear", "has", "getMany", "setMany", "deleteMany", "hasMany", "disconnect", "getRaw", "getManyRaw", "setRaw", "setManyRaw", "iterator"];
+declare const keyvPropertyNames: readonly ["hooks", "stats"];
+type KeyvMethods = Record<(typeof keyvMethodNames)[number], KeyvStorageMethod>;
+type KeyvProperties = Record<(typeof keyvPropertyNames)[number], boolean>;
+type KeyvCapability = {
+  compatible: boolean;
+  methods: KeyvMethods;
+  properties: KeyvProperties;
+};
+declare const keyvStorageMethodNames: readonly ["get", "getMany", "has", "hasMany", "set", "setMany", "delete", "deleteMany", "clear", "disconnect", "iterator"];
+type KeyvStorageMethods = Record<(typeof keyvStorageMethodNames)[number], KeyvStorageMethod>;
+type KeyvStorageCapability = {
+  compatible: boolean;
+  store: "mapLike" | "keyvStorage" | "asyncMap" | "none";
+  methods: KeyvStorageMethods;
+};
+declare const keyvCompressionMethodNames: readonly ["compress", "decompress"];
+type KeyvCompressionMethods = Record<(typeof keyvCompressionMethodNames)[number], KeyvStorageMethod>;
+type KeyvCompressionCapability = {
+  compatible: boolean;
+  methods: KeyvCompressionMethods;
+};
+declare const keyvSerializationMethodNames: readonly ["stringify", "parse"];
+type KeyvSerializationMethods = Record<(typeof keyvSerializationMethodNames)[number], KeyvStorageMethod>;
+type KeyvSerializationCapability = {
+  compatible: boolean;
+  methods: KeyvSerializationMethods;
+};
+declare const keyvEncryptionMethodNames: readonly ["encrypt", "decrypt"];
+type KeyvEncryptionMethods = Record<(typeof keyvEncryptionMethodNames)[number], KeyvStorageMethod>;
+type KeyvEncryptionCapability = {
+  compatible: boolean;
+  methods: KeyvEncryptionMethods;
+};
+/**
+ * Detect whether an object implements the full Keyv interface
+ * @param obj - The object to check
+ * @returns A {@link KeyvCapability} where `compatible` is `true` only when all required capabilities are present
+ * @example
+ * ```typescript
+ * import Keyv, { detectKeyv } from 'keyv';
+ *
+ * const result = detectKeyv(new Keyv());
+ * result.compatible;              // true — all capabilities present
+ * result.methods.get.exists;      // true
+ * result.methods.get.methodType;  // "async"
+ *
+ * const partial = detectKeyv(new Map());
+ * partial.compatible;             // false — missing getMany, setMany, hooks, stats, etc.
+ * partial.methods.get.exists;     // true
+ * ```
+ */
+declare function detectKeyv(obj: unknown): KeyvCapability;
+/**
+ * Detect whether an object implements the Keyv storage adapter interface
+ * @param obj - The object to check
+ * @returns A {@link KeyvStorageCapability} where:
+ * - `compatible` is `true` when the object is a valid storage adapter (`"keyvStorage"`, `"mapLike"`, or `"asyncMap"`)
+ * - `store` indicates the detected store type: `"keyvStorage"`, `"mapLike"`, `"asyncMap"`, or `"none"`
+ * - `methods` maps each method name to `{ exists, methodType }`
+ * @example
+ * ```typescript
+ * import { detectKeyvStorage } from 'keyv';
+ *
+ * const map = detectKeyvStorage(new Map());
+ * map.compatible;               // true
+ * map.store;                    // "mapLike"
+ * map.methods.get.exists;       // true
+ * map.methods.get.methodType;   // "sync"
+ *
+ * const adapter = detectKeyvStorage(asyncAdapter);
+ * adapter.compatible;               // true
+ * adapter.store;                    // "keyvStorage"
+ * adapter.methods.get.methodType;   // "async"
+ * ```
+ */
+declare function detectKeyvStorage(obj: unknown): KeyvStorageCapability;
+/**
+ * Detect whether an object implements the Keyv compression adapter interface
+ * @param obj - The object to check
+ * @returns A {@link KeyvCompressionCapability} where `compatible` is `true` when both `compress` and `decompress` methods are present
+ * @example
+ * ```typescript
+ * import { detectKeyvCompression } from 'keyv';
+ *
+ * detectKeyvCompression({ compress: (d) => d, decompress: (d) => d });
+ * // { compatible: true, methods: { compress: { exists: true, methodType: "sync" }, decompress: { exists: true, methodType: "sync" } } }
+ * ```
+ */
+declare function detectKeyvCompression(obj: unknown): KeyvCompressionCapability;
+/**
+ * Detect whether an object implements the Keyv serialization adapter interface
+ * @param obj - The object to check
+ * @returns A {@link KeyvSerializationCapability} where `compatible` is `true` when both `stringify` and `parse` methods are present
+ * @example
+ * ```typescript
+ * import { detectKeyvSerialization } from 'keyv';
+ *
+ * detectKeyvSerialization(JSON);
+ * // { compatible: true, methods: { stringify: { exists: true, methodType: "sync" }, parse: { exists: true, methodType: "sync" } } }
+ * ```
+ */
+declare function detectKeyvSerialization(obj: unknown): KeyvSerializationCapability;
+/**
+ * Detect whether an object implements the Keyv encryption adapter interface
+ * @param obj - The object to check
+ * @returns A {@link KeyvEncryptionCapability} where `compatible` is `true` when both `encrypt` and `decrypt` methods are present
+ * @example
+ * ```typescript
+ * import { detectKeyvEncryption } from 'keyv';
+ *
+ * detectKeyvEncryption({ encrypt: (d) => d, decrypt: (d) => d });
+ * // { compatible: true, methods: { encrypt: { exists: true, methodType: "sync" }, decrypt: { exists: true, methodType: "sync" } } }
+ * ```
+ */
+declare function detectKeyvEncryption(obj: unknown): KeyvEncryptionCapability;
+//#endregion
+//#region src/sanitize.d.ts
+/**
+ * Which dangerous-pattern categories to detect and strip.
+ * Each defaults to `true` when the parent scope is enabled.
+ */
+type KeyvSanitizePatterns = {
+  /**
+   * Detect and strip SQL injection patterns: semicolons (`;`), SQL comments (`--` and `/*`).
+   * @default false
+   */
+  sql: boolean;
+  /**
+   * Detect and strip MongoDB operator patterns: leading `$`, `{$` sequences.
+   * @default false
+   */
+  mongo: boolean;
+  /**
+   * Detect and strip dangerous control sequences: null bytes (`\0`), carriage returns (`\r`), newlines (`\n`).
+   * @default false
+   */
+  escape: boolean;
+  /**
+   * Detect and strip path traversal patterns: `../` and `..\\` sequences.
+   * @default false
+   */
+  path: boolean;
+};
+/**
+ * Options for configuring sanitization pattern categories.
+ * All categories default to `true` when the parent scope is enabled.
+ */
+type KeyvSanitizePatternsOptions = {
+  /**
+   * Detect and strip SQL injection patterns: semicolons (`;`), SQL comments (`--` and `/*`).
+   * @default true
+   */
+  sql?: boolean;
+  /**
+   * Detect and strip MongoDB operator patterns: leading `$`, `{$` sequences.
+   * @default true
+   */
+  mongo?: boolean;
+  /**
+   * Detect and strip dangerous control sequences: null bytes (`\0`), carriage returns (`\r`), newlines (`\n`).
+   * @default true
+   */
+  escape?: boolean;
+  /**
+   * Detect and strip path traversal patterns: `../` and `..\\` sequences.
+   * @default true
+   */
+  path?: boolean;
+};
+/**
+ * Controls what gets sanitized and with which patterns.
+ */
+type KeyvSanitizeOptions = {
+  /**
+   * Sanitize keys. Pass `true` for all pattern categories, `false` to skip,
+   * or a `KeyvSanitizePatternOptions` object for granular control.
+   * @default false
+   */
+  keys?: boolean | KeyvSanitizePatternsOptions;
+  /**
+   * Sanitize namespace strings. Pass `true` for all pattern categories, `false` to skip,
+   * or a `KeyvSanitizePatternOptions` object for granular control.
+   * @default false
+   */
+  namespace?: boolean | KeyvSanitizePatternsOptions;
+};
+/**
+ * Adapter interface for key and namespace sanitization.
+ * Implement this to provide custom sanitization logic to Keyv.
+ */
+type KeyvSanitizeAdapter = {
+  /** Whether any sanitization is currently enabled. */readonly enabled: boolean; /** The key sanitization pattern configuration. */
+  readonly keys: KeyvSanitizePatterns; /** The namespace sanitization pattern configuration. */
+  readonly namespace: KeyvSanitizePatterns; /** Sanitize a single key. */
+  cleanKey(key: string): string; /** Sanitize an array of keys. */
+  cleanKeys(keys: string[]): string[]; /** Sanitize a namespace string. */
+  cleanNamespace(ns: string): string;
+};
+/**
+ * Encapsulates key and namespace sanitization with an LRU result cache.
+ */
+declare class KeyvSanitize implements KeyvSanitizeAdapter {
+  private _keys;
+  private _namespace;
+  private _keyPatterns;
+  private _namespacePatterns;
+  private _enabled;
+  private _cacheKeys;
+  private _cacheNamespaces;
+  private _cacheMax;
+  constructor(options?: KeyvSanitizeOptions);
+  /**
+   * The key sanitization pattern configuration.
+   */
+  get keys(): KeyvSanitizePatterns;
+  /**
+   * Whether any sanitization pattern (keys or namespace) is enabled.
+   */
+  get enabled(): boolean;
+  /**
+   * The namespace sanitization pattern configuration.
+   */
+  get namespace(): KeyvSanitizePatterns;
+  /**
+   * Update the sanitization configuration. Recompiles patterns and clears the cache.
+   */
+  updateOptions(options: KeyvSanitizeOptions): void;
+  /**
+   * Sanitize a single key. Uses an LRU cache for repeated lookups.
+   */
+  cleanKey(key: string): string;
+  /**
+   * Sanitize an array of keys.
+   */
+  cleanKeys(keys: string[]): string[];
+  /**
+   * Sanitize a namespace string. Uses an LRU cache for repeated lookups.
+   */
+  cleanNamespace(ns: string): string;
+  /**
+   * Clear the LRU caches.
+   */
+  clearCache(): void;
+  private resolvePatterns;
 }
-
-type DeserializedData<Value> = {
-    value?: Value;
-    expires?: number | undefined;
+//#endregion
+//#region src/stats.d.ts
+/**
+ * Structure of a telemetry event emitted by Keyv.
+ */
+type KeyvTelemetryEvent = {
+  /** The event type (e.g. "hit", "miss", "set", "delete", "error"). */event: string; /** The cache key involved, if applicable. */
+  key?: string; /** The namespace of the Keyv instance. */
+  namespace?: string; /** Unix timestamp in milliseconds when the event occurred. */
+  timestamp: number;
+};
+type KeyvStatsOptions = {
+  /**
+   * Enable or disable stats tracking.
+   * @default false
+   */
+  enabled?: boolean;
+  /**
+   * Maximum number of entries per event-type LRU map.
+   * @default 1000
+   */
+  maxEntries?: number;
+  /**
+   * The event emitter (e.g. a Keyv instance) to subscribe to for telemetry events.
+   * If provided, KeyvStats will automatically subscribe on construction.
+   */
+  emitter?: IEventEmitter;
 };
-type CompressionAdapter = {
-    compress(value: any, options?: any): Promise<any>;
-    decompress(value: any, options?: any): Promise<any>;
-    serialize<Value>(data: DeserializedData<Value>): Promise<string> | string;
-    deserialize<Value>(data: string): Promise<DeserializedData<Value> | undefined> | DeserializedData<Value> | undefined;
+declare class KeyvStats {
+  private _hits;
+  private _misses;
+  private _sets;
+  private _deletes;
+  private _errors;
+  private _maxEntries;
+  private _enabled;
+  private readonly hitKeysMap;
+  private readonly missKeysMap;
+  private readonly setKeysMap;
+  private readonly deleteKeysMap;
+  private readonly errorKeysMap;
+  private _emitter?;
+  private readonly _listeners;
+  constructor(options?: KeyvStatsOptions);
+  /**
+   * Total number of cache hits.
+   */
+  get hits(): number;
+  /**
+   * Total number of cache misses.
+   */
+  get misses(): number;
+  /**
+   * Total number of cache sets.
+   */
+  get sets(): number;
+  /**
+   * Total number of cache deletes.
+   */
+  get deletes(): number;
+  /**
+   * Total number of cache errors.
+   */
+  get errors(): number;
+  /**
+   * LRU-bounded map of key to hit count.
+   */
+  get hitKeys(): Map<string, number>;
+  /**
+   * LRU-bounded map of key to miss count.
+   */
+  get missKeys(): Map<string, number>;
+  /**
+   * LRU-bounded map of key to set count.
+   */
+  get setKeys(): Map<string, number>;
+  /**
+   * LRU-bounded map of key to delete count.
+   */
+  get deleteKeys(): Map<string, number>;
+  /**
+   * LRU-bounded map of key to error count.
+   */
+  get errorKeys(): Map<string, number>;
+  /**
+   * Maximum number of entries per event-type LRU map.
+   * @default 1000
+   */
+  get maxEntries(): number;
+  /**
+   * Set the maximum number of entries per event-type LRU map.
+   * @param {number} value the new maximum entries
+   */
+  set maxEntries(value: number);
+  /**
+   * Whether stats tracking is enabled.
+   * @default false
+   */
+  get enabled(): boolean;
+  /**
+   * Enable or disable stats tracking. If false it will unsubscribe from the events
+   * @param {boolean} value true to enable, false to disable
+   */
+  set enabled(value: boolean);
+  /**
+   * Build a composite key from a telemetry event.
+   * Format: "namespace:key" if namespace is present, otherwise just "key".
+   */
+  buildKeyEventName(event: KeyvTelemetryEvent): string;
+  /**
+   * Increment the count for a key in an LRU-bounded map.
+   * Deletes and re-inserts to maintain LRU order, evicts the oldest entry when full.
+   */
+  incrementKeys(map: Map<string, number>, compositeKey: string): void;
+  /**
+   * Subscribe to telemetry events from an emitter (e.g. a Keyv instance).
+   * Automatically increments the corresponding stat counters and LRU key maps on each event.
+   * @param {IEventEmitter} emitter the event emitter to subscribe to
+   */
+  subscribe(emitter: IEventEmitter): void;
+  /**
+   * Unsubscribe from the currently subscribed emitter, removing all telemetry event listeners.
+   */
+  unsubscribe(): void;
+  /**
+   * Reset all counters and LRU key maps to their initial state.
+   */
+  reset(): void;
+}
+//#endregion
+//#region src/types/keyv.d.ts
+/**
+ * A Map or any Map-like object. Used as a flexible input type for stores.
+ */
+type KeyvMapAny = Map<any, any> | any;
+/**
+ * The envelope structure used to store values in Keyv.
+ * Wraps the actual value with an optional expiration timestamp.
+ */
+type KeyvValue<Value> = {
+  /** The stored value. */value?: Value; /** Absolute expiration timestamp in milliseconds since epoch, or `undefined` for no expiry. */
+  expires?: number | undefined;
 };
-type Serialize = <Value>(data: DeserializedData<Value>) => Promise<string> | string;
-type Deserialize = <Value>(data: string) => Promise<DeserializedData<Value> | undefined> | DeserializedData<Value> | undefined;
+/** @deprecated Use `KeyvValue` instead. */
+type DeserializedData<Value> = KeyvValue<Value>;
+/**
+ * Events emitted by Keyv for error handling and telemetry.
+ */
+declare enum KeyvEvents {
+  /** Emitted when an error occurs in a store operation. */
+  ERROR = "error",
+  /** Emitted for informational messages. */
+  INFO = "info",
+  /** Emitted for warning messages. */
+  WARN = "warn",
+  /** Telemetry: cache hit. */
+  STAT_HIT = "stat:hit",
+  /** Telemetry: cache miss. */
+  STAT_MISS = "stat:miss",
+  /** Telemetry: value set. */
+  STAT_SET = "stat:set",
+  /** Telemetry: value deleted. */
+  STAT_DELETE = "stat:delete",
+  /** Telemetry: operation error. */
+  STAT_ERROR = "stat:error"
+}
+/**
+ * Hook names for intercepting Keyv operations.
+ * Register hooks via `keyv.on(KeyvHooks.BEFORE_SET, callback)` to run logic before/after operations.
+ */
 declare enum KeyvHooks {
-    PRE_SET = "preSet",
-    POST_SET = "postSet",
-    PRE_GET = "preGet",
-    POST_GET = "postGet",
-    PRE_GET_MANY = "preGetMany",
-    POST_GET_MANY = "postGetMany",
-    PRE_GET_RAW = "preGetRaw",
-    POST_GET_RAW = "postGetRaw",
-    PRE_GET_MANY_RAW = "preGetManyRaw",
-    POST_GET_MANY_RAW = "postGetManyRaw",
-    PRE_DELETE = "preDelete",
-    POST_DELETE = "postDelete"
+  /** @deprecated Use BEFORE_SET instead */
+  PRE_SET = "preSet",
+  /** @deprecated Use AFTER_SET instead */
+  POST_SET = "postSet",
+  /** @deprecated Use BEFORE_GET instead */
+  PRE_GET = "preGet",
+  /** @deprecated Use AFTER_GET instead */
+  POST_GET = "postGet",
+  /** @deprecated Use BEFORE_GET_MANY instead */
+  PRE_GET_MANY = "preGetMany",
+  /** @deprecated Use AFTER_GET_MANY instead */
+  POST_GET_MANY = "postGetMany",
+  /** @deprecated Use BEFORE_GET_RAW instead */
+  PRE_GET_RAW = "preGetRaw",
+  /** @deprecated Use AFTER_GET_RAW instead */
+  POST_GET_RAW = "postGetRaw",
+  /** @deprecated Use BEFORE_GET_MANY_RAW instead */
+  PRE_GET_MANY_RAW = "preGetManyRaw",
+  /** @deprecated Use AFTER_GET_MANY_RAW instead */
+  POST_GET_MANY_RAW = "postGetManyRaw",
+  /** @deprecated Use BEFORE_SET_RAW instead */
+  PRE_SET_RAW = "preSetRaw",
+  /** @deprecated Use AFTER_SET_RAW instead */
+  POST_SET_RAW = "postSetRaw",
+  /** @deprecated Use BEFORE_SET_MANY_RAW instead */
+  PRE_SET_MANY_RAW = "preSetManyRaw",
+  /** @deprecated Use AFTER_SET_MANY_RAW instead */
+  POST_SET_MANY_RAW = "postSetManyRaw",
+  /** @deprecated Use BEFORE_SET_MANY instead */
+  PRE_SET_MANY = "preSetMany",
+  /** @deprecated Use AFTER_SET_MANY instead */
+  POST_SET_MANY = "postSetMany",
+  /** @deprecated Use BEFORE_DELETE instead */
+  PRE_DELETE = "preDelete",
+  /** @deprecated Use AFTER_DELETE instead */
+  POST_DELETE = "postDelete",
+  /** @deprecated Use BEFORE_DELETE_MANY instead */
+  PRE_DELETE_MANY = "preDeleteMany",
+  /** @deprecated Use AFTER_DELETE_MANY instead */
+  POST_DELETE_MANY = "postDeleteMany",
+  BEFORE_SET = "before:set",
+  AFTER_SET = "after:set",
+  BEFORE_GET = "before:get",
+  AFTER_GET = "after:get",
+  BEFORE_GET_MANY = "before:getMany",
+  AFTER_GET_MANY = "after:getMany",
+  BEFORE_GET_RAW = "before:getRaw",
+  AFTER_GET_RAW = "after:getRaw",
+  BEFORE_GET_MANY_RAW = "before:getManyRaw",
+  AFTER_GET_MANY_RAW = "after:getManyRaw",
+  BEFORE_SET_RAW = "before:setRaw",
+  AFTER_SET_RAW = "after:setRaw",
+  BEFORE_SET_MANY = "before:setMany",
+  AFTER_SET_MANY = "after:setMany",
+  BEFORE_SET_MANY_RAW = "before:setManyRaw",
+  AFTER_SET_MANY_RAW = "after:setManyRaw",
+  BEFORE_DELETE = "before:delete",
+  AFTER_DELETE = "after:delete",
+  BEFORE_DELETE_MANY = "before:deleteMany",
+  AFTER_DELETE_MANY = "after:deleteMany",
+  BEFORE_HAS = "before:has",
+  AFTER_HAS = "after:has",
+  BEFORE_HAS_MANY = "before:hasMany",
+  AFTER_HAS_MANY = "after:hasMany",
+  BEFORE_CLEAR = "before:clear",
+  AFTER_CLEAR = "after:clear",
+  BEFORE_DISCONNECT = "before:disconnect",
+  AFTER_DISCONNECT = "after:disconnect"
 }
-type KeyvEntry = {
-    /**
-     * Key to set.
-     */
-    key: string;
-    /**
-     * Value to set.
-     */
-    value: any;
-    /**
-     * Time to live in milliseconds.
-     */
-    ttl?: number;
+/**
+ * Represents a key-value entry with an optional TTL, used for batch operations like `setMany`.
+ */
+type KeyvEntry<Value = any> = {
+  /**
+   * Key to set.
+   */
+  key: string;
+  /**
+   * Value to set.
+   */
+  value: Value;
+  /**
+   * Time to live in milliseconds.
+   */
+  ttl?: number;
+};
+/**
+ * Configuration options for the Keyv constructor.
+ */
+type KeyvOptions = {
+  /**
+   * Namespace for the current instance.
+   * @default undefined
+   */
+  namespace?: string;
+  /**
+   * A custom serialization adapter with stringify and parse methods.
+   * @default KeyvJsonSerializer (built-in)
+   */
+  serialization?: KeyvSerializationAdapter | false;
+  /**
+   * The storage adapter instance to be used by Keyv.
+   * @default new Map() - in-memory store
+   */
+  store?: KeyvStorageAdapter | Map<any, any> | any;
+  /**
+   * Default TTL in milliseconds. Can be overridden by specifying a TTL on `.set()`.
+   * @default undefined
+   */
+  ttl?: number;
+  /**
+   * Enable compression option
+   * @default undefined
+   */
+  compression?: KeyvCompressionAdapter | any;
+  /**
+   * Enable or disable statistics (default is false)
+   * @default false
+   */
+  stats?: boolean;
+  /**
+   * Will throw on all errors if this is enabled to true. By default, errors
+   * will only throw if there are no listeners to the error event.
+   * This maps to hookified's `throwOnEmitError` under the hood.
+   * @default false
+   */
+  throwOnErrors?: boolean;
+  /**
+   * Enable sanitization of keys and namespaces by detecting dangerous patterns
+   * for SQL, MongoDB, or filesystem-based storage backends. Pass a `KeyvSanitizeOptions`
+   * object for granular control over targets and patterns.
+   * @default undefined
+   */
+  sanitize?: KeyvSanitizeOptions;
+  /**
+   * Enable encryption of stored values. Pass a `KeyvEncryptionAdapter` with
+   * `encrypt` and `decrypt` methods.
+   * @default undefined
+   */
+  encryption?: KeyvEncryptionAdapter;
+  /**
+   * When true, Keyv checks expiry on get/getMany/has/hasMany at its layer.
+   * When false (default), trusts the storage adapter to handle expiry.
+   * @default false
+   */
+  checkExpired?: boolean;
+};
+//#endregion
+//#region src/types/adapters.d.ts
+/**
+ * Adapter interface for custom serialization.
+ * Implement `stringify` and `parse` to control how values are serialized to/from strings.
+ */
+type KeyvSerializationAdapter = {
+  /** Converts a value to a string representation. */stringify: (object: unknown) => string | Promise<string>; /** Parses a string back into its original value. */
+  parse: <T>(data: string) => T | Promise<T>;
 };
-type StoredDataNoRaw<Value> = Value | undefined;
-type StoredDataRaw<Value> = DeserializedData<Value> | undefined;
-type StoredData<Value> = StoredDataNoRaw<Value> | StoredDataRaw<Value>;
-type IEventEmitter = {
-    on(event: string, listener: (...arguments_: any[]) => void): IEventEmitter;
+/**
+ * Adapter interface for compression.
+ * Implement `compress` and `decompress` to add compression to stored values.
+ */
+type KeyvCompressionAdapter = {
+  /** Compresses a string value. */compress(value: string): Promise<string>; /** Decompresses a string value back to its original form. */
+  decompress(value: string): Promise<string>;
 };
-type KeyvStoreAdapter = {
-    opts: any;
-    namespace?: string | undefined;
-    get<Value>(key: string): Promise<StoredData<Value> | undefined>;
-    set(key: string, value: any, ttl?: number): any;
-    setMany?(values: Array<{
-        key: string;
-        value: any;
-        ttl?: number;
-    }>): Promise<void>;
-    delete(key: string): Promise<boolean>;
-    clear(): Promise<void>;
-    has?(key: string): Promise<boolean>;
-    hasMany?(keys: string[]): Promise<boolean[]>;
-    getMany?<Value>(keys: string[]): Promise<Array<StoredData<Value | undefined>>>;
-    disconnect?(): Promise<void>;
-    deleteMany?(key: string[]): Promise<boolean>;
-    iterator?<Value>(namespace?: string): AsyncGenerator<Array<string | Awaited<Value> | undefined>, void>;
+/**
+ * Adapter interface for encryption.
+ * Implement `encrypt` and `decrypt` to add encryption to stored values.
+ */
+type KeyvEncryptionAdapter = {
+  /** Encrypts a string value. */encrypt: (data: string) => string | Promise<string>; /** Decrypts a string value back to its original form. */
+  decrypt: (data: string) => string | Promise<string>;
+};
+type KeyvStorageGetResult<Value> = KeyvValue<Value> | string | undefined;
+/**
+ * Interface that all Keyv storage adapters must implement.
+ * Adapters handle the actual persistence of key-value pairs.
+ */
+type KeyvStorageAdapter = {
+  /** Optional namespace for key isolation. */namespace?: string | undefined; /** Detected capabilities of the underlying store. */
+  capabilities?: KeyvStorageCapability; /** Retrieves a value by key. */
+  get<Value>(key: string): Promise<KeyvStorageGetResult<Value>>; /** Stores a value with a key and optional TTL in milliseconds. */
+  set(key: string, value: unknown, ttl?: number): Promise<boolean>; /** Stores multiple entries at once. */
+  setMany<Value>(values: KeyvEntry<Value>[]): Promise<boolean[] | undefined>; /** Deletes a key from the store. */
+  delete(key: string): Promise<boolean>; /** Clears all entries from the store (respects namespace if set). */
+  clear(): Promise<void>; /** Checks if a key exists in the store. */
+  has(key: string): Promise<boolean>; /** Checks if multiple keys exist in the store. */
+  hasMany(keys: string[]): Promise<boolean[]>; /** Retrieves multiple values by keys. */
+  getMany<Value>(keys: string[]): Promise<Array<KeyvStorageGetResult<Value | undefined>>>; /** Disconnects from the store and releases resources. */
+  disconnect?(): Promise<void>; /** Deletes multiple keys from the store. */
+  deleteMany(key: string[]): Promise<boolean[]>; /** Returns an async iterator over all key-value pairs. */
+  iterator?<Value>(): AsyncGenerator<Array<string | Awaited<Value> | undefined>, void>;
 } & IEventEmitter;
-type KeyvOptions = {
-    /**
-     * Emit errors
-     * @default true
-     */
-    emitErrors?: boolean;
-    /**
-     * Namespace for the current instance.
-     * @default 'keyv'
-     */
-    namespace?: string;
-    /**
-     * A custom serialization function.
-     * @default defaultSerialize using JSON.stringify
-     */
-    serialize?: Serialize;
-    /**
-     * A custom deserialization function.
-     * @default defaultDeserialize using JSON.parse
-     */
-    deserialize?: Deserialize;
-    /**
-     * The storage adapter instance to be used by Keyv.
-     * @default new Map() - in-memory store
-     */
-    store?: KeyvStoreAdapter | Map<any, any> | any;
-    /**
-     * Default TTL in milliseconds. Can be overridden by specifying a TTL on `.set()`.
-     * @default undefined
-     */
-    ttl?: number;
-    /**
-     * Enable compression option
-     * @default false
-     */
-    compression?: CompressionAdapter | any;
-    /**
-     * Enable or disable statistics (default is false)
-     * @default false
-     */
-    stats?: boolean;
-    /**
-     * Enable or disable key prefixing (default is true)
-     * @default true
-     */
-    useKeyPrefix?: boolean;
-    /**
-     * Will enable throwing errors on methods in addition to emitting them.
-     * @default false
-     */
-    throwOnErrors?: boolean;
+/**
+ * @deprecated Use `KeyvStorageAdapter` instead.
+ */
+type KeyvStoreAdapter = KeyvStorageAdapter;
+/**
+ * @deprecated Use `KeyvCompressionAdapter` instead.
+ */
+type KeyvCompression = KeyvCompressionAdapter;
+//#endregion
+//#region src/adapters/bridge.d.ts
+/**
+ * Configuration options for KeyvBridgeAdapter.
+ */
+type KeyvBridgeAdapterOptions = {
+  /**
+   * The namespace to use for keys.
+   * When set, all keys will be prefixed with the namespace followed by the key separator.
+   */
+  namespace?: string;
+  /**
+   * The separator used between namespace and key. Defaults to ":".
+   */
+  keySeparator?: string;
+};
+/**
+ * Interface for a promise-based store that can be used with KeyvBridgeAdapter.
+ * The store must implement get, set, delete, and clear as async operations.
+ * Optional methods (has, hasMany, getMany, setMany, deleteMany, iterator, disconnect)
+ * will be delegated to the store if present, otherwise fallback implementations are used.
+ */
+type KeyvBridgeStore = {
+  /** Store configuration/options (e.g. dialect, url) */opts?: any; /** Retrieves a value by key */
+  get(key: string): Promise<any>; /** Sets a value with a key and optional TTL */
+  set(key: string, value: any, ttl?: number): Promise<any>; /** Deletes a key from the store */
+  delete(key: string): Promise<boolean>; /** Clears all entries from the store */
+  clear(): Promise<void>; /** Checks if a key exists in the store */
+  has?(key: string): Promise<boolean>; /** Checks if multiple keys exist in the store */
+  hasMany?(keys: string[]): Promise<boolean[]>; /** Retrieves multiple values by keys */
+  getMany?(keys: string[]): Promise<any[]>; /** Sets multiple entries at once */
+  setMany?(entries: any[]): Promise<any>; /** Deletes multiple keys at once */
+  deleteMany?(keys: string[]): Promise<boolean | boolean[]>; /** Iterates over all entries, optionally filtered by namespace */
+  iterator?(namespace?: string): AsyncGenerator<any>; /** Disconnects from the store */
+  disconnect?(): Promise<void>; /** Subscribe to events (e.g. error events from v5 adapters) */
+  on?(event: string, listener: (...args: any[]) => void): any;
+};
+/**
+ * Data structure returned when parsing a prefixed key.
+ */
+type KeyPrefixData = {
+  /** The namespace extracted from the key, if present */namespace?: string; /** The key without the namespace prefix */
+  key: string;
 };
-type IteratorFunction = (argument: any) => AsyncGenerator<any, void>;
-declare class Keyv<GenericValue = any> extends EventManager {
-    iterator?: IteratorFunction;
-    hooks: HooksManager;
-    stats: StatsManager;
-    /**
-     * Time to live in milliseconds
-     */
-    private _ttl?;
-    /**
-     * Namespace
-     */
-    private _namespace?;
-    /**
-     * Store
-     */
-    private _store;
-    private _serialize;
-    private _deserialize;
-    private _compression;
-    private _useKeyPrefix;
-    private _throwOnErrors;
-    private _emitErrors;
-    /**
-     * Keyv Constructor
-     * @param {KeyvStoreAdapter | KeyvOptions | Map<any, any>} store  to be provided or just the options
-     * @param {Omit<KeyvOptions, 'store'>} [options] if you provide the store you can then provide the Keyv Options
-     */
-    constructor(store?: KeyvStoreAdapter | KeyvOptions | Map<any, any>, options?: Omit<KeyvOptions, "store">);
-    /**
-     * Keyv Constructor
-     * @param {KeyvOptions} options to be provided
-     */
-    constructor(options?: KeyvOptions);
-    /**
-     * Get the current store
-     */
-    get store(): KeyvStoreAdapter | Map<any, any> | any;
-    /**
-     * Set the current store. This will also set the namespace, event error handler, and generate the iterator. If the store is not valid it will throw an error.
-     * @param {KeyvStoreAdapter | Map<any, any> | any} store the store to set
-     */
-    set store(store: KeyvStoreAdapter | Map<any, any> | any);
-    /**
-     * Get the current compression function
-     * @returns {CompressionAdapter} The current compression function
-     */
-    get compression(): CompressionAdapter | undefined;
-    /**
-     * Set the current compression function
-     * @param {CompressionAdapter} compress The compression function to set
-     */
-    set compression(compress: CompressionAdapter | undefined);
-    /**
-     * Get the current namespace.
-     * @returns {string | undefined} The current namespace.
-     */
-    get namespace(): string | undefined;
-    /**
-     * Set the current namespace.
-     * @param {string | undefined} namespace The namespace to set.
-     */
-    set namespace(namespace: string | undefined);
-    /**
-     * Get the current TTL.
-     * @returns {number} The current TTL in milliseconds.
-     */
-    get ttl(): number | undefined;
-    /**
-     * Set the current TTL.
-     * @param {number} ttl The TTL to set in milliseconds.
-     */
-    set ttl(ttl: number | undefined);
-    /**
-     * Get the current serialize function.
-     * @returns {Serialize} The current serialize function.
-     */
-    get serialize(): Serialize | undefined;
-    /**
-     * Set the current serialize function.
-     * @param {Serialize} serialize The serialize function to set.
-     */
-    set serialize(serialize: Serialize | undefined);
-    /**
-     * Get the current deserialize function.
-     * @returns {Deserialize} The current deserialize function.
-     */
-    get deserialize(): Deserialize | undefined;
-    /**
-     * Set the current deserialize function.
-     * @param {Deserialize} deserialize The deserialize function to set.
-     */
-    set deserialize(deserialize: Deserialize | undefined);
-    /**
-     * Get the current useKeyPrefix value. This will enable or disable key prefixing.
-     * @returns {boolean} The current useKeyPrefix value.
-     * @default true
-     */
-    get useKeyPrefix(): boolean;
-    /**
-     * Set the current useKeyPrefix value. This will enable or disable key prefixing.
-     * @param {boolean} value The useKeyPrefix value to set.
-     */
-    set useKeyPrefix(value: boolean);
-    /**
-     * Get the current throwErrors value. This will enable or disable throwing errors on methods in addition to emitting them.
-     * @return {boolean} The current throwOnErrors value.
-     */
-    get throwOnErrors(): boolean;
-    /**
-     * Set the current throwOnErrors value. This will enable or disable throwing errors on methods in addition to emitting them.
-     * @param {boolean} value The throwOnErrors value to set.
-     */
-    set throwOnErrors(value: boolean);
-    /**
-     * Get the current emitErrors value. This will enable or disable emitting errors on methods.
-     * @return {boolean} The current emitErrors value.
-     * @default true
-     */
-    get emitErrors(): boolean;
-    /**
-     * Set the current emitErrors value. This will enable or disable emitting errors on methods.
-     * @param {boolean} value The emitErrors value to set.
-     */
-    set emitErrors(value: boolean);
-    generateIterator(iterator: IteratorFunction): IteratorFunction;
-    _checkIterableAdapter(): boolean;
-    _getKeyPrefix(key: string): string;
-    _getKeyPrefixArray(keys: string[]): string[];
-    _getKeyUnprefix(key: string): string;
-    _isValidStorageAdapter(store: KeyvStoreAdapter | any): boolean;
-    /**
-     * Get the Value of a Key
-     * @param {string | string[]} key passing in a single key or multiple as an array
-     * @param {{raw: boolean} | undefined} options can pass in to return the raw value by setting { raw: true }
-     */
-    get<Value = GenericValue>(key: string, options?: {
-        raw: false;
-    }): Promise<StoredDataNoRaw<Value>>;
-    get<Value = GenericValue>(key: string, options?: {
-        raw: true;
-    }): Promise<StoredDataRaw<Value>>;
-    get<Value = GenericValue>(key: string[], options?: {
-        raw: false;
-    }): Promise<Array<StoredDataNoRaw<Value>>>;
-    get<Value = GenericValue>(key: string[], options?: {
-        raw: true;
-    }): Promise<Array<StoredDataRaw<Value>>>;
-    /**
-     * Get many values of keys
-     * @param {string[]} keys passing in a single key or multiple as an array
-     * @param {{raw: boolean} | undefined} options can pass in to return the raw value by setting { raw: true }
-     */
-    getMany<Value = GenericValue>(keys: string[], options?: {
-        raw: false;
-    }): Promise<Array<StoredDataNoRaw<Value>>>;
-    getMany<Value = GenericValue>(keys: string[], options?: {
-        raw: true;
-    }): Promise<Array<StoredDataRaw<Value>>>;
-    /**
-     * Get the raw value of a key. This is the replacement for setting raw to true in the get() method.
-     * @param {string} key the key to get
-     * @returns {Promise<StoredDataRaw<Value> | undefined>} will return a StoredDataRaw<Value> or undefined if the key does not exist or is expired.
-     */
-    getRaw<Value = GenericValue>(key: string): Promise<StoredDataRaw<Value> | undefined>;
-    /**
-     * Get the raw values of many keys. This is the replacement for setting raw to true in the getMany() method.
-     * @param {string[]} keys the keys to get
-     * @returns {Promise<Array<StoredDataRaw<Value>>>} will return an array of StoredDataRaw<Value> or undefined if the key does not exist or is expired.
-     */
-    getManyRaw<Value = GenericValue>(keys: string[]): Promise<Array<StoredDataRaw<Value>>>;
-    /**
-     * Set an item to the store
-     * @param {string | Array<KeyvEntry>} key the key to use. If you pass in an array of KeyvEntry it will set many items
-     * @param {Value} value the value of the key
-     * @param {number} [ttl] time to live in milliseconds
-     * @returns {boolean} if it sets then it will return a true. On failure will return false.
-     */
-    set<Value = GenericValue>(key: string, value: Value, ttl?: number): Promise<boolean>;
-    /**
-     * Set many items to the store
-     * @param {Array<KeyvEntry>} entries the entries to set
-     * @returns {boolean[]} will return an array of booleans if it sets then it will return a true. On failure will return false.
-     */
-    setMany<Value = GenericValue>(entries: KeyvEntry[]): Promise<boolean[]>;
-    /**
-     * Delete an Entry
-     * @param {string | string[]} key the key to be deleted. if an array it will delete many items
-     * @returns {boolean} will return true if item or items are deleted. false if there is an error
-     */
-    delete(key: string | string[]): Promise<boolean>;
-    /**
-     * Delete many items from the store
-     * @param {string[]} keys the keys to be deleted
-     * @returns {boolean} will return true if item or items are deleted. false if there is an error
-     */
-    deleteMany(keys: string[]): Promise<boolean>;
-    /**
-     * Clear the store
-     * @returns {void}
-     */
-    clear(): Promise<void>;
-    /**
-     * Has a key
-     * @param {string} key the key to check
-     * @returns {boolean} will return true if the key exists
-     */
-    has(key: string[]): Promise<boolean[]>;
-    has(key: string): Promise<boolean>;
-    /**
-     * Check if many keys exist
-     * @param {string[]} keys the keys to check
-     * @returns {boolean[]} will return an array of booleans if the keys exist
-     */
-    hasMany(keys: string[]): Promise<boolean[]>;
-    /**
-     * Will disconnect the store. This is only available if the store has a disconnect method
-     * @returns {Promise<void>}
-     */
-    disconnect(): Promise<void>;
-    emit(event: string, ...arguments_: any[]): void;
-    serializeData<T>(data: DeserializedData<T>): Promise<string | DeserializedData<T>>;
-    deserializeData<T>(data: string | DeserializedData<T>): Promise<DeserializedData<T> | undefined>;
+/**
+ * A bridge storage adapter for Keyv that wraps any promise-based store.
+ *
+ * This class provides a unified interface for using various async stores
+ * with Keyv, handling namespace prefixing, TTL-based expiration, and batch operations.
+ * If the underlying store implements optional methods (has, hasMany, getMany, etc.),
+ * the bridge will delegate to them. Otherwise, it falls back to using primitives.
+ *
+ * @example
+ * ```typescript
+ * // Using with a promise-based store
+ * const bridge = new KeyvBridgeAdapter(myAsyncStore, { namespace: 'cache' });
+ *
+ * // Using with Keyv
+ * const keyv = new Keyv({ store: new KeyvBridgeAdapter(myAsyncStore) });
+ * ```
+ */
+declare class KeyvBridgeAdapter extends Hookified implements KeyvStorageAdapter {
+  private _store;
+  private _namespace?;
+  private _keySeparator;
+  private readonly _capabilities;
+  /**
+   * Creates a new KeyvBridgeAdapter instance.
+   * @param store - The underlying promise-based store to bridge
+   * @param options - Configuration options for the adapter
+   */
+  constructor(store: KeyvBridgeStore, options?: KeyvBridgeAdapterOptions);
+  /**
+   * Gets the underlying store instance.
+   */
+  get store(): KeyvBridgeStore;
+  /**
+   * Sets the underlying store instance.
+   */
+  set store(store: KeyvBridgeStore);
+  /**
+   * Gets the detected capabilities of the underlying store.
+   */
+  get capabilities(): KeyvStorageCapability;
+  /**
+   * Gets the current key separator used between namespace and key.
+   */
+  get keySeparator(): string;
+  /**
+   * Sets the key separator used between namespace and key.
+   */
+  set keySeparator(separator: string);
+  /**
+   * Gets the current namespace.
+   */
+  get namespace(): string | undefined;
+  /**
+   * Sets the namespace.
+   */
+  set namespace(namespace: string | undefined);
+  /**
+   * Creates a prefixed key by combining the namespace and key with the separator.
+   * @param key - The base key
+   * @param namespace - Optional namespace to prefix the key with
+   * @returns The prefixed key if namespace is provided, otherwise the original key
+   */
+  getKeyPrefix(key: string, namespace?: string): string;
+  /**
+   * Parses a prefixed key to extract the namespace and original key.
+   * @param key - The prefixed key to parse
+   * @returns An object containing the namespace (if present) and the original key
+   */
+  getKeyPrefixData(key: string): KeyPrefixData;
+  /**
+   * Retrieves a value from the store by key.
+   * Automatically handles namespace prefixing and TTL expiration.
+   * @param key - The key to retrieve
+   * @returns The stored data, or undefined if not found or expired
+   */
+  get<T>(key: string): Promise<KeyvStorageGetResult<T>>;
+  /**
+   * Retrieves multiple values from the store by their keys.
+   * Delegates to the store's native getMany if available.
+   * @param keys - Array of keys to retrieve
+   * @returns Array of stored data in the same order as the input keys
+   */
+  getMany<T>(keys: string[]): Promise<Array<KeyvStorageGetResult<T | undefined>>>;
+  /**
+   * Stores a value in the store with an optional TTL.
+   * @param key - The key to store the value under
+   * @param value - The value to store
+   * @param ttl - Optional time-to-live in milliseconds
+   * @returns Always returns true indicating success
+   */
+  set(key: string, value: any, ttl?: number): Promise<boolean>;
+  /**
+   * Stores multiple entries in the store at once.
+   * Delegates to the store's native setMany if available, otherwise loops over set.
+   * @param entries - Array of entries containing key, value, and optional TTL
+   */
+  setMany<Value>(entries: KeyvEntry<Value>[]): Promise<boolean[] | undefined>;
+  /**
+   * Checks if a key exists in the store and is not expired.
+   * Delegates to the store's native has if available.
+   * @param key - The key to check
+   * @returns True if the key exists and is not expired, false otherwise
+   */
+  has(key: string): Promise<boolean>;
+  /**
+   * Checks if multiple keys exist in the store and are not expired.
+   * Delegates to the store's native hasMany if available.
+   * @param keys - Array of keys to check
+   * @returns Array of booleans indicating existence for each key
+   */
+  hasMany(keys: string[]): Promise<boolean[]>;
+  /**
+   * Deletes a value from the store by key.
+   * @param key - The key to delete
+   * @returns True if the key was deleted, false otherwise
+   */
+  delete(key: string): Promise<boolean>;
+  /**
+   * Deletes multiple keys from the store at once.
+   * Delegates to the store's native deleteMany if available.
+   * @param keys - Array of keys to delete
+   * @returns Array of booleans indicating success for each key
+   */
+  deleteMany(keys: string[]): Promise<boolean[]>;
+  /**
+   * Clears entries from the store. If a namespace is set and the store supports
+   * iteration, only entries within that namespace are removed. Otherwise, the
+   * entire store is cleared.
+   */
+  clear(): Promise<void>;
+  /**
+   * Creates an async iterator for iterating over store entries.
+   * If the underlying store does not support iteration, returns an empty generator.
+   * @returns An async generator yielding [key, value] pairs
+   */
+  iterator<Value>(): AsyncGenerator<Array<string | Awaited<Value> | undefined>, void>;
+  /**
+   * Disconnects from the underlying store.
+   * No-op if the store does not support disconnect.
+   */
+  disconnect(): Promise<void>;
 }
-
-export { type CompressionAdapter, type Deserialize, type DeserializedData, type IEventEmitter, Keyv, type KeyvEntry, KeyvHooks, type KeyvOptions, type KeyvStoreAdapter, type Serialize, type StoredData, type StoredDataNoRaw, type StoredDataRaw, Keyv as default };
+//#endregion
+//#region src/keyv.d.ts
+declare class Keyv<GenericValue = any> extends Hookified {
+  /**
+   * Stats manager for tracking cache operation metrics (hits, misses, sets, deletes, errors).
+   * @default this is disabled.
+   */
+  private _stats;
+  /**
+   * Default time to live in milliseconds. Can be overridden per-key via {@link set}.
+   */
+  private _ttl?;
+  /**
+   * Key prefix namespace used to isolate keys across different Keyv instances sharing the same store.
+   */
+  private _namespace?;
+  /**
+   * The underlying storage adapter. Defaults to an in-memory {@link Map}.
+   */
+  private _store;
+  /**
+   * Pluggable serialization adapter with `stringify` and `parse` methods.
+   * When `undefined`, the built-in {@link KeyvJsonSerializer} is used.
+   */
+  private _serialization;
+  /**
+   * Pluggable compression adapter with `compress` and `decompress` methods.
+   */
+  private _compression;
+  /**
+   * Pluggable encryption adapter with `encrypt` and `decrypt` methods.
+   */
+  private _encryption;
+  /**
+   * Sanitization handler for keys and namespaces. By default it is disabled.
+   */
+  private _sanitize;
+  /**
+   * When true, Keyv checks expiry at its layer on get/getMany/has/hasMany.
+   */
+  private _checkExpired;
+  /**
+   * Keyv Constructor
+   * @param {KeyvStorageAdapter | KeyvOptions | Map<any, any> | any} store  to be provided or just the options
+   * @param {Omit<KeyvOptions, 'store'>} [options] if you provide the store you can then provide the Keyv Options
+   */
+  constructor(store?: KeyvStorageAdapter | KeyvOptions | KeyvMapAny, options?: Omit<KeyvOptions, "store">);
+  /**
+   * Keyv Constructor
+   * @param {KeyvOptions} options to be provided
+   */
+  constructor(options?: KeyvOptions);
+  /**
+   * Get the current storage adapter.
+   * @returns {KeyvStorageAdapter} The current storage adapter.
+   */
+  get store(): KeyvStorageAdapter;
+  /**
+   * Set the storage adapter.
+   * @param {KeyvStorageAdapter | Map<any, any> | any} store The storage adapter to set.
+   */
+  set store(store: KeyvStorageAdapter | KeyvMapAny);
+  /**
+   * Get the current compression adapter.
+   * @returns {KeyvCompressionAdapter | undefined} The current compression adapter.
+   */
+  get compression(): KeyvCompressionAdapter | undefined;
+  /**
+   * Set the compression adapter.
+   * @param {KeyvCompressionAdapter | undefined} compress The compression adapter to set.
+   */
+  set compression(compress: KeyvCompressionAdapter | undefined);
+  /**
+   * Get the current encryption adapter.
+   * @returns {KeyvEncryptionAdapter | undefined} The current encryption adapter.
+   */
+  get encryption(): KeyvEncryptionAdapter | undefined;
+  /**
+   * Set the encryption adapter.
+   * @param {KeyvEncryptionAdapter | undefined} encryption The encryption adapter to set.
+   */
+  set encryption(encryption: KeyvEncryptionAdapter | undefined);
+  /**
+   * Get the current namespace.
+   * @returns {string | undefined} The current namespace.
+   */
+  get namespace(): string | undefined;
+  /**
+   * Set the current namespace.
+   * @param {string | undefined} namespace The namespace to set.
+   */
+  set namespace(namespace: string | undefined);
+  /**
+   * Get the current TTL.
+   * @returns {number} The current TTL in milliseconds.
+   */
+  get ttl(): number | undefined;
+  /**
+   * Set the current TTL.
+   * @param {number} ttl The TTL to set in milliseconds.
+   */
+  set ttl(ttl: number | undefined);
+  /**
+   * Get the current serialization adapter. If `undefined`, serialization is not enabled.
+   * @returns {KeyvSerializationAdapter | undefined} The current serialization adapter.
+   */
+  get serialization(): KeyvSerializationAdapter | undefined;
+  /**
+   * Set the current serialization adapter. Pass a `KeyvSerializationAdapter` to enable
+   * custom serialization, or `undefined` to disable serialization entirely.
+   * @param {KeyvSerializationAdapter | undefined} serialization The serialization adapter to set.
+   */
+  set serialization(serialization: KeyvSerializationAdapter | false | undefined);
+  /**
+   * Get the current throwOnErrors value. When enabled, all errors with throw. By default, errors
+   * will only throw if there are no listeners to the error event.
+   * @return {boolean} The current throwOnErrors value.
+   */
+  get throwOnErrors(): boolean;
+  /**
+   * Set the current throwOnErrors value. When enabled, all errors will throw. By default, errors
+   * will only throw if there are no listeners to the error event.
+   * @param {boolean} value The throwOnErrors value to set.
+   */
+  set throwOnErrors(value: boolean);
+  /**
+   * Get the current sanitize adapter. Sanitization is disabled by default. To
+   * enable it `sanitize.keys` or `sanitize.namespace` to true or set KeyvSanitizePatterns
+   * to each.
+   * @returns {KeyvSanitizeAdapter} The current sanitize adapter.
+   */
+  get sanitize(): KeyvSanitizeAdapter;
+  /**
+   * Set the sanitize adapter directly and will run sanitization on namespace.
+   * @param {KeyvSanitizeAdapter} value The sanitize adapter to use.
+   */
+  set sanitize(value: KeyvSanitizeAdapter);
+  /**
+   * Get the stats. This is just for this instance
+   * @returns {KeyvStats} The current stats.
+   */
+  get stats(): KeyvStats;
+  /**
+   * When true, Keyv checks expiry at its layer on get/getMany/has/hasMany.
+   * When false (default), trusts the storage adapter.
+   */
+  get checkExpired(): boolean;
+  /**
+   * Set the stats. When setting a new instance it will unsubscribe the old listeners
+   * and subscribe the new instance.
+   * @param {KeyvStats} stats The stats instance to set.
+   */
+  set stats(stats: KeyvStats);
+  /**
+   * Resolves a store to a fully-compliant KeyvStorageAdapter using a 3-tier detection chain:
+   * 1. If the store already implements the full KeyvStorageAdapter interface, use it directly.
+   * 2. If the store is map-like (synchronous get/set/delete/has), wrap it in KeyvMemoryAdapter.
+   * 3. If the store has async get/set/delete/clear, wrap it in KeyvBridgeAdapter.
+   * 4. Otherwise, emit an error and fall back to a default in-memory KeyvMemoryAdapter.
+   *
+   * NOTE: this is used for internal but provided public for custom adapter testing
+   * @param {unknown} store The store to resolve.
+   * @returns {KeyvStorageAdapter} A fully-compliant storage adapter.
+   */
+  resolveStore(store: any): KeyvStorageAdapter;
+  /**
+   * Sets the storage adapter by resolving it via {@link resolveStore}, then wires up
+   * error forwarding and namespace propagation.
+   * @param {KeyvStorageAdapter | Map<any, any> | any} store The storage adapter to set.
+   */
+  setStore(store: KeyvStorageAdapter | KeyvMapAny): void;
+  /**
+   * Sets the TTL, treating zero and negative values as undefined (no TTL).
+   * @param {number | undefined} ttl The TTL to set in milliseconds.
+   */
+  setTtl(ttl?: number): void;
+  /**
+   * Get the Value of a Key
+   * @param {string | string[]} key passing in a single key or multiple as an array
+   */
+  get<Value = GenericValue>(key: string): Promise<Value | undefined>;
+  get<Value = GenericValue>(key: string[]): Promise<Array<Value | undefined>>;
+  /**
+   * Get many values of keys
+   * @param {string[]} keys passing in a single key or multiple as an array
+   */
+  getMany<Value = GenericValue>(keys: string[]): Promise<Array<Value | undefined>>;
+  /**
+   * Get the raw value of a key. This is the replacement for setting raw to true in the get() method.
+   * @param {string} key the key to get
+   * @returns {Promise<KeyvStorageGetResult<Value>>} will return a KeyvStorageGetResult<Value> or undefined
+   * if the key does not exist or is expired.
+   */
+  getRaw<Value = GenericValue>(key: string): Promise<KeyvStorageGetResult<Value>>;
+  /**
+   * Get the raw values of many keys. This is the replacement for setting raw to true in the getMany() method.
+   * @param {string[]} keys the keys to get
+   * @returns {Promise<Array<KeyvStorageGetResult<Value>>>} will return an array of KeyvStorageGetResult<Value> or undefined if the key does not exist or is expired.
+   */
+  getManyRaw<Value = GenericValue>(keys: string[]): Promise<Array<KeyvStorageGetResult<Value>>>;
+  /**
+   * Set an item to the store
+   * @param {string | Array<KeyvEntry<Value>>} key the key to use. If you pass in an array of KeyvEntry it will set many items
+   * @param {Value} value the value of the key
+   * @param {number} [ttl] time to live in milliseconds
+   * @returns {boolean} if it sets then it will return a true. On failure will return false.
+   */
+  set<Value = GenericValue>(key: string, value: Value, ttl?: number): Promise<boolean>;
+  /**
+   * Set many items to the store
+   * @param {Array<KeyvEntry<Value>>} entries the entries to set
+   * @returns {boolean[]} will return an array of booleans if it sets then it will return a true. On failure will return false.
+   */
+  setMany<Value = GenericValue>(entries: KeyvEntry<Value>[]): Promise<boolean[]>;
+  /**
+   * Set a raw value to the store without wrapping or serialization. This is the write-side counterpart to getRaw().
+   * The value should be a KeyvValue object with { value, expires? }. If you need TTL-based expiration,
+   * set `expires` on the value directly (e.g. `{ value: 'bar', expires: Date.now() + 60000 }`).
+   * The store-level TTL is derived automatically from `value.expires`.
+   * @param {string} key the key to set
+   * @param {KeyvValue<Value>} value the raw value envelope to store
+   * @returns {boolean} if it sets then it will return a true. On failure will return false.
+   */
+  setRaw<Value = GenericValue>(key: string, value: KeyvValue<Value>): Promise<boolean>;
+  /**
+   * Set many raw values to the store without wrapping or serialization. This is the write-side counterpart to getManyRaw().
+   * Each entry's value should be a KeyvValue object with { value, expires? }. If you need TTL-based expiration,
+   * set `expires` on each value directly. The store-level TTL is derived automatically from `value.expires`.
+   * @param {KeyvEntry<KeyvValue<Value>>[]} entries the raw entries to set
+   * @returns {boolean[]} will return an array of booleans if it sets then it will return a true. On failure will return false.
+   */
+  setManyRaw<Value = GenericValue>(entries: KeyvEntry<KeyvValue<Value>>[]): Promise<boolean[]>;
+  /**
+   * Delete an Entry
+   * @param {string} key the key to be deleted
+   * @returns {boolean} will return true if item is deleted. false if there is an error
+   */
+  delete(key: string): Promise<boolean>;
+  /**
+   * Delete multiple Entries
+   * @param {string[]} keys the keys to be deleted
+   * @returns {boolean[]} will return array of booleans for each key
+   */
+  delete(keys: string[]): Promise<boolean[]>;
+  /**
+   * Delete many items from the store
+   * @param {string[]} keys the keys to be deleted
+   * @returns {boolean[]} array of booleans indicating success for each key
+   */
+  deleteMany(keys: string[]): Promise<boolean[]>;
+  /**
+   * Has a key.
+   * @param {string} key the key to check
+   * @returns {boolean} will return true if the key exists
+   */
+  has(key: string[]): Promise<boolean[]>;
+  has(key: string): Promise<boolean>;
+  /**
+   * Check if many keys exist
+   * @param {string[]} keys the keys to check
+   * @returns {boolean[]} will return an array of booleans if the keys exist
+   */
+  hasMany(keys: string[]): Promise<boolean[]>;
+  /**
+   * Clear the store
+   * @returns {void}
+   */
+  clear(): Promise<void>;
+  /**
+   * Will disconnect the store. This is only available if the store has a disconnect method
+   * @returns {Promise<void>}
+   */
+  disconnect(): Promise<void>;
+  /**
+   * Iterate over all key-value pairs in the store. Automatically deserializes values,
+   * filters out expired entries, and deletes them from the store.
+   * @returns {AsyncGenerator<Array<string | unknown>, void>} An async generator yielding `[key, value]` pairs.
+   */
+  iterator(): AsyncGenerator<[string, any], void>;
+  /**
+   * Encodes a value for storage. Pipeline: serialize → compress → encrypt.
+   * If serialization is not configured, returns the data as-is.
+   * @param {KeyvValue<T>} data The value envelope to encode.
+   * @returns {Promise<unknown>} The encoded value, or the original data on failure.
+   */
+  encode<T>(data: KeyvValue<T>): Promise<unknown>;
+  /**
+   * Decodes a stored value. Pipeline: decrypt → decompress → deserialize (reverse of encode).
+   * If serialization is not configured, returns the data as a KeyvValue or undefined for strings.
+   * @param {unknown} data The raw data from the store.
+   * @returns {Promise<KeyvValue<T> | undefined>} The decoded value envelope, or undefined on failure.
+   */
+  decode<T>(data: unknown): Promise<KeyvValue<T> | undefined>;
+  /**
+   * Deserializes raw data from the store, checks for expiry, and deletes expired keys.
+   * Accepts a single key/value or arrays. Returns an array of decoded KeyvValue objects
+   * (undefined for missing or expired entries).
+   * @param {string | string[]} keys the key(s) to process
+   * @param {unknown | unknown[]} rawData the raw data from the store
+   * @returns {Promise<Array<KeyvValue<Value> | undefined>>} decoded values with expired entries removed
+   */
+  decodeWithExpire<Value>(keys: string | string[], rawData: unknown | unknown[]): Promise<Array<KeyvValue<Value> | undefined>>;
+  /**
+   * Fires a hook under its new name and also under the deprecated alias (if any),
+   * so that integrations still subscribing to the old PRE_/POST_ names keep working.
+   */
+  private hookWithDeprecated;
+  /**
+   * Emit a telemetry event for cache operations.
+   * @param {KeyvEvents} event the telemetry event type
+   * @param {string | string[]} [key] the cache key or keys (emits one event per key)
+   */
+  private emitTelemetry;
+  /**
+   * Merges the overloaded constructor arguments into a single KeyvOptions object.
+   */
+  private static resolveOptions;
+  /**
+   * Initializes the serialization adapter from options.
+   */
+  private initSerialization;
+  /**
+   * Initializes the sanitization handler from options.
+   */
+  private initSanitize;
+  /**
+   * Initializes the stats manager from options.
+   */
+  private initStats;
+  /**
+   * Initializes the namespace, applying sanitization if enabled.
+   */
+  private initNamespace;
+}
+//#endregion
+//#region src/adapters/memory.d.ts
+/**
+ * Configuration options for KeyvMemoryAdapter.
+ */
+type KeyvMemoryAdapterOptions = {
+  /**
+   * The namespace to use for keys.
+   * When set, all keys will be prefixed with the namespace followed by the key separator.
+   */
+  namespace?: string;
+  /**
+   * The separator used between namespace and key. Defaults to ":".
+   */
+  keySeparator?: string;
+};
+/**
+ * Interface for a Map-like store that can be used with KeyvMemoryAdapter.
+ * This allows any object implementing these methods to be used as the underlying storage.
+ * Compatible with Map, QuickLRU, lru.min, and other LRU cache implementations.
+ */
+type KeyvMapType = {
+  /** Retrieves a value by key */get: (key: string) => any; /** Sets a value with a key. Additional parameters (like TTL) vary by implementation. */
+  set: (key: string, value: any, ...args: any[]) => any; /** Deletes a key from the store */
+  delete: (key: string) => boolean; /** Clears all entries from the store */
+  clear: () => void; /** Checks if a key exists in the store */
+  has: (key: string) => boolean;
+};
+/**
+ * An in-memory storage adapter for Keyv that wraps any Map-like object.
+ *
+ * This class provides a unified interface for using various Map-like stores
+ * with Keyv, handling namespace prefixing, TTL-based expiration, and batch operations.
+ *
+ * @example
+ * ```typescript
+ * // Using with a standard Map
+ * const store = new KeyvMemoryAdapter(new Map(), { namespace: 'cache' });
+ *
+ * // Using with a custom store
+ * const customStore = new KeyvMemoryAdapter(myCustomMapLikeStore, {
+ *   namespace: 'tenant-123',
+ *   keySeparator: ':'
+ * });
+ * ```
+ */
+declare class KeyvMemoryAdapter extends Hookified implements KeyvStorageAdapter {
+  private _store;
+  private _namespace?;
+  private _keySeparator;
+  private readonly _capabilities;
+  /**
+   * Creates a new KeyvMemoryAdapter instance.
+   * @param store - The underlying Map or Map-like object to use for storage
+   * @param options - Configuration options for the store
+   */
+  constructor(store: KeyvMapType, options?: KeyvMemoryAdapterOptions);
+  /**
+   * Gets the detected capabilities of the underlying store.
+   */
+  get capabilities(): KeyvStorageCapability;
+  /**
+   * Gets the underlying store instance.
+   */
+  get store(): KeyvMapType;
+  /**
+   * Sets the underlying store instance.
+   */
+  set store(store: KeyvMapType);
+  /**
+   * Gets the current key separator used between namespace and key.
+   */
+  get keySeparator(): string;
+  /**
+   * Sets the key separator used between namespace and key.
+   */
+  set keySeparator(separator: string);
+  /**
+   * Gets the current namespace.
+   */
+  get namespace(): string | undefined;
+  /**
+   * Sets the namespace.
+   */
+  set namespace(namespace: string | undefined);
+  /**
+   * Creates a prefixed key by combining the namespace and key with the separator.
+   * @param key - The base key
+   * @param namespace - Optional namespace to prefix the key with
+   * @returns The prefixed key if namespace is provided, otherwise the original key
+   */
+  getKeyPrefix(key: string, namespace?: string): string;
+  /**
+   * Parses a prefixed key to extract the namespace and original key.
+   * @param key - The prefixed key to parse
+   * @returns An object containing the namespace (if present) and the original key
+   */
+  getKeyPrefixData(key: string): {
+    namespace: string;
+    key: string;
+  } | {
+    key: string;
+    namespace?: undefined;
+  };
+  /**
+   * Retrieves a value from the store by key.
+   * Automatically handles namespace prefixing and TTL expiration.
+   * @param key - The key to retrieve
+   * @returns The stored data, or undefined if not found or expired
+   */
+  get<T>(key: string): Promise<KeyvStorageGetResult<T>>;
+  /**
+   * Stores a value in the store with an optional TTL.
+   * @param key - The key to store the value under
+   * @param value - The value to store
+   * @param ttl - Optional time-to-live in milliseconds
+   * @returns Always returns true indicating success
+   */
+  set(key: string, value: any, ttl?: number): Promise<boolean>;
+  /**
+   * Stores multiple entries in the store at once.
+   * @param entries - Array of entries containing key, value, and optional TTL
+   */
+  setMany<Value>(entries: KeyvEntry<Value>[]): Promise<boolean[] | undefined>;
+  /**
+   * Deletes a value from the store by key.
+   * @param key - The key to delete
+   * @returns True if the key was deleted, false otherwise
+   */
+  delete(key: string): Promise<boolean>;
+  /**
+   * Clears entries from the store. If a namespace is set, only entries
+   * within that namespace are removed. Otherwise, the entire store is cleared.
+   * NOTE: if there is no `keys()` then we just do a full clear.
+   */
+  clear(): Promise<void>;
+  /**
+   * Checks if a key exists in the store and is not expired.
+   * @param key - The key to check
+   * @returns True if the key exists and is not expired, false otherwise
+   */
+  has(key: string): Promise<boolean>;
+  /**
+   * Checks if multiple keys exist in the store and are not expired.
+   * @param keys - Array of keys to check
+   * @returns Array of booleans indicating existence for each key
+   */
+  hasMany(keys: string[]): Promise<boolean[]>;
+  /**
+   * Retrieves multiple values from the store by their keys.
+   * @param keys - Array of keys to retrieve
+   * @returns Array of stored data in the same order as the input keys
+   */
+  getMany<T>(keys: string[]): Promise<Array<KeyvStorageGetResult<T | undefined>>>;
+  /**
+   * Deletes multiple keys from the store at once.
+   * @param keys - Array of keys to delete
+   * @returns Array of booleans indicating success for each key
+   */
+  deleteMany(keys: string[]): Promise<boolean[]>;
+  /**
+   * Creates an async iterator for iterating over store entries.
+   * If the underlying store does not support iteration, returns an empty generator.
+   * @returns {AsyncGenerator<Array<string | Awaited<Value> | undefined>, void>} An async generator yielding [key, value] pairs
+   */
+  iterator<Value>(): AsyncGenerator<Array<string | Awaited<Value> | undefined>, void>;
+  /**
+   * No-op disconnect for in-memory stores.
+   */
+  disconnect(): Promise<void>;
+}
+/**
+ * Creates a Keyv instance with a memory adapter optimized for in-memory storage.
+ *
+ * This factory function configures Keyv to bypass serialization/deserialization
+ * and key prefixing, resulting in faster performance for in-memory use cases
+ * where data doesn't need to be persisted or transmitted.
+ *
+ * @param store - The underlying Map or Map-like object to use for storage
+ * @param options - Configuration options for the memory adapter
+ * @returns A configured Keyv instance with optimized settings for in-memory storage
+ *
+ * @example
+ * ```typescript
+ * // Create a simple in-memory cache
+ * const cache = createKeyv(new Map());
+ * await cache.set('user:1', { name: 'John' });
+ *
+ * // Create with namespace for multi-tenant scenarios
+ * const tenantCache = createKeyv(new Map(), {
+ *   namespace: 'tenant-123',
+ *   keySeparator: ':'
+ * });
+ * ```
+ */
+declare function createKeyv(store: KeyvMapType, options?: KeyvMemoryAdapterOptions): Keyv<any>;
+//#endregion
+//#region src/json-serializer.d.ts
+declare class KeyvJsonSerializer implements KeyvSerializationAdapter {
+  stringify(object: unknown): string;
+  parse<T>(data: string): T;
+}
+declare const jsonSerializer: KeyvJsonSerializer;
+//#endregion
+export { type DeserializedData, Keyv, Keyv as default, KeyvBridgeAdapter, type KeyvBridgeAdapterOptions, type KeyvBridgeStore, type KeyvCapability, type KeyvCompression, type KeyvCompressionAdapter, type KeyvCompressionCapability, type KeyvCompressionMethods, type KeyvEncryptionAdapter, type KeyvEncryptionCapability, type KeyvEncryptionMethods, type KeyvEntry, KeyvEvents, KeyvHooks, KeyvJsonSerializer, type KeyvMapAny, type KeyvMapType, KeyvMemoryAdapter, type KeyvMemoryAdapterOptions, type KeyvMethods, type KeyvOptions, type KeyvProperties, KeyvSanitize, type KeyvSanitizeAdapter, type KeyvSanitizeOptions, type KeyvSanitizePatterns, type KeyvSerializationAdapter, type KeyvSerializationCapability, type KeyvSerializationMethods, KeyvStats, type KeyvStatsOptions, type KeyvStorageAdapter, type KeyvStorageCapability, type KeyvStorageGetResult, type KeyvStorageMethod, type KeyvStorageMethods, type KeyvStoreAdapter, type KeyvTelemetryEvent, type KeyvValue, type MethodType, createKeyv, detectKeyv, detectKeyvCompression, detectKeyvEncryption, detectKeyvSerialization, detectKeyvStorage, jsonSerializer };