@platforma-sdk/workflow-tengo 4.5.2 → 4.6.0

package/dist/tengo/lib/pframes.xsv-builder.lib.tengo

@@ -0,0 +1,625 @@
+ll := import("@platforma-sdk/workflow-tengo:ll")
+maps := import("@platforma-sdk/workflow-tengo:maps")
+strings := import("@platforma-sdk/workflow-tengo:strings")
+pSpec := import("@platforma-sdk/workflow-tengo:pframes.spec")
+pBuilder := import("@platforma-sdk/workflow-tengo:pframes.builder")
+xsv := import("@platforma-sdk/workflow-tengo:pframes.xsv")
+canonical := import("@platforma-sdk/workflow-tengo:canonical")
+
+xsvFileBuilder := func(xsvType) {
+    ll.assert(xsvType == "csv" || xsvType == "tsv", "xsvType must be 'csv' or 'tsv'")
+
+    PTablerNA := "%%NA%%" // Constant for PTabler NA representation
+    naValueInternal := ""  // Default NA value, can be changed by setNA
+
+    requests := []
+    addedColumnInternalIds := {}
+    localAxisHeaderOverrides := []
+    distiller := undefined
+    nextSequentialId := 1
+    nextPFrameKeyIndex := 1
+
+    getSpecDistiller := func() {
+        if is_undefined(distiller) {
+            columnsToDistill := []
+            for request in requests {
+                columnsToDistill = append(columnsToDistill, request.spec)
+            }
+
+            distiller = pSpec.createSpecDistiller(columnsToDistill)
+        }
+        return distiller
+    }
+
+
+
+
+    parseFlatFrameInput := func(flatFrame) {
+        parsedColumns := {}
+        processedBaseKeys := {}
+
+        for key, value in flatFrame {
+            if strings.has_suffix(key, ".spec") {
+                baseKey := strings.trim_suffix(key, ".spec")
+                if is_undefined(parsedColumns[baseKey]) {
+                    parsedColumns[baseKey] = { key: baseKey }
+                }
+                parsedColumns[baseKey].spec = value
+                processedBaseKeys[baseKey] = true
+            } else if strings.has_suffix(key, ".data") {
+                baseKey := strings.trim_suffix(key, ".data")
+                if is_undefined(parsedColumns[baseKey]) {
+                    parsedColumns[baseKey] = { key: baseKey }
+                }
+                parsedColumns[baseKey].data = value
+                processedBaseKeys[baseKey] = true
+            } else {
+                ll.panic("Invalid key format in flat frame input: %s. Expected '.spec' or '.data' suffix.", key)
+            }
+        }
+
+        resultArray := []
+        for baseKey, colParts in parsedColumns {
+            if is_undefined(colParts.spec) {
+                ll.panic("Missing .spec for base key '%s' in flat frame input.", baseKey)
+            }
+            if is_undefined(colParts.data) {
+                ll.panic("Missing .data for base key '%s' in flat frame input.", baseKey)
+            }
+            resultArray = append(resultArray, {
+                spec: colParts.spec,
+                data: colParts.data,
+                key: baseKey
+            })
+        }
+        return resultArray
+    }
+
+    getCanonicalAxisKey := func(axisSpec) {
+
+        nameStr := axisSpec.name
+        typeStr := axisSpec.type
+
+        domainCanonicalStr := ""
+        if is_map(axisSpec.domain) {
+            domainCanonicalStr = canonical.encode(axisSpec.domain)
+        } else {
+
+
+            domainCanonicalStr = canonical.encode({})
+        }
+        return nameStr + "|" + typeStr + "|" + domainCanonicalStr
+    }
+
+    findAxisHeaderOverride := func(axisSpec) {
+        for _, override in localAxisHeaderOverrides {
+            matcher := override[0]
+            if matcher.name == axisSpec.name {
+                specDistiller := getSpecDistiller()
+                discriminativeDomains := specDistiller.getDiscriminativeDomainsSet(axisSpec.name)
+                domainsMatch := true
+                for domainKey, domainValue in matcher.domain {
+                    if is_undefined(discriminativeDomains[domainKey]) {
+                        continue
+                    }
+                    if is_undefined(axisSpec.domain) || is_undefined(axisSpec.domain[domainKey]) || axisSpec.domain[domainKey] != domainValue {
+                        domainsMatch = false
+                        break
+                    }
+                }
+                if domainsMatch {
+                    return override[1]
+                }
+            }
+        }
+        return undefined
+    }
+
+    generateLabelForAxis := func(axisSpec) {
+        label := findAxisHeaderOverride(axisSpec)
+        if !is_undefined(label) {
+            return label
+        }
+
+        specDistiller := getSpecDistiller()
+        discriminativeDomains := specDistiller.getDiscriminativeDomains(axisSpec.name)
+
+        if len(discriminativeDomains) == 0 {
+            label = strings.substituteSpecialCharacters(axisSpec.name)
+        } else {
+
+
+            ll.panic(
+                "Cannot deduce header for axis '%s'. Discriminative domains: %s. Please provide a header override using setAxisHeader().",
+                axisSpec.name,
+                discriminativeDomains
+            )
+        }
+        return label
+    }
+
+    _constructPFrameAndDistillSpecs := func() {
+        frameBuilder := pBuilder.pFrameBuilder()
+        currentDistiller := getSpecDistiller() // Ensure distiller is created/updated
+        processedAxesMap := {}
+
+        for request in requests {
+            distilledSpec := currentDistiller.distill(request.spec)
+
+
+            distilledSpec = maps.deepMerge(distilledSpec, {
+                annotations: { "pl7.app/label": request.header }
+            })
+
+
+            if !is_undefined(distilledSpec.axesSpec) && is_array(distilledSpec.axesSpec) {
+                newAxesSpec := []
+                for axis_idx, axis_orig in distilledSpec.axesSpec {
+                    labelledAxis := maps.deepMerge(axis_orig, {
+                        annotations: { "pl7.app/label": generateLabelForAxis(axis_orig) }
+                    })
+                    newAxesSpec = append(newAxesSpec, labelledAxis)
+
+
+                    canonicalKey := getCanonicalAxisKey(labelledAxis) // Pass the whole axis spec
+                    if is_undefined(processedAxesMap[canonicalKey]) {
+                        processedAxesMap[canonicalKey] = {
+                            name: labelledAxis.name,
+                            type: labelledAxis.type,
+                            domain: labelledAxis.domain, // Store original domain from the labelled (effectively distilled) axis
+                            label: labelledAxis.annotations["pl7.app/label"]
+                        }
+                    }
+                }
+                distilledSpec.axesSpec = newAxesSpec
+            }
+
+
+            frameBuilder.add(request.pFrameKey, distilledSpec, request.data)
+        }
+
+        finalProcessedAxes := maps.getValues(processedAxesMap)
+        return {
+            pFrame: frameBuilder.build(),
+            uniqueAxes: finalProcessedAxes
+        }
+    }
+
+    self := undefined // Forward declaration for builder methods
+
+    processSingleCol := func(col, ops) {
+        if !is_map(col) || is_undefined(col.spec) || is_undefined(col.data) {
+            ll.panic("Invalid single column input. Expected {spec: ..., data: ..., key?: ...}, got: %v", col)
+        }
+
+
+
+        idPrefix := ops.idPrefix ? ops.idPrefix : ""
+        idSuffix := ops.idSuffix ? ops.idSuffix : ""
+        headerPrefix := ops.headerPrefix ? ops.headerPrefix : ""
+        headerSuffix := ops.headerSuffix ? ops.headerSuffix : ""
+
+        baseId := undefined
+        if !is_undefined(ops.id) {
+            if !is_string(ops.id) {
+                ll.panic("Option 'id' must be a string.")
+            }
+            baseId = ops.id
+        } else if !is_undefined(col.key) {
+            if !is_string(col.key) {
+                ll.panic("Column 'key' must be a string if provided.")
+            }
+            baseId = col.key
+        } else {
+            baseId = "user_col" + nextSequentialId
+            nextSequentialId += 1
+        }
+
+        internalId := idPrefix + baseId + idSuffix
+
+        if !is_undefined(addedColumnInternalIds[internalId]) {
+            ll.panic("Duplicate internalId detected: '%s'. Column IDs must be unique.", internalId)
+        }
+        addedColumnInternalIds[internalId] = true
+
+        header := undefined
+        if !is_undefined(ops.header) {
+            if !is_string(ops.header) {
+                ll.panic("Option 'header' must be a string.")
+            }
+            header = ops.header // Explicit header takes full precedence, no prefix/suffix from ops apply here
+        } else {
+            baseHeaderForOps := undefined
+            if !is_undefined(col.spec) &&
+               !is_undefined(col.spec.annotations) &&
+               !is_undefined(col.spec.annotations["pl7.app/label"]) &&
+               is_string(col.spec.annotations["pl7.app/label"]) &&
+               col.spec.annotations["pl7.app/label"] != "" {
+                baseHeaderForOps = col.spec.annotations["pl7.app/label"]
+            } else {
+                baseHeaderForOps = strings.substituteSpecialCharacters(internalId) // Fallback to internalId
+            }
+            header = headerPrefix + baseHeaderForOps + headerSuffix
+        }
+
+
+        pFrameKey := "col" + nextPFrameKeyIndex
+        nextPFrameKeyIndex += 1
+
+        requests = append(requests, {
+            internalId: internalId,
+            header: header,
+            spec: col.spec,
+            data: col.data,
+            originalKey: col.key, // Store original key if present
+            pFrameKey: pFrameKey
+        })
+        distiller = undefined // Invalidate distiller
+    }
+
+    processMultiCol := func(colsArray, ops) {
+        if !is_undefined(ops.id) || !is_undefined(ops.header) {
+            ll.panic("Single-column options ('id', 'header') cannot be used with multi-column 'add'.")
+        }
+        idPrefix := ops.idPrefix ? ops.idPrefix : ""
+        idSuffix := ops.idSuffix ? ops.idSuffix : ""
+        headerPrefix := ops.headerPrefix ? ops.headerPrefix : ""
+        headerSuffix := ops.headerSuffix ? ops.headerSuffix : ""
+
+        for col in colsArray {
+            if !is_map(col) || is_undefined(col.spec) || is_undefined(col.data) {
+                ll.panic("Invalid column item in array/frame. Expected {spec: ..., data: ..., key?: ...}, got: %v", col)
+            }
+
+            baseId := undefined
+            if !is_undefined(col.key) {
+                if !is_string(col.key) {
+                    ll.panic("Column 'key' must be a string if provided in multi-add.")
+                }
+                baseId = col.key
+            } else {
+                baseId = "user_col" + nextSequentialId
+                nextSequentialId += 1
+            }
+
+            internalId := idPrefix + baseId + idSuffix
+
+            if !is_undefined(addedColumnInternalIds[internalId]) {
+                ll.panic("Duplicate internalId detected: '%s'. Column IDs must be unique.", internalId)
+            }
+            addedColumnInternalIds[internalId] = true
+
+            baseHeader := undefined
+            if !is_undefined(col.spec) &&
+               !is_undefined(col.spec.annotations) &&
+               !is_undefined(col.spec.annotations["pl7.app/label"]) &&
+               is_string(col.spec.annotations["pl7.app/label"]) &&
+               col.spec.annotations["pl7.app/label"] != "" {
+                baseHeader = col.spec.annotations["pl7.app/label"]
+            } else {
+                baseHeader = strings.substituteSpecialCharacters(internalId) // Fallback to internalId
+            }
+            header := headerPrefix + baseHeader + headerSuffix
+
+
+            pFrameKey := "col" + nextPFrameKeyIndex
+            nextPFrameKeyIndex += 1
+
+            requests = append(requests, {
+                internalId: internalId,
+                header: header,
+                spec: col.spec,
+                data: col.data,
+                originalKey: col.key,
+                pFrameKey: pFrameKey
+            })
+        }
+        distiller = undefined // Invalidate distiller
+    }
+
+
+    self = {
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+        add: func(item, ...options) {
+            ops := {}
+            if len(options) > 0 {
+                if !is_map(options[0]) {
+                    ll.panic("Options for 'add' method must be a map.")
+                }
+                ops = options[0]
+            }
+
+            if is_array(item) { // Array of columns
+                processMultiCol(item, ops)
+            } else if is_map(item) {
+
+                if !is_undefined(item.spec) && !is_undefined(item.data) {
+                     processSingleCol(item, ops)
+                } else {
+
+
+                    isFlatFrame := false
+                    for k, _ in item {
+                        if strings.has_suffix(k, ".spec") || strings.has_suffix(k, ".data") {
+                            isFlatFrame = true
+                            break
+                        }
+                    }
+
+                    colsToProcess := []
+                    if isFlatFrame {
+                        colsToProcess = parseFlatFrameInput(item)
+                    } else { // Assume map of column objects: { "id1": {spec, data}, ... }
+                        for k, v_col in item {
+                             if !is_map(v_col) || is_undefined(v_col.spec) || is_undefined(v_col.data) {
+                                ll.panic("Invalid column value in frame for key '%s'. Expected {spec: ..., data: ...}.", k)
+                            }
+                            colsToProcess = append(colsToProcess, {
+                                spec: v_col.spec,
+                                data: v_col.data,
+                                key: k // Use map key as original key
+                            })
+                        }
+                    }
+                    processMultiCol(colsToProcess, ops)
+                }
+            } else {
+                ll.panic("'add' method input item must be a single column object, an array of columns, or a frame (map). Got: %v", item)
+            }
+            return self
+        },
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+        setAxisHeader: func(matcher, header) {
+            processedMatcher := undefined
+            if is_string(matcher) {
+                processedMatcher = { name: matcher, domain: {} }
+            } else if is_map(matcher) {
+
+
+
+                processedMatcher = pSpec.axisSpecToMatcher(matcher)
+            } else {
+                 ll.panic("Matcher for setAxisHeader must be a string (axis name) or an AxisSpec-like map (with at least 'name' and 'type' fields).")
+            }
+
+            if !is_string(header) {
+                ll.panic("Header for setAxisHeader must be a string.")
+            }
+
+            localAxisHeaderOverrides = [[processedMatcher, header]] + localAxisHeaderOverrides
+
+            return self
+        },
+
+
+
+
+
+
+
+
+        getHeader: func(internalId) {
+            if !is_string(internalId) {
+                ll.panic("internalId for getHeader must be a string.")
+            }
+            for request in requests {
+                if request.internalId == internalId {
+                    return request.header
+                }
+            }
+            ll.panic("Header not found for internalId: '%s'. Ensure column was added and ID is correct.", internalId)
+            return undefined // Should not reach here
+        },
+
+
+
+
+
+
+
+
+        getSpec: func(internalId) {
+            if !is_string(internalId) {
+                ll.panic("internalId for getSpec must be a string.")
+            }
+            for request in requests {
+                if request.internalId == internalId {
+                    return request.spec
+                }
+            }
+            ll.panic("Spec not found for internalId: '%s'. Ensure column was added and ID is correct.", internalId)
+            return undefined // Should not reach here
+        },
+
+
+
+
+
+
+
+
+
+
+        setNA: func(value) {
+            if !is_string(value) {
+                ll.panic("NA value for setNA must be a string.")
+            }
+            naValueInternal = value
+            return self
+        },
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+        build: func(...params) {
+            if len(requests) == 0 {
+                ll.panic("Cannot build XSV: no columns have been added.")
+            }
+
+
+            currentExportParams := { naStr: naValueInternal, nullStr: naValueInternal }
+
+            if len(params) > 0 {
+                if !is_map(params[0]) {
+                    ll.panic("Optional build params must be a map.")
+                }
+
+                currentExportParams = maps.deepMerge(currentExportParams, params[0])
+            }
+
+            pFrame := _constructPFrameAndDistillSpecs().pFrame
+            return xsv.exportFrame(pFrame, xsvType, currentExportParams)
+        },
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+        buildForPT: func() {
+            if len(requests) == 0 {
+                ll.panic("Cannot build PTabler output: no columns have been added.")
+            }
+
+            finalExportParams := {
+                naStr: PTablerNA,
+                nullStr: PTablerNA
+            }
+
+            buildOutput := _constructPFrameAndDistillSpecs()
+            pFrame := buildOutput.pFrame
+            uniqueAxes := buildOutput.uniqueAxes
+
+            tableResource := xsv.exportFrame(pFrame, xsvType, finalExportParams)
+
+            schema := []
+
+
+            for axisEntry in uniqueAxes {
+                axisSchema := {
+                    column: axisEntry.label,
+                    nullValue: PTablerNA
+                }
+                axisSchema.type = axisEntry.type
+                schema = append(schema, axisSchema)
+            }
+
+
+            for request in requests {
+                colSchema := {
+                    column: request.header,
+                    nullValue: PTablerNA
+                }
+                colSchema.type = request.spec.valueType
+                schema = append(schema, colSchema)
+            }
+
+            return {
+                xsvType: xsvType,
+                file: tableResource,
+                schema: schema
+            }
+        }
+    }
+    return ll.toStrict(self)
+}
+
+export ll.toStrict({
+    xsvFileBuilder: xsvFileBuilder
+})