@mantajs/core 0.1.6 → 0.2.0-beta.0

package/docs/13-testing.md

@@ -0,0 +1,345 @@
+# Testing
+
+## Philosophy
+
+The framework provides `@mantajs/test-utils` with in-memory adapters, spies, and helpers so tests run fast (no database, no network) and are deterministic.
+
+**Types of tests:**
+
+| Type | What it tests | Speed | Database |
+|------|--------------|-------|----------|
+| Unit | Models, services, validators | <1ms | No |
+| Integration | Commands, workflows, compensation | <100ms | No (in-memory) |
+| E2E | Full HTTP flow (command → event → subscriber) | <500ms | Optional |
+
+## Project structure
+
+Tests live in a `tests/` folder at the root of your project (outside `src/`):
+
+```
+my-project/
+├── src/
+│   ├── modules/
+│   ├── commands/
+│   ├── queries/
+│   └── ...
+├── tests/
+│   ├── unit/
+│   │   ├── product.test.ts        # Service CRUD + custom methods
+│   │   ├── inventory.test.ts
+│   │   └── commands.test.ts       # Command validation
+│   ├── integration/
+│   │   ├── create-product.test.ts # Full workflow with compensation
+│   │   └── auth.test.ts           # Login/logout flow
+│   └── e2e/
+│       └── api.test.ts            # HTTP endpoint testing
+├── manta.config.ts
+└── package.json
+```
+
+Why outside `src/`? The framework scans `src/` for modules, commands, queries, etc. Test files in `src/` could be picked up accidentally.
+
+## Setup
+
+```typescript
+import {
+  createTestMantaApp,
+  InMemoryCacheAdapter,
+  InMemoryEventBusAdapter,
+  InMemoryFileAdapter,
+  InMemoryLockingAdapter,
+  InMemoryRepository,
+  TestLogger,
+} from '@mantajs/test-utils'
+import { describe, expect, it, beforeEach, afterEach } from 'vitest'
+
+function makeTestInfra() {
+  return {
+    eventBus: new InMemoryEventBusAdapter(),
+    logger: new TestLogger(),
+    cache: new InMemoryCacheAdapter(),
+    locking: new InMemoryLockingAdapter(),
+    file: new InMemoryFileAdapter(),
+  }
+}
+
+describe('My tests', () => {
+  let app: TestMantaApp
+
+  beforeEach(() => {
+    app = createTestMantaApp({ infra: makeTestInfra() })
+  })
+
+  afterEach(async () => {
+    await app.dispose()
+  })
+})
+```
+
+## Testing a service
+
+```typescript
+import { InMemoryRepository, instantiateServiceDescriptor } from '@mantajs/test-utils'
+import productService from '../src/modules/catalog/entities/product/service'
+import productModel from '../src/modules/catalog/entities/product/model'
+
+describe('Product service', () => {
+  let repo: InMemoryRepository
+  let service: Record<string, Function>
+
+  beforeEach(() => {
+    repo = new InMemoryRepository('product')
+    service = instantiateServiceDescriptor(productService, repo, undefined, new TestLogger())
+  })
+
+  it('createProducts creates a product', async () => {
+    const product = await service.createProducts({
+      title: 'Widget', sku: 'W-001', price: 999, status: 'draft',
+    })
+    expect(product.title).toBe('Widget')
+    expect(product.id).toBeDefined()
+  })
+
+  it('activate changes status', async () => {
+    const product = await service.createProducts({
+      title: 'Widget', sku: 'W-001', price: 999, status: 'draft',
+    })
+    await service.activate(product.id)
+    const updated = await repo.find({ where: { id: product.id } })
+    expect(updated[0].status).toBe('active')
+  })
+
+  it('listProducts returns all products', async () => {
+    await service.createProducts({ title: 'A', sku: 'A-001', price: 10, status: 'draft' })
+    await service.createProducts({ title: 'B', sku: 'B-001', price: 20, status: 'active' })
+    const list = await service.listProducts()
+    expect(list).toHaveLength(2)
+  })
+})
+```
+
+Service methods are auto-compensated via repository snapshots. No manual `__compensate` needed.
+
+## Testing a command
+
+```typescript
+describe('create-product command', () => {
+  it('validates input with Zod', () => {
+    const cmd = defineCommand({
+      name: 'create-product',
+      description: 'Create a product',
+      input: z.object({
+        title: z.string().min(1),
+        sku: z.string(),
+        price: z.number().min(0),
+      }),
+      workflow: async (input, { step }) => {
+        return await step.service.catalog.create(input)
+      },
+    })
+
+    // Valid input
+    expect(cmd.input.safeParse({ title: 'Widget', sku: 'W-001', price: 99 }).success).toBe(true)
+
+    // Invalid input
+    expect(cmd.input.safeParse({ title: '', price: -1 }).success).toBe(false)
+  })
+})
+```
+
+## Testing a subscriber
+
+Subscribers receive `(event, { command, log })`. Test them by calling the handler directly:
+
+```typescript
+import productCreated from '../src/subscribers/product-created'
+
+describe('product-created subscriber', () => {
+  it('dispatches a command', async () => {
+    let commandCalled = false
+    const mockCommand = {
+      initializeInventory: async (input: unknown) => { commandCalled = true },
+    }
+    const mockLog = { info: () => {}, warn: () => {}, error: () => {} }
+
+    const event = {
+      eventName: 'product.created',
+      data: { id: 'prod_1', sku: 'W-001' },
+      metadata: { timestamp: Date.now() },
+    }
+
+    await productCreated.handler(event, { command: mockCommand, log: mockLog })
+    expect(commandCalled).toBe(true)
+  })
+})
+```
+
+## Testing a job
+
+Jobs also receive `{ command, log }`:
+
+```typescript
+import cleanupJob from '../src/jobs/cleanup-drafts'
+
+describe('cleanup-drafts job', () => {
+  it('dispatches cleanup command', async () => {
+    let cleanupInput: unknown = null
+    const mockCommand = {
+      cleanupDraftProducts: async (input: unknown) => { cleanupInput = input },
+    }
+    const mockLog = { info: () => {} }
+
+    await cleanupJob.handler({ command: mockCommand, log: mockLog })
+    expect(cleanupInput).toEqual({ olderThanDays: 30 })
+  })
+})
+```
+
+## Testing events with spies
+
+```typescript
+describe('Event emission', () => {
+  let bus: InMemoryEventBusAdapter
+
+  beforeEach(() => {
+    bus = new InMemoryEventBusAdapter()
+  })
+
+  it('product.created event is emitted', async () => {
+    const received: Message[] = []
+    bus.subscribe('product.created', (event) => { received.push(event) })
+
+    await bus.emit({
+      eventName: 'product.created',
+      data: { id: 'prod_1', sku: 'W-001' },
+      metadata: { timestamp: Date.now() },
+    })
+
+    expect(received).toHaveLength(1)
+    expect(received[0].data).toEqual({ id: 'prod_1', sku: 'W-001' })
+  })
+
+  it('grouped events are buffered until release', async () => {
+    const received: Message[] = []
+    bus.subscribe('order.placed', (event) => { received.push(event) })
+
+    await bus.emit(
+      { eventName: 'order.placed', data: { id: 'ord_1' }, metadata: { timestamp: Date.now() } },
+      { groupId: 'workflow-1' },
+    )
+
+    expect(received).toHaveLength(0) // Buffered
+
+    await bus.releaseGroupedEvents('workflow-1')
+    expect(received).toHaveLength(1) // Released
+  })
+})
+```
+
+## Testing queries
+
+```typescript
+import { QueryService } from '@mantajs/test-utils'
+
+describe('list-products query', () => {
+  it('returns products via graph', async () => {
+    const queryService = new QueryService()
+    queryService.registerResolver('product', async (config) => {
+      return [
+        { id: '1', title: 'Widget', status: 'active' },
+        { id: '2', title: 'Gadget', status: 'draft' },
+      ].filter((p) => !config.filters?.status || p.status === config.filters.status)
+    })
+
+    const result = await queryService.graph({
+      entity: 'product',
+      filters: { status: 'active' },
+    })
+
+    expect(result).toHaveLength(1)
+    expect(result[0].title).toBe('Widget')
+  })
+})
+```
+
+## Testing with database (integration)
+
+For tests that need a real PostgreSQL database:
+
+```typescript
+import { createTestDatabase, waitForPg } from '@mantajs/test-utils/pg'
+
+describe('Database integration', () => {
+  let dbUrl: string
+  let cleanup: () => Promise<void>
+
+  beforeAll(async () => {
+    await waitForPg(30)
+    const result = await createTestDatabase('test_catalog')
+    dbUrl = result.url
+    cleanup = result.cleanup
+  })
+
+  afterAll(async () => {
+    await cleanup()
+  })
+
+  it('creates and queries products', async () => {
+    // Use dbUrl to connect a real DrizzlePgAdapter
+  })
+})
+```
+
+Name integration test files with `.integration.test.ts` — they are excluded from `pnpm test` and run separately via `pnpm test:integration`.
+
+## Test utilities reference
+
+| Utility | Purpose |
+|---------|---------|
+| `createTestMantaApp(options)` | Create test app with in-memory adapters |
+| `InMemoryRepository(name)` | In-memory data store |
+| `InMemoryEventBusAdapter()` | Event pub/sub with grouped events |
+| `InMemoryCacheAdapter()` | Key-value cache with TTL |
+| `InMemoryLockingAdapter()` | Distributed lock simulation |
+| `InMemoryFileAdapter()` | File storage simulation |
+| `InMemoryJobScheduler()` | Cron job simulation |
+| `TestLogger()` | Logger that captures output |
+| `MockAuthPort()` | Mock JWT/API key verification |
+| `MockAuthModuleService()` | Mock auth with session management |
+| `MessageAggregator()` | Capture events emitted by services |
+| `instantiateServiceDescriptor()` | Create service instance from defineService result |
+| `QueryService()` | Test query handlers with mock resolvers |
+| `WorkflowManager(app)` | Execute workflows in tests |
+| `createTestDatabase(name)` | Isolated PostgreSQL DB per test file |
+| `resetAll(app)` | Reset all in-memory state between tests |
+| `spyOnEvents(app)` | Intercept events for assertions |
+
+## Running tests
+
+```bash
+# Unit + integration tests (fast, no DB)
+pnpm test
+
+# Integration tests only (needs PostgreSQL)
+pnpm test:integration
+
+# Specific file
+npx vitest run tests/unit/product.test.ts
+
+# Watch mode
+npx vitest tests/unit/product.test.ts
+```
+
+## AI guidance: writing tests
+
+When generating tests:
+
+1. **Start with CRUD** — Test all auto-generated methods first (createX, listX, retrieveX, updateX, deleteX)
+2. **Test custom methods** — Each method defined in defineService
+3. **Test validation** — Invalid inputs via Zod safeParse
+4. **Test events** — Verify CRUD operations emit `entity.created`, `entity.updated`, `entity.deleted`
+5. **Test subscribers** — Call handler directly with mock `{ command, log }`
+6. **Test jobs** — Call handler directly with mock `{ command, log }`
+7. **Use in-memory adapters** — No database needed for unit tests
+8. **Isolate tests** — `beforeEach` creates fresh state, `afterEach` disposes. No shared state.
+9. **Name clearly** — `it('createProducts creates a product with valid data')`

