KCL Artifact Lib for Node.js

Installation

npm install kcl-lib

Quick Start

import { execProgram, ExecProgramArgs } from "kcl-lib";

function main() {
  const result = execProgram(new ExecProgramArgs(["schema.k"]));
  console.log(result.yamlResult);
}

main();

Developing

• Install node.js and pnpm
• Install cargo (for Rust code)
• Install dependencies

pnpm install

Building

pnpm build

Testing

pnpm test

Format

pnpm format

API Reference

execProgram

Execute KCL file with arguments and return the JSON/YAML result.

The content of schema.k is

schema AppConfig:
    replicas: int

app: AppConfig {
    replicas: 2
}

Node.js Code

import { execProgram, ExecProgramArgs } from "kcl-lib";

const result = execProgram(new ExecProgramArgs(["schema.k"]));

A case with the file not found error

import { execProgram, ExecProgramArgs } from "kcl-lib";

try {
  const result = execProgram(new ExecProgramArgs(["file_not_found.k"]));
} catch (error) {
  console.log(error.message);
}

parseFile

Parse KCL single file to Module AST JSON string with import dependencies and parse errors.

The content of schema.k is

schema AppConfig:
    replicas: int

app: AppConfig {
    replicas: 2
}

Node.js Code

import { parseFile, ParseFileArgs } from "kcl-lib";

const result = parseFile(new ParseFileArgs("schema.k"));

parseProgram

Parse KCL program with entry files and return the AST JSON string.

The content of schema.k is

schema AppConfig:
    replicas: int

app: AppConfig {
    replicas: 2
}

Node.js Code

import { parseProgram, ParseProgramArgs } from "kcl-lib";

const result = parseProgram(new ParseProgramArgs(["schema.k"]));

loadPackage

loadPackage provides users with the ability to parse KCL program and semantic model information including symbols, types, definitions, etc.

The content of schema.k is

schema AppConfig:
    replicas: int

app: AppConfig {
    replicas: 2
}

Node.js Code

import { loadPackage, LoadPackageArgs } from "kcl-lib";

const result = loadPackage(new LoadPackageArgs(["schema.k"], [], true));

listVariable

listVariables provides users with the ability to parse KCL program and get all variables by specs.

The content of schema.k is

schema AppConfig:
    replicas: int

app: AppConfig {
    replicas: 2
}

Node.js Code

import { listVariables, ListVariablesArgs } from "kcl-lib";

const result = listVariables(new ListVariablesArgs(["schema.k"], []));

listOptions

listOptions provides users with the ability to parse KCL program and get all option information.

The content of options.k is

a = option("key1")
b = option("key2", required=True)
c = {
    metadata.key = option("metadata-key")
}

Node.js Code

import { listOptions, ListOptionsArgs } from "kcl-lib";

const result = listOptions(new ListOptionsArgs(["options.k"]));

getSchemaTypeMapping

Get schema type mapping defined in the program.

The content of schema.k is

schema AppConfig:
    replicas: int

app: AppConfig {
    replicas: 2
}

Node.js Code

import { getSchemaTypeMapping, GetSchemaTypeMappingArgs } from "kcl-lib";

const result = getSchemaTypeMapping(new GetSchemaTypeMappingArgs(["schema.k"]));

overrideFile

Override KCL file with arguments. See https://www.kcl-lang.io/docs/user_docs/guides/automation for more override spec guide.

The content of main.k is

schema AppConfig:
    replicas: int

app: AppConfig {replicas: 4}

Node.js Code

import { overrideFile, OverrideFileArgs } from "kcl-lib";

const result = overrideFile(
  new OverrideFileArgs("main.k", ["app.replicas=4"], [])
);

formatCode

Format the code source.

Node.js Code

import { formatCode, FormatCodeArgs } from "kcl-lib";

const schemaCode = `
schema Person:
    name:   str
    age:    int

    check:
        0 <   age <   120
`;
const result = formatCode(new FormatCodeArgs(schemaCode));
console.log(result.formatted);

formatPath

Format KCL file or directory path contains KCL files and returns the changed file paths.

