@koltakov/ffa-core 0.6.0

package/README.md

@@ -0,0 +1,281 @@
+# ffa-core
+
+**F**rontend **F**irst **A**PI — instant mock REST API for frontend development.
+
+Stop waiting for the backend. Describe your data, run one command, get a working API.
+
+---
+
+## 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
+- **Smart fake data** — field names drive generation (`email`, `price`, `avatar`, ...)
+- **Zod validation** — request bodies validated against your schema
+- **Swagger UI** — auto-generated docs at `/docs`
+- **Delay simulation** — test loading states with artificial latency
+- **TypeScript or JSON** — pick your config format
+
+---
+
+## Quick Start
+
+```bash
+# 1. Install
+npm install @koltakov/ffa-core
+
+# 2. Scaffold a config
+npx ffa init
+
+# 3. Start
+npx ffa dev
+```
+
+Or skip `init` and write `ffa.config.ts` manually (see below).
+
+---
+
+## Config: TypeScript
+
+```ts
+import { defineConfig, entity, string, number, boolean, enumField, belongsTo } from '@koltakov/ffa-core'
+
+export default defineConfig({
+  server: {
+    port: 3333,
+    delay: [200, 600],   // artificial latency (ms or [min, max])
+    persist: true,       // save data to ffa-data.json between restarts
+  },
+
+  entities: {
+    User: entity({
+      name: string().required(),
+      email: string().required(),
+      role: enumField(['admin', 'editor', 'viewer']).required(),
+      avatar: string().optional(),
+    }, { count: 20 }),
+
+    Post: entity({
+      title: string().required(),
+      body: string().required(),
+      status: enumField(['draft', 'published', 'archived']).required(),
+      price: number().min(0).max(9999).required(),
+      authorId: belongsTo('User'),
+    }),
+  },
+})
+```
+
+## 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)
+```
+
+---
+
+## Generated Endpoints
+
+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     |
+
+> Names are auto-pluralized: `Product` → `/products`, `Category` → `/categories`.
+
+---
+
+## Query Params on 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                  |
+
+All params are combinable:
+```
+GET /posts?search=react&status=published&sort=price&order=asc&page=1&limit=20
+```
+
+**Response envelope:**
+```json
+{
+  "data": [ { "id": "...", "title": "...", ... } ],
+  "meta": { "total": 47, "page": 1, "limit": 20, "pages": 3 }
+}
+```
+
+Also sets `X-Total-Count: 47` header.
+
+---
+
+## Relations
+
+```ts
+import { belongsTo, hasMany } from '@koltakov/ffa-core'
+
+entities: {
+  User: entity({ name: string().required() }),
+
+  Post: entity({
+    title: string().required(),
+    authorId: belongsTo('User'),   // stores a random User id
+    tagIds: hasMany('Tag'),        // stores 1–3 random Tag ids
+  }),
+}
+```
+
+**Inline join** on GET by id:
+```
+GET /posts/abc?include=authorId,tagIds
+```
+Returns the related objects inline instead of just ids.
+
+---
+
+## Field Types
+
+| Factory               | Faker output                     | Notes                          |
+|-----------------------|----------------------------------|--------------------------------|
+| `string()`            | Smart by field name or word      | See smart faker below          |
+| `number()`            | Integer 0–1000                   | Respects `.min()` / `.max()`   |
+| `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|                                |
+
+### Smart Faker by Field Name
+
+Field names drive faker output automatically:
+
+| Field name pattern          | Generated value               |
+|-----------------------------|-------------------------------|
+| `email`, `mail`             | `faker.internet.email()`      |
+| `name`, `firstName`         | `faker.person.firstName()`    |
+| `lastName`, `surname`       | `faker.person.lastName()`     |
+| `phone`, `tel`, `mobile`    | `faker.phone.number()`        |
+| `city`, `country`, `address`| Location values               |
+| `url`, `website`, `link`    | `faker.internet.url()`        |
+| `avatar`, `photo`, `image`  | `faker.image.avatar()`        |
+| `company`                   | `faker.company.name()`        |
+| `title`, `heading`          | Short sentence                |
+| `description`, `bio`, `text`| Paragraph                     |
+| `price`, `cost`, `amount`   | `faker.commerce.price()`      |
+| `color`                     | `faker.color.human()`         |
+
+---
+
+## Field Rules
+
+| 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          |
+
+---
+
+## Server Config
+
+```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
+}
+```
+
+If `delay` is set, system routes (`/__reset`, `/docs`) are not delayed.
+
+If the configured port is busy, ffa automatically tries the next one.
+
+---
+
+## 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               |
+
+```ts
+// Reset data from frontend code (e.g. in test setup)
+await fetch('http://localhost:3333/__reset', { method: 'POST' })
+```
+
+---
+
+## Terminal Output
+
+Every request is logged with method, URL, status code and response time:
+
+```
+  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
+
+  GET    /products                            200  312ms
+  POST   /products                           201  287ms
+  GET    /products/abc-123                   404  201ms
+  PATCH  /products/def-456                   200  344ms
+```
+
+---
+
+## License
+
+ISC

package/dist/cli.js

