@mat3ra/esse 2026.8.17-0 → 2026.8.18-0

package/src/js/esse/JSONSchemasGenerator.ts

@@ -1,105 +0,0 @@
-/* eslint-disable class-methods-use-this */
-import fs from "fs";
-import yaml from "js-yaml";
-import mergeAllOf from "json-schema-merge-allof";
-import path from "path";
-
-import { JSONSchemaWithPath, parseIncludeReferenceStatementsByDir } from "./server/utils";
-import { EXAMPLES_DIR, PROPERTIES_MANIFEST_PATH, SCHEMAS_DIR } from "./settings";
-import type { JSONSchema } from "./utils";
-
-interface JSONSchemasGeneratorConfig {
-    schemasDir: string;
-    examplesDir?: string;
-    propertiesManifestDir?: string;
-}
-
-const DEFAULT_CONFIG = {
-    schemasDir: SCHEMAS_DIR,
-    examplesDir: EXAMPLES_DIR,
-    propertiesManifestDir: PROPERTIES_MANIFEST_PATH,
-};
-
-export default class JSONSchemasGenerator implements JSONSchemasGeneratorConfig {
-    readonly schemas: JSONSchema[];
-
-    readonly examples?: JSONSchema[];
-
-    readonly wrappedExamples: JSONSchemaWithPath[];
-
-    readonly propertiesManifest: object;
-
-    readonly results: object;
-
-    readonly schemasDir: string;
-
-    readonly examplesDir?: string;
-
-    readonly propertiesManifestDir?: string;
-
-    constructor(config: JSONSchemasGeneratorConfig = DEFAULT_CONFIG) {
-        this.schemasDir = config.schemasDir;
-        this.examplesDir = config.examplesDir;
-        this.propertiesManifestDir = config.propertiesManifestDir;
-
-        this.schemas = parseIncludeReferenceStatementsByDir(this.schemasDir);
-
-        this.wrappedExamples = this.examplesDir
-            ? parseIncludeReferenceStatementsByDir(this.examplesDir, true)
-            : [];
-
-        this.examples = this.wrappedExamples.map((example) => example.data);
-
-        this.propertiesManifest = this.propertiesManifestDir
-            ? (yaml.load(fs.readFileSync(this.propertiesManifestDir, "utf-8")) as object)
-            : {};
-
-        this.results = Object.entries(this.propertiesManifest)
-            .map((k) => (k[1].isResult ? k[0] : null))
-            .filter((x) => x) as object;
-    }
-
-    writeResolvedSchemas(subfolder: string, skipMergeAllOff = false) {
-        const schemasFolder = `${subfolder}/schema`;
-        fs.rmSync(schemasFolder, { recursive: true, force: true });
-
-        const mergeAllOfConfig = {
-            resolvers: { defaultResolver: mergeAllOf.options.resolvers.title },
-        };
-
-        const schemas = this.schemas.map((schema) => {
-            console.log(`Resolving schema: ${schema.$id}`);
-            const mergedSchema = skipMergeAllOff ? schema : mergeAllOf(schema, mergeAllOfConfig);
-            let idAsPath = mergedSchema.$id;
-            if (!idAsPath) {
-                throw new Error(`Schema ID is missing:
-                ${JSON.stringify(mergedSchema)}`);
-            }
-            const schemaHasDash = idAsPath.includes("-");
-            if (schemaHasDash) {
-                // replace dashes with underscores
-                idAsPath = idAsPath.replace(/-/g, "_");
-            }
-
-            const fullPath = `${schemasFolder}/${idAsPath}.json`;
-
-            fs.mkdirSync(path.dirname(fullPath), { recursive: true });
-            fs.writeFileSync(fullPath, JSON.stringify(mergedSchema, null, 4), "utf8");
-
-            return mergedSchema;
-        });
-
-        fs.writeFileSync(`${subfolder}/schemas.json`, `${JSON.stringify(schemas)}`);
-    }
-
-    writeResolvedExamples(subfolder: string) {
-        const examplesFolder = `${subfolder}/example`;
-        fs.rmSync(`${examplesFolder}`, { recursive: true, force: true });
-        this.wrappedExamples.forEach((e) => {
-            const idAsPath = e.path.replace(/-/g, "_");
-            const fullPath = `${examplesFolder}/${idAsPath}.json`;
-            fs.mkdirSync(path.dirname(fullPath), { recursive: true });
-            fs.writeFileSync(fullPath, JSON.stringify(e.data, null, 4), "utf8");
-        });
-    }
-}

