@xata.io/client 0.0.0-alpha.vf2696e7 → 0.0.0-alpha.vf344dbc

package/.eslintrc.cjs

@@ -6,8 +6,7 @@ module.exports = {
     project: 'packages/client/tsconfig.json'
   },
   rules: {
-    '@typescript-eslint/no-explicit-any': 'off',
-    '@typescript-eslint/ban-types': 'off',
     '@typescript-eslint/no-floating-promises': 'error',
+    "@typescript-eslint/strict-boolean-expressions": ["error", { allowNullableString: true, allowNullableObject: true }],
   }
 };

package/CHANGELOG.md

@@ -1,5 +1,101 @@
 # @xata.io/client
 
+## 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
+
+- [#376](https://github.com/xataio/client-ts/pull/376) [`db3c88e`](https://github.com/xataio/client-ts/commit/db3c88e1f2bee6d308afb8d6e95b7c090a87e7a7) Thanks [@SferaDev](https://github.com/SferaDev)! - Hide xata object and expose getMetadata method
+
+### Patch Changes
+
+- [#364](https://github.com/xataio/client-ts/pull/364) [`1cde95f`](https://github.com/xataio/client-ts/commit/1cde95f05a6b9fbf0564ea05400140f0cef41a3a) Thanks [@SferaDev](https://github.com/SferaDev)! - Add peer dep of TS 4.5+
+
+* [#362](https://github.com/xataio/client-ts/pull/362) [`57bf0e2`](https://github.com/xataio/client-ts/commit/57bf0e2e049ed0498683ff42d287983f295342b7) Thanks [@SferaDev](https://github.com/SferaDev)! - Do not show error if date is not defined
+
+## 0.11.0
+
+### Minor Changes
+
+- [#322](https://github.com/xataio/client-ts/pull/322) [`bc64c28`](https://github.com/xataio/client-ts/commit/bc64c28fbfbb000c7190ac8092e2ef6a261df86f) Thanks [@SferaDev](https://github.com/SferaDev)! - Add filter support for cross-table search operations
+
+### Patch Changes
+
+- [#327](https://github.com/xataio/client-ts/pull/327) [`505257c`](https://github.com/xataio/client-ts/commit/505257c0c42ca0c8beaf5c0f638037c576dcc43c) Thanks [@SferaDev](https://github.com/SferaDev)! - Allow reading multiple uids at the same time
+
+* [#346](https://github.com/xataio/client-ts/pull/346) [`ff7e5c6`](https://github.com/xataio/client-ts/commit/ff7e5c6f211913196d8c28600d7a7675ed261688) Thanks [@SferaDev](https://github.com/SferaDev)! - Fix compat with TS 4.8
+
+- [#345](https://github.com/xataio/client-ts/pull/345) [`bf64cb8`](https://github.com/xataio/client-ts/commit/bf64cb885d55a0271e966314384324f02ded084e) Thanks [@SferaDev](https://github.com/SferaDev)! - Fix bug with nullable record filters inferred as never
+
+* [#334](https://github.com/xataio/client-ts/pull/334) [`ce07601`](https://github.com/xataio/client-ts/commit/ce07601e4ddf9f75e20249d479dc04a63795ca96) Thanks [@SferaDev](https://github.com/SferaDev)! - Add support for TS 4.5
+
+- [#325](https://github.com/xataio/client-ts/pull/325) [`12f1ce3`](https://github.com/xataio/client-ts/commit/12f1ce362f6cda27dfdb3afab0800282bddc8b5e) Thanks [@SferaDev](https://github.com/SferaDev)! - Fix offset errors with operations that affect many rows
+
+* [#345](https://github.com/xataio/client-ts/pull/345) [`a73a2a2`](https://github.com/xataio/client-ts/commit/a73a2a2014c44cf88eaef42196ba1dba9d516b4a) Thanks [@SferaDev](https://github.com/SferaDev)! - Fix issue with Filter<T> not narrowing down type on object properties
+
+## 0.10.2
+
+### Patch Changes
+
+- [#312](https://github.com/xataio/client-ts/pull/312) [`0edf1af`](https://github.com/xataio/client-ts/commit/0edf1af2205c4761d53a02c74ddaab3168d69775) Thanks [@SferaDev](https://github.com/SferaDev)! - Add filtering to search by table
+
+* [#312](https://github.com/xataio/client-ts/pull/312) [`66ad7cc`](https://github.com/xataio/client-ts/commit/66ad7cc0365046c5d039c37117feac04428d8373) Thanks [@SferaDev](https://github.com/SferaDev)! - Add new API method for searching in a given table
+
+## 0.10.1
+
+### Patch Changes
+
+- [#271](https://github.com/xataio/client-ts/pull/271) [`0bb17b8`](https://github.com/xataio/client-ts/commit/0bb17b88d49f1c8be32d2d6b0b3a5918890876cb) Thanks [@SferaDev](https://github.com/SferaDev)! - Link and resolve branches from git
+
+## 0.10.0
+
+### Minor Changes
+
+- [#272](https://github.com/xataio/client-ts/pull/272) [`6d76275`](https://github.com/xataio/client-ts/commit/6d7627555a404a4c2da42f4187df6f8300f9a46f) Thanks [@SferaDev](https://github.com/SferaDev)! - Rename page options to pagination
+
+* [#270](https://github.com/xataio/client-ts/pull/270) [`1864742`](https://github.com/xataio/client-ts/commit/18647428d8608841de514c3784fb711c39dccc6d) Thanks [@SferaDev](https://github.com/SferaDev)! - Move chunk to options object
+
+### Patch Changes
+
+- [#281](https://github.com/xataio/client-ts/pull/281) [`d1ec0df`](https://github.com/xataio/client-ts/commit/d1ec0df14834088a816919bfc68216f3f9b2d9ef) Thanks [@SferaDev](https://github.com/SferaDev)! - Do not send from param on undefined
+
+* [#282](https://github.com/xataio/client-ts/pull/282) [`1af6f1a`](https://github.com/xataio/client-ts/commit/1af6f1aaa1123e77a895961581c87f06a88db698) Thanks [@SferaDev](https://github.com/SferaDev)! - Do not allow filter/sort with cursor navigation
+
+- [#284](https://github.com/xataio/client-ts/pull/284) [`be4eda8`](https://github.com/xataio/client-ts/commit/be4eda8f73037d97fef7de28b56d7471dd867875) Thanks [@SferaDev](https://github.com/SferaDev)! - Fix cache ttl with 0 value
+
+* [#265](https://github.com/xataio/client-ts/pull/265) [`99be734`](https://github.com/xataio/client-ts/commit/99be734827576d888aa12a579ed1983a0a8a8e83) Thanks [@SferaDev](https://github.com/SferaDev)! - Add datetime field type support
+
+## 0.9.1
+
+### Patch Changes
+
+- [#250](https://github.com/xataio/client-ts/pull/250) [`5d7c9e4`](https://github.com/xataio/client-ts/commit/5d7c9e4fa2799255e2bfc8b6fb12c89dc4e1f35e) Thanks [@xata-bot](https://github.com/xata-bot)! - Add branch resolution endpoints to api client
+
+* [#261](https://github.com/xataio/client-ts/pull/261) [`e95f20a`](https://github.com/xataio/client-ts/commit/e95f20a7bce264936680353f816065fa379448fc) Thanks [@gimenete](https://github.com/gimenete)! - Fixes a compatibility error in CloudFlare workers with latest version of wrangler
+
+## 0.9.0
+
+### Minor Changes
+
+- [#246](https://github.com/xataio/client-ts/pull/246) [`2848894`](https://github.com/xataio/client-ts/commit/284889446bbac5d6737086bf01a588d97b841730) Thanks [@SferaDev](https://github.com/SferaDev)! - Rename getOne to getFirst
+
+### Patch Changes
+
+- [#254](https://github.com/xataio/client-ts/pull/254) [`2fc2788`](https://github.com/xataio/client-ts/commit/2fc2788e583c047ffb2cd693f053f60ce608149c) Thanks [@SferaDev](https://github.com/SferaDev)! - Deprecate XataApiClient
+
+* [#230](https://github.com/xataio/client-ts/pull/230) [`a96da7c`](https://github.com/xataio/client-ts/commit/a96da7c8b548604ed25001390992531537675a44) Thanks [@SferaDev](https://github.com/SferaDev)! - Include tables in Proxy target for object introspection (shell)
+
+- [#222](https://github.com/xataio/client-ts/pull/222) [`e8d595f`](https://github.com/xataio/client-ts/commit/e8d595f54efe126b39c78cc771a5d69c551f4fba) Thanks [@SferaDev](https://github.com/SferaDev)! - Add cache strategies
+
+* [#244](https://github.com/xataio/client-ts/pull/244) [`c4dcd11`](https://github.com/xataio/client-ts/commit/c4dcd110d8f9dc3a7e4510f2f00257c9109e51fa) Thanks [@gimenete](https://github.com/gimenete)! - getCurrentBranchName never returns a Promise that resolves to undefined
+
 ## 0.8.4
 
 ### Patch Changes

package/README.md

@@ -1 +1,265 @@
-Visit https://github.com/xataio/client-ts for more information.
+# 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.
+
+It also works in browsers for the same reason. But this is strongly discouraged because the API token would be leaked.
+
+## Installing
+
+```bash
+npm install @xata.io/client
+```
+
+## Usage
+
+There are three ways to use the SDK:
+
+- **Schema-generated Client**: SDK to create/read/update/delete records in a given database following a schema file (with type-safety).
+- **Schema-less Client**: SDK to create/read/update/delete records in any database without schema validation (with partial type-safety).
+- **API Client**: SDK to interact with the whole Xata API and all its endpoints.
+
+### 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 run it (and assuming you have configured the project with `xata init`):
+
+```bash
+xata codegen
+```
+
+In a TypeScript file start using the generated code:
+
+```ts
+import { XataClient } from './xata';
+
+const xata = new XataClient({
+  fetch: fetchImplementation // Required if your runtime doesn't provide a global `fetch` function.
+});
+```
+
+The import above will differ if you chose to genreate 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 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).
+
+```ts
+interface User extends Identifiable {
+  email?: string | null;
+}
+
+type UserRecord = User & XataRecord;
+
+async function initializeDatabase(admin: User): Promise<UserRecord> {
+  return xata.db.users.create(admin);
+}
+
+const admin = await initializeDatabase({ email: 'admin@example.com' });
+await admin.update({ email: 'admin@foo.bar' });
+await admin.delete();
+```
+
+You will learn more about the available operations below, under the `API Design` section.
+
+### Schema-less Client
+
+If you don't have a schema file, or you are building a generic way to interact with Xata, you can use the `BaseClient` class without schema validation.
+
+```ts
+import { BaseClient } from '@xata.io/client';
+
+const xata = new BaseClient({
+  branch: 'branchname',
+  apiKey: 'xau_1234abcdef',
+  fetch: fetchImplementation // Required if your runtime doesn't provide a global `fetch` function.
+});
+```
+
+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.
+
+### 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]`.
+
+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**
+
+Invoke the `create()` method in the repository. Example:
+
+```ts
+const user = await xata.db.users.create({
+  fullName: 'John Smith'
+});
+```
+
+If you want to create a record with a specific ID, you can invoke `insert()`.
+
+```ts
+const user = await xata.db.users.insert('user_admin', {
+  fullName: 'John Smith'
+});
+```
+
+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', {
+  fullName: 'John Smith'
+});
+```
+
+**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**
+
+```ts
+// Query objects selecting all fields.
+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 page = await xata.db.users.getPaginated();
+const user = await xata.db.users.getFirst();
+
+// Query objects selecting just one or more fields
+const page = await xata.db.users.select('email', 'profile').getPaginated();
+
+// Apply constraints
+const page = await xata.db.users.filter('email', 'foo@example.com').getPaginated();
+
+// Sorting
+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()`.
+
+```ts
+// Operators that combine multiple conditions can be deconstructed
+const { filter, any, all, not, sort } = xata.db.users;
+const query = filter('email', 'foo@example.com');
+
+// Single-column operators are imported directly from the package
+import { gt, includes, startsWith } from '@xata.io/client';
+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.getAll(); // still returns all admins
+
+// Finally fetch the results of the query
+const users = await query.getAll();
+const firstUser = await query.getFirst();
+```
+
+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:
+
+```ts
+for await (const record of xata.db.users) {
+  console.log(record);
+}
+
+for await (const record of xata.db.users.filter('team.id', teamId)) {
+  console.log(record);
+}
+
+for await (const records of xata.db.users.getIterator({ batchSize: 100 })) {
+  console.log(records);
+}
+```
+
+**Updating objects**
+
+Updating an object leaves the existing instance unchanged, but returns a new object with the updated values.
+
+```ts
+// Using an existing object
+const updatedUser = await user.update({
+  fullName: 'John Smith Jr.'
+});
+
+// Using an object's id
+const updatedUser = await xata.db.users.update('rec_1234abcdef', {
+  fullName: 'John Smith Jr.'
+});
+```
+
+**Deleting objects**
+
+```ts
+// Using an existing object
+await user.delete();
+
+// Using an object's id
+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...
+
+To communicate with the SDK we provide a constructor called `XataApiClient` that accepts an API token and an optional fetch implementation method.
+
+```ts
+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');
+
+await client.branches.createBranch(workspace, databaseName, 'branch');
+await client.tables.createTable(workspace, databaseName, 'branch', 'table');
+await client.tables.setTableSchema(workspace, databaseName, 'branch', 'table', {
+  columns: [{ name: 'email', type: 'string' }]
+});
+
+const { id: recordId } = await client.records.insertRecord(workspace, databaseName, 'branch', 'table', {
+  email: 'example@foo.bar'
+});
+
+const record = await client.records.getRecord(workspace, databaseName, 'branch', 'table', recordId);
+
+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:
+
+```ts
+import {
+  BaseClient,
+  Query,
+  Repository,
+  RestRespositoryFactory,
+  XataClientOptions,
+  XataRecord
+} from 'https://esm.sh/@xata.io/client@<version>/dist/schema?target=deno';
+```