Release v0.11.0 (#175)

.eslintrc.js

@@ -1,15 +1,24 @@
 module.exports = {
   parser: '@typescript-eslint/parser',
+  ignorePatterns: [
+    'src/gen/**/*.ts',
+    'src/**/*.test.ts',
+  ],
   env: {
     node: true,
   },
+  plugins: [
+    "jsdoc",
+  ],
   extends: [
     'plugin:@typescript-eslint/eslint-recommended',
     'plugin:@typescript-eslint/recommended',
+    'plugin:jsdoc/recommended-typescript-error',
   ],
   rules: {
     '@typescript-eslint/explicit-function-return-type': 'off',
     '@typescript-eslint/ban-ts-ignore': 'off',
     '@typescript-eslint/no-explicit-any': 'off',
+    'jsdoc/tag-lines': 'off', // not documented on jsdoc plugin site, unsure how to correct.
   },
 };

.github/workflows/test.yaml

@@ -10,25 +10,27 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-    - name: Checkout
-      uses: actions/checkout@v2
-    - name: Cache Yarn Cache
-      uses: actions/cache@v2
-      with:
-        path: 'node_modules'
-        key: ${{ runner.os }}-modules-${{ hashFiles('yarn.lock') }}
-    - name: Install modules
-      run: yarn --frozen-lockfile
-    - name: License Header Check
-      run: yarn license:header:check
-    - name: OSS License Whitelist Check
-      run: yarn license:check
-    - name: Check sources
-      run: |
-        yarn gen:proto
-        git add .
-        git diff --cached --quiet
-    - name: Build
-      run: yarn build
-    - name: Run tests
-      run: yarn coverage:upload
+      - name: Checkout
+        uses: actions/checkout@v2
+      - name: Cache Yarn Cache
+        uses: actions/cache@v2
+        with:
+          path: 'node_modules'
+          key: ${{ runner.os }}-modules-${{ hashFiles('yarn.lock') }}
+      - name: Install modules
+        run: yarn --frozen-lockfile
+      - name: License Header Check
+        run: yarn license:header:check
+      - name: OSS License Whitelist Check
+        run: yarn license:check
+      - name: Check sources
+        run: |
+          yarn gen:proto
+          git add .
+          git diff --cached --quiet
+      - name: Check Formatting
+        run: yarn prettier:check
+      - name: Build
+        run: yarn build
+      - name: Run tests
+        run: yarn coverage:upload

.prettierignore

@@ -0,0 +1 @@
+**/src/gen

package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nitric/sdk",
   "description": "Nitric NodeJS client sdk",
-  "nitric": "v0.20.0",
+  "nitric": "v0.22.0",
   "author": "Nitric <https://github.com/nitrictech>",
   "repository": "https://github.com/nitrictech/node-sdk",
   "main": "lib/index.js",
@@ -31,6 +31,14 @@
   ],
   "dependencies": {
     "@grpc/grpc-js": "1.8.1",
+    "@opentelemetry/api": "^1.4.1",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.36.1",
+    "@opentelemetry/instrumentation": "^0.36.1",
+    "@opentelemetry/instrumentation-grpc": "^0.36.1",
+    "@opentelemetry/instrumentation-http": "^0.36.1",
+    "@opentelemetry/resources": "^1.10.1",
+    "@opentelemetry/sdk-trace-node": "^1.10.1",
+    "@opentelemetry/semantic-conventions": "^1.10.1",
     "google-protobuf": "3.14.0",
     "tslib": "^2.1.0"
   },
@@ -50,6 +58,7 @@
     "@typescript-eslint/parser": "^4.22.0",
     "codecov": "^3.8.3",
     "eslint": "^7.24.0",
+    "eslint-plugin-jsdoc": "^40.1.0",
     "glob-run": "^0.1.7",
     "grpc-tools": "^1.11.3",
     "husky": "^6.0.0",

src/api/documents/index.ts

@@ -11,4 +11,4 @@
 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 // See the License for the specific language governing permissions and
 // limitations under the License.
-export * from './v0';
+export * from './v0';

src/api/documents/v0/collection-group-ref.ts

