phantomback 1.0.0

package/src/features/delay.js

@@ -0,0 +1,40 @@
+/**
+ * Response delay middleware.
+ *
+ * Adds configurable latency to simulate slow networks.
+ *
+ * Config:
+ *   latency: 500            → fixed 500ms delay
+ *   latency: [200, 1000]    → random delay between 200-1000ms
+ *   latency: { min: 200, max: 1000 }
+ */
+export function delayMiddleware(latency) {
+  if (!latency) return (_req, _res, next) => next();
+
+  return (_req, _res, next) => {
+    const ms = calculateDelay(latency);
+    if (ms <= 0) return next();
+    setTimeout(next, ms);
+  };
+}
+
+/**
+ * Calculate delay in ms from various config formats
+ */
+function calculateDelay(latency) {
+  if (typeof latency === 'number') {
+    return latency;
+  }
+
+  if (Array.isArray(latency) && latency.length === 2) {
+    const [min, max] = latency;
+    return Math.floor(Math.random() * (max - min + 1)) + min;
+  }
+
+  if (typeof latency === 'object' && latency.min !== undefined && latency.max !== undefined) {
+    const { min, max } = latency;
+    return Math.floor(Math.random() * (max - min + 1)) + min;
+  }
+
+  return 0;
+}

package/src/features/filters.js

@@ -0,0 +1,84 @@
+import { parseValue } from '../utils/helpers.js';
+
+/**
+ * Filter records by query parameters.
+ *
+ * Supports:
+ *   ?field=value          → exact match
+ *   ?field_gte=10         → greater than or equal
+ *   ?field_lte=100        → less than or equal
+ *   ?field_gt=10          → greater than
+ *   ?field_lt=100         → less than
+ *   ?field_ne=value       → not equal
+ *   ?field_like=text      → contains (case-insensitive)
+ */
+const RESERVED_PARAMS = new Set([
+  'page',
+  '_page',
+  'limit',
+  '_limit',
+  'per_page',
+  'offset',
+  'sort',
+  '_sort',
+  'order',
+  '_order',
+  'q',
+  '_q',
+  'search',
+  'fields',
+  '_fields',
+  'select',
+  '_embed',
+  '_expand',
+]);
+
+const OPERATORS = ['_gte', '_lte', '_gt', '_lt', '_ne', '_like'];
+
+export function applyFilters(records, query) {
+  let filtered = [...records];
+
+  for (const [key, rawValue] of Object.entries(query)) {
+    if (RESERVED_PARAMS.has(key)) continue;
+
+    // Check for operator suffix
+    let fieldName = key;
+    let operator = 'eq';
+
+    for (const op of OPERATORS) {
+      if (key.endsWith(op)) {
+        fieldName = key.slice(0, -op.length);
+        operator = op.slice(1); // remove leading _
+        break;
+      }
+    }
+
+    const value = parseValue(rawValue);
+
+    filtered = filtered.filter((record) => {
+      const fieldValue = record[fieldName];
+      if (fieldValue === undefined) return true;
+
+      switch (operator) {
+        case 'eq':
+          return fieldValue == value; // loose equality intentional for string/number matching
+        case 'ne':
+          return fieldValue != value;
+        case 'gt':
+          return fieldValue > value;
+        case 'gte':
+          return fieldValue >= value;
+        case 'lt':
+          return fieldValue < value;
+        case 'lte':
+          return fieldValue <= value;
+        case 'like':
+          return String(fieldValue).toLowerCase().includes(String(value).toLowerCase());
+        default:
+          return true;
+      }
+    });
+  }
+
+  return filtered;
+}

package/src/features/pagination.js

@@ -0,0 +1,38 @@
+/**
+ * Apply pagination to a list of records.
+ *
+ * Query params:
+ *   ?page=1&limit=10
+ *   ?_page=1&_limit=10
+ *   ?offset=0&limit=10
+ */
+export function paginate(records, query) {
+  const page = parseInt(query.page || query._page, 10) || 1;
+  const limit = parseInt(query.limit || query._limit || query.per_page, 10) || 10;
+  const offset = parseInt(query.offset, 10);
+
+  const total = records.length;
+  const totalPages = Math.ceil(total / limit);
+
+  let start;
+  if (!isNaN(offset)) {
+    start = offset;
+  } else {
+    start = (page - 1) * limit;
+  }
+
+  const end = start + limit;
+  const data = records.slice(start, end);
+
+  return {
+    data,
+    meta: {
+      page,
+      limit,
+      total,
+      totalPages,
+      hasNext: page < totalPages,
+      hasPrev: page > 1,
+    },
+  };
+}

package/src/features/search.js

