@amityco/ts-sdk 6.29.3-b60ec74.0 → 6.29.3-bd024fd.0

package/src/communityRepository/communityModeration/events/onLocalCommunityRoleRemoved.ts

@@ -0,0 +1,38 @@
+import { getActiveClient } from '~/client/api/activeClient';
+import { createEventSubscriber } from '~/core/events';
+
+/**
+ * ```js
+ * import { onLocalCommunityRoleRemoved } from '@amityco/ts-sdk'
+ * const dispose = onLocalCommunityRoleRemoved((community, member) => {
+ *   // ...
+ * })
+ * ```
+ *
+ * Fired when any {@link Amity.communityUsers} 's role has been added to any {@link Amity.Community}
+ *
+ * @param callback The function to call when the event was fired
+ * @returns an {@link Amity.Unsubscriber} function to stop listening
+ *
+ * @category Community Events
+ */
+export const onLocalCommunityRoleRemoved = (
+  callback: (community: Amity.Community, member: Amity.Membership<'community'>[]) => void,
+): Amity.Unsubscriber => {
+  const client = getActiveClient();
+
+  const filter = async (payload: Amity.ProcessedCommunityMembershipPayload) => {
+    const { communities, communityUsers } = payload;
+    callback(
+      communities[0],
+      communityUsers.filter(communityUser => communityUser.communityMembership === 'member')!,
+    );
+  };
+
+  return createEventSubscriber(
+    client,
+    'onLocalCommunityRoleRemoved',
+    'local.community.roleRemoved',
+    filter,
+  );
+};

package/src/communityRepository/observers/getCommunities/CommunitiesLiveCollectionController.ts

