Восстановление типов JSON

Для транспорта данных я почти всегда упаковываю их в JSON. Но вот беда: как правило, библиотеки для парсинга возвращают примитивные типы и объекты с массивами — всё то, что заложено самим форматом. Но что если хочется получить модели сущностей?

Нравится мне порой понаделать своего, даже если кто-то уже сделал что-то похожее. Ничего не могу с собою поделать. В повседневной работе с JavaScript я связан не слишком тесно, но для домашних проектов применяю часто: пишу на нём бэк и фронт, потому что уж слишком привлекает единая кодовая база. Чёрт с ней — с той производительностью, — раз это для развлечения. Зато какая ж красота!

// код упрощён для демонстрации
class Folder {
    constructor(data) {
        this.dir = data.dir;
        this.caption = data.caption;
        this.collectTime = data.collectTime;
        this.metaThumbnail = data.metaThumbnail;
        this.extras = data.extras;
    }
    
    get parentDir() {
        return this.dir.replace(/\/?[^\/]+$/, '');
    }
    
    static fromDirent(dirent) {
        return new this(/* ... */);
    }
    
    // не относящиеся к содержанию статьи методы
}

// признаю, название ужасное
class AContainer {
    constructor(data) {
        this.file = data.file;
        this.files = data.files; // остальные картинки из серии burst
        this.parentDir = data.parentDir;
        this.collectTime = data.collectTime;
        this.metaTime = data.metaTime;
        this.metaLat = data.metaLat;
        this.metaLon = data.metaLon;
        this.metaThumbnail = data.metaThumbnail;
        this.extras = data.extras;
    }
    
    static async checkFile(dirent) {
        throw new Error("Method 'checkFile' is abstract");
    }
}

async function collectDir(dir = '~') {
    const contClasses = [
        // order of appearence is important!
        ImageGif,
        ImageBurst,
        ImagePano,
        ImageBasic,
        VideoSlowmo,
        VideoTimelapse,
        VideoBasic,
    ];
    const dirents = await fsPromises.readdir(dir, { withFileTypes: true });
    const folders = [];
    const containers = [];
    for (const dirent of dirents) {
        if (dirent.isDirectory()) {
            folders.push(Folder.fromDirent(dirent));
        }
        else {
            let container;
            // последовательные проверки файла
            // всеми типами контейнеров:
            for (const contClass of contClasses) {
                container = contClass.checkFile(dirent);
                if (container) {
                    containers.push(container);
                    break;
                }
            }
            if (!container) {
                console.warn(`Unable to detect media format`, dirent);
            }
        }
    }
}

async function getFolder(dir) {
    dir = dir.replace(/[\/\\]+$/, '');
    
    const resFolder = await db.queryOne(`
        SELECT * from Folder where dir = ?
    `, [dir], models.Folder);
    if (!resFolder) {
        throw new Error(`Unknown Folder: ${dir}`);
    }
    
    resFolder.childContainers = await db.query(`
        SELECT * from Container where parentDir = ?
    `, [dir], models.AContainer);
    
    resFolder.childFolders = await db.query(`
        SELECT * from Folder where parentDir = ?
    `, [dir], models.Folder);
    
    return resFolder;
}

Из браузера дергаем API-метод и получаем с бэка сырые JS-объекты. А хочется классов моделей. Ещё и типы контейнеров потерялись. Как же быть?

Объект класса в JSON

На всякий случай поведаю, что стандартный сериализатор JSON в JavaScript умеет не только вызывать функцию-replacer для каждого значения, но и искать у объектов метод toJSON. Это позволяет до неузнаваемости обработать объект перед упаковкой. При этом реализация такой обработки будет на месте — в описании класса (а вот и нет, а вот и не всегда). Для некоторых стандартных типов есть такие реализации на уровне движка JS (например, для Date).

С классом Folder всё просто — там ничего особого не требуется. А вот для контейнеров нужно сохранить информацию о типе. Предлагаю просто:

class AContainer {
    // ...
    
    toJSON() {
        const res = {};
        Object.assign(res, this);
        // и классы-наследники тут всё сделают правильно:
        res.containerType = this.constructor.name;
        return this;
    }
}

Будь желание, можно было бы даже вложить один объект в другой, чтобы не было кисло из-за возможного конфликта имени свойства containerType. Но это уже для гурманов.

JSON в объект нужного класса

Предварительные ласки кончились. Нужно развернуть JSON как-то так, чтобы вместо сырых объектов получить сухие хрустящие экземпляры нужных классов. И топорная ручная обработка — не наш метод. Мне пригянулся подход к вопросу в Golang. Ну и потом, раз уж мы уже увидели, что «волшебные» методы вроде toJSON не порицаются, то почему бы не пойти дальше.

Договор будет следующим: если для класса описан статичный метод fromJSON, то будем его вызывать сразу после преобразования JSON во внутреннее представление (сырые объекты, массивы и примитивы), но перед выдачей результата обработки. Если же метода нет, то будем просто пробрасывать значение в качестве единственного аргумента конструктора.

