@gram-lang/i18n 1.4.1 → 1.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # @gram-lang/i18n
2
2
 
3
- [![npm version](https://badge.fury.io/js/@gram-lang%2Fi18n.svg)](https://www.npmjs.com/package/@gram-lang/i18n)
3
+ [![npm](https://img.shields.io/npm/v/@gram-lang/i18n?color=cb3837&style=flat-square)](https://www.npmjs.com/package/@gram-lang/i18n)
4
4
  [![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
5
5
 
6
6
  *Part of the [Gram monorepo](https://git.gram-lang.org/gram-lang/gram).*
@@ -11,7 +11,7 @@ The translation and normalization module of the Gram recipe language: it normali
11
11
 
12
12
  ## 📚 General Documentation
13
13
 
14
- For full syntax specifications, grammar details, cheatsheets, and best practices, please refer to the **[Gram Documentation](https://docs.gram-lang.org/)**.
14
+ For full syntax specifications, grammar details, cheatsheets, and best practices, please refer to the **[Gram Documentation](https://gram-lang.org/docs/)**.
15
15
 
16
16
  ---
17
17
 
@@ -47,11 +47,13 @@ console.log(resolveTimeUnit('minutes')); // 'm'
47
47
  `getDictionary(lang)` returns the dictionary of a language (`en` or `fr`): the labels of the renderer's views (`renderer.*`, including the names of the outputs and of the formats), the units of durations (`renderer.durationUnits`, `1h 30min` or `1j 1h`) and the strings of the playground. `fillTemplate(template, values)` fills the `{name}` placeholders of a dictionary string (`"Serve at {time}"` becomes `"Serve at 20:00"`) and leaves a name with no value as written, so a missing value shows up instead of vanishing.
48
48
 
49
49
  ```javascript
50
- import { getDictionary, fillTemplate } from '@gram-lang/i18n';
50
+ import { getDictionary, fillTemplate, formatNumber, parseDuration } from '@gram-lang/i18n';
51
51
 
52
52
  const t = getDictionary('fr');
53
53
  console.log(t.renderer.durationUnits); // { day: 'j', hour: 'h', minute: 'min', second: 's' }
54
54
  console.log(fillTemplate('Serve at {time}', { time: '20:00' })); // 'Serve at 20:00'
55
+ console.log(formatNumber(1.5, 'fr')); // '1,5'
56
+ console.log(parseDuration('1h 30min')); // { ok: true, kind: 'single', ... }
55
57
  ```
56
58
 
57
59
  A key is added in both languages together: a surface never carries a word of its own.
@@ -70,6 +72,9 @@ If a language-specific code (e.g., `'fr'`) is provided, the function checks the
70
72
  * `src/dictionary.ts`: Dictionary compiler helper that transforms structured translations into flat `O(1)` maps.
71
73
  * `src/units.ts`: Mass and volume unit dictionary (French & English) and normalizer.
72
74
  * `src/time.ts`: Time unit dictionary (French & English) and normalizer.
75
+ * `src/duration.ts`: Compound, clock, prime, and range duration parser (`parseDuration()`).
76
+ * `src/numbers.ts`: Locale-aware number formatting (`formatNumber()`, `localizeDecimals()`, `toKitchenFraction()`).
77
+ * `src/quantity.ts`: Quantity term arithmetic and formatting (`termsTotal()`, `mergeTerms()`, `scaleTerms()`, `formatTerms()`).
73
78
  * `src/locales/`: The `en` and `fr` dictionaries (renderer views, nutrients, playground) and `getDictionary()`.
74
79
  * `src/template.ts`: `fillTemplate()`.
75
80
  * `src/categories.ts`: Shopping list category keys and their labels per language.
package/dist/index.d.ts CHANGED
@@ -36,6 +36,45 @@ declare const UNIT_CONVERSIONS: {
36
36
  mass: UnitMap;
37
37
  volume: UnitMap;
38
38
  };
39
+ /**
40
+ * A run of units of one measuring system whose sizes are exact whole-number
41
+ * multiples of each other: what a cook can add up without rounding
42
+ * (`1 cup + 1 tbsp` = `17 tbsp`). Each step is the unit's size counted in the
43
+ * ladder's smallest unit (1 cup = 48 tsp).
44
+ *
45
+ * `UNIT_CONVERSIONS` says how much a unit weighs or holds in grams or
46
+ * milliliters, with its factors rounded (`cup: 236.588`); a ladder only says
47
+ * how units of one system relate, exactly. The two agree to 0.01%
48
+ * (`units-ladders.test.ts`).
49
+ */
50
+ interface UnitLadder {
51
+ id: "usVolume" | "imperialMass" | "metricMass" | "metricVolume";
52
+ family: keyof typeof UNIT_CONVERSIONS;
53
+ /** Canonical unit → its size in the ladder's smallest unit. */
54
+ steps: Readonly<Record<string, number>>;
55
+ }
56
+ declare const UNIT_LADDERS: readonly UnitLadder[];
57
+ /** Where a unit stands on its ladder. */
58
+ interface LadderStep {
59
+ ladder: UnitLadder;
60
+ /** The canonical unit (`cup` for `cups`, `tbsp` for `càs`). */
61
+ unit: string;
62
+ /** Its size in the ladder's smallest unit. */
63
+ size: number;
64
+ }
65
+ /**
66
+ * The ladder a unit belongs to (any spelling: `cups`, `càs`, `kilo`), or
67
+ * `null` for a unit on no ladder (`pinch`, `gousse`, no unit at all).
68
+ */
69
+ declare function ladderOf(rawUnit: string | undefined | null, lang?: string): LadderStep | null;
70
+ /**
71
+ * True when every unit stands on one same ladder (`cup`, `tbsp`, `tsp`), so
72
+ * their amounts add up exactly. False for no unit at all, for a unit on no
73
+ * ladder, and across systems (`cup` and `ml`, `oz` and `g`).
74
+ */
75
+ declare function sameLadder(rawUnits: readonly (string | undefined | null)[], lang?: string): boolean;
76
+ /** The spelling of a canonical unit (`tbsp`) in a language (`càs` in French). */
77
+ declare function unitSpelling(canonical: string, lang?: string): string;
39
78
  /**
40
79
  * Normalizes a raw string unit into a standard canon unit.
41
80
  * Examples: 'càs' -> 'tbsp', 'kilo' -> 'kg'.
@@ -69,6 +108,25 @@ declare function toLargerMetricUnit(value: number, rawUnit: string | undefined |
69
108
  value: number;
70
109
  unit: string;
71
110
  };
111
+ /**
112
+ * Converts a value between two units of the same family, mass to mass or
113
+ * volume to volume (`1 l` → `1000 ml`, `1 lb` → `453.59 g`), through
114
+ * `UNIT_CONVERSIONS` alone. The same unit, however spelled, gives the value
115
+ * back. Across families (mass and volume), or for a unit that is neither,
116
+ * `null`: crossing needs a density, which only the caller can bring.
117
+ */
118
+ declare function convertUnitInFamily(value: number, fromUnit: string | null | undefined, toUnit: string | null | undefined, lang?: string): number | null;
119
+ /**
120
+ * True when two counting units (neither a mass nor a volume) name the same
121
+ * thing: the same spelling, or one is the other with a plural ending `s`,
122
+ * `es` or `x` (`gousse`/`gousses`, `tranche`/`tranches`, `box`/`boxes`,
123
+ * `chou`/`choux`). Forms are compared, never a suffix stripped (`tranches`
124
+ * less `es` is `tranch`), and no plural is looked for under three letters.
125
+ * No unit, and every spelling of "a piece" (`pièce`, `pc`, `unit`...), count
126
+ * as the same: no unit. For ratios only: the shopping list keeps `gousse` and
127
+ * `gousses` apart.
128
+ */
129
+ declare function sameCountUnit(a: string | null | undefined, b: string | null | undefined, lang?: string): boolean;
72
130
  /** True for a unit of mass or volume Gram knows (g, kg, cup, tbsp, c.à.s...). */
73
131
  declare function isMeasureUnit(rawUnit: string | undefined | null, lang?: string): boolean;
74
132
  /**
@@ -92,11 +150,21 @@ declare function formatNumber(value: number, lang?: string, maxDecimals?: number
92
150
  /** The decimal separator of a language: `"."` in English, `","` in French. */
93
151
  declare function decimalSeparator(lang?: string): string;
94
152
  /**
95
- * The decimal points of a quantity already written as text (a range
96
- * `1.5-2`, a timer `1.5`) in the reader's language: `"1,5-2"` in French.
97
- * Only a point between two digits changes, so `1/2` or a unit stay as they are.
153
+ * The decimal separators of a quantity already written as text (a range
154
+ * `1.5-2`, a timer `1,5`) in the reader's language: `"1,5-2"` in French,
155
+ * `"1.5"` in English. Gram reads a point or a comma between two digits as a
156
+ * decimal separator, so both change; `1/2` or a unit stay as they are.
98
157
  */
99
158
  declare function localizeDecimals(text: string, lang?: string): string;
159
+ /**
160
+ * A comma that a reader could take for a thousands separator: exactly three
161
+ * digits after it and a whole part of one to three digits, not zero
162
+ * (`1,000`, `12,500`). Gram reads it as a decimal (1, 12.5), as it reads every
163
+ * comma between two digits, and has no thousands separator; `0,125` or
164
+ * `1,25` cannot be one. The point is not concerned: it has always been a
165
+ * decimal in Gram, so `1.000` keeps meaning 1.
166
+ */
167
+ declare function looksLikeThousands(text: string): boolean;
100
168
  /** `"1/4"` for a value strictly between 0 and 1 that is (nearly) a common fraction. */
101
169
  declare function commonFraction(value: number): string | undefined;
102
170
  /** True for a unit read in fractions (spoons, cups, imperial measures). */
@@ -268,6 +336,10 @@ declare const en: {
268
336
  runSheetInStock: string;
269
337
  runSheetProgramStep: string;
270
338
  runSheetProgramSteps: string;
339
+ /**
340
+ * @deprecated Since 1.5.0, will be removed in 2.0.0. (Ref: i18n-run-sheet-range)
341
+ * The run sheet writes a range with `formatDurationRange` (`8–16 h`), as the steps do.
342
+ */
271
343
  runSheetRange: string;
272
344
  runSheetPossibleFrom: string;
273
345
  runSheetFixedService: string;
@@ -316,6 +388,8 @@ declare const en: {
316
388
  tooltipBakers: string;
317
389
  tooltipTakenFrom: string;
318
390
  alternatives: string;
391
+ tooltipRatio: string;
392
+ relativeOf: string;
319
393
  decreasePortions: string;
320
394
  editPortions: string;
321
395
  increasePortions: string;
@@ -477,6 +551,10 @@ declare const en: {
477
551
  stepQuantitiesDesc: string;
478
552
  nutritionBasis: string;
479
553
  nutritionBasisAuto: string;
554
+ clock: string;
555
+ clockAuto: string;
556
+ clock12h: string;
557
+ clock24h: string;
480
558
  rejectedSlots: string;
481
559
  forceReference: string;
482
560
  autoDetect: string;
@@ -500,6 +578,7 @@ declare const en: {
500
578
  scaleByIngredient: string;
501
579
  bakersMath: string;
502
580
  comments: string;
581
+ clock: string;
503
582
  stepQuantities: string;
504
583
  nutritionBasis: string;
505
584
  bakersMathOnly: string;
@@ -534,6 +613,8 @@ declare const en: {
534
613
  show: string;
535
614
  expandConsole: string;
536
615
  collapseConsole: string;
616
+ notInDatabase: string;
617
+ showDatabase: string;
537
618
  };
538
619
  errorState: {
539
620
  title: string;
@@ -541,6 +622,12 @@ declare const en: {
541
622
  jumpToError: string;
542
623
  line: string;
543
624
  };
625
+ database: {
626
+ tabLabel: string;
627
+ project: string;
628
+ docLink: string;
629
+ docHref: string;
630
+ };
544
631
  tabs: {
545
632
  addFile: string;
546
633
  removeFile: string;
@@ -566,6 +653,18 @@ declare const en: {
566
653
  statusWarnings: string;
567
654
  copyBtn: string;
568
655
  };
656
+ cook: {
657
+ /** Under a step of `gram cook`: the state that ends it (`={ribbon stage}`). */
658
+ targetState: string;
659
+ /** When a timer of a step rings: the target states to check, `{states}`. */
660
+ checkTargetState: string;
661
+ };
662
+ languageServer: {
663
+ /** Hover on a section anchor: `{duration}` is the anticipation. */
664
+ anchorReady: string;
665
+ anchorInDays: string;
666
+ anchorInHours: string;
667
+ };
569
668
  };
570
669
  type GramLocale = typeof en;
571
670
 
@@ -578,4 +677,322 @@ declare function getDictionary(lang?: string): GramLocale;
578
677
  */
579
678
  declare function fillTemplate(template: string, values: Readonly<Record<string, string>>): string;
580
679
 
581
- export { CATEGORY_KEYS, type CategoryKey, type CompiledDict, type GramLocale, type LanguageDict, TIME_BY_LANG, TIME_DICTIONARIES, TIME_GLOBAL, TIME_TO_MINUTES, UNIT_BY_LANG, UNIT_CONVERSIONS, UNIT_DICTIONARIES, UNIT_GLOBAL, type UnitMap, commonFraction, compileDictionary, decimalSeparator, fillTemplate, formatNumber, getAiLanguageInstruction, getCategoryLabels, getDefaultCategories, getDictionary, isCategoryKey, isCoarseUnit, isFractionUnit, isMeasureUnit, isMetricMassUnit, localizeDecimals, normalizeUnit, resolveTimeUnit, toKitchenFraction, toLargerMetricUnit, unitContainsQuantity, unitKey };
680
+ /**
681
+ * Durations as a recipe writes them: `1h30`, `1 hr 30 mins`, `1 heure 30`,
682
+ * `1:30 h`, `5'30"`, `45 min - 1 h`. `parseDuration` reads one into minutes,
683
+ * or says precisely why it will not: it never guesses, and never turns an
684
+ * unclear duration into 0.
685
+ *
686
+ * Reading happens in two steps. The text is first cut into tokens by kind of
687
+ * character (numbers, letters, primes, `:`, `+`, `-`), so spaces carry no
688
+ * meaning (`1h30`, `1 h 30`, `1hr 30` read alike), except between a whole
689
+ * number and a fraction (`1 1/2`). The token sequence is then checked against
690
+ * the three forms (units, clock, primes) and the range rules.
691
+ *
692
+ * The units come from `TIME_DICTIONARIES`, every language at once: a timer
693
+ * reads without knowing the language of the recipe.
694
+ */
695
+ /** A canonical time unit: day, hour, minute, second. */
696
+ type DurationUnit = "d" | "h" | "m" | "s";
697
+ /** How a duration is written: `1h30` (units), `1:30 h` (clock), `5'30"` (primes). */
698
+ type DurationForm = "units" | "clock" | "prime";
699
+ /** One term of a duration, in the unit it was written in (`1h30` is `1 h` and `30 m`). */
700
+ interface DurationPart {
701
+ value: number;
702
+ unit: DurationUnit;
703
+ }
704
+ /** One duration, or one side of a range. */
705
+ interface DurationSide {
706
+ minutes: number;
707
+ parts: DurationPart[];
708
+ form: DurationForm;
709
+ }
710
+ /**
711
+ * Why a text is not a duration Gram reads:
712
+ * - `empty`: nothing between the braces;
713
+ * - `missingUnit`: a number with no unit at all (`30`, `1-2`);
714
+ * - `unknownUnit`: a word right after a number that is not a time unit (`3 bananas`);
715
+ * - `words`: any other word (`half an hour`, `1 heure et demie`, `about 10 min`);
716
+ * - `multiplication`: `2 * 2 min`, written as the total instead;
717
+ * - `iso8601`: `PT1H30M`, a notation for machines;
718
+ * - `unexpected`: a character or a sign out of place (`1h, 30min`, `-10 min`, `1/0 h`);
719
+ * - `ambiguousClock`: a two-part clock with no unit (`1:30`: hours or minutes?);
720
+ * - `clockFormat`: a malformed clock (`1:5 h`, `1:30 d`, more than three parts);
721
+ * - `unitOrder`: units not from the largest to the smallest (`30min 1h`);
722
+ * - `duplicateUnit`: the same unit twice (`1h 2h`);
723
+ * - `overflow60`: 60 or more after an hour or a minute, where the unit is
724
+ * implied, in a clock or with a prime (`1h75`, `1:75 h`, `5'90"`); with its
725
+ * unit written out it is read as written (`1 h 75 min` is 2 h 15 min);
726
+ * - `decimalInCompound`: a decimal or a fraction in a duration of several terms (`1.5h30`);
727
+ * - `decimalPrime`: a decimal or a fraction with a prime (`1.5'`);
728
+ * - `bareNumber`: a number with no unit where none can be implied (`1j3`, `1 30 min`);
729
+ * - `reversedRange`: a range written from the largest to the smallest (`2-1 h`):
730
+ * the minimum comes first, in the order of the text (logical order, so a
731
+ * right-to-left language writes it the same way);
732
+ * - `emptyRange`: a range whose two sides are equal (`1-1 h`);
733
+ * - `ambiguousRange`: a range where one side's unit cannot be told (`1-2h30`).
734
+ */
735
+ type DurationFailure = "empty" | "missingUnit" | "unknownUnit" | "words" | "multiplication" | "iso8601" | "unexpected" | "ambiguousClock" | "clockFormat" | "unitOrder" | "duplicateUnit" | "overflow60" | "decimalInCompound" | "decimalPrime" | "bareNumber" | "reversedRange" | "emptyRange" | "ambiguousRange";
736
+ type DurationResult = {
737
+ ok: true;
738
+ /** The duration the schedule uses: the middle of a range. */
739
+ minutes: number;
740
+ range?: {
741
+ min: number;
742
+ max: number;
743
+ };
744
+ /** One side, or the two sides of a range. */
745
+ sides: [DurationSide] | [DurationSide, DurationSide];
746
+ } | {
747
+ ok: false;
748
+ reason: DurationFailure;
749
+ /** The word read as a unit, for `unknownUnit`. */
750
+ unit?: string;
751
+ };
752
+ type Failure = Extract<DurationResult, {
753
+ ok: false;
754
+ }>;
755
+ /**
756
+ * `int`: digits only (`30`). `decimal`: `1.5`, `1,5`. `fraction`: `1/2`, `½`,
757
+ * `1½`, `1 1/2`. Only an `int` follows an hour or a minute without a unit, or
758
+ * makes a clock.
759
+ */
760
+ type NumKind = "int" | "decimal" | "fraction";
761
+ type Token = {
762
+ kind: "num";
763
+ value: number;
764
+ text: string;
765
+ num: NumKind;
766
+ space: boolean;
767
+ } | {
768
+ kind: "word";
769
+ text: string;
770
+ unit?: DurationUnit;
771
+ } | {
772
+ kind: "prime";
773
+ unit: "m" | "s";
774
+ } | {
775
+ kind: "colon";
776
+ } | {
777
+ kind: "plus";
778
+ } | {
779
+ kind: "dash";
780
+ } | {
781
+ kind: "star";
782
+ };
783
+ /**
784
+ * Cuts a duration into tokens: the step that makes `1h30`, `1 h 30` and
785
+ * `1hr 30` the same sequence. A unit is any run of letters, in any script,
786
+ * lowercased, with a `.` right after it dropped (`hr.`, `min.`, `Std.`).
787
+ */
788
+ declare function tokenizeDuration(text: string): {
789
+ ok: true;
790
+ tokens: Token[];
791
+ } | Failure;
792
+ /**
793
+ * Reads a duration as a recipe writes it, in any language Gram knows:
794
+ * `parseDuration("1h30")` is `{ ok: true, minutes: 90, … }`,
795
+ * `parseDuration("1:30")` is `{ ok: false, reason: "ambiguousClock" }`.
796
+ *
797
+ * A range keeps both sides and gives its middle as `minutes`, as the schedule
798
+ * uses it. No sign is read (an anchor's `-` is the caller's), and no duration
799
+ * is capped: that is the compiler's job.
800
+ */
801
+ declare function parseDuration(text: string): DurationResult;
802
+
803
+ /**
804
+ * A numeric value as the compiled recipe stores it: a plain number, or the
805
+ * parser's single / fraction / range shape (structurally the parser's
806
+ * `QuantityValueAST`, redeclared here so this module stays free of it).
807
+ */
808
+ type QuantityValue = {
809
+ type: "single";
810
+ value: number;
811
+ text?: string;
812
+ } | {
813
+ type: "fraction";
814
+ value: number;
815
+ numerator: number;
816
+ denominator: number;
817
+ text?: string;
818
+ } | {
819
+ type: "range";
820
+ value: number;
821
+ range: {
822
+ min: number;
823
+ max: number;
824
+ };
825
+ text?: string;
826
+ };
827
+ /** The value of one term: kept in the shape it was written in. */
828
+ type TermValue = number | QuantityValue;
829
+ interface Term {
830
+ value: TermValue;
831
+ unit: string | null;
832
+ /** Taken away from the total (`- 2 tbsp`). */
833
+ minus?: boolean;
834
+ }
835
+ /** What a list of terms amounts to, in the compiled recipe's `qty` / `unit` shape. */
836
+ interface TermsTotal {
837
+ qty: TermValue;
838
+ unit: string | null;
839
+ }
840
+ /** Raised by `scaleTerms` when a scaled value stops being a finite number. */
841
+ declare class QuantityOverflowError extends RangeError {
842
+ readonly factor: number;
843
+ constructor(factor: number);
844
+ }
845
+ /**
846
+ * Rounds a mass/quantity value to 2 decimal places, returning a `number`
847
+ * (not a string). Centralizes the `parseFloat(x.toFixed(2))` idiom used
848
+ * throughout kitchen/analyzer so there is a single, documented rounding rule
849
+ * to port when the compiler is reimplemented in another language: `toFixed`
850
+ * uses round-half-away-from-zero on the value's shortest decimal
851
+ * representation, which differs from IEEE round-half-to-even on exact ties.
852
+ */
853
+ declare const round2: (value: number) => number;
854
+ /** True for a value a term can hold (a number, or a single / fraction / range). */
855
+ declare function isTermValue(value: unknown): value is TermValue;
856
+ /**
857
+ * The number a value stands for: the number itself, or its `value` (the
858
+ * middle of a range). `null` when the value carries no number.
859
+ */
860
+ declare function termValueNumber(value: TermValue): number | null;
861
+ /**
862
+ * What the terms amount to.
863
+ *
864
+ * - no term: `null`;
865
+ * - one term added: that term as written (a range stays a range, a fraction
866
+ * keeps its text);
867
+ * - several terms of one unit (its spellings count as one: `cup` / `cups`):
868
+ * their sum in that unit, never converted (`1 tasse + 1 tasse` is
869
+ * `2 tasses`), spelled as the first term added;
870
+ * - several units of one ladder (`UNIT_LADDERS`): their exact sum in the
871
+ * smallest unit written (`1 cup + 1 tbsp` is `17 tbsp`);
872
+ * - several units of one family across systems (`cup` and `ml`, `oz` and
873
+ * `g`): their sum in grams or milliliters, rounded to 2 decimals;
874
+ * - otherwise (`cup` and `g`, `gousse` and `pièce`, a term with no unit next
875
+ * to one with a unit): `null`, the terms do not add up to one amount.
876
+ *
877
+ * A range is added by its bounds (`2-3 g + 200 g` is `202-203 g`): a term
878
+ * taken away removes its highest number from the lowest bound and its lowest
879
+ * number from the highest one. A total with a range in it stays a range.
880
+ */
881
+ declare function termsTotal(terms: readonly Term[]): TermsTotal | null;
882
+ /**
883
+ * How terms are grouped (`mergeKey`): by unit, by ladder of units (`cup` and
884
+ * `tbsp`), or by family, the kind of amount a unit measures (`familyOf`:
885
+ * every mass together, every volume together).
886
+ */
887
+ type MergeMode = "unit" | "ladder" | "family";
888
+ /**
889
+ * The kind of amount a unit measures, for telling the families of a sum
890
+ * apart: a mass, a volume, or (a unit Gram cannot convert, `gousse`) that
891
+ * unit itself.
892
+ */
893
+ declare function familyOf(unit: string | null): string;
894
+ /**
895
+ * The key `mergeTerms` groups a term's unit under: its family in `"family"`
896
+ * mode (`familyOf`), its ladder in `"ladder"` mode (`cup` and `tbsp`, `g`
897
+ * and `kg`), otherwise the unit itself, its spellings counted as one (`cup`
898
+ * / `cups`). A unit Gram does not know (`gousse`) is only lowercased:
899
+ * `gousse` and `gousses` stay two units.
900
+ */
901
+ declare function mergeKey(unit: string | null, mode: MergeMode): string;
902
+ /** The terms grouped by `mergeKey`, groups in the order their first term comes. */
903
+ declare function groupTerms(terms: readonly Term[], mode: MergeMode): Term[][];
904
+ /**
905
+ * Puts the terms of several amounts of one ingredient together, terms added
906
+ * before terms taken away (`2 tbsp` then `1 cup - 4 tbsp` gives
907
+ * `1 cup - 2 tbsp`, never a term taken away first).
908
+ *
909
+ * - `"unit"` adds up the terms of each unit into one, its spellings counted
910
+ * as one (`100 g` and `100 g` give `200 g`); two units stay apart, even on
911
+ * one ladder (`1 cup`, `2 tbsp`): this is how a section lists an
912
+ * ingredient it uses several times.
913
+ * - `"ladder"` adds up the terms of each ladder into one, in the smallest
914
+ * unit written (`1 cup`, `2 tbsp` and `- 4 tbsp` give `14 tbsp`, see
915
+ * `termsTotal`), and the terms of each unit on no ladder into one; two
916
+ * systems (`cup` and `ml`) or two families stay apart.
917
+ *
918
+ * Each result keeps the place of the first term it adds up; a negative
919
+ * result is a term taken away, a result of zero is left out (unless nothing
920
+ * else is left). A lone term stays as written.
921
+ */
922
+ declare function mergeTerms(terms: readonly Term[], mode: MergeMode): Term[];
923
+ /**
924
+ * Multiplies a value by `factor`, rounded to 2 decimals. The source text of a
925
+ * value (`text`, a fraction's `numerator` / `denominator`) only describes the
926
+ * unscaled value, so it is dropped: a scaled fraction becomes a single value.
927
+ * A value that is not a number (a malformed object) comes back untouched.
928
+ * Throws `QuantityOverflowError` when the product is no longer finite.
929
+ */
930
+ declare function scaleTermValue<T extends TermValue>(value: T, factor: number): TermValue;
931
+ /** Every term multiplied by `factor` (see `scaleTermValue`); units are kept. */
932
+ declare function scaleTerms(terms: readonly Term[], factor: number): Term[];
933
+ /** One term as written: its number (or source text) and its unit, without its sign. */
934
+ declare function formatTerm(term: Term): string;
935
+ interface FormatTermsOptions {
936
+ /** Placed between two terms added. Default ` + `. */
937
+ plus?: string;
938
+ /** Placed before a term taken away. Default ` − `. */
939
+ minus?: string;
940
+ /**
941
+ * `"written"` (default): the terms as the author wrote them.
942
+ * `"computed"`: an amount Gram worked out (scaled, or added up from
943
+ * several occurrences), written the way a cook measures it (see
944
+ * `formatTerms`).
945
+ */
946
+ mode?: "written" | "computed";
947
+ /** The reader's language: decimals, and the spelling of a unit Gram brings in. */
948
+ lang?: string;
949
+ /**
950
+ * Writes a number next to its unit. Default: the number as it is in
951
+ * `"written"` mode; in `"computed"` mode a whole number, a kitchen
952
+ * fraction for a spoon or an imperial unit (`1 1/2`), otherwise a
953
+ * decimal in the reader's language.
954
+ */
955
+ number?: (value: number, unit: string | null) => string;
956
+ /** Writes a value's source text (`1/2`, `2.5-3`). Default: as it is. */
957
+ text?: (text: string) => string;
958
+ /**
959
+ * `"computed"` only: an amount the reader buys (a shopping list). A
960
+ * metric amount reaches the larger unit (`1500 g` is `1.5 kg`), and a
961
+ * spoon or imperial amount is recomposed from the top of its scale
962
+ * (`34 tbsp` is `2 cup + 2 tbsp`) once it reaches one of a unit at least
963
+ * four times larger than its own (`3 tsp` stays `3 tsp`).
964
+ */
965
+ buying?: boolean;
966
+ /**
967
+ * `"computed"` only, default `true`: a recomposition may round its last
968
+ * term to what its unit measures (a scaled amount was no exact measure
969
+ * anyway: `1.1 cup` is `1 cup + 1 tbsp + 2 tsp`). `false` writes an
970
+ * amount that does not recompose exactly as it is (`1.6 cup`).
971
+ */
972
+ rounding?: boolean;
973
+ }
974
+ /**
975
+ * The terms as text, in their written order (`1 cup + 1 tbsp`,
976
+ * `1 cup − 2 tbsp + 30 g`); a list that would start with a term taken away
977
+ * writes the terms added first (`1 cup − 2 tbsp`, never `−2 tbsp + 1 cup`).
978
+ *
979
+ * `"written"` mode (the default) writes each term as the author wrote it.
980
+ * `"computed"` mode writes an amount Gram worked out, ladder by ladder (two
981
+ * systems stay apart, term by term):
982
+ *
983
+ * - a spoon, cup or imperial amount is recomposed the way a cook measures
984
+ * it: one amount of the largest unit written when that unit measures it
985
+ * (`MEASURED_FRACTIONS`: `1 1/2 cup`, never `2 1/8 cup`), the terms as they
986
+ * are when each is measurable, otherwise whole units then the rest in the
987
+ * next unit down (`cup`, `tbsp`, `tsp`; `gal`, `qt`, `pt`, `fl oz`; `lb`,
988
+ * `oz`), never above the largest unit written, three terms at most;
989
+ * - a metric amount is one decimal amount in the largest unit written
990
+ * (`1 kg + 200 g` doubled is `2.4 kg`; `800 g + 200 g` is `1000 g`, never
991
+ * `1 kg`, unless `buying`);
992
+ * - a range shares what both bounds have in common and puts the range on
993
+ * the last term (`2 cup + 2-4 tbsp`), otherwise writes each bound in full;
994
+ * - a unit on no ladder adds up with itself only (`2 gousses`).
995
+ */
996
+ declare function formatTerms(terms: readonly Term[], options?: FormatTermsOptions): string;
997
+
998
+ export { CATEGORY_KEYS, type CategoryKey, type CompiledDict, type DurationFailure, type DurationForm, type DurationPart, type DurationResult, type DurationSide, type DurationUnit, type FormatTermsOptions, type GramLocale, type LadderStep, type LanguageDict, type MergeMode, QuantityOverflowError, type QuantityValue, TIME_BY_LANG, TIME_DICTIONARIES, TIME_GLOBAL, TIME_TO_MINUTES, type Term, type TermValue, type TermsTotal, UNIT_BY_LANG, UNIT_CONVERSIONS, UNIT_DICTIONARIES, UNIT_GLOBAL, UNIT_LADDERS, type UnitLadder, type UnitMap, commonFraction, compileDictionary, convertUnitInFamily, decimalSeparator, familyOf, fillTemplate, formatNumber, formatTerm, formatTerms, getAiLanguageInstruction, getCategoryLabels, getDefaultCategories, getDictionary, groupTerms, isCategoryKey, isCoarseUnit, isFractionUnit, isMeasureUnit, isMetricMassUnit, isTermValue, ladderOf, localizeDecimals, looksLikeThousands, mergeKey, mergeTerms, normalizeUnit, parseDuration, resolveTimeUnit, round2, sameCountUnit, sameLadder, scaleTermValue, scaleTerms, termValueNumber, termsTotal, toKitchenFraction, toLargerMetricUnit, tokenizeDuration, unitContainsQuantity, unitKey, unitSpelling };