batchkit 0.1.0

package/README.md

@@ -0,0 +1,267 @@
+# batchkit
+
+Automatic batching for async operations.
+
+## Installation
+
+```bash
+npm install batchkit
+# or
+bun add batchkit
+```
+
+## Quick Start
+
+```typescript
+import { batch } from 'batchkit'
+
+const users = batch(
+  (ids) => db.users.findMany({ where: { id: { in: ids } } }),
+  'id'
+)
+
+// These calls are automatically batched into ONE database query
+const [alice, bob] = await Promise.all([
+  users.get(1),
+  users.get(2),
+])
+```
+
+That's it. Two arguments:
+1. A function that fetches many items at once
+2. The field to match results by
+
+## API
+
+### `batch(fn, match, options?)`
+
+Creates a batcher.
+
+```typescript
+const users = batch(
+  // The batch function - receives keys and an AbortSignal
+  async (ids: number[], signal: AbortSignal) => {
+    return api.getUsers(ids, { signal })
+  },
+  // How to match results - just the field name
+  'id',
+  // Optional configuration
+  {
+    wait: 10,       // ms to wait before dispatch (default: 0 = microtask)
+    max: 100,       // max batch size
+    name: 'users',  // for debugging
+  }
+)
+```
+
+### `batcher.get(key)` / `batcher.get(keys)`
+
+Get one or many items:
+
+```typescript
+// Single item
+const user = await users.get(1)
+
+// Multiple items (batched together)
+const [a, b] = await Promise.all([users.get(1), users.get(2)])
+
+// Array syntax
+const team = await users.get([1, 2, 3, 4, 5])
+```
+
+### `batcher.get(key, { signal })`
+
+Cancel a request:
+
+```typescript
+const controller = new AbortController()
+const user = await users.get(1, { signal: controller.signal })
+
+// Later...
+controller.abort() // Rejects with AbortError
+```
+
+### `batcher.flush()`
+
+Execute pending batch immediately:
+
+```typescript
+users.get(1)
+users.get(2)
+await users.flush() // Don't wait for scheduler
+```
+
+### `batcher.abort()`
+
+Abort the in-flight batch:
+
+```typescript
+users.abort() // All pending requests reject with AbortError
+```
+
+## Matching Results
+
+### By Field Name (most common)
+
+```typescript
+batch(fn, 'id')
+// Matches results where result.id === requestedKey
+```
+
+### For Record/Object Responses
+
+```typescript
+import { batch, indexed } from 'batchkit'
+
+const users = batch(
+  async (ids) => {
+    // Returns { "1": {...}, "2": {...} }
+    return fetchUsersAsRecord(ids)
+  },
+  indexed
+)
+```
+
+### Custom Matching
+
+```typescript
+batch(
+  fn,
+  (results, key) => results.find(r => r.externalId === key)
+)
+```
+
+## Scheduling
+
+### Default: Microtask
+
+Batches all calls within the same event loop tick:
+
+```typescript
+const users = batch(fn, 'id')
+
+// All batched into ONE request
+users.get(1)
+users.get(2)
+users.get(3)
+```
+
+### Delayed
+
+Wait before dispatching:
+
+```typescript
+batch(fn, 'id', { wait: 10 }) // 10ms window
+```
+
+### Animation Frame
+
+Sync with rendering:
+
+```typescript
+import { batch, onAnimationFrame } from 'batchkit'
+
+batch(fn, 'id', { schedule: onAnimationFrame })
+```
+
+### Idle
+
+Background/low-priority work:
+
+```typescript
+import { batch, onIdle } from 'batchkit'
+
+batch(fn, 'id', { schedule: onIdle({ timeout: 100 }) })
+```
+
+## Deduplication
+
+Duplicate keys in the same batch are automatically deduplicated:
+
+```typescript
+// Only ONE request for id=1
+await Promise.all([
+  users.get(1),
+  users.get(1),
+  users.get(1),
+])
+```
+
+For complex keys, provide a key function:
+
+```typescript
+batch(fn, match, {
+  key: (query) => query.id  // Dedupe by query.id
+})
+```
+
+## Tracing
+
+Debug batch behavior:
+
+```typescript
+batch(fn, 'id', {
+  name: 'users',
+  trace: (event) => {
+    console.log(event.type, event)
+    // 'get', 'schedule', 'dispatch', 'resolve', 'error', 'abort'
+  }
+})
+```
+
+## Examples
+
+### React + TanStack Query
+
+```typescript
+import { batch } from 'batchkit'
+import { useQuery } from '@tanstack/react-query'
+
+const users = batch(
+  (ids, signal) => fetch(`/api/users?ids=${ids.join(',')}`, { signal }).then(r => r.json()),
+  'id'
+)
+
+function UserAvatar({ userId }: { userId: string }) {
+  const { data } = useQuery({
+    queryKey: ['user', userId],
+    queryFn: ({ signal }) => users.get(userId, { signal })
+  })
+  
+  return <img src={data?.avatar} />
+}
+
+// Rendering 100 UserAvatars = 1 HTTP request
+```
+
+### API with Rate Limits
+
+```typescript
+const products = batch(
+  (ids) => shopify.products.list({ ids }),
+  'id',
+  { max: 50 }  // Shopify's limit
+)
+
+// 200 product requests = 4 API calls (50 each)
+```
+
+## TypeScript
+
+Full type inference:
+
+```typescript
+type User = { id: number; name: string }
+
+const users = batch(
+  async (ids: number[]): Promise<User[]> => fetchUsers(ids),
+  'id'
+)
+
+const user = await users.get(1) // user: User
+const many = await users.get([1, 2]) // many: User[]
+```
+
+## License
+
+MIT

