@ad-sdk/bgd 0.0.2 → 0.0.3

package/cancellation.d.ts

@@ -0,0 +1,74 @@
+import { type IDisposable } from "./lifecycle/disposable";
+/**
+ * Type defining a listener function for cancellation requests.
+ *
+ * @callback CancellationRequestListener
+ * @param listener - A function to handle the cancellation event.
+ * @param thisArgs - Optional `this` context for the listener function.
+ * @param disposables - Optional array to collect IDisposable resources.
+ * @returns {IDisposable} A disposable object to cancel the listener.
+ */
+export type CancellationRequestListener = (listener: (e: unknown) => unknown, thisArgs?: unknown, disposables?: IDisposable[]) => IDisposable;
+/**
+ * Interface representing a cancellation token that signals whether cancellation has been requested
+ * and includes an event listener for responding to cancellation requests.
+ */
+export interface ICancellationToken {
+    /**
+       * A flag signalling is cancellation has been requested.
+       */
+    readonly isCancellationRequested: boolean;
+    /**
+     * An event which fires when cancellation is requested. This event
+     * only ever fires `once` as cancellation can only happen once. Listeners
+     * that are registered after cancellation will be called (next event loop run),
+     * but also only once.
+     *
+     * @event
+     */
+    readonly onCancellationRequested: CancellationRequestListener;
+}
+/**
+ * Checks if the provided argument is an ICancellationToken.
+ *
+ * @param arg - The object to check.
+ * @returns {boolean} `true` if `arg` is an ICancellationToken, otherwise `false`.
+ */
+export declare function isCancellationToken(arg: unknown): arg is ICancellationToken;
+export declare namespace CancellationToken {
+    const None: Readonly<ICancellationToken>;
+    const Cancelled: Readonly<ICancellationToken>;
+}
+export declare class CancellationTokenSource {
+    private readonly _parent?;
+    private _token?;
+    private _parentListener?;
+    /**
+     * Constructs a CancellationTokenSource, optionally linked to a parent token to cascade cancellations.
+     *
+     * @param _parent - Optional parent cancellation token.
+     */
+    constructor(_parent?: ICancellationToken | undefined);
+    /**
+     * Gets the associated cancellation token, creating it if necessary.
+     */
+    get token(): ICancellationToken;
+    /**
+     * Gets the parent cancellation token, if any.
+     */
+    get parent(): ICancellationToken | undefined;
+    /**
+     * Requests cancellation for the token, optionally providing a reason and a stack trace location.
+     *
+     * @param reason - Optional reason for the cancellation.
+     * @param location - Optional stack trace location.
+     */
+    cancel(reason?: unknown): void;
+    /**
+     * Disposes of the token source, optionally canceling it before disposal.
+     *
+     * @param cancel - If `true`, requests cancellation before disposal.
+     * @param cancellationReason - Optional reason for cancellation.
+     */
+    dispose(cancel?: boolean, cancellationReason?: unknown): void;
+}

package/cancellation.js

