Geolocation.ts

Geolocation.ts overview

Browser geolocation integration for Effect programs.

This module defines a Geolocation service backed by navigator.geolocation. The service can read one current position or stream watched position updates with a sliding buffer. Browser callback failures are represented as GeolocationError values with PositionUnavailable, PermissionDenied, or Timeout reasons. The module also provides the browser-backed layer and a watchPosition accessor.

Since v4.0.0

---

Exports Grouped by Category

• accessors
  • watchPosition
• errors
  • GeolocationError (class)
    • [ErrorTypeId] (property)
  • GeolocationErrorReason (type alias)
  • PermissionDenied (class)
  • PositionUnavailable (class)
  • Timeout (class)
• layers
  • layer
• models
  • Geolocation (interface)
• services
  • Geolocation

---

accessors

watchPosition

Reads geolocation positions from the Geolocation service as a stream, with an optional sliding buffer size.

Signature

declare const watchPosition: (
  options?: (PositionOptions & { readonly bufferSize?: number | undefined }) | undefined
) => Stream.Stream<GeolocationPosition, GeolocationError, Geolocation>

Source

Since v4.0.0

errors

GeolocationError (class)

Tagged error wrapping a browser geolocation failure reason.

Signature

declare class GeolocationError {
  constructor(props: { readonly reason: GeolocationErrorReason })
}

Source

Since v4.0.0

[ErrorTypeId] (property)

Signature

readonly [ErrorTypeId]: "~@effect/platform-browser/Geolocation/GeolocationError"

Source

GeolocationErrorReason (type alias)

Union of browser geolocation error reasons represented by the service.

Signature

type GeolocationErrorReason = PositionUnavailable | PermissionDenied | Timeout

Source

Since v4.0.0

PermissionDenied (class)

Error reason for the browser geolocation PERMISSION_DENIED failure.

Signature

declare class PermissionDenied

Source

Since v4.0.0

PositionUnavailable (class)

Error reason for the browser geolocation POSITION_UNAVAILABLE failure.

Signature

declare class PositionUnavailable

Source

Since v4.0.0

Timeout (class)

Error reason for the browser geolocation TIMEOUT failure.

Signature

declare class Timeout

Source

Since v4.0.0

layers

layer

Layer that provides Geolocation using navigator.geolocation, with watched positions buffered in a sliding queue.

Signature

declare const layer: Layer.Layer<Geolocation, never, never>

Source

Since v4.0.0

models

Geolocation (interface)

Defines the service interface for browser geolocation, providing effects for the current position and streams of watched positions.

When to use

Use when browser code needs a typed Effect service for one-shot location reads or streamed location updates.

Details

getCurrentPosition returns one position effect. watchPosition returns a stream and accepts the browser PositionOptions plus an optional sliding bufferSize.

Gotchas

Browser permission prompts, denied permissions, timeouts, unavailable position data, secure-context restrictions, and policy restrictions are surfaced as GeolocationError.

See

• GeolocationError for represented browser geolocation failures
• layer for the browser-backed service implementation

Signature

export interface Geolocation {
  readonly [TypeId]: typeof TypeId
  readonly getCurrentPosition: (
    options?: PositionOptions | undefined
  ) => Effect.Effect<GeolocationPosition, GeolocationError>
  readonly watchPosition: (
    options?:
      | (PositionOptions & {
          readonly bufferSize?: number | undefined
        })
      | undefined
  ) => Stream.Stream<GeolocationPosition, GeolocationError>
}

Source

Since v4.0.0

services

Geolocation

Service tag for browser geolocation capabilities.

When to use

Use when you need to access or provide geolocation capabilities through Effect’s context.

See

• layer for providing the browser-backed geolocation service

Signature

declare const Geolocation: Context.Service<Geolocation, Geolocation>

Source

Since v4.0.0