@voidwalkers/void-functions

Runtime library for writing Void Walkers Void serverless functions. You use it inside the functions/ package that @voidwalkers/void-cli scaffolds; the CLI deploys that package and the Void runtime invokes the functions you register here.

# from your project root, functions live in ./functions
void-cli init
void-cli deploy -F            # deploy all functions
void-cli deploy -F echo       # deploy specific functions

Registering functions

import {registerHttpFunction, registerCallFunction} from '@voidwalkers/void-functions';

// HTTP function: reachable over HTTP, Express-like (req, res)
registerHttpFunction('hello-world', (req, res) => {
  res.send('Hello World!');
});

// Call function: invoked from the client SDK as voidClient.function('echo')(data)
registerCallFunction('echo', (data, context) => {
  // context.projectUser === {id} of the authenticated user, or null when anonymous
  return {context, data};
});

Whether a function is HTTP or call is decided by which register function you call — FunctionType is not something you pass yourself.

Function options

Both registerHttpFunction and registerCallFunction take an optional third options argument. This is where the FunctionSystemRole / FunctionTrigger* enums are used:

import {
  registerCallFunction,
  FunctionSystemRole,
  FunctionTriggerEvent,
  FunctionTriggerSubject
} from '@voidwalkers/void-functions';

// The function that authenticates users (assigns a system role; becomes private)
registerCallFunction('auth', (credentials) => { /* … */ }, {
  systemRole: FunctionSystemRole.UserAuth
});

// Run automatically when a document is written, instead of being called directly
registerCallFunction('on-item-write', (event) => { /* … */ }, {
  trigger: {
    subject: FunctionTriggerSubject.MongoDocument,
    event: FunctionTriggerEvent.Write,
    data: {} // optional, subject-specific configuration
  }
});

// Internal helper that clients must not call directly
registerHttpFunction('internal-webhook', (req, res) => { /* … */ }, {
  isPrivate: true
});

| Option | Type | Effect | | ------------ | -------------------------------------- | ------------------------------------------------------------------------- | | isPrivate | boolean | Marks the function private — not directly callable by clients | | systemRole | FunctionSystemRole | Assigns a platform role (e.g. UserAuth = the user-auth handler); implies private | | trigger | {subject, event, data?} | Runs the function on a platform event instead of direct calls; implies private |

A function is treated as private if any of isPrivate, systemRole, or trigger is set (see how the CLI resolves this in void-cli's deploy step). Private functions are deployed but not exposed for direct client invocation.

The trigger object combines a subject (what to watch) with an event (when to fire), plus an optional subject-specific data payload:

| Enum | Values | | ----------------------- | -------------------------------------------------------------- | | FunctionTriggerSubject | AuthUser (auth_user), MongoDocument (mongo_document), Schedule (schedule) | | FunctionTriggerEvent | Create, Update, Delete, Write, Schedule |

On the client side a call function is invoked like this (see @voidwalkers/void-client):

const result = await voidClient.function('echo')({hello: 'world'});
// => {context: {projectUser: {id: 'UUID'}}, data: {hello: 'world'}}

Reading project config

Values set with void-cli config set <key> <value> are available at runtime:

import {getConfigValue} from '@voidwalkers/void-functions';

const maxItems = await getConfigValue('maxItems', 50); // second arg is the default
const apiKey = await getConfigValue('stripeKey');      // throws if missing and no default

API

| Export | Purpose | | -------------------------------------------- | ----------------------------------------------------------------------- | | registerHttpFunction(name, fn, options?) | Register an HTTP function (req, res) => … | | registerCallFunction(name, fn, options?) | Register a callable function (data, context) => result | | getConfigValue(key, defaultValue?) | Read a project config; throws if missing and no default is provided | | setRegisterHandler(fn) / setGetConfigValueHandler(fn) | Wiring hooks the Void runtime sets — not called by user code |

Enums

Exported for use in the options argument (above) and for typing:

• FunctionSystemRole — UserAuth (the function that authenticates users)
• FunctionTriggerEvent — Create, Update, Delete, Write, Schedule
• FunctionTriggerSubject — AuthUser, MongoDocument, Schedule
• ProjectUserCredentialsType — Custom, Email

(Call vs Http is selected by the register function you call, so the FunctionType enum is internal and not exported.)

Related

• @voidwalkers/void-cli — deploy and manage functions, configs and rules.
• @voidwalkers/void-client — client SDK that calls your functions.