@morphql/server 0.1.17 → 0.1.18

package/README.md

@@ -1,245 +1,59 @@
-# MorphQL Server
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Hyperwindmill/morphql/main/morphql.png" alt="MorphQL" width="200" />
+</p>
 
-A high-performance, stateless NestJS API for the MorphQL transformation engine.
+<p align="center">
+  <a href="https://www.npmjs.com/package/@morphql/server"><img src="https://img.shields.io/npm/v/@morphql/server?label=%40morphql%2Fserver" alt="npm version" /></a>
+  <img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT" />
+</p>
 
-## Overview
+# @morphql/server
 
-This server provides a RESTful interface to compile and execute Morph Query Language (MorphQL) transformations. Built with NestJS, it's designed to be a lightweight, scalable microservice that can be deployed in containerized environments.
+A headless transformation server core for **MorphQL**. Designed to be embedded into existing NestJS or Node.js applications to provide managed transformation endpoints with caching and OpenAPI support.
 
-### Features
+## Core Features
 
-- 🚀 **Stateless Execution**: Designed for horizontal scaling
-- 🔄 **Isomorphic Engine**: Run the exact same transformations as the client-side library
-- ⚡ **Redis Caching**: Built-in compiled query caching for high-throughput scenarios
-- 🐳 **Docker Ready**: Production-optimized multi-stage container images
-- 🔐 **API Key Authentication**: Optional security via `X-API-KEY` header
-- 📊 **Swagger Documentation**: Interactive API docs at `/api`
-- 🏥 **Health Checks**: Liveness and readiness endpoints for orchestration
+- 🏗️ **Headless Core**: Embed MorphQL management into your own backend.
+- 🔗 **Staged Queries**: Map `.morphql` files to named API endpoints automatically.
+- ⚡ **Redis Integration**: Strategic caching of compiled queries for maximum throughput.
+- 📖 **Auto-OpenAPI**: Generates Swagger/OpenAPI fragments for all defined transformations.
+- 🛡️ **Type-Safe**: Inferred schemas for request and response formats.
 
-## Quick Start
-
-### Docker Compose (Recommended)
-
-```bash
-# Start server + Redis
-docker compose up -d
-
-# View logs
-docker compose logs -f server
-
-# Stop services
-docker compose down
-```
-
-The server will be available at `http://localhost:3000` with Swagger docs at `http://localhost:3000/api`.
-
-### Development Mode
-
-```bash
-# From monorepo root
-npm run server
-
-# Or from packages/server
-npm run start:dev
-```
-
-## API Reference
-
-All endpoints are prefixed with `/v1`. Full interactive documentation is available at `/api` when the server is running.
-
-### 1. Execute Transformation
-
-Compile and execute a query against data in a single request.
-
-**Endpoint**: `POST /v1/execute`
-
-**Request**:
-
-```json
-{
-  "query": "from json to json transform set firstName = split(fullName, ' ')[0]",
-  "data": { "fullName": "John Doe" }
-}
-```
-
-**Response**:
-
-```json
-{
-  "success": true,
-  "result": { "firstName": "John" },
-  "executionTime": 2.5
-}
-```
-
-**Example with curl**:
-
-```bash
-curl -X POST http://localhost:3000/v1/execute \
-  -H "Content-Type: application/json" \
-  -d '{
-    "query": "from json to json transform set name = fullName",
-    "data": { "fullName": "Jane Smith" }
-  }'
-```
-
-### 2. Compile Query
-
-Get the generated JavaScript code for a query without executing it.
-
-**Endpoint**: `POST /v1/compile`
-
-**Request**:
-
-```json
-{
-  "query": "from json to xml transform set name = fullName"
-}
-```
-
-**Response**:
-
-```json
-{
-  "success": true,
-  "code": "function(source) { /* generated code */ }"
-}
-```
-
-### 3. Health Checks
-
-**Liveness**: `GET /v1/health`
-
-```json
-{ "status": "ok", "timestamp": "2026-01-20T00:00:00.000Z" }
-```
-
-**Readiness**: `GET /v1/health/ready`
-
-- Returns `200` if service and Redis (if configured) are ready
-- Returns `503` if Redis is configured but unavailable
-
-## Configuration
-
-Configure the server via environment variables:
-
-| Variable       | Description                          | Default | Required |
-| -------------- | ------------------------------------ | ------- | -------- |
-| `PORT`         | Server port                          | `3000`  | No       |
-| `NODE_ENV`     | Environment mode                     | -       | No       |
-| `REDIS_HOST`   | Redis hostname for caching           | -       | No       |
-| `REDIS_PORT`   | Redis port                           | `6379`  | No       |
-| `REDIS_PREFIX` | Cache key prefix                     | `morphql:`  | No       |
-| `API_KEY`      | Optional API key for auth            | -       | No       |
-| `API_KEY_FILE` | Optional API key file (for secrets)  | -       | No       |
-
-**Note**: If `REDIS_HOST` is not set, the server runs without caching (queries are compiled on every request).
-
-## Authentication
-
-The server supports optional API key authentication via the `X-API-KEY` header.
-
-**Enable authentication**:
+## Installation
 
 ```bash
-# Set API_KEY environment variable
-export API_KEY=your-secret-key
-
-# Or in docker-compose.yml
-environment:
-  - API_KEY=your-secret-key
+npm install @morphql/server @morphql/core
 ```
 
