/**
 * Process-wide registration + dispatch for the relation-cache EVENT hook
 * (`onRelationsCacheEvent`). The relation cache emits lifecycle events
 * (hit/miss/store/force/bypass/evict); the host decides what to do with them —
 * write to `@nhtio/logger` or Adonis' logger, push metrics, trace, or nothing.
 *
 * Defaults to a **no-op** so the package stays dependency-neutral: lucid-resourceful
 * never imports a logger of its own, and never bakes in an observability shape.
 *
 * @module @nhtio/lucid-resourceful/private/utils/cache_event_handler
 */
import type { LucidModel } from '@adonisjs/lucid/types/model';
/**
 * A relation-cache lifecycle event:
 * - `hit` — a related row was served from cache (no DB query).
 * - `miss` — a cache miss; the row was loaded from the DB.
 * - `store` — a freshly-loaded row was written back to the cache.
 * - `force` — a `forceLoad` bypassed the read and refreshed the entry.
 * - `bypass` — caching was skipped (filtering callback / uncacheable relation).
 * - `evict` — a write-through eviction (`deleteByTag`) ran on a target's write.
 *
 * @public
 */
export type RelationCacheEvent = 'hit' | 'miss' | 'store' | 'force' | 'bypass' | 'evict';
/**
 * Structured context for a relation-cache event. Fields are populated per event
 * (e.g. `tag`/`ttl` only on `store`, `tag` only on `evict`).
 *
 * @public
 */
export interface RelationCacheEventContext {
    /** Canonical identity name of the model the event concerns. */
    model: string;
    /** The relation name, when the event is tied to a specific relation load. */
    relation?: string;
    /** The cache lookup key, when applicable. */
    key?: string | null;
    /** The store / eviction tag, when applicable. */
    tag?: string | null;
    /** The entry TTL forwarded on a `store`, when configured. */
    ttl?: unknown;
}
/**
 * Host-supplied observer for relation-cache lifecycle events. Observe-only: its
 * return value is ignored and a throw from it is swallowed.
 *
 * @public
 */
export type RelationsCacheEventHandler = (event: RelationCacheEvent, context: RelationCacheEventContext) => void;
/**
 * Registers (or clears) the process-wide default relation-cache event handler.
 *
 * The host calls this once at boot; passing `null` clears it (used by tests).
 * Absent any handler the event is simply dropped — the package never logs on its
 * own.
 *
 * @param handler - The default event handler, or `null` to clear it.
 * @public
 */
export declare const setDefaultOnRelationsCacheEvent: (handler: RelationsCacheEventHandler | null) => void;
/**
 * Reads the currently-registered default event handler. Exposed for completeness;
 * prefer {@link reportRelationCacheEvent}.
 *
 * @returns The default handler, or `null` when none is registered.
 * @internal
 */
export declare const getDefaultOnRelationsCacheEvent: () => RelationsCacheEventHandler | null;
/**
 * Clears the module-scoped default event handler. Test-only hook: hosts must not
 * call this at runtime. Mirrors `resetRelationCacheTargets`.
 *
 * @public
 */
export declare const resetDefaultOnRelationsCacheEvent: () => void;
/**
 * Dispatches a relation-cache event to the effective handler — the model's own
 * `$resourcefulOnRelationsCacheEvent` → the process-wide default → no-op.
 *
 * Invoked SYNCHRONOUSLY inside a guard (a throwing handler is swallowed) and
 * never awaited, so a host observer can neither break nor delay a cache op. When
 * no handler resolves, this returns immediately (no logger, no allocation).
 *
 * @param model - The model whose handler should be consulted.
 * @param event - The lifecycle event that occurred.
 * @param context - Structured context for the event.
 */
export declare const reportRelationCacheEvent: (model: LucidModel, event: RelationCacheEvent, context: RelationCacheEventContext) => void;