json-rest-api 1.0.29 → 2.1.0

package/plugins/core/lib/writing/knex-json-api-transformers-writing.js

@@ -1,110 +0,0 @@
-import { getSchemaStructure } from '../querying-writing/knex-constants.js'
-
-/**
- * Processes belongsTo relationships from JSON:API input to foreign key updates
- *
- * @param {Object} scope - The scope object containing schema info
- * @param {Object} deps - Dependencies object containing context with inputRecord
- * @returns {Object} Object mapping foreign key fields to their values
- *
- * @example
- * // Input: JSON:API document with relationships
- * const inputRecord = {
- *   data: {
- *     type: 'articles',
- *     attributes: { title: 'My Article' },
- *     relationships: {
- *       author: {
- *         data: { type: 'users', id: '123' }
- *       },
- *       category: {
- *         data: { type: 'categories', id: '456' }
- *       }
- *     }
- *   }
- * };
- *
- * // Schema has: author_id field with belongsTo: 'users', as: 'author'
- * // Schema has: category_id field with belongsTo: 'categories', as: 'category'
- *
- * const updates = processBelongsToRelationships(scope, { context: { inputRecord } });
- *
- * // Output: Foreign key values extracted
- * // {
- * //   author_id: '123',
- * //   category_id: '456'
- * // }
- *
- * @example
- * // Input: Removing a relationship (setting to null)
- * const inputRecord = {
- *   data: {
- *     type: 'articles',
- *     id: '1',
- *     relationships: {
- *       author: {
- *         data: null  // Remove author
- *       }
- *     }
- *   }
- * };
- *
- * const updates = processBelongsToRelationships(scope, { context: { inputRecord } });
- *
- * // Output: Foreign key set to null
- * // {
- * //   author_id: null
- * // }
- *
- * @description
- * Used by:
- * - rest-api-knex-plugin's dataPut and dataPatch methods
- * - Called before saving to extract foreign keys from JSON:API relationships
- * - Works in conjunction with relationship-processor for complete handling
- *
- * Purpose:
- * - Converts JSON:API relationship format to database foreign keys
- * - Maps from relationship names (e.g., 'author') to field names (e.g., 'author_id')
- * - Handles both setting relationships (with id) and removing them (null)
- * - Only processes belongsTo relationships, not hasMany
- *
- * Data flow:
- * 1. Receives JSON:API document with relationships section
- * 2. Looks up schema to find foreign key fields
- * 3. For each belongsTo field, checks if relationship exists in input
- * 4. Extracts id from relationship data or sets null
- * 5. Returns object ready to merge with attributes for database update
- */
-export const processBelongsToRelationships = (scope, deps) => {
-  const foreignKeyUpdates = {}
-
-  // Extract values from deps
-  const { context } = deps
-  const inputRecord = context.inputRecord
-
-  if (!inputRecord.data.relationships) {
-    return foreignKeyUpdates
-  }
-
-  // Extract schema from scope
-  const {
-    vars: {
-      schemaInfo: { schema }
-    }
-  } = scope
-
-  // Schema might be a Schema object or plain object
-  const schemaStructure = getSchemaStructure(schema)
-
-  for (const [fieldName, fieldDef] of Object.entries(schemaStructure)) {
-    if (fieldDef.belongsTo && fieldDef.as) {
-      const relName = fieldDef.as
-      if (inputRecord.data.relationships[relName] !== undefined) {
-        const relData = inputRecord.data.relationships[relName]
-        foreignKeyUpdates[fieldName] = relData.data?.id || null
-      }
-    }
-  }
-
-  return foreignKeyUpdates
-}

package/plugins/storage/s3-storage.js