Ещё один договор с самим собой будет таким: каждый класс, который расширяет AContainer, будет этому самому AContainer сообщать о своём существовании (это в рамках исходного проекта, который про фоточки).

class AContainer {
    // ...
    
    static implementations = {};
    
    static registerImplementation(implementationClass) {
        this.implementations[implementationClass.name] = implementationClass;
    }
    
    static fromJSON(data) {
        // нужно распаковать даты:
        data.collectTime = new Date(data.collectTime);
        data.metaTime = new Date(data.metaTime);
        
        // код курильщика:
        /*
        switch (data.containerType) {
            case 'ImageBasic': return new ImageBasic(data);
            case 'ImageBurst': return new ImageBurst(data);
            // ...
            case 'VideoTimelapse': return new VideoTimelapse(data);
        }
        */
        
        // код вейпера:
        const contClass = this.implementations[data.containerType];
        if (contClass) {
            return new contClass(data);
        }
        
        throw new Error(`Unknown container type: ${data.containerType}`);
    }
}


class ImageBasic extends AContainer { /*...*/ }
AContainer.registerImplementation(ImageBasic);


class ImageBurst extends AContainer { /*...*/ }
AContainer.registerImplementation(ImageBurst);


class VideoTimelapse extends AContainer { /*...*/ }
AContainer.registerImplementation(VideoTimelapse);

Выглядит неплохо. А как же вызывать этот fromJSON? Плясал я вокруг reviver-функции, но каши не сварил. Хотел как-то хитро её генерировать, передавать в JSON.parse(data, <сюда>), но с нею нереально работать, когда речь идёт о произвольных объектах переменной вложенности. Что же, значит будем парсить как есть, а потом делать пост-обработку результата.

Пора бы сделать что-то типа модуля. Пусть называется JSONSchema JSONSon.

JSONSon

Прикинул, как бы мне хотелось этим пользоваться:

JSONSon.parse(Folder, '{...}');
    // object<Folder>

JSONSon.parse(AContainer, '{...}');
    // object<? extends AContainer>

JSONSon.parse(Date, '"2022-02-08T21:15:56.180Z"');
    // object<Date>

JSONSon.parse('string', '"2022-02-08T21:15:56.180Z"');
    // "2022-02-08T21:15:56.180Z"

// и остановиться я уже не мог:
JSONSon.parse('number', '"2022-02-08T21:15:56.180Z"');
    // NaN
JSONSon.parse('number', '"2022"');
    // 2022
JSONSon.parse('boolean', '"2022"');
    // true
JSONSon.parse('boolean', '""');
    // false
JSONSon.parse('bigint', '"2022"');
    // 2022n
JSONSon.parse(Number, '"2022"');
    // object<Number> {2022}
JSONSon.parse(['number'], '[1, "2", 3, 4]');
    // [1, 2, 3, 4]
JSONSon.parse(['boolean', 'number', 'string'], '[1, "2", 3, 4]');
    // [true, 2, "3", "4"] - discover tuple in JS!
JSONSon.parse({ foo: Folder, bar: [AContainer] }, '{...}');
    // { foo: object<Folder>, bar: [object<? extends AContainer>] }

Пришлось писать. Сделал простой симметричный обход структур с конвертацией типов, парой проверок — и готово. Надо сказать, что привязки к JSON уже как бы и не осталось: JSON-ом данные были на предыдущем этапе — до его обработки, а нужная функция будет делать пост-обработку уже разобранных данных. Но так как схема двунаправленная (данные ↔ JSON), и я уже повязан с функцией toJSON, то пусть она таки будет с ним связана.

Объекты с необъявленными свойствами

Напомню, что апишный метод getFolder возвращает экземпляр класса Folder, но с дополнительными посторонними свойствами:

await serverApi.getFolder('~/Pictures'); -> {
    // объявленные свойства (те, о которых класс знает):
    dir: '~/Pictures',
    caption: 'Pictures',
    collectTime: '2022-02-08T21:15:56.180Z',
    metaThumbnail: 'data:image/jpeg;base64,...',
    extras: null,
    
    // посторонние свойства:
    childContainers: [{...}, {...}],
    childFolders: [{...}, {...}]
}

Конечно, было бы правильно их просто «объявить». Но я же тут занимаюсь целой парсилкой-конвертором-типов, а не каким-то там... с чего я вообще начинал? Короче, интереснее поискать ещё какое-то решение, потому что как ни крути, а в JS такие ситуации не редки. Нужно как-то обернуть класс, и вдобавок сообщить, какие ещё ожидаются посторонние свойства. А при обработке следует сначала преобразовать в экземпляр нужного класса, после чего отдельно пройтись по дополнительным свойствам. Вот, как представилось применение:

JSONSon.parse(JSONSon.mix(Folder, {
    childContainers: [AContainer],
    childFolders: [Folder],
}), jsonData);

Клюка для BigInt

Не проверял, как обстоят дела в других клиентах, но в Chrome 97 вы удивитесь, если захотите упаковать BigInt в JSON:

JSON.stringify(9007199254740993n);
    -> Error "TypeError: Do not know how to serialize a BigInt"

Не знаешь — научим:

