@platforma-sdk/workflow-tengo 2.9.6 → 2.9.7

package/dist/tengo/lib/exec.runenv.lib.tengo

@@ -1,6 +1,6 @@
-
-
-
+/**
+ * A library for run environments creation and bootstrapping.
+ */
 
 ll := import("@platforma-sdk/workflow-tengo:ll")
 smart := import("@platforma-sdk/workflow-tengo:smart")
@@ -18,103 +18,103 @@ _OUTPUT_RUN_ENV       := "runEnv"
 _OUTPUT_WD_OUT        := "workdirOut"
 
 saveBuilder := func(wd) {
-self := undefined
-
-pathsToSave := []
-envType := ""
-
-packagesMap := {}
-
-self = {
-addPath: func(path) {
-validation.assertJsonSchema(path, "string", "runenv.saveBuilder.addPath: <path> must be string")
-
-pathsToSave = append(pathsToSave, path)
-return self
-},
-
-envType: func(type) {
-validation.assertJsonSchema(type, "string", "runenv.saveBuilder.envType: <type> must be string")
-
-envType = type
-return self
-},
-
-
-
-
-addPackage: func(key, pkgRef) {
-ll.assert(!maps.containsKey(packagesMap, key), "runenv.saveBuilder.addPackage: package %q was already added to SaveRunEnv builder", key)
-validation.assertJsonSchema(pkgRef, validation.reference, "runenv.saveBuilder.addPackage: <pkgRef> must be reference")
-
-packagesMap[key] = pkgRef
-return self
-},
-
-build: func() {
-ll.assert(envType != "", "runenv.saveBuilder.build: environment type is not set")
-
-envSaver := smart.ephemeralBuilder(_RTYPE_SAVE_RUN_ENV)
-
-envSaver.getField(_INPUT_WD_IN).set(wd)
-
-envSaver.getField(_INPUT_SETTINGS).
-set(smart.createJsonResource({
-paths: pathsToSave,
-type: envType
-}))
-
-envSaver.getField(_INPUT_PACKAGES_MAP).
-set(smart.createMapResource(packagesMap))
-
-return oop.inherit(envSaver.lockAndBuild(), {
-
-
-
-
-
-
-runEnv: func() {
-return envSaver.getField(_OUTPUT_RUN_ENV)
-},
-
-
-
-
-
-
-
-workdir: func() {
-return envSaver.getField(_OUTPUT_WD_OUT)
-}
-})
-}
-}
-
-return self
+	self := undefined
+
+	pathsToSave := []
+	envType := ""
+
+	packagesMap := {}
+
+	self = {
+		addPath: func(path) {
+			validation.assertJsonSchema(path, "string", "runenv.saveBuilder.addPath: <path> must be string")
+
+			pathsToSave = append(pathsToSave, path)
+			return self
+		},
+
+		envType: func(type) {
+			validation.assertJsonSchema(type, "string", "runenv.saveBuilder.envType: <type> must be string")
+
+			envType = type
+			return self
+		},
+
+		/**
+		 * Bind package to created run environment, holding it as long as run environment exists.
+		 */
+		addPackage: func(key, pkgRef) {
+			ll.assert(!maps.containsKey(packagesMap, key), "runenv.saveBuilder.addPackage: package %q was already added to SaveRunEnv builder", key)
+			validation.assertJsonSchema(pkgRef, validation.reference, "runenv.saveBuilder.addPackage: <pkgRef> must be reference")
+
+			packagesMap[key] = pkgRef
+			return self
+		},
+
+		build: func() {
+			ll.assert(envType != "", "runenv.saveBuilder.build: environment type is not set")
+
+			envSaver := smart.ephemeralBuilder(_RTYPE_SAVE_RUN_ENV)
+
+			envSaver.getField(_INPUT_WD_IN).set(wd)
+
+			envSaver.getField(_INPUT_SETTINGS).
+				set(smart.createJsonResource({
+					paths: pathsToSave,
+					type: envType
+				}))
+
+			envSaver.getField(_INPUT_PACKAGES_MAP).
+				set(smart.createMapResource(packagesMap))
+
+			return oop.inherit(envSaver.lockAndBuild(), {
+				/**
+				 * Run environment reference
+				 *
+				 * @return runEnv: smart.field - field where run environment appears
+				 *                               after operation is done
+				 */
+				runEnv: func() {
+					return envSaver.getField(_OUTPUT_RUN_ENV)
+				},
+
+				/**
+				 * Working directory reference after operation is complete
+				 *
+				 * @return wd: smart.field - field where workdir appears after
+				 *                           operation is done
+				 */
+				workdir: func() {
+					return envSaver.getField(_OUTPUT_WD_OUT)
+				}
+			})
+		}
+	}
+
+	return self
 }
 
 loadDependencyFiles := func(packageRef, dependencies) {
-if len(dependencies) == 0 {
-return {}
-}
+	if len(dependencies) == 0 {
+		return {}
+	}
 
-depsMap := {}
+	depsMap := {}
 
-loader := pkg.pkgFileLoader(packageRef)
-for depName, fileName in dependencies {
-loader.saveFile(fileName)
-}
-deps := loader.load()
+	loader := pkg.pkgFileLoader(packageRef)
+	for depName, fileName in dependencies {
+		loader.saveFile(fileName)
+	}
+	deps := loader.load()
 
-for depName, fileName in dependencies {
-depsMap[depName] = deps.getFile(fileName)
-}
+	for depName, fileName in dependencies {
+		depsMap[depName] = deps.getFile(fileName)
+	}
 
-return depsMap
+	return depsMap
 }
 
 export ll.toStrict({
-saveBuilder                        : saveBuilder,
-loadDependencyFiles                : loadDependencyFiles
+	saveBuilder                        : saveBuilder,
+	loadDependencyFiles                : loadDependencyFiles
 })

