@ariestools/sdk 7.0.3

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

@@ -0,0 +1,152 @@
+// src/span.ts
+import { isDefined } from "../../typeof/neutral/index.mjs";
+import {
+  context,
+  propagation,
+  ROOT_CONTEXT,
+  SpanStatusCode,
+  trace as TRACE_API
+} from "@opentelemetry/api";
+
+// src/timeBudget.ts
+async function timeBudget(name, logger, func, budget, status = false) {
+  const start = Date.now();
+  const timer = status ? setInterval(() => {
+    const duration2 = Date.now() - start;
+    if (budget > 0 && duration2 > budget) {
+      logger?.warn(`Function [${name}] execution is exceeding budget: ${duration2}ms > ${budget}ms`);
+    }
+  }, Math.max(100, budget)) : void 0;
+  const result = await func();
+  const duration = Date.now() - start;
+  if (timer === void 0 && budget > 0 && duration > budget) {
+    logger?.warn(`Function [${name}] execution exceeded budget: ${duration}ms > ${budget}ms`);
+  }
+  if (timer !== void 0) {
+    clearInterval(timer);
+  }
+  return result;
+}
+
+// src/span.ts
+function cloneContextWithoutSpan(activeCtx, configKeys = []) {
+  let newCtx = ROOT_CONTEXT;
+  const baggage = propagation.getBaggage(activeCtx);
+  if (baggage) {
+    newCtx = propagation.setBaggage(newCtx, baggage);
+  }
+  for (const key of configKeys) {
+    const value = activeCtx.getValue(key);
+    if (value !== void 0) {
+      newCtx = newCtx.setValue(key, value);
+    }
+  }
+  return newCtx;
+}
+function span(name, fn, traceProvider = TRACE_API) {
+  const activeTracer = traceProvider.getTracer(name);
+  if (isDefined(activeTracer)) {
+    const span2 = activeTracer.startSpan(name);
+    return context.with(TRACE_API.setSpan(context.active(), span2), () => {
+      try {
+        const result = fn();
+        span2.setStatus({ code: SpanStatusCode.OK });
+        return result;
+      } catch (ex) {
+        const error = ex;
+        span2.recordException(error);
+        span2.setStatus({ code: SpanStatusCode.ERROR, message: error.message });
+        throw ex;
+      } finally {
+        span2.end();
+      }
+    });
+  }
+  return fn();
+}
+function spanRoot(name, fn, tracer) {
+  const activeTracer = tracer ?? TRACE_API.getTracer(name);
+  if (isDefined(activeTracer)) {
+    const activeContext = context.active();
+    const noSpanContext = cloneContextWithoutSpan(activeContext);
+    const span2 = activeTracer.startSpan(name, {}, noSpanContext);
+    return context.with(TRACE_API.setSpan(noSpanContext, span2), () => {
+      try {
+        const result = fn();
+        span2.setStatus({ code: SpanStatusCode.OK });
+        return result;
+      } catch (ex) {
+        const error = ex;
+        span2.recordException(error);
+        span2.setStatus({ code: SpanStatusCode.ERROR, message: error.message });
+        throw ex;
+      } finally {
+        span2.end();
+      }
+    });
+  }
+  return fn();
+}
+async function spanAsync(name, fn, {
+  timeBudgetLimit,
+  logger,
+  tracer
+} = {}) {
+  const activeTracer = tracer ?? TRACE_API.getTracer(name);
+  const funcToRun = isDefined(timeBudgetLimit) ? () => timeBudget(name, logger ?? console, fn, timeBudgetLimit) : fn;
+  if (isDefined(activeTracer)) {
+    const span2 = activeTracer.startSpan(name);
+    return await context.with(TRACE_API.setSpan(context.active(), span2), async () => {
+      try {
+        const result = await funcToRun();
+        span2.setStatus({ code: SpanStatusCode.OK });
+        return result;
+      } catch (ex) {
+        const error = ex;
+        span2.recordException(error);
+        span2.setStatus({ code: SpanStatusCode.ERROR, message: error.message });
+        throw ex;
+      } finally {
+        span2.end();
+      }
+    });
+  }
+  return await funcToRun();
+}
+async function spanRootAsync(name, fn, {
+  timeBudgetLimit,
+  logger,
+  tracer
+} = {}) {
+  const funcToRun = isDefined(timeBudgetLimit) ? () => timeBudget(name, logger ?? console, fn, timeBudgetLimit) : fn;
+  const activeTracer = tracer ?? TRACE_API.getTracer(name);
+  if (isDefined(activeTracer)) {
+    const activeContext = context.active();
+    const noSpanContext = cloneContextWithoutSpan(activeContext);
+    const span2 = activeTracer.startSpan(name, {}, noSpanContext);
+    return await context.with(TRACE_API.setSpan(noSpanContext, span2), async () => {
+      try {
+        const result = await funcToRun();
+        span2.setStatus({ code: SpanStatusCode.OK });
+        return result;
+      } catch (ex) {
+        const error = ex;
+        span2.recordException(error);
+        span2.setStatus({ code: SpanStatusCode.ERROR, message: error.message });
+        throw ex;
+      } finally {
+        span2.end();
+      }
+    });
+  }
+  return await funcToRun();
+}
+export {
+  cloneContextWithoutSpan,
+  span,
+  spanAsync,
+  spanRoot,
+  spanRootAsync,
+  timeBudget
+};
+//# sourceMappingURL=index.mjs.map

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

