Skip to main content

​
Overview

The loadNavaiFunctions function dynamically loads TypeScript/JavaScript modules and extracts callable functions, class methods, and object members into a registry. This registry can be used to execute functions by name at runtime, enabling OpenAI Realtime API function calling.

​
Function Signature

async function loadNavaiFunctions(
  functionModuleLoaders: NavaiFunctionModuleLoaders
): Promise<NavaiFunctionsRegistry>

​
Parameters

​
functionModuleLoaders
NavaiFunctionModuleLoaders
required
A record mapping module paths to their dynamic import loaders.
type NavaiFunctionModuleLoaders = Record<string, () => Promise<unknown>>;
Example:
{
  'src/ai/functions-modules/weather.ts': () => import('./weather'),
  'src/ai/functions-modules/calculator.ts': () => import('./calculator')
}

​
Return Type

​
NavaiFunctionsRegistry
object
A registry containing all loaded functions with lookup capabilities.

​
Type Definitions

type NavaiFunctionDefinition = {
  name: string;              // Normalized function name (snake_case)
  description: string;       // Human-readable description
  source: string;            // Module path and export name
  run: (                     // Callable function
    payload: NavaiFunctionPayload,
    context: NavaiFunctionContext
  ) => Promise<unknown> | unknown;
};

type NavaiFunctionPayload = Record<string, unknown>;
The payload object passed to functions. Special keys:
  • args or arguments: Array of direct arguments
  • value: Single value argument
  • constructorArgs: Constructor arguments for class methods
  • methodArgs: Method arguments for class methods
type NavaiFunctionContext = Record<string, unknown>;
Context object passed to functions (e.g., Express request object).

​
Function Loading Behavior

The loader automatically handles different export patterns:

​
1. Exported Functions

// weather.ts
export function getCurrentWeather(location: string) {
  return { temp: 72, location };
}
Registered as: get_current_weather

​
2. Default Function Export

// calculator.ts
export default function add(a: number, b: number) {
  return a + b;
}
Registered as: add (uses function name)

​
3. Class Exports

// EmailService.ts
export class EmailService {
  sendEmail(to: string, subject: string) {
    // Send email logic
  }
  
  scheduleEmail(to: string, time: Date) {
    // Schedule logic
  }
}
Registered as:
  • email_service_send_email
  • email_service_schedule_email

​
4. Object Exports

// utils.ts
export const math = {
  add: (a: number, b: number) => a + b,
  multiply: (a: number, b: number) => a * b
};
Registered as:
  • math_add
  • math_multiply

​
Example Usage

import { loadNavaiFunctions } from '@navai/voice-backend';

const loaders = {
  'src/functions/weather.ts': () => import('./functions/weather'),
  'src/functions/calculator.ts': () => import('./functions/calculator')
};

const registry = await loadNavaiFunctions(loaders);

console.log('Loaded functions:', registry.ordered.map(f => f.name));
console.log('Warnings:', registry.warnings);

// Execute a function
const weatherFn = registry.byName.get('get_current_weather');
if (weatherFn) {
  const result = await weatherFn.run({ location: 'San Francisco' }, {});
  console.log(result);
}

​
Name Normalization

Function names are automatically normalized to snake_case:
  • getCurrentWeather → get_current_weather
  • EmailService.sendEmail → email_service_send_email
  • math.add → math_add
Duplicate names are automatically renamed with numeric suffixes (_2, _3, etc.) and a warning is emitted.

​
Warnings

The function emits warnings for:
  • Modules with no exports
  • Modules with no callable exports
  • Classes with no instance methods
  • Objects with no callable members
  • Duplicate function names (after normalization)
  • Module loading failures
  • TypeScript declaration files (.d.ts - automatically skipped)
Always check the warnings array in production to catch configuration issues early.

​
Source Reference

Defined in: packages/voice-backend/src/functions.ts:278

Build docs developers (and LLMs) love

Get started for freeTalk to us