package/src/js/esse/JSONSchemasInterface.ts

@@ -1,99 +0,0 @@
-import { type JSONSchema, applyPatchTree } from "./utils";
-
-export type JSONSchemasInterfaceQuery = { [key in keyof JSONSchema]: { $regex: string } };
-
-export default class JSONSchemasInterface {
-    static schemasCache = new Map<string, JSONSchema>();
-
-    static setSchemas(schema: JSONSchema[]) {
-        schema.forEach((schema) => this.addSchema(schema));
-    }
-
-    static addSchema(schema: JSONSchema) {
-        if (schema.$id) {
-            this.schemasCache.set(schema.$id, schema);
-        }
-    }
-
-    static getSchemaById(schemaId: string) {
-        return this.schemasCache.get(schemaId);
-    }
-
-    /**
-     * Like {@link getSchemaById}, but throws if the schema is not registered.
-     */
-    static getRequiredSchemaById(schemaId: string): JSONSchema {
-        const schema = this.getSchemaById(schemaId);
-        if (!schema) {
-            throw new Error(`ESSE schema not found: ${schemaId}`);
-        }
-        return schema;
-    }
-
-    /**
-     * @example <caption>Search by $id regex</caption>
-     * JSONSchemasInterface.matchSchema({
-     *   $id: {
-     *     $regex: 'software-application'
-     *   }
-     * })
-     *
-     * @example <caption>Search by $id and title regex</caption>
-     * JSONSchemasInterface.matchSchema({
-     *   $id: {
-     *     $regex: 'software-application'
-     *   },
-     *   title: {
-     *     $regex: 'application'
-     *   }
-     * })
-     */
-    static matchSchema(query: JSONSchemasInterfaceQuery) {
-        const searchFields = Object.keys(query) as Array<keyof typeof query>;
-
-        return Array.from(this.schemasCache.values()).find((schema) => {
-            return searchFields.every((field) => {
-                const queryField = query[field];
-                const schemaField = schema[field];
-
-                if (!queryField || typeof schemaField !== "string") {
-                    return;
-                }
-
-                return new RegExp(queryField.$regex).test(schemaField);
-            });
-        });
-    }
-
-    /**
-     * Get a patched copy of a schema without modifying the cached version
-     * @param schemaId - The ID of the schema to patch
-     * @param propertyPatches - Object with property names as keys and patch objects as values
-     * @returns A new schema with patched properties
-     *
-     * @example
-     * JSONSchemasInterface.getPatchedSchema("boundary-conditions-provider", {
-     *   type: { default: "pbc" },
-     *   offset: { default: 0 }
-     * });
-     */
-    static getPatchedSchemaById(
-        schemaId: string,
-        patchConfig: Record<string, unknown>,
-    ): JSONSchema | undefined {
-        const baseSchema = this.getSchemaById(schemaId);
-        if (!baseSchema) {
-            return undefined;
-        }
-
-        const patchedSchema = JSON.parse(JSON.stringify(baseSchema));
-
-        applyPatchTree(
-            patchedSchema as Record<string, unknown>,
-            patchConfig as Record<string, unknown>,
-            [],
-        );
-
-        return patchedSchema;
-    }
-}

package/src/js/esse/JSONSchemasInterfaceServer.ts

