@xata.io/client 0.13.1 → 0.13.4

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @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

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,14 +128,14 @@ 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.
@@ -140,7 +156,7 @@ const page = await xata.db.users.filter('email', 'foo@example.com').getPaginated
 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 `getPaginated()`, `getMany()`, `getAll()`, or `getFirst()`.
+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
@@ -173,7 +189,7 @@ 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) {
@@ -189,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.
 
@@ -205,7 +221,7 @@ const updatedUser = await xata.db.users.update('rec_1234abcdef', {
 });
 ```
 
-**Deleting objects**
+#### Deleting Objects
 
 ```ts
 // Using an existing object
@@ -217,7 +233,7 @@ await xata.db.users.delete('rec_1234abcdef');
 
 ### 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.
 
@@ -229,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');
@@ -249,17 +264,8 @@ await client.workspaces.deleteWorkspace(workspace);
 
 ## 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:
+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 {
-  BaseClient,
-  Query,
-  Repository,
-  RestRespositoryFactory,
-  XataClientOptions,
-  XataRecord
-} from 'https://esm.sh/@xata.io/client@<version>/dist/schema?target=deno';
+import { buildClient, BaseClientOptions, XataRecord } from 'https://deno.land/x/xata/mod.ts';
 ```

package/Usage.md

@@ -1,23 +1,134 @@
-# TypeScript SDK
+# Xata SDK Reference
 
-There're four types of objects in the Xata TypeScript SDK:
+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.
 
-- `Repository`: a table representation that can be used to create, read, update, and delete records.
 - `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.
 
-## Repository
+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.
 
-Any table in the database can be represented by a `Repository` object.
+## Repository
 
-A repository is an object that can be used to create, read, update, and delete records in the table it represents.
+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.
 
-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.
+We'll see how to use these objects in the next section.
 
 ### Reading records
 
-The `read()` method can be used to read a records by their ids:
+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.
@@ -44,7 +155,7 @@ const user = await xata.db.users.read(object1);
 const users = await xata.db.users.read([object1, object2]);
 ```
 
-### Creating records
+### Creating Records
 
 Both the `create()` and `createOrUpdate()` methods can be used to create a new record.
 
@@ -93,7 +204,7 @@ const users = await xata.db.users.createOrUpdate([
 
 ### Updating records
 
-The `update()` method can be used to update an existing record. It will throw an Error if the record cannot be found.
+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' });
@@ -114,9 +225,9 @@ const users = await xata.db.users.update([
 ]);
 ```
 
-### Deleting records
+### Deleting Records
 
-The `delete()` method can be used to delete an existing record. It will throw an Error if the record cannot be found.
+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');
@@ -145,7 +256,7 @@ const object2 = { id: 'user_admin' };
 const users = await xata.db.users.delete([object1, object2]);
 ```
 
-### Searching records
+### Searching Records
 
 The `search()` method can be used to search records. It returns an array of records.
 
@@ -159,105 +270,9 @@ Also you can customize the results with an `options` object that includes `fuzzi
 const results = await xata.db.users.search('John', { fuzziness: 1, filter: { 'team.name': 'Marketing' } });
 ```
 
-## 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` 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.
-
 ## 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.
+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:
 
@@ -299,7 +314,7 @@ records.hasNextPage();
 const { records: page2Records } = await records.nextPage();
 ```
 
-Optionally you can provide `offset` and `size` parameters to the pagination and override the default values.
+Optionally, you can provide `offset` and `size` parameters to the pagination and override the default values.
 
 ```ts
 const page = await xata.db.users.getPaginated();
@@ -312,7 +327,7 @@ const page2 = await page.nextPage(50);
 const page3 = await page2.nextPage(10, 60);
 ```
 
-### Iterators and generators
+### Iterators and Generators
 
 The `Query` object can be used to iterate over the results as a way to paginate the results.
 
@@ -330,7 +345,7 @@ for await (const users of xata.db.users.getIterator({ batchSize: 50 })) {
 }
 ```
 
-### Helper variables
+### Helper Variables
 
 We expose some helper variables of the API limits when paginating:
 
@@ -339,7 +354,7 @@ We expose some helper variables of the API limits when paginating:
 - `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 the API limits are updated.
+You can use these variables if you implement your own pagination mechanism, as they will be updated when our API limits are updated.
 
 ## XataRecord
 

package/dist/index.cjs

@@ -21,7 +21,8 @@ function toBase64(value) {
   try {
     return btoa(value);
   } catch (err) {
-    return Buffer.from(value).toString("base64");
+    const buf = Buffer;
+    return buf.from(value).toString("base64");
   }
 }
 
@@ -77,7 +78,7 @@ function getFetchImplementation(userFetch) {
   return fetchImpl;
 }
 
-const VERSION = "0.13.1";
+const VERSION = "0.13.4";
 
 class ErrorWithCause extends Error {
   constructor(message, options) {
@@ -85,15 +86,20 @@ class ErrorWithCause extends Error {
   }
 }
 class FetcherError extends ErrorWithCause {
-  constructor(status, data) {
+  constructor(status, data, requestId) {
     super(getMessage(data));
     this.status = status;
     this.errors = isBulkError(data) ? data.errors : void 0;
+    this.requestId = requestId;
     if (data instanceof Error) {
       this.stack = data.stack;
       this.cause = data.cause;
     }
   }
+  toString() {
+    const error = super.toString();
+    return `[${this.status}] (${this.requestId ?? "Unknown"}): ${error}`;
+  }
 }
 function isBulkError(error) {
   return isObject(error) && Array.isArray(error.errors);
@@ -170,14 +176,15 @@ async function fetch$1({
   if (response.status === 204) {
     return {};
   }
+  const requestId = response.headers?.get("x-request-id") ?? void 0;
   try {
     const jsonResponse = await response.json();
     if (response.ok) {
       return jsonResponse;
     }
-    throw new FetcherError(response.status, jsonResponse);
+    throw new FetcherError(response.status, jsonResponse, requestId);
   } catch (error) {
-    throw new FetcherError(response.status, error);
+    throw new FetcherError(response.status, error, requestId);
   }
 }
 
@@ -988,10 +995,20 @@ function isCursorPaginationOptions(options) {
 }
 const _RecordArray = class extends Array {
   constructor(page, overrideRecords) {
-    super(...overrideRecords ?? page.records);
+    super(..._RecordArray.parseConstructorParams(page, overrideRecords));
     __privateAdd$6(this, _page, void 0);
     __privateSet$5(this, _page, page);
   }
+  static parseConstructorParams(...args) {
+    if (args.length === 1 && typeof args[0] === "number") {
+      return new Array(args[0]);
+    }
+    if (args.length <= 2 && isObject(args[0]?.meta) && Array.isArray(args[1] ?? [])) {
+      const result = args[1] ?? args[0].records ?? [];
+      return new Array(...result);
+    }
+    return new Array(...args);
+  }
   async nextPage(size, offset) {
     const newPage = await __privateGet$6(this, _page).nextPage(size, offset);
     return new _RecordArray(newPage);