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

main
ts 149 lines 4.41 KB
Raw
1 /**
2 * Browser clipboard integration for Effect programs.
3 *
4 * This module defines the `Clipboard` service, the `ClipboardError` raised by
5 * failed browser operations, a `make` constructor for custom implementations,
6 * and a browser-backed `layer` that uses `navigator.clipboard`. The service
7 * supports reading and writing text, reading and writing `ClipboardItem`
8 * payloads, writing one `Blob`, and clearing the clipboard.
9 *
10 * @stability unstable
11 * @since 4.0.0
12 */
13 import * as Context from "effect/Context"
14 import * as Data from "effect/Data"
15 import * as Effect from "effect/Effect"
16 import * as Layer from "effect/Layer"
17
18 const TypeId = "~@effect/platform-browser/Clipboard"
19 const ErrorTypeId = "~@effect/platform-browser/Clipboard/ClipboardError"
20
21 /**
22 * Defines the service interface for reading from, writing to, and clearing the browser clipboard.
23 *
24 * **When to use**
25 *
26 * Use when an application needs clipboard operations through an Effect service
27 * so browser failures stay in the error channel.
28 *
29 * **Details**
30 *
31 * `read` and `write` work with `ClipboardItem` arrays. `readString` and
32 * `writeString` use text, `writeBlob` writes one `Blob`, and `clear` writes an
33 * empty string.
34 *
35 * **Gotchas**
36 *
37 * Clipboard access generally requires a secure context and may require user
38 * activation, permissions, or a focused document. `ClipboardItem` and non-text
39 * MIME type support varies by browser. Failed browser operations are surfaced
40 * as `ClipboardError`.
41 *
42 * @stability unstable
43 * @category services
44 * @since 4.0.0
45 */
46 export interface Clipboard {
47 readonly [TypeId]: typeof TypeId
48 readonly read: Effect.Effect<ClipboardItems, ClipboardError>
49 readonly readString: Effect.Effect<string, ClipboardError>
50 readonly write: (items: ClipboardItems) => Effect.Effect<void, ClipboardError>
51 readonly writeString: (text: string) => Effect.Effect<void, ClipboardError>
52 readonly writeBlob: (blob: Blob) => Effect.Effect<void, ClipboardError>
53 readonly clear: Effect.Effect<void, ClipboardError>
54 }
55
56 /**
57 * Tagged error raised when a browser clipboard operation fails.
58 *
59 * @stability unstable
60 * @category errors
61 * @since 4.0.0
62 */
63 export class ClipboardError extends Data.TaggedError("ClipboardError")<{
64 readonly message: string
65 readonly cause: unknown
66 }> {
67 readonly [ErrorTypeId] = ErrorTypeId
68 }
69
70 /**
71 * Service tag for browser clipboard capabilities.
72 *
73 * **When to use**
74 *
75 * Use when you need to require or provide clipboard capabilities through
76 * Effect's context.
77 *
78 * @see {@link make} for building a custom clipboard service
79 * @see {@link layer} for providing the browser-backed clipboard service
80 *
81 * @stability unstable
82 * @category services
83 * @since 4.0.0
84 */
85 export const Clipboard: Context.Service<Clipboard, Clipboard> = Context.Service<Clipboard>(TypeId)
86
87 /**
88 * Builds a `Clipboard` service from primitive read and write operations, deriving `clear` and `writeBlob` helpers.
89 *
90 * @stability unstable
91 * @category constructors
92 * @since 4.0.0
93 */
94 export const make = (
95 impl: Omit<Clipboard, "clear" | "writeBlob" | typeof TypeId>
96 ): Clipboard =>
97 Clipboard.of({
98 ...impl,
99 [TypeId]: TypeId,
100 clear: impl.writeString(""),
101 writeBlob: (blob: Blob) => impl.write([new ClipboardItem({ [blob.type]: blob })])
102 })
103
104 /**
105 * Layer that directly interfaces with the browser Clipboard API.
106 *
107 * @stability unstable
108 * @category layers
109 * @since 4.0.0
110 */
111 export const layer: Layer.Layer<Clipboard> = Layer.succeed(
112 Clipboard,
113 make({
114 read: Effect.tryPromise({
115 try: () => navigator.clipboard.read(),
116 catch: (cause) =>
117 new ClipboardError({
118 cause,
119 "message": "Unable to read from clipboard"
120 })
121 }),
122 write: (s: Array<ClipboardItem>) =>
123 Effect.tryPromise({
124 try: () => navigator.clipboard.write(s),
125 catch: (cause) =>
126 new ClipboardError({
127 cause,
128 "message": "Unable to write to clipboard"
129 })
130 }),
131 readString: Effect.tryPromise({
132 try: () => navigator.clipboard.readText(),
133 catch: (cause) =>
134 new ClipboardError({
135 cause,
136 "message": "Unable to read a string from clipboard"
137 })
138 }),
139 writeString: (text: string) =>
140 Effect.tryPromise({
141 try: () => navigator.clipboard.writeText(text),
142 catch: (cause) =>
143 new ClipboardError({
144 cause,
145 "message": "Unable to write a string to clipboard"
146 })
147 })
148 })
149 )