@@ -0,0 +1,185 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.CancellationTokenSource = exports.CancellationToken = void 0;
+exports.isCancellationToken = isCancellationToken;
+var _nodeEvents = require("node:events");
+var _runtime = require("./runtime");
+var _disposable = require("./lifecycle/disposable");
+function _defineProperty(e, r, t) { return (r = _toPropertyKey(r)) in e ? Object.defineProperty(e, r, { value: t, enumerable: !0, configurable: !0, writable: !0 }) : e[r] = t, e; }
+function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == typeof i ? i : i + ""; }
+function _toPrimitive(t, r) { if ("object" != typeof t || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != typeof i) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
+/**
+ * Type defining a listener function for cancellation requests.
+ * 
+ * @callback CancellationRequestListener
+ * @param listener - A function to handle the cancellation event.
+ * @param thisArgs - Optional `this` context for the listener function.
+ * @param disposables - Optional array to collect IDisposable resources.
+ * @returns {IDisposable} A disposable object to cancel the listener.
+ */
+
+/**
+ * Interface representing a cancellation token that signals whether cancellation has been requested
+ * and includes an event listener for responding to cancellation requests.
+ */
+
+const shortcutEvent = Object.freeze(function (callback, context) {
+  return (0, _runtime.immediate)(callback.bind(context));
+});
+
+/**
+ * Checks if the provided argument is an ICancellationToken.
+ *
+ * @param arg - The object to check.
+ * @returns {boolean} `true` if `arg` is an ICancellationToken, otherwise `false`.
+ */
+function isCancellationToken(arg) {
+  if (typeof arg !== "object" || !arg || Array.isArray(arg)) return false;
+  const candidate = arg;
+  return typeof candidate.isCancellationRequested === "boolean" && typeof candidate.onCancellationRequested === "function";
+}
+
+// eslint-disable-next-line @typescript-eslint/no-namespace
+let CancellationToken = exports.CancellationToken = void 0;
+(function (_CancellationToken) {
+  const None = _CancellationToken.None = Object.freeze({
+    isCancellationRequested: false,
+    onCancellationRequested: () => Object.freeze({
+      dispose() {}
+    })
+  });
+  const Cancelled = _CancellationToken.Cancelled = Object.freeze({
+    isCancellationRequested: true,
+    onCancellationRequested: shortcutEvent
+  });
+})(CancellationToken || (exports.CancellationToken = CancellationToken = {}));
+class MutableToken extends _disposable.Disposable {
+  constructor(...args) {
+    super(...args);
+    _defineProperty(this, "_isCancelled", false);
+    _defineProperty(this, "_emitter", null);
+  }
+  /**
+   * Returns whether cancellation has been requested.
+   */
+  get isCancellationRequested() {
+    return this._isCancelled;
+  }
+
+  /**
+   * Returns an event listener for cancellation requests. If cancellation has been requested, returns an immediate event.
+   */
+  get onCancellationRequested() {
+    if (this._isCancelled) return shortcutEvent;
+    if (!this._emitter) {
+      this._emitter = new _nodeEvents.EventEmitter({
+        captureRejections: false
+      });
+    }
+    return (listener, thisArgs, disposables) => {
+      if (!this._isCancelled) {
+        this._emitter?.addListener("cancellationrequest", thisArgs ? listener.bind(thisArgs) : listener);
+        return;
+      }
+      if (disposables && Array.isArray(disposables)) {
+        disposables.push(shortcutEvent(listener, thisArgs));
+        for (const d of disposables) {
+          super._register(d);
+        }
+        return void 0;
+      }
+      return listener.call(thisArgs, void 0);
+    };
+  }
+
+  /**
+   * Requests cancellation, firing the cancellation event if applicable.
+   * 
+   * @param reason - Optional reason for the cancellation.
+   */
+  cancel(reason) {
+    if (this._isCancelled) return;
+    this._isCancelled = true;
+    if (!this._emitter) return this.dispose();
+    this._emitter.emit("cancellationrequest", reason ?? void 0);
+    this.dispose();
+  }
+
+  /**
+   * Disposes of the resources associated with the cancellation token.
+   */
+  dispose() {
+    if (this._emitter instanceof _nodeEvents.EventEmitter) {
+      this._emitter?.removeAllListeners();
+      this._emitter = null;
+    }
+    super.dispose();
+  }
+}
+class CancellationTokenSource {
+  /**
+   * Constructs a CancellationTokenSource, optionally linked to a parent token to cascade cancellations.
+   *
+   * @param _parent - Optional parent cancellation token.
+   */
+  constructor(_parent) {
+    _defineProperty(this, "_token", null);
+    _defineProperty(this, "_parentListener", null);
+    this._parent = _parent;
+    if (!_parent) return;
+    this._parentListener = _parent.onCancellationRequested(this.cancel, this);
+  }
+
+  /**
+   * Gets the associated cancellation token, creating it if necessary.
+   */
+  get token() {
+    if (!this._token) {
+      this._token = new MutableToken();
+    }
+    return this._token;
+  }
+
+  /**
+   * Gets the parent cancellation token, if any.
+   */
+  get parent() {
+    return this._parent;
+  }
+
+  /**
+   * Requests cancellation for the token, optionally providing a reason and a stack trace location.
+   *
+   * @param reason - Optional reason for the cancellation.
+   * @param location - Optional stack trace location.
+   */
+  cancel(reason) {
+    if (!this._token) {
+      this._token = CancellationToken.Cancelled;
+    } else if (this._token instanceof MutableToken) {
+      this._token.cancel(reason);
+    }
+  }
+
+  /**
+   * Disposes of the token source, optionally canceling it before disposal.
+   *
+   * @param cancel - If `true`, requests cancellation before disposal.
+   * @param cancellationReason - Optional reason for cancellation.
+   */
+  dispose(cancel = false, cancellationReason) {
+    if (cancel === true) {
+      this.cancel(cancellationReason);
+    }
+    this._parentListener?.dispose();
+    if (!this._token) {
+      this._token = CancellationToken.None;
+    } else if (this._token instanceof MutableToken) {
+      this._token.dispose();
+    }
+  }
+}
+exports.CancellationTokenSource = CancellationTokenSource;

package/mathlib/core.d.ts

@@ -13,5 +13,6 @@ export declare namespace MathLib {
         [K in keyof T]: T[K] extends (infer U)[] ? U : never;
     }[];
     export function zip<T extends unknown[][]>(...args: T): ZipResult<T>;
+    export function clamp(x: number, min: number, max: number): number;
     export {};
 }

package/mathlib/core.js

@@ -26,4 +26,8 @@ let MathLib = exports.MathLib = void 0;
     return result;
   }
   _MathLib.zip = zip;
+  function clamp(x, min, max) {
+    return Math.min(Math.max(x, min), max);
+  }
+  _MathLib.clamp = clamp;
 })(MathLib || (exports.MathLib = MathLib = {}));

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ad-sdk/bgd",
-  "version": "0.0.2",
-  "main": "dist/index.js",
+  "version": "0.0.3",
+  "main": "index.js",
   "license": "BSD-3-Clause",
   "repository": {
     "type": "git",

package/runtime.d.ts

@@ -0,0 +1,2 @@
+import { type IDisposable } from "./lifecycle";
+export declare function immediate<TArgs extends unknown[]>(callback: (...args: TArgs) => void, ...args: TArgs): IDisposable & Disposable;

package/runtime.js

@@ -0,0 +1,26 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.immediate = immediate;
+function immediate(callback, ...args) {
+  const hasNativeMethod = typeof setImmediate === "function";
+  const id = hasNativeMethod ? setImmediate(callback, ...args) : setTimeout(callback, 0, ...args);
+  return {
+    dispose() {
+      if (hasNativeMethod) {
+        clearImmediate(id);
+      } else {
+        clearTimeout(id);
+      }
+    },
+    [Symbol.dispose]() {
+      if (hasNativeMethod) {
+        clearImmediate(id);
+      } else {
+        clearTimeout(id);
+      }
+    }
+  };
+}