Batshit Batch Manager

To use @yornaath/batshit, initialize a Batcher by providing a fetcher function, a resolver, and an optional scheduler. The Batcher deduplicates and batches requests made within a specific time window into a single call.

• fetcher: An async function that receives an array of keys and returns the batched data.
• resolver: Uses keyResolver to identify how to extract unique keys from the data or how to map requests to results.
• scheduler: Uses windowScheduler(ms) to define the time window for batching. If omitted, it defaults to a window of 10ms.

This is ideal for reducing network overhead when multiple components or functions request data simultaneously.

import { Batcher, keyResolver, windowScheduler } from "@yornaath/batshit";

type User = { id: number; name: string };

const users = Batcher<User, number>({
  fetcher: async (ids) => {
    // ids is an array of the keys requested
    return client.users.where({
      userId_in: ids,
    });
  },
  resolver: keyResolver("id"),
  scheduler: windowScheduler(10), // Default and can be omitted.
});

// Requests made within the 10ms window will be batched into one call
const bob = users.fetch(1);
const alice = users.fetch(2);

const [bobData, aliceData] = await Promise.all([bob, alice]);

You can use a batcher inside react-query (or @tanstack/react-query) to deduplicate requests from multiple components.

Important: A batcher for a group of items should be created once (e.g., at the module level). Do not create batchers inside hooks, as this will prevent batching across different component instances.

import { useQuery } from "react-query";
import { create, keyResolver, windowScheduler } from "@yornaath/batshit";

const users = create({
  fetcher: async (ids: number[]) => {
    return client.users.where({
      userId_in: ids,
    });
  },
  resolver: keyResolver("id"),
  scheduler: windowScheduler(10),
});

const useUser = (id: number) => {
  return useQuery(["users", id], async () => {
    return users.fetch(id);
  });
};

const UserDetails = (props: { userId: number }) => {
  const { isFetching, data } = useUser(props.userId);
  return (
    <>
      {isFetching ? (
        <div>Loading user {props.userId}</div>
      ) : (
        <div>User: {data.name}</div>
      )}
    </>
  );
};

const UserList = () => {
  const userIds = [1, 2, 3, 4];
  return (
    <>
      {userIds.map((id) => (
        <UserDetails key={id} userId={id} />
      ))}
    </>
  );
    </>
  );
};

You can use @yornaath/batshit inside react-query to prevent a 'waterfall' of network requests when multiple components render at once. By wrapping the users.fetch(id) call inside a useQuery hook, all components requesting user data within the same 10ms window will trigger only one batch request instead of individual network calls.

import { useQuery } from "react-query";
import { Batcher, keyResolver, windowScheduler } from "@yornaath/batshit";

const users = Batcher<User, number>({
  fetcher: async (ids) => {
    return client.users.where({
      userId_in: ids,
    });
  },
  resolver: keyResolver("id"),
  scheduler: windowScheduler(10),
});

const useUser = (id: number) => {
  return useQuery(["users", id], async () => {
    return users.fetch(id);
  });
};

const UserDetails = (props: { userId: number }) => {
  const { isFetching, data } = useUser(props.userId);
  return (
    <>
      {isFetching ? (
        <div>Loading user {props.userId}</div>
      ) : (
        <div>User: {data.name}</div>
      )}
    </>
  );
};

const UserList = () => {
  const userIds = [1, 2, 3, 4];
  return (
    <>
      {userIds.map((id) => (
        <UserDetails key={id} userId={id} />
      ))}
    </>
  );
};

When your fetcher returns a flat list of items that doesn't map 1:1 to the requested keys (e.g., fetching posts for multiple authors), you can provide a custom resolver function.

The resolver signature is: (results, query) => T.

• results: The array of data returned by the fetcher.
• query: The specific query object passed to .fetch().

This allows you to filter the bulk results to return only the data relevant to the specific caller.

// Example: Fetching posts for multiple authors in one request
const userposts = Batcher<{ authorId: number, content: string }, { authorId: number }, any[]>({
  fetcher: async (queries) => {
    // queries is an array of the objects passed to .fetch()
    return api.posts.where({
      authorId_in: queries.map((q) => q.authorId),
    });
  },
  scheduler: windowScheduler(10),
  // The resolver filters the bulk 'posts' list for the specific 'query' requested
  resolver: (posts, query) =>
    posts.filter((post) => post.authorId === query.authorId),
});

// These two calls will be batched into one API request
const [alicesPosts, bobsPosts] = await Promise.all([
  userposts.fetch({ authorId: 1 }),
  userposts.fetch({ authorId: 2 }),
]);