Add RPC-like API for data exchange between the plugin/widget’s main and UI contexts

[isBatak]

Implementing an RPC-like API, similar to figma-jsonrpc, would improve data exchange between the plugin/widget’s main and UI contexts.
This approach would simplify integration with libraries like SWR and React Query.

[isBatak]

This is my current implementation:

// rpc.ts
import { emit, on, type EventHandler } from '@create-figma-plugin/utilities'

type RPCRequest<TParams = unknown[]> = {
  jsonrpc: '2.0'
  method: string
  params?: TParams
  id?: number
}

type RPCResponse<TResult = unknown, TErrorData = unknown> = {
  jsonrpc: '2.0'
  id: number
  result?: TResult
  error?: { code: number; message: string; data?: TErrorData }
}

type PendingRequest<TResult = unknown, TErrorData = unknown> = {
  timeout: NodeJS.Timeout
  (error: { code: number; message: string; data?: TErrorData } | null, result: TResult | null): void
}

type Procedure = (...args: unknown[]) => unknown
type Procedures = Record<string, Procedure>

export class RPCError<TData = unknown> extends Error {
  data?: TData
  statusCode: number

  constructor(message: string, statusCode: number, data?: TData) {
    super(message)
    this.name = this.constructor.name
    this.statusCode = statusCode
    this.data = data

    if (Error.captureStackTrace) {
      Error.captureStackTrace(this, this.constructor)
    }
  }
}

export class ParseError<TData = unknown> extends RPCError<TData> {
  constructor(data?: TData) {
    super('Parse error', -32700, data)
  }
}

export class InvalidRequest<TData = unknown> extends RPCError<TData> {
  constructor(data?: TData) {
    super('Invalid Request', -32600, data)
  }
}

export class MethodNotFound<TData = unknown> extends RPCError<TData> {
  constructor(data?: TData) {
    super('Method not found', -32601, data)
  }
}

export class InvalidParams<TData = unknown> extends RPCError<TData> {
  constructor(data?: TData) {
    super('Invalid params', -32602, data)
  }
}

export class InternalError<TData = unknown> extends RPCError<TData> {
  constructor(data?: TData) {
    super('Internal error', -32603, data)
  }
}

type RPCMessage =
  | RPCRequest<unknown[]> // Request with parameters
  | RPCResponse<unknown> // Response with result or error

type RPCMethods = Record<string, (...args: unknown[]) => unknown>

export interface SettingsHandler extends EventHandler {
  name: 'RPC'
  handler: (message: RPCMessage) => void
}

let rpcIndex = 0
const pending: Record<number, PendingRequest<unknown, unknown>> = {}
let globalMethods: RPCMethods = {}

on<SettingsHandler>('RPC', (message) => {
  handleRaw(message)
})

function sendRaw(message: RPCMessage) {
  emit<SettingsHandler>('RPC', message)
}

// Helper functions for sending messages
function sendJson(req: RPCRequest | RPCResponse) {
  try {
    sendRaw(req)
  } catch (err) {
    console.error(err)
  }
}

function sendResult<T = unknown>(id: number, result: T) {
  sendJson({ jsonrpc: '2.0', id, result })
}

function sendError(id: number, error: RPCError) {
  sendJson({
    jsonrpc: '2.0',
    id,
    error: {
      code: error.statusCode,
      message: error.message,
      data: error.data,
    },
  })
}

// Handle incoming messages
function handleRaw(data: RPCMessage | null | undefined) {
  try {
    if (!data) return
    handleRpc(data)
  } catch (err) {
    console.error(err, data)
  }
}

function handleRpc(json: RPCMessage) {
  if (typeof json.id !== 'undefined') {
    if ('result' in json || 'error' in json || !('method' in json)) {
      const callback = pending[json.id]
      if (!callback) {
        sendError(json.id, new MethodNotFound('Missing callback for ' + json.id))
        return
      }
      if (callback.timeout) {
        clearTimeout(callback.timeout)
      }
      delete pending[json.id]
      callback(json.error || null, json.result)
    } else {
      handleRequest(json as RPCRequest & { id: number })
    }
  } else {
    handleNotification(json as RPCRequest)
  }
}

function handleNotification(json: RPCRequest) {
  if (!json.method) return

  onRequest(json.method, json.params ?? [])
}