@@ -1,49 +0,0 @@
-import { SchemaObject } from "ajv";
-import fs from "fs";
-import path from "path";
-
-import { walkDirSync } from "../utils/filesystem";
-import JSONSchemasInterface from "./JSONSchemasInterface";
-
-export function readSchemaFolderSync(folderPath: string) {
-    const schemas: SchemaObject[] = [];
-
-    walkDirSync(folderPath, (filePath: string) => {
-        if (path.extname(filePath) !== ".json") {
-            return;
-        }
-        const schema = JSON.parse(fs.readFileSync(filePath).toString());
-        schemas.push(schema);
-    });
-
-    return schemas;
-}
-
-export default class JSONSchemasInterfaceServer extends JSONSchemasInterface {
-    static schemaFolder = path.resolve(__dirname, "./../schema");
-
-    static setSchemaFolder(schemaFolder: string) {
-        if (this.schemaFolder !== schemaFolder) {
-            this.schemaFolder = schemaFolder;
-            this.readSchemaFolder();
-        }
-    }
-
-    static readSchemaFolder() {
-        const schemas = readSchemaFolderSync(this.schemaFolder);
-
-        schemas.forEach((schema) => {
-            if (schema.$id) {
-                this.schemasCache.set(schema.$id, schema);
-            }
-        });
-    }
-
-    static getSchemaById(schemaId: string) {
-        if (this.schemasCache.size === 0) {
-            this.readSchemaFolder();
-        }
-
-        return super.getSchemaById(schemaId);
-    }
-}

package/src/js/esse/schemaUtils.ts

@@ -1,28 +0,0 @@
-import type { JSONSchema, JSONSchemaDefinition } from "./utils";
-
-export type MapSchema = (prop: JSONSchemaDefinition) => JSONSchemaDefinition | undefined;
-
-export function mapObjectDeep(object: JSONSchemaDefinition, mapValue: MapSchema): JSONSchema;
-
-export function mapObjectDeep(object: JSONSchemaDefinition[], mapValue: MapSchema): JSONSchema[];
-
-export function mapObjectDeep(
-    object: JSONSchemaDefinition | JSONSchemaDefinition[],
-    mapValue: MapSchema,
-): JSONSchemaDefinition | JSONSchemaDefinition[] {
-    if (typeof object !== "object" || object === null) {
-        return object;
-    }
-
-    if (Array.isArray(object)) {
-        return object.map((innerValue) => mapObjectDeep(innerValue, mapValue));
-    }
-
-    const mappedObject = mapValue(object) || object;
-
-    const entries = Object.entries(mappedObject).map(([key, value]) => {
-        return [key, mapObjectDeep(value, mapValue)];
-    });
-
-    return Object.fromEntries(entries);
-}

package/src/js/esse/server/utils.ts

@@ -1,82 +0,0 @@
-/**
- * Server-side schema parsing utilities.
- *
- * Use this module only in Node/server contexts where the filesystem is available.
- * It walks directories and reads JSON schema files from disk; do not import it in
- * browser bundles.
- */
-// @ts-ignore
-import deref from "json-schema-deref-sync";
-import path from "path";
-
-import { JSONInclude } from "../../json_include";
-import { walkDirSync } from "../../utils/filesystem";
-import type { JSONSchema } from "../utils";
-
-export interface JSONSchemaWithPath {
-    data: JSONSchema;
-    path: string;
-}
-
-/**
- * Resolves `include` and `$ref` statements.
- * @param filePath {String} file to parse.
- */
-export function parseIncludeReferenceStatements(filePath: string): JSONSchema {
-    const jsonResolver = new JSONInclude();
-    const parsed = jsonResolver.parseIncludeStatements(filePath) as JSONSchema;
-    const dirPath = path.dirname(filePath);
-    // Store the original $id before dereferencing
-    const originalId = parsed.$id;
-    let dereferenced = deref(parsed, { baseFolder: dirPath, removeIds: true });
-    // handle circular references and use non-dereferenced source
-    if (dereferenced instanceof Error && dereferenced.message === "Circular self reference") {
-        dereferenced = parsed;
-    }
-    // Restore the original $id after dereferencing
-    if (originalId) {
-        dereferenced.$id = originalId;
-    }
-    return dereferenced;
-}
-
-export function parseIncludeReferenceStatementsByDir(
-    dirPath: string,
-    wrapInDataAndPath: true,
-): JSONSchemaWithPath[];
-
-export function parseIncludeReferenceStatementsByDir(
-    dirPath: string,
-    wrapInDataAndPath?: false,
-): JSONSchema[];
-
-/**
- * Resolves `include` and `$ref` statements for all the JSON files inside a given directory.
- * @param dirPath directory to parse.
- */
-export function parseIncludeReferenceStatementsByDir(dirPath: string, wrapInDataAndPath = false) {
-    const schemas: JSONSchema[] = [];
-    const schemasWithPath: JSONSchemaWithPath[] = [];
-    const topDir = path.resolve(__dirname, "../../../../");
-
-    walkDirSync(dirPath, (filePath) => {
-        if (filePath.endsWith(".json")) {
-            const config = parseIncludeReferenceStatements(filePath);
-            if (wrapInDataAndPath) {
-                const _path = path.join(
-                    // remove leading slashes and "example" from path
-                    path
-                        .dirname(filePath)
-                        .replace(path.join(topDir, "example"), "")
-                        .replace(/^\/+/, ""),
-                    path.basename(filePath).replace(".json", ""),
-                );
-                schemasWithPath.push({ data: config, path: _path });
-            } else {
-                schemas.push(config);
-            }
-        }
-    });
-
-    return wrapInDataAndPath ? schemasWithPath : schemas;
-}

