WeWeb Backend Core

Core library for building and serving backend workflows in WeWeb applications. This package provides the foundation for creating configurable, secure API endpoints with flexible request handling and integration with external services.

Features

• API route handling and serving with Hono
• Dynamic workflow configuration and execution
• Security configuration with public/private access rules
• Advanced input validation and mapping
• Integration with external services via pluggable integrations
• Error handling and response formatting
• CORS support

Installation

This package is part of the WeWeb Supabase Backend Builder and is designed to be used with Deno.

import type { BackendConfig } from '@yamakasinge/backend-core';
import { serve } from '@yamakasinge/backend-core';

Core Concepts

Backend Configuration

The BackendConfig interface defines the structure for configuring your backend:

interface BackendConfig {
  workflows: Workflow[]
  integrations: PluginIntegration[]
  production: boolean
  rolesConfig?: RolesConfig
}

Workflows

Workflows define API endpoints with their HTTP methods, security settings, input validation, and actions:

interface Workflow {
  path: string
  methods: HttpMethod[]
  inputsValidation?: {
    query?: Record<string, unknown>
    body?: Record<string, unknown>
  }
  security?: {
    accessRule: 'public' | 'private'
    accessRoles?: string[]
    accessRolesCondition?: 'OR' | 'AND'
  }
  workflow: WorkflowAction[]
}

Integrations

Integrations allow external services to be accessed through defined methods:

interface PluginIntegration {
  name: string
  slug: string
  methods: {
    [slug: string]: (...args: any[]) => MaybePromise<any>
  }
}

Input Mapping

The package includes a powerful input mapping system that allows you to transform and map request data (query parameters, body, headers) to action inputs:

// Example input mapping
const mapping = {
  userId: '$query.id',
  userName: '$body.user.name',
  apiKey: '$headers.x-api-key',
  staticValue: 'constant',
  nestedValue: {
    fromBody: '$body.nested.value',
  },
};

Basic Usage

import type { BackendConfig } from '@yamakasinge/backend-core';
import { serve } from '@yamakasinge/backend-core';

// Define your backend configuration
const config: BackendConfig = {
  workflows: [
    {
      path: '/hello',
      methods: ['GET'],
      security: {
        accessRule: 'public',
      },
      workflow: [
        {
          type: 'action',
          id: 'hello_action',
          actionId: 'example.say_hello',
          inputMapping: [],
        },
      ],
    },
  ],
  integrations: [
    {
      name: 'Example',
      slug: 'example',
      methods: {
        say_hello: () => {
          return { message: 'Hello, World!' };
        },
      },
    },
  ],
  production: false,
};

// Start the server
const server = serve(config);
console.log('Server running on http://localhost:8000');

Advanced Features

Input Validation

Define JSON Schema validation for request bodies and query parameters:

const config = {
  path: '/users',
  methods: ['POST'],
  inputsValidation: {
    body: {
      type: 'object',
      properties: {
        name: { type: 'string' },
        email: { type: 'string', format: 'email' },
      },
      required: ['name', 'email'],
    },
  },
  // ...
};

Security Rules

Configure endpoints with public or private access rules:

const config = {
  security: {
    accessRule: 'private',
    accessRoles: ['admin', 'editor'],
    accessRolesCondition: 'OR', // User needs to be either admin OR editor
  }
};

Multi-action Workflows

Chain multiple actions in a workflow and pass results between them:

const config = {
  workflow: [
    {
      type: 'action',
      id: 'first_action',
      actionId: 'example.getData',
      inputMapping: [{ param: '$query.id' }],
    },
    {
      type: 'action',
      id: 'second_action',
      actionId: 'example.processData',
      inputMapping: [{ data: '$results.first_action.value' }],
    },
  ],
};

Development

Testing

The package uses Behavior-Driven Development (BDD) for testing:

import { expect } from 'jsr:@std/expect';
import { describe, it } from 'jsr:@std/testing/bdd';

describe('Feature', () => {
  it('should work correctly', () => {
    // Test code
    expect(result).toBe(expectedValue);
  });
});

Run tests with:

deno test

Code Quality

Format and lint your code:

deno fmt
deno lint

API Reference

Main Exports

• serve(config: BackendConfig): Deno.HttpServer - Starts the HTTP server with the provided configuration
• BackendConfig - Type for the backend configuration
• HttpMethod - Type for HTTP methods ("GET" | "POST" | "PUT" | "DELETE" | "PATCH")
• PluginIntegration - Type for integration definitions
• RequestContext - Type for the request context passed to actions
• RolesConfig - Type for role-based access control configuration
• Workflow - Type for workflow definitions
• WorkflowAction - Type for actions within workflows