@ariestools/sdk 7.0.3

package/dist/_pkg/creatable/neutral/index.mjs

@@ -0,0 +1,396 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result) __defProp(target, key, result);
+  return result;
+};
+
+// src/AbstractCreatable.ts
+import { assertEx } from "../../assert/neutral/index.mjs";
+import { BaseEmitter } from "../../events/neutral/index.mjs";
+import { spanRoot, spanRootAsync } from "../../telemetry/neutral/index.mjs";
+import {
+  isError,
+  isNumber as isNumber2,
+  isString,
+  isUndefined
+} from "../../typeof/neutral/index.mjs";
+import { Mutex } from "async-mutex";
+
+// src/Creatable.ts
+function creatable() {
+  return (constructor) => {
+    constructor;
+  };
+}
+function creatableFactory() {
+  return (constructor) => {
+    constructor;
+  };
+}
+
+// src/Factory.ts
+var Factory = class _Factory {
+  /** The Creatable class this factory delegates creation to. */
+  creatable;
+  /** Default parameters merged into every `create` call. */
+  defaultParams;
+  /** Labels identifying resources created by this factory. */
+  labels;
+  constructor(creatable2, params, labels = {}) {
+    this.creatable = creatable2;
+    this.defaultParams = params;
+    this.labels = Object.assign({}, creatable2.labels ?? {}, labels ?? {});
+  }
+  /**
+   * Creates a new Factory instance with the given default params and labels.
+   * @param creatableModule - The Creatable class to wrap
+   * @param params - Default parameters for new instances
+   * @param labels - Labels to assign to created instances
+   */
+  static withParams(creatableModule, params, labels = {}) {
+    return new _Factory(creatableModule, params, labels);
+  }
+  /**
+   * Creates a new instance, merging the provided params over the factory defaults.
+   * @param params - Optional parameters to override the factory defaults
+   */
+  create(params) {
+    const mergedParams = {
+      ...this.defaultParams,
+      ...params
+    };
+    return this.creatable.create(mergedParams);
+  }
+};
+
+// src/lib/getFunctionName.ts
+import { isNumber } from "../../typeof/neutral/index.mjs";
+function getFunctionName(depth = 2) {
+  const error = new Error("Stack");
+  let newIndex;
+  const stackParts = error.stack?.split("\n")[depth]?.split(" ");
+  const funcName = stackParts?.find((item, index) => {
+    if (!(item.length > 0 && item !== "at")) {
+      return;
+    }
+    if (item === "new") {
+      newIndex = index;
+    }
+    return true;
+  }) ?? "<unknown>";
+  return isNumber(newIndex) ? `${funcName} ${stackParts?.[newIndex + 1]}` : funcName;
+}
+
+// src/lib/getRootFunction.ts
+var getPrototype = (value) => {
+  const prototype = Object.getPrototypeOf(value);
+  return typeof prototype === "object" ? prototype : null;
+};
+function getRootFunction(obj, funcName) {
+  if (obj === null || typeof obj !== "object") return void 0;
+  let current = obj;
+  let prototype = getPrototype(current);
+  while (prototype !== null && prototype[funcName] !== void 0) {
+    current = prototype;
+    prototype = getPrototype(current);
+  }
+  return current[funcName];
+}
+
+// src/AbstractCreatable.ts
+var AbstractCreatableConstructorKey = /* @__PURE__ */ Symbol.for("AbstractCreatableConstructor");
+var CREATABLE_NOT_STARTED = "Creatable not Started";
+var AbstractCreatable = class extends BaseEmitter {
+  /** Optional default logger for this instance. */
+  defaultLogger;
+  _startPromise;
+  _status = null;
+  _statusMutex = new Mutex();
+  _validatedParams;
+  constructor(key, params) {
+    assertEx(key === AbstractCreatableConstructorKey, () => "AbstractCreatable should not be instantiated directly, use the static create method instead");
+    super(params);
+  }
+  /** The name identifier for this creatable instance. */
+  get name() {
+    return this.params.name;
+  }
+  /** The validated and merged parameters for this instance. */
+  get params() {
+    this._validatedParams ??= this.paramsValidator(super.params);
+    return this._validatedParams;
+  }
+  /** Whether this instance can be started (must be in 'created' or 'stopped' status). */
+  get startable() {
+    return this.status === "created" || this.status === "stopped";
+  }
+  /** The current lifecycle status of this instance, or null if not yet initialized. */
+  get status() {
+    return this._status;
+  }
+  /** The status reporter used to broadcast lifecycle changes. */
+  get statusReporter() {
+    return this.params.statusReporter;
+  }
+  /**
+   * Asynchronously creates a new instance by processing params, constructing,
+   * and running both static and instance createHandlers.
+   * @param inParams - Optional partial parameters to configure the instance
+   * @returns The fully initialized instance
+   */
+  static async create(inParams = {}) {
+    const params = await this.paramsHandler(inParams);
+    const name = params.name ?? this.name;
+    try {
+      const [Constructor] = [this];
+      const instance = new Constructor(AbstractCreatableConstructorKey, params);
+      instance.setStatus("creating");
+      const initializedInstance = await this.createHandler(instance);
+      await instance.createHandler();
+      instance.setStatus("created");
+      return initializedInstance;
+    } catch (ex) {
+      params.statusReporter?.report(name, "error", isError(ex) ? ex : new Error(`Error creating: ${name}`));
+      params.logger?.error(`Error creating creatable [${name}]: ${isError(ex) ? `${ex.message} ${ex.stack}` : String(ex)}`);
+      throw isError(ex) ? ex : new Error(`Error creating: ${name}`);
+    }
+  }
+  /**
+   * Static hook called during creation to perform additional initialization.
+   * Override in subclasses to customize post-construction setup.
+   * @param instance - The newly constructed instance
+   * @returns The instance, potentially modified
+   */
+  static createHandler(instance) {
+    return instance;
+  }
+  /**
+   * Static hook called during creation to validate and transform params.
+   * Override in subclasses to add default values or validation.
+   * @param params - The raw partial params provided to `create`
+   * @returns The processed params ready for construction
+   */
+  static paramsHandler(params = {}) {
+    return { ...params };
+  }
+  /** Instance-level creation hook. Override in subclasses to perform setup after construction. */
+  createHandler() {
+    assertEx(this._status === "creating", () => `createHandler can not be called [status = ${this.status}]`);
+  }
+  /**
+   * Validates and returns the merged params, ensuring required fields are present.
+   * Override in subclasses to add custom validation logic.
+   * @param params - The raw partial params to validate
+   * @returns The validated params
+   */
+  paramsValidator(params) {
+    return { ...params, name: params.name };
+  }
+  /**
+   * Executes a function within a telemetry span.
+   * @param name - The span name
+   * @param fn - The function to execute within the span
+   */
+  span(name, fn) {
+    return spanRoot(name, fn, this.tracer);
+  }
+  /**
+   * Executes an async function within a telemetry span.
+   * @param name - The span name
+   * @param fn - The async function to execute within the span
+   * @param config - Optional span configuration
+   */
+  async spanAsync(name, fn, config = {}) {
+    return await spanRootAsync(name, fn, {
+      ...config,
+      tracer: config.tracer ?? this.tracer,
+      logger: config.logger ?? this.defaultLogger
+    });
+  }
+  /**
+   * Starts the instance, transitioning through 'starting' to 'started' status.
+   * Thread-safe via mutex. Returns true if already started or started successfully.
+   */
+  async start() {
+    this._noOverride("start");
+    if (this.status === "started") {
+      return true;
+    }
+    return await this._statusMutex.runExclusive(async () => {
+      try {
+        if (this.status === "started") {
+          return true;
+        }
+        assertEx(this.startable, () => `Creatable [${this.name}] is not startable in status [${this.status}]`);
+        this.setStatus("starting");
+        await this.startHandler();
+        this.setStatus("started");
+        return true;
+      } catch (ex) {
+        this.setStatus("error", isError(ex) ? ex : new Error(`Error starting: ${String(ex)}`));
+        this.logger?.error(`Error starting creatable [${this.name}]: ${isError(ex) ? `${ex.message} ${ex.stack}` : String(ex)}`);
+        return false;
+      }
+    });
+  }
+  /**
+   * Checks whether this instance is currently started.
+   * Takes an action if not started, based on the notStartedAction parameter.
+   * @param notStartedAction - What to do if not started: 'error'/'throw' throws, 'warn'/'log' logs, 'none' is silent
+   * @returns True if started, false otherwise
+   */
+  started(notStartedAction = "log") {
+    if (isString(this.status) && this.status === "started") {
+      return true;
+    }
+    const message = () => `${CREATABLE_NOT_STARTED} [${this.name}] current state: ${this.status}`;
+    switch (notStartedAction) {
+      case "error": {
+        throw new Error(message());
+      }
+      case "throw": {
+        throw new Error(message());
+      }
+      case "warn": {
+        this.logger?.warn(message());
+        break;
+      }
+      case "log": {
+        this.logger?.log(message());
+        break;
+      }
+      case "none": {
+        break;
+      }
+      default: {
+        throw new Error(`Unknown notStartedAction: ${notStartedAction}`);
+      }
+    }
+    return false;
+  }
+  /**
+   * Async version of `started` that can optionally auto-start the instance.
+   * @param notStartedAction - What to do if not started and auto-start is disabled
+   * @param tryStart - If true, attempts to start the instance automatically
+   * @returns True if the instance is or becomes started
+   */
+  async startedAsync(notStartedAction = "log", tryStart = true) {
+    if (isString(this.status) && this.status === "started") {
+      return true;
+    }
+    if (this.status !== null && ["created", "stopped", "starting"].includes(this.status)) {
+      this._startPromise ??= (async () => {
+        if (tryStart) {
+          try {
+            return await this.start();
+          } finally {
+            this._startPromise = void 0;
+          }
+        }
+        return this.started(notStartedAction);
+      })();
+    } else {
+      const message = `${CREATABLE_NOT_STARTED} [${this.name}] current state: ${this.status}`;
+      throw new Error(message);
+    }
+    if (isUndefined(this._startPromise)) {
+      throw new Error(`Failed to create start promise: ${this.status}`);
+    }
+    return await this._startPromise;
+  }
+  /**
+   * Stops the instance, transitioning through 'stopping' to 'stopped' status.
+   * Thread-safe via mutex. Returns true if already stopped or stopped successfully.
+   */
+  async stop() {
+    this._noOverride("stop");
+    if (this.status === "stopped") {
+      return true;
+    }
+    return await this._statusMutex.runExclusive(async () => {
+      try {
+        if (this.status === "stopped") {
+          return true;
+        }
+        assertEx(this.status === "started", () => `Creatable [${this.name}] is not stoppable in status [${this.status}]`);
+        this.setStatus("stopping");
+        await this.stopHandler();
+        this.setStatus("stopped");
+        return true;
+      } catch (ex) {
+        this.setStatus("error", isError(ex) ? ex : new Error(`Error stopping: ${String(ex)}`));
+        return false;
+      }
+    });
+  }
+  /**
+   * Asserts that the given function has not been overridden in a subclass.
+   * Used to enforce the handler pattern (override `startHandler` not `start`).
+   */
+  _noOverride(functionName = getFunctionName(3)) {
+    const thisFunc = this[functionName];
+    const rootFunc = getRootFunction(this, functionName);
+    assertEx(thisFunc === rootFunc, () => `Override not allowed for [${functionName}] - override ${functionName}Handler instead`);
+  }
+  setStatus(value, progressOrError) {
+    this._status = value;
+    if (value !== null) {
+      if (value === "error") {
+        if (isError(progressOrError)) {
+          this.statusReporter?.report(this.name, value, progressOrError);
+          return;
+        }
+      } else {
+        if (isNumber2(progressOrError)) {
+          this.statusReporter?.report(this.name, value, progressOrError);
+          return;
+        }
+      }
+      this.statusReporter?.report(this.name, value);
+    }
+  }
+  /** Override in subclasses to define start behavior. Throw an error on failure. */
+  startHandler() {
+  }
+  /** Override in subclasses to define stop behavior. Throw an error on failure. */
+  stopHandler() {
+  }
+};
+AbstractCreatable = __decorateClass([
+  creatable()
+], AbstractCreatable);
+var AbstractCreatableWithFactory = class extends AbstractCreatable {
+  /**
+   * Creates a factory that produces instances of this class with pre-configured params and labels.
+   * @param params - Default parameters for instances created by the factory
+   * @param labels - Labels to assign to created instances
+   */
+  static factory(params, labels) {
+    return Factory.withParams(this, params, labels);
+  }
+};
+AbstractCreatableWithFactory = __decorateClass([
+  creatable()
+], AbstractCreatableWithFactory);
+
+// src/model/Labels.ts
+var hasAllLabels = (source, required) => {
+  if (!required) return true;
+  return Object.entries(required).every(([key, value]) => {
+    return Object.hasOwn(source ?? {}, key) && source?.[key] === value;
+  });
+};
+export {
+  AbstractCreatable,
+  AbstractCreatableWithFactory,
+  Factory,
+  creatable,
+  creatableFactory,
+  hasAllLabels
+};
+//# sourceMappingURL=index.mjs.map

