ДотНот - Геттер и сеттер по точечной нотации

RU | EN

ДотНот (не путать с .NET) - это JavaScript-библиотека, призванная облегчить доступ к глубоко вложенным свойствам объектов, используя для этого точечную нотацию. Библиотека полностью совместима с Node.js и браузерами. Производительность оптимизирована для v8, но на других движках код тоже должен работать довольно быстро.

Идея в следующем:

// Подключаем библиотеку удобным способом
const { get } = await import('https://unpkg.com/@withinnode/[email protected]/lib/index.js');

// Получаем значение приоритетного языка браузера
get(window, 'navigator.languages[0]'); // ru

Установка

Поставляемый пакет не имеет рантайм-зависимостей, поэтому для использования в продакшене рекомендуется устанавливать его без зависимостей для разработки:

npm install --omit=dev @withinnode/dotnot

Если же вы планируете запускать бенчмарки для самостоятельной проверки производительности, то вам понадобится установить пакет со всеми зависимостями:

npm install @withinnode/dotnot

Использование

ДотНот поддерживает два формата путей: стандартный для JavaScript синтаксис property accessors с точками и квадратными скобками, и синтаксис, состоящий только из точек.

// Можно импортировать get или set отдельно или вместе
import { get, set } from 'dotnot';

// Объект для примера
const obj = {
  foo: {
    bar: ['baz', { qux: 42 }]
  }
};

// Получаем значения, используя стандартный синтаксис
get(obj, 'foo.bar[0]'); // baz
get(obj, 'foo.bar[1].qux'); // 42

// Устанавливаем новые значения свойствам
set(obj, 'foo.bar[0]', 'zab');
set(obj, 'foo.bar[1].qux', 24);

// Получаем значения используя синтаксис только с точками
get(obj, 'foo.bar.0'); // zab
get(obj, 'foo.bar.1.qux'); // 24

API

ES Module

Модуль dotnot содержит два именованных экспорта - get и set, а так же экспорт по умолчанию default в виде объекта с этими свойствами.

Использование импорта по умолчанию:

import dotnot from 'dotnot';

// dotnot.get()
// dotnot.set()

Использование импорта по именам:

import { get, set } from 'dotnot';

// get()
// set()

get(obj: object, path: string, defaultValue?: any): any

Функция get - это геттер, который используется для получения значения свойства объекта по пути к этому свойству.

Аргументы:

• obj: object - Целевой объект
• path: string - Путь к свойству
• defaultValue: any - Значение, возвращаемое, если запрошенное свойство не установлено

Возвращает:

• Значение найденного свойства или значение по умолчанию (если передано) или undefined, если свойство не было найдено.

set(obj: object, path: string, value: any): object

Функция set - это сеттер, который используется для присвоения свойству объекта значения по пути к этому свойству.

Аргументы:

• obj: object - Целевой объект
• path: string - Путь к свойству
• value: any - Новое значение

Возвращает:

• Сссылку на переданный объект, который был изменен, или undefined, если свойство не было найдено.

Производительность

Для получения репрезентативных бенчмарков, при сравнении используются только пакеты, которые поддерживают полный синтаксис JS-аксессоров с точками для свойств объектов и квадратными скобками для индексов массивов. Синтаксис только с точками не является приоритетным для этой библиотеки, не смотря на то, что он может быть написан значительно производительнее.

Сравнение с основными конкурентами:

Benchmarking getters...
dotnot/get x 1,616,082 ops/sec ±0.17% (99 runs sampled)
lodash.get x 414,361 ops/sec ±0.10% (98 runs sampled)
dot-prop/getProperty x 385,361 ops/sec ±0.17% (98 runs sampled)
dot-object/pick x 528,419 ops/sec ±0.09% (94 runs sampled)
resolve-dotstringkey x 377,465 ops/sec ±0.37% (98 runs sampled)
keypather/get x 185,867 ops/sec ±0.10% (97 runs sampled)
mpath/get x 564,499 ops/sec ±0.14% (95 runs sampled)
Fastest is dotnot/get

Benchmarking setters...
dotnot/set x 1,338,293 ops/sec ±0.13% (97 runs sampled)
lodash.set x 348,360 ops/sec ±0.43% (96 runs sampled)
dot-prop/SetProperty x 408,039 ops/sec ±0.07% (99 runs sampled)
keypather/set x 179,563 ops/sec ±0.33% (99 runs sampled)
mpath/set x 546,170 ops/sec ±0.08% (95 runs sampled)
Fastest is dotnot/set

Стоит заметить, что в этих бенчмарках на функции get и set из библиотеки lodash наложены патчи, которые отключают мемоизацию результатов path resolver'а, т.к. нам абсолютно неинтересно тестировать производительность кеша. Если же вам по каким-то причинам это интересно, то вот результаты бенчмарков, где ДотНоту добавлена мемоизация из lodash:

Benchmarking getters...
dotnot/get x 9,821,512 ops/sec ±0.14% (97 runs sampled)
lodash.get x 5,354,197 ops/sec ±0.56% (96 runs sampled)
Fastest is dotnot/get

Benchmarking setters...
dotnot/set x 4,363,587 ops/sec ±0.25% (98 runs sampled)
lodash.set x 2,021,528 ops/sec ±0.26% (98 runs sampled)
Fastest is dotnot/get

Почему ДотНот все равно в два раза быстрее? Потому что помимо логики разрешения пути требуется выполнить еще получение свойств, и, хотя для этого нужен всего один цикл, но он все равно оптимизирован лучше в ДотНот.

Разработка

Код данной библиотеки написан с упором на производительность при исполнении движком v8, который поставляется с Node.js по умолчанию. При оптимизации активно использовался анализ байткода и ассемблерных инструкций, генерируемых интерпретатором и компиляторами v8 для платформы x86-64. Другие движки и платформы в настоящий момент не являются значимыми для проекта и целенаправленно оптимизация для них при разработке не проводится.

Лицензия

Это программное обеспечение распространяется под лицензией MIT и может свободно использоваться в личных или коммерческих проектах.