@effect/platform-browser 4.0.0-beta.66 → 4.0.0-beta.67

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (84) hide show
  1. package/dist/BrowserHttpClient.d.ts +18 -8
  2. package/dist/BrowserHttpClient.d.ts.map +1 -1
  3. package/dist/BrowserHttpClient.js +45 -8
  4. package/dist/BrowserHttpClient.js.map +1 -1
  5. package/dist/BrowserKeyValueStore.d.ts +13 -6
  6. package/dist/BrowserKeyValueStore.d.ts.map +1 -1
  7. package/dist/BrowserKeyValueStore.js +126 -2
  8. package/dist/BrowserKeyValueStore.js.map +1 -1
  9. package/dist/BrowserPersistence.d.ts +6 -2
  10. package/dist/BrowserPersistence.d.ts.map +1 -1
  11. package/dist/BrowserPersistence.js +6 -2
  12. package/dist/BrowserPersistence.js.map +1 -1
  13. package/dist/BrowserRuntime.d.ts +31 -4
  14. package/dist/BrowserRuntime.d.ts.map +1 -1
  15. package/dist/BrowserRuntime.js +3 -1
  16. package/dist/BrowserRuntime.js.map +1 -1
  17. package/dist/BrowserSocket.d.ts +29 -4
  18. package/dist/BrowserSocket.d.ts.map +1 -1
  19. package/dist/BrowserSocket.js +29 -4
  20. package/dist/BrowserSocket.js.map +1 -1
  21. package/dist/BrowserStream.d.ts +25 -3
  22. package/dist/BrowserStream.d.ts.map +1 -1
  23. package/dist/BrowserStream.js +25 -3
  24. package/dist/BrowserStream.js.map +1 -1
  25. package/dist/BrowserWorker.d.ts +6 -2
  26. package/dist/BrowserWorker.d.ts.map +1 -1
  27. package/dist/BrowserWorker.js +27 -3
  28. package/dist/BrowserWorker.js.map +1 -1
  29. package/dist/BrowserWorkerRunner.d.ts +9 -3
  30. package/dist/BrowserWorkerRunner.d.ts.map +1 -1
  31. package/dist/BrowserWorkerRunner.js +28 -4
  32. package/dist/BrowserWorkerRunner.js.map +1 -1
  33. package/dist/Clipboard.d.ts +30 -6
  34. package/dist/Clipboard.d.ts.map +1 -1
  35. package/dist/Clipboard.js +27 -5
  36. package/dist/Clipboard.js.map +1 -1
  37. package/dist/Geolocation.d.ts +44 -10
  38. package/dist/Geolocation.d.ts.map +1 -1
  39. package/dist/Geolocation.js +38 -8
  40. package/dist/Geolocation.js.map +1 -1
  41. package/dist/IndexedDb.d.ts +38 -11
  42. package/dist/IndexedDb.d.ts.map +1 -1
  43. package/dist/IndexedDb.js +35 -13
  44. package/dist/IndexedDb.js.map +1 -1
  45. package/dist/IndexedDbDatabase.d.ts +57 -10
  46. package/dist/IndexedDbDatabase.d.ts.map +1 -1
  47. package/dist/IndexedDbDatabase.js +36 -3
  48. package/dist/IndexedDbDatabase.js.map +1 -1
  49. package/dist/IndexedDbQueryBuilder.d.ts +103 -28
  50. package/dist/IndexedDbQueryBuilder.d.ts.map +1 -1
  51. package/dist/IndexedDbQueryBuilder.js +56 -26
  52. package/dist/IndexedDbQueryBuilder.js.map +1 -1
  53. package/dist/IndexedDbTable.d.ts +57 -13
  54. package/dist/IndexedDbTable.d.ts.map +1 -1
  55. package/dist/IndexedDbTable.js +21 -1
  56. package/dist/IndexedDbTable.js.map +1 -1
  57. package/dist/IndexedDbVersion.d.ts +37 -7
  58. package/dist/IndexedDbVersion.d.ts.map +1 -1
  59. package/dist/IndexedDbVersion.js +3 -1
  60. package/dist/IndexedDbVersion.js.map +1 -1
  61. package/dist/Permissions.d.ts +35 -8
  62. package/dist/Permissions.d.ts.map +1 -1
  63. package/dist/Permissions.js +31 -6
  64. package/dist/Permissions.js.map +1 -1
  65. package/dist/index.d.ts +12 -12
  66. package/dist/index.js +12 -12
  67. package/package.json +3 -3
  68. package/src/BrowserHttpClient.ts +48 -9
  69. package/src/BrowserKeyValueStore.ts +142 -4
  70. package/src/BrowserPersistence.ts +19 -3
  71. package/src/BrowserRuntime.ts +31 -4
  72. package/src/BrowserSocket.ts +29 -4
  73. package/src/BrowserStream.ts +25 -3
  74. package/src/BrowserWorker.ts +27 -3
  75. package/src/BrowserWorkerRunner.ts +28 -4
  76. package/src/Clipboard.ts +30 -6
  77. package/src/Geolocation.ts +44 -10
  78. package/src/IndexedDb.ts +39 -21
  79. package/src/IndexedDbDatabase.ts +57 -10
  80. package/src/IndexedDbQueryBuilder.ts +172 -58
  81. package/src/IndexedDbTable.ts +57 -13
  82. package/src/IndexedDbVersion.ts +37 -7
  83. package/src/Permissions.ts +35 -8
  84. package/src/index.ts +12 -12
