Encre-core: add documentation for Callables

[VictorS67]

abstract class Callable

Abstract class representing a callable. A callable is an object that can be "called" or invoked with an input to produce an output, potentially asynchronously.

static isCallable(anything)

A static method that checks if the argument is a callable class object.

abstract invoke(input, options?)

Abstract method that must be implemented by subclasses. Invokes the callable with the given input and options.

withConfig(config)

Creates a new CallableBind instance with the specified configuration. This method allows reconfiguration of the callable instance.

withFallbacks(fields: { fallbacks })

Creates a new CallableWithFallbacks instance with specified fallbacks. This method allows defining fallback callables for error handling or retries.

bind(kwargs)

Creates a new CallableBind instance with the specified keyword arguments. This method allows partial reconfiguration of the callable instance.

map()

Creates a new CallableEach instance for mapping inputs to outputs. This method allows applying the callable to each input in an array of inputs.

async batch(inputs, options?, batchOptions?)

Batch calls invoke N times, where N is the length of inputs. Subclasses would override this method with different arguments and returns.

async stream(input, options?)

Creates a readable stream for the callable outputs. This method allows streaming the outputs of the callable for continuous data.

pipe(callableLike)

Chains the current callable with another callable, creating a sequence. This method allows sequential execution of multiple callables.

---

class CallableBind

It represents a callable entity that can be bound with additional configurations and arguments. This class is used to create callable objects with specific bindings and configurations.

bound

The bound callable instance.

config

Configuration for the callable.

protected kwargs: Partial

Keyword arguments for additional configuration.

bind(kwargs)

Creates a new instance of CallableBind with the provided keyword arguments. This method allows for partial reconfiguration of the callable binding.

withConfig(config)

Creates a new instance of CallableBind with the provided configuration. This method allows for partial or complete reconfiguration of the callable.

async invoke(input, options?)

Invokes the bound callable with the provided input and options. Merges the provided options with the current keyword arguments and configuration.

---

class CallableMap

CallableMap class extends the Callable class for mapping multiple Callable instances. It allows the execution of multiple callables in parallel and aggregates their results.

protected steps

Holds the mapping of steps where each step is a callable.

static from(steps)

Static method to create a CallableMap instance from a mapping of callables.

async invoke(input, options?)

Invokes all callables in the map with the given input, in parallel. Aggregates and returns the results of all callables in a single record.

---

class CallableEach

The CallableEach class extends Callable to handle batch operations by applying a single Callable instance to each item in an input array.

bound

The bound Callable instance to which each input item is passed.

bind(kwargs)

Binds the given options to the callable and returns a new CallableEach instance.

async invoke(inputs, options?)

Invokes the callable for each item in the input array.

---

class CallableWithFallbacks

CallableWithFallbacks class extends Callable to provide fallback mechanisms. It allows the execution of a primary callable and fallbacks in case of failure.

protected callable

The primary callable to be invoked.

protected fallbacks: Callable<CallInput, CallOutput>[]

An array of fallback callables to be invoked if the primary callable fails.

*callables()

Generator function to iterate over the primary callable and fallbacks.

async invoke(input, options?)

Invokes the primary callable and falls back to the fallbacks in case of an error. If all callables fail, rethrows the first error encountered.

---

class CallableSequence

CallableSequence class extends Callable to create a sequence of callable operations. It allows chaining multiple callables, where the output of one is the input to the next.

protected first

The first callable in the sequence.

protected middle

An array of callables that form the middle of the sequence.

protected last

The last callable in the sequence, producing the final output.

get steps()

Gets the sequence of callables as an array.

static isCallableSequence(anything)

Static method to check if a given object is an instance of CallableSequence.

static from([first, ...callables])

Static method to create a CallableSequence instance from an array of callable-like objects.

async invoke(input, options?)

Invokes the sequence of callables with the given input. Each callable's output is passed as the input to the next callable.

pipe(callableLike)

Extends the current callable sequence by adding another callable or callable sequence to the end. This method allows for dynamic extension of the callable sequence, maintaining the flow of data.

---

class CallableLambda

CallableLambda class extends the Callable class, allowing the use of lambda functions. It's a specialized version of Callable that uses JavaScript lambda functions for its logic.

protected func

Holds the string representation of the lambda function.

static from(func)

Static method to create a CallableLambda instance from a lambda function.

async invoke(input, options?)

Public method to invoke the lambda function.

[Ikochoy]

LGTM