@medplum/react-hooks
Advanced tools
Comparing version 3.1.8 to 3.1.9
@@ -15,2 +15,3 @@ /// <reference types="react" /> | ||
import { ResourceType } from '@medplum/fhirtypes'; | ||
import { Subscription } from '@medplum/fhirtypes'; | ||
@@ -122,4 +123,17 @@ export declare interface MedplumContext { | ||
export declare function useSubscription(criteria: string, callback: (bundle: Bundle) => void): void; | ||
/** | ||
* Creates an in-memory `Subscription` resource with the given criteria on the Medplum server and calls the given callback when an event notification is triggered by a resource interaction over a WebSocket connection. | ||
* | ||
* Subscriptions created with this hook are lightweight, share a single WebSocket connection, and are automatically untracked and cleaned up when the containing component is no longer mounted. | ||
* | ||
* @param criteria - The FHIR search criteria to subscribe to. | ||
* @param callback - The callback to call when a notification event `Bundle` for this `Subscription` is received. | ||
* @param options - Optional options used to configure the created `Subscription`. | ||
*/ | ||
export declare function useSubscription(criteria: string, callback: (bundle: Bundle) => void, options?: UseSubscriptionOptions): void; | ||
export declare type UseSubscriptionOptions = { | ||
subscriptionProps?: Partial<Subscription>; | ||
}; | ||
export { } |
@@ -15,2 +15,3 @@ /// <reference types="react" /> | ||
import { ResourceType } from '@medplum/fhirtypes'; | ||
import { Subscription } from '@medplum/fhirtypes'; | ||
@@ -122,4 +123,17 @@ export declare interface MedplumContext { | ||
export declare function useSubscription(criteria: string, callback: (bundle: Bundle) => void): void; | ||
/** | ||
* Creates an in-memory `Subscription` resource with the given criteria on the Medplum server and calls the given callback when an event notification is triggered by a resource interaction over a WebSocket connection. | ||
* | ||
* Subscriptions created with this hook are lightweight, share a single WebSocket connection, and are automatically untracked and cleaned up when the containing component is no longer mounted. | ||
* | ||
* @param criteria - The FHIR search criteria to subscribe to. | ||
* @param callback - The callback to call when a notification event `Bundle` for this `Subscription` is received. | ||
* @param options - Optional options used to configure the created `Subscription`. | ||
*/ | ||
export declare function useSubscription(criteria: string, callback: (bundle: Bundle) => void, options?: UseSubscriptionOptions): void; | ||
export declare type UseSubscriptionOptions = { | ||
subscriptionProps?: Partial<Subscription>; | ||
}; | ||
export { } |
{ | ||
"name": "@medplum/react-hooks", | ||
"version": "3.1.8", | ||
"version": "3.1.9", | ||
"description": "Medplum React Hooks Library", | ||
@@ -60,11 +60,11 @@ "keywords": [ | ||
"devDependencies": { | ||
"@medplum/core": "3.1.8", | ||
"@medplum/definitions": "3.1.8", | ||
"@medplum/fhirtypes": "3.1.8", | ||
"@medplum/mock": "3.1.8", | ||
"@medplum/core": "3.1.9", | ||
"@medplum/definitions": "3.1.9", | ||
"@medplum/fhirtypes": "3.1.9", | ||
"@medplum/mock": "3.1.9", | ||
"@testing-library/dom": "10.1.0", | ||
"@testing-library/jest-dom": "6.4.5", | ||
"@testing-library/react": "15.0.7", | ||
"@testing-library/jest-dom": "6.4.6", | ||
"@testing-library/react": "16.0.0", | ||
"@types/jest": "29.5.12", | ||
"@types/node": "20.14.0", | ||
"@types/node": "20.14.2", | ||
"@types/react": "18.3.3", | ||
@@ -81,3 +81,3 @@ "@types/react-dom": "18.3.0", | ||
"peerDependencies": { | ||
"@medplum/core": "3.1.8", | ||
"@medplum/core": "3.1.9", | ||
"react": "^17.0.2 || ^18.0.0", | ||
@@ -84,0 +84,0 @@ "react-dom": "^17.0.2 || ^18.0.0" |
124
README.md
@@ -9,5 +9,6 @@ # Medplum React Hooks Library | ||
- `useMedplum` - handles shared global instance of `MedplumClient` | ||
- [`useMedplum`](#usemedplum) - handles shared global instance of `MedplumClient` | ||
- `useResource` - reads a resource by ID or reference with intelligent caching | ||
- `useSearch` - performs a FHIR search with intelligent state management | ||
- [`useSubscription`](#usesubscription) - subscribes to a FHIR search criteria and calls a given callback upon receiving a relevant notification | ||
@@ -87,2 +88,121 @@ ## Installation | ||
## `useSubscription` | ||
`useSubscription` creates an in-memory `Subscription` resource with the given criteria on the Medplum server and calls the given callback when an event notification is triggered by a resource interaction over a WebSocket connection. | ||
Subscriptions created with this hook are lightweight, share a single WebSocket connection, and are automatically untracked and cleaned up when the containing component is no longer mounted. | ||
```tsx | ||
function MyComponent(): JSX.Element { | ||
const [notificationCount, setNotificationCount] = useState(0); | ||
useSubscription( | ||
'Communication?sender=Practitioner/abc-123&recipient=Practitioner/me-456', | ||
(bundle: Bundle) => { | ||
console.log('Received a message from Practitioner/abc-123!'); | ||
handleNotificationBundle(bundle); // Do something with the bundle | ||
setNotificationCount(s => s + 1); | ||
} | ||
); | ||
return <div>Notifications received: {notificationCount}</div>; | ||
} | ||
``` | ||
### Subscription Extensions | ||
Any [Subscription extension](https://www.medplum.com/docs/subscriptions/subscription-extensions) supported by Medplum can be attached to a `Subscription` created by the `useSubscription` hook via a 3rd optional parameter to the hook, `options`, which takes an optional `subscriptionProps`. | ||
```tsx | ||
type UseSubscriptionOptions = { | ||
subscriptionProps?: Partial<Subscription>; | ||
} | ||
``` | ||
Here's how you would subscribe to only `create` interactions for a criteria: | ||
```tsx | ||
const createOnlyOptions = { | ||
subscriptionProps: { | ||
extension: [ | ||
{ | ||
url: 'https://medplum.com/fhir/StructureDefinition/subscription-supported-interaction', | ||
valueCode: 'create', | ||
}, | ||
], | ||
} | ||
}; | ||
function MyComponent(): JSX.Element { | ||
const [createCount, setCreateCount] = useState(0); | ||
useSubscription( | ||
'Communication?sender=Practitioner/abc-123&recipient=Practitioner/me-456', | ||
(_bundle) => { | ||
console.log('Received a new message from Practitioner/abc-123!'); | ||
setCreateCount(s => s + 1); | ||
}, | ||
createOnlyOptions, | ||
); | ||
return <div>Create notifications received: {createCount}</div>; | ||
} | ||
``` | ||
Subscriptions with the same criteria are tracked separately if they have differing `subscriptionProps`. This means you can create one `Subscription` to listen for `create` interactions and another for `update` interactions and they will not interfere with each other. | ||
```tsx | ||
const createOnlyOptions = { | ||
subscriptionProps: { | ||
extension: [ | ||
{ | ||
url: 'https://medplum.com/fhir/StructureDefinition/subscription-supported-interaction', | ||
valueCode: 'create', | ||
}, | ||
], | ||
} | ||
}; | ||
const updateOnlyOptions = { | ||
subscriptionProps: { | ||
extension: [ | ||
{ | ||
url: 'https://medplum.com/fhir/StructureDefinition/subscription-supported-interaction', | ||
valueCode: 'update', | ||
}, | ||
], | ||
} | ||
}; | ||
function MyComponent(): JSX.Element { | ||
const [createCount, setCreateCount] = useState(0); | ||
const [updateCount, setUpdateCount] = useState(0); | ||
useSubscription( | ||
'Communication?sender=Practitioner/abc-123&recipient=Practitioner/me-456', | ||
(_bundle) => { | ||
console.log('Received a new message from Practitioner/abc-123!'); | ||
setCreateCount(s => s + 1); | ||
}, | ||
createOnlyOptions, | ||
); | ||
useSubscription( | ||
'Communication?sender=Practitioner/abc-123&recipient=Practitioner/me-456', | ||
(_bundle) => { | ||
console.log('Received an update to message from Practitioner/abc-123!'); | ||
setUpdateCount(s => s + 1); | ||
}, | ||
updateOnlyOptions, | ||
); | ||
return ( | ||
<> | ||
<div>Create notifications received: {createCount}</div> | ||
<div>Update notifications received: {updateCount}</div> | ||
</> | ||
); | ||
} | ||
``` | ||
## About Medplum | ||
@@ -94,2 +214,2 @@ | ||
Apache 2.0. Copyright © Medplum 2023 | ||
Apache 2.0. Copyright © Medplum 2024 |
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
72981
267
213