Merge pull request #159 from appwrite/dev

ChiragAgg5k · web-flow · commit cf65e765fc23 · 2026-03-03T16:14:42.000+05:30
feat: Web SDK update for version 23.0.0
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,12 @@
 # Change Log
 
+## 23.0.0
+
+* Breaking: Made Channel.collection() require id parameter
+* Breaking: Made Channel.table() require id parameter
+* Breaking: Root factory methods require explicit IDs (databases, executions, tablesdb, bucket, function, team, membership)
+* Added ttl option to listDocuments and listRows for caching
+
 ## 22.4.1
 
 * Fix very large double values (for example 1.7976931348623157e+308) from being expanded into giant integer literals
diff --git a/README.md b/README.md
@@ -6,7 +6,7 @@
 [![Twitter Account](https://img.shields.io/twitter/follow/appwrite?color=00acee&label=twitter&style=flat-square)](https://twitter.com/appwrite)
 [![Discord](https://img.shields.io/discord/564160730845151244?label=discord&style=flat-square)](https://appwrite.io/discord)
 
-**This SDK is compatible with Appwrite server version 1.8.x. For older versions, please check [previous releases](https://github.com/appwrite/sdk-for-web/releases).**
+**This SDK is compatible with Appwrite server version latest. For older versions, please check [previous releases](https://github.com/appwrite/sdk-for-web/releases).**
 
 Appwrite is an open-source backend as a service server that abstracts and simplifies complex and repetitive development tasks behind a very simple to use REST API. Appwrite aims to help you develop your apps faster and in a more secure way. Use the Web SDK to integrate your app with the Appwrite server to easily start interacting with all of Appwrite backend APIs and tools. For full API documentation and tutorials go to [https://appwrite.io/docs](https://appwrite.io/docs)
 
@@ -33,7 +33,7 @@ import { Client, Account } from "appwrite";
 To install with a CDN (content delivery network) add the following scripts to the bottom of your <body> tag, but before you use any Appwrite services:
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/appwrite@22.4.1"></script>
+<script src="https://cdn.jsdelivr.net/npm/appwrite@23.0.0"></script>
 ```
 
 
diff --git a/docs/examples/databases/list-documents.md b/docs/examples/databases/list-documents.md
@@ -12,7 +12,8 @@ const result = await databases.listDocuments({
     collectionId: '<COLLECTION_ID>',
     queries: [], // optional
     transactionId: '<TRANSACTION_ID>', // optional
-    total: false // optional
+    total: false, // optional
+    ttl: 0 // optional
 });
 
 console.log(result);
diff --git a/docs/examples/tablesdb/list-rows.md b/docs/examples/tablesdb/list-rows.md
@@ -12,7 +12,8 @@ const result = await tablesDB.listRows({
     tableId: '<TABLE_ID>',
     queries: [], // optional
     transactionId: '<TRANSACTION_ID>', // optional
-    total: false // optional
+    total: false, // optional
+    ttl: 0 // optional
 });
 
 console.log(result);
diff --git a/package.json b/package.json
@@ -2,7 +2,7 @@
   "name": "appwrite",
   "homepage": "https://appwrite.io/support",
   "description": "Appwrite is an open-source self-hosted backend server that abstracts and simplifies complex and repetitive development tasks behind a very simple REST API",
-  "version": "22.4.1",
+  "version": "23.0.0",
   "license": "BSD-3-Clause",
   "main": "dist/cjs/sdk.js",
   "exports": {
diff --git a/src/channel.ts b/src/channel.ts
@@ -16,8 +16,14 @@ interface Resolved { _res: any }
 type Actionable = Document | Row | File | Team | Membership;
 
 function normalize(id: string): string {
-  const trimmed = id.trim();
-  return trimmed === "" ? "*" : trimmed;
+  if (id === undefined || id === null) {
+    throw new Error("Channel ID is required");
+  }
+  const trimmed = String(id).trim();
+  if (trimmed === "") {
+    throw new Error("Channel ID is required");
+  }
+  return trimmed;
 }
 
 export class Channel<T> {
@@ -44,9 +50,8 @@ export class Channel<T> {
 
   // --- DATABASE ROUTE ---
   // Only available on Channel<Database>
-  collection(this: Channel<Database>, id?: string): Channel<Collection> {
-    // Default: wildcard collection ID
-    return this.next<Collection>("collections", id ?? "*");
+  collection(this: Channel<Database>, id: string): Channel<Collection> {
+    return this.next<Collection>("collections", id);
   }
 
   // Only available on Channel<Collection>
@@ -56,9 +61,8 @@ export class Channel<T> {
   }
 
   // --- TABLESDB ROUTE ---
-  table(this: Channel<TablesDB>, id?: string): Channel<Table> {
-    // Default: wildcard table ID
-    return this.next<Table>("tables", id ?? "*");
+  table(this: Channel<TablesDB>, id: string): Channel<Table> {
+    return this.next<Table>("tables", id);
   }
 
   row(this: Channel<Table>, id?: string): Channel<Row> {
@@ -91,31 +95,31 @@ export class Channel<T> {
   }
 
   // --- ROOT FACTORIES ---
-  static database(id: string = "*") {
+  static database(id: string) {
     return new Channel<Database>(["databases", normalize(id)]);
   }
 
-  static execution(id: string = "*") {
+  static execution(id: string) {
     return new Channel<Execution>(["executions", normalize(id)]);
   }
 
-  static tablesdb(id: string = "*") {
+  static tablesdb(id: string) {
     return new Channel<TablesDB>(["tablesdb", normalize(id)]);
   }
 
-  static bucket(id: string = "*") {
+  static bucket(id: string) {
     return new Channel<Bucket>(["buckets", normalize(id)]);
   }
 
-  static function(id: string = "*") {
+  static function(id: string) {
     return new Channel<Func>(["functions", normalize(id)]);
   }
 
-  static team(id: string = "*") {
+  static team(id: string) {
     return new Channel<Team>(["teams", normalize(id)]);
   }
 
-  static membership(id: string = "*") {
+  static membership(id: string) {
     return new Channel<Membership>(["memberships", normalize(id)]);
   }
 
diff --git a/src/client.ts b/src/client.ts
@@ -392,7 +392,7 @@ class Client {
         'x-sdk-name': 'Web',
         'x-sdk-platform': 'client',
         'x-sdk-language': 'web',
-        'x-sdk-version': '22.4.1',
+        'x-sdk-version': '23.0.0',
         'X-Appwrite-Response-Format': '1.8.0',
     };
 
diff --git a/src/models.ts b/src/models.ts
@@ -241,7 +241,7 @@ export namespace Models {
          */
         $id: string;
         /**
-         * Row automatically incrementing ID.
+         * Row sequence ID.
          */
         $sequence: number;
         /**
@@ -280,7 +280,7 @@ export namespace Models {
          */
         $id: string;
         /**
-         * Document automatically incrementing ID.
+         * Document sequence ID.
          */
         $sequence: number;
         /**
diff --git a/src/services/databases.ts b/src/services/databases.ts
@@ -351,11 +351,12 @@ export class Databases {
      * @param {string[]} params.queries - Array of query strings generated using the Query class provided by the SDK. [Learn more about queries](https://appwrite.io/docs/queries). Maximum of 100 queries are allowed, each 4096 characters long.
      * @param {string} params.transactionId - Transaction ID to read uncommitted changes within the transaction.
      * @param {boolean} params.total - When set to false, the total count returned will be 0 and will not be calculated.
+     * @param {number} params.ttl - TTL (seconds) for cached responses when caching is enabled for select queries. Must be between 0 and 86400 (24 hours).
      * @throws {AppwriteException}
      * @returns {Promise<Models.DocumentList<Document>>}
      * @deprecated This API has been deprecated since 1.8.0. Please use `TablesDB.listRows` instead.
      */
-    listDocuments<Document extends Models.Document = Models.DefaultDocument>(params: { databaseId: string, collectionId: string, queries?: string[], transactionId?: string, total?: boolean }): Promise<Models.DocumentList<Document>>;
+    listDocuments<Document extends Models.Document = Models.DefaultDocument>(params: { databaseId: string, collectionId: string, queries?: string[], transactionId?: string, total?: boolean, ttl?: number }): Promise<Models.DocumentList<Document>>;
     /**
      * Get a list of all the user's documents in a given collection. You can use the query params to filter your results.
      *
@@ -364,26 +365,28 @@ export class Databases {
      * @param {string[]} queries - Array of query strings generated using the Query class provided by the SDK. [Learn more about queries](https://appwrite.io/docs/queries). Maximum of 100 queries are allowed, each 4096 characters long.
      * @param {string} transactionId - Transaction ID to read uncommitted changes within the transaction.
      * @param {boolean} total - When set to false, the total count returned will be 0 and will not be calculated.
+     * @param {number} ttl - TTL (seconds) for cached responses when caching is enabled for select queries. Must be between 0 and 86400 (24 hours).
      * @throws {AppwriteException}
      * @returns {Promise<Models.DocumentList<Document>>}
      * @deprecated Use the object parameter style method for a better developer experience.
      */
-    listDocuments<Document extends Models.Document = Models.DefaultDocument>(databaseId: string, collectionId: string, queries?: string[], transactionId?: string, total?: boolean): Promise<Models.DocumentList<Document>>;
+    listDocuments<Document extends Models.Document = Models.DefaultDocument>(databaseId: string, collectionId: string, queries?: string[], transactionId?: string, total?: boolean, ttl?: number): Promise<Models.DocumentList<Document>>;
     listDocuments<Document extends Models.Document = Models.DefaultDocument>(
-        paramsOrFirst: { databaseId: string, collectionId: string, queries?: string[], transactionId?: string, total?: boolean } | string,
-        ...rest: [(string)?, (string[])?, (string)?, (boolean)?]    
+        paramsOrFirst: { databaseId: string, collectionId: string, queries?: string[], transactionId?: string, total?: boolean, ttl?: number } | string,
+        ...rest: [(string)?, (string[])?, (string)?, (boolean)?, (number)?]    
     ): Promise<Models.DocumentList<Document>> {
-        let params: { databaseId: string, collectionId: string, queries?: string[], transactionId?: string, total?: boolean };
+        let params: { databaseId: string, collectionId: string, queries?: string[], transactionId?: string, total?: boolean, ttl?: number };
         
         if ((paramsOrFirst && typeof paramsOrFirst === 'object' && !Array.isArray(paramsOrFirst))) {
-            params = (paramsOrFirst || {}) as { databaseId: string, collectionId: string, queries?: string[], transactionId?: string, total?: boolean };
+            params = (paramsOrFirst || {}) as { databaseId: string, collectionId: string, queries?: string[], transactionId?: string, total?: boolean, ttl?: number };
         } else {
             params = {
                 databaseId: paramsOrFirst as string,
                 collectionId: rest[0] as string,
                 queries: rest[1] as string[],
                 transactionId: rest[2] as string,
-                total: rest[3] as boolean            
+                total: rest[3] as boolean,
+                ttl: rest[4] as number            
             };
         }
         
@@ -392,6 +395,7 @@ export class Databases {
         const queries = params.queries;
         const transactionId = params.transactionId;
         const total = params.total;
+        const ttl = params.ttl;
 
         if (typeof databaseId === 'undefined') {
             throw new AppwriteException('Missing required parameter: "databaseId"');
@@ -411,6 +415,9 @@ export class Databases {
         if (typeof total !== 'undefined') {
             payload['total'] = total;
         }
+        if (typeof ttl !== 'undefined') {
+            payload['ttl'] = ttl;
+        }
         const uri = new URL(this.client.config.endpoint + apiPath);
 
         const apiHeaders: { [header: string]: string } = {
diff --git a/src/services/tables-db.ts b/src/services/tables-db.ts
@@ -351,10 +351,11 @@ export class TablesDB {
      * @param {string[]} params.queries - Array of query strings generated using the Query class provided by the SDK. [Learn more about queries](https://appwrite.io/docs/queries). Maximum of 100 queries are allowed, each 4096 characters long.
      * @param {string} params.transactionId - Transaction ID to read uncommitted changes within the transaction.
      * @param {boolean} params.total - When set to false, the total count returned will be 0 and will not be calculated.
+     * @param {number} params.ttl - TTL (seconds) for cached responses when caching is enabled for select queries. Must be between 0 and 86400 (24 hours).
      * @throws {AppwriteException}
      * @returns {Promise<Models.RowList<Row>>}
      */
-    listRows<Row extends Models.Row = Models.DefaultRow>(params: { databaseId: string, tableId: string, queries?: string[], transactionId?: string, total?: boolean }): Promise<Models.RowList<Row>>;
+    listRows<Row extends Models.Row = Models.DefaultRow>(params: { databaseId: string, tableId: string, queries?: string[], transactionId?: string, total?: boolean, ttl?: number }): Promise<Models.RowList<Row>>;
     /**
      * Get a list of all the user's rows in a given table. You can use the query params to filter your results.
      *
@@ -363,26 +364,28 @@ export class TablesDB {
      * @param {string[]} queries - Array of query strings generated using the Query class provided by the SDK. [Learn more about queries](https://appwrite.io/docs/queries). Maximum of 100 queries are allowed, each 4096 characters long.
      * @param {string} transactionId - Transaction ID to read uncommitted changes within the transaction.
      * @param {boolean} total - When set to false, the total count returned will be 0 and will not be calculated.
+     * @param {number} ttl - TTL (seconds) for cached responses when caching is enabled for select queries. Must be between 0 and 86400 (24 hours).
      * @throws {AppwriteException}
      * @returns {Promise<Models.RowList<Row>>}
      * @deprecated Use the object parameter style method for a better developer experience.
      */
-    listRows<Row extends Models.Row = Models.DefaultRow>(databaseId: string, tableId: string, queries?: string[], transactionId?: string, total?: boolean): Promise<Models.RowList<Row>>;
+    listRows<Row extends Models.Row = Models.DefaultRow>(databaseId: string, tableId: string, queries?: string[], transactionId?: string, total?: boolean, ttl?: number): Promise<Models.RowList<Row>>;
     listRows<Row extends Models.Row = Models.DefaultRow>(
-        paramsOrFirst: { databaseId: string, tableId: string, queries?: string[], transactionId?: string, total?: boolean } | string,
-        ...rest: [(string)?, (string[])?, (string)?, (boolean)?]    
+        paramsOrFirst: { databaseId: string, tableId: string, queries?: string[], transactionId?: string, total?: boolean, ttl?: number } | string,
+        ...rest: [(string)?, (string[])?, (string)?, (boolean)?, (number)?]    
     ): Promise<Models.RowList<Row>> {
-        let params: { databaseId: string, tableId: string, queries?: string[], transactionId?: string, total?: boolean };
+        let params: { databaseId: string, tableId: string, queries?: string[], transactionId?: string, total?: boolean, ttl?: number };
         
         if ((paramsOrFirst && typeof paramsOrFirst === 'object' && !Array.isArray(paramsOrFirst))) {
-            params = (paramsOrFirst || {}) as { databaseId: string, tableId: string, queries?: string[], transactionId?: string, total?: boolean };
+            params = (paramsOrFirst || {}) as { databaseId: string, tableId: string, queries?: string[], transactionId?: string, total?: boolean, ttl?: number };
         } else {
             params = {
                 databaseId: paramsOrFirst as string,
                 tableId: rest[0] as string,
                 queries: rest[1] as string[],
                 transactionId: rest[2] as string,
-                total: rest[3] as boolean            
+                total: rest[3] as boolean,
+                ttl: rest[4] as number            
             };
         }
         
@@ -391,6 +394,7 @@ export class TablesDB {
         const queries = params.queries;
         const transactionId = params.transactionId;
         const total = params.total;
+        const ttl = params.ttl;
 
         if (typeof databaseId === 'undefined') {
             throw new AppwriteException('Missing required parameter: "databaseId"');
@@ -410,6 +414,9 @@ export class TablesDB {
         if (typeof total !== 'undefined') {
             payload['total'] = total;
         }
+        if (typeof ttl !== 'undefined') {
+            payload['ttl'] = ttl;
+        }
         const uri = new URL(this.client.config.endpoint + apiPath);
 
         const apiHeaders: { [header: string]: string } = {
diff --git a/src/services/teams.ts b/src/services/teams.ts
@@ -399,7 +399,7 @@ export class Teams {
      * 
      *
      * @param {string} params.teamId - Team ID.
-     * @param {string[]} params.roles - Array of strings. Use this param to set the user roles in the team. A role can be any string. Learn more about [roles and permissions](https://appwrite.io/docs/permissions). Maximum of 100 roles are allowed, each 32 characters long.
+     * @param {string[]} params.roles - Array of strings. Use this param to set the user roles in the team. A role can be any string. Learn more about [roles and permissions](https://appwrite.io/docs/permissions). Maximum of 100 roles are allowed, each 81 characters long.
      * @param {string} params.email - Email of the new team member.
      * @param {string} params.userId - ID of the user to be added to a team.
      * @param {string} params.phone - Phone number. Format this number with a leading '+' and a country code, e.g., +16175551212.
@@ -420,7 +420,7 @@ export class Teams {
      * 
      *
      * @param {string} teamId - Team ID.
-     * @param {string[]} roles - Array of strings. Use this param to set the user roles in the team. A role can be any string. Learn more about [roles and permissions](https://appwrite.io/docs/permissions). Maximum of 100 roles are allowed, each 32 characters long.
+     * @param {string[]} roles - Array of strings. Use this param to set the user roles in the team. A role can be any string. Learn more about [roles and permissions](https://appwrite.io/docs/permissions). Maximum of 100 roles are allowed, each 81 characters long.
      * @param {string} email - Email of the new team member.
      * @param {string} userId - ID of the user to be added to a team.
      * @param {string} phone - Phone number. Format this number with a leading '+' and a country code, e.g., +16175551212.
@@ -565,7 +565,7 @@ export class Teams {
      *
      * @param {string} params.teamId - Team ID.
      * @param {string} params.membershipId - Membership ID.
-     * @param {string[]} params.roles - An array of strings. Use this param to set the user's roles in the team. A role can be any string. Learn more about [roles and permissions](https://appwrite.io/docs/permissions). Maximum of 100 roles are allowed, each 32 characters long.
+     * @param {string[]} params.roles - An array of strings. Use this param to set the user's roles in the team. A role can be any string. Learn more about [roles and permissions](https://appwrite.io/docs/permissions). Maximum of 100 roles are allowed, each 81 characters long.
      * @throws {AppwriteException}
      * @returns {Promise<Models.Membership>}
      */
@@ -576,7 +576,7 @@ export class Teams {
      *
      * @param {string} teamId - Team ID.
      * @param {string} membershipId - Membership ID.
-     * @param {string[]} roles - An array of strings. Use this param to set the user's roles in the team. A role can be any string. Learn more about [roles and permissions](https://appwrite.io/docs/permissions). Maximum of 100 roles are allowed, each 32 characters long.
+     * @param {string[]} roles - An array of strings. Use this param to set the user's roles in the team. A role can be any string. Learn more about [roles and permissions](https://appwrite.io/docs/permissions). Maximum of 100 roles are allowed, each 81 characters long.
      * @throws {AppwriteException}
      * @returns {Promise<Models.Membership>}
      * @deprecated Use the object parameter style method for a better developer experience.

Original file line number	Diff line number	Diff line change
`@@ -16,8 +16,14 @@ interface Resolved { _res: any }`
`16`	`16`	`type Actionable = Document \| Row \| File \| Team \| Membership;`
`17`	`17`
`18`	`18`	`function normalize(id: string): string {`
`19`		`- const trimmed = id.trim();`
`20`		`- return trimmed === "" ? "*" : trimmed;`
	`19`	`+ if (id === undefined \|\| id === null) {`
	`20`	`+ throw new Error("Channel ID is required");`
	`21`	`+ }`
	`22`	`+ const trimmed = String(id).trim();`
	`23`	`+ if (trimmed === "") {`
	`24`	`+ throw new Error("Channel ID is required");`
	`25`	`+ }`
	`26`	`+ return trimmed;`
`21`	`27`	`}`
`22`	`28`
`23`	`29`	`export class Channel<T> {`
`@@ -44,9 +50,8 @@ export class Channel<T> {`
`44`	`50`
`45`	`51`	`// --- DATABASE ROUTE ---`
`46`	`52`	`// Only available on Channel<Database>`
`47`		`- collection(this: Channel<Database>, id?: string): Channel<Collection> {`
`48`		`- // Default: wildcard collection ID`
`49`		`- return this.next<Collection>("collections", id ?? "*");`
	`53`	`+ collection(this: Channel<Database>, id: string): Channel<Collection> {`
	`54`	`+ return this.next<Collection>("collections", id);`
`50`	`55`	`}`
`51`	`56`
`52`	`57`	`// Only available on Channel<Collection>`
`@@ -56,9 +61,8 @@ export class Channel<T> {`
`56`	`61`	`}`
`57`	`62`
`58`	`63`	`// --- TABLESDB ROUTE ---`
`59`		`- table(this: Channel<TablesDB>, id?: string): Channel<Table> {`
`60`		`- // Default: wildcard table ID`
`61`		`- return this.next<Table>("tables", id ?? "*");`
	`64`	`+ table(this: Channel<TablesDB>, id: string): Channel<Table> {`
	`65`	`+ return this.next<Table>("tables", id);`
`62`	`66`	`}`
`63`	`67`
`64`	`68`	`row(this: Channel<Table>, id?: string): Channel<Row> {`
`@@ -91,31 +95,31 @@ export class Channel<T> {`
`91`	`95`	`}`
`92`	`96`
`93`	`97`	`// --- ROOT FACTORIES ---`
`94`		`- static database(id: string = "*") {`
	`98`	`+ static database(id: string) {`
`95`	`99`	`return new Channel<Database>(["databases", normalize(id)]);`
`96`	`100`	`}`
`97`	`101`
`98`		`- static execution(id: string = "*") {`
	`102`	`+ static execution(id: string) {`
`99`	`103`	`return new Channel<Execution>(["executions", normalize(id)]);`
`100`	`104`	`}`
`101`	`105`
`102`		`- static tablesdb(id: string = "*") {`
	`106`	`+ static tablesdb(id: string) {`
`103`	`107`	`return new Channel<TablesDB>(["tablesdb", normalize(id)]);`
`104`	`108`	`}`
`105`	`109`
`106`		`- static bucket(id: string = "*") {`
	`110`	`+ static bucket(id: string) {`
`107`	`111`	`return new Channel<Bucket>(["buckets", normalize(id)]);`
`108`	`112`	`}`
`109`	`113`
`110`		`- static function(id: string = "*") {`
	`114`	`+ static function(id: string) {`
`111`	`115`	`return new Channel<Func>(["functions", normalize(id)]);`
`112`	`116`	`}`
`113`	`117`
`114`		`- static team(id: string = "*") {`
	`118`	`+ static team(id: string) {`
`115`	`119`	`return new Channel<Team>(["teams", normalize(id)]);`
`116`	`120`	`}`
`117`	`121`
`118`		`- static membership(id: string = "*") {`
	`122`	`+ static membership(id: string) {`
`119`	`123`	`return new Channel<Membership>(["memberships", normalize(id)]);`
`120`	`124`	`}`
`121`	`125`