@stripe/extensibility-sdk 0.24.1 → 0.25.0

package/dist/stdlib/index.js

@@ -1,116 +1,5 @@
 // src/stdlib/scalars.ts
 import "@formspec/core";
-function roundToInteger(value, direction) {
-  switch (direction) {
-    case "ceil":
-      return Math.ceil(value);
-    case "floor":
-      return Math.floor(value);
-    case "round-down":
-      return Math.trunc(value);
-    case "round-up":
-      return value >= 0 ? Math.ceil(value) : Math.floor(value);
-    case "half-up":
-      return value >= 0 ? Math.floor(value + 0.5) : Math.ceil(value - 0.5);
-    default: {
-      const _exhaustive = direction;
-      throw new Error(`Unknown rounding direction: ${String(_exhaustive)}`);
-    }
-  }
-}
-var Integer = {
-  /**
-   * Type guard that narrows a `number` to {@link (Integer:type)}.
-   *
-   * @example
-   * ```ts
-   * const n: number = getCount();
-   * if (Integer.is(n)) {
-   *   // n is Integer here
-   *   config.retryCount = n;
-   * }
-   * ```
-   * @public
-   */
-  is: (value) => Number.isInteger(value),
-  /**
-   * Coerces a number to an {@link (Integer:type)} by rounding.
-   * Throws if the value is not finite.
-   *
-   * @example
-   * ```ts
-   * const price = 9.99;
-   * const rounded = Integer.from(price, 'floor'); // 9
-   * const ceiled = Integer.from(price, 'ceil');   // 10
-   * ```
-   * @public
-   */
-  from: (value, rounding) => {
-    if (!Number.isFinite(value)) {
-      throw new Error(`Cannot round non-finite value ${String(value)} to an integer`);
-    }
-    return roundToInteger(value, rounding);
-  }
-};
-var PositiveInteger = {
-  /**
-   * Type guard that narrows a `number` to {@link (PositiveInteger:type)}.
-   *
-   * @example
-   * ```ts
-   * const n: number = getRetryCount();
-   * if (PositiveInteger.is(n)) {
-   *   // n is PositiveInteger here
-   *   config.maxRetries = n;
-   * }
-   * ```
-   * @public
-   */
-  is: (value) => Number.isInteger(value) && value >= 0,
-  /**
-   * Coerces a number to a {@link (PositiveInteger:type)} by rounding.
-   * Throws if the value is not finite or the rounded result is negative.
-   *
-   * @example
-   * ```ts
-   * const ratio = 2.7;
-   * const count = PositiveInteger.from(ratio, 'floor'); // 2
-   * ```
-   * @public
-   */
-  from: (value, rounding) => {
-    if (!Number.isFinite(value)) {
-      throw new Error(`Cannot round non-finite value ${String(value)} to an integer`);
-    }
-    const rounded = roundToInteger(value, rounding) || 0;
-    if (rounded < 0) {
-      throw new Error(
-        `Value ${String(value)} rounds to ${String(rounded)}, which is negative`
-      );
-    }
-    return rounded;
-  }
-};
-var StreetAddress = {
-  create: (address) => {
-    return address;
-  }
-};
-var Timestamp = {
-  create: (value) => {
-    return value;
-  }
-};
-
-// src/stdlib/refs.ts
-var Ref = {
-  create: (step) => {
-    return {
-      type: step.object,
-      id: step.id
-    };
-  }
-};
 
 // src/stdlib/decimal.ts
 var PLAIN_NOTATION_DIGIT_LIMIT = 30;