@@ -0,0 +1,2 @@
+export type { SpanConfig } from './span.ts';
+//# sourceMappingURL=model.d.ts.map

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

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

package/dist/_pkg/telemetry/neutral/span.d.ts

@@ -0,0 +1,51 @@
+import type { Logger } from '../../logger/neutral/index.ts';
+import type { Context, Tracer, TracerProvider } from '@opentelemetry/api';
+/** Configuration options for span creation and execution. */
+export interface SpanConfig {
+    /** Optional logger for time budget warnings. Falls back to console if not provided. */
+    logger?: Logger | null;
+    /** Maximum allowed execution time in milliseconds before logging a warning. */
+    timeBudgetLimit?: number;
+    /** OpenTelemetry tracer to use. Defaults to a tracer named after the span. */
+    tracer?: Tracer;
+}
+/**
+ * Creates a new OpenTelemetry context that preserves baggage and custom keys but has no active span.
+ * @param activeCtx - The context to clone from.
+ * @param configKeys - Additional context keys to copy.
+ * @returns A new context with baggage but no parent span.
+ */
+export declare function cloneContextWithoutSpan(activeCtx: Context, configKeys?: symbol[]): Context;
+/**
+ * Executes a synchronous function within an OpenTelemetry span, recording status and exceptions.
+ * @param name - The span name.
+ * @param fn - The function to execute.
+ * @param tracer - Optional tracer to use.
+ * @returns The return value of `fn`.
+ */
+export declare function span<T>(name: string, fn: () => T, traceProvider?: TracerProvider): T;
+/**
+ * Executes a synchronous function within a new root span that has no parent, even if a span is already active.
+ * @param name - The span name.
+ * @param fn - The function to execute.
+ * @param tracer - Optional tracer to use.
+ * @returns The return value of `fn`.
+ */
+export declare function spanRoot<T>(name: string, fn: () => T, tracer?: Tracer): T;
+/**
+ * Executes an async function within an OpenTelemetry span, with optional time budget monitoring.
+ * @param name - The span name.
+ * @param fn - The async function to execute.
+ * @param config - Optional span configuration (tracer, logger, time budget).
+ * @returns The resolved value of `fn`.
+ */
+export declare function spanAsync<T>(name: string, fn: () => Promise<T>, { timeBudgetLimit, logger, tracer, }?: SpanConfig): Promise<T>;
+/**
+ * Executes an async function within a new root span (no parent), with optional time budget monitoring.
+ * @param name - The span name.
+ * @param fn - The async function to execute.
+ * @param config - Optional span configuration (tracer, logger, time budget).
+ * @returns The resolved value of `fn`.
+ */
+export declare function spanRootAsync<T>(name: string, fn: () => Promise<T>, { timeBudgetLimit, logger, tracer, }?: SpanConfig): Promise<T>;
+//# sourceMappingURL=span.d.ts.map

