Moose + Hono Integration

A complete integration of Moose OLAP with Hono API server, running side by side with shared ClickHouse database.

🏗️ Architecture Overview

This project demonstrates how to integrate Moose's powerful data modeling and ClickHouse integration with a custom Hono API server. The architecture uses a dual-process approach where Moose and Hono run as separate, independent services that share the same ClickHouse database.

📁 Project Structure

my-app/
├── app/
│   ├── index.ts          # Moose resource definitions (compiler plugin target)
│   ├── server.ts         # Hono API server
│   └── db/
│       ├── models.ts     # Moose data models (OlapTable definitions)
│       ├── views.ts      # Moose views
│       └── client.ts     # ClickHouse client for Hono
├── tsconfig.json         # Main TS config (CommonJS + Moose plugins)
├── tsconfig.node.json    # Runtime TS config (ESNext + Moose plugins)
├── nodemon.json          # File watching configuration
└── moose.config.toml     # Moose configuration

🔧 Key Configuration Decisions

1. Separated Concerns

• app/index.ts: Only exports Moose resources for the compiler plugin
• app/server.ts: Contains the Hono API server logic
• No server code in index.ts: Prevents Moose from trying to run the Hono server

2. Dual TypeScript Configurations

• tsconfig.json: CommonJS + Moose compiler plugins (for building)
• tsconfig.node.json: ESNext + Moose compiler plugins (for runtime with ts-node)

3. Port Separation

• Moose: Uses ports 4000, 5001 (from moose.config.toml)
• Hono: Uses port 3000 (from server.ts)

🚀 Getting Started

Prerequisites

• Node.js 18+
• ClickHouse running locally
• Moose CLI installed

Installation

npm install

Development

Start both services concurrently:

npm run dev

This runs:

• Moose process: moose-cli dev - Handles data layer, ClickHouse setup, compiler plugins
• Hono process: npm run dev:hono - Serves API endpoints with file watching

Individual Services

# Start only Moose
npm run dev:moose

# Start only Hono (with file watching)
npm run dev:hono

🔗 Data Integration

Shared ClickHouse Database

Both services connect to the same ClickHouse instance:

• Moose: Manages schema, tables, materialized views
• Hono: Queries data using QueryClient from @514labs/moose-lib

Client Configuration

// app/db/client.ts
const clickhouseClient = getClickhouseClient({
  host: "localhost",
  port: "18123",
  username: "panda",
  password: "pandapass",
  database: "local",
  useSSL: "false",
});

📊 Data Models

Foo Model (Raw Data)

export interface FooModel {
  primaryKey: Key<string>;
  timestamp: number;
  optionalText?: string;
}

Bar Model (Processed Data)

export interface BarModel {
  primaryKey: Key<string>;
  utcTimestamp: Date;
  hasText: boolean;
  textLength: number;
}

Bar Aggregated Model

export interface BarAggregatedModel {
  dayOfMonth: number & ClickHouseInt<"int64">;
  totalRows: number & ClickHouseInt<"int64">;
  rowsWithText: number & ClickHouseInt<"int64">;
  totalTextLength: number & ClickHouseInt<"int64">;
  maxTextLength: number & ClickHouseInt<"int64">;
}

🌐 API Endpoints

Health Check

GET http://localhost:3000/

Data Ingestion

POST http://localhost:3000/ingest/Foo
Content-Type: application/json

{
  "primaryKey": "test-123",
  "timestamp": 1704067200,
  "optionalText": "This is a test message"
}

Data Querying

# Get bar data with query parameters
GET http://localhost:3000/bar?limit=5&orderBy=totalRows

# Get bar data v1
GET http://localhost:3000/bar/1

🔄 Data Flow

1. Moose (moose-cli dev):

   • Processes app/index.ts with compiler plugins
   • Sets up ClickHouse tables and materialized views
   • Manages data pipeline and transformations

2. Hono (npm run dev:hono):

   • Serves API endpoints on port 3000
   • Uses QueryClient to query ClickHouse
   • Can insert data via FooTable.insert()

🛠️ Development Features

File Watching

The Hono server automatically restarts when you modify TypeScript files in the app/ directory, thanks to nodemon configuration.

TypeScript Compiler Plugins

Both configurations include Moose's TypeScript compiler plugins:

• @514labs/moose-lib/dist/compilerPlugin.js
• typia/lib/transform

Hot Reload

• Moose: Automatically processes changes to data models
• Hono: Restarts server on file changes

🧪 Testing

Test Data Ingestion

curl -X POST http://localhost:3000/ingest/Foo \
  -H "Content-Type: application/json" \
  -d '{
    "primaryKey": "test-123",
    "timestamp": 1704067200,
    "optionalText": "This is a test message"
  }'

Test Data Querying

curl "http://localhost:3000/bar?limit=3&orderBy=totalRows"

🔧 Configuration Files

tsconfig.json

Main TypeScript configuration for building:

• CommonJS modules
• Moose compiler plugins
• Strict type checking

tsconfig.node.json

Runtime TypeScript configuration:

• ESNext modules
• ts-node specific settings
• Moose compiler plugins for runtime

nodemon.json

File watching configuration:

• Watches app/ directory
• Ignores test files
• Uses ts-node with Moose compiler plugins

🎯 Key Success Factors

1. Process Separation: Moose and Hono run independently, avoiding conflicts
2. Compiler Plugin Compatibility: Both configs include Moose's TypeScript compiler plugins
3. Shared Database: Both services use the same ClickHouse instance
4. Proper Module Resolution: CommonJS for building, ESNext for runtime
5. File Watching: nodemon provides development experience without breaking Moose plugins

📝 Scripts

• npm run dev - Start both Moose and Hono concurrently
• npm run dev:moose - Start only Moose
• npm run dev:hono - Start only Hono with file watching
• npm run build - Build the project
• npm run start - Start the built application

🤝 Contributing

This integration demonstrates how to combine Moose's powerful data modeling capabilities with custom API servers. The architecture can be adapted for other web frameworks or use cases.