@effect/platform-bun 4.0.2 → 4.0.4

package/dist/BunDatagramSocket.d.ts

@@ -0,0 +1,227 @@
+/**
+ * Bun UDP adapter for `effect/socket/DatagramSocket`, built on the native
+ * `Bun.udpSocket`. Requires Bun 1.4 or later: earlier versions throw `EAGAIN`
+ * from `send` instead of returning `false`, and never fire `drain`.
+ *
+ * `make` opens a new Bun socket for each reader acquisition, `fromUdpSocket`
+ * adopts a socket the caller creates, and `layer` provides the
+ * `DatagramSocket` service.
+ *
+ * The reader owns the native socket, so a send-only client must still acquire
+ * a reader, or its writes wait forever. Bun sends synchronously: a send error
+ * fails the write that caused it, and when the kernel buffer is full the write
+ * waits for `drain` and sends what is left.
+ *
+ * `writeAll` sends the batch with one `sendMany` call and fails with its first
+ * error. Which datagrams went out is unspecified, nothing is resent, and the
+ * error has no `address`, because Bun reports one error for the whole call.
+ *
+ * ICMP reports, such as a refused port, arrive after the write has completed,
+ * so they go to the `onError` option as a `DatagramSocketReadError` with no
+ * address.
+ *
+ * On macOS and Windows a poll error closes the socket without any event. The
+ * adapter notices on the next write, which fails with
+ * `DatagramSocketClosedError`, as do the reader and any write waiting for
+ * `drain`. Until then those waiting writes and `pull` keep waiting. The same
+ * applies when the caller closes a socket adopted with `fromUdpSocket`.
+ *
+ * **Example** (Echo server)
+ *
+ * ```ts
+ * import { BunDatagramSocket } from "@effect/platform-bun"
+ * import { Effect } from "effect"
+ *
+ * const echo = Effect.gen(function*() {
+ *   const socket = yield* BunDatagramSocket.make({ bind: { port: 9000 } })
+ *   const reader = yield* socket.reader
+ *   const writer = yield* socket.writer
+ *   while (true) {
+ *     for (const received of yield* reader.pull) {
+ *       yield* writer.write({ payload: received.payload, address: received })
+ *     }
+ *   }
+ * }).pipe(Effect.scoped)
+ * ```
+ *
+ * **Example** (Send-only client with a connected socket)
+ *
+ * ```ts
+ * import { BunDatagramSocket } from "@effect/platform-bun"
+ * import { Effect } from "effect"
+ *
+ * const send = (payload: string) =>
+ *   Effect.gen(function*() {
+ *     const socket = yield* BunDatagramSocket.make({
+ *       connect: { address: "localhost", port: 9000 }
+ *     })
+ *     // Required even for send-only clients.
+ *     yield* socket.reader
+ *     const writer = yield* socket.writer
+ *     yield* writer.write({ payload })
+ *   }).pipe(Effect.scoped)
+ * ```
+ *
+ * **Example** (Adopting a socket)
+ *
+ * ```ts
+ * import { BunDatagramSocket } from "@effect/platform-bun"
+ * import { Effect } from "effect"
+ *
+ * const receive = Effect.gen(function*() {
+ *   // `fromUdpSocket` replaces the socket's handlers with its own
+ *   const socket = yield* BunDatagramSocket.fromUdpSocket(
+ *     Effect.promise(() => Bun.udpSocket({ hostname: "127.0.0.1", port: 9000 }))
+ *   )
+ *   const reader = yield* socket.reader
+ *   return yield* reader.pull
+ * }).pipe(Effect.scoped)
+ * ```
+ *
+ * @stability experimental
+ * @since 4.0.0
+ */
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as NetAddress from "effect/net/NetAddress";
+import type * as Scope from "effect/Scope";
+import * as DatagramSocket from "effect/socket/DatagramSocket";
+/**
+ * An open-time endpoint. Hostnames resolve once per reader acquisition via
+ * `node:dns.lookup`, avoiding Bun's synchronous `getaddrinfo`.
+ * An `InetAddress` can be passed directly.
+ *
+ * @stability experimental
+ * @category models
+ * @since 4.0.0
+ */
+export interface Endpoint {
+    readonly address: string | NetAddress.IpAddress;
+    readonly port: number;
+}
+/**
+ * The local address and port to bind. Defaults to `0.0.0.0` (or `::` for
+ * `family: "ipv6"`) and an ephemeral port.
+ *
+ * @stability experimental
+ * @category models
+ * @since 4.0.0
+ */
+export interface BindOptions {
+    readonly address?: string | NetAddress.IpAddress | undefined;
+    readonly port?: number | undefined;
+}
+/**
+ * Options for `fromUdpSocket`. The caller configures the adopted socket, so
+ * only the options that live in JavaScript apply.
+ *
+ * @stability experimental
+ * @category models
+ * @since 4.0.0
+ */
+export interface AdoptOptions {
+    readonly peer?: Endpoint | undefined;
+    readonly receiveBuffer?: DatagramSocket.ReceiveBufferOptions | undefined;
+    readonly onError?: ((error: DatagramSocket.DatagramSocketError) => void) | undefined;
+}
+/**
+ * Options for `make` and `layer`.
+ *
+ * **Details**
+ *
+ * `peer` is a default destination and doesn't filter senders. `connect`
+ * connects the socket when Bun creates it, so the kernel filters senders. The
+ * two can't be combined.
+ *
+ * Family selection, in order: explicit `family`, a `bind` IP literal, the
+ * `peer` or `connect` address, a `bind` hostname, then `"ipv4"`. Hostname
+ * lookups use the family selected so far, or prefer IPv4 if none is set.
+ *
+ * `reuseAddress` means `SO_REUSEADDR` on Linux and `SO_REUSEPORT` on BSD and
+ * macOS.
+ *
+ * `multicast.interface` is the egress interface for datagrams sent to a group,
+ * which is a different socket option from the ingress `interface` of
+ * `Reader.joinMulticast`.
+ *
+ * @stability experimental
+ * @category models
+ * @since 4.0.0
+ */
+export type Options = {
+    readonly bind?: BindOptions | undefined;
+    readonly family?: "ipv4" | "ipv6" | undefined;
+    readonly reuseAddress?: boolean | undefined;
+    readonly reusePort?: boolean | undefined;
+    readonly ipv6Only?: boolean | undefined;
+    readonly broadcast?: boolean | undefined;
+    readonly ttl?: number | undefined;
+    readonly multicast?: {
+        readonly interface?: NetAddress.MulticastInterface | undefined;
+        readonly loopback?: boolean | undefined;
+        readonly ttl?: number | undefined;
+    } | undefined;
+    readonly receiveBuffer?: DatagramSocket.ReceiveBufferOptions | undefined;
+    readonly onError?: ((error: DatagramSocket.DatagramSocketError) => void) | undefined;
+} & ({
+    readonly peer?: Endpoint | undefined;
+    readonly connect?: undefined;
+} | {
+    readonly connect: Endpoint;
+    readonly peer?: undefined;
+});
+/**
+ * A native Bun UDP socket, connected or not.
+ *
+ * @stability experimental
+ * @category models
+ * @since 4.0.0
+ */
+export type UdpSocket = Bun.udp.Socket<"buffer"> | Bun.udp.ConnectedSocket<"buffer">;
+/**
+ * Creates a `DatagramSocket` that opens and binds a new Bun UDP socket for
+ * each reader acquisition.
+ *
+ * **Details**
+ *
+ * Creating the socket never fails. Binding, applying options and resolving
+ * names happen on reader acquisition and fail it with a `DatagramSocketError`.
+ * Hostnames in `bind`, `peer` and `connect` are resolved once per acquisition;
+ * sends never wait for DNS.
+ *
+ * Invalid `receiveBuffer.capacity` values cause a defect; use a positive
+ * safe integer.
+ *
+ * @stability experimental
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const make: (options?: Options) => Effect.Effect<DatagramSocket.DatagramSocket>;
+/**
+ * Adopts a Bun UDP socket.
+ *
+ * **Details**
+ *
+ * `acquire` runs once per reader acquisition, inside the reader's scope, and
+ * the adapter closes the socket when that scope ends. Whether the socket is
+ * connected is checked once at open.
+ *
+ * The adapter installs its own `data`, `drain` and `error` handlers with
+ * `socket.reload`, which replaces the ones the caller passed to
+ * `Bun.udpSocket`. Packets that arrive before `acquire` completes still go to
+ * the caller's handlers.
+ *
+ * @stability experimental
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const fromUdpSocket: <R>(acquire: Effect.Effect<UdpSocket, DatagramSocket.DatagramSocketError, R>, options?: AdoptOptions) => Effect.Effect<DatagramSocket.DatagramSocket, never, Exclude<R, Scope.Scope>>;
+/**
+ * Provides a `DatagramSocket` built with `make`.
+ *
+ * @stability experimental
+ * @category layers
+ * @since 4.0.0
+ */
+export declare const layer: (options?: Options) => Layer.Layer<DatagramSocket.DatagramSocket>;
+//# sourceMappingURL=BunDatagramSocket.d.ts.map

package/dist/BunDatagramSocket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BunDatagramSocket.d.ts","sourceRoot":"","sources":["../src/BunDatagramSocket.ts"],"names":[],"mappings":"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"}