@standardserver/shared 0.0.0

package/LICENCE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Standard Server
+
+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/dist/index.d.mts

@@ -0,0 +1,132 @@
+declare function toArray<T>(value: T): T extends readonly any[] ? T : Exclude<T, undefined | null>[];
+
+declare const PACKAGE_NAME = "@standardserver/shared";
+declare const PACKAGE_VERSION = "0.0.0";
+/**
+ * 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.
+ *
+ * @remarks
+ * - Ensure names are unique to avoid symbol collisions within the package.
+ * - Ensure package versions are synchronized (e.g., when the core package is updated, this package should also be updated).
+ */
+declare function getPackageSymbol(name: string): symbol;
+
+/**
+ * Error thrown when an operation is aborted.
+ * Uses the standardized 'AbortError' name for consistency with JavaScript APIs.
+ */
+declare class AbortError extends Error {
+    constructor(...rest: ConstructorParameters<typeof Error>);
+}
+
+/**
+ * Sequentially execute the function, if the previous execution is not completed, the next execution will be blocked
+ */
+declare function sequential<A extends any[], R>(fn: (...args: A) => Promise<R>): (...args: A) => Promise<R>;
+
+declare class SequentialIdGenerator {
+    private index;
+    generate(): string;
+}
+
+interface AsyncCleanupFn {
+    (isCompleted: boolean): Promise<void>;
+}
+
+declare function isAsyncIteratorObject(maybe: unknown): maybe is AsyncIteratorObject<any, any, any>;
+interface AsyncIteratorClassNextFn<T, TReturn> {
+    (): Promise<IteratorResult<T, TReturn>>;
+}
+declare const fallbackAsyncDisposeSymbol: unique symbol;
+declare const asyncDisposeSymbol: typeof Symbol extends {
+    asyncDispose: infer T;
+} ? T : typeof fallbackAsyncDisposeSymbol;
+declare class AsyncIteratorClass<T, TReturn = unknown, TNext = unknown> implements AsyncIteratorObject<T, TReturn, TNext>, AsyncGenerator<T, TReturn, TNext> {
+    private isDone;
+    private isExecuteComplete;
+    private readonly cleanup;
+    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>>;
+    /**
+     * asyncDispose symbol only available in esnext, we should fallback to Symbol.for('asyncDispose')
+     */
+    [asyncDisposeSymbol](): Promise<void>;
+    [Symbol.asyncIterator](): this;
+}
+
+declare function parseEmptyableJSON(text: string | null | undefined): unknown;
+declare function stringifyJSON<T>(value: T | {
+    toJSON(): T;
+}): undefined extends T ? undefined | string : string;
+
+/**
+ * Checks whether the provided container is a typescript object (object or function).
+ */
+declare function isTypescriptObject(maybeObject: unknown): maybeObject is object;
+
+/**
+ * A ProxyHandler whose `get` trap receives an additional `fallback` function.
+ *
+ * The `fallback` returns the default property value as if no proxy
+ * interception occurred, and automatically binds methods to the target.
+ */
+interface EnhancedProxyHandler<T extends object> extends Omit<ProxyHandler<T>, 'get'> {
+    get(target: T, p: PropertyKey, receiver: any, fallback: () => any): any;
+}
+/**
+ * Creates a Proxy that enhances the standard `get` trap by providing:
+ *
+ * - A `fallback` function that:
+ *   - Reads the property directly from the target
+ *   - Automatically binds methods to the target
+ *   - Caches bound methods for stable identity
+ * - An internal symbol that allows accessing the original target
+ */
+declare function createEnhancedProxy<T extends object>(target: T, handler: EnhancedProxyHandler<T>): T;
+/**
+ * Returns the underlying target of an enhanced proxy.
+ * If the given value is not an enhanced proxy, it is returned as-is.
+ */
+declare function getEnhancedProxyTarget<T extends object>(value: T): T;
+
+interface AsyncIdQueueCloseOptions {
+    id?: string;
+    reason?: unknown;
+}
+interface AsyncIdQueueOptions {
+    /**
+     * Maximum number of buffered items per queue.
+     *
+     * @default Infinity
+     */
+    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;
+}
+
+/**
+ * sleep for a specified amount of time
+ */
+declare function sleep(ms: number): Promise<void>;
+
+declare function tryDecodeURIComponent(value: string): string;
+
+export { AbortError, AsyncIdQueue, AsyncIteratorClass, PACKAGE_NAME, PACKAGE_VERSION, SequentialIdGenerator, createEnhancedProxy, getEnhancedProxyTarget, getPackageSymbol, isAsyncIteratorObject, isTypescriptObject, parseEmptyableJSON, sequential, sleep, stringifyJSON, toArray, tryDecodeURIComponent };
+export type { AsyncCleanupFn, AsyncIdQueueCloseOptions, AsyncIdQueueOptions, AsyncIteratorClassNextFn, EnhancedProxyHandler };

package/dist/index.d.ts

