The best way to control Claude Code, Codex and more from any computer or phone

main
ts 243 lines 6.66 KB
Raw
1 /**
2 * Browser geolocation integration for Effect programs.
3 *
4 * This module defines a `Geolocation` service backed by
5 * `navigator.geolocation`. The service can read one current position or stream
6 * watched position updates with a sliding buffer. Browser callback failures are
7 * represented as `GeolocationError` values with `PositionUnavailable`,
8 * `PermissionDenied`, or `Timeout` reasons. The module also provides the
9 * browser-backed layer and a `watchPosition` accessor.
10 *
11 * @stability unstable
12 * @since 4.0.0
13 */
14 import * as Cause from "effect/Cause"
15 import * as Context from "effect/Context"
16 import * as Data from "effect/Data"
17 import * as Effect from "effect/Effect"
18 import * as Layer from "effect/Layer"
19 import * as Queue from "effect/Queue"
20 import * as Stream from "effect/Stream"
21
22 const TypeId = "~@effect/platform-browser/Geolocation"
23 const ErrorTypeId = "~@effect/platform-browser/Geolocation/GeolocationError"
24
25 /**
26 * Defines the service interface for browser geolocation, providing effects for the current position and streams of watched positions.
27 *
28 * **When to use**
29 *
30 * Use when browser code needs a typed Effect service for one-shot location
31 * reads or streamed location updates.
32 *
33 * **Details**
34 *
35 * `getCurrentPosition` returns one position effect. `watchPosition` returns a
36 * stream and accepts the browser `PositionOptions` plus an optional sliding
37 * `bufferSize`.
38 *
39 * **Gotchas**
40 *
41 * Browser permission prompts, denied permissions, timeouts, unavailable
42 * position data, secure-context restrictions, and policy restrictions are
43 * surfaced as `GeolocationError`.
44 *
45 * @see {@link GeolocationError} for represented browser geolocation failures
46 * @see {@link layer} for the browser-backed service implementation
47 *
48 * @stability unstable
49 * @category services
50 * @since 4.0.0
51 */
52 export interface Geolocation {
53 readonly [TypeId]: typeof TypeId
54 readonly getCurrentPosition: (
55 options?: PositionOptions | undefined
56 ) => Effect.Effect<GeolocationPosition, GeolocationError>
57 readonly watchPosition: (
58 options?:
59 | PositionOptions & {
60 readonly bufferSize?: number | undefined
61 }
62 | undefined
63 ) => Stream.Stream<GeolocationPosition, GeolocationError>
64 }
65
66 /**
67 * Service tag for browser geolocation capabilities.
68 *
69 * **When to use**
70 *
71 * Use when you need to access or provide geolocation capabilities through
72 * Effect's context.
73 *
74 * @see {@link layer} for providing the browser-backed geolocation service
75 *
76 * @stability unstable
77 * @category services
78 * @since 4.0.0
79 */
80 export const Geolocation: Context.Service<Geolocation, Geolocation> = Context.Service<Geolocation>(TypeId)
81
82 /**
83 * Tagged error wrapping a browser geolocation failure reason.
84 *
85 * @stability unstable
86 * @category errors
87 * @since 4.0.0
88 */
89 export class GeolocationError extends Data.TaggedError("GeolocationError")<{
90 readonly reason: GeolocationErrorReason
91 }> {
92 constructor(props: {
93 readonly reason: GeolocationErrorReason
94 }) {
95 super({
96 ...props,
97 cause: props.reason.cause
98 } as any)
99 }
100
101 readonly [ErrorTypeId] = ErrorTypeId
102
103 override get message(): string {
104 return this.reason.message
105 }
106 }
107
108 /**
109 * Error reason for the browser geolocation `POSITION_UNAVAILABLE` failure.
110 *
111 * @stability unstable
112 * @category errors
113 * @since 4.0.0
114 */
115 export class PositionUnavailable extends Data.TaggedError("PositionUnavailable")<{
116 readonly cause: unknown
117 }> {
118 override get message(): string {
119 return this._tag
120 }
121 }
122
123 /**
124 * Error reason for the browser geolocation `PERMISSION_DENIED` failure.
125 *
126 * @stability unstable
127 * @category errors
128 * @since 4.0.0
129 */
130 export class PermissionDenied extends Data.TaggedError("PermissionDenied")<{
131 readonly cause: unknown
132 }> {
133 override get message(): string {
134 return this._tag
135 }
136 }
137
138 /**
139 * Error reason for the browser geolocation `TIMEOUT` failure.
140 *
141 * @stability unstable
142 * @category errors
143 * @since 4.0.0
144 */
145 export class Timeout extends Data.TaggedError("Timeout")<{
146 readonly cause: unknown
147 }> {
148 override get message(): string {
149 return this._tag
150 }
151 }
152
153 /**
154 * Union of browser geolocation error reasons represented by the service.
155 *
156 * @stability unstable
157 * @category errors
158 * @since 4.0.0
159 */
160 export type GeolocationErrorReason = PositionUnavailable | PermissionDenied | Timeout
161
162 const makeQueue = (
163 options:
164 | PositionOptions & {
165 readonly bufferSize?: number | undefined
166 }
167 | undefined
168 ) =>
169 Queue.sliding<GeolocationPosition, GeolocationError>(options?.bufferSize ?? 16).pipe(
170 Effect.tap((queue) =>
171 Effect.acquireRelease(
172 Effect.sync(() =>
173 navigator.geolocation.watchPosition(
174 (position) => Queue.offerUnsafe(queue, position),
175 (cause) => {
176 if (cause.code === cause.PERMISSION_DENIED) {
177 const error = new GeolocationError({
178 reason: new PermissionDenied({ cause })
179 })
180 Queue.failCauseUnsafe(queue, Cause.fail(error))
181 } else if (cause.code === cause.TIMEOUT) {
182 const error = new GeolocationError({
183 reason: new Timeout({ cause })
184 })
185 Queue.failCauseUnsafe(queue, Cause.fail(error))
186 } else if (cause.code === cause.POSITION_UNAVAILABLE) {
187 const error = new GeolocationError({
188 reason: new PositionUnavailable({ cause })
189 })
190 Queue.failCauseUnsafe(queue, Cause.fail(error))
191 }
192 },
193 options
194 )
195 ),
196 (handleId) => Effect.sync(() => navigator.geolocation.clearWatch(handleId))
197 )
198 )
199 )
200
201 /**
202 * Layer that provides `Geolocation` using `navigator.geolocation`, with watched positions buffered in a sliding queue.
203 *
204 * @stability unstable
205 * @category layers
206 * @since 4.0.0
207 */
208 export const layer: Layer.Layer<Geolocation> = Layer.succeed(
209 Geolocation,
210 Geolocation.of({
211 [TypeId]: TypeId,
212 getCurrentPosition: (options) =>
213 makeQueue(options).pipe(
214 Effect.flatMap(Queue.take),
215 Effect.scoped
216 ),
217 watchPosition: (options) =>
218 makeQueue(options).pipe(
219 Effect.map(Stream.fromQueue),
220 Stream.unwrap
221 )
222 })
223 )
224
225 /**
226 * Reads geolocation positions from the `Geolocation` service as a stream, with
227 * an optional sliding buffer size.
228 *
229 * @stability unstable
230 * @category accessors
231 * @since 4.0.0
232 */
233 export const watchPosition = (
234 options?:
235 | PositionOptions & {
236 readonly bufferSize?: number | undefined
237 }
238 | undefined
239 ): Stream.Stream<GeolocationPosition, GeolocationError, Geolocation> =>
240 Stream.unwrap(Effect.map(
241 Effect.service(Geolocation),
242 (geolocation) => geolocation.watchPosition(options)
243 ))