internetarchive · latonv · Nov 21, 2022 · Nov 2, 2022 · Nov 4, 2022 · Nov 4, 2022
diff --git a/demo/app-root.ts b/demo/app-root.ts
diff --git a/demo/index.html b/demo/index.html
@@ -3,9 +3,10 @@
 <head>
   <meta charset="utf-8">
   <style>
-    body {
+    html {
       background: #fff;
       font-family: sans-serif;
+      font-size: 10px;
     }
   </style>
 </head>

diff --git a/index.ts b/index.ts
@@ -46,5 +46,9 @@ export {
   SortDirection,
   AggregateSearchParams,
   AggregateSearchParam,
+  FilterMap,
+  FieldFilter,
+  FilterConstraint,
 } from './src/search-params';
+export { FilterMapBuilder } from './src/filter-map-builder';
 export { SearchServiceError } from './src/search-service-error';
diff --git a/src/filter-map-builder.ts b/src/filter-map-builder.ts
@@ -0,0 +1,134 @@
+import { FilterConstraint, FilterMap } from './search-params';
+
+/**
+ * A utility class for building filter maps
+ */
+export class FilterMapBuilder {
+  private filterMap: FilterMap = {};
+
+  /**
+   * Adds a filter to the FilterMap under construction.
+   * If existing constraint(s) already exist for this field and value, then the old and new constraints
+   * will be joined into a single array.
+   * @param field The field to filter on (e.g., 'subject', 'year', ...)
+   * @param value The value of the field to filter on (e.g., 'Cicero', '1920', ...)
+   * @param constraint The constraint to apply to the `field`, with respect to the given `value`.
+   * Allowed values are the enum members of `FilterConstraint`.
+   */
+  addFilter(field: string, value: string, constraint: FilterConstraint): this {
+    if (!this.filterMap[field]) {
+      this.filterMap[field] = {};
+    }
+
+    // If there are already constraints for this value, concat them into an array
+    if (this.filterMap[field][value]) {
+      const mergedConstraints = ([] as FilterConstraint[]).concat(
+        this.filterMap[field][value],
+        constraint
+      );
+
+      // Ensure there are no duplicate constraints in the array
+      this.filterMap[field][value] = Array.from(new Set(mergedConstraints));
+    } else {
+      // Otherwise just use the provided value
+      this.filterMap[field][value] = constraint;
+    }
+
+    return this;
+  }
+
+  /**
+   * Removes a single filter currently associated with the given field, value, and constraint type.
+   * @param field The field to remove a filter for
+   * @param value The value to remove the filter for
+   * @param constraint The constraint type to remove for this field and value
+   */
+  removeSingleFilter(
+    field: string,
+    value: string,
+    constraint: FilterConstraint
+  ): this {
+    if (!this.filterMap[field]?.[value]) return this;
+
+    const constraints = ([] as FilterConstraint[]).concat(
+      this.filterMap[field][value]
+    );
+    const constraintIndex = constraints.indexOf(constraint);
+    if (constraintIndex >= 0) {
+      constraints.splice(constraintIndex, 1);
+    }
+
+    // 2 or more constraints -> leave as array
+    // 1 constraint -> pull out single constraint
+    // 0 constraints -> delete the value entirely
+    this.filterMap[field][value] =
+      constraints.length === 1 ? constraints[0] : constraints;
+    if (constraints.length === 0) {
+      delete this.filterMap[field][value];
+    }
+
+    // If there are no remaining filters for this field, delete the whole field object.
+    if (Object.keys(this.filterMap[field]).length === 0) {
+      delete this.filterMap[field];
+    }
+
+    return this;
+  }
+
+  /**
+   * Removes any filters currently associated with the given field and value.
+   * @param field The field to remove a filter for
+   * @param value The value to remove the filter for
+   */
+  removeFilters(field: string, value: string): this {
+    if (!this.filterMap[field]) return this;
+
+    delete this.filterMap[field][value];
+
+    // If there are no remaining filters for this field, delete the whole field object.
+    if (Object.keys(this.filterMap[field]).length === 0) {
+      delete this.filterMap[field];
+    }
+
+    return this;
+  }
+
+  /**
+   * Initializes the filter map under construction to have filters exactly equal to the given one.
+   * This will overwrite *all* existing filters already added to the builder.
+   * @param map The FilterMap to set this builder's state to.
+   */
+  setFilterMap(map: FilterMap): this {
+    this.filterMap = { ...map };
+    return this;
+  }
+
+  /**
+   * Adds all filters from an existing filter map to the one being built.
+   * Filters from the provided map may overwrite existing filters already added to the builder.
+   * @param map The FilterMap to merge into the one being built.
+   */
+  mergeFilterMap(map: FilterMap): this {
+    for (const [field, filters] of Object.entries(map)) {
+      for (const [value, constraint] of Object.entries(filters)) {
+        // There may be either a single constraint or an array of them
+        if (Array.isArray(constraint)) {
+          for (const subConstraint of constraint) {
+            this.addFilter(field, value, subConstraint);
+          }
+        } else {
+          this.addFilter(field, value, constraint);
+        }
+      }
+    }
+    return this;
+  }
+
+  /**
+   * Produces a `FilterMap` including all the filters that have been applied to
+   * this builder.
+   */
+  build(): FilterMap {
+    return this.filterMap;
+  }
+}
diff --git a/src/search-param-url-generator.ts b/src/search-param-url-generator.ts
@@ -1,5 +1,6 @@
 import {
   AggregateSearchParams,
+  FilterMap,
   SearchParams,
   SortParam,
 } from './search-params';
@@ -54,6 +55,11 @@ export class SearchParamURLGenerator {
     return `${sortParams.field}:${sortParams.direction}`;
   }
 
+  static filterParamsAsString(filters: FilterMap): string {
+    // FilterMap already has the correct shape, we just need to stringify it
+    return JSON.stringify(filters);
+  }
+
   static generateURLSearchParams(searchParams: SearchParams): URLSearchParams {
     const params: URLSearchParams = new URLSearchParams();
     params.append('user_query', searchParams.query);
@@ -74,11 +80,19 @@ export class SearchParamURLGenerator {
       params.append('page', String(searchParams.page));
     }
 
-    if (searchParams.fields) {
+    if (searchParams.fields && searchParams.fields.length > 0) {
       params.append('fields', searchParams.fields.join(','));
     }
 
-    if (searchParams.sort) {
+    if (searchParams.filters && Object.keys(searchParams.filters).length > 0) {
+      const filterMapString = this.filterParamsAsString(searchParams.filters);
+      if (filterMapString && filterMapString !== '{}') {
+        // Don't send an empty map
+        params.append('filter_map', filterMapString);
+      }
+    }
+
+    if (searchParams.sort && searchParams.sort.length > 0) {
       const sortStrings = searchParams.sort.map(sort =>
         this.sortParamsAsString(sort)
       );

diff --git a/src/search-params.ts b/src/search-params.ts
@@ -48,6 +48,108 @@ export interface SortParam {
   direction: SortDirection;
 }
 
+/**
+ * Enumerates the possible contraints that may be imposed on search results
+ * by filter params.
+ */
+export enum FilterConstraint {
+  /**
+   * Specifies that all results must include _at least one of_ the values constrained
+   * with INCLUDE for this field.
+   *
+   * For instance, `{ subject: { baseball: INCLUDE, basketball: INCLUDE } }` specifies
+   * that only results containing _either_ `baseball` _or_ `basketball` as a subject
+   * should be returned.
+   */
+  INCLUDE = 'inc',
+
+  /**
+   * Specifies that all results must _not_ include the given value for this field.
+   *
+   * For instance, `{ subject: { baseball: EXCLUDE, basketball: EXCLUDE } }` specifies
+   * that only results containing _neither_ `baseball` _nor_ `basketball` as a subject
+   * should be returned.
+   */
+  EXCLUDE = 'exc',
+
+  /**
+   * Imposes a strict lower bound on numeric values for the current field.
+   * All returned hits must have a value for this field that is greater than the one
+   * specified by this filter.
+   *
+   * This only makes sense for numeric fields like `year`.
+   * Note that `GREATER_THAN` is not supported by the FTS engine, for which it is
+   * coerced to `GREATER_OR_EQUAL`.
+   */
+  GREATER_THAN = 'gt',
+
+  /**
+   * Imposes a non-strict lower bound on numeric values for the current field.
+   * All returned hits must have a value for this field that is greater than or equal
+   * to the one specified by this filter.
+   *
+   * This only makes sense for numeric fields like `year`.
+   */
+  GREATER_OR_EQUAL = 'gte',
+
+  /**
+   * Imposes a strict upper bound on numeric values for the current field.
+   * All returned hits must have a value for this field that is less than the one
+   * specified by this filter.
+   *
+   * This only makes sense for numeric fields like `year`.
+   * Note that `LESS_THAN` is not supported by the FTS engine, for which it is
+   * coerced to `LESS_OR_EQUAL`.
+   */
+  LESS_THAN = 'lt',
+
+  /**
+   * Imposes a non-strict upper bound on numeric values for the current field.
+   * All returned hits must have a value for this field that is less than or equal
+   * to the one specified by this filter.
+   *
+   * This only makes sense for numeric fields like `year`.
+   */
+  LESS_OR_EQUAL = 'lte',
+}
+
+/**
+ * A filter mapping a field value to the type of constraint(s) that it should impose on results.
+ * Multiple constraints for the same value may be provided as an array.
+ *
+ * Some examples (where the property values are members of `FilterConstraint`):
+ * - `{ 'puppies': INCLUDE }`
+ * - `{ '1950': GREATER_OR_EQUAL, '1970': LESS_OR_EQUAL }`
+ * - `{ '1950': [ GREATER_OR_EQUAL, EXCLUDE ] }`
+ */
+export type FieldFilter = Record<string, FilterConstraint | FilterConstraint[]>;
+
+/**
+ * A map of fields (e.g., 'year', 'subject', ...) to the filters that should be
+ * applied to them when retrieving search results.
+ *
+ * These filters may represent selected/hidden facets, value ranges (e.g., date picker),
+ * or other types of restrictions on the result set.
+ *
+ * An example of a valid FilterMap:
+ * ```
+ * {
+ *   'subject': {
+ *     'dogs': INCLUDE,
+ *     'puppies': EXCLUDE,
+ *   },
+ *   'year': {
+ *     '1990': GREATER_OR_EQUAL,
+ *     '2010': LESS_OR_EQUAL,
+ *     '2003': EXCLUDE,
+ *     '2004': EXCLUDE,
+ *   },
+ *   // ...
+ * }
+ * ```
+ */
+export type FilterMap = Record<string, FieldFilter>;
+
 /**
  * SearchParams provides an encapsulation to all of the search parameters
  * available for searching.
@@ -105,6 +207,26 @@ export interface SearchParams {
    */
   fields?: string[];
 
+  /**
+   * A map from field names to filters that can be used to shape the result set.
+   * The keys identify what field to filter on (e.g., `'year'`, `'subject'`, etc.),
+   * and the values identify what filters to apply for that field.
+   *
+   * The constraints allowed are the members of `FilterContraint`:
+   * - `INCLUDE` (at least one of these values must be present)
+   * - `EXCLUDE` (none of these values may be present)
+   * - `GREATER_THAN` (result values must be strictly greater than the one specified)
+   * - `GREATER_OR_EQUAL` (result values must be greater than or equal to than the one specified)
+   * - `LESS_THAN` (result values must be strictly less than the one specified)
+   * - `LESS_OR_EQUAL` (result values must be less than or equal to the one specified)
+   *
+   * So filters like `{ creator: { 'Cicero': INCLUDE } }` will produce
+   * search results that all include `Cicero` as a creator, while filters like
+   * `{ year: { '2000': GREATER_THAN, '2005': LESS_THAN } }` will produce search results whose
+   * `year` field is between 2000 and 2005 (exclusive).
+   */
+  filters?: FilterMap;
+
   /**
    * An object specifying which aggregation types should be returned with
    * a search query.