@@ -41,8 +41,10 @@ export class CollectionGroupRef<T extends DocumentStructure> {
   }
 
   /**
-   * Create a CollectionGroupRef referencing a sub-collection of this collection
-   * @param name
+   * Create a CollectionGroupRef referencing a sub-collection of this collection.
+   *
+   * @param name of the sub-collection
+   * @returns a reference to the sub-collection
    */
   public collection<T extends DocumentStructure>(
     name: string
@@ -56,7 +58,8 @@ export class CollectionGroupRef<T extends DocumentStructure> {
   }
 
   /**
-   * Create a new collection query object
+   * Create a new collection query object.
+   *
    * @returns a new collection query object
    */
   public query(): Query<T> {
@@ -88,9 +91,12 @@ export class CollectionGroupRef<T extends DocumentStructure> {
   }
 
   /**
-   * Creates a collection group reference from a collection reference
-   * @param ref
-   * @param dc
+   * Creates a collection group reference from a collection reference.
+   *
+   * @internal
+   * @param ref a collection reference.
+   * @param dc a document service client.
+   * @returns a collection group reference.
    */
   public static fromCollectionRef(
     ref: CollectionRef<any>,

src/api/documents/v0/collection-ref.ts

@@ -38,10 +38,12 @@ export class CollectionRef<T extends DocumentStructure> {
   }
 
   /**
-   * Return a reference to a subcollection within the documents of this collection.
+   * Return a reference to a sub-collection within the documents of this collection.
    *
-   * Useful when querying subcollection documents across all/many parent documents. E.g. Querying landmarks from multiple cities.
-   * @param name
+   * Useful when querying sub-collection documents across all/many parent documents. E.g. Querying landmarks from multiple cities.
+   *
+   * @param name the name of the collection
+   * @returns a reference to all sub-collections matching the name provided.
    */
   public collection(name: string): CollectionGroupRef<T> {
     return CollectionGroupRef.fromCollectionRef(
@@ -52,16 +54,18 @@ export class CollectionRef<T extends DocumentStructure> {
 
   /**
    * Return a reference to a document in the collection.
-   * @param documentId id the document unique id (required)
+   *
+   * @param id the unique id of the document
    * @returns new collection document reference
    */
   public doc(id: string): DocumentRef<T> {
     return new DocumentRef<T>(this.documentClient, this, id);
   }
 
   /**
-   * Create a new collection query object
-   * @returns a new collection query object
+   * Create a new collection query object.
+   *
+   * @returns a new collection query object.
    */
   public query(): Query<T> {
     return new Query<T>(this.documentClient, this);
@@ -73,7 +77,7 @@ export class CollectionRef<T extends DocumentStructure> {
     col.setName(this.name);
 
     if (this.parent) {
-      col.setParent(this.parent["toWire"]());
+      col.setParent(this.parent['toWire']());
     }
 
     return col;

src/api/documents/v0/document-ref.test.ts

@@ -13,7 +13,10 @@
 // limitations under the License.
 import { Struct } from 'google-protobuf/google/protobuf/struct_pb';
 import { DocumentServiceClient as GrpcKeyDocumentsClient } from '@nitric/api/proto/document/v1/document_grpc_pb';
-import { DocumentGetResponse, Document } from '@nitric/api/proto/document/v1/document_pb';
+import {
+  DocumentGetResponse,
+  Document,
+} from '@nitric/api/proto/document/v1/document_pb';
 import { InvalidArgumentError, UnimplementedError } from '../../errors';
 import { Documents, documents } from './documents';
 
@@ -43,7 +46,9 @@ describe('Document Ref Tests', () => {
 
     test('Then DocumentRef.Get should reject', async () => {
       const doc = documentsClient.collection('test').doc('id');
-      await expect(doc.get()).rejects.toEqual(new UnimplementedError("UNIMPLEMENTED"));
+      await expect(doc.get()).rejects.toEqual(
+        new UnimplementedError('UNIMPLEMENTED')
+      );
     });
 
     test('The Grpc client for DocumentServiceClient.Put should have been called exactly once', () => {
@@ -120,7 +125,7 @@ describe('Document Ref Tests', () => {
         doc.set({
           name: 'test',
         })
-      ).rejects.toEqual(new UnimplementedError("UNIMPLEMENTED"));
+      ).rejects.toEqual(new UnimplementedError('UNIMPLEMENTED'));
     });
 
     test('The Grpc client for DocumentServiceClient.Get should have been called exactly once', () => {
@@ -153,7 +158,9 @@ describe('Document Ref Tests', () => {
 
     test('Then DocumentRef.Delete should reject', async () => {
       const doc = documentsClient.collection('test').doc('id');
-      await expect(doc.delete()).rejects.toEqual(new UnimplementedError("UNIMPLEMENTED"));
+      await expect(doc.delete()).rejects.toEqual(
+        new UnimplementedError('UNIMPLEMENTED')
+      );
     });
 
     test('The Grpc client for DocumentServiceClient.Delete should have been called exactly once', () => {

src/api/documents/v0/document-ref.ts

@@ -19,15 +19,15 @@ import {
   DocumentSetRequest,
   DocumentDeleteRequest,
 } from '@nitric/api/proto/document/v1/document_pb';
-import { DocumentServiceClient } from '@nitric/api/proto/document/v1/document_grpc_pb'; 
+import { DocumentServiceClient } from '@nitric/api/proto/document/v1/document_grpc_pb';
 import { fromGrpcError, InvalidArgumentError } from '../../errors';
 import { CollectionRef } from './collection-ref';
 import { MAX_COLLECTION_DEPTH } from './constants';
 
 export type DocumentStructure = Record<string, any>;
 
 /**
- * Document Ref
+ * Document Ref.
  *
  * Provides a Document Reference class.
  * Used to create references to collections.
@@ -49,6 +49,7 @@ export class DocumentRef<T extends DocumentStructure> {
 
   /**
    * Return the collection document reference value.
+   *
    * @returns the collection document reference value, or null if not found
    */
   public async get(): Promise<T> {
@@ -78,6 +79,7 @@ export class DocumentRef<T extends DocumentStructure> {
    * Set the document content for this document reference in the database. If the
    * document does not exist an new item will be created, otherwise an
    * existing document will be update with the new value.
+   *
    * @param value content the document content to store (required)
    */
   public async set(value: T): Promise<void> {
@@ -116,7 +118,7 @@ export class DocumentRef<T extends DocumentStructure> {
 
   private toWire(): Key {
     const key = new Key();
-    key.setCollection(this.parent["toWire"]());
+    key.setCollection(this.parent['toWire']());
     key.setId(this.id);
     return key;
   }
@@ -133,6 +135,7 @@ export class DocumentRef<T extends DocumentStructure> {
 
   /**
    * Gets a Collection instance that refers to the collection at the specified path.
+   *
    * @param name The name of the collection (required)
    * @returns The Collection instance
    */

src/api/documents/v0/documents.ts

@@ -35,6 +35,7 @@ export class Documents {
 
   /**
    * Gets a Collection instance that refers to the collection at the specified path.
+   *
    * @param name The name of the collection (required)
    * @returns The Collection instance
    */
@@ -47,7 +48,8 @@ export class Documents {
 let DOCUMENTS = undefined;
 
 /**
- * Documents
+ * Documents API client.
+ *
  * @returns a Documents API client.
  * @example
  * ```typescript

src/api/documents/v0/query.test.ts

@@ -14,13 +14,13 @@
 import { Struct } from 'google-protobuf/google/protobuf/struct_pb';
 import { PassThrough } from 'stream';
 import { DocumentServiceClient as GrpcKeyDocumentsClient } from '@nitric/api/proto/document/v1/document_grpc_pb';
-import { 
-  DocumentQueryResponse, 
+import {
+  DocumentQueryResponse,
   DocumentQueryStreamResponse,
   Document,
   ExpressionValue,
   Collection,
-  Key
+  Key,
 } from '@nitric/api/proto/document/v1/document_pb';
 import { documents, Documents } from './documents';
 import { DocumentSnapshot } from './document-snapshot';
@@ -126,7 +126,9 @@ describe('Query Tests', () => {
 
     test('Then DocumentRef.Query should reject', async () => {
       const query = documentsClient.collection('test').query();
-      await expect(query.fetch()).rejects.toEqual(new UnimplementedError("UNIMPLEMENTED"));
+      await expect(query.fetch()).rejects.toEqual(
+        new UnimplementedError('UNIMPLEMENTED')
+      );
     });
 
     test('The Grpc client for DocumentServiceClient.Query should have been called exactly once', () => {
@@ -196,8 +198,7 @@ describe('Query Tests', () => {
     test('Providing an invalid paging token should throw error', async () => {
       const q = documents().collection('test').query();
 
-      //@ts-ignore
-      q.pagingFrom('test');
+      q.pagingFrom('test' as any);
 
       await expect(q.fetch()).rejects.toStrictEqual(
         new InvalidArgumentError('Invalid paging token provided!')
@@ -211,14 +212,13 @@ describe('Query Tests', () => {
       message: 'UNIMPLEMENTED',
     };
     let documentsClient: Documents;
-    let mockStream = new PassThrough();
+    const mockStream = new PassThrough();
     let queryStreamMock;
 
     beforeAll(() => {
       queryStreamMock = jest
         .spyOn(GrpcKeyDocumentsClient.prototype, 'queryStream')
-        // @ts-ignore
-        .mockReturnValueOnce(mockStream);
+        .mockReturnValueOnce(mockStream as any);
       documentsClient = documents();
     });
 
@@ -239,7 +239,9 @@ describe('Query Tests', () => {
         });
       });
 
-      await expect(test).resolves.toEqual(new UnimplementedError("UNIMPLEMENTED"));
+      await expect(test).resolves.toEqual(
+        new UnimplementedError('UNIMPLEMENTED')
+      );
     });
 
     test('The Grpc client for DocumentServiceClient.QueryStream should have been called exactly once', () => {
@@ -249,15 +251,14 @@ describe('Query Tests', () => {
 
   describe('Given DocumentServiceClient.QueryStream succeeds', () => {
     let documentsClient: Documents;
-    let mockStream = new PassThrough();
+    const mockStream = new PassThrough();
     let queryStreamMock;
     let mockKey;
 
     beforeAll(() => {
       queryStreamMock = jest
         .spyOn(GrpcKeyDocumentsClient.prototype, 'queryStream')
-        // @ts-ignore
-        .mockReturnValueOnce(mockStream);
+        .mockReturnValueOnce(mockStream as any);
       documentsClient = documents();
     });