@nebulahome/package-sdk 0.0.0-stage → 1.0.1

package/dist/testing.js

@@ -0,0 +1,608 @@
+import { t as SDK_VERSION } from "./chunks/version.js";
+//#region src/testing/schema.ts
+/**
+* One line for the problems a schema found.
+*
+* @param issues - The problems.
+* @returns What they say, joined.
+*/
+function messageOf(issues) {
+	return issues.map((issue) => issue.message).join("; ");
+}
+/**
+* Checks a value.
+*
+* @param schema - The schema.
+* @param value - The value.
+* @returns The value it gave back, or what is wrong.
+*/
+async function check(schema, value) {
+	if ("~standard" in schema) {
+		const result = await schema["~standard"].validate(value);
+		return result.issues === void 0 ? {
+			isValid: true,
+			value: result.value
+		} : {
+			isValid: false,
+			message: messageOf(result.issues)
+		};
+	}
+	const result = schema.safeParse(value);
+	return result.success ? {
+		isValid: true,
+		value: result.data
+	} : {
+		isValid: false,
+		message: String(result.error)
+	};
+}
+//#endregion
+//#region src/testing/index.ts
+/** Service names the platform keeps for itself. */
+const RESERVED_SERVICES = /* @__PURE__ */ new Set([
+	"command",
+	"rpc",
+	"settings",
+	"health",
+	"events",
+	"info"
+]);
+/** Who calls a method when a test does not say. */
+const TEST_CALLER = {
+	userId: "test-user",
+	username: "test",
+	role: "owner"
+};
+/**
+* Says whether a value is a record.
+*
+* @param value - The value.
+* @returns True for a non-null, non-array object.
+*/
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* Says whether a value is one a custom entity's field holds.
+*
+* @param value - The value.
+* @returns True for a string, a number, a boolean or null.
+*/
+function isCustomValue(value) {
+	return value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean";
+}
+/**
+* The fields of a settings declaration, by key.
+*
+* @param definition - The declaration.
+* @returns Each field, as a record.
+*/
+function fieldsOf(definition) {
+	const fields = isRecord(definition) && isRecord(definition["fields"]) ? definition["fields"] : {};
+	return new Map(Object.entries(fields).flatMap(([key, field]) => isRecord(field) ? [[key, field]] : []));
+}
+/**
+* Builds a context with no platform behind it.
+*
+* @param options - Its id, settings and the house it reads.
+* @returns The context, and what the package does with it.
+*/
+function createTestContext(options = {}) {
+	const id = options.id ?? "test-package";
+	const prefix = `${id.replaceAll("-", "_")}_`;
+	const fields = fieldsOf(options.definition);
+	let values = {
+		...Object.fromEntries([...fields].flatMap(([key, field]) => field["default"] === void 0 ? [] : [[key, field["default"]]])),
+		...options.settings
+	};
+	const abort = new AbortController();
+	const reports = [];
+	const logs = [];
+	const entities = new Map((options.entities ?? []).map((each) => [each.entityId, each]));
+	const methods = /* @__PURE__ */ new Map();
+	const services = /* @__PURE__ */ new Map();
+	const answers = /* @__PURE__ */ new Map();
+	const customHandlers = /* @__PURE__ */ new Map();
+	const settingsHandlers = /* @__PURE__ */ new Set();
+	const subscriptions = /* @__PURE__ */ new Set();
+	let commandHandler;
+	let synced;
+	/**
+	* Says whether the settings, as recorded, are the server's: whatever its declaration types
+	* them as, the test vouches for them.
+	*
+	* @param value - The settings.
+	* @returns True for a record.
+	*/
+	const isSettings = (value) => isRecord(value);
+	/**
+	* The settings, as the server reads them.
+	*
+	* @returns Them.
+	* @throws {Error} Never: they are always a record.
+	*/
+	const settingsNow = () => {
+		if (!isSettings(values)) throw new Error("The settings are not a record");
+		return values;
+	};
+	/**
+	* A logger that records each line, with the fields of its parents.
+	*
+	* @param bound - The fields every line carries.
+	* @returns The logger.
+	*/
+	const loggerWith = (bound) => {
+		/**
+		* One log method.
+		*
+		* @param level - Its level.
+		* @returns The method.
+		*/
+		const method = (level) => (first, message) => {
+			logs.push(typeof first === "string" ? {
+				level,
+				fields: bound,
+				message: first
+			} : {
+				level,
+				fields: {
+					...bound,
+					...first
+				},
+				message
+			});
+		};
+		return {
+			trace: method("trace"),
+			debug: method("debug"),
+			info: method("info"),
+			warn: method("warn"),
+			error: method("error"),
+			fatal: method("fatal"),
+			/**
+			* A logger whose lines carry more fields.
+			*
+			* @param more - The fields it adds.
+			* @returns The logger.
+			*/
+			child: (more) => loggerWith({
+				...bound,
+				...more
+			})
+		};
+	};
+	/**
+	* The object id of one of the package's entities.
+	*
+	* @param entityId - The entity.
+	* @returns What follows the prefix, or undefined for anyone else's.
+	*/
+	const objectIdOf = (entityId) => {
+		const objectId = entityId.split(".")[1];
+		return objectId?.startsWith(prefix) === true ? objectId.slice(prefix.length) : void 0;
+	};
+	/**
+	* Says whether an entity is one a filter names.
+	*
+	* @param filter - The filter.
+	* @param entityId - The entity.
+	* @returns True when it is.
+	*/
+	const matches = (filter, entityId) => (filter.domain === void 0 || entityId.startsWith(`${filter.domain}.`)) && (filter.entityIds === void 0 || filter.entityIds.includes(entityId));
+	/**
+	* Registers a method of the package's interface.
+	*
+	* @param name - The method.
+	* @param method - Who may call it, and what it takes.
+	* @param method.access - Who may call it.
+	* @param method.input - What checks its input, if anything.
+	* @param handler - What it does.
+	* @throws {Error} When the name is taken.
+	*/
+	function rpcMethod(name, method, handler) {
+		/**
+		* Says whether an input is the method's: its schema checked it, or it is the JSON the
+		* interface sent to a method that takes any.
+		*
+		* @param input - The input.
+		* @returns True.
+		*/
+		const isInput = (input) => input === input;
+		if (methods.has(name)) throw new Error(`The method ${name} is registered already`);
+		methods.set(name, {
+			input: method.input,
+			/**
+			* Hands the method its input, once checked.
+			*
+			* @param input - The input.
+			* @param call - Who calls.
+			* @returns What the method answers.
+			* @throws {Error} Never: every input is the method's.
+			*/
+			handler: (input, call) => {
+				if (!isInput(input)) throw new Error(`${name} was handed what it does not take`);
+				return handler(input, call);
+			}
+		});
+	}
+	/**
+	* Offers a service.
+	*
+	* @param name - The service.
+	* @param serviceOrHandler - What it takes, or what it answers.
+	* @param handler - What it answers, after its schema.
+	* @throws {Error} When the name is reserved or taken, or there is no handler.
+	*/
+	function provide(name, serviceOrHandler, handler) {
+		/**
+		* Says whether an input is the service's: its schema checked it, or it takes any.
+		*
+		* @param input - The input.
+		* @returns True.
+		*/
+		const isInput = (input) => input === input;
+		const answer = typeof serviceOrHandler === "function" ? serviceOrHandler : handler;
+		if (RESERVED_SERVICES.has(name) || name.startsWith("_")) throw new Error(`${name} is a name the platform keeps for itself`);
+		if (services.has(name)) throw new Error(`The service ${name} is provided already`);
+		if (answer === void 0) throw new Error(`The service ${name} has no handler`);
+		services.set(name, {
+			input: typeof serviceOrHandler === "function" ? void 0 : serviceOrHandler.input,
+			/**
+			* Hands the service its input, once checked.
+			*
+			* @param input - The input.
+			* @param call - Who calls.
+			* @returns What the service answers.
+			* @throws {Error} Never: every input is the service's.
+			*/
+			handler: (input, call) => {
+				if (!isInput(input)) throw new Error(`${name} was handed what it does not take`);
+				return answer(input, call);
+			}
+		});
+	}
+	/**
+	* Calls a service.
+	*
+	* @param target - The package or service.
+	* @param name - The service.
+	* @param input - What it is handed.
+	* @param call - What it answers.
+	* @param call.timeoutMs - In milliseconds.
+	* @param call.output - What checks the answer.
+	* @returns What it answered.
+	* @throws {Error} When nothing answers it, or the answer is not what was asked.
+	*/
+	async function callService(target, name, input, call) {
+		const answer = answers.get(`${target}.${name}`);
+		if (answer === void 0) throw new Error(`Nothing answers ${target}.${name}: answer it with answerService`);
+		const value = await answer(input);
+		if (call?.output === void 0) return value;
+		const checked = await check(call.output, value);
+		if (!checked.isValid) throw new Error(`${target}.${name} answered what was not asked: ${checked.message}`);
+		return checked.value;
+	}
+	return {
+		ctx: {
+			id,
+			version: options.version ?? "0.0.0",
+			platform: { version: "0.0.0-test" },
+			sdk: { version: SDK_VERSION },
+			/**
+			* The settings as they stand.
+			*
+			* @returns Them.
+			*/
+			get settings() {
+				return settingsNow();
+			},
+			/**
+			* Hears live changes of the settings.
+			*
+			* @param handler - What hears them.
+			* @returns What stops it hearing.
+			*/
+			onSettingsChange: (handler) => {
+				settingsHandlers.add(handler);
+				return () => {
+					settingsHandlers.delete(handler);
+				};
+			},
+			dataDir: options.dataDir ?? `/tmp/${id}/data`,
+			cacheDir: options.cacheDir ?? `/tmp/${id}/cache`,
+			signal: abort.signal,
+			logger: loggerWith({}),
+			/**
+			* One of the package's entities' ids.
+			*
+			* @param domain - Its domain.
+			* @param objectId - What follows the prefix.
+			* @returns The id.
+			*/
+			entityId: (domain, objectId) => `${domain}.${prefix}${objectId}`,
+			objectIdOf,
+			devices: {
+				/**
+				* Records the devices, and answers as the platform would.
+				*
+				* @param devices - Every device.
+				* @returns What was written.
+				*/
+				sync: async (devices) => {
+					synced = devices;
+					return Promise.resolve({
+						devices: devices.map((device) => ({
+							deviceId: `device-${device.externalId}`,
+							externalId: device.externalId,
+							entityIds: device.entities.map((entity) => `${"type" in entity ? "custom" : entity.domain}.${prefix}${entity.objectId}`)
+						})),
+						refused: [],
+						kept: []
+					});
+				},
+				/**
+				* Records a report.
+				*
+				* @param entityId - The entity.
+				* @param state - Its state.
+				* @param reportOptions - Its attributes and availability.
+				*/
+				report: (entityId, state, reportOptions) => {
+					reports.push({
+						entityId,
+						state,
+						...reportOptions === void 0 ? {} : { options: reportOptions }
+					});
+				},
+				/**
+				* Takes the handler of commands.
+				*
+				* @param handler - The handler.
+				* @returns What removes it.
+				* @throws {Error} When there is one already.
+				*/
+				onCommand: (handler) => {
+					if (commandHandler !== void 0) throw new Error("devices.onCommand has a handler already");
+					commandHandler = handler;
+					return () => {
+						commandHandler = void 0;
+					};
+				}
+			},
+			/**
+			* The entities of one of the package's entity types.
+			*
+			* @param type - The entity type.
+			* @returns Their ids, reports and commands.
+			*/
+			custom: (type) => ({
+				/**
+				* The id of one of its entities of this type.
+				*
+				* @param objectId - What follows the prefix.
+				* @returns The id.
+				*/
+				entityId: (objectId) => `custom.${prefix}${objectId}`,
+				/**
+				* Records a report of an entity's values.
+				*
+				* @param entityId - The entity.
+				* @param entityValues - Its values.
+				* @param reportOptions - Its attributes and availability.
+				*/
+				report: (entityId, entityValues, reportOptions) => {
+					reports.push({
+						entityId,
+						state: { custom: { values: Object.fromEntries(Object.entries(entityValues).filter((entry) => isCustomValue(entry[1]))) } },
+						...reportOptions === void 0 ? {} : { options: reportOptions }
+					});
+				},
+				/**
+				* Takes the handler of one of the type's commands.
+				*
+				* @param command - The command's id.
+				* @param handler - The handler.
+				* @returns What removes it.
+				* @throws {Error} When the command has one already.
+				*/
+				onCommand: (command, handler) => {
+					const key = `${type.id}:${command}`;
+					/**
+					* Says whether a command's arguments are its own: the platform checked them against
+					* the entity type before routing it.
+					*
+					* @param args - The arguments.
+					* @returns True for a record.
+					*/
+					const isArgs = (args) => isRecord(args);
+					if (customHandlers.has(key)) throw new Error(`${type.id} has a handler for ${command} already`);
+					customHandlers.set(key, (call) => {
+						if (!isArgs(call.args)) throw new Error(`${command} was sent without arguments`);
+						return handler({
+							entityId: call.entityId,
+							objectId: call.objectId,
+							args: call.args
+						});
+					});
+					return () => {
+						customHandlers.delete(key);
+					};
+				}
+			}),
+			entities: {
+				/**
+				* One entity of the house.
+				*
+				* @param entityId - The entity.
+				* @returns It, or undefined.
+				*/
+				get: async (entityId) => Promise.resolve(entities.get(entityId)),
+				/**
+				* The entities a filter names.
+				*
+				* @param filter - Which.
+				* @returns Them.
+				*/
+				list: async (filter = {}) => Promise.resolve([...entities.values()].filter((each) => matches(filter, each.entityId))),
+				/**
+				* Hears changes of the entities a filter names.
+				*
+				* @param filter - Which.
+				* @param handler - What hears them.
+				* @returns What stops it hearing.
+				*/
+				subscribe: (filter, handler) => {
+					const subscription = {
+						filter,
+						handler
+					};
+					subscriptions.add(subscription);
+					return () => {
+						subscriptions.delete(subscription);
+					};
+				}
+			},
+			rpc: { method: rpcMethod },
+			services: {
+				provide,
+				call: callService
+			}
+		},
+		/**
+		* The last list of devices.
+		*
+		* @returns It.
+		*/
+		synced: () => synced,
+		reports: {
+			all: reports,
+			/**
+			* The newest state of one entity.
+			*
+			* @param entityId - The entity.
+			* @returns Its state.
+			*/
+			last: (entityId) => reports.findLast((each) => each.entityId === entityId)?.state
+		},
+		logs,
+		/**
+		* Routes a command.
+		*
+		* @param command - The command.
+		* @throws {Error} When nothing handles it.
+		*/
+		sendCommand: async (command) => {
+			if (command.capability === "custom") {
+				const objectId = objectIdOf(command.entityId) ?? "";
+				const entity = synced?.flatMap((device) => device.entities).find((each) => "type" in each && each.objectId === objectId);
+				const typeId = entity !== void 0 && "type" in entity ? entity.type.id : void 0;
+				const handler = customHandlers.get(`${typeId ?? ""}:${command.command.command}`);
+				if (handler !== void 0) {
+					await handler({
+						entityId: command.entityId,
+						objectId,
+						args: command.command.args
+					});
+					return;
+				}
+			}
+			if (commandHandler === void 0) throw new Error(`Nothing handles commands to ${command.entityId}`);
+			await commandHandler(command);
+		},
+		/**
+		* Calls a method.
+		*
+		* @param method - The method.
+		* @param input - What it is handed.
+		* @param caller - Who calls.
+		* @returns What it answered.
+		* @throws {Error} When there is no such method, or it refuses the input.
+		*/
+		callRpc: async (method, input, caller = TEST_CALLER) => {
+			const registered = methods.get(method);
+			if (registered === void 0) throw new Error(`There is no method ${method}`);
+			if (registered.input === void 0) return registered.handler(input, { caller });
+			const checked = await check(registered.input, input);
+			if (!checked.isValid) throw new Error(`${method} refused its input: ${checked.message}`);
+			return registered.handler(checked.value, { caller });
+		},
+		/**
+		* Calls a service the package provides.
+		*
+		* @param name - The service.
+		* @param input - What it is handed.
+		* @param caller - Who calls.
+		* @returns What it answered.
+		* @throws {Error} When there is no such service, or it refuses the input.
+		*/
+		callService: async (name, input, caller = "test") => {
+			const service = services.get(name);
+			if (service === void 0) throw new Error(`The package provides no service ${name}`);
+			if (service.input === void 0) return service.handler(input, { caller });
+			const checked = await check(service.input, input);
+			if (!checked.isValid) throw new Error(`${name} refused its input: ${checked.message}`);
+			return service.handler(checked.value, { caller });
+		},
+		/**
+		* Changes settings.
+		*
+		* @param patch - What changes.
+		* @returns Whether the platform would restart the package.
+		*/
+		changeSettings: async (patch) => {
+			const changed = Object.keys(patch).filter((key) => patch[key] !== values[key]);
+			values = {
+				...values,
+				...patch
+			};
+			if (changed.some((key) => fields.get(key)?.["isLive"] !== true)) return { isRestart: true };
+			/**
+			* Says whether the keys changed are the settings': they are the patch's own.
+			*
+			* @param keys - The keys.
+			* @returns True.
+			*/
+			const areKeys = (keys) => Array.isArray(keys);
+			if (areKeys(changed)) for (const handler of settingsHandlers) await handler({
+				values: settingsNow(),
+				changed
+			});
+			return { isRestart: false };
+		},
+		/**
+		* Puts an entity of the house.
+		*
+		* @param snapshot - The entity.
+		*/
+		setEntity: (snapshot) => {
+			entities.set(snapshot.entityId, snapshot);
+		},
+		/**
+		* Changes an entity of the house.
+		*
+		* @param change - The change.
+		*/
+		emitStateChange: async (change) => {
+			entities.set(change.entityId, change.current);
+			for (const subscription of subscriptions) if (matches(subscription.filter, change.entityId)) await subscription.handler(change);
+		},
+		/**
+		* Answers a service the package calls.
+		*
+		* @param target - The package or service.
+		* @param name - The service.
+		* @param handler - What it answers.
+		*/
+		answerService: (target, name, handler) => {
+			answers.set(`${target}.${name}`, handler);
+		},
+		/**
+		* Asks the package to stop.
+		*/
+		stop: () => {
+			abort.abort();
+		}
+	};
+}
+//#endregion
+export { createTestContext };