@@ -0,0 +1,770 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { Command } from "commander";
+import { existsSync as existsSync3, writeFileSync as writeFileSync2, unlinkSync } from "fs";
+import { resolve } from "path";
+import { exec } from "child_process";
+
+// src/server.ts
+import Fastify from "fastify";
+import cors from "@fastify/cors";
+import swagger from "@fastify/swagger";
+import swaggerUi from "@fastify/swagger-ui";
+import path2 from "path";
+import { createServer } from "net";
+
+// src/config.ts
+import { existsSync, readFileSync } from "fs";
+import path from "path";
+import { pathToFileURL } from "url";
+function parseJsonConfig(raw) {
+  const entities = {};
+  for (const [entityName, entityRaw] of Object.entries(raw.entities ?? {})) {
+    const entityDef = entityRaw;
+    const fields = {};
+    for (const [fieldName, fieldRaw] of Object.entries(entityDef.fields ?? {})) {
+      if (Array.isArray(fieldRaw)) {
+        fields[fieldName] = { type: "enum", rules: { enumValues: fieldRaw } };
+      } else if (typeof fieldRaw === "string") {
+        const required = fieldRaw.endsWith("!");
+        const typeName = required ? fieldRaw.slice(0, -1) : fieldRaw;
+        fields[fieldName] = { type: typeName, rules: required ? { required: true } : {} };
+      } else if (typeof fieldRaw === "object" && fieldRaw !== null) {
+        const { type, required, min, max, readonly: ro, entity, enumValues } = fieldRaw;
+        fields[fieldName] = {
+          type,
+          rules: { required, min, max, readonly: ro, entity, enumValues }
+        };
+      }
+    }
+    entities[entityName] = { fields, count: entityDef.count };
+  }
+  return {
+    server: raw.server ?? { port: 3e3 },
+    entities
+  };
+}
+async function loadConfig() {
+  const tsPath = path.resolve(process.cwd(), "ffa.config.ts");
+  const jsonPath = path.resolve(process.cwd(), "ffa.config.json");
+  if (existsSync(tsPath)) {
+    const configUrl = pathToFileURL(tsPath).href;
+    const config = await import(`${configUrl}?t=${Date.now()}`);
+    return config.default;
+  }
+  if (existsSync(jsonPath)) {
+    const raw = JSON.parse(readFileSync(jsonPath, "utf-8"));
+    return parseJsonConfig(raw);
+  }
+  throw new Error("No config found. Create ffa.config.ts or ffa.config.json, or run: ffa init");
+}
+
+// src/memory-db.ts
+import { faker } from "@faker-js/faker";
+import { readFileSync as readFileSync2, writeFileSync, existsSync as existsSync2 } from "fs";
+var FIELD_NAME_MAP = {
+  email: () => faker.internet.email(),
+  mail: () => faker.internet.email(),
+  name: () => faker.person.firstName(),
+  firstname: () => faker.person.firstName(),
+  first_name: () => faker.person.firstName(),
+  lastname: () => faker.person.lastName(),
+  last_name: () => faker.person.lastName(),
+  surname: () => faker.person.lastName(),
+  fullname: () => faker.person.fullName(),
+  username: () => faker.person.fullName(),
+  phone: () => faker.phone.number(),
+  tel: () => faker.phone.number(),
+  mobile: () => faker.phone.number(),
+  city: () => faker.location.city(),
+  country: () => faker.location.country(),
+  address: () => faker.location.streetAddress(),
+  zip: () => faker.location.zipCode(),
+  postal: () => faker.location.zipCode(),
+  url: () => faker.internet.url(),
+  website: () => faker.internet.url(),
+  link: () => faker.internet.url(),
+  avatar: () => faker.image.avatar(),
+  photo: () => faker.image.avatar(),
+  image: () => faker.image.avatar(),
+  company: () => faker.company.name(),
+  title: () => faker.lorem.sentence(3),
+  heading: () => faker.lorem.sentence(3),
+  description: () => faker.lorem.paragraph(),
+  bio: () => faker.lorem.paragraph(),
+  text: () => faker.lorem.paragraph(),
+  color: () => faker.color.human(),
+  price: () => faker.commerce.price(),
+  cost: () => faker.commerce.price(),
+  amount: () => faker.commerce.price()
+};
+function generateFakeValue(def, fieldName, db) {
+  if (def.type === "enum") {
+    if (def.rules.enumValues?.length) return faker.helpers.arrayElement(def.rules.enumValues);
+    return faker.lorem.word();
+  }
+  if (def.type === "belongsTo") {
+    const target = def.rules.entity;
+    if (target && db[target]?.length) {
+      const items = db[target];
+      return items[Math.floor(Math.random() * items.length)].id;
+    }
+    return faker.string.uuid();
+  }
+  if (def.type === "hasMany") {
+    const target = def.rules.entity;
+    if (target && db[target]?.length) {
+      const items = db[target];
+      const count = faker.number.int({ min: 1, max: Math.min(3, items.length) });
+      return [...items].sort(() => Math.random() - 0.5).slice(0, count).map((i) => i.id);
+    }
+    return [];
+  }
+  const normalized = fieldName.toLowerCase().replace(/[-\s]/g, "_");
+  const mapFn = FIELD_NAME_MAP[normalized];
+  if (mapFn) return mapFn();
+  for (const key of Object.keys(FIELD_NAME_MAP)) {
+    if (normalized.includes(key)) return FIELD_NAME_MAP[key]();
+  }
+  const { type, rules } = def;
+  switch (type) {
+    case "string":
+      return faker.lorem.word();
+    case "number": {
+      const min = rules.min ?? 0;
+      const max = rules.max ?? 1e3;
+      return faker.number.int({ min, max });
+    }
+    case "boolean":
+      return faker.datatype.boolean();
+    case "uuid":
+      return faker.string.uuid();
+    case "datetime":
+      return faker.date.recent().toISOString();
+    default:
+      return faker.lorem.word();
+  }
+}
+function generateRecord(fields, db) {
+  return {
+    id: faker.string.uuid(),
+    ...Object.fromEntries(
+      Object.entries(fields).map(([key, def]) => [key, generateFakeValue(def, key, db)])
+    )
+  };
+}
+function createMemoryDB(entities, persistPath) {
+  const db = {};
+  if (persistPath && existsSync2(persistPath)) {
+    try {
+      const raw = readFileSync2(persistPath, "utf-8");
+      const saved = JSON.parse(raw);
+      for (const name in entities) {
+        db[name] = saved[name] ?? [];
+      }
+    } catch {
+    }
+  }
+  function seedAll() {
+    const names = Object.keys(entities);
+    const sorted = [
+      ...names.filter((n) => !Object.values(entities[n].fields).some((f) => f.type === "belongsTo" || f.type === "hasMany")),
+      ...names.filter((n) => Object.values(entities[n].fields).some((f) => f.type === "belongsTo" || f.type === "hasMany"))
+    ];
+    for (const name of sorted) {
+      const { fields, count = 10 } = entities[name];
+      db[name] = Array.from({ length: count }).map(() => generateRecord(fields, db));
+    }
+  }
+  const needsSeed = Object.keys(entities).filter((n) => !db[n]);
+  if (needsSeed.length > 0) {
+    const names = Object.keys(entities);
+    const sorted = [
+      ...names.filter((n) => !Object.values(entities[n].fields).some((f) => f.type === "belongsTo" || f.type === "hasMany")),
+      ...names.filter((n) => Object.values(entities[n].fields).some((f) => f.type === "belongsTo" || f.type === "hasMany"))
+    ];
+    for (const name of sorted) {
+      if (!db[name]) {
+        const { fields, count = 10 } = entities[name];
+        db[name] = Array.from({ length: count }).map(() => generateRecord(fields, db));
+      }
+    }
+  }
+  function persist() {
+    if (persistPath) {
+      writeFileSync(persistPath, JSON.stringify(db, null, 2), "utf-8");
+    }
+  }
+  return {
+    list(entity, options = {}) {
+      let items = [...db[entity] ?? []];
+      if (options.search) {
+        const q = options.search.toLowerCase();
+        items = items.filter(
+          (item) => Object.values(item).some((v) => typeof v === "string" && v.toLowerCase().includes(q))
+        );
+      }
+      if (options.filter) {
+        for (const [key, value] of Object.entries(options.filter)) {
+          items = items.filter((item) => String(item[key]) === value);
+        }
+      }
+      if (options.sort) {
+        const sortKey = options.sort;
+        const order = options.order ?? "asc";
+        items.sort((a, b) => {
+          const aVal = a[sortKey];
+          const bVal = b[sortKey];
+          if (aVal == null) return 1;
+          if (bVal == null) return -1;
+          const cmp = aVal < bVal ? -1 : aVal > bVal ? 1 : 0;
+          return order === "desc" ? -cmp : cmp;
+        });
+      }
+      const total = items.length;
+      const page = options.page ?? 1;
+      const limit = options.limit ?? total;
+      const pages = limit > 0 ? Math.ceil(total / limit) : 1;
+      const offset = (page - 1) * limit;
+      const data = options.limit ? items.slice(offset, offset + limit) : items;
+      return { data, meta: { total, page, limit, pages } };
+    },
+    get(entity, id) {
+      return db[entity]?.find((item) => item.id === id);
+    },
+    create(entity, data) {
+      const item = { id: faker.string.uuid(), ...data };
+      db[entity].push(item);
+      persist();
+      return item;
+    },
+    update(entity, id, data) {
+      const idx = db[entity].findIndex((i) => i.id === id);
+      if (idx === -1) return null;
+      db[entity][idx] = { ...db[entity][idx], ...data };
+      persist();
+      return db[entity][idx];
+    },
+    remove(entity, id) {
+      const idx = db[entity].findIndex((i) => i.id === id);
+      if (idx === -1) return false;
+      db[entity].splice(idx, 1);
+      persist();
+      return true;
+    },
+    reset() {
+      for (const name in entities) db[name] = [];
+      seedAll();
+      persist();
+    },
+    count(entity) {
+      return db[entity]?.length ?? 0;
+    }
+  };
+}
+
+// src/field/toZodSchema.ts
+import { z } from "zod";
+function fieldToZod(def) {
+  let schema;
+  switch (def.type) {
+    case "string": {
+      let s = z.string();
+      if (def.rules.min !== void 0) s = s.min(def.rules.min);
+      if (def.rules.max !== void 0) s = s.max(def.rules.max);
+      schema = s;
+      break;
+    }
+    case "number": {
+      let n = z.number();
+      if (def.rules.min !== void 0) n = n.gte(def.rules.min);
+      if (def.rules.max !== void 0) n = n.lte(def.rules.max);
+      schema = n;
+      break;
+    }
+    case "boolean": {
+      schema = z.boolean();
+      break;
+    }
+    case "uuid": {
+      schema = z.string().uuid();
+      break;
+    }
+    case "datetime": {
+      schema = z.string().datetime();
+      break;
+    }
+    case "enum": {
+      const values = def.rules.enumValues ?? [];
+      schema = values.length >= 1 ? z.enum(values) : z.string();
+      break;
+    }
+    case "belongsTo": {
+      schema = z.string();
+      break;
+    }
+    case "hasMany": {
+      schema = z.array(z.string());
+      break;
+    }
+    default: {
+      schema = z.unknown();
+    }
+  }
+  if (def.rules.required === false) {
+    schema = schema.optional();
+  }
+  return schema;
+}
+function entityToZod(fields) {
+  const shape = {};
+  for (const [key, def] of Object.entries(fields)) {
+    if (def.rules.readonly) continue;
+    shape[key] = fieldToZod(def);
+  }
+  return z.object(shape);
+}
+
+// src/openapi.ts
+function fieldToJsonSchema(def) {
+  switch (def.type) {
+    case "string": {
+      const prop = { type: "string" };
+      if (def.rules.min !== void 0) prop.minLength = def.rules.min;
+      if (def.rules.max !== void 0) prop.maxLength = def.rules.max;
+      return prop;
+    }
+    case "number": {
+      const prop = { type: "number" };
+      if (def.rules.min !== void 0) prop.minimum = def.rules.min;
+      if (def.rules.max !== void 0) prop.maximum = def.rules.max;
+      return prop;
+    }
+    case "boolean":
+      return { type: "boolean" };
+    case "uuid":
+      return { type: "string", format: "uuid" };
+    case "datetime":
+      return { type: "string", format: "date-time" };
+    case "enum":
+      return { type: "string", enum: def.rules.enumValues ?? [] };
+    case "belongsTo":
+      return { type: "string", format: "uuid" };
+    case "hasMany":
+      return { type: "array", items: { type: "string", format: "uuid" } };
+    default:
+      return { type: "string" };
+  }
+}
+function fieldsToJsonSchema(fields, includeReadonly = true) {
+  const properties = {
+    id: { type: "string", format: "uuid" }
+  };
+  const required = ["id"];
+  for (const [key, def] of Object.entries(fields)) {
+    if (!includeReadonly && def.rules.readonly) continue;
+    properties[key] = fieldToJsonSchema(def);
+    if (def.rules.required) required.push(key);
+  }
+  return { type: "object", properties, required };
+}
+function fieldsToInputSchema(fields) {
+  const properties = {};
+  const required = [];
+  for (const [key, def] of Object.entries(fields)) {
+    if (def.rules.readonly) continue;
+    properties[key] = fieldToJsonSchema(def);
+    if (def.rules.required) required.push(key);
+  }
+  return { type: "object", properties, required: required.length ? required : void 0 };
+}
+function pluralize(word) {
+  const lower = word.toLowerCase();
+  if (lower.endsWith("y") && !/[aeiou]y$/i.test(lower)) {
+    return lower.slice(0, -1) + "ies";
+  }
+  if (/(s|x|z|ch|sh)$/i.test(lower)) {
+    return lower + "es";
+  }
+  return lower + "s";
+}
+function generateOpenApiSpec(config) {
+  const schemas = {};
+  const paths = {};
+  for (const [entityName, entityDef] of Object.entries(config.entities)) {
+    const pluralName = pluralize(entityName);
+    const basePath = `/${pluralName}`;
+    schemas[entityName] = fieldsToJsonSchema(entityDef.fields);
+    schemas[`${entityName}Input`] = fieldsToInputSchema(entityDef.fields);
+    const entityRef = { $ref: `#/components/schemas/${entityName}` };
+    const inputRef = { $ref: `#/components/schemas/${entityName}Input` };
+    paths[basePath] = {
+      get: {
+        summary: `List all ${pluralName}`,
+        tags: [entityName],
+        responses: {
+          "200": {
+            description: "Success",
+            content: {
+              "application/json": {
+                schema: { type: "array", items: entityRef }
+              }
+            }
+          }
+        }
+      },
+      post: {
+        summary: `Create a ${entityName}`,
+        tags: [entityName],
+        requestBody: {
+          required: true,
+          content: {
+            "application/json": { schema: inputRef }
+          }
+        },
+        responses: {
+          "201": {
+            description: "Created",
+            content: {
+              "application/json": { schema: entityRef }
+            }
+          },
+          "422": { description: "Validation error" }
+        }
+      }
+    };
+    paths[`${basePath}/{id}`] = {
+      get: {
+        summary: `Get ${entityName} by ID`,
+        tags: [entityName],
+        parameters: [{ name: "id", in: "path", required: true, schema: { type: "string" } }],
+        responses: {
+          "200": {
+            description: "Success",
+            content: { "application/json": { schema: entityRef } }
+          },
+          "404": { description: "Not found" }
+        }
+      },
+      put: {
+        summary: `Replace ${entityName}`,
+        tags: [entityName],
+        parameters: [{ name: "id", in: "path", required: true, schema: { type: "string" } }],
+        requestBody: {
+          required: true,
+          content: { "application/json": { schema: inputRef } }
+        },
+        responses: {
+          "200": {
+            description: "Updated",
+            content: { "application/json": { schema: entityRef } }
+          },
+          "404": { description: "Not found" },
+          "422": { description: "Validation error" }
+        }
+      },
+      patch: {
+        summary: `Partially update ${entityName}`,
+        tags: [entityName],
+        parameters: [{ name: "id", in: "path", required: true, schema: { type: "string" } }],
+        requestBody: {
+          required: true,
+          content: { "application/json": { schema: inputRef } }
+        },
+        responses: {
+          "200": {
+            description: "Updated",
+            content: { "application/json": { schema: entityRef } }
+          },
+          "404": { description: "Not found" },
+          "422": { description: "Validation error" }
+        }
+      },
+      delete: {
+        summary: `Delete ${entityName}`,
+        tags: [entityName],
+        parameters: [{ name: "id", in: "path", required: true, schema: { type: "string" } }],
+        responses: {
+          "200": { description: "Deleted" },
+          "404": { description: "Not found" }
+        }
+      }
+    };
+  }
+  return {
+    openapi: "3.0.0",
+    info: {
+      title: "FFA Mock API",
+      version: "1.0.0",
+      description: "Auto-generated mock REST API by ffa-core"
+    },
+    paths,
+    components: { schemas }
+  };
+}
+
+// src/server.ts
+function pluralize2(word) {
+  const lower = word.toLowerCase();
+  if (lower.endsWith("y") && !/[aeiou]y$/i.test(lower)) return lower.slice(0, -1) + "ies";
+  if (/(s|x|z|ch|sh)$/i.test(lower)) return lower + "es";
+  return lower + "s";
+}
+function isPortFree(port) {
+  return new Promise((resolve2) => {
+    const srv = createServer();
+    srv.once("error", () => resolve2(false));
+    srv.once("listening", () => {
+      srv.close();
+      resolve2(true);
+    });
+    srv.listen(port, "0.0.0.0");
+  });
+}
+async function findPort(start) {
+  let port = start;
+  while (!await isPortFree(port)) {
+    console.log(`  Port ${port} is busy, trying ${port + 1}...`);
+    port++;
+  }
+  return port;
+}
+var c = {
+  reset: "\x1B[0m",
+  bold: "\x1B[1m",
+  dim: "\x1B[2m",
+  cyan: "\x1B[36m",
+  green: "\x1B[32m",
+  yellow: "\x1B[33m",
+  red: "\x1B[31m",
+  blue: "\x1B[34m",
+  gray: "\x1B[90m"
+};
+function colorMethod(method) {
+  const m = method.toUpperCase().padEnd(6);
+  switch (method.toUpperCase()) {
+    case "GET":
+      return `${c.cyan}${m}${c.reset}`;
+    case "POST":
+      return `${c.green}${m}${c.reset}`;
+    case "PUT":
+      return `${c.yellow}${m}${c.reset}`;
+    case "PATCH":
+      return `${c.yellow}${m}${c.reset}`;
+    case "DELETE":
+      return `${c.red}${m}${c.reset}`;
+    default:
+      return m;
+  }
+}
+function colorStatus(code) {
+  const s = String(code);
+  if (code < 300) return `${c.green}${s}${c.reset}`;
+  if (code < 400) return `${c.cyan}${s}${c.reset}`;
+  if (code < 500) return `${c.yellow}${s}${c.reset}`;
+  return `${c.red}${s}${c.reset}`;
+}
+var currentApp = null;
+async function startServer(portOverride) {
+  const config = await loadConfig();
+  const port = await findPort(portOverride ?? config.server.port);
+  const openApiSpec = generateOpenApiSpec(config);
+  const app = Fastify({ logger: false });
+  currentApp = app;
+  await app.register(cors, { origin: "*" });
+  await app.register(swagger, { mode: "static", specification: { document: openApiSpec } });
+  await app.register(swaggerUi, { routePrefix: "/docs" });
+  app.addHook("onRequest", (req, _reply, done) => {
+    req._ffaStart = Date.now();
+    done();
+  });
+  const delayConfig = config.server.delay;
+  if (delayConfig !== void 0) {
+    const SYSTEM_ROUTES = /* @__PURE__ */ new Set(["/__reset", "/docs", "/openapi.json"]);
+    app.addHook("preHandler", async (req) => {
+      if (SYSTEM_ROUTES.has(req.url) || req.url.startsWith("/docs")) return;
+      const ms = Array.isArray(delayConfig) ? Math.floor(Math.random() * (delayConfig[1] - delayConfig[0] + 1)) + delayConfig[0] : delayConfig;
+      await new Promise((r) => setTimeout(r, ms));
+    });
+  }
+  app.addHook("onResponse", (req, reply, done) => {
+    if (req.url.startsWith("/docs/static") || req.url === "/favicon.ico") {
+      done();
+      return;
+    }
+    const ms = Date.now() - (req._ffaStart ?? Date.now());
+    const method = colorMethod(req.method);
+    const status = colorStatus(reply.statusCode);
+    const time = `${c.gray}${ms}ms${c.reset}`;
+    console.log(`  ${method} ${req.url.padEnd(35)} ${status}  ${time}`);
+    done();
+  });
+  let persistPath;
+  if (config.server.persist) {
+    persistPath = typeof config.server.persist === "string" ? path2.resolve(process.cwd(), config.server.persist) : path2.resolve(process.cwd(), "ffa-data.json");
+  }
+  const db = createMemoryDB(config.entities, persistPath);
+  for (const entityName in config.entities) {
+    const base = `/${pluralize2(entityName)}`;
+    const zodSchema = entityToZod(config.entities[entityName].fields);
+    const entityFields = config.entities[entityName].fields;
+    app.get(base, (req, reply) => {
+      const query = req.query;
+      const page = query.page ? Number(query.page) : void 0;
+      const limit = query.limit ? Number(query.limit) : void 0;
+      const sort = query.sort;
+      const order = query.order === "desc" ? "desc" : "asc";
+      const search = query.search;
+      const reserved = /* @__PURE__ */ new Set(["page", "limit", "sort", "order", "include", "search"]);
+      const filter = {};
+      for (const [k, v] of Object.entries(query)) {
+        if (!reserved.has(k)) filter[k] = v;
+      }
+      const result = db.list(entityName, {
+        page,
+        limit,
+        sort,
+        order,
+        search,
+        filter: Object.keys(filter).length ? filter : void 0
+      });
+      reply.header("X-Total-Count", String(result.meta.total));
+      return result;
+    });
+    app.get(`${base}/:id`, (req, reply) => {
+      const item = db.get(entityName, req.params.id);
+      if (!item) return reply.code(404).send({ error: "Not found" });
+      const include = req.query.include;
+      if (!include) return item;
+      const result = { ...item };
+      for (const fieldName of include.split(",").map((s) => s.trim())) {
+        const fieldDef = entityFields[fieldName];
+        if (!fieldDef) continue;
+        if (fieldDef.type === "belongsTo" && fieldDef.rules.entity) {
+          result[fieldName] = db.get(fieldDef.rules.entity, item[fieldName]) ?? null;
+        } else if (fieldDef.type === "hasMany" && fieldDef.rules.entity) {
+          result[fieldName] = (item[fieldName] ?? []).map((id) => db.get(fieldDef.rules.entity, id)).filter(Boolean);
+        }
+      }
+      return result;
+    });
+    app.post(base, (req, reply) => {
+      const result = zodSchema.safeParse(req.body);
+      if (!result.success)
+        return reply.code(422).send({ error: "Validation failed", issues: result.error.issues });
+      return reply.code(201).send(db.create(entityName, result.data));
+    });
+    app.put(`${base}/:id`, (req, reply) => {
+      const result = zodSchema.safeParse(req.body);
+      if (!result.success)
+        return reply.code(422).send({ error: "Validation failed", issues: result.error.issues });
+      const item = db.update(entityName, req.params.id, result.data);
+      if (!item) return reply.code(404).send({ error: "Not found" });
+      return item;
+    });
+    app.patch(`${base}/:id`, (req, reply) => {
+      const result = zodSchema.partial().safeParse(req.body);
+      if (!result.success)
+        return reply.code(422).send({ error: "Validation failed", issues: result.error.issues });
+      const item = db.update(entityName, req.params.id, result.data);
+      if (!item) return reply.code(404).send({ error: "Not found" });
+      return item;
+    });
+    app.delete(`${base}/:id`, (req, reply) => {
+      const ok = db.remove(entityName, req.params.id);
+      if (!ok) return reply.code(404).send({ error: "Not found" });
+      return { success: true };
+    });
+  }
+  app.post("/__reset", () => {
+    db.reset();
+    return { success: true, message: "Data reset to seed state" };
+  });
+  app.get("/openapi.json", () => openApiSpec);
+  await app.listen({ port, host: "0.0.0.0" });
+  const entityRows = Object.keys(config.entities).map((name) => {
+    const count = db.count(name);
+    const url = `http://localhost:${port}/${pluralize2(name)}`;
+    return `  ${c.gray}\u2192${c.reset} ${name.padEnd(16)} ${c.gray}${String(count).padStart(3)} records${c.reset}   ${c.cyan}${url}${c.reset}`;
+  }).join("\n");
+  const delayInfo = delayConfig !== void 0 ? Array.isArray(delayConfig) ? `  ${c.gray}delay: ${delayConfig[0]}\u2013${delayConfig[1]}ms${c.reset}
+` : `  ${c.gray}delay: ${delayConfig}ms${c.reset}
+` : "";
+  console.log(
+    `
+  ${c.bold}FFA dev server${c.reset}  ${c.gray}v0.6.0${c.reset}
+
+${entityRows}
+
+${delayInfo}  ${c.gray}\u2192${c.reset} Swagger UI   ${c.cyan}http://localhost:${port}/docs${c.reset}
+`
+  );
+  return { app, port };
+}
+async function restartServer(portOverride) {
+  if (currentApp) {
+    await currentApp.close();
+    currentApp = null;
+  }
+  return startServer(portOverride);
+}
+
+// src/cli.ts
+var program = new Command();
+program.command("dev").description("Start FFA dev server").option("-p, --port <port>", "override server port").option("-w, --watch", "watch ffa.config.ts for changes and restart").option("-o, --open", "open Swagger UI in browser on start").action(async (opts) => {
+  const portOverride = opts.port ? Number(opts.port) : void 0;
+  const { port } = await startServer(portOverride);
+  if (opts.open) {
+    const url = `http://localhost:${port}/docs`;
+    const cmd = process.platform === "win32" ? `start "" "${url}"` : process.platform === "darwin" ? `open "${url}"` : `xdg-open "${url}"`;
+    exec(cmd);
+  }
+  if (opts.watch) {
+    const chokidar = await import("chokidar");
+    const configPath = process.cwd() + "/ffa.config.ts";
+    const watcher = chokidar.watch(configPath, { ignoreInitial: true });
+    watcher.on("change", async () => {
+      console.log("\n  [watch] ffa.config.ts changed \u2014 restarting...");
+      try {
+        await restartServer(portOverride);
+      } catch (err) {
+        console.error("  [watch] Restart failed:", err);
+      }
+    });
+    console.log("  [watch] Watching ffa.config.ts...\n");
+  }
+});
+program.command("init").description("Create ffa.config.ts in the current directory").action(() => {
+  const tsPath = resolve(process.cwd(), "ffa.config.ts");
+  if (existsSync3(tsPath)) {
+    console.log("  ffa.config.ts already exists!");
+    process.exit(1);
+  }
+  const template = `import { defineConfig, entity, string, number, boolean, enumField } from 'ffa-core'
+
+export default defineConfig({
+  server: { port: 3333 },
+  entities: {
+    Post: entity({
+      title: string().required(),
+      body: string().required(),
+      status: enumField(['draft', 'published', 'archived']).required(),
+      published: boolean().required(),
+    }),
+  },
+})
+`;
+  writeFileSync2(tsPath, template, "utf-8");
+  console.log("  ffa.config.ts created! Run: ffa dev");
+});
+program.command("reset").description("Delete persisted data file (ffa-data.json)").action(() => {
+  const dataPath = resolve(process.cwd(), "ffa-data.json");
+  if (!existsSync3(dataPath)) {
+    console.log("  No ffa-data.json found. Nothing to reset.");
+    return;
+  }
+  unlinkSync(dataPath);
+  console.log("  ffa-data.json deleted. Restart the server to regenerate seed data.");
+});
+program.parse();