package/src/js/esse/settings.ts

@@ -1,8 +0,0 @@
-import path from "path";
-
-export const SCHEMAS_DIR = path.resolve(__dirname, "../../../schema");
-export const EXAMPLES_DIR = path.resolve(__dirname, "../../../example");
-export const PROPERTIES_MANIFEST_PATH = path.resolve(
-    __dirname,
-    "../../../manifest/properties.yaml",
-);

package/src/js/esse/types.ts

@@ -1,3 +0,0 @@
-export interface AnyObject {
-    [key: string]: unknown;
-}

package/src/js/esse/utils.ts

@@ -1,63 +0,0 @@
-import { JSONSchema7, JSONSchema7Definition } from "json-schema";
-
-export type JSONSchema = JSONSchema7;
-
-export type JSONSchemaDefinition = JSONSchema7Definition;
-
-function isPlainObject(value: unknown): value is Record<string, unknown> {
-    return value !== null && typeof value === "object" && !Array.isArray(value);
-}
-
-export function applyPatchWithDotNotation(
-    target: Record<string, unknown>,
-    path: string,
-    patchValue: unknown,
-): void {
-    const keys = path.split(".");
-    let current: any = target;
-
-    // Navigate to parent of final key
-    for (let index = 0; index < keys.length - 1; index += 1) {
-        const key = keys[index];
-        if (!isPlainObject(current[key])) {
-            // Path does not exist or is not an object → skip patch
-            return;
-        }
-        current = current[key];
-    }
-
-    const finalKey = keys[keys.length - 1];
-    const existingValue = current[finalKey];
-
-    if (isPlainObject(existingValue) && isPlainObject(patchValue)) {
-        // Merge object into existing object
-        Object.assign(existingValue, patchValue);
-    } else if (existingValue !== undefined) {
-        // Overwrite leaf value
-        current[finalKey] = patchValue;
-    }
-    // If existingValue is undefined, we skip;
-}
-
-export function applyPatchTree(
-    schema: Record<string, unknown>,
-    patchNode: Record<string, unknown>,
-    pathPrefix: string[],
-): void {
-    Object.entries(patchNode).forEach(([key, value]) => {
-        if (key.includes(".")) {
-            // Dot notation relative to current prefix
-            const fullPathSegments = [...pathPrefix, ...key.split(".")];
-            const fullPath = fullPathSegments.join(".");
-            applyPatchWithDotNotation(schema, fullPath, value);
-        } else if (isPlainObject(value)) {
-            // Nested subtree → recurse with extended prefix
-            applyPatchTree(schema, value, [...pathPrefix, key]);
-        } else {
-            // Leaf patch (primitive / array) → treat as direct field patch
-            const fullPathSegments = [...pathPrefix, key];
-            const fullPath = fullPathSegments.join(".");
-            applyPatchWithDotNotation(schema, fullPath, value);
-        }
-    });
-}

package/src/js/json_include/index.ts

