feat(filter): implement ensureFields utility

packages/filter/package.json

@@ -28,11 +28,13 @@
     "!*/__tests__"
   ],
   "dependencies": {
+    "lodash": "^4.17.20",
     "tslib": "^2.0.2"
   },
   "devDependencies": {
     "@loopback/build": "^6.2.4",
     "@loopback/testlab": "^3.2.6",
+    "@types/lodash": "^4.14.161",
     "@types/node": "^10.17.35",
     "typescript": "~4.0.3"
   },

packages/filter/src/__tests__/acceptance/ensure-fields.acceptance.ts

@@ -0,0 +1,57 @@
+// Copyright IBM Corp. 2020. All Rights Reserved.
+// Node module: @loopback/filter
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+import {expect} from '@loopback/testlab';
+import {ensureFields, Filter} from '../..';
+
+describe('ensureFields', () => {
+  it('does not modify a filter when it does not specify fields', () => {
+    const filter = {} as Filter;
+    const {filter: newFilter, fieldsAdded} = ensureFields(['a', 'b'], filter);
+
+    expect(newFilter).to.eql({});
+    expect(fieldsAdded).to.eql([]);
+  });
+
+  it('does not modify a filter when it does not exclude target fields', () => {
+    const filter = {fields: {a: false, b: false}} as Filter;
+    const {filter: newFilter, fieldsAdded} = ensureFields(['c'], filter);
+
+    expect(newFilter).to.eql({fields: {a: false, b: false}});
+    expect(fieldsAdded).to.eql([]);
+  });
+
+  it('does not modify a filter when target fields are not specified', () => {
+    const filter = {fields: {a: false, b: false}} as Filter;
+    const {filter: newFilter, fieldsAdded} = ensureFields([], filter);
+
+    expect(newFilter).to.eql({fields: {a: false, b: false}});
+    expect(fieldsAdded).to.eql([]);
+  });
+
+  it('adds omitted fields', () => {
+    const filter = {fields: {a: true}} as Filter;
+    const {filter: newFilter, fieldsAdded} = ensureFields(['b'], filter);
+
+    expect(newFilter).to.eql({fields: {a: true, b: true}});
+    expect(fieldsAdded).to.eql(['b']);
+  });
+
+  it('adds explicitly disabled fields', () => {
+    const filter = {fields: {a: true, b: false}} as Filter;
+    const {filter: newFilter, fieldsAdded} = ensureFields(['b'], filter);
+
+    expect(newFilter).to.eql({fields: {a: true, b: true}});
+    expect(fieldsAdded).to.eql(['b']);
+  });
+
+  it('removes fields clause when it only excludes fields', () => {
+    const filter = {fields: {a: false, b: false}} as Filter;
+    const {filter: newFilter, fieldsAdded} = ensureFields(['b'], filter);
+
+    expect(newFilter).to.eql({});
+    expect(fieldsAdded).to.eql(['a', 'b']);
+  });
+});

packages/filter/src/ensure-fields.ts

@@ -0,0 +1,75 @@
+// Copyright IBM Corp. 2020. All Rights Reserved.
+// Node module: @loopback/filter
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+import _ from 'lodash';
+import {Filter, FilterBuilder} from './query';
+import {AnyObject} from './types';
+
+/**
+ * Ensures that queries which apply the returned filter would always include
+ * the target fields. To undo this effect later, fields that were disabled
+ * in the original filter will be added to the pruning mask.
+ *
+ * @param targetFields - An array of fields to include
+ * @param filter - A target filter
+ * @returns A tuple containing amended filter and pruning mask
+ */
+export function ensureFields<T extends object = AnyObject>(
+  targetFields: (keyof T)[],
+  filter: Filter<T>,
+) {
+  const builder = new FilterBuilder(filter);
+  const fields = builder.build().fields;
+  if (!fields || matchesFields(targetFields, filter)) {
+    return {
+      filter: builder.build(),
+      fieldsAdded: [] as (keyof T)[],
+    };
+  }
+  const isDisablingOnly = _.size(fields) > 0 && !_.some(fields, Boolean);
+  const fieldsAdded = (isDisablingOnly ? _.keys(fields) : []) as (keyof T)[];
+  targetFields.forEach(f => {
+    if (!fields[f]) {
+      fieldsAdded.push(f);
+      builder.fields(f);
+    }
+  });
+
+  const newFilter = builder.build();
+  // if the filter only hides the fields, unset the entire fields clause
+  if (isDisablingOnly) {
+    delete filter.fields;
+  }
+  return {
+    filter: newFilter,
+    fieldsAdded: _.uniq(fieldsAdded) as (keyof T)[],
+  } as const;
+}
+
+/**
+ * Checks whether fields array passed as an argument is a
+ * subset of fields picked by a target filter.
+ *
+ * @param fields - An array of fields to search in a filter
+ * @param filter - A target filter
+ */
+export function matchesFields<T extends object = AnyObject>(
+  fields: (keyof T)[],
+  filter?: Filter<T>,
+) {
+  const normalized = new FilterBuilder(filter).build();
+  const targetFields = normalized.fields;
+  if (!targetFields) {
+    return true;
+  }
+  const isDisablingOnly =
+    _.size(targetFields) > 0 && !_.some(targetFields, Boolean);
+  for (const f of fields) {
+    if (!targetFields[f] && (f in targetFields || !isDisablingOnly)) {
+      return false;
+    }
+  }
+  return true;
+}

packages/filter/src/index.ts

@@ -18,3 +18,4 @@
  */
 
 export * from './query';
+export * from './ensure-fields';

packages/filter/src/query.ts

@@ -506,7 +506,7 @@ export class WhereBuilder<MT extends object = AnyObject> {
 }
 
 /**
- * A builder for Filter. It provides fleunt APIs to add clauses such as
+ * A builder for Filter. It provides fluent APIs to add clauses such as
  * `fields`, `order`, `where`, `limit`, `offset`, and `include`.
  *
  * @example