@escapenavigator/utils 2.0.49 → 2.1.0

package/dist/composition-limits.d.ts

@@ -0,0 +1,63 @@
+import { OrderComposition, TariffCategory } from '@escapenavigator/types/dist/tariff/tariff-category';
+/**
+ * Границы выбора состава: до скольки можно докручивать каждую строку и можно
+ * ли текущий состав вообще оформить.
+ *
+ * Ключевая мысль — потолков два, и они независимы:
+ *  - вместимость комнаты ограничивает ВСЕХ гостей;
+ *  - сетка тарифа `price[N]` ограничивает только тех, кто входит в цену.
+ * Гость надбавочной категории (малыш до 7) занимает место в комнате, но на
+ * уровень `price[N]` не влияет — если считать его одним потолком, добавление
+ * малыша начинает отнимать место у взрослых.
+ *
+ * Второе: недоступный уровень внутри сетки (венью поставил 0 на «трёх») — это
+ * дырка, а не край. Через неё нужно уметь пройти к четверым, поэтому она не
+ * сужает границы, а лишь помечает состав как неоформляемый.
+ */
+export type CompositionLimitsSource = {
+    price?: Record<string, number> | null;
+    categories: TariffCategory[];
+    composition?: OrderComposition | null;
+    /** `questroom.playersMin`. Тарифный минимум всё равно сильнее. */
+    minPlayers?: number | null;
+    /** Вместимость: кап квеста и свободные места тикет-системы. */
+    maxPlayersLimit?: number | null;
+};
+export type CompositionLimits = {
+    /** Всего гостей влезает в комнату. */
+    capacityMax: number;
+    /** Гостей «в цене» — потолок сетки тарифа с учётом вместимости. */
+    pricingMax: number;
+    /** Гостей «в цене» — минимум, ниже которого игра не бронируется. */
+    effectiveMin: number;
+    pricingHeads: number;
+    totalHeads: number;
+    /** Уровни сетки с заданной ценой в пределах [effectiveMin, pricingMax]. */
+    availableLevels: number[];
+    /** Уровни для выбора числа тегами: влезают вместе с надбавочными гостями. */
+    baseLevelOptions: number[];
+    /** Состав внутри сетки, но цена на него не задана. */
+    levelUnavailable: boolean;
+    /** Гостей «в цене» не хватает на минимальную игру. */
+    belowMin: boolean;
+    /** Комната заполнена: «плюс» упёрся во вместимость. */
+    capacityReached: boolean;
+    /** Сетка цен исчерпана: «плюс» на платящих строках упёрся в тариф. */
+    pricingFull: boolean;
+    /** Состав можно оформить. */
+    bookable: boolean;
+    /** До скольки можно докрутить каждую строку. */
+    maxByCategory: Record<string, number>;
+};
+export declare const getCompositionLimits: ({ price, categories, composition, minPlayers, maxPlayersLimit, }: CompositionLimitsSource) => CompositionLimits;
+/**
+ * Состав торчит выше сетки — например, гость выбрал шестерых, а потом
+ * переключил вариацию, где цены есть только до четверых. Возвращает
+ * исправленный состав или `null`, если править нечего.
+ *
+ * Единственная автоправка состава, которая себя оправдывает: без неё на бэке
+ * `price[N]` = undefined → NaN → 500. Подтягивать состав к ближайшему
+ * доступному уровню в любую сторону — нельзя: для гостя это выглядит как
+ * «добавил подростка — отняло взрослого» и как «плюс не нажимается».
+ */
+export declare const clampCompositionToGrid: (source: CompositionLimitsSource) => OrderComposition | null;