package/docs/14-adapters.md

@@ -0,0 +1,204 @@
+# Creating Adapters
+
+An adapter is a concrete implementation of a port interface. The framework ships with in-memory adapters for dev and production adapters for cloud platforms. You can create your own for any service.
+
+## Port interfaces
+
+Every infrastructure concern is abstracted behind a port. Here are all ports you can implement:
+
+| Port | Responsibility | Dev adapter | Prod adapter |
+|------|---------------|-------------|--------------|
+| `ICachePort` | Key-value cache | InMemoryCacheAdapter | UpstashCacheAdapter |
+| `IEventBusPort` | Event pub/sub | InMemoryEventBusAdapter | Upstash Queues |
+| `IFilePort` | File storage | InMemoryFileAdapter | VercelBlobAdapter |
+| `ILoggerPort` | Structured logging | TestLogger | PinoLoggerAdapter |
+| `ILockingPort` | Distributed locks | InMemoryLockingAdapter | Neon advisory locks |
+| `IJobSchedulerPort` | Cron scheduling | InMemoryJobScheduler | VercelCronAdapter |
+| `IDatabasePort` | Database connection | InMemoryDatabaseAdapter | DrizzlePgAdapter |
+| `IHttpPort` | HTTP server | InMemoryHttpAdapter | H3Adapter |
+| `IRepository` | Entity CRUD | InMemoryRepository | DrizzleRepository |
+| `INotificationPort` | Notifications | InMemoryNotificationAdapter | (custom) |
+| `IAuthPort` | JWT/API key crypto | MockAuthPort | (built-in) |
+
+## Creating a cache adapter (example)
+
+### 1. Implement the port interface
+
+```typescript
+// packages/manta-adapter-cache-redis/src/adapter.ts
+import type { ICachePort } from '@mantajs/core'
+import { MantaError } from '@mantajs/core'
+import { createClient } from 'redis'
+
+export interface RedisCacheOptions {
+  url?: string
+}
+
+export class RedisCacheAdapter implements ICachePort {
+  private client: ReturnType<typeof createClient>
+
+  constructor(options: RedisCacheOptions = {}) {
+    const url = options.url ?? process.env.REDIS_URL
+    if (!url) throw new MantaError('INVALID_DATA', 'REDIS_URL is required for RedisCacheAdapter')
+    this.client = createClient({ url })
+  }
+
+  async get(key: string): Promise<unknown> {
+    const value = await this.client.get(key)
+    return value ? JSON.parse(value) : null
+  }
+
+  async set(key: string, data: unknown, ttl?: number): Promise<void> {
+    const serialized = JSON.stringify(data)
+    if (ttl) {
+      await this.client.set(key, serialized, { EX: Math.ceil(ttl / 1000) })
+    } else {
+      await this.client.set(key, serialized)
+    }
+  }
+
+  async invalidate(key: string): Promise<void> {
+    await this.client.del(key)
+  }
+
+  async clear(): Promise<void> {
+    await this.client.flushDb()
+  }
+}
+```
+
+### 2. Create the barrel export
+
+```typescript
+// packages/manta-adapter-cache-redis/src/index.ts
+export type { RedisCacheOptions } from './adapter'
+export { RedisCacheAdapter } from './adapter'
+```
+
+### 3. Package metadata
+
+```json
+{
+  "name": "manta-adapter-cache-redis",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "src/index.ts",
+  "exports": { ".": "./src/index.ts" },
+  "peerDependencies": { "@mantajs/core": ">=0.1.0" },
+  "dependencies": { "redis": "^4.0.0" }
+}
+```
+
+### 4. Register in config
+
+```typescript
+// manta.config.ts
+export default defineConfig({
+  adapters: {
+    ICachePort: {
+      adapter: 'manta-adapter-cache-redis',
+      options: { url: process.env.REDIS_URL },
+    },
+  },
+})
+```
+
+## Port interface reference
+
+### ICachePort
+
+```typescript
+interface ICachePort {
+  get(key: string): Promise<unknown>
+  set(key: string, data: unknown, ttl?: number): Promise<void>
+  invalidate(key: string): Promise<void>
+  clear(): Promise<void>
+}
+```
+
+### IEventBusPort
+
+```typescript
+interface IEventBusPort {
+  emit(event: Message | Message[]): Promise<void>
+  subscribe(eventName: string, handler: (event: Message) => Promise<void> | void, options?: { subscriberId?: string }): void
+  unsubscribe(subscriberId: string): void
+  releaseGroupedEvents(eventGroupId: string): Promise<void>
+  clearGroupedEvents(eventGroupId: string): Promise<void>
+}
+```
+
+### IFilePort
+
+```typescript
+interface IFilePort {
+  upload(key: string, data: Buffer | ReadableStream, contentType?: string): Promise<{ key: string; url: string }>
+  delete(key: string | string[]): Promise<void>
+  getPresignedDownloadUrl(key: string): Promise<string>
+  getDownloadStream(key: string): Promise<ReadableStream>
+  getAsBuffer(key: string): Promise<Buffer>
+  list(prefix?: string): Promise<string[]>
+}
+```
+
+### ILockingPort
+
+```typescript
+interface ILockingPort {
+  execute<T>(keys: string[], job: () => Promise<T>, options?: { timeout?: number }): Promise<T>
+  acquire(keys: string | string[], options?: { ownerId?: string; expire?: number }): Promise<boolean>
+  release(keys: string | string[], options?: { ownerId?: string }): Promise<void>
+  releaseAll(options?: { ownerId?: string }): Promise<void>
+}
+```
+
+### ILoggerPort
+
+```typescript
+interface ILoggerPort {
+  error(msg: string, ...args: unknown[]): void
+  warn(msg: string, ...args: unknown[]): void
+  info(msg: string, ...args: unknown[]): void
+  debug(msg: string, ...args: unknown[]): void
+  setLogLevel(level: string): void
+}
+```
+
+### IJobSchedulerPort
+
+```typescript
+interface IJobSchedulerPort {
+  register(name: string, schedule: string, handler: (ctx: { app: MantaApp }) => Promise<JobResult>, options?: { concurrency?: 'allow' | 'forbid'; timeout?: number }): void
+  runJob(name: string): Promise<JobResult>
+  getJobHistory(jobName: string, limit?: number): Promise<JobExecution[]>
+}
+```
+
+### IDatabasePort
+
+```typescript
+interface IDatabasePort {
+  initialize(config: DatabaseConfig): Promise<void>
+  dispose(): Promise<void>
+  healthCheck(): Promise<boolean>
+  getClient(): unknown
+  getPool(): unknown
+  raw<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>
+  transaction<T>(fn: (tx: unknown) => Promise<T>, options?: TransactionOptions): Promise<T>
+}
+```
+
+## Naming convention
+
+Published adapters: `manta-adapter-{port}-{implementation}`
+
+Examples:
+- `manta-adapter-cache-redis`
+- `manta-adapter-cache-memcached`
+- `manta-adapter-file-s3`
+- `manta-adapter-file-gcs`
+- `manta-adapter-eventbus-kafka`
+- `manta-adapter-locking-redis`
+- `manta-adapter-database-mysql` (if supported in the future)
+
+Include `AGENT.md` with instructions for AI and `README.md` with setup/config docs.