package/dist/batch.d.ts

@@ -0,0 +1,3 @@
+import type { Batcher, BatchFn, BatchOptions, Match } from './types';
+export declare function batch<K, V>(fn: BatchFn<K, V>, match: Match<K, V>, options?: BatchOptions<K>): Batcher<K, V>;
+//# sourceMappingURL=batch.d.ts.map

package/dist/batch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch.d.ts","sourceRoot":"","sources":["../src/batch.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,OAAO,EACP,OAAO,EACP,YAAY,EAEZ,KAAK,EAGN,MAAM,SAAS,CAAC;AAEjB,wBAAgB,KAAK,CAAC,CAAC,EAAE,CAAC,EACxB,EAAE,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,EACjB,KAAK,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAClB,OAAO,GAAE,YAAY,CAAC,CAAC,CAAM,GAC5B,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,CA0Rf"}

package/dist/errors.d.ts

@@ -0,0 +1,4 @@
+export declare class BatchError extends Error {
+    constructor(message: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,qBAAa,UAAW,SAAQ,KAAK;gBACvB,OAAO,EAAE,MAAM;CAI5B"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { batch } from './batch';
+export { BatchError } from './errors';
+export { indexed } from './indexed';
+export { onAnimationFrame, onIdle } from './schedulers';
+export type { Batcher, BatchFn, BatchOptions, GetOptions, Match, MatchFn, Scheduler, TraceEvent, TraceHandler, } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAExD,YAAY,EACV,OAAO,EACP,OAAO,EACP,YAAY,EACZ,UAAU,EACV,KAAK,EACL,OAAO,EACP,SAAS,EACT,UAAU,EACV,YAAY,GACb,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,320 @@
+// src/errors.ts
+class BatchError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "BatchError";
+  }
+}
+
+// src/indexed.ts
+var indexed = Symbol("indexed");
+
+// src/match.ts
+function isIndexed(match) {
+  return match === indexed;
+}
+function isKeyMatch(match) {
+  return typeof match === "string";
+}
+function normalizeMatch(match) {
+  if (isIndexed(match)) {
+    return null;
+  }
+  if (isKeyMatch(match)) {
+    const key = match;
+    return (results, requestedKey) => {
+      return results.find((item) => item[key] === requestedKey);
+    };
+  }
+  return match;
+}
+function createIndexedMatcher() {
+  return (results, key) => results[String(key)];
+}
+
+// src/schedulers.ts
+var microtask = (dispatch) => {
+  let cancelled = false;
+  queueMicrotask(() => {
+    if (!cancelled) {
+      dispatch();
+    }
+  });
+  return () => {
+    cancelled = true;
+  };
+};
+function wait(ms) {
+  return (dispatch) => {
+    const id = setTimeout(dispatch, ms);
+    return () => clearTimeout(id);
+  };
+}
+var onAnimationFrame = (dispatch) => {
+  const id = requestAnimationFrame(dispatch);
+  return () => cancelAnimationFrame(id);
+};
+function onIdle(options) {
+  return (dispatch) => {
+    if (typeof requestIdleCallback !== "undefined") {
+      const id2 = requestIdleCallback(dispatch, options?.timeout ? { timeout: options.timeout } : undefined);
+      return () => cancelIdleCallback(id2);
+    }
+    const id = setTimeout(dispatch, options?.timeout ?? 1);
+    return () => clearTimeout(id);
+  };
+}
+
+// src/trace.ts
+function createTracer(name, handler) {
+  let batchCounter = 0;
+  function emit(event) {
+    if (!handler)
+      return;
+    const fullEvent = {
+      ...event,
+      timestamp: performance.now()
+    };
+    handler(fullEvent);
+  }
+  function nextBatchId() {
+    return `${name ?? "batch"}-${++batchCounter}`;
+  }
+  return { emit, nextBatchId };
+}
+
+// src/batch.ts
+function batch(fn, match, options = {}) {
+  const {
+    wait: waitMs,
+    schedule,
+    max,
+    key: keyFn = (k) => k,
+    name,
+    trace: traceHandler
+  } = options;
+  const scheduler = schedule ?? (waitMs ? wait(waitMs) : microtask);
+  const tracer = createTracer(name, traceHandler);
+  const matchFn = normalizeMatch(match);
+  const isIndexedMatch = isIndexed(match);
+  const indexedMatcher = isIndexedMatch ? createIndexedMatcher() : null;
+  let queue = [];
+  const pendingKeys = new Set;
+  let cleanup = null;
+  let isScheduled = false;
+  let currentAbortController = null;
+  function scheduleDispatch() {
+    if (isScheduled || queue.length === 0)
+      return;
+    isScheduled = true;
+    const batchId = tracer.nextBatchId();
+    tracer.emit({
+      type: "schedule",
+      batchId,
+      size: queue.length
+    });
+    cleanup = scheduler(() => {
+      isScheduled = false;
+      dispatch(batchId);
+    });
+  }
+  async function dispatch(batchId) {
+    const activeQueue = queue.filter((req) => !req.aborted);
+    if (activeQueue.length === 0) {
+      queue = [];
+      pendingKeys.clear();
+      return;
+    }
+    if (cleanup) {
+      cleanup();
+      cleanup = null;
+    }
+    isScheduled = false;
+    const batch2 = activeQueue;
+    queue = [];
+    pendingKeys.clear();
+    const chunks = [];
+    if (max && max > 0) {
+      for (let i = 0;i < batch2.length; i += max) {
+        chunks.push(batch2.slice(i, i + max));
+      }
+    } else {
+      chunks.push(batch2);
+    }
+    for (let i = 0;i < chunks.length; i++) {
+      const chunkBatchId = i === 0 ? batchId ?? tracer.nextBatchId() : tracer.nextBatchId();
+      await processChunk(chunks[i], chunkBatchId);
+    }
+  }
+  async function processChunk(chunk, batchId) {
+    const keyToRequests = new Map;
+    const uniqueKeys = [];
+    for (const request of chunk) {
+      if (request.aborted)
+        continue;
+      const cacheKey = keyFn(request.key);
+      if (!keyToRequests.has(cacheKey)) {
+        keyToRequests.set(cacheKey, []);
+        uniqueKeys.push(request.key);
+      }
+      keyToRequests.get(cacheKey).push(request);
+    }
+    if (uniqueKeys.length === 0)
+      return;
+    tracer.emit({
+      type: "dispatch",
+      batchId,
+      keys: uniqueKeys
+    });
+    currentAbortController = new AbortController;
+    const signal = currentAbortController.signal;
+    const startedAt = performance.now();
+    try {
+      const results = await fn(uniqueKeys, signal);
+      const duration = performance.now() - startedAt;
+      if (signal.aborted) {
+        tracer.emit({ type: "abort", batchId });
+        return;
+      }
+      tracer.emit({
+        type: "resolve",
+        batchId,
+        duration
+      });
+      if (isIndexedMatch && indexedMatcher) {
+        const recordResults = results;
+        for (const key of uniqueKeys) {
+          const cacheKey = keyFn(key);
+          const requests = keyToRequests.get(cacheKey);
+          const value = indexedMatcher(recordResults, key);
+          for (const request of requests) {
+            if (request.aborted)
+              continue;
+            if (value === undefined) {
+              request.reject(new BatchError(`No result for key: ${String(key)}`));
+            } else {
+              request.resolve(value);
+            }
+          }
+        }
+      } else if (matchFn) {
+        const arrayResults = results;
+        if (!Array.isArray(arrayResults)) {
+          throw new BatchError("Batch function returned a non-array result. Use `indexed` for Record responses.");
+        }
+        for (const key of uniqueKeys) {
+          const cacheKey = keyFn(key);
+          const requests = keyToRequests.get(cacheKey);
+          const value = matchFn(arrayResults, key);
+          for (const request of requests) {
+            if (request.aborted)
+              continue;
+            if (value === undefined) {
+              request.reject(new BatchError(`No result for key: ${String(key)}`));
+            } else {
+              request.resolve(value);
+            }
+          }
+        }
+      }
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+      if (err.name === "AbortError" || signal.aborted) {
+        tracer.emit({ type: "abort", batchId });
+      } else {
+        tracer.emit({
+          type: "error",
+          batchId,
+          error: err
+        });
+      }
+      for (const requests of keyToRequests.values()) {
+        for (const request of requests) {
+          if (!request.aborted) {
+            request.reject(err);
+          }
+        }
+      }
+    } finally {
+      currentAbortController = null;
+    }
+  }
+  function getSingle(key, options2) {
+    const externalSignal = options2?.signal;
+    tracer.emit({ type: "get", key });
+    if (externalSignal?.aborted) {
+      return Promise.reject(new DOMException("Aborted", "AbortError"));
+    }
+    const cacheKey = keyFn(key);
+    if (pendingKeys.has(cacheKey)) {
+      tracer.emit({ type: "dedup", key });
+    } else {
+      pendingKeys.add(cacheKey);
+    }
+    return new Promise((resolve, reject) => {
+      const request = {
+        key,
+        resolve,
+        reject,
+        signal: externalSignal,
+        aborted: false
+      };
+      queue.push(request);
+      if (externalSignal) {
+        const onAbort = () => {
+          request.aborted = true;
+          reject(new DOMException("Aborted", "AbortError"));
+          const allAborted = queue.every((r) => r.aborted);
+          if (allAborted && currentAbortController) {
+            currentAbortController.abort();
+          }
+        };
+        externalSignal.addEventListener("abort", onAbort, { once: true });
+      }
+      scheduleDispatch();
+    });
+  }
+  function get(keyOrKeys, options2) {
+    if (Array.isArray(keyOrKeys)) {
+      return Promise.all(keyOrKeys.map((k) => getSingle(k, options2)));
+    }
+    return getSingle(keyOrKeys, options2);
+  }
+  async function flush() {
+    if (cleanup) {
+      cleanup();
+      cleanup = null;
+    }
+    isScheduled = false;
+    await dispatch();
+  }
+  function abort() {
+    for (const request of queue) {
+      request.aborted = true;
+      request.reject(new DOMException("Aborted", "AbortError"));
+    }
+    queue = [];
+    pendingKeys.clear();
+    if (currentAbortController) {
+      currentAbortController.abort();
+    }
+    if (cleanup) {
+      cleanup();
+      cleanup = null;
+    }
+    isScheduled = false;
+  }
+  return {
+    get,
+    flush,
+    abort,
+    name
+  };
+}
+export {
+  onIdle,
+  onAnimationFrame,
+  indexed,
+  batch,
+  BatchError
+};

