https://github.com/aserto-dev/aserto-react
Aserto React SDK
https://github.com/aserto-dev/aserto-react
Last synced: about 1 year ago
JSON representation
Aserto React SDK
- Host: GitHub
- URL: https://github.com/aserto-dev/aserto-react
- Owner: aserto-dev
- License: other
- Created: 2020-12-21T04:38:59.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2024-11-18T11:10:01.000Z (over 1 year ago)
- Last Synced: 2025-03-29T02:41:59.969Z (about 1 year ago)
- Language: TypeScript
- Size: 2.64 MB
- Stars: 2
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Aserto React SDK
Loosely modeled after the [Auth0 React SDK](https://github.com/auth0/auth0-react).
This SDK uses the [Aserto javascript SPA SDK](https://github.com/aserto-dev/aserto-spa-js).
## Installation
Using [npm](https://npmjs.org):
```sh
npm install @aserto/aserto-react
```
Using [yarn](https://yarnpkg.com):
```sh
yarn add @aserto/aserto-react
```
## Getting Started
Configure the SDK by wrapping your application in `AsertoProvider`. If using in conjunction with the `Auth0Provider`, `AsertoProvider` should be nested inside of it.
```jsx
// src/index.tsx
import React from 'react'
import ReactDOM from 'react-dom'
import { AsertoProvider } from '@aserto/aserto-react'
import { Auth0Provider } from '@auth0/auth0-react'
import App from './App'
ReactDOM.render(
,
document.getElementById('app')
);
```
Use the `useAserto` hook in your components to initialize (`init`), reload the display state map (`reload`) or to access its state (`loading`, `displayStateMap`, `getDisplayState`, etc):
```jsx
// src/App.js
import React from 'react'
import { useAserto } from '@aserto/aserto-react'
import { useAuth0 } from '@auth0/auth0-react'
function App() {
const {
loading, // true while the state is loading
isLoaded, // true if the displayStateMap was loaded
error, // error object (if initOptions.throwOnError is false)
identity, // identity header to send to displaystatemap call
setIdentity, // set the identity header
displayStateMap, // display state map
getDisplayState, // getDisplayState() function (see below)
init, // init() function (see below)
reload // reload() function (see below)
} = useAserto();
// the Aserto hook needs a valid access token.
// to use Auth0 to return an access token, you can use the following:
const { isLoading, isAuthenticated, getAccessTokenSilently } = useAuth0();
// use an effect to load the Aserto display state map
useEffect(() => {
async function load() {
const token = await getAccessTokenSilently();
if (token) {
await init({ accessToken: token });
}
}
// load the display state map when Auth0 has finished initializing
if (!isLoading && isAuthenticated) {
load();
}
// eslint-disable-next-line react-hooks/exhaustive-deps
}, [isAuthenticated]);
if (loading) {
return
Loading...;
}
if (error) {
return
Error: {error};
} else {
return (
{
// output the display state map as a string
displayStateMap
}
);
}
}
export default App
```
### init(options, body)
Initialize the Aserto client using the (required) `options` map.
If the `body` parameter is passed in, it is passed through to the `AsertoClient` instance that will retrieve the display state map from the API endpoint (and used as the resource context for the `decisiontree` API call).
```js
const { init, displayStateMap } = useAserto();
await init({
serviceUrl: 'http://service-url', // defaults to windows.location.origin
endpointName: '/__displaystatemap', // defaults to '/__displaystatemap'
accessToken: '', // REQUIRED
throwOnError: true, // true: re-throw errors. false: set error object. defaults to true.
defaultDisplayState: { // an optional default display state (default values below)
visible: false,
enabled: false
}
});
// log the display state map to the console
console.log(displayStateMap);
```
### reload(body, headers)
Re-load the display state map for a service that exposes it.
If the `body` parameter is passed in, it is passed through to the `AsertoClient` instance that will retrieve the display state map from the API endpoint (and used as the resource context for the `decisiontree` API call).
If the `headers` parameter is passed in, it is likewise passed through to the `AsertoClient` instance that will retrieve the display state map from the API endpoint.
Note: `init()` must be called before `reload()`.
```js
const { reload, displayStateMap } = useAserto();
await reload();
// log the display state map to the console
console.log(displayStateMap);
```
### identity and setIdentity
- `setIdentity` can be used to set the identity to pass as an `identity` HTTP header. It will override an `identity` header that is passed into `reload(headers)`. This is the preferred way to send an identity to the displayStateMap API, which can be used to override the Authorization header by the `displayStateMap` middleware in the `express-jwt-aserto` Node.js SDK.
- `identity` will return the current identity (or undefined if it hasn't been set).
### getDisplayState('method, 'path')
Retrieves a displayState associated with a specific resource.
By convention, the `method` argument is an HTTP method (GET, POST, PUT, DELETE), and the `path` argument is in the form `/path/to/resource`. It may contain a `__id` component to indicate an parameter - for example, `/mycars/__id`.
If only the `method` argument is passed in, it is assumed to be a key into the `displayStateMap` (typically in the form of `METHOD/path/to/resource`).
The returned map will be in the following format:
```js
{
visible: true,
enabled: false,
}
```
Note: `init()` must be called before `getDisplayState()`.
```js
const { getDisplayState } = useAserto();
const path = '/api/path';
// retrieve visibility of an element
const isVisible = aserto.getDisplayState('GET', path).visible;
// determine whether an update operation is enabled
const isUpdateEnabled = aserto.getDisplayState('PUT', path).enabled;
// print out display state values for each verb on a resource
for (const verb of ['GET', 'POST', 'PUT', 'DELETE']) {
const resource = aserto.getDisplayState(verb, path));
for (const value of ['visible', 'enabled']) {
console.log(`${verb} ${path} ${value} is ${resource[verb][value]}`);
}
}
```