lvovich

You can install Lvovich via npm for use in Node.js or bundler-based frontend projects, or include it directly in the browser via CDN.

npm installation:

npm install lvovich

Browser installation (CDN):

<script src="https://cdn.jsdelivr.net/npm/lvovich/dist/lvovich.min.js"></script>
<script>
  var city = 'Москва';
  document.writeln('Найдено в ' + lvovich.cityIn(city) + '<br/>');
  document.writeln('Из ' + lvovich.cityFrom(city) + '<br/>');
  document.writeln('Еду в ' + lvovich.cityTo(city) + '<br/>');
</script>

Lvovich provides functions to inflect Russian city names into different grammatical cases. This works for most compound names like 'Санкт-Петербург' or 'Ростов-на-Дону'.

• cityIn(name: string, gender?: GenderStrT): string: Returns the city in the prepositional case (e.g., "in which city do you live?").
• cityFrom(name: string, gender?: GenderStrT): string: Returns the city in the genitive case (e.g., "from which city did you arrive?").
• cityTo(name: string): string: Returns the city in the accusative/directional case (e.g., "to which city are you heading?").

import { cityIn, cityFrom, cityTo } from 'lvovich';

cityIn('Санкт-Петербург'); // 'Санкт-Петербурге'
cityFrom('Санкт-Петербург'); // 'Санкт-Петербурга'
cityTo('Москва'); // 'Москву'

These types define the structure for passing person data to the API.

FioT (used in getGender):

type FioT = {
  first?: ?string,
  last?: ?string,
  middle?: ?string,
}

LvovichPersonT (used in incline):

type LvovichPersonT = {
  first?: ?string,
  last?: ?string,
  middle?: ?string,
  gender?: ?GenderStrT,
}

// FioT structure
{
  first: 'string',
  last: 'string',
  middle: 'string'
}

// LvovichPersonT structure
{
  first: 'string',
  last: 'string',
  middle: 'string',
  gender: 'male' | 'female' | 'androgynous' | null
}

If you only have a single part of a name, you can use the following functions to get the gender as a string ('male', 'female', or 'androgynous') or null:

• getFirstnameGender(str: string): Returns gender for a first name.
• getLastnameGender(str: string): Returns gender for a last name.
• getMiddlenameGender(str: string): Returns gender for a middle name (patronymic).

import { getFirstnameGender, getLastnameGender } from 'lvovich';

const firstGender = getFirstnameGender('Анна'); // 'female'
const lastGender = getLastnameGender('Петров'); // 'male'

Use these functions to transform city names into specific Russian grammatical cases for use in sentences.

Available functions:

• cityIn(name: string, gender?: GenderStrT): string - Returns the city in the Prepositional case (e.g., "In which city do you live?").
• cityFrom(name: string, gender?: GenderStrT): string - Returns the city in the Genitive case (e.g., "From which city did you arrive?").
• cityTo(name: string): string - Returns the city in the Accusative/Directional case (e.g., "To which city are you heading?").

Use getGender(fio) to determine the gender of a person based on their Full Name (FIO) structure. The function returns a string representation of the gender ('male', 'female', or 'androgynous') or null if it cannot be determined.

To use this, provide an object conforming to the FioT type, which can contain first, last, and middle name strings.

import { getGender } from 'lvovich';

const gender = getGender({
  first: 'Иван',
  last: 'Иванов',
  middle: 'Иванович'
}); // returns 'male'

Use these utility functions to normalize or convert grammatical case identifiers.

• getDeclensionConst(key): Converts a string (e.g., 'genitive') or a constant to a numeric DeclentionT constant. Returns null if invalid.
• getDeclensionStr(cnst): Converts a numeric DeclentionT constant to its string representation (e.g., 'genitive'). Returns null if invalid.

import { getDeclensionConst, getDeclensionStr, GENITIVE } from 'lvovich/src/inclineRules';

const constVal = getDeclensionConst('genitive'); // returns 2
const strVal = getDeclensionStr(GENITIVE);      // returns 'genitive'

Use the inclineFirstname, inclineLastname, or inclineMiddlename functions to inflect individual components of a Russian name. By default, these functions use the accusative declension. If the gender is not provided, the library attempts to infer it automatically using internal gender detection logic.

Parameters

• str: The name string to inflect.
• declension: The target case (type DeclentionStrT). Defaults to 'accusative'.
• gender: (Optional) The gender of the person (type GenderStrT). If omitted, it is inferred from the string.

import { inclineFirstname, inclineLastname, inclineMiddlename } from 'lvovich';

// Inflect a first name
inclineFirstname('Иван', 'genitive');

// Inflect a last name with explicit gender
inclineLastname('Иванов', 'dative', 'male');