Self-hosted personal gallery application with online photo management and albums, supporting Live/Motion Photos, EXIF parsing, geolocation recognition, and an explore map.
TypeScript albumsexif-extractiongeocodinglive-photomotion-photophoto-galleryphoto-sharingwebgl-viewer
import type { NormalizedLocation } from '@chronoframe/contracts/location'
import { hasValidCoordinates } from './coordinates.ts'
import { normalizeMapbox, normalizeNominatim } from './normalize.ts'
export interface LocationInfo {
latitude: number
longitude: number
country?: string
city?: string
geocoding: NormalizedLocation
locationName?: string
}
export interface GeocodingProvider {
reverseGeocode(lat: number, lon: number): Promise<LocationInfo | null>
}
export interface GeocodingLogger {
success(...args: any[]): void
info(...args: any[]): void
warn(...args: any[]): void
error(...args: any[]): void
}
export interface RetryOptions {
maxAttempts?: number
baseDelay?: number
maxDelay?: number
timeout?: number
retryCondition?: (error: Error) => boolean
delayStrategy?: 'exponential' | 'linear' | 'fixed'
}
export interface GeocodingDependencies {
/** Processing queues can distinguish provider failures from successful empty results. */
throwOnError?: boolean
getLanguage(): Promise<string>
request: typeof fetch
waitForGeocodingSlot(
key: string,
intervalMs: number,
signal?: AbortSignal,
): Promise<void>
withRetry<T>(
operation: (signal: AbortSignal) => Promise<T>,
options?: RetryOptions,
logger?: GeocodingLogger,
): Promise<T>
retryOptions: RetryOptions
logger: GeocodingLogger
}
/** Create reverse-geocoding providers using caller-owned transport, retry, language and rate limits. */
export function createGeocodingServices({
getLanguage,
throwOnError = false,
request,
waitForGeocodingSlot,
withRetry,
retryOptions,
logger,
}: GeocodingDependencies) {
/**
* Mapbox 地理编码提供者
* 高精度商业地理编码服务,支持全球范围和多语言
*/
class MapboxGeocodingProvider implements GeocodingProvider {
private accessToken: string
private readonly baseUrl = 'https://api.mapbox.com'
private readonly rateLimitMs = 100 // Mapbox 默认速率限制为 1000/分钟,约60ms间隔
constructor(accessToken: string) {
this.accessToken = accessToken
}
async reverseGeocode(
lat: number,
lon: number,
): Promise<LocationInfo | null> {
try {
return await withRetry(
async (signal) => {
// 应用速率限制
await waitForGeocodingSlot(this.baseUrl, this.rateLimitMs, signal)
// 获取设置的地理编码语言,默认 'en'
const language = (await getLanguage()) || 'en'
const url = new URL('/search/geocode/v6/reverse', this.baseUrl)
url.searchParams.set('access_token', this.accessToken)
url.searchParams.set('longitude', lon.toString())
url.searchParams.set('latitude', lat.toString())
url.searchParams.set(
'types',
'address,place,locality,neighborhood,district,region,country',
)
// 映射 Mapbox 首选语言格式
let mapboxLang = language
if (language === 'zh-CN') {
mapboxLang = 'zh-Hans'
} else if (language === 'zh-TW') {
mapboxLang = 'zh-Hant'
}
url.searchParams.set('language', mapboxLang)
logger.info('Requesting Mapbox reverse geocoding')
const response = await request(url.toString(), { signal })
if (!response.ok) {
throw new Error(
`Mapbox API error: ${response.status} ${response.statusText}`,
)
}
const data = await response.json()
if (!data || !data.features || data.features.length === 0) {
logger.warn('Mapbox API returned no features')
return null
}
const geocoding = normalizeMapbox(data, language)
if (!geocoding) return null
return {
latitude: lat,
longitude: lon,
geocoding,
country: geocoding.components.country?.name,
city: geocoding.components.city?.name,
locationName: geocoding.formattedAddress,
}
},
{
...retryOptions,
timeout: 10000,
delayStrategy: 'exponential',
},
logger,
)
} catch (error) {
logger.error(
'Mapbox reverse geocoding failed after all retries:',
error,
)
if (throwOnError) throw error
return null
}
}
}
/**
* OpenStreetMap Nominatim API 地理编码提供者
* 免费的地理编码服务,适合开发和小规模使用
*/
class NominatimGeocodingProvider implements GeocodingProvider {
private readonly baseUrl: string
private readonly userAgent = 'chronoframe/1.0'
private readonly rateLimitMs = 1000 // Nominatim 要求至少1秒间隔
constructor(baseUrl?: string) {
this.baseUrl = baseUrl || 'https://nominatim.openstreetmap.org'
}
async reverseGeocode(
lat: number,
lon: number,
): Promise<LocationInfo | null> {
try {
return await withRetry(
async (signal) => {
// 应用速率限制
await waitForGeocodingSlot(this.baseUrl, this.rateLimitMs, signal)
// 获取设置的地理编码语言,默认 'en'
const language = (await getLanguage()) || 'en'
const url = new URL('/reverse', this.baseUrl)
url.searchParams.set('lat', lat.toString())
url.searchParams.set('lon', lon.toString())
url.searchParams.set('format', 'json')
url.searchParams.set('addressdetails', '1')
url.searchParams.set('accept-language', `${language},en`)
const response = await request(url.toString(), {
signal,
headers: {
'User-Agent': this.userAgent,
},
})
if (response.status === 404) {
const empty = await response.json().catch(() => null)
if (empty?.error === 'Unable to geocode') return null
}
if (!response.ok) {
throw new Error(
`Nominatim API error: ${response.status} ${response.statusText}`,
)
}
const data = await response.json()
if (!data || data.error === 'Unable to geocode') return null
if (data.error)
throw new Error(`Nominatim API returned error: ${data.error}`)
const geocoding = normalizeNominatim(data, language)
if (!geocoding) return null
return {
latitude: lat,
longitude: lon,
geocoding,
country: geocoding.components.country?.name,
city: geocoding.components.city?.name,
locationName: geocoding.formattedAddress,
}
},
{
...retryOptions,
timeout: 15000, // Nominatim 可能比较慢
delayStrategy: 'linear', // 线性退避,避免过快重试
},
logger,
)
} catch (error) {
logger.error(
'Nominatim reverse geocoding failed after all retries:',
error,
)
if (throwOnError) throw error
return null
}
}
}
/** Parse bounded decimal GPS text or explicit EXIF coordinates, applying hemisphere references. */
function parseGPSCoordinates(exifData: any): {
latitude?: number
longitude?: number
} {
try {
let latitude: number | undefined
let longitude: number | undefined
// 尝试从GPSLatitude和GPSLongitude获取
if (exifData.GPSLatitude != null && exifData.GPSLongitude != null) {
latitude = parseFloat(exifData.GPSLatitude.toString())
longitude = parseFloat(exifData.GPSLongitude.toString())
}
// 如果上面的方法失败,尝试从GPSCoordinates获取
if (
!hasValidCoordinates(latitude, longitude) &&
exifData.GPSCoordinates
) {
const coords = exifData.GPSCoordinates.toString()
// Bound metadata input and validate whole tokens without overlapping
// numeric quantifiers that can cause polynomial regex backtracking.
if (coords.length <= 256) {
const tokens = coords
.trim()
.split(/[°,\s]+/)
.filter(Boolean)
const [lat, lon] = tokens
const decimal = /^[-+]?\d+(?:\.\d*)?$/
if (
tokens.length === 2 &&
lat &&
lon &&
decimal.test(lat) &&
decimal.test(lon)
) {
latitude = Number(lat)
longitude = Number(lon)
}
}
}
// 应用GPS参考(南纬为负,西经为负)
if (latitude && exifData.GPSLatitudeRef === 'S') {
latitude = -Math.abs(latitude)
}
if (longitude && exifData.GPSLongitudeRef === 'W') {
longitude = -Math.abs(longitude)
}
if (!hasValidCoordinates(latitude, longitude)) return {}
return { latitude, longitude }
} catch (error) {
logger.error('Failed to parse GPS coordinates:', error)
return {}
}
}
return {
MapboxGeocodingProvider,
NominatimGeocodingProvider,
parseGPSCoordinates,
}
}
export * from './normalize.ts'
export * from './coordinates.ts'
export * from './rate-limit.ts'