@mat3ra/wode 2026.4.9-0 → 2026.5.29-0

package/src/js/units/BaseUnit.ts

@@ -0,0 +1,117 @@
+import { InMemoryEntity } from "@mat3ra/code/dist/js/entity";
+import {
+    type Defaultable,
+    defaultableEntityMixin,
+} from "@mat3ra/code/dist/js/entity/mixins/DefaultableMixin";
+import {
+    HashedEntity,
+    hashedEntityMixin,
+} from "@mat3ra/code/dist/js/entity/mixins/HashedEntityMixin";
+import {
+    type NamedEntity,
+    namedEntityMixin,
+} from "@mat3ra/code/dist/js/entity/mixins/NamedEntityMixin";
+import {
+    type RuntimeItems,
+    runtimeItemsMixin,
+} from "@mat3ra/code/dist/js/entity/mixins/RuntimeItemsMixin";
+import { Taggable, taggableMixin } from "@mat3ra/code/dist/js/entity/mixins/TaggableMixin";
+import type { NameResultSchema } from "@mat3ra/code/dist/js/utils/object";
+import type { Constructor } from "@mat3ra/code/dist/js/utils/types";
+import type { AnyObject } from "@mat3ra/esse/dist/js/esse/types";
+import type { StatusSchema, WorkflowBaseUnitSchema } from "@mat3ra/esse/dist/js/types";
+import { Utils } from "@mat3ra/utils";
+
+import { UnitStatus } from "../enums";
+import { type BaseUnitSchemaMixin, baseUnitSchemaMixin } from "../generated/BaseUnitSchemaMixin";
+import { type StatusSchemaMixin, statusSchemaMixin } from "../generated/StatusSchemaMixin";
+import {
+    type RuntimeItemsUILogic,
+    runtimeItemsUILogicMixin,
+} from "./mixins/RuntimeItemsUILogicMixin";
+
+type Schema = WorkflowBaseUnitSchema;
+
+type Base = typeof InMemoryEntity &
+    Constructor<NamedEntity> &
+    Constructor<Defaultable> &
+    Constructor<Taggable> &
+    Constructor<HashedEntity> &
+    Constructor<RuntimeItems> &
+    Constructor<RuntimeItemsUILogic> &
+    Constructor<BaseUnitSchemaMixin> &
+    Constructor<StatusSchemaMixin>;
+
+class BaseUnit<S extends Schema = Schema> extends (InMemoryEntity as Base) implements Schema {
+    declare toJSON: () => Schema & AnyObject;
+
+    declare _json: Schema & AnyObject;
+
+    defaultResults: NameResultSchema[] = [];
+
+    defaultMonitors: NameResultSchema[] = [];
+
+    defaultPostProcessors: NameResultSchema[] = [];
+
+    defaultPreProcessors: NameResultSchema[] = [];
+
+    repetition = 0;
+
+    /**
+     * @param config — `flowchartId` is optional; when absent, a new UUID is generated.
+     */
+    constructor(config: Partial<S> & Pick<S, "name">) {
+        super({
+            results: [],
+            monitors: [],
+            preProcessors: [],
+            postProcessors: [],
+            ...config,
+            status: config.status || UnitStatus.idle,
+            statusTrack: config.statusTrack || [],
+            flowchartId: config.flowchartId ?? Utils.uuid.getUUID(),
+            tags: config.tags || [],
+        });
+
+        this._initRuntimeItems(config);
+    }
+
+    get lastStatusUpdate() {
+        const statusTrack = (this.statusTrack || []).filter((s) => {
+            return (s.repetition || 0) === this.repetition;
+        });
+        const sortedStatusTrack = statusTrack.sort((a, b) => a.trackedAt - b.trackedAt); // lodash.sortBy(statusTrack, (x) => x.trackedAt);
+        return sortedStatusTrack[sortedStatusTrack.length - 1];
+    }
+
+    getHashObject(): object {
+        return { ...this.hashObjectFromRuntimeItems, type: this.type };
+    }
+
+    isInStatus(status: StatusSchema["status"]) {
+        return this.status === status;
+    }
+
+    clone(extraContext: object) {
+        const flowchartIDOverrideConfigAsExtraContext = {
+            flowchartId: Utils.uuid.getUUID(),
+            ...extraContext,
+        };
+        return super.clone(flowchartIDOverrideConfigAsExtraContext);
+    }
+
+    setRepetition(repetition: number) {
+        this.repetition = repetition;
+    }
+}
+
+taggableMixin(BaseUnit.prototype);
+hashedEntityMixin(BaseUnit.prototype);
+runtimeItemsMixin(BaseUnit.prototype);
+runtimeItemsUILogicMixin(BaseUnit.prototype);
+baseUnitSchemaMixin(BaseUnit.prototype);
+statusSchemaMixin(BaseUnit.prototype);
+namedEntityMixin(BaseUnit.prototype);
+defaultableEntityMixin(BaseUnit);
+
+export default BaseUnit;

