Add docstrings

Author: lahirumaramba

etc/firebase-admin.data-connect.api.md

@@ -8,11 +8,9 @@
 
 import { Agent } from 'http';
 
-// @public (undocumented)
+// @public
 export interface ConnectorConfig {
-    // (undocumented)
     location: string;
-    // (undocumented)
     serviceId: string;
 }
 
@@ -24,24 +22,23 @@ export class DataConnect {
     readonly app: App;
     // (undocumented)
     readonly connectorConfig: ConnectorConfig;
+    // @beta
     executeGraphql<GraphqlResponse, Variables>(query: string, options?: GraphqlOptions<Variables>): Promise<ExecuteGraphqlResponse<GraphqlResponse>>;
+    // @beta
     executeGraphqlRead<GraphqlResponse, Variables>(query: string, options?: GraphqlOptions<Variables>): Promise<ExecuteGraphqlResponse<GraphqlResponse>>;
 }
 
-// @public (undocumented)
+// @public
 export interface ExecuteGraphqlResponse<GraphqlResponse> {
-    // (undocumented)
     data: GraphqlResponse;
 }
 
 // @public
 export function getDataConnect(connectorConfig: ConnectorConfig, app?: App): DataConnect;
 
-// @public (undocumented)
+// @public
 export interface GraphqlOptions<Variables> {
-    // (undocumented)
     operationName?: string;
-    // (undocumented)
     variables?: Variables;
 }
 

src/data-connect/data-connect-api-client-internal.ts

@@ -27,7 +27,6 @@ import { ConnectorConfig, ExecuteGraphqlResponse, GraphqlOptions } from './data-
 
 // Data Connect backend constants
 const DATA_CONNECT_HOST = 'https://firebasedataconnect.googleapis.com';
-//const DATA_CONNECT_EMULATOR_HOST = 'http://127.0.0.1:9399';
 const DATA_CONNECT_API_URL_FORMAT =
   '{host}/v1alpha/projects/{projectId}/locations/{locationId}/services/{serviceId}:{endpointId}';
 
@@ -117,8 +116,7 @@ export class DataConnectApiClient {
           data,
         };
         const resp = await this.httpClient.send(request);