package/dist/_pkg/creatable/neutral/lib/getFunctionName.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Extracts the function name from the call stack at the given depth.
+ * @param depth - The stack frame depth to inspect (default: 2)
+ * @returns The function name, or '\<unknown\>' if it cannot be determined
+ */
+export declare function getFunctionName(depth?: number): string;
+//# sourceMappingURL=getFunctionName.d.ts.map

package/dist/_pkg/creatable/neutral/lib/getRootFunction.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Walks the prototype chain to find the root (base-most) definition of a named function.
+ * @param obj - The object to start searching from
+ * @param funcName - The name of the function to locate
+ * @returns The function from the highest prototype in the chain that defines it
+ */
+export declare function getRootFunction(obj: unknown, funcName: string): unknown;
+//# sourceMappingURL=getRootFunction.d.ts.map

package/dist/_pkg/creatable/neutral/lib/index.d.ts

@@ -0,0 +1,3 @@
+export * from './getFunctionName.ts';
+export * from './getRootFunction.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/_pkg/creatable/neutral/model/CreatableInstance.d.ts

@@ -0,0 +1,16 @@
+import type { EventData, EventEmitter } from '../../../events/neutral/index.ts';
+import type { CreatableName, CreatableParams } from './CreatableParams.ts';
+/** Represents a created instance with a managed lifecycle (start/stop) and event emission. */
+export interface CreatableInstance<TParams extends CreatableParams = CreatableParams, TEventData extends EventData = EventData> extends EventEmitter<TEventData> {
+    /** The event data type associated with this instance. */
+    eventData: TEventData;
+    /** The name identifier for this instance. */
+    name: CreatableName;
+    /** The parameters used to configure this instance. */
+    params: TParams;
+    /** Starts the instance. Resolves to true if started successfully. */
+    start: () => Promise<boolean>;
+    /** Stops the instance. Resolves to true if stopped successfully. */
+    stop: () => Promise<boolean>;
+}
+//# sourceMappingURL=CreatableInstance.d.ts.map