package/dist/composition-limits.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clampCompositionToGrid = exports.getCompositionLimits = void 0;
+const tariff_category_mode_enum_1 = require("@escapenavigator/types/dist/tariff/enum/tariff-category-mode.enum");
+const composition_price_1 = require("./composition-price");
+const get_prices_1 = require("./get-prices");
+const positiveInt = (value) => {
+    const amount = Math.round(Number(value));
+    return Number.isFinite(amount) && amount > 0 ? amount : 0;
+};
+const getCompositionLimits = ({ price, categories, composition, minPlayers, maxPlayersLimit, }) => {
+    const levels = (0, get_prices_1.getPricesPlayersArray)(price || {}).map((key) => +key);
+    const maxFromTariff = levels.length ? levels[levels.length - 1] : 0;
+    const minFromTariff = levels.length ? levels[0] : 0;
+    const capacityMax = typeof maxPlayersLimit === 'number' && Number.isFinite(maxPlayersLimit)
+        ? Math.max(0, maxPlayersLimit)
+        : maxFromTariff;
+    const pricingMax = Math.min(maxFromTariff, capacityMax);
+    const effectiveMin = typeof minPlayers === 'number' && Number.isFinite(minPlayers)
+        ? Math.max(minFromTariff, minPlayers)
+        : minFromTariff;
+    const pricingHeads = (0, composition_price_1.getPricingHeads)(composition, categories);
+    const totalHeads = (0, composition_price_1.getTotalHeads)(composition, categories);
+    const addOnHeads = totalHeads - pricingHeads;
+    const availableLevels = Object.entries(price || {})
+        .filter(([key, amount]) => !Number.isNaN(+key) && Number(amount) > 0)
+        .map(([key]) => +key)
+        .filter((level) => level >= effectiveMin && level <= pricingMax)
+        .sort((left, right) => left - right);
+    const capacityRoom = Math.max(0, capacityMax - totalHeads);
+    const pricingRoom = Math.max(0, pricingMax - pricingHeads);
+    const maxByCategory = {};
+    categories.forEach((category) => {
+        const value = positiveInt(composition?.[category.key]);
+        const room = category.countsInPrice ? Math.min(capacityRoom, pricingRoom) : capacityRoom;
+        const own = category.max === null || category.max === undefined
+            ? Number.POSITIVE_INFINITY
+            : positiveInt(category.max);
+        maxByCategory[category.key] = Math.min(own, value + room);
+    });
+    const levelUnavailable = pricingHeads >= effectiveMin && (0, composition_price_1.getPerPersonAmount)(price, pricingHeads) === 0;
+    return {
+        capacityMax,
+        pricingMax,
+        effectiveMin,
+        pricingHeads,
+        totalHeads,
+        availableLevels,
+        baseLevelOptions: availableLevels.filter((level) => level + addOnHeads <= capacityMax),
+        levelUnavailable,
+        belowMin: totalHeads > 0 && pricingHeads < effectiveMin,
+        capacityReached: capacityMax > 0 && totalHeads >= capacityMax,
+        pricingFull: pricingMax > 0 && pricingHeads >= pricingMax,
+        bookable: totalHeads > 0 &&
+            pricingHeads >= effectiveMin &&
+            !levelUnavailable &&
+            totalHeads <= capacityMax,
+        maxByCategory,
+    };
+};
+exports.getCompositionLimits = getCompositionLimits;
+/**
+ * Состав торчит выше сетки — например, гость выбрал шестерых, а потом
+ * переключил вариацию, где цены есть только до четверых. Возвращает
+ * исправленный состав или `null`, если править нечего.
+ *
+ * Единственная автоправка состава, которая себя оправдывает: без неё на бэке
+ * `price[N]` = undefined → NaN → 500. Подтягивать состав к ближайшему
+ * доступному уровню в любую сторону — нельзя: для гостя это выглядит как
+ * «добавил подростка — отняло взрослого» и как «плюс не нажимается».
+ */
+const clampCompositionToGrid = (source) => {
+    const { pricingHeads, pricingMax } = (0, exports.getCompositionLimits)(source);
+    if (!pricingMax || pricingHeads <= pricingMax)
+        return null;
+    const base = source.categories.find((category) => category.mode === tariff_category_mode_enum_1.TariffCategoryModeEnum.BASE);
+    if (!base)
+        return null;
+    const adjusted = positiveInt(source.composition?.[base.key]) - (pricingHeads - pricingMax);
+    if (adjusted < 0)
+        return null;
+    return { ...(source.composition || {}), [base.key]: adjusted };
+};
+exports.clampCompositionToGrid = clampCompositionToGrid;

