lumic-utility-functions

lumic-utility-functions is a versatile npm package that provides a comprehensive collection of utility functions for Node.js projects. It simplifies common tasks including:

• Making LLM API calls (OpenAI)
• Managing AWS services (Lambda, S3)
• Sending Slack messages
• Handling file operations (ZIP files, S3 storage)
• Working with JSON data

Installation

npm install lumic-utility-functions

Usage

Import the lumic namespace:

import { lumic } from "lumic-utility-functions";

// Access functions through their namespaces
const result = await lumic.llm.call("Your prompt");
const s3Result = await lumic.s3.upload("bucket", "file.txt");
const slackResult = await lumic.slack.sendMessage("#channel", "message");
const fixedJson = lumic.json.fix(brokenJsonString);

Required environment variables

The following environment variables are recommended for full functionality:

• MY_AWS_ACCESS_KEY_ID - For AWS services
• MY_AWS_REGION - For AWS services
• MY_AWS_SECRET_ACCESS_KEY - For AWS services
• OPENAI_API_KEY - For LLM calls
• PERPLEXITY_API_KEY - For Perplexity API
• SLACK_BOT_TOKEN - For Slack messaging

Most functions also accept explicit authentication parameters if you prefer not to use environment variables.

Table of Contents

• Installation
• Usage
• makeLLMCall
• sendMessageToSlack
• callPerplexityAPI
• invokeLambdaFunction
• Zip File Utilities
• AWS S3 Utilities
• JSON Utilities

makeLLMCall

The makeLLMCall function is designed to facilitate seamless interactions with OpenAI's large language models (LLMs).

Input parameters

• prompt (string): The text prompt to send to the LLM
• responseFormat (string | object): The desired format of the response. Can be:
  • "text": Returns plain text response
  • "json": Returns parsed JSON object
  • JSON schema object: Returns parsed object conforming to the provided schema
• options (object, optional): Additional options for the API call
  • model (string, optional): The model to use (default: "gpt-4o-mini" for OpenAI)
  • tokens (number, optional): Maximum number of tokens for the response (default: 16000)
  • systemPrompt (string, optional): Custom system prompt to use
  • apiKey (string, optional): Custom API key to use for the OpenAI API (defaults to the configured OPENAI_API_KEY)

Output

The function returns an object with two main properties:

• response: The processed response from the LLM
  • For "text" responseFormat: A string containing the LLM's response
  • For "json" responseFormat: A parsed JSON object
  • For JSON schema responseFormat: A parsed object conforming to the provided schema
• usage: Metadata about the API call
  • prompt_tokens: Number of tokens in the prompt
  • completion_tokens: Number of tokens in the response
  • provider: The AI provider used (e.g., 'openai')
  • model: The model used for the completion
  • cost: Calculated cost of the API call in USD (OpenAI only)

makeLLMCall Usage

To use makeLLMCall in your application:

import { lumic } from "lumic-utility-functions";

// Example with text response
const result = await lumic.llm.call(
  "Make up a silly joke about anything random.",
  "text",
  { model: "o1-mini", apiKey: "your-api-key" }
);

// Example with JSON response
const jsonResult = await lumic.llm.call(
  "Describe the Persian Empire in JSON format.",
  "json",
  { apiKey: "your-api-key" }
);

// Example with JSON schema
const schema = {
  type: "json_schema",
  schema: {
    type: "object",
    properties: {
      name: { type: "string" },
      age: { type: "number" },
      hobbies: { type: "array", items: { type: "string" } }
    },
    required: ["name", "age"]
  }
};

const schemaResult = await lumic.llm.call(
  "Generate a person's profile",
  schema,
  { apiKey: "your-api-key" }
);

callPerplexityAPI

The callPerplexityAPI function is designed to send a query to the Perplexity API and return the response.

Input parameters

• query (string): The text query to send to the Perplexity API.
• maxTokens (number, optional): The maximum number of tokens for the response (default: 4000).
• apiKey (string, optional): The API key to use for the Perplexity API (defaults to the configured PERPLEXITY_API_KEY).

If neither the parameter apiKey is passed nor the PERPLEXITY_API_KEY environment variable is set, an error will be thrown.

Output

The function returns a string containing the response from the Perplexity API.

callPerplexityAPI Usage

import { lumic } from "lumic-utility-functions";

const result = await lumic.llm.callPerplexity("What is the capital of France?");
console.log(result); // "The capital of France is Paris."

invokeLambdaFunction

The invokeLambdaFunction function is designed to invoke an AWS Lambda function.

