@koltakov/ffa-core 0.8.0 → 0.16.1

package/README.md

@@ -1,19 +1,24 @@
 # ffa-core
 
-**F**rontend **F**irst **A**PI — instant mock REST API for frontend development.
+**Frontend First API** — instant mock REST API for frontend development.
 
-Stop waiting for the backend. Describe your data, run one command, get a working API.
+Stop waiting for the backend. Describe your data in one config file, run one command, get a fully working REST API.
+
+```bash
+npx @koltakov/ffa-core init
+npx @koltakov/ffa-core dev
+```
 
 ---
 
 ## Why ffa?
 
-When building a frontend you need a real API to work against — but the backend isn't ready yet. `ffa` generates a fully functional REST API from a simple config file. No JSON files to maintain, no manual routes, no extra services.
-
 - **Zero boilerplate** — one config file, one command
-- **Auto CRUD** — all 6 routes per entity out of the box
+- **Auto CRUD** — 6 routes per entity, out of the box
 - **Smart fake data** — field names drive generation (`email`, `price`, `avatar`, ...)
-- **Zod validation** — request bodies validated against your schema
+- **Typed DSL** — `string().email().required()` with full TypeScript autocomplete
+- **Zod validation** — POST/PUT/PATCH bodies validated against your schema
+- **Relations** — `belongsTo` / `hasMany` with inline join via `?include=`
 - **Swagger UI** — auto-generated docs at `/docs`
 - **Delay simulation** — test loading states with artificial latency
 - **TypeScript or JSON** — pick your config format
@@ -23,101 +28,94 @@ When building a frontend you need a real API to work against — but the backend
 ## Quick Start
 
 ```bash
-# 1. Install
 npm install @koltakov/ffa-core
 
-# 2. Scaffold a config
-npx ffa init
-
-# 3. Start
-npx ffa dev
+npx ffa init   # scaffold ffa.config.ts
+npx ffa dev    # start server
 ```
 
-Or skip `init` and write `ffa.config.ts` manually (see below).
-
 ---
 
-## Config: TypeScript
+## Config
 
 ```ts
-import { defineConfig, entity, string, number, boolean, enumField, belongsTo } from '@koltakov/ffa-core'
+// ffa.config.ts
+import {
+  defineConfig, entity,
+  string, number, boolean, enumField,
+  belongsTo, hasMany, object, array,
+} from '@koltakov/ffa-core'
 
 export default defineConfig({
   server: {
     port: 3333,
-    delay: [200, 600],   // artificial latency (ms or [min, max])
+    delay: [200, 600],   // artificial latency in ms (number or [min, max])
     persist: true,       // save data to ffa-data.json between restarts
+    errorRate: 0.05,     // 5% of requests return 500 (for error state testing)
   },
 
   entities: {
     User: entity({
-      name: string().required(),
-      email: string().required(),
-      role: enumField(['admin', 'editor', 'viewer']).required(),
-      avatar: string().optional(),
-    }, { count: 20 }),
+      name:   string().fullName().required(),
+      email:  string().email().required(),
+      role:   enumField(['admin', 'editor', 'viewer']).required(),
+      avatar: string().avatar().optional(),
+      address: object({
+        city:    string().city(),
+        country: string().country(),
+        zip:     string().zip(),
+      }),
+      phones: array(string().phone()),
+    }, {
+      count: 20,
+      // Guaranteed records — appear first, rest are generated up to count
+      seed: [
+        { name: 'Admin User', email: 'admin@example.com', role: 'admin' },
+      ],
+    }),
 
     Post: entity({
-      title: string().required(),
-      body: string().required(),
-      status: enumField(['draft', 'published', 'archived']).required(),
-      price: number().price().required(),
+      title:    string().sentence().required(),
+      body:     string().paragraph().required(),
+      status:   enumField(['draft', 'published', 'archived']).required(),
+      price:    number().price().required(),
+      rating:   number().rating().optional(),
       authorId: belongsTo('User'),
+      tagIds:   hasMany('Tag'),
     }, {
-      count: 30,
+      count: 50,
       meta: {
-        // Static values — always present in meta regardless of filters
-        currency: 'USD',
-        supportedStatuses: ['draft', 'published', 'archived'],
-
-        // Functions — receive filtered items (before pagination), return computed value
-        total:     (items) => items.length,
-        avgPrice:  (items) => +(items.reduce((s, i) => s + (i.price as number), 0) / items.length).toFixed(2),
-        byStatus:  (items) => Object.fromEntries(
-          ['draft', 'published', 'archived'].map(s => [s, items.filter(i => i.status === s).length])
-        ),
+        currency: 'USD',                                           // static value
+        total:    (items) => items.length,                         // computed from filtered items
+        avgPrice: (items) => +(
+          items.reduce((s, i) => s + (i.price as number), 0) / items.length
+        ).toFixed(2),
       },
     }),
+
+    Tag: entity({
+      name:  string().word().required(),
+      color: string().hexColor().optional(),
+    }, { count: 15 }),
   },
 })
 ```
 
