json-rest-api 1.0.0 → 1.0.2

package/docs/mini-guides/file-uploads-complete.md

@@ -0,0 +1,159 @@
+# Complete File Upload Example with Multiple Files
+
+This guide shows a complete example of implementing file uploads with jsonrestapi, including:
+- Multiple file fields (images and PDFs)
+- Different storage configurations for different file types
+- HTML form for testing uploads
+- Express static file serving
+
+## Complete Example
+
+```javascript
+import { Api } from 'hooked-api';
+import { RestApiPlugin, FileHandlingPlugin, ExpressPlugin } from 'json-rest-api';
+import { LocalStorage } from 'json-rest-api/plugins/storage/local-storage.js';
+import express from 'express';
+
+// Create API
+const api = new Api({
+  name: 'my-library-api',
+  version: '1.0.0'
+});
+
+// Create storage for different file types
+const coverStorage = new LocalStorage({
+  directory: './uploads/covers',
+  baseUrl: 'http://localhost:3000/uploads/covers',
+  nameStrategy: 'hash',
+  allowedExtensions: ['.jpg', '.jpeg', '.png', '.gif']
+});
+
+const pdfStorage = new LocalStorage({
+  directory: './uploads/pdfs',
+  baseUrl: 'http://localhost:3000/uploads/pdfs',
+  nameStrategy: 'timestamp'
+});
+
+// Use plugins
+api.use(RestApiPlugin);
+api.use(FileHandlingPlugin);
+api.use(ExpressPlugin);  // File parser configuration shown in connector plugins section
+
+// Define schema with multiple file fields
+api.addResource('books', {
+  schema: {
+    title: { type: 'string', required: true },
+    author: { type: 'string', required: true },
+    year: { type: 'number' },
+    cover: {
+      type: 'file',
+      storage: coverStorage,
+      accepts: ['image/*'],
+      maxSize: '5mb'
+    },
+    sample: {
+      type: 'file',
+      storage: pdfStorage,
+      accepts: ['application/pdf'],
+      maxSize: '10mb',
+      required: false
+    }
+  }
+});
+
+// Simple data helpers
+api.vars.helpers.dataPost = async ({ scopeName, inputRecord }) => {
+  const newBook = {
+    id: String(Date.now()),
+    ...inputRecord.data.attributes
+  };
+  
+  console.log('Created book:', newBook);
+  
+  return {
+    data: {
+      type: 'books',
+      id: newBook.id,
+      attributes: newBook
+    }
+  };
+};
+
+api.vars.helpers.dataQuery = async () => {
+  return { data: [] };
+};
+
+// Express setup
+const app = express();
+app.use('/uploads', express.static('./uploads'));
+
+// Test form
+app.get('/', (req, res) => {
+  res.send(`
+    <form action="/api/books" method="POST" enctype="multipart/form-data">
+      <h2>Add a Book</h2>
+      <p>Title: <input name="title" required></p>
+      <p>Author: <input name="author" required></p>
+      <p>Year: <input name="year" type="number"></p>
+      <p>Cover: <input name="cover" type="file" accept="image/*"></p>
+      <p>Sample PDF: <input name="sample" type="file" accept=".pdf"></p>
+      <button type="submit">Add Book</button>
+    </form>
+  `);
+});
+
+api.express.mount(app);
+
+app.listen(3000, () => {
+  console.log('Library API running at http://localhost:3000');
+  console.log('Test form at http://localhost:3000');
+  console.log('API endpoints at http://localhost:3000/api/books');
+});
+```
+
+Remember to install the required peer dependency:
+
+```bash
+npm install busboy
+```
+
+## Key Features Demonstrated
+
+### Multiple Storage Configurations
+
+The example shows how to create different storage configurations for different file types:
+- **Cover images**: Use hash naming strategy and restrict to image files
+- **PDF samples**: Use timestamp naming strategy for PDFs
+
+### HTML Test Form
+
+The example includes a simple HTML form for testing file uploads without needing external tools.
+
+### Static File Serving
+
+The Express app serves uploaded files directly:
+```javascript
+app.use('/uploads', express.static('./uploads'));
+```
+
+This allows uploaded files to be accessed via URLs like:
+- `http://localhost:3000/uploads/covers/abc123.jpg`
+- `http://localhost:3000/uploads/pdfs/1234567890.pdf`
+
+## Testing the Example
+
+1. Run the server
+2. Open http://localhost:3000 in your browser
+3. Fill out the form and select files
+4. Submit to see the file upload in action
+5. Check the console for the created book data
+6. Access uploaded files via their URLs
+
+## Next Steps
+
+- Add validation for file types
+- Implement file deletion when records are deleted
+- Add image resizing for covers
+- Generate thumbnails
+- Add virus scanning for uploaded files
+- Implement S3 storage for production

