@esri/hub-common 9.48.0 → 9.49.0

package/dist/umd/common.umd.js

@@ -1,5 +1,5 @@
 /* @preserve
- * @esri/hub-common - v9.47.0 - Wed Jul 20 2022 22:15:24 GMT+0000 (Coordinated Universal Time)
+ * @esri/hub-common - v9.48.0 - Thu Jul 21 2022 15:41:36 GMT+0000 (Coordinated Universal Time)
  * Copyright (c) 2022 Environmental Systems Research Institute, Inc.
  * Apache-2.0
  */
@@ -14985,36 +14985,68 @@
         return __assign(__assign({}, state), facetState);
     }
 
+    var CATALOG_SCHEMA_VERSION = 1.0;
     /**
-     * Convert the original site catalog structure into a formal ICatalog
-     * @param original
+     * Apply schema upgrades to Catalog objects
+     * @param catalog
+     * @returns
      */
-    function convertCatalog(original) {
-        var catalog = {
-            schemaVersion: 1,
-            title: "Default Catalog",
-            scopes: {
-                item: {
-                    targetEntity: "item",
-                    filters: [],
-                },
-            },
-            collections: [],
-        };
-        var rawGroups = getProp(original, "groups");
-        var groups = [];
-        if (Array.isArray(rawGroups) && rawGroups.length) {
-            groups = rawGroups;
+    function upgradeCatalogSchema(catalog) {
+        var clone = cloneObject$1(catalog);
+        if (getProp(clone, "schemaVersion") === CATALOG_SCHEMA_VERSION) {
+            return clone;
         }
-        else if (typeof rawGroups === "string") {
-            groups = [rawGroups];
+        else {
+            // apply migrations in order
+            clone = applyCatalogSchema(clone);
+            return clone;
         }
-        if (groups.length) {
-            catalog.scopes.item.filters.push({
-                predicates: [{ group: groups }],
-            });
+    }
+    /**
+     * Apply the Catalog schema to the original, unversioned
+     * site catalog objects
+     * @param original
+     * @returns
+     */
+    function applyCatalogSchema(original) {
+        if (getProp(original, "schemaVersion") > 1.0) {
+            return original;
+        }
+        else {
+            var catalog = {
+                schemaVersion: 1,
+                title: "Default Catalog",
+                scopes: {
+                    item: {
+                        targetEntity: "item",
+                        filters: [],
+                    },
+                },
+                collections: [],
+            };
+            var rawGroups = getProp(original, "groups");
+            var groups = [];
+            if (Array.isArray(rawGroups) && rawGroups.length) {
+                groups = rawGroups;
+            }
+            else if (typeof rawGroups === "string") {
+                groups = [rawGroups];
+            }
+            if (groups.length) {
+                catalog.scopes.item.filters.push({
+                    predicates: [{ group: groups }],
+                });
+            }
+            return catalog;
         }
-        return catalog;
+    }
+    /**
+     * DEPRECATED: Use upgradeCatalogSchema(...)
+     * @param original
+     */
+    /* istanbul ignore next */
+    function convertCatalog(original) {
+        return upgradeCatalogSchema(original);
     }
 
     /**
@@ -18813,13 +18845,584 @@
                 };
                 fn = getProp(fnHash, apiType + "." + filterType);
                 if (!fn) {
-                    throw new HubError$1("hubSearch", "Search via \"" + filterType + "\" filter against \"" + apiType + "\" api is not implemented");
+                    throw new HubError$1("hubSearch", "Search via \"" + filterType + "\" filter against \"" + apiType + "\" api is not implemented. Please ensure \"targetEntity\" is defined on the query.");
                 }
                 return [2 /*return*/, fn(cloneObject$1(query), options)];
             });
         });
     }
 
