json-rest-api 1.0.29 → 2.0.0

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

@@ -1,161 +0,0 @@
-# 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',
-});
-
-// 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');
-}).on('error', (err) => {
-  console.error('Failed to start server:', err);
-  process.exit(1)
-});
-```
-
-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/eslint.config.js

@@ -1,13 +0,0 @@
-import neostandard from 'neostandard'
-
-export default [
-  ...neostandard({
-    ignores: ['node_modules/**', 'docs/**', 'tests/**', 'examples/**']
-  }),
-  {
-    files: ['index.js'],
-    rules: {
-      'import-x/export': 'off'
-    }
-  }
-]

package/examples/url-override-example.js

@@ -1,137 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * Example: Custom URL Override Using Hooks
- *
- * This example demonstrates how to override URL generation using the
- * hooked-api hooks system. This is the recommended approach for custom
- * URL scenarios like API gateways, CDNs, or multi-tenant applications.
- */
-
-import { Api } from 'hooked-api'
-import { RestApiPlugin, RestApiKnexPlugin, ExpressPlugin } from 'json-rest-api'
-import knexLib from 'knex'
-import express from 'express'
-
-// Create in-memory database
-const knex = knexLib({
-  client: 'better-sqlite3',
-  connection: { filename: ':memory:' },
-  useNullAsDefault: true
-})
-
-// Create API with URL override hook
-const api = new Api({
-  name: 'url-override-demo',
-
-  // Define hooks at API creation time
-  hooks: {
-    // This hook runs at the start of each request
-    'transport:request': [
-      async (payload) => {
-        const { context, req } = payload
-
-        // Example 1: Override based on custom header
-        // Useful for CDN or API gateway scenarios
-        if (req?.headers?.['x-public-url']) {
-          context.urlPrefixOverride = req.headers['x-public-url']
-          console.log(`✓ URL overridden via X-Public-URL header: ${context.urlPrefixOverride}`)
-        }
-
-        // Example 2: API versioning via header
-        // Route different API versions while maintaining same backend
-        else if (req?.headers?.['x-api-version'] === 'v2') {
-          context.urlPrefixOverride = 'https://api.example.com/v2'
-          console.log(`✓ URL overridden for API v2: ${context.urlPrefixOverride}`)
-        }
-
-        // Example 3: Multi-tenant based on host
-        // Each tenant gets their own domain in responses
-        else if (req?.hostname?.includes('tenant-a')) {
-          context.urlPrefixOverride = `https://tenant-a.api.com${req.baseUrl || ''}`
-          console.log(`✓ URL overridden for tenant-a: ${context.urlPrefixOverride}`)
-        }
-
-        // Example 4: Environment-based override
-        // Force production URLs in staging environment
-        else if (process.env.FORCE_PRODUCTION_URLS === 'true') {
-          context.urlPrefixOverride = 'https://api.production.com/api'
-          console.log(`✓ URL overridden via environment: ${context.urlPrefixOverride}`)
-        }
-
-        return payload
-      }
-    ]
-  }
-})
-
-// Install plugins
-await api.use(RestApiPlugin, {
-  returnRecordTransport: { post: 'full' }  // Return full JSON:API response
-})
-await api.use(RestApiKnexPlugin, { knex })
-await api.use(ExpressPlugin, { mountPath: '/api' })
-
-// Define a simple resource
-await api.addResource('items', {
-  schema: {
-    name: { type: 'string', required: true, max: 100 },
-    description: { type: 'string', max: 500 }
-  }
-})
-await api.resources.items.createKnexTable()
-
-// Create some test data
-console.log('\n📝 Creating test data...')
-await api.resources.items.post({
-  inputRecord: {
-    data: {
-      type: 'items',
-      attributes: {
-        name: 'Test Item 1',
-        description: 'This is a test item'
-      }
-    }
-  },
-  simplified: false
-})
-
-// Create Express app
-const app = express()
-app.use(api.http.express.router)
-
-// Start server
-const PORT = process.env.PORT || 3333
-const server = app.listen(PORT, () => {
-  console.log(`\n🚀 Server running on http://localhost:${PORT}`)
-  console.log('\n📚 Try these examples:\n')
-
-  console.log('1. Default URL (auto-detected):')
-  console.log(`   curl http://localhost:${PORT}/api/items`)
-  console.log('   → URLs will be: http://localhost:${PORT}/api/items/1\n')
-
-  console.log('2. Custom CDN URL:')
-  console.log(`   curl -H "X-Public-URL: https://cdn.example.com/api" http://localhost:${PORT}/api/items`)
-  console.log('   → URLs will be: https://cdn.example.com/api/items/1\n')
-
-  console.log('3. API Version Header:')
-  console.log(`   curl -H "X-API-Version: v2" http://localhost:${PORT}/api/items`)
-  console.log('   → URLs will be: https://api.example.com/v2/items/1\n')
-
-  console.log('4. Create with custom URL:')
-  console.log('   curl -X POST -H "Content-Type: application/vnd.api+json" \\')
-  console.log('        -H "X-Public-URL: https://public.api.com/api" \\')
-  console.log('        -d \'{"data":{"type":"items","attributes":{"name":"New Item"}}}\' \\')
-  console.log(`        http://localhost:${PORT}/api/items`)
-  console.log('   → Response URLs will use: https://public.api.com/api/items/2\n')
-
-  console.log('Press Ctrl+C to stop the server\n')
-})
-
-// Graceful shutdown
-process.on('SIGINT', async () => {
-  console.log('\n\n👋 Shutting down gracefully...')
-  server.close()
-  await knex.destroy()
-  process.exit(0)
-})

