docs: improved documentation (#3)

* docs: improved documentation

* npm test -- --coverage

* fix title

* run ci on any push

Author: onhate

.github/labeler.yml

@@ -1,3 +1,4 @@
 feature: [ 'feature-*', 'feat-*' ]
 bugfix: [ 'fix-*', 'bugfix-*' ]
 chore: [ 'chore-*' ]
+documentation: [ 'doc-*', 'docs-*' ]

.github/release-drafter.yml

@@ -1,5 +1,5 @@
-name-template: 'v$NEXT_PATCH_VERSION 🌈'
-tag-template: 'v$NEXT_PATCH_VERSION'
+name-template: 'v$RESOLVED_VERSION 🌈'
+tag-template: 'v$RESOLVED_VERSION'
 categories:
   - title: '🚀 Features'
     labels:
@@ -11,10 +11,23 @@ categories:
       - 'bugfix'
       - 'bug'
   - title: '🧰 Maintenance'
-    label: 'chore'
+    labels:
+      - 'chore'
+      - 'documentation'
 change-template: '- $TITLE @$AUTHOR (#$NUMBER)'
 exclude-labels:
   - 'skip-changelog'
+version-resolver:
+  major:
+    labels:
+      - 'major'
+  minor:
+    labels:
+      - 'minor'
+  patch:
+    labels:
+      - 'patch'
+  default: patch
 template: |
   ## Changes
 

.github/workflows/ci.yml

@@ -0,0 +1,16 @@
+name: "Pull Request Labeler"
+
+on:
+  push:
+    branches: "**"
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 18
+      - run: npm ci
+      - run: npm test -- --coverage

.github/workflows/labeler.yml

@@ -5,17 +5,15 @@
 # file with configuration.  For more information, see:
 # https://github.com/actions/labeler
 
-name: Labeler
+name: "Pull Request Labeler"
 on: [pull_request_target]
 
 jobs:
-  label:
-
+  labeler:
     runs-on: ubuntu-latest
     permissions:
       contents: read
       pull-requests: write
-
     steps:
     - uses: actions/labeler@v4
       with:

.github/workflows/releases.yml renamed to .github/workflows/release-drafter.yml

@@ -1,10 +1,15 @@
-# InBatches (📦📦📦)
+# @InBatches(📦,📦,📦,...)
 
-InBatches is a zero-dependency TypeScript library that provides a convenient way to batch and execute asynchronous
-operations in a controlled manner. This library is especially useful for scenarios where you need to perform multiple
-asynchronous operations efficiently, such as when making network requests or performing database queries.
+InBatches is a zero-dependency generic TypeScript library that provides a convenient way to batch executions that runs
+asynchronous.
 
-Heavily inspired by [graphql/dataloader](https://github.com/graphql/dataloader) but better 😜
+It is designed to be used as part of your application's data fetching layer to provide a consistent API over various
+backends and reduce requests to those backends via batching.
+
+This library is especially useful for scenarios where you need to perform multiple asynchronous operations efficiently,
+such as when making network requests or performing database queries.
+
+Heavily inspired by [graphql/dataloader](https://github.com/graphql/dataloader) but using classes and decorators 😜
 
 ## Table of Contents
 
@@ -27,12 +32,13 @@ npm install inbatches
 
 ## Usage
 
-### Basic Usage
+### Using the `Batcher` Class
 
 ```typescript
 import { Batcher } from 'inbatches';
 
 // Define a class that extends Batcher and implements the `run` method
+// the `run` method will be called with an array of keys collected from the `enqueue` method
 class MyBatcher extends Batcher<number, string> {
   async run(ids: number[]): Promise<string[]> {
     // Perform asynchronous operations using the keys
@@ -44,16 +50,14 @@ class MyBatcher extends Batcher<number, string> {
 // Create an instance of your batcher
 const batcher = new MyBatcher();
 
-// Enqueue keys for batching and execution
-const resultPromise1 = batcher.enqueue(1);
-const resultPromise2 = batcher.enqueue(2);
-
-resultPromise1.then(result => {
-  console.log(result); // Output: "{ id: 1, name: 'Result for key 1' }"
+// Enqueue keys for batched execution
+const result = [1, 2, 3, 4, 5].map(async id => {
+  return await batcher.enqueue(id);
 });
 
-resultPromise2.then(result => {
-  console.log(result); // Output: "{ id: 2, name: 'Result for key 2' }"
+// The result will be an array of results in the same order as the keys
+result.then(results => {
+  console.log(results); // Output: [{ id: 1, name: 'Result for key 1' }, ...]
 });
 ```
 
@@ -65,10 +69,13 @@ The library also provides a decorator called `InBatches` that you can use to bat
 import { InBatches } from 'inbatches';
 
 class MyService {
-  @InBatches()
+
+  // (optional) overloaded method, where you define the keys as `number` and the return type as `string` for typings
+  async fetch(keys: number): Promise<string>;
+
+  // in reality the Decorator will wrap this method and it will never be called with a single key :)
+  @InBatches() // This method is now batch-enabled
   async fetch(keys: number | number[]): Promise<string | string[]> {
-    // This method is now batch-enabled
-    // Perform asynchronous operations using the keys
     if (Array.isArray(keys)) {
       return this.db.getMany(keys);
     }
@@ -80,16 +87,13 @@ class MyService {
 
 const service = new MyService();
 
-// Enqueue keys for batching and execution
-const resultPromise1 = service.fetch(1);
-const resultPromise2 = service.fetch(2);
-
-resultPromise1.then(results => {
-  console.log(results); // Output: { id: 1, name: 'Result for key 1' }
+const result = [1, 2, 3, 4, 5].map(async id => {
+  return await service.fetch(id);
 });
 
-resultPromise2.then(results => {
-  console.log(results); // Output: { id: 2, name: 'Result for key 2' }
+// The result will be an array of results in the same order as the keys
+result.then(results => {
+  console.log(results); // Output: [{ id: 1, name: 'Result for key 1' }, ...]
 });
 ```
 
@@ -100,7 +104,9 @@ resultPromise2.then(results => {
 An interface to specify options for the batcher.
 
 - `maxBatchSize`: The maximum number of keys to batch together. Default is `25`.
-- `delayWindowInMs`: The delay window in milliseconds before dispatching the batch. Default is `undefined`.
+- `delayWindowInMs`: (not recommended) The delay window in milliseconds before dispatching the batch. Default
+  is `undefined` and will use `process.nextTick` to dispatch the batch, which is highly efficient and fast. Only use
+  this if you really want to accumulate promises calls in a window of time before dispatching the batch.
 
 ### `Batcher<K, V>` Class
 
@@ -116,15 +122,19 @@ A decorator function that can be applied to methods to enable batching.
 - Usage: `@InBatches(options?: BatcherOptions)`
 - Example:
 
-  ```typescript
-  class MyService {
-    @InBatches({ maxBatchSize: 10 })
-    async fetchResults(keys: number | number[]): Promise<string | string[]> {
-      // Batch-enabled method logic
-    }
-  }
-  ```
+```typescript
+class MyService {
 
+  // (optional) overloaded method, where you define the keys as `number` and the return type as `string` for typings
+  async fetchResults(keys: number): Promise<string>
+  
+  @InBatches({ maxBatchSize: 10 })
+  async fetchResults(keys: number | number[]): Promise<string | string[]> {
+    // Batch-enabled method logic
+  }
+}
+```
+  
 ## Contributing
 
 Contributions are welcome! Feel free to open issues or submit pull requests on

README.md

@@ -1,6 +1,6 @@
 {
   "name": "inbatches",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "private": false,
   "license": "MIT",
   "repository": {

package.json

@@ -3,7 +3,7 @@ export interface BatcherOptions {
   delayWindowInMs?: number;
 }
 
-interface Execution<K> {
+interface Callback<K> {
   key: K;
   resolve: Function;
   reject: Function;
@@ -12,15 +12,15 @@ interface Execution<K> {
 class Batch<K, V> {
   public active = true;
   public readonly cache = new Map<K, Promise<V>>();
-  public readonly executions: Execution<K>[] = [];
+  public readonly callbacks: Callback<K>[] = [];
 
   append(key: K) {
     if (this.cache.has(key)) {
       return this.cache.get(key);
     }
 
     const promise = new Promise<V>((resolve, reject) => {
-      this.executions.push({ key, resolve, reject });
+      this.callbacks.push({ key, resolve, reject });
     });
 
     this.cache.set(key, promise);
@@ -54,7 +54,7 @@ export abstract class Batcher<K, V> {
   private getCurrentBatch() {
     // if there is a current batch, and it has not been dispatched, and it is not full
     if (this.current) {
-      if (this.current.active && this.current.executions.length < this.options.maxBatchSize) {
+      if (this.current.active && this.current.callbacks.length < this.options.maxBatchSize) {
         return this.current;
       }
     }
@@ -82,12 +82,12 @@ export abstract class Batcher<K, V> {
   private dispatch(batch: Batch<K, V>) {
     batch.active = false;
 
-    if (batch.executions.length === 0) {
+    if (batch.callbacks.length === 0) {
       return;
     }
 
     try {
-      this.run(batch.executions.map(callback => callback.key))
+      this.run(batch.callbacks.map(callback => callback.key))
         .then(values => this.fulfill(batch, values))
         .catch(error => this.reject(batch, error));
     } catch (error) {
@@ -96,15 +96,15 @@ export abstract class Batcher<K, V> {
   }
 
   private fulfill(batch: Batch<K, V>, values: (V | Error)[]) {
-    batch.executions.forEach((callback, index) => {
+    batch.callbacks.forEach((callback, index) => {
       const value = values[index];
       if (value instanceof Error) callback.reject(value);
       else callback.resolve(value);
     });
   }
 
   private reject(batch: Batch<K, V>, error: Error) {
-    batch.executions.forEach(callback => {
+    batch.callbacks.forEach(callback => {
       callback.reject(error);
     });
   }

src/batcher.ts

@@ -4,16 +4,21 @@ class RunInBatches {
   constructor(private id: string = '') {
   }
 
+
+  async getAll(keys: string): Promise<string>;
+
   @InBatches()
-  async getAll(keys: string | string[]) {
+  async getAll(keys: string | string[]): Promise<string | string[]> {
     if (Array.isArray(keys)) {
       return keys.map((key, index) => `${key}-index-${index}-${this.id}`);
     }
     throw new Error('Should not be called with single key');
   }
 
+  async getCouple(keys: string): Promise<string>;
+
   @InBatches({ maxBatchSize: 2 })
-  async getCouple(keys: string | string[]) {
+  async getCouple(keys: string | string[]): Promise<string | string[]> {
     if (Array.isArray(keys)) {
       return keys.map((key, index) => `${key}-index-${index}-${this.id}`);
     }