@platforma-sdk/workflow-tengo 2.9.6 → 2.9.8

package/dist/tengo/lib/workdir.lib.tengo

@@ -1,6 +1,6 @@
-
-
-
+/**
+ * Gives an interface for working with workdirs.
+ */
 
 json := import("json")
 
@@ -17,356 +17,356 @@ validation := import("@platforma-sdk/workflow-tengo:validation")
 render := import("@platforma-sdk/workflow-tengo:render")
 
 create := func() {
-wd := smart.ephemeralBuilder(constants.RTYPE_WORKDIR_CREATE).lockAndBuild()
-return wd.getField("workdir")
+	wd := smart.ephemeralBuilder(constants.RTYPE_WORKDIR_CREATE).lockAndBuild()
+	return wd.getField("workdir")
 }
 
 _getFileFillRule := func(filePath, extension) {
-return {
-type: "file",
-path: filePath,
-permissions: 0o600,
-pathKey: filePath,
-blobKey: filePath,
-copyOptional: false,
-fileExtension: extension
-}
+	return {
+		type: "file",
+		path: filePath,
+		permissions: 0o600,
+		pathKey: filePath,
+		blobKey: filePath,
+		copyOptional: false,
+		fileExtension: extension
+	}
 }
 
 _getArchiveFillRule := func(dstDir, whatToExtract, archiveBlobKey) {
-extractRules := []
-for f in whatToExtract {
-extractRules = append(extractRules, {
-srcPath: f,
-dstPath: f,
-filePerms: 0o600,
-dirPerms: 0o700
-})
+	extractRules := []
+	for f in whatToExtract {
+		extractRules = append(extractRules, {
+			srcPath: f,
+			dstPath: f,
+			filePerms: 0o600,
+			dirPerms: 0o700
+		})
+	}
+
+	return {
+		type: "archive",
+		path: dstDir,
+		blobKey: archiveBlobKey,
+		archiveType: "zip",
+		extractRules: extractRules
+	}
 }
 
-return {
-type: "archive",
-path: dstDir,
-blobKey: archiveBlobKey,
-archiveType: "zip",
-extractRules: extractRules
-}
-}
-
-
-
-
-
-
-
+/**
+ * Generates a value fill rule for a given file path.
+ *
+ * @param filePath: string - the path of the file.
+ * @return rule: map - the value fill rule.
+ */
 _getValueFillRule := func(filePath) {
-return {
-type: "value",
-path: filePath,
-permissions: 0o600,
-pathKey: filePath,
-valueKey: filePath
+	return {
+		type: "value",
+		path: filePath,
+		permissions: 0o600,
+		pathKey: filePath,
+		valueKey: filePath
+	}
 }
-}
-
-
-
-
-
-
 
+/**
+ * Generates a directory fill rule for a given directory.
+ *
+ * @param dir: string - the path of the directory.
+ * @return rule: map - the directory fill rule.
+ */
 _getDirFillRule := func(dir) {
-return {
-type: "dir",
-path: dir,
-permissions: 0o700,
-pathKey: ""
+	return {
+		type: "dir",
+		path: dir,
+		permissions: 0o700,
+		pathKey: ""
+	}
 }
-}
-
-
-
-
-
 