package/docs/15-hosts.md

@@ -0,0 +1,163 @@
+# Creating Hosts
+
+A host bridges Manta's HTTP adapter (H3Adapter) to a specific runtime or server framework. The default host is Nitro (which powers Nuxt). You can create hosts for Express, Fastify, Hono, AWS Lambda, Cloudflare Workers, etc.
+
+## What a host does
+
+1. Bootstraps the Manta app (calls `bootstrapApp()`)
+2. Mounts the H3Adapter's routes on the target server
+3. Handles request/response translation (if the target uses a different API than Web `Request`/`Response`)
+4. Manages lifecycle (startup, shutdown, health checks)
+
+## Default host: Nitro
+
+Manta ships with a Nitro host (`packages/host-nitro/`). It:
+- Starts a Nitro dev server with HMR
+- Mounts the H3Adapter as middleware
+- Handles the catch-all route `server/routes/[...].ts`
+- Passes requests through to Manta's 12-step pipeline
+
+## Creating a custom host
+
+### Example: Express host
+
+```typescript
+// packages/manta-host-express/src/index.ts
+import express from 'express'
+import { bootstrapApp } from '@mantajs/cli/bootstrap'
+
+export async function startExpressHost(options: { port?: number; cwd?: string } = {}) {
+  const port = options.port ?? 3000
+  const cwd = options.cwd ?? process.cwd()
+
+  // Bootstrap the Manta app (same as manta dev / manta start)
+  const { app, adapter, logger, shutdown } = await bootstrapApp({
+    cwd,
+    mode: 'production',
+  })
+
+  // Create Express app
+  const server = express()
+
+  // Mount Manta's H3 adapter — translate Express req/res to Web Request/Response
+  server.all('*', async (req, res) => {
+    const url = new URL(req.url, `http://${req.headers.host}`)
+    const webRequest = new Request(url, {
+      method: req.method,
+      headers: Object.fromEntries(
+        Object.entries(req.headers).filter(([_, v]) => v != null) as [string, string][],
+      ),
+      body: ['GET', 'HEAD'].includes(req.method) ? undefined : req,
+    })
+
+    const webResponse = await adapter.handleRequest(webRequest)
+
+    res.status(webResponse.status)
+    for (const [key, value] of webResponse.headers.entries()) {
+      res.setHeader(key, value)
+    }
+    const body = await webResponse.text()
+    res.send(body)
+  })
+
+  // Start
+  server.listen(port, () => {
+    logger.info(`Manta (Express) running at http://localhost:${port}`)
+  })
+
+  // Graceful shutdown
+  process.on('SIGTERM', async () => {
+    await shutdown()
+    process.exit(0)
+  })
+}
+```
+
+### Example: AWS Lambda host
+
+```typescript
+// packages/manta-host-lambda/src/index.ts
+import { bootstrapApp } from '@mantajs/cli/bootstrap'
+
+let bootstrapped: Awaited<ReturnType<typeof bootstrapApp>> | null = null
+
+export async function handler(event: APIGatewayProxyEventV2) {
+  // Cold start: bootstrap once
+  if (!bootstrapped) {
+    bootstrapped = await bootstrapApp({ cwd: process.cwd(), mode: 'production' })
+  }
+
+  // Translate Lambda event to Web Request
+  const url = `https://${event.requestContext.domainName}${event.rawPath}${event.rawQueryString ? '?' + event.rawQueryString : ''}`
+  const request = new Request(url, {
+    method: event.requestContext.http.method,
+    headers: event.headers as Record<string, string>,
+    body: event.body ? Buffer.from(event.body, event.isBase64Encoded ? 'base64' : 'utf-8') : undefined,
+  })
+
+  // Delegate to Manta
+  const response = await bootstrapped.adapter.handleRequest(request)
+
+  // Translate back to Lambda response
+  return {
+    statusCode: response.status,
+    headers: Object.fromEntries(response.headers.entries()),
+    body: await response.text(),
+  }
+}
+```
+
+## The host interface
+
+A host must:
+
+1. **Call `bootstrapApp()`** — This returns the fully wired `MantaApp` + `H3Adapter` + `logger` + `shutdown()`
+2. **Translate requests** — Convert the target runtime's request format to Web `Request`, call `adapter.handleRequest(request)`, convert `Response` back
+3. **Handle lifecycle** — Call `shutdown()` on SIGTERM/SIGINT for graceful cleanup (connection pools, pending jobs, etc.)
+
+The H3Adapter's `handleRequest(request: Request): Promise<Response>` is the single entry point. It runs the full 12-step pipeline (auth, validation, routing, error handling).
+
+## What the pipeline provides
+
+Every request passing through `adapter.handleRequest()` goes through:
+
+| Step | What it does |
+|------|-------------|
+| 1. RequestID | Adds correlation ID header |
+| 2. CORS | Origin validation |
+| 3. Rate limit | Sliding window by IP (if enabled) |
+| 4. Scope | Creates AsyncLocalStorage context |
+| 5. Body parser | Parses JSON body |
+| 6. Auth | Extracts AuthContext from Bearer/API key/Cookie |
+| 7. Publishable key | Adds to context (if applicable) |
+| 8. Validation | Zod schema check (for commands) |
+| 9. Custom | App-defined middleware |
+| 10. RBAC | Role-based access (if enabled) |
+| 11. Handler | Route execution |
+| 12. Error handler | Catch + format MantaError → HTTP response |
+
+## Naming convention
+
+Published hosts: `manta-host-{runtime}`
+
+Examples:
+- `manta-host-express`
+- `manta-host-fastify`
+- `manta-host-hono`
+- `manta-host-lambda`
+- `manta-host-cloudflare`
+- `manta-host-bun`
+- `manta-host-deno`
+
+Include `AGENT.md` with deployment instructions and `README.md` with setup docs.
+
+## Package structure
+
+```
+manta-host-express/
+├── src/
+│   └── index.ts         # startExpressHost() + Lambda handler
+├── package.json         # name: "manta-host-express"
+├── AGENT.md             # AI instructions for deployment
+└── README.md            # Setup & config docs
+```