@glasstrace/sdk 1.16.0 → 1.17.0

package/dist/index.d.cts

@@ -90,6 +90,20 @@ interface RecordSideEffectInput {
      * prefix), so a categorical and a scalar facet can share a name.
      */
     scalars?: Record<string, unknown>;
+    /**
+     * Optional producer-asserted boolean relations (invariants) emitted on
+     * the categorical field channel. Keys must be camelCase ending in
+     * `Holds` (e.g. `timezonePreservedHolds`); values are real `boolean`s,
+     * coerced to `"true"`/`"false"` on the wire. A non-`Holds` key, a
+     * non-boolean value, or a key already attached by `fields` (a
+     * same-channel collision — `fields` wins) is dropped with the matching
+     * omission counter. Relations count against the same product-side
+     * per-operation field budget as `fields` (enforced at projection).
+     *
+     * Use {@link invariant} / {@link isNullInvariant} to compute the
+     * boolean from a comparison.
+     */
+    relations?: Record<string, boolean>;
 }
 /**
  * Record allowlisted side-effect evidence on the current active OTel
@@ -143,4 +157,63 @@ interface RecordSideEffectInput {
  */
 declare function recordSideEffect(input: RecordSideEffectInput): void;
 
-export { type RecordSideEffectInput, SideEffectOperationKind, SideEffectOperationPhase, SideEffectOperationStatus, SideEffectSemanticFieldKey, recordSideEffect };
+/**
+ * Producer-sugar for computing boolean relations to emit as `*Holds`
+ * side-effect evidence.
+ *
+ * These helpers turn a comparison into the boolean a producer passes to
+ * `recordSideEffect({ relations: { …Holds: invariant(a, "eq", b) } })`.
+ * They are pure (no I/O, no Node built-ins) and edge-safe, so they live
+ * on the root barrel. The operator set is intentionally minimal and
+ * fixed — six binary comparisons plus a separate unary null check — and
+ * is not a general expression DSL.
+ */
+/**
+ * The six supported binary comparison operators. `isNull` is **not** an
+ * operator here — use {@link isNullInvariant} for the unary case.
+ */
+type InvariantOp = "eq" | "neq" | "lt" | "lte" | "gt" | "gte";
+/**
+ * Evaluate a binary comparison invariant and return the boolean result.
+ *
+ * Both operands are constrained to the same primitive type. `eq`/`neq`
+ * use strict equality; the ordering operators (`lt`/`lte`/`gt`/`gte`)
+ * use the language relational operators (numeric for numbers/bigints,
+ * lexical for strings). Intended for producing a `*Holds` relation, e.g.
+ * `invariant(emittedDurationMinutes, "eq", declaredDurationMinutes)`.
+ *
+ * Operands should be comparable primitives. `NaN` follows IEEE-754
+ * (unequal to everything; all orderings `false`), so screen `NaN` before
+ * asserting a relation. Passing a non-primitive (e.g. a `Symbol`, or an
+ * object with a throwing `valueOf`) to an ordering operator throws per
+ * JS semantics — the type signature prevents this for typed callers.
+ *
+ * @param left - The left operand.
+ * @param op - One of the six {@link InvariantOp} comparisons.
+ * @param right - The right operand (same primitive type as `left`).
+ * @returns The boolean result of `left <op> right`.
+ *
+ * @example
+ * recordSideEffect({
+ *   kind: "calendar_link",
+ *   operation: "invite.create",
+ *   relations: {
+ *     durationMatchesHolds: invariant(emittedMinutes, "eq", declaredMinutes),
+ *   },
+ * });
+ */
+declare function invariant<T extends number | string | bigint | boolean>(left: T, op: InvariantOp, right: T): boolean;
+/**
+ * Unary null/undefined invariant — `true` when `value` is `null` or
+ * `undefined`. Kept separate from {@link invariant} because nullishness
+ * is a unary predicate, not a binary comparison (there is no `isNull`
+ * operator). Use for a `*Holds` relation asserting a value's absence,
+ * e.g. `relations: { recipientMissingHolds: isNullInvariant(recipient) }`.
+ *
+ * @param value - The value to test.
+ * @returns `true` when `value` is `null` or `undefined`, else `false`
+ *   (falsy-but-present values like `0`, `""`, `false`, `NaN` are `false`).
+ */
+declare function isNullInvariant(value: unknown): boolean;
+
+export { type InvariantOp, type RecordSideEffectInput, SideEffectOperationKind, SideEffectOperationPhase, SideEffectOperationStatus, SideEffectSemanticFieldKey, invariant, isNullInvariant, recordSideEffect };