@@ -1,5 +1,17 @@
1
1
  /**
2
- * @since 1.0.0
2
+ * Browser-backed persistence layers for Effect's persistence service.
3
+ *
4
+ * This module provides IndexedDB implementations of the Effect persistence services for applications that need a
5
+ * durable client-side cache, such as remembered query results, offline-capable workflows, or values that should survive
6
+ * page reloads. Entries are stored by persistence store id and key in a shared IndexedDB object store, with optional
7
+ * expiration timestamps for TTL-based invalidation.
8
+ *
9
+ * Because this storage depends on browser IndexedDB, operations can fail when storage is unavailable, quota is exceeded,
10
+ * data is cleared by the user or browser, or the payload cannot be structured-cloned by IndexedDB. Expired entries are
11
+ * removed lazily when they are read, so this module is best suited for application-managed cached objects rather than
12
+ * security-sensitive or authoritative data.
13
+ *
14
+ * @since 4.0.0
3
15
  */
4
16
  import type * as Arr from "effect/Array"
5
17
  import * as Clock from "effect/Clock"
@@ -9,8 +21,10 @@ import * as Layer from "effect/Layer"
9
21
  import * as Persistence from "effect/unstable/persistence/Persistence"
10
22
 
11
23
  /**
12
- * @since 1.0.0
24
+ * Creates a `BackingPersistence` layer backed by IndexedDB, optionally using the provided database name.
25
+ *
13
26
  * @category layers
27
+ * @since 4.0.0
14
28
  */