-## Config: JSON (no TypeScript needed)
-
-```json
-{
-  "server": { "port": 3333, "delay": 300 },
-  "entities": {
-    "Product": {
-      "count": 20,
-      "fields": {
-        "title": "string!",
-        "price": "number",
-        "status": ["draft", "published", "archived"],
-        "inStock": "boolean",
-        "createdAt": "datetime"
-      }
-    }
-  }
-}
-```
-
-Save as `ffa.config.json`. Type suffix `!` means required (`"string!"` → required string). An array is shorthand for `enumField`.
-
 ---
 
 ## CLI
 
-```bash
-ffa dev                    # start server
-ffa dev --port 4000        # override port
-ffa dev --watch            # restart on ffa.config.ts changes
-ffa dev --open             # open Swagger UI in browser on start
-ffa dev -p 4000 -w -o      # all flags combined
-
-ffa init                   # create ffa.config.ts in current directory
-ffa reset                  # delete ffa-data.json (clears persisted data)
-```
+| Command | Description |
+|---------|-------------|
+| `ffa dev` | Start the dev server |
+| `ffa dev -p 4000` | Override port |
+| `ffa dev -w` | Watch mode — restart on config changes |
+| `ffa dev -o` | Open Swagger UI in browser on start |
+| `ffa init` | Scaffold `ffa.config.ts` in current directory |
+| `ffa inspect` | Show config structure without starting the server |
+| `ffa snapshot` | Export current in-memory DB to JSON (server must be running) |
+| `ffa snapshot -o dump.json` | Custom output path |
+| `ffa reset` | Delete `ffa-data.json` (clears persisted data) |
 
 ---
 
@@ -125,341 +123,421 @@ ffa reset                  # delete ffa-data.json (clears persisted data)
 
 For every entity `Foo` ffa creates six routes:
 
-| Method    | Path         | Description                          | Status       |
-|-----------|--------------|--------------------------------------|--------------|
-| `GET`     | `/foos`      | List all records                     | 200          |
-| `GET`     | `/foos/:id`  | Get single record                    | 200, 404     |
-| `POST`    | `/foos`      | Create a record                      | 201, 422     |
-| `PUT`     | `/foos/:id`  | Full replace (all fields required)   | 200, 404, 422|
-| `PATCH`   | `/foos/:id`  | Partial update (all fields optional) | 200, 404, 422|
-| `DELETE`  | `/foos/:id`  | Delete a record                      | 200, 404     |
+| Method | Path | Description | Status |
+|--------|------|-------------|--------|
+| `GET` | `/foos` | List all records | 200 |
+| `GET` | `/foos/:id` | Get single record | 200, 404 |
+| `POST` | `/foos` | Create a record | 201, 422 |
+| `PUT` | `/foos/:id` | Full replace | 200, 404, 422 |
+| `PATCH` | `/foos/:id` | Partial update | 200, 404, 422 |
+| `DELETE` | `/foos/:id` | Delete a record | 200, 404 |
 
 > Names are auto-pluralized: `Product` → `/products`, `Category` → `/categories`.
 
+### System endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/__reset` | Regenerate all data |
+| `GET` | `/__snapshot` | Dump current DB to JSON |
+| `GET` | `/docs` | Swagger UI |
+| `GET` | `/openapi.json` | OpenAPI 3.0 spec |
+
 ---
 
