@unbound-app/api 0.11.0 → 1.1.1

package/testing/fake-metro.ts

@@ -0,0 +1,346 @@
+import * as React from 'react';
+
+import type { AnyObject } from '../src/patcher';
+
+import { createFakeReactNative } from './fake-react-native';
+import { createFakeComponents } from './fake-components';
+
+/** A module the fake metro serves: the exports a plugin finds. */
+export type FakeModule = AnyObject;
+
+/** A fake metro filter. `path` marks a file-path filter, which matches the path a module was registered under. */
+export type FakeFilter = ((module: FakeModule) => boolean) & { path?: string };
+
+type LazyOptions = {
+	signal?: AbortSignal;
+};
+
+type FindOptions = {
+	lazy?: boolean;
+	all?: boolean;
+};
+
+type FindAll = { all: true };
+
+type Presence = 'loaded' | 'missing';
+
+const LAZY_MARKER = '__METRO_LAZY__';
+
+// The props each `metro.common` member is found by, as in the client's metro/common.ts.
+const COMMON_PROPS = {
+	Reanimated: ['useAnimatedStyle', 'useSharedValue'],
+	Gestures: ['PanGestureHandler'],
+	Clipboard: ['setString', 'getString', 'setImage', 'getImage'],
+	MarkdownParser: ['parse', 'parseToAST', 'reactParserFor'],
+	Screens: ['FullWindowOverlay'],
+	SVG: ['Svg', 'Path'],
+	Commands: ['getBuiltInCommands'],
+	Moment: ['isMoment'],
+	Util: ['inspect'],
+	Assets: ['registerAsset'],
+	ImageSources: ['getImageSourcesFromImageProps'],
+	Clyde: ['createBotMessage'],
+	Constants: ['Fonts', 'Endpoints'],
+	Radius: ['Radius'],
+	Theme: ['colors', 'internal'],
+	REST: ['getAPIBaseURL'],
+	i18n: ['getLanguages', 'getSystemLocale', 'intl'],
+};
+
+// The props each `metro.api` member is found by, as in the client's metro/api.ts.
+const API_PROPS = {
+	Messages: ['sendMessage', 'receiveMessage'],
+	Linking: ['openURL', 'openSettings'],
+	Profiles: ['showUserProfile'],
+	AsyncUsers: ['fetchProfile'],
+	Invites: ['acceptInviteAndTransitionToInviteChannel'],
+	OAuth2: ['openOAuth2Modal'],
+	ActionSheets: ['openLazy', 'hideActionSheet'],
+	UserProfiles: ['getUserProfileActionSheetKey', 'showUserProfileActionSheetPostConnection'],
+};
+
+/** What a lazy handle looks its module up by. */
+type LazyLookup = {
+	resolve: () => FakeModule | undefined;
+	filter: FakeFilter;
+};
+
+type Wait = {
+	filter: FakeFilter;
+	onLoad: (module: FakeModule) => void;
+};
+
+/** A metro over modules a test registers, with the finders and filters plugins call. */
+export type FakeMetro = {
+	/** Adds a module, settling any `findLazy` or `onModuleLoaded` waiting for it and calling `onModuleLoad` listeners. */
+	register: (module: FakeModule, path?: string) => void;
+	/** Forgets every registered module and waiting `findLazy` or `onModuleLoaded`, so a lazy handle made earlier finds only what is registered next. */
+	reset: () => void;
+	/** Discord's Flux stores, by the name `metro.stores` gives them, such as `Users`; the preset binds each to the seeded store. */
+	stores: Record<string, FakeModule>;
+	/** Discord's components: each module a bag of fake components that draw their children and are found by name, such as `Discord.Text`. */
+	components: FakeModule;
+	/** Discord's API modules, each a lazy handle found by the same props as on device, such as `Messages`. */
+	api: Record<keyof typeof API_PROPS, FakeModule>;
+	/** Discord's common modules, each a lazy handle found by the same props as on device, such as `Theme`; `React` and `ReactNative` are the fakes. */
+	common: Record<keyof typeof COMMON_PROPS, FakeModule> & {
+		React: FakeModule;
+		ReactNative: FakeModule;
+	};
+	filters: {
+		byProps: (...props: string[]) => FakeFilter;
+		byName: (name: string) => FakeFilter;
+		byDisplayName: (name: string) => FakeFilter;
+		byTypeName: (name: string) => FakeFilter;
+		byFilePath: (path: string) => FakeFilter;
+		all: (...parts: FakeFilter[]) => FakeFilter;
+		any: (...parts: FakeFilter[]) => FakeFilter;
+		not: (part: FakeFilter) => FakeFilter;
+	};
+	/** A lazy handle to the first registered module the filter matches, as on device; `lazy: false` gives the module now, and `all: true` every match now. */
+	find: {
+		(filter: FakeFilter, options: FindAll): FakeModule[];
+		(filter: FakeFilter, options?: FindOptions): FakeModule | undefined;
+	};
+	findByProps: (...args: (string | FindOptions)[]) => FakeModule | undefined;
+	findByName: (...args: (string | FindOptions)[]) => FakeModule | undefined;
+	findByFilePath: (...args: (string | FindOptions)[]) => FakeModule | undefined;
+	/** `loaded` once a registered module matches a lazy handle, `missing` before; `undefined` for anything else. */
+	// UNKNOWN: a plugin may pass any value, and only a lazy handle has a presence.
+	getModulePresence: (handle: unknown) => Presence | undefined;
+	findLazy: (
+		filter: FakeFilter,
+		options?: LazyOptions,
+	) => FakeModule | Promise<FakeModule | undefined>;
+	onModuleLoaded: (filter: FakeFilter, onLoad: (module: FakeModule) => void) => () => void;
+	/** Calls `onLoad` with the module a lazy handle finds, at once when one is registered, else when it registers; a plain object is passed at once. Returns what stops waiting. */
+	whenLoaded: (target: FakeModule, onLoad: (module: FakeModule) => void) => () => void;
+	onModuleLoad: (listener: (module: FakeModule) => void) => () => void;
+};
+
+function names(args: (string | FindOptions)[]): string[] {
+	return args.filter((arg) => typeof arg === 'string');
+}
+
+// The client rejects a file-path filter inside a combination, because it matches the raw module record, not exports.
+function assertCombinable(kind: 'all' | 'any' | 'not', part: FakeFilter) {
+	if (part.path !== undefined) {
+		throw new TypeError(
+			`Failed to combine filters: ${kind}() cannot take a raw filter such as byFilePath.`,
+		);
+	}
+}
+
+function isEager(args: (string | FindOptions)[]): boolean {
+	return args.some((arg) => typeof arg === 'object' && arg.lazy === false);
+}
+
+// A lookup the plugin makes while it loads, as on device: each access reads the module registered by then.
+function lazyHandle(resolve: () => FakeModule | undefined, description: string): FakeModule {
+	const current = () => resolve() ?? {};
+
+	return new Proxy<FakeModule>(
+		{},
+		{
+			get: (_target, key) => Reflect.get(current(), key),
+			has: (_target, key) => key in current(),
+			ownKeys: () => Reflect.ownKeys(current()),
+			getOwnPropertyDescriptor(_target, key) {
+				if (key === LAZY_MARKER) {
+					return { value: true, configurable: true };
+				}
+
+				const descriptor = Reflect.getOwnPropertyDescriptor(current(), key);
+
+				return descriptor && { ...descriptor, configurable: true };
+			},
+			set(_target, key, value) {
+				const module = resolve();
+
+				if (!module) {
+					throw new Error(
+						`Failed to set ${String(key)}: no module matches ${description}. Call metro.register() before the plugin starts.`,
+					);
+				}
+
+				return Reflect.set(module, key, value);
+			},
+		},
+	);
+}
+
+/**
+ * @description Creates a metro that finds only the modules a test registers.
+ * @returns The fake metro.
+ */
+export function createFakeMetro(): FakeMetro {
+	const modules: FakeModule[] = [];
+	const paths = new Map<FakeModule, string>();
+	const waits = new Set<Wait>();
+	const listeners = new Set<(module: FakeModule) => void>();
+
+	const filters: FakeMetro['filters'] = {
+		byProps:
+			(...props) =>
+			(module) =>
+				props.every((prop) => prop in module),
+		byName: (name) => (module) => 'name' in module && module.name === name,
+		byDisplayName: (name) => (module) => module.displayName === name,
+		byTypeName: (name) => (module) => module.type?.name === name,
+		byFilePath: (path) =>
+			Object.assign((module: FakeModule) => paths.get(module) === path, { path }),
+		all: (...parts) => {
+			for (const part of parts) assertCombinable('all', part);
+
+			return (module) => parts.every((part) => part(module));
+		},
+		any: (...parts) => {
+			for (const part of parts) assertCombinable('any', part);
+
+			return (module) => parts.some((part) => part(module));
+		},
+		not: (part) => {
+			assertCombinable('not', part);
+
+			return (module) => !part(module);
+		},
+	};
+
+	const handles = new WeakMap<FakeModule, LazyLookup>();
+
+	function first(filter: FakeFilter): FakeModule | undefined {
+		return modules.find((module) => filter(module));
+	}
+
+	function find(filter: FakeFilter, options: FindAll): FakeModule[];
+	function find(filter: FakeFilter, options?: FindOptions): FakeModule | undefined;
+	function find(filter: FakeFilter, options: FindOptions = {}) {
+		return lookup(filter, 'the filter', [options]);
+	}
+
+	function lookup(filter: FakeFilter, description: string, options: (string | FindOptions)[]) {
+		if (options.some((arg) => typeof arg === 'object' && arg.all)) {
+			return modules.filter((module) => filter(module));
+		}
+
+		if (isEager(options)) {
+			return first(filter);
+		}
+
+		const resolve = () => first(filter);
+		const handle = lazyHandle(resolve, description);
+
+		handles.set(handle, { resolve, filter });
+
+		return handle;
+	}
+
+	function handlesOf<T extends Record<string, string[]>>(namespace: string, byProps: T) {
+		return Object.fromEntries(
+			Object.entries(byProps).map(([name, props]) => [
+				name,
+				lookup(filters.byProps(...props), `metro.${namespace}.${name}`, []),
+			]),
+		) as Record<keyof T, FakeModule>;
+	}
+
+	function onModuleLoaded(filter: FakeFilter, onLoad: (module: FakeModule) => void) {
+		const found = first(filter);
+
+		if (found) {
+			onLoad(found);
+
+			return () => void 0;
+		}
+
+		const wait: Wait = { filter, onLoad };
+
+		waits.add(wait);
+
+		return () => void waits.delete(wait);
+	}
+
+	const common = {
+		...handlesOf('common', COMMON_PROPS),
+		React,
+		ReactNative: createFakeReactNative(),
+	};
+
+	return {
+		stores: {},
+		components: createFakeComponents(),
+		api: handlesOf('api', API_PROPS),
+		common,
+		filters,
+		find,
+		findByProps: (...args) =>
+			lookup(filters.byProps(...names(args)), `props ${names(args).join(', ')}`, args),
+		findByName: (...args) =>
+			lookup(filters.byName(names(args)[0]), `name ${names(args)[0]}`, args),
+		findByFilePath: (...args) =>
+			lookup(filters.byFilePath(names(args)[0]), `path ${names(args)[0]}`, args),
+		getModulePresence(handle) {
+			const lazy = typeof handle === 'object' && handle ? handles.get(handle) : undefined;
+
+			if (!lazy) return;
+
+			return lazy.resolve() ? 'loaded' : 'missing';
+		},
+		findLazy(filter, { signal } = {}) {
+			const found = first(filter);
+
+			if (found) {
+				return found;
+			}
+
+			return new Promise((resolve) => {
+				const wait: Wait = { filter, onLoad: resolve };
+
+				waits.add(wait);
+				signal?.addEventListener('abort', () => {
+					waits.delete(wait);
+					resolve(undefined);
+				});
+			});
+		},
+		onModuleLoaded,
+		onModuleLoad(listener) {
+			listeners.add(listener);
+
+			return () => void listeners.delete(listener);
+		},
+		whenLoaded(target, onLoad) {
+			const lazy = handles.get(target);
+
+			if (!lazy) {
+				onLoad(target);
+
+				return () => void 0;
+			}
+
+			return onModuleLoaded(lazy.filter, onLoad);
+		},
+		reset() {
+			modules.length = 0;
+			paths.clear();
+			waits.clear();
+			listeners.clear();
+		},
+		register(module, path) {
+			modules.push(module);
+
+			if (path !== undefined) {
+				paths.set(module, path);
+			}
+
+			for (const wait of waits) {
+				if (wait.filter(module)) {
+					waits.delete(wait);
+					wait.onLoad(module);
+				}
+			}
+
+			for (const listener of listeners) listener(module);
+		},
+	};
+}