package/src/js/units/ConditionUnit.ts

@@ -0,0 +1,52 @@
+import type { Constructor } from "@mat3ra/code/dist/js/utils/types";
+import JSONSchemasInterface from "@mat3ra/esse/dist/js/esse/JSONSchemasInterface";
+import type { AnyObject } from "@mat3ra/esse/dist/js/esse/types";
+import type { ConditionUnitSchema } from "@mat3ra/esse/dist/js/types";
+
+import { UnitType } from "../enums";
+import {
+    type ConditionUnitSchemaMixin,
+    conditionUnitSchemaMixin,
+} from "../generated/ConditionUnitSchemaMixin";
+import BaseUnit from "./BaseUnit";
+
+type Schema = ConditionUnitSchema;
+type Base = typeof BaseUnit<Schema> & Constructor<ConditionUnitSchemaMixin>;
+
+export type ConditionUnitConfig = Partial<Schema>;
+
+class ConditionUnit extends (BaseUnit as Base) implements Schema {
+    declare toJSON: () => Schema & AnyObject;
+
+    declare _json: Schema & AnyObject;
+
+    static get jsonSchema() {
+        return JSONSchemasInterface.getSchemaById("workflow/unit/condition");
+    }
+
+    constructor(config: ConditionUnitConfig) {
+        const schema = {
+            input: [],
+            results: [],
+            preProcessors: [],
+            postProcessors: [],
+            monitors: [],
+            then: "",
+            else: "",
+            statement: "true",
+            maxOccurrences: 100,
+            ...config,
+            name: config.name ?? UnitType.condition,
+            type: UnitType.condition as Schema["type"],
+        };
+        super(schema);
+    }
+
+    getHashObject(): object {
+        return { statement: this.statement, maxOccurrences: this.maxOccurrences };
+    }
+}
+
+conditionUnitSchemaMixin(ConditionUnit.prototype);
+
+export default ConditionUnit;

package/src/js/units/ExecutionUnit.ts

