Bytes

Author: DellaBitta

common/api-review/firestore-lite.api.md

@@ -68,9 +68,11 @@ export function average(field: string | FieldPath): AggregateField<number | null
 // @public
 export class Bytes {
     static fromBase64String(base64: string): Bytes;
+    static fromJSON(json: object): Bytes;
     static fromUint8Array(array: Uint8Array): Bytes;
     isEqual(other: Bytes): boolean;
     toBase64(): string;
+    toJSON(): object;
     toString(): string;
     toUint8Array(): Uint8Array;
 }

common/api-review/firestore.api.md

@@ -68,9 +68,11 @@ export function average(field: string | FieldPath): AggregateField<number | null
 // @public
 export class Bytes {
     static fromBase64String(base64: string): Bytes;
+    static fromJSON(json: object): Bytes;
     static fromUint8Array(array: Uint8Array): Bytes;
     isEqual(other: Bytes): boolean;
     toBase64(): string;
+    toJSON(): object;
     toString(): string;
     toUint8Array(): Uint8Array;
 }

packages/firestore/src/lite-api/bytes.ts

@@ -91,4 +91,38 @@ export class Bytes {
   isEqual(other: Bytes): boolean {
     return this._byteString.isEqual(other._byteString);
   }
+
+  /** Returns a JSON-serializable representation of this `Bytes` instance. */
+  toJSON(): object {
+    return {
+      type: 'firestore/bytes/1.0',
+      data: this.toBase64()
+    };
+  }
+  /** Builds a `Bytes` instance from a JSON serialized version of `Bytes`. */
+  static fromJSON(json: object): Bytes {
+    const requiredFields = ['type', 'data'];
+    let error: string | undefined = undefined;
+    let data: string = '';
+    for (const key of requiredFields) {
+      if (!(key in json)) {
+        error = `json missing required field: ${key}`;
+      }
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const value = (json as any)[key];
+      if (typeof value !== 'string') {
+        error = `json field '${key}' must be a string.`;
+        break;
+      } else if (key === 'type' && value !== 'firestore/bytes/1.0') {
+        error = "Expected 'type' field to equal 'firestore/bytes/1.0'";
+        break;
+      } else if (key === 'data') {
+        data = value;
+      }
+    }
+    if (error) {
+      throw new FirestoreError(Code.INVALID_ARGUMENT, error);
+    }
+    return Bytes.fromBase64String(data);
+  }
 }

packages/firestore/test/unit/api/bytes.test.ts

@@ -55,4 +55,31 @@ describe('Bytes', () => {
     expectEqual(blob(1, 2, 3), blob(1, 2, 3));
     expectNotEqual(blob(1, 2, 3), blob(4, 5, 6));
   });
+  
+  it('fromJSON reconstructs the value from toJSON', () => {
+    const bytes  = Bytes.fromUint8Array(new Uint8Array([0, 1, 2, 3, 4, 5]));
+    expect(() => { Bytes.fromJSON(bytes.toJSON())} ).to.not.throw;
+    expect(Bytes.fromJSON(bytes.toJSON()).isEqual(bytes)).to.be.true;
+  });
+
+  it('toJSON -> fromJSON bytes comparison', () => {
+    Object.keys(base64Mappings).forEach(base64Str => {
+      const bytesToSerialize = Bytes.fromBase64String(base64Str);
+      const deserializedBytes = Bytes.fromJSON(bytesToSerialize.toJSON());
+      expectEqual(bytesToSerialize, deserializedBytes);
+      const expectedUint8Array = base64Mappings[base64Str];
+      const actualUint8Array = deserializedBytes.toUint8Array();
+      expect(actualUint8Array.length).to.equal(expectedUint8Array.length);
+      for (let i = 0; i < actualUint8Array.length; i++) {
+        expect(actualUint8Array[i]).to.equal(expectedUint8Array[i]);
+      }
+    });
+  })
+
+  it('fromJSON misisng fields throws', () => {
+    expect(() => {Bytes.fromJSON({type: 'firestore/bytes/1.0' /* missing data */})}).to.throw;
+    expect(() => {Bytes.fromJSON({data: 'AA==' /* missing type */})}).to.throw;
+    expect(() => {Bytes.fromJSON({type: 1, data: 'AA==' })}).to.throw;
+    expect(() => {Bytes.fromJSON({type: 'firestore/bytes/1.0', data: 1 })}).to.throw;
+  });
 });