---@meta lsqlite3

--------------------------------------------------------------------------------
-- lsqlite3 C module
--------------------------------------------------------------------------------

---@alias lsqlite3_value nil|boolean|number|string
---@alias lsqlite3_row table<integer,lsqlite3_value>
---@alias lsqlite3_named_row table<string,lsqlite3_value>
---@alias lsqlite3_exec_callback fun(userdata:any, columns:integer, values:table, names:table):integer|boolean|nil
---@alias lsqlite3_busy_callback fun(userdata:any, tries:integer):boolean|integer|nil
---@alias lsqlite3_hook_callback fun(userdata:any, ...:any)
---@alias lsqlite3_scalar_callback fun(ctx:lsqlite3_context*, ...:lsqlite3_value)
---@alias lsqlite3_collation_callback fun(a:string, b:string):integer

---@class lsqlite3_context*
local lsqlite3_context = {}

--- Get the user data saved when registering the function.
---@return any userdata User data
function lsqlite3_context:user_data() end

--- Get aggregate context data.
---@return any value Aggregate data
function lsqlite3_context:get_aggregate_data() end

--- Set aggregation context data.
---@param value any Aggregate data
function lsqlite3_context:set_aggregate_data(value) end

--- Get the number of aggregation calls.
---@return integer count Number of calls
function lsqlite3_context:aggregate_count() end

--- Set the SQL function return value.
---@param value lsqlite3_value return value
function lsqlite3_context:result(value) end

--- Set the SQL function to return NULL.
function lsqlite3_context:result_null() end

--- Sets the SQL function to return number.
---@param value number return value
function lsqlite3_context:result_number(value) end

--- Sets the SQL function to return double.
---@param value number return value
function lsqlite3_context:result_double(value) end

--- Sets the SQL function to return an integer.
---@param value integer return value
function lsqlite3_context:result_int(value) end

--- Sets the SQL function to return text.
---@param value string return value
function lsqlite3_context:result_text(value) end

--- Sets the SQL function to return a blob.
---@param value string return value
function lsqlite3_context:result_blob(value) end

--- Error setting SQL function.
---@param message string error message
function lsqlite3_context:result_error(message) end

---@class lsqlite3_backup*
local lsqlite3_backup = {}

--- Perform backup stepping.
---@param pages integer Number of pages; -1 means all
---@return integer code SQLite return code
function lsqlite3_backup:step(pages) end

--- Returns the number of remaining pages.
---@return integer count Number of pages remaining
function lsqlite3_backup:remaining() end

--- Returns the total number of pages.
---@return integer count Total pages
function lsqlite3_backup:pagecount() end

--- Complete backup.
---@return integer code SQLite return code
function lsqlite3_backup:finish() end

---@class lsqlite3_stmt*
local lsqlite3_stmt = {}

--- Whether the statement is still open.
---@return boolean ok Whether to open
function lsqlite3_stmt:isopen() end

--- Perform one step.
---@return integer code SQLite return code
function lsqlite3_stmt:step() end

--- reset statement.
---@return integer code SQLite return code
function lsqlite3_stmt:reset() end

--- Release statement.
---@return integer code SQLite return code
function lsqlite3_stmt:finalize() end

--- Returns the number of columns.
---@return integer count Number of columns
function lsqlite3_stmt:columns() end

--- Bind a parameter.
---@param index integer Parameter number, starting from 1
---@param value lsqlite3_value Parameter value
---@return integer code SQLite return code
function lsqlite3_stmt:bind(index, value) end

--- Bind all parameters in order.
---@param ... lsqlite3_value Parameter value
---@return integer code SQLite return code
function lsqlite3_stmt:bind_values(...) end

--- Bind parameters from a table by name or sequence number.
---@param values table<string|integer,lsqlite3_value> Parameter table
---@return integer code SQLite return code
function lsqlite3_stmt:bind_names(values) end

--- Bind blob parameters.
---@param index integer Parameter number, starting from 1
---@param value string blob data
---@return integer code SQLite return code
function lsqlite3_stmt:bind_blob(index, value) end

--- Returns the number of bound parameters.
---@return integer count Number of parameters
function lsqlite3_stmt:bind_parameter_count() end

