@cortexapps/js-block-libraries

A collection of bundled JavaScript libraries (Lodash, YAML, HCL) optimized for use in CortexApps custom JavaScript execution environments. This package provides both runtime bundles for backend execution and TypeScript declarations for frontend code editors.

📦 What's Included

• Lodash - Utility functions library
• YAML - YAML parser and serializer
• HCL - HashiCorp Configuration Language parser

💻 Frontend Usage (brain-app)

The frontend integration provides TypeScript declarations for the code editor to enable autocomplete and type checking.

Installation

yarn add @cortexapps/js-block-libraries

Setup in brain-app

1. Import the declarations in your editor setup:

import { librariesDeclarationsZipFile } from '@cortexapps/js-block-libraries/declarations';

2. Pass the declarations to the editor web worker:

// In your editor configuration
languageProvider.setGlobalOptions('typescript', {
  extraLibsZip: librariesDeclarationsZipFile
});

This will enable IntelliSense for all bundled libraries in the code editor:

// Users will get autocomplete for:
import _ from 'lodash';
import yaml from 'yaml';
import { parse as parseHCL } from 'hcl2-parser';

// Example usage with full type support
const chunked = _.chunk(['a', 'b', 'c', 'd'], 2);
const yamlString = yaml.stringify({ hello: 'world' });
const hclConfig = parseHCL('variable "example" { default = "value" }');

🖥️ Backend Usage (brain-backend)

The backend requires the actual JavaScript bundles to execute user code with these libraries available.

Setup in brain-backend

1. Download the Release Archive

   • Go to the latest release
   • Download the js-block-libraries-X.Y.Z.tar.gz file
   • Extract the archive

2. Copy Library Files

   • Copy all files from libraries/ directory to:

     web/src/main/resources/javascriptLibraries/

   • You should have:
     • javascriptLibraries/lodash.js
     • javascriptLibraries/yaml.js
     • javascriptLibraries/hcl.js

3. Configure the JavaScript Mixin

   • Update web/src/main/kotlin/com/brainera/web/workflows/actions/JavascriptMixin.kt
   • Add the libraries to the execution context:

   // Example configuration (adjust based on your implementation)
    val libraries =
        listOf(
            JSLibrary(
                moduleName = "lodash",
                filename = "lodash.js",
                importStatement = "import {_} from 'lodash';",
            ),
            JSLibrary(
                moduleName = "hcl",
                filename = "hcl.js",
                importStatement = "import {hcl} from 'hcl';",
            ),
            JSLibrary(
                moduleName = "yaml",
                filename = "yaml.js",
                importStatement = "import {YAML} from 'yaml'",
            ),
        )

🏗️ Development

Building

# Install dependencies
yarn install

# Build libraries and declarations
yarn build

This will create:

• /dist/libraries/ - JavaScript bundles for backend
• /dist/declarations/ - TypeScript declarations (zipped and base64 encoded)

Adding New Libraries

1. Add a New Library

To add a new JavaScript library to the bundle:

1. Install the library:

   yarn add your-new-library

2. Create the library entry point: Create a new file /src/libraries/your-library-name.ts:

   // src/libraries/your-library-name.ts
   export * from 'your-new-library';
   // or
   import yourLibrary from 'your-new-library';
   export default yourLibrary;

3. Build and test:

   yarn build

The build system will automatically detect the new file and create your-library-name.js in the output.

2. Add TypeScript Definitions from node_modules

For libraries that already include TypeScript definitions (like YAML or HCL):

1. Update the rslib configuration: Edit /rslib.config.ts and add the library to the typesToUse array:

   const typesToUse = [
     { from: 'yaml/**/*.d.ts', to: removeDistFromPath, context: "node_modules" },
     { from: 'hcl2-parser/**/*.d.ts', to: removeDistFromPath, context: "node_modules" },
     { from: 'your-library/**/*.d.ts', to: removeDistFromPath, context: "node_modules" }, // Add this line
     { from: '**/*.d.ts', to: removeDistFromPath, context: "src/definitions" },
   ];

2. Build to verify:

   yarn build

The TypeScript definitions will be automatically copied and included in the declarations archive.

3. Add Custom TypeScript Definitions

For libraries that don't have built-in TypeScript support or need custom definitions (like Lodash or Fetch):

1. Create the definitions directory:

   mkdir -p src/definitions/your-library-name

2. Create the definition file: Create /src/definitions/your-library-name/index.d.ts:

   // src/definitions/your-library-name/index.d.ts
      
   // For a simple library
   declare module 'your-library-name' {
     export function someFunction(param: string): number;
     export const someConstant: string;
   }
      
   // For a default export library
   declare module 'your-library-name' {
     interface YourLibrary {
       method(param: string): void;
     }
     const yourLibrary: YourLibrary;
     export default yourLibrary;
   }

3. Build to verify:

   yarn build

The custom definitions will be automatically included in the declarations archive.

Example: Adding Moment.js

Complete example of adding a new library:

1. Install Moment.js:

   yarn add moment
   yarn add -D @types/moment  # If types exist

2. Create library entry:

   // src/libraries/moment.ts
   import moment from 'moment';
   export default moment;
   export * from 'moment';

3. Add to rslib config (if using @types/moment):

   const typesToUse = [
     // ... existing entries
     { from: 'moment/**/*.d.ts', to: removeDistFromPath, context: "node_modules" },
     { from: '**/*.d.ts', to: removeDistFromPath, context: "src/definitions" },
   ];

4. Build:

   yarn build

You'll now have moment.js in /dist/libraries/ and TypeScript support in the editor.

Project Structure

js-block-libraries/
├── src/
│   ├── libraries/      # Library entry points
│   │   ├── lodash.ts   # Lodash exports
│   │   ├── yaml.ts     # YAML exports
│   │   └── hcl.ts      # HCL exports
│   └── definitions/    # Custom TypeScript definitions
├── scripts/
│   └── generate-declarations.js  # Builds declarations archive
├── dist/               # Build output (git ignored)
│   ├── libraries/      # Backend bundles
│   └── declarations/   # Frontend TypeScript declarations
└── rslib.config.ts     # Build configuration (auto-discovers libraries)

🔄 Release Process

Releases are automated via GitHub Actions when a semver tag is pushed:

git tag v1.2.3
git push origin v1.2.3

This will:

1. Build the project
2. Publish to npm registry
3. Create a GitHub release with the tar.gz archive

📝 Notes

• All libraries are bundled with CommonJS disabled (require is set to null)
• Libraries are minified for production use
• TypeScript declarations include all sub-modules and types
• The package exports ES modules targeting ES2023

🤝 Contributing

1. Make your changes
2. Run yarn build to test the build
3. Create a PR
4. Once merged, create a release tag to publish

📄 License

See the individual library licenses:

• Lodash: MIT License
• YAML: ISC License
• HCL2-Parser: MIT License