package/dist/_pkg/creatable/neutral/model/CreatableParams.d.ts

@@ -0,0 +1,16 @@
+import type { BaseClassName } from '../../../base/neutral/index.ts';
+import type { BaseEmitterParams } from '../../../events/neutral/index.ts';
+import type { CreatableStatus, CreatableStatusReporter } from './CreatableStatusReporter.ts';
+/** A branded string type used as the name identifier for creatables. */
+export type CreatableName = Exclude<string, 'creatable-name-reserved-32546239486'> & BaseClassName;
+/** The minimum required parameters for constructing a creatable. */
+export interface RequiredCreatableParams<TAdditionalStatus extends CreatableStatus | void = void> extends BaseEmitterParams {
+    /** Optional name identifying this creatable instance. */
+    name?: CreatableName;
+    /** Optional reporter for broadcasting status changes. */
+    statusReporter?: CreatableStatusReporter<TAdditionalStatus>;
+}
+/** Parameters for creating a creatable instance, combining required params with emitter params. */
+export interface CreatableParams extends RequiredCreatableParams, BaseEmitterParams {
+}
+//# sourceMappingURL=CreatableParams.d.ts.map

package/dist/_pkg/creatable/neutral/model/CreatableStatusReporter.d.ts

@@ -0,0 +1,15 @@
+import type { BaseClassName } from '../../../base/neutral/index.ts';
+/** The standard lifecycle statuses a creatable can transition through. */
+export type StandardCreatableStatus = 'creating' | 'created' | 'starting' | 'started' | 'stopping' | 'stopped' | 'error';
+/** A creatable's status, optionally extended with additional custom status values. */
+export type CreatableStatus<TAdditionalStatus extends void | string = void> = StandardCreatableStatus | (TAdditionalStatus extends void ? StandardCreatableStatus : TAdditionalStatus);
+/** Reports status changes for a creatable, supporting progress tracking and error reporting. */
+export interface CreatableStatusReporter<TAdditionalStatus extends void | string = void> {
+    /** Report a non-error status with a numeric progress value. */
+    report(name: BaseClassName, status: Exclude<CreatableStatus<TAdditionalStatus>, 'error'>, progress: number): void;
+    /** Report an error status with the associated Error. */
+    report(name: BaseClassName, status: Extract<CreatableStatus<TAdditionalStatus>, 'error'>, error: Error): void;
+    /** Report a status change without progress or error details. */
+    report(name: BaseClassName, status: CreatableStatus<TAdditionalStatus>): void;
+}
+//# sourceMappingURL=CreatableStatusReporter.d.ts.map

