@mantajs/core 0.1.7 → 0.2.0-beta.0

package/docs/06-queries.md

@@ -0,0 +1,342 @@
+# Queries — defineQuery() & defineQueryGraph()
+
+Queries are the CQRS read side. They expose data as GET endpoints. Two primitives:
+
+- `defineQuery()` — named query with custom handler (specific reads)
+- `defineQueryGraph()` — expose the query graph to frontend (flexible reads)
+
+## defineQuery()
+
+```typescript
+// src/queries/admin/list-products.ts
+import { z } from 'zod'
+
+export default defineQuery({
+  name: 'list-products',
+  description: 'List products with filtering',
+  input: z.object({
+    status: z.string().optional(),
+    ...listParams(),
+  }),
+  handler: async (input, { query, log, auth, headers }) => {
+    return query.graph({
+      entity: 'product',
+      filters: input.status ? { status: input.status } : undefined,
+      pagination: { take: input.limit, skip: input.offset },
+    })
+  },
+})
+```
+
+### Signature
+
+```typescript
+defineQuery({
+  name: string,            // Query name (becomes the endpoint)
+  description: string,     // For docs and AI tool discovery
+  input: z.ZodType,        // Zod schema for input validation
+  handler: (input, ctx) => Promise<output>,
+})
+```
+
+### Handler context
+
+```typescript
+{
+  query: QueryService,                          // query.graph() for cross-module joins
+  log: ILoggerPort,                             // Structured logging
+  auth: AuthContext | null,                     // Authenticated user
+  headers: Record<string, string | undefined>,  // Raw request headers
+}
+```
+
+**No `app` access** — queries are forced to use `query.graph()` for reads. This ensures consistent access control.
+
+### Routing
+
+The folder name = the context:
+```
+src/queries/admin/list-products.ts   → GET /api/admin/list-products
+src/queries/store/get-catalog.ts     → GET /api/store/get-catalog
+```
+
+Query parameters are passed as URL query string:
+```
+GET /api/admin/list-products?status=active&limit=10&offset=0
+```
+
+### Input helpers
+
+```typescript
+import { listParams, retrieveParams } from '@mantajs/sdk'
+
+// listParams() adds: limit, offset, sort, order, search
+z.object({
+  category: z.string().optional(),
+  ...listParams(),         // { limit: 20, offset: 0, sort?, order: 'desc', search? }
+})
+
+// retrieveParams() adds: id, fields
+z.object({
+  ...retrieveParams(),    // { id: string, fields?: string[] }
+})
+```
+
+### Auth in queries
+
+```typescript
+handler: async (input, { query, auth }) => {
+  // auth.id — user ID
+  // auth.type — context ('admin', 'customer')
+  // auth.email — user email
+
+  // Example: only return MY orders
+  return query.graph({
+    entity: 'order',
+    filters: { customer_id: auth!.id },
+  })
+}
+```
+
+## defineQueryGraph()
+
+Exposes the query graph to the frontend. The frontend can compose arbitrary queries.
+
+### Wildcard — full access (admin/AI)
+
+```typescript
+// src/queries/admin/graph.ts
+export default defineQueryGraph('*')
+```
+
+Creates `POST /api/admin/graph`. The frontend can query any entity with any filters, relations, pagination.
+
+### Scoped — per-entity access with row-level filtering
+
+```typescript
+// src/queries/store/graph.ts
+export default defineQueryGraph({
+  product: true,                                   // all products, no filter
+  category: true,                                  // all categories
+  order: (auth) => ({ customer_id: auth.id }),     // only MY orders
+  customer: (auth) => ({ id: auth.id }),           // only MY profile
+})
+```
+
+Creates `POST /api/store/graph` with access control:
+
+| Entity | Access | Behavior |
+|--------|--------|----------|
+| Listed as `true` | All rows | No filter applied |
+| Listed as function | Scoped rows | Function returns filters merged with user query |
+| Not listed | Blocked | 403 Forbidden |
+| Listed in `relations` but not allowed | Stripped | Warning logged in backend console |
+
+### Frontend usage
+
+```typescript
+// Using @mantajs/sdk
+const { data } = useGraphQuery({
+  entity: 'product',
+  filters: { status: 'active' },
+  relations: ['inventory_item'],
+  pagination: { limit: 20 },
+  sort: { field: 'created_at', order: 'desc' },
+})
+```
+
+### Graph query body
+
+```json
+POST /api/admin/graph
+{
+  "entity": "product",
+  "filters": { "status": "active" },
+  "pagination": { "limit": 20, "offset": 0 },
+  "sort": { "field": "created_at", "order": "desc" },
+  "relations": ["inventory_item", "category"],
+  "fields": ["id", "title", "price", "status"]
+}
+```
+
+### When to use defineQuery vs defineQueryGraph
+
+| Use case | Primitive | Why |
+|----------|-----------|-----|
+| Admin dashboard | `defineQueryGraph('*')` | Admin sees everything, AI needs full access |
+| Storefront public catalog | `defineQueryGraph({ product: true })` | Frontend composes queries freely, scoped |
+| Storefront orders | `defineQuery` or scoped graph | Need row-level filtering by customer |
+| Complex aggregation | `defineQuery` | Custom handler with business logic |
+| API for third parties | `defineQuery` | Fixed contract, no graph exposure |
+
+## extendQueryGraph() — external entity resolvers
+
+`extendQueryGraph()` plugs a **module-level resolver** into the query engine. It's how modules that own [external entities](./02-models.md#external-entities) (PostHog, Stripe, etc.) translate a Manta query graph request into a call to the third-party backend.
+
+Unlike `defineQueryGraph()` — which controls **access per context** — `extendQueryGraph()` adds **new resolution paths** to the engine itself. When any entity listed in `owns` is queried (via `query.graph()`, `useGraphQuery`, or an AI tool), the engine routes the query to your resolver instead of hitting the local database.
+
+```typescript
+// src/modules/posthog/queries/graph.ts
+export default extendQueryGraph({
+  owns: ['PostHogEvent', 'PostHogPerson', 'PostHogInsight'],
+
+  async resolve(query, { app, logger }) {
+    // `query` is the Manta GraphQueryConfig: entity, filters, pagination, sort, fields...
+    // Translate it into a HogQL / REST call against PostHog, then return normalized rows.
+    const rows = await fetchFromPostHog(query)
+    return rows
+  },
+
+  // Optional: whitelist the filters your backend can honour. Unsupported filters
+  // will throw a clear error so the caller (or AI) can adapt its query.
+  supportedFilters: {
+    PostHogEvent: ['distinct_id', 'event', 'timestamp'],
+    PostHogPerson: ['id', 'email'],
+  },
+})
+```
+
+### Signature
+
+```typescript
+extendQueryGraph({
+  owns: string[],                         // Entity names this module resolves
+  resolve: (query, ctx) => Promise<Row[]>,
+  supportedFilters?: Record<string, string[]>,
+})
+```
+
+### Resolver context
+
+```typescript
+{
+  app: MantaApp,       // Resolve plugin config, secrets, infra
+  logger: ILoggerPort, // Structured logging
+}
+```
+
+### Rules
+
+- File location: `src/modules/{module}/queries/graph.ts` (module-scoped — NOT in `src/queries/`).
+- `owns` must be non-empty and list entities declared with `.external()` in the same module.
+- `resolve` must return normalized rows whose shape matches the entity's `defineModel()` schema (keys == field names). The engine then applies relation hydration + access control as usual.
+- Omit `supportedFilters` to accept everything (use at your own risk — the resolver is fully on the hook for validation).
+- Local entities are still resolved by the database; only entities listed in `owns` are routed to the extension.
+
+### Relationship with defineLink
+
+External entities linked to local ones via `defineLink()` are hydrated transparently: when a query requests `{ entity: 'product', relations: ['posthog_event'] }`, the engine first hits Drizzle for products, then calls the PostHog extension's `resolve()` with the event query — both halves merge in the final result.
+
+## Relation field syntax in query.graph()
+
+The `fields` parameter in `query.graph()` supports a dot notation to eagerly load related entities:
+
+```typescript
+// Load all product fields + all linked inventory items
+return query.graph({
+  entity: 'product',
+  fields: ['*', 'inventory_items.*'],
+})
+```
+
+### How it works
+
+- `'*'` — all columns of the root entity
+- `'relation.*'` — eagerly load all columns of the linked entity (uses the relation alias from `defineLink`)
+
+### M:N links
+
+For many-to-many links, the relation field syntax loads through the pivot table and flattens results:
+
+```typescript
+// Load customers with their addresses
+return query.graph({
+  entity: 'customer',
+  fields: ['*', 'addresses.*'],
+})
+```
+
+If the link has extra columns (e.g., `type`, `is_default`), those pivot columns are merged into each target entity:
+
+```json
+{
+  "id": "cust_123",
+  "name": "Alice",
+  "addresses": [
+    { "id": "addr_1", "street": "123 Main", "type": "shipping", "is_default": true },
+    { "id": "addr_2", "street": "456 Oak", "type": "billing", "is_default": false }
+  ]
+}
+```
+
+### Relation pagination with relPagination
+
+Use `relPagination` to paginate relation results independently from the root entity:
+
+```typescript
+return query.graph({
+  entity: 'customer',
+  fields: ['*', 'orders.*'],
+  relPagination: {
+    orders: { take: 5, skip: 0 },
+  },
+})
+```
+
+This limits the eagerly loaded `orders` to 5 per customer, without affecting the root pagination.
+
+### Pagination limits and large result sets
+
+`pagination.limit` defaults to **100** when unspecified. There is **no hard cap** — callers may request any limit — but the Drizzle relational query adapter will log a warning when `limit > 10000` for a single page, since paginating by offset across large result sets is inefficient.
+
+```typescript
+// OK: small page
+query.graph({ entity: 'order', pagination: { limit: 100, offset: 200 } })
+
+// Warning logged: "DrizzleRelationalQuery: limit=15000 exceeds recommended
+// maximum (10000) for entity 'order'. Consider cursor pagination."
+query.graph({ entity: 'order', pagination: { limit: 15000 } })
+```
+
+**Why the warning exists**: offset pagination scans all preceding rows on every page, so cost grows linearly with `offset`. For result sets > 10k, switch to keyset (cursor) pagination:
+
+```typescript
+// Keyset: filter by the last seen id, constant time per page
+query.graph({
+  entity: 'order',
+  filters: lastId ? { id: { $gt: lastId } } : undefined,
+  sort: { id: 'asc' },
+  pagination: { limit: 100 },
+})
+```
+
+**Counting large result sets**: `graphAndCount()` computes the exact count by default. For very large tables (> 100k rows), an exact count can be as expensive as the main query. A `countMode: 'exact' | 'capped' | 'estimated'` option is planned — see BACKLOG BC-F30 for the decision rationale. Until then, prefer `graph()` + infinite scrolling over `graphAndCount()` + paginated UIs on large tables.
+
+## Typed returns with generics
+
+`query.graph()` and `query.graphAndCount()` accept an entity type parameter for end-to-end type safety:
+
+```typescript
+// When codegen has run, the entity name is narrowed and the return type is inferred
+const products = await query.graph({ entity: 'product' })
+// => InferEntityResult<'product'>[] — fully typed with DML fields
+
+const [orders, count] = await query.graphAndCount({ entity: 'order' })
+// => [InferEntityResult<'order'>[], number]
+```
+
+### How it works
+
+- **`EntityName`** — when codegen has populated `EntityRegistry`, this is a union of known entity names (e.g. `'product' | 'order'`). Without codegen, falls back to `string`.
+- **`InferEntityResult<E>`** — resolves to the DML-inferred shape when `E` is a known registry key, otherwise `Record<string, unknown>`.
+- **`GraphQueryConfig<E>`** — the `entity` field is typed as `E`, giving autocomplete on entity names.
+
+This means `as any[]` casts on query results are no longer needed. The type flows from `defineModel` through codegen into query results.
+
+### Without codegen (development / tests)
+
+If `EntityRegistry` is empty (no codegen), everything still works — `EntityName` is `string` and results are `Record<string, unknown>`. No breaking change.
+
+## No defineQueryGraph = no useGraphQuery
+
+If you don't create a `graph.ts` in a context, `useGraphQuery()` from the SDK will receive a 404. The query graph must be explicitly enabled per context.

