Skip to content

Geolocation

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.

9 exports Added in v4.0.0 Source

Accessors

watchPosition

Added in v4.0.0 Source

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

Signature

declare function watchPosition(
  options?: PositionOptions & {
    readonly bufferSize?: number;
  },
): Stream<GeolocationPosition, GeolocationError, Geolocation>;

Errors

GeolocationError

Added in v4.0.0 Source

Tagged error wrapping a browser geolocation failure reason.

Signature

declare class GeolocationError extends YieldableError<this> & {
  readonly _tag: "GeolocationError";
} & Readonly<{
  readonly reason: GeolocationErrorReason;
}> {
  constructor(props: {
    readonly reason: GeolocationErrorReason;
  });
  readonly "~@effect/platform-browser/Geolocation/GeolocationError": "~@effect/platform-browser/Geolocation/GeolocationError";
  message: string;
}

GeolocationErrorReason type

Added in v4.0.0 Source

Union of browser geolocation error reasons represented by the service.

Signature

type GeolocationErrorReason = PositionUnavailable | PermissionDenied | Timeout;

PermissionDenied

Added in v4.0.0 Source

Error reason for the browser geolocation PERMISSION_DENIED failure.

Signature

declare class PermissionDenied extends YieldableError<this> & {
  readonly _tag: "PermissionDenied";
} & Readonly<{
  readonly cause: unknown;
}> {
  constructor(args: {
    readonly cause: unknown;
  });
  message: string;
}

PositionUnavailable

Added in v4.0.0 Source

Error reason for the browser geolocation POSITION_UNAVAILABLE failure.

Signature

declare class PositionUnavailable extends YieldableError<this> & {
  readonly _tag: "PositionUnavailable";
} & Readonly<{
  readonly cause: unknown;
}> {
  constructor(args: {
    readonly cause: unknown;
  });
  message: string;
}

Timeout

Added in v4.0.0 Source

Error reason for the browser geolocation TIMEOUT failure.

Signature

declare class Timeout extends YieldableError<this> & {
  readonly _tag: "Timeout";
} & Readonly<{
  readonly cause: unknown;
}> {
  constructor(args: {
    readonly cause: unknown;
  });
  message: string;
}

Layers

layer

Added in v4.0.0 Source

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

Signature

declare const layer: Layer.Layer<Geolocation>;

Services

Geolocation

Added in v4.0.0 Source

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: Service<Geolocation, Geolocation>;

Geolocation interface

Added in v4.0.0 Source

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

interface Geolocation {
  readonly "~@effect/platform-browser/Geolocation": "~@effect/platform-browser/Geolocation";
  readonly getCurrentPosition: (
    options?: PositionOptions,
  ) => Effect<GeolocationPosition, GeolocationError>;
  readonly watchPosition: (
    options?: PositionOptions & {
      readonly bufferSize?: number;
    },
  ) => Stream<GeolocationPosition, GeolocationError>;
}