@xh/hoist 83.1.0 → 84.0.1

package/svc/TraceService.ts

@@ -4,10 +4,10 @@
  *
  * Copyright © 2026 Extremely Heavy Industries Inc.
  */
-import {HoistService, XH} from '@xh/hoist/core';
+import {HoistService, PlainObject, XH} from '@xh/hoist/core';
 import {SECONDS} from '@xh/hoist/utils/datetime';
 import {debounced, parseNameSource} from '@xh/hoist/utils/js';
-import {isEmpty, isString} from 'lodash';
+import {every, isEmpty, isString} from 'lodash';
 import {Span, SpanConfig} from '@xh/hoist/utils/telemetry';
 
 /**
@@ -18,7 +18,7 @@ import {Span, SpanConfig} from '@xh/hoist/utils/telemetry';
  * end-to-end traces from user interaction through server processing and back.
  *
  * Controlled by the `xhTraceConfig` soft config. When disabled (the default), all
- * span-creation methods are no-ops — the wrapped function still executes normally.
+ * span-creation methods are no-ops - the wrapped function still executes normally.
  *
  * Completed spans are batched and exported to the Hoist server endpoint `xh/submitSpans`,
  * which relays them to the configured collector.
@@ -111,7 +111,10 @@ export class TraceService extends HoistService {
      * Create a new span, or return null if tracing is disabled.
      * Inherits the parent's `source` tag if not specified.
      *
-     * Note: sampling is handled server-side when spans are relayed to the collector.
+     * Sampling rules from `xhTraceConfig.sampleRules` are evaluated against the span's tags
+     * at creation time (head-based). Child spans inherit their parent's sampling decision.
+     * Unsampled spans may still be exported if they end in error and `alwaysSampleErrors` is
+     * enabled — see {@link exportSpan}.
      *
      * @param config - span name string, or a SpanConfig with name and optional tags.
      */
@@ -122,14 +125,17 @@ export class TraceService extends HoistService {
 
         // Apply default tags.
         ret.tags = {
-            clientApp: XH.clientAppCode,
-            loadId: XH.loadId,
-            tabId: XH.tabId,
-            source: ret.parent?.tags?.source ?? 'app',
+            'xh.clientApp': XH.clientAppCode,
+            'xh.loadId': XH.loadId,
+            'xh.tabId': XH.tabId,
+            'xh.source': ret.parent?.tags?.['xh.source'] ?? 'app',
             ...(ret.caller ? {'code.namespace': parseNameSource(ret.caller)} : {}),
             ...ret.tags
         };
 
+        // Sampling: children inherit parent decision; root spans evaluate rules.
+        ret.sampled = ret.parent ? ret.parent.sampled : this.shouldSample(ret.tags);
+
         return new Span(ret);
     }
 
@@ -138,8 +144,15 @@ export class TraceService extends HoistService {
     //------------------
     /** Submit a completed span for export. */
     exportSpan(span: Span) {
-        this._pending.push(span);
-        this.pushPendingBuffered();
+        if (span.sampled || (this.conf.alwaysSampleErrors && span.status === 'error')) {
+            this._pending.push(span);
+
+            // Queue the span, but if this is the submitSpans export itself, don't schedule
+            // another flush or we'll loop forever.
+            if (!span.tags['url.path']?.endsWith('xh/submitSpans')) {
+                this.pushPendingBuffered();
+            }
+        }
     }
 
     /**
@@ -169,10 +182,55 @@ export class TraceService extends HoistService {
     //------------------
     @debounced(5 * SECONDS)
     private pushPendingBuffered() {
-        this.pushPendingAsync();
+        void this.pushPendingAsync();
+    }
+
+    /** Evaluate sampling rules against a span's tags. */
+    private shouldSample(tags: PlainObject): boolean {
+        try {
+            return Math.random() < this.getSampleRate(tags);
+        } catch (e) {
+            this.logError('Failed to compute sample rate', e);
+            return false;
+        }
+    }
+
+    private getSampleRate(tags: PlainObject): number {
+        const {conf} = this;
+        for (const rule of conf.sampleRules ?? []) {
+            if (every(rule.match, (v, k) => this.matchesValue(tags[k], v))) {
+                return rule.sampleRate;
+            }
+        }
+        return conf.sampleRate;
+    }
+
+    /** For strings, simple glob matching: `*` = any, `foo*` = prefix, `*foo` = suffix, `*foo*` = contains. */
+    private matchesValue(actual: any, pattern: any): boolean {
+        if (!isString(actual) || !isString(pattern)) {
+            return actual === pattern;
+        }
+
+        if (pattern === '*') return true;
+        const startsWithWild = pattern.startsWith('*'),
+            endsWithWild = pattern.endsWith('*'),
+            core = pattern.replace(/^\*|\*$/g, '');
+
+        if (startsWithWild && endsWithWild) return actual.includes(core);
+        if (startsWithWild) return actual.endsWith(core);
+        if (endsWithWild) return actual.startsWith(core);
+        return actual === pattern;
     }
 }
 
 interface TraceConfig {
     enabled: boolean;
+    sampleRules?: SamplingRule[];
+    sampleRate?: number;
+    alwaysSampleErrors?: boolean;
+}
+
+interface SamplingRule {
+    match: Record<string, string>;
+    sampleRate: number;
 }

package/utils/README.md

@@ -472,7 +472,6 @@ for the full list of supported props and conversion details.
 
 | Function | Description |
 |----------|-------------|
-| `getClassName(baseName, props, ...extras)` | Combine a base CSS class with `props.className` and additional class names |
 | `createObservableRef()` | Create a ref that works as both a React ref object and callback ref, with a MobX-observable `current` property |
 | `elementFromContent(content, addProps?)` | Create a React element from a `Content` value (element, HoistComponent, or render function) |
 