package/fixing_plan.md

@@ -1,112 +0,0 @@
-# Fixing Plan
-
-Checklist-style plan for addressing the audit findings. Items marked as requiring approval change public behavior, public API, or dependencies.
-
-## High Priority
-
-- [x] Fix AnyAPI custom `idProperty` canonical mapping.
-  - [x] Treat `schemaInfo.idProperty` as an alias of logical `id` in the canonical storage adapter.
-  - [x] Skip custom id fields such as `item_id` when building DB attribute selections.
-  - [x] Ensure cursor, sort, projection, sparse fieldset, and include paths translate both `id` and `idProperty` to `logical_id`.
-  - [x] Add AnyAPI tests for custom-id `post`, `get`, `query`, sparse fields, and cursor pagination.
-
-- [x] Fix AnyAPI PUT create parity.
-  - [x] Branch `helpers.dataPut` on `context.isCreate`.
-  - [x] In create mode, insert into `any_records` with tenant, resource, logical id, and translated attributes.
-  - [x] Keep the current update path for update mode.
-  - [x] Add legacy Knex and AnyAPI parity tests for `PUT /resource/:id` create, including custom IDs.
-
-- [x] Fix pagination link query-string round trips.
-  - [x] Replace manual query-string concatenation with one serializer that is the inverse of `parseJsonApiQuery`.
-  - [x] Use `URLSearchParams` for keys and values.
-  - [x] Map internal `queryParams.filters` back to public JSON:API `filter[...]`.
-  - [x] Add tests that parse generated `links.next` and prove filters, fields, sort, include, and page params survive round trip.
-
-- [x] Fix relationship PATCH cardinality validation.
-  - [x] Generate relationship-aware request contracts from relationship metadata.
-  - [x] Allow to-one relationship PATCH data to be `null` or one resource identifier only.
-  - [x] Allow to-many relationship data to be arrays only.
-  - [x] Make `processRelationships()` throw when a belongsTo relationship receives an array.
-  - [x] Add API and transport tests for invalid to-one arrays and invalid to-many scalars.
-
-- [x] Run `afterCommit` for relationship routes.
-  - [x] After `postRelationship`, `patchRelationship`, and `deleteRelationship` commit their own transaction, run `afterCommit`.
-  - [x] Preserve rollback behavior through `afterRollback`.
-  - [x] Verify Socket.IO deferred relationship broadcasts work, or define a separate relationship notification policy.
-  - [x] Add tests with an `afterCommit` hook counter and Socket.IO relationship-write subscription behavior.
-
-- [x] Decide and fix post-commit hook failure semantics.
-  - [x] Split transaction work from post-commit side effects.
-  - [x] Once `commit()` succeeds, do not call rollback handling.
-  - [x] Surface post-commit hook errors while preserving already-committed data.
-  - [x] Add tests proving the row remains committed and the response/error semantics are intentional.
-
-## Medium Priority
-
-- [x] Fix AnyAPI pagination fixture cleanup.
-  - [x] Register `cursor_products` and `cursor_items` with `storageMode.registerTable()` in `createCursorPaginationApi`.
-  - [x] Add a focused cleanup test proving `cleanTables(knex, ['cursor_products'])` deletes matching `any_records`.
-  - [x] Keep metadata-derived cleanup mappings as a later refactor if a broader helper change is approved.
-
-- [x] Fix file temp and orphan cleanup.
-  - [x] Wrap file processing in `try/finally` so detector temp files are cleaned after validation failures.
-  - [x] Track successfully uploaded URLs on `context`.
-  - [x] On rollback or later write error, call storage `delete(url)` where available.
-  - [x] Document `delete(url)` as the rollback-capable storage contract.
-  - [x] Add tests for invalid MIME cleanup and post-upload DB/validation rollback cleanup.
-
-- [x] Harden `LocalStorage` path containment.
-  - [x] Sanitize or reject custom basenames containing `/`, `\`, drive prefixes, or empty names.
-  - [x] Replace `startsWith(resolvedDir)` containment with `path.relative(resolvedDir, resolvedPath)`.
-  - [x] Add tests for sibling-prefix traversal such as `../uploads_evil/pwn`.
-
-- [x] Fix untrusted proxy URL generation. Requires maintainer approval.
-  - [x] Stop trusting `Host` and `X-Forwarded-*` by default for absolute links.
-  - [x] Prefer relative links unless `urlPrefixOverride` or an explicit public base URL is configured.
-  - [x] If forwarded headers remain supported, gate them behind `trustProxy` and allowed host/proto validation. Resolved by not supporting forwarded headers for URL generation.
-  - [x] Add Express and Fastify tests with hostile `Host` and `X-Forwarded-Host` headers.
-
-- [x] Fix `S3Storage` non-mock behavior. Dependency/public behavior choice requires maintainer approval.
-  - [x] Smallest safe fix: throw a clear "real S3 storage is not implemented" error when `mockMode: false`.
-  - [x] Reject full AWS SDK support for this pass because it adds dependency, credential, and public behavior scope.
-  - [x] Add tests for mock mode and the chosen non-mock behavior.
-
-## Low Priority
-
-- [x] Make field setter errors fail closed.
-  - [x] Change setter error handling to throw by default.
-  - [x] Do not add an opt-in non-fatal mode without a real use case.
-  - [x] Add a rollback test where a setter throws and no row is persisted.
-
-- [x] Normalize return-record boolean compatibility.
-  - [x] Create one shared return-record normalizer.
-  - [x] Normalize `true -> 'full'`, `false -> 'no'`, and keep valid strings unchanged.
-  - [x] Use the shared normalizer in plugin install and per-call setup.
-  - [x] Update tests and docs to prefer `'no'`, `'minimal'`, and `'full'` while preserving boolean compatibility.
-
-## Contract Drift
-
-- [x] Fix Socket.IO public exports and docs.
-  - [x] Export `SocketIOPlugin` from `index.js`.
-  - [x] Fix docs to import `Api` from `hooked-api`, not `json-rest-api`.
-  - [x] Remove invalid deep imports such as `json-rest-api/plugins/socketio`, or add formal package subpath exports. Subpath exports require maintainer approval.
-  - [x] Add a public import smoke test.
-
-- [x] Align S3 documentation with implementation.
-  - [x] Since real S3 is not implemented, make README and guide text state that the included adapter is mock/demo only.
-  - [x] Leave production S3 as a future approved dependency/API design rather than documenting unsupported behavior.
-
-- [x] Finish relationship validation contract consolidation.
-  - [x] Move relationship-route schemas into the same request-contract surface as resource routes.
-  - [x] Do this after the cardinality fix so the centralized contract is correct rather than merely centralized.
-
-## Verification Checklist
-
-- [x] `npm test`
-- [x] `npm run lint`
-- [x] `npm run test:anyapi`
-- [x] `npm run verify`
-- [x] Narrow repro for AnyAPI custom `idProperty`
-- [x] Narrow repro for relationship route `afterCommit`
-- [x] Narrow repro for pagination link round trip
-- [x] Import smoke test for public exports