@jwilleke/ngdpbase-types 0.0.0 → 5.18.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,17 @@
-# @jwilleke/ngdpbase-types — placeholder
+# @jwilleke/ngdpbase-types
 
-This 0.0.0 only reserves the name. Real versions are published from GitHub Actions with provenance, versioned with ngdpbase.
+The TypeScript types an ngdpbase add-on compiles against, and a test kit of core's own values. Published with each ngdpbase release, at the same version. A dev dependency only: it never ships to a site, where `host` and `engine` hand the add-on the running core.
+
+```sh
+npm install --save-dev @jwilleke/ngdpbase-types@<your ngdpbase.minVersion>
+```
+
+```typescript
+import type { AddonModule, AddonHost, WikiEngine } from '@jwilleke/ngdpbase-types';
+import { buildAddonHost, openAddonTestDatabase, toCsv, formatters } from '@jwilleke/ngdpbase-types/testing';
+```
+
+- The main entry is types only. Importing it at run time fails, on purpose.
+- `/testing` is for tests. `buildAddonHost(slug, defaults)` is the real host. `openAddonTestDatabase(owner, { migrations, ledgerTable })` is the handle `openAddonDatabase` returns, in memory. `toCsv` is `ExportManager.toCsv`. `formatters` is a plugin's `context.formatters`.
+
+The add-on guide is [docs/guides/addons-developer-guide.md](https://github.com/jwilleke/ngdpbase/blob/master/docs/guides/addons-developer-guide.md).

package/lib/packages/ngdpbase-types/index.d.ts

@@ -0,0 +1,32 @@
+/// <reference path="../../src/types/heic-decode.d.ts" />
+/// <reference path="../../src/types/linkedom.d.ts" />
+/// <reference path="../../src/types/markdown-it-plugins.d.ts" />
+/**
+ * `@jwilleke/ngdpbase-types`: the add-on API's types, published with each
+ * ngdpbase release (#1865, the types slice of #1813).
+ *
+ * This file is the public contract. It re-exports, as types only, the
+ * declarations an add-on compiles against; every one is core's own
+ * declaration, never a copy. Anything not named here is internal and may
+ * change in any release. Additive only between majors, as `host` is.
+ *
+ * Values come from `host` at run time, and in tests from
+ * `@jwilleke/ngdpbase-types/testing`. A test holds this file to `export type`
+ * only, so the published entry carries no JavaScript.
+ */
+export type { AddonModule } from '../../src/managers/AddonsManager.js';
+export type { AddonHost } from '../../src/utils/addonHost.js';
+export type { WikiEngine } from '../../src/types/WikiEngine.js';
+export type { ApiContext } from '../../src/context/ApiContext.js';
+export type { ActorContext } from '../../src/context/ActorContext.js';
+export type { PermissionSubject } from '../../src/managers/UserManager.js';
+export type { Decision } from '../../src/types/Policy.js';
+export type { PluginContext, PluginParams, PluginFormatters } from '../../src/managers/PluginManager.js';
+export type { SimplePlugin } from '../../src/plugins/types.js';
+export type { AuditEvent } from '../../src/utils/auditEvents.js';
+export type { JobRunContext } from '../../src/managers/BackgroundJobManager.js';
+export type { default as DatabaseManager, AddonDatabaseOptions } from '../../src/managers/DatabaseManager.js';
+export type { Migration } from '../../src/providers/sqliteMigrations.js';
+export type { AddonDatabaseDeclaration, DatabaseEncrypt } from '../../src/utils/addonDatabaseRules.js';
+export type { default as ExportManager } from '../../src/managers/ExportManager.js';
+export type { default as PolicyDecisionPoint } from '../../src/security/PolicyDecisionPoint.js';

package/lib/packages/ngdpbase-types/testing.d.ts

@@ -0,0 +1,43 @@
+/// <reference path="../../src/types/heic-decode.d.ts" />
+/// <reference path="../../src/types/linkedom.d.ts" />
+/// <reference path="../../src/types/markdown-it-plugins.d.ts" />
+import ExportManager from '../../src/managers/ExportManager.js';
+import { type AddonDatabaseOptions } from '../../src/managers/DatabaseManager.js';
+import { type SqliteHandle } from '../../src/providers/SqliteDatabaseProvider.js';
+import { type AddonHost } from '../../src/utils/addonHost.js';
+export { formatters } from '../../src/managers/PluginManager.js';
+/**
+ * Core's `buildAddonHost`, with the audit registry bound to this add-on's
+ * defaults, as a site's merged configuration binds it at boot. The host
+ * refuses an event the add-on does not declare; core's `recordAuditEvent`
+ * then finds a declared one in the registry, as it does on a site. The
+ * binding is process-wide: the last host built is the one bound.
+ *
+ * @param slug - The add-on's canonical slug
+ * @param addonDefaults - The add-on's own `config/default-config.json`
+ */
+export declare function buildAddonHost(slug: string, addonDefaults: Record<string, unknown>): AddonHost;
+/** The add-on whose declaration a test database is checked against: its slug and its own `config/default-config.json`. */
+export interface AddonTestDatabaseDeclarer {
+    slug: string;
+    defaults: Record<string, unknown>;
+}
+/**
+ * An add-on's database as `DatabaseManager.openAddonDatabase` returns it, in
+ * memory: the same provider, migration ledger and owner and ledger-table
+ * rules, with no file and no key. Each call opens a new database; the test
+ * closes the handle (`db.close()`).
+ *
+ * With `declaredBy`, the add-on's declaration (`ngdpbase.addons.<slug>.database`
+ * in its defaults, #1860) is read by core's own reader and must name this
+ * owner and ledger, so a test fails where a site would refuse the add-on or
+ * the open. `encrypt` is not applied: the database is in memory and never
+ * written to disk, so a declaration with `encrypt: "required"` opens without a key.
+ *
+ * @param owner - The add-on slug that owns the database
+ * @param options - Its migrations and ledger table, as given to `openAddonDatabase`
+ * @param declaredBy - The add-on whose declaration must cover this database
+ */
+export declare function openAddonTestDatabase<Handle = SqliteHandle>(owner: string, options: AddonDatabaseOptions, declaredBy?: AddonTestDatabaseDeclarer): Handle;
+/** `ExportManager.toCsv`: a header row and data rows as one CSV document (RFC 4180, CRLF, formula cells quoted). */
+export declare const toCsv: ExportManager['toCsv'];

package/lib/packages/ngdpbase-types/testing.js

@@ -0,0 +1,53 @@
+import ExportManager from '../../src/managers/ExportManager.js';
+import { addonDatabaseDeclarationFor, checkAddonDatabaseRequest } from '../../src/managers/DatabaseManager.js';
+import { addonDatabaseLayer } from '../../src/utils/addonConfigLayer.js';
+import SqliteDatabaseProvider from '../../src/providers/SqliteDatabaseProvider.js';
+import { buildAddonHost as buildHost } from '../../src/utils/addonHost.js';
+import { bindAuditEvents } from '../../src/utils/auditRegistry.js';
+export { formatters } from '../../src/managers/PluginManager.js';
+/**
+ * Core's `buildAddonHost`, with the audit registry bound to this add-on's
+ * defaults, as a site's merged configuration binds it at boot. The host
+ * refuses an event the add-on does not declare; core's `recordAuditEvent`
+ * then finds a declared one in the registry, as it does on a site. The
+ * binding is process-wide: the last host built is the one bound.
+ *
+ * @param slug - The add-on's canonical slug
+ * @param addonDefaults - The add-on's own `config/default-config.json`
+ */
+export function buildAddonHost(slug, addonDefaults) {
+    bindAuditEvents((key, fallback) => addonDefaults[key] ?? fallback);
+    return buildHost(slug, addonDefaults);
+}
+/**
+ * An add-on's database as `DatabaseManager.openAddonDatabase` returns it, in
+ * memory: the same provider, migration ledger and owner and ledger-table
+ * rules, with no file and no key. Each call opens a new database; the test
+ * closes the handle (`db.close()`).
+ *
+ * With `declaredBy`, the add-on's declaration (`ngdpbase.addons.<slug>.database`
+ * in its defaults, #1860) is read by core's own reader and must name this
+ * owner and ledger, so a test fails where a site would refuse the add-on or
+ * the open. `encrypt` is not applied: the database is in memory and never
+ * written to disk, so a declaration with `encrypt: "required"` opens without a key.
+ *
+ * @param owner - The add-on slug that owns the database
+ * @param options - Its migrations and ledger table, as given to `openAddonDatabase`
+ * @param declaredBy - The add-on whose declaration must cover this database
+ */
+export function openAddonTestDatabase(owner, options, declaredBy) {
+    checkAddonDatabaseRequest(owner, options);
+    if (declaredBy) {
+        const { slug, defaults } = declaredBy;
+        const layer = addonDatabaseLayer([{ slug, dir: '', source: 'directory', enabled: true, defaults }], {});
+        const refused = layer.refused.get(slug);
+        if (refused)
+            throw new Error(`Add-on '${slug}' is not loaded: ${refused}`);
+        addonDatabaseDeclarationFor(layer.declarations, owner, options.ledgerTable);
+    }
+    return new SqliteDatabaseProvider(':memory:', '', options.migrations, options.ledgerTable).handle;
+}
+// toCsv reads nothing from the engine; the instance exists only to own the method.
+const exportManager = new ExportManager({});
+/** `ExportManager.toCsv`: a header row and data rows as one CSV document (RFC 4180, CRLF, formula cells quoted). */
+export const toCsv = (headers, rows) => exportManager.toCsv(headers, rows);

package/lib/src/cache/CacheDependencies.d.ts

@@ -0,0 +1,50 @@
+/**
+ * What a cached render read (#1751).
+ *
+ * A render declares each data topic it depends on — by convention the name of
+ * the manager that owns the data, such as `LedgerManager` — before it reads.
+ * The topic's version is snapshotted at that moment, so a write that lands
+ * while the render is still running leaves the entry already stale rather
+ * than wrongly current. The manager bumps its topic after a write
+ * (`CacheManager.bump`), and `RegionCache.getOrSetVersioned` re-renders.
+ *
+ * A render whose output changes with nothing written (a clock) marks itself
+ * volatile: it is returned but never stored.
+ */
+export type VersionLookup = (topic: string) => Promise<string>;
+/** Pages: text, names, audiences, links, comments and footnotes. PageManager bumps it after every page change. */
+export declare const PAGE_DATA_TOPIC = "PageManager";
+/** Configuration, policies and role definitions. ConfigurationManager bumps it after every saved change. */
+export declare const CONFIG_DATA_TOPIC = "ConfigurationManager";
+/** Accounts: display names, roles, preferences. UserManager bumps it after every account change. */
+export declare const USER_DATA_TOPIC = "UserManager";
+/** Attachments: files, their metadata and which pages mention them. AttachmentManager bumps it after every write. */
+export declare const ATTACHMENT_DATA_TOPIC = "AttachmentManager";
+/** The media library index. MediaManager bumps it after every scan, rebuild or metadata change. */
+export declare const MEDIA_DATA_TOPIC = "MediaManager";
+/**
+ * The time, to the minute: its version is the current minute, so nothing has
+ * to write it. A plugin that shows the time, an uptime or a count that drifts
+ * on its own depends on it and is re-rendered at most once a minute, where
+ * `volatile` would re-render the whole page on every request.
+ */
+export declare const CLOCK_TOPIC = "Clock";
+/**
+ * What every cached page render reads (#1751): any page can link, list or
+ * include pages, show configuration and name people, so each render depends
+ * on these. A plugin adds its own data with `context.dependsOn(topic)`.
+ */
+export declare const BASE_RENDER_TOPICS: readonly string[];
+export default class CacheDependencies {
+    private readonly versionOf;
+    private readonly snapshots;
+    private volatile;
+    constructor(versionOf: VersionLookup);
+    /** This render reads `topic`'s data. Call it before reading. */
+    dependsOn(topic: string): void;
+    /** This render's output changes on its own; do not store it. */
+    markVolatile(): void;
+    isVolatile(): boolean;
+    /** Each declared topic with the version it had when declared. */
+    resolved(): Promise<Record<string, string>>;
+}

package/lib/src/cache/CacheDependencies.js

@@ -0,0 +1,50 @@
+/** Pages: text, names, audiences, links, comments and footnotes. PageManager bumps it after every page change. */
+export const PAGE_DATA_TOPIC = 'PageManager';
+/** Configuration, policies and role definitions. ConfigurationManager bumps it after every saved change. */
+export const CONFIG_DATA_TOPIC = 'ConfigurationManager';
+/** Accounts: display names, roles, preferences. UserManager bumps it after every account change. */
+export const USER_DATA_TOPIC = 'UserManager';
+/** Attachments: files, their metadata and which pages mention them. AttachmentManager bumps it after every write. */
+export const ATTACHMENT_DATA_TOPIC = 'AttachmentManager';
+/** The media library index. MediaManager bumps it after every scan, rebuild or metadata change. */
+export const MEDIA_DATA_TOPIC = 'MediaManager';
+/**
+ * The time, to the minute: its version is the current minute, so nothing has
+ * to write it. A plugin that shows the time, an uptime or a count that drifts
+ * on its own depends on it and is re-rendered at most once a minute, where
+ * `volatile` would re-render the whole page on every request.
+ */
+export const CLOCK_TOPIC = 'Clock';
+/**
+ * What every cached page render reads (#1751): any page can link, list or
+ * include pages, show configuration and name people, so each render depends
+ * on these. A plugin adds its own data with `context.dependsOn(topic)`.
+ */
+export const BASE_RENDER_TOPICS = [PAGE_DATA_TOPIC, CONFIG_DATA_TOPIC, USER_DATA_TOPIC];
+export default class CacheDependencies {
+    versionOf;
+    snapshots = new Map();
+    volatile = false;
+    constructor(versionOf) {
+        this.versionOf = versionOf;
+    }
+    /** This render reads `topic`'s data. Call it before reading. */
+    dependsOn(topic) {
+        if (topic && !this.snapshots.has(topic))
+            this.snapshots.set(topic, this.versionOf(topic));
+    }
+    /** This render's output changes on its own; do not store it. */
+    markVolatile() {
+        this.volatile = true;
+    }
+    isVolatile() {
+        return this.volatile;
+    }
+    /** Each declared topic with the version it had when declared. */
+    async resolved() {
+        const out = {};
+        for (const [topic, version] of this.snapshots)
+            out[topic] = await version;
+        return out;
+    }
+}

package/lib/src/cache/ICacheAdapter.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Cache Adapter Interface
+ *
+ * Defines the contract that all cache adapters must implement.
+ * This allows switching between different cache backends (node-cache, Redis, etc.)
+ * without changing application code.
+ */
+/**
+ * Cache statistics structure
+ */
+export interface CacheStats {
+    /** Number of cache hits */
+    hits: number;
+    /** Number of cache misses */
+    misses: number;
+    /** Number of keys in cache */
+    keys: number;
+    /** Approximate memory usage of keys in bytes */
+    ksize: number;
+    /** Approximate memory usage of values in bytes */
+    vsize: number;
+}
+/**
+ * Cache adapter interface
+ * All cache adapters must implement these methods
+ *
+ * @abstract
+ */
+declare abstract class ICacheAdapter {
+    /**
+     * Get a value from the cache
+     *
+     * @param {string} key - The cache key
+     * @returns {Promise<T|undefined>} The cached value or undefined if not found
+     */
+    abstract get<T = unknown>(key: string): Promise<T | undefined>;
+    /**
+     * Set a value in the cache
+     *
+     * @param {string} key - The cache key
+     * @param {unknown} value - The value to cache
+     * @param {number} [ttlSec] - Time to live in seconds
+     * @returns {Promise<void>}
+     */
+    abstract set(key: string, value: unknown, ttlSec?: number): Promise<void>;
+    /**
+     * Delete one or more keys from the cache
+     *
+     * @param {string|string[]} keys - Single key or array of keys to delete
+     * @returns {Promise<void>}
+     */
+    abstract del(keys: string | string[]): Promise<void>;
+    /**
+     * Clear cache entries
+     *
+     * @param {string} [pattern] - Optional pattern to match keys (e.g., 'user:*')
+     * @returns {Promise<void>}
+     */
+    abstract clear(pattern?: string): Promise<void>;
+    /**
+     * Get keys matching a pattern
+     *
+     * @param {string} pattern - Pattern to match (e.g., 'user:*' or '*' for all)
+     * @returns {Promise<string[]>} Array of matching keys
+     */
+    abstract keys(pattern?: string): Promise<string[]>;
+    /**
+     * Get cache statistics
+     *
+     * @returns {Promise<CacheStats>} Cache statistics
+     */
+    abstract stats(): Promise<CacheStats>;
+    /**
+     * Check if the cache adapter is healthy/connected
+     *
+     * @returns {Promise<boolean>} True if healthy
+     */
+    abstract isHealthy(): Promise<boolean>;
+    /**
+     * Close/cleanup the cache adapter
+     *
+     * @returns {Promise<void>}
+     */
+    abstract close(): Promise<void>;
+}
+export default ICacheAdapter;