json-rest-api 1.0.22 → 1.0.23

package/tests/http-connectors-parity.test.js

@@ -0,0 +1,235 @@
+import { describe, it, before, beforeEach, after } from 'node:test'
+import assert from 'node:assert/strict'
+import express from 'express'
+import request from 'supertest'
+import knexLib from 'knex'
+import { Api } from 'hooked-api'
+import {
+  RestApiPlugin,
+  RestApiKnexPlugin,
+  ExpressPlugin,
+  FastifyPlugin
+} from '../index.js'
+import { getUnsupportedMediaTypeErrorBody } from '../plugins/core/connectors/lib/transport-http-helpers.js'
+import { cleanTables, createJsonApiDocument } from './helpers/test-utils.js'
+import {
+  FakeFastifyApp,
+  invokeFastifyRoute
+} from './helpers/fake-fastify.js'
+
+const knex = knexLib({
+  client: 'better-sqlite3',
+  connection: {
+    filename: ':memory:'
+  },
+  useNullAsDefault: true
+})
+
+async function createConnectorParityApi () {
+  const expressApp = express()
+  const fastifyApp = new FakeFastifyApp()
+  const api = new Api({
+    name: 'connector-parity-test-api',
+    log: { level: process.env.LOG_LEVEL || 'silent' }
+  })
+
+  await api.use(RestApiPlugin, {
+    simplifiedApi: false,
+    simplifiedTransport: false,
+    returnRecordApi: {
+      post: true,
+      put: false,
+      patch: false
+    },
+    returnRecordTransport: {
+      post: 'full',
+      put: 'no',
+      patch: 'minimal'
+    },
+    sortableFields: ['id', 'name', 'code']
+  })
+
+  await api.use(RestApiKnexPlugin, { knex })
+  await api.use(ExpressPlugin, { mountPath: '/api' })
+  await api.use(FastifyPlugin, {
+    app: fastifyApp,
+    mountPath: '/api'
+  })
+
+  await api.customize({
+    hooks: {
+      'transport:request': {
+        functionName: 'connector-parity-rejector',
+        handler: async ({ context }) => {
+          if (context.transport?.request?.headers?.['x-block-request'] === 'yes') {
+            context.reject(401, 'Blocked by connector parity hook', {
+              title: 'Unauthorized'
+            })
+          }
+        }
+      },
+      'transport:response': {
+        functionName: 'connector-parity-header',
+        handler: async ({ context }) => {
+          context.transport.response.headers['x-connector-test'] = 'enabled'
+        }
+      }
+    }
+  })
+
+  await api.addResource('countries', {
+    schema: {
+      id: { type: 'id' },
+      name: { type: 'string', required: true, max: 100 },
+      code: { type: 'string', max: 2 }
+    },
+    tableName: 'connector_parity_countries'
+  })
+
+  await api.resources.countries.createKnexTable()
+  api.http.express.mount(expressApp)
+
+  return { api, expressApp, fastifyApp }
+}
+
+function assertLocationSuffix (location, resourceId) {
+  assert.ok(location, 'Expected Location header to be present')
+  assert.ok(
+    location.endsWith(`/api/countries/${resourceId}`) ||
+      location.endsWith(`/countries/${resourceId}`),
+    `Unexpected Location header: ${location}`
+  )
+}
+
+describe('HTTP Connector Parity', () => {
+  let api
+  let expressApp
+  let fastifyApp
+
+  before(async () => {
+    ({ api, expressApp, fastifyApp } = await createConnectorParityApi())
+  })
+
+  after(async () => {
+    await knex.destroy()
+  })
+
+  beforeEach(async () => {
+    await cleanTables(knex, ['connector_parity_countries'])
+  })
+
+  it('returns the same create semantics through Express and Fastify', async () => {
+    const expressDoc = createJsonApiDocument('countries', {
+      name: 'Express Country',
+      code: 'EC'
+    })
+    const fastifyDoc = createJsonApiDocument('countries', {
+      name: 'Fastify Country',
+      code: 'FC'
+    })
+
+    const expressResponse = await request(expressApp)
+      .post('/api/countries')
+      .set('Content-Type', 'application/vnd.api+json')
+      .set('Accept', 'application/vnd.api+json')
+      .send(expressDoc)
+
+    const { reply: fastifyReply } = await invokeFastifyRoute(fastifyApp, {
+      method: 'POST',
+      routeUrl: '/api/countries',
+      requestUrl: '/api/countries',
+      headers: {
+        'content-type': 'application/vnd.api+json',
+        accept: 'application/vnd.api+json'
+      },
+      body: fastifyDoc
+    })
+
+    assert.equal(expressResponse.status, 201)
+    assert.equal(fastifyReply.statusCode, 201)
+
+    assert.equal(expressResponse.body.data.type, 'countries')
+    assert.equal(fastifyReply.payload.data.type, 'countries')
+    assert.equal(expressResponse.body.data.attributes.name, 'Express Country')
+    assert.equal(fastifyReply.payload.data.attributes.name, 'Fastify Country')
+    assert.equal(expressResponse.headers['x-connector-test'], 'enabled')
+    assert.equal(fastifyReply.headers['x-connector-test'], 'enabled')
+
+    assertLocationSuffix(expressResponse.headers.location, expressResponse.body.data.id)
+    assertLocationSuffix(fastifyReply.headers.Location, fastifyReply.payload.data.id)
+  })
+
+  it('rejects unsupported write content types using each connector transport policy', async () => {
+    const expressResponse = await request(expressApp)
+      .post('/api/countries')
+      .set('Content-Type', 'text/plain')
+      .send('invalid payload')
+
+    const { reply: fastifyReply } = await invokeFastifyRoute(fastifyApp, {
+      method: 'POST',
+      routeUrl: '/api/countries',
+      requestUrl: '/api/countries',
+      headers: { 'content-type': 'text/plain' },
+      body: 'invalid payload'
+    })
+
+    assert.equal(expressResponse.status, 415)
+    assert.equal(fastifyReply.statusCode, 415)
+    assert.deepEqual(
+      expressResponse.body,
+      getUnsupportedMediaTypeErrorBody({ allowMultipart: true })
+    )
+    assert.deepEqual(
+      fastifyReply.payload,
+      getUnsupportedMediaTypeErrorBody()
+    )
+  })
+
+  it('maps validation errors the same way in both connectors', async () => {
+    const invalidDoc = createJsonApiDocument('countries', {
+      code: 'IV'
+    })
+
+    const expressResponse = await request(expressApp)
+      .post('/api/countries')
+      .set('Content-Type', 'application/vnd.api+json')
+      .set('Accept', 'application/vnd.api+json')
+      .send(invalidDoc)
+
+    const { reply: fastifyReply } = await invokeFastifyRoute(fastifyApp, {
+      method: 'POST',
+      routeUrl: '/api/countries',
+      requestUrl: '/api/countries',
+      headers: {
+        'content-type': 'application/vnd.api+json',
+        accept: 'application/vnd.api+json'
+      },
+      body: invalidDoc
+    })
+
+    assert.equal(expressResponse.status, 422)
+    assert.equal(fastifyReply.statusCode, 422)
+    assert.deepEqual(fastifyReply.payload, expressResponse.body)
+    assert.equal(expressResponse.headers['x-connector-test'], 'enabled')
+    assert.equal(fastifyReply.headers['x-connector-test'], 'enabled')
+  })
+
+  it('honors transport request rejection hooks the same way in both connectors', async () => {
+    const expressResponse = await request(expressApp)
+      .get('/api/countries')
+      .set('x-block-request', 'yes')
+
+    const { reply: fastifyReply } = await invokeFastifyRoute(fastifyApp, {
+      method: 'GET',
+      routeUrl: '/api/countries',
+      requestUrl: '/api/countries',
+      headers: { 'x-block-request': 'yes' }
+    })
+
+    assert.equal(expressResponse.status, 401)
+    assert.equal(fastifyReply.statusCode, 401)
+    assert.deepEqual(fastifyReply.payload, expressResponse.body)
+    assert.equal(expressResponse.headers['x-connector-test'], undefined)
+    assert.equal(fastifyReply.headers['x-connector-test'], undefined)
+  })
+})

