Skip to content

Commit 7152dd3

Browse files
committed
add ./convex.config.js entrypoint
1 parent 3f92ab3 commit 7152dd3

File tree

2 files changed

+60
-35
lines changed

2 files changed

+60
-35
lines changed

README.md

Lines changed: 56 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -6,25 +6,31 @@
66

77
<!-- START: Include on https://convex.dev/components -->
88

9-
This component adds a geospatial index to Convex, allowing you to efficiently store and query points on the Earth's surface.
9+
This component adds a geospatial index to Convex, allowing you to efficiently
10+
store and query points on the Earth's surface.
1011

11-
- Insert points into the geospatial key value store along with their geographic coordinates.
12+
- Insert points into the geospatial key value store along with their geographic
13+
coordinates.
1214
- Efficiently query for all points within a given rectangle on the sphere.
1315
- Control the sort order for the results with a custom sorting key.
1416
- Filter query results with equality and `IN` clauses.
15-
- And since it's built on Convex, everything is automatically consistent, reactive, and cached!
17+
- And since it's built on Convex, everything is automatically consistent,
18+
reactive, and cached!
1619

17-
This component is currently in beta. It's missing some functionality, but what's there should work. We've tested the example
18-
app up to about 1,000,000 points, so reach out if you're using a much larger dataset.
19-
If you find a bug or have a feature request, you can [file it here](https://github.com/get-convex/geospatial/issues).
20+
This component is currently in beta. It's missing some functionality, but what's
21+
there should work. We've tested the example app up to about 1,000,000 points, so
22+
reach out if you're using a much larger dataset. If you find a bug or have a
23+
feature request, you can
24+
[file it here](https://github.com/get-convex/geospatial/issues).
2025

2126
## Pre-requisite: Convex
2227

23-
You'll need an existing Convex project to use the component.
24-
Convex is a hosted backend platform, including a database, serverless functions,
25-
and a ton more you can learn about [here](https://docs.convex.dev/get-started).
28+
You'll need an existing Convex project to use the component. Convex is a hosted
29+
backend platform, including a database, serverless functions, and a ton more you
30+
can learn about [here](https://docs.convex.dev/get-started).
2631

27-
Run `npm create convex` or follow any of the [quickstarts](https://docs.convex.dev/home) to set one up.
32+
Run `npm create convex` or follow any of the
33+
[quickstarts](https://docs.convex.dev/home) to set one up.
2834

2935
## Installation
3036

@@ -34,11 +40,12 @@ First, add `@convex-dev/geospatial` to your Convex project:
3440
npm install @convex-dev/geospatial
3541
```
3642

37-
Then, install the component into your Convex project within the `convex/convex.config.ts` file:
43+
Then, install the component into your Convex project within the
44+
`convex/convex.config.ts` file:
3845

3946
```ts
4047
// convex/convex.config.ts
41-
import geospatial from "@convex-dev/geospatial/convex.config";
48+
import geospatial from "@convex-dev/geospatial/convex.config.js";
4249
import { defineApp } from "convex/server";
4350

4451
const app = defineApp();
@@ -47,7 +54,8 @@ app.use(geospatial);
4754
export default app;
4855
```
4956

50-
Finally, create a new `GeospatialIndex` within your `convex/` folder, and point it to the installed component:
57+
Finally, create a new `GeospatialIndex` within your `convex/` folder, and point
58+
it to the installed component:
5159

5260
```ts
5361
// convex/index.ts
@@ -59,9 +67,10 @@ const geospatial = new GeospatialIndex(components.geospatial);
5967

6068
## Inserting points
6169

62-
After installing the component, you can `insert`, `get`, and `remove` points from the index. You can specify
63-
a `filterKeys` record for filtering at query time and optionally a `sortKey` for the query result order. We
64-
currently only support ascending order on the `sortKey`.
70+
After installing the component, you can `insert`, `get`, and `remove` points
71+
from the index. You can specify a `filterKeys` record for filtering at query
72+
time and optionally a `sortKey` for the query result order. We currently only
73+
support ascending order on the `sortKey`.
6574

6675
```ts
6776
// convex/index.ts
@@ -85,9 +94,11 @@ const example = mutation({
8594
});
8695
```
8796

88-
If you would like some more typesafety, you can specify a type argument for the `GeospatialIndex` class. This
89-
will also provide you with auto-complete for the `filterKeys` and `sortKey` parameters.
90-
Above the key was "American Museum of Natural History" but most commonly the `key` will be an ID in another table of yours.
97+
If you would like some more typesafety, you can specify a type argument for the
98+
`GeospatialIndex` class. This will also provide you with auto-complete for the
99+
`filterKeys` and `sortKey` parameters. Above the key was "American Museum of
100+
Natural History" but most commonly the `key` will be an ID in another table of
101+
yours.
91102

92103
```ts
93104
// convex/index.ts
@@ -125,13 +136,13 @@ const example = query({
125136
});
126137
```
127138

128-
This query will find all points that lie within the query rectangle, sort them in ascending
129-
`sortKey` order, and return at most 16 results.
139+
This query will find all points that lie within the query rectangle, sort them
140+
in ascending `sortKey` order, and return at most 16 results.
130141

131142
You can optionally add filter conditions to queries.
132143

133-
The first type of filter condition is an `in()` filter, which requires that a matching
134-
document have a filter field with a value in a specified set.
144+
The first type of filter condition is an `in()` filter, which requires that a
145+
matching document have a filter field with a value in a specified set.
135146

136147
```ts
137148
// convex/index.ts
@@ -153,8 +164,8 @@ const example = query({
153164
});
154165
```
155166

156-
The second type of filter condition is an `eq()` filter, which requires that a matching
157-
document have a filter field with a value equal to a specified value.
167+
The second type of filter condition is an `eq()` filter, which requires that a
168+
matching document have a filter field with a value equal to a specified value.
158169

159170
```ts
160171
// convex/index.ts
@@ -170,7 +181,9 @@ const example = query({
170181
});
171182
```
172183

173-
The final type of filter condition allows you to specify ranges over the `sortKey`. We currently only support (optional) inclusive lower bounds and exclusive upper bounds.
184+
The final type of filter condition allows you to specify ranges over the
185+
`sortKey`. We currently only support (optional) inclusive lower bounds and
186+
exclusive upper bounds.
174187

175188
```ts
176189
// convex/index.ts
@@ -192,10 +205,13 @@ const example = query({
192205
});
193206
```
194207

195-
Queries take in a `limit`, which bounds the maximum number of rows returned. If this limit is hit,
196-
the query will return a `nextCursor` for continuation. The query may also return a `nextCursor` with fewer than `limit` results if it runs out of its IO budget while executing.
208+
Queries take in a `limit`, which bounds the maximum number of rows returned. If
209+
this limit is hit, the query will return a `nextCursor` for continuation. The
210+
query may also return a `nextCursor` with fewer than `limit` results if it runs
211+
out of its IO budget while executing.
197212

198-
In either case, you can continue the stream by passing `nextCursor` to the next call's `cursor` parameter.
213+
In either case, you can continue the stream by passing `nextCursor` to the next
214+
call's `cursor` parameter.
199215

200216
```ts
201217
// convex/index.ts
@@ -234,11 +250,13 @@ const example = query({
234250
});
235251
```
236252

237-
**Note: you typically pass the `nextCursor` in from a client that is paginating through results, to avoid loading too much data in a single query.**
253+
**Note: you typically pass the `nextCursor` in from a client that is paginating
254+
through results, to avoid loading too much data in a single query.**
238255

239256
## Querying the points nearest a query point
240257

241-
You can also query for the points closest to a given point, optionally limiting to a maximum distance (in meters).
258+
You can also query for the points closest to a given point, optionally limiting
259+
to a maximum distance (in meters).
242260

243261
```ts
244262
// convex/index.ts
@@ -258,11 +276,13 @@ const example = query({
258276
});
259277
```
260278

261-
The `maxDistance` parameter is optional, but providing it can greatly speed up searching the index.
279+
The `maxDistance` parameter is optional, but providing it can greatly speed up
280+
searching the index.
262281

263282
## Example
264283

265-
See [`example/`](./example/) for a full example with a [Leaflet](https://leafletjs.com/)-based frontend.
284+
See [`example/`](./example/) for a full example with a
285+
[Leaflet](https://leafletjs.com/)-based frontend.
266286

267287
## Development
268288

@@ -275,7 +295,8 @@ npm install
275295
npm run dev
276296
```
277297

278-
The component definition is in `src/` and reflects what users of the component will install. The example app,
279-
which is entirely independent, lives in `example/`.
298+
The component definition is in `src/` and reflects what users of the component
299+
will install. The example app, which is entirely independent, lives in
300+
`example/`.
280301

281302
<!-- END: Include on https://convex.dev/components -->

package.json

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,10 @@
5858
"./convex.config": {
5959
"types": "./dist/component/convex.config.d.ts",
6060
"default": "./dist/component/convex.config.js"
61+
},
62+
"./convex.config.js": {
63+
"types": "./dist/component/convex.config.d.ts",
64+
"default": "./dist/component/convex.config.js"
6165
}
6266
},
6367
"dependencies": {

0 commit comments

Comments
 (0)