package/dist/indexed.d.ts

@@ -0,0 +1,2 @@
+export declare const indexed: unique symbol;
+//# sourceMappingURL=indexed.d.ts.map

package/dist/indexed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"indexed.d.ts","sourceRoot":"","sources":["../src/indexed.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,OAAO,EAAE,OAAO,MAA0B,CAAC"}

package/dist/match.d.ts

@@ -0,0 +1,6 @@
+import type { Match, MatchFn } from './types';
+export declare function isIndexed<K, V>(match: Match<K, V>): match is symbol;
+export declare function isKeyMatch<K, V>(match: Match<K, V>): match is keyof V;
+export declare function normalizeMatch<K, V>(match: Match<K, V>): MatchFn<K, V> | null;
+export declare function createIndexedMatcher<K, V>(): (results: Record<string, V>, key: K) => V | undefined;
+//# sourceMappingURL=match.d.ts.map

package/dist/match.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"match.d.ts","sourceRoot":"","sources":["../src/match.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAE9C,wBAAgB,SAAS,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,KAAK,IAAI,MAAM,CAEnE;AAED,wBAAgB,UAAU,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,KAAK,IAAI,MAAM,CAAC,CAErE;AAED,wBAAgB,cAAc,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI,CAkB7E;AAED,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,CAAC,KAAK,CAC5C,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,EAC1B,GAAG,EAAE,CAAC,KACH,CAAC,GAAG,SAAS,CAEjB"}