@@ -0,0 +1,274 @@
+import type { Constructor } from "@mat3ra/code/dist/js/utils/types";
+import JSONSchemasInterface from "@mat3ra/esse/dist/js/esse/JSONSchemasInterface";
+import type { AnyObject } from "@mat3ra/esse/dist/js/esse/types";
+import type { ExecutionUnitInputItemSchema, ExecutionUnitSchema } from "@mat3ra/esse/dist/js/types";
+import { ApplicationRegistry, applicationVersionSatisfiesSupportedRange } from "@mat3ra/standata";
+import { Utils } from "@mat3ra/utils";
+
+import {
+    type AnyContextProvider,
+    type ExternalContext,
+    createProvider,
+} from "../context/providers";
+import type ConvergenceParameter from "../convergence/ConvergenceParameter";
+import { UnitType } from "../enums";
+import {
+    type ExecutionUnitSchemaMixin,
+    executionUnitSchemaMixin,
+} from "../generated/ExecutionUnitSchemaMixin";
+import BaseUnit from "./BaseUnit";
+import ExecutionUnitInput from "./ExecutionUnitInput";
+
+type Schema = ExecutionUnitSchema;
+
+type Base = typeof BaseUnit & Constructor<ExecutionUnitSchemaMixin>;
+
+export type ExecutionUnitConfig = Omit<Partial<Schema>, "application"> & SetApplicationProps;
+
+type SetApplicationProps = Pick<Schema, "application"> &
+    Pick<Partial<Schema>, "executable" | "flavor"> &
+    SetExecutableProps;
+
+type SetExecutableProps = {
+    executableName?: string;
+    flavorName?: string;
+};
+
+class ExecutionUnit extends (BaseUnit as Base) implements Schema {
+    inputInstances: ExecutionUnitInput[] = [];
+
+    renderingContext: Partial<ExternalContext> = {};
+
+    contextProvidersInstances: AnyContextProvider[] = [];
+
+    declare toJSON: () => Schema & AnyObject;
+
+    declare _json: Schema & AnyObject;
+
+    static get jsonSchema() {
+        return JSONSchemasInterface.getSchemaById("workflow/unit/execution");
+    }
+
+    constructor(config: ExecutionUnitConfig) {
+        const schema = {
+            name: UnitType.execution,
+            type: UnitType.execution as Schema["type"],
+            input: [],
+            results: [],
+            preProcessors: [],
+            postProcessors: [],
+            monitors: [],
+            context: [],
+            ...config,
+        };
+        super(schema);
+
+        this.setApplication(config);
+
+        this.name = this.name || this.flavor.name || "";
+    }
+
+    setApplication({
+        application,
+        executable,
+        flavor,
+        executableName,
+        flavorName,
+    }: SetApplicationProps) {
+        const currentExecutable = this.prop<Schema["executable"]>("executable");
+        const currentFlavor = this.prop<Schema["flavor"]>("flavor");
+
+        this.setProp("application", application);
+        this.setExecutable({
+            executableName: executableName ?? executable?.name ?? currentExecutable?.name,
+            flavorName: flavorName ?? flavor?.name ?? currentFlavor?.name,
+        });
+    }
+
+    setExecutable({ executableName, flavorName }: SetExecutableProps) {
+        const executable = new ApplicationRegistry()
+            .getExecutablesByApplication(this.application)
+            .find((executable) => {
+                return executableName ? executable.name === executableName : executable.isDefault;
+            });
+
+        if (!executable) {
+            throw new Error(`Executable ${executableName} not found`);
+        }
+
+        this.setProp("executable", executable);
+        this.setFlavor(flavorName);
+    }
+
+    setFlavor(flavorName?: string) {
+        const flavor = new ApplicationRegistry()
+            .getFlavorsByApplicationExecutable(this.application, this.executable)
+            .find((flavor) => (flavorName ? flavor.name === flavorName : flavor.isDefault));
+
+        if (!flavor) {
+            throw new Error(`Flavor ${flavorName} not found`);
+        }
+
+        this.defaultResults = flavor.results;
+        this.defaultMonitors = flavor.monitors;
+        this.defaultPreProcessors = flavor.preProcessors;
+        this.defaultPostProcessors = flavor.postProcessors;
+
+        // flavor is missing on the first run, so do not use getter this.flavor with requiredProperty
+        const previousFlavor = this.prop<Schema["flavor"]>("flavor");
+
+        if (previousFlavor?.name !== flavor.name) {
+            this.results = flavor.results;
+            this.monitors = flavor.monitors;
+            this.preProcessors = flavor.preProcessors;
+            this.postProcessors = flavor.postProcessors;
+        }
+
+        this.setProp("flavor", flavor);
+        this.setDefaultInput();
+    }
+
+    /**
+     * Persisted `input[].template` must match the current application/executable (and optional
+     * applicationVersion). Otherwise the stored template is stale, and we take the default from
+     * ApplicationRegistry.
+     */
+    private isPersistedInputItemCompatible(item: ExecutionUnitInputItemSchema): boolean {
+        const { template } = item;
+
+        if (
+            template.applicationName !== this.application.name ||
+            template.executableName !== this.executable.name
+        ) {
+            return false;
+        }
+
+        if (
+            !applicationVersionSatisfiesSupportedRange(
+                this.application.version,
+                template.applicationVersion ?? "",
+            )
+        ) {
+            return false;
+        }
+
+        return true;
+    }
+
+    /**
+     * Build `inputInstances` from the current flavor’s defaults (`ApplicationRegistry#getInput(application, flavor)`),
+     * merged with persisted `this.input` from saved workflow JSON. For each input slot from the registry we
+     * prefer a compatible persisted row matched by `template.name`, else by index; incompatible or missing
+     * rows use the registry template. `render()` then serializes from these instances into `this.input`, so UI
+     * and saved JSON stay aligned when Subworkflow re-serializes units after render.
+     */
+    setDefaultInput() {
+        const driverTemplates = new ApplicationRegistry().getInput(this.application, this.flavor);
+        const persisted = Array.isArray(this.input) ? this.input : [];
+
+        this.inputInstances = driverTemplates.map((driverTemplate, index) => {
+            const persistedItem =
+                persisted.find((item) => item?.template?.name === driverTemplate.name) ??
+                persisted[index];
+
+            if (persistedItem && this.isPersistedInputItemCompatible(persistedItem)) {
+                return new ExecutionUnitInput(persistedItem);
+            }
+
+            return ExecutionUnitInput.createFromTemplate(driverTemplate);
+        });
+
+        this.input = this.inputInstances.map((input) => input.toJSON());
+    }
+
+    render(externalContext: ExternalContext, convergence?: ConvergenceParameter) {
+        this.contextProvidersInstances = this.getContextProvidersInstances(
+            externalContext,
+            convergence,
+        );
+
+        this.saveContext(externalContext);
+    }
+
+    private getContextProvidersInstances(
+        externalContext: ExternalContext,
+        convergence?: ConvergenceParameter,
+    ) {
+        const uniqueContextProviderNames = [
+            ...new Set(
+                this.input
+                    .map((input) => {
+                        return input.template.contextProviders.map((provider) => {
+                            return provider.name;
+                        });
+                    })
+                    .flat(),
+            ),
+        ];
+
+        // TODO: kgrid should be abstracted and selected by user
+        const parameterToContextProviderMap = {
+            N_k: "kgrid",
+            N_k_nonuniform: "kgrid",
+        } as const;
+
+        return uniqueContextProviderNames
+            .map((name) => {
+                return createProvider(name, this.context, externalContext);
+            })
+            .map((provider) => {
+                if (
+                    convergence &&
+                    provider.name === parameterToContextProviderMap[convergence.name]
+                ) {
+                    provider.applyConvergenceParameter(convergence);
+                }
+                return provider;
+            });
+    }
+
+    savePersistentContext() {
+        const persistentItems = this.contextProvidersInstances.map((p) => p.getContextItemData());
+        this.context = persistentItems.filter((c) => c.isEdited);
+    }
+
+    saveRenderingContext(externalContext: ExternalContext) {
+        const renderingItems = this.contextProvidersInstances.map((p) =>
+            p.getContextItemDataForRendering(),
+        );
+        this.renderingContext = {
+            ...Object.fromEntries(renderingItems.map((context) => [context.name, context.data])),
+            ...externalContext,
+        };
+        this.input = this.inputInstances.map((input) => {
+            return input.render(this.renderingContext).toJSON();
+        });
+    }
+
+    saveContext(externalContext: ExternalContext) {
+        this.savePersistentContext();
+        this.saveRenderingContext(externalContext);
+    }
+
+    getHashObject() {
+        const { input, flavor, application, executable } = this.toJSON();
+
+        return {
+            ...super.getHashObject(),
+            application,
+            executable,
+            flavor,
+            input: Utils.hash.calculateHashFromObject(
+                input.map(({ template }) => {
+                    return Utils.str.removeEmptyLinesFromString(
+                        Utils.str.removeCommentsFromSourceCode(template.content),
+                    );
+                }),
+            ),
+        };
+    }
+}
+
+executionUnitSchemaMixin(ExecutionUnit.prototype);
+
+export default ExecutionUnit;

