@effect/sql-pg 4.0.0-rc.111 → 4.0.0-rc.113

package/dist/PgProtocol.d.ts

@@ -0,0 +1,783 @@
+import * as Result from "effect/Result";
+/**
+ * Default `maxMessageSize` for `makeParser`: 16 MiB.
+ *
+ * @category constants
+ * @since 4.0.0
+ */
+export declare const defaultMaxMessageSize: number;
+/**
+ * An incremental decoder for the post-startup backend message stream.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface Parser<A = Uint8Array | null> {
+    /**
+     * Reads each `DataRow` field, for a parser built with one. A result's
+     * columns are only known from its `RowDescription`, which arrives on the
+     * same stream, so this is settable: replace it when the columns change.
+     */
+    readField: FieldReader<A> | undefined;
+    /**
+     * Decodes a chunk and returns every complete message. A partial message is
+     * retained for the next call. Parse and field-reader errors are terminal and
+     * discard messages decoded earlier in the same call.
+     *
+     * **Details**
+     *
+     * `DataRow`, `CopyData`, and `Unknown` payloads are views into an internal
+     * buffer. Copy a payload that must outlive the current row, otherwise its
+     * entire buffer remains in memory.
+     */
+    readonly push: (chunk: Uint8Array) => ReadonlyArray<BackendMessage<A>>;
+    /**
+     * Decodes a chunk and passes each complete message to `onMessage`
+     * immediately. This lets a `RowDescription` update `readField` before a
+     * `DataRow` later in the same chunk is decoded. The failure and
+     * buffer-lifetime rules match `push`, except messages
+     * delivered before a failure are not discarded.
+     */
+    readonly pushEach: (chunk: Uint8Array, onMessage: (message: BackendMessage<A>) => void) => void;
+}
+/**
+ * Creates a `Parser`.
+ *
+ * **Details**
+ *
+ * Special pre-startup replies have no type byte. Use `decodeSslResponse` for
+ * those replies.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const makeParser: <A = Uint8Array | null>(options?: {
+    readonly maxMessageSize?: number | undefined;
+    /**
+     * Reads each `DataRow` field as it is parsed, so a client that decodes its
+     * columns never needs a view per column. Without one every field is handed
+     * out as a view, which is the default.
+     */
+    readonly readField?: FieldReader<A> | undefined;
+}) => Parser<A>;
+/**
+ * Prepares a named or unnamed statement.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface Parse {
+    readonly _tag: "Parse";
+    readonly name: string;
+    readonly query: string;
+    readonly parameterTypes: ReadonlyArray<number>;
+}
+/**
+ * Binds parameter values to a prepared statement and creates a portal.
+ * Parameters and results use the binary format.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface Bind {
+    readonly _tag: "Bind";
+    readonly portal: string;
+    readonly statement: string;
+    readonly parameters: ReadonlyArray<Uint8Array | null>;
+}
+/**
+ * Runs a portal, optionally limiting the number of rows returned.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface Execute {
+    readonly _tag: "Execute";
+    readonly portal: string;
+    readonly maxRows: number;
+}
+/**
+ * Which kind of object a `Describe` or `Close` message names.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export type DescribeTarget = "statement" | "portal";
+/**
+ * Asks for the parameter and row shape of a statement or portal.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface Describe {
+    readonly _tag: "Describe";
+    readonly target: DescribeTarget;
+    readonly name: string;
+}
+/**
+ * Drops a prepared statement or portal.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface Close {
+    readonly _tag: "Close";
+    readonly target: DescribeTarget;
+    readonly name: string;
+}
+/**
+ * Closes the current transaction block and requests a `ReadyForQuery`.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface Sync {
+    readonly _tag: "Sync";
+}
+/**
+ * Asks the backend to deliver buffered output without ending the transaction.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface Flush {
+    readonly _tag: "Flush";
+}
+/**
+ * Ends the session.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface Terminate {
+    readonly _tag: "Terminate";
+}
+/**
+ * Answers a cleartext or MD5 password request.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface PasswordMessage {
+    readonly _tag: "PasswordMessage";
+    readonly password: string;
+}
+/**
+ * Selects a SASL mechanism and carries its opaque initial response.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface SASLInitialResponse {
+    readonly _tag: "SASLInitialResponse";
+    readonly mechanism: string;
+    readonly initialResponse: Uint8Array | null;
+}
+/**
+ * Carries an opaque SASL continuation payload.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface SASLResponse {
+    readonly _tag: "SASLResponse";
+    readonly data: Uint8Array;
+}
+/**
+ * Any message the client sends after startup.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export type FrontendMessage = Parse | Bind | Execute | Describe | Close | Sync | Flush | Terminate | PasswordMessage | SASLInitialResponse | SASLResponse;
+declare const ParseError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "PgProtocolParseError";
+} & Readonly<A>;
+/**
+ * Error produced when bytes cannot be interpreted as a protocol message.
+ *
+ * @category errors
+ * @since 4.0.0
+ */
+export declare class ParseError extends ParseError_base<{
+    readonly message: string;
+}> {
+}
+declare const EncodeError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "PgProtocolEncodeError";
+} & Readonly<A>;
+/**
+ * Error returned when a frontend message cannot be encoded.
+ *
+ * @category errors
+ * @since 4.0.0
+ */
+export declare class EncodeError extends EncodeError_base<{
+    readonly message: string;
+}> {
+}
+/**
+ * Encodes a `Parse` message.
+ *
+ * @category encoding
+ * @since 4.0.0
+ */
+export declare const encodeParse: (options: Omit<Parse, "_tag">) => Result.Result<Uint8Array, EncodeError>;
+/**
+ * Encodes a `Bind` message.
+ *
+ * @category encoding
+ * @since 4.0.0
+ */
+export declare const encodeBind: (options: Omit<Bind, "_tag">) => Result.Result<Uint8Array, EncodeError>;
+/**
+ * A sink for writing parameter bytes into a `Bind` frame. The frame reserves
+ * and backfills each parameter length. `PgTypes.writeParameter` supports
+ * OID-typed values.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface ValueSink {
+    readonly uint8: (value: number) => void;
+    readonly int16: (value: number) => void;
+    readonly int32: (value: number) => void;
+    readonly float32: (value: number) => void;
+    readonly float64: (value: number) => void;
+    readonly bigInt64: (value: bigint) => void;
+    readonly raw: (value: Uint8Array) => void;
+    readonly utf8: (value: string) => void;
+    /** Writes SQL NULL. The value must write nothing else. */
+    readonly sqlNull: () => void;
+    /**
+     * Leaves room for an int32 length and returns a token for `endLength`, so a
+     * value that contains other values can frame them without knowing their
+     * sizes up front. Tokens nest, and must be closed in the order they were
+     * opened.
+     */
+    readonly beginLength: () => number;
+    /** Backfills the length of everything written since its `beginLength`. */
+    readonly endLength: (token: number) => void;
+}
+/**
+ * Creates a `Bind` encoder that writes parameters directly into the frame.
+ *
+ * **Details**
+ *
+ * `textFormat` identifies parameters encoded as text. All other parameters
+ * use the binary format.
+ *
+ * **Example** (Encoding a `Bind` message)
+ *
+ * ```ts
+ * import { PgProtocol, PgTypes } from "@effect/sql-pg"
+ *
+ * const encodeBind = PgProtocol.makeBindEncoder(PgTypes.writeParameter, PgTypes.isTextFormat)
+ * const frame = encodeBind({ portal: "", statement: "s1", parameters: [PgTypes.int4(1)] })
+ * ```
+ *
+ * @category encoding
+ * @since 4.0.0
+ */
+export declare const makeBindEncoder: <A, E = never>(writeParameter: (sink: ValueSink, value: A) => Result.Result<void, E>, textFormat?: (value: A) => boolean) => (options: {
+    readonly portal: string;
+    readonly statement: string;
+    readonly parameters: ReadonlyArray<A>;
+}) => Result.Result<Uint8Array, EncodeError | E>;
+/**
+ * Encodes an `Execute` message.
+ *
+ * @category encoding
+ * @since 4.0.0
+ */
+export declare const encodeExecute: (options: Omit<Execute, "_tag">) => Uint8Array;
+/**
+ * Encodes a `Describe` message.
+ *
+ * @category encoding
+ * @since 4.0.0
+ */
+export declare const encodeDescribe: (options: Omit<Describe, "_tag">) => Uint8Array;
+/**
+ * Encodes a `Close` message.
+ *
+ * @category encoding
+ * @since 4.0.0
+ */
+export declare const encodeClose: (options: Omit<Close, "_tag">) => Uint8Array;
+/**
+ * Encodes a `Sync` message.
+ *
+ * @category encoding
+ * @since 4.0.0
+ */
+export declare const encodeSync: () => Uint8Array;
+/**
+ * Encodes a `Flush` message.
+ *
+ * @category encoding
+ * @since 4.0.0
+ */
+export declare const encodeFlush: () => Uint8Array;
+/**
+ * Encodes a `Terminate` message.
+ *
+ * @category encoding
+ * @since 4.0.0
+ */
+export declare const encodeTerminate: () => Uint8Array;
+/**
+ * Encodes a `PasswordMessage`. The password is sent verbatim, so MD5 hashing
+ * belongs to the caller - see `PgAuth.md5Password`.
+ *
+ * @category encoding
+ * @since 4.0.0
+ */
+export declare const encodePasswordMessage: (options: Omit<PasswordMessage, "_tag">) => Uint8Array;
+/**
+ * Encodes a `SASLInitialResponse` message.
+ *
+ * @category encoding
+ * @since 4.0.0
+ */
+export declare const encodeSASLInitialResponse: (options: Omit<SASLInitialResponse, "_tag">) => Uint8Array;
+/**
+ * Encodes a `SASLResponse` message.
+ *
+ * @category encoding
+ * @since 4.0.0
+ */
+export declare const encodeSASLResponse: (options: Omit<SASLResponse, "_tag">) => Uint8Array;
+/**
+ * Encodes any frontend message.
+ *
+ * @category encoding
+ * @since 4.0.0
+ */
+export declare const encode: (message: FrontendMessage) => Result.Result<Uint8Array, EncodeError>;
+/**
+ * Startup parameters. `user` is required; any other run-time parameter the
+ * server accepts may be passed alongside it.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface StartupParameters {
+    readonly [key: string]: string | undefined;
+    readonly user: string;
+    readonly database?: string | undefined;
+    readonly application_name?: string | undefined;
+}
+/**
+ * Encodes an `SSLRequest`. It has no type byte and is only valid before
+ * startup.
+ *
+ * @category encoding
+ * @since 4.0.0
+ */
+export declare const encodeSslRequest: () => Uint8Array;
+/**
+ * Decodes the single byte the server sends in reply to an `SSLRequest`. `"S"`
+ * means the server will speak TLS, `"N"` means it will not.
+ *
+ * @category decoding
+ * @since 4.0.0
+ */
+export declare const decodeSslResponse: (byte: number) => Result.Result<"S" | "N", ParseError>;
+/**
+ * Encodes a `StartupMessage` for protocol 3.0. It has no type byte.
+ * `client_encoding` defaults to `UTF8` because this codec always writes UTF-8.
+ *
+ * @category encoding
+ * @since 4.0.0
+ */
+export declare const encodeStartupMessage: (parameters: StartupParameters) => Uint8Array;
+/**
+ * Encodes a `CancelRequest`. It has no type byte and is sent on a separate
+ * connection, using the `pid` and `secret` from `BackendKeyData`.
+ *
+ * @category encoding
+ * @since 4.0.0
+ */
+export declare const encodeCancelRequest: (options: {
+    readonly pid: number;
+    readonly secret: number;
+}) => Uint8Array;
+/**
+ * Authentication succeeded.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface AuthenticationOk {
+    readonly _tag: "AuthenticationOk";
+}
+/**
+ * The server wants the password in the clear.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface AuthenticationCleartextPassword {
+    readonly _tag: "AuthenticationCleartextPassword";
+}
+/**
+ * The server wants an MD5-hashed password, salted with these four bytes.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface AuthenticationMD5Password {
+    readonly _tag: "AuthenticationMD5Password";
+    readonly salt: Uint8Array;
+}
+/**
+ * The server offers these SASL mechanisms.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface AuthenticationSASL {
+    readonly _tag: "AuthenticationSASL";
+    readonly mechanisms: ReadonlyArray<string>;
+}
+/**
+ * An opaque SASL challenge.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface AuthenticationSASLContinue {
+    readonly _tag: "AuthenticationSASLContinue";
+    readonly data: Uint8Array;
+}
+/**
+ * The opaque final SASL payload, carrying the server signature.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface AuthenticationSASLFinal {
+    readonly _tag: "AuthenticationSASLFinal";
+    readonly data: Uint8Array;
+}
+/**
+ * An authentication request this codec does not model, such as GSSAPI or
+ * SSPI. The `method` is the raw sub-type integer.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface AuthenticationUnsupported {
+    readonly _tag: "AuthenticationUnsupported";
+    readonly method: number;
+    readonly payload: Uint8Array;
+}
+/**
+ * Reports a run-time parameter value, at startup or whenever it changes.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface ParameterStatus {
+    readonly _tag: "ParameterStatus";
+    readonly name: string;
+    readonly value: string;
+}
+/**
+ * The identity a `CancelRequest` needs.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface BackendKeyData {
+    readonly _tag: "BackendKeyData";
+    readonly pid: number;
+    readonly secret: number;
+}
+/**
+ * Transaction status: idle, in a transaction block, or in a failed
+ * transaction block.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export type TransactionStatus = "I" | "T" | "E";
+/**
+ * The backend is ready for a new query cycle.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface ReadyForQuery {
+    readonly _tag: "ReadyForQuery";
+    readonly status: TransactionStatus;
+}
+/**
+ * One column of a `RowDescription`.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface FieldDescription {
+    readonly name: string;
+    readonly tableOid: number;
+    readonly columnAttributeNumber: number;
+    readonly dataTypeOid: number;
+    readonly dataTypeSize: number;
+    readonly typeModifier: number;
+    readonly format: number;
+}
+/**
+ * Describes the columns a portal will return.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface RowDescription {
+    readonly _tag: "RowDescription";
+    readonly fields: ReadonlyArray<FieldDescription>;
+}
+/**
+ * One result row. Values stay raw bytes; `null` is SQL NULL. Decoding them
+ * requires the OIDs from the matching `RowDescription`.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface DataRow<out A = Uint8Array | null> {
+    readonly _tag: "DataRow";
+    readonly values: ReadonlyArray<A>;
+}
+/**
+ * Reads one `DataRow` field from the parser buffer.
+ *
+ * **Details**
+ *
+ * `size` is `-1` for SQL `NULL`, and `column` is the field index. Only bytes
+ * from `offset` through `offset + size` belong to the field. A thrown error
+ * permanently fails the parser.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export type FieldReader<A> = (bytes: Uint8Array, offset: number, size: number, column: number) => A;
+/**
+ * A command finished, reporting its tag such as `SELECT 3`.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface CommandComplete {
+    readonly _tag: "CommandComplete";
+    readonly commandTag: string;
+}
+/**
+ * The query string was empty.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface EmptyQueryResponse {
+    readonly _tag: "EmptyQueryResponse";
+}
+/**
+ * The statement or portal returns no rows.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface NoData {
+    readonly _tag: "NoData";
+}
+/**
+ * A `Parse` succeeded.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface ParseComplete {
+    readonly _tag: "ParseComplete";
+}
+/**
+ * A `Bind` succeeded.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface BindComplete {
+    readonly _tag: "BindComplete";
+}
+/**
+ * A `Close` succeeded.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface CloseComplete {
+    readonly _tag: "CloseComplete";
+}
+/**
+ * An `Execute` stopped at its row limit; the portal can be executed again.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface PortalSuspended {
+    readonly _tag: "PortalSuspended";
+}
+/**
+ * The parameter OIDs of a described statement.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface ParameterDescription {
+    readonly _tag: "ParameterDescription";
+    readonly parameterTypes: ReadonlyArray<number>;
+}
+/**
+ * The fields of an `ErrorResponse` or `NoticeResponse`. Unrecognised field
+ * codes are kept under their raw single-character key.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface ErrorFields {
+    readonly [key: string]: string | undefined;
+    readonly severity?: string | undefined;
+    readonly severityUnlocalized?: string | undefined;
+    readonly code?: string | undefined;
+    readonly message?: string | undefined;
+    readonly detail?: string | undefined;
+    readonly hint?: string | undefined;
+    readonly position?: string | undefined;
+    readonly internalPosition?: string | undefined;
+    readonly internalQuery?: string | undefined;
+    readonly where?: string | undefined;
+    readonly schema?: string | undefined;
+    readonly table?: string | undefined;
+    readonly column?: string | undefined;
+    readonly dataType?: string | undefined;
+    readonly constraint?: string | undefined;
+    readonly file?: string | undefined;
+    readonly line?: string | undefined;
+    readonly routine?: string | undefined;
+}
+/**
+ * An error. `code` is the SQLSTATE.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface ErrorResponse {
+    readonly _tag: "ErrorResponse";
+    readonly fields: ErrorFields;
+}
+/**
+ * A warning or notice. Same field set as `ErrorResponse`.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface NoticeResponse {
+    readonly _tag: "NoticeResponse";
+    readonly fields: ErrorFields;
+}
+/**
+ * A `LISTEN`/`NOTIFY` message.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface NotificationResponse {
+    readonly _tag: "NotificationResponse";
+    readonly pid: number;
+    readonly channel: string;
+    readonly payload: string;
+}
+/**
+ * The server speaks an older minor protocol version, or did not recognise
+ * some startup options.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface NegotiateProtocolVersion {
+    readonly _tag: "NegotiateProtocolVersion";
+    readonly minorVersion: number;
+    readonly unrecognizedOptions: ReadonlyArray<string>;
+}
+/**
+ * The server is ready to receive `COPY` data.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface CopyInResponse {
+    readonly _tag: "CopyInResponse";
+    readonly format: number;
+    readonly columnFormats: ReadonlyArray<number>;
+}
+/**
+ * The server is about to send `COPY` data.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface CopyOutResponse {
+    readonly _tag: "CopyOutResponse";
+    readonly format: number;
+    readonly columnFormats: ReadonlyArray<number>;
+}
+/**
+ * The connection entered bidirectional `COPY` mode, as used by replication.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface CopyBothResponse {
+    readonly _tag: "CopyBothResponse";
+    readonly format: number;
+    readonly columnFormats: ReadonlyArray<number>;
+}
+/**
+ * A chunk of `COPY` data.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface CopyData {
+    readonly _tag: "CopyData";
+    readonly data: Uint8Array;
+}
+/**
+ * The `COPY` stream ended.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface CopyDone {
+    readonly _tag: "CopyDone";
+}
+/**
+ * A message whose type byte this codec does not know. The payload excludes
+ * the type byte and the length prefix.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface Unknown {
+    readonly _tag: "Unknown";
+    readonly type: number;
+    readonly payload: Uint8Array;
+}
+/**
+ * Any message the server sends after startup.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export type BackendMessage<A = Uint8Array | null> = AuthenticationOk | AuthenticationCleartextPassword | AuthenticationMD5Password | AuthenticationSASL | AuthenticationSASLContinue | AuthenticationSASLFinal | AuthenticationUnsupported | ParameterStatus | BackendKeyData | ReadyForQuery | RowDescription | DataRow<A> | CommandComplete | EmptyQueryResponse | NoData | ParseComplete | BindComplete | CloseComplete | PortalSuspended | ParameterDescription | ErrorResponse | NoticeResponse | NotificationResponse | NegotiateProtocolVersion | CopyInResponse | CopyOutResponse | CopyBothResponse | CopyData | CopyDone | Unknown;
+export {};
+//# sourceMappingURL=PgProtocol.d.ts.map