package/dist/_pkg/creatable/neutral/model/Labels.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Object used to represent labels identifying a resource.
+ */
+export type Labels = Record<string, string | undefined>;
+/**
+ * Interface for objects that have labels.
+ */
+export interface WithLabels<T extends Labels = Labels> {
+    labels: T;
+}
+/**
+ * Interface for objects that have labels.
+ */
+export interface WithOptionalLabels<T extends Labels = Labels> {
+    labels?: T;
+}
+/**
+ * Returns true if the source object has all the labels from the required set
+ * @param source Source object to check against
+ * @param required Set of labels to check for in source
+ * @returns True of the source object has all the labels from the required set
+ */
+export declare const hasAllLabels: (source?: Labels, required?: Labels) => boolean;
+//# sourceMappingURL=Labels.d.ts.map

package/dist/_pkg/creatable/neutral/model/index.d.ts

@@ -0,0 +1,5 @@
+export * from './CreatableInstance.ts';
+export * from './CreatableParams.ts';
+export * from './CreatableStatusReporter.ts';
+export * from './Labels.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/_pkg/creatable/neutral/model.d.ts

@@ -0,0 +1,3 @@
+export type * from './Creatable.ts';
+export type * from './model/index.ts';
+//# sourceMappingURL=model.d.ts.map