package/dist/composition-limits.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/composition-limits.spec.js

@@ -0,0 +1,157 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tariff_category_mode_enum_1 = require("@escapenavigator/types/dist/tariff/enum/tariff-category-mode.enum");
+const composition_limits_1 = require("./composition-limits");
+const adults = {
+    key: 'adult',
+    title: 'Взрослые',
+    mode: tariff_category_mode_enum_1.TariffCategoryModeEnum.BASE,
+    value: 0,
+    countsInPrice: true,
+};
+const teens = {
+    key: 'teen',
+    title: 'Подростки',
+    mode: tariff_category_mode_enum_1.TariffCategoryModeEnum.PERCENT,
+    value: 2000,
+    countsInPrice: true,
+};
+/** Малыши: место в комнате занимают, на уровень `price[N]` не влияют. */
+const kids = {
+    key: 'kid',
+    title: 'До 7 лет',
+    mode: tariff_category_mode_enum_1.TariffCategoryModeEnum.FIXED,
+    value: 0,
+    countsInPrice: false,
+};
+const PRICE = { 2: 9800, 3: 12000, 4: 14000, 5: 16000, 6: 18000 };
+/** Венью закрыл игру на троих: цена 0 = «такой состав не продаём». */
+const PRICE_WITH_HOLE = { 2: 9800, 3: 0, 4: 14000, 5: 16000 };
+describe('надбавочные гости не отнимают места у платящих', () => {
+    it('малыш ест вместимость комнаты, но не место в сетке цен', () => {
+        const limits = (0, composition_limits_1.getCompositionLimits)({
+            price: PRICE,
+            categories: [adults, kids],
+            composition: { adult: 6, kid: 0 },
+            maxPlayersLimit: 8,
+        });
+        // Взрослых больше не добавить — сетка тарифа кончилась на шести.
+        expect(limits.maxByCategory.adult).toBe(6);
+        expect(limits.pricingFull).toBe(true);
+        // А малышей можно: в комнате ещё два места.
+        expect(limits.maxByCategory.kid).toBe(2);
+        expect(limits.capacityReached).toBe(false);
+        expect(limits.bookable).toBe(true);
+    });
+    it('добавленный малыш не сдвигает потолок взрослых', () => {
+        const withKid = (0, composition_limits_1.getCompositionLimits)({
+            price: PRICE,
+            categories: [adults, kids],
+            composition: { adult: 3, kid: 2 },
+            maxPlayersLimit: 8,
+        });
+        expect(withKid.pricingHeads).toBe(3);
+        expect(withKid.totalHeads).toBe(5);
+        expect(withKid.maxByCategory.adult).toBe(6);
+    });
+    it('вместимость режет всех, когда мест меньше, чем уровней тарифа', () => {
+        const limits = (0, composition_limits_1.getCompositionLimits)({
+            price: PRICE,
+            categories: [adults, kids],
+            composition: { adult: 3, kid: 1 },
+            maxPlayersLimit: 4,
+        });
+        expect(limits.capacityReached).toBe(true);
+        expect(limits.maxByCategory.adult).toBe(3);
+        expect(limits.maxByCategory.kid).toBe(1);
+    });
+});
+describe('закрытый уровень внутри сетки', () => {
+    const at = (composition) => (0, composition_limits_1.getCompositionLimits)({
+        price: PRICE_WITH_HOLE,
+        categories: [adults, teens],
+        composition,
+    });
+    it('его видно, но оформить нельзя', () => {
+        const limits = at({ adult: 2, teen: 1 });
+        expect(limits.pricingHeads).toBe(3);
+        expect(limits.levelUnavailable).toBe(true);
+        expect(limits.bookable).toBe(false);
+    });
+    it('сквозь него можно пройти к следующему рабочему составу', () => {
+        // Главное: «плюс» на закрытом уровне остаётся живым — взрослых можно
+        // докрутить до четырёх (это пятеро в цене, потолок сетки).
+        expect(at({ adult: 2, teen: 1 }).maxByCategory.adult).toBe(4);
+        expect(at({ adult: 3, teen: 1 }).levelUnavailable).toBe(false);
+        expect(at({ adult: 3, teen: 1 }).bookable).toBe(true);
+    });
+    it('в теги выбора числа закрытый уровень не попадает', () => {
+        expect(at({ adult: 2 }).baseLevelOptions).toEqual([2, 4, 5]);
+    });
+});
+describe('минимум и вместимость', () => {
+    it('одни малыши игру не составляют', () => {
+        const limits = (0, composition_limits_1.getCompositionLimits)({
+            price: PRICE,
+            categories: [adults, kids],
+            composition: { adult: 0, kid: 2 },
+        });
+        expect(limits.belowMin).toBe(true);
+        expect(limits.bookable).toBe(false);
+    });
+    it('пустой состав не считается ни бронируемым, ни ошибочным', () => {
+        const limits = (0, composition_limits_1.getCompositionLimits)({
+            price: PRICE,
+            categories: [adults, kids],
+            composition: {},
+        });
+        expect(limits.belowMin).toBe(false);
+        expect(limits.bookable).toBe(false);
+    });
+    it('минимум квеста сильнее тарифного, но не шире сетки', () => {
+        expect((0, composition_limits_1.getCompositionLimits)({
+            price: PRICE,
+            categories: [adults],
+            composition: { adult: 3 },
+            minPlayers: 4,
+        }).belowMin).toBe(true);
+        expect((0, composition_limits_1.getCompositionLimits)({
+            price: PRICE,
+            categories: [adults],
+            composition: { adult: 2 },
+            minPlayers: 1,
+        }).effectiveMin).toBe(2);
+    });
+    it('лимит категории не пробивается вместимостью', () => {
+        const limits = (0, composition_limits_1.getCompositionLimits)({
+            price: PRICE,
+            categories: [adults, { ...kids, max: 2 }],
+            composition: { adult: 2, kid: 1 },
+            maxPlayersLimit: 8,
+        });
+        expect(limits.maxByCategory.kid).toBe(2);
+    });
+});
+describe('состав выше сетки после смены вариации', () => {
+    it('опускается до нового потолка за счёт базовой категории', () => {
+        expect((0, composition_limits_1.clampCompositionToGrid)({
+            price: { 2: 9800, 3: 12000 },
+            categories: [adults, teens],
+            composition: { adult: 4, teen: 1 },
+        })).toEqual({ adult: 2, teen: 1 });
+    });
+    it('состав внутри сетки не трогается — даже на закрытом уровне', () => {
+        expect((0, composition_limits_1.clampCompositionToGrid)({
+            price: PRICE_WITH_HOLE,
+            categories: [adults, teens],
+            composition: { adult: 2, teen: 1 },
+        })).toBeNull();
+    });
+    it('не опускает базовую категорию ниже нуля', () => {
+        expect((0, composition_limits_1.clampCompositionToGrid)({
+            price: { 2: 9800 },
+            categories: [adults, teens],
+            composition: { adult: 0, teen: 5 },
+        })).toBeNull();
+    });
+});

