uuid-cbr 0.0.2 → 0.1.0

package/README.md

@@ -1,33 +1,160 @@
 # UUID-CBR
 
-> Js библиотека для генирации uuid по требованию ЦБ
+> Генератор уникальных идентификаторов (УИд) по требованиям Банка России (Указание 5251-У, Положение 758-П)
 
-### Пример использования
+Реализация алгоритма формирования УИд на основе UUID v1 с контрольным символом, полностью соответствующая официальному примеру ЦБ на C.
 
-**_Генерация uuid_**
+### Установка
+
+```bash
+npm install uuid-cbr
+```
+
+### Форматы модуля
+
+Пакет публикуется сразу в двух вариантах:
+
+- `require("uuid-cbr")` для CommonJS
+- `import { generate } from "uuid-cbr"` для ESM
+- встроенные декларации `index.d.ts` для TypeScript
+
+```js
+const { generate } = require("uuid-cbr");
+```
+
+```js
+import { generate } from "uuid-cbr";
+```
+
+### API
+
+#### `generate(datetime?)`
+
+Формирует УИд — строку из 38 символов в формате `8-4-4-4-12-1`, где последний символ — контрольный.
 
 ```JavaScript
 const { generate } = require("uuid-cbr");
-const nowDatetime = new Date("2021-09-24T09:55:09.332Z")
-const uuidByDate = generate(nowDatetime)
-console.log(uuidByDate); // 80c57a90-1d1d-11ec-adda-26dbb65f1526-0
 
-const uuidNowDate = generate()
-console.log(uuidNowDate); // 3ce3d880-1d1e-11ec-b690-d07329e2e226-5
+const uid = generate(new Date("2021-09-24T09:55:09.332Z"));
+// 80c57a90-1d1d-11ec-adda-26dbb65f1526-0
+
+const uidNow = generate();
+// генерация для текущего момента
 ```
 
-**_Проверка валидации_**
+#### `isValid(uuid)`
+
+Проверяет строку: формат UUID v1, variant-биты, контрольный символ.
 
 ```JavaScript
 const { isValid } = require("uuid-cbr");
-const isValidUUID = isValid('3ce3d880-1d1e-11ec-b690-d07329e2e226-5')
-console.log(isValidUUID) //true
+
+isValid("80c57a90-1d1d-11ec-adda-26dbb65f1526-0"); // true
+isValid("not-a-uuid");                               // false
 ```
 