BigInt.prototype.toJSON = function () { return this.toString(10); };

let json = JSON.stringify(9007199254740993n); // "9007199254740993"
JSONSon.parse('bigint', json); // 9007199254740993n
JSONSon.parse(BigInt, json); // object<BigInt> {9007199254740993n}

Кроме того, BigInt не является конструктором (в отличии от Boolean, Number и String). Поэтому для получения объектной обёртки для этого типа в JSONSon сделано специальное поведение: Object(BigInt(value)). Не знаю, зачем это может понадобиться, но для порядку — сделано.

Чудно: большие числа конвертируются в строку, и так же хорошо преобразуются обратно. Если хранить в виде обычного числа, то потеряется точность в процессе между разбором JSON-строки (а он, напомню, нативный) и передачей преобразователю типов.

Применение

А самого парсера-то внутри и нет. В самом деле, функция JSONSon.parse не делает почти ничего: она запускает стандартный парсер, а результат пробрасывает в поистине главную функцию — JSONSon.make. Поэтому получается, что вовсе не обязательно скармливать ей JSON-строку. Если я уже обладаю какими-то сырыми данными, и нужно просто преобразовать типы, то можно вызывать JSONSon.make.

Этой поделкой можно пользоваться в двух стилях:

1. вызывать статичные методы класса JSONSon;

2. сделать экземпляр класса и вызывать его методы.

// static:

JSONSon.parse(Folder, "{...}");
//or
let folder = await serverApi.getFolder('~/Videos'); // JSON parsed inside
JSONSon.make(Folder, folder);


// non-static:
let schema = new JSONSon(Folder);

JSONSon.parse("{...}");
// or
JSONSon.make(folder);

Передать JSONSon в JSON

Обычно я делаю так, что бэкенд предоставляет апишку вместе с авто-описанием её методов. Клиент обращается к серверу: «Какие у тебя есть методы»? А тот ему передаёт список всех методов с объявленными параметрами, а также и их типами (если язык позволяет). После этого клиент на своей стороне в обёртке организует всё так, чтобы применение выглядело как простой вызов функции: await serverApi.getFolder('~'). Было бы хорошо, если бы клиент ещё и взял на себя преобразование типов. И это можно: нужно лишь как-то передать на клиент саму схему — экземпляр JSONSon. Выходит, что и его нужно правильно преобразовать в JSON. А там же совершенно непригодные для преобразования классы! Как же быть? Было решено слишком не заморачиваться (хе-хе): просто определяем имя класса и отдаём строкой. А клиент сделает обратное преобразование. Но мало ли какая ещё сторона будет делать обратное преобразование. Как найти конструкторы по их именам? Короче говоря, сделал ещё один статичный метод JSONSon.resolveConstructor с примитивной стандартной реализацией. И его предполагается менять на свой лад в месте применения. Примерно так у меня выглядит блок инициализации на фронте:

<script type="module">
import JSONSon from './src/utils/JSONSon.js';
import Folder from './src/Folder.js';
import * as contClasses from './src/containers/index.js';

const supportedConstructorLibs = [
    window,
    {
        Folder,
        ...contClasses,
    },
];
JSONSon.resolveConstructor = (name) => {
    for (const lib of supportedConstructorLibs) {
        if (lib[name]) {
            return lib[name];
        }
    }
    return null;
};

//...
</script>

Итог: сервер отдаёт все объявленные API-методы, и ещё схему JSONSon результата для каждого; клиент это всё получает; в момент вызова каждого метода клиент знает, в какой тип следует преобразовать полученный результат.

Забавно, что реализации JSONSon.toJSON и JSONSon.fromJSON получились жирнее, чем код JSONSon.make, и вообще составляют почти 40% от кода модуля.

Ещё чуть-чуть путаницы

Помните, что апишный метод возвращает Folder с дополнительными посторонними свойствами? Вот я и подумал: неужели нельзя всё ещё немного усложнить :) Ну в самом деле — зачем мне постоянно писать так:

JSONSon.mix(Folder, {
    childContainers: [AContainer],
    childFolders: [Folder],
})

Можно же это тоже всё организовать в классе Folder. Но не вручную в методе fromJSON, а как-то похитрее. И таки да: можно декларировать, что JSONSon будет искать в классах ещё один волшебный метод, который будет выдавать уточнённую схему для типов. Ну и вот:

class Folder {
    // ...
    
    static getJSONSonSchema() {
        return JSONSon.mix(
            this,
            {
                childFolders: [this],
                childContainers: [AContainer],
            }
        );
    }
}

// демонстрация
let data = {
    dir: '/home/bars/',
    // ...
    childFolders: [
        { dir: '/home/bars/Videos' },
        { dir: '/home/bars/Images' },
        // ...
    ],
    childContainers: [{
        containerType: 'ImageBasic',
        file: '/home/bars/hello.jpg',
        // ...
    }],
};

// теперь можно прямо так:
let folder = JSONSon.make(Folder, data);

В результате будет папка с правильно заполненным массивом дочерних папок и контейнером типа ImageBasic.

Исходники поделки

https://github.com/bbars/utils/tree/master/js-json-son