aspernaturalias 1.0.0

package/packages/arcgis-rest-portal/src/util/SearchQueryBuilder.ts

@@ -0,0 +1,374 @@
+import { IParamBuilder, warn } from "@esri/arcgis-rest-request";
+/**
+ * `SearchQueryBuilder` can be used to construct the `q` param for [`searchItems`](/arcgis-rest-js/api/portal/searchItems#searchItems-search) or [`searchGroups`](/arcgis-rest-js/api/portal/searchGroups#searchGroups-search). By chaining methods, it helps build complex search queries.
+ *
+ * ```js
+ * const query = new SearchQueryBuilder()
+ *  .match("Patrick")
+ *  .in("owner")
+ *  .and()
+ *  .startGroup()
+ *    .match("Web Mapping Application")
+ *    .in("type")
+ *    .or()
+ *    .match("Mobile Application")
+ *    .in("type")
+ *    .or()
+ *    .match("Application")
+ *    .in("type")
+ *  .endGroup()
+ *  .and()
+ *  .match("Demo App");
+ *
+ * searchItems(query).then((results) => {
+ *   console.log(request);
+ * });
+ * ```
+ *
+ * Will search for items matching
+ * ```
+ * "owner: Patrick AND (type:"Web Mapping Application" OR type:"Mobile Application" OR type:Application) AND Demo App"
+ * ```
+ */
+export class SearchQueryBuilder implements IParamBuilder {
+  private termStack: any[] = [];
+  private rangeStack: any[] = [];
+  private q: string;
+  private openGroups = 0;
+  private currentModifer: string;
+
+  /**
+   * @param q An existing query string to start building from.
+   */
+  constructor(q: string = "") {
+    this.q = q;
+  }
+
+  /**
+   * Defines strings to search for.
+   *
+   * ```js
+   * const query = new SearchQueryBuilder()
+   *   .match("My Layer")
+   * ```
+   *
+   * @param terms strings to search for.
+   */
+  public match(this: SearchQueryBuilder, ...terms: string[]) {
+    this.termStack = this.termStack.concat(terms);
+    return this;
+  }
+
+  /**
+   * Defines fields to search in. You can pass `"*"` or call this method without arguments to search a default set of fields
+   *
+   * ```js
+   * const query = new SearchQueryBuilder()
+   *   .match("My Layer")
+   *   .in("title")
+   * ```
+   *
+   * @param field The field to search for the previous match in.
+   */
+  public in(this: SearchQueryBuilder, field?: string) {
+    const fn = `\`in(${field ? `"${field}"` : ""})\``;
+
+    if (!this.hasRange && !this.hasTerms) {
+      warn(
+        // prettier-ignore
+        `${fn} was called with no call to \`match(...)\` or \`from(...)\`/\`to(...)\`. Your query was not modified.`
+      );
+      return this;
+    }
+
+    if (field && field !== "*") {
+      this.q += `${field}:`;
+    }
+
+    return this.commit();
+  }
+
+  /**
+   * Starts a new search group.
+   *
+   * ```js
+   * const query = new SearchQueryBuilder()
+   *   .startGroup()
+   *     .match("Lakes")
+   *     .in("title")
+   *   .endGroup()
+   *   .or()
+   *   .startGroup()
+   *     .match("Rivers")
+   *     .in("title")
+   *   .endGroup()
+   * ```
+   */
+  public startGroup(this: SearchQueryBuilder) {
+    this.commit();
+    if (this.openGroups > 0) {
+      this.q += " ";
+    }
+    this.openGroups++;
+    this.q += "(";
+    return this;
+  }
+
+  /**
+   * Ends a search group.
+   *
+   * ```js
+   * const query = new SearchQueryBuilder()
+   *   .startGroup()
+   *     .match("Lakes")
+   *     .in("title")
+   *   .endGroup()
+   *   .or()
+   *   .startGroup()
+   *     .match("Rivers")
+   *     .in("title")
+   *   .endGroup()
+   * ```
+   */
+  public endGroup(this: SearchQueryBuilder) {
+    if (this.openGroups <= 0) {
+      warn(
+        `\`endGroup(...)\` was called without calling \`startGroup(...)\` first. Your query was not modified.`
+      );
+      return this;
+    }
+    this.commit();
+    this.openGroups--;
+    this.q += ")";
+    return this;
+  }
+
+  /**
+   * Joins two sets of queries with an `AND` clause.
+   *
+   * ```js
+   * const query = new SearchQueryBuilder()
+   *   .match("Lakes")
+   *   .in("title")
+   *   .and()
+   *   .match("Rivers")
+   *   .in("title")
+   * ```
+   */
+  public and(this: SearchQueryBuilder) {
+    return this.addModifier("and");
+  }
+
+  /**
+   * Joins two sets of queries with an `OR` clause.
+   *
+   * ```js
+   * const query = new SearchQueryBuilder()
+   *   .match("Lakes")
+   *   .in("title")
+   *   .or()
+   *   .match("Rivers")
+   *   .in("title")
+   * ```
+   */
+  public or(this: SearchQueryBuilder) {
+    return this.addModifier("or");
+  }
+
+  /**
+   * Joins two sets of queries with a `NOT` clause. Another option for filtering results is the [prohibit operator '-'](https://developers.arcgis.com/rest/users-groups-and-items/search-reference.htm#ESRI_SECTION1_5C6C35DB9E4A4F4492C5B937BDA2BF67).
+   *
+   * ```js
+   * // omit results with "Rivers" in their title
+   * const query = new SearchQueryBuilder()
+   *   .not()
+   *   .match("Rivers")
+   *   .in("title")
+   *
+   * // equivalent
+   * const query = new SearchQueryBuilder()
+   *   .match("Rivers")
+   *   .in("-title")
+   * ```
+   */
+  public not(this: SearchQueryBuilder) {
+    return this.addModifier("not");
+  }
+
+  /**
+   * Begins a new range query.
+   *
+   * ```js
+   * const query = new SearchQueryBuilder()
+   *   .from(yesterdaysDate)
+   *   .to(todaysDate)
+   *   .in("created")
+   * ```
+   */
+  public from(this: SearchQueryBuilder, term: number | string | Date) {
+    if (this.hasTerms) {
+      warn(
+        // prettier-ignore
+        `\`from(...)\` is not allowed after \`match(...)\` try using \`.from(...).to(...).in(...)\`. Your query was not modified.`
+      );
+      return this;
+    }
+    this.rangeStack[0] = term;
+    return this;
+  }
+
+  /**
+   * Ends a range query.
+   *
+   * ```js
+   * const query = new SearchQueryBuilder()
+   *   .from(yesterdaysDate)
+   *   .to(todaysDate)
+   *   .in("created")
+   * ```
+   */
+  public to(this: SearchQueryBuilder, term: any) {
+    if (this.hasTerms) {
+      warn(
+        // prettier-ignore
+        `\`to(...)\` is not allowed after \`match(...)\` try using \`.from(...).to(...).in(...)\`. Your query was not modified.`
+      );
+      return this;
+    }
+    this.rangeStack[1] = term;
+    return this;
+  }
+
+  /**
+   * Boosts the previous term to increase its rank in the results.
+   *
+   * ```js
+   * const query = new SearchQueryBuilder()
+   *   .match("Lakes")
+   *   .in("title")
+   *   .or()
+   *   .match("Rivers")
+   *   .in("title")
+   *   .boost(3)
+   * ```
+   */
+  public boost(this: SearchQueryBuilder, num: number) {
+    this.commit();
+    this.q += `^${num}`;
+    return this;
+  }
+
+  /**
+   * Returns the current query string. Called internally when the request is made.
+   */
+  public toParam() {
+    this.commit();
+    this.cleanup();
+    return this.q;
+  }
+
+  /**
+   * Returns a new instance of `SearchQueryBuilder` based on the current instance.
+   */
+  public clone() {
+    this.commit();
+    this.cleanup();
+    return new SearchQueryBuilder(this.q + "");
+  }
+
+  private addModifier(modifier: string) {
+    if (this.currentModifer) {
+      warn(
+        // prettier-ignore
+        `You have called \`${this.currentModifer}()\` after \`${modifier}()\`. Your current query was not modified.`
+      );
+      return this;
+    }
+
+    this.commit();
+
+    if (this.q === "" && modifier !== "not") {
+      warn(
+        `You have called \`${modifier}()\` without calling another method to modify your query first. Try calling \`match()\` first.`
+      );
+      return this;
+    }
+
+    this.currentModifer = modifier;
+    this.q += this.q === "" ? "" : " ";
+    this.q += `${modifier.toUpperCase()} `;
+    return this;
+  }
+
+  private hasWhiteSpace(s: string) {
+    return /\s/g.test(s);
+  }
+
+  private formatTerm(term: any) {
+    if (term instanceof Date) {
+      return term.getTime();
+    }
+
+    if (typeof term === "string" && this.hasWhiteSpace(term)) {
+      return `"${term}"`;
+    }
+
+    return term;
+  }
+
+  private commit() {
+    this.currentModifer = undefined;
+    if (this.hasRange) {
+      this.q += `[${this.formatTerm(this.rangeStack[0])} TO ${this.formatTerm(
+        this.rangeStack[1]
+      )}]`;
+      this.rangeStack = [undefined, undefined];
+    }
+
+    if (this.hasTerms) {
+      this.q += this.termStack
+        .map(term => {
+          return this.formatTerm(term);
+        })
+        .join(" ");
+      this.termStack = [];
+    }
+
+    return this;
+  }
+
+  private get hasTerms() {
+    return this.termStack.length > 0;
+  }
+
+  private get hasRange() {
+    return this.rangeStack.length && this.rangeStack[0] && this.rangeStack[1];
+  }
+
+  private cleanup() {
+    // end a group if we have started one
+    if (this.openGroups > 0) {
+      warn(
+        // prettier-ignore
+        `Automatically closing ${this.openGroups} group(s). You can use \`endGroup(...)\` to remove this warning.`
+      );
+
+      while (this.openGroups > 0) {
+        this.q += ")";
+        this.openGroups--;
+      }
+    }
+
+    const oldQ = this.q;
+    this.q = oldQ.replace(/( AND ?| NOT ?| OR ?)*$/, "");
+
+    if (oldQ !== this.q) {
+      warn(
+        `\`startGroup(...)\` was called without calling \`endGroup(...)\` first. Your query was not modified.`
+      );
+    }
+
+    // clear empty groups
+    this.q = this.q.replace(/(\(\))*/, "");
+  }
+}