@@ -0,0 +1,18 @@
+import { matchesSearch } from '../utils/helpers.js';
+
+/**
+ * Full-text search across all string fields.
+ *
+ * Query params:
+ *   ?q=search+term
+ *   ?_q=search+term
+ *   ?search=search+term
+ */
+export function applySearch(records, query) {
+  const searchTerm = query.q || query._q || query.search;
+  if (!searchTerm) return records;
+
+  return records.filter((record) => {
+    return Object.values(record).some((value) => matchesSearch(value, searchTerm));
+  });
+}

package/src/features/sorting.js

@@ -0,0 +1,47 @@
+/**
+ * Sort records by field and order.
+ *
+ * Query params:
+ *   ?sort=name&order=asc
+ *   ?_sort=name&_order=desc
+ *   ?sort=name,-age   (multi-field: comma-separated, prefix - for desc)
+ */
+export function applySort(records, query) {
+  const sortParam = query.sort || query._sort;
+  if (!sortParam) return records;
+
+  const orderParam = (query.order || query._order || 'asc').toLowerCase();
+
+  // Support multi-field sort: "name,-age,createdAt"
+  const sortFields = sortParam.split(',').map((field) => {
+    field = field.trim();
+    if (field.startsWith('-')) {
+      return { field: field.slice(1), order: 'desc' };
+    }
+    return { field, order: orderParam };
+  });
+
+  const sorted = [...records];
+  sorted.sort((a, b) => {
+    for (const { field, order } of sortFields) {
+      const valA = a[field];
+      const valB = b[field];
+
+      if (valA === valB) continue;
+      if (valA === undefined || valA === null) return 1;
+      if (valB === undefined || valB === null) return -1;
+
+      let comparison;
+      if (typeof valA === 'string' && typeof valB === 'string') {
+        comparison = valA.localeCompare(valB);
+      } else {
+        comparison = valA < valB ? -1 : 1;
+      }
+
+      return order === 'desc' ? -comparison : comparison;
+    }
+    return 0;
+  });
+
+  return sorted;
+}

package/src/index.js

@@ -0,0 +1,67 @@
+import { createServer } from './server/createServer.js';
+import { parseConfig } from './schema/parser.js';
+import { DEFAULT_RESOURCES } from './schema/defaults.js';
+import { logger } from './utils/logger.js';
+
+/**
+ * PhantomBack — Instant Fake Backend Generator
+ *
+ * Library API entry point.
+ *
+ * @example
+ * ```js
+ * import { createPhantom } from 'phantomback';
+ *
+ * const phantom = await createPhantom({
+ *   port: 3777,
+ *   resources: {
+ *     users: {
+ *       fields: {
+ *         name: { type: 'name', required: true },
+ *         email: { type: 'email', unique: true },
+ *       },
+ *       seed: 25,
+ *     },
+ *   },
+ * });
+ *
+ * // phantom.stop()   — stop the server
+ * // phantom.reset()  — reset & re-seed all data
+ * // phantom.getStore() — export current data as JSON
+ * ```
+ */
+export async function createPhantom(userConfig = {}) {
+  const config = await parseConfig(userConfig);
+
+  // If no resources defined, use defaults
+  if (Object.keys(config.resources).length === 0) {
+    config.resources = DEFAULT_RESOURCES;
+  }
+
+  logger.banner();
+  logger.table(config.resources);
+
+  const instance = await createServer(config);
+
+  logger.server(config.port);
+
+  return instance;
+}
+
+/**
+ * Create a zero-config phantom backend
+ * One line → full demo API
+ */
+export async function createPhantomZero(port = 3777) {
+  return createPhantom({
+    port,
+    resources: DEFAULT_RESOURCES,
+  });
+}
+
+// Named exports for advanced usage
+export { createServer } from './server/createServer.js';
+export { parseConfig } from './schema/parser.js';
+export { DEFAULT_RESOURCES } from './schema/defaults.js';
+export { DataStore } from './data/store.js';
+export { logger } from './utils/logger.js';

package/src/schema/defaults.js