function handleRequest(json: RPCRequest & { id: number }) {
  if (!json.method) {
    sendError(json.id, new InvalidRequest('Missing method'))
    return
  }
  try {
    const result = onRequest(json.method, json.params ?? [])

    if (result instanceof Promise) {
      result
        .then((res) => sendResult(json.id, res))
        .catch((err: RPCError) => sendError(json.id, err))
    } else {
      sendResult(json.id, result)
    }
  } catch (err) {
    sendError(json.id, err as RPCError)
  }
}

function onRequest(method: string, params: unknown[]): ReturnType<Procedures[string]> {
  if (!globalMethods[method]) {
    throw new MethodNotFound(method)
  }
  return Promise.resolve(globalMethods[method](...params))
}

export function setup(_methods: RPCMethods) {
  globalMethods = { ...globalMethods, ..._methods }
}

export function sendNotification(method: string, params?: unknown[]) {
  sendJson({ jsonrpc: '2.0', method, params })
}

export function sendRequest<T>(method: string, params?: unknown[], timeout = 3000): Promise<T> {
  return new Promise((resolve, reject) => {
    const id = rpcIndex++
    const req: RPCRequest & { id: number } = { jsonrpc: '2.0', method, params, id }

    const callback: PendingRequest = (err, result) => {
      if (err) {
        const jsError = new Error(err.message) as Error & { code?: number; data?: unknown }
        jsError.code = err.code
        jsError.data = err.data
        reject(jsError)
        return
      }
      resolve(result as T)
    }

    callback.timeout = setTimeout(() => {
      delete pending[id]
      reject(new Error(`Request ${method} timed out.`))
    }, timeout)

    pending[id] = callback
    sendJson(req)
  })
}

interface APIOptions {
  timeout?: number
}

export function createUiAPI<TProcedures extends Procedures>(
  methods: TProcedures,
  options?: APIOptions,
): TProcedures {
  const timeout = options?.timeout

  if (typeof parent !== 'undefined') {
    setup(methods)
  }

  return Object.keys(methods).reduce((api, method) => {
    api[method as keyof TProcedures] = ((...params: Parameters<TProcedures[typeof method]>) => {
      if (typeof parent !== 'undefined') {
        return Promise.resolve().then(() => methods[method](...params))
      }
      return sendRequest(method, params, timeout)
    }) as TProcedures[typeof method]

    return api
  }, {} as TProcedures)
}

export function createPluginAPI<TProcedures extends Procedures>(
  methods: TProcedures,
  options?: APIOptions,
): TProcedures {
  const timeout = options?.timeout

  if (typeof figma !== 'undefined') {
    setup(methods)
  }

  return Object.keys(methods).reduce((api, method) => {
    api[method as keyof TProcedures] = ((...params: Parameters<TProcedures[typeof method]>) => {
      if (typeof figma !== 'undefined') {
        return Promise.resolve().then(() => methods[method](...params))
      }
      return sendRequest(method, params, timeout)
    }) as TProcedures[typeof method]

    return api
  }, {} as TProcedures)
}

Setup:

// api.ts

import { createUiAPI, createPluginAPI } from './libs/rpc'
import { getTokensImportMetadata, importTokens } from './backend/services/tokens'

export const backendApi = createPluginAPI(
  {
    getTokensImportMetadata,
    importTokens,
  },
  {
    timeout: 10000,
  },
)

export const frontendApi = createUiAPI({})

SWR Hook:

import { backendApi } from '../../api'
import useSWR from 'swr'

export const importTokensMetadataKey = 'import-tokens-metadata'

export const useImportTokensMetadata = () => {
  return useSWR(importTokensMetadataKey, backendApi.getTokensImportMetadata)
}

export function useImportTokensMutation(
  options: SWRMutationConfiguration<TokensImportMetadata, unknown, Key, unknown> = {},
) {
  return useMutation(importTokensMetadataKey, backendApi.importTokens, options)
}

Usage:

export const TokensPage = () => {
  const { data: importTokensMetadata } = useImportTokensMetadata()
  const { trigger, isMutating } = useImportTokensMutation({
    populateCache: true,
  })

 return <Button onClick={() => trigger()} loading={isMutating}>{importTokensMetadata.timestamp}</Button>