+/**
+ * Fills a workdir with files, values, and directories.
+ *
+ * @param workdir: reference - a reference to the workdir to fill.
+ * @return self: builder - a builder that adds files and directories to the workdir. */
 _fill := func(workdir) {
-ll.assert(smart.isReference(workdir), "workdir must be a reference to a resource or field")
-
-wd := smart.ephemeralBuilder(constants.RTYPE_WORKDIR_FILL)
-wd.getField("workdirIn").set(workdir)
-
-blobs := {}
-files := {}
-zipExtractions := {}
-values := {}
-dirs := {}
-
-self := undefined
-self = ll.toStrict(oop.inherit(wd, {
-_getAllDirs: func(fileName) {
-dirsWithFileName := path.getBasenameDirs(fileName)
-return slices.slice(dirsWithFileName, 0, -1)
-},
-
-_addDirs: func(fileName) {
-newDirs := self._getAllDirs(fileName)
-sets.add(dirs, newDirs...)
-},
-
-
-
-
-
-
-
-
-
-
-
-
-
-addFromZip: func(zipResource, destinationDir, pathsInArchive) {
-validation.assertJsonSchema(zipResource, validation.reference, "workdir.builder.addFromZip: <zipResource> is not smart.reference")
-validation.assertJsonSchema(destinationDir, "string", "workdir.builder.addFromZip: <destinationDir> is not a string. It must be a path inside working directory")
-
-if (is_undefined(pathsInArchive)) {
-pathsInArchive = []
-}
-validation.assertJsonSchema(pathsInArchive, ["string"], "workdir.builder.addFromZip: <pathsInArchive> must contain list of strings with paths inside archive")
-
-blobKey := ll.idToString(zipResource.id)
-
-if is_undefined(blobs[blobKey]) {
-blobs[blobKey] = zipResource
-}
-
-if is_undefined(zipExtractions[blobKey]) {
-zipExtractions[blobKey] = {}
-}
-
-if is_undefined(zipExtractions[blobKey][destinationDir]) || len(pathsInArchive) == 0 {
-zipExtractions[blobKey][destinationDir] = pathsInArchive
-return self
-}
-
-if (len(pathsInArchive) > 0) {
-zipExtractions[blobKey][destinationDir] = append(zipExtractions[blobKey][destinationDir], pathsInArchive...)
-}
-
-return self
-},
-
-
-
-
-
-
-
-addFile: func(fileName, fileResource) {
-validation.assertJsonSchema(fileName, "string")
-validation.assertJsonSchema(fileResource, validation.reference)
-
-files[fileName] = fileResource
-blobs[fileName] = fileResource
-self._addDirs(fileName)
-
-return self
-},
-
-
-
-
-
-
-addFiles: func(fileMap) {
-enum.each(fileMap, self.addFile)
-return self
-},
-
-
-
-
-
-
-
-writeFile: func(fileName, contentRef) {
-validation.assertJsonSchema(fileName, "string")
-values[fileName] = contentRef
-self._addDirs(fileName)
-
-return self
-},
-
-
-
-
-
-
-writeFiles: func(contentRefMap) {
-enum.each(contentRefMap, self.writeFile)
-return self
-},
-
-
-
-
-
-
-mkDir: func(dir) {
-sets.add(dirs, path.getBasenameDirs(dir))
-return self
-},
-
-
-
-
-
-
-build: func() {
-rules := []
-for dir, _ in dirs {
-rules = append(rules, _getDirFillRule(dir))
-}
-for fileName, _ in files {
-rules = append(rules, _getFileFillRule(fileName, path.getExtension(fileName)))
+	ll.assert(smart.isReference(workdir), "workdir must be a reference to a resource or field")
+
+	wd := smart.ephemeralBuilder(constants.RTYPE_WORKDIR_FILL)
+	wd.getField("workdirIn").set(workdir)
+
+	blobs := {}
+	files := {}
+	zipExtractions := {}
+	values := {}
+	dirs := {}
+
+	self := undefined
+	self = ll.toStrict(oop.inherit(wd, {
+		_getAllDirs: func(fileName) {
+			dirsWithFileName := path.getBasenameDirs(fileName)
+			return slices.slice(dirsWithFileName, 0, -1)
+		},
+
+		_addDirs: func(fileName) {
+			newDirs := self._getAllDirs(fileName)
+			sets.add(dirs, newDirs...)
+		},
+
+		/**
+		 * Adds files from given zip archive into working directory.
+		 *
+		 * @param zipResource: smart.reference - reference to zip archive to be extracted.
+		 * @param destinationDir: string - path inside working directory for files to be extracted from archive.
+		 *                                 Consider it as 'cd' before extraction. It makes all extracted files to be
+		 *                                 stored inside this directory.
+		 * @param pathsInArchive: string[] - paths inside the archive to be extracted into destinationDir.
+		 *                                   Empty array means 'unpack full archive'.
+		 *                                   Full file paths are preserved during extraction: the file 'a/b/file.txt' would
+		 *                                   be extracted into '<destinationDir>/a/b/file.txt', NOT '<destinationDir>/file.txt',
+		 */
+		addFromZip: func(zipResource, destinationDir, pathsInArchive) {
+			validation.assertJsonSchema(zipResource, validation.reference, "workdir.builder.addFromZip: <zipResource> is not smart.reference")
+			validation.assertJsonSchema(destinationDir, "string", "workdir.builder.addFromZip: <destinationDir> is not a string. It must be a path inside working directory")
+
+			if (is_undefined(pathsInArchive)) {
+				pathsInArchive = []
+			}
+			validation.assertJsonSchema(pathsInArchive, ["string"], "workdir.builder.addFromZip: <pathsInArchive> must contain list of strings with paths inside archive")
+
+			blobKey := ll.idToString(zipResource.id)
+
+			if is_undefined(blobs[blobKey]) {
+				blobs[blobKey] = zipResource
+			}
+
+			if is_undefined(zipExtractions[blobKey]) {
+				zipExtractions[blobKey] = {}
+			}
+
+			if is_undefined(zipExtractions[blobKey][destinationDir]) || len(pathsInArchive) == 0 {
+				zipExtractions[blobKey][destinationDir] = pathsInArchive
+				return self
+			}
+
+			if (len(pathsInArchive) > 0) {
+				zipExtractions[blobKey][destinationDir] = append(zipExtractions[blobKey][destinationDir], pathsInArchive...)
+			}
+
+			return self
+		},
+
+		/**
+		 * Adds a file to the workdir.
+		 *
+		 * @param fileName: string - the name of the file.
+		 * @param fileResource: reference - the file to add.
+		 */
+		addFile: func(fileName, fileResource) {
+			validation.assertJsonSchema(fileName, "string")
+			validation.assertJsonSchema(fileResource, validation.reference)
+
+			files[fileName] = fileResource
+			blobs[fileName] = fileResource
+			self._addDirs(fileName)
+
+			return self
+		},
+
+		/**
+		 * Adds multiple files to the workdir.
+		 *
+		 * @param fileMap: map[string]reference - a map of files.
+		 */
+		addFiles: func(fileMap) {
+			enum.each(fileMap, self.addFile)
+			return self
+		},
+
+		/**
+		 * Adds a file with a content to the workdir.
+		 *
+		 * @param fileName: string - the name of the file.
+		 * @param contentRef: reference|any - the content as a reference to add or the content itself.
+		 */
+		writeFile: func(fileName, contentRef) {
+			validation.assertJsonSchema(fileName, "string")
+			values[fileName] = contentRef
+			self._addDirs(fileName)
+
+			return self
+		},
+
+		/**
+		 * Adds multiple files with contents to the workdir.
+		 *
+		 * @param contentMap: map[string]any|reference - a map of references to a content or to a content itself.
+		 */
+		writeFiles: func(contentRefMap) {
+			enum.each(contentRefMap, self.writeFile)
+			return self
+		},
+
+		/**
+		 * Creates a possibly nested directory in the workdir.
+		 *
+		 * @param dir: string - the path of the directory.
+		 */
+		mkDir: func(dir) {
+			sets.add(dirs, path.getBasenameDirs(dir))
+			return self
+		},
+
+		/**
+		 * Builds the filled workdir.
+		 *
+		 * @return wd: reference - a reference to the filled workdir.
+		 */
+		build: func() {
+			rules := []
+			for dir, _ in dirs {
+				rules = append(rules, _getDirFillRule(dir))
+			}
+			for fileName, _ in files {
+				rules = append(rules, _getFileFillRule(fileName, path.getExtension(fileName)))
+			}
+			for fileName, _ in values {
+				rules = append(rules, _getValueFillRule(fileName))
+			}
+
+			for blobKey, directories in zipExtractions {
+				for dstDir, whatToExtract in directories {
+					rules = append(rules, _getArchiveFillRule(dstDir, whatToExtract, blobKey))
+				}
+			}
+
+			rulesRes := smart.createValueResource(
+				constants.RTYPE_WORKDIR_FILL_RULES,
+				json.encode(rules)
+			)
+			self.getField("rules").set(rulesRes)
+
+			self.getField("dataIn").set(smart.createBinaryMapResource(values))
+			self.getField("blobsIn").set(smart.createBlobMapResource(blobs))
+
+			return self.lockAndBuild().outputs().workdirOut
+		}
+	}))
+
+	return self
 }
-for fileName, _ in values {
-rules = append(rules, _getValueFillRule(fileName))
-}
-
-for blobKey, directories in zipExtractions {
-for dstDir, whatToExtract in directories {
-rules = append(rules, _getArchiveFillRule(dstDir, whatToExtract, blobKey))
-}
-}
-
-rulesRes := smart.createValueResource(
-constants.RTYPE_WORKDIR_FILL_RULES,
-json.encode(rules)
-)
-self.getField("rules").set(rulesRes)
-
-self.getField("dataIn").set(smart.createBinaryMapResource(values))
-self.getField("blobsIn").set(smart.createBlobMapResource(blobs))
-
-return self.lockAndBuild().outputs().workdirOut
-}
-}))
-
-return self
-}
-
-
-
-
-
 
