@prismicio/simulator 0.1.0

package/src/channel/errors.ts

@@ -0,0 +1,53 @@
+import { UnknownErrorResponseMessage } from ".";
+
+import { UnknownRequestMessage } from "./types";
+
+export class ResponseError<
+	TErrorResponse extends UnknownErrorResponseMessage,
+> extends Error {
+	public response: TErrorResponse;
+
+	constructor(errorResponse: TErrorResponse) {
+		super(errorResponse.msg);
+
+		this.response = errorResponse;
+	}
+}
+
+export class ConnectionTimeoutError extends Error {
+	constructor() {
+		super("Connection timed out");
+	}
+}
+export class TooManyConcurrentRequestsError extends Error {
+	public request: UnknownRequestMessage;
+
+	constructor(request: UnknownRequestMessage) {
+		super(`Too many concurrent requests`);
+
+		this.request = request;
+	}
+}
+export class RequestTimeoutError<
+	TRequest extends UnknownRequestMessage,
+> extends Error {
+	public request: UnknownRequestMessage;
+
+	constructor(request: TRequest) {
+		super(`Request \`${request.requestID}\` timed out`);
+
+		this.request = request;
+	}
+}
+
+export class NotReadyError extends Error {}
+export class PortNotSetError extends Error {
+	constructor() {
+		super("Port is not set");
+	}
+}
+export class ChannelNotSetError extends Error {
+	constructor() {
+		super("Channel is not set");
+	}
+}

package/src/channel/index.ts

@@ -0,0 +1,75 @@
+export { ChannelNetwork, channelNetworkDefaultOptions } from "./ChannelNetwork";
+export type {
+	PostRequestOptions,
+	ChannelNetworkOptions,
+} from "./ChannelNetwork";
+
+export { ChannelEmitter, channelEmitterDefaultOptions } from "./ChannelEmitter";
+export type {
+	ChannelEmitterOptions,
+	AllChannelEmitterOptions,
+} from "./ChannelEmitter";
+
+export {
+	ChannelReceiver,
+	channelReceiverDefaultOptions,
+} from "./ChannelReceiver";
+export type {
+	ChannelReceiverOptions,
+	AllChannelReceiverOptions,
+} from "./ChannelReceiver";
+
+export {
+	createRequestMessage,
+	createSuccessResponseMessage,
+	createErrorResponseMessage,
+	validateMessage,
+	isRequestMessage,
+	isResponseMessage,
+	isSuccessResponseMessage,
+	isErrorResponseMessage,
+} from "./messages";
+
+export {
+	ResponseError,
+	ConnectionTimeoutError,
+	TooManyConcurrentRequestsError,
+	RequestTimeoutError,
+	NotReadyError,
+	PortNotSetError,
+	ChannelNotSetError,
+} from "./errors";
+
+export {
+	InternalEmitterRequestType,
+	InternalReceiverRequestType,
+} from "./types";
+export type {
+	// Messages
+	RequestMessage,
+	ResponseMessage,
+	ErrorResponseMessage,
+	SuccessResponseMessage,
+	ExtractSuccessResponseMessage,
+	ExtractErrorResponseMessage,
+	// Unknown messages
+	UnknownRequestMessage,
+	UnknownSuccessResponseMessage,
+	UnknownErrorResponseMessage,
+	UnknownResponseMessage,
+	UnknownMessage,
+	// Transactions
+	Transaction,
+	TransactionMethod,
+	TransactionHandler,
+	TransactionsMethods,
+	TransactionsHandlers,
+	// Unknown transactions
+	UnknownTransaction,
+	UnknownTransactionMethod,
+	UnknownTransactionHandler,
+	// Emitter
+	InternalEmitterTransactions,
+	// Receiver
+	InternalReceiverTransactions,
+} from "./types";

package/src/channel/messages.ts

