feat(data-connect): Add validateArgsWithOptions()

.changeset/funny-apples-pay.md

@@ -0,0 +1,6 @@
+---
+'@firebase/data-connect': minor
+'firebase': minor
+---
+
+Add validateArgsWithOptions() to Data Connect

common/api-review/data-connect.api.md

@@ -165,7 +165,7 @@ export function executeMutation<Data, Variables>(mutationRef: MutationRef<Data,
 // @public
 export function executeQuery<Data, Variables>(queryRef: QueryRef<Data, Variables>, options?: ExecuteQueryOptions): QueryPromise<Data, Variables>;
 
-// @public (undocumented)
+// @public
 export interface ExecuteQueryOptions {
     // (undocumented)
     fetchPolicy: QueryFetchPolicy;

packages/data-connect/src/api/index.ts

@@ -39,7 +39,7 @@ export * from './Reference';
 export * from './Mutation';
 export * from './query';
 export { setLogLevel } from '../logger';
-export { validateArgs } from '../util/validateArgs';
+export { validateArgs, validateArgsWithOptions } from '../util/validateArgs';
 export {
   DataConnectErrorCode,
   Code,

packages/data-connect/src/core/query/queryOptions.ts

@@ -23,11 +23,13 @@ export const QueryFetchPolicy = {
 
 /*
  * Represents policy for how executeQuery fetches data
- *
  */
 export type QueryFetchPolicy =
   (typeof QueryFetchPolicy)[keyof typeof QueryFetchPolicy];
 
+/**
+ * Options for executing a query.
+ */
 export interface ExecuteQueryOptions {
   fetchPolicy: QueryFetchPolicy;
 }

packages/data-connect/src/util/validateArgs.ts

@@ -15,44 +15,114 @@
  * limitations under the License.
  */
 
+import { ExecuteQueryOptions } from '../api';
 import {
   ConnectorConfig,
   DataConnect,
   getDataConnect
 } from '../api/DataConnect';
 import { Code, DataConnectError } from '../core/error';
+
 interface ParsedArgs<Variables> {
   dc: DataConnect;
   vars: Variables;
+  options?: ExecuteQueryOptions;
 }
 
 /**
- * The generated SDK will allow the user to pass in either the variable or the data connect instance with the variable,
- * and this function validates the variables and returns back the DataConnect instance and variables based on the arguments passed in.
+ * The generated SDK will allow the user to pass in either the variables or the data connect instance
+ * with the variables. This function validates the variables and returns back the DataConnect instance
+ * and variables based on the arguments passed in.
+ *
+ * Generated SDKs generated from versions 3.2.0 and lower of the Data Connect emulator binary are
+ * NOT concerned with options, and will use this function to validate arguments.
+ *
  * @param connectorConfig
  * @param dcOrVars
  * @param vars
- * @param validateVars
+ * @param variablesRequired
  * @returns {DataConnect} and {Variables} instance
  * @internal
  */
 export function validateArgs<Variables extends object>(
   connectorConfig: ConnectorConfig,
   dcOrVars?: DataConnect | Variables,
   vars?: Variables,
-  validateVars?: boolean
+  variablesRequired?: boolean
 ): ParsedArgs<Variables> {
   let dcInstance: DataConnect;
   let realVars: Variables;
-  if (dcOrVars && 'enableEmulator' in dcOrVars) {
+
+  const dcFirstArg = dcOrVars && 'enableEmulator' in dcOrVars;
+
+  if (dcFirstArg) {
     dcInstance = dcOrVars as DataConnect;
     realVars = vars as Variables;
   } else {
     dcInstance = getDataConnect(connectorConfig);
     realVars = dcOrVars as Variables;
   }
-  if (!dcInstance || (!realVars && validateVars)) {
+
+  if (!dcInstance || (!realVars && variablesRequired)) {
     throw new DataConnectError(Code.INVALID_ARGUMENT, 'Variables required.');
   }
+
   return { dc: dcInstance, vars: realVars };
 }
+
+/**
+ * The generated SDK will allow the user to pass in either the variables or the data connect instance
+ * with the variables, and/or options. This function validates the variables and returns back the
+ * DataConnect instance and variables, and potentially options, based on the arguments passed in.
+ *
+ * Generated SDKs generated from versions 3.2.0 and higher of the Data Connect emulator binary are
+ * in fact concerned with options, and will use this function to validate arguments.
+ *
+ * @param connectorConfig
+ * @param dcOrVarsOrOptions
+ * @param varsOrOptions
+ * @param variablesRequired
+ * @param options
+ * @returns {DataConnect} and {Variables} instance, and optionally {ExecuteQueryOptions}
+ * @internal
+ */
+export function validateArgsWithOptions<Variables extends object>(
+  connectorConfig: ConnectorConfig,
+  dcOrVarsOrOptions?: DataConnect | Variables | ExecuteQueryOptions,
+  varsOrOptions?: Variables | ExecuteQueryOptions,
+  options?: ExecuteQueryOptions,
+  hasVars?: boolean,
+  variablesRequired?: boolean
+): ParsedArgs<Variables> {
+  let dcInstance: DataConnect;
+  let realVars: Variables;
+  let realOptions: ExecuteQueryOptions;
+
+  const dcFirstArg = dcOrVarsOrOptions && 'enableEmulator' in dcOrVarsOrOptions;
+
+  if (dcFirstArg) {
+    dcInstance = dcOrVarsOrOptions as DataConnect;
+    if (hasVars) {
+      realVars = varsOrOptions as Variables;
+      realOptions = options as ExecuteQueryOptions;
+    } else {
+      realVars = undefined as unknown as Variables;
+      realOptions = varsOrOptions as ExecuteQueryOptions;
+    }
+  } else {
+    dcInstance = getDataConnect(connectorConfig);
+    if (hasVars) {
+      realVars = dcOrVarsOrOptions as Variables;
+      realOptions = varsOrOptions as ExecuteQueryOptions;
+    } else {
+      realVars = undefined as unknown as Variables;
+      realOptions = dcOrVarsOrOptions as ExecuteQueryOptions;
+    }
+  }
+
+  if (!dcInstance || (!realVars && variablesRequired)) {
+    throw new DataConnectError(Code.INVALID_ARGUMENT, 'Variables required.');
+  }
+
+  return { dc: dcInstance, vars: realVars, options: realOptions };
+}