package/dist/tengo/lib/exec.stream.lib.tengo

@@ -1,6 +1,6 @@
-
-
-
+/**
+ * A library for working with streams.
+ */
 
 ll := import("@platforma-sdk/workflow-tengo:ll")
 smart := import("@platforma-sdk/workflow-tengo:smart")
@@ -10,55 +10,55 @@ file := import("@platforma-sdk/workflow-tengo:file")
 _RTYPE_CREATE_STREAM := { Name: "CreateStream", Version: "2" }
 _RTYPE_STREAM_MANAGER := { Name: "StreamManager", Version: "2" }
 
-
-
-
-
-
-
-
+/**
+ * Creates a stream in the specified workdir for the given file path.
+ *
+ * @param workdir: reference - a reference to the workdir.
+ * @param filePath: string - the path of the file in the workdir.
+ * @return stream: resource - a smart.resource to the created stream with an output field.
+ */
 _create := func(workdir, filePath) {
-stream := smart.ephemeralBuilder(_RTYPE_CREATE_STREAM)
-stream.getField("workdir").set(workdir)
-stream.getField("filePath").setRefOrJson(filePath)
+	stream := smart.ephemeralBuilder(_RTYPE_CREATE_STREAM)
+	stream.getField("workdir").set(workdir)
+	stream.getField("filePath").setRefOrJson(filePath)
 
-return ll.toStrict(oop.inherit(stream.lockAndBuild(), {
-output: stream.outputs().stream
-}))
+	return ll.toStrict(oop.inherit(stream.lockAndBuild(), {
+		output: stream.outputs().stream
+	}))
 }
 
