@standardserver/shared 0.0.6 → 0.0.8

package/dist/index.d.mts

@@ -1,7 +1,7 @@
-declare function toArray<T>(value: T): T extends readonly any[] ? T : Exclude<T, undefined | null>[];
+declare function toArray<T>(value: T): T extends readonly any[] ? T : (T extends undefined | null ? never : T[]);
 
 declare const PACKAGE_NAME = "@standardserver/shared";
-declare const PACKAGE_VERSION = "0.0.6";
+declare const PACKAGE_VERSION = "0.0.8";
 /**
  * Generates a unique symbol for the specified name within the package scope.
  * The symbol is globally registered using `Symbol.for` to ensure consistency across modules.
@@ -19,6 +19,11 @@ declare function getPackageSymbol(name: string): symbol;
 declare class AbortError extends Error {
     constructor(...rest: ConstructorParameters<typeof Error>);
 }
+/**
+ * Forwards an error to the global unhandled rejection handler via a rejected Promise.
+ * Useful for routing errors from sync contexts into async error pipelines.
+ */
+declare function emitUnhandledRejection(error: unknown): void;
 
 /**
  * Sequentially execute the function, if the previous execution is not completed, the next execution will be blocked
@@ -31,7 +36,10 @@ declare class SequentialIdGenerator {
 }
 
 interface AsyncCleanupFn {
-    (isCompleted: boolean): Promise<void>;
+    (state: {
+        isCancelled: boolean;
+        error?: unknown;
+    }): Promise<void>;
 }
 
 declare function isAsyncIteratorObject(maybe: unknown): maybe is AsyncIteratorObject<any, any, any>;
@@ -49,7 +57,7 @@ declare class AsyncIteratorClass<T, TReturn = unknown, TNext = unknown> implemen
     readonly next: AsyncIteratorClassNextFn<T, TReturn>;
     constructor(next: AsyncIteratorClassNextFn<T, TReturn>, cleanup: AsyncCleanupFn);
     return(value?: any): Promise<IteratorResult<T, TReturn>>;
-    throw(err: any): Promise<IteratorResult<T, TReturn>>;
+    throw(error: any): Promise<IteratorResult<T, TReturn>>;
     /**
      * asyncDispose symbol only available in esnext, we should fallback to Symbol.for('asyncDispose')
      */
