@platforma-sdk/workflow-tengo 2.9.6 → 2.9.8

package/dist/tengo/lib/pframes.ll.lib.tengo

@@ -1,6 +1,6 @@
-
-
-
+/**
+ * Set of basic operations for PColumn data payload
+ */
 
 ll := import("@platforma-sdk/workflow-tengo:ll")
 assets := import("@platforma-sdk/workflow-tengo:assets")
@@ -9,77 +9,77 @@ render := import("@platforma-sdk/workflow-tengo:render")
 
 llAggTpl := assets.importTemplate("@platforma-sdk/workflow-tengo:pframes.aggregate")
 
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+/**
+ * Instantiate an aggregation pipeline for the given inputs, and returns rendered ephemeral template.
+ * Use r.output("output_name") method to get corresponding result, where r is an object returned by
+ * this method.
+ *
+ * Contract for the body template:
+ *
+ *   Inputs:
+ *     "__key__"   - will be set to the json representation of the group key (i.e. keys in all
+ *                   positions not specified in the indices parameter)
+ *     "__value__" - "PColumnData/ResourceMap" resource with all the records in the current group
+ *     ...extra    - all values or references passed to optional last parameter of this method
+ *                   will be forwarded to the template as is
+ *
+ *  Outputs:
+ *    array of output names to collect from aggregation operations is specified as a parameter
+ *    of this operation
+ *
+ * @param data    data resource (currently only PColumnData/ResourceMap is supported)
+ * @param indices indices to aggregate over (these indices will be stripped from the input map,
+ *                meaning of this parameter is the opposite of GROUP BY from SQL)
+ * @param bodyTpl reference to the template implementing particular aggregation (see contract above)
+ * @param outputs array of output settings to to collect from rendered templates
+ *
+ *                  Common fields for all subtypes:
+ *                     {
+ *                       name:  string     - name of the output
+ *                       path?: string[]   - [optional] overrides the path inside the body template
+ *                                           result, first name is interpreted as output name. If
+ *                                           not specified path equals to `[name]`.
+ *                     }
+ *
+ *                  Variants:
+ *                    | { type: "Resource" } // - assume normal singular resource is produced by
+ *                                                this output
+ *                    | {
+ *                        type: "ResourceMap",
+ *                        keyLength: number // - expected key length of result from each operation
+ *                      } // - assume each record is ResourceMap
+ *                    | {
+ *                        type: "BinaryPartitioned" | "JsonPartitioned",
+ *                        partitionKeyLength: number // - expected partition length of result from
+ *                                                        each operation
+ *                      } // - assume each record is a partitionded Json or Binary PColumn data itself
+ *
+ * @param isEph   if true, body template will be rendered as ephemeral
+ * @param extra   optional map of parameters to pass to the template
+ */
 aggregate := func(data, indices, bodyTpl, outputs, isEph, ...extra) {
-renderInputs := {
-params: smart.createJsonResource({
-indices: indices,
-eph: isEph,
-outputs: outputs
-}),
-body: bodyTpl,
-data: data
-}
-
-if len(extra) == 1 {
-for k, v in extra[0] {
-renderInputs["__extra_" + k] = v
-}
-} else if len(extra) != 0 {
-ll.panic("Wrong number of parameters for aggregate method.")
-}
-
-renderResult := render.createEphemeral(llAggTpl, renderInputs)
-return renderResult;
+	renderInputs := {
+		params: smart.createJsonResource({
+			indices: indices,
+			eph: isEph,
+			outputs: outputs
+		}),
+		body: bodyTpl,
+		data: data
+	}
+
+	if len(extra) == 1 {
+		for k, v in extra[0] {
+			renderInputs["__extra_" + k] = v
+		}
+	} else if len(extra) != 0 {
+		ll.panic("Wrong number of parameters for aggregate method.")
+	}
+
+	renderResult := render.createEphemeral(llAggTpl, renderInputs)
+	return renderResult;
 }
 
 export ll.toStrict({
-aggregate: aggregate
+	aggregate: aggregate
 })

package/dist/tengo/lib/pframes.pcolumn.lib.tengo

@@ -1,6 +1,6 @@
-
-
-
+/**
+ * Working with a single p-column
+ */
 
 ll := import("@platforma-sdk/workflow-tengo:ll")
 oop := import("@platforma-sdk/workflow-tengo:oop")
@@ -8,62 +8,62 @@ json := import("json")
 smart := import("@platforma-sdk/workflow-tengo:smart")
 constants := import("@platforma-sdk/workflow-tengo:pframes.constants")
 
-
-
-
+/**
+ * Returns true if given resource is a p-column resource map data
+ */
 isResourceMap := func(r) {
-return smart.isResource(r) && r.info().Type.Name == constants.RTYPE_P_COLUMN_DATA_RESOURCE_MAP.Name
+	return smart.isResource(r) && r.info().Type.Name == constants.RTYPE_P_COLUMN_DATA_RESOURCE_MAP.Name
 }
 
