phantomback 1.0.0

package/src/server/middleware.js

@@ -0,0 +1,64 @@
+import cors from 'cors';
+import express from 'express';
+import { logger } from '../utils/logger.js';
+
+/**
+ * Create and configure the Express server with standard middleware
+ */
+export function createExpressApp(config) {
+  const app = express();
+
+  // Body parsing
+  app.use(express.json({ limit: '10mb' }));
+  app.use(express.urlencoded({ extended: true }));
+
+  // CORS (allow everything in dev)
+  app.use(
+    cors({
+      origin: '*',
+      methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'],
+      allowedHeaders: ['Content-Type', 'Authorization', 'X-Requested-With'],
+    }),
+  );
+
+  // Request logger
+  app.use((req, _res, next) => {
+    logger.route(req.method, req.originalUrl);
+    next();
+  });
+
+  // Health check
+  app.get(`${config.prefix}/_health`, (_req, res) => {
+    res.json({ status: 'ok', uptime: process.uptime(), timestamp: new Date().toISOString() });
+  });
+
+  return app;
+}
+
+/**
+ * Add error handling middleware (call after all routes are registered)
+ */
+export function addErrorHandling(app) {
+  // 404 handler
+  app.use((_req, res) => {
+    res.status(404).json({
+      success: false,
+      error: {
+        status: 404,
+        message: 'Route not found. Check your API prefix and resource names.',
+      },
+    });
+  });
+
+  // Global error handler
+  app.use((err, _req, res, _next) => {
+    logger.error(err.message);
+    res.status(err.status || 500).json({
+      success: false,
+      error: {
+        status: err.status || 500,
+        message: err.message || 'Internal Server Error',
+      },
+    });
+  });
+}

package/src/server/router.js