package/dist/index.d.ts

@@ -0,0 +1,64 @@
+type FieldType = 'string' | 'number' | 'boolean' | 'uuid' | 'datetime' | 'enum' | 'belongsTo' | 'hasMany';
+interface FieldRules {
+    required?: boolean;
+    min?: number;
+    max?: number;
+    default?: any;
+    readonly?: boolean;
+    entity?: string;
+    enumValues?: string[];
+}
+interface FieldDefinition {
+    type: FieldType;
+    rules: FieldRules;
+}
+interface EntityDefinition {
+    fields: Record<string, FieldDefinition>;
+    count?: number;
+}
+
+interface ServerConfig {
+    port: number;
+    cors?: boolean | {
+        origin: string | string[];
+    };
+    persist?: boolean | string;
+    delay?: number | [number, number];
+}
+interface FfaConfig {
+    server: ServerConfig;
+    entities: Record<string, EntityDefinition>;
+}
+declare function defineConfig(config: FfaConfig): FfaConfig;
+
+declare function entity(fields: Record<string, any>, options?: {
+    count?: number;
+}): {
+    fields: Record<string, any>;
+    count: number | undefined;
+};
+
+declare class FieldBuilder {
+    private def;
+    constructor(type: FieldType, extraRules?: Partial<FieldRules>);
+    required(): this;
+    optional(): this;
+    min(value: number): this;
+    max(value: number): this;
+    default(value: any): this;
+    readonly(): this;
+    build(): FieldDefinition;
+}
+
+declare const string: () => FieldBuilder;
+declare const number: () => FieldBuilder;
+declare const boolean: () => FieldBuilder;
+declare const uuid: () => FieldBuilder;
+declare const datetime: () => FieldBuilder;
+declare const enumField: (values: [string, ...string[]]) => FieldBuilder;
+declare const belongsTo: (entity: string) => FieldBuilder;
+declare const hasMany: (entity: string) => FieldBuilder;
+
+declare const __ffa_version = "0.6.0";
+
+export { type FfaConfig, __ffa_version, belongsTo, boolean, datetime, defineConfig, entity, enumField, hasMany, number, string, uuid };