package/dist/_pkg/telemetry/neutral/timeBudget.d.ts

@@ -0,0 +1,12 @@
+import type { Logger } from '../../logger/neutral/index.ts';
+/**
+ * Executes an async function and logs a warning if it exceeds the given time budget.
+ * @param name - A label for the function, used in warning messages.
+ * @param logger - The logger to use for budget-exceeded warnings.
+ * @param func - The async function to execute.
+ * @param budget - The time budget in milliseconds.
+ * @param status - If true, logs periodic warnings while the function is still running.
+ * @returns The result of the executed function.
+ */
+export declare function timeBudget<TResult>(name: string, logger: Logger | undefined, func: () => Promise<TResult>, budget: number, status?: boolean): Promise<TResult>;
+//# sourceMappingURL=timeBudget.d.ts.map

package/dist/_pkg/telemetry-exporter/neutral/XyConsoleSpanExporter.d.ts

@@ -0,0 +1,40 @@
+import type { Logger } from '../../logger/neutral/index.ts';
+import type { ReadableSpan } from '@opentelemetry/sdk-trace-base';
+import { ConsoleSpanExporter } from '@opentelemetry/sdk-trace-base';
+type LogColor = (value: string) => string;
+/**
+ * Calculates the duration of a span in milliseconds from its high-resolution time tuple.
+ * @param span - The span to measure.
+ * @returns The span duration in milliseconds.
+ */
+export declare function spanDurationInMillis(span: ReadableSpan): number;
+/**
+ * A console span exporter that formats spans with color-coded durations using chalk.
+ * Spans are filtered by a configurable log level based on their duration.
+ */
+export declare class XyConsoleSpanExporter extends ConsoleSpanExporter {
+    /** Duration thresholds (in ms) that map to increasing log levels. */
+    static readonly durationToLogLevel: number[];
+    /** Chalk color functions corresponding to each log level. */
+    static readonly logLevelToChalkColor: LogColor[];
+    logger: Logger;
+    private _logLevel;
+    constructor(logLevel?: number, logger?: Logger);
+    /** The minimum log level required for a span to be exported. */
+    get logLevel(): number;
+    export(spans: ReadableSpan[]): void;
+    /**
+     * Returns the chalk color function for the given log level.
+     * @param level - The log level index.
+     * @returns A chalk color function.
+     */
+    logColor(level: number): LogColor;
+    /**
+     * Determines the log level of a span based on its duration.
+     * @param span - The span to evaluate.
+     * @returns The numeric log level (index into durationToLogLevel).
+     */
+    spanLevel(span: ReadableSpan): number;
+}
+export {};
+//# sourceMappingURL=XyConsoleSpanExporter.d.ts.map

package/dist/_pkg/telemetry-exporter/neutral/index.d.ts

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

package/dist/_pkg/telemetry-exporter/neutral/index.mjs