15
29
  export const layerBackingIndexedDb = (options?: {
16
30
  readonly database?: string | undefined
@@ -42,8 +56,10 @@ const entriesStoreName = "entries"
42
56
  const storeIdIndexName = "storeId"
43
57
 
44
58
  /**
45
- * @since 1.0.0
59
+ * Creates a `Persistence` layer backed by IndexedDB, optionally using the provided database name.
60
+ *
46
61
  * @category layers
62
+ * @since 4.0.0
47
63
  */
48
64
  export const layerIndexedDb = (options?: {
49
65
  readonly database?: string | undefined
@@ -1,17 +1,42 @@
1
1
  /**
2
- * @since 1.0.0
2
+ * Browser entry-point helpers for running Effect programs.
3
+ *
4
+ * This module exposes `runMain`, a browser-oriented main runner for launching
5
+ * an Effect as the root program of a page, single-page application, demo, or
6
+ * browser test harness. It delegates execution to the core Effect runtime while
7
+ * adding the browser lifecycle hook needed to interrupt the main fiber when the
8
+ * page receives `beforeunload`.
9
+ *
10
+ * `BrowserRuntime` does not provide application services by itself. Provide
11
+ * any required layers, such as browser HTTP, storage, worker, geolocation, or
12
+ * permission services, before passing the effect to `runMain`. Keep long-lived
13
+ * browser resources scoped so interruption can run their finalizers while the
14
+ * page is still active.
15
+ *
16
+ * Browser unload is more constrained than a process signal. Finalizers that
17
+ * need the network, timers, prompts, or long asynchronous work may not complete
18
+ * once navigation or tab close has started, and browsers do not expose a
19
+ * process exit status. Use `runMain` to connect the page lifecycle to Effect
20
+ * interruption, and use browser-specific persistence or delivery APIs for work
21
+ * that must survive page teardown.
22
+ *
23
+ * @since 4.0.0
3
24
  */
4
25
  import type * as Effect from "effect/Effect"
5
26
  import { makeRunMain, type Teardown } from "effect/Runtime"
6
27
 
7
28
  /**
8
- * @since 1.0.0
29
+ * Runs an effect as the browser main program and interrupts its fiber when the page receives a `beforeunload` event.
30
+ *
9
31
  * @category Runtime
32
+ * @since 4.0.0
10
33
  */
11
34
  export const runMain: {
12
35
  /**
13
- * @since 1.0.0
36
+ * Runs an effect as the browser main program and interrupts its fiber when the page receives a `beforeunload` event.
37
+ *
14
38
  * @category Runtime
39
+ * @since 4.0.0
15
40
  */
16
41
  (
17
42
  options?: {
@@ -20,8 +45,10 @@ export const runMain: {
20
45
  }
21
46
  ): <E, A>(effect: Effect.Effect<A, E>) => void
22
47
  /**
23
- * @since 1.0.0
48
+ * Runs an effect as the browser main program and interrupts its fiber when the page receives a `beforeunload` event.
49
+ *
24
50
  * @category Runtime
51
+ * @since 4.0.0
25
52
  */
26
53
  <E, A>(
27
54
  effect: Effect.Effect<A, E>,
@@ -1,12 +1,37 @@
1
1
  /**
2
- * @since 1.0.0
2
+ * Browser WebSocket layers for Effect sockets.
3
+ *
4
+ * This module provides the browser entry point for `Socket.Socket` values
5
+ * backed by the platform `WebSocket` implementation. Use `layerWebSocket` when
6
+ * client-side Effect programs, browser tests, RPC transports, or realtime UI
7
+ * features need a bidirectional socket connected to a WebSocket URL, and use
8
+ * `layerWebSocketConstructor` when lower-level socket APIs need access to the
9
+ * browser constructor service.
10
+ *
11
+ * Browser WebSocket rules still apply. Connections are created through
12
+ * `globalThis.WebSocket`, so URL schemes, subprotocol negotiation, mixed-content
13
+ * blocking, cookies, authentication, CORS-like origin checks, and extension
14
+ * negotiation are controlled by the browser and server rather than by Effect.
15
+ * Close events are translated into socket errors unless the provided
16
+ * `closeCodeIsError` predicate classifies the close code as clean, which is
17
+ * useful for protocols that use application-specific close codes.
18
+ *
19
+ * Messages are delivered as strings or binary `Uint8Array` values; browser
20
+ * `Blob` messages are read into bytes before they reach the socket handler.
21
+ * Outgoing data should already be serialized to a string or bytes, and protocol
22
+ * frames that represent an intentional close should be sent as `CloseEvent`
23
+ * values so the underlying `WebSocket.close` code and reason are preserved.
24
+ *
25
+ * @since 4.0.0
3
26
  */
4
27
  import * as Layer from "effect/Layer"
5
28
  import * as Socket from "effect/unstable/socket/Socket"
6
29
 
7
30
  /**
8
- * @since 1.0.0
31
+ * Creates a `Socket` layer connected to the given URL using the browser `WebSocket` constructor.
32
+ *
9
33
  * @category Layers
34
+ * @since 4.0.0
10
35
  */
11
36
  export const layerWebSocket = (url: string, options?: {
12
37
  readonly closeCodeIsError?: (code: number) => boolean
@@ -16,10 +41,10 @@ export const layerWebSocket = (url: string, options?: {
16
41
  )
17
42
 
18
43
  /**
19
- * A WebSocket constructor that uses `globalThis.WebSocket`.
44
+ * Layer that provides a `WebSocketConstructor` service backed by `globalThis.WebSocket`.
20
45
  *
21
- * @since 1.0.0
22
46
  * @category Layers
47
+ * @since 4.0.0
23
48
  */
24
49
  export const layerWebSocketConstructor: Layer.Layer<Socket.WebSocketConstructor> =
25
50
  Socket.layerWebSocketConstructorGlobal
@@ -1,5 +1,27 @@
1
1
  /**
2
- * @since 1.0.0
2
+ * Browser `Stream` constructors for DOM event targets.
3
+ *
4
+ * This module provides typed helpers for turning `window.addEventListener` and
5
+ * `document.addEventListener` callbacks into Effect `Stream`s. They are useful
6
+ * for UI and runtime signals such as resize, visibility, keyboard, pointer,
7
+ * focus, online / offline, and other browser events that should be composed
8
+ * with Effect stream operators and finalized with the consuming fiber.
9
+ *
10
+ * Browser events are push-based `EventTarget` notifications, so they do not
11
+ * apply Web Streams backpressure to the browser event source. Events are
12
+ * buffered until downstream pulls them; the default buffer is unbounded, so
13
+ * high-frequency sources like scroll, pointermove, or mousemove should usually
14
+ * set `bufferSize` and use stream operators that sample, debounce, throttle, or
15
+ * drop work as appropriate.
16
+ *
17
+ * These helpers are for DOM events, not for adapting `ReadableStream` request
18
+ * or response bodies. Fetch bodies follow the Web Streams body rules, including
19
+ * single-consumer locking and disturbed bodies after reads, and should be
20
+ * handled with body-specific HTTP or Web Streams APIs instead. When using the
21
+ * browser `once` option, pair the stream with `Stream.take(1)` if a finite
22
+ * stream is required.
23
+ *
24
+ * @since 4.0.0
3
25
  */
4
26
 
5
27
  import * as Stream from "effect/Stream"
@@ -10,8 +32,8 @@ import * as Stream from "effect/Stream"
10
32
  * By default, the underlying buffer is unbounded in size. You can customize the
11
33
  * buffer size an object as the second argument with the `bufferSize` field.
12
34
  *
13
- * @since 1.0.0
14
35
  * @category Streams
36
+ * @since 4.0.0
15
37
  */
16
38
  export const fromEventListenerWindow = <K extends keyof WindowEventMap>(
17
39
  type: K,
@@ -29,8 +51,8 @@ export const fromEventListenerWindow = <K extends keyof WindowEventMap>(
29
51
  * By default, the underlying buffer is unbounded in size. You can customize the
30
52
  * buffer size an object as the second argument with the `bufferSize` field.
31
53
  *
32
- * @since 1.0.0
33
54
  * @category Streams
55
+ * @since 4.0.0
34
56
  */
35
57
  export const fromEventListenerDocument = <K extends keyof DocumentEventMap>(
36
58
  type: K,
@@ -1,5 +1,25 @@
1
1
  /**
2
- * @since 1.0.0
2
+ * Parent-side browser support for Effect workers.
3
+ *
4
+ * This module provides the `WorkerPlatform` used by browser applications that
5
+ * spawn or connect to `Worker`, `SharedWorker`, and `MessagePort` endpoints
6
+ * through Effect's worker protocol. Pair it with `BrowserWorkerRunner` in the
7
+ * worker entrypoint when building worker-backed RPC clients, moving CPU-bound
8
+ * work off the main thread, isolating browser-only services, or adapting an
9
+ * existing `MessageChannel` in tests and custom transports.
10
+ *
11
+ * Dedicated workers communicate through the worker object itself, while shared
12
+ * workers communicate through `worker.port`; raw `MessagePort` values are also
13
+ * accepted and are started when supported. Messages are posted with the browser
14
+ * structured-clone algorithm, so payloads must be cloneable by the target
15
+ * runtime. Transfer lists can avoid copying values such as `ArrayBuffer` or
16
+ * `MessagePort`, but transferring moves ownership away from the sender and
17
+ * invalid or mismatched transferables can fail the send. Scope finalization
18
+ * sends the worker close signal over the port; the application that created a
19
+ * dedicated `Worker` remains responsible for any broader lifecycle such as
20
+ * terminating it.
21
+ *
22
+ * @since 4.0.0
3
23
  */
4
24
  import * as Deferred from "effect/Deferred"
5
25
  import * as Effect from "effect/Effect"
@@ -9,8 +29,10 @@ import * as Worker from "effect/unstable/workers/Worker"
9
29
  import { WorkerError, WorkerReceiveError } from "effect/unstable/workers/WorkerError"
10
30
 
11
31
  /**
12
- * @since 1.0.0
32
+ * Creates browser worker layers by combining the default `WorkerPlatform` with a spawner for `Worker`, `SharedWorker`, or `MessagePort` instances.
33
+ *
13
34
  * @category Layers
35
+ * @since 4.0.0
14
36
  */
15
37
  export const layer = (
16
38
  spawn: (id: number) => Worker | SharedWorker | MessagePort
@@ -21,8 +43,10 @@ export const layer = (
21
43
  )
22
44
 
23
45
  /**
24
- * @since 1.0.0
46
+ * Layer that provides the browser `WorkerPlatform` for `Worker`, `SharedWorker`, and `MessagePort` communication.
47
+ *
25
48
  * @category Layers
49
+ * @since 4.0.0
26
50
  */
27
51
  export const layerPlatform: Layer.Layer<Worker.WorkerPlatform> = Layer.succeed(Worker.WorkerPlatform)(
28
52
  Worker.makePlatform<globalThis.SharedWorker | globalThis.Worker | MessagePort>()({
@@ -1,5 +1,23 @@
1
1
  /**
2
- * @since 1.0.0
2
+ * Browser runtime support for Effect worker runners.
3
+ *
4
+ * This module is intended for code that is already executing in a browser
5
+ * worker context, or for tests and adapters that supply a `MessagePort` or
6
+ * `Window` endpoint directly. It provides the `WorkerRunnerPlatform` used by
7
+ * `WorkerRunner` and `RpcServer.layerProtocolWorkerRunner` to receive parent
8
+ * or client requests, run Effect handlers, and send responses through the
9
+ * browser `postMessage` channel.
10
+ *
11
+ * Use it with `BrowserWorker` when a browser application needs to move RPC
12
+ * handlers, CPU-bound computations, or browser-only services into a dedicated
13
+ * worker or shared worker. Dedicated workers communicate through the current
14
+ * `self` endpoint; shared workers accept multiple `onconnect` ports and cache
15
+ * ports that connect before the runner layer starts. Messages still use the
16
+ * browser structured-clone algorithm, so payload schemas, transfer lists,
17
+ * `messageerror` events, and the lifetime of each `MessagePort` must be
18
+ * considered when crossing worker boundaries.
19
+ *
20
+ * @since 4.0.0
3
21
  */
4
22
  import * as Cause from "effect/Cause"
5
23
  import * as Deferred from "effect/Deferred"
@@ -22,8 +40,10 @@ if (typeof self !== "undefined" && "onconnect" in self) {
22
40
  }
23
41
 
24
42
  /**
25
- * @since 1.0.0
43
+ * Creates a `WorkerRunnerPlatform` service that runs worker handlers over a `MessagePort` or `Window`.
44
+ *
26
45
  * @category Constructors
46
+ * @since 4.0.0
27
47
  */
28
48
  export const make = (self: MessagePort | Window): WorkerRunner.WorkerRunnerPlatform["Service"] => ({
29
49
  start: Effect.fnUntraced(function*<O = unknown, I = unknown>() {
@@ -151,16 +171,20 @@ export const make = (self: MessagePort | Window): WorkerRunner.WorkerRunnerPlatf
151
171
  })
152
172
 
153
173
  /**
154
- * @since 1.0.0
174
+ * Layer that provides a browser `WorkerRunnerPlatform` using the global `self` worker context.
175
+ *
155
176
  * @category Layers
177
+ * @since 4.0.0
156
178
  */
157
179
  export const layer: Layer.Layer<WorkerRunner.WorkerRunnerPlatform> = Layer.sync(WorkerRunner.WorkerRunnerPlatform)(() =>
158
180
  make(self)
159
181
  )
160
182
 
161
183
  /**
162
- * @since 1.0.0
184
+ * Layer that provides a `WorkerRunnerPlatform` using the supplied `MessagePort` or `Window`.
185
+ *
163
186
  * @category Layers
187
+ * @since 4.0.0
164
188
  */
165
189
  export const layerMessagePort = (port: MessagePort | Window): Layer.Layer<WorkerRunner.WorkerRunnerPlatform> =>
166
190
  Layer.succeed(WorkerRunner.WorkerRunnerPlatform)(make(port))
package/src/Clipboard.ts CHANGED
@@ -1,5 +1,21 @@
1
1
  /**
2
- * @since 1.0.0
2
+ * Browser clipboard service for Effect programs.
3
+ *
4
+ * This module wraps the browser `navigator.clipboard` API in a `Clipboard`
5
+ * service so client-side applications can read, write, and clear clipboard
6
+ * contents as typed Effects. It is useful for common UI workflows such as copy
7
+ * buttons, paste/import actions, sharing generated text, and moving rich
8
+ * clipboard payloads like `Blob`-backed `ClipboardItem`s through an Effect
9
+ * environment.
10
+ *
11
+ * Browser clipboard rules still apply. Clipboard access generally requires a
12
+ * secure context, and browsers may require a user gesture, permission prompt, or
13
+ * active focused document before reads or writes are allowed. Support also
14
+ * varies by operation and payload type: text helpers are the most portable,
15
+ * while `ClipboardItem` and non-text MIME types may be unavailable or restricted
16
+ * in some browsers. Failed browser operations are surfaced as `ClipboardError`.
17
+ *
18
+ * @since 4.0.0
3
19
  */
4
20
  import * as Context from "effect/Context"
5
21
  import * as Data from "effect/Data"
@@ -10,8 +26,10 @@ const TypeId = "~@effect/platform-browser/Clipboard"
10
26
  const ErrorTypeId = "~@effect/platform-browser/Clipboard/ClipboardError"
11
27
 
12
28
  /**
13
- * @since 1.0.0
29
+ * Service interface for reading from, writing to, and clearing the browser clipboard.
30
+ *
14
31
  * @category Models
32
+ * @since 4.0.0
15
33
  */
16
34
  export interface Clipboard {
17
35
  readonly [TypeId]: typeof TypeId
@@ -24,8 +42,10 @@ export interface Clipboard {
24
42
  }
25
43
 
26
44
  /**
27
- * @since 1.0.0
45
+ * Tagged error raised when a browser clipboard operation fails.
46
+ *
28
47
  * @category Errors
48
+ * @since 4.0.0
29
49
  */
30
50
  export class ClipboardError extends Data.TaggedError("ClipboardError")<{
31
51
  readonly message: string
@@ -35,14 +55,18 @@ export class ClipboardError extends Data.TaggedError("ClipboardError")<{
35
55
  }
36
56
 
37
57
  /**
38
- * @since 1.0.0
58
+ * Service tag for the browser `Clipboard` service.
59
+ *
39
60
  * @category Service
61
+ * @since 4.0.0
40
62
  */
41
63
  export const Clipboard: Context.Service<Clipboard, Clipboard> = Context.Service<Clipboard>(TypeId)
42
64
 
43
65
  /**
44
- * @since 1.0.0
66
+ * Builds a `Clipboard` service from primitive read and write operations, deriving `clear` and `writeBlob` helpers.
67
+ *
45
68
  * @category Constructors
69
+ * @since 4.0.0
46
70
  */
47
71
  export const make = (
48
72
  impl: Omit<Clipboard, "clear" | "writeBlob" | typeof TypeId>
@@ -57,8 +81,8 @@ export const make = (
57
81
  /**
58
82
  * A layer that directly interfaces with the navigator.clipboard api
59
83
  *
60
- * @since 1.0.0
61
84
  * @category Layers
85
+ * @since 4.0.0
62
86
  */
63
87
  export const layer: Layer.Layer<Clipboard> = Layer.succeed(
64
88
  Clipboard,
@@ -1,5 +1,21 @@
1
1
  /**
2
- * @since 1.0.0
2
+ * Browser geolocation support for Effect programs.
3
+ *
4
+ * This module provides a `Geolocation` service and browser-backed layer for
5
+ * reading device location through `navigator.geolocation`. Use
6
+ * `getCurrentPosition` when an application needs one location fix, such as a
7
+ * nearby-search, check-in, or delivery estimate, and `watchPosition` when it
8
+ * needs a stream of updates for navigation, tracking, or location-aware UI.
9
+ *
10
+ * The implementation is browser-only and relies on the browser permission and
11
+ * policy model for geolocation. Calls may prompt the user, fail when permission
12
+ * is denied, time out, or report that position data is unavailable because of
13
+ * device, browser, privacy, origin, or secure-context restrictions. Watched
14
+ * positions are scoped so the underlying browser watch is cleared when the
15
+ * stream is finalized, and slow consumers should account for the sliding
16
+ * buffer used by `watchPosition`.
17
+ *
18
+ * @since 4.0.0
3
19
  */
4
20
  import * as Cause from "effect/Cause"
5
21
  import * as Context from "effect/Context"
@@ -13,8 +29,10 @@ const TypeId = "~@effect/platform-browser/Geolocation"
13
29
  const ErrorTypeId = "~@effect/platform-browser/Geolocation/GeolocationError"
14
30
 
15
31
  /**
16
- * @since 1.0.0
32
+ * Service interface for browser geolocation, providing effects for the current position and streams of watched positions.
33
+ *
17
34
  * @category Models
35
+ * @since 4.0.0
18
36
  */
19
37
  export interface Geolocation {
20
38
  readonly [TypeId]: typeof TypeId
@@ -31,14 +49,18 @@ export interface Geolocation {
31
49
  }
32
50
 
33
51
  /**
34
- * @since 1.0.0
52
+ * Service tag for the browser `Geolocation` service.
53
+ *
35
54
  * @category Service
55
+ * @since 4.0.0
36
56
  */
37
57
  export const Geolocation: Context.Service<Geolocation, Geolocation> = Context.Service<Geolocation>(TypeId)
38
58
 
39
59
  /**
40
- * @since 1.0.0
60
+ * Tagged error wrapping a browser geolocation failure reason.
61
+ *
41
62
  * @category Errors
63
+ * @since 4.0.0
42
64
  */
43
65
  export class GeolocationError extends Data.TaggedError("GeolocationError")<{
44
66
  readonly reason: GeolocationErrorReason
@@ -60,8 +82,10 @@ export class GeolocationError extends Data.TaggedError("GeolocationError")<{
60
82
  }
61
83
 
62
84
  /**
63
- * @since 1.0.0
85
+ * Error reason for the browser geolocation `POSITION_UNAVAILABLE` failure.
86
+ *
64
87
  * @category Errors
88
+ * @since 4.0.0
65
89
  */
66
90
  export class PositionUnavailable extends Data.TaggedError("PositionUnavailable")<{
67
91
  readonly cause: unknown
@@ -72,8 +96,10 @@ export class PositionUnavailable extends Data.TaggedError("PositionUnavailable")
72
96
  }
73
97
 
74
98
  /**
75
- * @since 1.0.0
99
+ * Error reason for the browser geolocation `PERMISSION_DENIED` failure.
100
+ *
76
101
  * @category Errors
102
+ * @since 4.0.0
77
103
  */
78
104
  export class PermissionDenied extends Data.TaggedError("PermissionDenied")<{
79
105
  readonly cause: unknown
@@ -84,8 +110,10 @@ export class PermissionDenied extends Data.TaggedError("PermissionDenied")<{
84
110
  }
85
111
 
86
112
  /**
87
- * @since 1.0.0
113
+ * Error reason for the browser geolocation `TIMEOUT` failure.
114
+ *
88
115
  * @category Errors
116
+ * @since 4.0.0
89
117
  */
90
118
  export class Timeout extends Data.TaggedError("Timeout")<{
91
119
  readonly cause: unknown
@@ -96,8 +124,10 @@ export class Timeout extends Data.TaggedError("Timeout")<{
96
124
  }
97
125
 
98
126
  /**
99
- * @since 1.0.0
127
+ * Union of browser geolocation error reasons represented by the service.
128
+ *
100
129
  * @category Errors
130
+ * @since 4.0.0
101
131
  */
102
132
  export type GeolocationErrorReason = PositionUnavailable | PermissionDenied | Timeout
103
133
 
@@ -141,8 +171,10 @@ const makeQueue = (
141
171
  )
142
172
 
143
173
  /**
144
- * @since 1.0.0
174
+ * Layer that provides `Geolocation` using `navigator.geolocation`, with watched positions buffered in a sliding queue.
175
+ *
145
176
  * @category Layers
177
+ * @since 4.0.0
146
178
  */
147
179
  export const layer: Layer.Layer<Geolocation> = Layer.succeed(
148
180
  Geolocation,
@@ -162,8 +194,10 @@ export const layer: Layer.Layer<Geolocation> = Layer.succeed(
162
194
  )
163
195
 
164
196
  /**
165
- * @since 1.0.0
197
+ * Streams positions from the `Geolocation` service using `watchPosition`, with an optional sliding buffer size.
198
+ *
166
199
  * @category Accessors
200
+ * @since 4.0.0
167
201
  */
168
202
  export const watchPosition = (
169
203
  options?:
package/src/IndexedDb.ts CHANGED
@@ -1,18 +1,40 @@
1
1
  /**
2
+ * Browser IndexedDB primitives and key schemas for Effect applications.
3
+ *
4
+ * This module is the low-level bridge used by the platform-browser IndexedDB
5
+ * integration. It provides an `IndexedDb` service around the browser
6
+ * `indexedDB` factory and `IDBKeyRange` constructor, a `layerWindow` layer for
7
+ * wiring those primitives from `window`, and schemas for the key shapes accepted
8
+ * by IndexedDB object stores and indexes.
9
+ *
10
+ * Use it when building typed local persistence for browser caches,
11
+ * offline-first state, background queues, drafts, or other client-side data
12
+ * that should be validated before it reaches IndexedDB. Higher-level database,
13
+ * version, table, and query modules build on these primitives for migrations
14
+ * and typed transactions.
15
+ *
16
+ * IndexedDB still follows the browser rules: schema changes happen only during
17
+ * version upgrades, upgrades may be blocked by other open tabs or connections,
18
+ * and reads or writes must run in transactions scoped to the object stores they
19
+ * touch. The `layerWindow` constructor should be used only where browser
20
+ * globals are available, and code that also runs during SSR or in restricted
21
+ * browser contexts should account for `indexedDB` or `IDBKeyRange` being
22
+ * missing.
23
+ *
2
24
  * @since 4.0.0
3
25
  */
4
- import * as Config from "effect/Config"
5
26
  import * as Context from "effect/Context"
6
27
  import * as Effect from "effect/Effect"
7
28
  import * as Layer from "effect/Layer"
8
29
  import * as Schema from "effect/Schema"
9
- import * as SchemaIssue from "effect/SchemaIssue"
10
30
 
11
31
  const TypeId = "~@effect/platform-browser/IndexedDb"
12
32
 
13
33
  /**
14
- * @since 4.0.0
34
+ * Service interface that provides the browser `indexedDB` factory and `IDBKeyRange` constructor.
35
+ *
15
36
  * @category models
37
+ * @since 4.0.0
16
38
  */
17
39
  export interface IndexedDb {
18
40
  readonly [TypeId]: typeof TypeId
@@ -21,8 +43,10 @@ export interface IndexedDb {
21
43
  }
22
44
 
23
45
  /**
24
- * @since 4.0.0
46
+ * Service tag for browser IndexedDB primitives.
47
+ *
25
48
  * @category tag
49
+ * @since 4.0.0
26
50
  */
27
51
  export const IndexedDb: Context.Service<IndexedDb, IndexedDb> = Context.Service<IndexedDb, IndexedDb>(TypeId)
28
52
 
@@ -39,18 +63,18 @@ const IDBFlatKey = Schema.Union([
39
63
  ])
40
64
 
41
65
  /**
42
- * Schema for `IDBValidKey` (`number | string | Date | BufferSource | IDBValidKey[]`).
66
+ * Schema for IndexedDB keys: strings, non-NaN numbers, valid dates, buffer sources, or arrays of those flat key values.
43
67
  *
44
- * @since 4.0.0
45
68
  * @category schemas
69
+ * @since 4.0.0
46
70
  */
47
71
  export const IDBValidKey = Schema.Union([IDBFlatKey, Schema.Array(IDBFlatKey)])
48
72
 
49
73
  /**
50
- * Schema for `autoIncrement` key path (`number`).
74
+ * Schema for auto-incremented IndexedDB keys, accepting integers from 1 through `2 ** 53`.
51
75
  *
52
- * @since 4.0.0
53
76
  * @category schemas
77
+ * @since 4.0.0
54
78
  */
55
79
  export const AutoIncrement = Schema.Int.check(
56
80
  Schema.isBetween({ minimum: 1, maximum: 2 ** 53 })
@@ -61,18 +85,20 @@ export const AutoIncrement = Schema.Int.check(
61
85
  })
62
86
 
63
87
  /**
64
- * @since 4.0.0
88
+ * Creates an `IndexedDb` service from an `IDBFactory` and `IDBKeyRange` constructor.
89
+ *
65
90
  * @category constructor
91
+ * @since 4.0.0
66
92
  */
67
93
  export const make = (impl: Omit<IndexedDb, typeof TypeId>): IndexedDb => IndexedDb.of({ [TypeId]: TypeId, ...impl })
68
94
 
69
95
  /**
70
- * Instance of IndexedDb from the `window` object.
96
+ * Layer that provides `IndexedDb` from `window.indexedDB` and `window.IDBKeyRange`, failing with a config error when they are unavailable.
71
97
  *
72
- * @since 4.0.0
73
98
  * @category constructors
99
+ * @since 4.0.0
74
100
  */
75
- export const layerWindow: Layer.Layer<IndexedDb, Config.ConfigError> = Layer.effect(
101
+ export const layerWindow: Layer.Layer<IndexedDb> = Layer.effect(
76
102
  IndexedDb,
77
103
  Effect.suspend(() => {
78
104
  if (window.indexedDB && window.IDBKeyRange) {
@@ -83,15 +109,7 @@ export const layerWindow: Layer.Layer<IndexedDb, Config.ConfigError> = Layer.eff
83
109
  })
84
110
  )
85
111
  } else {
86
- return Effect.fail(
87
- new Config.ConfigError(
88
- new Schema.SchemaError(
89
- new SchemaIssue.MissingKey({
90
- messageMissingKey: "window.indexedDB is not available"
91
- })
92
- )
93
- )
94
- )
112
+ return Effect.die(new Error("window.indexedDB is not available"))
95
113
  }
96
114
  })
97
115
  )