-
-
-
-
-
-
-
+/**
+ * Creates a special manager resource that has either a blob or a stream in the `stream` field.
+ *
+ * @param stream: reference - a reference to the stream.
+ * @param downloadableRef: reference - a reference to the downloadable content.
+ * @return manager: reference - a reference to the stream manager.
+ */
 _manager := func(stream, downloadableRef) {
-res := smart.structBuilder(_RTYPE_STREAM_MANAGER)
+	res := smart.structBuilder(_RTYPE_STREAM_MANAGER)
 
-res.getField("downloadable").set(downloadableRef)
-res.getField("stream").set(stream.output)
+	res.getField("downloadable").set(downloadableRef)
+	res.getField("stream").set(stream.output)
 
-return res.lockAndBuild()
+	return res.lockAndBuild()
 }
 
-
-
-
-
-
-
-
-
+/**
+ * Creates a stream and manages its downloadable content.
+ *
+ * @param workdirBefore: reference - a reference to the workdir before RunCommand were executed.
+ * @param workdirAfter: reference - a reference to the resulted workdir field of RunCommand.
+ * @param filePath: string - the path of the file in the workdir.
+ * @return manager: reference - a reference to the stream manager.
+ */
 create := func(workdirBefore, workdirAfter, filePath) {
-stream := _create(workdirBefore, filePath)
-fileFuture := workdirAfter.files.getFutureInputField(filePath)
-downloadable := file.exportFile(fileFuture)
+	stream := _create(workdirBefore, filePath)
+	fileFuture := workdirAfter.files.getFutureInputField(filePath)
+	downloadable := file.exportFile(fileFuture)
 
-return _manager(stream, downloadable)
+	return _manager(stream, downloadable)
 }
 
 export ll.toStrict({
-create: create
+	create: create
 })

package/dist/tengo/lib/file.internal.lib.tengo

@@ -1,13 +1,13 @@
-
-
-
-
-
-
-
-
-
-
+/**
+ * Internal functions to work with blobs.
+ *
+ * This file contains functions intended for use only within workflow tengo SDK.
+ * Their parameters list, results and other parts of the interface may change from
+ * vertion to version without prior notice.
+ *
+ * DO NOT USE them in workflows or templates directly.
+ *
+ */
 
 ll := import("@platforma-sdk/workflow-tengo:ll")
 smart := import("@platforma-sdk/workflow-tengo:smart")
@@ -15,87 +15,87 @@ validation := import("@platforma-sdk/workflow-tengo:validation")
 
 json := import("json")
 
-
-
-
+//
+// Resource types:
+//
 
 RTYPE_BLOB_IMPORT_EXTERNAL := { Name: "BlobImportExternal", Version: "1" }
 RTYPE_BLOB_IMPORT_INTERNAL := { Name: "BlobImportInternal", Version: "1" }
 RTYPE_BLOB_UPLOAD := { Name: "BlobUpload", Version: "1" }
 RTYPE_BLOB_DOWNLOAD := { Name: "BlobDownload", Version: "2" }
 
-
-
-
-
-
-
+/**
+ * Create a task for importing blob from external service by URL
+ * Produces 2 fields:
+ *  'file' - reference to blob to appear once import gets finished.
+ *  'handle' - reference to resource with 'progress' API.
+ */
 createBlobImportExternal := func(settings) {
-validation.assertJsonSchema(settings, {
-"dataURL": "string",
-"dataHeaders,?": [["string"]],
-"dataVersion,?": "string"
-})
-
-importer := smart.structBuilder(RTYPE_BLOB_IMPORT_EXTERNAL, json.encode(settings)).lockAndBuild()
-
-return ll.toStrict({
-file: importer.getField("blob"),
-handle: importer.getField("handle")
-})
+	validation.assertJsonSchema(settings, {
+		"dataURL": "string",
+		"dataHeaders,?": [["string"]],
+		"dataVersion,?": "string"
+	})
+
+	importer := smart.structBuilder(RTYPE_BLOB_IMPORT_EXTERNAL, json.encode(settings)).lockAndBuild()
+
+	return ll.toStrict({
+		file: importer.getField("blob"),
+		handle: importer.getField("handle")
+	})
 }
 
