@slickgrid-universal/graphql 4.0.2 → 4.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slickgrid-universal/graphql",
-  "version": "4.0.2",
+  "version": "4.1.0",
   "description": "GraphQL Service to sync a grid with a GraphQL backend server",
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.js",
@@ -25,7 +25,8 @@
     "access": "public"
   },
   "files": [
-    "/dist"
+    "/dist",
+    "/src"
   ],
   "license": "MIT",
   "author": "Ghislain B.",
@@ -44,12 +45,12 @@
     "not dead"
   ],
   "dependencies": {
-    "@slickgrid-universal/common": "~4.0.2",
-    "@slickgrid-universal/utils": "~4.0.2"
+    "@slickgrid-universal/common": "~4.1.0",
+    "@slickgrid-universal/utils": "~4.1.0"
   },
   "funding": {
     "type": "ko_fi",
     "url": "https://ko-fi.com/ghiscoding"
   },
-  "gitHead": "bcfcd08a502c43be4a17202174f631b064b56571"
+  "gitHead": "1cfc2658f5d70e66c096e5ea77d1827dd44e0292"
 }

package/src/index.ts

@@ -0,0 +1,3 @@
+export { GraphqlService } from './services/graphql.service';
+export { default as GraphqlQueryBuilder } from './services/graphqlQueryBuilder';
+export * from './interfaces/index';

package/src/interfaces/graphqlCursorPaginationOption.interface.ts

@@ -0,0 +1,13 @@
+export interface GraphqlCursorPaginationOption {
+  /** Start our page After cursor X */
+  after?: string;
+
+  /** Start our page Before cursor X */
+  before?: string;
+
+  /** Get first X number of objects */
+  first?: number;
+
+  /** Get last X number of objects */
+  last?: number;
+}

package/src/interfaces/graphqlDatasetFilter.interface.ts

@@ -0,0 +1,13 @@
+import type { GraphqlFilteringOption } from './graphqlFilteringOption.interface';
+import type { GraphqlSortingOption } from './graphqlSortingOption.interface';
+
+export interface GraphqlDatasetFilter {
+  first?: number;
+  last?: number;
+  offset?: number;
+  after?: string;
+  before?: string;
+  locale?: string;
+  filterBy?: GraphqlFilteringOption[];
+  orderBy?: GraphqlSortingOption[];
+}

package/src/interfaces/graphqlFilteringOption.interface.ts

@@ -0,0 +1,12 @@
+import type { OperatorString, OperatorType } from '@slickgrid-universal/common';
+
+export interface GraphqlFilteringOption {
+  /** Field name to use when filtering */
+  field: string;
+
+  /** Operator to use when filtering */
+  operator: OperatorType | OperatorString;
+
+  /** Value to use when filtering */
+  value: any | any[];
+}

package/src/interfaces/graphqlPaginatedResult.interface.ts

@@ -0,0 +1,27 @@
+import type { Metrics, CursorPageInfo } from '@slickgrid-universal/common';
+
+export interface GraphqlPaginatedResult {
+  data: {
+    [datasetName: string]: {
+      /** result set of data objects (array of data) */
+      nodes: any[];
+
+      /** Total count of items in the table (needed for the Pagination to work) */
+      totalCount: number;
+
+      // ---
+      // When using a Cursor, we'll also have Edges and PageInfo according to a cursor position
+      /** Edges information of the current cursor */
+      edges?: {
+        /** Current cursor position */
+        cursor: string;
+      }
+
+      /** Page information of the current cursor, do we have a next page and what is the end cursor? */
+      pageInfo?: CursorPageInfo;
+    }
+  };
+
+  /** Some metrics of the last executed query (startTime, endTime, executionTime, itemCount, totalItemCount) */
+  metrics?: Metrics;
+}

package/src/interfaces/graphqlPaginationOption.interface.ts

@@ -0,0 +1,5 @@
+export interface GraphqlPaginationOption {
+  first?: number;
+  last?: number;
+  offset?: number;
+}

package/src/interfaces/graphqlResult.interface.ts

@@ -0,0 +1,10 @@
+import type { Metrics } from '@slickgrid-universal/common';
+
+export interface GraphqlResult<T = any> {
+  data: {
+    [datasetName: string]: T[];
+  };
+
+  /** Some metrics of the last executed query (startTime, endTime, executionTime, itemCount, totalItemCount) */
+  metrics?: Metrics;
+}

package/src/interfaces/graphqlServiceApi.interface.ts