package/tests/projected-fields.test.js

@@ -0,0 +1,319 @@
+import { describe, it, before, beforeEach, after } from 'node:test'
+import assert from 'node:assert/strict'
+import { Api } from 'hooked-api'
+import knexLib from 'knex'
+import { LabelPlugin, QueryProjectionsPlugin, RestApiKnexPlugin, RestApiPlugin } from '../index.js'
+import {
+  cleanTables,
+  createJsonApiDocument,
+  createRelationship,
+  resourceIdentifier,
+  validateJsonApiStructure,
+} from './helpers/test-utils.js'
+import { createProjectedFieldsApi } from './fixtures/api-configs.js'
+
+const knex = knexLib({
+  client: 'better-sqlite3',
+  connection: {
+    filename: ':memory:'
+  },
+  useNullAsDefault: true
+})
+
+describe('Query Projections', () => {
+  let api
+  const testData = {}
+
+  before(async () => {
+    api = await createProjectedFieldsApi(knex)
+  })
+
+  after(async () => {
+    await knex.destroy()
+  })
+
+  beforeEach(async () => {
+    await cleanTables(knex, ['projected_books', 'projected_authors'])
+
+    const authorPayloads = [
+      { first_name: 'Alex', last_name: 'Carter' },
+      { first_name: 'Alex', last_name: 'Carter' },
+      { first_name: 'Bella', last_name: 'Stone' },
+      { first_name: 'Aaron', last_name: 'Zephyr' }
+    ]
+
+    testData.authors = []
+    for (const payload of authorPayloads) {
+      const result = await api.resources.authors.post({
+        inputRecord: createJsonApiDocument('authors', payload),
+        simplified: false
+      })
+      testData.authors.push(result.data)
+    }
+
+    testData.expectedAuthorOrder = [
+      testData.authors[3].id,
+      testData.authors[0].id,
+      testData.authors[1].id,
+      testData.authors[2].id
+    ]
+
+    const bookOne = await api.resources.books.post({
+      inputRecord: createJsonApiDocument(
+        'books',
+        { title: 'Derived Fields Handbook' },
+        { author: createRelationship(resourceIdentifier('authors', testData.authors[0].id)) }
+      ),
+      simplified: false
+    })
+
+    const bookTwo = await api.resources.books.post({
+      inputRecord: createJsonApiDocument(
+        'books',
+        { title: 'Cursor Patterns' },
+        { author: createRelationship(resourceIdentifier('authors', testData.authors[2].id)) }
+      ),
+      simplified: false
+    })
+
+    testData.books = [bookOne.data, bookTwo.data]
+  })
+
+  async function createEphemeralProjectionApi (resourceName, resourceOptions) {
+    const api = new Api({
+      name: `${resourceName}-projection-test-api`,
+      log: { level: process.env.LOG_LEVEL || 'info' }
+    })
+
+    await api.use(RestApiPlugin, {
+      simplifiedApi: true,
+      simplifiedTransport: true,
+      returnRecordApi: {
+        post: true,
+        put: true,
+        patch: true
+      }
+    })
+    await api.use(QueryProjectionsPlugin)
+    await api.use(RestApiKnexPlugin, { knex })
+    await api.addResource(resourceName, resourceOptions)
+
+    return api
+  }
+
+  it('should return query projection fields by default and ignore query projection input on writes', async () => {
+    const created = await api.resources.authors.post({
+      inputRecord: createJsonApiDocument('authors', {
+        first_name: 'Nina',
+        last_name: 'Simone',
+        full_name: 'Injected Value'
+      }),
+      simplified: false
+    })
+
+    validateJsonApiStructure(created)
+    assert.equal(created.data.attributes.first_name, 'Nina')
+    assert.equal(created.data.attributes.last_name, 'Simone')
+    assert.equal(created.data.attributes.full_name, 'Nina Simone')
+
+    const fetched = await api.resources.authors.get({
+      id: created.data.id,
+      simplified: false
+    })
+
+    validateJsonApiStructure(fetched)
+    assert.equal(fetched.data.attributes.full_name, 'Nina Simone')
+  })
+
+  it('should allow query projection fields in sparse fieldsets', async () => {
+    const result = await api.resources.authors.get({
+      id: testData.authors[0].id,
+      queryParams: {
+        fields: {
+          authors: 'first_name,full_name'
+        }
+      },
+      simplified: false
+    })
+
+    validateJsonApiStructure(result)
+    assert.equal(result.data.attributes.first_name, 'Alex')
+    assert.equal(result.data.attributes.full_name, 'Alex Carter')
+    assert.equal(result.data.attributes.last_name, undefined)
+  })
+
+  it('should expose query projection fields on included resources', async () => {
+    const result = await api.resources.books.get({
+      id: testData.books[0].id,
+      queryParams: {
+        include: ['author'],
+        fields: {
+          books: 'title',
+          authors: 'full_name'
+        }
+      },
+      simplified: false
+    })
+
+    validateJsonApiStructure(result)
+    assert.ok(Array.isArray(result.included))
+
+    const includedAuthor = result.included.find((resource) => resource.type === 'authors')
+    assert.ok(includedAuthor, 'expected included author resource')
+    assert.equal(includedAuthor.attributes.full_name, 'Alex Carter')
+    assert.equal(includedAuthor.attributes.first_name, undefined)
+    assert.equal(includedAuthor.attributes.last_name, undefined)
+  })
+
+  it('should support stable cursor pagination when sorting by a query projection field', async () => {
+    const seenIds = []
+    const seenFirstNames = []
+    let nextCursor = null
+    let iterations = 0
+    let firstCursor = null
+
+    while (iterations < 10) {
+      const result = await api.resources.authors.query({
+        queryParams: {
+          sort: ['full_name'],
+          fields: {
+            authors: 'first_name'
+          },
+          page: {
+            size: 1,
+            ...(nextCursor ? { after: nextCursor } : {})
+          }
+        },
+        simplified: false
+      })
+
+      validateJsonApiStructure(result, true)
+      assert.equal(result.data.length, 1)
+
+      const resource = result.data[0]
+      seenIds.push(resource.id)
+      seenFirstNames.push(resource.attributes.first_name)
+      assert.equal(resource.attributes.full_name, undefined)
+
+      if (!firstCursor && result.meta?.pagination?.cursor?.next) {
+        firstCursor = result.meta.pagination.cursor.next
+      }
+
+      if (!result.meta?.pagination?.hasMore) {
+        break
+      }
+
+      nextCursor = result.meta.pagination.cursor.next
+      iterations += 1
+    }
+
+    assert.deepEqual(seenIds, testData.expectedAuthorOrder)
+    assert.equal(new Set(seenIds).size, seenIds.length, 'cursor pagination should not duplicate records')
+    assert.ok(firstCursor?.includes('full_name:'), 'cursor should encode query projection sort field')
+    assert.ok(firstCursor?.includes('id:'), 'cursor should append id as deterministic tie-breaker')
+    assert.deepEqual(seenFirstNames, ['Aaron', 'Alex', 'Alex', 'Bella'])
+  })
+
+  it('should allow sorting by a normallyHidden query projection field without returning it by default', async () => {
+    const result = await api.resources.authors.query({
+      queryParams: {
+        sort: ['sort_name']
+      },
+      simplified: false
+    })
+
+    validateJsonApiStructure(result, true)
+    assert.deepEqual(
+      result.data.map((resource) => resource.id),
+      testData.expectedAuthorOrder
+    )
+    result.data.forEach((resource) => {
+      assert.equal(resource.attributes.sort_name, undefined)
+    })
+  })
+
+  it('should reject query projection expressions that return plain SQL strings', async () => {
+    const stringApi = await createEphemeralProjectionApi('string_projection_authors', {
+      schema: {
+        id: { type: 'id' },
+        first_name: { type: 'string', required: true },
+        last_name: { type: 'string', required: true }
+      },
+      queryFields: {
+        full_name: {
+          type: 'string',
+          select: () => "trim(coalesce(first_name, '') || ' ' || coalesce(last_name, ''))"
+        }
+      },
+      tableName: 'projected_authors_string_expr'
+    })
+
+    await stringApi.resources.string_projection_authors.createKnexTable()
+    await knex('projected_authors_string_expr').insert({
+      first_name: 'Nina',
+      last_name: 'Simone'
+    })
+
+    await assert.rejects(
+      () => stringApi.resources.string_projection_authors.query({
+        queryParams: {},
+        simplified: false
+      }),
+      /Query field expressions must return knex raw, knex ref, or a knex query builder/
+    )
+  })
+
+  it('should reject query projection names that conflict with relationship names', async () => {
+    await assert.rejects(
+      () => createEphemeralProjectionApi('conflicting_projection_authors', {
+        schema: {
+          id: { type: 'id' },
+          name: { type: 'string', required: true }
+        },
+        queryFields: {
+          books: {
+            type: 'string',
+            select: ({ knex }) => knex.raw("'X'")
+          }
+        },
+        relationships: {
+          books: { type: 'hasMany', target: 'books', foreignKey: 'author_id' }
+        },
+        tableName: 'projected_authors_conflict'
+      }),
+      /conflicts with an existing schema/
+    )
+  })
+
+  it('should reject query projection names that conflict with computed fields injected by plugins', async () => {
+    const labeledApi = new Api({
+      name: 'label-projection-conflict-api',
+      log: { level: process.env.LOG_LEVEL || 'info' }
+    })
+
+    await labeledApi.use(RestApiPlugin, {
+      simplifiedApi: true,
+      simplifiedTransport: true
+    })
+    await labeledApi.use(LabelPlugin)
+    await labeledApi.use(QueryProjectionsPlugin)
+    await labeledApi.use(RestApiKnexPlugin, { knex })
+
+    await assert.rejects(
+      () => labeledApi.addResource('labeled_projection_authors', {
+        schema: {
+          id: { type: 'id' },
+          name: { type: 'string', required: true }
+        },
+        queryFields: {
+          label: {
+            type: 'string',
+            select: ({ knex }) => knex.raw("'X'")
+          }
+        },
+        tableName: 'projected_authors_label_conflict'
+      }),
+      /conflicts with an existing schema, computed, or relationship name/
+    )
+  })
+})

package/tests/relationships.test.js

@@ -330,7 +330,6 @@ describe('Relationship Operations', () => {
           }
         }
       }
-      console.log('THE NEXT LINE WILL BLOCK THE TEST')
       await basicApi.resources.books.put({
         id: bookResult.data.id,
         inputRecord: putDoc,
@@ -590,7 +589,7 @@ describe('Relationship Operations', () => {
       assert(publisher.relationships.country)
     })
 
-    it('should handle PUT with partial relationships object', async () => {
+    it('should clear omitted relationships when PUT provides a relationships object', async () => {
       // Create resources
       const countryDoc = createJsonApiDocument('countries', { name: 'USA', code: 'US' })
       const countryResult = await basicApi.resources.countries.post({
@@ -640,7 +639,8 @@ describe('Relationship Operations', () => {
         simplified: false
       })
 
-      // PUT with only publisher relationship (should preserve authors since relationships object is partial)
+      // PUT with only publisher relationship. Omitted relationships are cleared
+      // once a relationships object is provided for a complete replacement.
       const putDoc = {
         data: {
           type: 'books',