@@ -0,0 +1,132 @@
+declare function toArray<T>(value: T): T extends readonly any[] ? T : Exclude<T, undefined | null>[];
+
+declare const PACKAGE_NAME = "@standardserver/shared";
+declare const PACKAGE_VERSION = "0.0.0";
+/**
+ * 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.
+ *
+ * @remarks
+ * - Ensure names are unique to avoid symbol collisions within the package.
+ * - Ensure package versions are synchronized (e.g., when the core package is updated, this package should also be updated).
+ */
+declare function getPackageSymbol(name: string): symbol;
+
+/**
+ * Error thrown when an operation is aborted.
+ * Uses the standardized 'AbortError' name for consistency with JavaScript APIs.
+ */
+declare class AbortError extends Error {
+    constructor(...rest: ConstructorParameters<typeof Error>);
+}
+
+/**
+ * Sequentially execute the function, if the previous execution is not completed, the next execution will be blocked
+ */
+declare function sequential<A extends any[], R>(fn: (...args: A) => Promise<R>): (...args: A) => Promise<R>;
+
+declare class SequentialIdGenerator {
+    private index;
+    generate(): string;
+}
+
+interface AsyncCleanupFn {
+    (isCompleted: boolean): Promise<void>;
+}
+
+declare function isAsyncIteratorObject(maybe: unknown): maybe is AsyncIteratorObject<any, any, any>;
+interface AsyncIteratorClassNextFn<T, TReturn> {
+    (): Promise<IteratorResult<T, TReturn>>;
+}
+declare const fallbackAsyncDisposeSymbol: unique symbol;
+declare const asyncDisposeSymbol: typeof Symbol extends {
+    asyncDispose: infer T;
+} ? T : typeof fallbackAsyncDisposeSymbol;
+declare class AsyncIteratorClass<T, TReturn = unknown, TNext = unknown> implements AsyncIteratorObject<T, TReturn, TNext>, AsyncGenerator<T, TReturn, TNext> {
+    private isDone;
+    private isExecuteComplete;
+    private readonly cleanup;
+    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>>;
+    /**
+     * asyncDispose symbol only available in esnext, we should fallback to Symbol.for('asyncDispose')
+     */
+    [asyncDisposeSymbol](): Promise<void>;
+    [Symbol.asyncIterator](): this;
+}
+
+declare function parseEmptyableJSON(text: string | null | undefined): unknown;
+declare function stringifyJSON<T>(value: T | {
+    toJSON(): T;
+}): undefined extends T ? undefined | string : string;
+
+/**
+ * Checks whether the provided container is a typescript object (object or function).
+ */
+declare function isTypescriptObject(maybeObject: unknown): maybeObject is object;
+
+/**
+ * A ProxyHandler whose `get` trap receives an additional `fallback` function.
+ *
+ * The `fallback` returns the default property value as if no proxy
+ * interception occurred, and automatically binds methods to the target.
+ */
+interface EnhancedProxyHandler<T extends object> extends Omit<ProxyHandler<T>, 'get'> {
+    get(target: T, p: PropertyKey, receiver: any, fallback: () => any): any;
+}
+/**
+ * Creates a Proxy that enhances the standard `get` trap by providing:
+ *
+ * - A `fallback` function that:
+ *   - Reads the property directly from the target
+ *   - Automatically binds methods to the target
+ *   - Caches bound methods for stable identity
+ * - An internal symbol that allows accessing the original target
+ */
+declare function createEnhancedProxy<T extends object>(target: T, handler: EnhancedProxyHandler<T>): T;
+/**
+ * Returns the underlying target of an enhanced proxy.
+ * If the given value is not an enhanced proxy, it is returned as-is.
+ */
+declare function getEnhancedProxyTarget<T extends object>(value: T): T;
+
+interface AsyncIdQueueCloseOptions {
+    id?: string;
+    reason?: unknown;
+}
+interface AsyncIdQueueOptions {
+    /**
+     * Maximum number of buffered items per queue.
+     *
+     * @default Infinity
+     */
+    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;
+}
+
+/**
+ * sleep for a specified amount of time
+ */
+declare function sleep(ms: number): Promise<void>;
+
+declare function tryDecodeURIComponent(value: string): string;
+
+export { AbortError, AsyncIdQueue, AsyncIteratorClass, PACKAGE_NAME, PACKAGE_VERSION, SequentialIdGenerator, createEnhancedProxy, getEnhancedProxyTarget, getPackageSymbol, isAsyncIteratorObject, isTypescriptObject, parseEmptyableJSON, sequential, sleep, stringifyJSON, toArray, tryDecodeURIComponent };
+export type { AsyncCleanupFn, AsyncIdQueueCloseOptions, AsyncIdQueueOptions, AsyncIteratorClassNextFn, EnhancedProxyHandler };

package/dist/index.mjs

