Merge pull request #557 from dao-xyz/feat/canonical-open-dx

feat: canonical open DX improvements

Author: marcus-pousette

packages/clients/canonical/client/src/auto.ts

@@ -1,3 +1,4 @@
+import { getSchema } from "@dao-xyz/borsh";
 import type {
 	Address,
 	OpenOptions,
@@ -13,12 +14,31 @@ export type CanonicalOpenResult<T> = {
 	address?: Address;
 };
 
+/**
+ * Canonical open supports "proxy parents" (managed proxies returned by adapters),
+ * which are not instances of `Program`. This widens `OpenOptions.parent` so apps
+ * don't need `parent: proxy as any`.
+ */
+export type CanonicalOpenOptions<S extends Program<any>> = Omit<
+	OpenOptions<S>,
+	"parent"
+> & {
+	parent?: unknown;
+};
+
 export type CanonicalOpenAdapter<
 	S extends Program<any> = Program<any>,
 	T = unknown,
 > = {
 	name: string;
-	canOpen(program: Program<any>): program is S;
+	/**
+	 * Optional list of borsh @variant strings this adapter can open.
+	 * If `canOpen` is omitted, canonical open will match by comparing
+	 * `getSchema(program.constructor).variant` against these values.
+	 */
+	variant?: string;
+	variants?: string[];
+	canOpen?(program: Program<any>): program is S;
 	getKey?(program: S, options?: OpenOptions<S>): string | undefined;
 	open(ctx: {
 		program: S;
@@ -28,6 +48,41 @@ export type CanonicalOpenAdapter<
 	}): Promise<CanonicalOpenResult<T>>;
 };
 
+export const getProgramVariant = (program: Program<any>): string | undefined => {
+	if (!program || typeof program !== "object") return undefined;
+	try {
+		const schema = getSchema((program as any).constructor);
+		const variant = schema?.variant;
+		return typeof variant === "string" ? variant : undefined;
+	} catch {
+		return undefined;
+	}
+};
+
+export const createVariantAdapter = <
+	S extends Program<any> = Program<any>,
+	T = unknown,
+>(options: {
+	name: string;
+	variant: string | string[];
+	getKey?: (program: S, options?: OpenOptions<S>) => string | undefined;
+	open: CanonicalOpenAdapter<S, T>["open"];
+}): CanonicalOpenAdapter<S, T> => {
+	const variants = (
+		Array.isArray(options.variant) ? options.variant : [options.variant]
+	).map(String);
+	return {
+		name: options.name,
+		variants,
+		canOpen: (program: Program<any>): program is S => {
+			const candidate = getProgramVariant(program);
+			return !!candidate && variants.includes(candidate);
+		},
+		getKey: options.getKey,
+		open: options.open,
+	};
+};
+
 type ManagedProxy = {
 	parents: any[];
 	children: any[];

packages/clients/canonical/client/src/index.ts

@@ -2,8 +2,10 @@ export * from "./client.js";
 export type {
 	CanonicalOpenAdapter,
 	CanonicalOpenMode,
+	CanonicalOpenOptions,
 	CanonicalOpenResult,
 } from "./auto.js";
+export { createVariantAdapter, getProgramVariant } from "./auto.js";
 export * from "./service-worker.js";
 export * from "./window.js";
 export * from "./peerbit.js";

packages/clients/canonical/client/src/peerbit.ts

@@ -17,7 +17,9 @@ import type { Address, OpenOptions, ProgramClient } from "@peerbit/program";
 import {
 	type CanonicalOpenAdapter,
 	type CanonicalOpenMode,
+	type CanonicalOpenOptions,
 	createManagedProxy,
+	getProgramVariant,
 } from "./auto.js";
 import type { CanonicalChannel } from "./client.js";
 import type { CanonicalClient } from "./index.js";
@@ -242,7 +244,7 @@ export class PeerbitCanonicalClient {
 
 	async open<S extends Program<any>>(
 		storeOrAddress: S | Address,
-		openOptions: OpenOptions<S> = {},
+		openOptions: CanonicalOpenOptions<S> = {},
 	): Promise<S> {
 		const state = this.openState;
 		if (!state || state.adapters.length === 0) {
@@ -269,16 +271,29 @@ export class PeerbitCanonicalClient {
 		}
 
 		const program = storeOrAddress as Program<any>;
+		const programVariant = getProgramVariant(program);
 		const adapter = state.adapters.find((candidate) =>
-			candidate.canOpen(program),
+			typeof candidate.canOpen === "function"
+				? candidate.canOpen(program)
+				: !!programVariant &&
+					(candidate.variants ?? (candidate.variant ? [candidate.variant] : []))
+						.map(String)
+						.includes(programVariant),
 		);
 		if (!adapter) {
+			const knownVariants = state.adapters
+				.flatMap((candidate) =>
+					candidate.variants ?? (candidate.variant ? [candidate.variant] : []),
+				)
+				.filter((x): x is string => typeof x === "string" && x.length > 0);
 			throw new Error(
-				`No canonical adapter registered for ${program.constructor?.name ?? "program"}`,
+				`No canonical adapter registered for ${program.constructor?.name ?? "program"}${
+					programVariant ? ` (variant: '${programVariant}')` : ""
+				}${knownVariants.length ? `. Known variants: ${knownVariants.join(", ")}` : ""}`,
 			);
 		}
 
-		const key = adapter.getKey?.(program as any, openOptions);
+		const key = adapter.getKey?.(program as any, openOptions as OpenOptions<any>);
 		if (adapter.getKey && key === undefined) {
 			throw new Error(
 				`Canonical adapter '${adapter.name}' requires a cache key (adapter.getKey returned undefined)`,
@@ -306,21 +321,21 @@ export class PeerbitCanonicalClient {
 				if (openOptions?.parent) {
 					PeerbitCanonicalClient.attachParent(
 						existingProxy as any,
-						openOptions.parent,
+						openOptions.parent as any,
 					);
 				}
 				return existingProxy as S;
 			}
 		}
 
-		const peer = this as any as ProgramClient;
-		const openPromise = (async () => {
-			const result = await adapter.open({
-				program: program as any,
-				options: openOptions,
-				peer,
-				client: this.canonical,
-			});
+			const peer = this as any as ProgramClient;
+			const openPromise = (async () => {
+				const result = await adapter.open({
+					program: program as any,
+					options: openOptions as OpenOptions<any>,
+					peer,
+					client: this.canonical,
+				});
 
 			let managed: any;
 			managed = createManagedProxy(result.proxy as any, {
@@ -336,7 +351,7 @@ export class PeerbitCanonicalClient {
 
 			this.openState?.proxies.add(managed);
 			if (openOptions?.parent) {
-				PeerbitCanonicalClient.attachParent(managed, openOptions.parent);
+				PeerbitCanonicalClient.attachParent(managed, openOptions.parent as any);
 			}
 			return managed as S;
 		})();