package/dist/schedulers.d.ts

@@ -0,0 +1,8 @@
+import type { Scheduler } from './types';
+export declare const microtask: Scheduler;
+export declare function wait(ms: number): Scheduler;
+export declare const onAnimationFrame: Scheduler;
+export declare function onIdle(options?: {
+    timeout?: number;
+}): Scheduler;
+//# sourceMappingURL=schedulers.d.ts.map

package/dist/schedulers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schedulers.d.ts","sourceRoot":"","sources":["../src/schedulers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEzC,eAAO,MAAM,SAAS,EAAE,SAYvB,CAAC;AAEF,wBAAgB,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,CAK1C;AAED,eAAO,MAAM,gBAAgB,EAAE,SAG9B,CAAC;AAEF,wBAAgB,MAAM,CAAC,OAAO,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAahE"}

package/dist/trace.d.ts

@@ -0,0 +1,6 @@
+import type { TraceEventData, TraceHandler } from './types';
+export declare function createTracer<K>(name: string | undefined, handler: TraceHandler<K> | undefined): {
+    emit: (event: TraceEventData<K>) => void;
+    nextBatchId: () => string;
+};
+//# sourceMappingURL=trace.d.ts.map

package/dist/trace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace.d.ts","sourceRoot":"","sources":["../src/trace.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAc,cAAc,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAExE,wBAAgB,YAAY,CAAC,CAAC,EAC5B,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,SAAS;kBAIf,eAAe,CAAC,CAAC;uBAWd,MAAM;EAK/B"}

