json-rest-api 0.1.0 → 1.0.0

package/docs/example.js

@@ -0,0 +1,195 @@
+import express from 'express';
+import { 
+  createApi, 
+  Api, 
+  Schema,
+  MySQLPlugin,
+  HTTPPlugin,
+  ValidationPlugin,
+  PositioningPlugin,
+  VersioningPlugin
+} from './index.js';
+
+// Example 1: Simple API with memory storage
+const simpleApi = createApi({
+  storage: 'memory',
+  http: {
+    basePath: '/api/v1',
+    typeOptions: {
+      users: { 
+        searchFields: ['name', 'email'] 
+      }
+    }
+  }
+});
+
+// Define a schema
+const userSchema = new Schema({
+  id: { type: 'id' },
+  name: { type: 'string', required: true, min: 2, max: 100 },
+  email: { type: 'string', required: true, lowercase: true },
+  age: { type: 'number', min: 0, max: 150 },
+  active: { type: 'boolean', default: true },
+  createdAt: { type: 'timestamp', default: () => Date.now() }
+});
+
+// Register the schema
+simpleApi.addResource('users', userSchema);
+
+// Example 2: Advanced API with MySQL and all features
+const advancedApi = new Api({ idProperty: 'id' });
+
+// Configure plugins
+advancedApi
+  .use(ValidationPlugin)
+  .use(MySQLPlugin, {
+    connections: [{
+      name: 'main',
+      config: {
+        host: 'localhost',
+        user: 'root',
+        password: 'password',
+        database: 'myapp'
+      }
+    }]
+  })
+  .use(PositioningPlugin, {
+    positionField: 'position',
+    beforeIdField: 'beforeId'
+  })
+  .use(VersioningPlugin, {
+    apiVersion: '2.0.0',
+    trackHistory: true,
+    optimisticLocking: true
+  })
+  .use(HTTPPlugin, {
+    basePath: '/api/v2'
+  });
+
+// Define schemas
+const productSchema = new Schema({
+  id: { type: 'id' },
+  name: { type: 'string', required: true, min: 1, max: 200 },
+  description: { type: 'string', max: 1000 },
+  price: { type: 'number', required: true, min: 0, currency: true },
+  stock: { type: 'number', default: 0, min: 0 },
+  category: { type: 'string', required: true },
+  tags: { type: 'array', default: [] },
+  metadata: { type: 'object' },
+  active: { type: 'boolean', default: true },
+  position: { type: 'number', default: 0 },
+  version: { type: 'number', default: 1 },
+  createdAt: { type: 'timestamp', default: () => Date.now() },
+  updatedAt: { type: 'timestamp' }
+});
+
+// Create search schema from main schema
+const productSearchSchema = advancedApi.createSearchSchema(productSchema, [
+  'name', 'category', 'active'
+]);
+
+// Register schemas
+advancedApi.addResource('products', productSchema);
+
+// Custom validation hook
+advancedApi.hook('afterValidate', async (context) => {
+  if (context.method === 'insert' || context.method === 'update') {
+    const { data } = context;
+    
+    // Custom business rule: expensive products must have description
+    if (data.price > 1000 && !data.description) {
+      context.errors.push({
+        field: 'description',
+        message: 'Products over $1000 must have a description',
+        code: 'EXPENSIVE_PRODUCT_NEEDS_DESCRIPTION'
+      });
+    }
+  }
+});
+
+// Transform hook to add computed fields
+advancedApi.hook('transformResult', async (context) => {
+  if (context.result && context.options.type === 'products') {
+    const product = context.result;
+    
+    // Add computed field
+    product.displayPrice = `$${(product.price || 0).toFixed(2)}`;
+    product.inStock = product.stock > 0;
+  }
+});
+
+// Example 3: Using the API programmatically
+async function exampleUsage() {
+  // Insert a product
+  const newProduct = await advancedApi.insert({
+    name: 'Premium Widget',
+    description: 'A high-quality widget for professionals',
+    price: 1299.99,
+    stock: 50,
+    category: 'widgets',
+    tags: ['premium', 'professional'],
+    beforeId: null // Will be placed at the end
+  }, {
+    type: 'products',
+    table: 'products',
+    positioning: { enabled: true }
+  });
+
+  console.log('Created product:', newProduct);
+
+  // Query products
+  const products = await advancedApi.query({
+    filter: { category: 'widgets', active: true },
+    sort: '-price,name',
+    page: { size: 10, number: 1 }
+  }, {
+    type: 'products',
+    table: 'products'
+  });
+
+  console.log('Found products:', products);
+
+  // Update with optimistic locking
+  const updated = await advancedApi.update(newProduct.data.id, {
+    stock: 45,
+    version: newProduct.data.attributes.version // For optimistic locking
+  }, {
+    type: 'products',
+    table: 'products'
+  });
+
+  console.log('Updated product:', updated);
+
+  // Get version history
+  const history = await advancedApi.getVersionHistory('products', newProduct.data.id);
+  console.log('Version history:', history);
+}
+
+// Example 4: Express app setup
+const app = express();
+
+// Mount the APIs
+simpleApi.mount(app);
+advancedApi.mount(app);
+
+// Add custom middleware
+advancedApi.useMiddleware((req, res, next) => {
+  // Add user ID from session for versioning
+  req.options = { userId: req.session?.userId };
+  next();
+});
+
+// Sync database schema
+async function syncDatabase() {
+  await advancedApi.syncSchema(productSchema, 'products', {
+    connection: 'main'
+  });
+}
+
+// Start server
+app.listen(3000, () => {
+  console.log('API server running on http://localhost:3000');
+});
+
+// Export for use in other modules
+export { simpleApi, advancedApi, userSchema, productSchema };

