@unbound-app/api 0.11.0 → 1.1.1

package/testing/install-addon-globals.ts

@@ -0,0 +1,260 @@
+import type {
+	BuilderInput,
+	ChoiceInput,
+	ChoiceMap,
+	CommandContext,
+	OptionBuilder,
+	OptionSettings,
+	OptionSpec,
+	CommandTree,
+	OptionBuilders,
+	OptionKind,
+	OptionValue,
+	Reply,
+} from '../src/commands';
+import type { AddonHandle, AddonLogger, AddonManifest } from '../src/global';
+
+import { createRecordingPatcher, type RecordingPatcher } from './recording-patcher';
+import { createFakeMetro, type FakeMetro, type FakeModule } from './fake-metro';
+import { createMemoryStorage, type MemoryStorage } from './memory-storage';
+import { createFakeTimers, type FakeTimers } from './fake-timers';
+import { createFakeReact, type FakeReact } from './fake-react';
+
+type LogLevel = keyof AddonLogger;
+
+/** A line the fake `logger` received. */
+export type LogEntry = {
+	level: LogLevel;
+	args: unknown[];
+};
+
+/** A command's parsed options, by name, as its `execute` receives them. */
+export type CommandArgs = Record<string, OptionValue<OptionKind> | undefined>;
+
+/** The fake `commands`: register records each command tree by its root names. */
+export type FakeCommands = {
+	/** The registered command trees, by root name. */
+	registered: Map<string, object>;
+	register: <T>(commands: CommandTree<T>) => () => void;
+	unregister: (name: string) => void;
+	unregisterAll: () => void;
+	/** The option builders; each returns its kind and settings. */
+	option: OptionBuilders;
+	/**
+	 * Runs a registered command as Discord would, with parsed args.
+	 * @param path The command's name, with its subcommands after spaces, such as `'star'` or `'tags add'`.
+	 * @param args The parsed options, such as `{ user }`.
+	 * @param context Where it runs; a guild text channel when omitted.
+	 */
+	run: (path: string, args?: CommandArgs, context?: Partial<CommandContext>) => Promise<Reply>;
+};
+
+/** The fake `unbound`: the scoped namespaces the kit fakes, plus any a test adds. */
+export type FakeUnbound = {
+	storage: MemoryStorage;
+	patcher: RecordingPatcher;
+	metro: FakeMetro;
+	commands: FakeCommands;
+	[namespace: string]: FakeModule;
+};
+
+type InstallOptions = {
+	/** The manifest the fake `addon` reads; `id` also names the default Bucket. */
+	manifest?: Partial<AddonManifest>;
+	/** Namespaces to add to or replace on `unbound`, such as `assets` or `fs`. */
+	unbound?: Partial<FakeUnbound>;
+};
+
+/** The installed fake Addon scope, and `uninstall` to restore the previous globals. */
+export type InstalledAddonGlobals = {
+	React: FakeReact;
+	unbound: FakeUnbound;
+	addon: AddonHandle;
+	patcher: RecordingPatcher;
+	logger: AddonLogger;
+	commands: FakeCommands;
+	/** Every line `logger` received, in order. */
+	logs: LogEntry[];
+	storage: MemoryStorage;
+	metro: FakeMetro;
+	/** The scoped `setTimeout`, `setInterval` and their clears, installed as globals. */
+	timers: FakeTimers;
+	uninstall: () => void;
+};
+
+const LOG_LEVELS: LogLevel[] = ['log', 'info', 'success', 'warn', 'error', 'debug'];
+
+function createLogger(logs: LogEntry[]): AddonLogger {
+	const entries = LOG_LEVELS.map((level) => [
+		level,
+		(...args: unknown[]) => void logs.push({ level, args }),
+	]);
+
+	return Object.fromEntries(entries) as AddonLogger;
+}
+
+const DEFAULT_CONTEXT: CommandContext = {
+	channel: { id: '100000000000000001', type: 0, name: 'general', guild_id: '100000000000000002' },
+	guild: { id: '100000000000000002', name: 'Test Guild' },
+};
+
+// Builds the spec the client's builders return: the kind, `required`, `description` and the kind's settings.
+function spec<K extends OptionKind>(kind: K): OptionBuilder<K> {
+	return <const R extends boolean = false>(input: BuilderInput<K, R> = {}) => ({
+		kind,
+		required: (input.required ?? false) as R,
+		description: input.description,
+		settings: input,
+		choices: undefined,
+	});
+}
+
+// `choice` maps each value to its label's key; its typed `M` exists only for inference.
+function choice<const M extends ChoiceMap, const R extends boolean = false>(
+	choices: M,
+	settings: ChoiceInput<R> = {},
+): OptionSpec<'string', R, keyof M & string> {
+	const none: OptionSettings<'string'> = {};
+
+	return {
+		kind: 'string',
+		required: (settings.required ?? false) as R,
+		description: settings.description,
+		settings: none,
+		choices,
+	};
+}
+
+function createOptionBuilders(): OptionBuilders {
+	return {
+		string: spec('string'),
+		integer: spec('integer'),
+		number: spec('number'),
+		boolean: spec('boolean'),
+		user: spec('user'),
+		channel: spec('channel'),
+		role: spec('role'),
+		choice,
+	};
+}
+
+function findCommand(registered: FakeCommands['registered'], path: string) {
+	const [root = '', ...rest] = path.split(' ').filter(Boolean);
+	let node: unknown = registered.get(root);
+
+	for (const name of rest) {
+		const subcommands: unknown = node ? Reflect.get(node, 'subcommands') : void 0;
+
+		node = subcommands ? Reflect.get(subcommands, name) : void 0;
+	}
+
+	const execute: unknown = node ? Reflect.get(node, 'execute') : void 0;
+
+	if (typeof execute !== 'function') {
+		throw new Error(
+			`Failed to run command /${path}: it is not registered. Registered: ${[...registered.keys()].join(', ') || 'none'}.`,
+		);
+	}
+
+	return { node, execute };
+}
+
+function createCommands(): FakeCommands {
+	const registered: FakeCommands['registered'] = new Map();
+
+	return {
+		registered,
+		option: createOptionBuilders(),
+		async run(path, args = {}, context = {}) {
+			const { node, execute } = findCommand(registered, path);
+
+			return execute.call(node, args, { ...DEFAULT_CONTEXT, ...context });
+		},
+		register(commands) {
+			const roots = Object.keys(commands);
+
+			for (const root of roots) registered.set(root, Reflect.get(commands, root));
+
+			return () => {
+				for (const root of roots) registered.delete(root);
+			};
+		},
+		unregister: (name) => void registered.delete(name),
+		unregisterAll: () => registered.clear(),
+	};
+}
+
+function createAddon(manifest: AddonManifest): AddonHandle {
+	let enabled = true;
+
+	return {
+		id: manifest.id,
+		name: manifest.name,
+		version: manifest.version,
+		authors: manifest.authors,
+		manifest,
+		started: true,
+		failed: false,
+		isEnabled: () => enabled,
+		isPlugin: () => true,
+		enable: () => void (enabled = true),
+		disable: () => void (enabled = false),
+		reload: async () => {},
+		toJSON: () => manifest,
+	};
+}
+
+/**
+ * @description Installs a fake Addon scope on `globalThis`, so plugin code under test reads `addon`, `patcher`,
+ * `logger`, `commands`, `unbound`, `React` and the scoped timers as it would on device. Pass `unbound` to `mock.module('@unbound-app/api')`.
+ * @param options The fake addon's manifest and extra `unbound` namespaces.
+ * @returns The globals, the recorded logs, and `uninstall` to restore what was there before.
+ */
+export function installAddonGlobals(options: InstallOptions = {}): InstalledAddonGlobals {
+	const manifest: AddonManifest = {
+		id: 'test-addon',
+		name: 'Test Addon',
+		description: '',
+		authors: [],
+		main: 'index.js',
+		version: '1.0.0',
+		...options.manifest,
+	};
+	const logs: LogEntry[] = [];
+	const storage = createMemoryStorage(manifest.id);
+	const metro = createFakeMetro();
+	const patcher = createRecordingPatcher(metro.whenLoaded);
+	const commands = createCommands();
+	const timers = createFakeTimers();
+	const unbound: FakeUnbound = { storage, patcher, metro, commands, ...options.unbound };
+	const globals = {
+		React: createFakeReact(),
+		unbound,
+		addon: createAddon(manifest),
+		patcher,
+		logger: createLogger(logs),
+		commands,
+		setTimeout: timers.setTimeout,
+		setInterval: timers.setInterval,
+		clearTimeout: timers.clearTimeout,
+		clearInterval: timers.clearInterval,
+	};
+	const previous = new Map<string, PropertyDescriptor | undefined>();
+
+	for (const [name, value] of Object.entries(globals)) {
+		previous.set(name, Object.getOwnPropertyDescriptor(globalThis, name));
+		Object.defineProperty(globalThis, name, { value, configurable: true, writable: true });
+	}
+
+	function uninstall() {
+		for (const [name, descriptor] of previous) {
+			if (descriptor) {
+				Object.defineProperty(globalThis, name, descriptor);
+			} else {
+				Reflect.deleteProperty(globalThis, name);
+			}
+		}
+	}
+
+	return { ...globals, logs, storage, metro, timers, uninstall };
+}