@@ -1,93 +0,0 @@
-/**
- * S3 Storage Adapter (mock/demo)
- *
- * Generates S3-style URLs without uploading files to Amazon S3.
- *
- * Usage:
- * ```javascript
- * import { S3Storage } from 'json-rest-api';
- *
- * const storage = new S3Storage({
- *   bucket: 'my-uploads',
- *   region: 'us-east-1',
- *   prefix: 'uploads/',
- *   mockMode: true
- * });
- *
- * const schema = {
- *   image: { type: 'file', storage }
- * };
- * ```
- */
-
-import crypto from 'crypto'
-import path from 'path'
-
-const REAL_S3_NOT_IMPLEMENTED_MESSAGE = 'S3Storage real S3 mode is not implemented. The included adapter only supports mockMode: true; provide a production storage adapter or add an AWS SDK-backed implementation.'
-
-function createRealS3NotImplementedError () {
-  return new Error(REAL_S3_NOT_IMPLEMENTED_MESSAGE)
-}
-
-export class S3Storage {
-  constructor (options = {}) {
-    this.bucket = options.bucket
-    this.region = options.region || 'us-east-1'
-    this.prefix = options.prefix || ''
-    this.acl = options.acl || 'public-read'
-
-    if (!this.bucket) {
-      throw new Error('S3Storage requires a bucket name')
-    }
-
-    this.mockMode = options.mockMode !== false // Default to mock mode
-
-    if (!this.mockMode) {
-      throw createRealS3NotImplementedError()
-    }
-  }
-
-  /**
-   * Upload a file to mock S3 storage.
-   * @param {Object} file - File object from detector
-   * @returns {Promise<string>} URL of the uploaded file
-   */
-  async upload (file) {
-    // Generate S3 key
-    const ext = path.extname(file.filename)
-    const hash = crypto.randomBytes(16).toString('hex')
-    const key = `${this.prefix}${hash}${ext}`
-
-    if (this.mockMode) {
-      // Mock mode - just return a fake URL
-      const url = `https://${this.bucket}.s3.${this.region}.amazonaws.com/${key}`
-
-      // Simulate upload delay
-      await new Promise(resolve => setTimeout(resolve, 100))
-
-      return url
-    }
-
-    throw createRealS3NotImplementedError()
-  }
-
-  /**
-   * Delete a file from mock S3 storage.
-   * @param {string} url - URL returned by upload()
-   * @returns {Promise<void>}
-   */
-  async delete (url) {
-    if (!this.mockMode) {
-      throw createRealS3NotImplementedError()
-    }
-
-    const urlObj = new URL(url)
-
-    if (urlObj.pathname.length === 0) {
-      throw new Error('Invalid S3 object URL')
-    }
-
-    // Mock mode - just simulate deletion
-    await new Promise(resolve => setTimeout(resolve, 50))
-  }
-}

package/quickTest.js

