json-rest-api 0.1.0 → 1.0.0

package/docs/RESOURCES_IN_EXPRESS.md

@@ -0,0 +1,456 @@
+# Organizing Resources in Express with jsonrestapi
+
+This guide shows you how to organize your API resources in a scalable, maintainable way with minimal server setup.
+
+## Directory Structure
+
+```
+project/
+├── server.js
+├── api/
+│   ├── 1.0.0/
+│   │   ├── users.js      # Self-contained users resource
+│   │   ├── products.js   # Self-contained products resource
+│   │   └── orders.js     # Self-contained orders resource
+│   └── 2.0.0/
+│       ├── users.js      # Updated users resource
+│       ├── products.js   # Updated products resource
+│       └── orders.js     # Orders resource
+└── config/
+    └── database.js       # Database configuration
+```
+
+## Resource File Structure
+
+Each resource file is self-contained and handles its own setup.
+
+### Example: api/1.0.0/users.js
+
+```javascript
+import { Api, Schema, MySQLPlugin, ValidationPlugin, HTTPPlugin } from 'jsonrestapi';
+import { dbConfig } from '../../config/database.js';
+
+// Get or create the API instance for this version
+const api = Api.get('myapp', '1.0.0') || new Api({ 
+  name: 'myapp', 
+  version: '1.0.0' 
+});
+
+// Ensure plugins are loaded (safe to call multiple times)
+api
+  .use(ValidationPlugin)
+  .use(MySQLPlugin, {
+    connections: [{
+      name: 'main',
+      config: dbConfig
+    }]
+  })
+  .use(HTTPPlugin, {
+    basePath: '/api/1.0.0'
+  });
+
+// Define schema
+const userSchema = new Schema({
+  id: { type: 'id' },
+  username: { type: 'string', required: true, min: 3, max: 50 },
+  email: { type: 'string', required: true, lowercase: true },
+  password: { type: 'string', required: true, min: 8 },
+  firstName: { type: 'string', max: 100 },
+  lastName: { type: 'string', max: 100 },
+  role: { type: 'string', default: 'user' },
+  active: { type: 'boolean', default: true },
+  createdAt: { type: 'timestamp', default: () => Date.now() },
+  updatedAt: { type: 'timestamp' }
+});
+
+// Define hooks for this resource
+const userHooks = {
+  async afterValidate(context) {
+    const { data, method, errors } = context;
+    
+    if (method === 'insert' || method === 'update') {
+      // Check for duplicate email
+      const existing = await context.api.query({
+        filter: { email: data.email }
+      }, { type: 'users' });
+      
+      if (existing.meta.total > 0 && existing.results[0].id !== data.id) {
+        errors.push({
+          field: 'email',
+          message: 'Email already in use',
+          code: 'DUPLICATE_EMAIL'
+        });
+      }
+    }
+  },
+  
+  async transformResult(context) {
+    const { result } = context;
+    
+    // Never return password field
+    if (result && result.attributes) {
+      delete result.attributes.password;
+    }
+    
+    // Add computed fields
+    if (result && result.attributes) {
+      result.attributes.fullName = 
+        `${result.attributes.firstName || ''} ${result.attributes.lastName || ''}`.trim();
+    }
+  },
+  
+  async beforeInsert(context) {
+    const { data } = context;
+    
+    // Hash password before storing
+    if (data.password) {
+      const bcrypt = await import('bcrypt');
+      data.password = await bcrypt.hash(data.password, 10);
+    }
+    
+    // Set timestamps
+    data.createdAt = Date.now();
+    data.updatedAt = Date.now();
+  }
+};
+
+// Add the resource with schema and hooks
+api.addResource('users', userSchema, userHooks);
+
+// Export for server to mount
+export default api;
+```
+
+### Even Cleaner Approach with Shared Configuration
+
+The library includes a helper that manages shared API instances per version:
+
+```javascript
+// api/config.js - Shared configuration
+import { dbConfig } from '../config/database.js';
+
+export const apiConfig = {
+  name: 'myapp',
+  mysql: {
+    connections: [{
+      name: 'main',
+      config: dbConfig
+    }]
+  },
+  http: {
+    // Additional HTTP options
+  }
+};
+```
+
+Then use the helper in your resources:
+
+```javascript
+// api/1.0.0/users.js
+import { Schema, defineResource } from 'jsonrestapi/resource-helper.js';
+import { apiConfig } from '../config.js';
+
+export default defineResource('1.0.0', 'users', {
+  api: apiConfig, // Shared configuration
+  schema: new Schema({
+    id: { type: 'id' },
+    username: { type: 'string', required: true, min: 3, max: 50 },
+    email: { type: 'string', required: true, lowercase: true },
+    password: { type: 'string', required: true, min: 8 },
+    firstName: { type: 'string', max: 100 },
+    lastName: { type: 'string', max: 100 },
+    role: { type: 'string', default: 'user' },
+    active: { type: 'boolean', default: true },
+    createdAt: { type: 'timestamp', default: () => Date.now() },
+    updatedAt: { type: 'timestamp' }
+  }),
+  
+  storage: {
+    table: 'users',
+    searchFields: ['username', 'email', 'firstName', 'lastName']
+  },
+  
+  hooks: {
+    async afterValidate(context) {
+      const { data, method, errors } = context;
+      
+      if (method === 'insert' || method === 'update') {
+        const existing = await context.api.query({
+          filter: { email: data.email }
+        }, { type: 'users' });
+        
+        if (existing.meta.total > 0 && existing.results[0].id !== data.id) {
+          errors.push({
+            field: 'email',
+            message: 'Email already in use',
+            code: 'DUPLICATE_EMAIL'
+          });
+        }
+      }
+    },
+    
+    async transformResult(context) {
+      const { result } = context;
+      
+      if (result?.attributes) {
+        delete result.attributes.password;
+        result.attributes.fullName = 
+          `${result.attributes.firstName || ''} ${result.attributes.lastName || ''}`.trim();
+      }
+    },
+    
+    async beforeInsert(context) {
+      const bcrypt = await import('bcrypt');
+      context.data.password = await bcrypt.hash(context.data.password, 10);
+      context.data.createdAt = Date.now();
+      context.data.updatedAt = Date.now();
+    }
+  }
+});
+```
+
+## Minimal Server Setup
+
+### Option 1: Manual Loading (Most Control)
+
+```javascript
+// server.js
+import express from 'express';
+import session from 'express-session';
+
+const app = express();
+
+// Middleware
+app.use(express.json());
+app.use(session({
+  secret: process.env.SESSION_SECRET,
+  resave: false,
+  saveUninitialized: false
+}));
+
+// Load all resources - ONE LINE PER RESOURCE!
+const apis = [
+  await import('./api/1.0.0/users.js'),
+  await import('./api/1.0.0/products.js'),
+  await import('./api/1.0.0/orders.js'),
+  await import('./api/2.0.0/users.js'),
+  await import('./api/2.0.0/products.js'),
+  await import('./api/2.0.0/orders.js'),
+];
+
+// Mount all APIs - that's it!
+apis.forEach(module => module.default.mount(app));
+
+// Start server
+app.listen(3000, () => {
+  console.log('Server running on http://localhost:3000');
+});
+```
+
+### Option 2: Auto-Loading (Like the Old Library)
+
+Create a helper function:
+
+```javascript
+// load-resources.js
+import { readdir } from 'fs/promises';
+import { join } from 'path';
+
+export async function loadResourcesFromPath(apiPath, app) {
+  const versions = await readdir(apiPath);
+  
+  for (const version of versions) {
+    const versionPath = join(apiPath, version);
+    const files = await readdir(versionPath);
+    
+    for (const file of files) {
+      if (file.endsWith('.js')) {
+        const module = await import(join(versionPath, file));
+        if (module.default?.mount) {
+          module.default.mount(app);
+        }
+      }
+    }
+  }
+}
+```
+
+Then in your server:
+
+```javascript
+// server.js
+import express from 'express';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { loadResourcesFromPath } from './load-resources.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const app = express();
+
+app.use(express.json());
+
+// ONE LINE to load everything!
+await loadResourcesFromPath(join(__dirname, 'api'), app);
+
+app.listen(3000, () => {
+  console.log('Server running on http://localhost:3000');
+});
+```
+
+## Programmatic Access Between Resources
+
+Resources that share an API instance can interact with each other using the new intuitive API:
+
+```javascript
+// api/1.0.0/orders.js
+import { Api, Schema } from 'jsonrestapi';
+
+const api = Api.get('myapp', '1.0.0');
+
+// Define orders schema
+const orderSchema = new Schema({
+  id: { type: 'id' },
+  userId: { type: 'id', required: true },
+  productId: { type: 'id', required: true },
+  quantity: { type: 'number', min: 1 },
+  status: { type: 'string', default: 'pending' }
+});
+
+const orderHooks = {
+  async afterInsert(context) {
+    const { result } = context;
+    const order = result.data;
+    
+    // Access other resources using the intuitive API
+    const user = await api.resources.users.get(order.attributes.userId);
+    const product = await api.resources.products.get(order.attributes.productId);
+    
+    // Send email notification
+    await sendOrderConfirmation(user.data.attributes.email, {
+      order,
+      product: product.data.attributes
+    });
+  },
+  
+  async transformResult(context) {
+    const { result } = context;
+    
+    if (result?.data) {
+      // Enrich order with user and product data
+      const [user, product] = await Promise.all([
+        api.resources.users.get(result.data.attributes.userId),
+        api.resources.products.get(result.data.attributes.productId)
+      ]);
+      
+      result.data.relationships = {
+        user: { data: { type: 'users', id: user.data.id } },
+        product: { data: { type: 'products', id: product.data.id } }
+      };
+      
+      result.included = [
+        user.data,
+        product.data
+      ];
+    }
+  }
+};
+
+api.addResource('orders', orderSchema, orderHooks);
+
+export default api;
+```
+
+## Adding Authentication/Permissions
+
+You can add middleware to your resources:
+
+```javascript
+// api/1.0.0/secure-resource.js
+import { Schema } from 'jsonrestapi';
+import { createResource } from '../resource-helper.js';
+
+const api = createResource('1.0.0', 'secrets', {
+  schema: new Schema({
+    id: { type: 'id' },
+    content: { type: 'string', required: true },
+    level: { type: 'number', default: 1 }
+  })
+});
+
+// Add authentication middleware
+api.useMiddleware((req, res, next) => {
+  if (!req.session?.userId) {
+    return res.status(401).json({ 
+      error: 'Authentication required' 
+    });
+  }
+  next();
+});
+
+// Or use hooks for fine-grained control
+api.hook('beforeOperation', async (context) => {
+  if (context.options.type !== 'secrets') return;
+  
+  const { method, request } = context;
+  
+  if (!request.session?.userId) {
+    throw Object.assign(new Error('Authentication required'), { 
+      status: 401 
+    });
+  }
+  
+  if (method === 'delete' && request.session.role !== 'admin') {
+    throw Object.assign(new Error('Admin access required'), { 
+      status: 403 
+    });
+  }
+});
+
+export default api;
+```
+
+## Why Not Use createApi()?
+
+You might wonder why we don't use `createApi()` in each resource file. Here's why:
+
+1. **Shared Instance**: All resources in a version should share the same API instance, not create separate ones
+2. **Single Configuration**: Database connections, plugins, etc. should be configured once per version
+3. **Resource Interaction**: Resources can query each other when they share an API instance
+4. **Memory Efficiency**: One connection pool, one router, one set of hooks per version
+
+The `defineResource()` helper gives us the best of both worlds:
+- Simple like `createApi()`
+- But properly manages shared instances
+- Allows resource-specific configuration
+
+## Benefits
+
+1. **Minimal Server Code**: Server setup is just a few lines
+2. **Self-Contained Resources**: Each resource file has everything it needs
+3. **No Repetition**: The helper function eliminates boilerplate
+4. **Easy to Add Resources**: Just create a file and it works
+5. **Version Isolation**: Each version's resources are independent
+6. **Familiar Pattern**: Similar to the old library's approach but cleaner
+
+## Quick Start
+
+1. Create your resource file:
+```javascript
+// api/1.0.0/my-resource.js
+import { Schema } from 'jsonrestapi';
+import { createResource } from '../resource-helper.js';
+
+export default createResource('1.0.0', 'my-resource', {
+  schema: new Schema({
+    id: { type: 'id' },
+    name: { type: 'string', required: true }
+  })
+});
+```
+
+2. That's it! The resource is automatically available at:
+   - GET /api/1.0.0/my-resource
+   - GET /api/1.0.0/my-resource/:id
+   - POST /api/1.0.0/my-resource
+   - PATCH /api/1.0.0/my-resource/:id
+   - DELETE /api/1.0.0/my-resource/:id

