Merge branch 'migrate-dexie-to-sqlite'

src/db/databaseUtil.ts

@@ -227,10 +227,28 @@ export async function logConsoleAndDb(
 }
 
 /**
- * Generates an SQL INSERT statement and parameters from a model object.
- * @param model The model object containing fields to update
- * @param tableName The name of the table to update
- * @returns Object containing the SQL statement and parameters array
+ * Generates SQL INSERT statement and parameters from a model object
+ *
+ * This helper function creates a parameterized SQL INSERT statement
+ * from a JavaScript object. It filters out undefined values and
+ * creates the appropriate SQL syntax with placeholders.
+ *
+ * The function is used internally by the migration functions to
+ * safely insert data into the SQLite database.
+ *
+ * @function generateInsertStatement
+ * @param {Record<string, unknown>} model - The model object containing fields to insert
+ * @param {string} tableName - The name of the table to insert into
+ * @returns {Object} Object containing the SQL statement and parameters array
+ * @returns {string} returns.sql - The SQL INSERT statement
+ * @returns {unknown[]} returns.params - Array of parameter values
+ * @example
+ * ```typescript
+ * const contact = { did: 'did:example:123', name: 'John Doe' };
+ * const { sql, params } = generateInsertStatement(contact, 'contacts');
+ * // sql: "INSERT INTO contacts (did, name) VALUES (?, ?)"
+ * // params: ['did:example:123', 'John Doe']
+ * ```
  */
 export function generateInsertStatement(
   model: Record<string, unknown>,
@@ -248,12 +266,30 @@ export function generateInsertStatement(
 }
 
 /**
- * Generates an SQL UPDATE statement and parameters from a model object.
- * @param model The model object containing fields to update
- * @param tableName The name of the table to update
- * @param whereClause The WHERE clause for the update (e.g. "id = ?")
- * @param whereParams Parameters for the WHERE clause
- * @returns Object containing the SQL statement and parameters array
+ * Generates SQL UPDATE statement and parameters from a model object
+ *
+ * This helper function creates a parameterized SQL UPDATE statement
+ * from a JavaScript object. It filters out undefined values and
+ * creates the appropriate SQL syntax with placeholders.
+ *
+ * The function is used internally by the migration functions to
+ * safely update data in the SQLite database.
+ *
+ * @function generateUpdateStatement
+ * @param {Record<string, unknown>} model - The model object containing fields to update
+ * @param {string} tableName - The name of the table to update
+ * @param {string} whereClause - The WHERE clause for the update (e.g. "id = ?")
+ * @param {unknown[]} [whereParams=[]] - Parameters for the WHERE clause
+ * @returns {Object} Object containing the SQL statement and parameters array
+ * @returns {string} returns.sql - The SQL UPDATE statement
+ * @returns {unknown[]} returns.params - Array of parameter values
+ * @example
+ * ```typescript
+ * const contact = { name: 'Jane Doe' };
+ * const { sql, params } = generateUpdateStatement(contact, 'contacts', 'did = ?', ['did:example:123']);
+ * // sql: "UPDATE contacts SET name = ? WHERE did = ?"
+ * // params: ['Jane Doe', 'did:example:123']
+ * ```
  */
 export function generateUpdateStatement(
   model: Record<string, unknown>,