--- Returns the binding parameter name.
---@param index integer Parameter number, starting from 1
---@return string? name Parameter name
function lsqlite3_stmt:bind_parameter_name(index) end

--- Get the column value of the current row.
---@param index integer Column number, starting from 0
---@return lsqlite3_value value column value
function lsqlite3_stmt:get_value(index) end

--- Get all column values of the current row.
---@return lsqlite3_row values list of values
function lsqlite3_stmt:get_values() end

--- Get column names.
---@param index integer Column number, starting from 0
---@return string name List
function lsqlite3_stmt:get_name(index) end

--- Get all column names.
---@return string[] names column name list
function lsqlite3_stmt:get_names() end

--- Gets the column declaration type.
---@param index integer Column number, starting from 0
---@return string? typeName Type name
function lsqlite3_stmt:get_type(index) end

--- Get all column declaration types.
---@return table<integer,string?> types Type list
function lsqlite3_stmt:get_types() end

--- Returns the current row and column values as multiple return values.
---@return lsqlite3_value ...
function lsqlite3_stmt:get_uvalues() end

--- Returns column names as multiple return values.
---@return string ...
function lsqlite3_stmt:get_unames() end

--- Return column declaration type with multiple return values.
---@return string? ...
function lsqlite3_stmt:get_utypes() end

--- Get the current row value using the column name as the key.
---@return lsqlite3_named_row values value table
function lsqlite3_stmt:get_named_values() end

--- Gets the column declaration type keyed by the column name.
---@return table<string,string?> types type table
function lsqlite3_stmt:get_named_types() end

--- Returns a row-by-row iterator, where each row is an array table.
---@return fun():lsqlite3_row? iter Iterator
---@return lsqlite3_stmt* stmt statement object
function lsqlite3_stmt:rows() end

--- Returns a row-wise iterator, where each row is a table of column names and keys.
---@return fun():lsqlite3_named_row? iter Iterator
---@return lsqlite3_stmt* stmt statement object
function lsqlite3_stmt:nrows() end

--- Returns a row-by-row iterator, with multiple return values ​​for each row.
---@return fun():lsqlite3_value ... iter Iterator
---@return lsqlite3_stmt* stmt statement object
function lsqlite3_stmt:urows() end

--- Returns the most recently inserted rowid.
---@return integer|string rowid rowid
function lsqlite3_stmt:last_insert_rowid() end

--- `get_values` is compatible with aliases.
---@return lsqlite3_row values list of values
function lsqlite3_stmt:idata() end

--- `get_names` is compatible with aliases.
---@return string[] names column name list
function lsqlite3_stmt:inames() end

--- `get_types` is compatible with aliases.
---@return table<integer,string?> types Type list
function lsqlite3_stmt:itypes() end

--- `get_named_values` is compatible with aliases.
---@return lsqlite3_named_row values value table
function lsqlite3_stmt:data() end

--- `get_named_types` is compatible with aliases.
---@return table<string,string?> types type table
function lsqlite3_stmt:type() end

---@class lsqlite3_db*
local lsqlite3_db = {}

--- Whether the database is still open.
---@return boolean ok Whether to open
function lsqlite3_db:isopen() end

--- Returns the most recently inserted rowid.
---@return integer|string rowid rowid
function lsqlite3_db:last_insert_rowid() end

--- Returns the number of rows affected by the most recent statement.
---@return integer count Number of lines
function lsqlite3_db:changes() end

--- Returns the cumulative number of rows affected by the connection.
---@return integer count Number of lines
function lsqlite3_db:total_changes() end

--- Returns the most recent SQLite error code.
---@return integer code error code
function lsqlite3_db:errcode() end

--- Returns the most recent SQLite error code.
---@return integer code error code
function lsqlite3_db:error_code() end

--- Returns the most recent SQLite error message.
---@return string message error message
function lsqlite3_db:errmsg() end

--- Returns the most recent SQLite error message.
---@return string message error message
function lsqlite3_db:error_message() end

--- Interrupt a long operation on the current connection.
function lsqlite3_db:interrupt() end

--- Returns the file path corresponding to the specified database name.
---@param name string Database name, usually `main`, `temp` or attached name
---@return string? filename file path
function lsqlite3_db:db_filename(name) end