-
-
-
-
-
+/**
+ * Creates a builder for a resource map p-column's data.
+ *
+ * @param keyLength: int - key length
+ */
 resourceMapBuilder := func(keyLength) {
-r := smart.structBuilder(
-constants.RTYPE_P_COLUMN_DATA_RESOURCE_MAP,
-json.encode({ keyLength: keyLength })
-)
-
-self := undefined
-self = ll.toStrict(oop.inherit(r, {
-
-add: func(key, data) {
-ll.assert(is_array(key), "key must be an array, got ", key)
-ll.assert(len(key) == keyLength, "array length does not match specified keyLength", key, keyLength)
-r.createInputField(json.encode(key)).setRefOrJson(data)
-return self
-},
-
-build: func() {
-return r.lockAndBuild()
-}
-}))
-return self
+	r := smart.structBuilder(
+		constants.RTYPE_P_COLUMN_DATA_RESOURCE_MAP,
+		json.encode({ keyLength: keyLength })
+	)
+
+	self := undefined
+	self = ll.toStrict(oop.inherit(r, {
+
+		add: func(key, data) {
+			ll.assert(is_array(key), "key must be an array, got ", key)
+			ll.assert(len(key) == keyLength, "array length does not match specified keyLength", key, keyLength)
+			r.createInputField(json.encode(key)).setRefOrJson(data)
+			return self
+		},
+
+		build: func() {
+			return r.lockAndBuild()
+		}
+	}))
+	return self
 }
 
-
-
-
-
-
-
-
+/**
+ * Convert map object to a p-column resource map.
+ *
+ * @param map - tengo map
+ * @param keyLength: int - length of the partitioned key
+ * @param keyParser: func - function to parse string map keys and return array of p-column keys
+ */
 fromMap := func(map, keyLength, keyParser) {
-b := resourceMapBuilder(keyLength)
+	b := resourceMapBuilder(keyLength)
 
-for k, v in map {
-arr := keyParser(k)
-ll.assert(is_array(arr), "keyParser should return array")
-b.add(arr, v)
-}
+	for k, v in map {
+		arr := keyParser(k)
+		ll.assert(is_array(arr), "keyParser should return array")
+		b.add(arr, v)
+	}
 
-return b.build()
+	return b.build()
 }
 
 export ll.toStrict({
-fromMap: fromMap,
-isResourceMap: isResourceMap,
-resourceMapBuilder: resourceMapBuilder
+	fromMap: fromMap,
+	isResourceMap: isResourceMap,
+	resourceMapBuilder: resourceMapBuilder
 })

package/dist/tengo/lib/pframes.spec.lib.tengo

@@ -1,136 +1,136 @@
-
-
-
-
-
+/**
+ * PFrames spec library:
+ *  - well known domains, annotations and column names.
+ *  - utility methods to manipulate column and axis spec
+ */
 
 ll := import("@platforma-sdk/workflow-tengo:ll")
 maps := import("@platforma-sdk/workflow-tengo:maps")
 validation := import("@platforma-sdk/workflow-tengo:validation")
 json := import("json")
 
-
-
-
+//
+// Common schemas
+//
 
 P_AXIS_SPEC_SCHEMA := {
-
-`type`: `string,regex=Int|Long|Float|Double|String`,
-`name`: `string`,
-`domain,?`: { any: `string` },
-`annotations,?`: { any: `string` },
-`parentAxes,?`: `any` // [ `number` ]
+	// `__options__,closed`: ``, // commented out to keep the room for future schema modifications
+	`type`: `string,regex=Int|Long|Float|Double|String`,
+	`name`: `string`,
+	`domain,?`: { any: `string` },
+	`annotations,?`: { any: `string` },
+	`parentAxes,?`: `any` // [ `number` ]
 }
 
 P_COLUMN_SPEC_SCHEMA := {
-
-`kind`: `string,regex=PColumn`,
-`valueType`: `string`,
-`name`: `string`,
-`domain,?`: { any: `string` },
-`annotations,?`: { any: `string` },
-`parentAxes,?`: `any`, // [ `number` ]
-`axesSpec,?`: [ P_AXIS_SPEC_SCHEMA ]
+	// `__options__,closed`: ``, // commented out to keep the room for future schema modifications
+	`kind`: `string,regex=PColumn`,
+	`valueType`: `string`,
+	`name`: `string`,
+	`domain,?`: { any: `string` },
+	`annotations,?`: { any: `string` },
+	`parentAxes,?`: `any`, // [ `number` ]
+	`axesSpec,?`: [ P_AXIS_SPEC_SCHEMA ]
 }
 
 KIND_P_COLUMN := "PColumn"
 
