@xata.io/client 0.0.0-alpha.vf45a2df → 0.0.0-alpha.vf4752f8

package/CHANGELOG.md

@@ -1,5 +1,93 @@
 # @xata.io/client
 
+## 0.17.1
+
+### Patch Changes
+
+- [#584](https://github.com/xataio/client-ts/pull/584) [`a305072`](https://github.com/xataio/client-ts/commit/a3050726517632b4975f2a2ed5f771dd247e51d5) Thanks [@SferaDev](https://github.com/SferaDev)! - Fix issues with multiple filters
+
+* [#249](https://github.com/xataio/client-ts/pull/249) [`7812a41`](https://github.com/xataio/client-ts/commit/7812a414b7d99e9515c0ce48a61ad7a8b84d65d0) Thanks [@xata-bot](https://github.com/xata-bot)! - API: Add first endpoints for migration requests and schema compare
+
+- [#585](https://github.com/xataio/client-ts/pull/585) [`d4a8ced`](https://github.com/xataio/client-ts/commit/d4a8ced9c257058ed7f660e01ee5fd1da154c391) Thanks [@SferaDev](https://github.com/SferaDev)! - Fix problem with some special characters not being URI encoded
+
+* [#574](https://github.com/xataio/client-ts/pull/574) [`cf85b13`](https://github.com/xataio/client-ts/commit/cf85b13e1ca69e79100fd02f58d79d556012395d) Thanks [@SferaDev](https://github.com/SferaDev)! - Do not allow unknown tables on codegen output
+
+- [#576](https://github.com/xataio/client-ts/pull/576) [`2350739`](https://github.com/xataio/client-ts/commit/2350739d3f0a176b0f1fc77b0f4f597321349726) Thanks [@SferaDev](https://github.com/SferaDev)! - Allow sending empty, undefined or conditional filters
+
+* [#581](https://github.com/xataio/client-ts/pull/581) [`a336e61`](https://github.com/xataio/client-ts/commit/a336e6161be04a652e6f0f0a4c2edac10d50c99e) Thanks [@SferaDev](https://github.com/SferaDev)! - Update error codes in tracing
+
+## 0.17.0
+
+### Minor Changes
+
+- [#563](https://github.com/xataio/client-ts/pull/563) [`26e91d1`](https://github.com/xataio/client-ts/commit/26e91d1d84df082dedd7159271fc7c27ec87fefe) Thanks [@SferaDev](https://github.com/SferaDev)! - Return nulls on operations that can fail
+
+* [#563](https://github.com/xataio/client-ts/pull/563) [`3332d43`](https://github.com/xataio/client-ts/commit/3332d43121367f61c8d87dfb7da2af65bd1c278f) Thanks [@SferaDev](https://github.com/SferaDev)! - Return object on delete operation
+
+## 0.16.2
+
+### Patch Changes
+
+- [#541](https://github.com/xataio/client-ts/pull/541) [`c74467c`](https://github.com/xataio/client-ts/commit/c74467caeff4e3d60d0981a173b462e970c6c1fc) Thanks [@SferaDev](https://github.com/SferaDev)! - Add tracing with open telemetry
+
+* [#551](https://github.com/xataio/client-ts/pull/551) [`ee72bfe`](https://github.com/xataio/client-ts/commit/ee72bfef34765374ec66c7edaa6b5508c3f8e8dc) Thanks [@SferaDev](https://github.com/SferaDev)! - Fix filter operators and dates
+
+- [#552](https://github.com/xataio/client-ts/pull/552) [`e88effa`](https://github.com/xataio/client-ts/commit/e88effa00f8c2c0e24ec8cd60fb21859ac236191) Thanks [@SferaDev](https://github.com/SferaDev)! - Update error message for required settings
+
+* [#551](https://github.com/xataio/client-ts/pull/551) [`33293b3`](https://github.com/xataio/client-ts/commit/33293b3509d984bb9b1af457c96260d43f398efe) Thanks [@SferaDev](https://github.com/SferaDev)! - Add aliases for some operators
+
+- [#534](https://github.com/xataio/client-ts/pull/534) [`efc09b4`](https://github.com/xataio/client-ts/commit/efc09b420a25253b428662c2eec40ff3bc36ce79) Thanks [@SferaDev](https://github.com/SferaDev)! - Make sort direction optional
+
+## 0.16.1
+
+### Patch Changes
+
+- [#531](https://github.com/xataio/client-ts/pull/531) [`e33d8fb`](https://github.com/xataio/client-ts/commit/e33d8fbca264d3ab1597ed698d5e79484dcba8a3) Thanks [@xata-bot](https://github.com/xata-bot)! - Add new method to list database metadata in the API client
+
+* [#524](https://github.com/xataio/client-ts/pull/524) [`a3b1044`](https://github.com/xataio/client-ts/commit/a3b1044038c4ae73b4aacaa112818e69b7d380e1) Thanks [@SferaDev](https://github.com/SferaDev)! - Expose internal config information
+
+- [#525](https://github.com/xataio/client-ts/pull/525) [`5f0f2c2`](https://github.com/xataio/client-ts/commit/5f0f2c2bb42da360e810f0a61ce360f8f8b07a04) Thanks [@xata-bot](https://github.com/xata-bot)! - Update dependencies
+
+## 0.16.0
+
+### Minor Changes
+
+- [#485](https://github.com/xataio/client-ts/pull/485) [`a9cbb26`](https://github.com/xataio/client-ts/commit/a9cbb263fbca47cb91a827db252d95a5bb4079a6) Thanks [@SferaDev](https://github.com/SferaDev)! - Allow selecting columns with record operations
+
+* [#485](https://github.com/xataio/client-ts/pull/485) [`7e04a3d`](https://github.com/xataio/client-ts/commit/7e04a3d1c51958a44f687a0036ead8bb3f5a2dfb) Thanks [@SferaDev](https://github.com/SferaDev)! - Remove record cache
+
+### Patch Changes
+
+- [#503](https://github.com/xataio/client-ts/pull/503) [`6a96ea5`](https://github.com/xataio/client-ts/commit/6a96ea5da4c5b7ca9a99b57ebbce8d6766b5d4d8) Thanks [@xata-bot](https://github.com/xata-bot)! - Update API response types for create of tables and branches
+
+* [#421](https://github.com/xataio/client-ts/pull/421) [`43f2560`](https://github.com/xataio/client-ts/commit/43f25605ddd0d2fd514a1542a14389d28955c500) Thanks [@SferaDev](https://github.com/SferaDev)! - Add search boosters and allow prefix search
+
+## 0.15.0
+
+### Patch Changes
+
+- [#496](https://github.com/xataio/client-ts/pull/496) [`e923d11`](https://github.com/xataio/client-ts/commit/e923d11fe357519dc4ca3ae722670e6e70ccd1c6) Thanks [@gimenete](https://github.com/gimenete)! - Ignore git output in Xata client
+
+* [#481](https://github.com/xataio/client-ts/pull/481) [`599b52c`](https://github.com/xataio/client-ts/commit/599b52c3090222eedef85d1ad1e907874cd3e801) Thanks [@xata-bot](https://github.com/xata-bot)! - Add updateWorkspaceMemberInvite API method
+
+## 0.14.0
+
+### Minor Changes
+
+- [#409](https://github.com/xataio/client-ts/pull/409) [`8812380`](https://github.com/xataio/client-ts/commit/881238062b5eeac2dc8b9ba156720e0acc22c5c5) Thanks [@SferaDev](https://github.com/SferaDev)! - Infer types from schema in codegen
+
+* [#457](https://github.com/xataio/client-ts/pull/457) [`0584a5b`](https://github.com/xataio/client-ts/commit/0584a5b207a21dbc36ddc1d44b276f1d5bb60dc5) Thanks [@SferaDev](https://github.com/SferaDev)! - Load env variables so that code analysis detects them
+
+- [#469](https://github.com/xataio/client-ts/pull/469) [`8d8a912`](https://github.com/xataio/client-ts/commit/8d8a9129e36452266c4c12fe35b421f66e572498) Thanks [@gimenete](https://github.com/gimenete)! - Treat branch name specified with third party env variables as git branches in the resolution algorithm
+
+### Patch Changes
+
+- [#462](https://github.com/xataio/client-ts/pull/462) [`7547b7e`](https://github.com/xataio/client-ts/commit/7547b7edbc9a95c6620784cc5348316f27502c73) Thanks [@SferaDev](https://github.com/SferaDev)! - Fix bug with RecordArray.map
+
+* [#472](https://github.com/xataio/client-ts/pull/472) [`e99010c`](https://github.com/xataio/client-ts/commit/e99010c9ab9d355abadcfbcf98b5a3fcc80c307a) Thanks [@SferaDev](https://github.com/SferaDev)! - Add id as entity property
+
+- [#443](https://github.com/xataio/client-ts/pull/443) [`c4be404`](https://github.com/xataio/client-ts/commit/c4be404a3ecb34df9b1ef4501c92f5bdc221f19c) Thanks [@SferaDev](https://github.com/SferaDev)! - Improve performance with `create([])` operation
+
 ## 0.13.4
 
 ### Patch Changes

package/README.md

@@ -12,11 +12,11 @@ This SDK has zero dependencies, so it can be used in many JavaScript runtimes in
   - [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)
+    - [Creating Records](#creating-records)
+    - [Query a Single Record by its ID](#query-a-single-record-by-its-id)
+    - [Querying Multiple Records](#querying-multiple-records)
+    - [Updating Records](#updating-records)
+    - [Deleting Records](#deleting-records)
   - [API Client](#api-client)
 - [Deno support](#deno-support)
 
@@ -102,7 +102,7 @@ The Xata SDK to create/read/update/delete records follows the [repository patter
 
 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 Records
 
 Invoke the `create()` method in the repository. Example:
 
@@ -123,22 +123,22 @@ const user = await xata.db.users.insert('user_admin', {
 And if you want to create or insert a record with a specific ID, you can invoke `updateOrInsert()`.
 
 ```ts
-const user = await client.db.users.updateOrInsert('user_admin', {
+const user = await xata.db.users.updateOrInsert('user_admin', {
   fullName: 'John Smith'
 });
 ```
 
-#### Query a Single Object by its ID
+#### Query a Single Record by its ID
 
 ```ts
-// `user` will be null if the object cannot be found
+// `user` will be null if the record cannot be found
 const user = await xata.db.users.read('rec_1234abcdef');
 ```
 
-#### Querying Multiple Objects
+#### Querying Multiple Records
 
 ```ts
-// Query objects selecting all fields.
+// Query records selecting all fields.
 const page = await xata.db.users.select().getPaginated();
 const user = await xata.db.users.select().getFirst();
 
@@ -146,7 +146,7 @@ const user = await xata.db.users.select().getFirst();
 const page = await xata.db.users.getPaginated();
 const user = await xata.db.users.getFirst();
 
-// Query objects selecting just one or more fields
+// Query records selecting just one or more fields
 const page = await xata.db.users.select('email', 'profile').getPaginated();
 
 // Apply constraints
@@ -158,6 +158,8 @@ 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()`.
 
+To learn the differences between these methods, see the [reference](https://docs.xata.io/sdk/reference#query).
+
 ```ts
 // Operators that combine multiple conditions can be deconstructed
 const { filter, any, all, not, sort } = xata.db.users;
@@ -205,9 +207,9 @@ for await (const records of xata.db.users.getIterator({ batchSize: 100 })) {
 }
 ```
 
-#### Updating Objects
+#### Updating Records
 
-Updating an object leaves the existing instance unchanged, but returns a new object with the updated values.
+Updating a record leaves the existing object unchanged, but returns a new object with the updated values.
 
 ```ts
 // Using an existing object
@@ -215,19 +217,19 @@ const updatedUser = await user.update({
   fullName: 'John Smith Jr.'
 });
 
-// Using an object's id
+// Using a record id
 const updatedUser = await xata.db.users.update('rec_1234abcdef', {
   fullName: 'John Smith Jr.'
 });
 ```
 
-#### Deleting Objects
+#### Deleting Records
 
 ```ts
 // Using an existing object
 await user.delete();
 
-// Using an object's id
+// Using a record id
 await xata.db.users.delete('rec_1234abcdef');
 ```
 
@@ -244,22 +246,22 @@ const api = new XataApiClient({ apiKey: process.env.XATA_API_KEY });
 Once you have initialized the API client, the operations are organized following the same hiearchy as in the [official documentation](https://docs.xata.io). You have different namespaces for each entity (ie. `workspaces`, `databases`, `tables`, `branches`, `users`, `records`...).
 
 ```ts
-const { id: workspace } = await client.workspaces.createWorkspace({ name: 'example', slug: 'example' });
-const { databaseName } = await client.databases.createDatabase(workspace, 'database');
+const { id: workspace } = await api.workspaces.createWorkspace({ name: 'example', slug: 'example' });
+const { databaseName } = await api.databases.createDatabase(workspace, 'database');
 
-await client.branches.createBranch(workspace, databaseName, 'branch');
-await client.tables.createTable(workspace, databaseName, 'branch', 'table');
-await client.tables.setTableSchema(workspace, databaseName, 'branch', 'table', {
+await api.branches.createBranch(workspace, databaseName, 'branch');
+await api.tables.createTable(workspace, databaseName, 'branch', 'table');
+await api.tables.setTableSchema(workspace, databaseName, 'branch', 'table', {
   columns: [{ name: 'email', type: 'string' }]
 });
 
-const { id: recordId } = await client.records.insertRecord(workspace, databaseName, 'branch', 'table', {
+const { id: recordId } = await api.records.insertRecord(workspace, databaseName, 'branch', 'table', {
   email: 'example@foo.bar'
 });
 
-const record = await client.records.getRecord(workspace, databaseName, 'branch', 'table', recordId);
+const record = await api.records.getRecord(workspace, databaseName, 'branch', 'table', recordId);
 
-await client.workspaces.deleteWorkspace(workspace);
+await api.workspaces.deleteWorkspace(workspace);
 ```
 
 ## Deno support

package/Usage.md

@@ -38,8 +38,29 @@ To get a collection of records, you can use the `Query` object. It provides the
 
 - `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.
+- `getAll()`: returns all the records in the query results by making multiple requests to iterate over all the pages which exist. If the query is not filtered and the table is a large dataset, this operation can affect the performance.
+- `getMany()`: returns an array with a subset of the first results in the query. The default [pagination](#page) size (20) is used and can be customised by passing a different `{ pagination: { size: number } }` in its options. To learn more about default values, see [helper variables](#helper-variables).
+
+All these methods allow customising its filters, column selection, column ordering, pagination or cache TTL. For example:
+
+```ts
+// First item sorting by name
+const user = await xata.db.users.getFirst({ sort: 'name' });
+
+// Get first 50 items but ignore the first one
+const users = await xata.db.users.getMany({ pagination: { size: 50, offset: 1 } });
+
+// Get page of 100 items where name contains "foo"
+const page = await xata.db.users.getPaginated({ filter: { name: { $contains: 'foo' } }, pagination: { size: 100 } });
+
+// Get all admin users and cache the result for 5 minutes
+const user = await xata.db.users.filter('role', 'admin').getAll({ cache: 5 * 60 * 1000 });
+
+// Overwrite values set in a query
+const query = xata.db.users.filter('role', 'admin').select(['name']);
+const adminUsers = await query.getAll();
+const firstAdminUserWithEmail = await query.getFirst({ columns: ['name', 'email'] });
+```
 
 Since the [`Repository`](#repository) class implements the `Query` interface, you can use it to query and paginate the records in the table too.
 
@@ -155,6 +176,13 @@ const user = await xata.db.users.read(object1);
 const users = await xata.db.users.read([object1, object2]);
 ```
 
+By default an object with the first level properties is returned. If you want to reduce or expand its columns, you can pass an array of columns to the `read()` method.
+
+```ts
+const user = await xata.db.users.read('rec_1234abcdef', ['fullName', 'team.name']);
+const users = await xata.db.users.read(['rec_1234abcdef', 'rec_5678defgh'], ['fullName', 'team.name']);
+```
+
 ### Creating Records
 
 Both the `create()` and `createOrUpdate()` methods can be used to create a new record.
@@ -202,6 +230,19 @@ const users = await xata.db.users.createOrUpdate([
 ]);
 ```
 
+By default, the `create` and `createOrUpdate` methods will return the created record with the first level properties. If you want to reduce or expand its columns, you can pass an array of columns to the `create` or `createOrUpdate` method.
+
+```ts
+const user = await xata.db.users.create('user_admin', { fullName: 'John Smith' }, ['fullName', 'team.name']);
+const users = await xata.db.users.createOrUpdate(
+  [
+    { id: 'user_admin', fullName: 'John Smith' },
+    { id: 'user_manager', fullName: 'Jane Doe' }
+  ],
+  ['fullName', 'team.name']
+);
+```
+
 ### Updating records
 
 The `update()` method can be used to update an existing record. It will throw an `Error` if the record cannot be found.
@@ -225,6 +266,12 @@ const users = await xata.db.users.update([
 ]);
 ```
 
+By default, the `update` method will return the updated record with the first level properties. If you want to reduce or expand its columns, you can pass an array of columns to the `update` method.
+
+```ts
+const user = await xata.db.users.update('rec_1234abcdef', { fullName: 'John Smith' }, ['fullName', 'team.name']);
+```
+
 ### Deleting Records
 
 The `delete()` method can be used to delete an existing record. It will throw an `Error` if the record cannot be found.
@@ -349,10 +396,10 @@ for await (const users of xata.db.users.getIterator({ batchSize: 50 })) {
 
 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.
+- `PAGINATION_MAX_SIZE`: Maximum page size (200).
+- `PAGINATION_DEFAULT_SIZE`: Default page size (20).
+- `PAGINATION_MAX_OFFSET`: Maximum offset (800).
+- `PAGINATION_DEFAULT_OFFSET`: Default offset (0).
 
 You can use these variables if you implement your own pagination mechanism, as they will be updated when our API limits are updated.
 
@@ -373,6 +420,13 @@ user?.update({ fullName: 'John Doe' }); // Partially updates the record
 user?.delete(); // Deletes the record
 ```
 
+The `read` and `update` methods return the updated record with the first level properties. If you want to reduce or expand its columns, you can pass an array of columns to the `read` and `update` methods.
+
+```ts
+const user = await xata.db.users.read('rec_1234abcdef');
+user?.read(['fullName', 'team.name']); // Reads the record again with the `fullName` and `team.name` columns
+```
+
 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