package/docs/example-versioning.js

@@ -0,0 +1,168 @@
+import express from 'express';
+import { Api, Schema, createApi } from './index.js';
+
+// Example: Automatic API Versioning
+// The library handles all version negotiation automatically!
+
+// Version 1.0.0 - Original User API
+const userApiV1 = createApi({
+  name: 'users',
+  version: '1.0.0',
+  storage: 'memory'
+});
+
+const userSchemaV1 = new Schema({
+  id: { type: 'id' },
+  name: { type: 'string', required: true },
+  email: { type: 'string', required: true }
+});
+
+userApiV1.addResource('users', userSchemaV1);
+
+// Version 2.0.0 - Added phone number
+const userApiV2 = createApi({
+  name: 'users',
+  version: '2.0.0',
+  storage: 'memory'
+});
+
+const userSchemaV2 = 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!
+});
+
+userApiV2.addResource('users', userSchemaV2);
+
+// Version 2.1.0 - Added address
+const userApiV2_1 = createApi({
+  name: 'users',
+  version: '2.1.0',
+  storage: 'memory'
+});
+
+const userSchemaV2_1 = new Schema({
+  id: { type: 'id' },
+  name: { type: 'string', required: true },
+  email: { type: 'string', required: true },
+  phone: { type: 'string' },
+  active: { type: 'boolean', default: true },
+  address: { type: 'object' }  // New field!
+});
+
+userApiV2_1.addResource('users', userSchemaV2_1);
+
+// USAGE - The library handles version selection automatically!
+
+// 1. Get specific version
+const api1 = Api.get('users', '1.0.0');
+console.log('Got v1.0.0:', api1.options.version);
+
+// 2. Get latest version
+const apiLatest = Api.get('users', 'latest');
+console.log('Got latest:', apiLatest.options.version); // 2.1.0
+
+// 3. Get minimum version (2.0.0 or higher)
+const api2Plus = Api.get('users', '2.0.0');
+console.log('Got 2.0.0+:', api2Plus.options.version); // 2.1.0 (highest compatible)
+
+// 4. From within an API, access other APIs automatically
+const ordersApi = createApi({
+  name: 'orders',
+  version: '1.0.0',
+  storage: 'memory'
+});
+
+// The orders API can access the users API automatically
+ordersApi.hook('afterInsert', async (context) => {
+  if (context.options.type === 'orders') {
+    // This automatically gets a compatible users API!
+    const usersApi = ordersApi.apis.users;
+    
+    if (usersApi) {
+      const user = await usersApi.get(context.data.userId, { type: 'users' });
+      console.log('Order created for user:', user);
+    }
+  }
+});
+
+// 5. Express setup with automatic version routing
+const app = express();
+
+// Mount all versions - the library handles routing!
+userApiV1.mount(app, '/api');    // Available at /api/1.0.0/users
+userApiV2.mount(app, '/api');    // Available at /api/2.0.0/users
+userApiV2_1.mount(app, '/api');  // Available at /api/2.1.0/users
+
+// Version negotiation middleware
+app.use('/api/users/*', (req, res, next) => {
+  // Get requested version from header or query
+  const requestedVersion = 
+    req.headers['api-version'] || 
+    req.query.v || 
+    'latest';
+  
+  // Library finds the right version automatically
+  const api = Api.get('users', requestedVersion);
+  
+  if (!api) {
+    return res.status(404).json({
+      errors: [{
+        status: '404',
+        title: 'Version Not Found',
+        detail: `No compatible version for users API ${requestedVersion}`
+      }]
+    });
+  }
+  
+  // Forward to the correct API version
+  api.router(req, res, next);
+});
+
+// 6. Programmatic usage with automatic version selection
+async function createUser(data, minVersion = '1.0.0') {
+  // Get a compatible API automatically
+  const api = Api.get('users', minVersion);
+  
+  if (!api) {
+    throw new Error(`No users API version >= ${minVersion}`);
+  }
+  
+  return api.insert(data, { type: 'users' });
+}
+
+// This works with v1.0.0 data
+await createUser({
+  name: 'John Doe',
+  email: 'john@example.com'
+}, '1.0.0');
+
+// This requires v2.0.0+ for phone field
+await createUser({
+  name: 'Jane Doe',
+  email: 'jane@example.com',
+  phone: '+1234567890'
+}, '2.0.0');
+
+// Client examples:
+
+// Via header
+fetch('/api/users', {
+  headers: {
+    'API-Version': '2.0.0'  // Get v2.0.0 or higher
+  }
+});
+
+// Via query parameter
+fetch('/api/users?v=1.0.0');  // Get exactly v1.0.0
+
+// Via path (automatic routing)
+fetch('/api/2.1.0/users');  // Get exactly v2.1.0
+
+// Show all registered APIs
+console.log('Registered APIs:', Api.getRegistry());
+// Output: { users: ['2.1.0', '2.0.0', '1.0.0'] }
+
+export { userApiV1, userApiV2, userApiV2_1 };