Skip to content

Commit

Permalink
Turning all method names into links to the relevant header.
Browse files Browse the repository at this point in the history
  • Loading branch information
Oxyjun committed Nov 19, 2024
1 parent cc0de6f commit 236aad9
Show file tree
Hide file tree
Showing 4 changed files with 16 additions and 16 deletions.
4 changes: 2 additions & 2 deletions src/content/docs/d1/worker-api/d1-database.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ const stmt = env.DB.prepare("SELECT * FROM Customers WHERE CompanyName = ?").bin
| `?NNN` | Ordered | A question mark followed by a number `NNN` holds a spot for the `NNN`-th parameter. `NNN` must be between `1` and `SQLITE_MAX_VARIABLE_NUMBER` |
| `?` | Anonymous | A question mark that is not followed by a number creates a parameter with a number one greater than the largest parameter number already assigned. If this means the parameter number is greater than `SQLITE_MAX_VARIABLE_NUMBER`, it is an error. This parameter format is provided for compatibility with other database engines. But because it is easy to miscount the question marks, the use of this parameter format is discouraged. Programmers are encouraged to use one of the symbolic formats below or the `?NNN` format above instead. |

To bind a parameter, use the `D1PreparedStatement::bind` method.
To bind a parameter, use the `.bind` method.

Order and anonymous examples:

Expand Down Expand Up @@ -117,7 +117,7 @@ const batchResult = await env.DB.batch([
#### Return values

- <code>results</code>: <Type text="Array"/>
- An array of `D1Result` objects containing the results of the `D1Database::prepare` statements. Each object is in the array position corresponding to the array position of the initial `D1Database::prepare` statement within the `statements`.
- An array of `D1Result` objects containing the results of the [`D1Database::prepare`](#prepare) statements. Each object is in the array position corresponding to the array position of the initial [`D1Database::prepare`](#prepare) statement within the `statements`.
- Refer to [`D1Result`](/d1/worker-api/return-object/#d1result) for more information about this object.

<Details header="Example of return values" open={false}>
Expand Down
4 changes: 2 additions & 2 deletions src/content/docs/d1/worker-api/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -20,9 +20,9 @@ Refer to the relevant sections for the API documentation.

D1 Worker Bindings API is fully-typed via the [`@cloudflare/workers-types`](/workers/languages/typescript/#typescript) package, and also supports [generic types](https://www.typescriptlang.org/docs/handbook/2/generics.html#generic-types) as part of its TypeScript API. A generic type allows you to provide an optional `type parameter` so that a function understands the type of the data it is handling.

When using the [query statement methods](/d1/worker-api/prepared-statements) `D1PreparedStatement::run`, `D1PreparedStatement::raw` and `D1PreparedStatement::first`, you can provide a type representing each database row. D1's API will [return the result object](#return-object) with the correct type.
When using the query statement methods [`D1PreparedStatement::run`](/d1/worker-api/prepared-statements/#run), [`D1PreparedStatement::raw`](/d1/worker-api/prepared-statements/#raw) and [`D1PreparedStatement::first`](/d1/worker-api/prepared-statements/#first), you can provide a type representing each database row. D1's API will [return the result object](#return-object) with the correct type.

For example, providing an `OrderRow` type as a type parameter to `D1PreparedStatement::run` will return a typed `Array<OrderRow>` object instead of the default `Record<string, unknown>` type:
For example, providing an `OrderRow` type as a type parameter to [`D1PreparedStatement::run`](/d1/worker-api/prepared-statements/#run) will return a typed `Array<OrderRow>` object instead of the default `Record<string, unknown>` type:

```ts
// Row definition
Expand Down
12 changes: 6 additions & 6 deletions src/content/docs/d1/worker-api/prepared-statements.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -70,8 +70,8 @@ return Response.json(returnValue);
#### Guidance

- `results` is empty for write operations such as `UPDATE`, `DELETE`, or `INSERT`.
- When using TypeScript, you can pass a [type parameter](/d1/build-with-d1/d1-client-api/#typescript-support) to `D1PreparedStatement::run` to return a typed result object.
- `D1PreparedStatement::run` is functionally equivalent to `D1PreparedStatement::all`, and can be treated as an alias.
- When using TypeScript, you can pass a [type parameter](/d1/build-with-d1/d1-client-api/#typescript-support) to [`D1PreparedStatement::run`](#run) to return a typed result object.
- [`D1PreparedStatement::run`](#run) is functionally equivalent to `D1PreparedStatement::all`, and can be treated as an alias.
- You can choose to extract only the results you expect from the statement by simply returning the `results` property of the return object.

<Details header="Example of returning only the `results`" open={false}>
Expand Down Expand Up @@ -158,7 +158,7 @@ return Response.json(returnValue)

#### Guidance

- When using TypeScript, you can pass a [type parameter](/d1/build-with-d1/d1-client-api/#typescript-support) to `D1PreparedStatement::raw` to return a typed result array.
- When using TypeScript, you can pass a [type parameter](/d1/build-with-d1/d1-client-api/#typescript-support) to [`D1PreparedStatement::raw`](#raw) to return a typed result array.

### `first()`

Expand Down Expand Up @@ -217,7 +217,7 @@ return Response.json(returnValue)

#### Guidance

- If the query returns rows but `column` does not exist, then `D1PreparedStatement::first` throws the `D1_ERROR` exception.
- `D1PreparedStatement::first` does not alter the SQL query. To improve performance, consider appending `LIMIT 1` to your statement.
- When using TypeScript, you can pass a [type parameter](/d1/build-with-d1/d1-client-api/#typescript-support) to `D1PreparedStatement::first` to return a typed result object.
- If the query returns rows but `column` does not exist, then [`D1PreparedStatement::first`](#first) throws the `D1_ERROR` exception.
- [`D1PreparedStatement::first`](#first) does not alter the SQL query. To improve performance, consider appending `LIMIT 1` to your statement.
- When using TypeScript, you can pass a [type parameter](/d1/build-with-d1/d1-client-api/#typescript-support) to [`D1PreparedStatement::first`](#first) to return a typed result object.

12 changes: 6 additions & 6 deletions src/content/docs/d1/worker-api/return-object.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -7,14 +7,14 @@ sidebar:

Some D1 Worker Binding APIs return a typed object.

| D1 Worker Binding API | Return object |
| ---------------------------------------------- | ------------- |
| `D1PreparedStatement::run`, `D1Database::batch`| `D1Result` |
| `D1Database::exec` | `D1ExecResult`|
| D1 Worker Binding API | Return object |
| ------------------------------------------------------------------------------------------------------------------------------ | ------------- |
| [`D1PreparedStatement::run`](/d1/worker-api/prepared-statements/#run), [`D1Database::batch`](/d1/worker-api/d1-database/#batch)| `D1Result` |
| [`D1Database::exec`](/d1/worker-api/d1-database/#exec) | `D1ExecResult`|

## D1Result

The methods `D1PreparedStatement::run` and `D1Database::batch` return a typed `D1Result` object for each query statement. This object contains:
The methods [`D1PreparedStatement::run`](/d1/worker-api/prepared-statements/#run) and [`D1Database::batch`](/d1/worker-api/d1-database/#batch) return a typed [`D1Result`](#d1result) object for each query statement. This object contains:

- The success status
- A meta object with the internal duration of the operation in milliseconds
Expand Down Expand Up @@ -75,7 +75,7 @@ return Response.json(result)

## D1ExecResult

The method `D1Database::exec` returns a typed `D1ExecResult` object for each query statement. This object contains:
The method [`D1Database::exec`](/d1/worker-api/d1-database/#exec) returns a typed [`D1ExecResult`](#d1execresult) object for each query statement. This object contains:

- The number of executed queries
- The duration of the operation in milliseconds
Expand Down

0 comments on commit 236aad9

Please sign in to comment.