package/index.js

@@ -1,210 +1,61 @@
-/**
- * @fileOverview
- * Implements a simple REST API in an object. Requests and responses are in
- * JSON. Or are supposed to be.
- */
-'use strict';
-var http = require('http');
-var debug = require('debug')('json-rest-api');
-var url = require('url');
-var util = require('util');
-var inspect = util.inspect;
-var is = require('is2');
-var asyncerr = require('async-err');
-
-// set a default port to listen for requests
-var DEFAULT_PORT = process.env.PORT ? process.env.PORT : 44401;
-
-exports.RestApi = RestApi;
-
-/**
- * RestApi constructor. Creates the HTTP server objects and starts listening on
- * the socket.
- * @param {Object} [config] An optional configuration object to configure the
- * RestApi. Possible properties are: port and bindTo to specify the listening
- * port and the address to bind to. If no port is specified the default is 44401
- * and the default address is INADDR_ANY.
- * @param {Function} [cb] An optional callback. If there is a callback, the
- * process will be begin listening on the socket for HTTP requests.
- * @constructor
- */
-function RestApi(config, cb) {
-    var self = this;
-    self.routes = {};
-
-    self.bindTo = (config && config.bindTo) ? config.bindTo : undefined;
-    self.port = (config && config.port) ? config.port : DEFAULT_PORT;
-
-    // create the HTTP server object and on every request, try to match the
-    // request with a known route. If there is no match, return a 404 error.
-    self.HttpServer = http.createServer(function(req, res) {
-        var uriPath;
-        var queryStr;
-        var urlParts = url.parse(req.url, true);
-        if (is.obj(urlParts)) {
-            uriPath = urlParts.pathname || undefined;
-            queryStr = urlParts.query || undefined;
-            debug('queryStr: '+inspect(queryStr));
-        } else {
-            // no match was found, return a 404 error.
-            res.writeHead(400, {'Content-Type': 'application/json; charset=utf-8'});
-            res.end('{status:400, message:"Bad URI path."}', 'utf8');
-            return;
-        }
-
-        // try to match the request & method with a handler
-        for (var path in self.routes[req.method]) {
-            if (path === uriPath) {
-                self.routes[req.method][path](req, res, queryStr);
-                return;
-            }
-        }
-
-        // no match was found, return a 404 error.
-        res.writeHead(404, {'Content-Type': 'application/json; charset=utf-8'});
-        res.end('{status:404, message:"Content not found."}', 'utf8');
-    });
-
-    if (cb) self.listen(cb);
+// Core exports
+export { Api } from './api.js';
+export { Schema } from './schema.js';
+
+// Plugin exports
+export { MemoryPlugin } from './plugins/memory.js';
+export { MySQLPlugin } from './plugins/mysql.js';
+export { HTTPPlugin } from './plugins/http.js';
+export { ValidationPlugin } from './plugins/validation.js';
+export { PositioningPlugin } from './plugins/positioning.js';
+export { VersioningPlugin } from './plugins/versioning.js';
+export { SecurityPlugin } from './plugins/security.js';
+export { LoggingPlugin } from './plugins/logging.js';
+export { OpenAPIPlugin } from './plugins/openapi.js';
+export { ApiRegistryPlugin } from './plugins/api-registry.js';
+
+// Import for internal use
+import { Api } from './api.js';
+import { MemoryPlugin } from './plugins/memory.js';
+import { MySQLPlugin } from './plugins/mysql.js';
+import { HTTPPlugin } from './plugins/http.js';
+import { ValidationPlugin } from './plugins/validation.js';
+import { PositioningPlugin } from './plugins/positioning.js';
+import { VersioningPlugin } from './plugins/versioning.js';
+
+// Convenience function to create a fully configured API
+export function createApi(options = {}) {
+  const api = new Api(options);
+  
+  // Add default plugins based on options
+  if (options.validation !== false) {
+    api.use(ValidationPlugin, options.validation);
+  }
+  
+  if (options.storage === 'memory') {
+    api.use(MemoryPlugin, options.memory);
+  } else if (options.storage === 'mysql') {
+    api.use(MySQLPlugin, options.mysql);
+  }
+  
+  // Auto-add HTTP plugin if http options are provided
+  if (options.http) {
+    api.use(HTTPPlugin, options.http);
+  }
+  
+  if (options.positioning) {
+    api.use(PositioningPlugin, options.positioning);
+  }
+  
+  if (options.versioning) {
+    api.use(VersioningPlugin, options.versioning);
+  }
+  
+  return api;
 }
 
-/**
- * Start listening on the socket for HTTP requests.
- * @param {Function} [cb] An optional callback called when the server is ready.
- */
-RestApi.prototype.listen = function(cb) {
-    var self = this;
-
-    self.HttpServer.listen(self.port, self.bindTo, function(err) {
-        if (err)    {
-            var errStr = 'RestApi error: '+inspect(err);
-            debug(errStr);
-            if (cb)
-                return cb(new Error(errStr));
-            else
-                return;
-        }
-        debug('REST API listening on port: '+self.port);
-        if (cb)    cb();
-    });
-};
-
-/**
- * Stops the server from acccepting new connections and listening on the port.
- * @param {Function} [cb] The callback function. Optional.
- */
-RestApi.prototype.stop = function(cb) {
-    var self = this;
-
-    if (!is.obj(self.HttpServer))
-        return asyncerr(new Error('There server is not running.'), cb);
-
-    self.HttpServer.close(function(err) {
-        if (err && cb) return cb(err);
-        if (cb) return cb();
-    });
-};
-
-/**
- * Add a route along with a function to run.
- * @param {String} verb HTTP verb for route.
- * @param {String} path A valid URI path.
- * @param {Function} func A function to run when the path executes.
- * @return {Boolean|Error} True, if no errors on the parameters, Error
- * otherwise.
- * @return {Error|Boolean} true on success and Error on failure.
- */
-RestApi.prototype.addRoute = function(verb, path, func) {
-    var self = this;
-
-    if (!is.nonEmptyStr(verb))
-        return new Error('Bad verb: '+inspect(verb));
-
-    if (!is.nonEmptyStr(path))
-        return new Error('RestApi.addRoute bad path: '+inspect(path));
-
-    if (!is.func(func))
-        return new Error('RestApi.prototype.addRoute bad func: '+inspect(func));
-
-    var httpVerb = verb.toUpperCase();
-    debug('Adding: '+httpVerb+' '+path);
-    if (!self.routes[httpVerb])    self.routes[httpVerb] = {};
-
-    // Create a handling function for the route that gathers the
-    // the HTTP request body and passes that on.
-    self.routes[httpVerb][path] = function(req, res, queryStr) {
-        var body = '';     // buffer for body.
-
-        // collect the body in buf;
-        req.on('data', function (data) { body += data.toString(); });
-
-        // we have the body & header, now process.
-        req.on('end', function () {
-            req.body = body;
-            res.setHeader('Content-Type', 'application/json');
-            res.statusCode = 200;
-
-            // there may not be a body
-            if (body.length === 0)
-                return func(req, res, {}, queryStr);
-
-            // there is a body, make sure it is valid, parsable JSON
-            var jsonBody;
-            try {
-                jsonBody = JSON.parse(body);
-            } catch (err) {
-                debug('Error parsing JSON body:',body);
-                res.statusCode = 400;
-                res.end('{"success": false, "msg": "Bad request."}', 'utf8');
-                return;
-            }
-            func(req, res, jsonBody, queryStr);
-        });
-    };
-    return true;
-};
-
-/**
- * A method for the JsonServerResponse prototype to send json by passing an
- * object.    Usage:    res.json([status|body], [body])
- * @param {Number|Object} Optional. First argument may be either the status
- * code or the object to stringify into JSON.
- * @param {Object} Optional. If the first object is the status code, then the
- * second optional argument, if present, is an object to serialize into JSON.
- * @return {Boolean} true on success, false otherwise.
- */
-http.ServerResponse.prototype.json = function(obj) {
-
-    if (arguments.length === 2) {
-        if (typeof arguments[1] === 'number') {
-            this.statusCode = arguments[1];
-        } else {
-            this.statusCode = obj;
-            obj = arguments[1];
-        }
-    }
-
-    if (!is.obj(obj)) {
-        debug('http.ServerResponse.json bad object param: '+inspect(obj));
-        return false;
-    }
-
-    if (!is.positiveInt(this.statusCode)) {
-        debug('http.ServerResponse.json bad status param: '+
-              inspect(this.statusCode));
-        return false;
-    }
-
-    var str;
-    try {
-        str = JSON.stringify(obj);
-    } catch (err) {
-        debug('Error parsing JSON body: '+inspect(obj));
-        debug('Error err: '+inspect(err));
-        return false;
-    }
+// Re-export circular-json-es6 for convenience
+export { stringify as serialize, parse as deserialize } from 'circular-json-es6';
 
-    this.writeHead(this.statusCode, {'Content-Type': 'application/json'});
-    this.end(str, 'utf8');
-    return true;
-};
+// Export version
+export const VERSION = '1.0.0';

package/package.json

@@ -1,35 +1,25 @@
 {
   "name": "json-rest-api",
-  "version": "0.1.0",
-  "description": "A simple lightweight REST API that receives and responds to JSON HTTP requests, supports all verbs. Very simple.",
+  "version": "1.0.0",
+  "description": "A simple, extensible RESTful JSON API library with schema validation and positioning",
   "main": "index.js",
-  "scripts": {
-    "test": "./node_modules/.bin/mocha --reporter list ./test.js"
-  },
+  "type": "module",
+  "keywords": ["rest", "json-api", "mysql", "schema", "validation"],
+  "author": "Tony Mobily",
+  "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git://github.com/stdarg/json-rest-api.git"
-  },
-  "keywords": [
-    "simple",
-    "REST",
-    "HTTP",
-    "JSON",
-    "API",
-    "interface"
-  ],
-  "author": "Edmond Meinfelder",
-  "license": "MIT",
-  "bugs": {
-    "url": "https://github.com/stdarg/json-rest-api/issues"
+    "url": "https://github.com/mobily-enterprises/jsonrestapi.git"
   },
   "dependencies": {
-    "async-err": "0.0.2",
-    "debug": "0.7.4",
-    "is2": "0.0.12"
+    "circular-json-es6": "^2.0.2",
+    "express": "^4.21.1",
+    "mysql2": "^3.13.1",
+    "thenby": "^1.3.4",
+    "semver": "^7.5.4"
   },
-  "devDependencies": {
-    "mocha": "1.17.1",
-    "request": "2.33.0"
+  "devDependencies": {},
+  "engines": {
+    "node": ">=18"
   }
 }