Add JavaScript API reference document

2025-12-17 08:34:19 +01:00 · 2025-07-30 14:01:54 +03:00
parent 1acb396814
commit eae6e056cb
2 changed files with 155 additions and 0 deletions
--- a/docs/javascript-api-reference.md
+++ b/docs/javascript-api-reference.md
@@ -0,0 +1,151 @@
+# JavaScript API reference
+
+This document describes the JavaScript API for Turso. The API is implemented in two different packages:
+
+- **`bindings/javascript`**: Native bindings for the Turso database.
+- **`packages/turso-serverless`**: Serverless driver for Turso Cloud databases.
+
+The API is compatible with the libSQL promise API, which is an asynchronous variant of the `better-sqlite3` API.
+
+## class Database
+
+The `Database` class represents a connection that can prepare and execute SQL statements.
+
+### Methods
+
+#### new Database(path, [options]) ⇒ Database
+
+Creates a new database connection.
+
+| Param   | Type                | Description               |
+| ------- | ------------------- | ------------------------- |
+| path    | <code>string</code> | Path to the database file |
+
+The `path` parameter points to the SQLite database file to open. If the file pointed to by `path` does not exists, it will be created.
+To open an in-memory database, please pass `:memory:` as the `path` parameter.
+
+The function returns a `Database` object.
+
+#### prepare(sql) ⇒ Statement
+
+Prepares a SQL statement for execution.
+
+| Param  | Type                | Description                          |
+| ------ | ------------------- | ------------------------------------ |
+| sql    | <code>string</code> | The SQL statement string to prepare. |
+
+The function returns a `Statement` object.
+
+#### transaction(function) ⇒ function
+
+This function is currently not supported.
+
+#### pragma(string, [options]) ⇒ results
+
+This function is currently not supported.
+
+#### backup(destination, [options]) ⇒ promise
+
+This function is currently not supported.
+
+#### serialize([options]) ⇒ Buffer
+
+This function is currently not supported.
+
+#### function(name, [options], function) ⇒ this
+
+This function is currently not supported.
+
+#### aggregate(name, options) ⇒ this
+
+This function is currently not supported.
+
+#### table(name, definition) ⇒ this
+
+This function is currently not supported.
+
+#### authorizer(rules) ⇒ this
+
+This function is currently not supported.
+
+#### loadExtension(path, [entryPoint]) ⇒ this
+
+This function is currently not supported.
+
+#### exec(sql) ⇒ this
+
+Executes a SQL statement.
+
+| Param  | Type                | Description                          |
+| ------ | ------------------- | ------------------------------------ |
+| sql    | <code>string</code> | The SQL statement string to execute. |
+
+#### interrupt() ⇒ this
+
+This function is currently not supported.
+
+#### close() ⇒ this
+
+Closes the database connection.
+
+## class Statement
+
+### Methods
+
+#### run([...bindParameters]) ⇒ object
+
+Executes the SQL statement and returns an info object.
+
+| Param          | Type                          | Description                                      |
+| -------------- | ----------------------------- | ------------------------------------------------ |
+| bindParameters | <code>array of objects</code> | The bind parameters for executing the statement. |
+
+The returned info object contains two properties: `changes` that describes the number of modified rows and `info.lastInsertRowid` that represents the `rowid` of the last inserted row.
+
+#### get([...bindParameters]) ⇒ row
+
+Executes the SQL statement and returns the first row.
+
+| Param          | Type                          | Description                                      |
+| -------------- | ----------------------------- | ------------------------------------------------ |
+| bindParameters | <code>array of objects</code> | The bind parameters for executing the statement. |
+
+### all([...bindParameters]) ⇒ array of rows
+
+Executes the SQL statement and returns an array of the resulting rows.
+
+| Param          | Type                          | Description                                      |
+| -------------- | ----------------------------- | ------------------------------------------------ |
+| bindParameters | <code>array of objects</code> | The bind parameters for executing the statement. |
+
+### iterate([...bindParameters]) ⇒ iterator
+
+Executes the SQL statement and returns an iterator to the resulting rows.
+
+| Param          | Type                          | Description                                      |
+| -------------- | ----------------------------- | ------------------------------------------------ |
+| bindParameters | <code>array of objects</code> | The bind parameters for executing the statement. |
+
+#### pluck([toggleState]) ⇒ this
+
+This function is currently not supported.
+
+#### expand([toggleState]) ⇒ this
+
+This function is currently not supported.
+
+#### raw([rawMode]) ⇒ this
+
+This function is currently not supported.
+
+#### timed([toggle]) ⇒ this
+
+This function is currently not supported.
+
+#### columns() ⇒ array of objects
+
+This function is currently not supported.
+
+#### bind([...bindParameters]) ⇒ this
+
+This function is currently not supported.