@@ -1,76 +0,0 @@
-import fs from "fs";
-import path from "path";
-
-import { isInstanceOf, safeParseJSON } from "../utils/common";
-import { INCLUDE_KEY, INCLUDE_VALUE_REGEX, OBJECT_ONLY } from "./settings";
-
-export interface CacheObject {
-    [key: string]: CacheObject | CacheObject[];
-}
-
-export class JSONInclude {
-    JSON_INCLUDE_CACHE: CacheObject = {};
-
-    /**
-     * Extracts file name(path) from the include statement.
-     * @param value string to extract the file name from.
-     */
-    _getIncludeFileName = (value: unknown) => {
-        if (typeof value === "string" && value.search(INCLUDE_VALUE_REGEX) !== -1) {
-            const matched = value.match(INCLUDE_VALUE_REGEX);
-            return matched && matched[1];
-        }
-    };
-
-    /**
-     * Walks a nested object to resolve include statements.
-     * @param obj Object to traverse.
-     * @param dirpath directory from which `obj` is obtained. Include statements are relative to `obj` path.
-     */
-    _walkObjectToInclude(obj: CacheObject | CacheObject[], dirpath: string) {
-        if (isInstanceOf(obj, "Array")) {
-            for (let i = 0; i < obj.length; i++) {
-                if (isInstanceOf(obj[i], "Object") || isInstanceOf(obj[i], "Array")) {
-                    this._walkObjectToInclude(obj[i], dirpath);
-                }
-            }
-        } else if (isInstanceOf(obj, "Object")) {
-            if (INCLUDE_KEY in obj) {
-                const includeName = this._getIncludeFileName(obj[INCLUDE_KEY]);
-                if (includeName) {
-                    delete obj[INCLUDE_KEY];
-                    if (!(includeName in this.JSON_INCLUDE_CACHE)) {
-                        const filePath = path.join(dirpath, includeName);
-                        this.JSON_INCLUDE_CACHE[includeName] =
-                            this.parseIncludeStatements(filePath);
-                    }
-                    Object.keys(this.JSON_INCLUDE_CACHE[includeName]).forEach((attr) => {
-                        // @ts-ignore
-                        obj[attr] = this.JSON_INCLUDE_CACHE[includeName][attr];
-                    });
-                }
-            }
-            Object.keys(obj).forEach((key) => {
-                if (isInstanceOf(obj[key], "Object") || isInstanceOf(obj[key], "Array")) {
-                    this._walkObjectToInclude(obj[key], dirpath);
-                }
-            });
-        }
-    }
-
-    /**
-     * Resolves `include` statements.
-     * @param filePath file to parse.
-     */
-    parseIncludeStatements(filePath: string) {
-        const data: CacheObject[] = safeParseJSON(fs.readFileSync(filePath, "utf8"));
-        console.log("Parsing file: ", filePath);
-        if (OBJECT_ONLY && !isInstanceOf(data, "Object")) {
-            throw new Error(
-                "The JSON file being included should always be a dict rather than a list",
-            );
-        }
-        this._walkObjectToInclude(data, path.dirname(filePath));
-        return data;
-    }
-}

package/src/js/json_include/settings.ts

@@ -1,3 +0,0 @@
-export const INCLUDE_KEY = "...";
-export const INCLUDE_VALUE_REGEX = /^include\((.+)\)$/;
-export const OBJECT_ONLY = false; // whether to only include Object, and not Array.

package/src/js/scripts/compileTs.ts

