Add typings for stripes-connect sources

smart-components/lib/SearchAndSort/ConnectedSource/ApolloConnectedSource.d.ts

@@ -0,0 +1,16 @@
+import Logger from '../../../../util/logger';
+import { ApolloConnectedSourceProps, ApolloError, ConnectedSource } from './ConnectedSource';
+
+export default class ApolloConnectedSource implements ConnectedSource {
+  constructor(props: ApolloConnectedSourceProps, logger: Logger, resourceName?: string);
+  records(): unknown[];
+  resultCount(): number;
+  totalCount(): number | null | undefined;
+  pending(): boolean;
+  loaded(): boolean;
+  failure(): ApolloError | null | undefined;
+
+  failureMessage(): string;
+  fetchMore(increment: number): void;
+  successfulMutations(): unknown[];
+}

smart-components/lib/SearchAndSort/ConnectedSource/ConnectedSource.d.ts

@@ -0,0 +1,127 @@
+import Logger from '../../../../util/logger';
+import { QueryFunction } from '../makeQueryFunction';
+
+type ApolloError = {
+  message: string;
+  graphQLErrors: unknown[];
+  networkError: Error | null;
+  extraInfo: any;
+};
+
+export interface ApolloConnectedSourceProps {
+  apolloResource?: string;
+  apolloRecordsKey: string;
+  queryFunction: QueryFunction;
+  parentData: {
+    // properties directly on parentData
+    loading?: boolean;
+    successfulMutations?: unknown[];
+    error?: ApolloError;
+    fetchMore(params: {
+      variables: {
+        cql: string;
+        offset: number;
+        limit: number;
+      };
+      // record key is `apolloResource`
+      updateQuery: (
+        prev: Record<string, { records: unknown[] }>,
+        params: { fetchMoreResult: unknown },
+      ) => Record<string, { records: unknown[] }>;
+    }): void;
+  } & {
+    // all within resource name (within recordsObj)
+    [resourceName: string]: {
+      totalRecords?: number;
+    } & {
+      // equals apolloRecordsKey
+      [recordsKey: string]: unknown[];
+    };
+  };
+  parentResources: {
+    query: Record<string, unknown>;
+  };
+}
+
+type StripesError = {
+  dataKey?: string;
+  httpStatus?: unknown;
+  message?: string;
+  module?: unknown;
+  resource?: unknown;
+  throwErrors?: unknown;
+};
+
+type StripesResourceType = {
+  resultCount: number;
+  notes?: string | boolean;
+  filters?: string;
+} & {
+  // called recordsObj in code
+  [resourceName: string]: {
+    records?: unknown[];
+    hasLoaded?: boolean;
+    isPending?: boolean;
+    failed?: StripesError;
+    other?: unknown;
+    successfulMutations?: unknown[];
+  };
+};
+type StripesMutatorType = {
+  resultCount: {
+    replace: (count: number) => void;
+  };
+  resultOffset: {
+    replace: (offset: number) => void;
+  };
+  query: {
+    replace: (query: unknown) => void;
+    update: (query: unknown) => void;
+  };
+};
+
+export interface StripesConnectedSourceProps {
+  // key is from resourceName
+  parentResources: StripesResourceType;
+  resources?: StripesResourceType;
+  parentMutator?: StripesMutatorType;
+  mutator?: StripesMutatorType;
+}
+
+export interface ConnectedSource {
+  records(): unknown[];
+
+  /** Number of records retrieved so far */
+  resultCount(): number;
+  /**
+   * Number of records in the result-set, available to be retrieved.
+   *
+   * For {@code StripesConnectedSource}, when there are > 10k results to a search, the `totalRecords`
+   * value comes back as `999999999`, so we use that value to indicate
+   * that the count is, in fact, undefined vs returning null to indicate
+   * that the count has not been calculated.
+   */
+  totalCount(): number | null | undefined;
+
+  /** True only during a request, false before and after */
+  pending(): boolean;
+
+  /** True only after a request, false before and during */
+  loaded(): boolean;
+
+  failure(): ApolloError | StripesError | undefined | null;
+
+  failureMessage(): string;
+
+  fetchMore(increment: number): void;
+
+  successfulMutations(): unknown[];
+}
+
+export type ConnectedSourceProps = ApolloConnectedSourceProps | StripesConnectedSourceProps;
+
+export default function makeConnectedSource(
+  props: ConnectedSourceProps,
+  logger: Logger,
+  resourceName?: string,
+): ConnectedSource | null;

smart-components/lib/SearchAndSort/ConnectedSource/StripesConnectedSource.d.ts