package/docs/07-events.md

@@ -0,0 +1,248 @@
+# Events & Workflows — defineSubscriber(), defineJob() & defineWorkflow()
+
+## Events in Manta
+
+Events are the communication layer between modules. They decouple the "what happened" (command) from the "what should happen next" (subscriber).
+
+### Auto-generated events
+
+Every CRUD operation emits events automatically:
+
+| Operation | Event name | Data |
+|-----------|-----------|------|
+| `createProducts(data)` | `product.created` | `{ id }` |
+| `updateProducts(data)` | `product.updated` | `{ id }` |
+| `deleteProducts(ids)` | `product.deleted` | `{ id }` |
+
+The event name is derived from the entity name: `Product` → `product.created`.
+
+### Manual events
+
+In commands: `step.emit('event.name', data)` — buffered until workflow commits.
+
+## defineSubscriber()
+
+```typescript
+export default defineSubscriber({
+  event: 'product.created',
+  handler: async (event, { command, log }) => {
+    const { id, sku } = event.data as { id: string; sku: string }
+    log.info(`Product created: ${sku}`)
+    await command.initializeInventory({ productId: id })
+  },
+})
+```
+
+**Signature:**
+- `event` — Event name (string) or array of event names
+- `handler` — `async (event, { command, log }) => void`
+  - `event` — `Message<T>` with `eventName`, `data`, `metadata`
+  - `command` — CQRS command callables (with autocomplete from codegen)
+  - `log` — Logger instance
+
+### Typed event data
+
+Use the generic parameter to type `event.data`:
+
+```typescript
+interface ProductCreatedEvent {
+  id: string
+  sku: string
+  title: string
+  price: number
+}
+
+export default defineSubscriber<ProductCreatedEvent>({
+  event: 'product.created',
+  handler: async (event, { command, log }) => {
+    event.data.sku  // TS knows this is string
+  },
+})
+```
+
+### Multiple events
+
+```typescript
+export default defineSubscriber({
+  event: ['product.created', 'product.updated'],
+  handler: async (event, { log }) => {
+    log.info(`Product changed: ${event.eventName}`)
+  },
+})
+```
+
+### Idempotency (at-least-once)
+
+Events can be delivered more than once (at-least-once guarantee). Use `makeIdempotent()` to deduplicate:
+
+```typescript
+export default defineSubscriber({
+  event: 'order.created',
+  handler: makeIdempotent(
+    cache,  // ICachePort instance
+    async (event, { command, log }) => {
+      // Only executed once per unique event
+      await command.sendConfirmationEmail({ email: event.data.email })
+    },
+    {
+      keyFn: (event) => `order-confirm:${event.data.id}`,  // Custom dedup key
+      ttl: 24 * 3600 * 1000,  // 24 hours (default)
+    },
+  ),
+})
+```
+
+### Delivery guarantees
+
+- **At-least-once** — Events may be delivered more than once
+- **No ordering** — In production (queue), events arrive in any order
+- **Fire-and-forget** — Subscriber errors don't block the emitter
+- **No compensation** — Subscribers cannot roll back
+
+## defineJob()
+
+```typescript
+// Positional form (preferred)
+export default defineJob('cleanup-draft-products', '0 * * * *', async ({ command, log }) => {
+  const result = await command.cleanupDraftProducts({ olderThanDays: 1 })
+  log.info(`Cleanup: ${result.deleted} draft products removed`)
+  return result
+})
+```
+
+Or using the config object form:
+
+```typescript
+export default defineJob({
+  name: 'cleanup-draft-products',
+  schedule: '0 * * * *',  // Every hour
+  handler: async ({ command, log }) => {
+    const result = await command.cleanupDraftProducts({ olderThanDays: 1 })
+    log.info(`Cleanup: ${result.deleted} draft products removed`)
+    return result
+  },
+})
+```
+
+**Signature (positional):** `defineJob(name, schedule, handler)`
+**Signature (config):** `defineJob({ name, schedule, handler })`
+
+- `name` — Unique job identifier
+- `schedule` — Cron expression (5-field standard)
+- `handler` — `async ({ command, log }) => TResult`
+  - `command` — CQRS command callables (same scope as subscribers)
+  - `log` — Logger instance
+
+Jobs receive `{ command, log }` — the same scope as subscribers. Every mutation goes through a command (compensation, retry, audit trail). Jobs do NOT have direct access to `app` or module services.
+
+### Cron format
+
+```
+┌───────────── minute (0-59)
+│ ┌───────────── hour (0-23)
+│ │ ┌───────────── day of month (1-31)
+│ │ │ ┌───────────── month (1-12)
+│ │ │ │ ┌───────────── day of week (0-7, 0=Sun)
+│ │ │ │ │
+* * * * *
+```
+
+Examples:
+- `* * * * *` — Every minute
+- `0 * * * *` — Every hour
+- `0 0 * * *` — Every day at midnight
+- `0 9 * * 1` — Every Monday at 9am
+- `*/5 * * * *` — Every 5 minutes
+
+### Job locking
+
+Concurrent job executions are automatically skipped via `ILockingPort`. If a job is already running, the next invocation returns immediately without executing.
+
+## Emitting events
+
+In **commands**, events are buffered: `step.emit('event.name', data)` — only emitted if the workflow succeeds.
+
+In **subscribers and jobs**, use commands to perform mutations. Events from auto-generated CRUD (e.g., `product.created`) are emitted automatically when commands call service methods.
+
+## defineWorkflow() — Intra-module business logic
+
+A workflow is a compensable operation scoped to a single module. It orchestrates multiple entity services within the same module — pure business logic with no auth context.
+
+```typescript
+// src/modules/catalog/workflows/categorize-product.ts
+export default defineWorkflow({
+  name: 'categorize-product',
+  input: z.object({
+    productId: z.string(),
+    categoryId: z.string(),
+  }),
+  workflow: async (input, { step, log }) => {
+    const product = await step.service.catalog.retrieveProduct(input.productId)
+    await step.service.catalog.update(input.productId, { category_id: input.categoryId })
+    await step.emit('product.categorized', { id: product.id, categoryId: input.categoryId })
+    log.info(`Product ${product.id} categorized`)
+    return { productId: product.id }
+  },
+})
+```
+
+**Signature:** `defineWorkflow({ name, input, workflow })`
+
+- `name` — Unique workflow identifier (kebab-case)
+- `input` — Zod schema (validates input)
+- `workflow` — `async (input, { step, log }) => TResult`
+  - `step` — Scoped step proxy (only this module's services)
+  - `log` — Logger instance
+
+### Key differences from defineCommand
+
+| | defineCommand | defineWorkflow |
+|---|---|---|
+| **Location** | `src/commands/{ctx}/` | `src/modules/{mod}/workflows/` |
+| **Context** | `{ step, log, auth, headers }` | `{ step, log }` |
+| **Scope** | Any module | One module only |
+| **HTTP endpoint** | Yes (`POST /api/...`) | No |
+| **Auth** | Yes (`auth` param) | No |
+| **Called from** | HTTP, CLI, sub-command | Commands via `step.workflow.MODULE.NAME()` |
+| **Compensation** | Yes | Yes |
+
+### Calling workflows from commands
+
+```typescript
+// src/commands/admin/create-and-categorize.ts
+export default defineCommand({
+  name: 'create-and-categorize',
+  input: z.object({ title: z.string(), categoryId: z.string() }),
+  workflow: async (input, { step, auth }) => {
+    const product = await step.service.catalog.create({ title: input.title })
+    await step.workflow.catalog.categorizeProduct({
+      productId: product.id,
+      categoryId: input.categoryId,
+    })
+    return product
+  },
+})
+```
+
+The workflow runs within the command's compensation chain. If any step fails, all completed steps (including those inside the workflow) compensate in reverse order.
+
+## File locations
+
+```
+src/subscribers/{name}.ts                    # defineSubscriber()
+src/jobs/{name}.ts                           # defineJob()
+src/modules/{mod}/workflows/{name}.ts        # defineWorkflow()
+```
+
+## Validation errors
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `Subscriber event must be non-empty` | Empty event string | Set `event: 'product.created'` |
+| `Subscriber handler must be a function` | handler is not async function | Set `handler: async (event, { command, log }) => {...}` |
+| `Job name is required` | Missing name | Add `name: 'my-job'` |
+| `Job schedule (cron expression) is required` | Missing schedule | Add `schedule: '0 * * * *'` |
+| `Job handler must be a function` | handler is not function | Set `handler: async ({ command, log }) => {...}` |
+| `Workflow name is required` | Missing name | Add `name: 'my-workflow'` |
+| `Workflow "X" requires an input Zod schema` | Missing input | Add `input: z.object({})` |
+| `Workflow "X" workflow must be an async function` | workflow is not a function | Add `workflow: async (input, { step, log }) => {...}` |