@node-lambdas/core

The main code behind all "function-as-a-service" utilities at jsfn.run.

Introduction

Node Lambdas are tiny HTTP servers that receive an input request and generate an output. Each function has its own web address and works like a regular server.

The main motivation is to make it dead-easy to spin up new services that expose any NPM module or API under the hood.

Do you need to convert an image? Parse a YAML? Validate a JSON? Instead of installing something, just post it to a Node Lambda!

Functions API

A node-lambda is a single .mjs file that exports a configuration object.

A function handler receives two arguments, input and output.

They are the same instances of a normal Node.JS HTTP server, with some additional properties:

interface Request extends IncomingMessage {
  credentials: Record<string, string>;
  options: Record<string, string>;
  asText(): Promise<string>;
  asJson(): Promise<any>;
  asBuffer(): Promise<Buffer>;
}

interface Response extends ServerResponse {
  request: Request;
  header(name: string, value: string): void;
  reject(message: string): void;
  sendText(b: string): void;
  sendJson(b: any): void;
  sendBuffer(b: Buffer): void;
  pipeTo(nextCommand: string, args: string[]): void;
  send(body: any): void;
  send(status: number, body: any): void;
}

Examples

The simplest function just prints its input back to the output:

// index.mjs
export default function sendInputBack(input, output) {
  input.pipe(output);
}

A more useful example: create a hash from the input text

import { createHash } from 'node:crypto';

export default {
  version: 2,
  description: 'Create a hash from the input. Set the "type" option to any Node.js hash algorithm, like sha256',
  actions: {
    createHash: {
      default: true,
      options: {
        type: 'algorithm',
      },
      handler(input, output) {
        const type = input.options.type || 'sha256';
        const hash = createHash(type);
        input.on('data', c => hash.update(c));
        input.on('end', () => output.sendText(hash.digest('hex')));
      }
    }
  }
}

Function Configurations

To allow multiple actions in a single cloud function, and allow for options, the API prefers an object as a default export. For example:

// index.mjs

export default {
  actions: {
    echo: {
      default: true,
      handler(input, output) {
        input.pipe(output);
      }
    },
  },
};

This function is invoked calling POST https://echo.jsfn.run/ with any content. The data is just sent back as a stream.

Input/Output

A lambda handler function will receive two arguments, input and output, which are just Node.js request and response objects from an incoming request.

They have a few extra properties:

request.body

| input type | request.body | | ----------- | ------------ | | text | string | | json | object | | buffer | Buffer | | - not set - | undefined |

If not set, the request data won't be read from stream. Use request.on('data') and request.on('end') to read the input in the action.

response output (via output.send(response))

| output type | response body | | ----------- | ------------- | | text | string | | json | JSON string | | buffer | binary output | | - not set - | binary output |

In v1 only one input/output format can be specified In v2, each action can specify a different input/input/output format.

request.options

In v2, options are parsed from the query string parameters sent by the incoming HTTP request.

For example, consider a call to function foo with POST /action?alice=1&bob=2. Then request.options will be an object like { alice: 1, bob: 2 }

request.parsedUrl

Since v2. This is set to an instance of URL parsed from request.url.

Configuration object

v1

Accepts a configuration object and a simple handler function.

function textToJson(input, output) {
  const textInput = input.body;
  const jsonOutput = { text: textInput };

  output.sendJson(jsonOutput);
}

export default {
  version: 1,
  input: 'text',
  output: 'json',
  handler: main,
};

v2

Accepts multiple actions in a single lambda. One of the actions can be marked as default.

import { lambda, Format } from '@node-lambdas/core';

// encode text as JSON
function encode(text) {
  return { text };
}

// decode JSON back to text
function decode(json) {
  return json.text;
}

const configuration = {
  version: 2,
  description: '',
  actions: {
    encode: {
      default: true,
      input: 'text',
      output: 'json',
      handler: (input, output) => output.send(encode(input.body)),
    },

    decode: {
      input: 'json',
      output: 'text',
      handler: (input, output) => output.send(decode(input.body)),
    },
  },
};

export default configuration;

Version history

v1

First version. Just process input and send back an output.

v2

• Add support for multiple actions and different input/output formats per action.
• Parses the incoming URL
• adds request.options and request.credentials