@@ -0,0 +1,115 @@
+import statuses from "statuses";
+
+import {
+	ErrorResponseMessage,
+	RequestMessage,
+	SuccessResponseMessage,
+	UnknownErrorResponseMessage,
+	UnknownMessage,
+	UnknownRequestMessage,
+	UnknownResponseMessage,
+	UnknownSuccessResponseMessage,
+} from "./types";
+
+let requestID = 0;
+
+export const createRequestMessage = <
+	TType extends string = string,
+	TData = undefined,
+>(
+	type: TType,
+	data: TData,
+	prefix = "",
+): RequestMessage<TType, TData> => {
+	return {
+		requestID: `${prefix}${requestID++}`,
+		type,
+		data,
+	};
+};
+
+export const createSuccessResponseMessage = <TData = undefined>(
+	requestID: string,
+	data: TData,
+	status: keyof typeof statuses.message = 200,
+): SuccessResponseMessage<TData> => {
+	if (status >= 400) {
+		throw new TypeError(
+			`Invalid success status code, expected status to be within \`[100;400[\`, got \`${status}\``,
+		);
+	}
+
+	return {
+		requestID,
+		status,
+		msg: statuses.message[status]?.replace(/\.$/, "").toLowerCase() ?? "",
+		data,
+	};
+};
+
+export const createErrorResponseMessage = <TError = undefined>(
+	requestID: string,
+	error: TError,
+	status: keyof typeof statuses.message = 400,
+): ErrorResponseMessage<TError> => {
+	if (status < 400) {
+		throw new TypeError(
+			`Invalid error status code, expected status to be within \`[500;600[\`, got \`${status}\``,
+		);
+	}
+
+	return {
+		requestID,
+		status,
+		msg: statuses.message[status]?.replace(/\.$/, "").toLowerCase() ?? "",
+		error,
+	};
+};
+
+export const validateMessage = (message: unknown): UnknownMessage => {
+	if (typeof message !== "object" || message === null) {
+		throw new TypeError(
+			`Invalid message received, expected message to be of type \`object\`, got \`${typeof message}\``,
+		);
+	} else if (
+		!Object.keys(message).every((key) =>
+			["requestID", "type", "data", "status", "msg", "error"].includes(key),
+		)
+	) {
+		throw new TypeError(`Invalid message received: ${JSON.stringify(message)}`);
+	} else if (
+		typeof (message as Record<string, unknown>).requestID !== "string"
+	) {
+		throw new TypeError(
+			`Invalid message received, expected \`message.requestID\` to be of type \`string\`, got \`${typeof (
+				message as Record<string, unknown>
+			).id}\``,
+		);
+	}
+
+	return message as UnknownMessage;
+};
+
+export const isRequestMessage = (
+	message: UnknownMessage,
+): message is UnknownRequestMessage => {
+	return "type" in message;
+};
+
+export const isResponseMessage = (
+	message: UnknownMessage,
+): message is UnknownResponseMessage => {
+	return !("type" in message);
+};
+
+export const isSuccessResponseMessage = (
+	message: UnknownMessage,
+): message is UnknownSuccessResponseMessage => {
+	return isResponseMessage(message) && !("error" in message);
+};
+
+export const isErrorResponseMessage = (
+	message: UnknownMessage,
+): message is UnknownErrorResponseMessage => {
+	return isResponseMessage(message) && !("data" in message);
+};

package/src/channel/types.ts

