@theseam/ui-common 1.0.2-beta.51 → 1.0.2-beta.57

package/fesm2022/theseam-ui-common-graphql.mjs

@@ -1,14 +1,16 @@
 import { ApolloLink, NetworkStatus, Observable as Observable$1 } from '@apollo/client/core';
 import { print, visit as visit$1, parse, BREAK as BREAK$1, parseValue, Kind, valueFromASTUntyped } from 'graphql';
-import { hasProperty, notNullOrUndefined, isNullOrUndefined, withoutProperty, wrapIntoObservable, withoutProperties } from '@theseam/ui-common/utils';
 import { visit, BREAK } from 'graphql/language';
 import * as i0 from '@angular/core';
 import { isDevMode, InjectionToken, Optional, Inject, Injectable, EventEmitter } from '@angular/core';
+import { hasProperty, notNullOrUndefined, isNullOrUndefined, withoutProperty, wrapIntoObservable, withoutProperties } from '@theseam/ui-common/utils';
 import { Observable, EMPTY, from, defer, of, combineLatest, Subscription, Subject, BehaviorSubject, isObservable } from 'rxjs';
 import { switchMap, tap, take, concatMap, filter, toArray, map, auditTime, distinctUntilChanged, finalize, catchError, shareReplay, startWith, skip } from 'rxjs/operators';
 import * as i1 from 'apollo-angular';
 import { gql, provideApollo } from 'apollo-angular';
 import { THESEAM_COLUMNS_DATA_FILTER_DATE_TEXT_SEARCH_TYPES, getFormattedDateForComparison, THESEAM_COLUMNS_DATA_FILTER_DATE_RANGE_SEARCH_TYPES, THESEAM_COLUMNS_DATA_FILTER_NUMERIC_TEXT_SEARCH_TYPES, THESEAM_COLUMNS_DATA_FILTER_NUMERIC_RANGE_SEARCH_TYPES, THESEAM_COLUMNS_DATA_FILTER_TEXT_TEXT_SEARCH_TYPES } from '@theseam/ui-common/datatable';