+//
+// Column / axis names
+//
 
-
-
-
-
+/** Column containing labels for axis keys */
 N_LABEL := "pl7.app/label"
 
+//
+// Column / axis domains
+//
 
-
-
-
-
+/** Domain marking column or axis as block-specific, value must contain block id */
 D_BLOCK := "pl7.app/block"
 
+//
+// Column / axis annotations
+//
 
-
-
-
-
+/** Annotation with axis or column label */
 A_LABEL := "pl7.app/label"
-
-
-
-
-
-
-
-
-
-
-
+/**
+ * Annotation containing trace of operations resulting in a corresponding column.
+ *
+ * Value must containe JSON encoded array of structures:
+ *   {
+ *      type: string       - type of the step, often equals to block package name (i.e. milaboratories.mixcr-clonotyping)
+ *      label: string      - string representation of the operation often a block title
+ *      importance: number - higher the number higher the change label from trace step will be used to derive column label
+ *      id: string         - unique identifier of operation, often a block id
+ *   }
+ */
 A_TRACE := "pl7.app/trace"
 
-
-
-
+//
+// Utility methods
+//
 
 _TRACE_STEP_SCHEMA := {
-`type`: `string`,
-`label`: `string`,
-`importance,?`: `number`,
-`id,?`: `string`,
-`__options__,closed`: ``
+	`type`: `string`,
+	`label`: `string`,
+	`importance,?`: `number`,
+	`id,?`: `string`,
+	`__options__,closed`: ``
 }
 
 _TRACE_SCHEMA := [_TRACE_STEP_SCHEMA]
 
-
-
-
-
-
-
+/**
+ * Calculates content of pl7.app/trace annotation, given input column spec, or annotations section
+ * of specs, or directly content of pl7.app/trace from the input column spec.
+ *
+ * Basically validates and adds provided steps.
+ */
 makeTrace := func(input, ...steps) {
-
-validation.assertJsonSchema(steps, _TRACE_SCHEMA)
-
-currentTraceContent := undefined
-if is_string(input) {
-currentTraceContent = input
-} else if is_string(input[A_TRACE]) {
-currentTraceContent = input[A_TRACE]
-} else if is_string(input["annotations"][A_TRACE]) {
-currentTraceContent = input["annotations"][A_TRACE]
-}
-
-currentTrace := []
-if !is_undefined(currentTraceContent) {
-currentTrace = json.decode(currentTraceContent)
-
-validation.assertJsonSchema(currentTrace, _TRACE_SCHEMA)
-}
-
-currentTrace = append(currentTrace, steps...)
-currentTraceStr := string(json.encode(currentTrace))
-
-return ll.toStrict({
-value: currentTrace,
-valueStr: currentTraceStr,
-
-inject: func(spec) {
-validation.assertJsonSchema(spec, P_COLUMN_SPEC_SCHEMA)
-return maps.deepMerge(spec, {annotations: {"pl7.app/trace": currentTraceStr}})
-}
-})
+	// validating input step structure
+	validation.assertJsonSchema(steps, _TRACE_SCHEMA)
+
+	currentTraceContent := undefined
+	if is_string(input) {
+		currentTraceContent = input
+	} else if is_string(input[A_TRACE]) {
+		currentTraceContent = input[A_TRACE]
+	} else if is_string(input["annotations"][A_TRACE]) {
+		currentTraceContent = input["annotations"][A_TRACE]
+	}
+
+	currentTrace := []
+	if !is_undefined(currentTraceContent) {
+		currentTrace = json.decode(currentTraceContent)
+		// validating trace we just parsed
+		validation.assertJsonSchema(currentTrace, _TRACE_SCHEMA)
+	}
+
+	currentTrace = append(currentTrace, steps...)
+	currentTraceStr := string(json.encode(currentTrace))
+
+	return ll.toStrict({
+		value: currentTrace,
+		valueStr: currentTraceStr,
+		/** Injects trace information into column spec */
+		inject: func(spec) {
+			validation.assertJsonSchema(spec, P_COLUMN_SPEC_SCHEMA)
+			return maps.deepMerge(spec, {annotations: {"pl7.app/trace": currentTraceStr}})
+		}
+	})
 }
 
 export ll.toStrict({
-KIND_P_COLUMN: KIND_P_COLUMN,
+	KIND_P_COLUMN: KIND_P_COLUMN,
 
-N_LABEL: N_LABEL,
+	N_LABEL: N_LABEL,
 
-D_BLOCK: D_BLOCK,
+	D_BLOCK: D_BLOCK,
 
-A_LABEL: A_LABEL,
-A_TRACE: A_TRACE,
+	A_LABEL: A_LABEL,
+	A_TRACE: A_TRACE,
 
-makeTrace: makeTrace
+	makeTrace: makeTrace
 })