@@ -127,6 +16,9 @@ var DecimalRoundingPresets = Object.freeze({
 var DEFAULT_DIV_PRECISION = 34;
 var IMPLICIT_DECIMAL_COERCION_ERROR = "Implicit Decimal coercion is not allowed; use .add(), .sub(), .mul(), .div(), .toString(), or .toNumber() explicitly.";
 var MAX_EXPONENT = Number.MAX_SAFE_INTEGER;
+function normalizeZero(value) {
+  return Object.is(value, -0) ? 0 : value;
+}
 var DECIMAL_BRAND = /* @__PURE__ */ Symbol.for(
   "stripe.apps-extensibility-sdk.Decimal"
 );
@@ -240,13 +132,13 @@ var DecimalImpl = class _DecimalImpl {
   /**
    * Return the sum of this value and `other`.
    *
-   * @param other - The addend.
+   * @param other - The addend. Accepts any {@link DecimalLike} value.
    * @returns A new {@link Decimal} equal to `this + other`.
    *
    * @public
    */
   add(other) {
-    const otherImpl = toImpl(other);
+    const otherImpl = coerceToImpl(other);
     if (this.#exponent === otherImpl.#exponent) {
       return toDecimal(
         new _DecimalImpl(this.#coefficient + otherImpl.#coefficient, this.#exponent)
@@ -273,13 +165,13 @@ var DecimalImpl = class _DecimalImpl {
   /**
    * Return the difference of this value and `other`.
    *
-   * @param other - The subtrahend.
+   * @param other - The subtrahend. Accepts any {@link DecimalLike} value.
    * @returns A new {@link Decimal} equal to `this - other`.
    *
    * @public
    */
   sub(other) {
-    const otherImpl = toImpl(other);
+    const otherImpl = coerceToImpl(other);
     if (this.#exponent === otherImpl.#exponent) {
       return toDecimal(
         new _DecimalImpl(this.#coefficient - otherImpl.#coefficient, this.#exponent)
@@ -306,13 +198,13 @@ var DecimalImpl = class _DecimalImpl {
   /**
    * Return the product of this value and `other`.
    *
-   * @param other - The multiplicand.
+   * @param other - The multiplicand. Accepts any {@link DecimalLike} value.
    * @returns A new {@link Decimal} equal to `this × other`.
    *
    * @public
    */
   mul(other) {
-    const otherImpl = toImpl(other);
+    const otherImpl = coerceToImpl(other);
     return toDecimal(
       new _DecimalImpl(
         this.#coefficient * otherImpl.#coefficient,
@@ -339,7 +231,7 @@ var DecimalImpl = class _DecimalImpl {
    * Decimal.from('5').div(Decimal.from('2'), 0, 'half-even'); // "2"
    * ```
    *
-   * @param other - The divisor. Must not be zero.
+   * @param other - The divisor. Must not be zero. Accepts any {@link DecimalLike} value.
    * @param precision - Maximum number of decimal digits in the result.
    * @param direction - How to round when the exact quotient cannot
    *   be represented at the requested precision.
@@ -354,7 +246,7 @@ var DecimalImpl = class _DecimalImpl {
     if (precision < 0 || !Number.isInteger(precision)) {
       throw new Error("precision must be a non-negative integer");
     }
-    const otherImpl = toImpl(other);
+    const otherImpl = coerceToImpl(other);
     if (otherImpl.#coefficient === 0n) {
       throw new Error("Division by zero");
     }
@@ -396,13 +288,13 @@ var DecimalImpl = class _DecimalImpl {
    * a.cmp(a); //  0
    * ```
    *
-   * @param other - The value to compare against.
+   * @param other - The value to compare against. Accepts any {@link DecimalLike} value.
    * @returns `-1` if `this < other`, `0` if equal, `1` if `this > other`.
    *
    * @public
    */
   cmp(other) {
-    const otherImpl = toImpl(other);
+    const otherImpl = coerceToImpl(other);
     if (this.#exponent === otherImpl.#exponent) {
       if (this.#coefficient < otherImpl.#coefficient) return -1;
       if (this.#coefficient > otherImpl.#coefficient) return 1;
@@ -425,7 +317,7 @@ var DecimalImpl = class _DecimalImpl {
   /**
    * Return `true` if this value is numerically equal to `other`.
    *
-   * @param other - The value to compare against.
+   * @param other - The value to compare against. Accepts any {@link DecimalLike} value.
    * @returns `true` if `this === other` in value, `false` otherwise.
    *
    * @public
@@ -436,7 +328,7 @@ var DecimalImpl = class _DecimalImpl {
   /**
    * Return `true` if this value is strictly less than `other`.
    *
-   * @param other - The value to compare against.
+   * @param other - The value to compare against. Accepts any {@link DecimalLike} value.
    * @returns `true` if `this < other`, `false` otherwise.
    *
    * @public
@@ -447,7 +339,7 @@ var DecimalImpl = class _DecimalImpl {
   /**
    * Return `true` if this value is less than or equal to `other`.
    *
-   * @param other - The value to compare against.
+   * @param other - The value to compare against. Accepts any {@link DecimalLike} value.
    * @returns `true` if `this ≤ other`, `false` otherwise.
    *
    * @public
@@ -458,7 +350,7 @@ var DecimalImpl = class _DecimalImpl {
   /**
    * Return `true` if this value is strictly greater than `other`.
    *
-   * @param other - The value to compare against.
+   * @param other - The value to compare against. Accepts any {@link DecimalLike} value.
    * @returns `true` if `this > other`, `false` otherwise.
    *
    * @public
@@ -469,7 +361,7 @@ var DecimalImpl = class _DecimalImpl {
   /**
    * Return `true` if this value is greater than or equal to `other`.
    *
-   * @param other - The value to compare against.
+   * @param other - The value to compare against. Accepts any {@link DecimalLike} value.
    * @returns `true` if `this ≥ other`, `false` otherwise.
    *
    * @public
@@ -768,6 +660,38 @@ var DecimalImpl = class _DecimalImpl {
       return formatFixed(scaled);
     }
   }
+  /**
+   * Convert this value to an {@link (Integer:type)} by rounding.
+   *
+   * @remarks
+   * The rounding direction is always required — no invisible defaults
+   * in financial code.
+   *
+   * @example
+   * ```ts
+   * Decimal.from('2.7').toInteger('floor');     // 2
+   * Decimal.from('2.5').toInteger('half-up');   // 3
+   * Decimal.from('2.5').toInteger('half-even'); // 2
+   * ```
+   *
+   * @param direction - How to round when the value is not a whole number.
+   * @returns A branded {@link (Integer:type)} value.
+   * @throws Error if the rounded value is too large to represent as
+   *   a JavaScript `number`.
+   *
+   * @public
+   */
+  toInteger(direction) {
+    const fixed = this.toFixed(0, direction);
+    const num = Number(fixed);
+    if (!Number.isFinite(num) || !Number.isSafeInteger(num)) {
+      throw new Error(
+        `Decimal value ${fixed} cannot be exactly represented as a JavaScript integer`
+      );
+    }
+    const normalized = normalizeZero(num);
+    return normalized;
+  }
   /**
    * Reject implicit arithmetic-style coercion while preserving explicit
    * stringification.
@@ -808,23 +732,59 @@ var DecimalImpl = class _DecimalImpl {
 function toImpl(d) {
   return d;
 }
+function coerceToImpl(value) {
+  if (isDecimal(value)) {
+    return toImpl(value);
+  }
+  return toImpl(Decimal.from(value));
+}
 function toDecimal(impl) {
   return impl;
 }
 function isDecimal(value) {
-  return typeof value === "object" && value !== null && DECIMAL_BRAND in value;
+  return typeof value === "object" && value !== null && DECIMAL_BRAND in value && // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- symbol key access requires cast
+  value[DECIMAL_BRAND] === true;
+}
+function assertIsDecimal(value) {
+  if (!isDecimal(value)) {
+    throw new Error(`Expected a Decimal, got ${typeof value}`);
+  }
 }
 var Decimal = {
   /**
-   * Create a `Decimal` from a string, number, or bigint.
+   * Type guard that narrows an unknown value to {@link (Decimal:type)}.
+   *
+   * @example
+   * ```ts
+   * if (Decimal.is(value)) {
+   *   value.add(1); // value is Decimal
+   * }
+   * ```
+   * @public
+   */
+  is: isDecimal,
+  /**
+   * Assertion guard that throws if the value is not a {@link (Decimal:type)}.
+   *
+   * @example
+   * ```ts
+   * Decimal.assert(value);
+   * value.add(1); // value is Decimal
+   * ```
+   * @public
+   */
+  assert: assertIsDecimal,
+  /**
+   * Create a `Decimal` from a string, number, bigint, Integer, or Decimal.
    *
    * @remarks
+   * - **Decimal**: returned as-is (immutable passthrough).
    * - **string**: Parsed as a decimal literal. Accepts an optional sign,
    *   integer digits, an optional fractional part, and an optional `e`/`E`
    *   exponent. Leading/trailing whitespace is trimmed.
-   * - **number**: Must be finite. Converted via `Number.prototype.toString()`
-   *   then parsed, so `Decimal.from(0.1)` produces `"0.1"` (not the
-   *   53-bit binary approximation).
+   * - **number** (including Integer): Must be finite. Converted via
+   *   `Number.prototype.toString()` then parsed, so `Decimal.from(0.1)`
+   *   produces `"0.1"` (not the 53-bit binary approximation).
    * - **bigint**: Treated as an integer with exponent 0.
    *
    * @example
@@ -833,16 +793,21 @@ var Decimal = {
    * Decimal.from(42);       // number
    * Decimal.from(100n);     // bigint
    * Decimal.from('1.5e3');  // scientific notation → 1500
+   * Decimal.from(d);        // Decimal passthrough
    * ```
    *
    * @param value - The value to convert.
-   * @returns A new frozen `Decimal` instance.
+   * @returns A new frozen `Decimal` instance (or the same instance if
+   *   already a Decimal).
    * @throws Error if `value` is a non-finite number, an empty
    *   string, or a string that does not match the decimal literal grammar.
    *
    * @public
    */
   from(value) {
+    if (isDecimal(value)) {
+      return value;
+    }
     if (typeof value === "bigint") {
       return toDecimal(new DecimalImpl(value, 0));
     }
@@ -891,6 +856,273 @@ var Decimal = {
   zero: toDecimal(new DecimalImpl(0n, 0))
 };
 
+// src/stdlib/scalars.ts
+function roundToInteger(value, direction) {
+  switch (direction) {
+    case "ceil":
+      return Math.ceil(value);
+    case "floor":
+      return Math.floor(value);
+    case "round-down":
+      return Math.trunc(value);
+    case "round-up":
+      return value >= 0 ? Math.ceil(value) : Math.floor(value);
+    case "half-up":
+      return value >= 0 ? Math.floor(value + 0.5) : Math.ceil(value - 0.5);
+    default: {
+      const _exhaustive = direction;
+      throw new Error(`Unknown rounding direction: ${String(_exhaustive)}`);
+    }
+  }
+}
+function normalizeZero2(value) {
+  return Object.is(value, -0) ? 0 : value;
+}
+function assertIsInteger(value) {
+  if (!(typeof value === "number" && Number.isInteger(value))) {
+    throw new Error(
+      `Expected an integer, got ${typeof value === "number" ? String(value) : typeof value}`
+    );
+  }
+}
+function assertIsPositiveInteger(value) {
+  if (!(typeof value === "number" && Number.isInteger(value) && value >= 0)) {
+    throw new Error(
+      `Expected a non-negative integer, got ${typeof value === "number" ? String(value) : typeof value}`
+    );
+  }
+}
+function assertIntegerIsPositive(value) {
+  if (value < 0) {
+    throw new Error(`Expected a non-negative integer, got ${String(value)}`);
+  }
+}
+var Integer = {
+  /**
+   * The `Integer` value representing zero.
+   *
+   * @remarks
+   * Pre-allocated singleton — prefer `Integer.zero` over
+   * `Integer.from(0, 'floor')` to avoid an unnecessary call.
+   *
+   * @public
+   */
+  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions, @typescript-eslint/no-unsafe-type-assertion -- branded type construction: 0 is trivially an integer
+  zero: 0,
+  /**
+   * Type guard that narrows an unknown value to {@link (Integer:type)}.
+   *
+   * @example
+   * ```ts
+   * const n: unknown = getCount();
+   * if (Integer.is(n)) {
+   *   // n is Integer here
+   *   config.retryCount = n;
+   * }
+   * ```
+   * @public
+   */
+  is: (value) => typeof value === "number" && Number.isInteger(value),
+  /**
+   * Assertion guard that throws if the value is not an {@link (Integer:type)}.
+   *
+   * @example
+   * ```ts
+   * const n: unknown = getCount();
+   * Integer.assert(n);
+   * // n is Integer here
+   * ```
+   * @public
+   */
+  assert: assertIsInteger,
+  /**
+   * Coerces a value to an {@link (Integer:type)} by rounding.
+   *
+   * @remarks
+   * Accepts `number`, `string`, `Decimal`, or `Integer`. The rounding
+   * direction is always required — no invisible defaults.
+   *
+   * - **number** (including Integer): must be finite and round to a
+   *   safe integer (`Number.isSafeInteger`). IEEE 754 negative zero is
+   *   normalized to positive zero.
+   * - **string**: must be a valid numeric literal (not empty/whitespace).
+   *   Parsed via `Number()`, then rounded. The result must be a safe integer.
+   * - **Decimal**: delegated to {@link Decimal.toInteger | Decimal.toInteger()}.
+   *
+   * @example
+   * ```ts
+   * Integer.from(9.99, 'floor');              // 9
+   * Integer.from('1.5', 'ceil');              // 2
+   * Integer.from(Decimal.from('2.7'), 'half-up'); // 3
+   * ```
+   *
+   * @throws Error if the value is non-finite, an empty string, an
+   *   unparseable string, or rounds to a value outside the safe integer range.
+   *
+   * @public
+   */
+  from(value, rounding) {
+    if (typeof value === "number") {
+      if (!Number.isFinite(value)) {
+        throw new Error(`Cannot round non-finite value ${String(value)} to an integer`);
+      }
+      const rounded = normalizeZero2(roundToInteger(value, rounding));
+      if (!Number.isSafeInteger(rounded)) {
+        throw new Error(
+          `Value ${String(value)} rounds to ${String(rounded)}, which is outside the safe integer range`
+        );
+      }
+      return rounded;
+    }
+    if (typeof value === "string") {
+      if (value.trim() === "") {
+        throw new Error("Cannot parse empty string as an integer");
+      }
+      const num = Number(value);
+      if (!Number.isFinite(num)) {
+        throw new Error(
+          `Cannot parse "${value}" as a finite number for integer conversion`
+        );
+      }
+      const rounded = normalizeZero2(roundToInteger(num, rounding));
+      if (!Number.isSafeInteger(rounded)) {
+        throw new Error(
+          `Value "${value}" rounds to ${String(rounded)}, which is outside the safe integer range`
+        );
+      }
+      return rounded;
+    }
+    if (isDecimal(value)) {
+      return value.toInteger(rounding);
+    }
+    throw new Error(
+      `Cannot convert ${typeof value} to Integer; expected string, number, or Decimal`
+    );
+  },
+  /**
+   * Convert an {@link (Integer:type)} to a {@link (Decimal:type)}.
+   *
+   * @remarks
+   * This conversion is lossless — every JavaScript integer is exactly
+   * representable as a Decimal.
+   *
+   * @example
+   * ```ts
+   * const dec = Integer.toDecimal(Integer.from(42, 'floor'));
+   * dec.add(Decimal.from('0.5')); // 42.5
+   * ```
+   * @public
+   */
+  toDecimal(value) {
+    return Decimal.from(value);
+  },
+  /**
+   * Type guard that narrows an {@link (Integer:type)} to {@link (PositiveInteger:type)}.
+   *
+   * @example
+   * ```ts
+   * const n = Integer.from(count, 'floor');
+   * if (Integer.isPositive(n)) {
+   *   // n is PositiveInteger here
+   * }
+   * ```
+   * @public
+   */
+  isPositive: (value) => value >= 0,
+  /**
+   * Assertion guard that throws if an {@link (Integer:type)} is not a {@link (PositiveInteger:type)}.
+   *
+   * @example
+   * ```ts
+   * const n = Integer.from(count, 'floor');
+   * Integer.assertIsPositive(n);
+   * // n is PositiveInteger here
+   * ```
+   * @public
+   */
+  assertIsPositive: assertIntegerIsPositive
+};
+var PositiveInteger = {
+  /**
+   * Type guard that narrows an unknown value to {@link (PositiveInteger:type)}.
+   *
+   * @example
+   * ```ts
+   * const n: unknown = getRetryCount();
+   * if (PositiveInteger.is(n)) {
+   *   // n is PositiveInteger here
+   *   config.maxRetries = n;
+   * }
+   * ```
+   * @public
+   */
+  is: (value) => typeof value === "number" && Number.isInteger(value) && value >= 0,
+  /**
+   * Assertion guard that throws if the value is not a {@link (PositiveInteger:type)}.
+   *
+   * @example
+   * ```ts
+   * const n: unknown = getRetryCount();
+   * PositiveInteger.assert(n);
+   * // n is PositiveInteger here
+   * ```
+   * @public
+   */
+  assert: assertIsPositiveInteger,
+  /**
+   * Coerces a value to a {@link (PositiveInteger:type)} by rounding.
+   *
+   * @remarks
+   * Delegates to {@link (Integer:variable).from | Integer.from()} for
+   * rounding, then checks the result is non-negative. All error
+   * conditions from `Integer.from()` apply (non-finite, empty string,
+   * unsafe integer range), plus an additional check that the rounded
+   * result is ≥ 0. IEEE 754 negative zero is normalized to positive zero.
+   *
+   * @example
+   * ```ts
+   * PositiveInteger.from(2.7, 'floor');              // 2
+   * PositiveInteger.from('1.5', 'ceil');              // 2
+   * PositiveInteger.from(Decimal.from('3.2'), 'half-up'); // 3
+   * ```
+   *
+   * @throws Error if the value is non-finite, unparseable, outside the
+   *   safe integer range, or rounds to a negative number.
+   *
+   * @public
+   */
+  from(value, rounding) {
+    const rounded = Integer.from(value, rounding);
+    const normalized = normalizeZero2(rounded);
+    if (normalized < 0) {
+      throw new Error(
+        `Value ${String(value)} rounds to ${String(normalized)}, which is negative`
+      );
+    }
+    return normalized;
+  }
+};
+var StreetAddress = {
+  create: (address) => {
+    return address;
+  }
+};
+var Timestamp = {
+  create: (value) => {
+    return value;
+  }
+};
+
+// src/stdlib/refs.ts
+var Ref = {
+  create: (step) => {
+    return {
+      type: step.object,
+      id: step.id
+    };
+  }
+};
+
 // src/stdlib/types.ts
 var WireReadError = class extends Error {
   /**
@@ -1423,6 +1655,23 @@ function _applyConfig(descriptor, inputObject, appCtx) {
   const strategy = appCtx?.clockTime !== void 0 ? createJsonWireToType(appCtx) : _JsonWireToType;
   return _apply(descriptor, strategy, inputObject);
 }
+
+// src/stdlib/to-const.ts
+function toConst(value) {
+  if (value === null || typeof value !== "object") {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      toConst(item);
+    }
+    return Object.freeze(value);
+  }
+  for (const key of Object.keys(value)) {
+    toConst(value[key]);
+  }
+  return Object.freeze(value);
+}
 export {
   DEFAULT_DIV_PRECISION,
   Decimal,
@@ -1456,5 +1705,6 @@ export {
   _translateMap,
   _translateShape,
   _translateUnion,
-  isDecimal
+  isDecimal,
+  toConst
 };