package/src/js/units/ExecutionUnitInput.ts

@@ -0,0 +1,71 @@
+import { Template } from "@mat3ra/ade";
+import { InMemoryEntity } from "@mat3ra/code/dist/js/entity";
+import JSONSchemasInterface from "@mat3ra/esse/dist/js/esse/JSONSchemasInterface";
+import type { AnyObject } from "@mat3ra/esse/dist/js/esse/types";
+import type { TemplateSchema } from "@mat3ra/esse/dist/js/types";
+import { setupNunjucksEnvironment } from "@mat3ra/standata";
+import nunjucks from "nunjucks";
+
+import {
+    type ExecutionUnitInputSchemaMixin,
+    executionUnitInputSchemaMixin,
+} from "../generated/ExecutionUnitInputSchemaMixin";
+
+type Schema = ExecutionUnitInputSchemaMixin;
+type JSON = Schema & AnyObject;
+type ConstructorConfig = Schema | (Omit<Schema, "template"> & { template: Template });
+
+const env = setupNunjucksEnvironment(new nunjucks.Environment());
+
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+interface ExecutionUnitInput extends ExecutionUnitInputSchemaMixin {}
+
+class ExecutionUnitInput extends InMemoryEntity implements Schema {
+    declare _json: JSON;
+
+    declare toJSON: () => JSON;
+
+    declare toJSONQuick: () => JSON;
+
+    static get jsonSchema() {
+        return JSONSchemasInterface.getSchemaById("workflow/unit/input/-inputItem");
+    }
+
+    static createFromTemplate(template: Template | TemplateSchema) {
+        return new ExecutionUnitInput({
+            template,
+            rendered: template.content,
+            isManuallyChanged: false,
+        });
+    }
+
+    constructor(config: ConstructorConfig) {
+        const { template } = config;
+        const templateInstance = template instanceof Template ? template : new Template(template);
+
+        super({ ...config, template: templateInstance.toJSON() });
+    }
+
+    render(renderingContext: Record<string, unknown>) {
+        if (this.isManuallyChanged) {
+            return this;
+        }
+
+        try {
+            const rendered = nunjucks.compile(this.template.content, env).render(renderingContext);
+
+            this.rendered = rendered || this.template.content;
+
+            return this;
+        } catch (error) {
+            console.error("Error rendering template", this.template.content);
+            console.error("Rendering context: ", JSON.stringify(renderingContext));
+            console.error("Error", error);
+            throw error;
+        }
+    }
+}
+
+executionUnitInputSchemaMixin(ExecutionUnitInput.prototype);
+
+export default ExecutionUnitInput;

