@mantajs/core 0.1.6 → 0.2.0-beta.0

package/docs/01-getting-started.md

@@ -0,0 +1,224 @@
+# Getting Started
+
+## Prerequisites
+
+- Node.js 18+ (AsyncLocalStorage required)
+- PostgreSQL (local or cloud — Neon, Supabase, etc.)
+- pnpm
+
+## Create a project
+
+```bash
+manta init my-app
+cd my-app
+pnpm install
+```
+
+This creates:
+
+```
+my-app/
+├── manta.config.ts
+├── .env
+├── src/
+│   ├── modules/
+│   ├── commands/
+│   ├── subscribers/
+│   ├── jobs/
+│   ├── links/
+│   └── contexts/
+├── drizzle/migrations/
+└── tsconfig.json
+```
+
+## Step 1 — Configure the database
+
+Edit `.env`:
+
+```
+DATABASE_URL=postgresql://localhost:5432/my_app
+```
+
+Create the database:
+
+```bash
+manta db:create
+```
+
+## Step 2 — Define a model
+
+Create `src/modules/blog/entities/post/model.ts`:
+
+```typescript
+export default defineModel('Post', {
+  title: field.text(),
+  slug: field.text().unique(),
+  content: field.text(),
+  status: field.enum(['draft', 'published', 'archived']),
+  published_at: field.dateTime().nullable(),
+})
+```
+
+## Step 3 — Define the service
+
+Create `src/modules/blog/entities/post/service.ts`:
+
+```typescript
+export default defineService(
+  (model) => model.post,
+  (db) => ({
+    publish: service.method(
+      async (id: string) => {
+        const [post] = await db.find({ where: { id } })
+        const previousStatus = post.status
+        await db.update({ id, status: 'published', published_at: new Date() })
+        return { previousStatus }
+      },
+      async (result, id: string) => {
+        await db.update({ id, status: result.previousStatus, published_at: null })
+      },
+    ),
+  }),
+)
+```
+
+This gives you 8 CRUD methods for free + the custom `publish` method. No imports needed — `defineService`, `service`, and `model` are all globals.
+
+## Step 4 — Define a command
+
+Create `src/commands/create-post.ts`:
+
+```typescript
+export default defineCommand({
+  name: 'create-post',
+  description: 'Create a new blog post',
+  input: z.object({
+    title: z.string().min(1),
+    slug: z.string().regex(/^[a-z0-9-]+$/),
+    content: z.string(),
+    publish: z.boolean().default(false),
+  }),
+  workflow: async (input, { step }) => {
+    const post = await step.service.blog.create({
+      title: input.title,
+      slug: input.slug,
+      content: input.content,
+      status: 'draft',
+    })
+
+    if (input.publish) {
+      await step.service.blog.publish(post.id)
+    }
+
+    await step.emit('post.created', { id: post.id, slug: input.slug })
+
+    return { id: post.id, slug: input.slug, status: input.publish ? 'published' : 'draft' }
+  },
+})
+```
+
+## Step 5 — Define a subscriber (optional)
+
+Create `src/subscribers/post-created.ts`:
+
+```typescript
+export default defineSubscriber({
+  event: 'post.created',
+  handler: async ({ event, app }) => {
+    const { slug } = event.data as { slug: string }
+    app.infra.logger.info(`New post created: ${slug}`)
+  },
+})
+```
+
+## Step 6 — Define a context
+
+Create `src/contexts/admin.ts`:
+
+```typescript
+export default defineContext({
+  name: 'admin',
+  basePath: '/api/admin',
+  actors: ['admin'],
+  modules: {
+    blog: { expose: '*' },
+  },
+  commands: ['create-post'],
+  ai: { enabled: true },
+})
+```
+
+## Step 7 — Generate migrations and run
+
+```bash
+manta db:generate     # Creates SQL migration from Post model
+manta db:migrate      # Applies migration to database
+```
+
+## Step 8 — Start the dev server
+
+```bash
+manta dev
+```
+
+Output:
+```
+  [codegen] .manta/types/ (1 modules, 3 events)
+  Module: blog (Post) ✓
+  Subscriber: post.created → post-created ✓
+  Command: create-post ✓
+  Context: admin → /api/admin ✓
+
+  Server running at http://localhost:9000
+  API docs at http://localhost:9000/api/docs
+```
+
+## Step 9 — Test it
+
+Create a post:
+```bash
+curl -X POST http://localhost:9000/api/admin/command/create-post \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer <jwt>" \
+  -d '{
+    "title": "Hello World",
+    "slug": "hello-world",
+    "content": "My first Manta post",
+    "publish": true
+  }'
+```
+
+Query posts:
+```bash
+curl -X POST http://localhost:9000/api/admin/query/blog \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer <jwt>" \
+  -d '{"filters": {"status": "published"}}'
+```
+
+View API docs:
+```
+open http://localhost:9000/api/docs
+```
+
+## What happened automatically
+
+From your 4 files (model, service, command, context), Manta generated:
+
+- PostgreSQL table `posts` with all columns + indexes
+- 8 CRUD methods on `app.modules.blog`
+- HTTP endpoint `POST /api/admin/command/create-post`
+- HTTP endpoint `POST /api/admin/query/blog`
+- AI tool schema for `create-post` (Zod → JSON Schema)
+- OpenAPI spec with full schema documentation
+- TypeScript types for autocomplete (`.manta/types/`)
+- Event wiring for `post.created` subscriber
+- Compensation logic (if create-post fails, the post is deleted)
+
+## Next steps
+
+- Add more modules (see [Models](./02-models.md) and [Services](./03-services.md))
+- Add cross-module relations (see [Links](./07-links.md))
+- Add scheduled tasks (see [Events](./06-events.md))
+- Expose a storefront API (see [Contexts](./08-contexts.md))
+- Deploy to production (see [Config](./09-config.md))