@@ -1,136 +0,0 @@
-//
-// index.js
-//
-import { RestApiPlugin, RestApiKnexPlugin, ExpressPlugin } from './index.js' // Added: ExpressPlugin
-import { Api } from 'hooked-api'
-import knexLib from 'knex'
-import util from 'util'
-import express from 'express' // Added: Express
-
-// Utility used throughout this guide
-const inspect = (obj) => util.inspect(obj, { depth: 8 })
-
-// Create a Knex instance connected to SQLite in-memory database
-const knex = knexLib({
-  client: 'better-sqlite3',
-  connection: {
-    filename: ':memory:'
-  },
-  useNullAsDefault: true
-})
-
-// Create API instance
-const api = new Api({ name: 'book-catalog-api', logLevel: 'trace' })
-
-// Install plugins
-await api.use(RestApiPlugin, { returnBasePath: '/api' })
-await api.use(RestApiKnexPlugin, { knex })
-await api.use(ExpressPlugin, { mountPath: '/api' }) // Added: Express Plugin
-
-// Define publishers resource
-await api.addResource('publishers', {
-  schema: {
-    name: { type: 'string', required: true, max: 255, search: true, indexed: true },
-  },
-  relationships: {
-    // A publisher has many authors
-    authors: { hasMany: 'authors', foreignKey: 'publisher_id' },
-  },
-  searchSchema: { // Adding search schema for publishers
-    name: { type: 'string', filterOperator: 'like' }
-  }
-})
-await api.resources.publishers.createKnexTable()
-
-// Define authors resource, which belongs to a publisher
-await api.addResource('authors', {
-  schema: {
-    name: { type: 'string', required: true, max: 100, search: true },
-    surname: { type: 'string', required: true, max: 100, search: true },
-    publisher_id: { type: 'id', belongsTo: 'publishers', as: 'publisher', nullable: true }
-  },
-  searchSchema: { // Adding search schema for authors
-    name: { type: 'string', filterOperator: 'like' },
-    surname: { type: 'string', filterOperator: 'like' },
-    publisher: { type: 'id', actualField: 'publisher_id', nullable: true },
-    publisherName: { type: 'string', actualField: 'publishers.name', filterOperator: 'like' } // Cross-table search
-  }
-})
-await api.resources.authors.createKnexTable()
-
-// Method 1: Simplified mode without inputRecord (most concise)
-const penguinResult = await api.resources.publishers.post({
-  name: 'Penguin Random House'
-})
-console.log('Created publisher:', inspect(penguinResult))
-
-// Method 2: Simplified mode with inputRecord (explicit)
-const harperResult = await api.resources.publishers.post({
-  inputRecord: {
-    name: 'HarperCollins'
-  }
-})
-console.log('Created second publisher:', inspect(harperResult))
-
-// Method 3: Full JSON:API mode (standards compliant)
-const oxfordResult = await api.resources.publishers.post({
-  inputRecord: {
-    data: {
-      type: 'publishers',
-      attributes: {
-        name: 'Oxford University Press'
-      }
-    }
-  },
-  simplified: false
-})
-console.log('JSON:API response:', inspect(oxfordResult))
-
-// Create an author linked to the first publisher (simplified)
-const authorResult = await api.resources.authors.post({
-  name: 'George',
-  surname: 'Orwell',
-  publisher_id: penguinResult.id
-})
-console.log('Created author:', inspect(authorResult))
-
-// Get all publishers
-const allPublishers = await api.resources.publishers.query({})
-console.log('All publishers:', inspect(allPublishers))
-
-// Get publisher with included authors
-const publisherWithAuthors = await api.resources.publishers.get({
-  id: penguinResult.id,
-  include: ['authors']
-})
-console.log('Publisher with authors:', inspect(publisherWithAuthors))
-
-// Search authors by name
-const searchResult = await api.resources.authors.query({
-  filter: { name: 'George' }
-})
-console.log('Search results:', inspect(searchResult))
-
-// Update an author
-const updateResult = await api.resources.authors.patch({
-  id: authorResult.id,
-  surname: 'Orwell (Eric Blair)'
-})
-console.log('Updated author:', inspect(updateResult))
-
-/// *** ...programmatic calls here... ***
-
-// Create the express server and add the API's routes
-const app = express()
-app.use(api.http.express.router)
-app.use(api.http.express.notFoundRouter)
-
-app.listen(3000, () => {
-  console.log('Express server started on port 3000. API available at http://localhost:3000/api')
-}).on('error', (err) => {
-  console.error('Failed to start server:', err)
-  process.exit(1)
-}).on('error', (err) => {
-  console.error('Failed to start server:', err)
-  process.exit(1)
-})

package/scripts/debug-anyapi-review-filter.mjs

@@ -1,63 +0,0 @@
-import knexLib from 'knex'
-import { createCustomIdPropertyApi } from '../tests/fixtures/api-configs.js'
-import { createJsonApiDocument } from '../tests/helpers/test-utils.js'
-
-async function run () {
-  const knex = knexLib({ client: 'better-sqlite3', connection: { filename: ':memory:' }, useNullAsDefault: true })
-  const api = await createCustomIdPropertyApi(knex)
-
-  const country = await api.resources.countries.post({
-    inputRecord: createJsonApiDocument('countries', { name: 'USA', code: 'US' })
-  })
-
-  const book = await api.resources.books.post({
-    inputRecord: createJsonApiDocument('books',
-      { title: 'Test Book' },
-      { country: { data: { type: 'countries', id: country.data.id } } }
-    )
-  })
-
-  const author = await api.resources.authors.post({
-    inputRecord: createJsonApiDocument('authors', { name: 'Author' })
-  })
-
-  await api.resources.reviews.post({
-    inputRecord: createJsonApiDocument('reviews', {
-      rating: 5,
-      title: 'Book review',
-      content: 'Great book',
-      reviewer_name: 'Reader',
-      reviewable_type: 'books',
-      reviewable_id: book.data.id
-    })
-  })
-
-  await api.resources.reviews.post({
-    inputRecord: createJsonApiDocument('reviews', {
-      rating: 4,
-      title: 'Author review',
-      content: 'Great author',
-      reviewer_name: 'Fan',
-      reviewable_type: 'authors',
-      reviewable_id: author.data.id
-    })
-  })
-
-  try {
-    const res = await api.resources.reviews.query({
-      queryParams: { filters: { reviewable_type: 'books' } }
-    })
-    console.log('Query succeeded with rows:', res.data.length)
-  } catch (error) {
-    console.error('Query failed:', error)
-    if (error?.sql) {
-      console.error('SQL:', error.sql)
-    }
-  }
-
-  await knex.destroy()
-}
-
-run().catch((err) => {
-  console.error('Unexpected failure:', err)
-})