@@ -0,0 +1,138 @@
+// Messages
+export type MessageBase = {
+	requestID: string;
+};
+
+export type RequestMessage<TType extends string = string, TData = void> = {
+	type: TType;
+	data: TData;
+} & MessageBase;
+
+export type ResponseMessageBase = {
+	status: number;
+	msg: string;
+} & MessageBase;
+
+export type SuccessResponseMessage<TData = void> = {
+	data: TData;
+	error?: never;
+} & ResponseMessageBase;
+
+export type ErrorResponseMessage<TError = unknown> = {
+	data?: never;
+	error: unknown | TError;
+} & ResponseMessageBase;
+
+export type ResponseMessage<TData = void, TError = unknown> =
+	| SuccessResponseMessage<TData>
+	| ErrorResponseMessage<TError>;
+
+export type ExtractSuccessResponseMessage<
+	TResponse extends UnknownResponseMessage,
+> = Extract<TResponse, { error?: never }>;
+
+export type ExtractErrorResponseMessage<
+	TResponse extends UnknownResponseMessage,
+> = Extract<TResponse, { data?: never }>;
+
+// Unknown messages
+export type UnknownRequestMessage = RequestMessage<string, unknown>;
+
+export type UnknownSuccessResponseMessage = SuccessResponseMessage<unknown>;
+
+export type UnknownErrorResponseMessage = ErrorResponseMessage<unknown>;
+
+export type UnknownResponseMessage =
+	| UnknownSuccessResponseMessage
+	| UnknownErrorResponseMessage;
+
+export type UnknownMessage = UnknownRequestMessage | UnknownResponseMessage;
+
+// Transactions
+export type Transaction<
+	TRequest extends UnknownRequestMessage,
+	TResponse extends UnknownResponseMessage = ResponseMessage<void>,
+> = {
+	request: TRequest;
+	response: TResponse;
+};
+
+export type TransactionMethod<
+	TTransaction extends Transaction<
+		UnknownRequestMessage,
+		UnknownResponseMessage
+	>,
+> = (
+	data: TTransaction["request"]["data"],
+) => Promise<ExtractSuccessResponseMessage<TTransaction["response"]>>;
+
+export type TransactionHandler<
+	TTransaction extends Transaction<
+		UnknownRequestMessage,
+		UnknownResponseMessage
+	>,
+> = (
+	request: TTransaction["request"],
+	response: {
+		success: (
+			data: ExtractSuccessResponseMessage<TTransaction["response"]>["data"],
+			status?: number,
+		) => ExtractSuccessResponseMessage<TTransaction["response"]>;
+		error: (
+			error: ExtractErrorResponseMessage<TTransaction["response"]>["error"],
+			status?: number,
+		) => ExtractErrorResponseMessage<TTransaction["response"]>;
+	},
+) => Promise<TTransaction["response"]> | TTransaction["response"];
+
+export type TransactionsMethods<
+	TTransactions extends Record<string, UnknownTransaction>,
+> = {
+	[Key in keyof TTransactions]: TransactionMethod<TTransactions[Key]>;
+};
+
+export type TransactionsHandlers<
+	TTransactions extends Record<string, UnknownTransaction>,
+> = {
+	[Key in keyof TTransactions]: TransactionHandler<TTransactions[Key]>;
+};
+
+// Unknown transactions
+export type UnknownTransaction = Transaction<
+	UnknownRequestMessage,
+	UnknownResponseMessage
+>;
+
+export type UnknownTransactionMethod = TransactionMethod<UnknownTransaction>;
+
+export type UnknownTransactionHandler = TransactionHandler<UnknownTransaction>;
+
+// Emitter
+export enum InternalEmitterRequestType {
+	Connect = "connect",
+}
+
+export type InternalEmitterTransactions<
+	TReceiverOptions extends Record<string, unknown> = Record<string, unknown>,
+> = {
+	[InternalEmitterRequestType.Connect]: Transaction<
+		RequestMessage<
+			InternalEmitterRequestType.Connect,
+			| Partial<
+					Omit<TReceiverOptions, "debug" | "requestIDPrefix" | "readyTimeout">
+			  >
+			| undefined
+		>
+	>;
+};
+
+// Receiver
+export enum InternalReceiverRequestType {
+	Ready = "ready",
+}
+
+export type InternalReceiverTransactions = {
+	[InternalReceiverRequestType.Ready]: Transaction<
+		RequestMessage<InternalReceiverRequestType.Ready>
+	>;
+};

package/src/index.ts

@@ -0,0 +1,42 @@
+export {
+	SimulatorClient,
+	simulatorClientDefaultOptions,
+} from "./SimulatorClient";
+
+export { SimulatorAPI, simulatorAPIDefaultOptions } from "./SimulatorAPI";
+export type { SimulatorAPIOptions } from "./SimulatorAPI";
+
+export {
+	// Validators
+	validateMessage,
+	isRequestMessage,
+	isResponseMessage,
+	isSuccessResponseMessage,
+	isErrorResponseMessage,
+	// Error classes
+	ResponseError,
+	ConnectionTimeoutError,
+	TooManyConcurrentRequestsError,
+	RequestTimeoutError,
+	NotReadyError,
+	PortNotSetError,
+	ChannelNotSetError,
+} from "./channel";
+export type {
+	RequestMessage,
+	ResponseMessage,
+	ErrorResponseMessage,
+	SuccessResponseMessage,
+	AllChannelEmitterOptions,
+	AllChannelReceiverOptions,
+} from "./channel";
+
+export { APIRequestType, ClientRequestType } from "./types";
+export type {
+	ActiveSlice,
+	VariationSummary,
+	SliceSummary,
+	LibrarySummary,
+	APITransactions,
+	ClientTransactions,
+} from "./types";

package/src/kit/SimulatorManager.ts

