@plumix/core 0.1.0

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

@@ -0,0 +1,132 @@
+import type { SQLiteColumn } from "drizzle-orm/sqlite-core";
+import type { AppContext } from "../../context/app.js";
+import type { MetaBoxField } from "../../plugin/manifest.js";
+type MetaMap = Record<string, unknown>;
+/**
+ * Validated meta patch produced by `sanitizeMetaInput`. Values in
+ * `upserts` are the *decoded* post-sanitization objects — filter hooks
+ * see this shape, so keeping decoded values here means a plugin
+ * 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.
+ */
+export interface MetaPatch {
+    readonly upserts: Map<string, unknown>;
+    readonly deletes: readonly string[];
+}
+/**
+ * Reason codes are part of the RPC error `data.reason` surface — admin
+ * UIs and plugin tests match on these strings, so treat them as a
+ * public contract.
+ */
+type MetaSanitizationReason = "not_registered" | "invalid_value" | "value_too_large";
+export declare class MetaSanitizationError extends Error {
+    readonly key: string;
+    readonly reason: MetaSanitizationReason;
+    private constructor();
+    static notRegistered(ctx: {
+        key: string;
+    }): MetaSanitizationError;
+    static invalidValue(ctx: {
+        key: string;
+    }): MetaSanitizationError;
+    static valueTooLarge(ctx: {
+        key: string;
+    }): MetaSanitizationError;
+}
+/**
+ * Minimum shape of the oRPC `errors` object needed to surface a
+ * `MetaSanitizationError` as a CONFLICT. Declared structurally so this
+ * helper doesn't have to import oRPC types — the handler passes its
+ * `errors` in and TS matches on shape.
+ */
+interface RpcErrorsForMeta {
+    CONFLICT: (args: {
+        data: {
+            reason: string;
+            key?: string;
+        };
+    }) => Error;
+}
+/**
+ * Standard payload for `<entity>:meta_changed` actions. `set` is the
+ * decoded key → value map of upserts; `removed` is the list of
+ * cleared keys.
+ */
+export interface MetaChanges {
+    readonly set: Readonly<Record<string, unknown>>;
+    readonly removed: readonly string[];
+}
+/**
+ * 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.
+ */
+export declare function sanitizeMetaInput(findField: (key: string) => MetaBoxField | undefined, input: MetaMap | undefined): MetaPatch | null;
+/**
+ * Thin wrapper that translates a thrown `MetaSanitizationError` into
+ * the RPC handler's CONFLICT envelope.
+ */
+export declare function sanitizeMetaForRpc(findField: (key: string) => MetaBoxField | undefined, input: MetaMap | undefined, errors: RpcErrorsForMeta): MetaPatch | null;
+/**
+ * Walk a sanitized patch, group every reference upsert by
+ * `(kind, scope)`, and issue one `LookupAdapter.list({ ids })`
+ * query per group to confirm all upserted IDs are real and in
+ * scope **at validation time**. Throws `invalid_value` for any id
+ * missing from its group's live-id set — same surface whether the
+ * adapter is unregistered, the target is gone, or scope rejected
+ * it. Sync `sanitize` callbacks can't run DB queries, so this is a
+ * separate async step the RPC procedures invoke between
+ * sanitisation and `applyMetaPatch`.
+ *
+ * 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
+ * validate/apply pair in `ctx.db.transaction()` if a caller needs
+ * serializable consistency.
+ */
+export declare function validateMetaReferences(ctx: AppContext, findField: (key: string) => MetaBoxField | undefined, patch: MetaPatch): Promise<void>;
+/**
+ * RPC-shaped wrapper around `validateMetaReferences` — same envelope
+ * translation as `sanitizeMetaForRpc`. Procedures call this right
+ * after `sanitizeMetaForRpc` so reference validation rides on the
+ * 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>;
+/**
+ * Decode a raw meta bag (as returned by drizzle's JSON-mode column)
+ * into the plugin-typed shape RPC consumers expect. Unregistered keys
+ * pass through untouched — the row exists in the DB but the plugin
+ * that wrote it is no longer installed; we don't pretend to know its
+ * shape.
+ */
+export declare function decodeMetaBag(findField: (key: string) => MetaBoxField | undefined, raw: Readonly<Record<string, unknown>> | null | undefined): MetaMap;
+export declare function isEmptyMetaPatch(patch: MetaPatch | null): boolean;
+/**
+ * Merge a validated patch into the given `meta` JSON column for the
+ * row identified by `idColumn = id`. Uses SQLite `json_set` /
+ * `json_remove` so concurrent updaters touching disjoint keys don't
+ * clobber each other at the row level. Deletes nest inside sets so a
+ * caller clearing + re-setting the same key in one request behaves
+ * predictably.
+ */
+export declare function applyMetaPatch<TTable extends {
+    meta: SQLiteColumn;
+}>(ctx: AppContext, table: TTable, idColumn: SQLiteColumn, id: number, patch: MetaPatch): Promise<void>;
+/**
+ * Load + decode the full meta bag for a single row. Returns empty
+ * when the row is missing (deleted mid-flight) or has no saved meta.
+ */
+export declare function loadMeta<TTable extends {
+    meta: SQLiteColumn;
+}>(ctx: AppContext, table: TTable, idColumn: SQLiteColumn, id: number, findField: (key: string) => MetaBoxField | undefined): Promise<MetaMap>;
+export {};
+//# sourceMappingURL=core.d.ts.map

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

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