package/scripts/inspect-anyapi-descriptor-country.mjs

@@ -1,19 +0,0 @@
-import knexLib from 'knex'
-import { createCustomIdPropertyApi } from '../tests/fixtures/api-configs.js'
-
-async function run () {
-  const knex = knexLib({ client: 'better-sqlite3', connection: { filename: ':memory:' }, useNullAsDefault: true })
-  const api = await createCustomIdPropertyApi(knex)
-  const descriptor = await api.anyapi.registry.getDescriptor('default', 'countries')
-  console.log(JSON.stringify({
-    idProperty: descriptor.idProperty,
-    fields: descriptor.fields,
-    canonicalFieldMap: descriptor.canonicalFieldMap,
-    reverseAttributes: descriptor.reverseAttributes,
-  }, null, 2))
-  await knex.destroy()
-}
-
-run().catch((err) => {
-  console.error('Failed to inspect descriptor', err)
-})

package/scripts/inspect-anyapi-descriptor.mjs

@@ -1,19 +0,0 @@
-import knexLib from 'knex'
-import { createCustomIdPropertyApi } from '../tests/fixtures/api-configs.js'
-
-async function run () {
-  const knex = knexLib({ client: 'better-sqlite3', connection: { filename: ':memory:' }, useNullAsDefault: true })
-  const api = await createCustomIdPropertyApi(knex)
-  const descriptor = await api.anyapi.registry.getDescriptor('default', 'reviews')
-  console.log(JSON.stringify({
-    idProperty: descriptor.idProperty,
-    fields: descriptor.fields,
-    canonicalFieldMap: descriptor.canonicalFieldMap,
-    reverseAttributes: descriptor.reverseAttributes,
-  }, null, 2))
-  await knex.destroy()
-}
-
-run().catch((err) => {
-  console.error('Failed to inspect descriptor', err)
-})

package/scripts/run-docs.js