-## Query Params on GET /list
+## Query Params (GET /list)
 
-| Param         | Example                      | Description                         |
-|---------------|------------------------------|-------------------------------------|
-| `page`        | `?page=2`                    | Page number (default: 1)            |
-| `limit`       | `?limit=10`                  | Records per page                    |
-| `sort`        | `?sort=price`                | Sort by field                       |
-| `order`       | `?order=desc`                | `asc` (default) or `desc`           |
-| `search`      | `?search=apple`              | Full-text search across string fields|
-| `{field}`     | `?status=published`          | Exact field filter                  |
+### Pagination, sorting, search
 
-All params are combinable:
 ```
-GET /posts?search=react&status=published&sort=price&order=asc&page=1&limit=20
+?page=2&limit=10
+?sort=price&order=desc
+?search=apple                 full-text search across all string fields
+?status=published             exact match filter
 ```
 
-**Response envelope:**
-```json
-{
-  "data": [ { "id": "...", "title": "...", ... } ],
-  "meta": {
-    "pagination": { "total": 47, "page": 1, "limit": 10, "pages": 5 }
-  }
-}
+### Filter operators
+
+```
+?price_gte=100                price >= 100
+?price_lte=500                price <= 500
+?price_gt=0                   price > 0
+?price_lt=1000                price < 1000
+?price_ne=0                   price != 0
+?status_in=draft,published    status in ['draft', 'published']
+?title_contains=hello         title contains 'hello' (case-insensitive)
 ```
 
-With custom meta fields (see [Custom Meta](#custom-meta) below):
+All params are combinable:
+```
+GET /posts?search=react&status_in=draft,published&price_gte=10&sort=price&order=asc&page=1&limit=20
+```
+
+### Response envelope
+
 ```json
 {
-  "data": [ ... ],
+  "data": [{ "id": "...", "title": "...", "price": 49.99 }],
   "meta": {
-    "pagination": { "total": 23, "page": 1, "limit": 10, "pages": 3 },
+    "pagination": { "total": 47, "page": 1, "limit": 10, "pages": 5 },
     "currency": "USD",
-    "avgPrice": 149.99,
-    "byStatus": { "draft": 5, "published": 15, "archived": 3 }
+    "avgPrice": 124.50
   }
 }
 ```
 
-Also sets `X-Total-Count: 47` header.
+Header: `X-Total-Count: 47`
 
 ---
 
-## Custom Meta
+## Field Types
 
-Define `meta` on any entity to enrich the list response. Meta values can be **static** (always included as-is) or **functions** (computed on the current filtered dataset, before pagination).
+### Primitives
 
 ```ts
-import type { MetaFn } from '@koltakov/ffa-core'
-
-Product: entity({
-  price:  number().price().required(),
-  status: enumField(['active', 'sale', 'soldout']).required(),
-  rating: number().rating().required(),
-}, {
-  count: 50,
-  meta: {
-    // Static — always the same regardless of filters
-    currency:   'USD',
-    apiVersion: 2,
-    sortOptions: ['price', 'rating', 'title'],
-
-    // Functions — receive items after search/filter, before pagination
-    total:      (items) => items.length,
-    avgPrice:   (items) => +(items.reduce((s, i) => s + (i.price as number), 0) / items.length).toFixed(2),
-    avgRating:  (items) => +(items.reduce((s, i) => s + (i.rating as number), 0) / items.length).toFixed(1),
-    priceRange: (items) => ({
-      min: Math.min(...items.map(i => i.price as number)),
-      max: Math.max(...items.map(i => i.price as number)),
-    }),
-    byStatus:   (items) => Object.fromEntries(
-      ['active', 'sale', 'soldout'].map(s => [s, items.filter(i => i.status === s).length])
-    ),
-  },
-})
+string()     // chainable hints — see below
+number()     // chainable hints — see below
+boolean()
+uuid()
+datetime()
 ```
 
-Response when filtering with `?status=active&page=1&limit=10`:
-```json
-{
-  "data": [ ... ],
-  "meta": {
-    "pagination": { "total": 31, "page": 1, "limit": 10, "pages": 4 },
-    "currency": "USD",
-    "apiVersion": 2,
-    "sortOptions": ["price", "rating", "title"],
-    "total": 31,
-    "avgPrice": 124.50,
-    "avgRating": 4.1,
-    "priceRange": { "min": 9.99, "max": 599.99 },
-    "byStatus": { "active": 31, "sale": 0, "soldout": 0 }
-  }
-}
-```
-
-> Meta functions receive only the filtered items — so `avgPrice` and `byStatus` always reflect the current search/filter result, not the full dataset.
-
----
-
-## Relations
+### Enum
 
 ```ts