-**Making authenticated requests**:
-
-```bash
-curl -X POST http://localhost:3000/v1/execute \
-  -H "X-API-KEY: your-secret-key" \
-  -H "Content-Type: application/json" \
-  -d '{"query": "...", "data": {...}}'
-```
+## Basic Usage (NestJS/Node)
 
-If `API_KEY` is not set, all requests are allowed (useful for development).
+```typescript
+import { MorphServer } from '@morphql/server';
 
-## Docker Deployment
+const morph = new MorphServer({
+  queriesDir: './queries', // automatically load .morphql files
+  cache: redisCache, // optional Redis caching
+});
 
-### Building the Image
+await morph.initialize();
 
-```bash
-# From monorepo root
-docker build -f packages/server/Dockerfile -t morphql-server .
-```
-
-### Running with Docker
-
-```bash
-# Without Redis
-docker run -p 3000:3000 morphql-server
-
-# With Redis
-docker run -p 3000:3000 \
-  -e REDIS_HOST=redis.example.com \
-  -e REDIS_PORT=6379 \
-  morphql-server
+// Execute a named staged query
+const result = await morph.executeStaged('user-profile', sourceData);
 ```
 
-### Docker Compose Production
-
-The included `docker-compose.yml` provides a production-ready setup with:
-
-- NestJS server with health checks
-- Redis for query caching
-- Persistent Redis data volume
-- Automatic restart policies
-
-## Development
-
-### Available Scripts
-
-| Command               | Description              |
-| --------------------- | ------------------------ |
-| `npm run start`       | Start in production mode |
-| `npm run start:dev`   | Start with hot-reload    |
-| `npm run start:debug` | Start with debugger      |
-| `npm run build`       | Build for production     |
-| `npm run test`        | Run unit tests           |
-| `npm run test:e2e`    | Run end-to-end tests     |
-| `npm run lint`        | Lint and fix code        |
-
-### Project Structure
-
-```
-packages/server/
-├── src/
-│   ├── main.ts              # Application entry point
-│   ├── app.module.ts        # Root module
-│   ├── morph.controller.ts  # API endpoints
-│   └── auth.guard.ts        # API key authentication
-├── test/                    # E2E tests
-├── Dockerfile               # Multi-stage production build
-├── docker-compose.yml       # Local deployment stack
-└── package.json
-```
-
-## Performance
-
-- **Caching**: When Redis is enabled, compiled queries are cached indefinitely (queries are deterministic)
-- **Stateless**: Each request is independent, enabling horizontal scaling
-- **Async**: All endpoints use async/await for non-blocking I/O
-
-## Monitoring
+## Standalone Usage
 
-The server provides structured logging via NestJS:
+If you need a ready-to-deploy microservice, check the **[Server Instance Starter Template](https://github.com/Hyperwindmill/morphql/tree/main/packages/server-instance)** in our repository. It includes:
 
-- Request routing and mapping on startup
-- Error logging with stack traces
-- Performance metrics in `executionTime` field
+- Docker & Docker Compose setup
+- Pre-configured NestJS application
+- Health checks (Liveness/Readiness)
+- API Key authentication
 
-For production monitoring, consider:
+## Learn More
 
-- Health check endpoints for Kubernetes/Docker Swarm
-- Redis monitoring for cache hit rates
-- Application Performance Monitoring (APM) tools
+- 👉 **[Official Documentation](https://hyperwindmill.github.io/morphql/)**
+- 🏠 **[Main Repository](https://github.com/Hyperwindmill/morphql)**
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@morphql/server",
-  "version": "0.1.17",
+  "version": "0.1.18",
   "description": "MorphQL Server Core - Headless transformation engine",
   "author": "Hyperwindmill",
   "private": false,
@@ -29,10 +29,10 @@
     "js-yaml": "^4.1.1"
   },
   "peerDependencies": {
-    "@morphql/core": "^0.1.17"
+    "@morphql/core": "^0.1.18"
   },
   "devDependencies": {
-    "@morphql/core": "^0.1.17",
+    "@morphql/core": "^0.1.18",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^25.2.0",
     "typescript": "^5.9.3",