Skip to content

libsqlTypes

Person edited this page Nov 13, 2023 · 21 revisions

libsqlResult

Every function in this library returns a libsqlResult<T, R> type.

libsqlResult<T, R> is either:

{
    isOk: true,
    val: T
}

or:

{
    isOk: false,
    err: R
}

For example, the function awaitlibsqlExecute returns libsqlResult<libsqlStatementResOkData, libsqlError>, which is either:

{
    isOk: true,
    val: libsqlStatementResOkData
}

or:

{
    isOk: false,
    err: libsqlError
}

Benefits of Result Type

  • No need of ugly try { } catch { }.
  • Elegant error handling:
//you can do something like
const res = await libsqlExecute(conf, {sql: "SELECT * FROM mad_cats;"});

if (res.isOk) {
    //now res.val is guaranteed by typescript [js users, sorry]
    console.log(res.val.rows); //the rows returned
    console.log(res.val.affected_row_count) //affected rows
    //...
} else { //you might not even use this `else` clause if just wanna get the Ok result
    //now res.err is guaranteed by typescript
    if (res.err.kind==="LIBSQL_SERVER_ERROR") console.log(res.err.server_message); //error encountered by server
    if (res.err.kind==="LIBSQL_RESPONSE_ERROR") doSomething(res.err.data.code) //do something with the error code
    console.error(JSON.stringify(res.err)) //print out whatever error is received
    //...
}

Reference: libsqlExecute, libsqlStatementResOkData, libsqlError




libsqlConfig

The connection config to your libsql-server (DB)

Structure

{
    db_url: string,
    authToken?: string
}



libsqlError

The final wrapper for error in this library for what is returned by server.

Structure

{
    kind: "LIBSQL_SERVER_ERROR",
    server_message: string|null,
    http_status_code: number
}|{
    kind: "LIBSQL_RESPONSE_ERROR",
    data: libsqlStreamResErrData
}

Reference: libsqlStreamResErrData




libsqlPipelineReq

Structure

{
    baton: string | null,
    requests: Array<libsqlCloseStreamReq|libsqlExecuteStreamReq|libsqlBatchStreamReq>
}

Reference: libsqlCloseStreamReq, libsqlExecuteStreamReq, libsqlBatchStreamReq




libsqlPipelineRes

Structure

{
    baton: string | null,
    base_url: string | null,
    results: Array<libsqlStreamResOk|libsqlStreamResErr>
}

Reference: libsqlStreamResOk, libsqlStreamResErr




libsqlCloseStreamReq

Structure

{
    type: "close",
}



libsqlExecuteStreamReq

Structure

{
    type: "execute",
    stmt: libsqlSQLStatement
}

Reference: libsqlSQLStatement




libsqlBatchStreamReq

Structure

{
    type: "batch",
    batch: {
        steps: Array<libsqlBatchReqStep>,
    }
}

Reference: libsqlBatchReqStep




libsqlStreamResOk

Structure

{
    type: "ok",
    response:  libsqlCloseStreamResOk|libsqlExecuteStreamResOk|libsqlBatchStreamResOk
}

Reference: libsqlCloseStreamResOk, libsqlExecuteStreamResOk, libsqlBatchStreamResOk




libsqlStreamResErr

Structure

{
    type: "error",
    error: libsqlStreamResErrData
}

Reference: libsqlStreamResErrData




libsqlSQLStatement

An SQL statement, formatted for the server.

Structure

{
    sql: string,
    args?: Array<libsqlSQLValue>,
    named_args?: Array<{
        name: string,
        value: libsqlSQLValue,
    }>,
    want_rows?: boolean,
}

Reference: libsqlSQLValue




libsqlBatchReqStep

A step in a batch request.

Structure

{
    condition?: libsqlBatchReqStepExecCond | null,
    stmt: libsqlSQLStatement,
}

Reference: libsqlBatchReqStepExecCond, libsqlSQLStatement

A batch step is executed only when condition is either null or evaluates to true.




libsqlCloseStreamResOk

Structure

{
    type: "close",
}



libsqlExecuteStreamResOk

Structure

{
    type: "execute",
    result: libsqlStatementResOkData
}

Reference: libsqlStatementResOkData




libsqlBatchStreamResOk

Structure

{
    type: "batch",
    result: libsqlBatchStreamResOkData,
}

Reference: libsqlBatchStreamResOkData




libsqlStreamResErrData

Returned when something went wrong with the server.

Structure

{
    message: string,
    code?: string | null
}

Errors can be returned by the server in many places in the protocol, and they are always represented with the libsqlStreamResErrData structure. The message field contains an English human-readable description of the error. The code contains a machine-readable error code.

At this moment, the error codes are not yet stabilized and depend on the server implementation.




libsqlSQLValue

Types of values returned by the server. You are responsible for processing them appropriately. Or you could use libsql-stateless-easy instead of this library.

Structure

    { type: "null" } |
    { type: "integer", value: string } |
    { type: "float", value: number } |
    { type: "text", value: string } |
    { type: "blob", base64: string };

The type of the value depends on the type field:

  • null: the SQL NULL value.
  • integer: a 64-bit signed integer. In JSON, the value is a string to avoid losing precision, because some JSON implementations treat all numbers as 64-bit floats.
  • float: a 64-bit float.
  • text: a UTF-8 string.
  • blob: a binary blob with. In JSON, the value is base64-encoded.



libsqlBatchReqStepExecCond

Each of these evaluates to either true or false.

Structure

    { type: "ok", step: number } | //uint32: 0-based index in the steps array
    { type: "error", step: number } | //uint32: 0-based index in the steps array
    { type: "not", cond: libsqlBatchReqStepExecCond } |
    { type: "and", conds: Array<libsqlBatchReqStepExecCond> } |
    { type: "or", conds: Array<libsqlBatchReqStepExecCond> } |
    { type: "is_autocommit" };

Reference: libsqlBatchReqStepExecCond

  • ok evaluates to true if the step (referenced by its 0-based index) was executed successfully. If the statement was skipped, this condition evaluates to false.
  • error evaluates to true if the step (referenced by its 0-based index) has produced an error. If the statement was skipped, this condition evaluates to false.
  • not evaluates cond and returns the logical negative.
  • and evaluates conds and returns the logical conjunction of them.
  • or evaluates conds and returns the logical disjunction of them.
  • is_autocommit evaluates to true if the stream is currently in the autocommit state (not inside an explicit transaction)



libsqlStatementResOkData

The data returned by the server on execution of an SQL statement.

Structure

{
    cols: Array<libsqlSQLColumnElm>,
    rows: Array<Array<libsqlSQLValue>>,
    affected_row_count: number, //uint32
    last_insert_rowid: string | null
}

Reference: libsqlSQLColumnElm, libsqlSQLValue




libsqlBatchStreamResOkData

The data returned by the server on execution of a batch of SQL statement.

Structure

{
    step_results: Array<libsqlStatementResOkData | null>,
    step_errors: Array<libsqlStreamResErrData | null>
}

Reference: libsqlStatementResOkData, libsqlStreamResErrData




libsqlSQLColumnElm

An element of the returned column array.

Structure

{
    name: string | null,
    decltype: string | null
}