@@ -136,11 +136,11 @@ export class CommunityLiveCollectionController extends LiveCollectionController<
     if (!this.query.displayName) {
       const sortFn = (() => {
         switch (this.query.sortBy) {
-          case Amity.CommunitySortByEnum.FirstCreated:
+          case 'firstCreated':
             return sortByFirstCreated;
-          case Amity.CommunitySortByEnum.LastCreated:
+          case 'lastCreated':
             return sortByLastCreated;
-          case Amity.CommunitySortByEnum.DisplayName:
+          case 'displayName':
             return sortByDisplayName;
           default:
             return sortByLastCreated;

package/src/communityRepository/utils/payload.ts

@@ -53,6 +53,35 @@ export const prepareCommunityPayload = (
   };
 };
 
+export const prepareCommunityMembershipPayload = (
+  rawPayload: Amity.CommunityMembershipPayload,
+): Amity.ProcessedCommunityMembershipPayload => {
+  const communitiesWithPostSetting = addPostSetting({ communities: rawPayload.communities });
+
+  // map users with community
+  const mappedCommunityUsers: Array<Amity.Membership<'community'>> = rawPayload.communityUsers.map(
+    communityUser => {
+      const user = rawPayload.users.find(user => user.userId === communityUser.userId)!;
+
+      return {
+        ...communityUser,
+        user,
+      };
+    },
+  );
+
+  const communityWithMembershipStatus = updateMembershipStatus(
+    communitiesWithPostSetting,
+    mappedCommunityUsers,
+  );
+
+  return {
+    ...rawPayload,
+    communities: communityWithMembershipStatus,
+    communityUsers: mappedCommunityUsers,
+  };
+};
+
 export const prepareCommunityRequest = <
   T extends {
     postSetting?: Amity.Community['postSetting'];

package/src/core/model/idResolvers.ts

@@ -57,7 +57,7 @@ const idResolvers: Resolvers = {
   ad: ({ adId }) => adId,
   advertiser: ({ advertiserId }) => advertiserId,
 
-  pin: ({ referenceId }) => referenceId,
+  pin: ({ placement, referenceId }) => `${placement}#${referenceId}`,
   pinTarget: ({ targetId }) => targetId,
 };
 

package/src/postRepository/api/deletePost.ts

@@ -71,7 +71,15 @@ export const deletePost = async (
   // to support hard deletion
   const deleted = { ...post.data, isDeleted: true };
 
-  fireEvent('post.deleted', {
+  if (permanent) {
+    setTimeout(() => {
+      pushToTombstone('post', postId);
+    }, 0);
+  } else {
+    upsertInCache(['post', 'get', postId], { isDeleted: true });
+  }
+
+  fireEvent('local.post.deleted', {
     posts: [deleted],
     categories: [],
     comments: [],
@@ -83,13 +91,5 @@ export const deletePost = async (
     users: [],
   });
 
-  if (permanent) {
-    setTimeout(() => {
-      pushToTombstone('post', postId);
-    }, 0);
-  } else {
-    upsertInCache(['post', 'get', postId], { isDeleted: true });
-  }
-
   return LinkedObject.post(deleted);
 };

package/src/postRepository/api/updatePost.ts

@@ -51,7 +51,7 @@ export const updatePost = async <T extends Amity.PostContentType>(
   const cachedAt = client.cache && Date.now();
   if (client.cache) ingestInCache(data, { cachedAt });
 
-  fireEvent('local.post.updated', data);
+  fireEvent('local.post.updated', payload);
 
   const { posts } = data;
 

package/src/postRepository/events/onLocalPostDeleted.ts

@@ -0,0 +1,20 @@
+import { createLocalPostEventSubscriber, createPostEventSubscriber } from './utils';
+
+/**
+ * ```js
+ * import { onLocalPostDeleted } from '@amityco/ts-sdk'
+ * const dispose = onLocalPostDeleted(post => {
+ *   // ...
+ * })
+ * ```
+ *
+ * Fired when a {@link Amity.InternalPost} has been deleted
+ *
+ * @param callback The function to call when the event was fired
+ * @returns an {@link Amity.Unsubscriber} function to stop listening
+ *
+ * @category Post Events
+ */
+export const onLocalPostDeleted = (
+  callback: Amity.Listener<Amity.InternalPost>,
+): Amity.Unsubscriber => createLocalPostEventSubscriber('local.post.deleted', callback);

package/src/postRepository/events/onLocalPostReactionAdded.ts

@@ -0,0 +1,38 @@
+import { getActiveClient } from '~/client/api';
+import { pullFromCache, upsertInCache } from '~/cache/api';
+import { ingestInCache } from '~/cache/api/ingestInCache';
+import { createEventSubscriber } from '~/core/events';
+import { preparePostPayload } from '../utils/payload';
+
+/**
+ * ```js
+ * import { onLocalPostReactionAdded } from '@amityco/ts-sdk'
+ * const dispose = onPostReactionAdded(post => {
+ *   // ...
+ * })
+ * ```
+ *
+ * Fired when a {@link Amity.InternalPost} has been reacted
+ *
+ * @param callback The function to call when the event was fired
+ * @returns an {@link Amity.Unsubscriber} function to stop listening
+ *
+ * @category Post Events
+ */
+export const onLocalPostReactionAdded = (
+  callback: Amity.Listener<Amity.InternalPost>,
+): Amity.Unsubscriber => {
+  const client = getActiveClient();
+
+  const filter = ({ post }: Amity.Events['local.post.addReaction']) => {
+    if (!client.cache) {
+      callback(post);
+    } else {
+      upsertInCache(['post', 'get', post.postId], post);
+
+      callback(post);
+    }
+  };
+
+  return createEventSubscriber(client, 'local.post.addReaction', 'local.post.addReaction', filter);
+};

package/src/postRepository/events/onLocalPostReactionRemoved.ts

@@ -0,0 +1,41 @@
+import { getActiveClient } from '~/client/api';
+import { pullFromCache, upsertInCache } from '~/cache/api';
+import { createEventSubscriber } from '~/core/events';
+
+/**
+ * ```js
+ * import { onLocalPostReactionRemoved } from '@amityco/ts-sdk'
+ * const dispose = onPostReactionRemoved(post => {
+ *   // ...
+ * })
+ * ```
+ *
+ * Fired when a {@link Amity.InternalPost} has been reacted
+ *
+ * @param callback The function to call when the event was fired
+ * @returns an {@link Amity.Unsubscriber} function to stop listening
+ *
+ * @category Post Events
+ */
+export const onLocalPostReactionRemoved = (
+  callback: Amity.Listener<Amity.InternalPost>,
+): Amity.Unsubscriber => {
+  const client = getActiveClient();
+
+  const filter = ({ post }: Amity.Events['local.post.removeReaction']) => {
+    if (!client.cache) {
+      callback(post);
+    } else {
+      upsertInCache(['post', 'get', post.postId], post);
+
+      callback(post);
+    }
+  };
+
+  return createEventSubscriber(
+    client,
+    'local.post.removeReaction',
+    'local.post.removeReaction',
+    filter,
+  );
+};

package/src/postRepository/events/onPostUpdatedLocal.ts

@@ -0,0 +1,20 @@
+import { createLocalPostEventSubscriber } from './utils';
+
+/**
+ * ```js
+ * import { onPostUpdatedLocal } from '@amityco/ts-sdk'
+ * const dispose = onPostUpdatedLocal(post => {
+ *   // ...
+ * })
+ * ```
+ *
+ * Fired when a {@link Amity.InternalPost} has been updated
+ *
+ * @param callback The function to call when the event was fired
+ * @returns an {@link Amity.Unsubscriber} function to stop listening
+ *
+ * @category Post Events
+ */
+export const onPostUpdatedLocal = (
+  callback: Amity.Listener<Amity.InternalPost>,
+): Amity.Unsubscriber => createLocalPostEventSubscriber('local.post.updated', callback);

package/src/postRepository/events/utils.ts

@@ -1,10 +1,9 @@
 import { getActiveClient } from '~/client/api';
 import { ingestInCache } from '~/cache/api/ingestInCache';
 import { createEventSubscriber, fireEvent } from '~/core/events';
-import { pullFromCache, queryCache, upsertInCache } from '~/cache/api';
-import { pushToTombstone } from '~/cache/api/pushToTombstone';
-import { prepareMembershipPayload } from '~/group/utils';
+import { dropFromCache, pullFromCache, queryCache, upsertInCache } from '~/cache/api';
 import { isInTombstone } from '~/cache/api/isInTombstone';
+import { preparePostPayload } from '~/postRepository/utils/payload';
 
 export const createPostEventSubscriber = (
   event: keyof Amity.MqttPostEvents,
@@ -16,9 +15,9 @@ export const createPostEventSubscriber = (
     if (!client.cache) {
       callback(payload.posts[0]);
     } else {
-      const { communities, ...others } = payload;
+      const data = preparePostPayload(payload);
 
-      const data = prepareMembershipPayload(others, 'communityUsers');
+      const { communities } = data;
 
       ingestInCache(data);
 
@@ -49,7 +48,7 @@ export const createPostEventSubscriber = (
         // But if it is hard delete, it will pushed into tombstone before fire an event to BE. it means it will stay in tombstone already
         // and will got skip to notify in a previous code block
         if (postedUserId !== client.userId) {
-          pushToTombstone('post', postId);
+          dropFromCache(['post', 'get', postId]);
         }
 
         return callback(payload.posts[0]);
@@ -76,3 +75,39 @@ export const createPostEventSubscriber = (
 
   return createEventSubscriber(client, event, event, filter);
 };
+
+export const createLocalPostEventSubscriber = (
+  event: keyof Omit<Amity.LocalPostEvents, 'local.post.addReaction' | 'local.post.removeReaction'>,
+  callback: Amity.Listener<Amity.InternalPost>,
+) => {
+  const client = getActiveClient();
+
+  const filter = (payload: Amity.PostPayload) => {
+    if (!client.cache) {
+      callback(payload.posts[0]);
+    } else {
+      const data = preparePostPayload(payload);
+
+      const { communities } = data;
+
+      ingestInCache(data);
+
+      if (communities?.[0] && !['local.post.updated'].includes(event)) {
+        fireEvent('community.updated', {
+          communities,
+          categories: [],
+          communityUsers: data.communityUsers,
+          feeds: [],
+          files: [],
+          users: [],
+        });
+      }
+
+      const post = pullFromCache<Amity.InternalPost>(['post', 'get', payload.posts[0].postId])!;
+
+      callback(post.data);
+    }
+  };
+
+  return createEventSubscriber(client, event, event, filter);
+};

package/src/postRepository/internalApi/index.ts

@@ -1,16 +1 @@
-export * from './getPostByIds';
-
-export * from './createPost';
-export * from './updatePost';
-export * from './editPost';
-
-export * from './deletePost';
-export * from './softDeletePost';
-export * from './hardDeletePost';
-
-export * from './approvePost';
-export * from './declinePost';
-
-export * from './flagPost';
-export * from './unflagPost';
-export * from './isPostFlaggedByMe';
+export * from './getPost';

package/src/postRepository/observers/getPost.ts

@@ -15,6 +15,10 @@ import { pullFromCache, pushToCache } from '~/cache/api';
 import { LinkedObject } from '~/utils/linkedObject';
 import { onCommentCreated, onCommentDeleted } from '~/commentRepository';
 import { convertEventPayload } from '~/utils/event';
+import { onPostUpdatedLocal } from '~/postRepository/events/onPostUpdatedLocal';
+import { onLocalPostReactionAdded } from '~/postRepository/events/onLocalPostReactionAdded';
+import { onLocalPostReactionRemoved } from '~/postRepository/events/onLocalPostReactionRemoved';
+import { onLocalPostDeleted } from '~/postRepository/events/onLocalPostDeleted';
 
 /* begin_public_function
   id: post.get
@@ -52,6 +56,8 @@ export const getPost = (
   return liveObject(postId, responder, 'postId', _getPost, [
     onPostApproved,
     onPostDeclined,
+    onLocalPostReactionAdded,
+    onLocalPostReactionRemoved,
     (callback: Amity.Listener<Amity.InternalPost>) => {
       return onPostDeleted((post: Amity.InternalPost) => {
         let targetPost = post;
@@ -89,6 +95,8 @@ export const getPost = (
     },
     onPostUnflagged,
     onPostUpdated,
+    onPostUpdatedLocal,
+    onLocalPostDeleted,
     convertEventPayload(
       (callback: Amity.Listener<Amity.InternalComment>) => {
         return onCommentCreated(async (comment: Amity.InternalComment) => {

package/src/postRepository/observers/getPosts/PostLiveCollectionController.ts

@@ -28,6 +28,10 @@ import { preparePostPayload } from '~/postRepository/utils/payload';
 import { convertEventPayload } from '~/utils/event';
 import { onCommentCreated, onCommentDeleted } from '~/commentRepository';
 import { getPost } from '~/postRepository/internalApi/getPost';
+import { onPostUpdatedLocal } from '~/postRepository/events/onPostUpdatedLocal';
+import { onLocalPostReactionAdded } from '~/postRepository/events/onLocalPostReactionAdded';
+import { onLocalPostReactionRemoved } from '~/postRepository/events/onLocalPostReactionRemoved';
+import { onLocalPostDeleted } from '~/postRepository/events/onLocalPostDeleted';
 
 export class PostLiveCollectionController extends LiveCollectionController<
   'post',
@@ -84,6 +88,7 @@ export class PostLiveCollectionController extends LiveCollectionController<
     return this.queryStreamController.subscribeRTE([
       { fn: onPostCreated, action: EnumPostActions.OnPostCreated },
       { fn: onPostUpdated, action: EnumPostActions.OnPostUpdated },
+      { fn: onPostUpdatedLocal, action: EnumPostActions.OnPostUpdated },
       { fn: onPostDeleted, action: EnumPostActions.OnPostDeleted },
       { fn: onPostFlagged, action: EnumPostActions.OnPostFlagged },
       { fn: onPostUnflagged, action: EnumPostActions.OnPostUnflagged },
@@ -91,6 +96,9 @@ export class PostLiveCollectionController extends LiveCollectionController<
       { fn: onPostDeclined, action: EnumPostActions.OnPostDeclined },
       { fn: onPostReactionAdded, action: EnumPostActions.OnPostReactionAdded },
       { fn: onPostReactionRemoved, action: EnumPostActions.OnPostReactionRemoved },
+      { fn: onLocalPostReactionAdded, action: EnumPostActions.OnPostReactionAdded },
+      { fn: onLocalPostReactionRemoved, action: EnumPostActions.OnPostReactionRemoved },
+      { fn: onLocalPostDeleted, action: EnumPostActions.OnPostDeleted },
       {
         fn: convertEventPayload(
           (callback: Amity.Listener<Amity.InternalComment>) => {

package/src/postRepository/utils/payload.ts

@@ -2,8 +2,6 @@ import { addPostSetting } from '~/communityRepository/utils';
 import { updateMembershipStatus } from '~/communityRepository/utils/communityWithMembership';
 
 export const preparePostPayload = (postPayload: Amity.PostPayload): Amity.ProcessedPostPayload => {
-  const { posts } = postPayload;
-
   // Unpack community payload by mapping payload field to postSetting value.
   const communitiesWithPostSetting = addPostSetting({ communities: postPayload.communities });
 
@@ -24,6 +22,16 @@ export const preparePostPayload = (postPayload: Amity.PostPayload): Amity.Proces
     mappedCommunityUsers,
   );
 
+  // feed type
+  const posts = postPayload.posts.map(post => {
+    const feedType = postPayload.feeds.find(feed => feed.feedId === post.feedId)?.feedType;
+
+    return {
+      ...post,
+      feedType,
+    };
+  });
+
   return {
     ...postPayload,
     posts,

package/src/reactionRepository/api/addReaction.ts

@@ -4,6 +4,7 @@ import { upsertInCache, pullFromCache, pushToCache } from '~/cache/api';
 
 import { UNSYNCED_OBJECT_CACHED_AT_VALUE } from '~/utils/constants';
 import { dispatchReactable } from '../utils';
+import { fireEvent } from '~/core/events';
 
 /* begin_public_function
   id: reaction.add
@@ -50,8 +51,32 @@ export const addReaction = async (
       referenceId,
     ]);
 
-    model?.data &&
-      pushToCache([referenceType, 'get', referenceId], model.data, { cachedAt: Date.now() });
+    if (!model) return true;
+
+    const updatedModel = {
+      ...model.data,
+      reactionsCount: model.data.reactionsCount + 1,
+      myReactions: [...(model.data.myReactions ?? []), reactionName],
+      reactions: {
+        ...model.data.reactions,
+        [reactionName]: (model.data.reactions[reactionName] ?? 0) + 1,
+      },
+    } as Amity.Models[Amity.ReactableType];
+
+    if (referenceType === 'comment') {
+      fireEvent('local.comment.addReaction', {
+        comment: updatedModel as Amity.InternalComment,
+      });
+
+      return true;
+    }
+    if (referenceType === 'post') {
+      fireEvent('local.post.addReaction', {
+        post: updatedModel as Amity.InternalPost,
+      });
+
+      return true;
+    }
   }
 
   return true;

package/src/reactionRepository/api/removeReaction.ts

@@ -5,6 +5,7 @@ import { upsertInCache, pullFromCache, pushToCache } from '~/cache/api';
 import { UNSYNCED_OBJECT_CACHED_AT_VALUE } from '~/utils/constants';
 
 import { dispatchReactable } from '../utils';
+import { fireEvent } from '~/core/events';
 
 /* begin_public_function
   id: reaction.remove
@@ -53,8 +54,32 @@ export const removeReaction = async (
       referenceId,
     ]);
 
-    model?.data &&
-      pushToCache([referenceType, 'get', referenceId], model.data, { cachedAt: Date.now() });
+    if (!model) return true;
+
+    const updatedModel = {
+      ...model.data,
+      reactionsCount: Math.max(0, model.data.reactionsCount - 1),
+      myReactions: (model.data.myReactions ?? []).filter(item => item !== reactionName),
+      reactions: {
+        ...model.data.reactions,
+        [reactionName]: Math.max(0, (model.data.reactions[reactionName] ?? 0) - 1),
+      },
+    } as Amity.Models[Amity.ReactableType];
+
+    if (referenceType === 'comment') {
+      fireEvent('local.comment.removeReaction', {
+        comment: updatedModel as Amity.InternalComment,
+      });
+
+      return true;
+    }
+    if (referenceType === 'post') {
+      fireEvent('local.post.removeReaction', {
+        post: updatedModel as Amity.InternalPost,
+      });
+
+      return true;
+    }
   }
 
   return true;

package/src/report/api/createReport.ts

@@ -4,7 +4,7 @@ import { ingestInCache } from '~/cache/api/ingestInCache';
 import { fireEvent } from '~/core/events';
 import { prepareMessagePayload } from '~/messageRepository/utils';
 import { preparePostPayload } from '~/postRepository/utils/payload';
-import { prepareUserPayload } from '~/userRepository/utils';
+import { prepareUserPayload } from '~/userRepository/utils/prepareUserPayload';
 import { prepareCommentPayload } from '~/commentRepository/utils/payload';
 
 const createMessageReport = async ({

package/src/report/api/deleteReport.ts

@@ -5,7 +5,7 @@ import { ingestInCache } from '~/cache/api/ingestInCache';
 import { fireEvent } from '~/core/events';
 import { prepareMessagePayload } from '~/messageRepository/utils';
 import { preparePostPayload } from '~/postRepository/utils/payload';
-import { prepareUserPayload } from '~/userRepository/utils';
+import { prepareUserPayload } from '~/userRepository/utils/prepareUserPayload';
 import { prepareCommentPayload } from '~/commentRepository/utils/payload';
 
 const deleteMessageReport = async ({

package/src/userRepository/api/flagUser.ts

@@ -2,7 +2,7 @@ import { getActiveClient } from '~/client/api/activeClient';
 
 import { ingestInCache } from '~/cache/api/ingestInCache';
 import { fireEvent } from '~/core/events';
-import { prepareUserPayload } from '../utils';
+import { prepareUserPayload } from '~/userRepository/utils/prepareUserPayload';
 
 /* begin_public_function
   id: user.flag

package/src/userRepository/api/getUserByIds.ts

@@ -4,7 +4,7 @@ import { pullFromCache } from '~/cache/api';
 import { ingestInCache } from '~/cache/api/ingestInCache';
 import { fireEvent } from '~/core/events';
 import { LinkedObject } from '~/utils/linkedObject';
-import { prepareUserPayload } from '../utils';
+import { prepareUserPayload } from '~/userRepository/utils/prepareUserPayload';
 
 /* begin_public_function
   id: user.get_by_ids

package/src/userRepository/api/queryBlockedUsers.ts

@@ -3,7 +3,7 @@ import { ingestInCache } from '~/cache/api/ingestInCache';
 import { pullFromCache, pushToCache } from '~/cache/api';
 import { getResolver } from '~/core/model';
 import { toPageRaw } from '~/core/query';
-import { prepareUserPayload } from '../utils';
+import { prepareUserPayload } from '~/userRepository/utils/prepareUserPayload';
 
 /**
  * ```js

package/src/userRepository/api/unflagUser.ts

@@ -2,7 +2,7 @@ import { getActiveClient } from '~/client/api/activeClient';
 
 import { ingestInCache } from '~/cache/api/ingestInCache';
 import { fireEvent } from '~/core/events';
-import { prepareUserPayload } from '../utils';
+import { prepareUserPayload } from '~/userRepository/utils/prepareUserPayload';
 
 /* begin_public_function
   id: user.unflag

package/src/userRepository/api/updateUser.ts

@@ -2,7 +2,7 @@ import { getActiveClient } from '~/client/api';
 
 import { fireEvent } from '~/core/events';
 import { ingestInCache } from '~/cache/api/ingestInCache';
-import { prepareUserPayload } from '../utils';
+import { prepareUserPayload } from '~/userRepository/utils/prepareUserPayload';
 
 /* begin_public_function
   id: client.update_user

package/src/userRepository/events/utils.ts

@@ -2,7 +2,7 @@ import { getActiveClient } from '~/client/api/activeClient';
 import { createEventSubscriber } from '~/core/events';
 
 import { ingestInCache } from '~/cache/api/ingestInCache';
-import { prepareUserPayload } from '../utils';
+import { prepareUserPayload } from '../utils/prepareUserPayload';
 
 export const createUserEventSubscriber = (
   event: keyof Amity.MqttUserEvents,

package/src/userRepository/internalApi/getUser.ts

@@ -7,7 +7,7 @@ import { fireEvent } from '~/core/events';
 import { isInTombstone } from '~/cache/api/isInTombstone';
 import { checkIfShouldGoesToTombstone } from '~/cache/utils';
 import { pushToTombstone } from '~/cache/api/pushToTombstone';
-import { prepareUserPayload } from '../utils';
+import { prepareUserPayload } from '~/userRepository/utils/prepareUserPayload';
 
 /**
  * ```js

package/src/userRepository/internalApi/queryUsers.ts

@@ -4,7 +4,7 @@ import { pullFromCache, pushToCache } from '~/cache/api';
 import { ingestInCache } from '~/cache/api/ingestInCache';
 import { getResolver } from '~/core/model';
 import { fireEvent } from '~/core/events';
-import { prepareUserPayload } from '../utils';
+import { prepareUserPayload } from '~/userRepository/utils/prepareUserPayload';
 
 /**
  * ```js