package/dist/index.d.ts

@@ -90,6 +90,20 @@ interface RecordSideEffectInput {
      * prefix), so a categorical and a scalar facet can share a name.
      */
     scalars?: Record<string, unknown>;
+    /**
+     * Optional producer-asserted boolean relations (invariants) emitted on
+     * the categorical field channel. Keys must be camelCase ending in
+     * `Holds` (e.g. `timezonePreservedHolds`); values are real `boolean`s,
+     * coerced to `"true"`/`"false"` on the wire. A non-`Holds` key, a
+     * non-boolean value, or a key already attached by `fields` (a
+     * same-channel collision — `fields` wins) is dropped with the matching
+     * omission counter. Relations count against the same product-side
+     * per-operation field budget as `fields` (enforced at projection).
+     *
+     * Use {@link invariant} / {@link isNullInvariant} to compute the
+     * boolean from a comparison.
+     */
+    relations?: Record<string, boolean>;
 }
 /**
  * Record allowlisted side-effect evidence on the current active OTel
@@ -143,4 +157,63 @@ interface RecordSideEffectInput {
  */
 declare function recordSideEffect(input: RecordSideEffectInput): void;
 
-export { type RecordSideEffectInput, SideEffectOperationKind, SideEffectOperationPhase, SideEffectOperationStatus, SideEffectSemanticFieldKey, recordSideEffect };
+/**
+ * Producer-sugar for computing boolean relations to emit as `*Holds`
+ * side-effect evidence.
+ *
+ * These helpers turn a comparison into the boolean a producer passes to
+ * `recordSideEffect({ relations: { …Holds: invariant(a, "eq", b) } })`.
+ * They are pure (no I/O, no Node built-ins) and edge-safe, so they live
+ * on the root barrel. The operator set is intentionally minimal and
+ * fixed — six binary comparisons plus a separate unary null check — and
+ * is not a general expression DSL.
+ */
+/**
+ * The six supported binary comparison operators. `isNull` is **not** an
+ * operator here — use {@link isNullInvariant} for the unary case.
+ */
+type InvariantOp = "eq" | "neq" | "lt" | "lte" | "gt" | "gte";
+/**
+ * Evaluate a binary comparison invariant and return the boolean result.
+ *
+ * Both operands are constrained to the same primitive type. `eq`/`neq`
+ * use strict equality; the ordering operators (`lt`/`lte`/`gt`/`gte`)
+ * use the language relational operators (numeric for numbers/bigints,
+ * lexical for strings). Intended for producing a `*Holds` relation, e.g.
+ * `invariant(emittedDurationMinutes, "eq", declaredDurationMinutes)`.
+ *
+ * Operands should be comparable primitives. `NaN` follows IEEE-754
+ * (unequal to everything; all orderings `false`), so screen `NaN` before
+ * asserting a relation. Passing a non-primitive (e.g. a `Symbol`, or an
+ * object with a throwing `valueOf`) to an ordering operator throws per
+ * JS semantics — the type signature prevents this for typed callers.
+ *
+ * @param left - The left operand.
+ * @param op - One of the six {@link InvariantOp} comparisons.
+ * @param right - The right operand (same primitive type as `left`).
+ * @returns The boolean result of `left <op> right`.
+ *
+ * @example
+ * recordSideEffect({
+ *   kind: "calendar_link",
+ *   operation: "invite.create",
+ *   relations: {
+ *     durationMatchesHolds: invariant(emittedMinutes, "eq", declaredMinutes),
+ *   },
+ * });
+ */
+declare function invariant<T extends number | string | bigint | boolean>(left: T, op: InvariantOp, right: T): boolean;
+/**
+ * Unary null/undefined invariant — `true` when `value` is `null` or
+ * `undefined`. Kept separate from {@link invariant} because nullishness
+ * is a unary predicate, not a binary comparison (there is no `isNull`
+ * operator). Use for a `*Holds` relation asserting a value's absence,
+ * e.g. `relations: { recipientMissingHolds: isNullInvariant(recipient) }`.
+ *
+ * @param value - The value to test.
+ * @returns `true` when `value` is `null` or `undefined`, else `false`
+ *   (falsy-but-present values like `0`, `""`, `false`, `NaN` are `false`).
+ */
+declare function isNullInvariant(value: unknown): boolean;
+
+export { type InvariantOp, type RecordSideEffectInput, SideEffectOperationKind, SideEffectOperationPhase, SideEffectOperationStatus, SideEffectSemanticFieldKey, invariant, isNullInvariant, recordSideEffect };