package/packages/arcgis-rest-portal/src/util/generic-search.ts

@@ -0,0 +1,67 @@
+/* Copyright (c) 2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import {
+  request,
+  IRequestOptions,
+  appendCustomParams
+} from "@esri/arcgis-rest-request";
+import { IItem, IGroup } from "@esri/arcgis-rest-types";
+
+import { SearchQueryBuilder } from "./SearchQueryBuilder";
+import { getPortalUrl } from "../util/get-portal-url";
+import { ISearchOptions, ISearchResult } from "../util/search";
+
+export function genericSearch<T extends IItem | IGroup>(
+  search: string | ISearchOptions | SearchQueryBuilder,
+  searchType: "item" | "group"
+): Promise<ISearchResult<T>> {
+  let url: string;
+  let options: IRequestOptions;
+  if (typeof search === "string" || search instanceof SearchQueryBuilder) {
+    options = {
+      httpMethod: "GET",
+      params: {
+        q: search
+      }
+    };
+  } else {
+    options = appendCustomParams<ISearchOptions>(
+      search,
+      ["q", "num", "start", "sortField", "sortOrder"],
+      {
+        httpMethod: "GET"
+      }
+    );
+  }
+
+  url =
+    getPortalUrl(options) +
+    (searchType === "item" ? "/search" : "/community/groups");
+
+  // send the request
+  return request(url, options).then(r => {
+    if (r.nextStart && r.nextStart !== -1) {
+      r.nextPage = function() {
+        let newOptions: ISearchOptions;
+
+        if (
+          typeof search === "string" ||
+          search instanceof SearchQueryBuilder
+        ) {
+          newOptions = {
+            q: search,
+            start: r.nextStart
+          };
+        } else {
+          newOptions = search;
+          newOptions.start = r.nextStart;
+        }
+
+        return genericSearch<T>(newOptions, searchType);
+      };
+    }
+
+    return r;
+  });
+}

package/packages/arcgis-rest-portal/src/util/get-portal-url.ts

@@ -0,0 +1,27 @@
+/* Copyright (c) 2017 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { IRequestOptions, cleanUrl } from "@esri/arcgis-rest-request";
+
+/**
+ * Helper that returns the appropriate portal url for a given request. `requestOptions.portal` is given
+ * precedence over `authentication.portal`. If neither are present, `www.arcgis.com/sharing/rest` is returned.
+ *
+ * @param requestOptions - Request options that may have authentication manager
+ * @returns Portal url to be used in API requests
+ */
+export function getPortalUrl(requestOptions: IRequestOptions = {}): string {
+  // use portal in options if specified
+  if (requestOptions.portal) {
+    return cleanUrl(requestOptions.portal);
+  }
+
+  // if auth was passed, use that portal
+  if (requestOptions.authentication) {
+    // the portal url is already scrubbed in the auth package
+    return requestOptions.authentication.portal;
+  }
+
+  // default to arcgis.com
+  return "https://www.arcgis.com/sharing/rest";
+}