@@ -0,0 +1,18 @@
+import { StripesConnectedSourceProps, ConnectedSource, StripesError } from './ConnectedSource';
+import Logger from '../../../../util/logger';
+
+export default class StripesConnectedSource implements ConnectedSource {
+  constructor(props: StripesConnectedSourceProps, logger: Logger, resourceName?: string);
+  update(props: StripesConnectedSourceProps, resourceName?: string): void;
+  records(): unknown[];
+  resultCount(): number;
+  totalCount(): number | null | undefined;
+  pending(): boolean;
+  loaded(): boolean;
+  failure(): StripesError | null | undefined;
+  failureMessage(): string;
+  fetchMore(increment: number): void;
+  fetchByBrowsePoint(browsePoint: unknown): void;
+  fetchOffset(index: number): void;
+  successfulMutations(): unknown[];
+}

smart-components/lib/SearchAndSort/ConnectedSource/index.d.ts

@@ -0,0 +1,7 @@
+export {
+  default,
+  ConnectedSource,
+  ConnectedSourceProps,
+  ApolloConnectedSourceProps,
+  StripesConnectedSourceProps,
+} from './ConnectedSource';

smart-components/lib/SearchAndSort/makeQueryFunction.d.ts

@@ -0,0 +1,52 @@
+import { FilterGroupsConfig } from '../../../components';
+import Logger from '../../../util/logger';
+import { NsParamsType } from './nsQueryFunctions';
+
+/**
+ * Returns a string, or null, which stripes-connect will use to construct a resource query.
+ *
+ * Accepts four params:
+ * @param queryParams An object containing the UI URL's query parameters (as accessed by ?{name}).
+ * @param pathComponents An object containing the UI URL's path components (as accessed by :{name}).
+ * @param resourceData An object containing the component's resources' data (as accessed by %{name}).
+ * @param logger A logger object.
+ */
+export type QueryFunction = (
+  queryParams: Record<string, unknown>,
+  pathComponents: Record<string, unknown>,
+  resourceData: { query: Record<string, unknown> },
+  logger: Logger,
+) => string | null;
+
+/**
+ * Builds a {@link QueryFunction}
+ *
+ * @param findAll CQL query to retrieve all records when there is a sort clause but no CQL query
+ * @param queryTemplate CQL query to interpolate, or function which will return CQL
+ * @param sortMap map from sort keys to CQL fields
+ * @param filterConfig list of filter objects, see {@link FilterGroupsConfig}
+ * @param failOnCondition one of the following:
+ *   - 0 (or false (legacy)): do not fail even if query and filters and empty
+ *   - 1 (or true (legacy)): fail if query is empty, whatever the filter state
+ *   - 2: fail if both query and filters and empty
+ * @param nsParams namespace keys
+ * @param configOrEscape an object containing configuration parameters:
+ *   - escape: whether to escape the query string (default true)
+ *   - rightTrunc: whether to right-truncate the query string (default true)
+ * For backwards compatibility, this parameter may also be a boolean, in which case it is used as the `escape` configuration value.
+ */
+export default function makeQueryFunction(
+  findAll: string,
+  queryTemplate:
+    | string
+    | ((
+        nsQueryParams: Record<string, unknown>,
+        pathComponents: Record<string, unknown>,
+        queryObj: { query: Record<string, unknown> },
+      ) => string),
+  sortMap: Record<string, string>,
+  filterConfig: FilterGroupsConfig,
+  failOnCondition: 0 | 1 | 2 | true | false,
+  nsParams: NsParamsType,
+  configOrEscape: boolean | { escape?: boolean; rightTrunc?: boolean },
+): QueryFunction;

smart-components/lib/SearchAndSort/nsQueryFunctions.d.ts

@@ -0,0 +1,32 @@
+export type NsParamsType = string | Record<string, unknown> | undefined | null;
+
+export function getNsKey(key: string, params?: NsParamsType): string;
+
+/**
+ *
+ * Adds namespace / prefix to keys in whitelist for given values object
+ *
+ * @example
+ * ```
+ * values = mapNsKeys({ query: "test", filters: 'active', userId: 1 }, 'users')
+ * // result: { "users.query" : "test", "users.filters": "active", userId: 1 }
+ * ```
+ */
+export function mapNsKeys(
+  values: Record<string, unknown>,
+  params?: NsParamsType,
+): Record<string, unknown>;
+
+/**
+ * Removes namespace / prefix from keys for given values object
+ *
+ * @example
+ * ```
+ * values = removeNsKeys({ "users.query" : "test", "users.filters": "active" }, 'users')
+ * // result: { query: "test", filters: 'active' }
+ * ```
+ */
+export function removeNsKeys(
+  values: Record<string, unknown>,
+  params?: NsParamsType,
+): Record<string, unknown>;

util/logger.d.ts

@@ -0,0 +1,3 @@
+// TODO: actual typings for stripes logger
+declare type Logger = (...args: any) => void;
+export default Logger;