json-rest-api 0.1.1 → 1.0.0

package/README.md

@@ -1,165 +1,427 @@
-json-rest-api
-=============
-A lightweight REST API that receives and responds to JSON HTTP requests,
-supports all verbs. Expects JSON requests and responds in JSON via an added
-method to the http.ServerResponse object called `json` (see below).
-
-# Motivation
-Sometimes you want a simple REST API and don't need all the bells and whistles
-of express.js.
-
-# Installation
-
-    npm install json-rest-api
-
-# Example
-
-## server
-
-```JavaScript
-'use strict';
-var JsonRestApi = require('json-rest-api');
-var inspect = require('util').inspect;
-var debug = require('debug')('json-rest-api:example:server');
-
-var RestApi = new JsonRestApi({port: 8000}, function(err) {
-    if (err) {
-        debug('/ping error: '+inspect(err));
-        return;
-    }
-    console.log('Listening on port 8000.');
-
-    // add a "GET" route
-    RestApi.addRoute('get', '/ping', function(req, res, json, qs) {
-        var qsExp = {'alpha': 'one', 'beta': '2', 'gamma': 'true'};
-        assert.deepEqual(qsExp, qs);
-        res.json({success: true, pong: 'pong'});
-    });
+# JSON REST API
+
+A modern, plugin-based JSON REST API library with JSON:API compliance, schema validation, and extensible storage backends.
+
+## Features
+
+- **Plugin Architecture**: Extensible through plugins using `.use()` pattern
+- **JSON:API Compliant**: Follows JSON:API specification for RESTful APIs
+- **Schema Validation**: Built-in schema validation with extensible types and parameters
+- **Multiple Storage Backends**: Memory and MySQL support out of the box
+- **Automatic API Versioning**: Built-in version management with automatic routing
+- **Positioning**: Manage record ordering with drag-and-drop support
+- **Resource Versioning**: Track changes with version history
+- **TypeScript-like Schema**: Define schemas with types, validation rules, and defaults
+- **Hooks System**: Extensible through before/after hooks
+- **Express Integration**: Easy integration with Express.js
+- **Security**: Built-in security plugin with rate limiting, CORS, and authentication
+- **Logging**: Structured logging with sensitive data redaction
+- **OpenAPI**: Auto-generated API documentation
+
+## Installation
+
+```bash
+npm install jsonrestapi
+```
 
-    // add a "POST" route
-    RestApi.addRoute('get', '/setName', function(req, res, json, qs) {
-        var qsExp = {'alpha': 'one', 'beta': '2', 'gamma': 'true'};
+## Quick Start
 
-        assert.deepEqual(qsExp, qs);
-        res.json({success: true, pong: 'pong'});
-    });
+```javascript
+import { createApi, Schema } from 'jsonrestapi';
+import express from 'express';
+
+// Create an API with automatic versioning
+const api = createApi({
+  name: 'myapp',
+  version: '1.0.0',
+  storage: 'memory',
+  http: { basePath: '/api' }
+});
+
+// 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 },
+  active: { type: 'boolean', default: true }
+});
+
+// Register the schema
+api.addResource('users', userSchema);
+
+// Create Express app and mount API
+const app = express();
+api.mount(app);
+
+app.listen(3000);
+```
+
+## Core Concepts
+
+### Schema Definition
+
+Schemas define the structure and validation rules for your data:
+
+```javascript
+const schema = new Schema({
+  // Numeric types
+  id: { type: 'id' },
+  age: { type: 'number', min: 0, max: 150 },
+  price: { type: 'number', currency: true },
+  
+  // String types
+  name: { type: 'string', required: true, min: 2, max: 50 },
+  email: { type: 'string', lowercase: true },
+  description: { type: 'string', max: 1000 },
+  
+  // Boolean type
+  active: { type: 'boolean', default: true },
+  
+  // Date types
+  createdAt: { type: 'timestamp', default: () => Date.now() },
+  birthDate: { type: 'date' },
+  lastLogin: { type: 'dateTime' },
+  
+  // Complex types
+  tags: { type: 'array', default: [] },
+  metadata: { type: 'object' },
+  
+  // Special types
+  data: { type: 'serialize' }, // Circular JSON support
+  file: { type: 'blob' }
 });
 ```
 
-## client
+### Plugin System
+
+Extend functionality through plugins:
+
+```javascript
+const api = new Api();
+
+api
+  .use(ValidationPlugin)
+  .use(MySQLPlugin, { connection: dbConfig })
+  .use(HTTPPlugin, { basePath: '/api' })
+  .use(PositioningPlugin)
+  .use(VersioningPlugin, { trackHistory: true });
+```
+
+### Custom Plugins
 
-```JavaScript
-'use strict';
-var request = require('request');
-var inspect = require('util').inspect;
-var debug = require('debug')('json-rest-api:example:client');
-var assert = require('assert');
+Create your own plugins:
 
