@volter/world-core 3.0.69 → 3.0.71

package/dist/src/mysql/stream.d.ts

@@ -0,0 +1,113 @@
+import type { TwinStream } from '../twin-fetch.js';
+/** A column as the pack's engine describes it: MySQL's column type code (`MysqlType`) and flags. */
+export type MysqlColumn = {
+    name: string;
+    type: number;
+    flags?: number;
+    charset?: number;
+    length?: number;
+    decimals?: number;
+    table?: string;
+    orgTable?: string;
+    orgName?: string;
+    schema?: string;
+};
+/** A statement's outcome: rows (each value as MySQL's text protocol carries it, or null), or a count, or MySQL's error. */
+export type MysqlOutcome = {
+    columns: MysqlColumn[];
+    rows: (string | Uint8Array | null)[][];
+    warnings?: number;
+} | {
+    affectedRows: number;
+    insertId?: number | bigint;
+    warnings?: number;
+    info?: string;
+} | {
+    error: MysqlError;
+};
+export type MysqlError = {
+    errno: number;
+    sqlstate: string;
+    message: string;
+};
+export type MysqlStreamOptions<Session> = {
+    /** The handshake's server version: the one the pack's engine reports for `VERSION()`. */
+    version: string;
+    /** Admit `user` to `database` (null: none named) when `check` accepts what the pack stores for it: the password, or
+     *  MySQL's own stored form of it (`nativePasswordHash`, SHA1(SHA1(password)), as a server keeps it). */
+    connect(user: string, database: string | null, check: MysqlPasswordCheck): Promise<{
+        session: Session;
+    } | {
+        error: MysqlError;
+    }>;
+    /** Execute ONE statement (the kernel splits a script and binds parameters into the text) on the session. */
+    execute(session: Session, sql: string): Promise<MysqlOutcome>;
+    /** Whether the session holds an open transaction (SERVER_STATUS_IN_TRANS). */
+    inTransaction(session: Session): boolean;
+    /** Use another database on the session (COM_INIT_DB). */
+    useDatabase?(session: Session, database: string): Promise<MysqlError | null>;
+    /** The connection went away: roll back what it left open. */
+    close?(session: Session): void;
+};
+/** MySQL's column type codes. */
+export declare const MysqlType: {
+    readonly DECIMAL: 0;
+    readonly TINY: 1;
+    readonly SHORT: 2;
+    readonly LONG: 3;
+    readonly FLOAT: 4;
+    readonly DOUBLE: 5;
+    readonly NULL: 6;
+    readonly TIMESTAMP: 7;
+    readonly LONGLONG: 8;
+    readonly INT24: 9;
+    readonly DATE: 10;
+    readonly TIME: 11;
+    readonly DATETIME: 12;
+    readonly YEAR: 13;
+    readonly VARCHAR: 15;
+    readonly BIT: 16;
+    readonly JSON: 245;
+    readonly NEWDECIMAL: 246;
+    readonly ENUM: 247;
+    readonly SET: 248;
+    readonly TINY_BLOB: 249;
+    readonly MEDIUM_BLOB: 250;
+    readonly LONG_BLOB: 251;
+    readonly BLOB: 252;
+    readonly VAR_STRING: 253;
+    readonly STRING: 254;
+    readonly GEOMETRY: 255;
+};
+export declare const MysqlFlag: {
+    readonly NOT_NULL: 1;
+    readonly PRI_KEY: 2;
+    readonly UNIQUE_KEY: 4;
+    readonly MULTIPLE_KEY: 8;
+    readonly BLOB: 16;
+    readonly UNSIGNED: 32;
+    readonly BINARY: 128;
+    readonly AUTO_INCREMENT: 512;
+};
+/** Whether the client's mysql_native_password answer proves a password: from the password itself, or from MySQL's
+ *  stored form of it (hex SHA1(SHA1(password))), as a MySQL server checks it without holding the password. */
+export type MysqlPasswordCheck = {
+    password(password: string): boolean;
+    storedHash(hex: string): boolean;
+};
+/** MySQL's stored form of a password for mysql_native_password: SHA1(SHA1(password)), hex. A pack keeps it when the
+ *  password is made, beside whatever else it keeps, so the wire can admit the password without the pack holding it. */
+export declare function nativePasswordHash(password: string): string;
+/** mysql_native_password's token for `password` against `scramble`: SHA1(pw) XOR SHA1(scramble + SHA1(SHA1(pw))). */
+export declare function nativePasswordToken(password: string, scramble: Uint8Array): Uint8Array;
+/** A multi-statement script's statements, empty ones dropped. */
+export declare function splitStatements(sql: string): string[];
+export declare function countPlaceholders(sql: string): number;
+/** A bound parameter: an integer, a float, text, bytes (a BLOB parameter, or text that is not UTF-8), a date or time. */
+export type MysqlParam = null | bigint | number | string | Uint8Array | {
+    date: string;
+};
+/** `sql` with each `?` placeholder replaced by its parameter's literal. */
+export declare function bindParameters(sql: string, params: MysqlParam[]): string;
+/** A MySQL server as a TwinStream: the protocol here, the meaning in `options`. */
+export declare function createMysqlStream<Session>(options: MysqlStreamOptions<Session>): TwinStream;