@akoskovacs/keyed-list v1.2.0

keyed-list.ts

Efficiently store and retreive list elements based on their id key. This approach has the same benefits as having both an array and a hash for the same list.

With the array we can simply iterate through the elements or use them by their index. And with the hash, we can efficiently retrieve them, just by the id. Although, this implementation will only store the ids in the array to conserve space. But, this mechanism is completely transparent, the user don't have to think about it.

The immutability makes this library easy to use with React or other functional libraries and is also less error-prone.

Installation

The preferred way is to add it to the project locally as a dependency:

npm install --save @akoskovacs/keyed-list

Or via yarn:

yarn add @akoskovacs/keyed-list

Usage

The list element must include a unqiue id property. The id can be a GUID given by an API. It then can be used to efficiently address the elements. Take this example:

import keyedList from '@akoskovacs/keyed-list';

interface PostItem {
  id: string;
  author: string;
  content: string;
  createdAt: Date;
};

const posts: PostItem[] = [
  {
    id: '1234',
    author: 'John',
    votes: 4,
    content: 'Hello, world!',
    createdAt: new Date('2020-12-11 10:45:21')
  },
  {
    id: '2222',
    author: 'Steve',
    votes: 0,
    content: 'Second post',
    createdAt: new Date('2020-12-11 14:12:55')
  },
  {
    id: '4242',
    author: 'Peter',
    votes: 2,
    content: 'This is not the end',
    createdAt: new Date('2020-12-11 14:12:55')
  }
];

After the API gave back the elements the library can start manipulating the data, with the following functions:

A more complete example with React

Posts.tsx:

/* ... API handlers ...*/

type PostItemList = keyedList.IdKeyedList<PostItem>;

const Posts = () => {
  const [posts, setPosts] = React.useState<PostItemList>(keyedList.fromArray());
  const [isInitialized, setIsInitialized] = React.useState<boolean>(false);

  React.useEffect(() => {
    if (!isInitialized) {
      if (!initialPosts) {
        fetchAllPosts();
      }
      setIsInitialized(true);
    } else {
      fetchAllPosts();
    }
  }, []);

  const fetchAllPosts = () => {
    // fetchPosts does a GET request to load all posts into an array, then those are converted into a list
    fetchPosts(cs => setPosts(keyedList.fromArray(cs)));
  };

  const submitPost = () => {
    // savePost does the POST request for creating a new post, the new item then can be inserted to the list
    savePost(content, (c) => {
      setPosts(keyedList.insert(posts, c));
      setContent("");
    });
    return true;
  };

  const setPostContent = (id: string, content: string) => {
    // When the content is edited, the new content is updated through this call
    setPosts(keyedList.update(posts, { id, content }));
    return true;
  };

  const voteOnPost = (id: string) => {
    // When the post is voted on, the request will give back the number of all votes, so we can show it to the users
    votePost(id, (votes) => {
      setPosts(keyedList.update(posts, { id, vote: votes }));
    });
  };

  const doDelete = (id: string) => {
    if (confirm('Are you sure to delete this post?')) {
      setPosts(keyedList.removeById(posts, id));
    }
  };

  return (
    <>
      {
        keyedList.mapIds(id =>
          <Post
            id={ id }
            key={ id }
            editContent={ setPostContent }
            getById={ id => keyedList.getById(posts, id) }
            onVote={ id => voteOnPost }
            onDelete={ doDelete } />
        )
      }
    </>
  );
};

export default Posts;

Post.tsx:

interface PostProps {
  id: Uuid;
  onEditContent?: (id: string, content: string) => void;
  onVote?: (id: string) => void;
  onDelete?: (id: string) => void;
  getById?: (id: string) => PostItem;
}


export const Post = ({ id, getById, setContent, onDelete }: PostProps) => {
  const post = (id && getById) ? getById(id) : undefined;

  if (!post)
    return undefined;

  return (
    <div className="post">
      <p><em>Posted by { post.author }</em></p>
      {
        onVote &&
          <button className="vote" onClick={ () => onVote(id) } />
      }
      <p className="post-content">
        { post.content }
      </p>
      {
        onEditContent &&
        /* create and editor for the content and call onEditContent when done */
      }
      {
        onDelete &&
          <button className="delete" onClick={ () => onDelete(id) } />
      }
    </div>
  );
};