Input parameters

• functionName (string): The name of the Lambda function to invoke.
• payload (object, optional): The payload to send to the Lambda function (default: empty object).
• invocationType (string, optional): The type of invocation (default: 'RequestResponse').
• auth (object, optional): AWS credentials for Lambda invocation. If not provided, falls back to environment variables.
  • AWS_ACCESS_KEY_ID (string): AWS access key ID
  • AWS_SECRET_ACCESS_KEY (string): AWS secret access key
  • AWS_REGION (string): AWS region

Output

The function returns the parsed response from the invoked Lambda function.

invokeLambdaFunction Usage

import { lumic } from "lumic-utility-functions";

// Using environment variables
const result = await lumic.lambda.invoke(
  "myLambdaFunction",
  { key: "value" }
);

// Using explicit auth credentials
const resultWithAuth = await lumic.lambda.invoke(
  "myLambdaFunction",
  { key: "value" },
  'RequestResponse',
  {
    AWS_ACCESS_KEY_ID: 'your-access-key',
    AWS_SECRET_ACCESS_KEY: 'your-secret-key',
    AWS_REGION: 'us-west-2'
  }
);

// result will be:
// {
//   statusCode: 200,
//   body: { message: "Success" }
// }

sendMessageToSlack

The sendMessageToSlack function is designed to send a message to a specified Slack channel.

Input parameters

• channel (string): The Slack channel to send the message to.
• message (string): The message content to send.

Output

The function returns a boolean indicating whether the message was successfully sent.

sendMessageToSlack Usage

import { lumic } from "lumic-utility-functions";

const success = await lumic.slack.sendMessage("#general", "Hello, Slack!");
console.log(success); // true if message was sent successfully

Zip File Utilities

The lumic-utility-functions package includes a set of file management utilities to work with zip files, along with other general utility functions. These include creating zip archives, extracting files, and adding new items to an existing zip file.

createZipFile

The createZipFile function compresses a directory into a zip file.

Input parameters

• sourceDir (string): The path of the directory to compress. It must start with /tmp/ for security purposes.

Output

• A string containing the path to the created zip file.

Example

import { lumic } from "lumic-utility-functions";

const zipFilePath = await lumic.zip.create("/tmp/myDirectory");
console.log(`Zip file created at: ${zipFilePath}`);

extractZipFile

The extractZipFile function extracts a zip archive into a specified directory.

Input parameters

• zipPath (string): The path to the zip file. It must start with /tmp/.
• destPath (string): The directory where the zip content will be extracted. It must start with /tmp/.

Output

• The path to the extracted directory.

Example

import { lumic } from "lumic-utility-functions";

const destPath = await lumic.zip.extract("/tmp/myZipFile.zip", "/tmp/extractedFolder");
console.log(`Files extracted to: ${destPath}`);

addToZipFile

The addToZipFile function allows adding new files or directories to an existing zip file.

Input parameters

• zipFilePath (string): The path to the existing zip file (must start with /tmp/).
• itemPath (string): The file or directory to add to the zip (must start with /tmp/).
• destPath (string, optional): The destination folder inside the zip.

Output

• The updated zip file path.

Example

import { lumic } from "lumic-utility-functions";

const updatedZip = await lumic.zip.addTo("/tmp/myZipFile.zip", "/tmp/newFile.txt");
console.log(`File added to zip: ${updatedZip}`);

AWS S3 Utilities

The package includes comprehensive S3 management functions:

Core Functions

• create(bucketName, auth?): Creates a new S3 bucket
• destroy(bucketName, auth?): Deletes a bucket and all its contents
• generateBucketName(prefix?): Generates a valid S3 bucket name

File Operations

• upload(bucketName, sourcePath, destinationPath?, auth?): Uploads files/directories
• download(bucketName, s3Path?, localPath?, auth?): Downloads from S3
• readFile(bucket, key, auth?): Reads a single file as a stream
• saveTo(bucket, content, filename?, auth?): Saves content directly to S3
• deleteFile(s3FileUrl, auth?): Deletes a file using its S3 URL

Utility Functions

• generateBucketName(prefix?): Creates a valid bucket name with optional prefix
• checkBucketForFileNamePart(bucketName, fileNamePart, auth?): Searches for files in a bucket

All S3 functions accept an optional auth parameter with AWS credentials, falling back to environment variables if not provided:

const auth = {
  AWS_ACCESS_KEY_ID: 'your-key',
  AWS_SECRET_ACCESS_KEY: 'your-secret',
  AWS_REGION: 'your-region'
};