package/packages/arcgis-rest-portal/src/util/get-portal.ts

@@ -0,0 +1,52 @@
+/* Copyright (c) 2017-2019 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { request, IRequestOptions } from "@esri/arcgis-rest-request";
+
+import { getPortalUrl } from "./get-portal-url";
+
+export interface IPortal {
+  id: string;
+  isPortal: boolean;
+  name: string;
+  [key: string]: any;
+}
+
+/**
+ * Get the portal
+ * @param requestOptions
+ */
+export function getSelf(requestOptions?: IRequestOptions): Promise<IPortal> {
+  // just delegate to getPortal w/o an id
+  return getPortal(null, requestOptions);
+}
+
+/**
+ * ```js
+ * import { getPortal } from "@esri/arcgis-rest-request";
+ * //
+ * getPortal()
+ * getPortal("fe8")
+ * getPortal(null, { portal: "https://custom.maps.arcgis.com/sharing/rest/" })
+ * ```
+ * Fetch information about the current portal by id. If no id is passed, portals/self will be called
+ * @param id
+ * @param requestOptions
+ */
+export function getPortal(
+  id?: string,
+  requestOptions?: IRequestOptions
+): Promise<IPortal> {
+  // construct the search url
+  const idOrSelf = id ? id : "self";
+  const url = `${getPortalUrl(requestOptions)}/portals/${idOrSelf}`;
+
+  // default to a GET request
+  const options: IRequestOptions = {
+    ...{ httpMethod: "GET" },
+    ...requestOptions
+  };
+
+  // send the request
+  return request(url, options);
+}

