hrana
Version:
A tiny (1034b) runtime-agnostic Hrana HTTP client
328 lines (327 loc) • 8.26 kB
text/typescript
/**
* The native Hrana types.
*/
export declare namespace Hrana {
type uint32 = number;
type uint64 = number;
type double = number;
/**
* The value structures that come from the Hrana server.
*/
export type Value = Value.Text | Value.Float | Value.Integer | Value.Blob | Value.Null;
/**
* The {@link Hrana.Value} sub-types.
*/
export namespace Value {
type Decoded = string | number | bigint | Uint8Array | null;
type Text = {
type: "text"
value: string
};
type Null = {
type: "null"
};
type Float = {
type: "float"
value: number
};
type Integer = {
type: "integer"
value: string
};
type Blob = {
type: "blob"
base64: string
};
}
/**
* An Hrana error response structure
*/
export type Error = {
message: string
code?: string | null
};
/**
* A Hrana statement structure.
*/
export type Stmt = {
sql: string
args?: Value[]
want_rows?: boolean
named_args?: Array<{
name: string
value: Value
}>
};
/**
* An Hrana `StreamRequest` structure.
*/
export type StreamRequest = CloseStreamReq | ExecuteStreamReq | BatchStreamReq;
/**
* An Hrana `StreamResponse` structure.
*/
export type StreamResponse = CloseStreamResp | ExecuteStreamResp | BatchStreamResp;
/**
* An Hrana `PipelineReqBody` structure.
* @see https://github.com/tursodatabase/libsql/blob/main/docs/HRANA_3_SPEC.md#execute-a-pipeline-of-requests-json
*/
export type PipelineReqBody = {
baton: string | null
requests: Array<StreamRequest>
};
/**
* An Hrana `PipelineRespBody` structure.
* @see https://github.com/tursodatabase/libsql/blob/main/docs/HRANA_3_SPEC.md#execute-a-pipeline-of-requests-json
*/
export type PipelineRespBody<T extends StreamResponse> = {
baton: string | null
base_url: string | null
results: Array<StreamResultOk<T> | StreamResultError>
};
/**
* An Hrana `CloseStreamReq` structure.
*
* The close request closes the stream.
*/
type CloseStreamReq = {
type: "close"
};
/**
* An Hrana `CloseStreamResp` structure.
*
* The response from closing a stream.
*/
type CloseStreamResp = {
type: "close"
};
/**
* An Hrana `StreamResultOk` structure.
*
* Successfully executed a pipeline of requests.
*/
type StreamResultOk<T extends StreamResponse> = {
type: "ok"
response: T
};
/**
* An Hrana `StreamResultError` structure.
*
* An error occurred while executing a pipeline of requests.
*/
type StreamResultError = {
type: "error"
error: Error
};
/**
* An Hrana `BatchStreamReq` structure.
*
* The request to execute a batch of statements.
*/
export type BatchStreamReq = {
type: "batch"
batch: Batch
};
/**
* An Hrana `BatchStreamResp` structure.
*
* The response from executing a batch of statements.
*/
export type BatchStreamResp = {
type: "batch"
result: BatchResult
};
/**
* An Hrana `ExecuteStreamReq` structure.
*
* The request to execute a statement.
*/
export type ExecuteStreamReq = {
type: "execute"
stmt: Stmt
};
/**
* An Hrana `ExecuteStreamResp` structure.
*
* The response from executing a statement.
*/
export type ExecuteStreamResp = {
type: "execute"
result: StmtResult
};
/**
* A Hrana statement result structure.
*/
export type StmtResult = {
cols: Array<Col>
rows: Array<Value[]>
affected_row_count: uint64
last_insert_rowid: string | null
rows_read: uint64
rows_written: uint64
query_duration_ms: double
};
/**
* Hrana Column information.
*/
export type Col = {
name: string | null
decltype: string | null
};
/**
* An Hrana batch structure.
*/
export type Batch = {
steps: Array<BatchStep>
};
/**
* An individual Hrana batch step structure.
*/
export type BatchStep = {
stmt: Stmt
condition?: BatchCond | null
};
/**
* An Hrana batch condition structure.
*/
export type BatchCond = {
type: "ok"
step: uint32
} | {
type: "error"
step: uint32
} | {
type: "not"
cond: BatchCond
} | {
type: "and"
conds: Array<BatchCond>
} | {
type: "or"
conds: Array<BatchCond>
} | {
type: "is_autocommit"
};
/**
* The result of executing a batch.
*/
export type BatchResult = {
step_results: Array<StmtResult | null>
step_errors: Array<Error | null>
};
export {};
}
/**
* The credentials and/or configuration for the Hrana client.
*/
export type Config = {
/**
* The database URL.
*
* **NOTE:** Only `https://` URLs are supported.
*/
url: string
/**
* Authentication token for the database.
*/
token?: string
/**
* Custom `fetch` implementation.
*
* @default `globalThis.fetch`
*/
fetch?: typeof globalThis.fetch
};
/**
* Execute a single statement.
*
* > [!NOTE]
* > Throws an `Error` for pipeline statement errors.
* > Throws the `Response` for non-2xx status codes (eg, Authorization issues).
*/
export declare function execute(config: Config, query: Hrana.Stmt): Promise<Hrana.StmtResult>;
/**
* Execute a batch of statements, which will be executed sequentially.
*
* If the condition of a step is present and evaluates to false, the statement is not executed.
*
* > [!NOTE]
* > Throws an `Error` for pipeline statement errors.
* > Throws the `Response` for non-2xx status codes (eg, Authorization issues).
*/
export declare function batch(config: Config, steps: Hrana.BatchStep[]): Promise<Hrana.BatchResult>;
/**
* The Transaction Mode.
*
* * `IMMEDIATE` - starts a transaction and commits it immediately.
* * `DEFERRED` - only starts a transaction once a read/write is attempted. (default)
* * `READONLY` - starts a read-only transaction that fails if any writes occur.
*
* @see https://www.sqlite.org/lang_transaction.html
* @source https://github.com/tursodatabase/libsql/commit/91f4780c0b5eeb738c10abd82d1d8a97e99b2923
*/
export type TransactionMode = "readonly" | "immediate" | "deferred";
/**
* Execute a transaction.
*
* > [!NOTE]
* > Throws an `Error` for pipeline statement errors.
* > Throws the `Response` for non-2xx status codes (eg, Authorization issues).
*
* @param config The Hrana configuration.
* @param type The transaction mode.
* @param stmts The statements to execute.
*/
export declare function transaction(config: Config, type: TransactionMode, ...stmts: Hrana.Stmt[]): Promise<Hrana.BatchResult>;
/**
* Check if the server supports Hrana V3 over HTTP with JSON encoding.
* @see https://github.com/tursodatabase/libsql/blob/main/docs/HRANA_3_SPEC.md#check-support-for-version-3-json
*/
export declare function supports(config: Config): Promise<boolean>;
/**
* Parsing options for "integer" values.
* @default "number"
* @see https://github.com/tursodatabase/libsql/blob/main/docs/HRANA_3_SPEC.md#values
*/
export type IntegerMode = "number" | "bigint" | "string";
/**
* The parsed Row type.
*/
export type Row = {
[column: string]: unknown
};
/**
* A custom transformer function for a column.
*/
export type Transformer<T> = (value: Hrana.Value.Decoded) => T;
/**
* A map of column names to transformer functions.
*/
export type Transformers<T extends Row> = { [K in keyof T]? : Transformer<T[K]> };
/**
* Parse all Rows from the statement results.
*
* @param result The statement results.
* @param options The parsing options.
*/
export declare function parse<T extends Row = Row>(result: Hrana.StmtResult, options?: IntegerMode | Transformers<T>): T[];
/**
* Decode a value.
*
* @param raw The value to parse.
* @param mode The integer {@link IntegerMode}; default="number"
*/
export declare function decode(raw: Hrana.Value.Null): null;
export declare function decode(raw: Hrana.Value.Text): string;
export declare function decode(raw: Hrana.Value.Blob): Uint8Array;
export declare function decode(raw: Hrana.Value.Float): number;
export declare function decode(raw: Hrana.Value.Integer): number;
export declare function decode(raw: Hrana.Value.Integer, mode: "number"): number;
export declare function decode(raw: Hrana.Value.Integer, mode: "string"): string;
export declare function decode(raw: Hrana.Value.Integer, mode: "bigint"): bigint;
export declare function decode(raw: Hrana.Value, mode?: IntegerMode): Hrana.Value.Decoded;
/**
* Encode a JS value into its Hrana representation.
*
* @param v The value to encode.
*/
export declare function encode(v: Hrana.Value.Decoded | ArrayBuffer | Uint8Array | boolean | undefined): Hrana.Value;