package/testing/listener-registry.ts

@@ -0,0 +1,39 @@
+/** The listeners a plugin added through the fake API and has not removed, for `stopPlugin`'s leak check. */
+export type ListenerRegistry = {
+	/** Records a listener; the returned function removes it, calling `remove` once. */
+	track: (label: string, remove: () => void) => () => void;
+	/** The label of each listener still added, in the order they were added. */
+	active: () => string[];
+	/** Removes every listener still added. */
+	clear: () => void;
+};
+
+type Listener = { label: string; remove: () => void };
+
+/**
+ * @description Creates a registry of the listeners a plugin holds.
+ * @returns The registry.
+ */
+export function createListenerRegistry(): ListenerRegistry {
+	const listeners = new Map<symbol, Listener>();
+
+	return {
+		track(label, remove) {
+			const id = Symbol(label);
+
+			listeners.set(id, { label, remove });
+
+			return () => {
+				if (!listeners.delete(id)) return;
+
+				remove();
+			};
+		},
+		active: () => [...listeners.values()].map(({ label }) => label),
+		clear() {
+			for (const { remove } of listeners.values()) remove();
+
+			listeners.clear();
+		},
+	};
+}

package/testing/memory-storage.ts

@@ -0,0 +1,149 @@
+import type { Bucket, SettingsPayload, SettingsPredicate } from '../src/storage';
+import type { SettingsObject, SettingsValue } from '../src/global';
+import type { Widen } from '../src/_types';
+
+/** In-memory Buckets: `storage.getBucket(name)` without a device, and the settings each holds. */
+export type MemoryStorage = {
+	/** Every Bucket's settings, by Bucket name. A Bucket left empty has no entry, as on disk. */
+	data: Map<string, SettingsObject>;
+	/** Returns a Bucket by name, or the default Bucket when `name` is omitted. */
+	getBucket: (name?: string) => Bucket;
+	/** Returns a Bucket by name. Without a renderer there is nothing to re-render. */
+	useBucket: (name: string, predicate?: SettingsPredicate) => Bucket;
+	/** Calls `callback` for each change the predicate accepts, until the returned function runs. */
+	onChange: (
+		predicate: SettingsPredicate,
+		callback: (payload: SettingsPayload) => void,
+	) => () => void;
+};
+
+function isSettingsObject(value: SettingsValue | undefined): value is SettingsObject {
+	return typeof value === 'object' && value !== null;
+}
+
+/**
+ * @description Creates in-memory Buckets that keep settings for the life of a test, with the client storage's semantics.
+ * @param defaultName The Bucket `getBucket()` returns without a name, such as the plugin's id.
+ * @returns The storage, with each Bucket's settings readable from `data`.
+ */
+export function createMemoryStorage(defaultName: string = 'test-addon'): MemoryStorage {
+	const data = new Map<string, SettingsObject>();
+	const listeners = new Set<(payload: SettingsPayload) => void>();
+
+	function emit(payload: SettingsPayload) {
+		for (const listener of listeners) listener(payload);
+	}
+
+	function get<T>(store: string, key: string, def: T): Widen<T> {
+		let result: SettingsValue | undefined = data.get(store);
+
+		for (const segment of key.split('.')) {
+			const next: SettingsValue | undefined = isSettingsObject(result)
+				? result[segment]
+				: void 0;
+
+			if (next === void 0) {
+				return def as Widen<T>;
+			}
+
+			result = next;
+		}
+
+		return result as Widen<T>;
+	}
+
+	function set(store: string, key: string, value: SettingsValue) {
+		const keys = key.split('.');
+		const last = keys.pop() ?? key;
+		let current = data.get(store);
+
+		if (!current) {
+			current = {};
+			data.set(store, current);
+		}
+
+		for (const segment of keys) {
+			const next: SettingsValue = (current[segment] ??= {});
+
+			if (!isSettingsObject(next)) {
+				throw new TypeError(`Cannot set ${store}.${key}: ${segment} is not an object.`);
+			}
+
+			current = next;
+		}
+
+		current[last] = value;
+		emit({ store, key, value });
+	}
+
+	function remove(store: string, key: string) {
+		const keys = key.split('.');
+		const last = keys.pop() ?? key;
+		const parents: SettingsObject[] = [];
+		let current: SettingsValue | undefined = data.get(store);
+
+		for (const segment of keys) {
+			if (!isSettingsObject(current)) return;
+
+			parents.push(current);
+			current = current[segment];
+		}
+
+		if (!isSettingsObject(current) || current[last] === undefined) return;
+
+		delete current[last];
+
+		for (let index = keys.length - 1; index >= 0; index--) {
+			const parent = parents[index];
+			const segment = keys[index];
+
+			if (!parent || segment === undefined) {
+				break;
+			}
+
+			const child = parent[segment];
+
+			if (!isSettingsObject(child) || Object.keys(child).length > 0) {
+				break;
+			}
+
+			delete parent[segment];
+		}
+
+		if (Object.keys(data.get(store) ?? {}).length === 0) {
+			data.delete(store);
+		}
+
+		emit({ store, key, value: undefined });
+	}
+
+	function clear(store: string) {
+		if (!data.delete(store)) return;
+
+		emit({ store, key: null, value: undefined });
+	}
+
+	function getBucket(name: string = defaultName): Bucket {
+		return {
+			get: (key, def) => get(name, key, def),
+			set: (key, value) => set(name, key, value),
+			toggle: (key, def) => set(name, key, !get(name, key, def)),
+			remove: (key) => remove(name, key),
+			clear: () => clear(name),
+		};
+	}
+
+	function onChange(predicate: SettingsPredicate, callback: (payload: SettingsPayload) => void) {
+		function listener(payload: SettingsPayload) {
+			if (predicate(payload)) {
+				callback(payload);
+			}
+		}
+
+		listeners.add(listener);
+
+		return () => void listeners.delete(listener);
+	}
+
+	return { data, getBucket, useBucket: (name) => getBucket(name), onChange };
+}

