@flickfyi/flkr 0.0.140 → 0.0.146

package/node_modules/numeric-quantity/dist/numeric-quantity.legacy-esm.d.ts

@@ -0,0 +1,293 @@
+//#region src/types.d.ts
+export interface NumericQuantityOptions {
+  /**
+   * Round the result to this many decimal places. Defaults to 3; must
+   * be greater than or equal to zero.
+   *
+   * @default 3
+   */
+  round?: number | false;
+  /**
+   * Allow and ignore trailing invalid characters _à la_ `parseFloat`.
+   *
+   * @default false
+   */
+  allowTrailingInvalid?: boolean;
+  /**
+   * Attempt to parse Roman numerals if Arabic numeral parsing fails.
+   *
+   * @default false
+   */
+  romanNumerals?: boolean;
+  /**
+   * Generates a `bigint` value if the string represents
+   * a valid integer too large for the `number` type.
+   */
+  bigIntOnOverflow?: boolean;
+  /**
+   * Specifies which character ("." or ",") to treat as the decimal separator.
+   *
+   * @default "."
+   */
+  decimalSeparator?: "," | ".";
+  /**
+   * Allow and strip currency symbols (Unicode `\p{Sc}` category) from the
+   * start and/or end of the string.
+   *
+   * @default false
+   */
+  allowCurrency?: boolean;
+  /**
+   * Parse percentage strings by stripping the `%` suffix.
+   * - `'decimal'` or `true`: `"50%"` → `0.5` (divide by 100)
+   * - `'number'`: `"50%"` → `50` (strip `%`, keep value)
+   * - `false` or omitted: `"50%"` → `NaN` (default behavior)
+   *
+   * @default false
+   */
+  percentage?: "decimal" | "number" | boolean;
+  /**
+   * Return a verbose result object with additional parsing metadata.
+   *
+   * @default false
+   */
+  verbose?: boolean;
+}
+/**
+ * Extracts the type of the `verbose` option from an options type, defaulting to `false`.
+ */
+export type VerboseOption<T> = T extends {
+  verbose?: infer V;
+} ? V : false;
+/**
+ * Extracts the type of the `bigIntOnOverflow` option from an options type,
+ * defaulting to `false`.
+ */
+export type BigIntOnOverflowOption<T> = T extends {
+  bigIntOnOverflow?: infer B;
+} ? B : false;
+/**
+ * Resolves the return type of {@link numericQuantity} based on the options provided.
+ *
+ * @remarks
+ * Inference requires the options object to have literal types. An options object
+ * annotated as `const opts: NumericQuantityOptions = { ... }` widens every option to
+ * `boolean | undefined`, so the return type is the full
+ * `number | bigint | NumericQuantityVerboseResult` union. Use
+ * `satisfies NumericQuantityOptions` instead of a `:` annotation to retain literal
+ * inference.
+ */
+export type NumericQuantityReturnType<T extends NumericQuantityOptions | undefined | null = undefined> = boolean extends VerboseOption<T> ? number | bigint | NumericQuantityVerboseResult : true extends VerboseOption<T> ? NumericQuantityVerboseResult : boolean extends BigIntOnOverflowOption<T> ? number | bigint : true extends BigIntOnOverflowOption<T> ? number | bigint : number;
+/**
+ * Verbose result returned when `verbose: true` is set.
+ */
+export interface NumericQuantityVerboseResult {
+  /** The parsed numeric value (NaN if invalid). */
+  value: number | bigint;
+  /** The original input, coerced to a string (`symbol` input becomes e.g. `'Symbol(1)'`). */
+  input: string;
+  /** Currency symbol(s) stripped from the start, if any. */
+  currencyPrefix?: string;
+  /** Currency symbol(s) stripped from the end, if any. */
+  currencySuffix?: string;
+  /** True if a `%` suffix was stripped. */
+  percentageSuffix?: boolean;
+  /** Trailing invalid (usually non-numeric) characters detected in the input, if any. Populated even when `allowTrailingInvalid` is `false`. */
+  trailingInvalid?: string;
+  /** The leading sign character (`'-'` or `'+'`), if present. Omitted when no explicit sign was in the input. */
+  sign?: "-" | "+";
+  /** The whole-number part of a mixed fraction (e.g. `1` from `"1 2/3"`). Omitted for pure fractions, decimals, and integers. */
+  whole?: number;
+  /** The numerator of a fraction (e.g. `2` from `"1 2/3"`, or `1` from `"1/2"`). Always unsigned. */
+  numerator?: number;
+  /** The denominator of a fraction (e.g. `3` from `"1 2/3"`, or `2` from `"1/2"`). Always unsigned. */
+  denominator?: number;
+}
+/**
+ * Unicode vulgar fraction code points.
+ */
+export type VulgarFraction = "¼" | "½" | "¾" | "⅐" | "⅑" | "⅒" | "⅓" | "⅔" | "⅕" | "⅖" | "⅗" | "⅘" | "⅙" | "⅚" | "⅛" | "⅜" | "⅝" | "⅞" | "⅟";
+/**
+ * Unicode superscript digit code points.
+ */
+export type SuperscriptDigit = "⁰" | "¹" | "²" | "³" | "⁴" | "⁵" | "⁶" | "⁷" | "⁸" | "⁹";
+/**
+ * Unicode subscript digit code points.
+ */
+export type SubscriptDigit = "₀" | "₁" | "₂" | "₃" | "₄" | "₅" | "₆" | "₇" | "₈" | "₉";
+/**
+ * Allowable Roman numeral characters (ASCII, uppercase only).
+ */
+export type RomanNumeralAscii = "I" | "V" | "X" | "L" | "C" | "D" | "M";
+/**
+ * Unicode Roman numeral code points (uppercase and lowercase,
+ * representing 1-12, 50, 100, 500, and 1000).
+ */
+export type RomanNumeralUnicode = "Ⅰ" | "Ⅱ" | "Ⅲ" | "Ⅳ" | "Ⅴ" | "Ⅵ" | "Ⅶ" | "Ⅷ" | "Ⅸ" | "Ⅹ" | "Ⅺ" | "Ⅻ" | "Ⅼ" | "Ⅽ" | "Ⅾ" | "Ⅿ" | "ⅰ" | "ⅱ" | "ⅲ" | "ⅳ" | "ⅴ" | "ⅵ" | "ⅶ" | "ⅷ" | "ⅸ" | "ⅹ" | "ⅺ" | "ⅻ" | "ⅼ" | "ⅽ" | "ⅾ" | "ⅿ";
+/**
+ * Union of ASCII and Unicode Roman numeral characters/code points.
+ */
+export type RomanNumeral = RomanNumeralAscii | RomanNumeralUnicode;
+//#endregion
+//#region src/constants.d.ts
+/**
+ * Normalizes non-ASCII decimal digits to ASCII digits.
+ * Converts characters from Unicode decimal digit blocks (e.g., Arabic-Indic,
+ * Devanagari, Bengali) to their ASCII equivalents (0-9).
+ *
+ * All current Unicode \p{Nd} blocks are included in decimalDigitBlockStarts.
+ */
+export declare const normalizeDigits: (str: string) => string;
+/**
+ * Map of Unicode superscript and subscript digit code points to ASCII digits.
+ */
+export declare const superSubDigitToAsciiMap: Record<SuperscriptDigit | SubscriptDigit, `${number}`>;
+/**
+ * Captures Unicode superscript and subscript digits.
+ */
+export declare const superSubDigitsRegex: RegExp;
+/**
+ * Map of Unicode fraction code points to their ASCII equivalents.
+ */
+export declare const vulgarFractionToAsciiMap: Record<VulgarFraction, `${number}/${number | ""}`>;
+/**
+ * Captures the individual elements of a numeric string. Commas and underscores are allowed
+ * as separators, as long as they appear between digits and are not consecutive.
+ *
+ * Capture groups:
+ *
+ * |  #  | Description                                        | Example(s)                                                              |
+ * | --- | -------------------------------------------------- | ----------------------------------------------------------------------- |
+ * | `0` | entire match                                       | `"2 1/3"` from `"2 1/3"`                                                |
+ * | `1` | sign (`-` or `+`)                                  | `"-"` from `"-2 1/3"`                                                   |
+ * | `2` | whole number or numerator                          | `"2"` from `"2 1/3"`; `"1"` from `"1/3"`                                |
+ * | `3` | entire tail: fraction, decimal, and/or exponent    | `" 1/3"` from `"2 1/3"`; `".23"` from `"1.23"`; `".5e3"` from `"1.5e3"` |
+ * | `4` | exponent, when there is no decimal portion         | `"e3"` from `"1e3"`                                                     |
+ * | `5` | exponent, when there is a decimal portion          | `"e-3"` from `"1.5e-3"`                                                 |
+ * | `6` | numerator of a mixed number (incl. leading space)  | `" 2"` from `"1 2/3"`                                                   |
+ *
+ * Groups 4–6 are subgroups of group 3 and are not used directly by
+ * {@link numericQuantity}; only groups 1–3 are consumed.
+ *
+ * _Capture groups 2 and 3 may include comma/underscore separators._
+ *
+ * @example
+ *
+ * ```ts
+ * numericRegex.exec("1")      // [ "1",      null, "1",     null,     null, null,  null ]
+ * numericRegex.exec("1.23")   // [ "1.23",   null, "1",     ".23",    null, null,  null ]
+ * numericRegex.exec("1 2/3")  // [ "1 2/3",  null, "1",     " 2/3",   null, null,  " 2" ]
+ * numericRegex.exec("2/3")    // [ "2/3",    null, "2",     "/3",     null, null,  null ]
+ * numericRegex.exec("2 / 3")  // [ "2 / 3",  null, "2",     " / 3",   null, null,  null ]
+ * numericRegex.exec("-2 1/3") // [ "-2 1/3", "-",  "2",     " 1/3",   null, null,  " 1" ]
+ * numericRegex.exec("1e3")    // [ "1e3",    null, "1",     "e3",     "e3", null,  null ]
+ * numericRegex.exec("1.5e-3") // [ "1.5e-3", null, "1",     ".5e-3",  null, "e-3", null ]
+ * numericRegex.exec("1,000")  // [ "1,000",  null, "1,000", null,     null, null,  null ]
+ * ```
+ *
+ * @remarks
+ *
+ * This pattern and {@link numericRegexWithTrailingInvalid} are maintained as two separate
+ * literals and must be kept in sync. They differ _only_ in the tail: `$` here versus
+ * `(\s*[^.\d/].*)?` there. `src/index.test.ts` asserts that equality.
+ *
+ * Group 2 is `((?:\d(?:[,_]\d|\d)*)?)`, deliberately `?` and not `*`. Every string the
+ * inner group matches begins and ends with a digit, so concatenating two of them yields
+ * another string of the same shape: an outer `*` would add no strings to the language,
+ * only exponentially many ways to split one digit run across iterations. That made a
+ * failing match catastrophically backtrack — `'1'.repeat(30) + '!'` took ~15s on V8.
+ */
+export declare const numericRegex: RegExp;
+/**
+ * Same as {@link numericRegex}, but allows (and ignores) trailing invalid characters.
+ * Capture groups 1–6 are identical to {@link numericRegex}'s; capture group 7 contains the
+ * trailing invalid portion.
+ *
+ * @example
+ *
+ * ```ts
+ * numericRegexWithTrailingInvalid.exec("1abc")
+ * // [ "1abc",      null, "1", null,   null, null, null, "abc"  ]
+ * numericRegexWithTrailingInvalid.exec("1 2/3 xyz")
+ * // [ "1 2/3 xyz", null, "1", " 2/3", null, null, " 2", " xyz" ]
+ * ```
+ *
+ * @remarks
+ *
+ * Must be kept in sync with {@link numericRegex} — see that pattern's remarks.
+ */
+export declare const numericRegexWithTrailingInvalid: RegExp;
+/**
+ * Captures any Unicode vulgar fractions.
+ */
+export declare const vulgarFractionsRegex: RegExp;
+/**
+ * Map of Roman numeral sequences to their decimal equivalents.
+ */
+export declare const romanNumeralValues: { [k in `${RomanNumeralAscii}` | `${RomanNumeralAscii}${RomanNumeralAscii}` | `${RomanNumeralAscii}${RomanNumeralAscii}${RomanNumeralAscii}` | `${RomanNumeralAscii}${RomanNumeralAscii}${RomanNumeralAscii}${RomanNumeralAscii}`]?: number; };
+/**
+ * Map of Unicode Roman numeral code points to their ASCII equivalents.
+ */
+export declare const romanNumeralUnicodeToAsciiMap: Record<RomanNumeralUnicode, keyof typeof romanNumeralValues>;
+/**
+ * Captures all Unicode Roman numeral code points.
+ */
+export declare const romanNumeralUnicodeRegex: RegExp;
+/**
+ * Captures a valid Roman numeral sequence.
+ *
+ * Capture groups:
+ *
+ * |  #  |  Description    |         Example          |
+ * | --- | --------------- | ------------------------ |
+ * | `0` |  Entire string  |  "MCCXIV" from "MCCXIV"  |
+ * | `1` |  Thousands      |  "M" from "MCCXIV"       |
+ * | `2` |  Hundreds       |  "CC" from "MCCXIV"      |
+ * | `3` |  Tens           |  "X" from "MCCXIV"       |
+ * | `4` |  Ones           |  "IV" from "MCCXIV"      |
+ *
+ * @example
+ *
+ * ```ts
+ * romanNumeralRegex.exec("M")      // [      "M", "M",   "",  "",   "" ]
+ * romanNumeralRegex.exec("XII")    // [    "XII",  "",   "", "X", "II" ]
+ * romanNumeralRegex.exec("MCCXIV") // [ "MCCXIV", "M", "CC", "X", "IV" ]
+ * ```
+ */
+export declare const romanNumeralRegex: RegExp;
+/**
+ * Default options for {@link numericQuantity}.
+ */
+export declare const defaultOptions: Required<NumericQuantityOptions>;
+//#endregion
+//#region src/isNumericQuantity.d.ts
+/**
+ * Checks if a value represents a valid numeric quantity.
+ *
+ * Returns `true` if the value can be parsed as a number, `false` otherwise.
+ * Accepts the same options as `numericQuantity`.
+ */
+export declare const isNumericQuantity: (quantity: unknown, options?: NumericQuantityOptions) => boolean;
+//#endregion
+//#region src/numericQuantity.d.ts
+/**
+ * Converts a string to a number, like an enhanced version of `parseFloat`.
+ *
+ * The string can include mixed numbers, vulgar fractions, or Roman numerals.
+ * Input is expected to be a `string`, but will be coerced to `string` if necessary.
+ */
+declare function numericQuantity(quantity: unknown): number;
+declare function numericQuantity<const T extends NumericQuantityOptions | undefined | null>(quantity: unknown, options: T): NumericQuantityReturnType<T>;
+//#endregion
+//#region src/parseRomanNumerals.d.ts
+/**
+ * Converts a string of Roman numerals to a number, like `parseInt`
+ * for Roman numerals. Uses modern, strict rules (only 1 to 3999).
+ *
+ * The string can include ASCII representations of Roman numerals
+ * or Unicode Roman numeral code points (`U+2160` through `U+217F`).
+ */
+export declare const parseRomanNumerals: (romanNumerals: string) => number;
+//#endregion
+export { numericQuantity };
+//# sourceMappingURL=numeric-quantity.legacy-esm.d.ts.map