@@ -66,6 +74,10 @@ declare function stringifyJSON<T>(value: T | {
  * Checks whether the provided container is a typescript object (object or function).
  */
 declare function isTypescriptObject(maybeObject: unknown): maybeObject is object & Record<PropertyKey, unknown>;
+/**
+ *  Creates a new object with the specified keys omitted.
+ */
+declare function omit<T extends object, K extends keyof T>(obj: T, keys: K[]): Omit<T, K>;
 
 interface GetOrBindOptions {
     /**
@@ -77,41 +89,42 @@ interface GetOrBindOptions {
 }
 declare function getOrBind<T extends object, K extends PropertyKey>(target: T, property: K, { bind }?: GetOrBindOptions): K extends keyof T ? T[K] : unknown;
 
-interface AsyncIdQueueCloseOptions {
-    id?: string;
-    reason?: unknown;
-}
-interface AsyncIdQueueOptions {
+declare class Queue<T> {
+    private readonly items;
+    private readonly pendingPulls;
+    private closed;
+    /**
+     * Pushes an item into the queue.
+     * @throws when the queue is closed or aborted
+     */
+    push(item: T): void;
     /**
-     * Maximum number of buffered items per queue.
+     * Pulls the next item from the queue.
      *
-     * @default Infinity
+     * @throws when the queue is closed or aborted. Note that buffered items can still be pulled after close until the buffer is drained.
      */
-    maxBufferedSize?: number;
-}
-declare class AsyncIdQueue<T> {
-    private readonly maxBufferedSize;
-    private readonly openIds;
-    private readonly queues;
-    private readonly waiters;
-    constructor(options?: AsyncIdQueueOptions);
-    get length(): number;
-    get waiterIds(): string[];
-    hasBufferedItems(id: string): boolean;
-    open(id: string): void;
-    isOpen(id: string): boolean;
-    push(id: string, item: T): void;
-    pull(id: string): Promise<T>;
-    close({ id, reason }?: AsyncIdQueueCloseOptions): void;
-    assertOpen(id: string): void;
+    pull(): Promise<T>;
+    /**
+     * Closes the queue and rejects any pending pulls.
+     * Buffered items remain available to be pulled. Repeated calls are ignored.
+     */
+    close(reason?: unknown): void;
+    /**
+     * Aborts the queue.
+     * Unlike `close()`, this also discards any buffered items before closing.
+     */
+    abort(reason?: unknown): void;
 }
 
+interface SleepOptions {
+    signal?: AbortSignal | undefined;
+}
 /**
  * sleep for a specified amount of time
  */
-declare function sleep(ms: number): Promise<void>;
+declare function sleep(ms: number, { signal }?: SleepOptions): Promise<void>;
 
 declare function tryDecodeURIComponent(value: string): string;
 
-export { AbortError, AsyncIdQueue, AsyncIteratorClass, PACKAGE_NAME, PACKAGE_VERSION, SequentialIdGenerator, getOrBind, getPackageSymbol, isAsyncIteratorObject, isTypescriptObject, parseEmptyableJSON, sequential, sleep, stringifyJSON, toArray, tryDecodeURIComponent };
-export type { AsyncCleanupFn, AsyncIdQueueCloseOptions, AsyncIdQueueOptions, AsyncIteratorClassNextFn, GetOrBindOptions };
+export { AbortError, AsyncIteratorClass, PACKAGE_NAME, PACKAGE_VERSION, Queue, SequentialIdGenerator, emitUnhandledRejection, getOrBind, getPackageSymbol, isAsyncIteratorObject, isTypescriptObject, omit, parseEmptyableJSON, sequential, sleep, stringifyJSON, toArray, tryDecodeURIComponent };
+export type { AsyncCleanupFn, AsyncIteratorClassNextFn, GetOrBindOptions, SleepOptions };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-declare function toArray<T>(value: T): T extends readonly any[] ? T : Exclude<T, undefined | null>[];
+declare function toArray<T>(value: T): T extends readonly any[] ? T : (T extends undefined | null ? never : T[]);
 
 declare const PACKAGE_NAME = "@standardserver/shared";
-declare const PACKAGE_VERSION = "0.0.6";
+declare const PACKAGE_VERSION = "0.0.8";
 /**
  * Generates a unique symbol for the specified name within the package scope.
  * The symbol is globally registered using `Symbol.for` to ensure consistency across modules.
@@ -19,6 +19,11 @@ declare function getPackageSymbol(name: string): symbol;
 declare class AbortError extends Error {
     constructor(...rest: ConstructorParameters<typeof Error>);
 }
+/**
+ * Forwards an error to the global unhandled rejection handler via a rejected Promise.
+ * Useful for routing errors from sync contexts into async error pipelines.
+ */
+declare function emitUnhandledRejection(error: unknown): void;
 
 /**
  * Sequentially execute the function, if the previous execution is not completed, the next execution will be blocked
@@ -31,7 +36,10 @@ declare class SequentialIdGenerator {
 }
 
 interface AsyncCleanupFn {
-    (isCompleted: boolean): Promise<void>;
+    (state: {
+        isCancelled: boolean;
+        error?: unknown;
+    }): Promise<void>;
 }
 
 declare function isAsyncIteratorObject(maybe: unknown): maybe is AsyncIteratorObject<any, any, any>;
@@ -49,7 +57,7 @@ declare class AsyncIteratorClass<T, TReturn = unknown, TNext = unknown> implemen
     readonly next: AsyncIteratorClassNextFn<T, TReturn>;
     constructor(next: AsyncIteratorClassNextFn<T, TReturn>, cleanup: AsyncCleanupFn);
     return(value?: any): Promise<IteratorResult<T, TReturn>>;
-    throw(err: any): Promise<IteratorResult<T, TReturn>>;
+    throw(error: any): Promise<IteratorResult<T, TReturn>>;
     /**
      * asyncDispose symbol only available in esnext, we should fallback to Symbol.for('asyncDispose')
      */
@@ -66,6 +74,10 @@ declare function stringifyJSON<T>(value: T | {
  * Checks whether the provided container is a typescript object (object or function).
  */
 declare function isTypescriptObject(maybeObject: unknown): maybeObject is object & Record<PropertyKey, unknown>;
+/**
+ *  Creates a new object with the specified keys omitted.
+ */
+declare function omit<T extends object, K extends keyof T>(obj: T, keys: K[]): Omit<T, K>;
 
 interface GetOrBindOptions {
     /**
@@ -77,41 +89,42 @@ interface GetOrBindOptions {
 }
 declare function getOrBind<T extends object, K extends PropertyKey>(target: T, property: K, { bind }?: GetOrBindOptions): K extends keyof T ? T[K] : unknown;
 
-interface AsyncIdQueueCloseOptions {
-    id?: string;
-    reason?: unknown;
-}
-interface AsyncIdQueueOptions {
+declare class Queue<T> {
+    private readonly items;
+    private readonly pendingPulls;
+    private closed;
+    /**
+     * Pushes an item into the queue.
+     * @throws when the queue is closed or aborted
+     */
+    push(item: T): void;
     /**
-     * Maximum number of buffered items per queue.
+     * Pulls the next item from the queue.
      *
-     * @default Infinity
+     * @throws when the queue is closed or aborted. Note that buffered items can still be pulled after close until the buffer is drained.
      */
-    maxBufferedSize?: number;
-}
-declare class AsyncIdQueue<T> {
-    private readonly maxBufferedSize;
-    private readonly openIds;
-    private readonly queues;
-    private readonly waiters;
-    constructor(options?: AsyncIdQueueOptions);
-    get length(): number;
-    get waiterIds(): string[];
-    hasBufferedItems(id: string): boolean;
-    open(id: string): void;
-    isOpen(id: string): boolean;
-    push(id: string, item: T): void;
-    pull(id: string): Promise<T>;
-    close({ id, reason }?: AsyncIdQueueCloseOptions): void;
-    assertOpen(id: string): void;
+    pull(): Promise<T>;
+    /**
+     * Closes the queue and rejects any pending pulls.
+     * Buffered items remain available to be pulled. Repeated calls are ignored.
+     */
+    close(reason?: unknown): void;
+    /**
+     * Aborts the queue.
+     * Unlike `close()`, this also discards any buffered items before closing.
+     */
+    abort(reason?: unknown): void;
 }
 
+interface SleepOptions {
+    signal?: AbortSignal | undefined;
+}
 /**
  * sleep for a specified amount of time
  */
-declare function sleep(ms: number): Promise<void>;
+declare function sleep(ms: number, { signal }?: SleepOptions): Promise<void>;
 
 declare function tryDecodeURIComponent(value: string): string;
 
-export { AbortError, AsyncIdQueue, AsyncIteratorClass, PACKAGE_NAME, PACKAGE_VERSION, SequentialIdGenerator, getOrBind, getPackageSymbol, isAsyncIteratorObject, isTypescriptObject, parseEmptyableJSON, sequential, sleep, stringifyJSON, toArray, tryDecodeURIComponent };
-export type { AsyncCleanupFn, AsyncIdQueueCloseOptions, AsyncIdQueueOptions, AsyncIteratorClassNextFn, GetOrBindOptions };
+export { AbortError, AsyncIteratorClass, PACKAGE_NAME, PACKAGE_VERSION, Queue, SequentialIdGenerator, emitUnhandledRejection, getOrBind, getPackageSymbol, isAsyncIteratorObject, isTypescriptObject, omit, parseEmptyableJSON, sequential, sleep, stringifyJSON, toArray, tryDecodeURIComponent };
+export type { AsyncCleanupFn, AsyncIteratorClassNextFn, GetOrBindOptions, SleepOptions };

package/dist/index.mjs

@@ -3,7 +3,7 @@ function toArray(value) {
 }
 
 const PACKAGE_NAME = "@standardserver/shared";
-const PACKAGE_VERSION = "0.0.6";
+const PACKAGE_VERSION = "0.0.8";
 function getPackageSymbol(name) {
   return Symbol.for(`${PACKAGE_NAME}@${PACKAGE_VERSION}/${name}`);
 }
@@ -14,6 +14,11 @@ class AbortError extends Error {
     this.name = "AbortError";
   }
 }
+function emitUnhandledRejection(error) {
+  Promise.reject(error).catch(() => {
+    throw error;
+  });
+}
 
 function sequential(fn) {
   let lastOperationPromise = Promise.resolve();
@@ -53,19 +58,21 @@ class AsyncIteratorClass {
       if (this.isDone) {
         return { done: true, value: void 0 };
       }
+      let errorRef;
       try {
         const result = await next();
         if (result.done) {
           this.isDone = true;
         }
         return result;
-      } catch (err) {
+      } catch (error) {
+        errorRef = { value: error };
         this.isDone = true;
-        throw err;
+        throw error;
       } finally {
         if (this.isDone && !this.isExecuteComplete) {
           this.isExecuteComplete = true;
-          await this.cleanup(true);
+          await this.cleanup(errorRef ? { isCancelled: false, error: errorRef.value } : { isCancelled: false });
         }
       }
     });
@@ -74,17 +81,17 @@ class AsyncIteratorClass {
     this.isDone = true;
     if (!this.isExecuteComplete) {
       this.isExecuteComplete = true;
-      await this.cleanup(false);
+      await this.cleanup({ isCancelled: true });
     }
     return { done: true, value };
   }
-  async throw(err) {
+  async throw(error) {
     this.isDone = true;
     if (!this.isExecuteComplete) {
       this.isExecuteComplete = true;
-      await this.cleanup(false);
+      await this.cleanup({ isCancelled: true, error });
     }
-    throw err;
+    throw error;
   }
   /**
    * asyncDispose symbol only available in esnext, we should fallback to Symbol.for('asyncDispose')
@@ -93,7 +100,7 @@ class AsyncIteratorClass {
     this.isDone = true;
     if (!this.isExecuteComplete) {
       this.isExecuteComplete = true;
-      await this.cleanup(false);
+      await this.cleanup({ isCancelled: true });
     }
   }
   [Symbol.asyncIterator]() {
@@ -118,6 +125,13 @@ function isTypescriptObject(maybeObject) {
   const type = typeof maybeObject;
   return type === "object" || type === "function";
 }
+function omit(obj, keys) {
+  const result = { ...obj };
+  for (const key of keys) {
+    delete result[key];
+  }
+  return result;
+}
 
 const GET_OR_BIND_CACHE = /* @__PURE__ */ new WeakMap();
 function getOrBind(target, property, { bind = true } = {}) {
@@ -136,98 +150,86 @@ function getOrBind(target, property, { bind = true } = {}) {
   return bound;
 }
 
-class AsyncIdQueue {
-  maxBufferedSize;
-  openIds = /* @__PURE__ */ new Set();
-  queues = /* @__PURE__ */ new Map();
-  waiters = /* @__PURE__ */ new Map();
-  constructor(options = {}) {
-    this.maxBufferedSize = options.maxBufferedSize ?? Infinity;
-  }
-  get length() {
-    return this.openIds.size;
-  }
-  get waiterIds() {
-    return Array.from(this.waiters.keys());
-  }
-  hasBufferedItems(id) {
-    return Boolean(this.queues.get(id)?.length);
-  }
-  open(id) {
-    this.openIds.add(id);
-  }
-  isOpen(id) {
-    return this.openIds.has(id);
-  }
-  push(id, item) {
-    this.assertOpen(id);
-    const pending = this.waiters.get(id);
-    if (pending?.length) {
-      pending.shift()[0](item);
-      if (pending.length === 0) {
-        this.waiters.delete(id);
-      }
+class Queue {
+  items = [];
+  pendingPulls = [];
+  closed;
+  /**
+   * Pushes an item into the queue.
+   * @throws when the queue is closed or aborted
+   */
+  push(item) {
+    if (this.closed) {
+      throw this.closed.reason;
+    }
+    const pendingPull = this.pendingPulls.shift();
+    if (pendingPull) {
+      pendingPull[0](item);
     } else {
-      let items = this.queues.get(id);
-      if (!items) {
-        items = [];
-        this.queues.set(id, items);
-      }
-      items.push(item);
-      if (items.length > this.maxBufferedSize) {
-        items.shift();
-      }
-      if (items.length === 0) {
-        this.queues.delete(id);
-      }
+      this.items.push(item);
     }
   }
-  async pull(id) {
-    this.assertOpen(id);
-    const items = this.queues.get(id);
-    if (items?.length) {
-      const item = items.shift();
-      if (items.length === 0) {
-        this.queues.delete(id);
-      }
+  /**
+   * Pulls the next item from the queue.
+   *
+   * @throws when the queue is closed or aborted. Note that buffered items can still be pulled after close until the buffer is drained.
+   */
+  async pull() {
+    const item = this.items.shift();
+    if (item !== void 0) {
       return item;
     }
+    if (this.closed) {
+      throw this.closed.reason;
+    }
     return new Promise((resolve, reject) => {
-      const waitingPulls = this.waiters.get(id);
-      const pending = [resolve, reject];
-      if (waitingPulls) {
-        waitingPulls.push(pending);
-      } else {
-        this.waiters.set(id, [pending]);
-      }
+      this.pendingPulls.push([resolve, reject]);
     });
   }
-  close({ id, reason } = {}) {
-    if (id === void 0) {
-      this.waiters.forEach((pendingPulls, id2) => {
-        const error2 = reason ?? new AbortError(`[AsyncIdQueue] Queue[${id2}] was closed or aborted while waiting for pulling.`);
-        pendingPulls.forEach(([, reject]) => reject(error2));
-      });
-      this.waiters.clear();
-      this.openIds.clear();
-      this.queues.clear();
+  /**
+   * Closes the queue and rejects any pending pulls.
+   * Buffered items remain available to be pulled. Repeated calls are ignored.
+   */
+  close(reason) {
+    if (this.closed) {
       return;
     }
-    const error = reason ?? new AbortError(`[AsyncIdQueue] Queue[${id}] was closed or aborted while waiting for pulling.`);
-    this.waiters.get(id)?.forEach(([, reject]) => reject(error));
-    this.waiters.delete(id);
-    this.openIds.delete(id);
-    this.queues.delete(id);
-  }
-  assertOpen(id) {
-    if (!this.isOpen(id)) {
-      throw new Error(`[AsyncIdQueue] Cannot access queue[${id}] because it is not open or aborted.`);
-    }
+    reason ??= new AbortError("Queue was closed.");
+    this.closed = { reason };
+    this.pendingPulls.forEach(([, reject]) => reject(reason));
+    this.pendingPulls.length = 0;
+  }
+  /**
+   * Aborts the queue.
+   * Unlike `close()`, this also discards any buffered items before closing.
+   */
+  abort(reason) {
+    reason ??= new AbortError("Queue was aborted.");
+    this.items.length = 0;
+    this.close(reason);
   }
 }
 
-function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
+function sleep(ms, { signal } = {}) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(signal.reason);
+      return;
+    }
+    let abortListener = null;
+    const timeout = setTimeout(() => {
+      if (abortListener) {
+        signal?.removeEventListener("abort", abortListener);
+      }
+      resolve();
+    }, ms);
+    if (signal) {
+      signal.addEventListener("abort", abortListener = () => {
+        clearTimeout(timeout);
+        reject(signal?.reason);
+      }, { once: true });
+    }
+  });
 }
 
 function tryDecodeURIComponent(value) {
@@ -238,4 +240,4 @@ function tryDecodeURIComponent(value) {
   }
 }
 
-export { AbortError, AsyncIdQueue, AsyncIteratorClass, PACKAGE_NAME, PACKAGE_VERSION, SequentialIdGenerator, getOrBind, getPackageSymbol, isAsyncIteratorObject, isTypescriptObject, parseEmptyableJSON, sequential, sleep, stringifyJSON, toArray, tryDecodeURIComponent };
+export { AbortError, AsyncIteratorClass, PACKAGE_NAME, PACKAGE_VERSION, Queue, SequentialIdGenerator, emitUnhandledRejection, getOrBind, getPackageSymbol, isAsyncIteratorObject, isTypescriptObject, omit, parseEmptyableJSON, sequential, sleep, stringifyJSON, toArray, tryDecodeURIComponent };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@standardserver/shared",
   "type": "module",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "license": "MIT",
   "homepage": "https://standardserver.dev",
   "repository": {