.opencode/node_modules/effect/dist/unstable/socket/Socket.d.ts

/**
 * Models bidirectional socket connections in Effect.
 *
 * The `Socket` service runs handlers for binary, string, or raw frames and
 * provides a scoped writer for outgoing bytes, text, or close events. This
 * module also includes socket errors, channel adapters, WebSocket layers, and
 * transform-stream-backed sockets.
 *
 * @since 4.0.0
 */
import type { NonEmptyReadonlyArray } from "../../Array.ts";
import type * as Cause from "../../Cause.ts";
import * as Channel from "../../Channel.ts";
import * as Context from "../../Context.ts";
import type * as Duration from "../../Duration.ts";
import * as Effect from "../../Effect.ts";
import * as Layer from "../../Layer.ts";
import * as Result from "../../Result.ts";
import * as Schema from "../../Schema.ts";
import * as Scope from "../../Scope.ts";
/**
 * Runtime type identifier attached to `Socket` services.
 *
 * @category type IDs
 * @since 4.0.0
 */
export declare const TypeId = "~effect/socket/Socket";
/**
 * Returns `true` when a value is a `Socket`.
 *
 * @category guards
 * @since 4.0.0
 */
export declare const isSocket: (u: unknown) => u is Socket;
/**
 * Service tag for bidirectional socket transports.
 *
 * **When to use**
 *
 * Use to access or provide the socket implementation used by programs that
 * read and write frames through the Effect environment.
 *
 * @category services
 * @since 4.0.0
 */
export declare const Socket: Context.Service<Socket, Socket>;
/**
 * Effect-based socket abstraction for running string or binary read handlers
 * and obtaining a scoped writer for outgoing frames and close events.
 *
 * @category models
 * @since 4.0.0
 */
export interface Socket {
    readonly [TypeId]: typeof TypeId;
    readonly run: <_, E = never, R = never>(handler: (_: Uint8Array) => Effect.Effect<_, E, R> | void, options?: {
        readonly onOpen?: Effect.Effect<void> | undefined;
    }) => Effect.Effect<void, SocketError | E, R>;
    readonly runString: <_, E = never, R = never>(handler: (_: string) => Effect.Effect<_, E, R> | void, options?: {
        readonly onOpen?: Effect.Effect<void> | undefined;
    }) => Effect.Effect<void, SocketError | E, R>;
    readonly runRaw: <_, E = never, R = never>(handler: (_: string | Uint8Array) => Effect.Effect<_, E, R> | void, options?: {
        readonly onOpen?: Effect.Effect<void> | undefined;
    }) => Effect.Effect<void, SocketError | E, R>;
    readonly writer: Effect.Effect<(chunk: Uint8Array | string | CloseEvent) => Effect.Effect<void, SocketError>, never, Scope.Scope>;
}
/**
 * Constructs a `Socket` from a raw read loop and scoped writer, deriving binary
 * and string read loops when they are not provided.
 *
 * @category constructors
 * @since 4.0.0
 */
export declare const make: (options: {
    readonly runRaw: <_, E, R>(handler: (_: string | Uint8Array) => Effect.Effect<_, E, R> | void, options?: {
        readonly onOpen?: Effect.Effect<void> | undefined;
    }) => Effect.Effect<void, SocketError | E, R>;
    readonly run?: <_, E, R>(handler: (_: Uint8Array) => Effect.Effect<_, E, R> | void, options?: {
        readonly onOpen?: Effect.Effect<void> | undefined;
    }) => Effect.Effect<void, SocketError | E, R>;
    readonly runString?: <_, E, R>(handler: (_: string) => Effect.Effect<_, E, R> | void, options?: {
        readonly onOpen?: Effect.Effect<void> | undefined;
    }) => Effect.Effect<void, SocketError | E, R>;
    readonly writer: Effect.Effect<(chunk: Uint8Array | string | CloseEvent) => Effect.Effect<void, SocketError>, never, Scope.Scope>;
}) => Socket;
declare const CloseEventTypeId = "~effect/socket/Socket/CloseEvent";
/**
 * Represents a socket close event value carrying a close code and optional
 * reason.
 *
 * @category models
 * @since 4.0.0
 */
