-
Notifications
You must be signed in to change notification settings - Fork 10
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
feat: Add
@cerbos/react
package (#876)
* @cerbos/react initial commit Signed-off-by: Hasan Ayan <hasanayan@me.com> * address PR comments Signed-off-by: Hasan Ayan <hasanayan@me.com> * move eslint-plugin-react-hooks to the react package deps Signed-off-by: Hasan Ayan <hasanayan@me.com> * remove unnecessary dependency Signed-off-by: Hasan Ayan <hasanayan@me.com> * docs improvements Signed-off-by: Hasan Ayan <hasanayan@me.com> * Optimise deep equality check and refactor `useCerbosRequest` Signed-off-by: Andrew Haines <haines@cerbos.dev> Signed-off-by: Hasan Ayan <hasanayan@me.com> * Just add the dependency... Signed-off-by: Andrew Haines <haines@cerbos.dev> Signed-off-by: Hasan Ayan <hasanayan@me.com> * improve docs Signed-off-by: Hasan Ayan <hasanayan@me.com> * add tests Signed-off-by: Hasan Ayan <hasanayan@me.com> * docs improvements Signed-off-by: Hasan Ayan <hasanayan@me.com> * resolve conflicts Signed-off-by: Hasan Ayan <hasanayan@me.com> * add changelog.yaml Signed-off-by: Hasan Ayan <hasanayan@me.com> * fix test env setup Signed-off-by: Hasan Ayan <hasanayan@me.com> * implement AbortSignal Signed-off-by: Hasan Ayan <hasanayan@me.com> * address PR comments Signed-off-by: Hasan Ayan <hasanayan@me.com> * regenerate docs Signed-off-by: Hasan Ayan <hasanayan@me.com> * bring back !aborted check in the then block Signed-off-by: Hasan Ayan <hasanayan@me.com> --------- Signed-off-by: Hasan Ayan <hasanayan@me.com> Signed-off-by: Andrew Haines <haines@cerbos.dev> Co-authored-by: Andrew Haines <haines@cerbos.dev>
- Loading branch information
Showing
32 changed files
with
2,566 additions
and
9 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,25 @@ | ||
<!-- Do not edit this file. It is automatically generated by API Documenter. --> | ||
|
||
[Home](./index.md) > [@cerbos/react](./react.md) > [AsyncResult](./react.asyncresult.md) | ||
|
||
## AsyncResult type | ||
|
||
The result of calling an async method on a client. | ||
|
||
**Signature:** | ||
|
||
```typescript | ||
export type AsyncResult<T> = { | ||
isLoading: true; | ||
data: undefined; | ||
error: undefined; | ||
} | { | ||
isLoading: false; | ||
data: T; | ||
error: undefined; | ||
} | { | ||
isLoading: false; | ||
data: undefined; | ||
error: Error; | ||
}; | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,98 @@ | ||
<!-- Do not edit this file. It is automatically generated by API Documenter. --> | ||
|
||
[Home](./index.md) > [@cerbos/react](./react.md) > [CerbosProvider](./react.cerbosprovider.md) | ||
|
||
## CerbosProvider() function | ||
|
||
A component to provide a Cerbos client to your application's components. | ||
|
||
**Signature:** | ||
|
||
```typescript | ||
export declare function CerbosProvider({ children, client, principal, auxData, }: CerbosProviderProps): ReactElement; | ||
``` | ||
|
||
## Parameters | ||
|
||
<table><thead><tr><th> | ||
|
||
Parameter | ||
|
||
|
||
</th><th> | ||
|
||
Type | ||
|
||
|
||
</th><th> | ||
|
||
Description | ||
|
||
|
||
</th></tr></thead> | ||
<tbody><tr><td> | ||
|
||
{ children, client, principal, auxData, } | ||
|
||
|
||
</td><td> | ||
|
||
[CerbosProviderProps](./react.cerbosproviderprops.md) | ||
|
||
|
||
</td><td> | ||
|
||
|
||
</td></tr> | ||
</tbody></table> | ||
**Returns:** | ||
|
||
ReactElement | ||
|
||
## Remarks | ||
|
||
The provider should be placed close to the root of your application. | ||
|
||
You need to provide a principal, but it can describe an anonymous user so that you can perform permission checks for unauthenticated users. You could use a single hardcoded ID for all anonymous users, or store a unique identifier in the session. | ||
|
||
You can use whichever of the [HTTP](https://github.com/cerbos/cerbos-sdk-javascript/blob/main/packages/http/README.md) or [embedded](https://github.com/cerbos/cerbos-sdk-javascript/blob/main/packages/embedded/README.md) client libraries best fit your needs. | ||
|
||
## Example | ||
|
||
|
||
```typescript | ||
import { Embedded as Cerbos } from "@cerbos/embedded"; | ||
* // or, import { HTTP as Cerbos } from "@cerbos/http"; | ||
import { CerbosProvider } from "@cerbos/react"; | ||
|
||
// Initialize the Cerbos client using any of the client libraries | ||
// that fit the needs of your application. In this example we are | ||
// using the client from `@cerbos/embedded`. | ||
const client = new Cerbos(); | ||
|
||
function MyApp({ children }) { | ||
const user = useYourAuthenticationLogic(...); | ||
|
||
return ( | ||
<CerbosProvider | ||
client={client} | ||
principal={ | ||
user | ||
? { | ||
id: user.id, | ||
roles: user.roles, | ||
} | ||
: { | ||
// Define an arbitrary ID for unauthenticated users. | ||
id: "###ANONYMOUS_USER###", | ||
// Define a role that represents unauthenticated users (at least one is required). | ||
roles: ["anonymous"], | ||
} | ||
} | ||
> | ||
{children} | ||
</CerbosProvider> | ||
); | ||
} | ||
``` | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,18 @@ | ||
<!-- Do not edit this file. It is automatically generated by API Documenter. --> | ||
|
||
[Home](./index.md) > [@cerbos/react](./react.md) > [CerbosProviderProps](./react.cerbosproviderprops.md) > [auxData](./react.cerbosproviderprops.auxdata.md) | ||
|
||
## CerbosProviderProps.auxData property | ||
|
||
Auxiliary data related to the principal. | ||
|
||
**Signature:** | ||
|
||
```typescript | ||
auxData?: Pick<AuxData, "jwt"> | undefined; | ||
``` | ||
|
||
## Remarks | ||
|
||
You can read claims directly from a JWT in your authorization policies by configuring [the Cerbos policy decision point (PDP) service](https://docs.cerbos.dev/cerbos/latest/configuration/auxdata.html) or [an embedded PDP client](https://github.com/cerbos/cerbos-sdk-javascript/blob/main/docs/embedded.options.md) to decode the token. | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,13 @@ | ||
<!-- Do not edit this file. It is automatically generated by API Documenter. --> | ||
|
||
[Home](./index.md) > [@cerbos/react](./react.md) > [CerbosProviderProps](./react.cerbosproviderprops.md) > [children](./react.cerbosproviderprops.children.md) | ||
|
||
## CerbosProviderProps.children property | ||
|
||
Your application's component tree. | ||
|
||
**Signature:** | ||
|
||
```typescript | ||
children: ReactNode; | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,13 @@ | ||
<!-- Do not edit this file. It is automatically generated by API Documenter. --> | ||
|
||
[Home](./index.md) > [@cerbos/react](./react.md) > [CerbosProviderProps](./react.cerbosproviderprops.md) > [client](./react.cerbosproviderprops.client.md) | ||
|
||
## CerbosProviderProps.client property | ||
|
||
The Cerbos client to provide. | ||
|
||
**Signature:** | ||
|
||
```typescript | ||
client: Client; | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,114 @@ | ||
<!-- Do not edit this file. It is automatically generated by API Documenter. --> | ||
|
||
[Home](./index.md) > [@cerbos/react](./react.md) > [CerbosProviderProps](./react.cerbosproviderprops.md) | ||
|
||
## CerbosProviderProps interface | ||
|
||
Props for the [CerbosProvider()](./react.cerbosprovider.md) component. | ||
|
||
**Signature:** | ||
|
||
```typescript | ||
export interface CerbosProviderProps | ||
``` | ||
|
||
## Properties | ||
|
||
<table><thead><tr><th> | ||
|
||
Property | ||
|
||
|
||
</th><th> | ||
|
||
Modifiers | ||
|
||
|
||
</th><th> | ||
|
||
Type | ||
|
||
|
||
</th><th> | ||
|
||
Description | ||
|
||
|
||
</th></tr></thead> | ||
<tbody><tr><td> | ||
|
||
[auxData?](./react.cerbosproviderprops.auxdata.md) | ||
|
||
|
||
</td><td> | ||
|
||
|
||
</td><td> | ||
|
||
Pick<[AuxData](./core.auxdata.md)<!-- -->, "jwt"> \| undefined | ||
|
||
|
||
</td><td> | ||
|
||
_(Optional)_ Auxiliary data related to the principal. | ||
|
||
|
||
</td></tr> | ||
<tr><td> | ||
|
||
[children](./react.cerbosproviderprops.children.md) | ||
|
||
|
||
</td><td> | ||
|
||
|
||
</td><td> | ||
|
||
ReactNode | ||
|
||
|
||
</td><td> | ||
|
||
Your application's component tree. | ||
|
||
|
||
</td></tr> | ||
<tr><td> | ||
|
||
[client](./react.cerbosproviderprops.client.md) | ||
|
||
|
||
</td><td> | ||
|
||
|
||
</td><td> | ||
|
||
[Client](./core.client.md) | ||
|
||
|
||
</td><td> | ||
|
||
The Cerbos client to provide. | ||
|
||
|
||
</td></tr> | ||
<tr><td> | ||
|
||
[principal](./react.cerbosproviderprops.principal.md) | ||
|
||
|
||
</td><td> | ||
|
||
|
||
</td><td> | ||
|
||
[Principal](./core.principal.md) | ||
|
||
|
||
</td><td> | ||
|
||
The principal to check. | ||
|
||
|
||
</td></tr> | ||
</tbody></table> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,18 @@ | ||
<!-- Do not edit this file. It is automatically generated by API Documenter. --> | ||
|
||
[Home](./index.md) > [@cerbos/react](./react.md) > [CerbosProviderProps](./react.cerbosproviderprops.md) > [principal](./react.cerbosproviderprops.principal.md) | ||
|
||
## CerbosProviderProps.principal property | ||
|
||
The principal to check. | ||
|
||
**Signature:** | ||
|
||
```typescript | ||
principal: Principal; | ||
``` | ||
|
||
## Remarks | ||
|
||
This is required, but can describe an anonymous user so that you can perform permission checks for unauthenticated users. | ||
|
Oops, something went wrong.