package/packages/arcgis-rest-portal/src/util/search.ts

@@ -0,0 +1,38 @@
+/* Copyright (c) 2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { IRequestOptions } from "@esri/arcgis-rest-request";
+import { IPagingParams, IItem, IGroup } from "@esri/arcgis-rest-types";
+import { SearchQueryBuilder } from "./SearchQueryBuilder";
+
+export interface ISearchOptions extends IRequestOptions, IPagingParams {
+  q: string | SearchQueryBuilder;
+  sortField?: string;
+  sortOrder?: string;
+  [key: string]: any;
+}
+
+/**
+ * Results from an item or group search.
+ */
+export interface ISearchResult<T extends IItem | IGroup> {
+  query: string; // matches the api's form param
+  total: number;
+  start: number;
+  num: number;
+  nextStart: number;
+  results: T[];
+  nextPage?: () => Promise<ISearchResult<T>>;
+  /**
+   * Aggregations will only be present on item searches when [`fieldCounts`](https://developers.arcgis.com/rest/users-groups-and-items/search.htm#GUID-1C625F8A-4A12-45BB-B537-74C82315759A) are requested.
+   */
+  aggregations?: {
+    counts: {
+      fieldName: string;
+      fieldValues: Array<{
+        value: any;
+        count: number;
+      }>;
+    };
+  };
+}