@effect/sql-pg 4.0.0-rc.110 → 4.0.0-rc.112

package/dist/PgProtocol.d.ts

@@ -0,0 +1,750 @@
+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;
+    /**
+     * Feeds the next chunk of socket bytes and returns every message that is now
+     * complete. A partial trailing message is retained until the bytes that
+     * finish it arrive. A thrown parse or field-reader error is terminal and the
+     * parser cannot be reused afterward; any messages decoded earlier in the
+     * failing push are discarded.
+     *
+     * Byte fields on the returned messages - `DataRow` values, `CopyData` and
+     * `Unknown` payloads - are views into an internal buffer that the parser
+     * never rewrites, so they stay valid for as long as they are held. They are
+     * meant to be consumed before the next `push`: holding one keeps its whole
+     * buffer alive, so copy it if it has to outlive the row.
+     */
+    readonly push: (chunk: Uint8Array) => ReadonlyArray<BackendMessage<A>>;
+}
+/**
+ * Creates a `Parser`.
+ *
+ * Special pre-startup replies have no type byte and are not handled here; use
+ * `decodeSslResponse` for those.
+ *
+ * @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, creating a portal.
+ *
+ * Parameters and results always use the binary format code.
+ *
+ * @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;
+}> {
+}
+export declare const encodeParse: (options: Omit<Parse, "_tag">) => Result.Result<Uint8Array, EncodeError>;
+export declare const encodeBind: (options: Omit<Bind, "_tag">) => Result.Result<Uint8Array, EncodeError>;
+/**
+ * Where a value writes its wire bytes. `Bind` frames a parameter by leaving
+ * room for its length, letting the sink fill in the body, and backfilling the
+ * length from what was written, so a value never needs an array of its own.
+ *
+ * `PgTypes.writeParameter` is the implementation for 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;
+}
+export declare const makeBindEncoder: <A, E = never>(writeParameter: (sink: ValueSink, value: A) => Result.Result<void, E>) => (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 out of the parser's buffer, for a parser given a
+ * `readField`. `size` is -1 for SQL NULL, and `column` is the field's position
+ * in the row.
+ *
+ * The bytes are the parser's buffer rather than a view of the field, so they
+ * are only the field's for `offset` to `offset + size`, and reading outside
+ * that reads the rest of the stream. `PgTypes.makeFieldReader` is the
+ * implementation for OID-typed columns.
+ *
+ * A reader runs inside the stateful parser. If it throws, that failure is
+ * terminal just like a `ParseError`.
+ *
+ * @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