{"version":3,"file":"cache_error_handler.mjs","sources":["../../../src/private/utils/cache_error_handler.ts"],"sourcesContent":["/**\n * Process-wide registration + dispatch for the relation-cache error handler\n * (`onRelationsCacheError`, ADR-009). Holds the host-supplied default handler and\n * reports every runtime cache-infra/serialization failure to the effective\n * handler (per-model → process-wide default → no-op), guarded and never awaited\n * so a reporter can neither throw into nor delay a load/write.\n *\n * Defaults to a **no-op** so the package stays dependency-neutral — it never\n * imports a logger; the host wires `onRelationsCacheError` to its own logger /\n * Sentry / metrics (or nothing).\n *\n * @module @nhtio/lucid-resourceful/private/utils/cache_error_handler\n */\n\nimport type { LucidModel } from '@adonisjs/lucid/types/model'\nimport type { E_RELATION_CACHE_OPERATION_FAILED } from '@nhtio/lucid-resourceful/errors'\n\n/**\n * Host-supplied observer invoked when a runtime relation-cache operation fails\n * (ADR-009). Observe-only: its return value is ignored — it cannot change the\n * fallback control flow — and a throw from it is swallowed.\n *\n * @public\n */\nexport type RelationsCacheErrorHandler = (error: E_RELATION_CACHE_OPERATION_FAILED) => void\n\n/**\n * Module-scoped holder for the process-wide default error handler. Set once at\n * boot by the host; read through the precedence chain when a model declares no\n * own `onRelationsCacheError`. A plain function reference, so — unlike the cache\n * service — there is nothing to memoize.\n * @internal\n */\nlet defaultRelationsCacheErrorHandler: RelationsCacheErrorHandler | null = null\n\n/**\n * Registers (or clears) the process-wide default relation-cache error handler.\n *\n * The host application calls this once at boot. Passing `null` clears the\n * default (used by tests). Models without their own `onRelationsCacheError` fall\n * back to this handler, and absent a default the built-in best-effort log is\n * used — so registering nothing is a valid (logged) configuration.\n *\n * @param handler - The default handler, or `null` to clear it.\n * @public\n */\nexport const setDefaultOnRelationsCacheError = (\n  handler: RelationsCacheErrorHandler | null\n): void => {\n  defaultRelationsCacheErrorHandler = handler\n}\n\n/**\n * Reads the currently-registered default handler. Exposed for completeness;\n * prefer {@link reportRelationCacheError}.\n *\n * @returns The default handler, or `null` when none is registered.\n * @internal\n */\nexport const getDefaultOnRelationsCacheError = (): RelationsCacheErrorHandler | null =>\n  defaultRelationsCacheErrorHandler\n\n/**\n * Clears the module-scoped default handler. Test-only hook: hosts must not call\n * this at runtime. Mirrors `resetRelationCacheTargets`.\n *\n * @public\n */\nexport const resetDefaultOnRelationsCacheError = (): void => {\n  defaultRelationsCacheErrorHandler = null\n}\n\n/**\n * Reports a runtime relation-cache failure to the effective handler (ADR-009).\n *\n * Resolves the handler by precedence — the model's own\n * `$resourcefulOnRelationsCacheError` → the process-wide default → no-op — then\n * invokes it SYNCHRONOUSLY inside a guard (a throwing handler is swallowed) and\n * does NOT await it (a returned promise is fire-and-forget), so a slow or failing\n * reporter can neither delay nor break the load. When no handler resolves the\n * failure is dropped (the package never logs on its own). The CALLER performs the\n * actual fallback (DB load / skip caching / continue the write); this function\n * only observes.\n *\n * @param model - The model whose handler should be consulted.\n * @param error - The typed relation-cache operational failure to report.\n */\nexport const reportRelationCacheError = (\n  model: LucidModel,\n  error: E_RELATION_CACHE_OPERATION_FAILED\n): void => {\n  const perModelHandler = (\n    model as LucidModel & { $resourcefulOnRelationsCacheError?: RelationsCacheErrorHandler }\n  ).$resourcefulOnRelationsCacheError\n  const handler = perModelHandler ?? defaultRelationsCacheErrorHandler\n  if (!handler) {\n    return\n  }\n  try {\n    handler(error)\n  } catch {\n    // ADR-009: a handler that itself throws must never escalate into the load/write.\n  }\n}\n"],"names":[],"mappings":"AAiCA,IAAI,oCAAuE;AAapE,MAAM,kCAAkC,CAC7C,YACS;AACT,sCAAoC;AACtC;AASO,MAAM,kCAAkC,MAC7C;AAQK,MAAM,oCAAoC,MAAY;AAC3D,sCAAoC;AACtC;AAiBO,MAAM,2BAA2B,CACtC,OACA,UACS;AACT,QAAM,kBACJ,MACA;AACF,QAAM,UAAU,mBAAmB;AACnC,MAAI,CAAC,SAAS;AACZ;AAAA,EACF;AACA,MAAI;AACF,YAAQ,KAAK;AAAA,EACf,QAAQ;AAAA,EAER;AACF;"}