@plumix/core 0.5.0 → 0.7.0

package/dist/plugin/lookup.d.ts

@@ -20,16 +20,59 @@ export interface LookupResult {
     readonly targetType?: string;
     readonly subtitle?: string;
     /**
-     * Adapter-provided cached fields. When the field's
-     * `referenceTarget.valueShape === "object"`, the meta pipeline
-     * merges these into the stored value on every write so reads can
-     * render without a resolve round-trip. Examples: `mime`,
-     * `filename` for media; could be `width`/`height` later.
-     *
-     * Picker UIs may also read `cached` to render preview thumbnails
-     * (e.g. `cached.mime` to decide image vs file icon).
+     * Public URL for the row, when it has one — entry permalink, term
+     * archive. Read-time consumers (menu resolution) render links from
+     * it; adapters whose rows have no public URL omit it.
      */
-    readonly cached?: Readonly<Record<string, unknown>>;
+    readonly href?: string;
+}
+/**
+ * Minimum shape of a batched-hydration payload. `id` is the stored
+ * reference id (string form) so a hydrated value posted back through
+ * a meta write self-heals to the plain id — the same `{ id, ... }`
+ * extraction that migrates legacy snapshot values.
+ */
+export interface HydratedReference {
+    readonly id: string;
+}
+export interface LookupHydrateOptions<TScope = unknown> {
+    readonly ids: readonly string[];
+    readonly scope?: TScope;
+}
+/**
+ * Read-shape registry for reference kinds, keyed by adapter `kind`.
+ * Core declares its own kinds; plugins augment via declaration
+ * merging (`declare module "plumix/plugin"`), so the typed-meta layer
+ * can resolve a reference field's hydrated value without core knowing
+ * plugin-provided kinds.
+ */
+export interface ReferenceHydrationShapes {
+    readonly entry: EntryReferenceSummary;
+    readonly term: TermReferenceSummary;
+    readonly user: UserReferenceSummary;
+}
+/** Hydrated shape of an `entry` reference — enough to render a link. */
+export interface EntryReferenceSummary extends HydratedReference {
+    readonly type: string;
+    /** `null` mirrors `LookupResult.label`: no human-authored title. */
+    readonly title: string | null;
+    readonly slug: string;
+    /** Permalink; `null` when the entry has no public URL. */
+    readonly url: string | null;
+}
+/** Hydrated shape of a `term` reference. */
+export interface TermReferenceSummary extends HydratedReference {
+    readonly taxonomy: string;
+    readonly name: string;
+    readonly slug: string;
+    /** Archive URL; `null` for private taxonomies / nested terms. */
+    readonly url: string | null;
+}
+/** Hydrated shape of a `user` reference — public-safe columns only. */
+export interface UserReferenceSummary extends HydratedReference {
+    readonly name: string | null;
+    readonly slug: string;
+    readonly avatarUrl: string | null;
 }
 export interface LookupListOptions<TScope = unknown> {
     readonly query?: string;
@@ -54,7 +97,7 @@ export interface LookupListOptions<TScope = unknown> {
  * Two methods, one round-trip per call regardless of selection size:
  *  - `list` covers search/browse (no `ids`, optional `query`) and
  *    resolve-by-id batch (`ids` set, `query` ignored). The meta
- *    pipeline (`validateMetaReferences` + `filterMetaOrphans`)
+ *    pipeline (`validateMetaReferences` + `hydrateMetaBags`)
  *    groups all reference fields by `(kind, scope)` and issues one
  *    `list({ ids })` per group, eliminating per-field N+1 on both
  *    reads and writes. The `MultiReferencePicker` batches the same
@@ -67,6 +110,27 @@ export interface LookupAdapter<TScope = unknown> {
     list(ctx: AppContext, options: LookupListOptions<TScope>): Promise<readonly LookupResult[]>;
     /** Returns `null` when the target is gone or no longer matches scope (orphan). */
     resolve(ctx: AppContext, id: string, scope?: TScope): Promise<LookupResult | null>;
+    /**
+     * Batched read-time hydration: resolve `ids` (subject to `scope`)
+     * into this kind's hydrated shape (`ReferenceHydrationShapes[kind]`)
+     * in one query. Ids that are gone or out of scope are simply absent
+     * from the result — the meta pipeline reads absence as an orphan.
+     * Optional: kinds without it read as plain ids (orphan-stripped via
+     * `list({ ids })`, the pre-hydration behavior).
+     */
+    hydrate?(ctx: AppContext, options: LookupHydrateOptions<TScope>): Promise<readonly HydratedReference[]>;
+    /**
+     * Cache tags a hydrated payload contributes to the page that embeds it,
+     * so editing or deleting the referenced entity purges the pages that
+     * hydrated it (#1508). Called once per hydrated payload during
+     * read-time hydration; the tags fold into the embedding page's stored
+     * cache tags. Return the same tag the entity's own purge enqueues —
+     * the entry adapter returns `e:<id>`, the precise per-entity tag. Kinds
+     * whose entities carry no per-entity purge identity (e.g. `user`) omit
+     * this method; their references embed without a cache-tag dependency.
+     * Optional.
+     */
+    embeddedCacheTags?(payload: HydratedReference): readonly string[];
 }
 export interface RegisteredLookupAdapter<TScope = unknown> extends LookupAdapterOptions<TScope> {
     readonly kind: string;

package/dist/plugin/lookup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lookup.d.ts","sourceRoot":"","sources":["../../src/plugin/lookup.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AASpD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B;;;;;;;OAOG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;;;;;;OASG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACrD;AAED,MAAM,WAAW,iBAAiB,CAAC,MAAM,GAAG,OAAO;IACjD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;;;;OAQG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,aAAa,CAAC,MAAM,GAAG,OAAO;IAC7C,IAAI,CACF,GAAG,EAAE,UAAU,EACf,OAAO,EAAE,iBAAiB,CAAC,MAAM,CAAC,GACjC,OAAO,CAAC,SAAS,YAAY,EAAE,CAAC,CAAC;IAEpC,kFAAkF;IAClF,OAAO,CACL,GAAG,EAAE,UAAU,EACf,EAAE,EAAE,MAAM,EACV,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;CACjC;AAMD,MAAM,WAAW,uBAAuB,CACtC,MAAM,GAAG,OAAO,CAChB,SAAQ,oBAAoB,CAAC,MAAM,CAAC;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACxC;;;;;;;;OAQG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CACtC;AAED,MAAM,WAAW,oBAAoB,CAAC,MAAM,GAAG,OAAO;IACpD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACxC,iFAAiF;IACjF,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACrC"}
+{"version":3,"file":"lookup.d.ts","sourceRoot":"","sources":["../../src/plugin/lookup.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AASpD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B;;;;;;;OAOG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,oBAAoB,CAAC,MAAM,GAAG,OAAO;IACpD,QAAQ,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,KAAK,EAAE,qBAAqB,CAAC;IACtC,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;IACpC,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;CACrC;AAED,wEAAwE;AACxE,MAAM,WAAW,qBAAsB,SAAQ,iBAAiB;IAC9D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,oEAAoE;IACpE,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,0DAA0D;IAC1D,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED,4CAA4C;AAC5C,MAAM,WAAW,oBAAqB,SAAQ,iBAAiB;IAC7D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,iEAAiE;IACjE,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED,uEAAuE;AACvE,MAAM,WAAW,oBAAqB,SAAQ,iBAAiB;IAC7D,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CACnC;AAED,MAAM,WAAW,iBAAiB,CAAC,MAAM,GAAG,OAAO;IACjD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;;;;OAQG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,aAAa,CAAC,MAAM,GAAG,OAAO;IAC7C,IAAI,CACF,GAAG,EAAE,UAAU,EACf,OAAO,EAAE,iBAAiB,CAAC,MAAM,CAAC,GACjC,OAAO,CAAC,SAAS,YAAY,EAAE,CAAC,CAAC;IAEpC,kFAAkF;IAClF,OAAO,CACL,GAAG,EAAE,UAAU,EACf,EAAE,EAAE,MAAM,EACV,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;IAEhC;;;;;;;OAOG;IACH,OAAO,CAAC,CACN,GAAG,EAAE,UAAU,EACf,OAAO,EAAE,oBAAoB,CAAC,MAAM,CAAC,GACpC,OAAO,CAAC,SAAS,iBAAiB,EAAE,CAAC,CAAC;IAEzC;;;;;;;;;;OAUG;IACH,iBAAiB,CAAC,CAAC,OAAO,EAAE,iBAAiB,GAAG,SAAS,MAAM,EAAE,CAAC;CACnE;AAMD,MAAM,WAAW,uBAAuB,CACtC,MAAM,GAAG,OAAO,CAChB,SAAQ,oBAAoB,CAAC,MAAM,CAAC;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACxC;;;;;;;;OAQG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CACtC;AAED,MAAM,WAAW,oBAAoB,CAAC,MAAM,GAAG,OAAO;IACpD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACxC,iFAAiF;IACjF,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACrC"}