snapsrv4u

Mock API Server

A lightweight mock API server that generates realistic fake data using Faker.js, persists it to a real or file-based database, and pushes live updates to connected clients over WebSocket and Socket.io.

Table of Contents

• Installation
• Quick Start
• Constructor Options
• Database Adapters
  • snap4db (default)
  • SQLite
  • PostgreSQL
  • MongoDB
• Adding Routes
  • GET
  • POST
  • DELETE
• Real-Time: WebSocket & Socket.io
• Pre-built Schemas
• Supported Data Types
• Property Config Options

---

Installation

npm install snapsrv4u

Install only the database driver(s) you need:

npm install better-sqlite3   # SQLite
npm install pg               # PostgreSQL
npm install mongodb          # MongoDB

Install real-time transports if you need them:

npm install ws               # raw WebSocket
npm install socket.io        # Socket.io

---

Quick Start

Generate fake data with no database — GET requests only.

const MockApiServer = require('snapsrv4u');

const server = new MockApiServer({ port: 4517 });

server.addRoute('/api/users', {
  method: 'GET',
  count: 10,
  properties: {
    id:    { type: 'uuid' },
    name:  { type: 'fullname' },
    email: { type: 'email' }
  }
});

server.start();
// GET http://localhost:4517/api/users  →  { data: [ { id, name, email }, ... ] }

---

Constructor Options

const server = new MockApiServer({
  port:      4517,    // port to listen on (default: 4517)
  dbName:    'mydb',  // snap4db database name (legacy option)
  db:        { ... }, // real database config (see Database Adapters)
  websocket: true,    // attach a raw ws WebSocket server (default: true)
  socketio:  true,    // attach a Socket.io server (default: true)
});

The legacy positional signature still works for backwards compatibility:

const server = new MockApiServer(4517);
// or
const server = new MockApiServer(4517, 'mydb');

---

Database Adapters

snap4db (default)

A file-based CSV store included with the package. No extra install needed.

const server = new MockApiServer({
  port:   4517,
  dbName: 'myDatabase'
});

---

SQLite

Stores data in a local .db file (or in memory with ':memory:').

const server = new MockApiServer({
  port: 4517,
  db: {
    type:     'sqlite',
    filename: './data.db'   // use ':memory:' for an in-memory database
  }
});

---

PostgreSQL

Connects to a running Postgres instance. Tables are created automatically — no migrations needed.

// Using a connection string
const server = new MockApiServer({
  port: 4517,
  db: {
    type:             'postgres',
    connectionString: 'postgresql://user:password@localhost:5432/mydb'
  }
});

// Or individual fields
const server = new MockApiServer({
  port: 4517,
  db: {
    type:     'postgres',
    host:     'localhost',
    port:     5432,
    database: 'mydb',
    user:     'postgres',
    password: 'secret'
  }
});

---

MongoDB

Connects to a running MongoDB instance. Collections are created on first use.

const server = new MockApiServer({
  port: 4517,
  db: {
    type: 'mongodb',
    uri:  'mongodb://localhost:27017',
    name: 'mydb'
  }
});

---

Adding Routes

GET

Generate fake data on every request (no database needed):

server.addRoute('/api/products', {
  method: 'GET',
  count:  5,
  properties: {
    id:    { type: 'uuid' },
    name:  { type: 'product' },
    price: { type: 'price' },
    inStock: { type: 'boolean' }
  }
});
// GET /api/products  →  { data: [ {...}, {...}, ... ] }

Fetch a single record from the database by ID:

// ID from URL param
server.addRoute('/api/users/:id', {
  method:     'GET',
  collection: 'users'
});
// GET /api/users/abc123

// ID from query string
server.addRoute('/api/users', {
  method:     'GET',
  collection: 'users'
});
// GET /api/users?id=abc123

Use the built-in person schema shorthand:

server.addRoute('/api/people', {
  method:      'GET',
  count:       3,
  properties:  'person'
});

---

POST

Inserts the request body into the database collection. Optionally enforces unique constraints.

