@cubejs-client/react 1.7.13 → 1.7.14

package/src/{QueryRenderer.jsx → QueryRenderer.tsx}

@@ -1,10 +1,23 @@
 import React from 'react';
 import { equals, toPairs, fromPairs } from 'ramda';
 import { isQueryPresent } from '@cubejs-client/core';
+import type { CubeApi, LoadMethodOptions, Query, ResultSet } from '@cubejs-client/core';
 
 import CubeContext from './CubeContext';
-
-export default class QueryRenderer extends React.Component {
+import type {
+  MutexObj,
+  QueryRendererLoadState,
+  QueryRendererProps,
+  QueryRendererRenderProps,
+  QueryRendererState,
+} from './types';
+
+/**
+ * `<QueryRenderer />` a react component that accepts a query, fetches the given query, and uses the render prop to render the resulting data
+ * @stickyTypes QueryRendererProps, QueryRendererRenderProps
+ * @noInheritDoc
+ */
+export default class QueryRenderer extends React.Component<QueryRendererProps, QueryRendererState> {
   static contextType = CubeContext;
 
   static defaultProps = {
@@ -19,11 +32,11 @@ export default class QueryRenderer extends React.Component {
   };
 
   // @deprecated use `isQueryPresent` from `@cubejs-client/core`
-  static isQueryPresent(query) {
+  static isQueryPresent(query: Query | Query[]) {
     return isQueryPresent(query);
   }
 
-  constructor(props) {
+  constructor(props: QueryRendererProps) {
     super(props);
     this.state = {};
     this.mutexObj = {};
@@ -39,7 +52,7 @@ export default class QueryRenderer extends React.Component {
     }
   }
 
-  shouldComponentUpdate(nextProps, nextState) {
+  shouldComponentUpdate(nextProps: QueryRendererProps, nextState: QueryRendererState) {
     const {
       query, queries, render, cubeApi, loadSql, updateOnlyOnStateChange
     } = this.props;
@@ -55,7 +68,7 @@ export default class QueryRenderer extends React.Component {
       || nextProps.updateOnlyOnStateChange !== updateOnlyOnStateChange;
   }
 
-  componentDidUpdate(prevProps) {
+  componentDidUpdate(prevProps: QueryRendererProps) {
     const { query, queries } = this.props;
     if (!equals(prevProps.query, query)) {
       this.load(query);
@@ -66,12 +79,22 @@ export default class QueryRenderer extends React.Component {
     }
   }
 
-  cubeApi() {
+  // These sit after the lifecycle methods because `react/sort-comp` sorts
+  // TypeScript field declarations into `everything-else`, which the configured
+  // order puts after `lifecycle`. Runtime is unaffected: field initializers run
+  // right after `super()`, so the constructor's assignments still win.
+  //
+  // `this.context` is not re-declared: React types it as `any`, and a field
+  // declaration would be emitted at runtime and shadow the context React
+  // assigns.
+  private mutexObj: MutexObj;
+
+  cubeApi(): CubeApi {
     // eslint-disable-next-line react/destructuring-assignment
     return this.props.cubeApi || this.context && this.context.cubeApi;
   }
 
-  load(query) {
+  load(query: Query | Query[]) {
     const { resetResultSetOnChange, cache } = this.props;
     this.setState({
       isLoading: true,
@@ -82,7 +105,7 @@ export default class QueryRenderer extends React.Component {
     const { loadSql } = this.props;
     const cubeApi = this.cubeApi();
 
-    const loadOptions = {
+    const loadOptions: LoadMethodOptions = {
       mutexObj: this.mutexObj,
       mutexKey: 'query',
       ...(cache ? { cache } : {}),
@@ -121,7 +144,7 @@ export default class QueryRenderer extends React.Component {
     }
   }
 
-  loadQueries(queries) {
+  loadQueries(queries?: { [key: string]: Query }) {
     const cubeApi = this.cubeApi();
     const { resetResultSetOnChange, cache } = this.props;
     this.setState({
@@ -130,12 +153,12 @@ export default class QueryRenderer extends React.Component {
       error: null
     });
 
-    const resultPromises = Promise.all(toPairs(queries).map(
+    const resultPromises = Promise.all(toPairs(queries as { [key: string]: Query }).map(
       ([name, query]) => cubeApi.load(query, {
         mutexObj: this.mutexObj,
         mutexKey: name,
         ...(cache ? { cache } : {}),
-      }).then(r => [name, r])
+      }).then((r): [string, ResultSet] => [name, r])
     ));
 
     resultPromises
@@ -157,7 +180,7 @@ export default class QueryRenderer extends React.Component {
     } = this.state;
     const { render } = this.props;
 
-    const loadState = {
+    const loadState: QueryRendererLoadState = {
       error: error ? new Error(error.response?.plainError || error.message || error.toString()) : null,
       resultSet: queries ? (resultSet || {}) : resultSet,
       loadingState: { isLoading },
@@ -165,7 +188,9 @@ export default class QueryRenderer extends React.Component {
     };
 
     if (render) {
-      return render(loadState);
+      // The prop is declared as returning `void` for backwards compatibility,
+      // while what it returns is what gets rendered
+      return render(loadState as QueryRendererRenderProps) as React.ReactNode;
     }
 
     return null;

package/src/QueryRendererWithTotals.tsx

@@ -0,0 +1,24 @@
+import React from 'react';
+import type { TimeDimension } from '@cubejs-client/core';
+
+import QueryRenderer from './QueryRenderer';
+import type { QueryRendererWithTotalsProps } from './types';
+
+const QueryRendererWithTotals = ({ query, ...restProps }: QueryRendererWithTotalsProps) => (
+  <QueryRenderer
+    queries={{
+      // `granularity: null` is sent to the API on purpose to get totals
+      totals: {
+        ...query,
+        dimensions: [],
+        timeDimensions: query.timeDimensions
+          ? query.timeDimensions.map(td => ({ ...td, granularity: null }) as unknown as TimeDimension)
+          : undefined
+      },
+      main: query
+    }}
+    {...restProps}
+  />
+);
+
+export default QueryRendererWithTotals;

package/src/hooks/cube-fetch.ts

@@ -0,0 +1,98 @@
+import { useContext, useEffect, useState, useRef } from 'react';
+import { isQueryPresent } from '@cubejs-client/core';
+import type { MetaMethodOptions, Query } from '@cubejs-client/core';
+
+import CubeContext from '../CubeContext';
+import useDeepCompareMemoize from './deep-compare-memoize';
+import type {
+  CubeFetchArgs,
+  CubeFetchDispatch,
+  CubeFetchMethod,
+  CubeFetchState,
+  MutexObj,
+  UseCubeFetchInternalResult,
+  UseCubeFetchLoadOptions,
+  UseCubeFetchOptions,
+  UseCubeFetchResult,
+} from '../types';
+
+/**
+ * @hidden
+ */
+export function useCubeFetch<T>(
+  method: CubeFetchMethod,
+  options?: UseCubeFetchOptions
+): UseCubeFetchResult<T>;
+
+export function useCubeFetch<T>(
+  method: CubeFetchMethod,
+  options: UseCubeFetchOptions = {}
+): UseCubeFetchInternalResult<T> {
+  const context = useContext(CubeContext);
+  const mutexRef = useRef<MutexObj>({});
+
+  const [response, setResponse] = useState<CubeFetchState<T>>({
+    isLoading: false,
+    response: null,
+  });
+  const [error, setError] = useState<Error | null>(null);
+
+  const { skip = false } = options;
+
+  async function load(loadOptions: UseCubeFetchLoadOptions = {}, ignoreSkip = false) {
+    const cubeApi = options.cubeApi || context?.cubeApi;
+    const query = loadOptions.query || options.query;
+    const onlyViews = 'onlyViews' in loadOptions ? loadOptions.onlyViews : options.onlyViews;
+
+    const queryCondition = method === 'meta' ? true : query && isQueryPresent(query);
+
+    if (cubeApi && (ignoreSkip || !skip) && queryCondition) {
+      setError(null);
+      setResponse({
+        isLoading: true,
+        response: null,
+      });
+
+      const coreOptions: MetaMethodOptions = {
+        mutexObj: mutexRef.current,
+        mutexKey: method,
+        ...(options.baseRequestId ? { baseRequestId: options.baseRequestId } : {}),
+        ...(method === 'meta' && onlyViews ? { onlyViews: true } : {})
+      };
+      const args: CubeFetchArgs = method === 'meta' ? [coreOptions] : [query!, coreOptions];
+      // `method` picks between overloaded `CubeApi` methods, so the call is
+      // dispatched dynamically while keeping `cubeApi` as the receiver
+      const fetchMethod = cubeApi[method] as CubeFetchDispatch;
+
+      try {
+        const fetchResponse = await fetchMethod.apply(cubeApi, args) as T;
+
+        setResponse({
+          response: fetchResponse,
+          isLoading: false,
+        });
+      } catch (fetchError) {
+        setError(fetchError as Error);
+        setResponse({
+          isLoading: false,
+          response: null,
+        });
+      }
+    }
+  }
+
+  useEffect(() => {
+    load();
+    // `order` is read off a single query; an array of queries does not carry it
+  }, useDeepCompareMemoize([
+    Object.keys((options.query as Query | undefined)?.order || {}),
+    options,
+    context,
+  ]));
+
+  return {
+    ...response,
+    error,
+    refetch: (refetchOptions?: UseCubeFetchLoadOptions) => load(refetchOptions, true),
+  };
+}

package/src/hooks/cube-meta.ts

@@ -0,0 +1,8 @@
+import type { Meta } from '@cubejs-client/core';
+
+import { useCubeFetch } from './cube-fetch';
+import type { CubeMetaFetchOptions, UseCubeFetchResult } from '../types';
+
+export function useCubeMeta(options: CubeMetaFetchOptions = {}): UseCubeFetchResult<Meta> {
+  return useCubeFetch<Meta>('meta', options);
+}

package/src/hooks/{cube-query.js → cube-query.ts}

@@ -1,21 +1,87 @@
 import { useContext, useEffect, useState, useRef } from 'react';
 import { isQueryPresent, areQueriesEqual } from '@cubejs-client/core';
+import type {
+  DeeplyReadonly,
+  ProgressResponse,
+  Query,
+  QueryRecordType,
+  ResultSet,
+  UnsubscribeObj,
+} from '@cubejs-client/core';
 
 import CubeContext from '../CubeContext';
 import useDeepCompareMemoize from './deep-compare-memoize';
-
-export function useCubeQuery(query, options = {}) {
-  const mutexRef = useRef({});
-  const [currentQuery, setCurrentQuery] = useState(null);
+import type {
+  MutexObj,
+  ProgressCallback,
+  ProgressResultWithResponse,
+  ReadonlyQueryInput,
+  UseCubeQueryInternalResult,
+  UseCubeQueryOptions,
+  UseCubeQueryResult,
+} from '../types';
+
+/**
+ * A React hook for executing Cube.js queries
+ * ```js
+ * import React from 'react';
+ * import { Table } from 'antd';
+ * import { useCubeQuery }  from '@cubejs-client/react';
+ *
+ * export default function App() {
+ *   const { resultSet, isLoading, error, progress } = useCubeQuery({
+ *     measures: ['Orders.count'],
+ *     dimensions: ['Orders.createdAt.month'],
+ *   });
+ *
+ *   if (isLoading) {
+ *     return <div>{progress?.stage || 'Loading...'}</div>;
+ *   }
+ *
+ *   if (error) {
+ *     return <div>{error.toString()}</div>;
+ *   }
+ *
+ *   if (!resultSet) {
+ *     return null;
+ *   }
+ *
+ *   const dataSource = resultSet.tablePivot();
+ *   const columns = resultSet.tableColumns();
+ *
+ *   return <Table columns={columns} dataSource={dataSource} />;
+ * }
+ *
+ * ```
+ * @order 1
+ * @stickyTypes
+ */
+export function useCubeQuery<
+  Data,
+  QueryInput extends ReadonlyQueryInput = ReadonlyQueryInput
+>(
+  query: QueryInput,
+  options?: UseCubeQueryOptions
+): UseCubeQueryResult<QueryInput, unknown extends Data ? QueryRecordType<QueryInput> : Data>;
+
+export function useCubeQuery(
+  query: ReadonlyQueryInput,
+  options: UseCubeQueryOptions = {}
+): UseCubeQueryInternalResult {
+  const mutexRef = useRef<MutexObj>({});
+  const [currentQuery, setCurrentQuery] = useState<ReadonlyQueryInput | null>(null);
   const [isLoading, setLoading] = useState(!options.skip);
-  const [resultSet, setResultSet] = useState(null);
-  const [progress, setProgress] = useState(null);
-  const [error, setError] = useState(null);
+  const [resultSet, setResultSet] = useState<ResultSet | null>(null);
+  const [progress, setProgress] = useState<ProgressResponse | null>(null);
+  const [error, setError] = useState<Error | null>(null);
   const context = useContext(CubeContext);
 
-  let subscribeRequest = null;
+  let subscribeRequest: UnsubscribeObj | null = null;
 
-  const progressCallback = ({ progressResponse }) => setProgress(progressResponse);
+  // `progressResponse` is not part of the public `ProgressResult` API
+  const progressCallback: ProgressCallback = (progressResult) => setProgress(
+    (progressResult as unknown as ProgressResultWithResponse).progressResponse
+  );
 
   async function fetch() {
     const { resetResultSetOnChange } = options;
@@ -43,8 +109,8 @@ export function useCubeQuery(query, options = {}) {
 
       setResultSet(response);
       setProgress(null);
-    } catch (error) {
-      setError(error);
+    } catch (loadError) {
+      setError(loadError as Error);
       setResultSet(null);
       setProgress(null);
     }
@@ -63,7 +129,11 @@ export function useCubeQuery(query, options = {}) {
 
     async function loadQuery() {
       if (!skip && isQueryPresent(query)) {
-        if (!areQueriesEqual(currentQuery, query)) {
+        // `areQueriesEqual` is declared for a single query, and reads no more
+        // than `order` off one when given an array of queries
+        const previousQuery = currentQuery as DeeplyReadonly<Query> | null;
+
+        if (!areQueriesEqual(previousQuery, query as DeeplyReadonly<Query>)) {
           if (resetResultSetOnChange == null || resetResultSetOnChange) {
             setResultSet(null);
           }
@@ -102,7 +172,7 @@ export function useCubeQuery(query, options = {}) {
             await fetch();
           }
         } catch (e) {
-          setError(e);
+          setError(e as Error);
           setResultSet(null);
           setLoading(false);
           setProgress(null);
@@ -118,7 +188,13 @@ export function useCubeQuery(query, options = {}) {
         subscribeRequest = null;
       }
     };
-  }, useDeepCompareMemoize([query, Object.keys((query && query.order) || {}), options, context]));
+    // `order` is read off a single query; an array of queries does not carry it
+  }, useDeepCompareMemoize([
+    query,
+    Object.keys((query as DeeplyReadonly<Query> | undefined)?.order || {}),
+    options,
+    context,
+  ]));
 
   return {
     isLoading,

package/src/hooks/cube-sql.ts

@@ -0,0 +1,22 @@
+import type { DryRunResponse, Query, SqlQuery } from '@cubejs-client/core';
+
+import { useCubeFetch } from './cube-fetch';
+import type { UseCubeFetchOptions, UseCubeFetchResult } from '../types';
+
+/**
+ * The hook resolves with a `SqlQuery`, while its `response` stays declared as a
+ * dry-run response for backwards compatibility — `UseCubeSqlResult` spells the
+ * real shape. `refetch` is declared, as it is on `useDryRun` and `useCubeMeta`,
+ * because all three return the same object.
+ *
+ * @hidden
+ */
+export function useCubeSql(
+  query: Query | Query[],
+  options: UseCubeFetchOptions = {}
+): UseCubeFetchResult<DryRunResponse> {
+  return useCubeFetch<SqlQuery>('sql', {
+    ...options,
+    query
+  }) as unknown as UseCubeFetchResult<DryRunResponse>;
+}

package/src/hooks/{deep-compare-memoize.js → deep-compare-memoize.ts}

@@ -1,8 +1,8 @@
 import { useRef } from 'react';
 import { equals } from 'ramda';
 
-export default function useDeepCompareMemoize(value) {
-  const ref = useRef([]);
+export default function useDeepCompareMemoize(value: unknown[]): unknown[] {
+  const ref = useRef<unknown[]>([]);
 
   if (!equals(value, ref.current)) {
     ref.current = value;

package/src/hooks/dry-run.ts

@@ -0,0 +1,17 @@
+import type { DryRunResponse, Query } from '@cubejs-client/core';
+
+import { useCubeFetch } from './cube-fetch';
+import type { UseCubeFetchOptions, UseCubeFetchResult } from '../types';
+
+/**
+ * @hidden
+ */
+export function useDryRun(
+  query: Query | Query[],
+  options: UseCubeFetchOptions = {}
+): UseCubeFetchResult<DryRunResponse> {
+  return useCubeFetch<DryRunResponse>('dryRun', {
+    ...options,
+    query,
+  });
+}

package/src/hooks/lazy-dry-run.ts

@@ -0,0 +1,24 @@
+import type { DryRunResponse, Query } from '@cubejs-client/core';
+
+import { useCubeFetch } from './cube-fetch';
+import type {
+  CubeFetchResult,
+  UseCubeFetchLoadOptions,
+  UseCubeFetchOptions,
+} from '../types';
+
+/**
+ * @hidden
+ */
+export function useLazyDryRun(
+  query?: Query | Query[],
+  options: UseCubeFetchOptions = {}
+): [(loadOptions?: UseCubeFetchLoadOptions) => Promise<void>, CubeFetchResult<DryRunResponse>] {
+  const { refetch, ...result } = useCubeFetch<DryRunResponse>('dryRun', {
+    ...options,
+    query,
+    skip: true
+  });
+
+  return [refetch, result];
+}

package/src/index.ts

@@ -0,0 +1,77 @@
+/**
+ * @title @cubejs-client/react
+ * @permalink /@cubejs-client-react
+ * @menuCategory Reference
+ * @subcategory Frontend
+ * @menuOrder 3
+ * @description `@cubejs-client/react` provides React Components for easy Cube.js integration in a React app.
+ */
+import QueryRenderer from './QueryRenderer';
+import QueryRendererWithTotals from './QueryRendererWithTotals';
+import QueryBuilder from './QueryBuilder';
+import CubeProvider from './CubeProvider';
+import CubeContext from './CubeContext';
+
+export * from './hooks/cube-sql';
+export * from './hooks/dry-run';
+export * from './hooks/lazy-dry-run';
+export * from './hooks/cube-query';
+export * from './hooks/cube-meta';
+
+export type {
+  AvailableCube,
+  AvailableMembers,
+  ChartType,
+  CubeContextProps,
+  CubeFetchOptions,
+  CubeFetchResult,
+  CubeMetaFetchOptions,
+  CubeProviderOptions,
+  CubeProviderProps,
+  DimensionUpdater,
+  FilterExtraFields,
+  FilterUpdateFields,
+  FilterUpdater,
+  FilterWithExtraFields,
+  GranularityOption,
+  GranularityOptions,
+  LoadLazyDryRunOptions,
+  MeasureUpdater,
+  MemberUpdater,
+  OrderUpdater,
+  PivotConfigExtraUpdateFields,
+  PivotConfigUpdater,
+  PivotConfigUpdaterArgs,
+  QueryBuilderProps,
+  QueryBuilderRenderProps,
+  QueryBuilderState,
+  QueryRendererProps,
+  QueryRendererRenderProps,
+  QueryRendererWithTotalsProps,
+  ReadonlyQueryInput,
+  SchemaChangeProps,
+  SegmentUpdater,
+  TimeDimensionComparisonUpdateFields,
+  TimeDimensionExtraFields,
+  TimeDimensionRangedUpdateFields,
+  TimeDimensionUpdater,
+  TimeDimensionWithExtraFields,
+  TLoadingState,
+  UseCubeFetchLoadOptions,
+  UseCubeFetchOptions,
+  UseCubeFetchResult,
+  UseCubeQueryOptions,
+  UseCubeQueryResult,
+  UseCubeSqlResponse,
+  UseCubeSqlResult,
+  UseDryRunResult,
+  VizState,
+} from './types';
+
+export {
+  QueryRenderer,
+  QueryRendererWithTotals,
+  QueryBuilder,
+  CubeContext,
+  CubeProvider,
+};