@@ -0,0 +1,29 @@
+import type { BackendServiceApi, Observable } from '@slickgrid-universal/common';
+
+import type { GraphqlResult } from './graphqlResult.interface';
+import type { GraphqlPaginatedResult } from './graphqlPaginatedResult.interface';
+import type { GraphqlServiceOption } from './graphqlServiceOption.interface';
+import type { GraphqlService } from '../services/index';
+
+export interface GraphqlServiceApi extends BackendServiceApi {
+  /** Backend Service Options */
+  options: GraphqlServiceOption;
+
+  /** Backend Service instance (could be OData or GraphQL Service) */
+  service: GraphqlService;
+
+  /** On init (or on page load), what action to perform? */
+  onInit?: (query: string) => Promise<GraphqlResult | GraphqlPaginatedResult> | Observable<GraphqlResult | GraphqlPaginatedResult>;
+
+  /** On Processing, we get the query back from the service, and we need to provide a Promise/Observable. For example: this.http.get(myGraphqlUrl) */
+  process: (query: string) => Promise<GraphqlResult | GraphqlPaginatedResult> | Observable<GraphqlResult | GraphqlPaginatedResult>;
+
+  /** After executing the query, what action to perform? For example, stop the spinner */
+  postProcess?: (response: GraphqlResult | GraphqlPaginatedResult) => void;
+
+  /**
+   * INTERNAL USAGE ONLY by Slickgrid-Universal
+   * This internal process will be run just before postProcess and is meant to refresh the Dataset & Pagination after a GraphQL call
+   */
+  internalPostProcess?: (result: GraphqlResult | GraphqlPaginatedResult) => void;
+}

package/src/interfaces/graphqlServiceOption.interface.ts

@@ -0,0 +1,52 @@
+import type { BackendServiceOption } from '@slickgrid-universal/common';
+
+import type { GraphqlFilteringOption } from './graphqlFilteringOption.interface';
+import type { GraphqlSortingOption } from './graphqlSortingOption.interface';
+import type { GraphqlCursorPaginationOption } from './graphqlCursorPaginationOption.interface';
+import type { GraphqlPaginationOption } from './graphqlPaginationOption.interface';
+import type { QueryArgument } from './queryArgument.interface';
+
+export interface GraphqlServiceOption extends BackendServiceOption {
+  /**
+   * When using Translation, we probably want to add locale as a query parameter for the filterBy/orderBy to work
+   * ex.: users(first: 10, offset: 0, locale: "en-CA", filterBy: [{field: name, operator: EQ, value:"John"}]) { }
+   */
+  addLocaleIntoQuery?: boolean;
+
+  /** What is the dataset, this is required for the GraphQL query to be built */
+  datasetName: string;
+
+  /** Used for defining the operation name when building the GraphQL query */
+  operationName?: string;
+
+  /**
+   * Extra query arguments that be passed in addition to the default query arguments
+   * For example in GraphQL, if we want to pass "userId" and we want the query to look like
+   * users (first: 20, offset: 10, userId: 123) { ... }
+   */
+  extraQueryArguments?: QueryArgument[];
+
+  /** array of Filtering Options, ex.: { field: name, operator: EQ, value: "John" }  */
+  filteringOptions?: GraphqlFilteringOption[];
+
+  /** What are the pagination options? ex.: (first, last, offset) */
+  paginationOptions?: GraphqlPaginationOption | GraphqlCursorPaginationOption;
+
+  /** array of Filtering Options, ex.: { field: name, direction: DESC }  */
+  sortingOptions?: GraphqlSortingOption[];
+
+  /**
+   * Do we want to keep double quotes on field arguments of filterBy/sortBy (field: "name" instead of field: name)
+   * ex.: { field: "name", operator: EQ, value: "John" }
+   */
+  keepArgumentFieldDoubleQuotes?: boolean;
+
+  /** Use Pagination Cursor in the GraphQL Server */
+  useCursor?: boolean;
+
+  /**
+   * When false, searchTerms may be manipulated to be functional with certain filters eg: string only filters.
+   * When true, JSON.stringify is used on the searchTerms and used in the query "as-is". It is then the responsibility of the developer to sanitise the `searchTerms` property if necessary.
+   */
+  useVerbatimSearchTerms?: boolean;
+}

package/src/interfaces/graphqlSortingOption.interface.ts

@@ -0,0 +1,6 @@
+import type { SortDirection, SortDirectionString } from '@slickgrid-universal/common';
+
+export interface GraphqlSortingOption {
+  field: string;
+  direction: SortDirection | SortDirectionString;
+}

package/src/interfaces/index.ts

@@ -0,0 +1,10 @@
+export * from './graphqlCursorPaginationOption.interface';
+export * from './graphqlDatasetFilter.interface';
+export * from './graphqlFilteringOption.interface';
+export * from './graphqlPaginatedResult.interface';
+export * from './graphqlPaginationOption.interface';
+export * from './graphqlResult.interface';
+export * from './graphqlServiceApi.interface';
+export * from './graphqlServiceOption.interface';
+export * from './graphqlSortingOption.interface';
+export * from './queryArgument.interface';

package/src/interfaces/queryArgument.interface.ts

@@ -0,0 +1,4 @@
+export interface QueryArgument {
+  field: string;
+  value: string | number | boolean;
+}