server.addRoute('/api/users', {
  method:     'POST',
  collection: 'users',
  properties: {
    username: { type: 'username', unique: true },
    email:    { type: 'email',    unique: true },
    password: { type: 'password' }
  }
});

POST /api/users
{ "username": "alice", "email": "alice@example.com", "password": "s3cr3t" }

→ { "id": "...", "username": "alice", "email": "alice@example.com", "password": "s3cr3t" }

If a unique field is duplicated, the server responds with:

{ "error": { "message": "Property <email> needs to be unique" } }

---

DELETE

Removes a record by ID. Accepts the ID from URL params, query string, or request body.

// From URL param
server.addRoute('/api/users/:id', {
  method:     'DELETE',
  collection: 'users'
});
// DELETE /api/users/abc123

// From query string
server.addRoute('/api/users', {
  method:     'DELETE',
  collection: 'users'
});
// DELETE /api/users?id=abc123

---

Real-Time: WebSocket & Socket.io

When ws and/or socket.io are installed, the server automatically broadcasts events to all connected clients whenever data changes.

const server = new MockApiServer({
  port: 4517,
  db:   { type: 'sqlite', filename: './data.db' }
});

server.addRoute('/api/messages', { method: 'POST',   collection: 'messages' });
server.addRoute('/api/messages/:id', { method: 'DELETE', collection: 'messages' });

server.start();

Events emitted automatically:

Event	Triggered by	Payload
created	Successful POST	{ route, record }
deleted	Successful DELETE	{ route, id }

Listening with Socket.io (browser / Node client):

import { io } from 'socket.io-client';

const socket = io('http://localhost:4517');

socket.on('created', ({ route, record }) => {
  console.log('New record on', route, record);
});

socket.on('deleted', ({ route, id }) => {
  console.log('Deleted', id, 'from', route);
});

Listening with a raw WebSocket:

const ws = new WebSocket('ws://localhost:4517');

ws.onmessage = ({ data }) => {
  const { event, route, record, id } = JSON.parse(data);
  console.log(event, route, record ?? id);
};

Registering custom events (server-side):

server.addSocketEvent('chat:message', (data, socket) => {
  console.log('Received chat message:', data);
  // socket is the Socket.io socket or raw ws client
});

Disabling real-time transports:

const server = new MockApiServer({
  port:      4517,
  websocket: false,  // disable raw WebSocket
  socketio:  false,  // disable Socket.io
});

---

Pre-built Schemas

MockApiServer.personSchema is a ready-made 12-field schema for user/person data:

Field	Type
userId	uuid
username	username
firstName	firstname
lastName	lastname
email	email
avatar	avatar
phone	phone
dateOfBirth	past date
address	street address
bio	bio
jobTitle	jobTitle
registeredAt	timestamp

Use it directly in any route:

server.addRoute('/api/users', {
  method:     'GET',
  count:      5,
  properties: 'person'
});

Or access the schema object manually:

const schema = MockApiServer.personSchema;

---

Supported Data Types

Pass any of these as the type field in a property config.

Category	Types
Numbers	number, float, id, uuid
Strings	string, sentence, paragraph
Dates	date, past, future, timestamp
Personal	firstname, lastname, fullname, username, email, avatar, phone, gender, jobTitle, bio
Location	latitude, longitude, city, country, address, zipcode
Internet	url, ipv4, password, useragent
Company	company, department, catchPhrase
Commerce	product, price, color
Boolean	boolean
Custom	faker — direct Faker.js method access (see below)

Custom faker access:

properties: {
  genre:   { type: 'faker', method: 'music.genre' },
  vehicle: { type: 'faker', method: 'vehicle.model' }
}

---

Property Config Options

Option	Applies to	Description
type	all	(Required) Data type to generate
min	number, float, string	Minimum value or length
max	number, float, string	Maximum value or length
zeros	id	Number of digits (e.g. zeros: 5 → "00042")
from	date	Start of date range (e.g. '2020-01-01')
to	date	End of date range (e.g. '2024-12-31')
unique	any (POST)	Reject duplicates for this field (true/false)
method	faker	Faker.js path, e.g. 'music.genre'
options	faker	Options object forwarded to the Faker.js method