+    /**
+     * Collection Class
+     *
+     * Abstracts searching a Collection
+     *
+     * For more information, check out the [Catalog & Collection Guide](/hub.js/guides/concepts/catalog-collection/)
+     */
+    var Collection = /** @class */ (function () {
+        function Collection(collection, context) {
+            this._collection = collection;
+            this._context = context;
+        }
+        /**
+         * Create an instance of a Collection from a JSON object
+         * @param collection
+         * @param context
+         * @returns
+         */
+        Collection.fromJson = function (collection, context) {
+            return new Collection(collection, context);
+        };
+        /**
+         * Return the JSON object backing the instance
+         * @returns
+         */
+        Collection.prototype.toJson = function () {
+            return cloneObject$1(this._collection);
+        };
+        Object.defineProperty(Collection.prototype, "label", {
+            // Getters
+            get: function () {
+                return this._collection.label;
+            },
+            enumerable: false,
+            configurable: true
+        });
+        Object.defineProperty(Collection.prototype, "key", {
+            get: function () {
+                return this._collection.key;
+            },
+            enumerable: false,
+            configurable: true
+        });
+        Object.defineProperty(Collection.prototype, "include", {
+            get: function () {
+                return this._collection.include || [];
+            },
+            enumerable: false,
+            configurable: true
+        });
+        Object.defineProperty(Collection.prototype, "scope", {
+            get: function () {
+                return this._collection.scope;
+            },
+            enumerable: false,
+            configurable: true
+        });
+        Object.defineProperty(Collection.prototype, "sortField", {
+            get: function () {
+                return this._collection.sortField || "title";
+            },
+            enumerable: false,
+            configurable: true
+        });
+        Object.defineProperty(Collection.prototype, "sortDirection", {
+            get: function () {
+                return this._collection.sortDirection || "asc";
+            },
+            enumerable: false,
+            configurable: true
+        });
+        Object.defineProperty(Collection.prototype, "targetEntity", {
+            get: function () {
+                return this._collection.targetEntity;
+            },
+            enumerable: false,
+            configurable: true
+        });
+        /**
+         * Search the collection using a string or IQuery
+         * @param query
+         * @param options
+         * @returns
+         */
+        Collection.prototype.search = function (query, options) {
+            if (options === void 0) { options = {}; }
+            return __awaiter(this, void 0, void 0, function () {
+                var qry, opts;
+                return __generator(this, function (_a) {
+                    if (typeof query === "string") {
+                        // construct a query from that...
+                        qry = {
+                            targetEntity: this._collection.targetEntity,
+                            filters: [
+                                {
+                                    predicates: [
+                                        {
+                                            term: query,
+                                        },
+                                    ],
+                                },
+                            ],
+                        };
+                    }
+                    else {
+                        qry = query;
+                    }
+                    // TODO: What should happen when a Query is passed in that has a targetEntity that doesn't match the collection's targetEntity?
+                    // merge the passed in query w/ the scope
+                    qry.filters = __spreadArrays(qry.filters, this.scope.filters);
+                    opts = cloneObject$1(options);
+                    opts.requestOptions = this._context.hubRequestOptions;
+                    // inject default sort info if not specified
+                    opts.sortField = options.sortField || this.sortField;
+                    opts.sortOrder = options.sortOrder || this.sortDirection;
+                    // inject default includes if not specified
+                    opts.include = options.include || this.include;
+                    // execute the search and return results
+                    return [2 /*return*/, hubSearch(qry, opts)];
+                });
+            });
+        };
+        return Collection;
+    }());
+
+    /**
+     * Fetch a IHubCatalog from a backing item.
+     * This will apply schema upgrades to the structure
+     * @param identifier
+     * @param requestOptions
+     * @returns
+     */
+    function fetchCatalog(identifier, requestOptions) {
+        return __awaiter(this, void 0, void 0, function () {
+            var getPrms, url, fetched;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        // identifier can be a guid or a url
+                        if (identifier.indexOf("http") === 0) {
+                            url = identifier;
+                            // get down the the hostname
+                            url = stripProtocol(url);
+                            // if url does not include a hash (i.e. it's not portal)
+                            // then we want to split on the first slash to get the hostname
+                            // lookupDomain will handle the enterprise base urls
+                            if (!url.includes("#")) {
+                                url = url.split("/")[0];
+                            }
+                            getPrms = lookupDomain(url, requestOptions)
+                                // get the item's data, and read the catalog out of it
+                                .then(function (_a) {
+                                var siteId = _a.siteId;
+                                return getItemData(siteId, requestOptions);
+                            })
+                                .then(function (data) {
+                                return upgradeCatalogSchema(data.catalog || {});
+                            });
+                        }
+                        else if (isGuid(identifier)) {
+                            // get the item's data, and read the catalog out of it
+                            getPrms = getItemData(identifier, requestOptions).then(function (data) {
+                                return upgradeCatalogSchema(data.catalog || {});
+                            });
+                        }
+                        else {
+                            throw new HubError$1("Catalog.create", "Identifier must be a url, guid");
+                        }
+                        return [4 /*yield*/, getPrms];
+                    case 1:
+                        fetched = _a.sent();
+                        return [2 /*return*/, fetched];
+                }
+            });
+        });
+    }
+
+    /**
+     * Catalog Class
+     *
+     * Abstracts working with Catalogs and fetching collections with
+     * the correct scope applied.
+     *
+     * For more information, check out the [Catalog & Collection Guide](/hub.js/guides/concepts/catalog-collection/)
+     */
+    var Catalog = /** @class */ (function () {
+        // internal - use static factory methods
+        function Catalog(catalog, context) {
+            this._catalog = catalog;
+            this._context = context;
+        }
+        /**
+         * Create a Collection instance from a Catalog json object, a site url or itemId
+         * '''js
+         * const catalog = await Catalog.create('https://site-org.hub.arcgis.com', context);
+         * '''
+         *
+         * @param identifier
+         * @param context
+         * @returns
+         */
+        Catalog.init = function (identifier, context) {
+            return __awaiter(this, void 0, void 0, function () {
+                var mgr, fetched;
+                return __generator(this, function (_a) {
+                    switch (_a.label) {
+                        case 0:
+                            if (!!context) return [3 /*break*/, 2];
+                            return [4 /*yield*/, ArcGISContextManager.create()];
+                        case 1:
+                            mgr = _a.sent();
+                            context = mgr.context;
+                            _a.label = 2;
+                        case 2: return [4 /*yield*/, fetchCatalog(identifier, context.hubRequestOptions)];
+                        case 3:
+                            fetched = _a.sent();
+                            // return an instance
+                            return [2 /*return*/, new Catalog(fetched, context)];
+                    }
+                });
+            });
+        };
+        /**
+         * Create a Catalog instance from a Catalog Json object
+         * @param json
+         * @param context
+         * @returns
+         */
+        Catalog.fromJson = function (json, context) {
+            // ensure it's in the latest structure
+            var catalog = upgradeCatalogSchema(json);
+            return new Catalog(catalog, context);
+        };
+        /**
+         * Return the JSON object backing the instance
+         * @returns
+         */
+        Catalog.prototype.toJson = function () {
+            return cloneObject$1(this._catalog);
+        };
+        Object.defineProperty(Catalog.prototype, "schemaVersion", {
+            /**
+             * Return the schema version
+             */
+            get: function () {
+                return this._catalog.schemaVersion;
+            },
+            enumerable: false,
+            configurable: true
+        });
+        Object.defineProperty(Catalog.prototype, "title", {
+            /**
+             * Title getter
+             */
+            get: function () {
+                return this._catalog.title;
+            },
+            /**
+             * Title setter
+             */
+            set: function (v) {
+                this._catalog.title = v;
+            },
+            enumerable: false,
+            configurable: true
+        });
+        Object.defineProperty(Catalog.prototype, "scopes", {
+            /**
+             * Return the existing scopes hash
+             */
+            get: function () {
+                return this._catalog.scopes;
+            },
+            enumerable: false,
+            configurable: true
+        });
+        Object.defineProperty(Catalog.prototype, "availableScopes", {
+            /**
+             * Return an array of the entity types available in this Catalog
+             */
+            get: function () {
+                return Object.keys(this.scopes);
+            },
+            enumerable: false,
+            configurable: true
+        });
+        /**
+         * Get the scope's query for a particular entity type
+         * @param type
+         * @returns
+         */
+        Catalog.prototype.getScope = function (type) {
+            return this._catalog.scopes[type];
+        };
+        /**
+         * Set the scope for a specific entity type
+         * @param type
+         * @param query
+         */
+        Catalog.prototype.setScope = function (type, query) {
+            this._catalog.scopes[type] = query;
+        };
+        Object.defineProperty(Catalog.prototype, "collections", {
+            /**
+             * Get the collections array. Returns simple objects not Collection instances
+             */
+            get: function () {
+                return this._catalog.collections || [];
+            },
+            enumerable: false,
+            configurable: true
+        });
+        Object.defineProperty(Catalog.prototype, "collectionNames", {
+            /**
+             * Get the names of the collections
+             */
+            get: function () {
+                return mapBy("key", this.collections);
+            },
+            enumerable: false,
+            configurable: true
+        });
+        /**
+         * Get a Collection instance by name
+         * @param name
+         * @returns
+         */
+        Catalog.prototype.getCollection = function (name) {
+            var json = this.collections.find(function (entry) { return entry.key === name; });
+            if (json) {
+                // clone it then merge in the associated scope filter
+                var clone = cloneObject$1(json);
+                var catalogScope = this.getScope(clone.scope.targetEntity);
+                if (catalogScope === null || catalogScope === void 0 ? void 0 : catalogScope.filters) {
+                    clone.scope.filters = __spreadArrays(clone.scope.filters, catalogScope.filters);
+                }
+                return Collection.fromJson(clone, this._context);
+            }
+            else {
+                throw new HubError$1("getCollection", "Collection \"" + name + "\" is not present in the Catalog");
+            }
+        };
+        /**
+         * Search for Items
+         * Will throw if the Catalog does not have a scope defined for items
+         * @param query
+         * @param options
+         * @returns
+         */
+        Catalog.prototype.searchItems = function (query, options) {
+            if (options === void 0) { options = {}; }
+            if (!this.getScope("item")) {
+                var result = this.getEmptyResult();
+                result.messages = [
+                    {
+                        code: "missingScope",
+                        message: "Catalog does not have a scope for items",
+                        data: {
+                            scope: "item",
+                        },
+                    },
+                ];
+                return Promise.resolve(result);
+            }
+            else {
+                // ensure it's an item search
+                options.targetEntity = "item";
+                return this.search(query, options);
+            }
+        };
+        /**
+         * Search for Groups
+         * Will throw if the Catalog does not have a scope defined for groups
+         * @param query
+         * @param options
+         * @returns
+         */
+        Catalog.prototype.searchGroups = function (query, options) {
+            if (options === void 0) { options = {}; }
+            if (!this.getScope("group")) {
+                var result = this.getEmptyResult();
+                result.messages = [
+                    {
+                        code: "missingScope",
+                        message: "Catalog does not have a scope for groups",
+                        data: {
+                            scope: "group",
+                        },
+                    },
+                ];
+                return Promise.resolve(result);
+            }
+            else {
+                // ensure it's an group search
+                options.targetEntity = "group";
+                return this.search(query, options);
+            }
+        };
+        /**
+         * Search for Users
+         * Will throw if the Catalog does not have a scope defined for users
+         * @param query
+         * @param options
+         * @returns
+         */
+        Catalog.prototype.searchUsers = function (query, options) {
+            if (options === void 0) { options = {}; }
+            if (!this.getScope("user")) {
+                var result = this.getEmptyResult();
+                result.messages = [
+                    {
+                        code: "missingScope",
+                        message: "Catalog does not have a scope for user",
+                        data: {
+                            scope: "user",
+                        },
+                    },
+                ];
+                return Promise.resolve(result);
+            }
+            else {
+                // ensure it's an group search
+                options.targetEntity = "user";
+                return this.search(query, options);
+            }
+        };
+        /**
+         * Execute a search against all the collections in the Catalog
+         * @param query
+         * @param options
+         * @returns
+         */
+        Catalog.prototype.searchCollections = function (query, options) {
+            if (options === void 0) { options = {}; }
+            return __awaiter(this, void 0, void 0, function () {
+                var qry, promiseKeys, promises, responses, hash, i;
+                var _this = this;
+                return __generator(this, function (_a) {
+                    switch (_a.label) {
+                        case 0:
+                            qry = {
+                                targetEntity: "item",
+                                filters: [
+                                    {
+                                        predicates: [
+                                            {
+                                                term: query,
+                                            },
+                                        ],
+                                    },
+                                ],
+                            };
+                            promiseKeys = [];
+                            promises = this.collectionNames.map(function (name) {
+                                var col = _this.getCollection(name);
+                                promiseKeys.push(name);
+                                qry.targetEntity = col.targetEntity;
+                                return col.search(qry, options);
+                            });
+                            return [4 /*yield*/, Promise.all(promises)];
+                        case 1:
+                            responses = _a.sent();
+                            hash = {};
+                            for (i = 0; i < promiseKeys.length; i++) {
+                                hash[promiseKeys[i]] = responses[i];
+                            }
+                            return [2 /*return*/, hash];
+                    }
+                });
+            });
+        };
+        /**
+         * Execute a search against all the scopes in the Catalog
+         * @param query
+         * @param options
+         * @returns
+         */
+        Catalog.prototype.searchScopes = function (query, options) {
+            if (options === void 0) { options = {}; }
+            return __awaiter(this, void 0, void 0, function () {
+                var qry, promiseKeys, promises, responses, hash, i;
+                var _this = this;
+                return __generator(this, function (_a) {
+                    switch (_a.label) {
+                        case 0:
+                            qry = {
+                                targetEntity: "item",
+                                filters: [
+                                    {
+                                        predicates: [
+                                            {
+                                                term: query,
+                                            },
+                                        ],
+                                    },
+                                ],
+                            };
+                            promiseKeys = [];
+                            promises = this.availableScopes.map(function (name) {
+                                promiseKeys.push(name);
+                                // make clones
+                                var qryClone = cloneObject$1(qry);
+                                var optsClone = cloneObject$1(options);
+                                // set the target entity
+                                qryClone.targetEntity = name;
+                                optsClone.targetEntity = name;
+                                // return the search promise
+                                return _this.search(qryClone, optsClone);
+                            });
+                            return [4 /*yield*/, Promise.all(promises)];
+                        case 1:
+                            responses = _a.sent();
+                            hash = {};
+                            for (i = 0; i < promiseKeys.length; i++) {
+                                hash[promiseKeys[i]] = responses[i];
+                            }
+                            return [2 /*return*/, hash];
+                    }
+                });
+            });
+        };
+        /**
+         * Execute a search against the Catalog as a whole
+         * @param query
+         * @param targetEntity
+         * @returns
+         */
+        Catalog.prototype.search = function (query, options) {
+            var targetEntity = options.targetEntity;
+            var qry;
+            if (typeof query === "string") {
+                qry = {
+                    targetEntity: targetEntity,
+                    filters: [
+                        {
+                            predicates: [
+                                {
+                                    term: query,
+                                },
+                            ],
+                        },
+                    ],
+                };
+            }
+            else {
+                qry = cloneObject$1(query);
+            }
+            // Now merge in catalog scope level filters
+            qry.filters = __spreadArrays(qry.filters, this.getScope(targetEntity).filters);
+            var opts = cloneObject$1(options);
+            // An Catalog instance always uses the context so we remove/replace any passed in auth
+            delete opts.authentication;
+            opts.requestOptions = this._context.hubRequestOptions;
+            return hubSearch(qry, opts);
+        };
+        /**
+         * Construct an empty result. Returned when a search is performed against an entity type that
+         * does not have a scope defined.
+         * @returns
+         */
+        Catalog.prototype.getEmptyResult = function () {
+            return {
+                results: [],
+                total: 0,
+                hasNext: false,
+                next: null,
+            };
+        };
+        return Catalog;
+    }());
+
     /**
      * Enrich a generic search result
      * @param group
@@ -20430,6 +21033,8 @@
 
     exports.ArcGISContext = ArcGISContext;
     exports.ArcGISContextManager = ArcGISContextManager;
+    exports.Catalog = Catalog;
+    exports.Collection = Collection;
     exports.DEFAULT_THEME = DEFAULT_THEME;
     exports.ENTERPRISE_SITE_ITEM_TYPE = ENTERPRISE_SITE_ITEM_TYPE;
     exports.GLOBAL_EXTENT = GLOBAL_EXTENT;
@@ -20741,6 +21346,7 @@
     exports.updateModel = updateModel;
     exports.updateProject = updateProject;
     exports.updateSite = updateSite;
+    exports.upgradeCatalogSchema = upgradeCatalogSchema;
     exports.upgradeProtocol = upgradeProtocol;
     exports.upgradeSiteSchema = upgradeSiteSchema;
     exports.uploadResourcesFromUrl = uploadResourcesFromUrl;