-import { belongsTo, hasMany } from '@koltakov/ffa-core'
+enumField(['draft', 'published', 'archived'])
+```
 
-entities: {
-  User: entity({ name: string().required() }),
+### Relations
 
-  Post: entity({
-    title: string().required(),
-    authorId: belongsTo('User'),   // stores a random User id
-    tagIds: hasMany('Tag'),        // stores 1–3 random Tag ids
-  }),
-}
+```ts
+belongsTo('User')   // stores a random User id
+hasMany('Tag')      // stores an array of 1–3 Tag ids
 ```
 
-**Inline join** on GET by id:
+**Inline join** on `GET /:id`:
 ```
 GET /posts/abc?include=authorId,tagIds
 ```
-Returns the related objects inline instead of just ids.
 
----
+### Nested structures (v0.12.0)
 
-## Field Types
+```ts
+// Nested object — generates each field recursively
+address: object({
+  city:    string().city(),
+  country: string().country(),
+  zip:     string().zip(),
+})
 
-| Factory               | Faker output                     | Notes                          |
-|-----------------------|----------------------------------|--------------------------------|
-| `string()`            | Smart by field name or word      | Chainable hints — see below    |
-| `number()`            | Integer 0–1000                   | Chainable hints — see below    |
-| `boolean()`           | `true` / `false`                 |                                |
-| `uuid()`              | UUID v4                          |                                |
-| `datetime()`          | ISO 8601 string                  |                                |
-| `enumField([...])`    | Random value from array          | Also validates on write        |
-| `belongsTo('Entity')` | Random id from that entity       |                                |
-| `hasMany('Entity')`   | Array of 1–3 ids from that entity|                                |
+// Array of typed items
+tags:   array(string().word())
+phones: array(string().phone(), [1, 4])  // [min, max] items
+scores: array(number().rating())
+```
 
 ---
 
-## DSL Fake Hints
-
-When field name alone isn't enough, chain a hint method to control exactly what gets generated.
-Hints take priority over smart field-name detection.
+## String Fake Hints
 
-### `string()` hints
+Chain a method on `string()` to control what gets generated:
 
 ```ts
 // Internet
-string().email()       // → "user@example.com"
-string().url()         // → "https://example.com"
-string().domain()      // → "example.com"
-string().ip()          // → "192.168.1.1"
-string().username()    // → "john_doe"
+string().email()       // "user@example.com"
+string().url()         // "https://example.com"
+string().domain()      // "example.com"
+string().ip()          // "192.168.1.1"
+string().username()    // "john_doe"
 
 // Media
-string().image()       // → "https://loremflickr.com/640/480"
-string().avatar()      // → "https://avatars.githubusercontent.com/..."
+string().image()              // "https://picsum.photos/seed/xxx/1280/720" (default 16:9)
+string().image(300, 450)      // "https://picsum.photos/seed/xxx/300/450"  (portrait 2:3)
+string().image(1920, 1080)    // "https://picsum.photos/seed/xxx/1920/1080" (Full HD)
+string().avatar()             // avatar URL
 
 // Person
-string().firstName()   // → "Alice"
-string().lastName()    // → "Johnson"
-string().fullName()    // → "Alice Johnson"
-string().phone()       // → "+1-555-234-5678"
+string().firstName()   // "Alice"
+string().lastName()    // "Johnson"
+string().fullName()    // "Alice Johnson"
+string().phone()       // "+1-555-234-5678"
 
 // Location