@@ -0,0 +1,88 @@
+// src/XyConsoleSpanExporter.ts
+import { ConsoleSpanExporter } from "@opentelemetry/sdk-trace-base";
+var color = (open, close = 39) => {
+  return (value) => `\x1B[${open}m${value}\x1B[${close}m`;
+};
+var logColors = {
+  green: color(32),
+  grey: color(90),
+  magenta: color(35),
+  red: color(31),
+  white: color(37),
+  yellow: color(33)
+};
+function spanDurationInMillis(span) {
+  return span.duration[0] * 1e3 + span.duration[1] / 1e6;
+}
+var XyConsoleSpanExporter = class _XyConsoleSpanExporter extends ConsoleSpanExporter {
+  /** Duration thresholds (in ms) that map to increasing log levels. */
+  static durationToLogLevel = [
+    0,
+    1,
+    10,
+    100,
+    1e3
+  ];
+  /** Chalk color functions corresponding to each log level. */
+  static logLevelToChalkColor = [
+    logColors.grey,
+    logColors.white,
+    logColors.green,
+    logColors.yellow,
+    logColors.red
+  ];
+  logger;
+  _logLevel;
+  constructor(logLevel = 0, logger = console) {
+    super();
+    this._logLevel = logLevel;
+    this.logger = logger;
+  }
+  /** The minimum log level required for a span to be exported. */
+  get logLevel() {
+    return this._logLevel;
+  }
+  export(spans) {
+    for (const span of spans) {
+      const spanLevel = this.spanLevel(span);
+      if (spanLevel < this.logLevel) {
+        continue;
+      }
+      const duration = spanDurationInMillis(span);
+      this.logger.log(logColors.grey([
+        `Span [${span.name}]`,
+        this.logColor(spanLevel)(`${duration}ms`),
+        `TraceId: ${span.spanContext().traceId}`
+      ].join(", ")));
+    }
+  }
+  /**
+   * Returns the chalk color function for the given log level.
+   * @param level - The log level index.
+   * @returns A chalk color function.
+   */
+  logColor(level) {
+    return _XyConsoleSpanExporter.logLevelToChalkColor[level] ?? logColors.magenta;
+  }
+  /**
+   * Determines the log level of a span based on its duration.
+   * @param span - The span to evaluate.
+   * @returns The numeric log level (index into durationToLogLevel).
+   */
+  spanLevel(span) {
+    let logLevel = 0;
+    const duration = spanDurationInMillis(span);
+    for (let x = _XyConsoleSpanExporter.durationToLogLevel.length - 1; x >= 0; x--) {
+      if (duration > _XyConsoleSpanExporter.durationToLogLevel[x]) {
+        logLevel = x;
+        break;
+      }
+    }
+    return logLevel;
+  }
+};
+export {
+  XyConsoleSpanExporter,
+  spanDurationInMillis
+};
+//# sourceMappingURL=index.mjs.map

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

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

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

@@ -0,0 +1,75 @@
+// src/setTimeoutEx.ts
+import { assertEx } from "../../assert/neutral/index.mjs";
+var TimerScheduler = class {
+  currentTimeout;
+  interval = -1;
+  timeouts = [];
+  /**
+   * Cancels a timeout previously created with setTimeoutEx.
+   * @param id - The timeout ID returned by setTimeoutEx.
+   */
+  clearTimeoutEx(id) {
+    this.timeouts = this.timeouts.filter((timeout) => timeout.id !== id);
+    this.update(this.timeouts);
+  }
+  /** Clears all scheduled timeouts and resets internal state. */
+  reset() {
+    this.interval = -1;
+    clearTimeout(this.currentTimeout);
+    this.currentTimeout = void 0;
+    this.timeouts = [];
+  }
+  /**
+   * Sets a timeout using an optimized internal timer that coalesces multiple timeouts into a single native timer.
+   * @param func - The function to call after the delay.
+   * @param delay - The delay in milliseconds (must be >= 0).
+   * @returns A unique string ID that can be used with clearTimeoutEx to cancel the timeout.
+   */
+  setTimeoutEx(func, delay) {
+    assertEx(delay >= 0, () => "delay must be >= 0");
+    const id = `${Date.now()}|${Math.random() * 9999999999}`;
+    this.timeouts.push({
+      delay,
+      func,
+      id
+    });
+    this.update();
+    return id;
+  }
+  timerFunc() {
+    const notFiring = this.timeouts.filter((timeout) => timeout.delay > this.interval);
+    const firing = this.timeouts.filter((timeout) => timeout.delay <= this.interval);
+    this.update(notFiring, this.interval);
+    for (const timeout of firing) {
+      timeout.func();
+    }
+  }
+  update(newTimeouts = this.timeouts, delayPassed = 0) {
+    if (newTimeouts.length === 0) {
+      this.reset();
+    } else {
+      const newInterval = Math.min(...newTimeouts.map((timeout) => timeout.delay));
+      if (newInterval === this.interval && this.currentTimeout !== void 0) {
+        return;
+      }
+      clearTimeout(this.currentTimeout);
+      this.timeouts = newTimeouts.map((timeout) => ({
+        delay: timeout.delay - delayPassed,
+        func: timeout.func,
+        id: timeout.id
+      }));
+      this.interval = newInterval;
+      this.currentTimeout = setTimeout(() => this.timerFunc(), this.interval);
+    }
+  }
+};
+var defaultTimerScheduler = new TimerScheduler();
+var setTimeoutEx = (func, delay) => defaultTimerScheduler.setTimeoutEx(func, delay);
+var clearTimeoutEx = (id) => defaultTimerScheduler.clearTimeoutEx(id);
+export {
+  TimerScheduler,
+  clearTimeoutEx,
+  defaultTimerScheduler,
+  setTimeoutEx
+};
+//# sourceMappingURL=index.mjs.map

