From d53755cff98b429be827bc70a83112a5b63094bc Mon Sep 17 00:00:00 2001 From: Tilman Roeder Date: Sun, 11 Sep 2022 18:05:21 +0100 Subject: [PATCH] Improve doc comments (#207) * Improve doc comments ahead of new version --- src/db.ts | 38 ++++++++++---- src/error.ts | 2 +- src/query.ts | 142 +++++++++++++++++++++++++++++++++++++++++---------- 3 files changed, 145 insertions(+), 37 deletions(-) diff --git a/src/db.ts b/src/db.ts index 83b318f..2b0f140 100644 --- a/src/db.ts +++ b/src/db.ts @@ -142,6 +142,14 @@ export class DB { * const rows = db.query<[string, number]>("SELECT name, age FROM people WHERE city = ?", [city]); * // rows = [["Peter Parker", 21], ...] * ``` + * + * ```typescript + * const rows = db.query<[string, number]>( + * "SELECT name, age FROM people WHERE city = :city", + * { city }, + * ); + * // rows = [["Peter Parker", 21], ...] + * ``` */ query( sql: string, @@ -168,6 +176,14 @@ export class DB { * const rows = db.queryEntries<{ name: string, age: number }>("SELECT name, age FROM people"); * // rows = [{ name: "Peter Parker", age: 21 }, ...] * ``` + * + * ```typescript + * const rows = db.queryEntries<{ name: string, age: number }>( + * "SELECT name, age FROM people WHERE age >= :minAge", + * { minAge }, + * ); + * // rows = [{ name: "Peter Parker", age: 21 }, ...] + * ``` */ queryEntries( sql: string, @@ -205,15 +221,15 @@ export class DB { * to specify precise types for returned data and * query parameters. * - * The first type parameter `R` indicates the tuple type - * for rows returned by the query. + * + The first type parameter `R` indicates the tuple type + * for rows returned by the query. * - * The second type parameter `O` indicates the record type - * for rows returned as entries (mappings from column names - * to values). + * + The second type parameter `O` indicates the record type + * for rows returned as entries (mappings from column names + * to values). * - * The third type parameter `P` indicates the type this query - * accepts as parameters. + * + The third type parameter `P` indicates the type this query + * accepts as parameters. * * Note, that the correctness of those types must * be guaranteed by the caller of this function. @@ -226,7 +242,9 @@ export class DB { * { name: string, age: number }, * { city: string }, * >("SELECT name, age FROM people WHERE city = :city"); + * * // use query ... + * * query.finalize(); * ``` */ @@ -318,9 +336,9 @@ export class DB { * the database is no longer used to avoid leaking * open file descriptors. * - * If `force` is specified, any active `PreparedQuery` - * will be finalized. Otherwise, this throws if there - * are active queries. + * If `force = true` is passed, any non-finalized + * `PreparedQuery` objects will be finalized. Otherwise, + * this throws if there are active queries. * * `close` may safely be called multiple * times. diff --git a/src/error.ts b/src/error.ts index ab07e1c..81fb33d 100644 --- a/src/error.ts +++ b/src/error.ts @@ -3,7 +3,7 @@ import { getStr } from "./wasm.ts"; import { Status } from "./constants.ts"; /** - * Errors which can be thrown while interacting with + * Errors which can occur while interacting with * a database. */ export class SqliteError extends Error { diff --git a/src/query.ts b/src/query.ts index 85dab0e..9d0aa4f 100644 --- a/src/query.ts +++ b/src/query.ts @@ -89,8 +89,23 @@ export type QueryParameterSet = * Name of a column in a database query. */ export interface ColumnName { + /** + * Name of the returned column. + */ name: string; + /** + * Name of the database column that stores + * the data returned from this query. + * + * This might be different from `name` if a + * columns was renamed using e.g. as in + * `SELECT foo AS bar FROM table`. + */ originName: string; + /** + * Name of the table that stores the data + * returned from this query. + */ tableName: string; } @@ -118,10 +133,7 @@ export class PreparedQuery< private _finalized: boolean; /** - * A prepared query which can be executed many - * times. - * - * The constructor should never be used directly. + * This constructor should never be used directly. * Instead a prepared query can be obtained by * calling `DB.prepareQuery`. */ @@ -321,7 +333,11 @@ export class PreparedQuery< * rows into memory and hence allows to process a large * number of rows. * - * # Example: + * Calling `iter`, `all`, or `first` invalidates any iterators + * previously returned from this prepared query. + * + * # Examples + * * ```typescript * const query = db.prepareQuery<[number, string]>("SELECT id, name FROM people"); * for (const [id, name] of query.iter()) { @@ -329,13 +345,20 @@ export class PreparedQuery< * } * ``` * - * Calling `iter` invalidates any iterators previously returned - * from this prepared query. Using an invalidated iterator is a bug. - * * To avoid SQL injection, user-provided values * should always be passed to the database through * a query parameter. * + * ```typescript + * const query = db.prepareQuery("SELECT id FROM people WHERE name = ?"); + * preparedQuery.iter([name]); + * ``` + * + * ```typescript + * const query = db.prepareQuery("SELECT id FROM people WHERE name = :name"); + * preparedQuery.iter({ name }); + * ``` + * * See `QueryParameterSet` for documentation on * how values can be bound to SQL statements. * @@ -357,6 +380,15 @@ export class PreparedQuery< /** * Like `iter` except each row is returned * as an object containing key-value pairs. + * + * # Examples + * + * ```typescript + * const query = db.prepareQuery<_, { id: number, name: string }>("SELECT id, name FROM people"); + * for (const { id, name } of query.iter()) { + * // ... + * } + * ``` */ iterEntries(params?: P): RowsIterator { this.iter(params); @@ -401,14 +433,28 @@ export class PreparedQuery< * and returns an array containing all resulting * rows. * - * Calling `all` invalidates any iterators - * previously returned by calls to `iter`. - * Using an invalidated iterator is a bug. + * # Examples + * + * ```typescript + * const query = db.prepareQuery<[number, string]>("SELECT id, name FROM people"); + * const rows = query.all(); + * // [[1, "Peter"], ...] + * ``` * * To avoid SQL injection, user-provided values * should always be passed to the database through * a query parameter. * + * ```typescript + * const query = db.prepareQuery("SELECT id FROM people WHERE name = ?"); + * preparedQuery.all([name]); + * ``` + * + * ```typescript + * const query = db.prepareQuery("SELECT id FROM people WHERE name = :name"); + * preparedQuery.all({ name }); + * ``` + * * See `QueryParameterSet` for documentation on * how values can be bound to SQL statements. * @@ -432,6 +478,14 @@ export class PreparedQuery< /** * Like `all` except each row is returned * as an object containing key-value pairs. + * + * # Examples + * + * ```typescript + * const query = db.prepareQuery<_, { id: number, name: string }>("SELECT id, name FROM people"); + * const rows = query.all(); + * // [{ id: 1, name: "Peter" }, ...] + * ``` */ allEntries(params?: P): Array { return this.all(params).map((row) => this.makeRowObject(row)); @@ -443,14 +497,34 @@ export class PreparedQuery< * `undefined` when there are no rows returned * by the query. * - * Calling `first` invalidates any iterators - * previously returned by calls to `iter`. - * Using an invalidated iterator is a bug. + * # Examples + * + * ```typescript + * const query = db.prepareQuery<[number, string]>("SELECT id, name FROM people"); + * const person = query.first(); + * // [1, "Peter"] + * ``` + * + * ```typescript + * const query = db.prepareQuery("SELECT id, name FROM people WHERE name = ?"); + * const person = query.first(["not a name"]); + * // undefined + * ``` * * To avoid SQL injection, user-provided values * should always be passed to the database through * a query parameter. * + * ```typescript + * const query = db.prepareQuery("SELECT id FROM people WHERE name = ?"); + * preparedQuery.first([name]); + * ``` + * + * ```typescript + * const query = db.prepareQuery("SELECT id FROM people WHERE name = :name"); + * preparedQuery.first({ name }); + * ``` + * * See `QueryParameterSet` for documentation on * how values can be bound to SQL statements. * @@ -479,6 +553,14 @@ export class PreparedQuery< /** * Like `first` except the row is returned * as an object containing key-value pairs. + * + * # Examples + * + * ```typescript + * const query = db.prepareQuery<_, { id: number, name: string }>("SELECT id, name FROM people"); + * const person = query.first(); + * // { id: 1, name: "Peter" } + * ``` */ firstEntry(params?: P): O | undefined { const row = this.first(params); @@ -486,7 +568,7 @@ export class PreparedQuery< } /** - * Deprecated, prefer `first`. + * **Deprecated:** prefer `first`. */ one(params?: P): R { const rows = this.all(params); @@ -501,7 +583,7 @@ export class PreparedQuery< } /** - * Deprecated, prefer `firstEntry`. + * **Deprecated:** prefer `firstEntry`. */ oneEntry(params?: P): O { return this.makeRowObject(this.one(params)); @@ -516,16 +598,23 @@ export class PreparedQuery< * rows returned by a query are not needed or * the query does not return any rows. * - * Calling `execute` invalidates any iterators - * previously returned by calls to `iter`. - * Using an invalidated iterator is a bug. + * # Examples * - * To avoid SQL injection, user-provided values - * should always be passed to the database through - * a query parameter. + * ```typescript + * const query = db.prepareQuery<_, _, [string]>("INSERT INTO people (name) VALUES (?)"); + * query.execute(["Peter"]); + * ``` + * + * ```typescript + * const query = db.prepareQuery<_, _, { name: string }>("INSERT INTO people (name) VALUES (:name)"); + * query.execute({ name: "Peter" }); + * ``` * * See `QueryParameterSet` for documentation on * how values can be bound to SQL statements. + * + * See `QueryParameter` for documentation on how + * values are returned from the database. */ execute(params?: P) { this.startQuery(params); @@ -544,10 +633,11 @@ export class PreparedQuery< * to avoid leaking resources. * * After a prepared query has been finalized, - * trying to call `iter`, `all`, `one`, - * `execute`, or `columns`, or using iterators which where - * previously obtained from the finalized query - * is a bug. + * calls to `iter`, `all`, `first`, `execute`, + * or `columns` will fail. + * + * Using iterators which were previously returned + * from the finalized query will fail. * * `finalize` may safely be called multiple * times.