json-rest-api 1.0.0 → 1.0.2

package/docs/example.js

@@ -1,195 +0,0 @@
-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/plugins/API guide.md

@@ -1,364 +0,0 @@
-● Programmatic API Usage Guide
-
-  Here's how to use the JSON REST API methods programmatically:
-
-  Basic Setup
-
-  import { createApi, Schema } from './jsonrestapi/index.js';
-
-  // Create API instance
-  const api = createApi({
-    storage: 'memory', // or 'mysql'
-    http: false        // Disable HTTP if using programmatically only
-  });
-
-  // Define a schema
-  const userSchema = new Schema({
-    id: { type: 'id' },
-    name: { type: 'string', required: true },
-    email: { type: 'string', required: true, lowercase: true },
-    age: { type: 'number', min: 0 },
-    active: { type: 'boolean', default: true }
-  });
-
-  // Register schema
-  api.addResource('users', userSchema);
-
-  CRUD Operations
-
-  1. Create (Insert)
-
-  // Simple insert
-  const newUser = await api.insert({
-    name: 'John Doe',
-    email: 'john@example.com',
-    age: 30
-  }, {
-    type: 'users'
-  });
-
-  console.log(newUser);
-  // Output: { data: { id: '1', type: 'users', attributes: { name: 'John 
-  Doe', ... } } }
-
-  // Insert with positioning (if PositioningPlugin is used)
-  const secondUser = await api.insert({
-    name: 'Jane Smith',
-    email: 'jane@example.com',
-    beforeId: null  // Place at end
-  }, {
-    type: 'users',
-    positioning: { enabled: true }
-  });
-
-  2. Read (Get)
-
-  // Get by ID
-  const user = await api.get('1', {
-    type: 'users'
-  });
-
-  console.log(user);
-  // Output: { data: { id: '1', type: 'users', attributes: { ... } } }
-
-  // Handle not found
-  try {
-    const notFound = await api.get('999', { type: 'users' });
-  } catch (error) {
-    console.log('User not found');
-  }
-
-  3. Update
-
-  // Partial update
-  const updated = await api.update('1', {
-    age: 31,
-    active: false
-  }, {
-    type: 'users'
-  });
-
-  // Update with validation context
-  const updateWithContext = await api.update('1', {
-    email: 'newemail@example.com'
-  }, {
-    type: 'users',
-    userId: 'admin-123',  // For audit logging
-    ipAddress: '192.168.1.1'
-  });
-
-  4. Delete
-
-  // Delete by ID
-  await api.delete('1', {
-    type: 'users'
-  });
-
-  // Delete returns { data: null } on success
-
-  5. Query (List)
-
-  // Simple query
-  const allUsers = await api.query({}, {
-    type: 'users'
-  });
-
-  // Advanced query with filters
-  const activeAdults = await api.query({
-    filter: {
-      active: true,
-      age: { $gte: 18 }  // If your storage plugin supports operators
-    },
-    sort: '-age,name',    // Sort by age DESC, then name ASC
-    page: {
-      size: 20,
-      number: 1
-    }
-  }, {
-    type: 'users'
-  });
-
-  console.log(activeAdults);
-  // Output: {
-  //   data: [ { id: '1', type: 'users', attributes: {...} }, ... ],
-  //   meta: { total: 45, pageSize: 20, pageNumber: 1, totalPages: 3 },
-  //   links: { self: '...', next: '...', last: '...' }
-  // }
-
-  // Search (if configured)
-  const searchResults = await api.query({
-    search: 'john',
-    filter: { active: true }
-  }, {
-    type: 'users',
-    searchFields: ['name', 'email']
-  });
-
-  Advanced Usage
-
-  With MySQL Storage
-
-  import { Api, MySQLPlugin, ValidationPlugin } from
-  './jsonrestapi/index.js';
-
-  const api = new Api()
-    .use(ValidationPlugin)
-    .use(MySQLPlugin, {
-      connection: {
-        host: 'localhost',
-        user: 'root',
-        password: 'password',
-        database: 'myapp'
-      }
-    });
-
-  // Sync schema with database
-  await api.syncSchema(userSchema, 'users');
-
-  // Use with table specification
-  const user = await api.insert({
-    name: 'Database User',
-    email: 'db@example.com'
-  }, {
-    type: 'users',
-    table: 'users',  // MySQL table name
-    connection: 'default'
-  });
-
-  With Authentication Context
-
-  // Add security plugin
-  api.use(SecurityPlugin);
-
-  // All operations can include auth context
-  const result = await api.insert({
-    title: 'Secure Post',
-    content: 'This is secure'
-  }, {
-    type: 'posts',
-    userId: 'user-123',      // From decoded JWT
-    authenticated: true,
-    permissions: ['create', 'read']
-  });
-
-  Batch Operations
-
-  // Insert multiple records
-  const users = [
-    { name: 'User 1', email: 'user1@example.com' },
-    { name: 'User 2', email: 'user2@example.com' },
-    { name: 'User 3', email: 'user3@example.com' }
-  ];
-
-  const created = await Promise.all(
-    users.map(user => api.insert(user, { type: 'users' }))
-  );
-
-  // Update multiple records
-  const updates = [
-    { id: '1', data: { active: false } },
-    { id: '2', data: { active: false } },
-    { id: '3', data: { active: false } }
-  ];
-
-  await Promise.all(
-    updates.map(({ id, data }) =>
-      api.update(id, data, { type: 'users' })
-    )
-  );
-
-  With Transactions (MySQL)
-
-  // Get connection pool
-  const { pool } = api.getConnection();
-  const connection = await pool.getConnection();
-
-  try {
-    await connection.beginTransaction();
-
-    // Create user
-    const user = await api.insert({
-      name: 'Transaction User',
-      email: 'tx@example.com'
-    }, {
-      type: 'users',
-      connection  // Pass connection for transaction
-    });
-
-    // Create related profile
-    await api.insert({
-      userId: user.data.id,
-      bio: 'Created in transaction'
-    }, {
-      type: 'profiles',
-      connection
-    });
-
-    await connection.commit();
-  } catch (error) {
-    await connection.rollback();
-    throw error;
-  } finally {
-    connection.release();
-  }
-
-  With Custom Validation
-
-  // Add custom validation hook
-  api.hook('afterValidate', async (context) => {
-    if (context.options.type === 'users') {
-      const { data, method } = context;
-
-      // Check email uniqueness
-      if ((method === 'insert' || method === 'update') && data.email) {
-        const existing = await api.query({
-          filter: { email: data.email }
-        }, { type: 'users' });
-
-        if (existing.data.length > 0) {
-          context.errors.push({
-            field: 'email',
-            message: 'Email already exists',
-            code: 'DUPLICATE_EMAIL'
-          });
-        }
-      }
-    }
-  });
-
-  Error Handling
-
-  try {
-    const user = await api.insert({
-      name: 'J',  // Too short!
-      email: 'invalid-email'
-    }, { type: 'users' });
-  } catch (error) {
-    if (error.errors) {
-      // Validation errors
-      error.errors.forEach(err => {
-        console.log(`${err.field}: ${err.message}`);
-      });
-    } else {
-      // Other errors
-      console.error('Unexpected error:', error);
-    }
-  }
-
-  Direct Storage Access
-
-  // If you need direct access to storage
-  if (api.memoryData) {
-    // Direct memory access
-    console.log('All data:', api.memoryData);
-  }
-
-  if (api.mysqlPools) {
-    // Direct MySQL access
-    const { pool } = api.getConnection();
-    const [rows] = await pool.query('SELECT * FROM users WHERE active = ?',
-   [true]);
-  }
-
-  Complete Example: Task Manager
-
-  import { createApi, Schema, PositioningPlugin } from
-  './jsonrestapi/index.js';
-
-  // Create API
-  const api = createApi({ storage: 'memory' })
-    .use(PositioningPlugin);
-
-  // Define schema
-  const taskSchema = new Schema({
-    id: { type: 'id' },
-    title: { type: 'string', required: true, min: 1, max: 200 },
-    description: { type: 'string', max: 1000 },
-    completed: { type: 'boolean', default: false },
-    priority: { type: 'string', enum: ['low', 'medium', 'high'], default:
-  'medium' },
-    dueDate: { type: 'date' },
-    position: { type: 'number' },
-    createdAt: { type: 'timestamp', default: () => Date.now() }
-  });
-
-  api.addResource('tasks', taskSchema);
-
-  // Usage
-  async function taskManager() {
-    // Create tasks
-    const task1 = await api.insert({
-      title: 'Write documentation',
-      priority: 'high',
-      dueDate: '2024-12-31'
-    }, { type: 'tasks' });
-
-    const task2 = await api.insert({
-      title: 'Review PR',
-      priority: 'medium',
-      beforeId: task1.data.id  // Position before first task
-    }, {
-      type: 'tasks',
-      positioning: { enabled: true }
-    });
-
-    // List high priority incomplete tasks
-    const urgent = await api.query({
-      filter: {
-        completed: false,
-        priority: 'high'
-      },
-      sort: 'position,dueDate'
-    }, { type: 'tasks' });
-
-    console.log(`Found ${urgent.meta.total} urgent tasks`);
-
-    // Complete a task
-    await api.update(task1.data.id, {
-      completed: true
-    }, { type: 'tasks' });
-
-    // Reorder tasks
-    await api.reposition('tasks', task2.data.id, null); // Move to end
-  }
-

