Skip to content

Commit

Permalink
Improve doc comments (#207)
Browse files Browse the repository at this point in the history
* Improve doc comments ahead of new version
  • Loading branch information
dyedgreen authored Sep 11, 2022
1 parent 16bd8a7 commit d53755c
Show file tree
Hide file tree
Showing 3 changed files with 145 additions and 37 deletions.
38 changes: 28 additions & 10 deletions src/db.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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<R extends Row = Row>(
sql: string,
Expand All @@ -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<O extends RowObject = RowObject>(
sql: string,
Expand Down Expand Up @@ -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.
Expand All @@ -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();
* ```
*/
Expand Down Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion src/error.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand Down
142 changes: 116 additions & 26 deletions src/query.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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;
}

Expand Down Expand Up @@ -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`.
*/
Expand Down Expand Up @@ -321,21 +333,32 @@ 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()) {
* // ...
* }
* ```
*
* 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.
*
Expand All @@ -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<O> {
this.iter(params);
Expand Down Expand Up @@ -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.
*
Expand All @@ -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<O> {
return this.all(params).map((row) => this.makeRowObject(row));
Expand All @@ -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.
*
Expand Down Expand Up @@ -479,14 +553,22 @@ 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);
return row === undefined ? undefined : this.makeRowObject(row);
}

/**
* Deprecated, prefer `first`.
* **Deprecated:** prefer `first`.
*/
one(params?: P): R {
const rows = this.all(params);
Expand All @@ -501,7 +583,7 @@ export class PreparedQuery<
}

/**
* Deprecated, prefer `firstEntry`.
* **Deprecated:** prefer `firstEntry`.
*/
oneEntry(params?: P): O {
return this.makeRowObject(this.one(params));
Expand All @@ -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);
Expand All @@ -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.
Expand Down

0 comments on commit d53755c

Please sign in to comment.