-**_Преобразование uuid к дате_**
+#### `toDate(uuid)`
+
+Извлекает дату из UUID-части идентификатора.
 
 ```JavaScript
 const { toDate } = require("uuid-cbr");
-const datetime = toDate('80c57a90-1d1d-11ec-adda-26dbb65f1526-0')
-console.log(datetime) //2021-09-24T09:55:09.332Z
-```
+
+toDate("80c57a90-1d1d-11ec-adda-26dbb65f1526-0");
+// 2021-09-24T09:55:09.332Z
+```
+
+#### `info(uuid)`
+
+Метаданные идентификатора: длина, валидность, контрольный символ, clock sequence, дата.
+
+```JavaScript
+const { info } = require("uuid-cbr");
+
+info("80c57a90-1d1d-11ec-adda-26dbb65f1526-0");
+// { len: 38, valid: true, controlNum: '0', gClockSeq: ..., datetime: 2021-09-24T09:55:09.332Z }
+```
+
+#### `getTime(datetime?)`
+
+Возвращает метку времени в 100-наносекундных интервалах (Number) — то же значение, которое кодируется в UUID.
+
+```JavaScript
+const { getTime } = require("uuid-cbr");
+
+getTime(new Date("2021-09-24T09:55:09.332Z"));
+```
+
+#### `uid_init(options?)` / `uid_deinit()`
+
+Lifecycle-управление генератором, аналог `uid_init` и `uid_deinit` из официального C-примера ЦБ.
+
+```JavaScript
+const { uid_init, uid_deinit, uid_create } = require("uuid-cbr");
+
+uid_init({
+  node: [0x10, 0x20, 0x30, 0x40, 0x50, 0x60],
+  clockSeq: 0x1234,
+});
+
+const uid = uid_create(new Date("2021-09-24T09:55:09.332Z"));
+uid_deinit();
+```
+
+`options`:
+
+- `node` — 6 байт (Buffer, Array или hex-строка). По умолчанию — случайные.
+- `clockSeq` — 13-битное значение clock sequence. По умолчанию — случайное.
+
+#### `uid_create(datetime?)` / `uuid_create(datetime?)`
+
+- `uid_create` — формирует УИд-строку (аналог `generate`).
+- `uuid_create` — возвращает структуру полей UUID: `time_low`, `time_mid`, `time_hi_and_version`, `clock_seq_hi_and_reserved`, `clock_seq_low`, `node`.
+
+`uuid_init` / `uuid_deinit` — алиасы для `uid_init` / `uid_deinit`.
+
+### Тесты
+
+```bash
+npm test
+```
+
+Тесты запускаются через встроенный раннер Node.js `node:test` и покрывают поведение публичного API как unit-тесты.
+
+### Сверка с официальным алгоритмом
+
+```bash
+npm run compare:official
+```
+
+Скрипт собирает УИд при детерминированных входных данных и побайтово сравнивает результат с эталонной реализацией, эквивалентной официальному C-коду ЦБ.
+
+### Проверка перед публикацией
+
+```bash
+npm run verify:publish
+```
+
+Эта команда последовательно выполняет:
+
+- unit-тесты;
+- сверку с официальным алгоритмом;
+- `npm pack --dry-run`, чтобы проверить состав публикуемого пакета.
+
+При `npm publish` эта проверка запускается автоматически через `prepublishOnly`.
+
+### Что попадает в npm
+
+В опубликованный пакет входят только файлы рантайма:
+
+- `index.js`
+- `index.mjs`
+- `index.d.ts`
+- `README.md`
+
+Тесты, служебные скрипты, локальные временные файлы и официальный reference-архив остаются в репозитории, но не публикуются в npm.
+
+### Официальные материалы
+
+- [docs/official/README.md](docs/official/README.md) — описание сохранённых документов
+- [docs/official/cbr-algorithm-findings.md](docs/official/cbr-algorithm-findings.md) — результаты сверки с официальным примером

package/index.d.ts

@@ -0,0 +1,55 @@
+/// <reference types="node" />
+
+export interface GeneratorOptions {
+  node?: Buffer | number[] | string;
+  clockSeq?: number;
+  lastTime?: bigint | number | string;
+  lastUSNS?: number;
+}
+
+export interface UuidStruct {
+  time_low: number;
+  time_mid: number;
+  time_hi_and_version: number;
+  clock_seq_hi_and_reserved: number;
+  clock_seq_low: number;
+  node: number[];
+}
+
+export interface UidInfo {
+  len: number;
+  valid: boolean;
+  controlNum: string | undefined;
+  gClockSeq: number;
+  datetime: Date;
+}
+
+export type DatetimeInput = Date | number | string;
+
+export function generate(datetime?: DatetimeInput): string;
+export function uid_init(options?: GeneratorOptions): boolean;
+export function uid_deinit(): void;
+export function uid_create(datetime?: DatetimeInput): string;
+export function uuid_init(options?: GeneratorOptions): boolean;
+export function uuid_deinit(): void;
+export function uuid_create(datetime?: DatetimeInput): UuidStruct;
+export function isValid(data: string): boolean;
+export function getTime(datetime?: DatetimeInput): number;
+export function toDate(uuid: string): Date;
+export function info(uuid: string): UidInfo;
+
+declare const api: {
+  generate: typeof generate;
+  uid_init: typeof uid_init;
+  uid_deinit: typeof uid_deinit;
+  uid_create: typeof uid_create;
+  uuid_init: typeof uuid_init;
+  uuid_deinit: typeof uuid_deinit;
+  uuid_create: typeof uuid_create;
+  isValid: typeof isValid;
+  getTime: typeof getTime;
+  toDate: typeof toDate;
+  info: typeof info;
+};
+
+export default api;

package/index.js

@@ -1,32 +1,89 @@
 const crypto = require("crypto");
-const winEpoch = new Date("01-01-1601 UTC").getTime();
+const WIN_EPOCH_MS = BigInt(Date.UTC(1601, 0, 1));
+const UUID_TIME_OFFSET = 5748192000000000n;
+const HUNDRED_NS_PER_MS = 10000n;
 
-const random = (min, max) => {
-  return Math.floor(Math.random() * (max - min + 1) + min);
+const UUID_WITH_CHECKSUM_REGEX =
+  /^([0-9a-f]{8})-([0-9a-f]{4})-([0-9a-f]{4})-([0-9a-f]{4})-([0-9a-f]{12})(?:-([0-9a-f]{1}))?$/i;
+
+const formatHex = (value, length) => value.toString(16).padStart(length, "0");
+
+const normalizeNode = (node) => {
+  if (Buffer.isBuffer(node)) {
+    return Buffer.from(node);
+  }
+
+  if (Array.isArray(node)) {
+    return Buffer.from(node);
+  }
+
+  if (typeof node === "string") {
+    return Buffer.from(node, "hex");
+  }
+
+  throw new TypeError("Invalid node");
 };
 
-let gLastUSNS = 0;
-let gLastTime = 0;
-let time = 0;
+const createState = (options = {}) => {
+  const node =
+    options.node === undefined
+      ? crypto.randomBytes(6)
+      : normalizeNode(options.node);
+  if (node.length !== 6) {
+    throw new RangeError("Node must be 6 bytes long");
+  }
+
+  node[5] |= 0x01;
 
-const getTime = (datetime) => {
-  do {
-    const winDate = (new Date(datetime).getTime() - winEpoch) * 10000;
-    time = winDate + 5748192000000000;
-  } while (time === gLastTime && gLastUSNS === 9999);
-
-  if (time === gLastTime) {
-    // Если время не изменилось, за микро- и наносекунды
-    // возьмем предыдущее значение плюс один
-    gLastUSNS++;
+  const clockSeq =
+    options.clockSeq === undefined
+      ? crypto.randomBytes(2).readUInt16LE(0) & 0x1fff
+      : Number(options.clockSeq) & 0x1fff;
+
+  return {
+    lastUSNS: options.lastUSNS === undefined ? 0 : Number(options.lastUSNS),
+    lastTime: options.lastTime === undefined ? 0n : BigInt(options.lastTime),
+    node,
+    nodeHex: Buffer.from(node).reverse().toString("hex"),
+    clockSeq,
+    clockSeqLow: clockSeq & 0xff,
+    clockSeqHiAndReserved: ((clockSeq & 0x3f00) >> 8) | 0x80,
+  };
+};
+
+let state = createState();
+
+const ensureState = () => {
+  if (!state) {
+    state = createState();
+  }
+
+  return state;
+};
+
+const getTimestamp100ns = (datetime) => {
+  const currentState = ensureState();
+  const date = new Date(datetime);
+  if (Number.isNaN(date.getTime())) {
+    throw new TypeError("Invalid datetime");
+  }
+
+  const currentTime =
+    (BigInt(date.getTime()) - WIN_EPOCH_MS) * HUNDRED_NS_PER_MS +
+    UUID_TIME_OFFSET;
+
+  if (currentTime === currentState.lastTime) {
+    currentState.lastUSNS++;
   } else {
-    // Если время изменилось, за микро- и наносекунды возьмём 0.
-    gLastUSNS = random(1, 10000);
-    // и запомним значение времени
-    gLastTime = time;
+    currentState.lastUSNS = 0;
+    currentState.lastTime = currentTime;
   }
-  time += gLastUSNS;
-  return time;
+
+  return currentTime + BigInt(currentState.lastUSNS);
+};
+
+const getTime = (datetime) => {
+  return Number(getTimestamp100ns(datetime));
 };
 
 const calcCtrl = (uuid) => {
@@ -34,114 +91,131 @@ const calcCtrl = (uuid) => {
   let index = 1;
   let sum = 0;
   while (uuid[pos]) {
-    const c = uuid[pos++];
-    // если символ - десятичная цифра
-    if (/\d/.test(c)) {
-      // увеличение суммы и индекса
-      sum += parseInt(c, 10) * index++;
+    const code = uuid.charCodeAt(pos++);
+
+    if (code >= 48 && code <= 57) {
+      sum += (code - 48) * index++;
+    } else {
+      const lowerCode = code | 32;
+      if (lowerCode >= 97 && lowerCode <= 102) {
+        sum += (lowerCode - 87) * index++;
+      }
     }
 
-    // если символ - шестнадцатеричная цифра
-    if (/[a-f]/i.test(c)) {
-      sum += parseInt(c, 16) * index++;
-    }
     // если значение индекса превысило 10, сбрасываем индекс в 1
     if (index > 10) index = 1;
   }
 
   const r = sum % 16;
-  // возврат результата в виде контрольного символа
-  if (r < 10) {
-    return r;
-  }
   return r.toString(16);
 };
 
 const isValid = (data) => {
-  const res = data.match(/^([0-9a-f]{8}-[0-9a-f]{4}-1[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12})-([0-9a-f]{1})$/);
+  if (typeof data !== "string") {
+    return false;
+  }
+
+  const res = data.match(
+    /^([0-9a-f]{8}-[0-9a-f]{4}-1[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12})-([0-9a-f]{1})$/,
+  );
   if (!res) return false;
   const [, uuid, cs] = res;
   if (!uuid && !cs) {
     return false;
   }
-  return calcCtrl(uuid) == cs;
+  return calcCtrl(uuid) === cs;
 };
 
-const bin2Hex = (bin) => {
-  const dec = parseInt(bin, 2);
-  const hex = dec.toString(16).padStart(4, "0");
-  return hex;
+const uuid_create = (datetime = new Date()) => {
+  const currentState = ensureState();
+  const timeValue = getTimestamp100ns(datetime);
+
+  return {
+    time_low: Number(timeValue & 0xffffffffn),
+    time_mid: Number((timeValue >> 32n) & 0xffffn),
+    time_hi_and_version: Number((timeValue >> 48n) & 0x0fffn) | (1 << 12),
+    clock_seq_hi_and_reserved: currentState.clockSeqHiAndReserved,
+    clock_seq_low: currentState.clockSeqLow,
+    node: Array.from(currentState.node),
+  };
 };
 
-const gClockSeq = Buffer.alloc(14, crypto.randomBytes(14).readUInt32BE(0, true).toString(2));
 const generate = (datetime = new Date()) => {
-  const gt = getTime(datetime);
+  const currentState = ensureState();
+  const uuid = uuid_create(datetime);
 
-  const buff = Buffer.alloc(57, gt.toString(2));
+  const result =
+    `${formatHex(uuid.time_low, 8)}-` +
+    `${formatHex(uuid.time_mid, 4)}-` +
+    `${formatHex(uuid.time_hi_and_version, 4)}-` +
+    `${formatHex(uuid.clock_seq_hi_and_reserved, 2)}${formatHex(uuid.clock_seq_low, 2)}-` +
+    currentState.nodeHex;
 
-  const version_time_hide = Buffer.from(buff.buffer, 0, 9); // Из-за смещения 3ех нулей беру 9 байт
+  return result + "-" + calcCtrl(result);
+};
 
-  const clockseq_low = Buffer.from(gClockSeq.buffer, 6);
-  const variant_clockseq_high = Buffer.from(gClockSeq.buffer, 0, 6);
+const uid_create = (datetime = new Date()) => generate(datetime);
 
-  const time_low = Buffer.from(buff.buffer, 25);
+const uid_init = (options = {}) => {
+  state = createState(options);
+  return true;
+};
 
-  const time_mid = Buffer.from(buff.buffer, 9, 16);
+const uid_deinit = () => {
+  state = null;
+};
 
-  const time = {
-    time_bin: buff + "",
-    time_low: time_low + "",
-    time_mid: (time_mid + "").padStart(16, "0"),
-    version_time_hide: "0001000" + version_time_hide,
-    clockseq_low: `10${variant_clockseq_high.toString("binary")}${clockseq_low.toString("binary")}`,
-  };
+const uuid_init = (options = {}) => uid_init(options);
 
-  const node = Buffer.alloc(6);
-  node[0] = crypto.randomBytes(4).readUInt32BE(0, true);
-  node[1] = crypto.randomBytes(4).readUInt32BE(0, true);
-  node[2] = crypto.randomBytes(4).readUInt32BE(0, true);
-  node[3] = crypto.randomBytes(4).readUInt32BE(0, true);
-  node[4] = crypto.randomBytes(4).readUInt32BE(0, true);
-  node[5] = crypto.randomBytes(4).readUInt32BE(0, true);
-  const result = [
-    bin2Hex(time.time_low).padStart(8, "0"),
-    bin2Hex(time.time_mid),
-    bin2Hex(time.version_time_hide),
-    bin2Hex(time.clockseq_low),
-    node.toString("hex"),
-  ].join("-");
-  return result + "-" + calcCtrl(result);
+const uuid_deinit = () => {
+  uid_deinit();
 };
 
 const toDate = (uuid) => {
-  const [, time_low, time_mid, version_time_hide] = uuid.match(/^([0-9a-f]{8})-([0-9a-f]{4})-([0-9a-f]{4})-([0-9a-f]{4})/);
+  if (typeof uuid !== "string") {
+    throw new TypeError("Invalid UUID");
+  }
 
-  const bin_version_time_hide = parseInt(version_time_hide, 16)
-    .toString(2)
-    .replace(/^1000(.+)/, "$1");
-  const bin_time_mid = parseInt(time_mid, 16).toString(2).padStart(16, "0");
-  const bin_time_low = parseInt(time_low, 16).toString(2).padStart(32, "0");
+  const match = uuid.match(UUID_WITH_CHECKSUM_REGEX);
+  if (!match) {
+    throw new TypeError("Invalid UUID");
+  }
 
-  const buff = Buffer.alloc(57, `${bin_version_time_hide}${bin_time_mid}${bin_time_low}`);
+  const [, timeLow, timeMid, timeHiAndVersion] = match;
+  const timestamp =
+    ((BigInt(`0x${timeHiAndVersion}`) & 0x0fffn) << 48n) |
+    (BigInt(`0x${timeMid}`) << 32n) |
+    BigInt(`0x${timeLow}`);
+  const dateMs =
+    (timestamp - UUID_TIME_OFFSET) / HUNDRED_NS_PER_MS + WIN_EPOCH_MS;
 
-  const nSec = parseInt(buff.toString("binary"), 2) - 5748192000000000;
-  return new Date(nSec / 10000 + winEpoch);
+  return new Date(Number(dateMs));
 };
 
 const info = (uuid) => {
+  if (typeof uuid !== "string") {
+    throw new TypeError("Invalid UUID");
+  }
+
   const controlNum = uuid.split("-")[5];
 
   return {
     len: uuid.length,
     valid: isValid(uuid),
     controlNum,
-    gClockSeq: parseInt(gClockSeq.toString("hex"), 16),
+    gClockSeq: ensureState().clockSeq,
     datetime: toDate(uuid),
   };
 };
 
 module.exports = {
   generate,
+  uid_init,
+  uid_deinit,
+  uid_create,
+  uuid_init,
+  uuid_deinit,
+  uuid_create,
   isValid,
   getTime,
   toDate,

package/index.mjs

@@ -0,0 +1,17 @@
+import cjsModule from "./index.js";
+
+export const {
+  generate,
+  uid_init,
+  uid_deinit,
+  uid_create,
+  uuid_init,
+  uuid_deinit,
+  uuid_create,
+  isValid,
+  getTime,
+  toDate,
+  info,
+} = cjsModule;
+
+export default cjsModule;

package/package.json

@@ -1,18 +1,41 @@
-{
-  "name": "uuid-cbr",
-  "version": "0.0.2",
-  "description": "Js библиотека для генирации uuid по требованию ЦБ",
-  "keywords": [
-    "uuid",
-    "ЦБ",
-    "cb",
-    "cbr"
-  ],
-  "main": "index.js",
-  "author": "kdinisv",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/kdinisv/uuid-cbr"
-  },
-  "license": "MIT"
-}
+{
+  "name": "uuid-cbr",
+  "version": "0.1.0",
+  "description": "Генератор уникальных идентификаторов (УИд) по требованиям Банка России",
+  "keywords": [
+    "uuid",
+    "ЦБ",
+    "cb",
+    "cbr"
+  ],
+  "main": "index.js",
+  "module": "index.mjs",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.mjs",
+      "require": "./index.js",
+      "default": "./index.js"
+    }
+  },
+  "files": [
+    "index.js",
+    "index.mjs",
+    "index.d.ts",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "author": "kdinisv",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kdinisv/uuid-cbr"
+  },
+  "license": "MIT",
+  "scripts": {
+    "test": "node --test test.js",
+    "compare:official": "node scripts/compare-official.js",
+    "verify:publish": "npm test && npm run compare:official && npm pack --dry-run",
+    "prepublishOnly": "npm run verify:publish"
+  }
+}

package/test.js

@@ -1,21 +0,0 @@
-const { generate, isValid, info, toDate } = require("./index.js");
-
-
-const nowDatetime = new Date("2021-09-24T09:55:09.332Z")
-
-const uuid = generate(nowDatetime)
-console.log(uuid)
-
-const isValidUUID = isValid(uuid)
-
-console.log(isValidUUID)
-
-const infoUUID = info(uuid)
-
-console.log(nowDatetime.toISOString(), infoUUID.datetime.toISOString())
-console.assert(nowDatetime.toISOString() === infoUUID.datetime.toISOString())
-
-
-const datetime = toDate('80c57a90-1d1d-11ec-adda-26dbb65f1526-0')
-
-console.log(datetime)