Async Function Serializer

Why

Initially, I needed to queue some fetch calls in another project, and since I was unaware of the Async package, I wrote something fast & dirty myself.

I then needed more functionality, and testing, and etc, so I split it out into a little package to see if I could make something which scratched my own itch.

Any time I think of something else I might need, or am just interested to see if I am capable of building, then I add it to this repo.

Features

• Basic synchronous and asynchronous queue
• Optional execution concurrency
• Input transformer, allowing most recent results to influence the execution of the next step
• Returns execution results or error
• Batching on addition to queue
• Sorting immediately before drawing from queue
• Initial execution delaying

Background

https://www.chriskerr.dev/writing/serialising-async-functions

Usage

npm i async-function-serializer
yarn add async-function-serializer

import serializer from "async-function-serializer";

const exampleFunction = async ( wait: number ): Promise<number> => {
 return await new Promise( resolve => setTimeout(() => resolve( wait ), wait ));
};

const serialExample = serializer( exampleFunction, options? );

const { data, error } = await serialExample( 1000, inputOptions? );

Serializer options

type SerializeOptions<Input, Return> = {
 /**
  * Maximum number of simultaneous executions
  * @defaultValue 1
  */
 concurrency?: number;

 /**
  * How long to delay before starting initial execution
  * @defaultValue 0
  */
 delay?: number;

 /**
  * Used to sort the queue at the beginning of each execution cycle
  * @defaultValue undefined
  */
 sortBy?: {
  /**
   * Key of input to sort. Will only populate if input is of type object, and only supports top-level keys.
   */
  key: keyof Input;
  /**
   * Sort direction.
   * @defaultValue 'asc'
   */
  direction?: 'asc' | 'desc';
 };

 /**
  * Batch input when adding them to the queue.
  * @defaultValue undefined
  */
 batch?: {
  /**
   * How to long wait before adding the batch to the queue
   */
  debounceInterval: number;

  /**
   * Maximum duration before a batch will close
   */
  maxDebounceInterval?: number;

  /**
   * Function to combine the new queue item into the current batch
   * @param existingBatch - the current batch
   * @param newInput - the new item being added into the batch
   */
  batchTransformer: (
   existingBatch: Input | undefined,
   newInput: Input,
  ) => Input;
 };

 /**
  * Function to transform the input at the beginning of each execution cycle
  * @param input - the current value being transformed
  * @param previousResult - the results from the previous execution, if any
  */
 inputTransformer?: (
  input: Input,
  previousResult: Awaited<Return> | undefined,
 ) => Input | Promise<Input>;
};

Input options

type InputOptions = {
 /**
  * This will force-start a new batch. If another batch is in-progress, it will be immediately added to queue.
  * */
 startNewBatch?: boolean;
};

Bugs, Feedback & Contributions

I'd be glad to hear from you! So please provide any through issues, discussions or as a pull request above 😃