docs: fix and add jsdocs to promise.js for tsc inference (#205)

We noticed that many of the types in the tsc-generated `promise.d.ts`
definitions were either missing or incorrect. This attempts to address
some of those issues through updating JSDocs. In particular, correcting
the Database constructor to type the parameter as NativeDb allows tsc to
correctly infer more method return types.

Here is `promise.d.ts` after a local run of tsc with these changes
applied:
```ts
import Authorization = require("./auth");
/**
 * Database represents a connection that can prepare and execute SQL statements.
 */
export class Database {
    /**
     * Creates a new database connection. If the database file pointed to by `path` does not exists, it will be created.
     *
     * @constructor
     * @param {NativeDb} db - Database object
     */
    constructor(db: NativeDb);
    db: NativeDb;
    memory: boolean;
    sync(): Promise<import("./index.js").SyncResult>;
    syncUntil(replicationIndex: any): void;
    /**
     * Prepares a SQL statement for execution.
     *
     * @param {string} sql - The SQL statement string to prepare.
     */
    prepare(sql: string): Promise<Statement>;
    /**
     * Returns a function that executes the given function in a transaction.
     *
     * @param {function} fn - The function to wrap in a transaction.
     */
    transaction(fn: Function): (...bindParameters: any[]) => Promise<any>;
    /**
     * Execute a pragma statement
     * @param {string} source - The pragma statement to execute, without the `PRAGMA` prefix.
     * @param {object} [options] - Options object.
     * @param {boolean} [options.simple] - If true, return a single value for single-column results.
     */
    pragma(source: string, options?: {
        simple?: boolean | undefined;
    }): Promise<object>;
    backup(filename: any, options: any): void;
    serialize(options: any): void;
    function(name: any, options: any, fn: any): void;
    aggregate(name: any, options: any): void;
    table(name: any, factory: any): void;
    authorizer(rules: any): void;
    authorizer(hook: any): this;
    /**
     * Loads an extension into the database
     * @param {Parameters<NativeDb['loadExtension']>} args - Arguments to pass to the underlying loadExtension method
     */
    loadExtension(path: string, entryPoint?: string | null | undefined): void;
    maxWriteReplicationIndex(): number;
    /**
     * Executes a SQL statement.
     *
     * @param {string} sql - The SQL statement string to execute.
     */
    exec(sql: string): Promise<void>;
    /**
     * Interrupts the database connection.
     */
    interrupt(): void;
    /**
     * Closes the database connection.
     */
    close(): void;
    /**
     * Toggle 64-bit integer support.
     * @param {boolean} [toggle] - Whether to use safe integers by default.
     */
    defaultSafeIntegers(toggle?: boolean): this;
    unsafeMode(...args: any[]): void;
}
import SqliteError = require("./sqlite-error.js");
/**
 * Statement represents a prepared SQL statement that can be executed.
 */
export class Statement {
    /**
     * @param {NativeStatement} stmt
     */
    constructor(stmt: NativeStatement);
    stmt: NativeStatement;
    /**
     * Toggle raw mode.
     *
     * @param {boolean} [raw] - Enable or disable raw mode. If you don't pass the parameter, raw mode is enabled.
     */
    raw(raw?: boolean): this;
    /**
     * Toggle pluck mode.
     *
     * @param {boolean} [pluckMode] - Enable or disable pluck mode. If you don't pass the parameter, pluck mode is enabled.
     */
    pluck(pluckMode?: boolean): this;
    /**
     * Toggle query timing.
     *
     * @param {boolean} [timingMode] - Enable or disable query timing. If you don't pass the parameter, query timing is enabled.
     */
    timing(timingMode?: boolean): this;
    get reader(): void;
    /**
     * Executes the SQL statement and returns an info object.
     */
    run(...bindParameters: any[]): Promise<object>;
    /**
     * Executes the SQL statement and returns the first row.
     *
     * @param bindParameters - The bind parameters for executing the statement.
     */
    get(...bindParameters: any[]): Promise<object>;
    /**
     * Executes the SQL statement and returns an iterator to the resulting rows.
     *
     * @param bindParameters - The bind parameters for executing the statement.
     */
    iterate(...bindParameters: any[]): Promise<{
        next(): any;
        [Symbol.asyncIterator](): {
            next(): any;
        };
    }>;
    /**
     * Executes the SQL statement and returns an array of the resulting rows.
     *
     * @param bindParameters - The bind parameters for executing the statement.
     */
    all(...bindParameters: any[]): Promise<any[]>;
    /**
     * Interrupts the statement.
     */
    interrupt(): this;
    /**
     * Returns the columns in the result set returned by this prepared statement.
     */
    columns(): unknown[];
    /**
     * Toggle 64-bit integer support.
     */
    safeIntegers(toggle: any): this;
}
/**
 * Creates a new database connection.
 *
 * @param {string} path - Path to the database file.
 * @param {NativeOptions} opts - Options.
 */
export function connect(path: string, opts: NativeOptions): Promise<Database>;
import { Database as NativeDb } from "./index.js";
import type { Statement as NativeStatement } from './index.js';
import type { Options as NativeOptions } from './index.js';
export { Authorization, SqliteError };

```

Author: penberg

promise.js

@@ -4,6 +4,10 @@ const { Database: NativeDb, connect: nativeConnect } = require("./index.js");
 const SqliteError = require("./sqlite-error.js");
 const Authorization = require("./auth");
 
+/**
+ * @import {Options as NativeOptions, Statement as NativeStatement} from './index.js'
+ */
+
 function convertError(err) {
   // Handle errors from Rust with JSON-encoded message
   if (typeof err.message === 'string') {
@@ -32,7 +36,7 @@ function convertError(err) {
  * Creates a new database connection.
  *
  * @param {string} path - Path to the database file.
- * @param {object} opts - Options.
+ * @param {NativeOptions} opts - Options.
  */
 const connect = async (path, opts) => {
   const db = await nativeConnect(path, opts);
@@ -47,7 +51,7 @@ class Database {
    * Creates a new database connection. If the database file pointed to by `path` does not exists, it will be created.
    *
    * @constructor
-   * @param {string} path - Path to the database file.
+   * @param {NativeDb} db - Database object
    */
   constructor(db) {
     this.db = db;
@@ -124,6 +128,12 @@ class Database {
     return properties.default.value;
   }
 
+  /**
+   * Execute a pragma statement
+   * @param {string} source - The pragma statement to execute, without the `PRAGMA` prefix.
+   * @param {object} [options] - Options object.
+   * @param {boolean} [options.simple] - If true, return a single value for single-column results.
+   */
   async pragma(source, options) {
     if (options == null) options = {};
     if (typeof source !== 'string') throw new TypeError('Expected first argument to be a string');
@@ -161,6 +171,10 @@ class Database {
     }
   }
 
+  /**
+   * Loads an extension into the database
+   * @param {Parameters<NativeDb['loadExtension']>} args - Arguments to pass to the underlying loadExtension method
+   */
   loadExtension(...args) {
     try {
       this.db.loadExtension(...args);
@@ -211,6 +225,7 @@ class Database {
 
   /**
    * Toggle 64-bit integer support.
+   * @param {boolean} [toggle] - Whether to use safe integers by default.
    */
   defaultSafeIntegers(toggle) {
     this.db.defaultSafeIntegers(toggle);
@@ -226,14 +241,17 @@ class Database {
  * Statement represents a prepared SQL statement that can be executed.
  */
 class Statement {
+  /**
+   * @param {NativeStatement} stmt
+   */
   constructor(stmt) {
     this.stmt = stmt;
   }
 
   /**
    * Toggle raw mode.
    *
-   * @param raw Enable or disable raw mode. If you don't pass the parameter, raw mode is enabled.
+   * @param {boolean} [raw] - Enable or disable raw mode. If you don't pass the parameter, raw mode is enabled.
    */
   raw(raw) {
     this.stmt.raw(raw);
@@ -243,7 +261,7 @@ class Statement {
   /**
    * Toggle pluck mode.
    *
-   * @param pluckMode Enable or disable pluck mode. If you don't pass the parameter, pluck mode is enabled.
+   * @param {boolean} [pluckMode] - Enable or disable pluck mode. If you don't pass the parameter, pluck mode is enabled.
    */
   pluck(pluckMode) {
     this.stmt.pluck(pluckMode);
@@ -253,7 +271,7 @@ class Statement {
   /**
    * Toggle query timing.
    *
-   * @param timing Enable or disable query timing. If you don't pass the parameter, query timing is enabled.
+   * @param {boolean} [timingMode] - Enable or disable query timing. If you don't pass the parameter, query timing is enabled.
    */
   timing(timingMode) {
     this.stmt.timing(timingMode);