package/src/js/units/IOUnit.ts

@@ -0,0 +1,43 @@
+import type { Constructor } from "@mat3ra/code/dist/js/utils/types";
+import JSONSchemasInterface from "@mat3ra/esse/dist/js/esse/JSONSchemasInterface";
+import type { AnyObject } from "@mat3ra/esse/dist/js/esse/types";
+import type { DataIOUnitSchema } from "@mat3ra/esse/dist/js/types";
+
+import { UnitType } from "../enums";
+import { type IOUnitSchemaMixin, iOUnitSchemaMixin } from "../generated/IOUnitSchemaMixin";
+import BaseUnit from "./BaseUnit";
+
+type Schema = DataIOUnitSchema;
+type Base = typeof BaseUnit<Schema> & Constructor<IOUnitSchemaMixin>;
+
+export type IOUnitConfig = Partial<Schema>;
+
+class IOUnit extends (BaseUnit as Base) implements Schema {
+    declare toJSON: () => Schema & AnyObject;
+
+    declare _json: Schema & AnyObject;
+
+    static get jsonSchema() {
+        return JSONSchemasInterface.getSchemaById("workflow/unit/io");
+    }
+
+    constructor(config: IOUnitConfig) {
+        const schema = {
+            name: UnitType.io,
+            subtype: "input" as const,
+            source: "api" as const,
+            input: [],
+            results: [],
+            preProcessors: [],
+            postProcessors: [],
+            monitors: [],
+            ...config,
+            type: UnitType.io as Schema["type"],
+        };
+        super(schema);
+    }
+}
+
+iOUnitSchemaMixin(IOUnit.prototype);
+
+export default IOUnit;

