@isdk/util 0.3.1 → 0.3.3

package/docs/classes/BinarySemaphore.md

@@ -0,0 +1,418 @@
+[**@isdk/util**](../README.md)
+
+***
+
+[@isdk/util](../globals.md) / BinarySemaphore
+
+# Class: BinarySemaphore
+
+Defined in: [src/async-semaphore.ts:88](https://github.com/isdk/util.js/blob/f6ac1e1b241d01211870dd55d000c1e9d4daa404/src/async-semaphore.ts#L88)
+
+A binary semaphore implementation for managing concurrency in asynchronous operations.
+Unlike a general semaphore, a binary semaphore allows only one caller to acquire the semaphore at a time.
+It provides methods to acquire, release, and manage waiting tasks efficiently.
+
+Example usage:
+
+```typescript
+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
+  }
+);
+
+async function fetchData(x) {
+  await semaphore.acquire()
+  try {
+    console.log(semaphore.pendingCount + ' calls to fetch are waiting')
+    // ... do some async stuff with x
+  } finally {
+    semaphore.release();
+  }
+}
+
+const data = await Promise.all(array.map(fetchData));
+```
+
+## Extended by
+
+- [`Semaphore`](Semaphore.md)
+
+## Constructors
+
+### Constructor
+
+> **new BinarySemaphore**(`options`): `BinarySemaphore`
+
+Defined in: [src/async-semaphore.ts:145](https://github.com/isdk/util.js/blob/f6ac1e1b241d01211870dd55d000c1e9d4daa404/src/async-semaphore.ts#L145)
+
+Creates a binary semaphore object for managing concurrency in asynchronous operations.
+
+#### Parameters
+
+##### options
+
+[`BinarySemaphoreOptions`](../interfaces/BinarySemaphoreOptions.md) = `{}`
+
+#### Returns
+
+`BinarySemaphore`
+
+## Properties
+
+### \_activeCount
+
+> `protected` **\_activeCount**: `number`
+
+Defined in: [src/async-semaphore.ts:97](https://github.com/isdk/util.js/blob/f6ac1e1b241d01211870dd55d000c1e9d4daa404/src/async-semaphore.ts#L97)
+
+***
+
+### emitter
+
+> `protected` **emitter**: `EventEmitter`
+
+Defined in: [src/async-semaphore.ts:91](https://github.com/isdk/util.js/blob/f6ac1e1b241d01211870dd55d000c1e9d4daa404/src/async-semaphore.ts#L91)
+
+***
+
+### free
+
+> `protected` **free**: `any`
+
+Defined in: [src/async-semaphore.ts:90](https://github.com/isdk/util.js/blob/f6ac1e1b241d01211870dd55d000c1e9d4daa404/src/async-semaphore.ts#L90)
+
+***
+
+### initTokenFn()
+
+> `protected` **initTokenFn**: (`token`?) => `void`
+
+Defined in: [src/async-semaphore.ts:95](https://github.com/isdk/util.js/blob/f6ac1e1b241d01211870dd55d000c1e9d4daa404/src/async-semaphore.ts#L95)
+
+#### Parameters
+
+##### token?
+
+`any`
+
+#### Returns
+
+`void`
+
+***
+
+### paused
+
+> `protected` **paused**: `boolean`
+
+Defined in: [src/async-semaphore.ts:96](https://github.com/isdk/util.js/blob/f6ac1e1b241d01211870dd55d000c1e9d4daa404/src/async-semaphore.ts#L96)
+
+***
+
+### pauseFn()?
+
+> `protected` `optional` **pauseFn**: () => `void`
+
+Defined in: [src/async-semaphore.ts:93](https://github.com/isdk/util.js/blob/f6ac1e1b241d01211870dd55d000c1e9d4daa404/src/async-semaphore.ts#L93)
+
+#### Returns
+
+`void`
+
+***
+
+### resumeFn()?
+
+> `protected` `optional` **resumeFn**: () => `void`
+
+Defined in: [src/async-semaphore.ts:94](https://github.com/isdk/util.js/blob/f6ac1e1b241d01211870dd55d000c1e9d4daa404/src/async-semaphore.ts#L94)
+
+#### Returns
+
+`void`
+
+***
+
+### useDefaultTokens
+
+> `protected` **useDefaultTokens**: `boolean`
+
+Defined in: [src/async-semaphore.ts:92](https://github.com/isdk/util.js/blob/f6ac1e1b241d01211870dd55d000c1e9d4daa404/src/async-semaphore.ts#L92)
+
+***
+
+### waiting
+
+> `readonly` **waiting**: [`Deque`](Deque.md)\<`undefined` \| [`SemaphoreTaskItem`](../interfaces/SemaphoreTaskItem.md)\>
+
+Defined in: [src/async-semaphore.ts:89](https://github.com/isdk/util.js/blob/f6ac1e1b241d01211870dd55d000c1e9d4daa404/src/async-semaphore.ts#L89)
+
+## Accessors
+
+### activeCount
+
+#### Get Signature
+
+> **get** **activeCount**(): `number`
+
+Defined in: [src/async-semaphore.ts:318](https://github.com/isdk/util.js/blob/f6ac1e1b241d01211870dd55d000c1e9d4daa404/src/async-semaphore.ts#L318)
+
+Get the total count of all active operations.
+
+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.
+
+##### Returns
+
+`number`
+
+The total count of active operations, including both waiting and ongoing tasks.
+
+***
+
+### pendingCount
+
+#### Get Signature
+
+> **get** **pendingCount**(): `number`
+
+Defined in: [src/async-semaphore.ts:327](https://github.com/isdk/util.js/blob/f6ac1e1b241d01211870dd55d000c1e9d4daa404/src/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.
+
+## Methods
+
+### \_dispatchTask()
+
+> **\_dispatchTask**(`task`, `options`?): `void`
+
+Defined in: [src/async-semaphore.ts:212](https://github.com/isdk/util.js/blob/f6ac1e1b241d01211870dd55d000c1e9d4daa404/src/async-semaphore.ts#L212)
+
+#### Parameters
+
+##### task
+
+[`SemaphoreTaskItem`](../interfaces/SemaphoreTaskItem.md)
+
+##### options?
+
+[`BinarySemaphoreReleaseOptions`](../interfaces/BinarySemaphoreReleaseOptions.md)
+
+#### Returns
+
+`void`
+
+***
+
+### \_newReleaser()
+
+> **\_newReleaser**(`options`?): [`BinarySemaphoreReleaserFunc`](../interfaces/BinarySemaphoreReleaserFunc.md)
+
+Defined in: [src/async-semaphore.ts:199](https://github.com/isdk/util.js/blob/f6ac1e1b241d01211870dd55d000c1e9d4daa404/src/async-semaphore.ts#L199)
+
+#### Parameters
+
+##### options?
+
+[`BinarySemaphoreReleaseOptions`](../interfaces/BinarySemaphoreReleaseOptions.md)
+
+#### Returns
+
+[`BinarySemaphoreReleaserFunc`](../interfaces/BinarySemaphoreReleaserFunc.md)
+
+***
+
+### abort()
+
+> **abort**(`reason`?): `void`
+
+Defined in: [src/async-semaphore.ts:301](https://github.com/isdk/util.js/blob/f6ac1e1b241d01211870dd55d000c1e9d4daa404/src/async-semaphore.ts#L301)
+
+#### Parameters
+
+##### reason?
+
+`any`
+
+#### Returns
+
+`void`
+
+***
+
+### acquire()
+
+> **acquire**(`options`?): `Promise`\<[`BinarySemaphoreReleaserFunc`](../interfaces/BinarySemaphoreReleaserFunc.md)\>
+
+Defined in: [src/async-semaphore.ts:243](https://github.com/isdk/util.js/blob/f6ac1e1b241d01211870dd55d000c1e9d4daa404/src/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
+
+##### options?
+
+[`BinarySemaphoreAcquireOptions`](../interfaces/BinarySemaphoreAcquireOptions.md)
+
+#### Returns
+
+`Promise`\<[`BinarySemaphoreReleaserFunc`](../interfaces/BinarySemaphoreReleaserFunc.md)\>
+
+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.
+
+***
+
+### drain()
+
+> **drain**(): `Promise`\<`any`[]\>
+
+Defined in: [src/async-semaphore.ts:296](https://github.com/isdk/util.js/blob/f6ac1e1b241d01211870dd55d000c1e9d4daa404/src/async-semaphore.ts#L296)
+
+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`[]\>
+
+***
+
+### init()
+
+> **init**(`options`): `void`
+
+Defined in: [src/async-semaphore.ts:193](https://github.com/isdk/util.js/blob/f6ac1e1b241d01211870dd55d000c1e9d4daa404/src/async-semaphore.ts#L193)
+
+#### Parameters
+
+##### options
+
+[`BinarySemaphoreOptions`](../interfaces/BinarySemaphoreOptions.md)
+
+#### Returns
+
+`void`
+
+***
+
+### initFree()
+
+> **initFree**(`options`?): `void`
+
+Defined in: [src/async-semaphore.ts:173](https://github.com/isdk/util.js/blob/f6ac1e1b241d01211870dd55d000c1e9d4daa404/src/async-semaphore.ts#L173)
+
+#### Parameters
+
+##### options?
+
+[`BinarySemaphoreOptions`](../interfaces/BinarySemaphoreOptions.md)
+
+#### Returns
+
+`void`
+
+***
+
+### lock()
+
+> **lock**(`options`?): `any`
+
+Defined in: [src/async-semaphore.ts:217](https://github.com/isdk/util.js/blob/f6ac1e1b241d01211870dd55d000c1e9d4daa404/src/async-semaphore.ts#L217)
+
+#### Parameters
+
+##### options?
+
+[`BinarySemaphoreAcquireOptions`](../interfaces/BinarySemaphoreAcquireOptions.md)
+
+#### Returns
+
+`any`
+
+***
+
+### onReleased()
+
+> **onReleased**(`options`?): `void`
+
+Defined in: [src/async-semaphore.ts:177](https://github.com/isdk/util.js/blob/f6ac1e1b241d01211870dd55d000c1e9d4daa404/src/async-semaphore.ts#L177)
+
+#### Parameters
+
+##### options?
+
+[`BinarySemaphoreReleaseOptions`](../interfaces/BinarySemaphoreReleaseOptions.md)
+
+#### Returns
+
+`void`
+
+***
+
+### release()
+
+> **release**(`options`?): `void`
+
+Defined in: [src/async-semaphore.ts:288](https://github.com/isdk/util.js/blob/f6ac1e1b241d01211870dd55d000c1e9d4daa404/src/async-semaphore.ts#L288)
+
+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
+
+##### options?
+
+[`BinarySemaphoreReleaseOptions`](../interfaces/BinarySemaphoreReleaseOptions.md)
+
+#### Returns
+
+`void`
+
+***
+
+### tryAcquire()
+
+> **tryAcquire**(`options`?): `any`
+
+Defined in: [src/async-semaphore.ts:234](https://github.com/isdk/util.js/blob/f6ac1e1b241d01211870dd55d000c1e9d4daa404/src/async-semaphore.ts#L234)
+
+Attempt to acquire a token from the semaphore, if one is available immediately. Otherwise, return undefined.
+
+#### Parameters
+
+##### options?
+
+[`BinarySemaphoreAcquireOptions`](../interfaces/BinarySemaphoreAcquireOptions.md)
+
+#### Returns
+
+`any`
+
+Returns a token if the semaphore is not full; otherwise, returns `undefined`.
+
+***
+
+### unlock()
+
+> **unlock**(`token`?): `void`
+
+Defined in: [src/async-semaphore.ts:225](https://github.com/isdk/util.js/blob/f6ac1e1b241d01211870dd55d000c1e9d4daa404/src/async-semaphore.ts#L225)
+
+#### Parameters
+
+##### token?
+
+`any`
+
+#### Returns
+
+`void`

package/docs/classes/ConfigFile.md

@@ -6,7 +6,7 @@
 
 # Class: ConfigFile
 
-Defined in: [config-file.ts:46](https://github.com/isdk/util.js/blob/37cf8e647afe115375188dc281429b45345985c4/src/config-file.ts#L46)
+Defined in: [src/config-file.ts:46](https://github.com/isdk/util.js/blob/f6ac1e1b241d01211870dd55d000c1e9d4daa404/src/config-file.ts#L46)
 
 Represents a configuration file utility class that provides methods to load and save configuration files.
 It supports multiple file formats such as YAML, JSON, etc., by registering corresponding parsers and stringifiers.
@@ -45,17 +45,66 @@ console.log(config); // Output: { key: 'value' }
 
 > `static` **stringifys**: `Record`\<`string`, [`StringifyFunc`](../type-aliases/StringifyFunc.md)\> = `{}`
 
-Defined in: [config-file.ts:50](https://github.com/isdk/util.js/blob/37cf8e647afe115375188dc281429b45345985c4/src/config-file.ts#L50)
+Defined in: [src/config-file.ts:50](https://github.com/isdk/util.js/blob/f6ac1e1b241d01211870dd55d000c1e9d4daa404/src/config-file.ts#L50)
 
 A record of registered stringify functions for different file extensions.
 
 ## Methods
 
+### existsSync()
+
+> `static` **existsSync**(`filename`, `options`?): `boolean`
+
+Defined in: [src/config-file.ts:132](https://github.com/isdk/util.js/blob/f6ac1e1b241d01211870dd55d000c1e9d4daa404/src/config-file.ts#L132)
+
+Checks if a configuration file exists at the specified path.
+
+This method normalizes the filename by removing the extension (if present) and then delegates
+to the underlying LoadConfigFile utility to perform the existence check. The normalization
+ensures consistent handling of files regardless of whether they include extensions in the
+provided filename.
+
+#### Parameters
+
+##### filename
+
+`string`
+
+The path to the configuration file to check for existence.
+                 This can include or omit the file extension.
+
+##### options?
+
+[`LoadConfigFileOptions`](../interfaces/LoadConfigFileOptions.md)
+
+Optional configuration options that may affect how the file existence
+                is checked, including extension level handling.
+
+#### Returns
+
+`boolean`
+
+`true` if the configuration file exists, `false` otherwise.
+
+#### Example
+
+```typescript
+// Check if a YAML config file exists
+const exists = ConfigFile.existsSync('config.yaml');
+console.log(exists); // true or false
+
+// Check with options
+const existsWithExt = ConfigFile.existsSync('config', { extLevel: 2 });
+console.log(existsWithExt); // true or false
+```
+
+***
+
 ### loadSync()
 
 > `static` **loadSync**(`filename`, `options`?): `any`
 
-Defined in: [config-file.ts:85](https://github.com/isdk/util.js/blob/37cf8e647afe115375188dc281429b45345985c4/src/config-file.ts#L85)
+Defined in: [src/config-file.ts:85](https://github.com/isdk/util.js/blob/f6ac1e1b241d01211870dd55d000c1e9d4daa404/src/config-file.ts#L85)
 
 Loads a configuration file based on the provided filename and options.
 
@@ -92,7 +141,7 @@ console.log(config); // Output: { key: 'value' }
 
 > `static` **register**(`extname`, `parser`, `stringify`): `void`
 
-Defined in: [config-file.ts:64](https://github.com/isdk/util.js/blob/37cf8e647afe115375188dc281429b45345985c4/src/config-file.ts#L64)
+Defined in: [src/config-file.ts:64](https://github.com/isdk/util.js/blob/f6ac1e1b241d01211870dd55d000c1e9d4daa404/src/config-file.ts#L64)
 
 Registers a parser and stringifier for specific file extensions.
 
@@ -132,7 +181,7 @@ ConfigFile.register(['.json'], JSON.parse, (obj) => JSON.stringify(obj, null, 2)
 
 > `static` **saveSync**(`filename`, `config`, `options`?): `string`
 
-Defined in: [config-file.ts:102](https://github.com/isdk/util.js/blob/37cf8e647afe115375188dc281429b45345985c4/src/config-file.ts#L102)
+Defined in: [src/config-file.ts:102](https://github.com/isdk/util.js/blob/f6ac1e1b241d01211870dd55d000c1e9d4daa404/src/config-file.ts#L102)
 
 Saves a configuration object to a file with the specified filename and options.