@plumix/core 0.5.0 → 0.7.0

package/dist/rpc/meta/core.d.ts

@@ -1,6 +1,8 @@
 import type { SQLiteColumn } from "drizzle-orm/sqlite-core";
 import type { AppContext } from "../../context/app.js";
+import type { ReferenceHydrationShapes } from "../../plugin/lookup.js";
 import type { MetaBoxField } from "../../plugin/manifest.js";
+import type { FieldPipelineMode, MetaFieldError } from "./field-pipeline.js";
 type MetaMap = Record<string, unknown>;
 /**
  * Validated meta patch produced by `sanitizeMetaInput`. Values in
@@ -9,10 +11,9 @@ type MetaMap = Record<string, unknown>;
  * doesn't have to double-parse. `applyMetaPatch` JSON-encodes at the
  * last moment, before the UPDATE.
  *
- * `upserts` is mutable: `validateMetaReferences` rewrites values for
- * cached-object reference fields (`referenceTarget.valueShape ===
- * "object"`) to merge adapter-supplied cached fields into the
- * stored shape. Other callers should treat it as read-only.
+ * `upserts` is mutable: `validateMetaReferences` normalizes reference
+ * values to the plain-id storage form (a legacy `{ id, ... }` object
+ * self-heals to its id). Other callers should treat it as read-only.
  */
 export interface MetaPatch {
     readonly upserts: Map<string, unknown>;
@@ -44,11 +45,12 @@ export declare class MetaSanitizationError extends Error {
  * helper doesn't have to import oRPC types — the handler passes its
  * `errors` in and TS matches on shape.
  */
-interface RpcErrorsForMeta {
+export interface RpcErrorsForMeta {
     CONFLICT: (args: {
         data: {
             reason: string;
             key?: string;
+            errors?: MetaFieldError[];
         };
     }) => Error;
 }
@@ -61,19 +63,65 @@ export interface MetaChanges {
     readonly set: Readonly<Record<string, unknown>>;
     readonly removed: readonly string[];
 }
+/**
+ * The whole-patch rejection produced by `sanitizeMetaInput` when any
+ * field's pipeline reports errors: every `{ path, message }` across
+ * every key of the request, so the admin form can address each
+ * offending input in one round-trip. Nothing is written when this
+ * throws.
+ */
+export declare class MetaValidationError extends Error {
+    readonly errors: readonly MetaFieldError[];
+    constructor(errors: readonly MetaFieldError[]);
+}
 /**
  * Validate an incoming meta map against a field-lookup fn produced by
  * the caller (entry vs term differ only in which registry they walk).
- * Unregistered keys and type-coercion failures throw so the caller can
- * surface them as 4xx before any write. `null` / `undefined` values
- * are deletion requests; everything else is coerced + sanitized.
+ * `null` / `undefined` values are deletion requests; everything else
+ * runs the per-field pipeline (coercion → `.sanitize()` → declarative
+ * constraints → `.validate()`). Pipeline rejections aggregate across
+ * the whole patch into one `MetaValidationError`; unregistered keys
+ * and oversized values keep the legacy fail-fast
+ * `MetaSanitizationError` surface.
+ */
+export declare function sanitizeMetaInput(findField: (key: string) => MetaBoxField | undefined, input: MetaMap | undefined, mode?: FieldPipelineMode): Promise<MetaPatch | null>;
+/**
+ * Thin wrapper that translates thrown meta errors into the RPC
+ * handler's CONFLICT envelope. Pipeline rejections ship their
+ * `{ path, message }` list under `data.errors` (with `key` pointing
+ * at the first error's top-level field for legacy consumers); the
+ * fail-fast `MetaSanitizationError` reasons keep their existing
+ * `data.reason`/`data.key` shape.
+ */
+/**
+ * Map a whole-patch meta validation failure onto the RPC `CONFLICT`
+ * envelope — one place so the wire shape (`key` at the first error's
+ * top-level field, the full `errors` list) can't drift between the write
+ * path and the publish gate.
  */
-export declare function sanitizeMetaInput(findField: (key: string) => MetaBoxField | undefined, input: MetaMap | undefined): MetaPatch | null;
+export declare function metaValidationConflict(error: MetaValidationError, errors: RpcErrorsForMeta): Error;
+export declare function sanitizeMetaForRpc(findField: (key: string) => MetaBoxField | undefined, input: MetaMap | undefined, errors: RpcErrorsForMeta, mode?: FieldPipelineMode): Promise<MetaPatch | null>;
 /**
- * Thin wrapper that translates a thrown `MetaSanitizationError` into
- * the RPC handler's CONFLICT envelope.
+ * Strict publish gate: validate a whole *stored* meta bag against the full
+ * field list before `entry.publish` promotes it onto the live row. Draft
+ * autosaves are lenient (business rules skipped so work-in-progress always
+ * saves), so publish is where required fields, bounds, formats, option
+ * membership, and row counts are finally enforced. It walks the field
+ * *definitions*, not just the bag, so a required field ABSENT from the bag
+ * is caught as well as one stored empty — `runFieldPipeline` sees
+ * `undefined` and rejects it in strict mode.
+ *
+ * Rejections aggregate across the bag into one `MetaValidationError` the
+ * RPC layer maps onto the admin inputs, blocking the publish. A passing bag
+ * comes back canonicalized (each registered value re-run through
+ * `.sanitize()`); a conditionally-hidden field can't be required, so it's
+ * skipped; keys the field system doesn't own (e.g. from an uninstalled
+ * plugin) pass through untouched, matching the read path. Field
+ * capabilities and reference existence are not re-checked here — a
+ * whole-bag gate would block a publisher over a co-author's field, and both
+ * were already enforced at write time.
  */
-export declare function sanitizeMetaForRpc(findField: (key: string) => MetaBoxField | undefined, input: MetaMap | undefined, errors: RpcErrorsForMeta): MetaPatch | null;
+export declare function validateAndPromoteMetaBag(fields: readonly MetaBoxField[], bag: Readonly<Record<string, unknown>>): Promise<Record<string, unknown>>;
 /**
  * Walk a sanitized patch, group every reference upsert by
  * `(kind, scope)`, and issue one `LookupAdapter.list({ ids })`
@@ -88,7 +136,7 @@ export declare function sanitizeMetaForRpc(findField: (key: string) => MetaBoxFi
  * TOCTOU note: validate runs in a separate query from the eventual
  * `applyMetaPatch`, and callers don't share a transaction. A
  * concurrent delete between validate and apply leaves an orphan id
- * in the meta bag; `filterMetaOrphans` masks it on read. Wrap the
+ * in the meta bag; `hydrateMetaBags` masks it on read. Wrap the
  * validate/apply pair in `ctx.db.transaction()` if a caller needs
  * serializable consistency.
  */
@@ -100,7 +148,37 @@ export declare function validateMetaReferences(ctx: AppContext, findField: (key:
  * same `meta_invalid_value` error surface authors already match on.
  */
 export declare function validateMetaReferencesForRpc(ctx: AppContext, findField: (key: string) => MetaBoxField | undefined, patch: MetaPatch, errors: RpcErrorsForMeta): Promise<void>;
-export declare function filterMetaOrphans(ctx: AppContext, findField: (key: string) => MetaBoxField | undefined, decoded: MetaMap): Promise<MetaMap>;
+/**
+ * A decoded meta bag plus the field lookup that scopes it — the unit
+ * `hydrateMetaBags` operates on. Multi-entity responses pass one per
+ * entity so ids aggregate across the whole response.
+ */
+export interface HydratableBag {
+    readonly findField: (key: string) => MetaBoxField | undefined;
+    readonly decoded: MetaMap;
+}
+/** Single-bag convenience over {@link hydrateMetaBags}. */
+export declare function hydrateMetaReferences(ctx: AppContext, findField: (key: string) => MetaBoxField | undefined, decoded: MetaMap): Promise<MetaMap>;
+export declare function hydrateMetaBags(ctx: AppContext, bags: readonly HydratableBag[]): Promise<MetaMap[]>;
+/**
+ * Batched, tag-accounted hydration of a raw id set for one reference kind
+ * — the theme-facing counterpart to the meta pipeline's hydration (#1508).
+ * A theme holding an id-only reference field (a field declared
+ * `.returns("id")`, or one contributed by a third-party plugin) resolves
+ * it here instead of hand-rolled per-item fetches: ids resolve through the
+ * adapter's batched `hydrate` (chunked, one in-query per chunk) and every
+ * resolved entity folds its cache tag into the page through the same
+ * accumulator the meta pipeline uses, so the page is purged when an
+ * embedded entity changes.
+ *
+ * Returns the hydrated payloads dense and in the requested id order — ids
+ * that are gone or out of scope are dropped, mirroring multi-reference
+ * field hydration. An unregistered kind, an adapter without the `hydrate`
+ * contract, or an empty id set yields `[]`.
+ */
+export declare function hydrateReferences<K extends keyof ReferenceHydrationShapes>(ctx: AppContext, kind: K, ids: readonly string[], options?: {
+    readonly scope?: unknown;
+}): Promise<ReferenceHydrationShapes[K][]>;
 /**
  * Decode a raw meta bag (as returned by drizzle's JSON-mode column)
  * into the plugin-typed shape RPC consumers expect. Unregistered keys

package/dist/rpc/meta/core.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../../src/rpc/meta/core.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../../src/rpc/meta/core.ts"],"names":[],"mappings":"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"}