package/dist/index.js

@@ -0,0 +1,84 @@
+// src/config/defineConfig.ts
+function defineConfig(config) {
+  return {
+    server: config.server ?? { port: 3e3 },
+    entities: config.entities ?? {}
+  };
+}
+
+// src/entity/entity.ts
+function entity(fields, options) {
+  const builtFields = {};
+  for (const [key, value] of Object.entries(fields)) {
+    builtFields[key] = value.build();
+  }
+  return {
+    fields: builtFields,
+    count: options?.count
+  };
+}
+
+// src/field/FieldBuilder.ts
+var FieldBuilder = class {
+  def;
+  constructor(type, extraRules) {
+    this.def = {
+      type,
+      rules: { ...extraRules }
+    };
+  }
+  required() {
+    this.def.rules.required = true;
+    return this;
+  }
+  optional() {
+    this.def.rules.required = false;
+    return this;
+  }
+  min(value) {
+    this.def.rules.min = value;
+    return this;
+  }
+  max(value) {
+    this.def.rules.max = value;
+    return this;
+  }
+  default(value) {
+    this.def.rules.default = value;
+    return this;
+  }
+  readonly() {
+    this.def.rules.readonly = true;
+    return this;
+  }
+  build() {
+    return structuredClone(this.def);
+  }
+};
+
+// src/field/factories.ts
+var string = () => new FieldBuilder("string");
+var number = () => new FieldBuilder("number");
+var boolean = () => new FieldBuilder("boolean");
+var uuid = () => new FieldBuilder("uuid");
+var datetime = () => new FieldBuilder("datetime");
+var enumField = (values) => new FieldBuilder("enum", { enumValues: values });
+var belongsTo = (entity2) => new FieldBuilder("belongsTo", { entity: entity2 });
+var hasMany = (entity2) => new FieldBuilder("hasMany", { entity: entity2 });
+
+// src/index.ts
+var __ffa_version = "0.6.0";
+export {
+  __ffa_version,
+  belongsTo,
+  boolean,
+  datetime,
+  defineConfig,
+  entity,
+  enumField,
+  hasMany,
+  number,
+  string,
+  uuid
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/config/defineConfig.ts","../src/entity/entity.ts","../src/field/FieldBuilder.ts","../src/field/factories.ts","../src/index.ts"],"sourcesContent":["import type { EntityDefinition } from '../field/types'\n\nexport interface ServerConfig {\n  port: number\n  cors?: boolean | { origin: string | string[] }\n  persist?: boolean | string\n  delay?: number | [number, number]\n}\n\nexport interface FfaConfig {\n  server: ServerConfig\n  entities: Record<string, EntityDefinition>\n}\n\nexport function defineConfig(config: FfaConfig): FfaConfig {\n  return {\n    server: config.server ?? { port: 3000 },\n    entities: config.entities ?? {},\n  }\n}\n","// src/entity/entity.ts\nexport function entity(fields: Record<string, any>, options?: { count?: number }) {\n  const builtFields: Record<string, any> = {}\n\n  for (const [key, value] of Object.entries(fields)) {\n    builtFields[key] = value.build()\n  }\n\n  return {\n    fields: builtFields,\n    count: options?.count,\n  }\n}\n","import { FieldDefinition, FieldRules, FieldType } from './types'\n\nexport class FieldBuilder {\n  private def: FieldDefinition\n\n  constructor(type: FieldType, extraRules?: Partial<FieldRules>) {\n    this.def = {\n      type,\n      rules: { ...extraRules },\n    }\n  }\n\n  required() {\n    this.def.rules.required = true\n    return this\n  }\n\n  optional() {\n    this.def.rules.required = false\n    return this\n  }\n\n  min(value: number) {\n    this.def.rules.min = value\n    return this\n  }\n\n  max(value: number) {\n    this.def.rules.max = value\n    return this\n  }\n\n  default(value: any) {\n    this.def.rules.default = value\n    return this\n  }\n\n  readonly() {\n    this.def.rules.readonly = true\n    return this\n  }\n\n  build(): FieldDefinition {\n    return structuredClone(this.def)\n  }\n}\n","import { FieldBuilder } from './FieldBuilder'\n\nexport const string = () => new FieldBuilder('string')\nexport const number = () => new FieldBuilder('number')\nexport const boolean = () => new FieldBuilder('boolean')\nexport const uuid = () => new FieldBuilder('uuid')\nexport const datetime = () => new FieldBuilder('datetime')\nexport const enumField = (values: [string, ...string[]]) => new FieldBuilder('enum', { enumValues: values })\nexport const belongsTo = (entity: string) => new FieldBuilder('belongsTo', { entity })\nexport const hasMany = (entity: string) => new FieldBuilder('hasMany', { entity })\n","// config\nexport { defineConfig } from './config/defineConfig'\nexport type { FfaConfig } from './config/defineConfig'\n\n// entity\nexport { entity } from './entity/entity'\n\n// field DSL\nexport { string, number, boolean, uuid, datetime, enumField, belongsTo, hasMany } from './field/factories'\n\nexport const __ffa_version = '0.6.0'\n"],"mappings":";AAcO,SAAS,aAAa,QAA8B;AACzD,SAAO;AAAA,IACL,QAAQ,OAAO,UAAU,EAAE,MAAM,IAAK;AAAA,IACtC,UAAU,OAAO,YAAY,CAAC;AAAA,EAChC;AACF;;;AClBO,SAAS,OAAO,QAA6B,SAA8B;AAChF,QAAM,cAAmC,CAAC;AAE1C,aAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,MAAM,GAAG;AACjD,gBAAY,GAAG,IAAI,MAAM,MAAM;AAAA,EACjC;AAEA,SAAO;AAAA,IACL,QAAQ;AAAA,IACR,OAAO,SAAS;AAAA,EAClB;AACF;;;ACVO,IAAM,eAAN,MAAmB;AAAA,EAChB;AAAA,EAER,YAAY,MAAiB,YAAkC;AAC7D,SAAK,MAAM;AAAA,MACT;AAAA,MACA,OAAO,EAAE,GAAG,WAAW;AAAA,IACzB;AAAA,EACF;AAAA,EAEA,WAAW;AACT,SAAK,IAAI,MAAM,WAAW;AAC1B,WAAO;AAAA,EACT;AAAA,EAEA,WAAW;AACT,SAAK,IAAI,MAAM,WAAW;AAC1B,WAAO;AAAA,EACT;AAAA,EAEA,IAAI,OAAe;AACjB,SAAK,IAAI,MAAM,MAAM;AACrB,WAAO;AAAA,EACT;AAAA,EAEA,IAAI,OAAe;AACjB,SAAK,IAAI,MAAM,MAAM;AACrB,WAAO;AAAA,EACT;AAAA,EAEA,QAAQ,OAAY;AAClB,SAAK,IAAI,MAAM,UAAU;AACzB,WAAO;AAAA,EACT;AAAA,EAEA,WAAW;AACT,SAAK,IAAI,MAAM,WAAW;AAC1B,WAAO;AAAA,EACT;AAAA,EAEA,QAAyB;AACvB,WAAO,gBAAgB,KAAK,GAAG;AAAA,EACjC;AACF;;;AC3CO,IAAM,SAAS,MAAM,IAAI,aAAa,QAAQ;AAC9C,IAAM,SAAS,MAAM,IAAI,aAAa,QAAQ;AAC9C,IAAM,UAAU,MAAM,IAAI,aAAa,SAAS;AAChD,IAAM,OAAO,MAAM,IAAI,aAAa,MAAM;AAC1C,IAAM,WAAW,MAAM,IAAI,aAAa,UAAU;AAClD,IAAM,YAAY,CAAC,WAAkC,IAAI,aAAa,QAAQ,EAAE,YAAY,OAAO,CAAC;AACpG,IAAM,YAAY,CAACA,YAAmB,IAAI,aAAa,aAAa,EAAE,QAAAA,QAAO,CAAC;AAC9E,IAAM,UAAU,CAACA,YAAmB,IAAI,aAAa,WAAW,EAAE,QAAAA,QAAO,CAAC;;;ACC1E,IAAM,gBAAgB;","names":["entity"]}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@koltakov/ffa-core",
+  "version": "0.6.0",
+  "description": "Instant mock REST API for frontend development",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "ffa": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsx src/cli.ts",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run typecheck && npm run build"
+  },
+  "keywords": [
+    "mock",
+    "api",
+    "fake",
+    "rest",
+    "faker",
+    "frontend",
+    "development",
+    "cli",
+    "scaffold",
+    "prototype"
+  ],
+  "author": "IgorKoltakov",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/IgorKoltakov/ffa-core.git"
+  },
+  "bugs": {
+    "url": "https://github.com/IgorKoltakov/ffa-core/issues"
+  },
+  "homepage": "https://github.com/IgorKoltakov/ffa-core#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@faker-js/faker": "^10.3.0",
+    "@fastify/cors": "^11.2.0",
+    "@fastify/swagger": "^9.7.0",
+    "@fastify/swagger-ui": "^5.2.5",
+    "chokidar": "^5.0.0",
+    "commander": "^14.0.3",
+    "fastify": "^5.7.4",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/chokidar": "^1.7.5",
+    "@types/node": "^25.3.3",
+    "tsup": "^8.0.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  }
+}