package/dist/types.d.ts

@@ -0,0 +1,61 @@
+export type BatchFn<K, V> = (keys: K[], signal: AbortSignal) => Promise<V[] | Record<string, V>>;
+export type Match<K, V> = keyof V | symbol | MatchFn<K, V>;
+export type MatchFn<K, V> = (results: V[], key: K) => V | undefined;
+export type IndexedMatchFn<K, V> = (results: Record<string, V>, key: K) => V | undefined;
+export type Scheduler = (dispatch: () => void) => () => void;
+export type TraceHandler<K = unknown> = (event: TraceEvent<K>) => void;
+export type TraceEventData<K = unknown> = {
+    type: 'get';
+    key: K;
+} | {
+    type: 'dedup';
+    key: K;
+} | {
+    type: 'schedule';
+    batchId: string;
+    size: number;
+} | {
+    type: 'dispatch';
+    batchId: string;
+    keys: K[];
+} | {
+    type: 'resolve';
+    batchId: string;
+    duration: number;
+} | {
+    type: 'error';
+    batchId: string;
+    error: Error;
+} | {
+    type: 'abort';
+    batchId: string;
+};
+export type TraceEvent<K = unknown> = TraceEventData<K> & {
+    timestamp: number;
+};
+export interface BatchOptions<K = unknown> {
+    wait?: number;
+    schedule?: Scheduler;
+    max?: number;
+    key?: (k: K) => unknown;
+    name?: string;
+    trace?: TraceHandler<K>;
+}
+export interface GetOptions {
+    signal?: AbortSignal;
+}
+export interface Batcher<K, V> {
+    get(key: K, options?: GetOptions): Promise<V>;
+    get(keys: K[], options?: GetOptions): Promise<V[]>;
+    flush(): Promise<void>;
+    abort(): void;
+    readonly name?: string;
+}
+export interface PendingRequest<K, V> {
+    key: K;
+    resolve: (value: V) => void;
+    reject: (error: Error) => void;
+    signal?: AbortSignal;
+    aborted: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "batchkit",
+  "version": "0.1.0",
+  "description": "A modern TypeScript library for batching async operations",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "bun": "./src/index.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir ./dist --target node && tsc -p tsconfig.build.json",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "batch",
+    "batching",
+    "dataloader"
+  ],
+  "author": "",
+  "license": "MIT",
+  "devDependencies": {
+    "bun-types": "latest",
+    "typescript": "5.3.3"
+  }
+}

package/src/batch.ts