package/dist/_pkg/timer/neutral/setTimeoutEx.d.ts

@@ -0,0 +1,37 @@
+/** Coalesces multiple logical timeouts into a single native timer. */
+export declare class TimerScheduler {
+    private currentTimeout;
+    private interval;
+    private timeouts;
+    /**
+     * Cancels a timeout previously created with setTimeoutEx.
+     * @param id - The timeout ID returned by setTimeoutEx.
+     */
+    clearTimeoutEx(id: string): void;
+    /** Clears all scheduled timeouts and resets internal state. */
+    reset(): void;
+    /**
+     * Sets a timeout using an optimized internal timer that coalesces multiple timeouts into a single native timer.
+     * @param func - The function to call after the delay.
+     * @param delay - The delay in milliseconds (must be >= 0).
+     * @returns A unique string ID that can be used with clearTimeoutEx to cancel the timeout.
+     */
+    setTimeoutEx(func: () => void, delay: number): string;
+    private timerFunc;
+    private update;
+}
+/** Default scheduler used by the module-level timeout helpers. */
+export declare const defaultTimerScheduler: TimerScheduler;
+/**
+ * Sets a timeout using an optimized internal timer that coalesces multiple timeouts into a single native timer.
+ * @param func - The function to call after the delay.
+ * @param delay - The delay in milliseconds (must be >= 0).
+ * @returns A unique string ID that can be used with clearTimeoutEx to cancel the timeout.
+ */
+export declare const setTimeoutEx: (func: () => void, delay: number) => string;
+/**
+ * Cancels a timeout previously created with setTimeoutEx.
+ * @param id - The timeout ID returned by setTimeoutEx.
+ */
+export declare const clearTimeoutEx: (id: string) => void;
+//# sourceMappingURL=setTimeoutEx.d.ts.map

package/dist/_pkg/typeof/neutral/Brand.d.ts

@@ -0,0 +1,5 @@
+/** Creates a branded type by intersecting base type T with brand type B, enabling nominal typing in TypeScript. */
+export type Brand<T, B> = T & {
+    [K in keyof B]: B[K];
+};
+//# sourceMappingURL=Brand.d.ts.map

package/dist/_pkg/typeof/neutral/IdentityFunction.d.ts

@@ -0,0 +1,3 @@
+/** A type guard function that narrows an unknown value to type T. */
+export type IdentityFunction<T> = (value: unknown) => value is T;
+//# sourceMappingURL=IdentityFunction.d.ts.map

package/dist/_pkg/typeof/neutral/ObjectTypeShape.d.ts

@@ -0,0 +1,5 @@
+/** Union of string literals representing the possible types of an object field. */
+export type FieldType = 'string' | 'number' | 'object' | 'symbol' | 'undefined' | 'null' | 'array' | 'function';
+/** Describes the expected shape of an object by mapping each key to its expected field type. */
+export type ObjectTypeShape = Record<string | number | symbol, FieldType>;
+//# sourceMappingURL=ObjectTypeShape.d.ts.map

package/dist/_pkg/typeof/neutral/TypeOfTypes.d.ts

@@ -0,0 +1,3 @@
+/** Union of string literals representing the possible results of the extended `typeOf` function. */
+export type TypeOfTypes = 'string' | 'number' | 'object' | 'array' | 'buffer' | 'null' | 'undefined' | 'bigint' | 'boolean' | 'function' | 'symbol';
+//# sourceMappingURL=TypeOfTypes.d.ts.map