+/**
+ * Creates and fills a workdir with files, contents, and directories. See _fill for futher documentation.
+ *
+ * @return self: builder - a builder that adds files and directories to the workdir.
+ */
 builder := func() {
-return _fill(create())
+	return _fill(create())
 }
 
-
-
-
-
-
-
+/**
+ * Saves a workdir.
+ *
+ * @param workdir: reference - a reference to the workdir to save.
+ * @return self: builder - the builder that helps adding save rules to the save workdir.
+ */
 save := func(workdir) {
-ll.assert(smart.isReference(workdir), "workdir must be a reference to a resource or field")
-
-
-files := {}
-
-filesContent := {}
-
-fileSets := {}
-
-fileSetsContent := {}
-
-self := undefined
-self = ll.toStrict({
-
-
-
-
-
-saveFile: func(fileName) {
-validation.assertJsonSchema(fileName, "string")
-sets.add(files, fileName)
-return self
-},
-
-
-
-
-
-
-saveFileContent: func(fileName) {
-validation.assertJsonSchema(fileName, "string")
-sets.add(filesContent, fileName)
-return self
-},
-
-
-
-
-
-
-
-saveFileSet: func(name, regex) {
-validation.assertJsonSchema(regex, "string")
-ll.assert(is_undefined(fileSets[name]), "file set with name '", name, "' is already in added")
-fileSets[name] = regex
-return self
-},
-
-
-
-
-
-
-
-saveFileSetContent: func(name, regex) {
-validation.assertJsonSchema(regex, "string")
-ll.assert(is_undefined(fileSetsContent[name]), "file set content with name '", name, "' is already in added")
-sets.add(fileSetsContent, regex)
-return self
-},
-
-
-
-
-
-
-build: func() {
-
-tpl := assets.importTemplate("@platforma-sdk/workflow-tengo:workdir.save")
-inputs := {
-workdir: workdir,
-files: files,
-filesContent: filesContent,
-fileSets: fileSets,
-fileSetsContent: fileSetsContent
-}
-
-wds := render.createEphemeral(tpl, inputs)
-
-return ll.toStrict({
-files: wds.output("files"),
-filesContent: wds.output("filesContent"),
-fileSets : wds.output("fileSets"),
-fileSetsContent : wds.output("fileSetsContent"),
-workdir: wds.output("workdir"),
-progress: wds.output("progress")
-})
-}
-})
-
-return self
+	ll.assert(smart.isReference(workdir), "workdir must be a reference to a resource or field")
+
+	// files to save
+	files := {}
+	// files to save their content
+	filesContent := {}
+	// file sets to save by regex
+	fileSets := {}
+	// file sets to save their content by regex
+	fileSetsContent := {}
+
+	self := undefined
+	self = ll.toStrict({
+		/**
+		 * Saves a file from the workdir.
+		 *
+		 * @param fileName: string - the name of the file.
+		 */
+		saveFile: func(fileName) {
+			validation.assertJsonSchema(fileName, "string")
+			sets.add(files, fileName)
+			return self
+		},
+
+		/**
+		 * Saves a file to a value resource from the workdir.
+		 *
+		 * @param fileName: string - the name of the file.
+		 */
+		saveFileContent: func(fileName) {
+			validation.assertJsonSchema(fileName, "string")
+			sets.add(filesContent, fileName)
+			return self
+		},
+
+		/**
+		 * Save files which names satisfy given regex rule
+		 *
+		 * @param name: string - a name to refer this file set in the outputs
+		 * @param regex: string - regex
+		 */
+		saveFileSet: func(name, regex) {
+			validation.assertJsonSchema(regex, "string")
+			ll.assert(is_undefined(fileSets[name]), "file set with name '", name, "' is already in added")
+			fileSets[name] = regex
+			return self
+		},
+
+		/**
+		 * Save files content which names satisfy given regex rule
+		 *
+		 * @param name: string - a name to refer this file set in the outputs
+		 * @param regex: string - regex
+		 */
+		saveFileSetContent: func(name, regex) {
+			validation.assertJsonSchema(regex, "string")
+			ll.assert(is_undefined(fileSetsContent[name]), "file set content with name '", name, "' is already in added")
+			sets.add(fileSetsContent, regex)
+			return self
+		},
+
+		/**
+		 * Builds the saved workdir.
+		 *
+		 * @return wd: reference - the saved workdir with additional fields.
+		 */
+		build: func() {
+
+			tpl := assets.importTemplate("@platforma-sdk/workflow-tengo:workdir.save")
+			inputs := {
+				workdir: workdir,
+				files: files,
+				filesContent: filesContent,
+				fileSets: fileSets,
+				fileSetsContent: fileSetsContent
+			}
+
+			wds := render.createEphemeral(tpl, inputs)
+
+			return ll.toStrict({
+				files: wds.output("files"),
+				filesContent: wds.output("filesContent"),
+				fileSets : wds.output("fileSets"),
+				fileSetsContent : wds.output("fileSetsContent"),
+				workdir: wds.output("workdir"),
+				progress: wds.output("progress")
+			})
+		}
+	})
+
+	return self
 }
 
 export ll.toStrict({
-builder: builder,
-create: create,
-save: save
+	builder: builder,
+	create: create,
+	save: save
 })