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:

Function name	Description	Example
fromArray	Create a list from an array	const list = keyedList.fromArray(posts);
toArray	Converts the list back into an array	const newPosts = keyedList.toArray(list);
getIds	Retrieve multiple elements by their ids	const ids = keyedList.getIds(list);
getById	Retrieve the element by its id	const steve = keyedList.getById(list, '2222');
getByIds	Converts the list back into an array	const sp = keyedList.getByIds(list, ['4242, '2222']);
getIdByIndex	Retrieve the id by the element's numeric index	const firstId = keyedList.getIdByIndex(list, 0);
getFirst	Gets the first element in the list	const first = keyedList.getFirst(list);
getLast	Gets the last elemenet in the list	const last = keyedList.getLast(list);
getByIndex	Gets the element by its index	const second = keyedList.getByIndex(list, 1);
getCount	Get the length of the list	const count = keyedList.getCount(list);
update	Update properties of given list element	const newList = keyedList.update(list, { id: '4242', votes: 1 });
append	Adds a new element to the end the list	const newList = keyedList.append(list, { id: '5200', author: 'Riley' /* ... */});
insert	Insert a new element to the beginning of the list	const newList = keyedList.insert(list, { id: '5200', author: 'Riley' /* ... */});
removeById	Removes an element by its id	const newList = keyedList.removeById(list, '2222');
map	Iterates through the list elements	const nameArray = keyedList.map(list, p => p.author);
mapIds	Iterates through the ids of the list	const ids = keyedList.mapIds(list, id => id);
filter	Filters out elements which stasify a given condition	const nonZeroVotes = keyedList.filter(list, p => p.votes > 0);
sort	Sorts the array, by a given comparison function	const sortedList = keyedList.sort(list, (left, right) => left.votes - right.votes);

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>
  );
};