package/utils/async/Timer.ts

@@ -172,6 +172,12 @@ export class Timer {
     }
 }
 
+/**
+ * Configuration for a {@link Timer} - a managed interval that runs a function repeatedly
+ * with configurable delay, timeout, and app-config-driven intervals.
+ *
+ * @see Timer
+ */
 export interface TimerSpec {
     /**
      * Function to run.

package/utils/js/LangUtils.ts

@@ -282,7 +282,7 @@ export function mergeDeep(target: PlainObject, ...sources: PlainObject[]): Plain
 }
 
 /**
- * A string, or an object from which a name can be derived — via `displayName` (e.g. React
+ * A string, or an object from which a name can be derived - via `displayName` (e.g. React
  * components) or `constructor.name` (e.g. class instances). Used for logging and tracing.
  */
 export type NameSource = string | {displayName: string} | {constructor: {name: string}};

package/utils/js/TestUtils.ts

@@ -9,7 +9,7 @@ import {isString} from 'lodash';
 
 /**
  * HTML attribute name used to tag elements with stable test identifiers. Use as a computed
- * property key on element specs — e.g. `{[TEST_ID]: 'my-grid'}` — to emit a `data-testid`
+ * property key on element specs - e.g. `{[TEST_ID]: 'my-grid'}` - to emit a `data-testid`
  * attribute that automated test drivers can locate reliably.
  */
 export const TEST_ID = 'data-testid';

package/utils/react/index.ts

@@ -4,7 +4,6 @@
  *
  * Copyright © 2026 Extremely Heavy Industries Inc.
  */
-export * from './ClassName';
 export * from './ReactUtils';
 export * from './LayoutPropUtils';
 export * from './ObservableRef';

package/utils/telemetry/Span.ts

@@ -29,7 +29,7 @@ export class Span {
     /** Epoch ms (Date.now()-based). */
     startTime: number;
 
-    /** Epoch ms — set when span ends. */
+    /** Epoch ms - set when span ends. */
     endTime: number;
 
     /** Duration in ms (endTime - startTime). */
@@ -42,6 +42,9 @@ export class Span {
     tags: PlainObject;
     events: SpanEvent[] = [];
 
+    /** Whether this span was selected by client-side sampling rules. */
+    sampled: boolean;
+
     constructor(config: SpanConfig) {
         const parent = config.parent;
         this.traceId = parent?.traceId ?? genTraceId();
@@ -51,6 +54,7 @@ export class Span {
         this.kind = config.kind ?? 'internal';
         this.startTime = config.startTime ?? Date.now();
         this.tags = {...config.tags};
+        this.sampled = config.sampled ?? true;
     }
 
     /** End this span, recording status and computing duration. */
@@ -83,11 +87,19 @@ export class Span {
             duration: this.duration,
             status: this.status,
             tags: this.tags,
-            events: this.events
+            events: this.events,
+            sampled: this.sampled
         };
     }
 }
 
+/**
+ * Configuration for a {@link Span} - a lightweight trace span for distributed tracing.
+ * Create via {@link TraceService} rather than directly.
+ *
+ * @see Span
+ * @see TraceService
+ */
 export interface SpanConfig {
     name: string;
     kind?: SpanKind;
@@ -95,6 +107,7 @@ export interface SpanConfig {
     parent?: Span;
     startTime?: number;
     caller?: NameSource;
+    sampled?: boolean;
 }
 
 export interface SpanEvent {
@@ -110,8 +123,12 @@ export type SpanStatus = 'ok' | 'error' | 'unset';
  * Format a W3C traceparent header value.
  * @see https://www.w3.org/TR/trace-context/#traceparent-header
  */
-export function formatTraceparent(traceId: string, spanId: string): string {
-    return `00-${traceId}-${spanId}-01`;
+export function formatTraceparent(
+    traceId: string,
+    spanId: string,
+    sampled: boolean = true
+): string {
+    return `00-${traceId}-${spanId}-${sampled ? '01' : '00'}`;
 }
 
 /** Generate a 32-hex-char (128-bit) trace ID. */

package/build/types/utils/react/ClassName.d.ts

@@ -1,14 +0,0 @@
-/**
- * Generate a string with one or more CSS classes to apply to a component, typically concatenating a
- * standardized base className with any instance-specific getClassName(s) provided via props and any
- * optional / conditional class names determined at render-time.
- *
- * Components should call this to produce a combined class list and apply it to their outermost
- * (or otherwise most appropriate) rendered component.
- *
- * @param baseName - base class name for the component.
- * @param props - component props.
- * @param extraNames - optional, additional class names to append.
- * @returns concatenated, space-delimited class name appropriate for html className attribute.
- */
-export declare function getClassName(baseName: string, props: any, ...extraNames: string[]): string;

package/utils/react/ClassName.ts

@@ -1,24 +0,0 @@
-/*
- * This file belongs to Hoist, an application development toolkit
- * developed by Extremely Heavy Industries (www.xh.io | info@xh.io)
- *
- * Copyright © 2026 Extremely Heavy Industries Inc.
- */
-import classNames from 'classnames';
-
-/**
- * Generate a string with one or more CSS classes to apply to a component, typically concatenating a
- * standardized base className with any instance-specific getClassName(s) provided via props and any
- * optional / conditional class names determined at render-time.
- *
- * Components should call this to produce a combined class list and apply it to their outermost
- * (or otherwise most appropriate) rendered component.
- *
- * @param baseName - base class name for the component.
- * @param props - component props.
- * @param extraNames - optional, additional class names to append.
- * @returns concatenated, space-delimited class name appropriate for html className attribute.
- */
-export function getClassName(baseName: string, props: any, ...extraNames: string[]): string {
-    return classNames(baseName, props.className, ...extraNames);
-}