docs: added jsdocs to exported functions and types

src/database.ts

@@ -3,6 +3,14 @@ import type { Connector, Database } from "./types";
 
 const SQL_WITH_RES_RE = /^select/i;
 
+/**
+ * Creates and returns a database interface using the specified connector.
+ * This interface allows you to execute raw SQL queries, prepare SQL statements,
+ * and execute SQL queries with parameters using tagged template literals.
+ *
+ * @param {Connector} connector - The database connector used to execute and prepare SQL statements. See {@link Connector}.
+ * @returns {Database} The database interface that allows SQL operations. See {@link Database}.
+ */
 export function createDatabase(connector: Connector): Database {
   return <Database>{
     exec: (sql: string) => {

src/index.ts

@@ -1,6 +1,11 @@
 export * from "./database";
 export * from "./types";
 
+/**
+ * A mapping of available database connector identifiers to their module paths.
+ * This constant facilitates the use of different database connectors by providing easy access to the
+ * by providing easy access to the connector's specific import paths.
+ */
 export const connectors = {
   sqlite: "db0/connectors/better-sqlite3",
   postgresql: "db0/connectors/postgresql",
@@ -13,4 +18,8 @@ export const connectors = {
   "bun-sqlite": "db0/connectors/bun-sqlite",
 } as const;
 
+/**
+ * Type alias for the keys of the {@link connectors} map.
+ * Represents the names of available database connectors.
+ */
 export type ConnectorName = keyof typeof connectors;

src/types.ts

@@ -1,20 +1,70 @@
+/**
+ * Represents primitive types that can be used in SQL operations.
+ */
 export type Primitive = string | number | boolean | undefined | null;
 
 export type Statement = {
+  /**
+   * Binds parameters to the statement and returns itself for concatenation.
+   * @param {...Primitive[]} params - Parameters to bind to the SQL statement.
+   * @returns {Statement} The instance of the statement for further cascading.
+   */
   bind(...params: Primitive[]): Statement;
+
+  /**
+   * Executes the statement and returns all resulting rows as an array.
+   * @param {...Primitive[]} params - Parameters to bind to the SQL statement.
+   * @returns {Promise<unknown[]>} A promise that resolves to an array of rows.
+   */
   all(...params: Primitive[]): Promise<unknown[]>;
+
+  /**
+   * Executes the statement as an action (e.g. insert, update, delete).
+   * @param {...Primitive[]} params - Parameters to bind to the SQL statement.
+   * @returns {Promise<{ success: boolean }>} A promise that resolves to the success state of the action.
+   */
   run(...params: Primitive[]): Promise<{ success: boolean }>;
+
+  /**
+   * Executes the statement and returns a single row.
+   * @param {...Primitive[]} params - Parameters to bind to the SQL statement.
+   * @returns {Promise<unknown>} A promise that resolves to the first row in the result set.
+   */
   get(...params: Primitive[]): Promise<unknown>;
 };
 
+/**
+ * Represents the result of a database execution.
+ */
 export type ExecResult = unknown;
 
+/**
+ * Defines a database connector for executing SQL queries and preparing statements.
+ */
 export type Connector = {
+  /**
+   * The name of the connector.
+   */
   name: string;
+
+  /**
+   * Executes an SQL query directly and returns the result.
+   * @param {string} sql - The SQL string to execute.
+   * @returns {ExecResult | Promise<ExecResult>} The result of the execution.
+   */
   exec: (sql: string) => ExecResult | Promise<ExecResult>;
+
+  /**
+   * Prepares an SQL statement for execution.
+   * @param {string} sql - The SQL string to prepare.
+   * @returns {statement} The prepared SQL statement.
+   */
   prepare: (sql: string) => Statement;
 };
 
+/**
+ * Represents default SQL results, including any error messages, row changes and rows returned.
+ */
 type DefaultSQLResult = {
   lastInsertRowid?: number;
   changes?: number;
@@ -23,8 +73,27 @@ type DefaultSQLResult = {
 };
 
 export interface Database {
+  /**
+   * Executes a raw SQL string.
+   * @param {string} sql - The SQL string to execute.
+   * @returns {Promise<ExecResult>} A promise that resolves with the execution result.
+   */
   exec: (sql: string) => Promise<ExecResult>;
+
+  /**
+   * Prepares an SQL statement from a raw SQL string.
+   * @param {string} sql - The SQL string to prepare.
+   * @returns {statement} The prepared SQL statement.
+   */
   prepare: (sql: string) => Statement;
+
+  /**
+   * Executes SQL queries using tagged template literals.
+   * @template T The expected type of query result.
+   * @param {TemplateStringsArray} strings - The segments of the SQL string.
+   * @param {...Primitive[]} values - The values to interpolate into the SQL string.
+   * @returns {Promise<T>} A promise that resolves with the typed result of the query.
+   */
   sql: <T = DefaultSQLResult>(
     strings: TemplateStringsArray,
     ...values: Primitive[]