@@ -0,0 +1,62 @@
+/**
+ * Default zero-config resources for PhantomBack
+ * Used when no config file is found or --zero flag is used
+ */
+export const DEFAULT_RESOURCES = {
+  users: {
+    fields: {
+      name: { type: 'name', required: true },
+      email: { type: 'email', unique: true },
+      username: { type: 'username' },
+      avatar: { type: 'avatar' },
+      bio: { type: 'bio' },
+      age: { type: 'number', min: 18, max: 65 },
+      role: { type: 'enum', values: ['admin', 'user', 'moderator'] },
+      isActive: { type: 'boolean' },
+    },
+    seed: 25,
+    auth: true,
+  },
+  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,
+  },
+  products: {
+    fields: {
+      name: { type: 'product', required: true },
+      description: { type: 'description' },
+      price: { type: 'price' },
+      category: { type: 'category' },
+      image: { type: 'image' },
+      inStock: { type: 'boolean' },
+      rating: { type: 'rating' },
+    },
+    seed: 30,
+  },
+  todos: {
+    fields: {
+      title: { type: 'sentence', required: true },
+      completed: { type: 'boolean' },
+      priority: { type: 'enum', values: ['low', 'medium', 'high'] },
+      userId: { type: 'relation', resource: 'users' },
+    },
+    seed: 40,
+  },
+};

package/src/schema/parser.js

@@ -0,0 +1,94 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+/**
+ * Default configuration
+ */
+export const DEFAULT_CONFIG = {
+  port: 3777,
+  prefix: '/api',
+  latency: 0,
+  auth: {
+    enabled: false,
+    secret: 'phantomback-secret-key',
+    expiresIn: '24h',
+  },
+  chaos: {
+    enabled: false,
+  },
+  resources: {},
+  snapshot: false,
+};
+
+/**
+ * Parse configuration from file or object
+ */
+export async function parseConfig(configPathOrObject) {
+  // If already an object, merge with defaults
+  if (configPathOrObject && typeof configPathOrObject === 'object') {
+    return mergeConfig(configPathOrObject);
+  }
+
+  // Try to find config file
+  const configPath = configPathOrObject || (await findConfigFile());
+
+  if (!configPath) {
+    return { ...DEFAULT_CONFIG };
+  }
+
+  const ext = configPath.split('.').pop();
+  let userConfig;
+
+  if (ext === 'json') {
+    const raw = readFileSync(configPath, 'utf-8');
+    userConfig = JSON.parse(raw);
+  } else if (ext === 'js' || ext === 'mjs') {
+    const fileUrl = pathToFileURL(resolve(configPath)).href;
+    const mod = await import(fileUrl);
+    userConfig = mod.default || mod;
+  } else {
+    throw new Error(`Unsupported config file format: .${ext}`);
+  }
+
+  return mergeConfig(userConfig);
+}
+
+/**
+ * Search for config file in CWD
+ */
+async function findConfigFile() {
+  const cwd = process.cwd();
+  const candidates = [
+    'phantom.config.js',
+    'phantom.config.mjs',
+    'phantom.config.json',
+    '.phantomrc.json',
+    '.phantomrc.js',
+  ];
+
+  for (const name of candidates) {
+    const fullPath = resolve(cwd, name);
+    if (existsSync(fullPath)) return fullPath;
+  }
+
+  return null;
+}
+
+/**
+ * Merge user config with defaults
+ */
+function mergeConfig(userConfig) {
+  return {
+    ...DEFAULT_CONFIG,
+    ...userConfig,
+    auth: {
+      ...DEFAULT_CONFIG.auth,
+      ...(userConfig.auth || {}),
+    },
+    chaos: {
+      ...DEFAULT_CONFIG.chaos,
+      ...(userConfig.chaos || {}),
+    },
+  };
+}

package/src/schema/validator.js

