TypeScript Utilities for EIP-6963: Multi Injected Provider Discovery
## Contents
- [Install](#install)
- [Store](#store)
- [Utilities](#utilities)
- [`requestProviders`](#requestproviders)
- [`announceProvider`](#announceprovider)
- [`window` Type Polyfill](#window-polyfill)
- [Types](#types)
- [Configuration](#configuration)
## Install
```bash
npm i mipd
```
```bash
pnpm add mipd
```
```bash
yarn add mipd
```
## Store
The MIPD Store stores the Providers that have been emitted by a Wallet (or other source), and provides a way to subscribe to the store and retrieve the Providers.
### Overview
```ts
import { createStore } from 'mipd'
// Set up a MIPD Store, and request Providers.
const store = createStore()
// Subscribe to the MIPD Store.
store.subscribe(providerDetails => {
console.log(providerDetails)
// => [EIP6963ProviderDetail, EIP6963ProviderDetail, ...]
})
// Retrieve emitted Providers.
store.getProviders()
// => [EIP6963ProviderDetail, EIP6963ProviderDetail, ...]
// Find a Provider Detail.
store.findProvider({ rdns: 'com.example' })
// => EIP6963ProviderDetail | undefined
// Clear the store, including all Providers.
store.clear()
// Reset the store, and emit an event to request Providers.
store.reset()
// Destroy the store, and remove all Providers and event listeners.
store.destroy()
```
### Usage
#### Vanilla JS
```tsx
import { useSyncExternalStore } from 'react'
import { createStore } from 'mipd'
const store = createStore()
let providers = store.getProviders()
store.subscribe(providerDetails => (providers = providerDetails))
```
#### React
```tsx
import { useSyncExternalStore } from 'react'
import { createStore } from 'mipd'
const store = createStore()
function Example() {
const providers = useSyncExternalStore(store.subscribe, store.getProviders)
// ...
}
```
#### Svelte
```html
```
#### Vue
```html
```
### API
#### createStore()
Creates a MIPD Store, and emits an event to request Providers from the Wallet(s).
```ts
const store = createStore()
```
#### store.subscribe(listener, args)
Subscribes to the MIPD Store, and returns a function to unsubscribe.
```ts
const unsubscribe = store.subscribe(providers => {
console.log(providers)
// => [EIP6963ProviderDetail, EIP6963ProviderDetail, ...]
})
```
**Definition**
```ts
export type Listener = (
// The updated Providers store.
providerDetails: EIP6963ProviderDetail[],
meta?: {
// The Providers that were added to the store.
added?: EIP6963ProviderDetail[]
// The Providers that were removed from the store.
removed?: EIP6963ProviderDetail[]
},
) => void
function subscribe(
// The listener function.
listener: Listener,
args?: {
// If `true`, the listener will be called immediately with the stored Providers.
emitImmediately?: boolean
}
): () => void // Returns an unsubscribe function.
```
#### store.getProviders()
Returns the current Providers.
```ts
const providers = store.getProviders()
// => [EIP6963ProviderDetail, EIP6963ProviderDetail, ...]
```
**Definition**
```ts
function getProviders(): EIP6963ProviderDetail[]
```
#### store.findProvider(args)
Finds a provider detail by its RDNS (Reverse Domain Name Identifier).
```ts
const provider = store.findProvider({ rdns: 'com.example' })
```
**Definition**
```ts
function findProvider(args: {
// The RDNS of the Provider Detail to find.
rdns: string
}): EIP6963ProviderDetail | undefined
```
#### store.clear()
Clears the store, including all Providers.
```ts
store.clear()
```
**Definition**
```ts
function clear(): void
```
#### store.reset()
Resets the store, and emits an event to request Providers from the Wallet(s).
```ts
store.reset()
```
**Definition**
```ts
function reset(): void
```
#### store.destroy()
Destroys the store, and removes all Providers and event listeners.
```ts
store.destroy()
```
**Definition**
```ts
function destroy(): void
```
## Utilities
### requestProviders
The `requestProviders` utility emits an event to request Providers from the Wallet(s). It returns an `unsubscribe` function to clean up event listeners.
```ts
import { requestProviders } from 'mipd'
let providers = []
const unsubscribe = requestProviders(providerDetail => providers.push(providerDetail))
```
**Definition**
```ts
function requestProviders(
// The listener.
listener: (providerDetail: EIP6963ProviderDetail) => void
// Unsubscribe function to clean up the listener.
): () => void
```
### announceProvider
The `announceProvider` utility emits an event to announce a Provider to the Wallet(s), and also listen for incoming requests. It returns an `unsubscribe` function to clean up event listeners.
```ts
import { announceProvider } from 'mipd'
const unsubscribe = announceProvider({
info: {
icon: 'data:image/svg+xml,',
name: 'Example',
rdns: 'com.example',
uuid: '00000000-0000-0000-0000-000000000000'
},
provider: new EIP1193Provider()
})
```
**Definition**
```ts
function requestProviders(
// The EIP-1193 Provider and Provider Info.
detail: EIP6963ProviderDetail
// Unsubscribe function to clean up the listener.
): () => void
```
## `window` Polyfill
By importing the `mipd/window` Polyfill, the types on `window.addEventListener` will be inferred to include the `EIP6963AnnounceProviderEvent` and `EIP6963RequestProviderEvent` types.
```ts
import 'mipd/window'
window.addEventListener(
'eip6963:announceProvider'
// ^? 'eip6963:announceProvider' | 'eip6963:requestProvider' | 'click' | ...
event => {
// ^? EIP6963AnnounceProviderEvent
event.type
// ^? 'eip6963:announceProvider'
event.detail
// ^? EIP6963ProviderDetail
event.detail.info
// ^? EIP6963ProviderInfo
event.detail.provider
// ^? EIP1193Provider
}
)
window.addEventListener(
'eip6963:requestProvider'
// ^? 'eip6963:announceProvider' | 'eip6963:requestProvider' | 'click' | ...
event => {
// ^? EIP6963RequestProviderEvent
event.type
// ^? 'eip6963:requestProvider'
}
)
```
## Types
### EIP6963ProviderDetail
Event detail from `eip6963:announceProvider`.
#### Import
```ts
import { type EIP6963ProviderDetail } from 'mipd'
```
#### Definition
```ts
export interface EIP6963ProviderDetail