Skip to content

README.md

Latest commit

 

History

History
156 lines (119 loc) · 4.76 KB

README.md

File metadata and controls

156 lines (119 loc) · 4.76 KB

Cloudflare Workers API for Couchbase

This project demonstrates how to build a Cloudflare Workers-based API using the Hono framework that interfaces with Couchbase's Data API to manage airport data from the travel-sample dataset.

Note: The FTS features require:

  1. A Full Text Search index with geo-spatial mapping on hotel documents
  2. The travel-sample dataset with hotel documents in the inventory.hotel collection
  3. Hotels must have geo coordinates (geo.lat and geo.lon fields) for proximity search

Prerequisites

Setup

  1. Clone the repository
  2. Navigate to the cloudflare-workers directory:
cd cloudflare-workers
  1. Install dependencies:
npm install
  1. Configure your database (see Database Configuration in the main README)
  2. Configure your environment variables (see Deployment section for details)

FTS Index Setup

Before using the hotel search functionality, you need to create a Full Text Search index. Use the Node.js script provided in the root of the repository.

See ../scripts/README.md for detailed instructions on creating the required hotel-geo-index for geo-spatial hotel searches.

Development

Start the development server:

npm run dev

Deployment

Prerequisites

Authentication

wrangler login

Environment Variables

Set your Couchbase Data API credentials using one of these methods:

Option 1: Cloudflare Dashboard (Recommended)

  1. Deploy first: npm run deploy
  2. Go to Workers Dashboard → Your Worker → Settings → Environment Variables
  3. Add: DATA_API_USERNAME, DATA_API_PASSWORD, DATA_API_ENDPOINT as secrets

Option 2: CLI Secrets

wrangler secret put DATA_API_USERNAME
wrangler secret put DATA_API_PASSWORD
wrangler secret put DATA_API_ENDPOINT

Option 3: wrangler.jsonc (Development only)

{
  "vars": {
    "DATA_API_USERNAME": "your_username",
    "DATA_API_PASSWORD": "your_password",
    "DATA_API_ENDPOINT": "your_endpoint"
  }
}

Deploy

npm run deploy

Testing

This project includes comprehensive unit tests for all handler functions using Vitest and the @cloudflare/vitest-pool-workers testing framework.

Running Tests

Run all unit tests:

npm run test

Run specific test categories:

# Run only unit tests
npm run test:unit

# Run only handler tests
npm run test:handlers

# Run a specific test file
npm test test/handlers/getHotelsNearAirport.spec.ts

Integration Tests

Integration tests are available to test against your deployed Worker. These tests perform real API calls to your deployed Cloudflare Worker endpoint.

Run integration tests:

#Set environment variable and run
export WORKER_URL="https://your-worker.your-subdomain.workers.dev"
npm run test:integration

Project Structure

src/
├── handlers/          # API route handlers
│   ├── createAirport.ts
│   ├── getAirport.ts
│   ├── updateAirport.ts
│   ├── deleteAirport.ts
│   ├── getAirportRoutes.ts
│   ├── getAirportAirlines.ts
│   └── getHotelsNearAirport.ts
├── types/             # TypeScript type definitions
│   └── env.ts
├── utils/             # Utility functions
└── index.ts           # Main application entry point
test/
├── handlers/          # Handler unit tests
│   ├── createAirport.spec.ts
│   ├── getAirport.spec.ts
│   ├── updateAirport.spec.ts
│   ├── deleteAirport.spec.ts
│   ├── getAirportRoutes.spec.ts
│   ├── getAirportAirlines.spec.ts
│   └── getHotelsNearAirport.spec.ts
├── utils/             # Test utilities and helpers
│   └── testHelpers.ts
├── integration.test.ts # Integration tests for deployed Worker
└── setup.ts           # Test setup configuration