phantomback 1.0.0

package/src/cli/commands.js

@@ -0,0 +1,138 @@
+import { writeFileSync, existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { logger } from '../utils/logger.js';
+
+/**
+ * CLI command: phantomback init
+ * Generates a starter phantom.config.js in the CWD
+ */
+export async function initCommand() {
+  const configPath = resolve(process.cwd(), 'phantom.config.js');
+
+  if (existsSync(configPath)) {
+    logger.warn('phantom.config.js already exists. Skipping.');
+    return;
+  }
+
+  const template = `// PhantomBack Configuration
+// Docs: https://github.com/phantomback/phantomback
+
+export default {
+  port: 3777,
+  prefix: '/api',
+
+  // Global response latency (ms). Use [min, max] for random range.
+  // latency: 0,
+  // latency: [200, 800],
+
+  auth: {
+    enabled: true,
+    secret: 'my-super-secret-key',
+    expiresIn: '24h',
+  },
+
+  resources: {
+    users: {
+      fields: {
+        name: { type: 'name', required: true },
+        email: { type: 'email', unique: true },
+        username: { type: 'username' },
+        avatar: { type: 'avatar' },
+        age: { type: 'number', min: 18, max: 65 },
+        role: { type: 'enum', values: ['admin', 'user', 'moderator'] },
+      },
+      seed: 25,     // Auto-generate 25 fake records
+      auth: true,   // Protect CRUD with JWT token
+    },
+
+    posts: {
+      fields: {
+        title: { type: 'title', required: true },
+        body: { type: 'paragraphs', count: 3 },
+        slug: { type: 'slug' },
+        image: { type: 'image' },
+        published: { type: 'boolean' },
+        views: { type: 'number', min: 0, max: 10000 },
+        userId: { type: 'relation', resource: 'users' },
+      },
+      seed: 50,
+    },
+
+    comments: {
+      fields: {
+        body: { type: 'paragraph', required: true },
+        rating: { type: 'rating' },
+        userId: { type: 'relation', resource: 'users' },
+        postId: { type: 'relation', resource: 'posts' },
+      },
+      seed: 100,
+    },
+  },
+
+  // Chaos Engineering (Reality Mode) — Phase 2
+  // chaos: {
+  //   enabled: true,
+  //   jitter: { min: 100, max: 3000 },
+  //   failureRate: 0.1,
+  //   duplicateRate: 0.05,
+  //   connectionDropRate: 0.02,
+  // },
+};
+`;
+
+  writeFileSync(configPath, template, 'utf-8');
+  logger.success(`Created ${configPath}`);
+  logger.info('Edit the file to define your resources, then run: phantomback start');
+}
+
+/**
+ * CLI command: phantomback start
+ */
+export async function startCommand(options) {
+  const { parseConfig } = await import('../schema/parser.js');
+  const { DEFAULT_RESOURCES } = await import('../schema/defaults.js');
+  const { createServer } = await import('../server/createServer.js');
+
+  logger.banner();
+
+  let config;
+
+  if (options.zero) {
+    logger.info('Zero-config mode: generating demo backend...');
+    config = await parseConfig({
+      port: options.port || 3777,
+      prefix: options.prefix || '/api',
+      resources: DEFAULT_RESOURCES,
+    });
+  } else if (options.config) {
+    config = await parseConfig(options.config);
+  } else {
+    config = await parseConfig(); // auto-find config file
+  }
+
+  // CLI overrides
+  if (options.port) config.port = parseInt(options.port, 10);
+  if (options.prefix) config.prefix = options.prefix;
+
+  // Check if using defaults (no config found and no resources)
+  if (Object.keys(config.resources).length === 0) {
+    logger.warn('No config found and no resources defined. Using zero-config defaults.');
+    config.resources = DEFAULT_RESOURCES;
+  }
+
+  logger.table(config.resources);
+
+  const { stop } = await createServer(config);
+
+  logger.server(config.port);
+
+  // Graceful shutdown
+  const shutdown = async () => {
+    logger.info('Shutting down...');
+    await stop();
+    process.exit(0);
+  };
+
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+}

package/src/data/relations.js

@@ -0,0 +1,59 @@
+/**
+ * Detect and build relation metadata between resources.
+ * Used for auto-generating nested routes like GET /users/:id/posts
+ */
+export function detectRelations(resources) {
+  const relations = {};
+
+  for (const [resourceName, schema] of Object.entries(resources)) {
+    const fields = schema.fields || {};
+
+    for (const [fieldName, fieldDef] of Object.entries(fields)) {
+      const def = typeof fieldDef === 'string' ? { type: fieldDef } : fieldDef;
+
+      if (def.type === 'relation' && def.resource) {
+        // This resource has a foreign key to def.resource
+        // e.g., posts.userId → users
+        if (!relations[def.resource]) {
+          relations[def.resource] = [];
+        }
+
+        relations[def.resource].push({
+          childResource: resourceName,
+          foreignKey: fieldName,
+          parentResource: def.resource,
+        });
+
+        // Also store on the child side
+        if (!relations[resourceName]) {
+          relations[resourceName] = [];
+        }
+
+        relations[resourceName].push({
+          parentResource: def.resource,
+          foreignKey: fieldName,
+          childResource: resourceName,
+          direction: 'belongsTo',
+        });
+      }
+    }
+  }
+
+  return relations;
+}
+
+/**
+ * Get child resources for a parent (for nested routes)
+ */
+export function getChildren(resourceName, relations) {
+  if (!relations[resourceName]) return [];
+  return relations[resourceName].filter((r) => r.childResource !== resourceName || !r.direction);
+}
+
+/**
+ * Get parent resources for a child (for nested routes)
+ */
+export function getParents(resourceName, relations) {
+  if (!relations[resourceName]) return [];
+  return relations[resourceName].filter((r) => r.direction === 'belongsTo');
+}

package/src/data/seeder.js

@@ -0,0 +1,190 @@
+import { faker } from '@faker-js/faker';
+import { generateId } from '../utils/helpers.js';
+
+/**
+ * Map of schema field types → Faker generators
+ */
+const FIELD_GENERATORS = {
+  // People
+  name: () => faker.person.fullName(),
+  firstName: () => faker.person.firstName(),
+  lastName: () => faker.person.lastName(),
+  username: () => faker.internet.username(),
+  email: () => faker.internet.email(),
+  avatar: () => faker.image.avatar(),
+  bio: () => faker.person.bio(),
+  jobTitle: () => faker.person.jobTitle(),
+  phone: () => faker.phone.number(),
+
+  // Text
+  word: () => faker.lorem.word(),
+  sentence: () => faker.lorem.sentence(),
+  paragraph: () => faker.lorem.paragraph(),
+  paragraphs: (opts) => faker.lorem.paragraphs(opts?.count || 3),
+  slug: () => faker.lorem.slug(),
+  title: () => faker.lorem.sentence({ min: 3, max: 8 }),
+  description: () => faker.lorem.sentences({ min: 2, max: 4 }),
+  text: () => faker.lorem.text(),
+
+  // Numbers
+  number: (opts) => faker.number.int({ min: opts?.min ?? 0, max: opts?.max ?? 1000 }),
+  float: (opts) =>
+    faker.number.float({
+      min: opts?.min ?? 0,
+      max: opts?.max ?? 1000,
+      fractionDigits: opts?.precision ?? 2,
+    }),
+  price: () => faker.commerce.price({ min: 1, max: 500, dec: 2 }),
+  rating: () => faker.number.float({ min: 1, max: 5, fractionDigits: 1 }),
+
+  // Boolean
+  boolean: () => faker.datatype.boolean(),
+
+  // Dates
+  date: () => faker.date.recent({ days: 365 }).toISOString(),
+  pastDate: () => faker.date.past().toISOString(),
+  futureDate: () => faker.date.future().toISOString(),
+  birthdate: () => faker.date.birthdate().toISOString().split('T')[0],
+
+  // Internet
+  url: () => faker.internet.url(),
+  image: () => faker.image.url(),
+  ip: () => faker.internet.ip(),
+  color: () => faker.color.human(),
+  hex: () => faker.color.rgb(),
+
+  // Address
+  address: () => faker.location.streetAddress(),
+  city: () => faker.location.city(),
+  country: () => faker.location.country(),
+  zipCode: () => faker.location.zipCode(),
+  latitude: () => faker.location.latitude(),
+  longitude: () => faker.location.longitude(),
+
+  // Commerce
+  product: () => faker.commerce.productName(),
+  company: () => faker.company.name(),
+  department: () => faker.commerce.department(),
+  category: () => faker.commerce.department(),
+
+  // IDs
+  uuid: () => faker.string.uuid(),
+  id: () => generateId(),
+
+  // Enum
+  enum: (opts) => {
+    if (!opts?.values || !opts.values.length) return null;
+    return faker.helpers.arrayElement(opts.values);
+  },
+
+  // Array
+  array: (opts) => {
+    const count = opts?.count || faker.number.int({ min: 1, max: 5 });
+    const itemType = opts?.items || 'word';
+    const generator = FIELD_GENERATORS[itemType];
+    if (!generator) return [];
+    return Array.from({ length: count }, () => generator(opts));
+  },
+
+  // Object (nested)
+  object: (opts) => {
+    if (!opts?.fields) return {};
+    return generateRecord(opts.fields);
+  },
+
+  // Relation (foreign key) — handled separately by seeder
+  relation: () => null,
+};
+
+/**
+ * Generate a single field value from the schema definition
+ */
+export function generateFieldValue(fieldDef) {
+  // If fieldDef is a string, treat it as the type
+  const def = typeof fieldDef === 'string' ? { type: fieldDef } : fieldDef;
+  const generator = FIELD_GENERATORS[def.type];
+
+  if (!generator) {
+    // Fallback: if type matches a faker method path like "lorem.sentence"
+    return faker.lorem.word();
+  }
+
+  return generator(def);
+}
+
+/**
+ * Generate a single record from a fields schema
+ */
+export function generateRecord(fields) {
+  const record = {};
+  for (const [fieldName, fieldDef] of Object.entries(fields)) {
+    record[fieldName] = generateFieldValue(fieldDef);
+  }
+  return record;
+}
+
+/**
+ * Seed a resource with realistic fake data
+ */
+export function seedResource(resourceName, schema, store, _allResources = {}) {
+  const { fields, seed = 10 } = schema;
+  if (!fields || seed <= 0) return;
+
+  store.register(resourceName);
+
+  const records = [];
+  for (let i = 0; i < seed; i++) {
+    const record = generateRecord(fields);
+    records.push(record);
+  }
+
+  // Create all records first
+  const createdRecords = store.createMany(resourceName, records);
+
+  // Now resolve relations (foreign keys)
+  for (const [fieldName, fieldDef] of Object.entries(fields)) {
+    const def = typeof fieldDef === 'string' ? { type: fieldDef } : fieldDef;
+    if (def.type === 'relation' && def.resource) {
+      const relatedRecords = store.findAll(def.resource);
+      if (relatedRecords.length > 0) {
+        for (const record of createdRecords) {
+          const relatedRecord = faker.helpers.arrayElement(relatedRecords);
+          store.patch(resourceName, record.id, { [fieldName]: relatedRecord.id });
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Seed all resources respecting dependency order
+ */
+export function seedAll(resources, store) {
+  // First pass: find resources without relations (they get seeded first)
+  const withRelations = [];
+  const withoutRelations = [];
+
+  for (const [name, schema] of Object.entries(resources)) {
+    const fields = schema.fields || {};
+    const hasRelation = Object.values(fields).some((f) => {
+      const def = typeof f === 'string' ? { type: f } : f;
+      return def.type === 'relation';
+    });
+
+    if (hasRelation) {
+      withRelations.push([name, schema]);
+    } else {
+      withoutRelations.push([name, schema]);
+    }
+  }
+
+  // Seed independent resources first
+  for (const [name, schema] of withoutRelations) {
+    seedResource(name, schema, store, resources);
+  }
+
+  // Then seed dependent resources
+  for (const [name, schema] of withRelations) {
+    seedResource(name, schema, store, resources);
+  }
+}

package/src/data/store.js

@@ -0,0 +1,181 @@
+import { generateId, timestamp, deepClone } from '../utils/helpers.js';
+
+/**
+ * In-memory data store for all resources.
+ * Structure: Map<resourceName, Map<id, record>>
+ */
+export class DataStore {
+  constructor() {
+    /** @type {Map<string, Map<string, object>>} */
+    this.collections = new Map();
+  }
+
+  /**
+   * Initialize a collection for a resource
+   */
+  register(resourceName) {
+    if (!this.collections.has(resourceName)) {
+      this.collections.set(resourceName, new Map());
+    }
+    return this;
+  }
+
+  /**
+   * Get all records from a resource
+   */
+  findAll(resourceName) {
+    const collection = this.collections.get(resourceName);
+    if (!collection) return [];
+    return Array.from(collection.values()).map(deepClone);
+  }
+
+  /**
+   * Get a single record by ID
+   */
+  findById(resourceName, id) {
+    const collection = this.collections.get(resourceName);
+    if (!collection) return null;
+    const record = collection.get(id);
+    return record ? deepClone(record) : null;
+  }
+
+  /**
+   * Find records matching a filter function
+   */
+  findWhere(resourceName, filterFn) {
+    return this.findAll(resourceName).filter(filterFn);
+  }
+
+  /**
+   * Create a new record
+   */
+  create(resourceName, data) {
+    const collection = this.collections.get(resourceName);
+    if (!collection) {
+      throw new Error(`Resource "${resourceName}" is not registered.`);
+    }
+
+    const now = timestamp();
+    const record = {
+      id: data.id || generateId(),
+      ...data,
+      createdAt: now,
+      updatedAt: now,
+    };
+
+    collection.set(record.id, record);
+    return deepClone(record);
+  }
+
+  /**
+   * Bulk create records
+   */
+  createMany(resourceName, items) {
+    return items.map((item) => this.create(resourceName, item));
+  }
+
+  /**
+   * Update a record (full replace, keeps id + timestamps)
+   */
+  update(resourceName, id, data) {
+    const collection = this.collections.get(resourceName);
+    if (!collection) return null;
+
+    const existing = collection.get(id);
+    if (!existing) return null;
+
+    const updated = {
+      ...data,
+      id,
+      createdAt: existing.createdAt,
+      updatedAt: timestamp(),
+    };
+
+    collection.set(id, updated);
+    return deepClone(updated);
+  }
+
+  /**
+   * Partial update a record (merge)
+   */
+  patch(resourceName, id, data) {
+    const collection = this.collections.get(resourceName);
+    if (!collection) return null;
+
+    const existing = collection.get(id);
+    if (!existing) return null;
+
+    const patched = {
+      ...existing,
+      ...data,
+      id, // prevent id override
+      createdAt: existing.createdAt,
+      updatedAt: timestamp(),
+    };
+
+    collection.set(id, patched);
+    return deepClone(patched);
+  }
+
+  /**
+   * Delete a record
+   */
+  delete(resourceName, id) {
+    const collection = this.collections.get(resourceName);
+    if (!collection) return false;
+    return collection.delete(id);
+  }
+
+  /**
+   * Count records in a resource
+   */
+  count(resourceName) {
+    const collection = this.collections.get(resourceName);
+    return collection ? collection.size : 0;
+  }
+
+  /**
+   * Clear all records from a resource
+   */
+  clear(resourceName) {
+    const collection = this.collections.get(resourceName);
+    if (collection) collection.clear();
+    return this;
+  }
+
+  /**
+   * Reset the entire store
+   */
+  reset() {
+    this.collections.clear();
+    return this;
+  }
+
+  /**
+   * Export the entire store as a plain object (for snapshots)
+   */
+  toJSON() {
+    const result = {};
+    for (const [name, collection] of this.collections) {
+      result[name] = Array.from(collection.values());
+    }
+    return result;
+  }
+
+  /**
+   * Import data from a plain object (restore snapshot)
+   */
+  fromJSON(data) {
+    for (const [name, records] of Object.entries(data)) {
+      this.register(name);
+      const collection = this.collections.get(name);
+      for (const record of records) {
+        collection.set(record.id, record);
+      }
+    }
+    return this;
+  }
+}
+
+// Singleton store instance
+export const store = new DataStore();

package/src/features/auth.js

@@ -0,0 +1,123 @@
+import jwt from 'jsonwebtoken';
+import { sendError, sendResponse, asyncHandler } from '../utils/helpers.js';
+
+const DEFAULT_SECRET = 'phantomback-secret-key';
+const DEFAULT_EXPIRES_IN = '24h';
+
+/**
+ * Create auth routes (login, register)
+ */
+export function createAuthRoutes(router, store, config) {
+  const secret = config.auth?.secret || DEFAULT_SECRET;
+  const expiresIn = config.auth?.expiresIn || DEFAULT_EXPIRES_IN;
+
+  // POST /api/auth/register
+  router.post(
+    `${config.prefix}/auth/register`,
+    asyncHandler(async (req, res) => {
+      const { email, password, ...rest } = req.body;
+
+      if (!email || !password) {
+        return sendError(res, 400, 'Email and password are required');
+      }
+
+      // Check if user already exists
+      const existing = store.findAll('users').find((u) => u.email === email);
+
+      if (existing) {
+        return sendError(res, 409, 'User with this email already exists');
+      }
+
+      // Create user (password is stored but this is a fake backend)
+      const user = store.create('users', {
+        email,
+        password, // In a real app, this would be hashed
+        ...rest,
+      });
+
+      const token = jwt.sign({ id: user.id, email: user.email }, secret, { expiresIn });
+
+      return sendResponse(res, 201, {
+        user: { ...user, password: undefined },
+        token,
+      });
+    }),
+  );
+
+  // POST /api/auth/login
+  router.post(
+    `${config.prefix}/auth/login`,
+    asyncHandler(async (req, res) => {
+      const { email, password } = req.body;
+
+      if (!email) {
+        return sendError(res, 400, 'Email is required');
+      }
+
+      // Find user by email
+      const user = store.findAll('users').find((u) => u.email === email);
+
+      if (!user) {
+        return sendError(res, 401, 'Invalid credentials');
+      }
+
+      // In phantom mode, any password works if user exists
+      // But if a password was set during registration, check it
+      if (user.password && password && user.password !== password) {
+        return sendError(res, 401, 'Invalid credentials');
+      }
+
+      const token = jwt.sign({ id: user.id, email: user.email }, secret, { expiresIn });
+
+      return sendResponse(res, 200, {
+        user: { ...user, password: undefined },
+        token,
+      });
+    }),
+  );
+
+  // GET /api/auth/me — get current user from token
+  router.get(
+    `${config.prefix}/auth/me`,
+    authMiddleware(secret),
+    asyncHandler(async (req, res) => {
+      const user = store.findById('users', req.user.id);
+      if (!user) {
+        return sendError(res, 404, 'User not found');
+      }
+      return sendResponse(res, 200, { ...user, password: undefined });
+    }),
+  );
+}
+
+/**
+ * Auth middleware — verifies JWT token
+ */
+export function authMiddleware(secret) {
+  return (req, res, next) => {
+    const authHeader = req.headers.authorization;
+
+    if (!authHeader) {
+      return sendError(res, 401, 'Authorization header is required. Use: Bearer <token>');
+    }
+
+    const parts = authHeader.split(' ');
+    if (parts.length !== 2 || parts[0] !== 'Bearer') {
+      return sendError(res, 401, 'Invalid authorization format. Use: Bearer <token>');
+    }
+
+    const token = parts[1];
+
+    try {
+      const secret_key = secret || DEFAULT_SECRET;
+      const decoded = jwt.verify(token, secret_key);
+      req.user = decoded;
+      next();
+    } catch (err) {
+      if (err.name === 'TokenExpiredError') {
+        return sendError(res, 401, 'Token has expired');
+      }
+      return sendError(res, 401, 'Invalid token');
+    }
+  };
+}