package/testing/fake-native-bridge.ts

@@ -0,0 +1,98 @@
+import type { NativeCancelablePromise, NativeHandle } from '../src/native';
+
+/** One call a plugin made to a fake native bridge, in order. */
+export type NativeCall = {
+	bridge: 'objc' | 'java' | 'hooks';
+	/** The bridge member called, such as `invoke`. */
+	method: string;
+	/** The class the call reached, or `unknown` when the target is not a registered object. */
+	target: string;
+	/** The selector (Objective-C) or method or field name (Java), empty when the call has none. */
+	name: string;
+	args: unknown[];
+};
+
+/** The calls plugins made to the fake bridges since the last reset. */
+export type NativeCallLog = {
+	calls: NativeCall[];
+	record: (call: NativeCall) => void;
+};
+
+/**
+ * @description Creates the list the fake bridges append each call to.
+ * @returns The log.
+ */
+export function createCallLog(): NativeCallLog {
+	const calls: NativeCall[] = [];
+
+	return { calls, record: (call) => void calls.push(call) };
+}
+
+/**
+ * @description Wraps a settled call in the promise the bridge returns, which rejects when the call throws.
+ * @param run The call.
+ * @returns A promise with a `cancel` that does nothing, since the call has run.
+ */
+export function settled<T>(run: () => T): NativeCancelablePromise<T> {
+	let promise: Promise<T>;
+
+	try {
+		promise = Promise.resolve(run());
+	} catch (error) {
+		promise = Promise.reject(error);
+	}
+
+	return Object.assign(promise, { cancel: () => {} });
+}
+
+/**
+ * @description Gives a bridge the members a test did not fake as functions that throw naming the member, so a plugin reaching one fails loudly.
+ * @param name The bridge's name, such as `objc`.
+ * @param members The members the kit fakes.
+ * @returns The bridge.
+ */
+export function withMissingMembers<T extends object>(name: string, members: Partial<T>): T {
+	// UNKNOWN: the members are a partial bridge; the proxy answers the rest, so it has the whole bridge's shape.
+	return new Proxy(members, {
+		get(target, key, receiver) {
+			if (typeof key !== 'string' || key in target) {
+				return Reflect.get(target, key, receiver);
+			}
+
+			return () => {
+				throw new Error(
+					`Failed to call native.${name}.${key}: the test kit does not fake it. Pass your own with startPlugin({ native: { ${name}: { ${key} } } }).`,
+				);
+			};
+		},
+	}) as T;
+}
+
+/**
+ * @description Lays a test's own members over a fake bridge: a member the test gave wins, and every other one is the fake's.
+ * @template T The bridge type.
+ * @param base The fake bridge.
+ * @param overrides The members the test gave.
+ * @returns A new bridge, which a plugin sees in place of the fake.
+ */
+export function overlayBridge<T extends object>(base: T, overrides: Partial<T> = {}): T {
+	// A new object each time, so what a plugin keys by its bridge, such as cached class descriptions, starts empty for each start.
+	return new Proxy(base, {
+		get: (target, key, receiver) =>
+			Reflect.get(key in overrides ? overrides : target, key, receiver),
+		has: (target, key) => key in overrides || key in target,
+	});
+}
+
+/** Any fake object that stands for a native handle. */
+export type Brandable = { constructor: { name: string } };
+
+/**
+ * @description Types a fake's own object as the opaque handle a native bridge hands out, which has no runtime shape.
+ * @template T The handle type.
+ * @param value The fake object that stands for the handle.
+ * @returns The same object, as a handle.
+ */
+export function brand<T extends NativeHandle>(value: Brandable): T {
+	return value as T;
+}

