@xata.io/client 0.0.0-alpha.vfaca77b → 0.0.0-alpha.vfb22b4f

package/CHANGELOG.md

@@ -1,5 +1,53 @@
 # @xata.io/client
 
+## 0.13.4
+
+### Patch Changes
+
+- [#444](https://github.com/xataio/client-ts/pull/444) [`3c3a5af`](https://github.com/xataio/client-ts/commit/3c3a5afb1d5fb3295fd8cf6c2b66709a5c047507) Thanks [@SferaDev](https://github.com/SferaDev)! - Publish xata client on deno.land
+
+## 0.13.3
+
+### Patch Changes
+
+- [#434](https://github.com/xataio/client-ts/pull/434) [`b82383d`](https://github.com/xataio/client-ts/commit/b82383d7541d19ae71ad7e047fd100901981f28b) Thanks [@SferaDev](https://github.com/SferaDev)! - Fix problem with SSR `RecordArray` in Next.js
+
+## 0.13.2
+
+### Patch Changes
+
+- [#431](https://github.com/xataio/client-ts/pull/431) [`8f62024`](https://github.com/xataio/client-ts/commit/8f62024101028b981dc31a68fb258e89110d45dc) Thanks [@SferaDev](https://github.com/SferaDev)! - Include request ids in the error response
+
+* [#429](https://github.com/xataio/client-ts/pull/429) [`bb102b4`](https://github.com/xataio/client-ts/commit/bb102b46b722d0a61996c42cda991c9f0080e464) Thanks [@SferaDev](https://github.com/SferaDev)! - Avoid detection of `Buffer` in edge runtime middleware
+
+- [#428](https://github.com/xataio/client-ts/pull/428) [`06740ca`](https://github.com/xataio/client-ts/commit/06740cad216831216f0be8cf9de7e354c0ef9191) Thanks [@SferaDev](https://github.com/SferaDev)! - Improve selection types to make them more readable
+
+## 0.13.1
+
+### Patch Changes
+
+- [#417](https://github.com/xataio/client-ts/pull/417) [`86a14ec`](https://github.com/xataio/client-ts/commit/86a14eccbca94f572252327c9c0306577a1c3ebd) Thanks [@SferaDev](https://github.com/SferaDev)! - Update User-Agent
+
+* [#422](https://github.com/xataio/client-ts/pull/422) [`2896418`](https://github.com/xataio/client-ts/commit/289641844e5b2752197dbbbf3a93ef6068b684e4) Thanks [@SferaDev](https://github.com/SferaDev)! - Allow sending link as string id
+
+- [#420](https://github.com/xataio/client-ts/pull/420) [`301b21f`](https://github.com/xataio/client-ts/commit/301b21f4784f755a8694ca21a0f2fd48e1b16df4) Thanks [@SferaDev](https://github.com/SferaDev)! - Exclude date internal columns in selection
+
+* [#399](https://github.com/xataio/client-ts/pull/399) [`dd4b2ef`](https://github.com/xataio/client-ts/commit/dd4b2effed2251ac8afbfb2909c21a9deb35bef1) Thanks [@SferaDev](https://github.com/SferaDev)! - Allow create many objects mixed some with ids others without
+
+- [#425](https://github.com/xataio/client-ts/pull/425) [`00279ff`](https://github.com/xataio/client-ts/commit/00279ff985793020237f8098cba97dfec7738f82) Thanks [@SferaDev](https://github.com/SferaDev)! - Do not send falsy values to query string
+
+* [#399](https://github.com/xataio/client-ts/pull/399) [`8e66998`](https://github.com/xataio/client-ts/commit/8e6699867a1aa1968d12db4ced80c13d4b951f88) Thanks [@SferaDev](https://github.com/SferaDev)! - Allow passing identifiable objects to `read()` operations
+
+- [#425](https://github.com/xataio/client-ts/pull/425) [`8a4e019`](https://github.com/xataio/client-ts/commit/8a4e019031e678d946cf9dfb0e4803906fad9b5f) Thanks [@SferaDev](https://github.com/SferaDev)! - Add fallback branch to `api.databases.resolveBranch`
+
+## 0.13.0
+
+### Minor Changes
+
+- [#375](https://github.com/xataio/client-ts/pull/375) [`c9f34ad`](https://github.com/xataio/client-ts/commit/c9f34ad37d75203083a1dec2fac2b03e096521af) Thanks [@SferaDev](https://github.com/SferaDev)! - Change default pagination size to 20
+
+* [#375](https://github.com/xataio/client-ts/pull/375) [`5f82e43`](https://github.com/xataio/client-ts/commit/5f82e4394010f40dcbf3faf2d0bdb58a6fc1c37a) Thanks [@SferaDev](https://github.com/SferaDev)! - Return a paginable object in getPaginated
+
 ## 0.12.0
 
 ### Minor Changes

package/README.md

@@ -1,10 +1,28 @@
 # Xata SDK for TypeScript and JavaScript
 
-This SDK has zero dependencies, so it can be used in many JavaScript runtimes including Node.js, Cloudflare workers, Deno, Electron, etc.
+This SDK has zero dependencies, so it can be used in many JavaScript runtimes including Node.js, Cloudflare workers, Deno, Electron, etc. It also works in browsers for the same reason. But this is strongly discouraged because you can easily leak your API keys from browsers.
 
-It also works in browsers for the same reason. But this is strongly discouraged because the API token would be leaked.
+## Table of Contents
 
-## Installing
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Schema-generated Client](#schema-generated-client)
+  - [Schema-less Client](#schema-less-client)
+  - [API Design](#api-design)
+    - [Creating Objects](#creating-objects)
+    - [Query a Single Object by its ID](#query-a-single-object-by-its-id)
+    - [Querying Multiple Objects](#querying-multiple-objects)
+    - [Updating Objects](#updating-objects)
+    - [Deleting Objects](#deleting-objects)
+  - [API Client](#api-client)
+- [Deno support](#deno-support)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+## Installation
 
 ```bash
 npm install @xata.io/client
@@ -20,7 +38,7 @@ There are three ways to use the SDK:
 
 ### Schema-generated Client
 
-To use the schema-generated client, you need to run the code generator utility that comes with [our CLI](../../cli/README.md).
+To use the schema-generated client, you need to run the code generator utility that comes with [our CLI](https://docs.xata.io/cli/getting-started).
 
 To run it (and assuming you have configured the project with `xata init`):
 
@@ -28,19 +46,17 @@ To run it (and assuming you have configured the project with `xata init`):
 xata codegen
 ```
 
-In a TypeScript file start using the generated code:
+In a TypeScript file, start using the generated code like this:
 
 ```ts
-import { XataClient } from './xata';
+import { XataClient } from './xata'; // or wherever you chose to generate the client
 
-const xata = new XataClient({
-  fetch: fetchImplementation // Required if your runtime doesn't provide a global `fetch` function.
-});
+const xata = new XataClient();
 ```
 
-The import above will differ if you chose to genreate the code in a different location.
+The import above will differ if you chose to generate the code in a different location.
 
-The `fetch` paramter is required only if your runtime doesn't provide a global `fetch` function. There's also a `databaseURL` argument that by default will contain a URL pointing to your database (e.g. `https://myworkspace-123abc.xata.sh/db/databasename`), it can be specified in the constructor to overwrite that value if for whatever reason you need to connect to a different workspace or database.
+The `XataClient` constructor accepts an object with configuration options, like the `fetch` parameter, which is required only if your runtime doesn't provide a global `fetch` function. There's also a `databaseURL` argument that by default will contain a URL pointing to your database (e.g. `https://myworkspace-123abc.xata.sh/db/databasename`). It can be specified in the constructor to overwrite that value if for whatever reason you need to connect to a different workspace or database.
 
 The code generator will create two TypeScript types for each schema entity. The base one will be an `Identifiable` entity with the internal properties your entity has and the `Record` one will extend it with a set of operations (update, delete, etc...) and some schema metadata (xata version).
 
@@ -60,7 +76,7 @@ await admin.update({ email: 'admin@foo.bar' });
 await admin.delete();
 ```
 
-You will learn more about the available operations below, under the `API Design` section.
+You will learn more about the available operations below, under the [`API Design`](#api-design) section.
 
 ### Schema-less Client
 
@@ -78,15 +94,15 @@ const xata = new BaseClient({
 
 It works the same way as the code-generated `XataClient` but doesn't provide type-safety for your model.
 
-You can read more on the methods available below, under the `API Design` section.
+You can read more on the methods available below, in the next section.
 
 ### API Design
 
-The Xata SDK to create/read/update/delete records follows the repository pattern. Each table will have a repository object available at `xata.db.[table-name]`.
+The Xata SDK to create/read/update/delete records follows the [repository pattern](https://lyz-code.github.io/blue-book/architecture/repository_pattern/). Each table will have a repository object available at `xata.db.[table-name]`.
 
-For example if you have a `users` table there'll be a repository at `xata.db.users`. If you're using the schema-less client, you can also use the `xata.db.[table-name]` syntax to access the repository but without TypeScript auto-completion.
+For example if you have a `users` table, there'll be a repository at `xata.db.users`. If you're using the schema-less client, you can also use the `xata.db.[table-name]` syntax to access the repository but without TypeScript auto-completion.
 
-**Creating objects**
+#### Creating Objects
 
 Invoke the `create()` method in the repository. Example:
 
@@ -112,35 +128,35 @@ const user = await client.db.users.updateOrInsert('user_admin', {
 });
 ```
 
-**Query a single object by its id**
+#### Query a Single Object by its ID
 
 ```ts
 // `user` will be null if the object cannot be found
 const user = await xata.db.users.read('rec_1234abcdef');
 ```
 
-**Querying multiple objects**
+#### Querying Multiple Objects
 
 ```ts
 // Query objects selecting all fields.
-const users = await xata.db.users.select().getMany();
+const page = await xata.db.users.select().getPaginated();
 const user = await xata.db.users.select().getFirst();
 
 // You can also use `xata.db.users` directly, since it's an immutable Query too!
-const users = await xata.db.users.getMany();
+const page = await xata.db.users.getPaginated();
 const user = await xata.db.users.getFirst();
 
 // Query objects selecting just one or more fields
-const users = await xata.db.users.select('email', 'profile').getMany();
+const page = await xata.db.users.select('email', 'profile').getPaginated();
 
 // Apply constraints
-const users = await xata.db.users.filter('email', 'foo@example.com').getMany();
+const page = await xata.db.users.filter('email', 'foo@example.com').getPaginated();
 
 // Sorting
-const users = await xata.db.users.sort('fullName', 'asc').getMany();
+const page = await xata.db.users.sort('full_name', 'asc').getPaginated();
 ```
 
-Query operations (`select()`, `filter()`, `sort()`) return a `Query` object. These objects are immutable. You can add additional constraints, sort, etc. by calling their methods, and a new query will be returned. In order to finally make a query to the database you'll invoke `getAll()`, `getFirst()`, `getMany()` or `getPaginated()`.
+Query operations (`select()`, `filter()`, `sort()`) return a `Query` object. These objects are immutable. You can add additional constraints, `sort`, etc. by calling their methods, and a new query will be returned. In order to finally make a query to the database you'll invoke `getPaginated()`, `getMany()`, `getAll()`, or `getFirst()`.
 
 ```ts
 // Operators that combine multiple conditions can be deconstructed
@@ -154,19 +170,26 @@ filter('email', startsWith('username')).not(filter('created_at', gt(somePastDate
 // Queries are immutable objects. This is useful to derive queries from other queries
 const admins = filter('admin', true);
 const spaniardsAdmins = admins.filter('country', 'Spain');
-await admins.getMany(); // still returns all admins
+await admins.getAll(); // still returns all admins
 
 // Finally fetch the results of the query
-const users = await query.getMany();
+const users = await query.getAll();
 const firstUser = await query.getFirst();
+```
 
-// Also you can paginate the results
-const page = await query.getPaginated();
-const hasPage2 = page.hasNextPage();
-const page2 = await page.nextPage();
+The `getPaginated()` method will return a `Page` object. It's a wrapper that internally uses cursor based pagination.
+
+```ts
+page.records; // Array of records
+page.hasNextPage(); // Boolean
+
+const nextPage = await page.nextPage(); // Page object
+const previousPage = await page.previousPage(); // Page object
+const firstPage = await page.firstPage(); // Page object
+const lastPage = await page.lastPage(); // Page object
 ```
 
-If you want to use an iterator, both the Repository and the Query classes implement an AsyncIterable. Alternatively you can use `getIterator()` and customize the batch size of the iterator:
+If you want to use an iterator, both the Repository and the Query classes implement an `AsyncIterable`. Alternatively you can use `getIterator()` and customize the batch size of the iterator:
 
 ```ts
 for await (const record of xata.db.users) {
@@ -182,7 +205,7 @@ for await (const records of xata.db.users.getIterator({ batchSize: 100 })) {
 }
 ```
 
-**Updating objects**
+#### Updating Objects
 
 Updating an object leaves the existing instance unchanged, but returns a new object with the updated values.
 
@@ -198,7 +221,7 @@ const updatedUser = await xata.db.users.update('rec_1234abcdef', {
 });
 ```
 
-**Deleting objects**
+#### Deleting Objects
 
 ```ts
 // Using an existing object
@@ -208,26 +231,9 @@ await user.delete();
 await xata.db.users.delete('rec_1234abcdef');
 ```
 
-#### Deno support
-
-Right now we are still not publishing the client on deno.land or have support for deno in the codegen.
-
-However you can already use it with your preferred node CDN with the following import in the auto-generated `xata.ts` file:
-
-```ts
-import {
-  BaseClient,
-  Query,
-  Repository,
-  RestRespositoryFactory,
-  XataClientOptions,
-  XataRecord
-} from 'https://esm.sh/@xata.io/client@<version>/dist/schema?target=deno';
-```
-
 ### API Client
 
-One of the main features of the SDK is the ability to interact with the whole Xata API and perform administrative operations such as creating/reading/updating/deleting workspaces, databases, tables, branches...
+One of the main features of the SDK is the ability to interact with the whole Xata API and perform administrative operations such as creating/reading/updating/deleting [workspaces](https://docs.xata.io/concepts/workspaces), databases, tables, branches...
 
 To communicate with the SDK we provide a constructor called `XataApiClient` that accepts an API token and an optional fetch implementation method.
 
@@ -239,7 +245,6 @@ Once you have initialized the API client, the operations are organized following
 
 ```ts
 const { id: workspace } = await client.workspaces.createWorkspace({ name: 'example', slug: 'example' });
-
 const { databaseName } = await client.databases.createDatabase(workspace, 'database');
 
 await client.branches.createBranch(workspace, databaseName, 'branch');
@@ -256,3 +261,11 @@ const record = await client.records.getRecord(workspace, databaseName, 'branch',
 
 await client.workspaces.deleteWorkspace(workspace);
 ```
+
+## Deno support
+
+We publish the client on [deno.land](https://deno.land/x/xata). You can use it by changing the import in the auto-generated `xata.ts` file:
+
+```ts
+import { buildClient, BaseClientOptions, XataRecord } from 'https://deno.land/x/xata/mod.ts';
+```

package/Usage.md

@@ -0,0 +1,395 @@
+# Xata SDK Reference
+
+There are four types of objects in the Xata TypeScript SDK. In this document, we will understand them deeper to better work with the Xata SDK.
+
+- `Query`: a combination of filters and other parameters to retrieve a collection of records.
+- `Repository`: a table representation that can be used to create, read, update, and delete records.
+- `XataRecord`: a row in a table.
+- `Page`: a collection of records that can be paginated.
+
+Let's explore them below.
+
+## Table of Contents
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+- [Query](#query)
+  - [Column selection](#column-selection)
+  - [Sorting](#sorting)
+  - [Filtering](#filtering)
+  - [Combining queries](#combining-queries)
+- [Repository](#repository)
+  - [Reading records](#reading-records)
+  - [Creating records](#creating-records)
+  - [Updating records](#updating-records)
+  - [Deleting records](#deleting-records)
+  - [Searching records](#searching-records)
+- [Page](#page)
+  - [Iterators and generators](#iterators-and-generators)
+  - [Helper variables](#helper-variables)
+- [XataRecord](#xatarecord)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+## Query
+
+To get a collection of records, you can use the `Query` object. It provides the following methods:
+
+- `getFirst()`: returns the first record in the query results.
+- `getPaginated()`: returns a page of records in the query results.
+- `getAll()`: returns all the records in the query results.
+- `getMany()`: returns an array of some records in the query results.
+
+Since the [`Repository`](#repository) class implements the `Query` interface, you can use it to query and paginate the records in the table too.
+
+```ts
+const user = xata.db.users.getFirst();
+```
+
+### Column selection
+
+The `Query` object can be used to select the columns that will be returned in the results. You can pick multiple columns by providing an array of column names, or you can pick all the columns by providing `*`.
+
+The dot notation is supported to select columns from nested objects.
+
+```ts
+const user = xata.db.users.select(['*', 'team.*']).getFirst();
+```
+
+### Sorting
+
+The `Query` object can be used to sort the order of the results. You can sort the results by providing a column name and an `asc` or `desc` string.
+
+```ts
+const user = xata.db.users.orderBy('fullName', 'asc').getFirst();
+```
+
+### Filtering
+
+You can filter the results by providing the column and the value to filter.
+
+```ts
+const user = xata.db.users.filter('fullName', 'John').getFirst();
+```
+
+To combine multiple filters in an 'AND' clause, you can pipe the filters together.
+
+```ts
+const user = xata.db.users.filter('fullName', 'John').filter('team.name', 'Marketing').getFirst();
+```
+
+Also you can filter the results by providing a `filter` object.
+
+```ts
+const user = xata.db.users.filter({ fullName: 'John', 'team.name': 'Marketing' }).getFirst();
+```
+
+We offer some helper functions to build the filter values, like: `gt`, `ge`, `gte`, `lt`, `le`, `lte`, `exists`, `notExists`, `startsWith`, `endsWith`, `pattern`, `is`, `isNot`, `contains`, `includes`, and others specific to the type of the column.
+
+```ts
+const user = xata.db.users.filter('name', startsWith('Bar')).getFirst();
+```
+
+If you prefer to directly use the filter operators as in the API, you can add them in the `filter` object.
+
+```ts
+xata.db.users.filter({ full_name: { $startsWith: 'foo' } }).getFirst();
+```
+
+### Combining Queries
+
+Queries can be stored in variables and can be combined with other queries.
+
+```ts
+const johnQuery = xata.db.users.filter('fullName', 'John');
+const janeQuery = xata.db.users.filter('fullName', 'Jane');
+
+const johns = await johnQuery.getAll();
+const janes = await janeQuery.getAll();
+
+const users = await xata.db.users.any(johnQuery, janeQuery).getAll();
+```
+
+We offer the following helper methods to combine queries:
+
+- `any()`: returns the records that match any of the queries.
+- `all()`: returns the records that match all of the queries.
+- `none()`: returns the records that match none of the queries.
+- `not()`: returns the records that don't match the given query.
+
+You can read more about the query operators in the API section for the query table endpoint.
+
+## Repository
+
+Any table in the database can be represented by a `Repository` object. A repository is an object that can be used to create, read, update, and delete records in the table it represents. It also implements the `Query` and `Page` interfaces, so you can use it to query and paginate the records in the table too.
+
+We'll see how to use these objects in the next section.
+
+### Reading records
+
+The `read()` method can be used to read records by their ids:
+
+- If the object cannot be found, the method will return `null`.
+- If the object can be found, the method will return a `XataRecord` object.
+
+You can read a single record by its id.
+
+```ts
+const user = await xata.db.users.read('rec_1234abcdef');
+```
+
+You can also read multiple records by their ids.
+
+```ts
+const users = await xata.db.users.read(['rec_1234abcdef', 'rec_5678defgh']);
+```
+
+And you can read records coming from an object that contains an `id` property.
+
+```ts
+const object1 = { id: 'rec_1234abcdef' };
+const object2 = { id: 'rec_5678defgh' };
+
+const user = await xata.db.users.read(object1);
+const users = await xata.db.users.read([object1, object2]);
+```
+
+### Creating Records
+
+Both the `create()` and `createOrUpdate()` methods can be used to create a new record.
+
+- The `create()` method will create a new record and fail if the provided id already exists.
+- The `createOrUpdate()` method will create a new record if the provided id doesn't exist, or update an existing record if it does.
+
+You can create a record without providing an id, and the id will be generated automatically.
+
+```ts
+const user = await xata.db.users.create({ fullName: 'John Smith' });
+user.id; // 'rec_1234abcdef'
+```
+
+You can create a record with an id as parameter, and the id will be used.
+
+```ts
+const user = await xata.db.users.create('user_admin', { fullName: 'John Smith' });
+user.id; // 'user_admin'
+```
+
+You can create a record with the id provided in the object, and the id will be used.
+
+```ts
+const user = await xata.db.users.create({ id: 'user_admin', fullName: 'John Smith' });
+user.id; // 'user_admin'
+```
+
+You can create multiple records at once by providing an array of objects.
+
+```ts
+const users = await xata.db.users.create([{ fullName: 'John Smith' }, { id: 'user_admin', fullName: 'Jane Doe' }]);
+users[0].id; // 'rec_1234abcdef'
+users[1].id; // 'user_admin'
+```
+
+The `createOrUpdate()` method beaves the same way as `create()` but you will always need to provide an id.
+
+```ts
+const user1 = await xata.db.users.createOrUpdate('user_admin', { fullName: 'John Smith' });
+const user2 = await xata.db.users.createOrUpdate({ id: 'user_manager', fullName: 'Jane Doe' });
+const users = await xata.db.users.createOrUpdate([
+  { id: 'user_admin', fullName: 'John Smith' },
+  { id: 'user_manager', fullName: 'Jane Doe' }
+]);
+```
+
+### Updating records
+
+The `update()` method can be used to update an existing record. It will throw an `Error` if the record cannot be found.
+
+```ts
+const user = await xata.db.users.update('rec_1234abcdef', { fullName: 'John Smith' });
+```
+
+The `id` property can also be sent in the object update.
+
+```ts
+const user = await xata.db.users.update({ id: 'user_admin', fullName: 'John Smith' });
+```
+
+You can update multiple records at once by providing an array of objects.
+
+```ts
+const users = await xata.db.users.update([
+  { id: 'rec_1234abcdef', fullName: 'John Smith' },
+  { id: 'user_admin', fullName: 'Jane Doe' }
+]);
+```
+
+### Deleting Records
+
+The `delete()` method can be used to delete an existing record. It will throw an `Error` if the record cannot be found.
+
+```ts
+const user = await xata.db.users.delete('rec_1234abcdef');
+```
+
+You can delete multiple records at once by providing an array of ids.
+
+```ts
+const users = await xata.db.users.delete(['rec_1234abcdef', 'user_admin']);
+```
+
+You can delete records coming from an object that contains an `id` property.
+
+```ts
+const object1 = { id: 'rec_1234abcdef' };
+
+const user = await xata.db.users.delete(object1);
+```
+
+You can delete records coming from an array of objects that contain an `id` property.
+
+```ts
+const object1 = { id: 'rec_1234abcdef' };
+const object2 = { id: 'user_admin' };
+
+const users = await xata.db.users.delete([object1, object2]);
+```
+
+### Searching Records
+
+The `search()` method can be used to search records. It returns an array of records.
+
+```ts
+const results = await xata.db.users.search('John');
+```
+
+Also you can customize the results with an `options` object that includes `fuzziness`, `filter` and all the other options the API supports.
+
+```ts
+const results = await xata.db.users.search('John', { fuzziness: 1, filter: { 'team.name': 'Marketing' } });
+```
+
+## Page
+
+Some methods of the `Query` interface provide a `Page` object as a return value that can be used to paginate the results. The `Page` object can be used to get the queried records of a table in pages. It is an abstraction of cursor-based pagination.
+
+It contains:
+
+- `records`: Array of `XataRecord` objects.
+- `hasNextPage`: Function that returns a boolean indicating if there is a next page.
+- `nextPage`: Async function that can be used to get the next page.
+- `previousPage`: Async function that can be used to get the previous page.
+- `firstPage`: Async function that can be used to get the first page.
+- `lastPage`: Async function that can be used to get the last page.
+- `meta`: Information about the current page and its cursor.
+
+```ts
+const page = await xata.db.users.getPaginated();
+page.records; // Array of `XataRecord` objects.
+page.hasNextPage();
+
+const page2 = await page.nextPage();
+page2.records; // Array of `XataRecord` objects.
+
+const page1 = await page2.previousPage();
+page1.records; // Array of `XataRecord` objects.
+
+const firstPage = await page1.firstPage();
+firstPage.records; // Array of `XataRecord` objects.
+```
+
+The `Repository` class implements the `Query` interface, so you can use it to paginate the records in the table too.
+
+```ts
+const page = await xata.db.users.firstPage();
+page.records; // Array of `XataRecord` objects.
+```
+
+The array returned in `records` also implements the `Page` interface.
+
+```ts
+const { records } = await xata.db.users.getPaginated();
+records.hasNextPage();
+const { records: page2Records } = await records.nextPage();
+```
+
+Optionally, you can provide `offset` and `size` parameters to the pagination and override the default values.
+
+```ts
+const page = await xata.db.users.getPaginated();
+page.records; // Array of `XataRecord` objects.
+
+// A second page with size 50
+const page2 = await page.nextPage(50);
+
+// A third page with size 10 but an offset of 60
+const page3 = await page2.nextPage(10, 60);
+```
+
+### Iterators and Generators
+
+The `Query` object can be used to iterate over the results as a way to paginate the results.
+
+```ts
+for await (const user of xata.db.users) {
+  await user.update({ full_name: 'John Doe' });
+}
+```
+
+Also if you want to retrieve more than one record at a time in the iterator, you can use the `getIterator()` method.
+
+```ts
+for await (const users of xata.db.users.getIterator({ batchSize: 50 })) {
+  console.log(users);
+}
+```
+
+### Helper Variables
+
+We expose some helper variables of the API limits when paginating:
+
+- `PAGINATION_MAX_SIZE`: Maximum page size.
+- `PAGINATION_DEFAULT_SIZE`: Default page size.
+- `PAGINATION_MAX_OFFSET`: Maximum offset.
+- `PAGINATION_DEFAULT_OFFSET`: Default offset.
+
+You can use these variables if you implement your own pagination mechanism, as they will be updated when our API limits are updated.
+
+## XataRecord
+
+Every row in a table is represented by an `XataRecord` object.
+
+It contains an `id` property that represents the unique identifier of the record and all the fields of the table.
+
+Also it provides some methods to read again, update or delete the record.
+
+```ts
+const user = await xata.db.users.read('rec_1234abcdef');
+user?.id; // 'rec_1234abcdef'
+user?.fullName; // 'John Smith'
+user?.read(); // Reads the record again
+user?.update({ fullName: 'John Doe' }); // Partially updates the record
+user?.delete(); // Deletes the record
+```
+
+If the table contains a link property, it will be represented as a `Link` object containing its `id` property and methods to read again or update the linked record.
+
+```ts
+const user = await xata.db.users.read('rec_1234abcdef');
+user?.team?.id; // 'rec_5678defgh'
+user?.team?.read(); // Reads the linked record properties
+user?.team?.update({ name: 'A team' }); // Partially updates the linked record
+```
+
+When working with `queries` you can expand the properties returned in a `XataRecord` object.
+
+By default only the current table fields are returned, and the id of any linked record.
+
+```ts
+const user = await xata.db.users.filter('id', 'rec_1234abcdef').select(['*', 'team.*']).getFirst();
+user?.id; // 'rec_1234abcdef'
+user?.fullName; // 'John Smith'
+user?.team?.id; // 'rec_5678defgh'
+user?.team?.name; // 'A team'
+```