feat: introduce a named type to represent the teardown function, expo…

…rt as part of public API (#33)

* introduce a named type to represent the untyped teardown function to be exported with the public API

* JSDoc for the `TeardownFn` symbol

* reorder public exports in-code

src/index.ts

@@ -1,20 +1,22 @@
 import {
   iterified,
-  type Iterified,
   type IterifiedIterable,
   type IterifiedIterator,
+  type ExecutorFn,
+  type TeardownFn,
+  type Iterified,
 } from './iterified';
 import { iterifiedUnwrapped, type IterifiedUnwrapped } from './iterifiedUnwrapped';
-import { type ExecutorFn } from './utils/types/ExecutorFn';
 
 export {
   iterified,
   iterifiedUnwrapped,
-  type ExecutorFn,
-  type Iterified,
   type IterifiedIterable,
   type IterifiedUnwrapped,
   type IterifiedIterator,
+  type ExecutorFn,
+  type TeardownFn,
+  type Iterified,
 };
 
 // TODO: Should implement such that when an instance is ended (or all has all its active iterators closed), it can always be reinitialized by just consuming it again, similarly with RxJS observables?

src/iterified.ts

@@ -1,9 +1,10 @@
+import { type MaybePromise } from './utils/types/MaybePromise';
 import { MulticastChannel, createMulticastChannel } from './utils/createMulticastChannel';
-import { type ExecutorFn } from './utils/types/ExecutorFn';
 
 export {
   iterified,
   type ExecutorFn,
+  type TeardownFn,
   type IterifiedIterable,
   type Iterified,
   type IterifiedIterator,
@@ -97,6 +98,10 @@ function iterified<TNext>(executorFn: ExecutorFn<TNext>): IterifiedIterable<TNex
   }
 }
 
+type IterifiedIterable<TNextValue, TDoneValue = undefined | void> = {
+  [Symbol.asyncIterator](): IterifiedIterator<TNextValue, TDoneValue>;
+};
+
 /**
  * @deprecated This type is deprecated - use {@link IterifiedIterable} instead.
  * @see {@link IterifiedIterable}
@@ -106,11 +111,37 @@ type Iterified<TNextValue, TDoneValue = undefined | void> = IterifiedIterable<
   TDoneValue
 >;
 
-type IterifiedIterable<TNextValue, TDoneValue = undefined | void> = {
-  [Symbol.asyncIterator](): IterifiedIterator<TNextValue, TDoneValue>;
-};
-
 type IterifiedIterator<TNextValue, TDoneValue = undefined | void> = {
   next(): Promise<IteratorResult<TNextValue, TDoneValue>>;
   return(): Promise<IteratorReturnResult<TDoneValue>>;
 };
+
+type ExecutorFn<TNext> = (
+  nextCb: (nextValue: TNext) => void,
+  doneCb: () => void,
+  errorCb: (error: unknown) => void
+) => MaybePromise<void | TeardownFn>;
+
+/**
+ * A teardown function which can be optionally returned from the _Executor function_ ({@link ExecutorFn})
+ * provided by the user.
+ *
+ * This is the appropriate place to close and dispose of any resources opened during the
+ * _executor_'s lifetime and used to generate values from. This function may be asynchronous
+ * (return a promise).
+ *
+ * If provided, the _teardown function_ would always be triggered automatically when either
+ * of these takes place:
+ *
+ * - The `iterified` iterable is ended from __inside__ (meaning _initiated by the producer_);
+ * by calling the `done()` or `error(e)` callbacks from within the _executor function_
+ *
+ * - The `iterified` iterable is ended from __outside__ (meaning _initiated by the consumer_);
+ * by closing the last remaining active iterator
+ * (or [`for await...of`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of) loop)
+ *
+ * @see {@link ExecutorFn}
+ *
+ * @see https://github.com/shtaif/iterified#specifying-teardown-logic for more reference
+ */
+type TeardownFn = () => MaybePromise<void>;