@@ -0,0 +1,153 @@
+import { sendError } from '../utils/helpers.js';
+
+/**
+ * Validate incoming request body against the resource schema fields
+ */
+export function validateBody(fields, body, isPartial = false) {
+  const errors = [];
+  const sanitized = {};
+
+  if (!body || typeof body !== 'object') {
+    return {
+      valid: false,
+      errors: [{ field: '_body', message: 'Request body must be a JSON object' }],
+      data: null,
+    };
+  }
+
+  for (const [fieldName, fieldDef] of Object.entries(fields)) {
+    const def = typeof fieldDef === 'string' ? { type: fieldDef } : fieldDef;
+    const value = body[fieldName];
+
+    // Skip relation fields — they're managed by the client directly
+    if (def.type === 'relation') {
+      if (value !== undefined) {
+        sanitized[fieldName] = value;
+      }
+      continue;
+    }
+
+    // Required check (only for full updates, not patches)
+    if (!isPartial && def.required && (value === undefined || value === null || value === '')) {
+      errors.push({ field: fieldName, message: `"${fieldName}" is required` });
+      continue;
+    }
+
+    // If not provided on partial update, skip
+    if (value === undefined) {
+      if (!isPartial) {
+        // For full creates, use whatever default the field has
+        sanitized[fieldName] = value;
+      }
+      continue;
+    }
+
+    // Type validation
+    const typeError = validateType(fieldName, value, def);
+    if (typeError) {
+      errors.push(typeError);
+      continue;
+    }
+
+    // Range validation
+    if (def.min !== undefined && typeof value === 'number' && value < def.min) {
+      errors.push({ field: fieldName, message: `"${fieldName}" must be at least ${def.min}` });
+      continue;
+    }
+    if (def.max !== undefined && typeof value === 'number' && value > def.max) {
+      errors.push({ field: fieldName, message: `"${fieldName}" must be at most ${def.max}` });
+      continue;
+    }
+
+    // Unique check is done at the route level (needs store access)
+
+    // Enum validation
+    if (def.type === 'enum' && def.values && !def.values.includes(value)) {
+      errors.push({
+        field: fieldName,
+        message: `"${fieldName}" must be one of: ${def.values.join(', ')}`,
+      });
+      continue;
+    }
+
+    // Email format
+    if (def.type === 'email' && !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)) {
+      errors.push({ field: fieldName, message: `"${fieldName}" must be a valid email address` });
+      continue;
+    }
+
+    sanitized[fieldName] = value;
+  }
+
+  // Allow extra fields not in schema (flexible mode)
+  for (const [key, value] of Object.entries(body)) {
+    if (!(key in fields) && key !== 'id' && key !== 'createdAt' && key !== 'updatedAt') {
+      sanitized[key] = value;
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    data: sanitized,
+  };
+}
+
+/**
+ * Validate a single field's type
+ */
+function validateType(fieldName, value, def) {
+  const type = def.type;
+
+  switch (type) {
+    case 'number':
+    case 'float':
+    case 'price':
+    case 'rating':
+      if (typeof value !== 'number') {
+        return { field: fieldName, message: `"${fieldName}" must be a number` };
+      }
+      break;
+
+    case 'boolean':
+      if (typeof value !== 'boolean') {
+        return { field: fieldName, message: `"${fieldName}" must be a boolean` };
+      }
+      break;
+
+    case 'array':
+      if (!Array.isArray(value)) {
+        return { field: fieldName, message: `"${fieldName}" must be an array` };
+      }
+      break;
+
+    case 'object':
+      if (typeof value !== 'object' || Array.isArray(value)) {
+        return { field: fieldName, message: `"${fieldName}" must be an object` };
+      }
+      break;
+
+    // String-like types — accept strings
+    default:
+      if (typeof value !== 'string' && typeof value !== 'number') {
+        return { field: fieldName, message: `"${fieldName}" must be a string` };
+      }
+      break;
+  }
+
+  return null;
+}
+
+/**
+ * Express middleware factory: validate request body
+ */
+export function validationMiddleware(fields, isPartial = false) {
+  return (req, res, next) => {
+    const { valid, errors, data } = validateBody(fields, req.body, isPartial);
+    if (!valid) {
+      return sendError(res, 400, 'Validation failed', errors);
+    }
+    req.validatedBody = data;
+    next();
+  };
+}

package/src/server/createServer.js

@@ -0,0 +1,57 @@
+import { createExpressApp, addErrorHandling } from './middleware.js';
+import { createRouter } from './router.js';
+import { createAuthRoutes } from '../features/auth.js';
+import { seedAll } from '../data/seeder.js';
+import { DataStore } from '../data/store.js';
+import { logger } from '../utils/logger.js';
+
+/**
+ * Create and start a PhantomBack server instance
+ *
+ * @param {object} config - Parsed configuration object
+ * @returns {{ app, server, store, stop, reset, getStore }}
+ */
+export async function createServer(config) {
+  const store = new DataStore();
+  const app = createExpressApp(config);
+
+  // Seed data
+  seedAll(config.resources, store);
+
+  // Register auth routes if any resource uses auth
+  const hasAuth = Object.values(config.resources).some((r) => r.auth);
+  if (hasAuth) {
+    createAuthRoutes(app, store, config);
+    logger.route('POST', `${config.prefix}/auth/register`);
+    logger.route('POST', `${config.prefix}/auth/login`);
+    logger.route('GET', `${config.prefix}/auth/me`);
+  }
+
+  // Register resource routes
+  const router = createRouter(config, store);
+  app.use(router);
+
+  // Error handling (must be last)
+  addErrorHandling(app);
+
+  // Start listening
+  const server = await new Promise((resolve) => {
+    const srv = app.listen(config.port, () => resolve(srv));
+  });
+
+  return {
+    app,
+    server,
+    store,
+    stop: () =>
+      new Promise((resolve) => {
+        server.close(resolve);
+      }),
+    reset: () => {
+      store.reset();
+      seedAll(config.resources, store);
+      logger.info('Store has been reset and re-seeded');
+    },
+    getStore: () => store.toJSON(),
+  };
+}