import { Pool } from 'pg'; /** * Widget link URN + resolver. * * Background: widgets stored link URLs as plain strings, baked at edit * time. When the underlying entity's URL key changed (rename a category, * change a page's slug, etc.) every widget linking to it broke. URNs * keep stable references in storage and let us resolve to the current * URL at request time, with per-request batching so a page with N * internal links does at most one query per kind. * * Format: standard EverShop URN — `urn:evershop:::`, * built and parsed via `UrnService`. id is uuid for product/category/page, * code for collection. Plain URLs (custom or pre-URN saved settings) pass * through unchanged. * * Extensibility: third-party modules register loaders for their types via * `registerLinkLoader('blog', 'post', factory)` in their bootstrap, after * also calling `registerUrnSchema()` for the same (service, type) pair. */ /** Loader contract: given a batch of ids of one kind, return URLs (or null) in the same order. */ export type LinkBatchFn = (ids: readonly string[], pool: Pool) => Promise<(string | null)[]>; export type LinkLoader = { load: (id: string) => Promise; }; export type LinkLoaderFactory = (pool: Pool) => LinkLoader; /** Loaders keyed by `${service}:${type}` to match the URN registry's composite key. */ export type LinkLoaders = Record; /** * Build a loader factory from a batch function. Convenience wrapper so * extensions don't need to think about queueing. * * registerLinkLoader('blog', 'post', linkLoaderFromBatch(async (uuids, pool) => { * const rows = await select('uuid', 'slug').from('blog_post') * .where('uuid', 'IN', [...uuids]).execute(pool); * const m = new Map(rows.map(r => [r.uuid, `/blog/${r.slug}`])); * return uuids.map(u => m.get(u) ?? null); * })); */ export declare function linkLoaderFromBatch(batchFn: LinkBatchFn): LinkLoaderFactory; /** * Register a custom link loader. Must be called from a module's * bootstrap (the value registry is locked once bootstrap completes). * The same (service, type) must also be registered with the URN * schema registry — otherwise URNs of that type fail to parse. */ export declare function registerLinkLoader(service: string, type: string, factory: LinkLoaderFactory): void; /** Build per-request loaders. Called by the GraphQL middleware once per request. */ export declare function createLinkLoaders(pool: Pool): LinkLoaders; /** * Resolve a stored link value to a current URL. Plain URLs pass through * unchanged; URNs go through their loader. Returns null when an internal * entity can't be found (so widgets can suppress the link). */ export declare function resolveLink(value: string | null | undefined, loaders: LinkLoaders | undefined): Promise;