export declare class CloseEvent {
    /**
     * Marks this value as a socket close event for runtime guards.
     *
     * @since 4.0.0
     */
    readonly [CloseEventTypeId]: typeof CloseEventTypeId;
    readonly code: number;
    readonly reason?: string | undefined;
    constructor(code?: number, reason?: string);
    /**
     * Formats the close code and optional reason for display.
     *
     * @since 4.0.0
     */
    toString(): string;
}
/**
 * Returns `true` when a value is a `CloseEvent`.
 *
 * @category refinements
 * @since 4.0.0
 */
export declare const isCloseEvent: (u: unknown) => u is CloseEvent;
/**
 * Type-level identifier used to mark `SocketError` values.
 *
 * @category type IDs
 * @since 4.0.0
 */
export type SocketErrorTypeId = "~effect/socket/Socket/SocketError";
/**
 * Runtime type identifier attached to `SocketError` values.
 *
 * @category type IDs
 * @since 4.0.0
 */
export declare const SocketErrorTypeId: SocketErrorTypeId;
/**
 * Returns `true` when a value is a `SocketError`.
 *
 * @category refinements
 * @since 4.0.0
 */
export declare const isSocketError: (u: unknown) => u is SocketError;
declare const SocketReadError_base: Schema.Class<SocketReadError, Schema.Struct<{
    readonly _tag: Schema.tag<"SocketReadError">;
    readonly cause: Schema.Defect;
}>, Cause.YieldableError>;
/**
 * Typed error for failures that occur while reading from a socket.
 *
 * @category errors
 * @since 4.0.0
 */
export declare class SocketReadError extends SocketReadError_base {
    /**
     * Default message used for socket read failures.
     *
     * @since 4.0.0
     */
    readonly message = "An error occurred during Read";
}
declare const SocketWriteError_base: Schema.Class<SocketWriteError, Schema.Struct<{
    readonly _tag: Schema.tag<"SocketWriteError">;
    readonly cause: Schema.Defect;
}>, Cause.YieldableError>;
/**
 * Typed error for failures that occur while writing to a socket.
 *
 * @category errors
 * @since 4.0.0
 */
export declare class SocketWriteError extends SocketWriteError_base {
    /**
     * Default message used for socket write failures.
     *
     * @since 4.0.0
     */
    readonly message = "An error occurred during Write";
}
declare const SocketOpenError_base: Schema.Class<SocketOpenError, Schema.Struct<{
    readonly _tag: Schema.tag<"SocketOpenError">;
    readonly kind: Schema.Literals<readonly ["Unknown", "Timeout"]>;
    readonly cause: Schema.Defect;
}>, Cause.YieldableError>;
/**
 * Typed error for failures that occur while opening a socket, including
 * unknown open failures and open timeouts.
 *
 * @category errors
 * @since 4.0.0
 */
export declare class SocketOpenError extends SocketOpenError_base {
    /**
     * Formats timeout and unknown open failures for display.
     *
     * @since 4.0.0
     */
    get message(): "timeout waiting for \"open\"" | "An error occurred during Open";
}
declare const SocketCloseError_base: Schema.Class<SocketCloseError, Schema.Struct<{
    readonly _tag: Schema.tag<"SocketCloseError">;
    readonly code: Schema.Number;
    readonly closeReason: Schema.optional<Schema.String>;
}>, Cause.YieldableError>;
/**
 * Typed error for a socket close event, carrying the close code and optional
 * close reason.
 *
 * @category errors
 * @since 4.0.0
 */
export declare class SocketCloseError extends SocketCloseError_base {
    /**
     * Separates clean socket close errors from errors that should remain failures.
     *
     * @since 4.0.0
     */
    static filterClean(isClean: (code: number) => boolean): <E>(u: E) => Result.Result<SocketCloseError, E>;
    get message(): string;
}
/**
 * Schema for all socket-specific error reasons.
 *
 * @category errors
 * @since 4.0.0
 */
export declare const SocketErrorReason: Schema.Union<readonly [typeof SocketReadError, typeof SocketWriteError, typeof SocketOpenError, typeof SocketCloseError]>;
/**
 * Union of socket-specific read, write, open, and close error reasons.
 *
 * @category errors
 * @since 4.0.0
 */
