Installation

Plain JS

<script src="RussianNouns.min.js"></script>

or (in a module)

import 'RussianNouns.min.js';

or (in a Worker)

importScripts('RussianNouns.min.js');

Bundlers, backend

npm i --save russian-nouns-js

const RussianNouns = require('russian-nouns-js');

Usage

The basics

const rne = new RussianNouns.Engine();

// Grammatical gender is a sort of noun class, related primarily to their sound.
// Although mostly native speakers just remember them.

const Gender = RussianNouns.Gender;
const Case = RussianNouns.Case;


rne.decline({text: 'имя', gender: Gender.NEUTER}, Case.GENITIVE);
// ◂ [ "имени" ]

rne.decline({text: 'имя', gender: Gender.NEUTER}, Case.INSTRUMENTAL);
// ◂ [ "именем" ]

// In these lines, each `decline` call implicitly creates a `Lemma`.
// When processing the same lemma multiple times, it is much faster
// to create it yourself once.

// A number of loan words are not declined.
// You should explicitly state this to prevent inflection.

let coat = RussianNouns.Lemma.create({
    text: 'пальто',
    gender: Gender.NEUTER,
    indeclinable: true
});

rne.decline(coat, Case.GENITIVE);
// ◂ [ "пальто" ]

RussianNouns.getDeclension(coat);
// ◂ -1


// Cases can be specified not only by name, but also by index.
// There is a list of cases: NOM, GEN, DAT, ACC, INS, PREP.
// And there is also the locative case as the seventh.
// It usually matches the prepositional one.

let mountain = RussianNouns.Lemma.create({
    text: 'гора',
    gender: Gender.FEMININE
});

RussianNouns.CASES.map(c => {
    return rne.decline(mountain, c);
});

// ◂ [
//     ["гора"]
//     ["горы"]
//     ["горе"]
//     ["гору"]
//     ["горой", "горою"]
//     ["горе"],
//     ["горе"]
// ]


// This is how you can get a plural form in the nominative case.

rne.pluralize(mountain);
// ◂ [ "горы" ]


// When you have the plural form in the nominative case, pass it
// as the third argument of the decline function to decline in plural.

RussianNouns.CASES.map(c => {
    return rne.decline(mountain, c, 'горы');
});

// ◂ [ 
//     [ 'горы' ]
//     [ 'гор' ]
//     [ 'горам' ]
//     [ 'горы' ]
//     [ 'горами' ]
//     [ 'горах' ]
//     [ 'горах' ]
// ]


// For words that are used only in plural, the original form
// of the word is the plural form in the nominative case.
// You should also explicitly state this.
// The concept of grammatical gender doesn't make sense for such words.

let scissors = RussianNouns.Lemma.create({
    text: 'ножницы',
    pluraleTantum: true
});

rne.pluralize(scissors);
// ◂ [ 'ножницы' ]

RussianNouns.CASES.map(c => {
    return rne.decline(scissors, c);
});

// ◂ [
//     [ 'ножницы' ]
//     [ 'ножниц' ]
//     [ 'ножницам' ]
//     [ 'ножницы' ]
//     [ 'ножницами' ]
//     [ 'ножницах' ]
//     [ 'ножницах' ] 
// ]

A complex example

const Gender = RussianNouns.Gender;
const Lemma = RussianNouns.Lemma;

const rne = new RussianNouns.Engine();

function sg(lemma, caseNumber) {
    const c = RussianNouns.CASES[caseNumber - 1];
    return rne.decline(lemma, c)[0];
}

function pl(lemma, caseNumber) {
    const c = RussianNouns.CASES[caseNumber - 1];
    const pluralForm = rne.pluralize(lemma)[0];
    return rne.decline(lemma, c, pluralForm)[0];
}

function cap(str) {
    return str[0].toUpperCase() + str.substring(1);
}


// Николай Степанович Гумилев
// Рассказ девушки (фрагмент)

const ворота = Lemma.create({text: 'ворота', pluraleTantum: true});
const тень = Lemma.create({text: 'тень', gender: Gender.FEMININE});
const снег = Lemma.create({text: 'снег', gender: Gender.MASCULINE});

const милая = Lemma.create({text: 'милая', gender: Gender.FEMININE});
const старая = Lemma.create({text: 'старая', gender: Gender.FEMININE});
const ель = Lemma.create({text: 'ель', gender: Gender.FEMININE});

const неведомая = Lemma.create({text: 'неведомая', gender: Gender.FEMININE});
const высота = Lemma.create({text: 'высота', gender: Gender.FEMININE});

console.log(`* * *
Я отдыхала у ${pl(ворота, 2)}
Под ${sg(тень, 5)} ${sg(милая, 2)}, ${sg(старая, 2)} ${sg(ель, 2)},
А надо мною пламенели
${cap(pl(снег, 1))} ${pl(неведомая, 2)} ${pl(высота, 2)}.`);

// * * *
// Я отдыхала у ворот
// Под тенью милой, старой ели,
// А надо мною пламенели
// Снега неведомых высот.

Limitations

This library does not prevent you from misusing singularia tantum.

References

• Современный русский язык. Морфология - Камынина А.А., Уч. пос. 1999 - 240 с.
• Russian grammar (English Wikipedia)
• OpenCorpora (Russian text corpus)
• К семантике русского локатива ("второго предложного" падежа) - Плунгян В. А., Семиотика и информатика. - Вып. 37. - М., 2002. - С. 229-254