@@ -0,0 +1,301 @@
+import { BatchError } from './errors';
+import { createIndexedMatcher, isIndexed, normalizeMatch } from './match';
+import { microtask, wait } from './schedulers';
+import { createTracer } from './trace';
+import type {
+  Batcher,
+  BatchFn,
+  BatchOptions,
+  GetOptions,
+  Match,
+  PendingRequest,
+  Scheduler,
+} from './types';
+
+export function batch<K, V>(
+  fn: BatchFn<K, V>,
+  match: Match<K, V>,
+  options: BatchOptions<K> = {},
+): Batcher<K, V> {
+  const {
+    wait: waitMs,
+    schedule,
+    max,
+    key: keyFn = (k: K) => k,
+    name,
+    trace: traceHandler,
+  } = options;
+
+  const scheduler: Scheduler = schedule ?? (waitMs ? wait(waitMs) : microtask);
+  const tracer = createTracer(name, traceHandler);
+
+  const matchFn = normalizeMatch(match);
+  const isIndexedMatch = isIndexed(match);
+  const indexedMatcher = isIndexedMatch ? createIndexedMatcher<K, V>() : null;
+
+  let queue: PendingRequest<K, V>[] = [];
+  const pendingKeys = new Set<unknown>();
+  let cleanup: (() => void) | null = null;
+  let isScheduled = false;
+  let currentAbortController: AbortController | null = null;
+
+  function scheduleDispatch(): void {
+    if (isScheduled || queue.length === 0) return;
+
+    isScheduled = true;
+    const batchId = tracer.nextBatchId();
+
+    tracer.emit({
+      type: 'schedule',
+      batchId,
+      size: queue.length,
+    });
+
+    cleanup = scheduler(() => {
+      isScheduled = false;
+      dispatch(batchId);
+    });
+  }
+
+  async function dispatch(batchId?: string): Promise<void> {
+    const activeQueue = queue.filter((req) => !req.aborted);
+
+    if (activeQueue.length === 0) {
+      queue = [];
+      pendingKeys.clear();
+      return;
+    }
+
+    if (cleanup) {
+      cleanup();
+      cleanup = null;
+    }
+    isScheduled = false;
+
+    const batch = activeQueue;
+    queue = [];
+    pendingKeys.clear();
+
+    const chunks: PendingRequest<K, V>[][] = [];
+    if (max && max > 0) {
+      for (let i = 0; i < batch.length; i += max) {
+        chunks.push(batch.slice(i, i + max));
+      }
+    } else {
+      chunks.push(batch);
+    }
+
+    for (let i = 0; i < chunks.length; i++) {
+      const chunkBatchId =
+        i === 0 ? (batchId ?? tracer.nextBatchId()) : tracer.nextBatchId();
+      await processChunk(chunks[i], chunkBatchId);
+    }
+  }
+
+  async function processChunk(
+    chunk: PendingRequest<K, V>[],
+    batchId: string,
+  ): Promise<void> {
+    const keyToRequests = new Map<unknown, PendingRequest<K, V>[]>();
+    const uniqueKeys: K[] = [];
+
+    for (const request of chunk) {
+      if (request.aborted) continue;
+
+      const cacheKey = keyFn(request.key);
+
+      if (!keyToRequests.has(cacheKey)) {
+        keyToRequests.set(cacheKey, []);
+        uniqueKeys.push(request.key);
+      }
+      keyToRequests.get(cacheKey)!.push(request);
+    }
+
+    if (uniqueKeys.length === 0) return;
+
+    tracer.emit({
+      type: 'dispatch',
+      batchId,
+      keys: uniqueKeys,
+    });
+
+    currentAbortController = new AbortController();
+    const signal = currentAbortController.signal;
+
+    const startedAt = performance.now();
+
+    try {
+      const results = await fn(uniqueKeys, signal);
+
+      const duration = performance.now() - startedAt;
+
+      if (signal.aborted) {
+        tracer.emit({ type: 'abort', batchId });
+        return;
+      }
+
+      tracer.emit({
+        type: 'resolve',
+        batchId,
+        duration,
+      });
+
+      if (isIndexedMatch && indexedMatcher) {
+        const recordResults = results as Record<string, V>;
+        for (const key of uniqueKeys) {
+          const cacheKey = keyFn(key);
+          const requests = keyToRequests.get(cacheKey)!;
+          const value = indexedMatcher(recordResults, key);
+
+          for (const request of requests) {
+            if (request.aborted) continue;
+            if (value === undefined) {
+              request.reject(
+                new BatchError(`No result for key: ${String(key)}`),
+              );
+            } else {
+              request.resolve(value);
+            }
+          }
+        }
+      } else if (matchFn) {
+        const arrayResults = results as V[];
+
+        if (!Array.isArray(arrayResults)) {
+          throw new BatchError(
+            'Batch function returned a non-array result. Use `indexed` for Record responses.',
+          );
+        }
+
+        for (const key of uniqueKeys) {
+          const cacheKey = keyFn(key);
+          const requests = keyToRequests.get(cacheKey)!;
+          const value = matchFn(arrayResults, key);
+
+          for (const request of requests) {
+            if (request.aborted) continue;
+            if (value === undefined) {
+              request.reject(
+                new BatchError(`No result for key: ${String(key)}`),
+              );
+            } else {
+              request.resolve(value);
+            }
+          }
+        }
+      }
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+
+      if (err.name === 'AbortError' || signal.aborted) {
+        tracer.emit({ type: 'abort', batchId });
+      } else {
+        tracer.emit({
+          type: 'error',
+          batchId,
+          error: err,
+        });
+      }
+
+      for (const requests of keyToRequests.values()) {
+        for (const request of requests) {
+          if (!request.aborted) {
+            request.reject(err);
+          }
+        }
+      }
+    } finally {
+      currentAbortController = null;
+    }
+  }
+
+  function getSingle(key: K, options?: GetOptions): Promise<V> {
+    const externalSignal = options?.signal;
+
+    tracer.emit({ type: 'get', key });
+
+    if (externalSignal?.aborted) {
+      return Promise.reject(new DOMException('Aborted', 'AbortError'));
+    }
+
+    const cacheKey = keyFn(key);
+
+    if (pendingKeys.has(cacheKey)) {
+      tracer.emit({ type: 'dedup', key });
+    } else {
+      pendingKeys.add(cacheKey);
+    }
+
+    return new Promise<V>((resolve, reject) => {
+      const request: PendingRequest<K, V> = {
+        key,
+        resolve,
+        reject,
+        signal: externalSignal,
+        aborted: false,
+      };
+
+      queue.push(request);
+
+      if (externalSignal) {
+        const onAbort = () => {
+          request.aborted = true;
+          reject(new DOMException('Aborted', 'AbortError'));
+
+          const allAborted = queue.every((r) => r.aborted);
+          if (allAborted && currentAbortController) {
+            currentAbortController.abort();
+          }
+        };
+
+        externalSignal.addEventListener('abort', onAbort, { once: true });
+      }
+
+      scheduleDispatch();
+    });
+  }
+
+  function get(key: K, options?: GetOptions): Promise<V>;
+  function get(keys: K[], options?: GetOptions): Promise<V[]>;
+  function get(keyOrKeys: K | K[], options?: GetOptions): Promise<V | V[]> {
+    if (Array.isArray(keyOrKeys)) {
+      return Promise.all(keyOrKeys.map((k) => getSingle(k, options)));
+    }
+    return getSingle(keyOrKeys, options);
+  }
+
+  async function flush(): Promise<void> {
+    if (cleanup) {
+      cleanup();
+      cleanup = null;
+    }
+    isScheduled = false;
+    await dispatch();
+  }
+
+  function abort(): void {
+    for (const request of queue) {
+      request.aborted = true;
+      request.reject(new DOMException('Aborted', 'AbortError'));
+    }
+    queue = [];
+    pendingKeys.clear();
+
+    if (currentAbortController) {
+      currentAbortController.abort();
+    }
+
+    if (cleanup) {
+      cleanup();
+      cleanup = null;
+    }
+    isScheduled = false;
+  }
+
+  return {
+    get,
+    flush,
+    abort,
+    name,
+  };
+}