-string().city()        // → "Berlin"
-string().country()     // → "Germany"
-string().address()     // → "12 Oak Street"
-string().zip()         // → "10115"
-string().locale()      // → "DE"
+string().city()        // "Berlin"
+string().country()     // "Germany"
+string().address()     // "12 Oak Street"
+string().zip()         // "10115"
+string().locale()      // "DE"
 
 // Business
-string().company()     // → "Acme Corp"
-string().jobTitle()    // → "Senior Engineer"
-string().department()  // → "Electronics"
-string().currency()    // → "EUR"
+string().company()     // "Acme Corp"
+string().jobTitle()    // "Senior Engineer"
+string().department()  // "Electronics"
+string().currency()    // "EUR"
 
 // Text
-string().word()        // → "matrix"
-string().slug()        // → "hello-world"
-string().sentence()    // → "The quick brown fox."
-string().paragraph()   // → "Lorem ipsum dolor..."
-string().bio()         // → "Lorem ipsum dolor..."
+string().word()        // "matrix"
+string().slug()        // "hello-world"
+string().sentence()    // "The quick brown fox."
+string().paragraph()   // "Lorem ipsum dolor..."
+string().bio()         // "Lorem ipsum dolor..."
 
 // Visual
-string().color()       // → "azure"
-string().hexColor()    // → "#A3F5C2"
+string().color()       // "azure"
+string().hexColor()    // "#A3F5C2"
 
 // Id
-string().uuid()        // → "a3f7c2b1-..."
+string().uuid()        // UUID v4
 ```
 
-### `number()` hints
+## Number Fake Hints
 
 ```ts
-number().price()       // → 19.99
-number().age()         // → 34
-number().rating()      // → 4
-number().percent()     // → 72
-number().lat()         // → 51.5074
-number().lng()         // → -0.1278
-number().year()        // → 2021
+number().price()       // 19.99
+number().age()         // 34
+number().rating()      // 4
+number().percent()     // 72
+number().lat()         // 51.5074
+number().lng()         // -0.1278
+number().year()        // 2021
 ```
 
-### Escape hatch
+## Smart Field-Name Detection
+
+When no hint is set, ffa infers the right value from the field name automatically:
+
+| Field name pattern | Generated value |
+|--------------------|----------------|
+| `email`, `mail` | Email address |
+| `name`, `firstName` | First name |
+| `lastName`, `surname` | Last name |
+| `phone`, `tel`, `mobile` | Phone number |
+| `city`, `country`, `address` | Location values |
+| `url`, `website`, `link` | URL |
+| `avatar`, `photo` | Avatar URL |
+| `image` | Image URL |
+| `company` | Company name |
+| `title`, `heading` | Short sentence |
+| `description`, `bio`, `text` | Paragraph |
+| `price`, `cost`, `amount` | Price |
+| `color` | Color name |
+
+---
+
+## Field Rules
 
-For any case not covered by the methods above, use `.fake(hint)` directly with full TypeScript autocomplete:
+All builders share these chainable rules:
+
+| Method | Effect |
+|--------|--------|
+| `.required()` | Field required in POST/PUT |
+| `.optional()` | Field can be omitted (default) |
+| `.min(n)` | Min string length / min number value |
+| `.max(n)` | Max string length / max number value |
+| `.readonly()` | Excluded from create/update validation |
+| `.default(val)` | Default value |
+| `.fake(hint)` | Explicit faker hint |
+| `.image(w, h)` | Image dimensions (only for `string().image()`) |
+
+---
+
+## Seed Data (v0.9.0)
+
+Guarantee specific records always exist in your entity:
 
 ```ts
-string().fake('hexColor')
-number().fake('rating')
+User: entity({
+  name: string().fullName().required(),
+  role: enumField(['admin', 'editor', 'viewer']).required(),
+}, {
+  count: 20,
+  seed: [
+    { id: 'admin-1', name: 'Admin User', role: 'admin' },
+    { name: 'Guest User', role: 'viewer' },  // id auto-generated if omitted
+  ],
+})
 ```
 
-### Example config
+Seed records appear first. The remaining `count - seed.length` records are generated.
+
+---
+
+## Custom Meta (v0.8.0)
+
+Attach extra fields to the list response `meta`. Values can be static or computed from the current filtered dataset (before pagination):
 
 ```ts