package/dist/_pkg/typeof/neutral/Typed.d.ts

@@ -0,0 +1,41 @@
+/** A value that can appear in a typed object tree (primitives, objects, arrays, functions, and symbols). */
+export type TypedValue = bigint | string | number | boolean | null | TypedObject | TypedArray | Function | symbol | undefined;
+/** A valid key for a typed object. Defaults to string | number | symbol unless narrowed by T. */
+export type TypedKey<T extends string | void = void> = T extends string ? T : string | number | symbol;
+/** An object whose keys are TypedKey and whose values are TypedValue. */
+export type TypedObject = object | {
+    [key: TypedKey]: TypedValue;
+};
+/** An array of TypedValue elements. */
+export type TypedArray = TypedValue[];
+/**
+ * Type guard that checks whether a value is a valid TypedKey (string, bigint, number, or symbol).
+ * @param value - The value to check.
+ * @returns True if the value is a valid TypedKey.
+ */
+export declare const isTypedKey: (value: unknown) => value is TypedKey;
+/**
+ * Type guard that checks whether a value is a valid TypedValue.
+ * @param value - The value to check.
+ * @returns True if the value is a string, number, boolean, null, TypedObject, or TypedArray.
+ */
+export declare const isTypedValue: (value: unknown) => value is TypedValue;
+/**
+ * Type guard that checks whether a value is a TypedArray (an array where every element is a TypedValue).
+ * @param value - The value to check.
+ * @returns True if the value is an array of TypedValue elements.
+ */
+export declare const isTypedArray: (value: unknown) => value is TypedArray;
+/**
+ * Type guard that checks whether a key-value pair has a valid TypedKey and TypedValue.
+ * @param pair - A tuple of [key, value] to validate.
+ * @returns True if the key is a TypedKey and the value is a TypedValue.
+ */
+export declare const isValidTypedFieldPair: (pair: [key: unknown, value: unknown]) => pair is [key: TypedKey, value: TypedValue];
+/**
+ * Type guard that checks whether a value is a TypedObject (an object with TypedKey keys and TypedValue values).
+ * @param value - The value to check.
+ * @returns True if the value is a valid TypedObject.
+ */
+export declare const isTypedObject: (value: unknown) => value is TypedObject;
+//# sourceMappingURL=Typed.d.ts.map

package/dist/_pkg/typeof/neutral/ifDefined.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Invokes the callback only if the value is neither null nor undefined.
+ * @param value - The value to check.
+ * @param func - The callback to invoke with the value if it is defined.
+ * @returns The value if defined, or undefined otherwise.
+ */
+export declare const ifDefined: <T>(value: T, func: (value: T) => void) => T | undefined;
+//# sourceMappingURL=ifDefined.d.ts.map

package/dist/_pkg/typeof/neutral/ifTypeOf.d.ts

@@ -0,0 +1,11 @@
+import type { TypeOfTypes } from './TypeOfTypes.ts';
+/**
+ * Invokes the callback if the value matches the specified type, with an optional additional predicate.
+ * @param typeName - The expected type name to match against.
+ * @param value - The value to check.
+ * @param trueFunc - The callback to invoke if the type matches.
+ * @param isFunc - Optional additional predicate that must also return true.
+ * @returns The result of trueFunc if the type matches (and isFunc passes), or undefined.
+ */
+export declare const ifTypeOf: <T, R>(typeName: TypeOfTypes, value: unknown, trueFunc: (value: T) => R, isFunc?: (value: T) => boolean) => R | undefined;
+//# sourceMappingURL=ifTypeOf.d.ts.map

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

@@ -0,0 +1,12 @@
+export * from './Brand.ts';
+export * from './IdentityFunction.ts';
+export * from './ifDefined.ts';
+export * from './ifTypeOf.ts';
+export * from './is.ts';
+export * from './isType.ts';
+export * from './ObjectTypeShape.ts';
+export * from './Typed.ts';
+export * from './typeOf.ts';
+export * from './TypeOfTypes.ts';
+export * from './validateType.ts';
+//# sourceMappingURL=index.d.ts.map