@esri/hub-common 9.1.3 → 9.4.0

package/dist/types/search/types.d.ts

@@ -0,0 +1,294 @@
+import { UserSession } from "@esri/arcgis-rest-auth";
+import { IHubContent } from "..";
+/**
+ * Generic filter used with various search functions.
+ *
+ * `Filter<T extends FilterType>` [FilterType](../FilterType) is constrained to
+ *
+ * - `Filter<"any">` [IAnyFilterDefinition](../IAnyFilterDefinition)
+ * - `Filter<"content">` [IContentFilterDefinition](../IContentFilterDefinition)
+ * - `Filter<"user">` [IUserFilterDefinition](../IUserFilterDefinition)
+ * - `Filter<"group">` [IGroupFilterDefinition](../IGroupFilterDefinition)
+ *
+ * When constructing a Filter as json, the `filterType` must be specified,
+ * and it must be `keyof` [FilterTypeMap](../FilterTypeMap)
+ *
+ * ```ts
+ * const f:Filter<"content"> = {
+ *   filterType: "content" // must match the FilterType
+ *   term: "water"
+ * }
+ * ```
+ */
+export declare type Filter<T extends FilterType> = IFilterTypeMap[T] & {
+    filterType: T;
+};
+/**
+ * Defines the valid FilterTypes for use with `Filter<T extends FilterType>`
+ * See [Filter](../Filter)
+ */
+export interface IFilterTypeMap {
+    any: IAnyFilterDefinition;
+    content: IContentFilterDefinition;
+    user: IUserFilterDefinition;
+    group: IGroupFilterDefinition;
+    event: IEventFilterDefinition;
+}
+export declare type FilterType = keyof IFilterTypeMap;
+/**
+ * Common set of fields that are reasonable to apply at the
+ * top level of a Catalog
+ */
+export interface IAnyFilterDefinition {
+    title?: string | string[] | IMatchOptions;
+    access?: string | string[] | IMatchOptions;
+    owner?: string | string[] | IMatchOptions;
+    tags?: string | string[] | IMatchOptions;
+    created?: IDateRange<number> | IRelativeDate;
+    modified?: IDateRange<number> | IRelativeDate;
+    description?: string | string[] | IMatchOptions;
+    group?: string | string[] | IMatchOptions;
+    orgid?: string | string[] | IMatchOptions;
+    type?: string | NamedContentFilter | Array<string | NamedContentFilter> | IMatchOptions;
+}
+/**
+ * Fields related to Content based searches
+ */
+export interface IContentFilterDefinition {
+    access?: string | string[] | IMatchOptions;
+    owner?: string | string[] | IMatchOptions;
+    tags?: string | string[] | IMatchOptions;
+    created?: IDateRange<number> | IRelativeDate;
+    description?: string | string[] | IMatchOptions;
+    snippet?: string | string[] | IMatchOptions;
+    group?: string | string[] | IMatchOptions;
+    id?: string | string[] | IMatchOptions;
+    modified?: IDateRange<number> | IRelativeDate;
+    orgid?: string | string[] | IMatchOptions;
+    term?: string;
+    title?: string | string[] | IMatchOptions;
+    type?: string | NamedContentFilter | Array<string | NamedContentFilter> | IMatchOptions;
+    typekeywords?: string | string[] | IMatchOptions;
+    [key: string]: any;
+    /**
+     * @internal
+     * Support for complex OR queries; Used with various expansions
+     */
+    subFilters?: Array<IContentFilterDefinition | NamedContentFilter>;
+}
+export interface IContentFilter {
+    access?: IMatchOptions;
+    created?: IDateRange<number>;
+    description?: IMatchOptions;
+    group?: IMatchOptions;
+    id?: IMatchOptions;
+    modified?: IDateRange<number>;
+    orgid?: IMatchOptions;
+    owner?: IMatchOptions;
+    tags?: IMatchOptions;
+    term?: string;
+    title?: IMatchOptions;
+    type?: IMatchOptions;
+    typekeywords?: IMatchOptions;
+    [key: string]: any;
+    subFilters?: IContentFilter[];
+}
+export interface IWellKnownContentFilters {
+    $apps: IContentFilterDefinition[];
+    $dashboard: IContentFilterDefinition[];
+    $dataset: IContentFilterDefinition[];
+    $experience: IContentFilterDefinition[];
+    $site: IContentFilterDefinition[];
+    $storymap: IContentFilterDefinition[];
+    $initiative: IContentFilterDefinition[];
+    $document: IContentFilterDefinition[];
+}
+export declare type NamedContentFilter = keyof IWellKnownContentFilters;
+export interface IUserFilterDefinition {
+    disabled?: boolean;
+    email?: string | string[] | IMatchOptions;
+    firstname?: string | string[] | IMatchOptions;
+    fullname?: string | string[] | IMatchOptions;
+    groups?: string | string[] | IMatchOptions;
+    lastname?: string | string[] | IMatchOptions;
+    username?: string | string[] | IMatchOptions;
+}
+export interface IGroupFilterDefinition {
+    access?: string | string[] | IMatchOptions;
+    created?: IDateRange<number> | IRelativeDate;
+    id?: string | string[] | IMatchOptions;
+    isInvitationOnly: boolean;
+    modified?: IDateRange<number> | IRelativeDate;
+    orgid?: string | string[] | IMatchOptions;
+    searchUserAccess?: "groupMember" | "admin";
+    tags?: string | string[] | IMatchOptions;
+    title?: string | string[] | IMatchOptions;
+    typekeywords?: string | string[] | IMatchOptions;
+}
+export interface IEventFilterDefinition {
+    created?: IDateRange<number> | IRelativeDate;
+    modified?: IDateRange<number> | IRelativeDate;
+    orgid?: string | string[] | IMatchOptions;
+    title?: string | string[] | IMatchOptions;
+}
+export interface IFacet {
+    label: string;
+    attribute?: string;
+    type: "single-select" | "multi-select" | "date-range" | "histogram";
+    options?: IFacetOption[];
+}
+export interface IFacetOption {
+    label: string;
+    value: string;
+    count?: number;
+    selected: boolean;
+    filter: Filter<FilterType>;
+}
+/**
+ * Catalog is the definition which powers what options
+ * are available in a Gallery. It controls not only
+ * the scoping of the search, but also the options
+ * available to the UX.
+ *
+ * Thus the lower-level `searchContent`, `searchUser`, `searchGroup` functions
+ * do not take Catalogs, rather they accept [Filters](../Filter)
+ *
+ * ```ts
+ * const simpleCatalog:Catalog = {
+ *   title: "Select Map",
+ *   filter: {
+ *     filterType: "content",
+ *     type: "Web Map",
+ *     owner: "jsmith"
+ *   }
+ * }
+ * ```
+ *
+ * ## Collections
+ * The key feature of a Catalog is the ability to defined [Collections](../Collection).
+ * These are essentially sub-sets of content, typically organized around
+ * generalized content types, i.e. "Datasets", vs "Maps", vs "Documents"
+ *
+ *
+ * ```ts
+ * const complex:Catalog = {
+ *   filter: {
+ *    type: "content",
+ *    groups: ["3ef", "bc4"]
+ *   },
+ *   collections: [
+ *     {
+ *       label: "Documents",
+ *       filter: {
+ *         filterType: "content",
+ *         type: ["Microsoft Word", "PDF", "Microsoft Excel"]
+ *       }
+ *     },
+ *     {
+ *       label: "Datasets",
+ *       filter: {
+ *         filterType: "content",
+ *         type: ["Feature Layer", "Feature Service", "Map Service", "CSV"]
+ *       }
+ *     }
+ *   ]
+ * }
+ * ```
+ */
+export interface ICatalog {
+    /**
+     * Title for the Gallery
+     */
+    title?: string;
+    filter: Filter<FilterType>;
+    sort?: ISortOption[];
+    collections?: ICollection[];
+    facets?: IFacet[];
+}
+export interface ISortOption {
+    label: string;
+    attribute: string;
+}
+/**
+ * A Filter that defines a subset of a Catalog, aka a Collection
+ */
+export interface ICollection {
+    label: string;
+    filter: Filter<FilterType>;
+    facets?: IFacet[];
+}
+export interface IDateRange<T> {
+    type?: "date-range";
+    from: T;
+    to: T;
+}
+export interface IRelativeDate {
+    type: "relative-date";
+    num: number;
+    unit: "minutes" | "hours" | "days" | "weeks" | "months" | "years";
+}
+/**
+ * Define how values should be matched
+ */
+export interface IMatchOptions {
+    /**
+     * return results which have ANY of the listed values
+     * for the specified field
+     */
+    any?: string | string[];
+    /**
+     * return resutls which have ALL of the listed values
+     * for the specified field
+     */
+    all?: string | string[];
+    /**
+     * return results which do not have any of the listed
+     * values for the specified field
+     */
+    not?: string | string[];
+    /**
+     * Depending on the API being searched, `exact` will
+     * attempt to structure the query such that it is an
+     * exact match. For Portal API, this may involve using
+     * the `filter` parameter, if the specific field can
+     * be used with that parameter
+     */
+    exact?: string | string[];
+}
+/**
+ * Search Options
+ */
+export interface IHubSearchOptions {
+    site?: string;
+    authentication?: UserSession;
+    sortField?: string;
+    sortOrder?: "desc" | "asc";
+    page?: string;
+    num?: number;
+    aggregations?: string[];
+    bbox?: string;
+    fields?: string;
+    apis?: Array<NamedApis | IApiDefinition>;
+}
+/**
+ * searchContent return
+ */
+export interface IContentSearchResult {
+    content: IHubContent[];
+    facets?: IFacet[];
+}
+export interface IWellKnownApis {
+    arcgis: IApiDefinition;
+    arcgisQA: IApiDefinition;
+    arcgisDEV: IApiDefinition;
+    hub: IApiDefinition;
+    hubQA: IApiDefinition;
+    hubDEV: IApiDefinition;
+}
+export declare type NamedApis = keyof IWellKnownApis;
+export interface IApiDefinition {
+    label?: string;
+    url: string;
+    type: "arcgis" | "arcgis-hub";
+    authentication?: UserSession;
+}