-User: entity({
-  name:       string().fullName().required(),
-  email:      string().email().required(),
-  avatar:     string().avatar().optional(),
-  bio:        string().paragraph().optional(),
-  role:       enumField(['admin', 'editor', 'viewer']).required(),
-}),
-
-Product: entity({
-  title:      string().sentence().required(),
-  image:      string().image().required(),
-  price:      number().price().required(),
-  rating:     number().rating().required(),
-  company:    string().company().required(),
-  color:      string().color().optional(),
-  lat:        number().lat().required(),
-  lng:        number().lng().required(),
-}),
-```
-
-### Smart Faker by Field Name (auto, no hint needed)
-
-If the field name matches a known keyword, ffa generates the right value automatically — no hint required:
-
-| Field name pattern          | Generated value         |
-|-----------------------------|-------------------------|
-| `email`, `mail`             | Email address           |
-| `name`, `firstName`         | First name              |
-| `lastName`, `surname`       | Last name               |
-| `phone`, `tel`, `mobile`    | Phone number            |
-| `city`, `country`, `address`| Location values         |
-| `url`, `website`, `link`    | URL                     |
-| `avatar`, `photo`           | Avatar URL              |
-| `image`                     | Image URL               |
-| `company`                   | Company name            |
-| `title`, `heading`          | Short sentence          |
-| `description`, `bio`, `text`| Paragraph               |
-| `price`, `cost`, `amount`   | Price                   |
-| `color`                     | Color name              |
+Product: entity({ price: number().price(), status: enumField(['active', 'sale']) }, {
+  count: 50,
+  meta: {
+    currency:   'USD',                                              // static
+    apiVersion: 2,                                                  // static
+    total:      (items) => items.length,                            // computed
+    avgPrice:   (items) => +(items.reduce((s, i) => s + (i.price as number), 0) / items.length).toFixed(2),
+    byStatus:   (items) => Object.fromEntries(
+      ['active', 'sale'].map(s => [s, items.filter(i => i.status === s).length])
+    ),
+  },
+})
+```
+
+Meta functions receive items **after** search/filter but **before** pagination — so aggregates always reflect the current query.
 
 ---
 
-## Field Rules
+## Seed Data Export (v0.15.0)
+
+Export the current in-memory DB while the server is running — useful for generating fixture files:
+
+```bash
+ffa snapshot                  # → ffa-snapshot.json
+ffa snapshot -o fixtures.json
+ffa snapshot -p 4000          # specify port if not in config
+```
+
+Or call directly:
+```
+GET /__snapshot   → { "User": [...], "Post": [...] }
+```
+
+---
+
+## Inspect Config (v0.16.0)
+
+Print your config structure without starting the server:
+
+```bash
+ffa inspect
+```
+
+```
+  FFA inspect  port 3333
+
+  User  20 records  +1 seed
+    *  name      string  [fullName]
+    *  email     string  [email]
+    *  role      enum    (admin | editor | viewer)
+       avatar    string  [avatar]
+       address   object  { city, country, zip }
+       phones    array   of string
+
+  Post  50 records
+    *  title     string     [sentence]
+    *  body      string     [paragraph]
+    *  status    enum       (draft | published | archived)
+    *  price     number     [price]
+       authorId  belongsTo  → User
+       tagIds    hasMany    → Tag
+       meta: currency, total, avgPrice
+
+  delay 200–600ms  ·  persist ffa-data.json  ·  errorRate 5%
+```
+
+---
+
+## Config Validation (v0.11.0)
+
+On startup, ffa checks your config and prints warnings:
 
-| Rule          | Applies to         | Effect                                          |
-|---------------|--------------------|-------------------------------------------------|
-| `.required()` | all                | Field required in POST/PUT requests             |
-| `.optional()` | all                | Field can be omitted                            |
-| `.min(n)`     | `string`, `number` | Min length / min value                         |
-| `.max(n)`     | `string`, `number` | Max length / max value                         |
-| `.readonly()` | all                | Excluded from create/update validation          |
-| `.fake(hint)` | `string`, `number` | Explicit faker hint (see DSL hints above)       |
+```
+  ⚠  Post.authorId (belongsTo) references 'Author' which is not defined
+  ⚠  Tag.type is enum but has no values
+  ⚠  User: seed has 5 records but count is 3 — seed will be truncated
+```
 
 ---
 