package/src/errors.ts

@@ -0,0 +1,6 @@
+export class BatchError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'BatchError';
+  }
+}

package/src/index.ts

@@ -0,0 +1,16 @@
+export { batch } from './batch';
+export { BatchError } from './errors';
+export { indexed } from './indexed';
+export { onAnimationFrame, onIdle } from './schedulers';
+
+export type {
+  Batcher,
+  BatchFn,
+  BatchOptions,
+  GetOptions,
+  Match,
+  MatchFn,
+  Scheduler,
+  TraceEvent,
+  TraceHandler,
+} from './types';

package/src/indexed.ts

@@ -0,0 +1 @@
+export const indexed: unique symbol = Symbol('indexed');

package/src/match.ts

@@ -0,0 +1,37 @@
+import { indexed } from './indexed';
+import type { Match, MatchFn } from './types';
+
+export function isIndexed<K, V>(match: Match<K, V>): match is symbol {
+  return match === indexed;
+}
+
+export function isKeyMatch<K, V>(match: Match<K, V>): match is keyof V {
+  return typeof match === 'string';
+}
+
+export function normalizeMatch<K, V>(match: Match<K, V>): MatchFn<K, V> | null {
+  if (isIndexed(match)) {
+    // Indexed matching is handled separately
+    return null;
+  }
+
+  if (isKeyMatch<K, V>(match)) {
+    const key = match;
+    return (results: V[], requestedKey: K) => {
+      return results.find(
+        (item) =>
+          (item as Record<string, unknown>)[key as string] === requestedKey,
+      );
+    };
+  }
+
+  // Already a function
+  return match as MatchFn<K, V>;
+}
+
+export function createIndexedMatcher<K, V>(): (
+  results: Record<string, V>,
+  key: K,
+) => V | undefined {
+  return (results, key) => results[String(key)];
+}