--- Register a scalar SQL function.
---@param name string SQL function name
---@param nargs integer Number of parameters
---@param callback lsqlite3_scalar_callback callback
---@param userdata? any User data
---@return boolean ok Is it successful?
function lsqlite3_db:create_function(name, nargs, callback, userdata) end

--- Register aggregate SQL functions.
---@param name string SQL function name
---@param nargs integer Number of parameters
---@param step lsqlite3_scalar_callback step callback
---@param final fun(ctx:lsqlite3_context*) finalize callback
---@param userdata? any User data
---@return boolean ok Is it successful?
function lsqlite3_db:create_aggregate(name, nargs, step, final, userdata) end

--- Register sorting rules.
---@param name string collation name
---@param callback? lsqlite3_collation_callback callback; nil means removal
function lsqlite3_db:create_collation(name, callback) end

--- Load SQLite extension; turn off extension loading when no extension is passed.
---@param extname? string Expansion path
---@param entrypoint? string Entry function name
---@return boolean ok Is it successful?
---@return string? errMsg error message
function lsqlite3_db:load_extension(extname, entrypoint) end

--- Set trace callback.
---@param callback? fun(userdata:any, sql:string) callback; nil means removal
---@param userdata? any User data
function lsqlite3_db:trace(callback, userdata) end

--- Set the progress callback.
---@param opcodes? integer opcode Interval; nil means remove
---@param callback? fun(userdata:any):boolean|integer|nil callback
---@param userdata? any User data
function lsqlite3_db:progress_handler(opcodes, callback, userdata) end

--- Set busy timeout in milliseconds.
---@param ms integer milliseconds
function lsqlite3_db:busy_timeout(ms) end

--- Set busy callback.
---@param callback? lsqlite3_busy_callback callback; nil means removal
---@param userdata? any User data
function lsqlite3_db:busy_handler(callback, userdata) end

--- Set update hook.
---@param callback? fun(userdata:any, operation:integer, database:string, tableName:string, rowid:integer|string) callback; nil means removal
---@param userdata? any User data
function lsqlite3_db:update_hook(callback, userdata) end

--- Set commit hook.
---@param callback? fun(userdata:any):boolean|integer|nil callback; nil means removal
---@param userdata? any User data
function lsqlite3_db:commit_hook(callback, userdata) end

--- Set up rollback hook.
---@param callback? lsqlite3_hook_callback callback; nil means removal
---@param userdata? any User data
function lsqlite3_db:rollback_hook(callback, userdata) end

--- Compile SQL statements.
---@param sql string SQL text
---@return lsqlite3_stmt*? stmt statement object
---@return string|integer? tailOrCode It is the uncompiled tail when it succeeds, and it is the error code when it fails.
function lsqlite3_db:prepare(sql) end

--- Execute SQL and return an array row iterator.
---@param sql string SQL text
---@param ... any Bind parameters or a single parameter list
---@return fun():lsqlite3_row? iter Iterator
---@return lsqlite3_stmt* stmt temporary statement object
function lsqlite3_db:rows(sql, ...) end

--- Execute SQL and return a column name key row iterator.
---@param sql string SQL text
---@param ... any Bind parameters or a single parameter list
---@return fun():lsqlite3_named_row? iter Iterator
---@return lsqlite3_stmt* stmt temporary statement object
function lsqlite3_db:nrows(sql, ...) end

--- Execute SQL and iterate row by row with multiple return values.
---@param sql string SQL text
---@param ... any Bind parameters or a single parameter list
---@return fun():lsqlite3_value ... iter Iterator
---@return lsqlite3_stmt* stmt temporary statement object
function lsqlite3_db:urows(sql, ...) end

--- Execute SQL.
---@param sql string SQL text
---@param callback? lsqlite3_exec_callback line callback
---@param userdata? any User data
---@return integer code SQLite return code
function lsqlite3_db:exec(sql, callback, userdata) end

--- Execute SQL.
---@param sql string SQL text
---@param callback? lsqlite3_exec_callback line callback
---@param userdata? any User data
---@return integer code SQLite return code
function lsqlite3_db:execute(sql, callback, userdata) end

--- Close the database.
---@return integer? code SQLite return code
function lsqlite3_db:close() end

