Captain is currently in ALPHA. We are happy to get your feedback
SDK
@captn/react
Modules
Use Sdk

Module: use-sdk

Table of contents

Functions

Functions

useSDK

▸ useSDK<T, R>(appId, options): Object

Provides a React hook for establishing and managing Inter-Process Communication (IPC) with an SDK. This hook facilitates sending messages to and receiving messages from the SDK, handling files, and navigating directories, thereby incorporating robust error handling and abstracting the intricacies of IPC messaging for minimal setup. React's useCallback, useEffect, and useRef hooks are utilized to ensure an efficient, memory-safe implementation. Error handling is deeply integrated, enabling consumers to appropriately respond to communication and operation issues.

Type parameters

NameDescription
TThe type of messages being sent to the SDK, constrained to be an object with string keys.
RThe type of messages expected from the SDK, also constrained to be an object with string keys.

Parameters

NameTypeDescription
appIdstringA unique identifier for the application or SDK instance. This ID is used to construct the IPC channel name, ensuring correct message routing.
optionsObjectConfiguration options for the hook, including callbacks for message reception and error handling.
options.onErrorundefined | FunctionAn optional callback function for handling errors that occur during IPC communication or file operations, including message sending failures, subscription issues, or file operation errors. The error object is passed to this callback.
options.onMessageundefined | FunctionAn optional callback function invoked when a message is received from the SDK. The received message is passed as an argument, allowing the consuming component to process or react to it.

Returns

Object

An object containing:

  • channel: The constructed IPC channel name for debugging or informational purposes.
  • send: A function to send messages to the SDK. This function is memoized and designed to internally catch and handle errors, invoking onError if provided.
  • getFilePath: A function to get the path of a specific file, leveraging the IPC mechanism.
  • getDirectoryPath: A function to get the path of a specific directory, leveraging the IPC mechanism.
  • readFile: A function to read the content of a file, encapsulating the IPC file reading capabilities.
  • writeFile: A function to write content to a file, encapsulating the IPC file writing capabilities.
NameType
channelstring
copyFileWithMetadata(options: any) => Promise<void | {}[]>
getDirectoryPath() => Promise<string>
getFilePath() => Promise<string>
readFile(name: any, encoding: any) => Promise<string>
send(message: any) => void
writeFile(name: any, content: any, options: any, context: any) => Promise<{}>

Example

// Using the `useSDK` hook within a component
const App = () => {
  const { send, readFile, writeFile } = useSDK("myAppId", {
    onMessage: (message) => {
      console.log("Received message from SDK:", message.action, message.payload);
    },
    onError: (error) => {
      console.error("An error occurred:", error);
    }
  });
 
  // Example usage of readFile and writeFile
  const handleFileOperations = async () => {
    try {
      const filePath = await writeFile('test.txt', 'Hello SDK!', { encoding: 'utf8' });
      const content = await readFile(filePath, 'utf8');
      console.log('File content:', content);
    } catch (error) {
      console.error('File operation error:', error);
    }
  };
 
  return (
    <div>
      <button onClick={() => send({ action: "greet", payload: "Hello, SDK!" })}>
        Send Message
      </button>
      <button onClick={handleFileOperations}>
        Test File Operations
      </button>
    </div>
  );
};

Remarks

  • The hook is flexible and easy to integrate, requiring just an appId and optional onMessage and onError callbacks for setup.
  • Proper handling of options.onError is crucial to ensure errors are not overlooked. This may involve UI updates, error logging, or other strategies appropriate for the application context.
  • The hook manages subscriptions to prevent memory leaks, automatically cleaning up on component unmount.
  • While the hook simplifies IPC communication, a basic understanding of IPC mechanisms and file operations is beneficial for effective use and handling potential edge cases or errors.

Defined in

react/dist/esm/use-sdk/index.js:84

Use save ImageUse Seed