@xata.io/client 0.10.1 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # @xata.io/client
 
+## 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

package/README.md

@@ -1 +1,258 @@
-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 users = await xata.db.users.select().getMany();
+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 user = await xata.db.users.getFirst();
+
+// Query objects selecting just one or more fields
+const users = await xata.db.users.select('email', 'profile').getMany();
+
+// Apply constraints
+const users = await xata.db.users.filter('email', 'foo@example.com').getMany();
+
+// Sorting
+const users = await xata.db.users.sort('fullName', 'asc').getMany();
+```
+
+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()`.
+
+```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.getMany(); // still returns all admins
+
+// Finally fetch the results of the query
+const users = await query.getMany();
+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();
+```
+
+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');
+```
+
+#### 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...
+
+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);
+```

package/dist/index.cjs

@@ -11,8 +11,11 @@ function compact(arr) {
 function isObject(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
+function isDefined(value) {
+  return value !== null && value !== void 0;
+}
 function isString(value) {
-  return value !== void 0 && value !== null && typeof value === "string";
+  return isDefined(value) && typeof value === "string";
 }
 function toBase64(value) {
   try {
@@ -74,7 +77,12 @@ function getFetchImplementation(userFetch) {
   return fetchImpl;
 }
 
-class FetcherError extends Error {
+class ErrorWithCause extends Error {
+  constructor(message, options) {
+    super(message, options);
+  }
+}
+class FetcherError extends ErrorWithCause {
   constructor(status, data) {
     super(getMessage(data));
     this.status = status;
@@ -370,6 +378,11 @@ const queryTable = (variables) => fetch$1({
   method: "post",
   ...variables
 });
+const searchTable = (variables) => fetch$1({
+  url: "/db/{dbBranchName}/tables/{tableName}/search",
+  method: "post",
+  ...variables
+});
 const searchBranch = (variables) => fetch$1({
   url: "/db/{dbBranchName}/search",
   method: "post",
@@ -433,6 +446,7 @@ const operationsByTag = {
     getRecord,
     bulkInsertTableRecords,
     queryTable,
+    searchTable,
     searchBranch
   }
 };
@@ -888,6 +902,13 @@ class RecordsApi {
       ...this.extraProps
     });
   }
+  searchTable(workspace, database, branch, tableName, query) {
+    return operationsByTag.records.searchTable({
+      pathParams: { workspace, dbBranchName: `${database}:${branch}`, tableName },
+      body: query,
+      ...this.extraProps
+    });
+  }
   searchBranch(workspace, database, branch, query) {
     return operationsByTag.records.searchBranch({
       pathParams: { workspace, dbBranchName: `${database}:${branch}` },
@@ -954,6 +975,9 @@ const PAGINATION_MAX_SIZE = 200;
 const PAGINATION_DEFAULT_SIZE = 200;
 const PAGINATION_MAX_OFFSET = 800;
 const PAGINATION_DEFAULT_OFFSET = 0;
+function isCursorPaginationOptions(options) {
+  return isDefined(options) && (isDefined(options.first) || isDefined(options.last) || isDefined(options.after) || isDefined(options.before));
+}
 
 var __accessCheck$5 = (obj, member, msg) => {
   if (!member.has(obj))
@@ -975,7 +999,7 @@ var __privateSet$4 = (obj, member, value, setter) => {
 };
 var _table$1, _repository, _data;
 const _Query = class {
-  constructor(repository, table, data, parent) {
+  constructor(repository, table, data, rawParent) {
     __privateAdd$5(this, _table$1, void 0);
     __privateAdd$5(this, _repository, void 0);
     __privateAdd$5(this, _data, { filter: {} });
@@ -987,6 +1011,7 @@ const _Query = class {
     } else {
       __privateSet$4(this, _repository, this);
     }
+    const parent = cleanParent(data, rawParent);
     __privateGet$5(this, _data).filter = data.filter ?? parent?.filter ?? {};
     __privateGet$5(this, _data).filter.$any = data.filter?.$any ?? parent?.filter?.$any;
     __privateGet$5(this, _data).filter.$all = data.filter?.$all ?? parent?.filter?.$all;
@@ -1058,13 +1083,13 @@ const _Query = class {
   }
   async *getIterator(options = {}) {
     const { batchSize = 1 } = options;
-    let offset = 0;
-    let end = false;
-    while (!end) {
-      const { records, meta } = await this.getPaginated({ ...options, pagination: { size: batchSize, offset } });
-      yield records;
-      offset += batchSize;
-      end = !meta.page.more;
+    let page = await this.getPaginated({ ...options, pagination: { size: batchSize, offset: 0 } });
+    let more = page.hasNextPage();
+    yield page.records;
+    while (more) {
+      page = await page.nextPage();
+      more = page.hasNextPage();
+      yield page.records;
     }
   }
   async getMany(options = {}) {
@@ -1106,12 +1131,20 @@ let Query = _Query;
 _table$1 = new WeakMap();
 _repository = new WeakMap();
 _data = new WeakMap();
+function cleanParent(data, parent) {
+  if (isCursorPaginationOptions(data.pagination)) {
+    return { ...parent, sorting: void 0, filter: void 0 };
+  }
+  return parent;
+}
 
 function isIdentifiable(x) {
   return isObject(x) && isString(x?.id);
 }
 function isXataRecord(x) {
-  return isIdentifiable(x) && typeof x?.xata === "object" && typeof x?.xata?.version === "number";
+  const record = x;
+  const metadata = record?.getMetadata();
+  return isIdentifiable(x) && isObject(metadata) && typeof metadata.version === "number";
 }
 
 function isSortFilterString(value) {
@@ -1188,6 +1221,8 @@ class RestRepository extends Query {
   }
   async create(a, b) {
     if (Array.isArray(a)) {
+      if (a.length === 0)
+        return [];
       const records = await __privateMethod$2(this, _bulkInsertTableRecords, bulkInsertTableRecords_fn).call(this, a);
       await Promise.all(records.map((record) => __privateMethod$2(this, _setCacheRecord, setCacheRecord_fn).call(this, record)));
       return records;
@@ -1213,27 +1248,36 @@ class RestRepository extends Query {
     }
     throw new Error("Invalid arguments for create method");
   }
-  async read(recordId) {
-    const cacheRecord = await __privateMethod$2(this, _getCacheRecord, getCacheRecord_fn).call(this, recordId);
-    if (cacheRecord)
-      return cacheRecord;
-    const fetchProps = await __privateGet$4(this, _getFetchProps).call(this);
-    try {
-      const response = await getRecord({
-        pathParams: { workspace: "{workspaceId}", dbBranchName: "{dbBranch}", tableName: __privateGet$4(this, _table), recordId },
-        ...fetchProps
-      });
-      const schema = await __privateMethod$2(this, _getSchema$1, getSchema_fn$1).call(this);
-      return initObject(this.db, schema, __privateGet$4(this, _table), response);
-    } catch (e) {
-      if (isObject(e) && e.status === 404) {
-        return null;
+  async read(a) {
+    if (Array.isArray(a)) {
+      if (a.length === 0)
+        return [];
+      return this.getAll({ filter: { id: { $any: a } } });
+    }
+    if (isString(a)) {
+      const cacheRecord = await __privateMethod$2(this, _getCacheRecord, getCacheRecord_fn).call(this, a);
+      if (cacheRecord)
+        return cacheRecord;
+      const fetchProps = await __privateGet$4(this, _getFetchProps).call(this);
+      try {
+        const response = await getRecord({
+          pathParams: { workspace: "{workspaceId}", dbBranchName: "{dbBranch}", tableName: __privateGet$4(this, _table), recordId: a },
+          ...fetchProps
+        });
+        const schema = await __privateMethod$2(this, _getSchema$1, getSchema_fn$1).call(this);
+        return initObject(this.db, schema, __privateGet$4(this, _table), response);
+      } catch (e) {
+        if (isObject(e) && e.status === 404) {
+          return null;
+        }
+        throw e;
       }
-      throw e;
     }
   }
   async update(a, b) {
     if (Array.isArray(a)) {
+      if (a.length === 0)
+        return [];
       if (a.length > 100) {
         console.warn("Bulk update operation is not optimized in the Xata API yet, this request might be slow");
       }
@@ -1255,6 +1299,8 @@ class RestRepository extends Query {
   }
   async createOrUpdate(a, b) {
     if (Array.isArray(a)) {
+      if (a.length === 0)
+        return [];
       if (a.length > 100) {
         console.warn("Bulk update operation is not optimized in the Xata API yet, this request might be slow");
       }
@@ -1276,6 +1322,8 @@ class RestRepository extends Query {
   }
   async delete(a) {
     if (Array.isArray(a)) {
+      if (a.length === 0)
+        return;
       if (a.length > 100) {
         console.warn("Bulk delete operation is not optimized in the Xata API yet, this request might be slow");
       }
@@ -1296,9 +1344,14 @@ class RestRepository extends Query {
   }
   async search(query, options = {}) {
     const fetchProps = await __privateGet$4(this, _getFetchProps).call(this);
-    const { records } = await searchBranch({
-      pathParams: { workspace: "{workspaceId}", dbBranchName: "{dbBranch}" },
-      body: { tables: [__privateGet$4(this, _table)], query, fuzziness: options.fuzziness },
+    const { records } = await searchTable({
+      pathParams: { workspace: "{workspaceId}", dbBranchName: "{dbBranch}", tableName: __privateGet$4(this, _table) },
+      body: {
+        query,
+        fuzziness: options.fuzziness,
+        highlight: options.highlight,
+        filter: options.filter
+      },
       ...fetchProps
     });
     const schema = await __privateMethod$2(this, _getSchema$1, getSchema_fn$1).call(this);
@@ -1481,7 +1534,8 @@ const transformObjectLinks = (object) => {
 };
 const initObject = (db, schema, table, object) => {
   const result = {};
-  Object.assign(result, object);
+  const { xata, ...rest } = object ?? {};
+  Object.assign(result, rest);
   const { columns } = schema.tables.find(({ name }) => name === table) ?? {};
   if (!columns)
     console.error(`Table ${table} not found in schema`);
@@ -1489,10 +1543,10 @@ const initObject = (db, schema, table, object) => {
     const value = result[column.name];
     switch (column.type) {
       case "datetime": {
-        const date = new Date(value);
-        if (isNaN(date.getTime())) {
+        const date = value !== void 0 ? new Date(value) : void 0;
+        if (date && isNaN(date.getTime())) {
           console.error(`Failed to parse date ${value} for field ${column.name}`);
-        } else {
+        } else if (date) {
           result[column.name] = date;
         }
         break;
@@ -1517,7 +1571,10 @@ const initObject = (db, schema, table, object) => {
   result.delete = function() {
     return db[table].delete(result["id"]);
   };
-  for (const prop of ["read", "update", "delete"]) {
+  result.getMetadata = function() {
+    return xata;
+  };
+  for (const prop of ["read", "update", "delete", "getMetadata"]) {
     Object.defineProperty(result, prop, { enumerable: false });
   }
   Object.freeze(result);
@@ -1699,10 +1756,10 @@ _schema = new WeakMap();
 _search = new WeakSet();
 search_fn = async function(query, options, getFetchProps) {
   const fetchProps = await getFetchProps();
-  const { tables, fuzziness } = options ?? {};
+  const { tables, fuzziness, highlight } = options ?? {};
   const { records } = await searchBranch({
     pathParams: { workspace: "{workspaceId}", dbBranchName: "{dbBranch}" },
-    body: { tables, query, fuzziness },
+    body: { tables, query, fuzziness, highlight },
     ...fetchProps
   });
   return records;
@@ -1992,6 +2049,7 @@ exports.insertRecord = insertRecord;
 exports.insertRecordWithID = insertRecordWithID;
 exports.inviteWorkspaceMember = inviteWorkspaceMember;
 exports.is = is;
+exports.isCursorPaginationOptions = isCursorPaginationOptions;
 exports.isIdentifiable = isIdentifiable;
 exports.isNot = isNot;
 exports.isXataRecord = isXataRecord;
@@ -2007,6 +2065,7 @@ exports.removeWorkspaceMember = removeWorkspaceMember;
 exports.resendWorkspaceMemberInvite = resendWorkspaceMemberInvite;
 exports.resolveBranch = resolveBranch;
 exports.searchBranch = searchBranch;
+exports.searchTable = searchTable;
 exports.setTableSchema = setTableSchema;
 exports.startsWith = startsWith;
 exports.updateBranchMetadata = updateBranchMetadata;