package/dist/index.js

@@ -10,7 +10,7 @@ import {
   recordSideEffect,
   registerGlasstrace,
   withGlasstraceConfig
-} from "./chunk-EWW3TZ52.js";
+} from "./chunk-F2IPBTDJ.js";
 import {
   getStatus,
   isReady,
@@ -20,7 +20,7 @@ import {
   GlasstraceSpanProcessor,
   SdkError,
   captureCorrelationId
-} from "./chunk-KM4UNN3Q.js";
+} from "./chunk-EVX6D2TX.js";
 import "./chunk-CL3OVHPO.js";
 import "./chunk-DQ25VOKK.js";
 import "./chunk-YG3X7TUI.js";
@@ -31,7 +31,7 @@ import {
   performInit,
   saveCachedConfig,
   sendInitRequest
-} from "./chunk-T7B752NF.js";
+} from "./chunk-VEQX2YSQ.js";
 import {
   isAnonymousMode,
   isProductionDisabled,
@@ -41,13 +41,36 @@ import {
 import {
   getOrCreateAnonKey,
   readAnonKey
-} from "./chunk-774XIOZG.js";
+} from "./chunk-UOAG72NR.js";
 import {
   deriveSessionId,
   isSideEffectSemanticFieldKey
-} from "./chunk-GBVMPMVV.js";
+} from "./chunk-MKT54VEH.js";
 import "./chunk-YIEXKQYP.js";
 import "./chunk-NSBPE2FW.js";