@@ -1,85 +0,0 @@
-import { SchemaObject } from "ajv";
-import fs from "fs";
-import { compile } from "json-schema-to-typescript";
-
-import { mapObjectDeep } from "../esse/schemaUtils";
-import type { JSONSchema } from "../esse/utils";
-import { walkDir } from "../utils/filesystem";
-
-/**
- * By definition, the "compile" function will generate 2 schemas based on the following input:
- * {
- *    "title": "schema1",
- *    "type": "object",
- *    "properties": {
- *        "prop": {
- *             "title": "schema2",
- *             "type": "string"
- *        }
- *    }
- * }
- *
- * Result:
- * type schema2 = string;
- *
- * interface schema1 {
- *      prop: schema2
- * }
- *
- * To disable this behavior we need to remove "title" property from the "prop":
- *  {
- *    "title": "schema1",
- *    "type": "object",
- *    "properties": {
- *        "prop": {
- *             "type": "string"
- *        }
- *    }
- * }
- *
- * New result:
- * interface schema1 {
- *      prop: string;
- * }
- * @returns Clean schema
- */
-function cleanSchema(schema: JSONSchema): JSONSchema {
-    let firstRun = true;
-
-    return mapObjectDeep(schema, (object) => {
-        if (typeof object === "object" && object?.title && !firstRun) {
-            firstRun = false;
-
-            // eslint-disable-next-line @typescript-eslint/no-unused-vars
-            const { title, $schema, ...restObject } = object as SchemaObject;
-            return restObject;
-        }
-
-        firstRun = false;
-    });
-}
-
-export default async function compileTS(schemaPath: string, savePath: string) {
-    try {
-        await fs.promises.unlink(savePath);
-    } catch (err) {
-        console.log("File with types not exists");
-    }
-
-    await walkDir(schemaPath, async (filePath) => {
-        const data = await fs.promises.readFile(filePath, "utf8");
-        const schema = cleanSchema(JSON.parse(data));
-
-        console.log(`Compiling Typescript: ${filePath}`);
-
-        // @ts-ignore
-        const compiledSchema = await compile(schema, schema.title || "", {
-            unreachableDefinitions: true,
-            additionalProperties: false,
-            enableConstEnums: false,
-            bannerComment: `/** Schema ${filePath} */`,
-        });
-
-        await fs.promises.appendFile(savePath, `${compiledSchema} \n`, { flag: "a+" });
-    });
-}

package/src/js/scripts/createEnumsFromYaml.ts

@@ -1,29 +0,0 @@
-import fs from "fs";
-import yaml from "js-yaml";
-import lodash from "lodash";
-import path from "path";
-
-import { walkDir } from "../utils/filesystem";
-
-/**
- *  We use YAML files to list enum options which need to be reused in other places.
- *  The format also allows for additional context to the often shortened slugs, such as DOIs.
- *  This script converts the enum lists to JSON files for $ref blocks inside schemas.
- */
-
-const SCHEMA_DIR = "../../../schema/";
-
-walkDir(SCHEMA_DIR, (filePath: string) => {
-    if (path.extname(filePath) !== ".yml") {
-        return;
-    }
-    console.log(filePath);
-    const outFilename = `${path.basename(filePath, ".yml")}.json`;
-    const dirname = path.dirname(filePath);
-
-    const fileContents = fs.readFileSync(filePath);
-    const obj = yaml.load(fileContents.toString()) as object;
-    const enumObj = lodash.mapValues(obj, (value) => ({ enum: value }));
-
-    fs.writeFileSync(`${path.join(dirname, outFilename)}`, `${JSON.stringify(enumObj, null, 4)}\n`);
-});

package/src/js/scripts/setSchemaIds.ts

@@ -1,29 +0,0 @@
-import fs from "fs";
-import path from "path";
-
-import { walkDirSync } from "../utils/filesystem";
-
-/**
- * Helper script.
- * Applies correct $id to all schemas based on the schema path
- */
-
-export default function setSchemaIds(schemaDir: string) {
-    walkDirSync(schemaDir, (filePath) => {
-        if (path.extname(filePath) !== ".json") {
-            return;
-        }
-
-        const fileContents = fs.readFileSync(filePath);
-        console.log(filePath);
-        // eslint-disable-next-line @typescript-eslint/no-unused-vars
-        const { $id, ...schema } = JSON.parse(fileContents.toString());
-        const schemaId = filePath.replace(schemaDir, "").replace(".json", "").replace(/_/g, "-");
-        if ($id !== schemaId) {
-            console.log(`Set correct $id: ${filePath}`);
-            const newContent = JSON.stringify({ $id: schemaId, ...schema }, null, 4);
-
-            fs.writeFileSync(filePath, `${newContent}\n`);
-        }
-    });
-}