export type SocketErrorReason = SocketReadError | SocketWriteError | SocketOpenError | SocketCloseError;
declare const SocketError_base: Schema.Class<SocketError, Schema.TaggedStruct<"SocketError", {
    readonly _tag: Schema.tag<"SocketError">;
    readonly reason: Schema.Union<readonly [typeof SocketReadError, typeof SocketWriteError, typeof SocketOpenError, typeof SocketCloseError]>;
}>, Cause.YieldableError>;
/**
 * Tagged error that wraps socket read, write, open, and close failures while
 * preserving the underlying reason.
 *
 * @category errors
 * @since 4.0.0
 */
export declare class SocketError extends SocketError_base {
    constructor(props: {
        readonly reason: SocketReadError | SocketWriteError | SocketOpenError | SocketCloseError;
    });
    /**
     * Marks this value as a socket error wrapper for runtime guards.
     *
     * @since 4.0.0
     */
    readonly [SocketErrorTypeId]: SocketErrorTypeId;
    /**
     * Returns `true` when the value is a `SocketError`.
     *
     * @since 4.0.0
     */
    static is(u: unknown): u is SocketError;
    readonly message: string;
}
/**
 * Converts a `Socket` into a bidirectional `Channel`, mapping incoming string
 * or binary frames and writing outgoing frame batches to the socket.
 *
 * @category combinators
 * @since 4.0.0
 */
export declare const toChannelMap: <IE, A>(self: Socket, f: (data: Uint8Array | string) => A) => Channel.Channel<NonEmptyReadonlyArray<A>, SocketError | IE, void, NonEmptyReadonlyArray<Uint8Array | string | CloseEvent>, IE>;
/**
 * Converts a `Socket` into a binary `Channel`, encoding incoming string frames
 * as UTF-8 bytes.
 *
 * @category combinators
 * @since 4.0.0
 */
export declare const toChannel: <IE>(self: Socket) => Channel.Channel<NonEmptyReadonlyArray<Uint8Array>, SocketError | IE, void, NonEmptyReadonlyArray<Uint8Array | string | CloseEvent>, IE>;
/**
 * Converts a `Socket` into a string `Channel`, decoding binary frames with the
 * optional text encoding.
 *
 * @category combinators
 * @since 4.0.0
 */
export declare const toChannelString: {
    /**
     * Converts a `Socket` into a string `Channel`, decoding binary frames with the
     * optional text encoding.
     *
     * @category combinators
     * @since 4.0.0
     */
    (encoding?: string | undefined): <IE>(self: Socket) => Channel.Channel<NonEmptyReadonlyArray<string>, SocketError | IE, void, NonEmptyReadonlyArray<Uint8Array | string | CloseEvent>, IE>;
    /**
     * Converts a `Socket` into a string `Channel`, decoding binary frames with the
     * optional text encoding.
     *
     * @category combinators
     * @since 4.0.0
     */
    <IE>(self: Socket, encoding?: string | undefined): Channel.Channel<NonEmptyReadonlyArray<string>, SocketError | IE, void, NonEmptyReadonlyArray<Uint8Array | string | CloseEvent>, IE>;
};
/**
 * Creates a `Socket` to binary `Channel` adapter with a fixed upstream error
 * type.
 *
 * @category combinators
 * @since 4.0.0
 */
export declare const toChannelWith: <IE = never>() => (self: Socket) => Channel.Channel<NonEmptyReadonlyArray<Uint8Array>, SocketError | IE, void, NonEmptyReadonlyArray<Uint8Array | string | CloseEvent>, IE>;
/**
 * Creates a binary socket `Channel` from the `Socket` service in the
 * environment.
 *
 * @category constructors
 * @since 4.0.0
 */
export declare const makeChannel: <IE = never>() => Channel.Channel<NonEmptyReadonlyArray<Uint8Array>, SocketError | IE, void, NonEmptyReadonlyArray<Uint8Array | string | CloseEvent>, IE, unknown, Socket>;
/**
 * Default close-code classifier that treats every socket close code as an
 * error.
 *
 * @category predicates
 * @since 4.0.0
 */
export declare const defaultCloseCodeIsError: (_code: number) => boolean;
declare const WebSocket_base: Context.ServiceClass<WebSocket, "~effect/socket/Socket/WebSocket", globalThis.WebSocket>;
/**
 * Context service for the active `WebSocket` instance available while a
 * WebSocket-backed socket run is handling events.
 *
 * @category services
 * @since 4.0.0
 */