For security, file operations are restricted to the /tmp directory.

Usage Examples

Creating and Managing Buckets

import { lumic } from "lumic-utility-functions";

// Generate a unique bucket name with prefix
const bucketName = await lumic.s3.generateBucketName("myproject");
// Result: "myproject-a1b2c3d-bucket"

// Create the bucket
await lumic.s3.create(bucketName);

// Clean up when done
await lumic.s3.destroy(bucketName);

Uploading and Downloading Files

// Upload a file
const uploadResult = await lumic.s3.upload(
  "my-bucket",
  "/tmp/myfile.txt",
  "uploads/myfile.txt"
);
// Returns: { s3Url, s3Key, message }

// Download files
const downloadResult = await lumic.s3.download(
  "my-bucket",
  "uploads/",
  "/tmp/downloads"
);

// Stream a file
const fileStream = await lumic.s3.readFile(
  "my-bucket",
  "uploads/myfile.txt"
);

Working with Content

// Save JSON directly to S3
const jsonContent = { name: "John", age: 30 };
const saveResult = await lumic.s3.saveTo(
  "my-bucket",
  jsonContent,
  "data.json"
);
// Creates: data-2024-10-30-123456.json

// Check if a file exists
const searchResult = await lumic.s3.checkBucketForFileNamePart(
  "my-bucket",
  "data-2024"
);
// Returns: { exists: true, fileName: "data-2024-10-30-123456.json", lastModifiedDate: "..." }

// Delete a file using its URL
await lumic.s3.deleteFile(
  "https://my-bucket.s3.region.amazonaws.com/uploads/myfile.txt"
);

Using Custom Authentication

const auth = {
  AWS_ACCESS_KEY_ID: 'your-key',
  AWS_SECRET_ACCESS_KEY: 'your-secret',
  AWS_REGION: 'us-west-2'
};

// Use auth with any S3 function
await lumic.s3.upload(
  "my-bucket",
  "/tmp/myfile.txt",
  "uploads/",
  auth
);

JSON Utilities

The package includes utility functions for working with JSON data, particularly for handling and fixing malformed JSON.

fixBrokenJson

The fixBrokenJson function is a robust JSON parser that attempts to repair and parse malformed JSON strings. It handles common issues such as:

• Missing or mismatched quotes
• Unescaped special characters
• Missing commas
• Trailing commas
• Improperly escaped dollar signs
• Unquoted keys
• Missing braces or brackets

Input parameters

• jsonStr (string): The potentially malformed JSON string to fix and parse

Output

• The parsed JavaScript object if successful, or null if parsing fails completely

Example

import { lumic } from "lumic-utility-functions";

// Fix malformed JSON
const brokenJson = `{
  name: "John",
  age: 30,
  hobbies: ['reading' "writing", coding],
  address: {
    street: '123 Main St,
    city: "Springfield"
  },
}`;

const fixed = lumic.json.fix(brokenJson);
console.log(fixed);
// Output:
// {
//   "name": "John",
//   "age": 30,
//   "hobbies": ["reading", "writing", "coding"],
//   "address": {
//     "street": "123 Main St",
//     "city": "Springfield"
//   }
// }

isValidJson

The isValidJson function checks if a string contains valid JSON.

Input parameters

• jsonString (string): The string to validate as JSON

Output

• boolean: Returns true if the string is valid JSON, false otherwise

Example

import { lumic } from "lumic-utility-functions";

const validJson = '{"name": "John", "age": 30}';
const invalidJson = '{name: John, age: 30}';

console.log(lumic.json.isValid(validJson));                         // true
console.log(lumic.json.isValid(invalidJson));                       // false
console.log(lumic.json.isValid('{"name": "John", "age": 30}'));     // true
console.log(lumic.json.isValid('{name: John, age: 30}'));           // false
console.log(lumic.json.isValid('["a", "b", "c"]'));                 // true
console.log(lumic.json.isValid('not json at all'));                 // false

The JSON utilities are particularly useful when working with:

• API responses that may contain malformed JSON
• User-provided JSON input
• Legacy data formats
• Debugging JSON-related issues
• Converting JSON-like strings to valid JSON objects

TypeScript Support

This package includes TypeScript definitions. When using TypeScript, you'll get full type support and autocompletion for all functions and their parameters.

import { lumic } from "lumic-utility-functions";

// TypeScript will provide type checking and autocompletion
const result = await lumic.llm.call(
  "Your prompt",
  "json",
  { model: "gpt-4o-mini" }
);

Author

The utility-functions project is a product of Lumic.ai.