package/dist/_pkg/creatable/neutral/model.mjs

@@ -0,0 +1 @@
+//# sourceMappingURL=model.mjs.map

package/dist/_pkg/decimal-precision/neutral/fromFixedPoint.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Converts a fixed-point bigint back to a whole-number bigint by dividing out the decimal places.
+ * @param value - The fixed-point bigint value to convert
+ * @param places - Number of decimal places (default 18)
+ * @returns The whole-number bigint result
+ */
+export declare const fromFixedPoint: (value: bigint, places?: number) => bigint;
+//# sourceMappingURL=fromFixedPoint.d.ts.map

package/dist/_pkg/decimal-precision/neutral/index.d.ts

@@ -0,0 +1,4 @@
+export * from './fromFixedPoint.ts';
+export * from './toDecimalPrecision.ts';
+export * from './toFixedPoint.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/_pkg/decimal-precision/neutral/index.mjs

@@ -0,0 +1,39 @@
+// src/fromFixedPoint.ts
+var fromFixedPoint = (value, places = 18) => {
+  if (!Number.isSafeInteger(places)) throw new Error(`places (${places}) must be an Integer`);
+  return value / 10n ** BigInt(places);
+};
+
+// src/toDecimalPrecision.ts
+var toDecimalPrecision = (value, digits) => {
+  let fixed = 0;
+  const result = Number(value.toPrecision(digits));
+  while (Number(result.toFixed(fixed)) !== result && fixed < 20) {
+    fixed++;
+  }
+  return result.toFixed(fixed);
+};
+
+// src/toFixedPoint.ts
+var toFixedPoint = (value, places = 18) => {
+  if (!Number.isSafeInteger(places)) throw new Error(`places (${places}) must be an Integer`);
+  if (typeof value === "string") {
+    const parts = value.split(".");
+    if (parts.length > 2) {
+      throw new Error("Too many decimals in value");
+    }
+    if (parts.length === 1) {
+      return BigInt(value) * 10n ** BigInt(places);
+    }
+    const [whole, fraction] = parts;
+    const trimmed = fraction.slice(0, places);
+    return BigInt(whole + trimmed.padEnd(Number(places), "0"));
+  }
+  return value * 10n ** BigInt(places);
+};
+export {
+  fromFixedPoint,
+  toDecimalPrecision,
+  toFixedPoint
+};
+//# sourceMappingURL=index.mjs.map