--- Closes the specified statement or the statement associated with the current connection.
---@param stmt? lsqlite3_stmt* statement object
---@return integer? code SQLite return code
function lsqlite3_db:close_vm(stmt) end

--- Get the underlying sqlite3 pointer.
---@return lightuserdata ptr sqlite3 pointer
function lsqlite3_db:get_ptr() end

---@class lsqlite3*
---@field OK integer
---@field ERROR integer
---@field INTERNAL integer
---@field PERM integer
---@field ABORT integer
---@field BUSY integer
---@field LOCKED integer
---@field NOMEM integer
---@field READONLY integer
---@field INTERRUPT integer
---@field IOERR integer
---@field CORRUPT integer
---@field NOTFOUND integer
---@field FULL integer
---@field CANTOPEN integer
---@field PROTOCOL integer
---@field EMPTY integer
---@field SCHEMA integer
---@field TOOBIG integer
---@field CONSTRAINT integer
---@field MISMATCH integer
---@field MISUSE integer
---@field NOLFS integer
---@field FORMAT integer
---@field NOTADB integer
---@field RANGE integer
---@field ROW integer
---@field DONE integer
---@field INTEGER integer
---@field FLOAT integer
---@field TEXT integer
---@field BLOB integer
---@field NULL integer
---@field CREATE_INDEX integer
---@field CREATE_TABLE integer
---@field CREATE_TEMP_INDEX integer
---@field CREATE_TEMP_TABLE integer
---@field CREATE_TEMP_TRIGGER integer
---@field CREATE_TEMP_VIEW integer
---@field CREATE_TRIGGER integer
---@field CREATE_VIEW integer
---@field DELETE integer
---@field DROP_INDEX integer
---@field DROP_TABLE integer
---@field DROP_TEMP_INDEX integer
---@field DROP_TEMP_TABLE integer
---@field DROP_TEMP_TRIGGER integer
---@field DROP_TEMP_VIEW integer
---@field DROP_TRIGGER integer
---@field DROP_VIEW integer
---@field INSERT integer
---@field PRAGMA integer
---@field READ integer
---@field SELECT integer
---@field TRANSACTION integer
---@field UPDATE integer
---@field ATTACH integer
---@field DETACH integer
---@field ALTER_TABLE integer
---@field REINDEX integer
---@field ANALYZE integer
---@field CREATE_VTABLE integer
---@field DROP_VTABLE integer
---@field FUNCTION integer
---@field SAVEPOINT integer
---@field OPEN_READONLY integer
---@field OPEN_READWRITE integer
---@field OPEN_CREATE integer
---@field OPEN_URI integer
---@field OPEN_MEMORY integer
---@field OPEN_NOMUTEX integer
---@field OPEN_FULLMUTEX integer
---@field OPEN_SHAREDCACHE integer
---@field OPEN_PRIVATECACHE integer
---@type lsqlite3*
local M = {}

--- Returns the lsqlite3 binding version.
---@return string version Binding version
function M.lversion() end

--- Returns the underlying SQLite version.
---@return string version SQLite version
function M.version() end

--- Determine whether SQL is a complete statement.
---@param sql string SQL text
---@return boolean ok Is it complete?
function M.complete(sql) end

--- Gets or sets the SQLite temporary directory.
---@param path? string|nil New temporary directory; nil means empty
---@return string? oldPath old temporary directory
function M.temp_directory(path) end

--- Open the database.
---@param filename string file path
---@param flags? integer open flags， Default `OPEN_READWRITE | OPEN_CREATE`
---@return lsqlite3_db*? db database object
---@return integer? errCode error code
---@return string? errMsg error message
function M.open(filename, flags) end

--- Open the in-memory database.
---@return lsqlite3_db*? db database object
---@return integer? errCode error code
---@return string? errMsg error message
function M.open_memory() end

--- Opens a database object from the underlying sqlite3 pointer.
---@param ptr lightuserdata sqlite3 pointer
---@return lsqlite3_db* db database object
function M.open_ptr(ptr) end

--- Initialize online backup.
---@param target lsqlite3_db* target database
---@param targetName string target database name
---@param source lsqlite3_db* Source database
---@param sourceName string Source database name
---@return lsqlite3_backup*? backup Backup object
function M.backup_init(target, targetName, source, sourceName) end

return M
