@platforma-sdk/workflow-tengo 2.14.0 → 2.15.0

package/README.md

@@ -1,6 +1,22 @@
+# Platforma Template Engine: Intelligent Workflows Made Simple
+
+*Transform static workflows into intelligent pipelines that make decisions as they process your data.*
+
+The Platforma Template Engine (powered by Tengo) enables bioinformaticians and scientists to:
+
+- Create workflows that automatically adapt to different data characteristics without manual intervention
+- Build reusable analysis components that can be combined into sophisticated processing pipelines
+- Define smart decision points where your workflow can take different paths based on results
+- Handle varying data inputs and quality issues with built-in adaptive logic
+- Focus on scientific questions instead of complex workflow orchestration
+- Scale from simple analyses to complex multi-stage pipelines with minimal code
+- Respond dynamically to unexpected data patterns or computational outcomes
+
+Perfect for researchers who need flexible data processing that can intelligently respond to experimental results, sequence quality, or computational findings - all without requiring extensive programming expertise.
+
 # Resources
 
 - [Tengo syntax](https://github.com/d5/tengo/blob/master/docs/tutorial.md)
 - [Tengo builtin functions](https://github.com/d5/tengo/blob/master/docs/builtins.md)
-- [Modules provided by the pl (`tx` and `plapi`)](https://github.com/milaboratory/pl/blob/main/controllers/templates/pkg/lang/interpreter_api_v1.go)
+
 

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 declare type TemplateFromFile = { readonly type: "from-file"; readonly path: string; };
-declare type TplName = "pframes.export-single-pcolumn" | "pframes.import-dir" | "pframes.map-pframe" | "waiter.waiter" | "workdir.save" | "workflow.build-ctx" | "exec.R.create-renv" | "exec.python.install-deps" | "pframes.export-multiple-pcolumns" | "exec.python.create-venv" | "exec.monetization_to_json" | "exec.exec" | "pframes.xsv-export-pframe" | "pframes.xsv-import-map" | "pframes.process-pcolumn-data" | "pframes.export-pframe";
+declare type TplName = "ll.get-field" | "pframes.export-single-pcolumn" | "pframes.import-dir" | "pframes.remove-nulls" | "waiter.waiter" | "workdir.save" | "workflow.build-ctx" | "exec.R.create-renv" | "exec.python.install-deps" | "pframes.export-multiple-pcolumns" | "exec.python.create-venv" | "exec.monetization_to_json" | "exec.exec" | "pframes.xsv-export-pframe" | "pframes.xsv-import-if-not-null" | "pframes.xsv-import-map" | "pframes.process-pcolumn-data" | "pframes.export-pframe";
 declare const Templates: Record<TplName, TemplateFromFile>;
 export { Templates };

package/dist/index.js

@@ -1,7 +1,8 @@
 module.exports = { Templates: {
+  'll.get-field': { type: 'from-file', path: require.resolve('./tengo/tpl/ll.get-field.plj.gz') },
   'pframes.export-single-pcolumn': { type: 'from-file', path: require.resolve('./tengo/tpl/pframes.export-single-pcolumn.plj.gz') },
   'pframes.import-dir': { type: 'from-file', path: require.resolve('./tengo/tpl/pframes.import-dir.plj.gz') },
-  'pframes.map-pframe': { type: 'from-file', path: require.resolve('./tengo/tpl/pframes.map-pframe.plj.gz') },
+  'pframes.remove-nulls': { type: 'from-file', path: require.resolve('./tengo/tpl/pframes.remove-nulls.plj.gz') },
   'waiter.waiter': { type: 'from-file', path: require.resolve('./tengo/tpl/waiter.waiter.plj.gz') },
   'workdir.save': { type: 'from-file', path: require.resolve('./tengo/tpl/workdir.save.plj.gz') },
   'workflow.build-ctx': { type: 'from-file', path: require.resolve('./tengo/tpl/workflow.build-ctx.plj.gz') },
@@ -12,6 +13,7 @@ module.exports = { Templates: {
   'exec.monetization_to_json': { type: 'from-file', path: require.resolve('./tengo/tpl/exec.monetization_to_json.plj.gz') },
   'exec.exec': { type: 'from-file', path: require.resolve('./tengo/tpl/exec.exec.plj.gz') },
   'pframes.xsv-export-pframe': { type: 'from-file', path: require.resolve('./tengo/tpl/pframes.xsv-export-pframe.plj.gz') },
+  'pframes.xsv-import-if-not-null': { type: 'from-file', path: require.resolve('./tengo/tpl/pframes.xsv-import-if-not-null.plj.gz') },
   'pframes.xsv-import-map': { type: 'from-file', path: require.resolve('./tengo/tpl/pframes.xsv-import-map.plj.gz') },
   'pframes.process-pcolumn-data': { type: 'from-file', path: require.resolve('./tengo/tpl/pframes.process-pcolumn-data.plj.gz') },
   'pframes.export-pframe': { type: 'from-file', path: require.resolve('./tengo/tpl/pframes.export-pframe.plj.gz') }

package/dist/index.mjs

@@ -1,8 +1,9 @@
 import { resolve } from 'node:path';
 export const Templates = {
+  'll.get-field': { type: 'from-file', path: resolve(import.meta.dirname, './tengo/tpl/ll.get-field.plj.gz') },
   'pframes.export-single-pcolumn': { type: 'from-file', path: resolve(import.meta.dirname, './tengo/tpl/pframes.export-single-pcolumn.plj.gz') },
   'pframes.import-dir': { type: 'from-file', path: resolve(import.meta.dirname, './tengo/tpl/pframes.import-dir.plj.gz') },
-  'pframes.map-pframe': { type: 'from-file', path: resolve(import.meta.dirname, './tengo/tpl/pframes.map-pframe.plj.gz') },
+  'pframes.remove-nulls': { type: 'from-file', path: resolve(import.meta.dirname, './tengo/tpl/pframes.remove-nulls.plj.gz') },
   'waiter.waiter': { type: 'from-file', path: resolve(import.meta.dirname, './tengo/tpl/waiter.waiter.plj.gz') },
   'workdir.save': { type: 'from-file', path: resolve(import.meta.dirname, './tengo/tpl/workdir.save.plj.gz') },
   'workflow.build-ctx': { type: 'from-file', path: resolve(import.meta.dirname, './tengo/tpl/workflow.build-ctx.plj.gz') },
@@ -13,6 +14,7 @@ export const Templates = {
   'exec.monetization_to_json': { type: 'from-file', path: resolve(import.meta.dirname, './tengo/tpl/exec.monetization_to_json.plj.gz') },
   'exec.exec': { type: 'from-file', path: resolve(import.meta.dirname, './tengo/tpl/exec.exec.plj.gz') },
   'pframes.xsv-export-pframe': { type: 'from-file', path: resolve(import.meta.dirname, './tengo/tpl/pframes.xsv-export-pframe.plj.gz') },
+  'pframes.xsv-import-if-not-null': { type: 'from-file', path: resolve(import.meta.dirname, './tengo/tpl/pframes.xsv-import-if-not-null.plj.gz') },
   'pframes.xsv-import-map': { type: 'from-file', path: resolve(import.meta.dirname, './tengo/tpl/pframes.xsv-import-map.plj.gz') },
   'pframes.process-pcolumn-data': { type: 'from-file', path: resolve(import.meta.dirname, './tengo/tpl/pframes.process-pcolumn-data.plj.gz') },
   'pframes.export-pframe': { type: 'from-file', path: resolve(import.meta.dirname, './tengo/tpl/pframes.export-pframe.plj.gz') }

package/dist/tengo/lib/assets.lib.tengo

@@ -1,4 +1,4 @@
-/** API to retrieve assets packed with template code (like other templates). */
+
 
 plapi := import("plapi")
 json := import("json")
@@ -7,30 +7,30 @@ smart := import("@platforma-sdk/workflow-tengo:smart")
 swinfo := import("@platforma-sdk/workflow-tengo:assets.swinfo")
 maps := import("@platforma-sdk/workflow-tengo:maps")
 
-/**
- * Returns resource of template available in current execution context.
- *
- * @param tplName: string - full name of a template, including namespace (package name).
- * Local templates (within the same package) can omit namespace part and start the name with colon:
- *  - "@company/package:someTemplateName"
- *  - ":myLocalTemplate"
- *
- * @return template: smart.resource - resource of tengo template with given name.
- */
+
+
+
+
+
+
+
+
+
+
 importTemplate := func(tplName) {
 	return smart.resource(plapi.getTemplateId(tplName))
 }
 
-/**
- * Returns asset description suitable for 'exec' operations.
- * Asset is the way to put static files into working directory before execution of the command.
- *
- * @param assetName: string - full name of asset entrypoint, including namespace (NPM package name).
- *                            Local software entrypoints (within the same package) can omit namespace
- *                            part and start the name with colon:
- *                              - "@company/package:some-software"
- *                              - ":my-local-software"
- */
+
+
+
+
+
+
+
+
+
+
 importAsset := func(assetName) {
 	asset := plapi.getSoftwareInfo(assetName)
 	return ll.toStrict({
@@ -45,13 +45,13 @@ importAsset := func(assetName) {
 	})
 }
 
-/**
- * Checks if given item is an asset info
- *
- * @param toCheck: any - item to check
- *
- * @return isAsset: boolean - true for asset info, loaded with importAsset()
- */
+
+
+
+
+
+
+
 isAssetInfo := func(toCheck) {
 	if !ll.isMap(toCheck) {
 		return false

package/dist/tengo/lib/assets.swinfo.lib.tengo

@@ -1,6 +1,6 @@
-/**
- * A file that contains software info constructors and related functions.
- */
+
+
+
 
 plapi := import("plapi")
 ll := import("@platforma-sdk/workflow-tengo:ll")
@@ -8,9 +8,9 @@ maps := import("@platforma-sdk/workflow-tengo:maps")
 smart := import("@platforma-sdk/workflow-tengo:smart")
 json := import("json")
 
-/**
- * Creates a software info by sw that is got from backend.
- */
+
+
+
 newSoftwareInfo := func(sw) {
 	return ll.toStrict({
 		_type: "softwareDescriptor",
@@ -24,28 +24,28 @@ newSoftwareInfo := func(sw) {
 	})
 }
 
-/**
- * Returns software description suitable for 'exec' operations.
- *
- * @param swName: string - full name of the software entrypoint, including namespace (NPM package name).
- *                         Local software entrypoints (within the same package) can omit namespace part
- *                         and start the name with colon:
- *                           - "@company/package:some-oftware"
- *                           - ":my-local-software"
- *
- * @return softwareInfo: softwareInfo - structure with software info.
- */
+
+
+
+
+
+
+
+
+
+
+
 importSoftware := func(swName) {
 	return newSoftwareInfo(plapi.getSoftwareInfo(swName))
 }
 
-/**
- * Checks if given item is a software info
- *
- * @param toCheck: any - item to check
- *
- * @return isSoftware: boolean - true for software info, loaded with importSoftware()
- */
+
+
+
+
+
+
+
 isSoftwareInfo := func(toCheck) {
 	if !ll.isMap(toCheck) {
 		return false

package/dist/tengo/lib/constants.lib.tengo

@@ -1,11 +1,13 @@
-// constants
+
 
 ll := import("@platforma-sdk/workflow-tengo:ll")
 
+RTYPE_NULL                := { Name: "Null",              Version: "1" }
+
 RTYPE_JSON                := { Name: "json/object",       Version: "1" }
 
 RTYPE_MAP                 := { Name: "std/map",           Version: "1" }
-// @TODO this should be deleted once we align on map type name
+
 RTYPE_MAP_ALT             := { Name: "StdMap",            Version: "1" }
 RTYPE_MAP_EPH             := { Name: "EphStdMap",         Version: "1" }
 
@@ -34,7 +36,7 @@ RTYPE_WORKDIR_FILL_RULES  := { Name: "WorkdirFill/rules", Version: "1" }
 RTYPE_WORKDIR_SAVE        := { Name: "WorkdirSave",       Version: "1" }
 RTYPE_WORKDIR_SAVE_RULES  := { Name: "WorkdirSave/rules", Version: "1" }
 
-/** Main resource type of representing a PL error */
+
 RTYPE_JSON_ERROR          := { Name: "json/resourceError", Version: "1"}
 
 FTYPE_OTW                 := "OTW" // Generic one-time writable field. The value of this field can be set only once.
@@ -50,6 +52,7 @@ export ll.toStrict({
 	FTYPE_OUTPUT                : FTYPE_OUTPUT,
 	FTYPE_DYNAMIC               : FTYPE_DYNAMIC,
 
+	RTYPE_NULL                  : RTYPE_NULL,
 	RTYPE_BINARY_MAP            : RTYPE_BINARY_MAP,
 	RTYPE_BINARY_VALUE          : RTYPE_BINARY_VALUE,
 	RTYPE_BLOB_MAP              : RTYPE_BLOB_MAP,

package/dist/tengo/lib/exec.R.internal.lib.tengo

@@ -33,8 +33,8 @@ runRBuilder := func(operationMode, wd, rPackage, rDescriptor) {
 		envTyped("RENV_PATHS_CACHE", t, path.join("{R}", "renv-root", "cache"))
 
 	if (operationMode != "dev-local") {
-		// In production we can use only locally cached packages: most of commercials have
-		// Platforma Backend executed in a very restricted environment with limited access to the internet.
+
+
 		builder.envTyped("RENV_CONFIG_REPOS_OVERRIDE", t, path.join("{R}", "packages"))
 	}
 

package/dist/tengo/lib/exec.R.lib.tengo

@@ -67,67 +67,67 @@ rVenvBuilder := func() {
 			return self
 		},
 
-		/**
-		 * Sets the cache time in milliseconds.
-		 *
-		 * @param millis: number
-		 */
+
+
+
+
+
 		cacheMillis: func(millis) {
 			ll.assert(is_int(millis) && millis > 0, "exec.R.cacheMillis: cache time must be a number of milliseconds")
 			cache = millis * times.millisecond
 			return self
 		},
 
-		/**
-		 * Sets the cache time in seconds.
-		 *
-		 * @param seconds: number
-		 */
+
+
+
+
+
 		cacheSeconds: func(seconds) {
 			ll.assert(is_int(seconds) && seconds > 0, "exec.R.cacheSeconds: cache time must be a number of seconds")
 			cache = seconds * times.second
 			return self
 		},
 
-		/**
-		 * Sets the cache time in minutes.
-		 *
-		 * @param minutes: number
-		 */
+
+
+
+
+
 		cacheMinutes: func(minutes) {
 			ll.assert(is_int(minutes) && minutes > 0, "exec.R.cacheMinutes: cache time must be a number of minutes")
 			cache = minutes * times.minute
 			return self
 		},
 
-		/**
-		 * Sets the cache time in hours.
-		 *
-		 * @param hours: number
-		 */
+
+
+
+
+
 		cacheHours: func(hours) {
 			ll.assert(is_int(hours) && hours > 0, "exec.R.cacheHours: cache time must be a number of hours")
 			cache = hours * times.hour
 			return self
 		},
 
-		/**
-		 * Sets the cache time in days
-		 *
-		 * @param days: number
-		 */
+
+
+
+
+
 		cacheDays: func(days) {
 			ll.assert(is_int(days) && days > 0, "exec.R.cacheDays: cache time must be a number of days")
 			cache = days * times.hour * 24
 			return self
 		},
 
-		/**
-		 * @deprecated, use cacheMillis, cacheSeconds, cacheMinutes, cacheHours and cacheDays instead.
-		 * Sets the cache time.
-		 *
-		 * @param time: duration - the cache time from 'times' library.
-		 */
+
+
+
+
+
+
 		cache: func(time) {
 			ll.assert(
 				is_int(time) && time > times.millisecond,
@@ -156,20 +156,20 @@ rVenvBuilder := func() {
 
 			self := undefined
 			self = ll.toStrict(oop.inherit(tpl, {
-				/**
-				 * R virtual environment with all dependencies installed.
-				 *
-				 * @return renv: smart.field - a reference to the R portable run environment.
-				 */
+
+
+
+
+
 				venv: func() {
 					return tpl.output(_OUTPUT_RUN_ENV, cache)
 				},
 
-				/**
-				 * R runtime used for R virtual environment creation.
-				 *
-				 * @return R: smart.Field - a reference to the R runtime.
-				 */
+
+
+
+
+
 				R: func() {
 					return rPkg
 				}

package/dist/tengo/lib/exec.descriptor.lib.tengo

@@ -1,6 +1,6 @@
-/** Everything about software descriptors
- * The scheme is here:
- * https://github.com/milaboratory/platforma/blob/main/tools/package-builder/src/core/renderer.ts#L161 */
+
+
+
 
 
 runEnvScheme := {

package/dist/tengo/lib/exec.internal.lib.tengo

@@ -1,9 +1,9 @@
-/**
- * Internal 'exec' module library.
- *
- * NOT INTENDEND FOR USE OUTSIDE 'exec' MODULE.
- * May completely change API from release to release.
- */
+
+
+
+
+
+
 
 ll := import("@platforma-sdk/workflow-tengo:ll")
 feats := import("@platforma-sdk/workflow-tengo:feats")
@@ -22,7 +22,7 @@ constants := import("@platforma-sdk/workflow-tengo:exec.constants")
 desc := import("@platforma-sdk/workflow-tengo:exec.descriptor")
 validation := import("@platforma-sdk/workflow-tengo:validation")
 
-// Variables, substituted in command arguments and environment variable values.
+
 _ARG_VAR_PKG            := "pkg"  // abs path to software package
 _ARG_VAR_JAVA           := "java" // abs path to 'java' run environment
 _ARG_VAR_PYTHON         := "python" // abs path to 'python' run environment
@@ -30,7 +30,7 @@ _ARG_VAR_R              := "R" // abs path to 'R' run environment runtime
 _ARG_VAR_R_VENV         := "rVenv" // abs path to 'R' portable virtual environment
 _ARG_VAR_MNZ            := "monetization" // monetization env value
 
-/** Converts the args above to the expressions. */
+
 _expr := func(varName) {
 	return "{" + varName + "}"
 }
@@ -42,13 +42,13 @@ _newTypedArg := func(type, value) {
 	})
 }
 
-/**
- * Create new argument with a type. The type can be either string, expression or variable.
- * Decides whether we need a simple argument or an expression one.
- * Until 15 Mar 2025, we keep deprecated variable arguments.
- *
- * @param isString: boolean - whether it is a string or a difficult (expression) argument.
- */
+
+
+
+
+
+
+
 _newArg := func(isString, value) {
 	if isString {
 		return _newTypedArg(constants.ARG_TYPE_STRING, value)
@@ -60,7 +60,7 @@ _newArg := func(isString, value) {
 }
 
 _newRefVar := func(varName, refName, reference) {
-	// deprecated, remove on 15 Mar 2025
+
 	if !feats.commandExpressions {
 		return ll.toStrict({
 			varName: "{" + varName + "}",
@@ -178,8 +178,8 @@ _loadRRunEnvironment := func(operationMode, descriptor, softName, softPkg) {
 	}
 
 	if (operationMode != "dev-local") {
-		// In production we can use only locally cached packages: most of commercials have
-		// Platforma Backend executed in a very restricted environment with limited access to the internet.
+
+
 		envs["RENV_CONFIG_REPOS_OVERRIDE"] = _newArg(false, path.join(_expr(_ARG_VAR_R), "packages"))
 	}
 
@@ -207,17 +207,17 @@ _loadRunEnvironment := func(operationMode, descriptor, softName, softPackage) {
 	ll.panic("run environment type %q is not currently supported by workflow-sdk",	descriptor.runEnv.type)
 }
 
-/**
- * @param operationMode: "remote" | "dev-local"
- */
+
+
+
 _binPackageCallOptions := func(operationMode, softwareName, variables, descriptor, softPackage) {
 	customPaths := []
 	envs := ll.toStrict({})
 	args := []
 	runEnvType := "binary"
 
-	// Real command should be:
-	//   [<runEnv bin>] [<runEnv options>] [<entrypoint bin>] [<entrypoint options>] <cmd> <args>
+
+
 	if (maps.containsKey(descriptor, "runEnv")) {
 		runEnvInfo := _loadRunEnvironment(operationMode, descriptor, softwareName, softPackage)
 
@@ -280,10 +280,10 @@ _remotePackageCallOptions := func(softwareName, binaryDescriptor) {
 	return _binPackageCallOptions("remote", softwareName, variables, binaryDescriptor, softPackage)
 }
 
-/** Turns a given software to a list of options that needs to be passed to run cmd builder.
- * Creates resources to install a software
- * and runs R or Python env builder templates
- * if it's necessary. */
+
+
+
+
 swToRunCmdOptions := func(softwareName, softwareVersion, softwareDescriptor) {
 	ll.assert(is_string(softwareName),
 		"exec.internal.swToRunCmdOptions: software name must be a string, got %v", softwareName)
@@ -303,8 +303,8 @@ swToRunCmdOptions := func(softwareName, softwareVersion, softwareDescriptor) {
 			softwareName, softwareVersion)
 	}
 
-	// Clone result fields explicitly here
-	// just to have a gist of what the function returns.
+
+
 	return ll.toStrict({
 		runEnvType: result.runEnvType,
 		variables: result.variables,
@@ -320,9 +320,9 @@ binaryRunOptions := func(runOptions, mnzEnvs) {
 
 	runCmdOpts := undefined
 	if (is_undefined(ll.fromStrict(runOptions).software)) {
-		//
-		// Simple local command run, no software packages involved (backward compatibility)
-		//
+
+
+
 		runCmdOpts = _directCallOptions(runOptions)
 	} else {
 		software := runOptions.software
@@ -331,10 +331,10 @@ binaryRunOptions := func(runOptions, mnzEnvs) {
 		runCmdOpts = swToRunCmdOptions(software.name, software.version, descriptor)
 	}
 
-	// adds exec builder's defined options from run options.
-	// If argsTyped or envsTyped are set (which is a new API from exec.builder),
-	// then pass them directly.
-	// Otherwise, pass args and envs the old way, without possible expression evaluating.
+
+
+
+
 	opts := ll.fromStrict(runOptions)
 	shouldUseNewTyped := !is_undefined(opts.argsTyped) || !is_undefined(opts.envsTyped)
 
@@ -351,8 +351,8 @@ binaryRunOptions := func(runOptions, mnzEnvs) {
 	}
 
 	for name, val in mnzEnvs { // can be empty
-		// if it's not empty, then we create an env that has
-		// a result of monetization client.
+
+
 		runCmdOpts.envs[name] = _newArg(false, _expr(_ARG_VAR_MNZ))
 
 		runCmdOpts.variables = append(runCmdOpts.variables,
@@ -366,18 +366,18 @@ binaryRunOptions := func(runOptions, mnzEnvs) {
 prepareCommandRun := func(wd, opts) {
 	runBuilder := runcmd.builder(wd)
 
-	// Make installed packages to be available for the command run
+
 	for varInfo in opts.variables {
 		runBuilder.ref(varInfo.refName, varInfo.reference)
 		runBuilder.substitutionRule(varInfo.varName, varInfo.refName)
 	}
 
-	// Patch command's PATH env variable
+
 	for p in opts.customPaths {
 		runBuilder.addToPath(p.type, p.value)
 	}
 
-	// Configure environment variables required for correct command run environment setup
+
 	for name, value in opts.envs {
 		runBuilder.envTyped(name, value.type, value.value)
 	}