package/dist/_pkg/decimal-precision/neutral/toDecimalPrecision.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Formats a number to the specified number of significant digits, returning a string with minimal trailing zeros.
+ * @param value - The number to format
+ * @param digits - The number of significant digits
+ * @returns A string representation of the number with the specified precision
+ */
+export declare const toDecimalPrecision: (value: number, digits: number) => string;
+//# sourceMappingURL=toDecimalPrecision.d.ts.map

package/dist/_pkg/decimal-precision/neutral/toFixedPoint.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Converts a bigint or decimal string to a fixed-point bigint representation.
+ * @param value - The value to convert (bigint or string with optional decimal point)
+ * @param places - Number of decimal places (default 18)
+ * @returns A bigint representing the value scaled by 10^places
+ */
+export declare const toFixedPoint: (value: bigint | string, places?: number) => bigint;
+//# sourceMappingURL=toFixedPoint.d.ts.map

package/dist/_pkg/delay/neutral/delay.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Returns a promise that resolves after the specified number of milliseconds.
+ * @param ms - The number of milliseconds to delay.
+ * @returns A promise that resolves after the delay.
+ */
+export declare const delay: (ms: number) => Promise<void>;
+//# sourceMappingURL=delay.d.ts.map

package/dist/_pkg/delay/neutral/index.d.ts

@@ -0,0 +1,2 @@
+export { delay } from './delay.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/_pkg/delay/neutral/index.mjs

@@ -0,0 +1,9 @@
+// src/delay.ts
+import { setTimeoutEx } from "../../timer/neutral/index.mjs";
+var delay = (ms) => {
+  return new Promise((resolve) => setTimeoutEx(() => resolve(), ms));
+};
+export {
+  delay
+};
+//# sourceMappingURL=index.mjs.map

package/dist/_pkg/ellipsize/neutral/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Truncates a string to show the first and last `length` characters separated by an ellipsis.
+ * @param value - The string to ellipsize
+ * @param length - Number of characters to keep at each end (default 2)
+ * @returns The ellipsized string
+ */
+export declare const ellipsize: (value: string, length?: number) => string;
+//# sourceMappingURL=index.d.ts.map

package/dist/_pkg/ellipsize/neutral/index.mjs

@@ -0,0 +1,10 @@
+// src/index.ts
+var ellipsize = (value, length = 2) => {
+  const part1 = value.slice(0, length);
+  const part2 = value.slice(value.length - length);
+  return `${part1}...${part2}`;
+};
+export {
+  ellipsize
+};
+//# sourceMappingURL=index.mjs.map