package/src/js/units/MapUnit.ts

@@ -0,0 +1,59 @@
+import type { Constructor } from "@mat3ra/code/dist/js/utils/types";
+import JSONSchemasInterface from "@mat3ra/esse/dist/js/esse/JSONSchemasInterface";
+import type { AnyObject } from "@mat3ra/esse/dist/js/esse/types";
+import type { MapUnitSchema } from "@mat3ra/esse/dist/js/types";
+
+import { UnitType } from "../enums";
+import { type MapUnitSchemaMixin, mapUnitSchemaMixin } from "../generated/MapUnitSchemaMixin";
+import BaseUnit from "./BaseUnit";
+
+type Schema = MapUnitSchema;
+
+export const defaultMapConfig = {
+    name: UnitType.map,
+    type: UnitType.map,
+    workflowId: "",
+    input: {
+        target: "MAP_DATA",
+        scope: "global",
+        name: "",
+        values: [],
+        useValues: false,
+    },
+    results: [],
+    monitors: [],
+    preProcessors: [],
+    postProcessors: [],
+};
+
+type Base = typeof BaseUnit<Schema> & Constructor<MapUnitSchemaMixin>;
+
+export type MapUnitConfig = Partial<Omit<Schema, "type">>;
+
+class MapUnit extends (BaseUnit as Base) implements Schema {
+    declare toJSON: () => Schema & AnyObject;
+
+    declare _json: Schema & AnyObject;
+
+    static get jsonSchema() {
+        return JSONSchemasInterface.getSchemaById("workflow/unit/flowchart");
+    }
+
+    constructor(config: MapUnitConfig) {
+        const schema: Schema = {
+            ...defaultMapConfig,
+            ...config,
+            flowchartId: config.flowchartId ?? "",
+            type: UnitType.map,
+        };
+        super(schema);
+    }
+
+    setWorkflowId(id: string) {
+        this.setProp("workflowId", id);
+    }
+}
+
+mapUnitSchemaMixin(MapUnit.prototype);
+
+export default MapUnit;

package/src/js/units/ReduceUnit.ts

@@ -0,0 +1,46 @@
+import type { Constructor } from "@mat3ra/code/dist/js/utils/types";
+import JSONSchemasInterface from "@mat3ra/esse/dist/js/esse/JSONSchemasInterface";
+import type { AnyObject } from "@mat3ra/esse/dist/js/esse/types";
+import type { ReduceUnitSchema } from "@mat3ra/esse/dist/js/types";
+
+import { UnitType } from "../enums";
+import {
+    type ReduceUnitSchemaMixin,
+    reduceUnitSchemaMixin,
+} from "../generated/ReduceUnitSchemaMixin";
+import BaseUnit from "./BaseUnit";
+
+type Schema = ReduceUnitSchema;
+type Base = typeof BaseUnit<Schema> & Constructor<ReduceUnitSchemaMixin>;
+
+export type ReduceUnitConfig = Partial<Omit<Schema, "type" | "flowchartId">> &
+    Pick<Schema, "flowchartId">;
+
+class ReduceUnit extends (BaseUnit as Base) implements Schema {
+    declare toJSON: () => Schema & AnyObject;
+
+    declare _json: Schema & AnyObject;
+
+    static get jsonSchema() {
+        return JSONSchemasInterface.getSchemaById("workflow/unit/flowchart");
+    }
+
+    constructor(config: ReduceUnitConfig) {
+        const schema: Schema = {
+            name: UnitType.reduce,
+            mapFlowchartId: "",
+            input: [],
+            results: [],
+            preProcessors: [],
+            postProcessors: [],
+            monitors: [],
+            ...config,
+            type: UnitType.reduce,
+        };
+        super(schema);
+    }
+}
+
+reduceUnitSchemaMixin(ReduceUnit.prototype);
+
+export default ReduceUnit;