package/examples/express-example.js

@@ -0,0 +1,262 @@
+import express from 'express';
+import { Api } from './index.js';
+import { RestApiPlugin } from './rest-api-plugin.js';
+import { ExpressPlugin } from './express-plugin.js';
+
+// Create an Express app
+const app = express();
+
+// Create API instance
+const api = new Api({
+  name: 'blog-api',
+  version: '1.0.0'
+});
+
+// Install plugins
+api.use(RestApiPlugin, {
+  idProperty: 'id',
+  pageSize: 10,
+  sortableFields: ['title', 'created_at']
+});
+
+api.use(ExpressPlugin, {
+  basePath: '/api',
+  strictContentType: false, // Make testing easier
+  requestSizeLimit: '5mb'
+});
+
+// Define a simple articles scope
+api.addScope('articles', {
+  schema: {
+    id: { type: 'id' },
+    title: { type: 'string', required: true, max: 200 },
+    body: { type: 'string', required: true },
+    author_id: { belongsTo: 'users', as: 'author' },
+    created_at: { type: 'dateTime', default: () => new Date().toISOString() }
+  },
+  relationships: {
+    comments: { hasMany: 'comments' },
+    tags: { hasMany: 'tags', through: 'article_tags' }
+  }
+});
+
+// Define users scope
+api.addScope('users', {
+  schema: {
+    id: { type: 'id' },
+    name: { type: 'string', required: true },
+    email: { type: 'string', required: true }
+  },
+  relationships: {
+    articles: { hasMany: 'articles', foreignKey: 'author_id' }
+  }
+});
+
+// Mock storage plugin for demonstration
+const MockStoragePlugin = {
+  name: 'mock-storage',
+  install({ helpers }) {
+    // Mock data
+    const articles = [
+      { 
+        id: 1, 
+        title: 'First Article', 
+        body: 'This is the first article', 
+        author_id: 1,
+        created_at: '2024-01-01T10:00:00Z'
+      },
+      { 
+        id: 2, 
+        title: 'Second Article', 
+        body: 'This is the second article', 
+        author_id: 2,
+        created_at: '2024-01-02T10:00:00Z'
+      }
+    ];
+    
+    const users = [
+      { id: 1, name: 'John Doe', email: 'john@example.com' },
+      { id: 2, name: 'Jane Smith', email: 'jane@example.com' }
+    ];
+    
+    // Implement storage helpers
+    helpers.dataExists = async function({ scopeName, id }) {
+      if (scopeName === 'articles') {
+        return articles.some(a => a.id == id);
+      }
+      if (scopeName === 'users') {
+        return users.some(u => u.id == id);
+      }
+      return false;
+    };
+    
+    helpers.dataGet = async function({ scopeName, id }) {
+      let record;
+      if (scopeName === 'articles') {
+        record = articles.find(a => a.id == id);
+      } else if (scopeName === 'users') {
+        record = users.find(u => u.id == id);
+      }
+      
+      if (!record) {
+        const { RestApiResourceError } = await import('./rest-api-errors.js');
+        throw new RestApiResourceError(`${scopeName} with id ${id} not found`, {
+          subtype: 'not_found',
+          resourceType: scopeName,
+          resourceId: id
+        });
+      }
+      
+      return {
+        data: {
+          type: scopeName,
+          id: String(record.id),
+          attributes: { ...record, id: undefined }
+        }
+      };
+    };
+    
+    helpers.dataQuery = async function({ scopeName, queryParams }) {
+      let records = [];
+      if (scopeName === 'articles') {
+        records = [...articles];
+      } else if (scopeName === 'users') {
+        records = [...users];
+      }
+      
+      // Simple sorting
+      if (queryParams.sort && queryParams.sort.length > 0) {
+        records.sort((a, b) => {
+          for (const sortField of queryParams.sort) {
+            const desc = sortField.startsWith('-');
+            const field = desc ? sortField.substring(1) : sortField;
+            const aVal = a[field];
+            const bVal = b[field];
+            if (aVal < bVal) return desc ? 1 : -1;
+            if (aVal > bVal) return desc ? -1 : 1;
+          }
+          return 0;
+        });
+      }
+      
+      return {
+        data: records.map(record => ({
+          type: scopeName,
+          id: String(record.id),
+          attributes: { ...record, id: undefined }
+        }))
+      };
+    };
+    
+    helpers.dataPost = async function({ scopeName, inputRecord }) {
+      const newRecord = {
+        ...inputRecord.data.attributes,
+        id: Date.now() // Simple ID generation
+      };
+      
+      if (scopeName === 'articles') {
+        articles.push(newRecord);
+      } else if (scopeName === 'users') {
+        users.push(newRecord);
+      }
+      
+      return {
+        data: {
+          type: scopeName,
+          id: String(newRecord.id),
+          attributes: { ...newRecord, id: undefined }
+        }
+      };
+    };
+    
+    helpers.dataPatch = async function({ scopeName, id, inputRecord }) {
+      let record;
+      if (scopeName === 'articles') {
+        record = articles.find(a => a.id == id);
+      } else if (scopeName === 'users') {
+        record = users.find(u => u.id == id);
+      }
+      
+      if (!record) {
+        const { RestApiResourceError } = await import('./rest-api-errors.js');
+        throw new RestApiResourceError(`${scopeName} with id ${id} not found`, {
+          subtype: 'not_found',
+          resourceType: scopeName,
+          resourceId: id
+        });
+      }
+      
+      // Update attributes
+      Object.assign(record, inputRecord.data.attributes);
+      
+      return {
+        data: {
+          type: scopeName,
+          id: String(record.id),
+          attributes: { ...record, id: undefined }
+        }
+      };
+    };
+    
+    helpers.dataPut = async function({ scopeName, id, inputRecord, isCreate }) {
+      if (isCreate) {
+        return this.dataPost({ scopeName, inputRecord });
+      } else {
+        // For update, replace all attributes
+        let record;
+        if (scopeName === 'articles') {
+          const index = articles.findIndex(a => a.id == id);
+          if (index !== -1) {
+            articles[index] = {
+              ...inputRecord.data.attributes,
+              id: Number(id)
+            };
+            record = articles[index];
+          }
+        }
+        
+        return {
+          data: {
+            type: scopeName,
+            id: String(record.id),
+            attributes: { ...record, id: undefined }
+          }
+        };
+      }
+    };
+    
+    helpers.dataDelete = async function({ scopeName, id }) {
+      if (scopeName === 'articles') {
+        const index = articles.findIndex(a => a.id == id);
+        if (index === -1) {
+          const { RestApiResourceError } = await import('./rest-api-errors.js');
+          throw new RestApiResourceError(`${scopeName} with id ${id} not found`, {
+            subtype: 'not_found',
+            resourceType: scopeName,
+            resourceId: id
+          });
+        }
+        articles.splice(index, 1);
+      }
+    };
+  }
+};
+
+// Install the mock storage plugin
+api.use(MockStoragePlugin);
+
+// Mount the API routes
+app.use(api.rest.express.router);
+
+// Start the server
+const PORT = process.env.PORT || 3000;
+app.listen(PORT, () => {
+  console.log(`Server running on http://localhost:${PORT}`);
+  console.log('\nTry these commands:');
+  console.log('  curl http://localhost:3000/api/articles');
+  console.log('  curl http://localhost:3000/api/articles/1');
+  console.log('  curl http://localhost:3000/api/articles?sort=-created_at');
+  console.log('  curl -X POST http://localhost:3000/api/articles \\');
+  console.log('    -H "Content-Type: application/vnd.api+json" \\');
+  console.log('    -d \'{"data":{"type":"articles","attributes":{"title":"New Article","body":"Content here","author_id":1}}}\'');
+});