-        //console.dir(resp, { depth: null });
-        if (resp.data.errors && validator.isArray(resp.data.errors)) {
+        if (resp.data.errors && validator.isNonEmptyArray(resp.data.errors)) {
           const allMessages = resp.data.errors.map((error: { message: any; }) => error.message).join(' ');
           throw new FirebaseDataConnectError(
             DATA_CONNECT_ERROR_CODE_MAPPING.QUERY_ERROR, allMessages);

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

@@ -15,16 +15,42 @@
  * limitations under the License.
  */
 
+/**
+ * Interface representing a Data Connect connector configuration.
+ */
 export interface ConnectorConfig {
+  /**
+   * Location ID of the Data Connect service.
+   */
   location: string;
+
+  /**
+   * Service ID of the Data Connect service.
+   */
   serviceId: string;
 }
 
+/**
+ * Interface representing GraphQL response.
+ */
 export interface ExecuteGraphqlResponse<GraphqlResponse> {
+  /**
+   * Data payload of the GraphQL response.
+   */
   data: GraphqlResponse;
 }
 
+/**
+ * Interface representing GraphQL options.
+ */
 export interface GraphqlOptions<Variables> {
+  /**
+   * Values for GraphQL variables provided in this query or mutation.
+   */
   variables?: Variables;
+
+  /**
+   * The name of the GraphQL operation. Required only if `query` contains multiple operations.
+   */
   operationName?: string;
 }

src/data-connect/data-connect.ts

@@ -17,13 +17,11 @@
 
 import { App } from '../app';
 import { DataConnectApiClient } from './data-connect-api-client-internal';
-//import * as validator from '../utils/validator';
 
 import {
   ConnectorConfig,
   ExecuteGraphqlResponse,
   GraphqlOptions,
-  //GraphqlReadOptions,
 } from './data-connect-api';
 
 export class DataConnectService {
@@ -48,9 +46,9 @@ export class DataConnectService {
   }
 
   /**
- * Returns the app associated with this `DataConnect` instance.
+ * Returns the app associated with this `DataConnectService` instance.
  *
- * @returns The app associated with this `DataConnect` instance.
+ * @returns The app associated with this `DataConnectService` instance.
  */
   get app(): App {
     return this.appInternal;
@@ -65,7 +63,7 @@ export class DataConnect {
   private readonly client: DataConnectApiClient;
 
   /**
- * @param connectorConfig - Connector Config
+ * @param connectorConfig - The connector configuration.
  * @param app - The app for this `DataConnect` service.
  * @constructor
  * @internal
@@ -78,9 +76,10 @@ export class DataConnect {
  * Execute an arbitrary GraphQL query or mutation
  *
  * @param query - The GraphQL query or mutation.
- * @param options - Optional options object when creating a new App Check Token.
+ * @param options - Optional {@link GraphqlOptions} when executing a GraphQL query or mutation.
  *
- * @returns A promise that fulfills with a `Something`.
+ * @returns A promise that fulfills with a `ExecuteGraphqlResponse`.
+ * @beta
  */
   public executeGraphql<GraphqlResponse, Variables>(
     query: string,
@@ -93,9 +92,10 @@ export class DataConnect {
  * Execute an arbitrary read-only GraphQL query
  *
  * @param query - The GraphQL read-only query.
- * @param options - Optional options object when creating a new App Check Token.
+ * @param options - Optional {@link GraphqlOptions} when executing a read-only GraphQL query.
  *
- * @returns A promise that fulfills with a `Something`.
+ * @returns A promise that fulfills with a `ExecuteGraphqlResponse`.
+ * @beta
  */
   public executeGraphqlRead<GraphqlResponse, Variables>(
     query: string,

src/data-connect/index.ts

@@ -36,32 +36,37 @@ export {
 } from './data-connect'
 
 /**
- * Gets the {@link DataConnect} service for the default app
- * or a given app.
+ * Gets the {@link DataConnect} service with the provided connector configuration
+ * for the default app or a given app.
  *
- * `getDataConnect()` can be called with no arguments to access the default
- * app's `DataConnect` service or as `getDataConnect(app)` to access the
+ * `getDataConnect(connectorConfig)` can be called with no app argument to access the default
+ * app's `DataConnect` service or as `getDataConnect(connectorConfig, app)` to access the
  * `DataConnect` service associated with a specific app.
  *
  * @example
  * ```javascript
+ * const connectorConfig: ConnectorConfig = {
+ *  location: 'us-west2',
+ *  serviceId: 'my-service',
+ * };
+ * 
  * // Get the `DataConnect` service for the default app
- * const defaultDataConnect = getDataConnect();
+ * const defaultDataConnect = getDataConnect(connectorConfig);
  * ```
  *
  * @example
  * ```javascript
  * // Get the `DataConnect` service for a given app
- * const otherDataConnect = getDataConnect(otherApp);
+ * const otherDataConnect = getDataConnect(connectorConfig, otherApp);
  * ```
  * 
- * @param connectorConfig - Connector Config
+ * @param connectorConfig - Connector configuration for the `DataConnect` service.
  *
  * @param app - Optional app for which to return the `DataConnect` service.
  *   If not provided, the default `DataConnect` service is returned.
  *
- * @returns The default `DataConnect` service if no app is provided, or the `DataConnect`
- *   service associated with the provided app.
+ * @returns The default `DataConnect` service with the provided connector configuration
+ *  if no app is provided, or the `DataConnect` service associated with the provided app.
  */
 export function getDataConnect(connectorConfig: ConnectorConfig, app?: App): DataConnect {
   if (typeof app === 'undefined') {

test/integration/data-connect.spec.ts

@@ -24,6 +24,13 @@ chai.use(chaiAsPromised);
 const expect = chai.expect;
 
 interface UserResponse {
+  user: {
+    name: string;
+    uid: string;
+  }
+}
+
+interface UsersResponse {
   users: [
     user: {
       id: string;
@@ -33,6 +40,24 @@ interface UserResponse {
   ];
 }
 
+interface UserUpdateResponse {
+  user_upsert: { uid: string }
+}
+
+interface EmailsResponse {
+  emails: [
+    email: {
+      text: string;
+      subject: string;
+      id: string;
+      date: string;
+      from: {
+        name: string;
+      }
+    }
+  ];
+}
+
 interface UserVariables {
   id: string;
 }
@@ -42,76 +67,75 @@ const connectorConfig: ConnectorConfig = {
   serviceId: 'my-service',
 };
 
+const userId = 'QVBJcy5ndXJ3';
+
 describe('getDataConnect()', () => {
 
-  const query1 = 'query ListUsers @auth(level: PUBLIC) { users { uid, name, address } }';
-  const query2 = 'query ListEmails @auth(level: NO_ACCESS) { emails { id subject text date from { name } } }';
-  const getUserQuery = 'query GetUser($id: User_Key!) { user(key: $id) { uid name } }';
+  const queryListUsers = 'query ListUsers @auth(level: PUBLIC) { users { uid, name, address } }';
+  const queryListEmails = 'query ListEmails @auth(level: NO_ACCESS) { emails { id subject text date from { name } } }';
+  const queryGetUserById = 'query GetUser($id: User_Key!) { user(key: $id) { uid name } }';
   const multipleQueries = `
-  ${query1}
-  ${query2}
+  ${queryListUsers}
+  ${queryListEmails}
   `;
-  const mutation = 'mutation user { user_insert(data: {uid: "QVBJcy5ndXJ3", address: "Address", name: "Name"}) }'
-  const mutationUpdate = 'mutation UpdateUser($id: User_Key!) { user_update(key: $id, data: { name: "Name" }) }';
+  const mutation = `mutation user { user_insert(data: {uid: "${userId}", address: "32 St", name: "Fred Car"}) }`;
+  const upsertUser = `mutation UpsertUser($id: String) { 
+  user_upsert(data: { uid: $id, address: "32 St.", name: "Fred" }) }`;
 
   describe('executeGraphql()', () => {
+    it('executeGraphql() successfully executes a GraphQL mutation', async () => {
+      const resp = await getDataConnect(connectorConfig).executeGraphql<UserUpdateResponse, unknown>(
+        upsertUser, { variables: { id: userId } }
+      );
+      //{ data: { user_insert: { uid: 'QVBJcy5ndXJ3' } } }
+      expect(resp.data.user_upsert.uid).to.be.not.empty;
+      expect(resp.data.user_upsert.uid).equals(userId);
+    });
+
     it('executeGraphql() successfully executes a GraphQL', async () => {
-      const resp = await getDataConnect(connectorConfig).executeGraphql<UserResponse, UserVariables>(query1);
-      //console.dir(resp.data.users);
+      const resp = await getDataConnect(connectorConfig).executeGraphql<UsersResponse, UserVariables>(queryListUsers);
       expect(resp.data.users).to.be.not.empty;
       expect(resp.data.users[0].name).to.be.not.undefined;
       expect(resp.data.users[0].address).to.be.not.undefined;
     });
 
     it('executeGraphql() use the operationName when multiple queries are provided', async () => {
-      const resp = await getDataConnect(connectorConfig).executeGraphql(
+      const resp = await getDataConnect(connectorConfig).executeGraphql<EmailsResponse, unknown>(
         multipleQueries, 
         { operationName: 'ListEmails' }
       );
-      console.dir(resp.data);
-      // expect(resp.data.users).to.be.not.empty;
-      // expect(resp.data.users[0].name).to.be.not.undefined;
-      // expect(resp.data.users[0].address).to.be.not.undefined;
-    });
-
-    it('executeGraphql() successfully executes a GraphQL mutation', async () => {
-      const resp = await getDataConnect(connectorConfig).executeGraphql(
-        mutationUpdate, { variables: { id: 'QVBJcy5ndXJ3' } }
-      );
-      console.dir(resp); //{ data: { user_insert: { uid: 'QVBJcy5ndXJ3' } } }
-      //expect(resp.data.users).to.be.not.empty;
-      // expect(resp.data.users[0].name).to.be.not.undefined;
-      // expect(resp.data.users[0].address).to.be.not.undefined;
+      expect(resp.data.emails).to.be.not.empty;
+      expect(resp.data.emails[0].id).to.be.not.undefined;
+      expect(resp.data.emails[0].from.name).to.be.not.undefined;
     });
 
-    it('executeGraphql() should throw for a duplicate key GraphQL mutation', async () => {
+    it('executeGraphql() should throw for a query error', async () => {
       return getDataConnect(connectorConfig).executeGraphql(mutation)
         .should.eventually.be.rejected.and.have.property('code', 'data-connect/query-error');
     });
 
     it('executeGraphql() successfully executes a GraphQL query with variables', async () => {
       const resp = await getDataConnect(connectorConfig).executeGraphql<UserResponse, UserVariables>(
-        getUserQuery,
-        { variables: { id: 'QVBJcy5ndXJ3' } }
+        queryGetUserById,
+        { variables: { id: userId } }
       );
-      console.dir(resp);
-      // expect(resp.data.users).to.be.not.empty;
-      // expect(resp.data.users[0].name).to.be.not.undefined;
-      // expect(resp.data.users[0].address).to.be.not.undefined;
+      expect(resp.data.user.name).to.be.not.undefined;
+      expect(resp.data.user.uid).equals(userId);
     });
   });
 
   describe('executeGraphqlRead()', () => {
     it('executeGraphqlRead() successfully executes a read-only GraphQL', async () => {
-      const resp = await getDataConnect(connectorConfig).executeGraphqlRead<UserResponse, UserVariables>(query1);
+      const resp =
+        await getDataConnect(connectorConfig).executeGraphqlRead<UsersResponse, UserVariables>(queryListUsers);
       expect(resp.data.users).to.be.not.empty;
       expect(resp.data.users[0].name).to.be.not.undefined;
       expect(resp.data.users[0].address).to.be.not.undefined;
     });
 
     it('executeGraphqlRead() should throw for a GraphQL mutation', async () => {
       return getDataConnect(connectorConfig).executeGraphqlRead(mutation)
-        .should.eventually.be.rejected.and.have.property('code', 'data-connect/permission-denied');
+        .should.eventually.be.rejected;
     });
   });
 });