@@ -0,0 +1,274 @@
+import express from 'express';
+import { paginate } from '../features/pagination.js';
+import { applyFilters } from '../features/filters.js';
+import { applySort } from '../features/sorting.js';
+import { applySearch } from '../features/search.js';
+import { authMiddleware } from '../features/auth.js';
+import { delayMiddleware } from '../features/delay.js';
+import { validationMiddleware } from '../schema/validator.js';
+import { detectRelations, getChildren } from '../data/relations.js';
+import { asyncHandler, sendResponse, sendError } from '../utils/helpers.js';
+import { logger } from '../utils/logger.js';
+
+/**
+ * Generate REST CRUD routes for all resources
+ */
+export function createRouter(config, store) {
+  const router = express.Router();
+  const { resources, prefix } = config;
+  const relations = detectRelations(resources);
+
+  // Apply global latency
+  if (config.latency) {
+    router.use(delayMiddleware(config.latency));
+  }
+
+  // Info endpoint: list all available routes
+  router.get(`${prefix}`, (_req, res) => {
+    const endpoints = {};
+    for (const name of Object.keys(resources)) {
+      endpoints[name] = {
+        list: `GET ${prefix}/${name}`,
+        getOne: `GET ${prefix}/${name}/:id`,
+        create: `POST ${prefix}/${name}`,
+        update: `PUT ${prefix}/${name}/:id`,
+        patch: `PATCH ${prefix}/${name}/:id`,
+        delete: `DELETE ${prefix}/${name}/:id`,
+      };
+
+      // Add nested routes info
+      const children = getChildren(name, relations);
+      if (children.length > 0) {
+        endpoints[name].nested = children.map(
+          (c) => `GET ${prefix}/${name}/:id/${c.childResource}`,
+        );
+      }
+    }
+
+    res.json({
+      success: true,
+      message: '👻 PhantomBack API is running!',
+      endpoints,
+    });
+  });
+
+  // Generate routes for each resource
+  for (const [resourceName, schema] of Object.entries(resources)) {
+    const fields = schema.fields || {};
+    const basePath = `${prefix}/${resourceName}`;
+    const resourceAuth = schema.auth || false;
+    const secret = config.auth?.secret;
+
+    // Optionally protect routes with auth
+    const protect = resourceAuth ? [authMiddleware(secret)] : [];
+
+    // Per-resource latency
+    if (schema.latency) {
+      router.use(basePath, delayMiddleware(schema.latency));
+    }
+
+    // ─── GET /resource ─── List all with pagination, filtering, sorting, search
+    router.get(
+      basePath,
+      ...protect,
+      asyncHandler(async (req, res) => {
+        let records = store.findAll(resourceName);
+
+        // Apply search
+        records = applySearch(records, req.query);
+
+        // Apply filters
+        records = applyFilters(records, req.query);
+
+        // Apply sort
+        records = applySort(records, req.query);
+
+        // Field selection
+        const selectParam = req.query.fields || req.query._fields || req.query.select;
+        if (selectParam) {
+          const selectedFields = selectParam.split(',').map((f) => f.trim());
+          records = records.map((record) => {
+            const picked = { id: record.id };
+            for (const f of selectedFields) {
+              if (f in record) picked[f] = record[f];
+            }
+            return picked;
+          });
+        }
+
+        // Apply pagination
+        const { data, meta } = paginate(records, req.query);
+
+        return sendResponse(res, 200, data, meta);
+      }),
+    );
+
+    // ─── GET /resource/:id ─── Get one by ID
+    router.get(
+      `${basePath}/:id`,
+      ...protect,
+      asyncHandler(async (req, res) => {
+        const record = store.findById(resourceName, req.params.id);
+        if (!record) {
+          return sendError(res, 404, `${resourceName} with id "${req.params.id}" not found`);
+        }
+        return sendResponse(res, 200, record);
+      }),
+    );
+
+    // ─── POST /resource ─── Create new record
+    router.post(
+      basePath,
+      ...protect,
+      validationMiddleware(fields, false),
+      asyncHandler(async (req, res) => {
+        // Unique field check
+        const uniqueError = checkUnique(resourceName, fields, req.validatedBody, store);
+        if (uniqueError) {
+          return sendError(res, 409, uniqueError);
+        }
+
+        const record = store.create(resourceName, req.validatedBody);
+        return sendResponse(res, 201, record);
+      }),
+    );
+
+    // ─── PUT /resource/:id ─── Full update
+    router.put(
+      `${basePath}/:id`,
+      ...protect,
+      validationMiddleware(fields, false),
+      asyncHandler(async (req, res) => {
+        const existing = store.findById(resourceName, req.params.id);
+        if (!existing) {
+          return sendError(res, 404, `${resourceName} with id "${req.params.id}" not found`);
+        }
+
+        // Unique check (exclude current record)
+        const uniqueError = checkUnique(
+          resourceName,
+          fields,
+          req.validatedBody,
+          store,
+          req.params.id,
+        );
+        if (uniqueError) {
+          return sendError(res, 409, uniqueError);
+        }
+
+        const updated = store.update(resourceName, req.params.id, req.validatedBody);
+        return sendResponse(res, 200, updated);
+      }),
+    );
+
+    // ─── PATCH /resource/:id ─── Partial update
+    router.patch(
+      `${basePath}/:id`,
+      ...protect,
+      validationMiddleware(fields, true),
+      asyncHandler(async (req, res) => {
+        const existing = store.findById(resourceName, req.params.id);
+        if (!existing) {
+          return sendError(res, 404, `${resourceName} with id "${req.params.id}" not found`);
+        }
+
+        const uniqueError = checkUnique(
+          resourceName,
+          fields,
+          req.validatedBody,
+          store,
+          req.params.id,
+        );
+        if (uniqueError) {
+          return sendError(res, 409, uniqueError);
+        }
+
+        const patched = store.patch(resourceName, req.params.id, req.validatedBody);
+        return sendResponse(res, 200, patched);
+      }),
+    );
+
+    // ─── DELETE /resource/:id ─── Delete
+    router.delete(
+      `${basePath}/:id`,
+      ...protect,
+      asyncHandler(async (req, res) => {
+        const existing = store.findById(resourceName, req.params.id);
+        if (!existing) {
+          return sendError(res, 404, `${resourceName} with id "${req.params.id}" not found`);
+        }
+
+        store.delete(resourceName, req.params.id);
+        return sendResponse(res, 200, {
+          message: `${resourceName} deleted successfully`,
+          id: req.params.id,
+        });
+      }),
+    );
+
+    // ─── Nested routes ─── GET /resource/:id/childResource
+    const children = getChildren(resourceName, relations);
+    for (const relation of children) {
+      const nestedPath = `${basePath}/:id/${relation.childResource}`;
+
+      router.get(
+        nestedPath,
+        ...protect,
+        asyncHandler(async (req, res) => {
+          // Verify parent exists
+          const parent = store.findById(resourceName, req.params.id);
+          if (!parent) {
+            return sendError(res, 404, `${resourceName} with id "${req.params.id}" not found`);
+          }
+
+          // Find child records where foreignKey === parent id
+          let records = store.findWhere(relation.childResource, (record) => {
+            return record[relation.foreignKey] === req.params.id;
+          });
+
+          records = applySearch(records, req.query);
+          records = applyFilters(records, req.query);
+          records = applySort(records, req.query);
+
+          const { data, meta } = paginate(records, req.query);
+          return sendResponse(res, 200, data, meta);
+        }),
+      );
+
+      logger.route('GET', nestedPath);
+    }
+
+    // Log registered routes
+    logger.route('GET', basePath);
+    logger.route('GET', `${basePath}/:id`);
+    logger.route('POST', basePath);
+    logger.route('PUT', `${basePath}/:id`);
+    logger.route('PATCH', `${basePath}/:id`);
+    logger.route('DELETE', `${basePath}/:id`);
+  }
+
+  return router;
+}
+
+/**
+ * Check unique constraints on fields
+ */
+function checkUnique(resourceName, fields, data, store, excludeId = null) {
+  for (const [fieldName, fieldDef] of Object.entries(fields)) {
+    const def = typeof fieldDef === 'string' ? { type: fieldDef } : fieldDef;
+    if (!def.unique) continue;
+
+    const value = data[fieldName];
+    if (value === undefined) continue;
+
+    const existing = store.findAll(resourceName).find((r) => {
+      return r[fieldName] === value && r.id !== excludeId;
+    });
+
+    if (existing) {
+      return `A ${resourceName} with ${fieldName} "${value}" already exists`;
+    }
+  }
+
+  return null;
+}

