116 lines
2.8 KiB
Markdown
116 lines
2.8 KiB
Markdown
# @remotestorage/module-places
|
|
|
|
[](https://www.npmjs.com/package/@remotestorage/module-places) [](https://gitea.kosmos.org/raucao/remotestorage-module-places/actions)
|
|
|
|
This module allows you to manage saved places (Points of Interest) using the [remoteStorage](https://remotestorage.io/) protocol.
|
|
|
|
It leverages [Geohashes](https://www.geohash.es/) to organize data, enabling efficient retrieval of places within specific geographic areas. This structure is particularly optimized for map applications that need to load data only for the visible viewport.
|
|
|
|
For a demo application, as well as source code using this module, check out [Marco](https://marco.kosmos.org).
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
# npm
|
|
npm install @remotestorage/module-places
|
|
|
|
# pnpm
|
|
pnpm add @remotestorage/module-places
|
|
|
|
# yarn
|
|
yarn add @remotestorage/module-places
|
|
|
|
# bun
|
|
bun add @remotestorage/module-places
|
|
```
|
|
|
|
## Usage
|
|
|
|
```javascript
|
|
import RemoteStorage from 'remotestoragejs';
|
|
import PlacesModule from '@remotestorage/module-places';
|
|
|
|
const remoteStorage = new RemoteStorage({
|
|
modules: [PlacesModule],
|
|
});
|
|
|
|
// Access the module
|
|
const places = remoteStorage.places;
|
|
|
|
// Store a place
|
|
await places.store({
|
|
title: 'My Favorite Coffee Shop',
|
|
lat: 52.520008,
|
|
lon: 13.404954,
|
|
});
|
|
|
|
// List all places
|
|
const allPlaces = await places.getPlaces();
|
|
console.log(allPlaces);
|
|
|
|
// List places for specific geohash prefixes (e.g. for a map view)
|
|
const areaPlaces = await places.getPlaces(['u33d', 'u33e']);
|
|
console.log(areaPlaces);
|
|
```
|
|
|
|
## Lists
|
|
|
|
### Default lists
|
|
|
|
There are currently two default lists, which you can initiate like this:
|
|
|
|
```javascript
|
|
await places.lists.initDefaults();
|
|
```
|
|
|
|
This will create the lists if they don't exist yet (meaning the user hasn't yet
|
|
used an app that integrates this module).
|
|
|
|
The default lists are:
|
|
|
|
| Path | Default Name | Default Color |
|
|
| --- | --- | --- |
|
|
| `_lists/to-go` | Want to go | #2e9e4f (green) |
|
|
| `_lists/to-do` | To do | #2a7fff (blue) |
|
|
|
|
### Custom lists
|
|
|
|
```javascript
|
|
// Create a list
|
|
await places.lists.create('hiking', 'Hiking', '#74d3ba');
|
|
|
|
// Delete a list
|
|
await places.lists.delete('hiking');
|
|
```
|
|
|
|
### List membership
|
|
|
|
```javascript
|
|
// Add a place to a list (requires list ID, place ID, and place geohash)
|
|
await places.lists.addPlace('to-go', 'place-id-123', 'u33dc0');
|
|
|
|
// Remove from list
|
|
await places.lists.removePlace('to-go', 'place-id-123');
|
|
```
|
|
|
|
### Reading lists
|
|
|
|
```javascript
|
|
// Get all lists
|
|
await places.lists.getAll();
|
|
|
|
// Get specific list
|
|
await places.lists.get('to-do');
|
|
```
|
|
|
|
## API Reference
|
|
|
|
### Interfaces
|
|
|
|
- [PlacesClient](docs/interfaces/PlacesClient.md)
|
|
|
|
### Type Aliases
|
|
|
|
- [Place](docs/type-aliases/Place.md)
|
|
- [List](docs/type-aliases/List.md)
|