@primafuture/contrib-kit-react 1.0.0

package/src/internal/adapter-registry-protocol.ts

@@ -0,0 +1,365 @@
+import type * as contribKitCore from "@primafuture/contrib-kit-core";
+
+import * as reactAdapterError from "../react-adapter-error.js";
+
+/** Lifecycle checkpoint spuštěný po každé user-observable registry operaci. */
+export type AdapterRegistryProtocolCheckpoint = () => void;
+
+/** Fáze, ve které validní, ale neaktivní registry odmítne novou práci. */
+export type AdapterRegistryAvailabilityPhase = "resolve" | "lifecycle";
+
+/** Cache-safe pre-subscribe token odvozený pouze z public snapshot stavu. */
+export type AdapterRegistrySnapshotToken = `${contribKitCore.ExtensionRegistryState}:${number}`;
+
+/**
+ * Read-once structural registry snapshot používaný budoucím React bridgem.
+ */
+export interface AdapterRegistryProtocolSnapshot {
+	/** Přesný raw receiver bez proxy unwrappingu nebo Core brand kontroly. */
+	readonly rawRegistry: object;
+	/** Neprázdná registry identita zachycená při vzniku snapshotu. */
+	readonly registryId: string;
+	/** Aktivní registry stav ověřený až po úplné shape validaci. */
+	readonly initialState: "active";
+	/** Stabilní reference public Core subscriber metody. */
+	readonly subscribe: contribKitCore.ExtensionRegistry["subscribe"];
+	/** Stabilní reference public Core snapshot selectoru. */
+	readonly createSnapshot: contribKitCore.ExtensionRegistry["createSnapshot"];
+	/** Stabilní reference public Core katalogového readu. */
+	readonly listContributions: contribKitCore.ExtensionRegistry["listContributions"];
+	/** Stabilní reference public Core resolved-view readu. */
+	readonly resolveContributions: contribKitCore.ExtensionRegistry["resolveContributions"];
+}
+
+/** Sdílený checkpoint pro capture bez existující lifecycle autority. */
+export function skipAdapterRegistryProtocolCheckpoint(): void {
+	// Samotná strukturální inspekce nemá adapter scope, který by mohla zneplatnit.
+}
+
+/**
+ * Vytvoří bezpečnou registry chybu bez vložení raw vstupu do detailů.
+ */
+function createRegistryProtocolError(
+	code: "REACT_REGISTRY_INVALID" | "REACT_REGISTRY_UNAVAILABLE",
+	phase: "configuration" | AdapterRegistryAvailabilityPhase,
+	message: string,
+	field: string,
+	cause?: unknown,
+	preserveCause = false,
+): reactAdapterError.ReactAdapterError {
+	return new reactAdapterError.ReactAdapterError(
+		code,
+		message,
+		preserveCause
+			? { cause, details: { field, phase } }
+			: { details: { field, phase } },
+	);
+}
+
+/**
+ * Ověří raw registry eligibility bez přijetí callable objektu jako registry.
+ */
+function requireRegistryObject(value: unknown): object {
+	if (typeof value !== "object" || value === null) {
+		throw createRegistryProtocolError(
+			"REACT_REGISTRY_INVALID",
+			"configuration",
+			"Registry must be a non-null object.",
+			"registry",
+		);
+	}
+
+	return value;
+}
+
+/**
+ * Načte jedno registry protocol pole právě jednou a následně ověří autoritu.
+ */
+function readRegistryProperty(
+	registry: object,
+	property:
+		| "registryId"
+		| "state"
+		| "subscribe"
+		| "createSnapshot"
+		| "listContributions"
+		| "resolveContributions",
+	checkpoint: AdapterRegistryProtocolCheckpoint,
+): unknown {
+	let value: unknown;
+	try {
+		value = Reflect.get(registry, property, registry);
+	} catch (cause: unknown) {
+		throw createRegistryProtocolError(
+			"REACT_REGISTRY_INVALID",
+			"configuration",
+			`Unable to read registry.${property}.`,
+			`registry.${property}`,
+			cause,
+			true,
+		);
+	}
+
+	checkpoint();
+	return value;
+}
+
+/**
+ * Ověří neprázdnou primitive registry identitu.
+ */
+function requireRegistryId(value: unknown, field: string): string {
+	if (typeof value !== "string" || value.length === 0) {
+		throw createRegistryProtocolError(
+			"REACT_REGISTRY_INVALID",
+			"configuration",
+			"Registry ID must be a non-empty string.",
+			field,
+		);
+	}
+
+	return value;
+}
+
+/**
+ * Ověří exact public registry state union bez rozhodnutí o dostupnosti.
+ */
+function requireRegistryState(value: unknown, field: string): contribKitCore.ExtensionRegistryState {
+	if (value !== "active" && value !== "disposing" && value !== "disposed") {
+		throw createRegistryProtocolError(
+			"REACT_REGISTRY_INVALID",
+			"configuration",
+			"Registry state is invalid.",
+			field,
+		);
+	}
+
+	return value;
+}
+
+/**
+ * Oddělí validní protocol shape od lifecycle dostupnosti nové práce.
+ */
+function requireRegistryAvailability(
+	state: contribKitCore.ExtensionRegistryState,
+	phase: AdapterRegistryAvailabilityPhase,
+): "active" {
+	if (state !== "active") {
+		throw createRegistryProtocolError(
+			"REACT_REGISTRY_UNAVAILABLE",
+			phase,
+			"Registry is not active.",
+			"registry.state",
+		);
+	}
+
+	return state;
+}
+
+/**
+ * Ověří callability jedné již read-once zachycené public Core metody.
+ */
+function requireRegistryMethod(value: unknown, field: string): (...args: readonly unknown[]) => unknown {
+	if (typeof value !== "function") {
+		throw createRegistryProtocolError(
+			"REACT_REGISTRY_INVALID",
+			"configuration",
+			`${field} must be callable.`,
+			field,
+		);
+	}
+
+	return value as (...args: readonly unknown[]) => unknown;
+}
+
+/**
+ * Zachytí úplný šestipolový registry protocol v normativním pořadí.
+ */
+export function captureAdapterRegistryProtocol(
+	value: unknown,
+	checkpoint: AdapterRegistryProtocolCheckpoint = skipAdapterRegistryProtocolCheckpoint,
+): AdapterRegistryProtocolSnapshot {
+	const rawRegistry = requireRegistryObject(value);
+	const registryId = readRegistryProperty(rawRegistry, "registryId", checkpoint);
+	const state = readRegistryProperty(rawRegistry, "state", checkpoint);
+	const subscribe = readRegistryProperty(rawRegistry, "subscribe", checkpoint);
+	const createSnapshot = readRegistryProperty(rawRegistry, "createSnapshot", checkpoint);
+	const listContributions = readRegistryProperty(rawRegistry, "listContributions", checkpoint);
+	const resolveContributions = readRegistryProperty(rawRegistry, "resolveContributions", checkpoint);
+
+	const validatedRegistryId = requireRegistryId(registryId, "registry.registryId");
+	const validatedState = requireRegistryState(state, "registry.state");
+	const validatedSubscribe = requireRegistryMethod(subscribe, "registry.subscribe");
+	const validatedCreateSnapshot = requireRegistryMethod(createSnapshot, "registry.createSnapshot");
+	const validatedListContributions = requireRegistryMethod(
+		listContributions,
+		"registry.listContributions",
+	);
+	const validatedResolveContributions = requireRegistryMethod(
+		resolveContributions,
+		"registry.resolveContributions",
+	);
+	const activeState = requireRegistryAvailability(validatedState, "resolve");
+
+	return Object.freeze({
+		rawRegistry,
+		registryId: validatedRegistryId,
+		initialState: activeState,
+		subscribe: validatedSubscribe as contribKitCore.ExtensionRegistry["subscribe"],
+		createSnapshot: validatedCreateSnapshot as contribKitCore.ExtensionRegistry["createSnapshot"],
+		listContributions: validatedListContributions as contribKitCore.ExtensionRegistry["listContributions"],
+		resolveContributions: validatedResolveContributions as contribKitCore.ExtensionRegistry["resolveContributions"],
+	});
+}
+
+/**
+ * Ověří jediný live state read existujícího protocol snapshotu.
+ */
+export function requireAdapterRegistryAvailable(
+	protocol: AdapterRegistryProtocolSnapshot,
+	phase: AdapterRegistryAvailabilityPhase,
+	checkpoint: AdapterRegistryProtocolCheckpoint = skipAdapterRegistryProtocolCheckpoint,
+): "active" {
+	const state = readRegistryProperty(protocol.rawRegistry, "state", checkpoint);
+	return requireRegistryAvailability(requireRegistryState(state, "registry.state"), phase);
+}
+
+/**
+ * Načte jedno pole public Core snapshotu právě jednou se zachovaným receiverem.
+ */
+function readSnapshotProperty(
+	snapshot: object,
+	property: "registryId" | "state" | "revision",
+	checkpoint: AdapterRegistryProtocolCheckpoint,
+): unknown {
+	let value: unknown;
+	try {
+		value = Reflect.get(snapshot, property, snapshot);
+	} catch (cause: unknown) {
+		throw createRegistryProtocolError(
+			"REACT_REGISTRY_INVALID",
+			"configuration",
+			`Unable to read registry snapshot ${property}.`,
+			`registry.createSnapshot().${property}`,
+			cause,
+			true,
+		);
+	}
+
+	checkpoint();
+	return value;
+}
+
+/**
+ * Ověří public Core snapshot objekt bez čtení dalších nebo neznámých polí.
+ */
+function requireSnapshotObject(value: unknown): object {
+	if (typeof value !== "object" || value === null) {
+		throw createRegistryProtocolError(
+			"REACT_REGISTRY_INVALID",
+			"configuration",
+			"Registry snapshot must be a non-null object.",
+			"registry.createSnapshot()",
+		);
+	}
+
+	return value;
+}
+
+/**
+ * Ověří revision použitelnou jako stabilní external-store version.
+ */
+function requireSnapshotRevision(value: unknown): number {
+	if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+		throw createRegistryProtocolError(
+			"REACT_REGISTRY_INVALID",
+			"configuration",
+			"Registry snapshot revision must be a non-negative safe integer.",
+			"registry.createSnapshot().revision",
+		);
+	}
+
+	return value;
+}
+
+/**
+ * Vytvoří cache-safe primitive pre-subscribe token z public Core snapshotu.
+ */
+export function createAdapterRegistrySnapshotToken(
+	protocol: AdapterRegistryProtocolSnapshot,
+	checkpoint: AdapterRegistryProtocolCheckpoint = skipAdapterRegistryProtocolCheckpoint,
+): AdapterRegistrySnapshotToken {
+	let candidate: unknown;
+	try {
+		candidate = Reflect.apply(protocol.createSnapshot, protocol.rawRegistry, []);
+	} catch (cause: unknown) {
+		throw createRegistryProtocolError(
+			"REACT_REGISTRY_INVALID",
+			"configuration",
+			"Registry snapshot creation failed.",
+			"registry.createSnapshot",
+			cause,
+			true,
+		);
+	}
+	checkpoint();
+
+	const snapshot = requireSnapshotObject(candidate);
+	const registryId = readSnapshotProperty(snapshot, "registryId", checkpoint);
+	const state = readSnapshotProperty(snapshot, "state", checkpoint);
+	const revision = readSnapshotProperty(snapshot, "revision", checkpoint);
+	const validatedRegistryId = requireRegistryId(
+		registryId,
+		"registry.createSnapshot().registryId",
+	);
+	const validatedState = requireRegistryState(
+		state,
+		"registry.createSnapshot().state",
+	);
+	const validatedRevision = requireSnapshotRevision(revision);
+
+	if (validatedRegistryId !== protocol.registryId) {
+		throw createRegistryProtocolError(
+			"REACT_REGISTRY_INVALID",
+			"configuration",
+			"Registry snapshot ID does not match the captured registry.",
+			"registry.createSnapshot().registryId",
+		);
+	}
+
+	return `${validatedState}:${validatedRevision}`;
+}
+
+/**
+ * Zavolá zachycenou subscriber metodu s původní raw registry jako receiverem.
+ */
+export function subscribeAdapterRegistry(
+	protocol: AdapterRegistryProtocolSnapshot,
+	listener: contribKitCore.RegistrySubscriber,
+): unknown {
+	return Reflect.apply(protocol.subscribe, protocol.rawRegistry, [listener]);
+}
+
+/**
+ * Zavolá zachycený katalogový read s původní raw registry jako receiverem.
+ */
+export function listAdapterRegistryContributions<
+	Point extends contribKitCore.AnyExtensionPoint,
+>(
+	protocol: AdapterRegistryProtocolSnapshot,
+	point: Point,
+): unknown {
+	return Reflect.apply(protocol.listContributions, protocol.rawRegistry, [point]);
+}
+
+/**
+ * Zavolá zachycený resolved-view read s původní raw registry jako receiverem.
+ */
+export function resolveAdapterRegistryContributions<
+	Point extends contribKitCore.AnyExtensionPoint,
+>(
+	protocol: AdapterRegistryProtocolSnapshot,
+	point: Point,
+	context: contribKitCore.ExtensionPointContext<Point>,
+): unknown {
+	return Reflect.apply(protocol.resolveContributions, protocol.rawRegistry, [point, context]);
+}