Skip to content

Commit 82c9ac5

Browse files
nikgrafnikgraf
authored
Docs update (#282)
1 parent 94d7e53 commit 82c9ac5

21 files changed

+974
-60
lines changed

‎README.md

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,6 @@ pnpm build
2929
hypergraph typesync
3030
```
3131

32-
3332
Any time you make changes to the schema, you will need to run the following commands:
3433

3534
```sh
@@ -46,6 +45,13 @@ cd apps/next-example
4645
pnpm dev
4746
```
4847

48+
To run the docs locally, you can run:
49+
50+
```sh
51+
cd docs
52+
pnpm start
53+
```
54+
4955

5056
## Upgrading Dependencies
5157

‎docs/docs/advanced/running-connect-and-sync-server-locally.md

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
## Running Connect and Sync Server Locally
2+
3+
To run the Connect and Sync Server locally, you need to get the Hypergraph repository:
4+
5+
```bash
6+
git clone https://github.com/graphprotocol/hypergraph.git
7+
cd hypergraph
8+
pnpm install
9+
```
10+
11+
```bash
12+
cd apps/connect
13+
pnpm dev
14+
# in another tab
15+
cd apps/server
16+
pnpm dev
17+
```
18+
19+
The Connect app is available at `http://localhost:5173` and the Sync Server is available at `http://localhost:3000`.

‎docs/docs/authentication.md

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
# Authentication
2+
3+
## Geo Connect
4+
5+
The default and recommended way to authenticate is via Geo Connect. Geo Connect is dedicated application hosted by the GeoBrowser team. Through Geo Connect you can authenticate with your GeoBrowser account and use it to selectively delegate access to your private and public spaces.
6+
7+
If you create you application using TypeSync or use the [hypergraph-app-template](https://github.com/graphprotocol/hypergraph-app-template) the full authentication flow is already implemented for you.
8+
9+
In the connect app you can create spaces. In the near future you will be able to delete private spaces and you also will be able to give an app permissions to create new private and/or public spaces.
10+
11+
## Hypergraph API
12+
13+
```tsx
14+
import { useHypergraphAuth } from "@graphprotocol/hypergraph-react";
15+
16+
function RouteComponent() {
17+
const { authenticated, identity } = useHypergraphAuth();
18+
}
19+
```
20+
21+
- `authenticated` - a boolean indicating if the user is authenticated
22+
- `identity` - the identity of the logged in user
23+
24+
## Authentication Flows with Geo Connect
25+
26+
### Signup coming from an App (without an existing Geo account)
27+
28+
1. User is opening App (Running App)
29+
2. Clicks on "Sign in/Sign up with Geo"
30+
- Redirect to Connect
31+
3. Sign up for Connect -> Email + One-time Code
32+
4. Connect: "Do you authorize this app (App ID, redirect URL)"
33+
- Select spaces
34+
- Click "Authorize" -> Redirect to App
35+
5. You are logged into the app with your account
36+
37+
### Signup coming from an App (with an existing Geo account)
38+
39+
1. User is opening App (Running App)
40+
2. Clicks on "Sign in/Sign up with Geo"
41+
- Redirect to Connect
42+
3. Login in the connect App -> Email + One-time Code
43+
4. Connect: "Do you authorize this app (App ID, redirect URL)"
44+
- Select spaces
45+
- Click "Authorize" -> Redirect to App
46+
5. You are logged into the app with your account
47+
48+
### Login coming from an App (user is logged out from app and connect)
49+
50+
1. User is opening App (Running App)
51+
2. Clicks on "Sign in/Sign up with Geo"
52+
- Redirect to Connect
53+
3. Login in the connect App -> Email + One-time Code
54+
4. Do you want to login with this app? (App ID, redirect URL)
55+
- Select spaces (optional)
56+
- Click "Authorize" -> Redirect to App
57+
5. You are logged into the app with your account
58+
59+
### Login coming from an App (user is logged out from app and logged in to connect)
60+
61+
1. User is opening App (Running App)
62+
2. Clicks on "Sign in/Sign up with Geo"
63+
- Redirect to Connect
64+
3. Do you want to login with this app? (App ID, redirect URL)
65+
- Select spaces (optional)
66+
- Click "Authorize" -> Redirect to App
67+
4. You are logged into the app with your account
68+
69+
## Geo Connect API
70+
71+
### `redirectToConnect`
72+
73+
```tsx
74+
import { useHypergraphApp } from "@graphprotocol/hypergraph-react";
75+
76+
function Login() {
77+
const { redirectToConnect } = useHypergraphApp();
78+
return (
79+
<button
80+
onClick={() => {
81+
redirectToConnect({
82+
storage: localStorage,
83+
connectUrl: "https://hypergraph-connect.vercel.app/",
84+
successUrl: `${window.location.origin}/authenticate-success`,
85+
// your app id (any valid uuid)
86+
appId: "93bb8907-085a-4a0e-83dd-62b0dc98e793",
87+
redirectFn: (url: URL) => {
88+
window.location.href = url.toString();
89+
},
90+
});
91+
}}
92+
>
93+
Authenticate with Connect
94+
</button>
95+
);
96+
}
97+
```
98+
99+
### `processConnectAuthSuccess`
100+
101+
```tsx
102+
import { useHypergraphApp } from "@graphprotocol/hypergraph-react";
103+
104+
function RouteComponent() {
105+
const { ciphertext, nonce } = Route.useSearch(); // get the ciphertext and nonce from the URL
106+
const { processConnectAuthSuccess } = useHypergraphApp();
107+
const navigate = useNavigate();
108+
109+
useEffect(() => {
110+
processConnectAuthSuccess({ storage: localStorage, ciphertext, nonce });
111+
console.log("redirecting to /");
112+
navigate({ to: "/", replace: true });
113+
}, [ciphertext, nonce, processConnectAuthSuccess, navigate]);
114+
115+
return <div>Authenticating …</div>;
116+
}
117+
```

‎docs/docs/faq.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -61,17 +61,17 @@ Find solutions in our Troubleshooting guide: [🛠 Troubleshooting](/docs/troubl
6161

6262
## Technical
6363

64-
### Which database do you use under the hood?
64+
<!-- ### Which database do you use under the hood?
6565
66-
None. Updates are stored as **CRDT events** on the sync server and optionally mirrored to IPFS for redundancy. Public data is published as JSON-LD on-chain.
66+
None. Updates are stored as **CRDT events** on the sync server and optionally mirrored to IPFS for redundancy. Public data is published as JSON-LD on-chain. -->
6767

6868
### Is Hypergraph open-source?
6969

7070
100 %. Apache-2.0 license. Contributions welcome!
7171

72-
### How big can a Space grow?
72+
<!-- ### How big can a Space grow?
7373
74-
We tested 50 k events / 10 MB snapshots on consumer laptops. Planned optimizations include **document sharding** and delta compression.
74+
We tested 50 k events / 10 MB snapshots on consumer laptops. Planned optimizations include **document sharding** and delta compression. -->
7575

7676
---
7777

‎docs/docs/filtering-query-results.md

Lines changed: 211 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,211 @@
1+
# Filtering Query Results
2+
3+
The filter API allows you to filter the results of a query by property values and in the future also by relations.
4+
5+
Note: Filtering is not yet supported for public data.
6+
7+
## Filtering by property values
8+
9+
```tsx
10+
export class Event extends Entity.Class<Event>("Event")({
11+
name: Type.Text,
12+
cancelled: Type.Checkbox,
13+
}) {}
14+
15+
// inside the React component
16+
const { data } = useQuery(Event, {
17+
filter: {
18+
cancelled: { is: false },
19+
},
20+
});
21+
```
22+
23+
The filter API supports different filters for different property types and offers a logical `or` and `not` operator.
24+
25+
```tsx
26+
// checkbox filter
27+
{
28+
is: true/false, // exact match
29+
exists: true/false, // filter by existence of the property
30+
}
31+
32+
// text filter
33+
{
34+
is: "text", // exact match
35+
contains: "text",
36+
startsWith: "text",
37+
endsWith: "text",
38+
exists: true/false, // filter by existence of the property
39+
}
40+
41+
// number filter
42+
{
43+
is: 42,
44+
lessThan: 42,
45+
lessThanOrEqual: 42,
46+
greaterThan: 42,
47+
greaterThanOrEqual: 42,
48+
exists: true/false, // filter by existence of the property
49+
}
50+
51+
// point filter
52+
{
53+
is: [0, 42],
54+
exists: true/false, // filter by existence of the property
55+
}
56+
57+
// logical `not` for a string
58+
{
59+
not: {
60+
is: "Jane Doe",
61+
},
62+
}
63+
64+
// logical `or` for a string
65+
{
66+
or: [
67+
{ name: "Jane Doe" },
68+
{ name: "John Doe" },
69+
],
70+
}
71+
```
72+
73+
## Combining logical filters
74+
75+
```tsx
76+
77+
{
78+
or: [
79+
not: { name: "Jane Doe" },
80+
not: { name: "John Doe" },
81+
],
82+
}
83+
```
84+
85+
## Full examples
86+
87+
```tsx
88+
// ever person except if their name is not Jane Doe or John Doe
89+
const { data } = useQuery(Person, {
90+
filter: {
91+
or: [
92+
not: { name: { is: "Jane Doe" } },
93+
not: { name: { is: "John Doe" } },
94+
],
95+
},
96+
});
97+
98+
// ever person that is 42, but their name is not Jane Doe or John Doe
99+
const { data } = useQuery(Person, {
100+
filter: {
101+
age: {
102+
equals: 42
103+
},
104+
or: [
105+
not: { name: { is: "Jane Doe" } },
106+
not: { name: { is: "John Doe" } },
107+
],
108+
not: {
109+
or: [
110+
{ name: { is: "Jane Doe" } },
111+
{ name: { is: "John Doe" } },
112+
],
113+
},
114+
},
115+
});
116+
117+
// every person that is not 42 years old
118+
const { data } = useQuery(Person, {
119+
filter: {
120+
age: {
121+
not: { is: 42 },
122+
},
123+
},
124+
});
125+
```
126+
127+
## Relation filtering
128+
129+
### Filter on values of the to entity
130+
131+
```tsx
132+
// schema
133+
export class Todo extends Entity.Class<Todo2>('Todo')({
134+
name: Type.Text,
135+
checked: Type.Checkbox,
136+
assignees: Type.Relation(User),
137+
})
138+
```
139+
140+
1 level filtering
141+
142+
```tsx
143+
const { data } = useQuery(Person, {
144+
filter: {
145+
assignees: {
146+
name: { is: "John" },
147+
},
148+
},
149+
});
150+
```
151+
152+
2 level filtering
153+
154+
```tsx
155+
const { data } = useQuery(Person, {
156+
filter: {
157+
assignees: {
158+
name: { is: "John" },
159+
friends: {
160+
age: { greaterThan: 60 },
161+
},
162+
},
163+
includes: {
164+
name: {},
165+
description: {},
166+
friends: {},
167+
},
168+
},
169+
});
170+
```
171+
172+
### Filter on the relation entity
173+
174+
```tsx
175+
// schema
176+
export class Todo extends Entity.Class<Todo2>('Todo')({
177+
name: Type.Text,
178+
checked: Type.Checkbox,
179+
assignees: Type.Relation(User, {
180+
entity: {
181+
assignedAt: Type.DateTime,
182+
}
183+
}),
184+
})
185+
```
186+
187+
```tsx
188+
const { data } = useQuery(Person, {
189+
filter: {
190+
assignees: {
191+
_relation: {
192+
entity: { assignedAt: { greaterThan: new Date("2025-01-01") } },
193+
},
194+
name: { is: "John" },
195+
},
196+
},
197+
});
198+
```
199+
200+
Note: To access the relation entity you need to use the `_relation` property.
201+
202+
```tsx
203+
{
204+
todo.assignees.map((assignee) => (
205+
<span key={assignee._relation.id}>
206+
{assignee._relation.entity.assignedAt}
207+
{assignee.name}
208+
</span>
209+
));
210+
}
211+
```

0 commit comments

Comments
 (0)