-
-
-
-
-
-
+/**
+ * Create a task for importing blob from one of preconfigured storages.
+ * Produces 2 fields:
+ *  'file' - reference to blob to appear once import gets finished.
+ *  'handle' - reference to resource with 'progress' API.
+ */
 createBlobImportInternal := func(settings) {
-validation.assertJsonSchema(settings, {
-"path": "string",
-"storageId": "string",
-"maxSpeedBytes,?": "number",
-"dataVersion,?": "string"
-})
-
-importer := smart.structBuilder(RTYPE_BLOB_IMPORT_INTERNAL, json.encode(settings)).lockAndBuild()
-
-return ll.toStrict({
-file: importer.getField("blob"),
-handle: importer.getField("handle")
-})
+	validation.assertJsonSchema(settings, {
+		"path": "string",
+		"storageId": "string",
+		"maxSpeedBytes,?": "number",
+		"dataVersion,?": "string"
+	})
+
+	importer := smart.structBuilder(RTYPE_BLOB_IMPORT_INTERNAL, json.encode(settings)).lockAndBuild()
+
+	return ll.toStrict({
+		file: importer.getField("blob"),
+		handle: importer.getField("handle")
+	})
 }
 
-
-
-
-
-
-
+/**
+ * Create a task for getting a blob directly from the user via 'upload' procedure.
+ * Produces 2 fields:
+ *  'file' - reference to blob to appear once upload gets finished.
+ *  'handle' - reference to resource with 'progress' and 'upload' APIs.
+ */
 createBlobUpload := func(settings) {
-validation.assertJsonSchema(settings, {
-"modificationTime": "string",
-"localPath": "string",
-"pathSignature": "string",
-"sizeBytes": "string"
-})
-
-uploader := smart.structBuilder(RTYPE_BLOB_UPLOAD, json.encode(settings)).lockAndBuild()
-
-return ll.toStrict({
-file: uploader.getField("blob"),
-handle: uploader.getField("handle")
-})
+	validation.assertJsonSchema(settings, {
+		"modificationTime": "string",
+		"localPath": "string",
+		"pathSignature": "string",
+		"sizeBytes": "string"
+	})
+
+	uploader := smart.structBuilder(RTYPE_BLOB_UPLOAD, json.encode(settings)).lockAndBuild()
+
+	return ll.toStrict({
+		file: uploader.getField("blob"),
+		handle: uploader.getField("handle")
+	})
 }
 
 export ll.toStrict({
-RTYPE_BLOB_IMPORT_EXTERNAL      : RTYPE_BLOB_IMPORT_EXTERNAL,
-RTYPE_BLOB_IMPORT_INTERNAL      : RTYPE_BLOB_IMPORT_INTERNAL,
-RTYPE_BLOB_UPLOAD               : RTYPE_BLOB_UPLOAD,
-RTYPE_BLOB_DOWNLOAD             : RTYPE_BLOB_DOWNLOAD,
-
-createBlobImportExternal        : createBlobImportExternal,
-createBlobImportInternal        : createBlobImportInternal,
-createBlobUpload                : createBlobUpload
+	RTYPE_BLOB_IMPORT_EXTERNAL      : RTYPE_BLOB_IMPORT_EXTERNAL,
+	RTYPE_BLOB_IMPORT_INTERNAL      : RTYPE_BLOB_IMPORT_INTERNAL,
+	RTYPE_BLOB_UPLOAD               : RTYPE_BLOB_UPLOAD,
+	RTYPE_BLOB_DOWNLOAD             : RTYPE_BLOB_DOWNLOAD,
+
+	createBlobImportExternal        : createBlobImportExternal,
+	createBlobImportInternal        : createBlobImportInternal,
+	createBlobUpload                : createBlobUpload
 })

package/dist/tengo/lib/file.lib.tengo

