@isdk/ai-tool 0.4.0 → 0.5.1

package/docs/classes/Semaphore.md

@@ -1,4 +1,4 @@
-[**@isdk/ai-tool**](../README.md) • **Docs**
+[**@isdk/ai-tool**](../README.md)
 
 ***
 
@@ -6,8 +6,11 @@
 
 # Class: Semaphore
 
+Defined in: [packages/ai-tool/src/utils/async-semaphore.ts:372](https://github.com/isdk/ai-tool.js/blob/6a89194ac34437a1bc58f7ec590cd22976939ca6/src/utils/async-semaphore.ts#L372)
+
 A Semaphore implementation for managing concurrency in asynchronous operations.
 Semaphores allow a fixed number of resources to be accessed concurrently.
+This class extends BinarySemaphore and adds support for a maximum concurrency limit and an optional readiness check.
 
 Example usage:
 
@@ -17,7 +20,17 @@ const semaphore = new Semaphore(5); // Allows 5 concurrent operations.
 const semaphore = new Semaphore(
   4, // Allow 4 concurrent async calls
   {
-    capacity: 100 // Prealloc space for 100 tokens
+    capacity: 100, // Prealloc space for 100 tokens
+    isReadyFn: async () => {
+      // Check if the system is ready to handle more requests
+      return true;
+    },
+    pauseFn: () => {
+      console.log('Pausing the stream');
+    },
+    resumeFn: () => {
+      console.log('Resuming the stream');
+    }
   }
 );
 
@@ -34,77 +47,317 @@ async function fetchData(x) {
 const data = await Promise.all(array.map(fetchData));
 ```
 
+## Extends
+
+- [`BinarySemaphore`](BinarySemaphore.md)
+
 ## Constructors
 
 ### new Semaphore()
 
-> **new Semaphore**(`maxConcurrency`, `__namedParameters`): [`Semaphore`](Semaphore.md)
+> **new Semaphore**(`maxConcurrency`, `options`?): [`Semaphore`](Semaphore.md)
+
+Defined in: [packages/ai-tool/src/utils/async-semaphore.ts:390](https://github.com/isdk/ai-tool.js/blob/6a89194ac34437a1bc58f7ec590cd22976939ca6/src/utils/async-semaphore.ts#L390)
 
 Creates a semaphore object. The first argument is the maximum concurrently number and the second argument is optional.
 
 #### Parameters
 
-• **maxConcurrency**: `number`
+##### maxConcurrency
 
 The maximum number of callers allowed to acquire the semaphore concurrently.
 
-• **\_\_namedParameters** = `{}`
+`number` | [`SemaphoreOptions`](../interfaces/SemaphoreOptions.md)
 
-• **\_\_namedParameters.capacity?**: `number` = `DefaultAsyncSemaphoreCapacity`
+##### options?
 
-• **\_\_namedParameters.initFn?** = `defaultInit`
-
-• **\_\_namedParameters.pauseFn?**
-
-• **\_\_namedParameters.resumeFn?**
+[`SemaphoreOptions`](../interfaces/SemaphoreOptions.md)
 
 #### Returns
 
 [`Semaphore`](Semaphore.md)
 
-#### Defined in
+#### Overrides
 
-[packages/ai-tool/src/utils/async-semaphore.ts:207](https://github.com/isdk/ai-tool.js/blob/b0813174e9b350ae47231f8e5f885150313123b0/src/utils/async-semaphore.ts#L207)
+[`BinarySemaphore`](BinarySemaphore.md).[`constructor`](BinarySemaphore.md#constructors)
 
 ## Properties
 
+### \_activeCount
+
+> `protected` **\_activeCount**: `number`
+
+Defined in: [packages/ai-tool/src/utils/async-semaphore.ts:97](https://github.com/isdk/ai-tool.js/blob/6a89194ac34437a1bc58f7ec590cd22976939ca6/src/utils/async-semaphore.ts#L97)
+
+#### Inherited from
+
+[`BinarySemaphore`](BinarySemaphore.md).[`_activeCount`](BinarySemaphore.md#_activecount)
+
+***
+
+### emitter
+
+> `protected` **emitter**: [`EventEmitter`](EventEmitter.md)
+
+Defined in: [packages/ai-tool/src/utils/async-semaphore.ts:91](https://github.com/isdk/ai-tool.js/blob/6a89194ac34437a1bc58f7ec590cd22976939ca6/src/utils/async-semaphore.ts#L91)
+
+#### Inherited from
+
+[`BinarySemaphore`](BinarySemaphore.md).[`emitter`](BinarySemaphore.md#emitter)
+
+***
+
+### free
+
+> `protected` **free**: `Deque`\<`any`\>
+
+Defined in: [packages/ai-tool/src/utils/async-semaphore.ts:374](https://github.com/isdk/ai-tool.js/blob/6a89194ac34437a1bc58f7ec590cd22976939ca6/src/utils/async-semaphore.ts#L374)
+
+#### Overrides
+
+[`BinarySemaphore`](BinarySemaphore.md).[`free`](BinarySemaphore.md#free)
+
+***
+
+### initTokenFn()
+
+> `protected` **initTokenFn**: (`token`?) => `void`
+
+Defined in: [packages/ai-tool/src/utils/async-semaphore.ts:95](https://github.com/isdk/ai-tool.js/blob/6a89194ac34437a1bc58f7ec590cd22976939ca6/src/utils/async-semaphore.ts#L95)
+
+#### Parameters
+
+##### token?
+
+`any`
+
+#### Returns
+
+`void`
+
+#### Inherited from
+
+[`BinarySemaphore`](BinarySemaphore.md).[`initTokenFn`](BinarySemaphore.md#inittokenfn)
+
+***
+
 ### maxConcurrency
 
 > `readonly` **maxConcurrency**: `number`
 
-#### Defined in
+Defined in: [packages/ai-tool/src/utils/async-semaphore.ts:373](https://github.com/isdk/ai-tool.js/blob/6a89194ac34437a1bc58f7ec590cd22976939ca6/src/utils/async-semaphore.ts#L373)
+
+***
+
+### paused
+
+> `protected` **paused**: `boolean`
+
+Defined in: [packages/ai-tool/src/utils/async-semaphore.ts:96](https://github.com/isdk/ai-tool.js/blob/6a89194ac34437a1bc58f7ec590cd22976939ca6/src/utils/async-semaphore.ts#L96)
+
+#### Inherited from
+
+[`BinarySemaphore`](BinarySemaphore.md).[`paused`](BinarySemaphore.md#paused)
+
+***
+
+### pauseFn()?
+
+> `protected` `optional` **pauseFn**: () => `void`
+
+Defined in: [packages/ai-tool/src/utils/async-semaphore.ts:93](https://github.com/isdk/ai-tool.js/blob/6a89194ac34437a1bc58f7ec590cd22976939ca6/src/utils/async-semaphore.ts#L93)
+
+#### Returns
+
+`void`
+
+#### Inherited from
 
-[packages/ai-tool/src/utils/async-semaphore.ts:151](https://github.com/isdk/ai-tool.js/blob/b0813174e9b350ae47231f8e5f885150313123b0/src/utils/async-semaphore.ts#L151)
+[`BinarySemaphore`](BinarySemaphore.md).[`pauseFn`](BinarySemaphore.md#pausefn)
+
+***
+
+### resumeFn()?
+
+> `protected` `optional` **resumeFn**: () => `void`
+
+Defined in: [packages/ai-tool/src/utils/async-semaphore.ts:94](https://github.com/isdk/ai-tool.js/blob/6a89194ac34437a1bc58f7ec590cd22976939ca6/src/utils/async-semaphore.ts#L94)
+
+#### Returns
+
+`void`
+
+#### Inherited from
+
+[`BinarySemaphore`](BinarySemaphore.md).[`resumeFn`](BinarySemaphore.md#resumefn)
+
+***
+
+### useDefaultTokens
+
+> `protected` **useDefaultTokens**: `boolean`
+
+Defined in: [packages/ai-tool/src/utils/async-semaphore.ts:92](https://github.com/isdk/ai-tool.js/blob/6a89194ac34437a1bc58f7ec590cd22976939ca6/src/utils/async-semaphore.ts#L92)
+
+#### Inherited from
+
+[`BinarySemaphore`](BinarySemaphore.md).[`useDefaultTokens`](BinarySemaphore.md#usedefaulttokens)
 
 ***
 
 ### waiting
 
-> `readonly` **waiting**: `Deque`
+> `readonly` **waiting**: `Deque`\<`undefined` \| [`SemaphoreTaskItem`](../interfaces/SemaphoreTaskItem.md)\>
+
+Defined in: [packages/ai-tool/src/utils/async-semaphore.ts:89](https://github.com/isdk/ai-tool.js/blob/6a89194ac34437a1bc58f7ec590cd22976939ca6/src/utils/async-semaphore.ts#L89)
+
+#### Inherited from
+
+[`BinarySemaphore`](BinarySemaphore.md).[`waiting`](BinarySemaphore.md#waiting)
+
+## Accessors
+
+### activeCount
+
+#### Get Signature
+
+> **get** **activeCount**(): `number`
+
+Defined in: [packages/ai-tool/src/utils/async-semaphore.ts:318](https://github.com/isdk/ai-tool.js/blob/6a89194ac34437a1bc58f7ec590cd22976939ca6/src/utils/async-semaphore.ts#L318)
+
+Get the total count of all active operations.
 
-#### Defined in
+This method returns the number of operations that are either:
+- Waiting in the queue to acquire the semaphore (`pendingCount`).
+- Already acquired the semaphore but have not yet released it.
 
-[packages/ai-tool/src/utils/async-semaphore.ts:152](https://github.com/isdk/ai-tool.js/blob/b0813174e9b350ae47231f8e5f885150313123b0/src/utils/async-semaphore.ts#L152)
+##### Returns
+
+`number`
+
+The total count of active operations, including both waiting and ongoing tasks.
+
+#### Inherited from
+
+[`BinarySemaphore`](BinarySemaphore.md).[`activeCount`](BinarySemaphore.md#activecount)
+
+***
+
+### pendingCount
+
+#### Get Signature
+
+> **get** **pendingCount**(): `number`
+
+Defined in: [packages/ai-tool/src/utils/async-semaphore.ts:327](https://github.com/isdk/ai-tool.js/blob/6a89194ac34437a1bc58f7ec590cd22976939ca6/src/utils/async-semaphore.ts#L327)
+
+Get the number of callers waiting on the semaphore, i.e. the number of pending promises.
+
+##### Returns
+
+`number`
+
+The number of waiters in the waiting list.
+
+#### Inherited from
+
+[`BinarySemaphore`](BinarySemaphore.md).[`pendingCount`](BinarySemaphore.md#pendingcount)
 
 ## Methods
 
+### \_dispatchTask()
+
+> **\_dispatchTask**(`task`, `options`?): `void`
+
+Defined in: [packages/ai-tool/src/utils/async-semaphore.ts:212](https://github.com/isdk/ai-tool.js/blob/6a89194ac34437a1bc58f7ec590cd22976939ca6/src/utils/async-semaphore.ts#L212)
+
+#### Parameters
+
+##### task
+
+[`SemaphoreTaskItem`](../interfaces/SemaphoreTaskItem.md)
+
+##### options?
+
+[`BinarySemaphoreReleaseOptions`](../interfaces/BinarySemaphoreReleaseOptions.md)
+
+#### Returns
+
+`void`
+
+#### Inherited from
+
+[`BinarySemaphore`](BinarySemaphore.md).[`_dispatchTask`](BinarySemaphore.md#_dispatchtask)
+
+***
+
+### \_newReleaser()
+
+> **\_newReleaser**(`options`?): [`BinarySemaphoreReleaserFunc`](../interfaces/BinarySemaphoreReleaserFunc.md)
+
+Defined in: [packages/ai-tool/src/utils/async-semaphore.ts:199](https://github.com/isdk/ai-tool.js/blob/6a89194ac34437a1bc58f7ec590cd22976939ca6/src/utils/async-semaphore.ts#L199)
+
+#### Parameters
+
+##### options?
+
+[`BinarySemaphoreReleaseOptions`](../interfaces/BinarySemaphoreReleaseOptions.md)
+
+#### Returns
+
+[`BinarySemaphoreReleaserFunc`](../interfaces/BinarySemaphoreReleaserFunc.md)
+
+#### Inherited from
+
+[`BinarySemaphore`](BinarySemaphore.md).[`_newReleaser`](BinarySemaphore.md#_newreleaser)
+
+***
+
+### abort()
+
+> **abort**(`reason`?): `void`
+
+Defined in: [packages/ai-tool/src/utils/async-semaphore.ts:301](https://github.com/isdk/ai-tool.js/blob/6a89194ac34437a1bc58f7ec590cd22976939ca6/src/utils/async-semaphore.ts#L301)
+
+#### Parameters
+
+##### reason?
+
+`any`
+
+#### Returns
+
+`void`
+
+#### Inherited from
+
+[`BinarySemaphore`](BinarySemaphore.md).[`abort`](BinarySemaphore.md#abort)
+
+***
+
 ### acquire()
 
-> **acquire**(`signal`?): `Promise`\<`any`\>
+> **acquire**(`options`?): `Promise`\<[`BinarySemaphoreReleaserFunc`](../interfaces/BinarySemaphoreReleaserFunc.md)\>
+
+Defined in: [packages/ai-tool/src/utils/async-semaphore.ts:243](https://github.com/isdk/ai-tool.js/blob/6a89194ac34437a1bc58f7ec590cd22976939ca6/src/utils/async-semaphore.ts#L243)
 
 Acquire a token from the semaphore, thus decrement the number of available execution slots. If initFn is not used then the return value of the function can be discarded.
 
 #### Parameters
 
-• **signal?**: `AbortSignal`
+##### options?
+
+[`BinarySemaphoreAcquireOptions`](../interfaces/BinarySemaphoreAcquireOptions.md)
 
 #### Returns
 
-`Promise`\<`any`\>
+`Promise`\<[`BinarySemaphoreReleaserFunc`](../interfaces/BinarySemaphoreReleaserFunc.md)\>
 
-#### Defined in
+A promise that resolves to a release function when a token is acquired. If the semaphore is full, the caller will be added to a waiting queue.
 
-[packages/ai-tool/src/utils/async-semaphore.ts:265](https://github.com/isdk/ai-tool.js/blob/b0813174e9b350ae47231f8e5f885150313123b0/src/utils/async-semaphore.ts#L265)
+#### Inherited from
+
+[`BinarySemaphore`](BinarySemaphore.md).[`acquire`](BinarySemaphore.md#acquire)
 
 ***
 
@@ -112,66 +365,174 @@ Acquire a token from the semaphore, thus decrement the number of available execu
 
 > **drain**(): `Promise`\<`any`[]\>
 
+Defined in: [packages/ai-tool/src/utils/async-semaphore.ts:439](https://github.com/isdk/ai-tool.js/blob/6a89194ac34437a1bc58f7ec590cd22976939ca6/src/utils/async-semaphore.ts#L439)
+
 Drains the semaphore and returns all the initialized tokens in an array. Draining is an ideal way to ensure there are no pending async tasks, for example before a process will terminate.
 
 #### Returns
 
 `Promise`\<`any`[]\>
 
-#### Defined in
+#### Overrides
 
-[packages/ai-tool/src/utils/async-semaphore.ts:301](https://github.com/isdk/ai-tool.js/blob/b0813174e9b350ae47231f8e5f885150313123b0/src/utils/async-semaphore.ts#L301)
+[`BinarySemaphore`](BinarySemaphore.md).[`drain`](BinarySemaphore.md#drain)
 
 ***
 
-### pendingCount()
+### init()
 
-> **pendingCount**(): `number`
+> **init**(`options`): `void`
+
+Defined in: [packages/ai-tool/src/utils/async-semaphore.ts:193](https://github.com/isdk/ai-tool.js/blob/6a89194ac34437a1bc58f7ec590cd22976939ca6/src/utils/async-semaphore.ts#L193)
+
+#### Parameters
 
-Returns the number of callers waiting on the semaphore, i.e. the number of pending promises.
+##### options
+
+[`BinarySemaphoreOptions`](../interfaces/BinarySemaphoreOptions.md)
 
 #### Returns
 
-`number`
+`void`
 
-The number of waiters in the waiting list.
+#### Inherited from
+
+[`BinarySemaphore`](BinarySemaphore.md).[`init`](BinarySemaphore.md#init)
+
+***
+
+### initFree()
+
+> **initFree**(`options`): `void`
+
+Defined in: [packages/ai-tool/src/utils/async-semaphore.ts:408](https://github.com/isdk/ai-tool.js/blob/6a89194ac34437a1bc58f7ec590cd22976939ca6/src/utils/async-semaphore.ts#L408)
+
+#### Parameters
+
+##### options
+
+[`SemaphoreOptions`](../interfaces/SemaphoreOptions.md)
 
-#### Defined in
+#### Returns
+
+`void`
+
+#### Overrides
+
+[`BinarySemaphore`](BinarySemaphore.md).[`initFree`](BinarySemaphore.md#initfree)
+
+***
+
+### lock()
+
+> **lock**(`options`?): `any`
+
+Defined in: [packages/ai-tool/src/utils/async-semaphore.ts:435](https://github.com/isdk/ai-tool.js/blob/6a89194ac34437a1bc58f7ec590cd22976939ca6/src/utils/async-semaphore.ts#L435)
+
+#### Parameters
+
+##### options?
+
+[`BinarySemaphoreAcquireOptions`](../interfaces/BinarySemaphoreAcquireOptions.md)
+
+#### Returns
+
+`any`
+
+#### Overrides
+
+[`BinarySemaphore`](BinarySemaphore.md).[`lock`](BinarySemaphore.md#lock)
+
+***
+
+### onReleased()
+
+> **onReleased**(`options`?): `void`
+
+Defined in: [packages/ai-tool/src/utils/async-semaphore.ts:177](https://github.com/isdk/ai-tool.js/blob/6a89194ac34437a1bc58f7ec590cd22976939ca6/src/utils/async-semaphore.ts#L177)
+
+#### Parameters
+
+##### options?
+
+[`BinarySemaphoreReleaseOptions`](../interfaces/BinarySemaphoreReleaseOptions.md)
 
-[packages/ai-tool/src/utils/async-semaphore.ts:314](https://github.com/isdk/ai-tool.js/blob/b0813174e9b350ae47231f8e5f885150313123b0/src/utils/async-semaphore.ts#L314)
+#### Returns
+
+`void`
+
+#### Inherited from
+
+[`BinarySemaphore`](BinarySemaphore.md).[`onReleased`](BinarySemaphore.md#onreleased)
 
 ***
 
 ### release()
 
-> **release**(`token`?): `void`
+> **release**(`options`?): `void`
+
+Defined in: [packages/ai-tool/src/utils/async-semaphore.ts:288](https://github.com/isdk/ai-tool.js/blob/6a89194ac34437a1bc58f7ec590cd22976939ca6/src/utils/async-semaphore.ts#L288)
 
-Release the semaphore, thus increment the number of free execution slots. If initFn is used then the token returned by acquire() should be given as an argument when calling this function.
+Releases the semaphore, incrementing the number of free execution slots. If there are tasks in the waiting queue, the next task will be dispatched.
 
 #### Parameters
 
-• **token?**: `any`
+##### options?
+
+[`BinarySemaphoreReleaseOptions`](../interfaces/BinarySemaphoreReleaseOptions.md)
 
 #### Returns
 
 `void`
 
-#### Defined in
+#### Inherited from
 
-[packages/ai-tool/src/utils/async-semaphore.ts:294](https://github.com/isdk/ai-tool.js/blob/b0813174e9b350ae47231f8e5f885150313123b0/src/utils/async-semaphore.ts#L294)
+[`BinarySemaphore`](BinarySemaphore.md).[`release`](BinarySemaphore.md#release)
 
 ***
 
 ### tryAcquire()
 
-> **tryAcquire**(): `any`
+> **tryAcquire**(`options`?): `any`
+
+Defined in: [packages/ai-tool/src/utils/async-semaphore.ts:416](https://github.com/isdk/ai-tool.js/blob/6a89194ac34437a1bc58f7ec590cd22976939ca6/src/utils/async-semaphore.ts#L416)
 
 Attempt to acquire a token from the semaphore, if one is available immediately. Otherwise, return undefined.
 
+#### Parameters
+
+##### options?
+
+[`BinarySemaphoreAcquireOptions`](../interfaces/BinarySemaphoreAcquireOptions.md)
+
 #### Returns
 
 `any`
 
-#### Defined in
+Returns a token if the semaphore is not full; otherwise, returns `undefined`.
+
+#### Overrides
+
+[`BinarySemaphore`](BinarySemaphore.md).[`tryAcquire`](BinarySemaphore.md#tryacquire)
+
+***
+
+### unlock()
+
+> **unlock**(`token`?): `void`
+
+Defined in: [packages/ai-tool/src/utils/async-semaphore.ts:431](https://github.com/isdk/ai-tool.js/blob/6a89194ac34437a1bc58f7ec590cd22976939ca6/src/utils/async-semaphore.ts#L431)
+
+#### Parameters
+
+##### token?
+
+`any`
+
+#### Returns
+
+`void`
+
+#### Overrides
 
-[packages/ai-tool/src/utils/async-semaphore.ts:258](https://github.com/isdk/ai-tool.js/blob/b0813174e9b350ae47231f8e5f885150313123b0/src/utils/async-semaphore.ts#L258)
+[`BinarySemaphore`](BinarySemaphore.md).[`unlock`](BinarySemaphore.md#unlock)