package/dist/types/search/utils.d.ts

@@ -0,0 +1,92 @@
+import { ISearchOptions } from "@esri/arcgis-rest-portal";
+import { IMatchOptions, IDateRange, IRelativeDate, IWellKnownApis, IApiDefinition, NamedApis, IContentSearchResult } from "./types";
+/**
+ * Well known APIs
+ * Short-forms for specifying common APIs
+ */
+export declare const SEARCH_APIS: IWellKnownApis;
+/**
+ * @private
+ * Convert api "names" into full ApiDefinitions
+ * @param apis
+ * @returns
+ */
+export declare function expandApis(apis: Array<NamedApis | IApiDefinition>): IApiDefinition[];
+/**
+ * @private
+ * Merge multiple search responses
+ *
+ * Naieve implementation that just merges arrays
+ * @param responses
+ * @returns
+ */
+export declare function mergeSearchResults(responses: IContentSearchResult[]): IContentSearchResult;
+/**
+ * @private
+ * Merge two date ranges by taking the longest span
+ * @param dr1
+ * @param dr2
+ * @returns
+ */
+export declare function mergeDateRange(dr1: IDateRange<number>, dr2: IDateRange<number>): IDateRange<number>;
+/**
+ * @private
+ * Merge two [`MatchOptions`](../MatchOptions)
+ *
+ * Currently a naieve implementation where the arrays are simply merged
+ *
+ * @param mo1
+ * @param mo2
+ * @returns
+ */
+export declare function mergeMatchOptions(mo1: IMatchOptions, mo2: IMatchOptions): IMatchOptions;
+/**
+ * @private
+ * Convert a field value into a MatchOptions if it's not already one
+ * @param value
+ * @returns
+ */
+export declare function valueToMatchOptions(value: string | string[] | IMatchOptions): IMatchOptions;
+/**
+ * @private
+ * Convert a RelativeDate to a DateRange<number>
+ * @param relative
+ * @returns
+ */
+export declare function relativeDateToDateRange(relative: IRelativeDate): IDateRange<number>;
+/**
+ * @private
+ * As a final `ISearchOptions` object gets created, many such objects are created, and
+ * need to be systematically "merged" so as to return consistently structured `q` and `filter`
+ * values.
+ * @param so1
+ * @param so2
+ * @param join
+ * @returns
+ */
+export declare function mergeSearchOptions(so1: ISearchOptions, so2: ISearchOptions, join: "AND" | "OR"): ISearchOptions;
+/**
+ * @private
+ * Serialize a `MatchOptions` into `q` or `filter` on an `ISearchOptions`
+ * @param key
+ * @param opts
+ * @returns
+ */
+export declare function serializeMatchOptions(key: string, opts: IMatchOptions): ISearchOptions;
+/**
+ * @private
+ * Serialize a DateRange<number> into a Portal Query string
+ * @param key
+ * @param range
+ * @returns
+ */
+export declare function serializeDateRange(key: string, range: IDateRange<number>): ISearchOptions;
+/**
+ * @private
+ * Serialize a `string` or `string[]` into a string
+ * @param join
+ * @param key
+ * @param value
+ * @returns
+ */
+export declare function serializeStringOrArray(join: "AND" | "OR", key: string, value: string | string[]): string;