package/src/schedulers.ts

@@ -0,0 +1,42 @@
+import type { Scheduler } from './types';
+
+export const microtask: Scheduler = (dispatch) => {
+  let cancelled = false;
+
+  queueMicrotask(() => {
+    if (!cancelled) {
+      dispatch();
+    }
+  });
+
+  return () => {
+    cancelled = true;
+  };
+};
+
+export function wait(ms: number): Scheduler {
+  return (dispatch) => {
+    const id = setTimeout(dispatch, ms);
+    return () => clearTimeout(id);
+  };
+}
+
+export const onAnimationFrame: Scheduler = (dispatch) => {
+  const id = requestAnimationFrame(dispatch);
+  return () => cancelAnimationFrame(id);
+};
+
+export function onIdle(options?: { timeout?: number }): Scheduler {
+  return (dispatch) => {
+    if (typeof requestIdleCallback !== 'undefined') {
+      const id = requestIdleCallback(
+        dispatch,
+        options?.timeout ? { timeout: options.timeout } : undefined,
+      );
+      return () => cancelIdleCallback(id);
+    }
+
+    const id = setTimeout(dispatch, options?.timeout ?? 1);
+    return () => clearTimeout(id);
+  };
+}

package/src/trace.ts

@@ -0,0 +1,25 @@
+import type { TraceEvent, TraceEventData, TraceHandler } from './types';
+
+export function createTracer<K>(
+  name: string | undefined,
+  handler: TraceHandler<K> | undefined,
+) {
+  let batchCounter = 0;
+
+  function emit(event: TraceEventData<K>) {
+    if (!handler) return;
+
+    const fullEvent = {
+      ...event,
+      timestamp: performance.now(),
+    } as TraceEvent<K>;
+
+    handler(fullEvent);
+  }
+
+  function nextBatchId(): string {
+    return `${name ?? 'batch'}-${++batchCounter}`;
+  }
+
+  return { emit, nextBatchId };
+}

package/src/types.ts

@@ -0,0 +1,57 @@
+export type BatchFn<K, V> = (
+  keys: K[],
+  signal: AbortSignal,
+) => Promise<V[] | Record<string, V>>;
+
+export type Match<K, V> = keyof V | symbol | MatchFn<K, V>;
+
+export type MatchFn<K, V> = (results: V[], key: K) => V | undefined;
+
+export type IndexedMatchFn<K, V> = (
+  results: Record<string, V>,
+  key: K,
+) => V | undefined;
+
+export type Scheduler = (dispatch: () => void) => () => void;
+
+export type TraceHandler<K = unknown> = (event: TraceEvent<K>) => void;
+
+export type TraceEventData<K = unknown> =
+  | { type: 'get'; key: K }
+  | { type: 'dedup'; key: K }
+  | { type: 'schedule'; batchId: string; size: number }
+  | { type: 'dispatch'; batchId: string; keys: K[] }
+  | { type: 'resolve'; batchId: string; duration: number }
+  | { type: 'error'; batchId: string; error: Error }
+  | { type: 'abort'; batchId: string };
+
+export type TraceEvent<K = unknown> = TraceEventData<K> & { timestamp: number };
+
+export interface BatchOptions<K = unknown> {
+  wait?: number;
+  schedule?: Scheduler;
+  max?: number;
+  key?: (k: K) => unknown;
+  name?: string;
+  trace?: TraceHandler<K>;
+}
+
+export interface GetOptions {
+  signal?: AbortSignal;
+}
+
+export interface Batcher<K, V> {
+  get(key: K, options?: GetOptions): Promise<V>;
+  get(keys: K[], options?: GetOptions): Promise<V[]>;
+  flush(): Promise<void>;
+  abort(): void;
+  readonly name?: string;
+}
+
+export interface PendingRequest<K, V> {
+  key: K;
+  resolve: (value: V) => void;
+  reject: (error: Error) => void;
+  signal?: AbortSignal;
+  aborted: boolean;
+}