-var qs = {
-    alpha: 'one',
-    beta: 2,
-    gamma: true
+```javascript
+const MyPlugin = {
+  install(api, options) {
+    // Add new methods
+    api.myMethod = () => { /* ... */ };
+    
+    // Register hooks
+    api.hook('beforeInsert', async (context) => {
+      // Modify context before insert
+    });
+    
+    // Add custom types
+    api.registerType('myType', ({ value }) => {
+      // Custom type logic
+      return processedValue;
+    });
+  }
 };
 
-request({json:true, qs:qs, uri: 'http://localhost:8000/ping'}, function(err, res, json) {
-    if (err) {
-        debug('Error: '+inspect(err));
-        return;
-    }
+api.use(MyPlugin, { /* options */ });
+```
+
+## API Methods
+
+### CRUD Operations
+
+```javascript
+// Get single resource
+const user = await api.get('123', { type: 'users' });
+
+// Query resources
+const users = await api.query({
+  filter: { active: true },
+  sort: '-createdAt,name',
+  page: { size: 20, number: 1 }
+}, { type: 'users' });
+
+// Insert resource
+const newUser = await api.insert({
+  name: 'John Doe',
+  email: 'john@example.com'
+}, { type: 'users' });
+
+// Update resource
+const updated = await api.update('123', {
+  name: 'Jane Doe'
+}, { type: 'users' });
+
+// Delete resource
+await api.delete('123', { type: 'users' });
+```
+
+### HTTP Endpoints
+
+When using HTTPPlugin, the following endpoints are available:
 
-    assert.ok(json.success === true);
-    assert.ok(json.pong === 'pong');
-    console.log('Success!');
+- `GET /api/{type}` - List resources
+- `GET /api/{type}/{id}` - Get single resource
+- `POST /api/{type}` - Create resource
+- `PATCH /api/{type}/{id}` - Update resource
+- `DELETE /api/{type}/{id}` - Delete resource
+
+Query parameters:
+- `filter[field]=value` - Filter by field
+- `sort=-field1,field2` - Sort by fields
+- `page[size]=10&page[number]=2` - Pagination
+- `include=relation1,relation2` - Include relationships
+
+## Storage Backends
+
+### Memory Storage
+
+```javascript
+api.use(MemoryPlugin, {
+  initialData: [
+    { id: 1, name: 'Item 1' },
+    { id: 2, name: 'Item 2' }
+  ]
+});
+```
+
+### MySQL Storage
+
+```javascript
+api.use(MySQLPlugin, {
+  connection: {
+    host: 'localhost',
+    user: 'root',
+    password: 'password',
+    database: 'myapp'
+  }
 });
 
-request({json:true, qs:qs, uri: 'http://localhost:8000/setName'}, function(err, res, json) {
-    if (err) {
-        debug('Error: '+inspect(err));
-        return;
-    }
+// Sync schema with database
+await api.syncSchema(userSchema, 'users');
+```
+
+## Advanced Features
 
-    var qsExp = {'alpha': 'one', 'beta': '2', 'gamma': 'true'};
+### Positioning
 
-    assert.ok(json.success === true);
-    assert.ok(json.cmd === 'setName');
-    assert.deepEqual(json.qs, qsExp);
-    console.log('Success!');
+Manage record order:
+
+```javascript
+api.use(PositioningPlugin);
+
+// Insert at specific position
+await api.insert({
+  name: 'Item',
+  beforeId: '123' // Place before item with ID 123
+}, {
+  type: 'items',
+  positioning: { enabled: true }
+});
+
+// Reposition existing item
+await api.reposition('items', '456', null); // Move to end
+```
+
+### API Versioning
+
+Create multiple versions of your API with automatic version negotiation:
+
+```javascript
+// Version 1.0.0
+const apiV1 = createApi({
+  name: 'users',
+  version: '1.0.0',
+  storage: 'memory'
+});
+
+apiV1.addResource('users', new Schema({
+  id: { type: 'id' },
+  name: { type: 'string', required: true },
+  email: { type: 'string', required: true }
+}));
+
+// Version 2.0.0 with new fields
+const apiV2 = createApi({
+  name: 'users',
+  version: '2.0.0',
+  storage: 'memory'
 });
+
+apiV2.addResource('users', new Schema({
+  id: { type: 'id' },
+  name: { type: 'string', required: true },
+  email: { type: 'string', required: true },
+  phone: { type: 'string' },  // New field
+  active: { type: 'boolean', default: true }  // New field
+}));
+
+// Automatic version selection
+const api = Api.get('users', 'latest');  // Gets v2.0.0
+const apiV1Compat = Api.get('users', '1.0.0');  // Gets v1.0.0 or higher
+
+// HTTP endpoints with automatic versioning
+// GET /api/1.0.0/users
+// GET /api/2.0.0/users
+// GET /api/users?v=2.0.0
+// GET /api/users (with API-Version: 2.0.0 header)
 ```
 
-# API
+### Resource Versioning
 
-## RestApi([config], [cb])
-RestApi constructor. Creates the HTTP server objects and starts listening on
-the socket.
+Track changes to individual resources:
 
-### Params:
-* **Object** *[config]* Optional configuration object to configure the server.
-  The configuration options are:
-    * bindTo - Optional. The address to bind, default: INADDR_ANY.
-    * port - Optional. The port to bind the server, default: 44401.
-* **Function** *[cb]* An optional callback. If there is a callback, the process
-  will be begin listening on the socket for HTTP requests. Without a callback,
-  you must call listen explicitly.
+```javascript
+api.use(VersioningPlugin, {
+  trackHistory: true,
+  optimisticLocking: true
+});
 
-## listen([cb])
-Start listening on the socket for HTTP requests.
+// Automatic version tracking
+const user = await api.insert({ name: 'John' }, { type: 'users' });
+// user.version = 1
 
-### Params:
-* **Function** *[cb]* An optional callback called when the server is ready.
+const updated = await api.update(user.id, { name: 'Jane' }, { type: 'users' });
+// updated.version = 2
 
-## stop([cb])
-Stops the server from acccepting new connections and listening on the port.
+// Get version history
+const history = await api.getVersionHistory('users', user.id);
 
-### Params:
-* **Function** *[cb]* The callback function. Optional.
+// Restore previous version
+await api.restoreVersion('users', user.id, 1);
 
-## addRoute(verb, path, cb)
-Add a route along with a function to run.
+// Compare versions
+const diff = await api.diffVersions('users', user.id, 1, 2);
+```
 
-### Params:
-* **String** *verb* HTTP verb for route. e.g.: 'get', 'post'.
-* **String** *path* A valid URI path.
-* **Function** *cb* A function to run when the path executes. Which has the
-  following form: fn(req, res, json, qs):
-        * @param {Object} req - Node.js HTTP request object
-        * @param {Object} res - Node.js HTTP response object
-        * @param {Object} json - The JSON body of the request, if present.
-        * @param {Object} qs - The query string of the request, if present.
+### Hooks
 
-### Return:
-* **Boolean|Error** True, if no errors on the parameters, Error
-* **Error|Boolean** true on success and Error on failure.
+Extend behavior with hooks:
 
-## json([status code,] jsonObject)
-A method for the JsonServerResponse prototype to send JSON by passing an object.
+```javascript
+// Validation hooks
+api.hook('beforeValidate', async (context) => {
+  // Modify data before validation
+});
 
-### Params:
-* **Number|Object** *Optional.* First argument may be either the status code or
-  the object to convert to JSON.
-* **Object** *Optional.* If the first object is the status code, then the second
-  param must be the object to convert to JSON.
+api.hook('afterValidate', async (context) => {
+  // Add custom validation
+  if (context.data.price < 0) {
+    context.errors.push({
+      field: 'price',
+      message: 'Price cannot be negative'
+    });
+  }
+});
 
-# LICENSE
+// CRUD hooks
+api.hook('beforeInsert', async (context) => {
+  context.data.createdBy = context.options.userId;
+});
 
-The MIT License (MIT)
+api.hook('transformResult', async (context) => {
+  // Add computed fields
+  if (context.result) {
+    context.result.displayName = context.result.name.toUpperCase();
+  }
+});
+```
 
-Copyright (c) 2013,2014 Edmond Meinfelder
+## Schema Extensions
 
-Permission is hereby granted, free of charge, to any person obtaining a copy of
-this software and associated documentation files (the "Software"), to deal in
-the Software without restriction, including without limitation the rights to
-use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
-the Software, and to permit persons to whom the Software is furnished to do so,
-subject to the following conditions:
+Add custom types and parameters:
 
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
+```javascript
+// Custom type
+schema.registerType('phone', ({ value }) => {
+  const cleaned = value.replace(/\D/g, '');
+  if (cleaned.length !== 10) {
+    throw new Error('Invalid phone number');
+  }
+  return cleaned;
+});
+
+// Custom parameter
+schema.registerParam('unique', async ({ value, fieldName, object }) => {
+  const exists = await checkUniqueness(fieldName, value);
+  if (exists) {
+    throw new Error(`${fieldName} must be unique`);
+  }
+});
+
+// Use in schema
+const schema = new Schema({
+  phone: { type: 'phone', required: true },
+  username: { type: 'string', unique: true }
+});
+```
+
+## Cross-API Communication
+
+APIs can access each other with automatic version compatibility:
+
+```javascript
+// Orders API can access Users API
+const ordersApi = createApi({
+  name: 'orders',
+  version: '1.0.0'
+});
+
+ordersApi.hook('afterInsert', async (context) => {
+  // Automatically gets a compatible users API
+  const usersApi = ordersApi.apis.users;
+  
+  if (usersApi && context.data.userId) {
+    const user = await usersApi.get(context.data.userId, { type: 'users' });
+    console.log('Order created for:', user);
+  }
+});
+```
+
+## Security Best Practices
+
+Enable comprehensive security features:
+
+```javascript
+import { SecurityPlugin, LoggingPlugin } from 'jsonrestapi';
+
+api
+  .use(SecurityPlugin, {
+    rateLimit: { max: 100, windowMs: 15 * 60 * 1000 },
+    authentication: { type: 'bearer', required: true },
+    cors: { origin: 'https://app.example.com' }
+  })
+  .use(LoggingPlugin, {
+    level: 'info',
+    auditLog: true
+  });
+```
+
+## Error Handling
+
+Errors follow JSON:API format:
+
+```javascript
+try {
+  await api.insert({ name: '' }, { type: 'users' });
+} catch (error) {
+  console.log(error.errors);
+  // [{
+  //   status: '422',
+  //   title: 'Validation Error',
+  //   detail: 'Field required',
+  //   source: { pointer: '/data/attributes/name' }
+  // }]
+}
+```
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
-FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
-COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
-IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
-CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+## License
 
+MIT

package/TODO.todo

@@ -0,0 +1,113 @@
+TODO
+
+10. Utility Features
+
+  - Missing from original:
+    - artificial delay for testing <-- ADD!!!
+    - Request decoration pattern <-- I DON'T KNOW WHAT THIS IS, BUT IF IT'S BEST PRACTICE/INDUSTRU STANDARD, TELL ME ABOUT IT
+    - Store inheritance/extension <--- THIS, I NEVER WANTED, NEVER USED IN 10 YEARS IN PRODUCTION
+    - Automatic timestamp fields <-- WOULD BE NICE
+    - Soft delete support <-- WOULD BE NICE BUT I DON'T THINK THE ORIGINAL HAD IT. I WILL IMPLEMENT IT IN THE FUTURE
+
+
+  5. Error Handling
+
+  - Missing structured error classes:
+    - BadRequest, NotFound, Conflict classes
+    - Error code standardization
+    - Multi-field validation errors
+    - Error context preservation
+
+  6. Hook System Gaps
+
+  - Missing hooks from original:
+    - beforeId, afterId
+    - beforeRetrieve, afterRetrieve
+    - beforeInsert, afterInsert (full lifecycle)
+    - queryFieldsAndJoins
+    - updateConditionsAndArgs
+    - deleteConditionsAndArgs
+
+  7. Store Templates
+
+  - No equivalent to storeTemplate.js:
+    - Automatic REST endpoint generation
+    - Built-in authentication handling
+    - Session management
+    - Request/response transformation
+
+  8. Memory Store Features
+
+  - Current memory plugin lacks:
+    - Query operators ($like, $in, $gt, etc.)
+    - Sorting by multiple fields
+    - Limit/offset with total count
+    - Deep object filtering
+
+
+
+  11. JSON:API Compliance Gaps
+
+  - Current HTTP plugin missing:
+    - Proper relationship handling
+    - Compound documents
+    - Sparse fieldsets
+    - Include parameter processing
+    - Meta information structure
+
+  12. Performance Features
+
+  - Not implemented:
+    - Connection pooling configuration
+    - Query result caching
+    - Batch operations
+    - Transaction support across operations
+
+
+
+    **************************************************************************
+    DONE
+    **************************************************************************
+    
+      2. MySQL Schema Synchronization
+
+  - Current MySQL plugin is basic, missing:
+    - Automatic table creation/modification
+    - Column type mapping from schema
+    - Index creation for searchable fields
+    - Foreign key constraint management
+    - Schema migration tracking
+
+  9. Schema Features
+
+  - SimplSchema integration missing:
+    - onlyObjectValues for partial updates
+    - Conditional defaults based on other fields
+    - Array validation with item schemas
+    - Custom error messages per validator
+
+1. Positioning System
+
+  - Current has basic positioning plugin but lacks:
+    - Filtering support during repositioning
+    - Gap-free positioning algorithm
+    - Complex position calculations with conditions
+    - Batch repositioning operations
+
+      3. Advanced Querying
+
+  - Missing query capabilities:
+    - Complex field joins (queryFieldsAndJoins hook)
+    - Nested object queries
+    - Array field queries
+    - Custom SQL conditions
+    - Aggregation support
+
+      4. Versioning Management
+
+  - Current versioning is rudimentary, missing:
+    - Version range negotiation
+    - Store registry with semver matching
+    - Version-specific schema transformations
+    - Backward compatibility helpers
+