RAI-13623 add filtering/sorting options to listTransactions (#101)

* RAI-13623 add filtering/sorting options to listTransactions

* add next param

* address comments

Author: OsamaSBCrea

CHANGELOG.md

@@ -1,11 +1,18 @@
 # Change Log
 
+## v0.7.4-alpha
+
+- Added filtering, sorting and pagination options to `listTransactions` API. [\#101](https://github.com/RelationalAI/rai-sdk-javascript/pull/101)
+### Breaking Changes
+- `listTransactions` API now returns an object that contains `transactions` and `next` properties.
+  - `transactions` is the result of the API call.
+  - `next` is a continuation token that can be used to fetch the next page of results. `next` is `undefined` if there are no more results to fetch.
+
+
 ## v0.7.1-alpha
 - Storing `AccessToken.createdOn` in seconds to be consistent with other RAI SDKs.
 
-## v0.7.0
-
-## [v0.7.0](https://github.com/relationalai/rai-sdk-javascript/tree/v0.7.0) (2022-XX-XX)
+## [v0.7.0](https://github.com/relationalai/rai-sdk-javascript/tree/v0.7.0)
 
 [Full Changelog](https://github.com/relationalai/rai-sdk-javascript/compare/v0.6.3...v0.7.0)
 

package-lock.json

@@ -1,7 +1,7 @@
 {
   "name": "@relationalai/rai-sdk-javascript",
   "description": "RelationalAI SDK for JavaScript",
-  "version": "0.7.3-alpha",
+  "version": "0.7.4-alpha",
   "author": {
     "name": "RelationalAI",
     "url": "https://relational.ai"

package.json

@@ -19,7 +19,7 @@ import nock from 'nock';
 
 import { baseUrl, getMockConfig } from '../../testUtils';
 import { TransactionAsyncApi } from './transactionAsyncApi';
-import { TransactionAsyncState } from './types';
+import { TransactionAsyncState, TransactionListOptions } from './types';
 
 const path = '/transactions';
 
@@ -280,23 +280,41 @@ describe('TransactionAsyncApi', () => {
 
     scope.done();
 
-    expect(result).toEqual(mockTransactions);
+    expect(result).toEqual(response);
   });
 
   it('should list transactions with params', async () => {
     const response = {
       transactions: mockTransactions,
+      next: 'nextToken',
     };
+    const date = new Date();
+    const options: TransactionListOptions = {
+      engine_name: 'test_engine',
+      tags: ['tag1', 'tag2'],
+      'created_on.lt': date,
+      'duration.gt': 1000,
+      sortBy: {
+        field: 'created_on',
+        order: 'desc',
+      },
+      next: 'nextToken',
+    };
+
     const query = {
       engine_name: 'test_engine',
       tags: ['tag1', 'tag2'],
+      'created_on.lt': date.getTime(),
+      'duration.gt': 1000,
+      $sortby: '-created_on',
+      next: 'nextToken',
     };
     const scope = nock(baseUrl).get(path).query(query).reply(200, response);
-    const result = await api.listTransactions(query);
+    const result = await api.listTransactions(options);
 
     scope.done();
 
-    expect(result).toEqual(mockTransactions);
+    expect(result).toEqual(response);
   });
 
   it('should get transaction', async () => {

src/api/transaction/transactionAsyncApi.test.ts

@@ -31,7 +31,12 @@ import {
 
 const ENDPOINT = 'transactions';
 
-type ListResponse = { transactions: TransactionAsync[] };
+/**
+ * @param next Is a continuation token that can be used to fetch the next page.
+ *   `next` value is undefined if there are no more results to fetch.
+ */
+type ListResponse = { transactions: TransactionAsync[]; next?: string };
+
 type SingleResponse = { transaction: TransactionAsync };
 type CancelResponse = {
   message?: string;
@@ -54,10 +59,22 @@ export class TransactionAsyncApi extends Base {
     };
   }
 
-  async listTransactions(options?: TransactionListOptions) {
-    const result = await this.get<ListResponse>(ENDPOINT, options);
+  async listTransactions(
+    options?: TransactionListOptions,
+  ): Promise<ListResponse> {
+    const { sortBy, ...opts } = options ?? ({} as any);
+
+    Object.keys(opts).forEach(key => {
+      if (opts[key] instanceof Date) {
+        opts[key] = opts[key].getTime();
+      }
+    });
+
+    if (sortBy) {
+      opts.$sortby = `${sortBy.order === 'desc' ? '-' : ''}${sortBy.field}`;
+    }
 
-    return result.transactions;
+    return this.get<ListResponse>(ENDPOINT, opts);
   }
 
   async getTransaction(transactionId: string) {

src/api/transaction/transactionAsyncApi.ts

@@ -17,6 +17,12 @@
 import { Table } from 'apache-arrow';
 
 import { RelationId } from '../../proto/generated/schema';
+import {
+  BooleanOperator,
+  NumericOperator,
+  SortBy,
+  StringOperator,
+} from '../../rest';
 
 export type RelValue = string | number | boolean | null | number[];
 
@@ -239,9 +245,36 @@ export type TransactionAsyncResult = {
   results: ArrowRelation[];
 };
 
+export type TransactionListSortBy = SortBy<'created_on' | 'duration'>;
+
+/**
+ * TransactionListOptions represents the options that can be used to list
+ * transactions which includes filtering, sorting and pagination options. Each
+ * filter option has a set of operators that can be used to filter.
+ *
+ * @param sortBy Is used to perform sorting on a single field of `created_on`
+ *   and `duration` in ascending or descending orders.
+ * @param next Is used as a continuation token for cursor based pagination.
+ */
 export type TransactionListOptions = {
+  id?: string | string[];
+  created_by?: string | string[];
   database_name?: string | string[];
   engine_name?: string | string[];
   state?: TransactionAsyncState | TransactionAsyncState[];
   tags?: string | string[];
-};
+} & {
+  [key in
+    | `id.${StringOperator}`
+    | `created_by.${StringOperator}`
+    | `state.${StringOperator}`
+    | `database_name.${StringOperator}`
+    | `engine_name.${StringOperator}`
+    | `tags.${StringOperator}`]?: string | string[];
+} &
+  { [key in `created_on.${NumericOperator}`]?: number | Date } &
+  { [key in `duration.${NumericOperator}`]?: number } &
+  { [key in `read_only.${BooleanOperator}`]?: boolean } & {
+    sortBy?: TransactionListSortBy;
+    next?: string;
+  };

src/api/transaction/types.ts

@@ -33,6 +33,15 @@ export type RequestOptions = {
   onResponse?: (r: ApiResponse) => void;
 };
 
+export type SortBy<T extends string> = {
+  field: T;
+  order: 'asc' | 'desc';
+};
+
+export type BooleanOperator = 'equals';
+export type StringOperator = 'equals' | 'contains';
+export type NumericOperator = 'lt' | 'lte' | 'gt' | 'gte';
+
 export type PollOptions = {
   overheadRate?: number;
   maxInterval?: number;