@@ -1,133 +0,0 @@
-#!/usr/bin/env node
-
-import { spawn } from 'child_process'
-import path from 'path'
-import { fileURLToPath } from 'url'
-
-const __filename = fileURLToPath(import.meta.url)
-const __dirname = path.dirname(__filename)
-const projectRoot = path.join(__dirname, '..')
-const docsRoot = path.join(projectRoot, 'docs')
-const LOCAL_URL = 'http://localhost:4000/json-rest-api/'
-const BROWSER_DELAY_MS = 3000
-
-function parseMode (argv = []) {
-  if (argv.includes('--serve') || argv.includes('--dev')) {
-    return 'serve'
-  }
-
-  return 'build'
-}
-
-async function runCommand (command, args, options = {}) {
-  return new Promise((resolve, reject) => {
-    const proc = spawn(command, args, {
-      stdio: 'inherit',
-      shell: true,
-      ...options
-    })
-
-    proc.on('error', reject)
-    proc.on('exit', (code) => {
-      if (code === 0) {
-        resolve()
-        return
-      }
-
-      reject(new Error(`Command failed with code ${code}`))
-    })
-  })
-}
-
-async function ensureBundlerDependencies () {
-  try {
-    await runCommand('bundle', ['check'], { cwd: docsRoot })
-  } catch {
-    console.log('Installing Jekyll dependencies...')
-    await runCommand('bundle', ['install'], { cwd: docsRoot })
-  }
-}
-
-async function openBrowser (url) {
-  const platform = process.platform
-  const command = platform === 'darwin'
-    ? 'open'
-    : platform === 'win32'
-      ? 'start'
-      : 'xdg-open'
-
-  try {
-    await runCommand(command, [url])
-    console.log(`Opened browser at ${url}`)
-  } catch {
-    console.log(`Visit ${url} in your browser`)
-  }
-}
-
-async function buildDocs () {
-  console.log('Building documentation site...')
-  await runCommand('bundle', ['exec', 'jekyll', 'build'], { cwd: docsRoot })
-}
-
-async function serveDocs () {
-  console.log('Starting documentation server...')
-
-  const jekyll = spawn('bundle', ['exec', 'jekyll', 'serve', '--watch'], {
-    cwd: docsRoot,
-    stdio: 'pipe',
-    shell: true
-  })
-
-  jekyll.stdout.on('data', (data) => {
-    const output = data.toString()
-    process.stdout.write(output)
-
-    if (output.includes('Server running') || output.includes('Server address:')) {
-      setTimeout(() => openBrowser(LOCAL_URL), 1000)
-    }
-  })
-
-  jekyll.stderr.on('data', (data) => {
-    process.stderr.write(data)
-  })
-
-  process.on('SIGINT', () => {
-    console.log('\nShutting down Jekyll server...')
-    jekyll.kill()
-    process.exit(0)
-  })
-
-  jekyll.on('error', (err) => {
-    console.error('Jekyll server error:', err)
-    process.exit(1)
-  })
-
-  jekyll.on('exit', (code) => {
-    if (code !== 0 && code !== null) {
-      console.error(`Jekyll server exited with code ${code}`)
-      process.exit(code)
-    }
-  })
-
-  setTimeout(() => openBrowser(LOCAL_URL), BROWSER_DELAY_MS)
-}
-
-async function main () {
-  const mode = parseMode(process.argv.slice(2))
-
-  try {
-    await ensureBundlerDependencies()
-
-    if (mode === 'serve') {
-      await serveDocs()
-      return
-    }
-
-    await buildDocs()
-  } catch (error) {
-    console.error('Error:', error.message)
-    process.exit(1)
-  }
-}
-
-main()

package/test-debug.js

@@ -1,59 +0,0 @@
-import { createBasicApi } from './tests/fixtures/api-configs.js'
-import { cleanTables, createJsonApiDocument } from './tests/helpers/test-utils.js'
-import knex from 'knex'
-
-const dbConfig = {
-  client: 'better-sqlite3',
-  connection: { filename: ':memory:' },
-  useNullAsDefault: true
-}
-
-const db = knex(dbConfig)
-
-async function test () {
-  const api = await createBasicApi(db)
-
-  // Create test data
-  await cleanTables(db, ['basic_countries', 'basic_publishers', 'basic_authors', 'basic_books', 'basic_book_authors'])
-
-  // Create a country first
-  const countryDoc = createJsonApiDocument('countries', { name: 'Test Country', code: 'TC' })
-  const country = await api.resources.countries.post({ inputRecord: countryDoc })
-
-  // Create an author
-  const authorDoc = createJsonApiDocument('authors', { name: 'Test Author' })
-  const author = await api.resources.authors.post({ inputRecord: authorDoc })
-
-  // Create a book with proper relationships
-  const bookDoc = {
-    data: {
-      type: 'books',
-      attributes: { title: 'Test Book' },
-      relationships: {
-        country: { data: { type: 'countries', id: String(country.data.id) } }
-      }
-    }
-  }
-  const book = await api.resources.books.post({ inputRecord: bookDoc })
-
-  // Create the many-to-many relationship
-  await db('basic_book_authors').insert({
-    author_id: author.data.id,
-    book_id: book.data.id
-  })
-
-  // Now try to query authors with books included
-  console.log('Querying authors with books included...')
-  try {
-    const result = await api.resources.authors.query({
-      queryParams: { include: ['books'] }
-    })
-    console.log('Success!', JSON.stringify(result, null, 2))
-  } catch (error) {
-    console.error('Error:', error.message)
-  }
-
-  await db.destroy()
-}
-
-test().catch(console.error)