feat: add/update associations business logic

packages/common/src/associations/addAssociation.ts

@@ -2,6 +2,9 @@ import { IWithAssociations } from "../core/traits/IWithAssociations";
 import { IAssociationInfo } from "./types";
 
 /**
+ * ** DEPRECATED: please use requestAssociation instead.
+ * This will be removed in the next breaking version **
+ *
  * Add an association to an entity
  * Persisted into the entity's `.typeKeywords` array
  * @param info

packages/common/src/associations/breakAssociation.ts

@@ -0,0 +1,64 @@
+import { unshareItemWithGroup } from "@esri/arcgis-rest-portal";
+import { IArcGISContext } from "../ArcGISContext";
+import { getProp } from "../objects";
+import { fetchHubEntity } from "../core";
+import { HubEntity, HubEntityType } from "../core/types";
+import { getTypeFromEntity } from "../core/getTypeFromEntity";
+import { updateHubEntity } from "../core/updateHubEntity";
+import { getAssociationHierarchy } from "./internal/getAssociationHierarchy";
+import { isAssociationSupported } from "./internal/isAssociationSupported";
+import { removeAssociationKeyword } from "./internal/removeAssociationKeyword";
+
+/**
+ * When an entity decides it wants to "disconnect" itself
+ * from an existing association, half of the association
+ * "connection" is broken.
+ *
+ * from the parent's perspective: the parent removes
+ * the child from its association group
+ *
+ * From the child's perspective: the child removes
+ * the parent reference (ref|<parentType>|<parentID>)
+ * from its typeKeywords
+ *
+ * @param entity - entity initiating the disconnection
+ * @param type - type of the entity the initiating entity wants to disconnect from
+ * @param id - id of the entity the initiating entity wants to disconnect from
+ * @param context - contextual portal and auth information
+ */
+export const breakAssociation = async (
+  entity: HubEntity,
+  associationType: HubEntityType,
+  id: string,
+  context: IArcGISContext
+): Promise<void> => {
+  const entityType = getTypeFromEntity(entity);
+  const isSupported = isAssociationSupported(entityType, associationType);
+
+  if (isSupported) {
+    const associationHierarchy = getAssociationHierarchy(entityType);
+    const isParent = associationHierarchy.children.includes(associationType);
+
+    if (isParent) {
+      const associationGroupId = getProp(entity, "associations.groupId");
+      const { owner } = await fetchHubEntity(associationType, id, context);
+      await unshareItemWithGroup({
+        id,
+        groupId: associationGroupId,
+        authentication: context.session,
+        owner,
+      });
+    } else {
+      entity.typeKeywords = removeAssociationKeyword(
+        entity.typeKeywords,
+        associationType,
+        id
+      );
+      await updateHubEntity(entityType, entity, context);
+    }
+  } else {
+    throw new Error(
+      `breakAssociation: Association between ${entityType} and ${associationType} is not supported.`
+    );
+  }
+};

packages/common/src/associations/getAssociatedEntitiesQuery.ts

@@ -0,0 +1,52 @@
+import { getTypeFromEntity } from "../core/getTypeFromEntity";
+import { IQuery } from "../search/types";
+import { HubEntity, HubEntityType } from "../core/types";
+import { getAssociationHierarchy } from "./internal/getAssociationHierarchy";
+import { isAssociationSupported } from "./internal/isAssociationSupported";
+import { getIncludesAndReferencesQuery } from "./internal/getIncludesAndReferencesQuery";
+import { IArcGISContext } from "../ArcGISContext";
+
+/**
+ * Associated entities are those which have mutually
+ * "agreed" to be connected with one another. They
+ * require a two-way "connection" between parent/child:
+ *
+ * parent: "includes" the child in its association query
+ * child: "references" the parent via a typeKeyword of
+ * the form ref|<parentType>|<parentID>
+ *
+ * The following returns a query to view an entity's
+ * associations with another entity type
+ *
+ * @param entity - Hub entity
+ * @param associationType - entity type to query for
+ * @param context - contextual auth and portal information
+ * @returns {IQuery}
+ */
+export const getAssociatedEntitiesQuery = async (
+  entity: HubEntity,
+  associationType: HubEntityType,
+  context: IArcGISContext
+): Promise<IQuery> => {
+  let query: IQuery;
+  const entityType = getTypeFromEntity(entity);
+  const isSupported = isAssociationSupported(entityType, associationType);
+
+  if (isSupported) {
+    const associationHierarchy = getAssociationHierarchy(entityType);
+    const isParent = associationHierarchy.children.includes(associationType);
+
+    query = await getIncludesAndReferencesQuery(
+      entity,
+      associationType,
+      isParent,
+      context
+    );
+  } else {
+    throw new Error(
+      `getAssociatedEntitiesQuery: Association between ${entityType} and ${associationType} is not supported.`
+    );
+  }
+
+  return query;
+};

packages/common/src/associations/getAssociationStats.ts

@@ -0,0 +1,83 @@
+import { IArcGISContext } from "../ArcGISContext";
+import { getTypeFromEntity } from "../core/getTypeFromEntity";
+import { HubEntity, HubEntityType } from "../core/types";
+import { IQuery } from "../search/types";
+import { hubSearch } from "../search/hubSearch";
+import { getAssociatedEntitiesQuery } from "./getAssociatedEntitiesQuery";
+import { getPendingEntitiesQuery } from "./getPendingEntitiesQuery";
+import { getRequestingEntitiesQuery } from "./getRequestingEntitiesQuery";
+import { getAssociationHierarchy } from "./internal/getAssociationHierarchy";
+import { isAssociationSupported } from "./internal/isAssociationSupported";
+
+interface IAssociationStats {
+  associated: number;
+  pending: number;
+  requesting: number;
+  referenced?: number;
+  included?: number;
+}
+
+/**
+ * get an entity's association stats - # of associated, pending,
+ * requesting, included/referenced entities
+ *
+ * @param entity - Hub entity
+ * @param associationType - entity type to query for
+ * @param context - contextual auth and portal information
+ * @returns
+ */
+export const getAssociationStats = async (
+  entity: HubEntity,
+  associationType: HubEntityType,
+  context: IArcGISContext
+): Promise<IAssociationStats> => {
+  let stats: IAssociationStats;
+  const entityType = getTypeFromEntity(entity);
+  const isSupported = isAssociationSupported(entityType, associationType);
+
+  if (isSupported) {
+    const associationHierarchy = getAssociationHierarchy(entityType);
+    const isParent = associationHierarchy.children.includes(associationType);
+
+    stats = {
+      associated: 0,
+      pending: 0,
+      requesting: 0,
+      ...(isParent ? { included: 0 } : { referenced: 0 }),
+    };
+
+    try {
+      const queries = await Promise.all([
+        getAssociatedEntitiesQuery(entity, associationType, context),
+        getPendingEntitiesQuery(entity, associationType, context),
+        getRequestingEntitiesQuery(entity, associationType, context),
+      ]);
+
+      const [{ total: associated }, { total: pending }, { total: requesting }] =
+        await Promise.all(
+          queries.map((query: IQuery) => {
+            return hubSearch(query, {
+              requestOptions: context.hubRequestOptions,
+            });
+          })
+        );
+
+      stats = {
+        associated,
+        pending,
+        requesting,
+        ...(isParent
+          ? { included: associated + pending }
+          : { referenced: associated + pending }),
+      };
+    } catch (error) {
+      return stats;
+    }
+  } else {
+    throw new Error(
+      `getAssociationStats: Association between ${entityType} and ${associationType} is not supported.`
+    );
+  }
+
+  return stats;
+};