package/dist/composition-price.d.ts

@@ -0,0 +1,148 @@
+import { TariffReducedRateModeEnum } from '@escapenavigator/types/dist/tariff/enum/tariff-reduced-rate-mode.enum';
+import { OrderComposition, TariffCategory } from '@escapenavigator/types/dist/tariff/tariff-category';
+/**
+ * Расчёт цены игры по составу, разложенному на категории участников.
+ *
+ * Категория — не абсолютный билет, а отношение к базовой доле группы
+ * (`price[уровень] / уровень`). Так сохраняется нелинейная сетка квестов:
+ * гость всегда дешевле в большой команде, и повышение цен не требует
+ * переписывать льготные колонки.
+ *
+ * Модуль заменяет `get-players-price` + `reduced-price` как источник истины;
+ * прежние поля (`players` / `children` / `reducedPlayers`) выражаются через
+ * категории адаптерами ниже и остаются в API ради не обновлённых клиентов.
+ */
+/** Конфиг тарифа в терминах, от которых зависит цена игры. */
+export type CompositionPricingConfig = {
+    price?: Record<string, number> | null;
+    /** Пусто — категории собираются из легаси-полей (`legacy` ниже). */
+    categories?: TariffCategory[] | null;
+    minGameAmount?: number | null;
+    /** Легаси-описание состава — используется, только если `categories` пуст. */
+    legacy?: {
+        reducedRateMode?: TariffReducedRateModeEnum | null;
+        reducedRate?: number | null;
+        reducedTitle?: string | null;
+        reducedPriceDescription?: string | null;
+        childPriceDescription?: string | null;
+    } | null;
+};
+export type CompositionPriceSource = CompositionPricingConfig & {
+    composition?: OrderComposition | null;
+};
+/**
+ * Базовая категория тарифа: полная доля групповой цены. Ровно одна на тариф —
+ * именно она задаёт «цену за человека», от которой считаются остальные.
+ */
+export declare const baseCategory: (categories: TariffCategory[]) => TariffCategory | undefined;
+/**
+ * Категории тарифа, собранные из легаси-полей. Нужны, пока не все тарифы
+ * прошли бэкфилл и пока старые клиенты присылают тариф без `categories`.
+ *
+ * Соответствие точное, поэтому цена не меняется: льготная ставка — это
+ * категория, занимающая место в составе, а детская — надбавка сверх группы.
+ */
+export declare const categoriesFromLegacy: (config: CompositionPricingConfig) => TariffCategory[];
+/**
+ * В тарифе есть строки кроме базовых взрослых: льготные места или надбавка
+ * сверх группы. Для такого состава пикер рисует степперы, а в сумме прячет
+ * «за человека» — она уже стоит на каждой строке.
+ */
+export declare const hasExtraCategories: (categories: TariffCategory[] | null | undefined) => boolean;
+/**
+ * Дописывает в уже сохранённые категории те строки, которые ещё живут только
+ * в легаси-полях (`price.child`, `reduced*`).
+ *
+ * Нужно рефилу: тариф, который успели открыть в новом редакторе, получил
+ * `[BASE]` и больше не попадает в «пустой список», хотя детская цена на нём
+ * ещё есть. Идемпотентен: уже перенесённые детская/льгота не дублируются.
+ */
+export declare const mergeLegacyCategories: (existing: TariffCategory[] | null | undefined, config: CompositionPricingConfig) => TariffCategory[];
+/**
+ * Категории, по которым считать цену: собственные, если тариф уже переведён,
+ * иначе собранные из легаси-полей. Без базовой категории список бессмысленен
+ * (не от чего считать доли) — такой тоже уходит в легаси-ветку.
+ */
+export declare const resolveCategories: (config: CompositionPricingConfig) => TariffCategory[];
+/**
+ * «2 взрослых, 3 студента» — подпись под общим числом человек, когда в тарифе
+ * есть льготные или надбавочные строки. Без них раскладывать нечего.
+ */
+export declare const formatCompositionBreakdown: (composition: OrderComposition | null | undefined, categories: TariffCategory[] | null | undefined) => string;
+/** Нормализованный состав: целые неотрицательные числа, лишние ключи выброшены. */
+export declare const normalizeComposition: (composition: OrderComposition | null | undefined, categories: TariffCategory[]) => OrderComposition;
+/** Гостей всего: и те, что занимают место в сетке, и надбавочные. */
+export declare const getTotalHeads: (composition: OrderComposition | null | undefined, categories: TariffCategory[]) => number;
+/** Гостей, определяющих уровень сетки `price[N]`. */
+export declare const getPricingHeads: (composition: OrderComposition | null | undefined, categories: TariffCategory[]) => number;
+/** Групповая цена уровня. 0 — состав недоступен для брони. */
+export declare const getLevelAmount: (price: Record<string, number> | null | undefined, heads: number) => number;
+/**
+ * Доля одного гостя в групповой цене. Не округляем: остаток от неровного
+ * деления (108 / 3) уходит в скидку места, а групповой итог остаётся ровно
+ * тем, что стоит в прайсе.
+ */
+export declare const getPerPersonAmount: (price: Record<string, number> | null | undefined, heads: number) => number;
+/**
+ * Скидка одного гостя категории от базовой доли.
+ *
+ * Считаем именно скидку, а не цену гостя: групповой итог тогда остаётся
+ * суммой из прайса, а неровное деление не размазывается копейками по головам.
+ */
+export declare const getCategorySeatDiscount: (category: TariffCategory, perPerson: number) => number;
+/** Цена одного гостя категории при текущем составе. */
+export declare const getCategorySeatPrice: (category: TariffCategory, perPerson: number) => number;
+/**
+ * Цена игры за состав.
+ *
+ * Сумма = цена уровня по головам, занимающим место, минус скидки этих голов,
+ * плюс надбавочные категории, и всё это не ниже минимальной стоимости игры.
+ */
+export declare const getCompositionPrice: (source: CompositionPriceSource) => number;
+/**
+ * Сколько гостей категории ещё снижают цену, не упираясь в пол выручки.
+ * Это не лимит выбора — отметить можно больше, цена просто перестанет падать.
+ */
+export declare const getMaxDiscountedSeats: (source: CompositionPriceSource, categoryKey: string) => number;
+/**
+ * Состав по категориям из полей старого формата.
+ *
+ * `reducedPlayers` — это часть `players`, поэтому базовой категории достаётся
+ * остаток. Обратное преобразование — `legacyCountsFromComposition`.
+ */
+export declare const compositionFromLegacy: (legacyCounts: {
+    players?: number | null;
+    children?: number | null;
+    reducedPlayers?: number | null;
+}, categories: TariffCategory[]) => OrderComposition;
+/**
+ * Легаси-поля тарифа, восстановленные из категорий. Обратная операция к
+ * `categoriesFromLegacy`: венью правит тариф уже категориями, а мобильное
+ * приложение и не обновлённые интеграции продолжают читать `price.child` и
+ * `reduced*` — без этой проекции они бы застыли на значениях до перехода.
+ *
+ * Схлопывание с потерями и это нормально: легаси-формат умеет ровно одну
+ * льготную категорию и ровно одну надбавочную. Берём первые — цена там, где
+ * есть `categories`, всё равно считается по ним.
+ */
+export declare const legacyFromCategories: (categories: TariffCategory[], price?: Record<string, number> | null) => {
+    childPrice: number | null;
+    childPriceDescription: string | null;
+    reducedRateMode: TariffReducedRateModeEnum | null;
+    reducedRate: number;
+    reducedTitle: string | null;
+    reducedPriceDescription: string | null;
+};
+/**
+ * Поля старого формата из состава по категориям. Нужны, пока их читают не
+ * обновлённые клиенты (мобильное приложение) и вся отчётность по броням.
+ *
+ * На тарифе с несколькими льготными категориями `reducedPlayers` схлопывает
+ * их в одно число: восстановить цену из легаси-полей в таком случае нельзя,
+ * источник истины — `composition` и снимок категорий на брони.
+ */
+export declare const legacyCountsFromComposition: (composition: OrderComposition | null | undefined, categories: TariffCategory[]) => {
+    players: number;
+    children: number;
+    reducedPlayers: number;
+};