GeoEngine SDK (@abdelamrah/geo-sdk)

SDK TypeScript sans interface graphique pour la géolocalisation : géocodage, géocodage inverse, itinéraires et suggestions d’adresses. Les données sont structurées en JSON ; aucune carte ni dépendance Leaflet / Mapbox / Google Maps.

• Injection de dépendances : géocodeur, routeur et recherche sont des ports que vous implémentez ou fournissez via les adaptateurs de référence (Nominatim, OSRM).
• Cache optionnel : mémoire, no-op ou Redis (ioredis en peer dependency optionnelle).
• Rate limiting HTTP partagé : RateLimitedFetchGate pour sérialiser les appels et respecter une cadence (ex. 1 req/s).

Node.js ≥ 18 (fetch natif).

Installation

npm install @abdelamrah/geo-sdk

Pour le cache Redis ou la création automatique du client depuis une URL :

npm install ioredis

Usage rapide (composition manuelle)

import { GeoEngine } from "@abdelamrah/geo-sdk";
import {
  NominatimGeocoderProvider,
  NominatimAddressSearchProvider,
  OsrmRouterProvider,
  RateLimitedFetchGate,
} from "@abdelamrah/geo-sdk/providers";

const gate = new RateLimitedFetchGate({ minIntervalMs: 1000 });
const fetchLimited = gate.wrap(globalThis.fetch);

const geo = new GeoEngine({
  geocoder: new NominatimGeocoderProvider({
    baseUrl: "https://nominatim.openstreetmap.org",
    fetch: fetchLimited,
    headers: { "User-Agent": "MonApp/1.0 ([email protected])" },
  }),
  router: new OsrmRouterProvider({
    baseUrl: "https://router.project-osrm.org",
    fetch: fetchLimited,
  }),
  addressSearch: new NominatimAddressSearchProvider({
    baseUrl: "https://nominatim.openstreetmap.org",
    fetch: fetchLimited,
    headers: { "User-Agent": "MonApp/1.0 ([email protected])" },
  }),
});

await geo.geocode("Oran Centre");
await geo.reverseGeocode({ lat: 35.697, lng: -0.6337 });
await geo.route({ lng: x1, lat: y1 }, { lng: x2, lat: y2 });
await geo.searchAddresses("Or");

Sans addressSearch, searchAddresses() lève une erreur explicite (ConfigurationError). Utilisez geo.hasAddressSearch() pour tester la présence du port.

Variables d’environnement

Lecture complète depuis process.env ou Nest ConfigService

import { createGeoEngineFromEnv } from "@abdelamrah/geo-sdk";

const { geo, disconnectRedis, config } = await createGeoEngineFromEnv({
  configGet: (key) => configService.get<string>(key),
});

await disconnectRedis?.(); // si Redis a été créé par la factory

Surcharges camelCase (redisUri, URLs…) sans préfixe GEO_ENGINE_*

Pour mapper vos propres clés (REDIS_URI, etc.) :

import { createGeoEngineFromInlineConfig } from "@abdelamrah/geo-sdk";

const { geo, disconnectRedis } = await createGeoEngineFromInlineConfig({
  redisUri: configService.get<string>("REDIS_URI"),
  nominatimUrl: configService.get<string>("NOMINATIM_URL"),
  osrmUrl: configService.get<string>("OSRM_URL"),
  userAgent: configService.get<string>("APP_USER_AGENT"),
});

Combinaison env + inline (Nest)

Les champs présents dans inline remplacent la configuration déjà résolue depuis l’environnement :

await createGeoEngineFromEnv({
  configGet: (key) => configService.get<string>(key),
  inline: {
    redisUri: configService.get<string>("REDIS_URI"),
  },
});

Principales variables supportées (GEO_ENGINE_*)

| Variable | Rôle | |----------|------| | GEO_ENGINE_NOMINATIM_URL | URL Nominatim (défaut instance publique) | | GEO_ENGINE_OSRM_URL | URL OSRM (défaut démo publique) | | GEO_ENGINE_OSRM_PROFILE | Profil routeur (ex. driving) | | GEO_ENGINE_USER_AGENT | Fortement recommandé pour Nominatim | | GEO_ENGINE_NOMINATIM_EMAIL | Politique / contact Nominatim | | GEO_ENGINE_ENABLE_ADDRESS_SEARCH | true / false (défaut true) | | GEO_ENGINE_REDIS_URL ou REDIS_URL | Cache Redis | | GEO_ENGINE_REDIS_KEY_PREFIX | Préfixe des clés | | GEO_ENGINE_RATE_LIMIT_MS | Intervalle minimal entre débuts de requêtes HTTP partagées (défaut 1000, 0 = désactivé) | | GEO_ENGINE_TTL_*_SECONDS | TTL cache (GEOCODE, REVERSE, ROUTE, SEARCH) |

Utilitaires : parseGeoEngineEnv, mergeGeoEngineEnvFromGetter, GEO_ENGINE_ENV_KEYS, resolveGeoEngineInlineConfig, applyGeoEngineInlineOverrides.

Imports

• Point d’entrée principal : @abdelamrah/geo-sdk
• Providers HTTP de référence : @abdelamrah/geo-sdk/providers

Adaptateurs cache

• NoOpCacheAdapter — pas de cache
• MemoryCacheAdapter — process unique / tests
• RedisCacheAdapter — injectez un client compatible RedisLikeClient

Les services utilisent une stratégie read-through sur les clés versionnées (geo:v1:…, hash SHA-256 des entrées normalisées).

Scripts (développement du package)

npm run build
npm test

Publier sur npm

1. Compte et scope
   Le package est nommé @abdelamrah/geo-sdk (scope = ton compte npm @abdelamrah). Tu dois être connecté avec ce compte pour publier.

2. Connexion

   npm login
   npm whoami

3. Vérifier le contenu du paquet

   npm run build
   npm pack --dry-run

4. Publication
   publishConfig.access est déjà réglé sur public pour un package scoped.

   npm publish

   Les versions suivantes : incrémente version dans package.json (ou npm version patch|minor|major) puis npm publish.

5. OTP (2FA)
   Si l’auth à deux facteurs est activée : npm publish --otp=CODE.

Licence

MIT — voir le fichier LICENSE.