Geolocation unstable

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 Since v4.0.0 Source

Accessors

watchPosition

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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 unstable

Since v4.0.0

Union of browser geolocation error reasons represented by the service.

Signature

type GeolocationErrorReason = PositionUnavailable | PermissionDenied | Timeout

PermissionDenied

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

Signature

declare const layer: Layer.Layer<Geolocation>

Services

Geolocation

unstable

Since v4.0.0

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 unstable

Since v4.0.0

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>;
}