The content of format_path.k is

schema Person:
    name:   str
    age:    int

    check:
        0 <   age <   120

Node.js Code

import { formatPath, FormatPathArgs } from "kcl-lib";

const result = formatPath(new FormatPathArgs("format_path.k"));

lintPath

Lint files and return error messages including errors and warnings.

The content of lint_path.k is

import math

a = 1

Node.js Code

import { lintPath, LintPathArgs } from "kcl-lib";

const result = lintPath(new LintPathArgs(["lint_path.k"]));

validateCode

Validate code using schema and JSON/YAML data strings.

Node.js Code

import { validateCode, ValidateCodeArgs } from "kcl-lib";

const code = `
schema Person:
    name: str
    age: int

    check:
        0 < age < 120
`;
const data = '{"name": "Alice", "age": 10}';
const result = validateCode(
  new ValidateCodeArgs(undefined, data, undefined, code)
);

rename

Rename all the occurrences of the target symbol in the files. This API will rewrite files if they contain symbols to be renamed. Return the file paths that got changed.

The content of main.k is

a = 1
b = a

Node.js Code

import { rename, RenameArgs } from "kcl-lib";

const args = new RenameArgs(".", "a", ["main.k"], "a2");
const result = rename(args);

renameCode

Rename all the occurrences of the target symbol and return the modified code if any code has been changed. This API won't rewrite files but return the changed code.

Node.js Code

import { renameCode, RenameCodeArgs } from "kcl-lib";

const args = RenameCodeArgs(
  "/mock/path",
  "a",
  { "/mock/path/main.k": "a = 1\nb = a" },
  "a2"
);
const result = renameCode(args);

test

Test KCL packages with test arguments.

Node.js Code

import { test as kclTest, TestArgs } from "kcl-lib";

const result = kclTest(new TestArgs(["/path/to/test/module/..."]));

loadSettingsFiles

Load the setting file config defined in kcl.yaml

The content of kcl.yaml is

kcl_cli_configs:
  strict_range_check: true
kcl_options:
  - key: key
    value: value

Node.js Code

import { loadSettingsFiles, LoadSettingsFilesArgs } from "kcl-lib";

const result = loadSettingsFiles(new LoadSettingsFilesArgs(".", ["kcl.yaml"]));

updateDependencies

Download and update dependencies defined in the kcl.mod file and return the external package name and location list.

The content of module/kcl.mod is

[package]
name = "mod_update"
edition = "0.0.1"
version = "0.0.1"

[dependencies]
helloworld = { oci = "oci://ghcr.io/kcl-lang/helloworld", tag = "0.1.0" }
flask = { git = "https://github.com/kcl-lang/flask-demo-kcl-manifests", commit = "ade147b" }

Node.js Code

import { updateDependencies, UpdateDependenciesArgs } from "kcl-lib";

const result = updateDependencies(new UpdateDependenciesArgs("module", false));

Call execProgram with external dependencies

The content of module/kcl.mod is

[package]
name = "mod_update"
edition = "0.0.1"
version = "0.0.1"

[dependencies]
helloworld = { oci = "oci://ghcr.io/kcl-lang/helloworld", tag = "0.1.0" }
flask = { git = "https://github.com/kcl-lang/flask-demo-kcl-manifests", commit = "ade147b" }

The content of module/main.k is

import helloworld
import flask

a = helloworld.The_first_kcl_program

Node.js Code

import {
  execProgram,
  ExecProgramArgs,
  updateDependencies,
  UpdateDependenciesArgs,
} from "../index.js";

const result = updateDependencies(new UpdateDependenciesArgs("module", false));
const execResult = execProgram(
  new ExecProgramArgs(
    ["module/main.k"],
    undefined,
    undefined,
    undefined,
    undefined,
    undefined,
    undefined,
    undefined,
    undefined,
    undefined,
    result.externalPkgs
  )
);

getVersion

Return the KCL service version information.

Node.js Code

import { getVersion } from "../index.js";

const result = getVersion();
console.log(result.versionInfo);