-## Server Config
+## Error Simulation (v0.14.0)
+
+Test your frontend error handling without mocking:
 
 ```ts
 server: {
-  port: 3333,              // default: 3000
-  delay: 400,              // fixed delay in ms
-  delay: [200, 800],       // random delay between min and max ms
-  persist: true,           // save to ./ffa-data.json
-  persist: './data.json',  // custom file path
+  errorRate: 0.1   // 10% of requests return 500
 }
 ```
 
-If `delay` is set, system routes (`/__reset`, `/docs`) are not delayed.
-
-If the configured port is busy, ffa automatically tries the next one.
+System routes (`/__reset`, `/__snapshot`, `/docs`) are never affected.
 
 ---
 
-## System Endpoints
-
-| Method | Path           | Description                        |
-|--------|----------------|------------------------------------|
-| `POST` | `/__reset`     | Regenerate all seed data in memory |
-| `GET`  | `/docs`        | Swagger UI                         |
-| `GET`  | `/openapi.json`| Raw OpenAPI 3.0 spec               |
+## Persistence
 
 ```ts
-// Reset data from frontend code (e.g. in test setup)
-await fetch('http://localhost:3333/__reset', { method: 'POST' })
+server: {
+  persist: true,             // save to ./ffa-data.json
+  persist: './data/db.json', // custom path
+}
 ```
 
+Data is saved on every write (POST/PUT/PATCH/DELETE) and restored on restart.
+
+---
+
+## JSON Config (no TypeScript)
+
+```json
+{
+  "server": { "port": 3333, "delay": 300 },
+  "entities": {
+    "Product": {
+      "count": 20,
+      "fields": {
+        "title":     "string!",
+        "price":     "number",
+        "status":    ["draft", "published", "archived"],
+        "inStock":   "boolean",
+        "createdAt": "datetime"
+      }
+    }
+  }
+}
+```
+
+Save as `ffa.config.json`. `"string!"` = required, `"string"` = optional. Arrays are shorthand for `enumField`.
+
 ---
 
 ## Terminal Output
 
-Every request is logged with method, URL, status code and response time:
+```
+  FFA dev server  v0.16.0
+
+  Entity    Count  Route
+  ──────────────────────────────────────────────────────────
+  User         20  GET POST  http://localhost:3333/users
+  Post         50  GET POST  http://localhost:3333/posts
+  Tag          15  GET POST  http://localhost:3333/tags
+
+  delay      200–600ms
+  errorRate  5% chance of 500
+
+  docs    http://localhost:3333/docs
+  reset   POST http://localhost:3333/__reset
 
+  GET    /users                              200  14ms
+  POST   /posts                             201  312ms
+  GET    /posts/abc-123                     404  8ms
+  PATCH  /posts/def-456                     200  267ms
 ```
-  FFA dev server  v0.6.0
 
-  → Product          20 records   http://localhost:3333/products
-  → User             10 records   http://localhost:3333/users
+---
 
-  delay: 200–600ms
-  → Swagger UI   http://localhost:3333/docs
+## Testing
 
-  GET    /products                            200  312ms
-  POST   /products                           201  287ms
-  GET    /products/abc-123                   404  201ms
-  PATCH  /products/def-456                   200  344ms
+```bash
+npm test          # run all tests once
+npm run test:watch  # watch mode
 ```
 
+Tests live in `tests/` and are excluded from the build. 144 tests covering:
+
+- DSL builders and all fake hints (`string()`, `number()`, `object()`, `array()`, ...)
+- Zod schema generation for all field types
+- `entity()` helper
+- `createMemoryDB` — CRUD, pagination, sorting, search, filter operators, seed, meta, relations, image dimensions
+- `validateConfig` — all warning scenarios
+
 ---
 
 ## License