@@ -1,15 +1,15 @@
-
-
-
-
-
-
-
-
-
-
-
-
+/**
+ * Functions to work with blobs / files.
+ *
+ * Allowing to create resources to import files from configured storages
+ * as well as creation of resources to facilitate file upload from the
+ * users machine.
+ *
+ * This library exposes rather high level functions working with
+ * ImportFileHandle, encoding user intent to import a file from a pl-wide
+ * configured storage or to upload file from users side in a universal
+ * string representation.
+ */
 
 ll := import("@platforma-sdk/workflow-tengo:ll")
 smart := import("@platforma-sdk/workflow-tengo:smart")
@@ -18,59 +18,59 @@ blobs := import("@platforma-sdk/workflow-tengo:file.internal")
 
 json := import("json")
 
-
-
-
-
-
-
-
-
-
-
-
-
-
+/**
+ * Imports an external file into the workflow, either from pre-configured storage,
+ * available from the pl instance, or from the client machine via upload.
+ *
+ * @param importFileHandle string a string file import handle, in most cases obtained via the
+ *                         LS controller in UI
+ *
+ * @return a structure with two field references
+ *         {
+ *             file: field,
+ *             handle: field
+ *         }
+ */
 importFile := func(importFileHandle) {
-validation.assertJsonSchema(
-importFileHandle,
-`string,regex=^(upload://upload/.*|index://index/.*)`
-)
-
-url := ll.parseUrl(importFileHandle)
-path := url.Path[1:] // trim  "/"
-
-settings := json.decode(path)
-
-if url.Scheme == "upload" {
-ll.assert(url.Host == "upload", "wrong 'host' in import file handle. Expected: 'upload', found: '", url.Host, "'")
-return blobs.createBlobUpload(settings)
-} else if url.Scheme == "index" {
-ll.assert(url.Host == "index", "wrong 'host' in import file handle. Expected 'index', found: '", url.Host, "'")
-return blobs.createBlobImportInternal(settings)
-} else if (url.Scheme == "download") {
-ll.assert(url.Host == "download", "wrong 'host' in import file handle. Expected: 'download', found: '", url.Host, "'")
-return blobs.createBlobImportExternal(settings)
-} else {
-ll.panic("Unknown file import handle schema: ", url.Scheme)
-}
+	validation.assertJsonSchema(
+		importFileHandle,
+		`string,regex=^(upload://upload/.*|index://index/.*)`
+	)
+
+	url := ll.parseUrl(importFileHandle)
+	path := url.Path[1:] // trim  "/"
+
+	settings := json.decode(path)
+
+	if url.Scheme == "upload" {
+		ll.assert(url.Host == "upload", "wrong 'host' in import file handle. Expected: 'upload', found: '", url.Host, "'")
+		return blobs.createBlobUpload(settings)
+	} else if url.Scheme == "index" {
+		ll.assert(url.Host == "index", "wrong 'host' in import file handle. Expected 'index', found: '", url.Host, "'")
+		return blobs.createBlobImportInternal(settings)
+	} else if (url.Scheme == "download") {
+		ll.assert(url.Host == "download", "wrong 'host' in import file handle. Expected: 'download', found: '", url.Host, "'")
+		return blobs.createBlobImportExternal(settings)
+	} else {
+		ll.panic("Unknown file import handle schema: ", url.Scheme)
+	}
 }
 
-
-
-
-
+/**
+ * Given a reference to the file, converts it into resource that can be
+ * downloaded from the UI side.
+ */
 exportFile := func(blob) {
-builder := smart.structBuilder(blobs.RTYPE_BLOB_DOWNLOAD)
+	builder := smart.structBuilder(blobs.RTYPE_BLOB_DOWNLOAD)
 
-builder.createInputField("blob").set(blob)
+	builder.createInputField("blob").set(blob)
 
-downloader := builder.lockAndBuild()
+	downloader := builder.lockAndBuild()
 
-return downloader.getField("downloadable")
+	return downloader.getField("downloadable")
 }
 
 export ll.toStrict({
-importFile: importFile,
-exportFile: exportFile
+	importFile: importFile,
+	exportFile: exportFile
 })