export declare class WebSocket extends WebSocket_base {
}
declare const WebSocketConstructor_base: Context.ServiceClass<WebSocketConstructor, "@effect/platform/Socket/WebSocketConstructor", (url: string, protocols?: string | Array<string> | undefined) => globalThis.WebSocket>;
/**
 * Context service for constructing `WebSocket` instances from a URL and
 * optional protocols.
 *
 * @category services
 * @since 4.0.0
 */
export declare class WebSocketConstructor extends WebSocketConstructor_base {
}
/**
 * Layer that provides `WebSocketConstructor` using `globalThis.WebSocket`.
 *
 * @category layers
 * @since 4.0.0
 */
export declare const layerWebSocketConstructorGlobal: Layer.Layer<WebSocketConstructor>;
/**
 * Creates a `Socket` backed by a `WebSocketConstructor`, acquiring the
 * WebSocket for each run and using the close-code classifier to decide which
 * closes fail the run.
 *
 * @category constructors
 * @since 4.0.0
 */
export declare const makeWebSocket: (url: string | Effect.Effect<string>, options?: {
    readonly closeCodeIsError?: ((code: number) => boolean) | undefined;
    readonly openTimeout?: Duration.Input | undefined;
    readonly protocols?: string | Array<string> | undefined;
}) => Effect.Effect<Socket, never, WebSocketConstructor>;
/**
 * Builds a `Socket` from a scoped WebSocket acquisition effect, waiting for the
 * socket to open, dispatching message handlers in fibers, and translating
 * open, read, and close events into `SocketError` values.
 *
 * @category constructors
 * @since 4.0.0
 */
export declare const fromWebSocket: <RO>(acquire: Effect.Effect<globalThis.WebSocket, SocketError, RO>, options?: {
    readonly closeCodeIsError?: ((code: number) => boolean) | undefined;
    readonly openTimeout?: Duration.Input | undefined;
} | undefined) => Effect.Effect<Socket, never, Exclude<RO, Scope.Scope>>;
/**
 * Creates a binary `Channel` backed by a WebSocket URL, requiring a
 * `WebSocketConstructor` service.
 *
 * @category constructors
 * @since 4.0.0
 */
export declare const makeWebSocketChannel: <IE = never>(url: string, options?: {
    readonly closeCodeIsError?: (code: number) => boolean;
}) => Channel.Channel<NonEmptyReadonlyArray<Uint8Array>, SocketError | IE, void, NonEmptyReadonlyArray<Uint8Array | string | CloseEvent>, IE, unknown, WebSocketConstructor>;
/**
 * Layer that provides a `Socket` service backed by a WebSocket URL or URL
 * effect.
 *
 * @category layers
 * @since 4.0.0
 */
export declare const layerWebSocket: (url: string | Effect.Effect<string>, options?: {
    readonly closeCodeIsError?: ((code: number) => boolean) | undefined;
    readonly openTimeout?: Duration.Input | undefined;
    readonly protocols?: string | Array<string> | undefined;
} | undefined) => Layer.Layer<Socket, never, WebSocketConstructor>;
/**
 * Context reference for socket send queue capacity, defaulting to `16`.
 *
 * @category fiber refs
 * @since 4.0.0
 */
export declare const SendQueueCapacity: Context.Reference<number>;
/**
 * Readable and writable stream pair used to adapt transform-style streams into
 * a `Socket`.
 *
 * @category models
 * @since 4.0.0
 */
export interface InputTransformStream {
    readonly readable: ReadableStream<Uint8Array> | ReadableStream<string> | ReadableStream<Uint8Array | string>;
    readonly writable: WritableStream<Uint8Array>;
}
/**
 * Builds a `Socket` from a scoped `InputTransformStream`, reading incoming
 * chunks through socket handlers and writing outgoing chunks to the writable
 * stream, encoding strings as UTF-8 and using close-code classification for
 * `CloseEvent` values.
 *
 * @category constructors
 * @since 4.0.0
 */
export declare const fromTransformStream: <R>(acquire: Effect.Effect<InputTransformStream, SocketError, R>, options?: {
    readonly closeCodeIsError?: (code: number) => boolean;
}) => Effect.Effect<Socket, never, Exclude<R, Scope.Scope>>;
export {};
//# sourceMappingURL=Socket.d.ts.map