package/docs/02-models.md

@@ -0,0 +1,163 @@
+# Models — defineModel()
+
+## What is a model
+
+A model declares the shape of an entity in your database. It generates:
+- A PostgreSQL table (via `manta db:generate`)
+- TypeScript types (via codegen)
+- CRUD methods on the service (auto-generated at boot)
+
+## defineModel()
+
+```typescript
+export default defineModel('Product', {
+  title: field.text(),
+  description: field.text().nullable(),
+  sku: field.text().unique(),
+  price: field.number(),
+  status: field.enum(['draft', 'active', 'archived']),
+  image_urls: field.json().nullable(),
+})
+```
+
+**Signature:** `defineModel(name: string, schema: Record<string, Property>): DmlEntity`
+
+- `name` must be PascalCase (e.g., `Product`, `InventoryItem`, `BlogPost`)
+- `schema` must have at least one property
+- `defineModel` is a global — no import needed
+
+## Property types
+
+`field` is the global property factory:
+
+| Factory | TypeScript type | PostgreSQL type | Example |
+|---------|----------------|-----------------|---------|
+| `field.text()` | `string` | `TEXT` | `title: field.text()` |
+| `field.number()` | `number` | `INTEGER` | `quantity: field.number()` |
+| `field.boolean()` | `boolean` | `BOOLEAN` | `active: field.boolean()` |
+| `field.float()` | `number` | `REAL` | `rating: field.float()` |
+| `field.bigNumber()` | `number` | `NUMERIC` | `amount: field.bigNumber()` |
+| `field.serial()` | `number` | `SERIAL` | `position: field.serial()` |
+| `field.dateTime()` | `Date` | `TIMESTAMPTZ` | `published_at: field.dateTime()` |
+| `field.json()` | `Record<string, unknown>` | `JSONB` | `metadata: field.json()` |
+| `field.enum(values)` | Union type | `TEXT + CHECK` | `status: field.enum(['draft', 'active'])` |
+| `field.array()` | `unknown[]` | `JSONB` | `tags: field.array()` |
+
+## Modifiers
+
+Chain modifiers after any property:
+
+```typescript
+field.text().nullable()        // Allow NULL
+field.text().unique()          // UNIQUE constraint
+field.text().indexed()         // Create index
+field.number().default(0)      // Default value
+```
+
+| Modifier | Effect |
+|----------|--------|
+| `.nullable()` | Column allows NULL |
+| `.unique()` | UNIQUE constraint |
+| `.indexed()` | B-tree index |
+| `.searchable()` | Full-text search index |
+| `.default(value)` | Default value in SQL |
+
+## Implicit columns
+
+Every entity automatically gets these columns (you cannot redefine them):
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `id` | `TEXT PRIMARY KEY` | UUID auto-generated |
+| `created_at` | `TIMESTAMPTZ DEFAULT NOW()` | Creation timestamp |
+| `updated_at` | `TIMESTAMPTZ DEFAULT NOW()` | Last update timestamp |
+| `deleted_at` | `TIMESTAMPTZ NULL` | Soft-delete marker |
+
+## Relations
+
+Relations between entities are defined with `defineLink()`, not in the model. There is no `field.relation()` API.
+
+- **Intra-module relations**: `defineLink()` in `src/modules/{mod}/links/` (1:1/1:N create FK directly, M:N creates pivot)
+- **Cross-module relations**: `defineLink()` in `src/links/` (always creates pivot table)
+
+See [Links](./08-links.md) for the full API and examples.
+
+## File location
+
+Each entity has a folder inside `entities/`. The model is `model.ts`, the service is `service.ts` (same folder):
+
+```
+src/modules/catalog/entities/product/model.ts
+src/modules/catalog/entities/category/model.ts
+src/modules/inventory/entities/inventory-item/model.ts
+```
+
+## Migrations
+
+After defining or changing a model:
+
+```bash
+manta db:generate              # Generate SQL migration
+manta db:migrate               # Apply to database
+manta db:diff                  # Compare schema vs DB (diagnostic)
+```
+
+## External entities
+
+Mark an entity as **external** when it lives in a third-party system (PostHog, Stripe, Shopify, etc.) and Manta should NOT own its storage. The framework still registers the entity so it remains visible to the query graph, to AI tools (`query_entity`, `describe_entity`), and can be linked to local entities with `defineLink()`.
+
+```typescript
+// src/modules/posthog/entities/posthog-event/model.ts
+export default defineModel('PostHogEvent', {
+  id: field.text().primaryKey(),
+  event: field.text(),
+  distinct_id: field.text(),
+  timestamp: field.dateTime(),
+  properties: field.json(),
+}).external()
+```
+
+When `.external()` is set, the framework:
+
+- does **NOT** generate a database table
+- does **NOT** generate migrations
+- does **NOT** auto-generate a CRUD service
+- **DOES** register the entity in the entity registry (links, AI tools, query graph)
+
+External entities MUST be paired with a resolver declared via `extendQueryGraph()` in the same module — see [06-queries.md](./06-queries.md#extendquerygraph--external-entity-resolvers).
+
+### fromZodSchema() — declaring an external model from a Zod schema
+
+When you already have a Zod schema for the third-party payload (e.g. generated from an SDK via `ts-to-zod`), use `fromZodSchema()` to turn it into a DML field record:
+
+```typescript
+import { defineModel, fromZodSchema } from '@mantajs/core'
+import { postHogEventSchema } from './schemas'
+
+export default defineModel('PostHogEvent', fromZodSchema(postHogEventSchema)).external()
+```
+
+Zod → DML mapping:
+
+| Zod | DML |
+|-----|-----|
+| `z.string()` | `field.text()` |
+| `z.number()` | `field.number()` |
+| `z.boolean()` | `field.boolean()` |
+| `z.date()` | `field.dateTime()` |
+| `z.enum([...])` | `field.enum([...])` |
+| `z.array(...)` | `field.array()` |
+| `z.object(...)` / `z.record(...)` | `field.json()` |
+| `.optional()` / `.nullable()` / `.default()` | `.nullable()` |
+
+Convention: a field named `id` is automatically marked as primary key.
+
+## Validation errors
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `Entity name is required` | Empty string passed | Use PascalCase name: `defineModel('Product', {...})` |
+| `Entity name must be PascalCase` | Lowercase name | Change `product` to `Product` |
+| `Entity must have at least one property` | Empty schema `{}` | Add properties: `{ title: field.text() }` |
+| `Property "id" is implicit and cannot be redefined` | Declared `id` in schema | Remove it — `id` is auto-generated |
+| `Property uses reserved "raw_" prefix` | Name starts with `raw_` | Rename — `raw_` is for bigNumber shadow columns |

package/docs/03-services.md

@@ -0,0 +1,208 @@
+# Services — defineService()
+
+## The rule
+
+**1 entity = 1 service. Always.**
+
+A service defines the mutations (writes) for **one** entity. The repository it receives is typed for that entity only. A service cannot mutate another entity — that's a command.
+
+A module can have multiple entities, and therefore multiple services. If you need to mutate two entities together, write a module command that orchestrates them.
+
+If you don't have an entity, you don't have a module. Use `app.infra.*` for infrastructure (file storage, cache, logging).
+
+## defineService()
+
+```typescript
+export default defineService('product', ({ db, log }) => ({
+  activate: async (id: string) => {
+    await db.update({ id, status: 'active' })
+    log.info(`Product ${id} activated`)
+  },
+
+  archive: async (id: string) => {
+    await db.update({ id, status: 'archived' })
+    log.info(`Product ${id} archived`)
+  },
+}))
+```
+
+**Signature:** `defineService(entityName: string, factory: ({ db, log }) => Methods, options?)`
+
+- `entityName` — Entity name as a string (autocompletes from codegen)
+- `factory` — Receives `{ db, log }` (typed repository + logger), returns methods
+- `options.publicMethods` — (optional) Array of method names visible to other modules
+
+No imports needed — `defineService` is a global. Compensation is automatic — the repo snapshots state before every mutation. No `service.method()` wrapper needed.
+
+## Auto-generated CRUD methods
+
+From `defineService(Product, ...)`, the framework generates these 8 methods automatically:
+
+| Method | Signature | Events emitted |
+|--------|-----------|---------------|
+| `retrieveProduct(id, config?)` | `(string, ServiceConfig?) => Promise<Product>` | none |
+| `listProducts(filters?, config?)` | `(Partial<Product>?, ServiceConfig?) => Promise<Product[]>` | none |
+| `listAndCountProducts(filters?, config?)` | `(Partial<Product>?, ServiceConfig?) => Promise<[Product[], number]>` | none |
+| `createProducts(data)` | `(Partial<Product> \| Partial<Product>[]) => Promise<Product \| Product[]>` | `product.created` |
+| `updateProducts(data)` | `(({id} & Partial<Product>) \| ...[]) => Promise<Product \| Product[]>` | `product.updated` |
+| `deleteProducts(ids)` | `(string \| string[]) => Promise<void>` | `product.deleted` |
+| `softDeleteProducts(ids)` | `(string \| string[]) => Promise<Record<string, string[]>>` | none |
+| `restoreProducts(ids)` | `(string \| string[]) => Promise<void>` | none |
+
+Plus two query helpers:
+- `list()` — All entities, ordered by `created_at DESC`
+- `findById(id)` — Single entity or `null`
+
+**The method names are derived from the entity name.** `Product` → `createProducts`, `InventoryItem` → `createInventoryItems`.
+
+## Auto-compensation — snapshot-based rollback
+
+Service methods are plain `async` functions. No `service.method()` wrapper needed.
+
+```typescript
+activate: async (id: string) => {
+  await db.update({ id, status: 'active' })
+}
+```
+
+**How it works:** The framework auto-snapshots repository state before every mutation. In a workflow, if step 3 fails, steps 1 and 2 are automatically rolled back using the snapshots. You don't write compensation logic — the framework handles it.
+
+## TypedRepository — the db API
+
+The `db` parameter is a `TypedRepository<T>` where `T` is the inferred entity type:
+
+```typescript
+// Find entities
+const products = await db.find({
+  where: { status: 'active' },     // Partial<Product> filter
+  order: { created_at: 'DESC' },   // Sort
+  limit: 10,                        // Pagination
+  offset: 0,
+  withDeleted: false,                // Include soft-deleted (default: false)
+})
+
+// Find with count
+const [items, total] = await db.findAndCount({ where: { status: 'draft' } })
+
+// Create
+const product = await db.create({ title: 'Widget', sku: 'W-001', price: 999 })
+
+// Update (id required)
+const updated = await db.update({ id: 'prod_123', status: 'active' })
+
+// Delete
+await db.delete('prod_123')         // Hard delete
+await db.delete(['id1', 'id2'])     // Batch delete
+
+// Soft-delete
+await db.softDelete(['prod_123'])   // Sets deleted_at
+await db.restore(['prod_123'])       // Clears deleted_at
+
+// Bulk upsert (insert or replace on conflict)
+await db.upsertWithReplace(
+  [{ id: 'prod_1', title: 'A' }, { id: 'prod_2', title: 'B' }],
+  ['title'],           // fields to replace on conflict (optional)
+  ['id'],              // conflict target columns (optional, defaults to ['id'])
+)
+// Note: upsertWithReplace bypasses compensation — it's a bulk operation
+// mixing creates and updates, which cannot be atomically reversed.
+```
+
+## Raw SQL escape hatch — db.raw()
+
+When TypedRepository methods are not enough (complex aggregations, window functions, CTEs), use `db.raw()` on the database port:
+
+```typescript
+// In a command step or via app.infra.db
+const results = await app.infra.db.raw<{ total: number; status: string }>(
+  `SELECT status, COUNT(*)::int AS total FROM product WHERE created_at > $1 GROUP BY status`,
+  [since],
+)
+```
+
+**Signature:** `raw<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>`
+
+- Uses `$1`, `$2` parameterized placeholders (safe from SQL injection)
+- Available on all database adapters: DrizzlePgAdapter, NeonAdapter, InMemoryDatabaseAdapter
+- The in-memory adapter throws `MantaError('NOT_FOUND')` — raw SQL only works against real databases
+- **Use sparingly** — prefer TypedRepository methods for standard CRUD. `raw()` is for queries that the ORM cannot express.
+
+## Isolation
+
+The service factory receives **only `{ db, log }`** (typed repository + logger). You cannot:
+- Import another module's service
+- Access `app` or `app.modules.*`
+- Call external APIs directly
+
+This is **structural**, not a convention — the type system enforces it. If you need to orchestrate multiple modules, use a `defineCommand()`.
+
+## publicMethods (access control)
+
+By default, all methods (CRUD + custom) are accessible from jobs, subscribers, and commands. To restrict:
+
+```typescript
+export default defineService('product', ({ db }) => ({
+  activate: async (id: string) => {
+    await db.update({ id, status: 'active' })
+  },
+  _internalReset: async (id: string) => {
+    await db.update({ id, status: 'draft' })
+  },
+}), { publicMethods: ['activate'] })  // Only activate is visible via app.modules.catalog
+```
+
+## Soft-delete behavior
+
+All reads automatically filter `WHERE deleted_at IS NULL`. To include soft-deleted records:
+
+```typescript
+await db.find({ withDeleted: true })
+// Or via auto-generated CRUD:
+await app.modules.catalog.listProducts({}, { withDeleted: true })
+```
+
+## Module structure
+
+Each entity lives in its own folder inside `entities/`, containing both `model.ts` and `service.ts`:
+
+```
+src/modules/catalog/
+├── entities/
+│   ├── product/
+│   │   ├── model.ts        # defineModel('Product', {...})
+│   │   └── service.ts      # defineService('product', ({ db, log }) => ({...}))
+│   └── category/
+│       ├── model.ts        # defineModel('Category', {...})
+│       └── service.ts      # defineService('category', ({ db, log }) => ({...}))
+├── links/                  # Intra-module relations (FK or pivot)
+│   └── product-category.ts
+├── workflows/              # Intra-module business logic (no auth)
+│   └── categorize-product.ts
+└── index.ts                # Barrel — re-exports only
+```
+
+The `model.ts` and `service.ts` are an inseparable pair. One entity, one service, one folder. The service uses the entity name as a string to reference its entity (no imports needed).
+
+### The barrel (index.ts)
+
+Pure re-exports, no logic:
+
+```typescript
+// src/modules/catalog/index.ts
+export { Product } from './entities/product/model'
+export { Category } from './entities/category/model'
+export { default } from './entities/product/service'
+```
+
+### Why 1 entity = 1 service?
+
+A service method that mutates Product AND Category in the same call cannot be compensated correctly — if the Category mutation fails, how does the service undo the Product mutation? It can't, because it only has the Product `db`.
+
+That's why cross-entity mutations go in **workflows** (intra-module) or **commands** (cross-module): the step proxy handles compensation across multiple services automatically.
+
+## Validation errors
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `Service method "X" must be an async function` | Non-function in factory return | Define as `async (args) => { ... }` |
+| `Module "X" is already registered` | Two modules with same name | Rename one of the modules |