batchkit 0.1.0 → 0.2.0-beta.1

package/README.md

@@ -1,6 +1,6 @@
 # batchkit
 
-Automatic batching for async operations.
+Tiny batching library. Supports various scheduling and deduplication strategies.
 
 ## Installation
 
@@ -20,17 +20,13 @@ const users = batch(
   'id'
 )
 
-// These calls are automatically batched into ONE database query
+// These calls are 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?)`
@@ -140,7 +136,7 @@ Batches all calls within the same event loop tick:
 ```typescript
 const users = batch(fn, 'id')
 
-// All batched into ONE request
+// these synchronous invocations are batched into one request
 users.get(1)
 users.get(2)
 users.get(3)
@@ -231,7 +227,7 @@ function UserAvatar({ userId }: { userId: string }) {
   return <img src={data?.avatar} />
 }
 
-// Rendering 100 UserAvatars = 1 HTTP request
+// Rendering 100 UserAvatars from a service -> 1 HTTP request
 ```
 
 ### API with Rate Limits
@@ -248,7 +244,7 @@ const products = batch(
 
 ## TypeScript
 
-Full type inference:
+Correctly infers types based on call site
 
 ```typescript
 type User = { id: number; name: string }

package/dist/batch.d.ts.map

@@ -1 +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"}
+{"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,CA8Rf"}

package/dist/index.js

@@ -66,16 +66,32 @@ function onIdle(options) {
 }
 
 // src/trace.ts
+function getDevtools() {
+  if (typeof window !== "undefined" && window.__BATCHKIT_DEVTOOLS__) {
+    return window.__BATCHKIT_DEVTOOLS__;
+  }
+  return;
+}
 function createTracer(name, handler) {
   let batchCounter = 0;
+  let registeredWithDevtools = false;
   function emit(event) {
-    if (!handler)
-      return;
+    const timestamp = performance.now();
     const fullEvent = {
       ...event,
-      timestamp: performance.now()
+      timestamp
     };
-    handler(fullEvent);
+    if (handler) {
+      handler(fullEvent);
+    }
+    const devtools = getDevtools();
+    if (devtools && name) {
+      if (!registeredWithDevtools) {
+        devtools.register({ name, registeredAt: timestamp });
+        registeredWithDevtools = true;
+      }
+      devtools.emit(name, fullEvent);
+    }
   }
   function nextBatchId() {
     return `${name ?? "batch"}-${++batchCounter}`;
@@ -153,11 +169,13 @@ function batch(fn, match, options = {}) {
       if (request.aborted)
         continue;
       const cacheKey = keyFn(request.key);
-      if (!keyToRequests.has(cacheKey)) {
-        keyToRequests.set(cacheKey, []);
+      let requests = keyToRequests.get(cacheKey);
+      if (!requests) {
+        requests = [];
+        keyToRequests.set(cacheKey, requests);
         uniqueKeys.push(request.key);
       }
-      keyToRequests.get(cacheKey).push(request);
+      requests.push(request);
     }
     if (uniqueKeys.length === 0)
       return;
@@ -186,6 +204,8 @@ function batch(fn, match, options = {}) {
         for (const key of uniqueKeys) {
           const cacheKey = keyFn(key);
           const requests = keyToRequests.get(cacheKey);
+          if (!requests)
+            continue;
           const value = indexedMatcher(recordResults, key);
           for (const request of requests) {
             if (request.aborted)
@@ -205,6 +225,8 @@ function batch(fn, match, options = {}) {
         for (const key of uniqueKeys) {
           const cacheKey = keyFn(key);
           const requests = keyToRequests.get(cacheKey);
+          if (!requests)
+            continue;
           const value = matchFn(arrayResults, key);
           for (const request of requests) {
             if (request.aborted)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "batchkit",
-  "version": "0.1.0",
+  "version": "0.2.0-beta.1",
   "description": "A modern TypeScript library for batching async operations",
   "type": "module",
   "main": "./dist/index.js",

package/src/batch.ts

@@ -104,11 +104,13 @@ export function batch<K, V>(
 
       const cacheKey = keyFn(request.key);
 
-      if (!keyToRequests.has(cacheKey)) {
-        keyToRequests.set(cacheKey, []);
+      let requests = keyToRequests.get(cacheKey);
+      if (!requests) {
+        requests = [];
+        keyToRequests.set(cacheKey, requests);
         uniqueKeys.push(request.key);
       }
-      keyToRequests.get(cacheKey)!.push(request);
+      requests.push(request);
     }
 
     if (uniqueKeys.length === 0) return;
@@ -144,7 +146,8 @@ export function batch<K, V>(
         const recordResults = results as Record<string, V>;
         for (const key of uniqueKeys) {
           const cacheKey = keyFn(key);
-          const requests = keyToRequests.get(cacheKey)!;
+          const requests = keyToRequests.get(cacheKey);
+          if (!requests) continue;
           const value = indexedMatcher(recordResults, key);
 
           for (const request of requests) {
@@ -169,7 +172,8 @@ export function batch<K, V>(
 
         for (const key of uniqueKeys) {
           const cacheKey = keyFn(key);
-          const requests = keyToRequests.get(cacheKey)!;
+          const requests = keyToRequests.get(cacheKey);
+          if (!requests) continue;
           const value = matchFn(arrayResults, key);
 
           for (const request of requests) {

package/src/trace.ts

@@ -1,20 +1,47 @@
 import type { TraceEvent, TraceEventData, TraceHandler } from './types';
 
+interface DevtoolsRegistry {
+  register(info: { name: string; registeredAt: number }): void;
+  emit(name: string, event: unknown): void;
+}
+
+declare const window: { __BATCHKIT_DEVTOOLS__?: DevtoolsRegistry } | undefined;
+
+function getDevtools(): DevtoolsRegistry | undefined {
+  // biome-ignore lint/complexity/useOptionalChain: need typeof check for Node.js
+  if (typeof window !== 'undefined' && window.__BATCHKIT_DEVTOOLS__) {
+    return window.__BATCHKIT_DEVTOOLS__;
+  }
+  return undefined;
+}
+
 export function createTracer<K>(
   name: string | undefined,
   handler: TraceHandler<K> | undefined,
 ) {
   let batchCounter = 0;
+  let registeredWithDevtools = false;
 
   function emit(event: TraceEventData<K>) {
-    if (!handler) return;
+    const timestamp = performance.now();
 
     const fullEvent = {
       ...event,
-      timestamp: performance.now(),
+      timestamp,
     } as TraceEvent<K>;
 
-    handler(fullEvent);
+    if (handler) {
+      handler(fullEvent);
+    }
+
+    const devtools = getDevtools();
+    if (devtools && name) {
+      if (!registeredWithDevtools) {
+        devtools.register({ name, registeredAt: timestamp });
+        registeredWithDevtools = true;
+      }
+      devtools.emit(name, fullEvent);
+    }
   }
 
   function nextBatchId(): string {

package/dist/batch.d.ts

@@ -1,3 +0,0 @@
-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/errors.d.ts

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

package/dist/errors.d.ts.map

@@ -1 +0,0 @@
-{"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

@@ -1,6 +0,0 @@
-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

@@ -1 +0,0 @@
-{"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/indexed.d.ts

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

package/dist/indexed.d.ts.map

@@ -1 +0,0 @@
-{"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

@@ -1,6 +0,0 @@
-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

@@ -1 +0,0 @@
-{"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

@@ -1,8 +0,0 @@
-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

@@ -1 +0,0 @@
-{"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

@@ -1,6 +0,0 @@
-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

@@ -1 +0,0 @@
-{"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

@@ -1,61 +0,0 @@
-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

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