Update README.md

Author: do-

README.md

@@ -1,7 +1,7 @@
 ![workflow](https://github.com/do-/node-ru-codes/actions/workflows/main.yml/badge.svg)
 ![Jest coverage](./badges/coverage-jest%20coverage.svg)
 
-[ru-codes](https://github.com/do-/node-ru-codes) - один из модулей node.js для проверки корректности ввода ИНН, КПП, ОГРН[ИП] и СНИЛС.
+[ru-codes](https://github.com/do-/node-ru-codes/wiki) - один из модулей node.js для проверки корректности ввода ИНН, КПП, ОГРН[ИП] и СНИЛС, а также для генерации таких кодов в автоматических тестах.
 
 Особенности:
 * итог проверки представлен не результатом функции (который в случае успеха всегда `undefined`), а объектом Error с дополнительными полями;
@@ -23,8 +23,12 @@ const {
     isOGRN13,
     isOGRN15,
     isSNILS,
-//  scalarProduct,
-//  digit,
+    randomINN10,
+    randomINN12,
+    randomKPP,
+    randomOGRN13,
+    randomOGRN15,
+    randomSNILS,
 } = require ('ru-codes')
 
 try {
@@ -40,22 +44,30 @@ catch (err) {
     case 'char':
       // err.value -- символ не попавший в интервал '0'..'9'
       // err.pos -- позиция этого символа (от 0)
+    case 'format':
+      // err.pos -- позиция проблемного символа (для формата СНИЛС)
     case 'checksum': 
       // err.tobe -- контрольная сумма, вычисленная по основной части строки
       // err.asis -- значение контрольной суммы, прочитанное непосредственно из строки
-      // err.phase -- для isINN12: номер контрольной суммы (1 или 2) 
     default:
       throw err
   }
 }
+
+const testINN10 = randomINN10 ()
+const testINN12 = randomINN12 ()
+const testKPP = randomKPP ()
+const testOGRN13 = randomOGRN13 ()
+const testOGRN15 = randomOGRN15 ()
+const testSNILS = randomSNILS (/*{format: true}*/)
 ```
 # API
-## Основные функции
-Каждая из функций, описанных в данном разделе, принимает на вход проверяемый код в виде строки (не числа или иного объекта), состоящей только из цифр от '0' до '9'. Если проверка проходит успешно, исполнение функции завершается без результата, иначе генерируется ошибка.
+## Функции проверки
+Каждая из функций `isXXXX`, описанных в данном разделе, принимает на вход проверяемый код в виде строки (не числа или иного объекта), состоящей только из цифр от '0' до '9'. Исключение составляет `isSNILS`, допускающая значения формата "XXX-XXX-XXX YY"..
 
-Реализованы только проверки форматов и контрольных сумм, но не чего-либо, связанного с внешними источниками данных (наборы кодов регионов, отделений ФНС, ЕГРЮЛ и т. п.)
+Если проверка проходит успешно, функция `isXXXX` возвращает `undefined`, иначе генерируется ошибка с дополнительными полями `code`, `type`, `tobe`, `asis`, `value` и `pos` — подробнее см. комментарии в примере выше.
 
-Реализованы все проверки через вызовы нижеописанных `scalarProduct` и `digit`.
+Реализованы только проверки форматов и контрольных сумм, но не чего-либо, связанного с внешними источниками данных (наборы кодов регионов, отделений ФНС, ЕГРЮЛ и т. п.)
 
 ### isINN10
 Проверяет, может ли аргумент быть [ИНН](https://ru.wikipedia.org/wiki/%D0%98%D0%B4%D0%B5%D0%BD%D1%82%D0%B8%D1%84%D0%B8%D0%BA%D0%B0%D1%86%D0%B8%D0%BE%D0%BD%D0%BD%D1%8B%D0%B9_%D0%BD%D0%BE%D0%BC%D0%B5%D1%80_%D0%BD%D0%B0%D0%BB%D0%BE%D0%B3%D0%BE%D0%BF%D0%BB%D0%B0%D1%82%D0%B5%D0%BB%D1%8C%D1%89%D0%B8%D0%BA%D0%B0) юридического лица.
@@ -73,21 +85,29 @@ catch (err) {
 Проверяет, может ли аргумент быть [ОГРНИП](https://ru.wikipedia.org/wiki/%D0%9E%D1%81%D0%BD%D0%BE%D0%B2%D0%BD%D0%BE%D0%B9_%D0%B3%D0%BE%D1%81%D1%83%D0%B4%D0%B0%D1%80%D1%81%D1%82%D0%B2%D0%B5%D0%BD%D0%BD%D1%8B%D0%B9_%D1%80%D0%B5%D0%B3%D0%B8%D1%81%D1%82%D1%80%D0%B0%D1%86%D0%B8%D0%BE%D0%BD%D0%BD%D1%8B%D0%B9_%D0%BD%D0%BE%D0%BC%D0%B5%D1%80_%D0%B8%D0%BD%D0%B4%D0%B8%D0%B2%D0%B8%D0%B4%D1%83%D0%B0%D0%BB%D1%8C%D0%BD%D0%BE%D0%B3%D0%BE_%D0%BF%D1%80%D0%B5%D0%B4%D0%BF%D1%80%D0%B8%D0%BD%D0%B8%D0%BC%D0%B0%D1%82%D0%B5%D0%BB%D1%8F).
 
 ### isSNILS
-Проверяет, может ли аргумент быть [СНИЛС](https://ru.wikipedia.org/wiki/%D0%A1%D1%82%D1%80%D0%B0%D1%85%D0%BE%D0%B2%D0%BE%D0%B9_%D0%BD%D0%BE%D0%BC%D0%B5%D1%80_%D0%B8%D0%BD%D0%B4%D0%B8%D0%B2%D0%B8%D0%B4%D1%83%D0%B0%D0%BB%D1%8C%D0%BD%D0%BE%D0%B3%D0%BE_%D0%BB%D0%B8%D1%86%D0%B5%D0%B2%D0%BE%D0%B3%D0%BE_%D1%81%D1%87%D1%91%D1%82%D0%B0). Как и в остальных функциях `is...`, на вход должна подаваться строка только из цифр, без дополнительных символов форматирования.
+Проверяет, может ли аргумент быть [СНИЛС](https://ru.wikipedia.org/wiki/%D0%A1%D1%82%D1%80%D0%B0%D1%85%D0%BE%D0%B2%D0%BE%D0%B9_%D0%BD%D0%BE%D0%BC%D0%B5%D1%80_%D0%B8%D0%BD%D0%B4%D0%B8%D0%B2%D0%B8%D0%B4%D1%83%D0%B0%D0%BB%D1%8C%D0%BD%D0%BE%D0%B3%D0%BE_%D0%BB%D0%B8%D1%86%D0%B5%D0%B2%D0%BE%D0%B3%D0%BE_%D1%81%D1%87%D1%91%D1%82%D0%B0). 
+
+Аргумент может быть либо в формате "XXX-XXX-XXX YY", либо только цифры.
+
+## Генераторы случайных значений
+Каждая из функций `randomXXXX`, описанных в данном разделе, возвращает случайную строку соответствующего формата с корректной контрольной суммой (кроме КПП, для которого контроль не определён).
+
+### randomINN10
+Генерирует случайный [ИНН](https://ru.wikipedia.org/wiki/%D0%98%D0%B4%D0%B5%D0%BD%D1%82%D0%B8%D1%84%D0%B8%D0%BA%D0%B0%D1%86%D0%B8%D0%BE%D0%BD%D0%BD%D1%8B%D0%B9_%D0%BD%D0%BE%D0%BC%D0%B5%D1%80_%D0%BD%D0%B0%D0%BB%D0%BE%D0%B3%D0%BE%D0%BF%D0%BB%D0%B0%D1%82%D0%B5%D0%BB%D1%8C%D1%89%D0%B8%D0%BA%D0%B0) юридического лица.
+
+### randomINN12
+Генерирует случайный [ИНН](https://ru.wikipedia.org/wiki/%D0%98%D0%B4%D0%B5%D0%BD%D1%82%D0%B8%D1%84%D0%B8%D0%BA%D0%B0%D1%86%D0%B8%D0%BE%D0%BD%D0%BD%D1%8B%D0%B9_%D0%BD%D0%BE%D0%BC%D0%B5%D1%80_%D0%BD%D0%B0%D0%BB%D0%BE%D0%B3%D0%BE%D0%BF%D0%BB%D0%B0%D1%82%D0%B5%D0%BB%D1%8C%D1%89%D0%B8%D0%BA%D0%B0) физического лица.
 
-## Вспомогательные функции
-### digit
-Для заданной строки `str`, состоящей из только из цифр, и номера позиции `pos` возвращает число, соответствующее цифре, занимающей данную позицию (без создания промежуточной подстроки и вызова `parseInt`).
+### randomKPP
+Генерирует случайный [КПП](https://ru.wikipedia.org/wiki/%D0%98%D0%B4%D0%B5%D0%BD%D1%82%D0%B8%D1%84%D0%B8%D0%BA%D0%B0%D1%86%D0%B8%D0%BE%D0%BD%D0%BD%D1%8B%D0%B9_%D0%BD%D0%BE%D0%BC%D0%B5%D1%80_%D0%BD%D0%B0%D0%BB%D0%BE%D0%B3%D0%BE%D0%BF%D0%BB%D0%B0%D1%82%D0%B5%D0%BB%D1%8C%D1%89%D0%B8%D0%BA%D0%B0#%D0%9A%D0%BE%D0%B4_%D0%BF%D1%80%D0%B8%D1%87%D0%B8%D0%BD%D1%8B_%D0%BF%D0%BE%D1%81%D1%82%D0%B0%D0%BD%D0%BE%D0%B2%D0%BA%D0%B8_%D0%BD%D0%B0_%D1%83%D1%87%D1%91%D1%82_(%D0%9A%D0%9F%D0%9F)).
 
-Используется функциями `is...` для чтения контрольных чисел.
+### randomOGRN13
+Генерирует случайный [ОГРН](https://ru.wikipedia.org/wiki/%D0%9E%D1%81%D0%BD%D0%BE%D0%B2%D0%BD%D0%BE%D0%B9_%D0%B3%D0%BE%D1%81%D1%83%D0%B4%D0%B0%D1%80%D1%81%D1%82%D0%B2%D0%B5%D0%BD%D0%BD%D1%8B%D0%B9_%D1%80%D0%B5%D0%B3%D0%B8%D1%81%D1%82%D1%80%D0%B0%D1%86%D0%B8%D0%BE%D0%BD%D0%BD%D1%8B%D0%B9_%D0%BD%D0%BE%D0%BC%D0%B5%D1%80).
 
-### scalarProduct
-Для заданного массива чисел `coef` и строки `str`:
-* гарантирует, что `str` является строкой такой же длины, что `coef`, и состоящей только из цифр;
-* возвращает скалярное произведение `coef` на массив чисел, соответствующих отдельным цифрам `str`.
+### randomOGRN15
+Генерирует случайный [ОГРНИП](https://ru.wikipedia.org/wiki/%D0%9E%D1%81%D0%BD%D0%BE%D0%B2%D0%BD%D0%BE%D0%B9_%D0%B3%D0%BE%D1%81%D1%83%D0%B4%D0%B0%D1%80%D1%81%D1%82%D0%B2%D0%B5%D0%BD%D0%BD%D1%8B%D0%B9_%D1%80%D0%B5%D0%B3%D0%B8%D1%81%D1%82%D1%80%D0%B0%D1%86%D0%B8%D0%BE%D0%BD%D0%BD%D1%8B%D0%B9_%D0%BD%D0%BE%D0%BC%D0%B5%D1%80_%D0%B8%D0%BD%D0%B4%D0%B8%D0%B2%D0%B8%D0%B4%D1%83%D0%B0%D0%BB%D1%8C%D0%BD%D0%BE%D0%B3%D0%BE_%D0%BF%D1%80%D0%B5%D0%B4%D0%BF%D1%80%D0%B8%D0%BD%D0%B8%D0%BC%D0%B0%D1%82%D0%B5%D0%BB%D1%8F).
 
-На старте `str` преобразуется в [буфер](https://nodejs.org/dist/latest/docs/api/buffer.html) -- и это единственный объект, создаваемый по ходу неаварийного исполнения функции: все остальные операции -- числовые.
+### randomSNILS
+Генерирует случайный [СНИЛС](https://ru.wikipedia.org/wiki/%D0%A1%D1%82%D1%80%D0%B0%D1%85%D0%BE%D0%B2%D0%BE%D0%B9_%D0%BD%D0%BE%D0%BC%D0%B5%D1%80_%D0%B8%D0%BD%D0%B4%D0%B8%D0%B2%D0%B8%D0%B4%D1%83%D0%B0%D0%BB%D1%8C%D0%BD%D0%BE%D0%B3%D0%BE_%D0%BB%D0%B8%D1%86%D0%B5%D0%B2%D0%BE%D0%B3%D0%BE_%D1%81%D1%87%D1%91%D1%82%D0%B0). 
 
-Используется функциями `is...` для:
-* общей проверки формата;
-* одновременного вычисления контрольных сумм.
+При вызове `randomSNILS ({format: true})` результат будет отформатирован, иначе — только цифры.