package/src/utils/helpers.js

@@ -0,0 +1,114 @@
+import { randomUUID } from 'node:crypto';
+
+/**
+ * Generate a unique ID
+ */
+export function generateId() {
+  return randomUUID().split('-')[0];
+}
+
+/**
+ * Get current ISO timestamp
+ */
+export function timestamp() {
+  return new Date().toISOString();
+}
+
+/**
+ * Deep clone an object (structured clone)
+ */
+export function deepClone(obj) {
+  return structuredClone(obj);
+}
+
+/**
+ * Pick specific keys from an object
+ */
+export function pick(obj, keys) {
+  const result = {};
+  for (const key of keys) {
+    if (key in obj) result[key] = obj[key];
+  }
+  return result;
+}
+
+/**
+ * Omit specific keys from an object
+ */
+export function omit(obj, keys) {
+  const result = { ...obj };
+  for (const key of keys) {
+    delete result[key];
+  }
+  return result;
+}
+
+/**
+ * Pluralize a resource name (simple)
+ */
+export function pluralize(str) {
+  if (str.endsWith('s')) return str;
+  if (str.endsWith('y')) return str.slice(0, -1) + 'ies';
+  return str + 's';
+}
+
+/**
+ * Singularize a resource name (simple)
+ */
+export function singularize(str) {
+  if (str.endsWith('ies')) return str.slice(0, -3) + 'y';
+  if (str.endsWith('s')) return str.slice(0, -1);
+  return str;
+}
+
+/**
+ * Parse a string value to its proper type
+ */
+export function parseValue(value) {
+  if (value === 'true') return true;
+  if (value === 'false') return false;
+  if (value === 'null') return null;
+  if (value === 'undefined') return undefined;
+  const num = Number(value);
+  if (!isNaN(num) && value !== '') return num;
+  return value;
+}
+
+/**
+ * Check if a value matches a search query (case-insensitive)
+ */
+export function matchesSearch(value, query) {
+  if (value === null || value === undefined) return false;
+  return String(value).toLowerCase().includes(query.toLowerCase());
+}
+
+/**
+ * Wrap an async Express handler to catch errors
+ */
+export function asyncHandler(fn) {
+  return (req, res, next) => {
+    Promise.resolve(fn(req, res, next)).catch(next);
+  };
+}
+
+/**
+ * Send a standardized JSON response
+ */
+export function sendResponse(res, statusCode, data, meta = null) {
+  const response = { success: statusCode >= 200 && statusCode < 300 };
+  if (meta) response.meta = meta;
+  if (data !== undefined) response.data = data;
+  return res.status(statusCode).json(response);
+}
+
+/**
+ * Send an error response
+ */
+export function sendError(res, statusCode, message, errors = null) {
+  const response = {
+    success: false,
+    error: { status: statusCode, message },
+  };
+  if (errors) response.error.details = errors;
+  return res.status(statusCode).json(response);
+}