package/plugins/api-registry.js

@@ -1,142 +0,0 @@
-import semver from 'semver';
-
-/**
- * API Registry Plugin - Automatic version management
- */
-export const ApiRegistryPlugin = {
-  install(api, options = {}) {
-    // Initialize the global registry if it doesn't exist
-    if (!globalThis.__jsonRestApiRegistry) {
-      globalThis.__jsonRestApiRegistry = new ApiRegistry();
-    }
-    
-    const registry = globalThis.__jsonRestApiRegistry;
-    
-    // Register this API instance
-    const apiName = options.name || api.options.name;
-    const apiVersion = options.version || api.options.version;
-    
-    if (!apiName || !apiVersion) {
-      throw new Error('API name and version are required for registration');
-    }
-    
-    api.apiName = apiName;
-    api.apiVersion = apiVersion;
-    
-    // Register in global registry
-    registry.register(apiName, apiVersion, api);
-    
-    // Add version resolution to the API
-    api.apis = new Proxy({}, {
-      get(target, prop) {
-        const requestedVersion = api.apiVersion;
-        return registry.getCompatibleApi(prop, requestedVersion);
-      }
-    });
-    
-    // Override HTTP routes to handle version negotiation
-    if (api.router) {
-      const originalMount = api.mount;
-      api.mount = function(app, basePath = '/api') {
-        // Mount versioned routes
-        const versionPath = `${basePath}/${apiVersion}`;
-        originalMount.call(api, app, versionPath);
-        
-        // Also mount on base path with version negotiation
-        app.use(`${basePath}/:apiName/*`, (req, res, next) => {
-          const requestedVersion = 
-            req.headers['api-version'] || 
-            req.headers['x-api-version'] || 
-            req.query.v ||
-            'latest';
-          
-          const compatibleApi = registry.getCompatibleApi(
-            req.params.apiName, 
-            requestedVersion
-          );
-          
-          if (!compatibleApi) {
-            return res.status(400).json({
-              errors: [{
-                status: '400',
-                title: 'Version Not Found',
-                detail: `No compatible version found for ${req.params.apiName} ${requestedVersion}`
-              }]
-            });
-          }
-          
-          // Forward to the compatible API
-          req.url = req.url.replace(`/${req.params.apiName}`, '');
-          compatibleApi.router(req, res, next);
-        });
-        
-        return api;
-      };
-    }
-  }
-};
-
-/**
- * Global API Registry
- */
-class ApiRegistry {
-  constructor() {
-    this.apis = new Map(); // name -> version -> api
-  }
-  
-  register(name, version, api) {
-    if (!this.apis.has(name)) {
-      this.apis.set(name, new Map());
-    }
-    
-    const versions = this.apis.get(name);
-    versions.set(version, api);
-    
-    // Sort versions for efficient lookup
-    const sortedVersions = Array.from(versions.entries())
-      .sort(([a], [b]) => semver.compare(b, a));
-    
-    this.apis.set(name, new Map(sortedVersions));
-  }
-  
-  getCompatibleApi(name, versionSpec) {
-    const versions = this.apis.get(name);
-    if (!versions) return null;
-    
-    // Special case: latest
-    if (versionSpec === 'latest') {
-      return versions.values().next().value;
-    }
-    
-    // Exact match
-    if (versions.has(versionSpec)) {
-      return versions.get(versionSpec);
-    }
-    
-    // Find compatible version
-    for (const [version, api] of versions) {
-      if (semver.satisfies(version, versionSpec)) {
-        return api;
-      }
-    }
-    
-    // Fallback: find any version >= requested
-    if (!versionSpec.includes('>') && !versionSpec.includes('<') && !versionSpec.includes('^') && !versionSpec.includes('~')) {
-      for (const [version, api] of versions) {
-        if (semver.gte(version, versionSpec)) {
-          return api;
-        }
-      }
-    }
-    
-    return null;
-  }
-  
-  getAllVersions(name) {
-    const versions = this.apis.get(name);
-    return versions ? Array.from(versions.keys()) : [];
-  }
-}
-
-// Export the registry for direct access if needed
-export const apiRegistry = globalThis.__jsonRestApiRegistry || new ApiRegistry();