@asaidimu/utils-sync 1.0.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Saidimu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,413 @@
+# `@asaidimu/utils-sync`
+
+> **Synchronization primitives for TypeScript/JavaScript** – Mutex, Once, and Serializer utilities with fine‑grained concurrency control.
+
+[![npm version](https://img.shields.io/npm/v/@asaidimu/utils-sync.svg)](https://www.npmjs.com/package/@asaidimu/utils-sync)
+[![license](https://img.shields.io/npm/l/@asaidimu/utils-sync.svg)](https://github.com/asaidimu/erp-utils/blob/main/LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue)](https://www.typescriptlang.org/)
+[![vitest](https://img.shields.io/badge/tested%20with-vitest-6b9f3e)](https://vitest.dev/)
+
+## Table of Contents
+
+- [Overview & Features](#overview--features)
+- [Installation & Setup](#installation--setup)
+- [Usage Documentation](#usage-documentation)
+  - [Mutex](#mutex)
+  - [Once](#once)
+  - [Serializer](#serializer)
+- [Project Architecture](#project-architecture)
+- [Development & Contributing](#development--contributing)
+- [Additional Information](#additional-information)
+
+---
+
+## Overview & Features
+
+Modern JavaScript applications often face subtle concurrency issues – race conditions, duplicate work, or unexpected interleaving of async operations. `@asaidimu/utils-sync` provides three battle‑tested primitives to tame asynchronous chaos:
+
+- **`Mutex`** – A mutual exclusion lock that allows only one task at a time to access a shared resource. Configurable handoff scheduling (microtask vs macrotask) prevents microtask starvation under heavy contention.
+- **`Once`** – Guarantees that a given asynchronous operation runs exactly once, even when called concurrently from many places. Ideal for lazy initialisation, cache population, or one‑time setup. Supports optional retry on failure and sync/async functions.
+- **`Serializer`** – Processes queued tasks sequentially (FIFO) while maintaining the last successful result. Built‑in backpressure protection and the ability to permanently close the queue. Perfect for rate‑limited APIs, write serialisation, or sequential job processing.
+
+All utilities are written in strict TypeScript, fully typed, and come with zero runtime dependencies.
+
+### Key Features
+
+- **Mutual exclusion** – `Mutex` with optional timeout and queue capacity limits.
+- **Configurable yield behaviour** – Choose `"macrotask"` (default, prevents starvation) or `"microtask"` (zero‑delay handoff) per instance.
+- **Once‑only execution** – `Once` deduplicates concurrent calls, caches success/failure, and optionally retries on error.
+- **Sequential task processing** – `Serializer` maintains order, provides last‑result peeking, and can be closed permanently.
+- **Timeout support** – All operations accept a timeout parameter (lock acquisition + execution).
+- **Backpressure** – Configurable queue size to prevent uncontrolled growth.
+- **Tiny & focused** – No external dependencies, tree‑shakeable exports.
+- **First‑class TypeScript** – Generics, error types, and accurate return types.
+
+---
+
+## Installation & Setup
+
+### Prerequisites
+
+- **Node.js** 18+ (or any modern environment with `Promise`, `queueMicrotask`, and `setTimeout`)
+- **TypeScript** 4.7+ (if using types, but not required)
+
+### Installation
+
+```bash
+npm install @asaidimu/utils-sync
+```
+
+```bash
+pnpm add @asaidimu/utils-sync
+```
+
+```bash
+yarn add @asaidimu/utils-sync
+```
+
+### Verification
+
+After installation, you can test that the library works correctly:
+
+```typescript
+import { Mutex } from '@asaidimu/utils-sync';
+
+const mutex = new Mutex();
+console.log(mutex.locked()); // false
+```
+
+If the import runs without errors, the package is ready.
+
+---
+
+## Usage Documentation
+
+All examples assume ES module import syntax:
+
+```typescript
+import { Mutex, Once, Serializer } from '@asaidimu/utils-sync';
+```
+
+For CommonJS:
+
+```javascript
+const { Mutex, Once, Serializer } = require('@asaidimu/utils-sync');
+```
+
+---
+
+### Mutex
+
+A mutual exclusion lock. Use it to protect critical sections where only one async operation should run at a time.
+
+#### Basic example
+
+```typescript
+const mutex = new Mutex();
+
+async function criticalSection() {
+  await mutex.lock();
+  try {
+    // Only one caller executes this block at a time
+    await doSomething();
+  } finally {
+    mutex.unlock();
+  }
+}
+```
+
+#### With timeout
+
+```typescript
+try {
+  await mutex.lock(1000); // wait max 1 second
+  // ... work ...
+  mutex.unlock();
+} catch (err) {
+  if (err instanceof TimeoutError) {
+    console.log('Could not acquire lock in time');
+  }
+}
+```
+
+#### Non‑blocking attempt
+
+```typescript
+if (mutex.tryLock()) {
+  try {
+    // lock acquired immediately
+  } finally {
+    mutex.unlock();
+  }
+} else {
+  // lock was already held – do something else
+}
+```
+
+#### Options
+
+| Option       | Type                     | Default       | Description                                                                                   |
+|--------------|--------------------------|---------------|-----------------------------------------------------------------------------------------------|
+| `capacity`   | `number`                 | `Infinity`    | Max pending waiters. If exceeded, `lock()` throws an error.                                   |
+| `yieldMode`  | `"macrotask"` \| `"microtask"` | `"macrotask"` | `"macrotask"` yields via `setTimeout(…,0)` (prevents starvation). `"microtask"` uses `queueMicrotask` for lower latency. |
+
+#### API
+
+| Method                       | Return type           | Description                                                                                             |
+|------------------------------|-----------------------|---------------------------------------------------------------------------------------------------------|
+| `lock(timeout?: number)`     | `Promise<void>`       | Acquire lock, waiting if necessary. Throws `TimeoutError` if timeout elapses or queue is full.          |
+| `tryLock()`                  | `boolean`             | Attempt to acquire lock without waiting. Returns `true` if acquired.                                   |
+| `unlock()`                   | `void`                | Release the lock. Throws if not locked. Schedules next waiter according to `yieldMode`.                 |
+| `locked()`                   | `boolean`             | Returns `true` if the lock is currently held.                                                           |
+| `pending()`                  | `number`              | Number of tasks waiting for the lock.                                                                   |
+
+---
+
+### Once
+
+Guarantees a function runs exactly once, even when many callers invoke `do()` concurrently. The result (or error) is cached and returned to all future callers.
+
+#### Basic example
+
+```typescript
+const once = new Once<string>();
+
+async function getConfig() {
+  const result = await once.do(async () => {
+    const res = await fetch('/api/config');
+    return res.json();
+  });
+  // result.value contains the config, or result.error if failed
+  return result.value;
+}
+```
+
+#### With retry on failure
+
+```typescript
+const once = new Once<string>({ retry: true });
+
+// If the first attempt fails, the next call will retry
+await once.do(failingFn); // fails, but _done = false
+await once.do(successFn); // runs again, succeeds, caches result
+```
+
+#### Synchronous functions
+
+```typescript
+const once = new Once<number>();
+const result = await once.do(() => 42); // works with sync return
+```
+
+#### Checking state without awaiting
+
+```typescript
+if (once.isReady()) {
+  const { value, error } = once.peek();
+  // safely inspect cached result
+}
+```
+
+#### Options
+
+| Option    | Type      | Default | Description                                                                      |
+|-----------|-----------|---------|----------------------------------------------------------------------------------|
+| `retry`   | `boolean` | `false` | If `true`, a failed execution does **not** mark the instance as done – next call will retry. |
+| `throws`  | `boolean` | `false` | If `true`, the `do()` method will **throw** the error instead of returning it in the result object. |
+
+#### API
+
+| Method                            | Return type                         | Description                                                                                       |
+|-----------------------------------|-------------------------------------|---------------------------------------------------------------------------------------------------|
+| `do(fn, timeout?)`                | `Promise<OnceResult<T>>`            | Executes `fn` once. Returns `{ value, error }` (unless `throws:true`). Timeout covers lock + execution. |
+| `isReady()`                       | `boolean`                           | `true` if operation has completed (success or non‑retryable failure) and no execution is running. |
+| `running()`                       | `boolean`                           | `true` if the operation is currently executing.                                                   |
+| `peek()`                          | `OnceResult<T>`                     | Returns current cached `{ value, error }` without waiting.                                        |
+| `get()`                           | `T \| null`                         | Returns cached value if done, otherwise throws. Throws cached error if present.                   |
+| `reset()`                         | `void`                              | Clears state – next `do()` will run again.                                                        |
+| `done()`                          | `boolean`                           | `true` if finished (success or final failure).                                                    |
+| `resolved()`                      | `Promise<OnceResult<T>> \| null`    | Returns the underlying promise if running or done, otherwise `null`.                              |
+
+---
+
+### Serializer
+
+Processes tasks sequentially (FIFO order). Each task runs only after all previous tasks have completed. Use it to serialise writes to a file, throttle API calls, or enforce ordering.
+
+#### Basic example
+
+```typescript
+const serializer = new Serializer<string>();
+
+async function log(message: string) {
+  const result = await serializer.do(async () => {
+    await appendToFile('log.txt', message);
+    return message;
+  });
+  return result.value; // last successful result
+}
+```
+
+#### Handling failures
+
+Even if a task fails, the serializer continues processing the next queued tasks:
+
+```typescript
+await serializer.do(failingFn);      // returns { error: ... }
+await serializer.do(successfulFn);   // still runs
+```
+
+#### Peeking at the last result
+
+```typescript
+const { value, error } = serializer.peek();
+```
+
+#### Closing the serializer permanently
+
+```typescript
+serializer.close();
+const result = await serializer.do(anyFn);
+// result.error instanceof SerializerExecutionDone
+```
+
+#### Options
+
+| Option       | Type                     | Default    | Description                                                      |
+|--------------|--------------------------|------------|------------------------------------------------------------------|
+| `capacity`   | `number`                 | `1000`     | Max pending tasks. When full, `do()` returns an error immediately. |
+| `yieldMode`  | `"macrotask"` \| `"microtask"` | `"macrotask"` | Handoff scheduling for the internal mutex. Default prevents microtask starvation. |
+
+#### API
+
+| Method                        | Return type                          | Description                                                                                          |
+|-------------------------------|--------------------------------------|------------------------------------------------------------------------------------------------------|
+| `do(fn, timeout?)`            | `Promise<SerializerResult<T\|null>>` | Enqueues `fn`. Returns `{ value, error }`. If closed or queue full, error is `SerializerExecutionDone`. |
+| `peek()`                      | `SerializerResult<T\|null>`          | Returns the last successful result or last error.                                                    |
+| `close()`                     | `void`                               | Permanently closes the serializer. All subsequent `do()` calls fail immediately.                     |
+| `pending()`                   | `number`                             | Number of tasks waiting in the queue.                                                                |
+| `running()`                   | `boolean`                            | `true` if a task is currently executing.                                                             |
+
+---
+
+## Project Architecture
+
+The library is written in **TypeScript** and follows a simple, functional‑object design. Each class is independent and does not rely on shared global state.
+
+### Core Components
+
+- **`Mutex`** – Implements the lock with a FIFO waiter queue. Handoff uses either `setTimeout` (macrotask) or `queueMicrotask` to give callers control over fairness vs. latency.
+- **`Once`** – Built on top of `Mutex` with `microtask` yield mode for minimal overhead. Tracks execution state (`_done`, `_value`, `_error`) and returns a cached promise to concurrent callers.
+- **`Serializer`** – Also uses `Mutex` (default `macrotask` yield) to serialise work. Maintains the last result and supports backpressure via `capacity`.
+
+### Data Flow
+
+1. **Mutex** – Callers invoke `lock()`. If unlocked, they acquire immediately. Otherwise they are added to `waiters`. When `unlock()` is called, the next waiter is scheduled according to `yieldMode`.
+2. **Once** – First caller acquires the mutex, runs the function, and stores the promise. Later callers see the existing promise and await it directly (no mutex contention). After completion, the promise is cleared and `_done` is set.
+3. **Serializer** – Each `do()` call attempts to lock the internal mutex. Only one task holds the lock at a time. When a task finishes (success or error), the lock is released, allowing the next queued task to run.
+
+### Extension Points
+
+The library is designed to be used as‑is, but you can easily compose the primitives:
+
+- Use `Mutex` to build your own synchronisation patterns (e.g., read‑write locks).
+- Extend `Once` or `Serializer` by subclassing (both are standard ES6 classes).
+- Replace the underlying promise scheduling by providing a custom `Mutex` with different `yieldMode` logic (though the built‑in modes cover most needs).
+
+---
+
+## Development & Contributing
+
+### Development Setup
+
+```bash
+git clone https://github.com/asaidimu/erp-utils.git
+cd erp-utils/src/sync
+npm install
+```
+
+### Scripts
+
+| Command              | Description                                      |
+|----------------------|--------------------------------------------------|
+| `npm test`           | Run tests once (Vitest)                          |
+| `npm run test:watch` | Run tests in watch mode                          |
+| `npm run test:browser` | Run tests in a browser environment (Vitest)   |
+
+### Testing
+
+Tests are written with **Vitest** and cover:
+
+- `Once` – deduplication, retry behaviour, state transitions, error handling.
+- `Serializer` – FIFO ordering, backpressure, closing, error resilience.
+- `Mutex` – locking, timeout, capacity, yield modes (implicitly tested via Serializer and Once).
+
+To run the full suite:
+
+```bash
+npm test
+```
+
+### Contributing Guidelines
+
+1. **Fork** the repository and create a feature branch.
+2. **Write tests** for any new functionality or bug fixes.
+3. **Ensure existing tests pass** (`npm test`).
+4. **Follow the existing code style** (Prettier / ESLint – see root of monorepo).
+5. **Commit messages** should follow [Conventional Commits](https://www.conventionalcommits.org/) (e.g., `feat: add timeout to Mutex`).
+6. **Open a Pull Request** against the `main` branch.
+
+### Issue Reporting
+
+Report bugs or request features via [GitHub Issues](https://github.com/asaidimu/erp-utils/issues). Please include:
+
+- A clear description of the problem.
+- Minimal code to reproduce (if bug).
+- Environment details (Node version, package manager, OS).
+
+---
+
+## Additional Information
+
+### Troubleshooting
+
+| Problem                                      | Possible solution                                                                                     |
+|----------------------------------------------|-------------------------------------------------------------------------------------------------------|
+| `Mutex` lock never resolves                  | Check that `unlock()` is always called (e.g., use `try/finally`).                                     |
+| `Serializer` tasks stop running              | Did you call `close()`? Once closed, all new tasks fail immediately.                                  |
+| `Once` returns stale error even after retry  | Ensure `retry: true` is set. Without it, a failure marks `_done = true` and never retries.            |
+| `TimeoutError` when queue seems small        | Increase `capacity` in `Mutex` or `Serializer` options.                                               |
+| Microtask starvation in high‑contention code | Set `yieldMode: "macrotask"` (default for `Serializer` and `Mutex`). `Once` uses microtask by design. |
+
+### FAQ
+
+**Q: Can I use `Once` with a synchronous function?**  
+Yes – `Once.do()` accepts both `() => Promise<T>` and `() => T`. Synchronous return values are automatically wrapped in a resolved promise.
+
+**Q: What happens if `Once.do()` times out?**  
+The timeout applies to the entire operation (including waiting for the mutex and execution). If a timeout occurs, the `do()` call rejects with `TimeoutError`, but the background execution (if already started) continues. Future callers will receive the final result.
+
+**Q: Is `Serializer` safe for long‑running tasks?**  
+Absolutely. Tasks run sequentially, so a long task will delay subsequent tasks. Use `timeout` if you need to enforce a maximum wait per task.
+
+**Q: Can I reuse a `Once` instance after a non‑retryable failure?**  
+Yes – call `reset()` to clear the cached error and allow a fresh execution.
+
+**Q: Does `Mutex` re‑entrant?**  
+No – attempting to `lock()` from the same execution context that already holds the lock will deadlock. Use a single lock acquisition per critical section.
+
+### Changelog & Roadmap
+
+See the [CHANGELOG.md](https://github.com/asaidimu/erp-utils/blob/main/CHANGELOG.md) for version history. Future plans include:
+
+- `Semaphore` implementation.
+- `AsyncCondition` variable.
+- `DebouncedSerializer` for coalescing rapid consecutive calls.
+
+### License
+
+[MIT](https://github.com/asaidimu/erp-utils/blob/main/LICENSE) © Saidimu
+
+### Acknowledgments
+
+Inspired by similar synchronisation primitives in Rust (`Mutex`, `OnceCell`), Go (`sync.Mutex`), and the classic async patterns of the JavaScript ecosystem. Built with ❤️ using TypeScript and Vitest.

package/index.d.mts

@@ -0,0 +1,177 @@
+interface MutexOptions {
+    /**
+     * Maximum number of pending requests allowed in the queue.
+     * If exceeded, tryLock/lock will fail.
+     * @default Infinity
+     */
+    capacity?: number;
+    /**
+     * Controls how lock handoff is scheduled when a waiter is unblocked.
+     *
+     * - `"macrotask"` (default): Uses setTimeout(fn, 0) to yield to the event
+     *   loop between handoffs. Prevents microtask starvation under heavy
+     *   contention — I/O, rendering, and other macrotasks can run between
+     *   lock acquisitions. Use for invalidationSerializer and other
+     *   coarse-grained serializers.
+     *
+     * - `"microtask"`: Uses queueMicrotask(fn) for handoff. Near-zero latency
+     *   between acquisitions — no macrotask delay. Safe when you need
+     *   back-to-back operations to complete as fast as possible and starvation
+     *   is not a concern (e.g. buildOnce, streamSerializer where builds are
+     *   infrequent and latency matters more than fairness).
+     */
+    yieldMode?: "macrotask" | "microtask";
+}
+/**
+ * A mutual exclusion lock.
+ * Allows only one execution context to access a resource at a time.
+ *
+ * Yield mode is configurable per instance:
+ * - "macrotask" (default): yields between handoffs, preventing microtask starvation.
+ * - "microtask": zero-delay handoff for latency-sensitive paths.
+ */
+declare class Mutex {
+    private _locked;
+    private _capacity;
+    private _yieldMode;
+    private waiters;
+    constructor(options?: MutexOptions);
+    /**
+     * Acquires the lock. If already held, waits until released or timeout reached.
+     *
+     * @param timeout - Optional maximum wait time in milliseconds.
+     * @throws {TimeoutError} If the lock cannot be acquired within the timeout.
+     * @throws {Error} If the wait queue is full (backpressure).
+     */
+    lock(timeout?: number): Promise<void>;
+    /**
+     * Attempts to acquire the lock without waiting.
+     * @returns `true` if the lock was acquired, `false` otherwise.
+     */
+    tryLock(): boolean;
+    /**
+     * Releases the lock, scheduling the next waiter according to yieldMode.
+     * @throws {Error} If the mutex is not currently locked.
+     */
+    unlock(): void;
+    /** Returns true if the mutex is currently locked. */
+    locked(): boolean;
+    /** Returns the number of operations waiting for the lock. */
+    pending(): number;
+}
+type OnceResult<T> = {
+    value: T | null;
+    error?: unknown;
+};
+/**
+ * Ensures a specific task is executed exactly once, regardless of concurrent callers.
+ * Handles race conditions, caching, and optional retries on failure.
+ *
+ * Uses microtask yield mode for its internal mutex — builds are latency-sensitive
+ * and starvation is not a concern (only one build runs at a time by design).
+ *
+ * @template T - The type of value returned by the execution.
+ */
+declare class Once<T = void> {
+    private mutex;
+    private promise;
+    private _value;
+    private _error;
+    private _done;
+    private retry;
+    private throws;
+    constructor({ retry, throws }?: {
+        retry?: boolean;
+        throws?: boolean;
+    });
+    /**
+     * Execute the function if it hasn't been executed yet.
+     * Subsequent calls return the result of the first execution.
+     *
+     * @param fn - The function to execute.
+     * @param timeout - Max wait time in ms (includes lock wait + execution time).
+     */
+    do(fn: () => Promise<T> | T, timeout?: number): Promise<OnceResult<T>>;
+    /**
+     * Returns true if the operation has completed (success or non-retryable failure)
+     * and is not currently executing.
+     * Replaces the previous `done() && !running()` two-call pattern.
+     */
+    isReady(): boolean;
+    /**
+     * Returns true if the operation is currently executing.
+     */
+    running(): boolean;
+    /**
+     * Returns the current state without waiting.
+     */
+    peek(): OnceResult<T>;
+    /**
+     * Returns the stored value if successful, otherwise throws the stored error.
+     * Throws if the operation is not yet complete.
+     */
+    get(): T | null;
+    /**
+     * Resets the instance, allowing the action to run again on the next call.
+     */
+    reset(): void;
+    /**
+     * Returns the underlying promise if running or done, null otherwise.
+     */
+    resolved(): Promise<OnceResult<T>> | null;
+    /**
+     * Returns true if the operation has finished (success or final failure).
+     */
+    done(): boolean;
+    private _awaitWithTimeout;
+}
+type SerializerResult<T> = {
+    value: T | null;
+    error?: unknown;
+};
+interface SerializerOptions {
+    /**
+     * Max items in queue. If full, .do() returns an error immediately.
+     * @default 1000
+     */
+    capacity?: number;
+    /**
+     * Yield mode for the internal mutex. Defaults to "macrotask" for
+     * coarse-grained serializers (invalidationSerializer). Use "microtask"
+     * for fine-grained latency-sensitive serializers (streamSerializer).
+     */
+    yieldMode?: "macrotask" | "microtask";
+}
+/**
+ * Ensures tasks are executed sequentially (FIFO).
+ * Maintains the result of the last successful execution.
+ * Includes backpressure protection via configurable queue capacity.
+ */
+declare class Serializer<T = void> {
+    private mutex;
+    private _done;
+    private _lastValue;
+    private _lastError;
+    constructor(options?: SerializerOptions);
+    /**
+     * Enqueue a function to be executed after all previous tasks complete.
+     *
+     * @param fn - The function to execute.
+     * @param timeout - Max time to wait to acquire the lock.
+     * @returns Object containing the value or error.
+     */
+    do(fn: () => Promise<T> | T, timeout?: number): Promise<SerializerResult<T | null>>;
+    /** Returns the result of the last successful execution. */
+    peek(): SerializerResult<T | null>;
+    /**
+     * Permanently closes the serializer.
+     * Subsequent calls to `do()` will fail immediately with SerializerExecutionDone.
+     */
+    close(): void;
+    /** Returns the number of tasks currently waiting. */
+    pending(): number;
+    /** Returns true if a task is currently executing. */
+    running(): boolean;
+}
+
+export { Mutex, type MutexOptions, Once, type OnceResult, Serializer, type SerializerOptions, type SerializerResult };

package/index.d.ts

@@ -0,0 +1,177 @@
+interface MutexOptions {
+    /**
+     * Maximum number of pending requests allowed in the queue.
+     * If exceeded, tryLock/lock will fail.
+     * @default Infinity
+     */
+    capacity?: number;
+    /**
+     * Controls how lock handoff is scheduled when a waiter is unblocked.
+     *
+     * - `"macrotask"` (default): Uses setTimeout(fn, 0) to yield to the event
+     *   loop between handoffs. Prevents microtask starvation under heavy
+     *   contention — I/O, rendering, and other macrotasks can run between
+     *   lock acquisitions. Use for invalidationSerializer and other
+     *   coarse-grained serializers.
+     *
+     * - `"microtask"`: Uses queueMicrotask(fn) for handoff. Near-zero latency
+     *   between acquisitions — no macrotask delay. Safe when you need
+     *   back-to-back operations to complete as fast as possible and starvation
+     *   is not a concern (e.g. buildOnce, streamSerializer where builds are
+     *   infrequent and latency matters more than fairness).
+     */
+    yieldMode?: "macrotask" | "microtask";
+}
+/**
+ * A mutual exclusion lock.
+ * Allows only one execution context to access a resource at a time.
+ *
+ * Yield mode is configurable per instance:
+ * - "macrotask" (default): yields between handoffs, preventing microtask starvation.
+ * - "microtask": zero-delay handoff for latency-sensitive paths.
+ */
+declare class Mutex {
+    private _locked;
+    private _capacity;
+    private _yieldMode;
+    private waiters;
+    constructor(options?: MutexOptions);
+    /**
+     * Acquires the lock. If already held, waits until released or timeout reached.
+     *
+     * @param timeout - Optional maximum wait time in milliseconds.
+     * @throws {TimeoutError} If the lock cannot be acquired within the timeout.
+     * @throws {Error} If the wait queue is full (backpressure).
+     */
+    lock(timeout?: number): Promise<void>;
+    /**
+     * Attempts to acquire the lock without waiting.
+     * @returns `true` if the lock was acquired, `false` otherwise.
+     */
+    tryLock(): boolean;
+    /**
+     * Releases the lock, scheduling the next waiter according to yieldMode.
+     * @throws {Error} If the mutex is not currently locked.
+     */
+    unlock(): void;
+    /** Returns true if the mutex is currently locked. */
+    locked(): boolean;
+    /** Returns the number of operations waiting for the lock. */
+    pending(): number;
+}
+type OnceResult<T> = {
+    value: T | null;
+    error?: unknown;
+};
+/**
+ * Ensures a specific task is executed exactly once, regardless of concurrent callers.
+ * Handles race conditions, caching, and optional retries on failure.
+ *
+ * Uses microtask yield mode for its internal mutex — builds are latency-sensitive
+ * and starvation is not a concern (only one build runs at a time by design).
+ *
+ * @template T - The type of value returned by the execution.
+ */
+declare class Once<T = void> {
+    private mutex;
+    private promise;
+    private _value;
+    private _error;
+    private _done;
+    private retry;
+    private throws;
+    constructor({ retry, throws }?: {
+        retry?: boolean;
+        throws?: boolean;
+    });
+    /**
+     * Execute the function if it hasn't been executed yet.
+     * Subsequent calls return the result of the first execution.
+     *
+     * @param fn - The function to execute.
+     * @param timeout - Max wait time in ms (includes lock wait + execution time).
+     */
+    do(fn: () => Promise<T> | T, timeout?: number): Promise<OnceResult<T>>;
+    /**
+     * Returns true if the operation has completed (success or non-retryable failure)
+     * and is not currently executing.
+     * Replaces the previous `done() && !running()` two-call pattern.
+     */
+    isReady(): boolean;
+    /**
+     * Returns true if the operation is currently executing.
+     */
+    running(): boolean;
+    /**
+     * Returns the current state without waiting.
+     */
+    peek(): OnceResult<T>;
+    /**
+     * Returns the stored value if successful, otherwise throws the stored error.
+     * Throws if the operation is not yet complete.
+     */
+    get(): T | null;
+    /**
+     * Resets the instance, allowing the action to run again on the next call.
+     */
+    reset(): void;
+    /**
+     * Returns the underlying promise if running or done, null otherwise.
+     */
+    resolved(): Promise<OnceResult<T>> | null;
+    /**
+     * Returns true if the operation has finished (success or final failure).
+     */
+    done(): boolean;
+    private _awaitWithTimeout;
+}
+type SerializerResult<T> = {
+    value: T | null;
+    error?: unknown;
+};
+interface SerializerOptions {
+    /**
+     * Max items in queue. If full, .do() returns an error immediately.
+     * @default 1000
+     */
+    capacity?: number;
+    /**
+     * Yield mode for the internal mutex. Defaults to "macrotask" for
+     * coarse-grained serializers (invalidationSerializer). Use "microtask"
+     * for fine-grained latency-sensitive serializers (streamSerializer).
+     */
+    yieldMode?: "macrotask" | "microtask";
+}
+/**
+ * Ensures tasks are executed sequentially (FIFO).
+ * Maintains the result of the last successful execution.
+ * Includes backpressure protection via configurable queue capacity.
+ */
+declare class Serializer<T = void> {
+    private mutex;
+    private _done;
+    private _lastValue;
+    private _lastError;
+    constructor(options?: SerializerOptions);
+    /**
+     * Enqueue a function to be executed after all previous tasks complete.
+     *
+     * @param fn - The function to execute.
+     * @param timeout - Max time to wait to acquire the lock.
+     * @returns Object containing the value or error.
+     */
+    do(fn: () => Promise<T> | T, timeout?: number): Promise<SerializerResult<T | null>>;
+    /** Returns the result of the last successful execution. */
+    peek(): SerializerResult<T | null>;
+    /**
+     * Permanently closes the serializer.
+     * Subsequent calls to `do()` will fail immediately with SerializerExecutionDone.
+     */
+    close(): void;
+    /** Returns the number of tasks currently waiting. */
+    pending(): number;
+    /** Returns true if a task is currently executing. */
+    running(): boolean;
+}
+
+export { Mutex, type MutexOptions, Once, type OnceResult, Serializer, type SerializerOptions, type SerializerResult };

package/index.js

@@ -0,0 +1 @@
+"use strict";var t=class t extends Error{constructor(e,r){super(e,{cause:r}),this.name="SyncError",Object.setPrototypeOf(this,t.prototype)}},e=class extends t{constructor(t){super(`[ArtifactContainer] Operation timed out: ${t}`)}},r=class extends t{constructor(t){super("[Serializer] The serializer has been marked as done!",t)}},i=class{_locked=!1;_capacity;_yieldMode;waiters=[];constructor(t){this._capacity=t?.capacity??1/0,this._yieldMode=t?.yieldMode??"macrotask"}async lock(t){if(!this._locked)return void(this._locked=!0);if(this.waiters.length>=this._capacity)throw new Error(`Mutex queue is full (capacity: ${this._capacity})`);let r;const i=new Promise((t=>r=t));this.waiters.push(r),null!=t?await Promise.race([i,new Promise(((i,s)=>setTimeout((()=>{const t=this.waiters.indexOf(r);-1!==t&&this.waiters.splice(t,1),s(new e("Mutex lock timed out"))}),t)))]):await i}tryLock(){return!this._locked&&(this._locked=!0,!0)}unlock(){if(!this._locked)throw new Error("Mutex is not locked");const t=this.waiters.shift();t?"microtask"===this._yieldMode?queueMicrotask(t):setTimeout(t,0):this._locked=!1}locked(){return this._locked}pending(){return this.waiters.length}};exports.Mutex=i,exports.Once=class{mutex=new i({yieldMode:"microtask"});promise=null;_value=null;_error;_done=!1;retry;throws;constructor({retry:t,throws:e}={}){this.retry=Boolean(t),this.throws=Boolean(e)}async do(t,e){return this._done?this.peek():this.promise?this._awaitWithTimeout(this.promise,e,"Once do() timed out"):(await this.mutex.lock(),this.promise?(this.mutex.unlock(),this._awaitWithTimeout(this.promise,e,"Once do() timed out")):(this.promise=(async()=>{try{const e=await t();this._value=e,this._done=!0}catch(t){if(this._error=t,this.retry||(this._done=!0),this.throws)throw t}finally{this.promise=null}return this.peek()})(),this.mutex.unlock(),this._awaitWithTimeout(this.promise,e,"Once do() timed out")))}isReady(){return this._done&&null===this.promise}running(){return null!==this.promise&&!this._done}peek(){return{value:this._value,error:this._error}}get(){if(!this._done)throw new Error("Once operation is not yet complete");if(this._error)throw this._error;return this._value}reset(){this._done=!1,this.promise=null,this._value=null,this._error=void 0}resolved(){return this.promise}done(){return this._done}_awaitWithTimeout(t,r,i="Operation timed out"){return null==r?t:Promise.race([t,new Promise(((t,s)=>setTimeout((()=>s(new e(i))),r)))])}},exports.Serializer=class{mutex;_done=!1;_lastValue=null;_lastError=void 0;constructor(t){this.mutex=new i({capacity:t?.capacity??1e3,yieldMode:t?.yieldMode??"macrotask"})}async do(t,e){if(this._done)return{value:null,error:new r};try{await this.mutex.lock(e)}catch(t){return{value:null,error:t}}let i,s=null;try{if(this._done)throw new r;s=await t(),this._lastValue=s,this._lastError=void 0}catch(t){i=t,this._lastError=t}finally{this.mutex.unlock()}return{value:s,error:i}}peek(){return{value:this._lastValue,error:this._lastError}}close(){this._done=!0}pending(){return this.mutex.pending()}running(){return this.mutex.locked()}};

package/index.mjs

@@ -0,0 +1 @@
+var t=class t extends Error{constructor(e,r){super(e,{cause:r}),this.name="SyncError",Object.setPrototypeOf(this,t.prototype)}},e=class extends t{constructor(t){super(`[ArtifactContainer] Operation timed out: ${t}`)}},r=class extends t{constructor(t){super("[Serializer] The serializer has been marked as done!",t)}},i=class{_locked=!1;_capacity;_yieldMode;waiters=[];constructor(t){this._capacity=t?.capacity??1/0,this._yieldMode=t?.yieldMode??"macrotask"}async lock(t){if(!this._locked)return void(this._locked=!0);if(this.waiters.length>=this._capacity)throw new Error(`Mutex queue is full (capacity: ${this._capacity})`);let r;const i=new Promise((t=>r=t));this.waiters.push(r),null!=t?await Promise.race([i,new Promise(((i,s)=>setTimeout((()=>{const t=this.waiters.indexOf(r);-1!==t&&this.waiters.splice(t,1),s(new e("Mutex lock timed out"))}),t)))]):await i}tryLock(){return!this._locked&&(this._locked=!0,!0)}unlock(){if(!this._locked)throw new Error("Mutex is not locked");const t=this.waiters.shift();t?"microtask"===this._yieldMode?queueMicrotask(t):setTimeout(t,0):this._locked=!1}locked(){return this._locked}pending(){return this.waiters.length}},s=class{mutex=new i({yieldMode:"microtask"});promise=null;_value=null;_error;_done=!1;retry;throws;constructor({retry:t,throws:e}={}){this.retry=Boolean(t),this.throws=Boolean(e)}async do(t,e){return this._done?this.peek():this.promise?this._awaitWithTimeout(this.promise,e,"Once do() timed out"):(await this.mutex.lock(),this.promise?(this.mutex.unlock(),this._awaitWithTimeout(this.promise,e,"Once do() timed out")):(this.promise=(async()=>{try{const e=await t();this._value=e,this._done=!0}catch(t){if(this._error=t,this.retry||(this._done=!0),this.throws)throw t}finally{this.promise=null}return this.peek()})(),this.mutex.unlock(),this._awaitWithTimeout(this.promise,e,"Once do() timed out")))}isReady(){return this._done&&null===this.promise}running(){return null!==this.promise&&!this._done}peek(){return{value:this._value,error:this._error}}get(){if(!this._done)throw new Error("Once operation is not yet complete");if(this._error)throw this._error;return this._value}reset(){this._done=!1,this.promise=null,this._value=null,this._error=void 0}resolved(){return this.promise}done(){return this._done}_awaitWithTimeout(t,r,i="Operation timed out"){return null==r?t:Promise.race([t,new Promise(((t,s)=>setTimeout((()=>s(new e(i))),r)))])}},o=class{mutex;_done=!1;_lastValue=null;_lastError=void 0;constructor(t){this.mutex=new i({capacity:t?.capacity??1e3,yieldMode:t?.yieldMode??"macrotask"})}async do(t,e){if(this._done)return{value:null,error:new r};try{await this.mutex.lock(e)}catch(t){return{value:null,error:t}}let i,s=null;try{if(this._done)throw new r;s=await t(),this._lastValue=s,this._lastError=void 0}catch(t){i=t,this._lastError=t}finally{this.mutex.unlock()}return{value:s,error:i}}peek(){return{value:this._lastValue,error:this._lastError}}close(){this._done=!0}pending(){return this.mutex.pending()}running(){return this.mutex.locked()}};export{i as Mutex,s as Once,o as Serializer};

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@asaidimu/utils-sync",
+  "version": "1.0.0",
+  "description": "A collection of sync utilities.",
+  "main": "index.js",
+  "module": "index.mjs",
+  "types": "index.d.ts",
+  "keywords": [
+    "typescript",
+    "utility"
+  ],
+  "author": "Saidimu <47994458+asaidimu@users.noreply.github.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/asaidimu/erp-utils.git"
+  },
+  "bugs": {
+    "url": "https://github.com/asaidimu/erp-utils/issues"
+  },
+  "homepage": "https://github.com/asaidimu/erp-utils/tree/main/src/sync#readme",
+  "files": [
+    "./*"
+  ],
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./index.d.ts",
+        "default": "./index.mjs"
+      },
+      "require": {
+        "types": "./index.d.ts",
+        "default": "./index.js"
+      }
+    }
+  },
+  "dependencies": {},
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "tag": "latest",
+    "access": "public"
+  },
+  "release": {
+    "plugins": [
+      [
+        "@semantic-release/npm",
+        {
+          "pkgRoot": "./dist"
+        }
+      ],
+      [
+        "@semantic-release/git",
+        {
+          "assets": [
+            "CHANGELOG.md",
+            "package.json"
+          ],
+          "message": "chore(release): Release @asaidimu/utils-sync v${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
+        }
+      ]
+    ]
+  }
+}