+
+// src/side-effect/invariant.ts
+function invariant(left, op, right) {
+  switch (op) {
+    case "eq":
+      return left === right;
+    case "neq":
+      return left !== right;
+    case "lt":
+      return left < right;
+    case "lte":
+      return left <= right;
+    case "gt":
+      return left > right;
+    case "gte":
+      return left >= right;
+  }
+  op;
+  return false;
+}
+function isNullInvariant(value) {
+  return value === null || value === void 0;
+}
 export {
   GlasstraceExporter,
   GlasstraceSpanProcessor,
@@ -65,7 +88,9 @@ export {
   getOrCreateAnonKey,
   getOrigin,
   getStatus,
+  invariant,
   isAnonymousMode,
+  isNullInvariant,
   isProductionDisabled,
   isReady,
   isSideEffectSemanticFieldKey,

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}
+{"version":3,"sources":["../src/side-effect/invariant.ts"],"sourcesContent":["/**\n * Producer-sugar for computing boolean relations to emit as `*Holds`\n * side-effect evidence.\n *\n * These helpers turn a comparison into the boolean a producer passes to\n * `recordSideEffect({ relations: { …Holds: invariant(a, \"eq\", b) } })`.\n * They are pure (no I/O, no Node built-ins) and edge-safe, so they live\n * on the root barrel. The operator set is intentionally minimal and\n * fixed — six binary comparisons plus a separate unary null check — and\n * is not a general expression DSL.\n */\n\n/**\n * The six supported binary comparison operators. `isNull` is **not** an\n * operator here — use {@link isNullInvariant} for the unary case.\n */\nexport type InvariantOp = \"eq\" | \"neq\" | \"lt\" | \"lte\" | \"gt\" | \"gte\";\n\n/**\n * Evaluate a binary comparison invariant and return the boolean result.\n *\n * Both operands are constrained to the same primitive type. `eq`/`neq`\n * use strict equality; the ordering operators (`lt`/`lte`/`gt`/`gte`)\n * use the language relational operators (numeric for numbers/bigints,\n * lexical for strings). Intended for producing a `*Holds` relation, e.g.\n * `invariant(emittedDurationMinutes, \"eq\", declaredDurationMinutes)`.\n *\n * Operands should be comparable primitives. `NaN` follows IEEE-754\n * (unequal to everything; all orderings `false`), so screen `NaN` before\n * asserting a relation. Passing a non-primitive (e.g. a `Symbol`, or an\n * object with a throwing `valueOf`) to an ordering operator throws per\n * JS semantics — the type signature prevents this for typed callers.\n *\n * @param left - The left operand.\n * @param op - One of the six {@link InvariantOp} comparisons.\n * @param right - The right operand (same primitive type as `left`).\n * @returns The boolean result of `left <op> right`.\n *\n * @example\n * recordSideEffect({\n *   kind: \"calendar_link\",\n *   operation: \"invite.create\",\n *   relations: {\n *     durationMatchesHolds: invariant(emittedMinutes, \"eq\", declaredMinutes),\n *   },\n * });\n */\nexport function invariant<T extends number | string | bigint | boolean>(\n  left: T,\n  op: InvariantOp,\n  right: T,\n): boolean {\n  switch (op) {\n    case \"eq\":\n      return left === right;\n    case \"neq\":\n      return left !== right;\n    case \"lt\":\n      return left < right;\n    case \"lte\":\n      return left <= right;\n    case \"gt\":\n      return left > right;\n    case \"gte\":\n      return left >= right;\n  }\n  // For well-typed callers `op` is `never` here, so this `satisfies`\n  // enforces switch exhaustiveness at compile time (adding an\n  // `InvariantOp` member without a case is a type error). The `return`\n  // is the runtime fallback for an untyped (JS) caller passing an\n  // out-of-domain op — it yields a `boolean`, never `undefined`.\n  op satisfies never;\n  return false;\n}\n\n/**\n * Unary null/undefined invariant — `true` when `value` is `null` or\n * `undefined`. Kept separate from {@link invariant} because nullishness\n * is a unary predicate, not a binary comparison (there is no `isNull`\n * operator). Use for a `*Holds` relation asserting a value's absence,\n * e.g. `relations: { recipientMissingHolds: isNullInvariant(recipient) }`.\n *\n * @param value - The value to test.\n * @returns `true` when `value` is `null` or `undefined`, else `false`\n *   (falsy-but-present values like `0`, `\"\"`, `false`, `NaN` are `false`).\n */\nexport function isNullInvariant(value: unknown): boolean {\n  return value === null || value === undefined;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+CO,SAAS,UACd,MACA,IACA,OACS;AACT,UAAQ,IAAI;AAAA,IACV,KAAK;AACH,aAAO,SAAS;AAAA,IAClB,KAAK;AACH,aAAO,SAAS;AAAA,IAClB,KAAK;AACH,aAAO,OAAO;AAAA,IAChB,KAAK;AACH,aAAO,QAAQ;AAAA,IACjB,KAAK;AACH,aAAO,OAAO;AAAA,IAChB,KAAK;AACH,aAAO,QAAQ;AAAA,EACnB;AAMA;AACA,SAAO;AACT;AAaO,SAAS,gBAAgB,OAAyB;AACvD,SAAO,UAAU,QAAQ,UAAU;AACrC;","names":[]}