package/src/utils/logger.js

@@ -0,0 +1,58 @@
+import chalk from 'chalk';
+
+const PREFIX = chalk.hex('#a78bfa').bold('[PhantomBack]');
+
+export const logger = {
+  info: (...args) => console.log(PREFIX, chalk.cyan('INFO'), ...args),
+  success: (...args) => console.log(PREFIX, chalk.green('✓'), ...args),
+  warn: (...args) => console.log(PREFIX, chalk.yellow('⚠'), ...args),
+  error: (...args) => console.error(PREFIX, chalk.red('✗'), ...args),
+  route: (method, path) => {
+    const colors = {
+      GET: chalk.green,
+      POST: chalk.blue,
+      PUT: chalk.yellow,
+      PATCH: chalk.magenta,
+      DELETE: chalk.red,
+    };
+    const colorFn = colors[method] || chalk.white;
+    console.log(PREFIX, colorFn.bold(method.padEnd(7)), chalk.dim(path));
+  },
+  server: (port) => {
+    console.log('');
+    console.log(PREFIX, chalk.green.bold('Server is running!'));
+    console.log(PREFIX, chalk.dim('Local:'), chalk.cyan.underline(`http://localhost:${port}`));
+    console.log('');
+  },
+  banner: () => {
+    console.log('');
+    console.log(chalk.hex('#a78bfa').bold('  ╔═══════════════════════════════════════╗'));
+    console.log(
+      chalk.hex('#a78bfa').bold('  ║         ') +
+        chalk.white.bold('PhantomBack v1.0.0') +
+        chalk.hex('#a78bfa').bold('         ║'),
+    );
+    console.log(
+      chalk.hex('#a78bfa').bold('  ║   ') +
+        chalk.dim('Instant Fake Backend Generator') +
+        chalk.hex('#a78bfa').bold('    ║'),
+    );
+    console.log(chalk.hex('#a78bfa').bold('  ╚═══════════════════════════════════════╝'));
+    console.log('');
+  },
+  table: (resources) => {
+    console.log(PREFIX, chalk.white.bold('Registered Resources:'));
+    for (const [name, config] of Object.entries(resources)) {
+      const count = config.seed || 0;
+      const auth = config.auth ? chalk.yellow(' 🔒') : '';
+      console.log(
+        PREFIX,
+        chalk.dim('  ├─'),
+        chalk.white.bold(name),
+        chalk.dim(`(${count} records)`),
+        auth,
+      );
+    }
+    console.log('');
+  },
+};