@@ -0,0 +1,199 @@
+import type { SliceZone } from "@prismicio/client";
+
+import { throttle } from "../lib/throttle";
+
+import { ClientRequestType } from "../types";
+import { StateEventType } from "./types";
+
+import { SimulatorAPI } from "../SimulatorAPI";
+import { ResponseError } from "../channel";
+
+import { State } from "./State";
+import {
+	getSimulatorDOM,
+	getSimulatorRootDOM,
+	getSliceZoneDOM,
+} from "./domHelpers";
+import { sliceSimulatorAccessedDirectly } from "./messages";
+
+type ManagerConstructorArgs = {
+	slices?: SliceZone;
+};
+
+export class SimulatorManager {
+	public state: State;
+	private _api: SimulatorAPI | null;
+	private _initialized: boolean;
+
+	constructor(args?: ManagerConstructorArgs) {
+		this.state = new State(args);
+		this._api = null;
+		this._initialized = false;
+	}
+
+	async init(): Promise<void> {
+		if (this._initialized) {
+			return;
+		} else {
+			this._initialized = true;
+		}
+
+		// Init state manager
+		await this.state.init();
+
+		// Init API
+		try {
+			await this._initAPI();
+		} catch (error) {
+			if (
+				error instanceof Error &&
+				error.message === "Receiver is currently not embedded as an iframe" &&
+				!this.state.slices.length
+			) {
+				// Catch not embedded error and display message
+				this.state.message = sliceSimulatorAccessedDirectly;
+			}
+			console.error(error);
+
+			return;
+		}
+
+		// Init listeners
+		this._initListeners();
+	}
+
+	private async _initAPI(): Promise<void> {
+		// Register SimulatorAPI request handlers
+		this._api = new SimulatorAPI({
+			[ClientRequestType.SetSliceZone]: (req, res) => {
+				this.state.setSliceZone(req.data);
+
+				return res.success();
+			},
+			[ClientRequestType.ScrollToSlice]: (req, res) => {
+				// Error if `sliceIndex` is invalid
+				if (req.data.sliceIndex < 0) {
+					return res.error("`sliceIndex` must be > 0", 400);
+				} else if (req.data.sliceIndex >= this.state.slices.length) {
+					return res.error(
+						`\`sliceIndex\` must be < ${this.state.slices.length} (\`<SliceZone />\` current length)`,
+						400,
+					);
+				}
+
+				const $sliceZone = getSliceZoneDOM(this.state.slices.length);
+				if (!$sliceZone) {
+					return res.error("Failed to find `<SliceZone />`", 500);
+				}
+
+				// Destroy existing active slice as we're about to scroll
+				this.state.activeSlice = null;
+
+				const $slice = $sliceZone.children[req.data.sliceIndex];
+				if (!$slice) {
+					return res.error(
+						`Failed fo find slice at index $\`{req.data.sliceIndex}\` in \`<SliceZone />\``,
+						500,
+					);
+				}
+
+				// Scroll to Slice
+				$slice.scrollIntoView({
+					behavior: req.data.behavior,
+					block: req.data.block,
+					inline: req.data.inline,
+				});
+
+				// Update active slice after scrolling
+				this._api?.options.activeSliceAPI &&
+					setTimeout(this.state.setActiveSlice, 750);
+
+				return res.success();
+			},
+		});
+
+		// Mark API as ready
+		await this._api.ready();
+	}
+
+	private _initListeners(): void {
+		if (this._api?.options.activeSliceAPI) {
+			// Update active slice on mouse move
+			window.addEventListener("mousemove", () => {
+				this.state.setActiveSlice();
+			});
+			// Update active slice on events impacting slices rendering
+			window.addEventListener("resize", () => {
+				this.state.setActiveSlice();
+			});
+			window.addEventListener("mousewheel", () => {
+				this._api?.options.activeSliceAPI &&
+					setTimeout(this.state.setActiveSlice, 200);
+			});
+
+			// Update active slice when slices are set
+			this.state.on(StateEventType.Slices, () => {
+				this.state.setActiveSlice();
+			});
+			// Send active slices to renderer
+			this.state.on(StateEventType.ActiveSlice, async (activeSlice) => {
+				if (this._api) {
+					try {
+						await this._api.setActiveSlice(activeSlice);
+					} catch (error) {
+						// Just log bad requests, throw everything else
+						if (
+							error instanceof ResponseError &&
+							error.response.status === 400
+						) {
+							console.error(error.response);
+						} else {
+							throw error;
+						}
+					}
+				}
+			});
+		}
+
+		if (this._api?.options.sliceZoneSizeAPI) {
+			// Monitor Simulator root node size
+			const resizeObserver = new ResizeObserver(
+				throttle(async (entries) => {
+					const [entry] = entries;
+
+					if (this._api && entry) {
+						try {
+							await this._api.setSliceZoneSize({ rect: entry.contentRect });
+						} catch (error) {
+							// Just log bad requests, throw everything else
+							if (
+								error instanceof ResponseError &&
+								error.response.status === 400
+							) {
+								console.error(error.response);
+							} else {
+								throw error;
+							}
+						}
+					}
+				}, 16),
+			);
+			const observeSimulatorRoot = () => {
+				const simulatorRootDOM = getSimulatorRootDOM();
+				if (simulatorRootDOM) {
+					resizeObserver.disconnect();
+					resizeObserver.observe(simulatorRootDOM);
+				}
+			};
+
+			// Monitor Simulator root node in DOM
+			const mutationObserver = new MutationObserver(observeSimulatorRoot);
+			// We want it to fail if not found
+			// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+			mutationObserver.observe(getSimulatorDOM()!, {
+				subtree: false,
+				childList: true,
+			});
+		}
+	}
+}