# useDid

The `useDid` hook is a convenient utility for easily extracting and working with specific DID-related information from the `session.user` object. It simplifies parsing the user object to get commonly needed data like the permanent DID, wallet information, and connected accounts without manual processing.

This hook should be used within a component that is a child of the `SessionProvider` to ensure it has access to the session context.

## How to Use

To use the hook, import it along with `useSession`. Call `useSession` to get the current session state, and then pass the `session` object to `useDid`.

```javascript Basic Usage icon=logos:react
import { useSession } from '@arcblock/did-connect-react';
import { useDid } from '@arcblock/did-connect-react/lib/User';

function UserProfile() {
  const { session } = useSession();
  const {
    did,
    walletDid,
    connectedDids,
    sourceProvider,
    connectedAccounts,
  } = useDid({ session });

  if (!session.user) {
    return <p>Please log in to view your DID information.</p>;
  }

  return (
    <div>
      <h2>User DID Information</h2>
      <p><strong>Permanent DID:</strong> {did}</p>
      <p><strong>Wallet DID:</strong> {walletDid || 'N/A'}</p>
      <p><strong>Login Method:</strong> {sourceProvider}</p>
      <h3>Connected Accounts ({connectedAccounts.length})</h3>
      <ul>
        {connectedAccounts.map((account) => (
          <li key={account.did}>
            {account.provider}: {account.did}
          </li>
        ))}
      </ul>
    </div>
  );
}
```

## Parameters

The `useDid` hook accepts a single object as its parameter.

<x-field data-name="options" data-type="object" data-required="true">
  <x-field data-name="session" data-type="object" data-required="true" data-desc="The session object obtained from the `useSession` hook. The hook will only compute data when `session.user` is present.">
    <x-field data-name="user" data-type="object" data-required="false" data-desc="The user object provided by the session context after a successful login."></x-field>
  </x-field>
</x-field>

## Return Value

The hook returns a state object containing various pieces of derived DID information. This object will be updated whenever the `session.user` object changes.

<x-field-group>
  <x-field data-name="did" data-type="string" data-desc="The user's permanent DID. This is an alias for `permanentDid`."></x-field>
  <x-field data-name="wallet" data-type="object" data-desc="The connected account object where the provider is 'wallet'. Returns `undefined` if no wallet is connected.">
      <x-field data-name="did" data-type="string" data-desc="The DID of the wallet account."></x-field>
      <x-field data-name="provider" data-type="string" data-desc="The provider name, which will be 'wallet'."></x-field>
  </x-field>
  <x-field data-name="walletDid" data-type="string" data-desc="The DID of the user's connected wallet. Returns `undefined` if no wallet is connected."></x-field>
  <x-field data-name="permanentDid" data-type="string" data-desc="The user's permanent DID, which is the primary identifier from `user.did`."></x-field>
  <x-field data-name="connectedDids" data-type="string[]" data-desc="An array of all DIDs from the user's connected accounts."></x-field>
  <x-field data-name="connectedAccounts" data-type="object[]" data-desc="The full array of connected account objects.">
    <x-field data-name="did" data-type="string" data-desc="The DID of the connected account."></x-field>
    <x-field data-name="provider" data-type="string" data-desc="The provider of the account (e.g., 'wallet', 'github')."></x-field>
  </x-field>
  <x-field data-name="sourceProvider" data-type="string" data-desc="The provider the user originally used to log in (e.g., 'wallet', 'github'). Defaults to 'wallet'."></x-field>
  <x-field data-name="sourceProviders" data-type="string[]" data-desc="An array of all provider names from the user's connected accounts."></x-field>
</x-field-group>

## Standalone Helper Functions

The `useDid` hook is built on a set of exported helper functions. If you don't need the reactive state management of a hook and just want to extract a specific piece of information from a user object, you can import and use these functions directly.

| Function                 | Description                                                  |
| ------------------------ | ------------------------------------------------------------ |
| `getPermanentDid(user)`  | Extracts the permanent DID from the user object.             |
| `getWalletDid(user)`     | Extracts the DID of the connected wallet.                    |
| `getConnectedAccounts(user)` | Retrieves the array of connected accounts.                 |
| `getConnectedDids(user)`   | Retrieves an array of DIDs from all connected accounts.      |
| `getSourceProvider(user)`  | Gets the provider used for the initial login.                |
| `getSourceProviders(user)` | Gets an array of all connected provider names.               |
| `getWallet(user)`        | Finds and returns the complete wallet account object.        |

### Example: Using a Helper Function

```javascript Direct Function Usage icon=logos:javascript
import { getWalletDid } from '@arcblock/did-connect-react/lib/User/use-did';
import { useSession } from '@arcblock/did-connect-react';

// This approach can be useful inside event handlers or other non-React functions
function handleUserAction() {
  const { session } = useSession();
  if (session.user) {
    const walletDid = getWalletDid(session.user);
    console.log('User Wallet DID:', walletDid);
  }
}
```