package/testing/plugin-files.ts

@@ -0,0 +1,155 @@
+import { basename, dirname, extname, join, relative, resolve, sep } from 'node:path';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+
+import type { AddonAuthor, AddonManifest } from '../src/global';
+import type { LocaleTable } from './fake-locales';
+import type { AnyObject } from '../src/patcher';
+
+const ENTRY_EXTENSIONS = ['.tsx', '.ts', '.jsx', '.js'];
+
+function isRecord(value: unknown): value is AnyObject {
+	return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+// UNKNOWN: a JSON file holds anything; each caller narrows it with a guard.
+function readJson(path: string): unknown {
+	try {
+		return JSON.parse(readFileSync(path, 'utf8'));
+	} catch (error) {
+		throw new Error(`Failed to read ${path}: ${(error as Error).message}`, { cause: error });
+	}
+}
+
+function nearestManifest(from: string): string | undefined {
+	for (let dir = resolve(from); ; dir = dirname(dir)) {
+		if (existsSync(join(dir, 'manifest.json'))) {
+			return dir;
+		}
+
+		if (dirname(dir) === dir) return;
+	}
+}
+
+/**
+ * @description Finds the plugin under test: `UNBOUND_PLUGIN_ROOT`, else the folder holding the nearest
+ * `manifest.json` above the first test file, else above the working directory.
+ * @param testFile The first test file bun runs, `Bun.main`.
+ * @returns The plugin's directory; throws when there is no manifest above either.
+ */
+export function findPluginRoot(testFile: string = Bun.main): string {
+	const configured = process.env.UNBOUND_PLUGIN_ROOT;
+
+	if (configured) {
+		return resolve(configured);
+	}
+
+	const found = nearestManifest(dirname(testFile)) ?? nearestManifest(process.cwd());
+
+	if (!found) {
+		throw new Error(
+			`Failed to find the plugin under test: no manifest.json above ${testFile} or ${process.cwd()}.`,
+		);
+	}
+
+	return found;
+}
+
+/**
+ * @description Reads the fields of a plugin's manifest.json that the fake `addon` serves.
+ * @param root The plugin's directory.
+ * @returns The manifest's string fields and authors; throws when it is not a JSON object.
+ */
+export function readManifest(root: string): Partial<AddonManifest> {
+	const path = join(root, 'manifest.json');
+	const value = readJson(path);
+
+	if (!isRecord(value)) {
+		throw new Error(`Failed to read ${path}: it is not a JSON object.`);
+	}
+
+	const manifest: Partial<AddonManifest> = {};
+
+	for (const key of ['id', 'name', 'description', 'version', 'main'] as const) {
+		const field = value[key];
+
+		if (typeof field === 'string') {
+			manifest[key] = field;
+		}
+	}
+
+	if (Array.isArray(value.authors)) {
+		manifest.authors = value.authors.filter(
+			(author): author is AddonAuthor =>
+				isRecord(author) &&
+				typeof author.name === 'string' &&
+				typeof author.id === 'string' &&
+				author.id !== '' &&
+				Number.isInteger(Number(author.id)),
+		);
+	}
+
+	return manifest;
+}
+
+/**
+ * @description Reads every `i18n/<code>.json` of a plugin, each a JSON object of message keys to strings.
+ * @param root The plugin's directory.
+ * @returns Each table by locale code; empty when the plugin has no `i18n/`. Throws naming an invalid file.
+ */
+export function readLocaleTables(root: string): Map<string, LocaleTable> {
+	const directory = join(root, 'i18n');
+	const tables = new Map<string, LocaleTable>();
+
+	if (!existsSync(directory)) {
+		return tables;
+	}
+
+	for (const file of readdirSync(directory).filter((name) => name.endsWith('.json'))) {
+		const path = join(directory, file);
+		const value = readJson(path);
+
+		if (!isRecord(value)) {
+			throw new Error(`Failed to read ${path}: it is not a JSON object of strings.`);
+		}
+
+		const table: LocaleTable = {};
+
+		for (const [key, message] of Object.entries(value)) {
+			if (typeof message !== 'string') {
+				throw new Error(`Failed to read ${path}: ${key} is not a string.`);
+			}
+
+			table[key] = message;
+		}
+
+		tables.set(basename(file, '.json'), table);
+	}
+
+	return tables;
+}
+
+/**
+ * @description Finds a plugin's entry as the build does: `src/index` with a TypeScript or JavaScript extension.
+ * @param root The plugin's directory.
+ * @returns The entry's path, or `undefined` when there is none.
+ */
+export function findEntry(root: string): string | undefined {
+	return ENTRY_EXTENSIONS.map((extension) => join(root, 'src', `index${extension}`)).find(
+		(path) => existsSync(path),
+	);
+}
+
+/**
+ * @description Names the asset an image file is, as the build does: its path without extension or `@2x`/`@3x`,
+ * relative to `assets/` inside it and to the plugin root outside it.
+ * @param root The plugin's directory.
+ * @param path The image's absolute path.
+ * @returns The asset name, such as `icons/star`.
+ */
+export function assetNameOf(root: string, path: string): string {
+	const assets = join(root, 'assets');
+	const base = path.startsWith(assets + sep) ? assets : root;
+	const name = relative(base, path).slice(0, -extname(path).length).split(sep).join('/');
+
+	return name.endsWith('@2x') || name.endsWith('@3x') ? name.slice(0, -'@2x'.length) : name;
+}