+import { faFileCsv } from '@fortawesome/free-solid-svg-icons';
+import FileSaver from 'file-saver';
 import { concat, InMemoryCache } from '@apollo/client';
 
 /**
@@ -44,35 +46,15 @@ function logQueryLink(inner, options) {
     return ApolloLink.from([beforeLink, inner, afterLink]);
 }
 
-class GQLDirection {
-    direction;
-    constructor(direction) {
-        this.direction = direction;
-    }
-    static ASC = new GQLDirection('ASC');
-    static DESC = new GQLDirection('DESC');
-}
-
-var HintsKind;
-(function (HintsKind) {
-    HintsKind["OperationDefinition"] = "OperationDefinition";
-    HintsKind["Field"] = "Field";
-    HintsKind["VariableDefinition"] = "VariableDefinition";
-    HintsKind["Variable"] = "Variable";
-    HintsKind["Argument"] = "Argument";
-})(HintsKind || (HintsKind = {}));
-
-const DEFAULT_TO_REMOVE_ON_UNDEFINED = ['where', 'order'];
-
-class GQLVariable {
-    name;
-    type;
-    constructor(name, type) {
-        this.name = name;
-        this.type = type;
-    }
-}
-
+/**
+ * Checks whether a GraphQL document or value node contains a reference to
+ * the named variable.
+ *
+ * This includes references inside variable definitions — a variable that is
+ * defined but not used as an argument will still be found. This behavior is
+ * relied on by `removeIfNotUsed` processing to avoid removing variables that
+ * may be needed after a later inline step.
+ */
 function containsVariable(node, variableName) {
     let found = false;
     visit(node, {
@@ -86,10 +68,32 @@ function containsVariable(node, variableName) {
     return found;
 }
 
+/**
+ * Creates a variable reference marker for use in filter objects that will be
+ * passed to `toGQL` and inlined into a query.
+ *
+ * When `toGQL` encounters an object with a `gqlVar` property, it emits the
+ * value as-is (e.g. `$search`), producing a GraphQL variable reference in the
+ * output rather than a string literal.
+ *
+ * @example
+ * ```typescript
+ * const filter = { name: { contains: gqlVar('search') } }
+ * // toGQL(filter) → '{name: {contains: $search}}'
+ * ```
+ */
 function gqlVar(varName) {
     return { gqlVar: `$${varName}` };
 }
 
+/**
+ * Replaces all references to a variable in the query body with a literal
+ * value. If the value represents `undefined`, the variable references are
+ * removed from the query instead.
+ *
+ * This does not remove the variable definition — use `removeVariableDefinition`
+ * separately if needed.
+ */
 function inlineVariable(query, variableName, variableValue) {
     // return visit(query, {
     //   VariableDefinition(node) {
@@ -163,6 +167,35 @@ function parseComments(ast) {
     return comments;
 }
 
+class GQLDirection {
+    direction;
+    constructor(direction) {
+        this.direction = direction;
+    }
+    static ASC = new GQLDirection('ASC');
+    static DESC = new GQLDirection('DESC');
+}
+
+var HintsKind;
+(function (HintsKind) {
+    HintsKind["OperationDefinition"] = "OperationDefinition";
+    HintsKind["Field"] = "Field";
+    HintsKind["VariableDefinition"] = "VariableDefinition";
+    HintsKind["Variable"] = "Variable";
+    HintsKind["Argument"] = "Argument";
+})(HintsKind || (HintsKind = {}));
+
+const DEFAULT_TO_REMOVE_ON_UNDEFINED = ['where', 'order'];
+
+class GQLVariable {
+    name;
+    type;
+    constructor(name, type) {
+        this.name = name;
+        this.type = type;
+    }
+}
+
 const HINT_PREFIX_REGEX = /^\s*@gql-hint:.+/;
 const HINT_NAMES_CAPTURE_REGEX = /^\s*@gql-hint:([a-zA-z-\d\s]+)$/;
 /**
@@ -268,6 +301,13 @@ function parseHints(ast) {
         .filter(notNullOrUndefined);
 }
 
+/**
+ * Removes a variable's definition from the query (e.g. `$where: String` in the
+ * operation signature). Does not remove argument references to that variable in
+ * the query body.
+ *
+ * To remove both the definition and argument references, use `removeVariable`.
+ */
 function removeVariableDefinition(query, variableName) {
     return visit$1(query, {
         VariableDefinition: {
@@ -281,6 +321,14 @@ function removeVariableDefinition(query, variableName) {
     });
 }
 
+/**
+ * Removes variable definitions from the specified operation when the variable
+ * does not have a corresponding value in the provided variables object (i.e.
+ * the value is `null` or `undefined`).
+ *
+ * Unlike `removeVariable`, this only removes the definitions — it does not
+ * remove argument references in the query body.
+ */
 function removeVariableDefinitionsNotDefined(query, node, variables) {
     return visit$1(query, {
         OperationDefinition(opDef) {
@@ -298,6 +346,14 @@ function removeVariableDefinitionsNotDefined(query, node, variables) {
     });
 }
 
+/**
+ * Removes a variable from the query by removing both the variable definition
+ * (e.g. `$where: String` in the operation signature) and argument references
+ * with the same name (e.g. `where: $where` in the field arguments).
+ *
+ * To remove only the definition without touching arguments, use
+ * `removeVariableDefinition`.
+ */
 function removeVariable(query, variableName) {
     return visit$1(query, {
         VariableDefinition: {
@@ -468,70 +524,120 @@ const removeNotDefinedHintDef = {
 // ]
 
 /**
- * Apollo link that transforms GraphQL operations before they are sent.
+ * Transforms a GraphQL query and its variables according to the provided
+ * processing configuration.
  *
  * Two mechanisms are supported and can be combined freely:
  *
- * **Hint-based** — place `# @gql-hint: <name>` comments directly in the query.
- * Supported hints:
- * - `remove-not-defined` on the operation definition: removes every variable
- *   whose value is null/undefined (definition + argument usage).
- * - `inline-variable` on a variable definition or usage: substitutes the
- *   variable's current value directly into the query AST and removes it from
- *   the variables map.
+ * **Hint-based** — `# @gql-hint: <name>` comments in the query.
+ * - `remove-not-defined`: removes variables whose value is null/undefined.
+ * - `inline-variable`: substitutes variable values directly into the AST.
  *
- * **Config-based** — pass a `QueryProcessingConfig` via Apollo context under
- * the key `queryProcessingConfig`. Supported options:
- * - `variables.removeIfNotDefined`: remove named variables when null/undefined.
- * - `variables.removeIfNotUsed`: remove named variable definitions when the
- *   variable is not referenced anywhere in the (possibly already-transformed)
- *   query body.
- * - `variables.inline`: inline named variables into the query AST.
+ * **Config-based** — via `QueryProcessingConfig`:
+ * - `removeIfNotDefined`: remove named variables when null/undefined.
+ * - `removeIfNotUsed`: remove named variable definitions when unreferenced.
+ * - `inline`: inline named variables into the query AST.
+ * - `orderTiebreaker`: append a fallback sort field for deterministic pagination.
  *
- * Hints are applied first, then config-based processing.
+ * Hints are applied first, then config-based processing, then cleanup.
  */
-const queryProcessingLink = new ApolloLink((operation, forward) => {
-    const context = operation.getContext();
-    const queryProcessingConfig = context.queryProcessingConfig ?? {};
-    // Reparse to ensure token/comment info is present for hint parsing.
-    let _ast = parseAst(operation.query);
+function processGql(query, variables, queryProcessingConfig) {
+    let _ast = parseAst(query);
+    let _variables = { ...variables };
+    // ---- Hint: remove-not-defined ------------------------------------------
     const rules = parseHints(_ast);
-    // ---- Hint: remove-not-defined ----------------------------------------
     for (const hintsToken of hintsTokensContainingHint(rules, removeNotDefinedHintDef.name)) {
-        const result = removeNotDefinedHintDef.transformer({ query: _ast, variables: operation.variables }, hintsToken);
+        const result = removeNotDefinedHintDef.transformer({ query: _ast, variables: _variables }, hintsToken);
         _ast = result.query;
-        operation.variables = result.variables;
+        _variables = result.variables;
     }
-    // ---- Hint: inline-variable --------------------------------------------
+    // ---- Hint: inline-variable ---------------------------------------------
     for (const hintsToken of hintsTokensContainingHint(rules, inlineVariableHintDef.name)) {
-        const result = inlineVariableHintDef.transformer({ query: _ast, variables: operation.variables }, hintsToken);
+        const result = inlineVariableHintDef.transformer({ query: _ast, variables: _variables }, hintsToken);
         _ast = result.query;
-        operation.variables = result.variables;
+        _variables = result.variables;
     }
-    // ---- Config: removeIfNotDefined ---------------------------------------
+    // ---- Config: removeIfNotDefined ----------------------------------------
     for (const varName of queryProcessingConfig?.variables?.removeIfNotDefined ??
         []) {
-        if (isNullOrUndefined(operation.variables[varName])) {
+        if (isNullOrUndefined(_variables[varName])) {
             _ast = removeVariable(_ast, varName);
         }
     }
-    // ---- Config: removeIfNotUsed -----------------------------------------
-    // Intentionally runs after removeIfNotDefined so that variables which were
-    // only referenced inside another (now-removed) variable can be cleaned up.
+    // ---- Config: removeIfNotUsed -------------------------------------------
     for (const varName of queryProcessingConfig?.variables?.removeIfNotUsed ??
         []) {
         if (!containsVariable(_ast, varName)) {
             _ast = removeVariable(_ast, varName);
         }
     }
-    // ---- Config: inline --------------------------------------------------
+    // ---- Config: inline ----------------------------------------------------
     for (const varName of queryProcessingConfig?.variables?.inline ?? []) {
-        const varValue = operation.variables[varName];
-        operation.variables = withoutProperty(operation.variables, varName);
+        const varValue = _variables[varName];
+        _variables = withoutProperty(_variables, varName);
         _ast = removeVariableDefinition(_ast, varName);
         _ast = inlineVariable(_ast, varName, parseValue(toGQL(varValue)));
     }
-    operation.query = _ast;
+    // ---- Config: orderTiebreaker -------------------------------------------
+    const orderTiebreaker = queryProcessingConfig?.variables?.orderTiebreaker;
+    if (typeof orderTiebreaker === 'string' && orderTiebreaker.length > 0) {
+        const order = _variables['order'];
+        if (!isNullOrUndefined(order) && Array.isArray(order)) {
+            const idx = order.findIndex((x) => x[orderTiebreaker] !== undefined);
+            if (idx === -1) {
+                _variables['order'] = [...order, { [orderTiebreaker]: 'DESC' }];
+            }
+        }
+    }
+    // ---- Cleanup: empty where ----------------------------------------------
+    // Targets inlined filter results like `where: { and: [] }` where the
+    // datatable's automated filter merging produced an empty array. We
+    // intentionally do NOT match deeper nesting (e.g. `where: { status: { in: [] } }`)
+    // — an empty condition at that level likely indicates a real bug in the
+    // filter code that should surface as an error.
+    _ast = visit$1(_ast, {
+        Argument(node) {
+            if (node.name.value === 'where' &&
+                node.value?.fields?.length &&
+                node.value?.fields[0]?.value?.values?.length === 0) {
+                return null;
+            }
+        },
+    });
+    return { query: _ast, variables: _variables };
+}
+
+/**
+ * Apollo link that transforms GraphQL operations before they are sent.
+ *
+ * Two mechanisms are supported and can be combined freely:
+ *
+ * **Hint-based** — place `# @gql-hint: <name>` comments directly in the query.
+ * Supported hints:
+ * - `remove-not-defined` on the operation definition: removes every variable
+ *   whose value is null/undefined (definition + argument usage).
+ * - `inline-variable` on a variable definition or usage: substitutes the
+ *   variable's current value directly into the query AST and removes it from
+ *   the variables map.
+ *
+ * **Config-based** — pass a `QueryProcessingConfig` via Apollo context under
+ * the key `queryProcessingConfig`. Supported options:
+ * - `variables.removeIfNotDefined`: remove named variables when null/undefined.
+ * - `variables.removeIfNotUsed`: remove named variable definitions when the
+ *   variable is not referenced anywhere in the (possibly already-transformed)
+ *   query body.
+ * - `variables.inline`: inline named variables into the query AST.
+ * - `variables.orderTiebreaker`: append a fallback sort field for deterministic
+ *   pagination.
+ *
+ * Hints are applied first, then config-based processing.
+ */
+const queryProcessingLink = new ApolloLink((operation, forward) => {
+    const context = operation.getContext();
+    const queryProcessingConfig = context.queryProcessingConfig ?? {};
+    const result = processGql(operation.query, operation.variables, queryProcessingConfig);
+    operation.query = result.query;
+    operation.variables = result.variables;
     return forward(operation);
 });
 
@@ -990,6 +1096,20 @@ class DatatableGraphQLQueryRef {
         // (including any disablePaging requery).
         switchMap((v) => hasEmittedSubject.pipe(map((hasEmitted) => (hasEmitted ? v : true)))));
     }
+    /**
+     * Returns an observable of mapped rows from the query result.
+     *
+     * The mapper transforms the raw GraphQL response data into the row format
+     * the datatable expects, and provides the total count for pagination.
+     *
+     * @example
+     * ```typescript
+     * this.rows$ = this._queryRef.rows((data) => ({
+     *   rows: data.items.items,
+     *   totalCount: data.items.totalCount,
+     * }))
+     * ```
+     */
     rows(mapper) {
         return this._rowsObservable(mapper);
     }
@@ -1513,6 +1633,80 @@ const mapSearchTextColumnsDataFilterStateToGql = (filterState, context) => {
     return filter;
 };
 
+/**
+ * Abstract transport for server-side datatable exports.
+ *
+ * THIS SHOULD BE IMPLEMENTED AND PROVIDED BY THE APPLICATION USING 'ui-common'.
+ *
+ * Example:
+ * ```ts
+ * bootstrapApplication(AppComponent, {
+ *   providers: [
+ *     provideDatatableExportTransport(AppDatatableExportTransport),
+ *   ],
+ * })
+ * ```
+ */
+class DatatableExportTransport {
+}
+/**
+ * Register the application's `DatatableExportTransport` implementation.
+ *
+ * ```ts
+ * bootstrapApplication(AppComponent, {
+ *   providers: [
+ *     provideDatatableExportTransport(AppDatatableExportTransport),
+ *   ],
+ * })
+ * ```
+ */
+function provideDatatableExportTransport(transportType) {
+    return { provide: DatatableExportTransport, useClass: transportType };
+}
+
+class DatatableGqlDataExporter {
+    _exporterName;
+    _exporterLabel;
+    _columns;
+    _queryRef;
+    _transport;
+    _exportType;
+    get name() {
+        return this._exporterName;
+    }
+    get label() {
+        return this._exporterLabel;
+    }
+    icon = faFileCsv;
+    skipDataMapping = true;
+    constructor(_exporterName, _exporterLabel, _columns, _queryRef, _transport, _exportType) {
+        this._exporterName = _exporterName;
+        this._exporterLabel = _exporterLabel;
+        this._columns = _columns;
+        this._queryRef = _queryRef;
+        this._transport = _transport;
+        this._exportType = _exportType;
+    }
+    export(data) {
+        const options = this._queryRef.getOptions();
+        const { query, variables } = processGql(options.query, this._queryRef.getVariables(), this._queryRef.getQueryProcessingConfig() ?? { variables: {} });
+        const operationName = query.definitions.find((d) => d.kind === 'OperationDefinition')?.name?.value ?? '';
+        const payload = {
+            graphQlQuery: {
+                queryString: print(query),
+                queryVariables: variables,
+                operationName,
+                columns: this._columns,
+            },
+            exportType: this._exportType,
+        };
+        return this._transport.export(payload).pipe(tap((file) => FileSaver.saveAs(file)), map(() => true), catchError((err) => {
+            console.error(err);
+            return of(false);
+        }));
+    }
+}
+
 const baseSchemaFragment = gql `
   input ComparableInt32OperationFilterInput {
     eq: Int
@@ -2168,5 +2362,5 @@ const SIMPLE_GQL_TEST_SEARCH_QUERY = gql `
  * Generated bundle index. Do not edit.
  */
 
-export { DATATABLE_GRAPHQL_SERVICE_CONFIG, DEFAULT_PAGE_SIZE, DEFAULT_TO_REMOVE_ON_UNDEFINED, DatatableGraphQLQueryRef, DatatableGraphqlService, GQLDirection, GQLVariable, HINT_NAMES_CAPTURE_REGEX, HINT_PREFIX_REGEX, HintsKind, MAX_ERROR_RECOVERY_ATTEMPTS, MockDatatable, SIMPLE_GQL_TEST_QUERY, SIMPLE_GQL_TEST_SEARCH_QUERY, baseSchemaFragment, checkRecordsHaveValue, containsVariable, createHintsToken, createMockApolloTestingProvider, createSimpleGqlTestRecord, createSimpleGqlTestRoot, createSortsMapper, filterWhere, filteredResults, getHintsToken, getPageInfo, getTokenAppliesTo, gqlVar, hintNamesFromHintToken, hintsTokensContainingHint, inlineVariable, inlineVariableHintDef, inlineVariableTransformer, isCommentToken, isHintToken, isInlineComment, logQueryLink, mapFilterStates, mapSearchDateColumnsDataFilterStateToGql, mapSearchNumericColumnsDataFilterStateToGql, mapSearchTextColumnsDataFilterStateToGql, mockGraphQLLink, observeRowsWithGqlInputsHandling, parseAst, parseComments, parseHints, queryProcessingLink, removeNotDefinedHintDef, removeNotDefinedTransformer, removeVariable, removeVariableDefinition, removeVariableDefinitionsNotDefined, skipAndTake, sortItems, toGQL };
+export { DATATABLE_GRAPHQL_SERVICE_CONFIG, DEFAULT_PAGE_SIZE, DEFAULT_TO_REMOVE_ON_UNDEFINED, DatatableExportTransport, DatatableGqlDataExporter, DatatableGraphQLQueryRef, DatatableGraphqlService, GQLDirection, GQLVariable, HINT_NAMES_CAPTURE_REGEX, HINT_PREFIX_REGEX, HintsKind, MAX_ERROR_RECOVERY_ATTEMPTS, MockDatatable, SIMPLE_GQL_TEST_QUERY, SIMPLE_GQL_TEST_SEARCH_QUERY, baseSchemaFragment, checkRecordsHaveValue, containsVariable, createHintsToken, createMockApolloTestingProvider, createSimpleGqlTestRecord, createSimpleGqlTestRoot, createSortsMapper, filterWhere, filteredResults, getHintsToken, getPageInfo, getTokenAppliesTo, gqlVar, hintNamesFromHintToken, hintsTokensContainingHint, inlineVariable, inlineVariableHintDef, inlineVariableTransformer, isCommentToken, isHintToken, isInlineComment, logQueryLink, mapFilterStates, mapSearchDateColumnsDataFilterStateToGql, mapSearchNumericColumnsDataFilterStateToGql, mapSearchTextColumnsDataFilterStateToGql, mockGraphQLLink, observeRowsWithGqlInputsHandling, parseAst, parseComments, parseHints, processGql, provideDatatableExportTransport, queryProcessingLink, removeNotDefinedHintDef, removeNotDefinedTransformer, removeVariable, removeVariableDefinition, removeVariableDefinitionsNotDefined, skipAndTake, sortItems, toGQL };
 //# sourceMappingURL=theseam-ui-common-graphql.mjs.map