feat: Deprecate LiveQuery fields option in favor of keys for semantic consistency (#8388)

Author: dblythy

DEPRECATIONS.md

@@ -12,6 +12,7 @@ The following is a list of deprecations, according to the [Deprecation Policy](h
 | DEPPS6 | Auth providers disabled by default | [#7953](https://github.com/parse-community/parse-server/pull/7953)   | 5.3.0 (2022)                    | 7.0.0 (2024)                    | deprecated            | -     |
 | DEPPS7 | Remove file trigger syntax `Parse.Cloud.beforeSaveFile((request) => {})` | [#7966](https://github.com/parse-community/parse-server/pull/7966)   | 5.3.0 (2022)                    | 7.0.0 (2024)                    | deprecated            | -     |
 | DEPPS8 | Login with expired 3rd party authentication token defaults to `false` | [#7079](https://github.com/parse-community/parse-server/pull/7079)   | 5.3.0 (2022)                    | 7.0.0 (2024)                    | deprecated            | -     |
+| DEPPS9 | Rename LiveQuery `fields` option to `keys` | [#8389](https://github.com/parse-community/parse-server/issues/8389)   | 6.0.0 (2023)                    | 7.0.0 (2024)                    | deprecated            | -     |
 
 [i_deprecation]: ## "The version and date of the deprecation."
 [i_removal]: ## "The version and date of the planned removal."

spec/ParseLiveQueryServer.spec.js

@@ -294,7 +294,7 @@ describe('ParseLiveQueryServer', function () {
       where: {
         key: 'value',
       },
-      fields: ['test'],
+      keys: ['test'],
     };
     const requestId = 2;
     const request = {
@@ -331,7 +331,7 @@ describe('ParseLiveQueryServer', function () {
       where: {
         key: 'value',
       },
-      fields: ['test'],
+      keys: ['test'],
     };
     const requestId = 2;
     const request = {
@@ -378,7 +378,7 @@ describe('ParseLiveQueryServer', function () {
       where: {
         key: 'value',
       },
-      fields: ['test'],
+      keys: ['test'],
     };
     await addMockSubscription(parseLiveQueryServer, clientId, requestId, parseWebSocket, query);
     // Add subscription for mock client 2
@@ -390,7 +390,7 @@ describe('ParseLiveQueryServer', function () {
       where: {
         key: 'value',
       },
-      fields: ['testAgain'],
+      keys: ['testAgain'],
     };
     const requestIdAgain = 1;
     await addMockSubscription(
@@ -1060,7 +1060,7 @@ describe('ParseLiveQueryServer', function () {
       where: {
         key: 'value',
       },
-      fields: ['test'],
+      keys: ['test'],
     };
     await addMockSubscription(parseLiveQueryServer, clientId, requestId, parseWebSocket, query);
     // Mock _matchesSubscription to return matching
@@ -1087,6 +1087,62 @@ describe('ParseLiveQueryServer', function () {
     done();
   });
 
+  it('can deprecate fields', async () => {
+    const Deprecator = require('../lib/Deprecator/Deprecator');
+    const spy = spyOn(Deprecator, 'logRuntimeDeprecation').and.callFake(() => {});
+    jasmine.restoreLibrary('../lib/LiveQuery/Client', 'Client');
+    const Client = require('../lib/LiveQuery/Client').Client;
+    const parseLiveQueryServer = new ParseLiveQueryServer({});
+    // Make mock request message
+    const message = generateMockMessage();
+
+    const clientId = 1;
+    const parseWebSocket = {
+      clientId,
+      send: jasmine.createSpy('send'),
+    };
+    const client = new Client(clientId, parseWebSocket);
+    spyOn(client, 'pushCreate').and.callThrough();
+    parseLiveQueryServer.clients.set(clientId, client);
+
+    // Add mock subscription
+    const requestId = 2;
+    const query = {
+      className: testClassName,
+      where: {
+        key: 'value',
+      },
+      fields: ['test'],
+    };
+    await addMockSubscription(parseLiveQueryServer, clientId, requestId, parseWebSocket, query);
+    // Mock _matchesSubscription to return matching
+    parseLiveQueryServer._matchesSubscription = function (parseObject) {
+      if (!parseObject) {
+        return false;
+      }
+      return true;
+    };
+    parseLiveQueryServer._matchesACL = function () {
+      return Promise.resolve(true);
+    };
+
+    parseLiveQueryServer._onAfterSave(message);
+
+    // Make sure we send create command to client
+    await timeout();
+
+    expect(client.pushCreate).toHaveBeenCalled();
+    const args = parseWebSocket.send.calls.mostRecent().args;
+    const toSend = JSON.parse(args[0]);
+    expect(toSend.object).toBeDefined();
+    expect(toSend.original).toBeUndefined();
+    expect(spy).toHaveBeenCalledWith({
+      usage: 'Subscribing using fields parameter',
+      solution:
+        `Subscribe using "keys" instead.`,
+    });
+  });
+
   it('can handle create command with watch', async () => {
     jasmine.restoreLibrary('../lib/LiveQuery/Client', 'Client');
     const Client = require('../lib/LiveQuery/Client').Client;
@@ -1865,7 +1921,7 @@ describe('ParseLiveQueryServer', function () {
         where: {
           key: 'value',
         },
-        fields: ['test'],
+        keys: ['test'],
       };
     }
     const request = {

src/LiveQuery/Client.js

@@ -98,13 +98,13 @@ class Client {
         response['requestId'] = subscriptionId;
       }
       if (typeof parseObjectJSON !== 'undefined') {
-        let fields;
+        let keys;
         if (this.subscriptionInfos.has(subscriptionId)) {
-          fields = this.subscriptionInfos.get(subscriptionId).fields;
+          keys = this.subscriptionInfos.get(subscriptionId).keys;
         }
-        response['object'] = this._toJSONWithFields(parseObjectJSON, fields);
+        response['object'] = this._toJSONWithFields(parseObjectJSON, keys);
         if (parseOriginalObjectJSON) {
-          response['original'] = this._toJSONWithFields(parseOriginalObjectJSON, fields);
+          response['original'] = this._toJSONWithFields(parseOriginalObjectJSON, keys);
         }
       }
       Client.pushResponse(this.parseWebSocket, JSON.stringify(response));

src/LiveQuery/ParseLiveQueryServer.js

@@ -23,6 +23,7 @@ import LRU from 'lru-cache';
 import UserRouter from '../Routers/UsersRouter';
 import DatabaseController from '../Controllers/DatabaseController';
 import { isDeepStrictEqual } from 'util';
+import Deprecator from '../Deprecator/Deprecator';
 
 class ParseLiveQueryServer {
   clients: Map;
@@ -850,9 +851,6 @@ class ParseLiveQueryServer {
         await runTrigger(trigger, `beforeSubscribe.${className}`, request, auth);
 
         const query = request.query.toJSON();
-        if (query.keys) {
-          query.fields = query.keys.split(',');
-        }
         request.query = query;
       }
 
@@ -901,8 +899,17 @@ class ParseLiveQueryServer {
         subscription: subscription,
       };
       // Add selected fields, sessionToken and installationId for this subscription if necessary
+      if (request.query.keys) {
+        subscriptionInfo.keys = Array.isArray(request.query.keys)
+          ? request.query.keys
+          : request.query.keys.split(',');
+      }
       if (request.query.fields) {
-        subscriptionInfo.fields = request.query.fields;
+        subscriptionInfo.keys = request.query.fields;
+        Deprecator.logRuntimeDeprecation({
+          usage: `Subscribing using fields parameter`,
+          solution: `Subscribe using "keys" instead.`,
+        });
       }
       if (request.query.watch) {
         subscriptionInfo.watch = request.query.watch;

src/LiveQuery/RequestSchema.js

@@ -70,6 +70,22 @@ const subscribe = {
           minItems: 1,
           uniqueItems: true,
         },
+        keys: {
+          type: 'array',
+          items: {
+            type: 'string',
+          },
+          minItems: 1,
+          uniqueItems: true,
+        },
+        watch: {
+          type: 'array',
+          items: {
+            type: 'string',
+          },
+          minItems: 1,
+          uniqueItems: true,
+        },
       },
       required: ['where', 'className'],
       additionalProperties: false,
@@ -108,6 +124,22 @@ const update = {
           minItems: 1,
           uniqueItems: true,
         },
+        keys: {
+          type: 'array',
+          items: {
+            type: 'string',
+          },
+          minItems: 1,
+          uniqueItems: true,
+        },
+        watch: {
+          type: 'array',
+          items: {
+            type: 'string',
+          },
+          minItems: 1,
+          uniqueItems: true,
+        },
       },
       required: ['where', 'className'],
       additionalProperties: false,