package/testing/fake-native.ts

@@ -0,0 +1,211 @@
+import type {
+	NativePluginBridge,
+	NativePluginCapability,
+	NativePluginPlatform,
+	PluginContext,
+} from '../src/native';
+import type { AddonManifest } from '../src/global';
+import type { FakeModule } from './fake-metro';
+
+import { createCallLog, overlayBridge, type NativeCallLog } from './fake-native-bridge';
+import { createFakeJava, type FakeJava } from './fake-java';
+import { createFakeObjc, type FakeObjc } from './fake-objc';
+
+/** What `startPlugin` takes to build the `PluginContext` its `start` receives; the rest is filled in as the client would. */
+export type StartContext = Partial<Omit<PluginContext, 'native'>> & {
+	/** The bridge members the plugin calls; the others are empty objects. */
+	native?: Partial<NativePluginBridge>;
+};
+
+/** The fake `native` namespace's state, which a test sets through the `native` recorder. */
+export type NativeState = {
+	/** The host platform `definePlatform` selects by and `Platform.OS` reports; `ios` until a test sets it. */
+	platform: NativePluginPlatform;
+	/** The native modules `getNativeModule` finds, by name. */
+	modules: Map<string, unknown>;
+	/** The capabilities `native.has` reports. */
+	capabilities: NativePluginCapability[];
+};
+
+/** The fake `native`, its state, and the `PluginContext` builder. */
+export type FakeNative = {
+	namespace: FakeModule;
+	state: NativeState;
+	/** The fake Objective-C bridge a plugin gets as `context.native.objc` on iOS. */
+	objc: FakeObjc;
+	/** The fake Java and hooks bridges a plugin gets as `context.native.java` and `hooks` on Android. */
+	java: FakeJava;
+	/** Every call a plugin made to the fake bridges, in order. */
+	calls: NativeCallLog['calls'];
+	/** Puts the platform back to `ios` and forgets modules, capabilities, classes, objects, hooks and calls. */
+	reset: () => void;
+	/** Builds the context `start` receives: the manifest, the platform and capabilities from the state, and `overrides` on top. */
+	context: (manifest: AddonManifest, overrides?: StartContext) => PluginContext;
+};
+
+// A bridge member the test did not give: an empty object it can fill in, since the plugin reads only what it calls.
+function emptyMember<T>(): T {
+	return Object.create(null);
+}
+
+const PLATFORMS: readonly NativePluginPlatform[] = ['ios', 'android'];
+
+class NativePluginUnavailableError extends Error {
+	readonly code = 'NATIVE_PLUGIN_UNAVAILABLE';
+}
+
+class NativePluginCapabilityError extends Error {
+	readonly code = 'NATIVE_PLUGIN_CAPABILITY_DENIED';
+	readonly capability: NativePluginCapability;
+
+	constructor(capability: NativePluginCapability) {
+		super(`Native plugin capability is not declared: ${capability}`);
+		this.capability = capability;
+	}
+}
+
+class NativePluginUnsupportedPlatformError extends Error {
+	readonly code = 'NATIVE_PLUGIN_PLATFORM_EXCLUDED';
+	readonly platforms: readonly NativePluginPlatform[];
+
+	constructor(platforms: readonly NativePluginPlatform[], platform: string) {
+		super(`This plugin supports ${platforms.join(', ')}; the host platform is ${platform}.`);
+		this.platforms = platforms;
+	}
+}
+
+class NativePluginVersionError extends Error {
+	readonly code = 'NATIVE_PLUGIN_API_VERSION_UNSUPPORTED';
+	readonly installedApi: string;
+	readonly requiredApi: string;
+
+	constructor(requiredApi: string, installedApi: string) {
+		super(`Native plugin API ${requiredApi} is required, but ${installedApi} is installed.`);
+		this.installedApi = installedApi;
+		this.requiredApi = requiredApi;
+	}
+}
+
+class NativePluginDisposedError extends Error {
+	readonly code = 'NATIVE_PLUGIN_SCOPE_DISPOSED';
+
+	constructor() {
+		super('The native plugin scope has been disposed.');
+	}
+}
+
+/**
+ * @description Creates the fake `native`: `definePlatform` selects by the state's platform on each call of a function handler, `getNativeModule` reads its modules,
+ * and the error classes and metadata modules exist as on device.
+ * @returns The namespace, its state, and the context builder.
+ */
+export function createFakeNative(): FakeNative {
+	const state: NativeState = { platform: 'ios', modules: new Map(), capabilities: [] };
+	const log = createCallLog();
+	const objc = createFakeObjc(log);
+	const java = createFakeJava(log);
+
+	function select<Handler>(handlers: Partial<Record<NativePluginPlatform, Handler>>): Handler {
+		const handler = handlers[state.platform];
+
+		if (handler === undefined) {
+			throw new NativePluginUnsupportedPlatformError(
+				PLATFORMS.filter((name) => handlers[name] !== undefined),
+				state.platform,
+			);
+		}
+
+		return handler;
+	}
+
+	// A plugin selects as it imports platform.ts, before a test sets the platform, so a function handler
+	// is a forwarder to the current platform's handler. Any other value is read now.
+	function definePlatform<Handler>(
+		handlers: Partial<Record<NativePluginPlatform, Handler>>,
+	): Handler {
+		const selected = select(handlers);
+
+		if (typeof selected !== 'function') {
+			return selected;
+		}
+
+		return new Proxy(selected, {
+			apply: (_target, self, args) => Reflect.apply(select(handlers) as never, self, args),
+			construct: (_target, args) => Reflect.construct(select(handlers) as never, args),
+			get: (_target, key) => Reflect.get(select(handlers) as never, key),
+			has: (_target, key) => Reflect.has(select(handlers) as never, key),
+		});
+	}
+
+	const namespace: FakeModule = {
+		NativePluginUnavailableError,
+		NativePluginCapabilityError,
+		NativePluginUnsupportedPlatformError,
+		NativePluginVersionError,
+		NativePluginDisposedError,
+		BundleInfo: {},
+		BundleManager: {},
+		DeviceInfo: {},
+		definePlatform,
+		getNativeModule: (...names: string[]) =>
+			names.map((name) => state.modules.get(name)).find(Boolean),
+		getNativeResources: () => undefined,
+		getRuntimeProperties: () => ({}),
+		has: (capability: NativePluginCapability) => state.capabilities.includes(capability),
+		reload: async () => {},
+	};
+
+	return {
+		namespace,
+		state,
+		objc,
+		java,
+		calls: log.calls,
+		reset() {
+			objc.reset();
+			java.reset();
+			log.calls.length = 0;
+			state.platform = 'ios';
+			state.modules.clear();
+			state.capabilities = [];
+		},
+		context(manifest, overrides = {}) {
+			const { native, ...rest } = overrides;
+			const capabilities = rest.capabilities ?? state.capabilities;
+			const bridge: NativePluginBridge = {
+				apiVersion: '1.0.0',
+				abiVersion: '1',
+				capabilities,
+				ffi: emptyMember(),
+				fabric: emptyMember(),
+				runtime: emptyMember(),
+				debug: emptyMember(),
+				ui: emptyMember(),
+				...native,
+				// The overrides lie over the fake's members, so one the test gave wins and the rest stay.
+				objc: overlayBridge(
+					state.platform === 'ios' ? objc.bridge : emptyMember(),
+					native?.objc,
+				),
+				java: overlayBridge(
+					state.platform === 'android' ? java.bridge : emptyMember(),
+					native?.java,
+				),
+				hooks: overlayBridge(
+					state.platform === 'android' ? java.hooks : emptyMember(),
+					native?.hooks,
+				),
+			};
+
+			return {
+				manifest,
+				id: manifest.id,
+				platform: state.platform,
+				capabilities,
+				dispose: () => {},
+				...rest,
+				native: bridge,
+			};
+		},
+	};
+}