remotestorage-module-places/README.md

@remotestorage/module-places

This module allows you to manage saved places (Points of Interest) using the remoteStorage protocol.

It leverages Geohashes 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.

Installation

# 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

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:

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

// Create a list
await places.lists.create('hiking', 'Hiking', '#74d3ba');

// Delete a list
await places.lists.delete('hiking');

List membership

// 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

// Get all lists
await places.lists.getAll();

// Get specific list
await places.lists.get('to-do');

API Reference

Interfaces

• PlacesClient

Type Aliases

• Place
• List