@@ -0,0 +1,253 @@
+function toArray(value) {
+  return Array.isArray(value) ? value : value === void 0 || value === null ? [] : [value];
+}
+
+const PACKAGE_NAME = "@standardserver/shared";
+const PACKAGE_VERSION = "0.0.0";
+function getPackageSymbol(name) {
+  return Symbol.for(`${PACKAGE_NAME}@${PACKAGE_VERSION}/${name}`);
+}
+
+class AbortError extends Error {
+  constructor(...rest) {
+    super(...rest);
+    this.name = "AbortError";
+  }
+}
+
+function sequential(fn) {
+  let lastOperationPromise = Promise.resolve();
+  return (...args) => {
+    return lastOperationPromise = lastOperationPromise.catch(() => {
+    }).then(() => {
+      return fn(...args);
+    });
+  };
+}
+
+class SequentialIdGenerator {
+  index = BigInt(1);
+  generate() {
+    const id = this.index.toString(36);
+    this.index++;
+    return id;
+  }
+}
+
+function isAsyncIteratorObject(maybe) {
+  if (!maybe || typeof maybe !== "object") {
+    return false;
+  }
+  return "next" in maybe && typeof maybe.next === "function" && Symbol.asyncIterator in maybe && typeof maybe[Symbol.asyncIterator] === "function";
+}
+const fallbackAsyncDisposeSymbol = Symbol.for("asyncDispose");
+const asyncDisposeSymbol = Symbol.asyncDispose ?? fallbackAsyncDisposeSymbol;
+class AsyncIteratorClass {
+  isDone = false;
+  isExecuteComplete = false;
+  cleanup;
+  next;
+  constructor(next, cleanup) {
+    this.cleanup = cleanup;
+    this.next = sequential(async () => {
+      if (this.isDone) {
+        return { done: true, value: void 0 };
+      }
+      try {
+        const result = await next();
+        if (result.done) {
+          this.isDone = true;
+        }
+        return result;
+      } catch (err) {
+        this.isDone = true;
+        throw err;
+      } finally {
+        if (this.isDone && !this.isExecuteComplete) {
+          this.isExecuteComplete = true;
+          await this.cleanup(true);
+        }
+      }
+    });
+  }
+  async return(value) {
+    this.isDone = true;
+    if (!this.isExecuteComplete) {
+      this.isExecuteComplete = true;
+      await this.cleanup(false);
+    }
+    return { done: true, value };
+  }
+  async throw(err) {
+    this.isDone = true;
+    if (!this.isExecuteComplete) {
+      this.isExecuteComplete = true;
+      await this.cleanup(false);
+    }
+    throw err;
+  }
+  /**
+   * asyncDispose symbol only available in esnext, we should fallback to Symbol.for('asyncDispose')
+   */
+  async [asyncDisposeSymbol]() {
+    this.isDone = true;
+    if (!this.isExecuteComplete) {
+      this.isExecuteComplete = true;
+      await this.cleanup(false);
+    }
+  }
+  [Symbol.asyncIterator]() {
+    return this;
+  }
+}
+
+function parseEmptyableJSON(text) {
+  if (!text) {
+    return void 0;
+  }
+  return JSON.parse(text);
+}
+function stringifyJSON(value) {
+  return JSON.stringify(value);
+}
+
+function isTypescriptObject(maybeObject) {
+  if (!maybeObject) {
+    return false;
+  }
+  const type = typeof maybeObject;
+  return type === "object" || type === "function";
+}
+
+const ENHANCED_PROXY_TARGET_SYMBOL = getPackageSymbol("ENHANCED_PROXY_TARGET");
+function createEnhancedProxy(target, handler) {
+  const boundMethodCache = /* @__PURE__ */ new WeakMap();
+  return new Proxy(target, {
+    ...handler,
+    get(target2, p, receiver) {
+      if (p === ENHANCED_PROXY_TARGET_SYMBOL) {
+        return target2;
+      }
+      return handler.get(target2, p, receiver, () => {
+        const value = Reflect.get(target2, p);
+        if (typeof value !== "function") {
+          return value;
+        }
+        const cached = boundMethodCache.get(value);
+        if (cached) {
+          return cached;
+        }
+        const bound = value.bind(target2);
+        boundMethodCache.set(value, bound);
+        return bound;
+      });
+    }
+  });
+}
+function getEnhancedProxyTarget(value) {
+  return value[ENHANCED_PROXY_TARGET_SYMBOL] ?? value;
+}
+
+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);
+      }
+    } 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);
+      }
+    }
+  }
+  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);
+      }
+      return item;
+    }
+    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]);
+      }
+    });
+  }
+  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();
+      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.`);
+    }
+  }
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function tryDecodeURIComponent(value) {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+}
+
+export { AbortError, AsyncIdQueue, AsyncIteratorClass, PACKAGE_NAME, PACKAGE_VERSION, SequentialIdGenerator, createEnhancedProxy, getEnhancedProxyTarget, getPackageSymbol, isAsyncIteratorObject, isTypescriptObject, parseEmptyableJSON, sequential, sleep, stringifyJSON, toArray, tryDecodeURIComponent };

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@standardserver/shared",
+  "type": "module",
+  "version": "0.0.0",
+  "license": "MIT",
+  "homepage": "https://standardserver.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/standardserver/standardserver.git",
+    "directory": "packages/shared"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "unbuild",
+    "type:check": "tsc -b"
+  }
+}