json-rest-api 1.0.23 → 1.0.25

package/tests/fixtures/api-configs.js

@@ -1,5 +1,13 @@
 import { Api } from 'hooked-api'
-import { RestApiPlugin, RestApiKnexPlugin, RestApiAnyapiKnexPlugin, QueryProjectionsPlugin } from '../../index.js'
+import {
+  FileHandlingPlugin,
+  QueryProjectionsPlugin,
+  RestApiAnyapiKnexPlugin,
+  RestApiKnexPlugin,
+  RestApiPlugin,
+  RowPolicyPlugin,
+  SocketIOPlugin
+} from '../../index.js'
 import { ExpressPlugin } from '../../plugins/core/connectors/express-plugin.js'
 import express from 'express'
 import { createServer } from 'http'
@@ -198,6 +206,266 @@ export async function createBasicApi (knex, pluginOptions = {}) {
   }
 }
 
+export async function createReturnRecordApi (knex, pluginOptions = {}) {
+  const apiName = pluginOptions.apiName || 'return-record-test-api'
+  const tablePrefix = pluginOptions.tablePrefix || 'return'
+  if (storageMode.isAnyApi()) {
+    storageMode.clearRegistry()
+  }
+
+  const api = new Api({
+    name: apiName,
+    log: { level: process.env.LOG_LEVEL || 'info' }
+  })
+
+  const previousTenant = storageMode.currentTenant
+  const tenantId = storageMode.isAnyApi()
+    ? (pluginOptions.tenantId || `${tablePrefix}_tenant`)
+    : storageMode.defaultTenant
+  if (storageMode.isAnyApi()) {
+    storageMode.setCurrentTenant(tenantId)
+  }
+
+  await api.use(RestApiPlugin, {
+    simplifiedApi: false,
+    simplifiedTransport: false,
+    returnRecordApi: {
+      post: true,
+      put: false,
+      patch: false
+    },
+    returnRecordTransport: {
+      post: false,
+      put: true,
+      patch: 'minimal'
+    },
+    sortableFields: ['id', 'name'],
+    ...pluginOptions['rest-api']
+  })
+  await useStoragePlugin(api, knex, { tenantId })
+  await resetAnyApiTables(knex)
+
+  try {
+    await api.addResource('global_items', {
+      schema: {
+        id: { type: 'id' },
+        name: { type: 'string', required: true, max: 100 }
+      },
+      tableName: `${tablePrefix}_global_items`
+    })
+    await api.resources.global_items.createKnexTable()
+    mapTable(`${tablePrefix}_global_items`, 'global_items')
+
+    await api.addResource('scope_items', {
+      schema: {
+        id: { type: 'id' },
+        name: { type: 'string', required: true, max: 100 }
+      },
+      tableName: `${tablePrefix}_scope_items`,
+      returnRecordApi: {
+        post: false,
+        put: true,
+        patch: 'minimal'
+      },
+      returnRecordTransport: true
+    })
+    await api.resources.scope_items.createKnexTable()
+    mapTable(`${tablePrefix}_scope_items`, 'scope_items')
+  } finally {
+    if (storageMode.isAnyApi()) {
+      storageMode.setCurrentTenant(previousTenant)
+    }
+  }
+
+  return api
+}
+
+/**
+ * Creates a small API that uses logical camelCase belongsTo fields with default snake_case storage mapping.
+ * This reproduces the full JSON:API linkage path where storage column names differ from logical field names.
+ */
+export async function createCamelCaseBelongsToApi (knex, pluginOptions = {}) {
+  const apiName = pluginOptions.apiName || 'camelcase-belongsto-test-api'
+  const tablePrefix = pluginOptions.tablePrefix || 'camel_fk'
+
+  const api = new Api({
+    name: apiName,
+    log: { level: process.env.LOG_LEVEL || 'info' }
+  })
+
+  await api.use(RestApiPlugin, {
+    simplifiedApi: false,
+    simplifiedTransport: false,
+    returnRecordApi: {
+      post: true,
+      put: false,
+      patch: false
+    },
+    returnRecordTransport: {
+      post: 'full',
+      put: 'no',
+      patch: 'full'
+    },
+    ...(pluginOptions['rest-api'] || {})
+  })
+
+  await api.use(RestApiKnexPlugin, { knex })
+
+  await api.addResource('countries', {
+    schema: {
+      id: { type: 'id' },
+      name: { type: 'string', required: true, max: 100 }
+    },
+    tableName: `${tablePrefix}_countries`
+  })
+  await api.resources.countries.createKnexTable()
+
+  await api.addResource('publishers', {
+    schema: {
+      id: { type: 'id' },
+      name: { type: 'string', required: true, max: 200 },
+      countryId: { type: 'number', nullable: true, belongsTo: 'countries', as: 'country' }
+    },
+    tableName: `${tablePrefix}_publishers`
+  })
+  await api.resources.publishers.createKnexTable()
+
+  return api
+}
+
+/**
+ * Creates a small API focused on resource ID normalization behavior.
+ */
+export async function createIdNormalizationApi (knex, pluginOptions = {}) {
+  const apiName = pluginOptions.apiName || 'id-normalization-test-api'
+  const tablePrefix = pluginOptions.tablePrefix || 'id_norm'
+  if (storageMode.isAnyApi()) {
+    storageMode.clearRegistry()
+  }
+
+  const api = new Api({
+    name: apiName,
+    log: { level: process.env.LOG_LEVEL || 'info' }
+  })
+
+  const previousTenant = storageMode.currentTenant
+  const tenantId = storageMode.isAnyApi()
+    ? (pluginOptions.tenantId || `${tablePrefix}_tenant`)
+    : storageMode.defaultTenant
+  if (storageMode.isAnyApi()) {
+    storageMode.setCurrentTenant(tenantId)
+  }
+
+  await api.use(RestApiPlugin, {
+    simplifiedApi: false,
+    simplifiedTransport: false,
+    returnRecordApi: {
+      post: true,
+      put: false,
+      patch: false
+    },
+    returnRecordTransport: {
+      post: 'full',
+      put: 'no',
+      patch: 'minimal'
+    },
+    ...(pluginOptions['rest-api'] || {})
+  })
+
+  try {
+    await withTenantContext(tenantId, async () => {
+      await useStoragePlugin(api, knex, { tenantId })
+      await resetAnyApiTables(knex)
+
+      await api.addResource('countries', {
+        schema: {
+          id: { type: 'string', required: true },
+          name: { type: 'string', required: true, max: 100 }
+        },
+        tableName: `${tablePrefix}_countries`,
+        ...(pluginOptions.countryResourceOptions || {})
+      })
+      await knex.schema.dropTableIfExists(`${tablePrefix}_countries`)
+      await knex.schema.createTable(`${tablePrefix}_countries`, (table) => {
+        table.string('id').primary()
+        table.string('name').notNullable()
+      })
+      mapTable(`${tablePrefix}_countries`, 'countries')
+
+      await api.addResource('publishers', {
+        schema: {
+          id: { type: 'string', required: true },
+          name: { type: 'string', required: true, max: 100 },
+          country_id: { type: 'string', nullable: true, belongsTo: 'countries', as: 'country' }
+        },
+        relationships: {
+          tags: { type: 'manyToMany', through: 'publisher_tags', foreignKey: 'publisher_id', otherKey: 'tag_id' }
+        },
+        tableName: `${tablePrefix}_publishers`,
+        ...(pluginOptions.publisherResourceOptions || {})
+      })
+      await knex.schema.dropTableIfExists(`${tablePrefix}_publishers`)
+      await knex.schema.createTable(`${tablePrefix}_publishers`, (table) => {
+        table.string('id').primary()
+        table.string('name').notNullable()
+        table.string('country_id').nullable()
+      })
+      mapTable(`${tablePrefix}_publishers`, 'publishers')
+
+      await api.addResource('tags', {
+        schema: {
+          id: { type: 'string', required: true },
+          name: { type: 'string', required: true, max: 100 }
+        },
+        tableName: `${tablePrefix}_tags`,
+        ...(pluginOptions.tagResourceOptions || {})
+      })
+      await knex.schema.dropTableIfExists(`${tablePrefix}_tags`)
+      await knex.schema.createTable(`${tablePrefix}_tags`, (table) => {
+        table.string('id').primary()
+        table.string('name').notNullable()
+      })
+      mapTable(`${tablePrefix}_tags`, 'tags')
+
+      await api.addResource('publisher_tags', {
+        schema: {
+          id: { type: 'id' },
+          publisher_id: { type: 'string', required: true, belongsTo: 'publishers', as: 'publisher' },
+          tag_id: { type: 'string', required: true, belongsTo: 'tags', as: 'tag' }
+        },
+        tableName: `${tablePrefix}_publisher_tags`
+      })
+      await knex.schema.dropTableIfExists(`${tablePrefix}_publisher_tags`)
+      await knex.schema.createTable(`${tablePrefix}_publisher_tags`, (table) => {
+        table.increments('id').primary()
+        table.string('publisher_id').notNullable()
+        table.string('tag_id').notNullable()
+      })
+      mapTable(`${tablePrefix}_publisher_tags`, 'publisher_tags')
+      if (storageMode.isAnyApi()) {
+        const descriptorTenant = api.anyapi?.tenantId || tenantId
+        const publishersDescriptor = await api.anyapi.registry.getDescriptor(descriptorTenant, 'publishers')
+        const tagsDescriptor = await api.anyapi.registry.getDescriptor(descriptorTenant, 'tags')
+        const relationshipKey = publishersDescriptor?.manyToMany?.tags?.relationship
+        const inverseRelationshipKey = tagsDescriptor?.manyToMany?.publishers?.relationship
+        storageMode.registerLink(
+          `${tablePrefix}_publisher_tags`,
+          'publishers',
+          'tags',
+          relationshipKey,
+          inverseRelationshipKey
+        )
+      }
+    })
+
+    return api
+  } finally {
+    if (storageMode.isAnyApi()) {
+      storageMode.setCurrentTenant(previousTenant)
+    }
+  }
+}
+
 /**
  * Creates a basic API with bulk operations enabled
  */
@@ -588,7 +856,6 @@ export async function createPaginationApi (knex, options = {}) {
  * Creates an API with WebSocket/Socket.IO support for testing
  */
 export async function createWebSocketApi (knex, pluginOptions = {}) {
-  const { SocketIOPlugin } = await import('../../plugins/core/socketio-plugin.js')
   const { jwtVerify } = await import('jose')
 
   const api = await createBasicApi(knex, {
@@ -1425,6 +1692,148 @@ export async function createAutoFilterApi (knex, pluginOptions = {}) {
   return api
 }
 
+export async function createRowPolicyApi (knex, pluginOptions = {}) {
+  const api = new Api({
+    name: 'row-policy-test-api',
+  })
+
+  const tenantId = storageMode.isAnyApi() ? 'row_policy_tenant' : storageMode.defaultTenant
+  const previousTenant = storageMode.currentTenant
+  if (storageMode.isAnyApi()) {
+    storageMode.setCurrentTenant(tenantId)
+  }
+
+  await api.use(RestApiPlugin, {
+    simplifiedApi: false,
+    simplifiedTransport: false,
+    returnRecordApi: {
+      post: true,
+      put: false,
+      patch: false
+    },
+    sortableFields: ['id', 'name', 'title', 'access_group', 'project_id']
+  })
+
+  await useStoragePlugin(api, knex, { tenantId })
+  await resetAnyApiTables(knex)
+
+  const rowPolicyOptions = pluginOptions.rowPolicy || {}
+  await api.use(RowPolicyPlugin, {
+    ...rowPolicyOptions,
+    policies: {
+      groupVisibility: ({ query, context, column, value, scopeName, queryPurpose }) => {
+        pluginOptions.onPolicy?.({ scopeName, queryPurpose })
+
+        if (context.visibility?.all === true) {
+          return true
+        }
+
+        const groups = context.visibility?.groups
+        if (!Array.isArray(groups) || groups.length === 0) {
+          return false
+        }
+
+        query.whereIn(
+          column('access_group'),
+          groups.map((group) => value('access_group', group))
+        )
+        return true
+      },
+      ...(rowPolicyOptions.policies || {})
+    }
+  })
+
+  await api.addResource('policy_projects', {
+    schema: {
+      id: { type: 'id' },
+      name: { type: 'string', required: true, max: 200 },
+      access_group: { type: 'string', required: true }
+    },
+    relationships: {
+      tasks: { type: 'hasMany', target: 'policy_tasks', foreignKey: 'project_id' },
+      shared_tasks: {
+        type: 'manyToMany',
+        target: 'policy_tasks',
+        through: 'policy_project_tasks',
+        foreignKey: 'project_id',
+        otherKey: 'task_id'
+      }
+    },
+    rowPolicy: 'groupVisibility',
+    tableName: 'row_policy_projects'
+  })
+  await api.resources.policy_projects.createKnexTable()
+  mapTable('row_policy_projects', 'policy_projects')
+
+  await api.addResource('policy_tasks', {
+    schema: {
+      id: { type: 'id' },
+      title: { type: 'string', required: true, max: 200, search: true },
+      access_group: { type: 'string', required: true },
+      project_id: {
+        type: 'number',
+        nullable: true,
+        belongsTo: 'policy_projects',
+        as: 'project',
+        search: true
+      }
+    },
+    relationships: {
+      shared_projects: {
+        type: 'manyToMany',
+        target: 'policy_projects',
+        through: 'policy_project_tasks',
+        foreignKey: 'task_id',
+        otherKey: 'project_id'
+      }
+    },
+    rowPolicy: 'groupVisibility',
+    tableName: 'row_policy_tasks'
+  })
+  await api.resources.policy_tasks.createKnexTable()
+  mapTable('row_policy_tasks', 'policy_tasks')
+
+  await api.addResource('policy_project_tasks', {
+    schema: {
+      id: { type: 'id' },
+      project_id: { type: 'number', required: true, belongsTo: 'policy_projects', as: 'project' },
+      task_id: { type: 'number', required: true, belongsTo: 'policy_tasks', as: 'task' }
+    },
+    tableName: 'row_policy_project_tasks'
+  })
+  await api.resources.policy_project_tasks.createKnexTable()
+  mapTable('row_policy_project_tasks', 'policy_project_tasks')
+
+  if (storageMode.isAnyApi()) {
+    const projectsDescriptor = await api.anyapi.registry.getDescriptor(tenantId, 'policy_projects')
+    const tasksDescriptor = await api.anyapi.registry.getDescriptor(tenantId, 'policy_tasks')
+    storageMode.registerLink(
+      'row_policy_project_tasks',
+      'policy_projects',
+      'shared_tasks',
+      projectsDescriptor?.manyToMany?.shared_tasks?.relationship,
+      tasksDescriptor?.manyToMany?.shared_projects?.relationship
+    )
+  }
+
+  await api.addResource('policy_broken', {
+    schema: {
+      id: { type: 'id' },
+      name: { type: 'string', required: true }
+    },
+    rowPolicy: () => undefined,
+    tableName: 'row_policy_broken'
+  })
+  await api.resources.policy_broken.createKnexTable()
+  mapTable('row_policy_broken', 'policy_broken')
+
+  if (storageMode.isAnyApi()) {
+    storageMode.setCurrentTenant(previousTenant)
+  }
+
+  return api
+}
+
 /**
  * Creates an API with positioning support for testing
  */
@@ -1714,7 +2123,7 @@ export async function createCursorPaginationApi (knex) {
       put: 'full',
       patch: 'minimal'
     },
-    sortableFields: ['id', 'name', 'category', 'brand', 'price', 'sku', 'created_at', 'code', 'status', 'type'],
+    sortableFields: ['id', 'name', 'category', 'brand', 'price', 'sku', 'createdAt', 'code', 'status', 'type'],
     queryDefaultLimit: 20,
     queryMaxLimit: 100,
     returnBasePath: 'https://api.example.com'
@@ -1734,11 +2143,12 @@ export async function createCursorPaginationApi (knex) {
       price: { type: 'number', required: true },
       sku: { type: 'string', required: true, max: 50, unique: true },
       status: { type: 'string', max: 50, default: 'active' },
-      created_at: { type: 'dateTime', default: 'now()' }
+      createdAt: { type: 'dateTime', default: 'now()' }
     },
     tableName: 'cursor_products'
   })
   await api.resources.products.createKnexTable()
+  mapTable('cursor_products', 'products')
 
   // Create items table with custom ID property
   await api.addResource('items', {
@@ -1753,6 +2163,7 @@ export async function createCursorPaginationApi (knex) {
     tableName: 'cursor_items'
   })
   await api.resources.items.createKnexTable()
+  mapTable('cursor_items', 'items')
 
   return api
 }
@@ -1915,3 +2326,83 @@ export async function createSearchSchemaMergeApi (knex, pluginOptions = {}) {
 
   return api
 }
+
+export async function createFileUploadApi (knex, pluginOptions = {}) {
+  const apiName = pluginOptions.apiName || 'file-upload-test-api'
+  const tableName = pluginOptions.tableName || 'file_documents'
+  const tablePrefix = pluginOptions.tablePrefix || 'file'
+  const storage = pluginOptions.storage
+  const detectorState = pluginOptions.detectorState || { payload: null }
+
+  if (!storage) {
+    throw new Error('createFileUploadApi requires a storage adapter')
+  }
+
+  if (storageMode.isAnyApi()) {
+    storageMode.clearRegistry()
+  }
+
+  const api = new Api({
+    name: apiName,
+    log: { level: process.env.LOG_LEVEL || 'info' }
+  })
+
+  const previousTenant = storageMode.currentTenant
+  const tenantId = storageMode.isAnyApi()
+    ? (pluginOptions.tenantId || `${tablePrefix}_tenant`)
+    : storageMode.defaultTenant
+
+  if (storageMode.isAnyApi()) {
+    storageMode.setCurrentTenant(tenantId)
+  }
+
+  try {
+    await api.use(RestApiPlugin, {
+      simplifiedApi: false,
+      simplifiedTransport: false,
+      returnRecordApi: {
+        post: true,
+        put: false,
+        patch: false
+      },
+      returnRecordTransport: {
+        post: 'full',
+        put: 'no',
+        patch: 'minimal'
+      },
+      sortableFields: ['id', 'title'],
+      ...pluginOptions['rest-api']
+    })
+    await useStoragePlugin(api, knex, { tenantId })
+    await resetAnyApiTables(knex)
+    await api.use(FileHandlingPlugin)
+
+    api.rest.registerFileDetector({
+      name: 'test-file-detector',
+      detect: () => Boolean(detectorState.payload),
+      parse: async () => detectorState.payload
+    })
+
+    await api.addResource('documents', {
+      schema: {
+        id: { type: 'id' },
+        title: { type: 'string', required: true },
+        attachment: {
+          type: 'file',
+          storage,
+          accepts: ['image/png'],
+          maxSize: '1mb'
+        }
+      },
+      tableName
+    })
+    await api.resources.documents.createKnexTable()
+    mapTable(tableName, 'documents')
+
+    return api
+  } finally {
+    if (storageMode.isAnyApi()) {
+      storageMode.setCurrentTenant(previousTenant)
+    }
+  }
+}

package/tests/full-jsonapi-belongsto-linkage.test.js

@@ -0,0 +1,150 @@
+import { after, before, beforeEach, describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+import knexLib from 'knex'
+import { createCamelCaseBelongsToApi } from './fixtures/api-configs.js'
+import {
+  createJsonApiDocument,
+  createRelationship,
+  resourceIdentifier,
+  assertResourceRelationship
+} from './helpers/test-utils.js'
+
+const knex = knexLib({
+  client: 'better-sqlite3',
+  connection: {
+    filename: ':memory:'
+  },
+  useNullAsDefault: true
+})
+
+let api
+
+describe('Full JSON:API belongsTo linkage', () => {
+  before(async () => {
+    api = await createCamelCaseBelongsToApi(knex)
+  })
+
+  after(async () => {
+    await knex.destroy()
+  })
+
+  beforeEach(async () => {
+    await knex('camel_fk_publishers').delete()
+    await knex('camel_fk_countries').delete()
+  })
+
+  const createCountry = async () => {
+    return api.resources.countries.post({
+      inputRecord: createJsonApiDocument('countries', {
+        name: 'United States'
+      }),
+      simplified: false
+    })
+  }
+
+  const createPublisher = async (countryId = null) => {
+    return api.resources.publishers.post({
+      inputRecord: createJsonApiDocument(
+        'publishers',
+        { name: 'Mapped Publisher' },
+        {
+          country: createRelationship(
+            countryId == null ? null : resourceIdentifier('countries', countryId)
+          )
+        }
+      ),
+      simplified: false
+    })
+  }
+
+  it('emits belongsTo linkage on primary resources without include for single and collection responses', async () => {
+    const country = await createCountry()
+    const publisher = await createPublisher(country.data.id)
+
+    assertResourceRelationship(
+      publisher.data,
+      'country',
+      resourceIdentifier('countries', country.data.id)
+    )
+    assert.equal(Object.hasOwn(publisher.data.attributes, 'countryId'), false)
+
+    const single = await api.resources.publishers.get({
+      id: publisher.data.id,
+      simplified: false
+    })
+
+    assertResourceRelationship(
+      single.data,
+      'country',
+      resourceIdentifier('countries', country.data.id)
+    )
+    assert.equal(Object.hasOwn(single.data.attributes, 'countryId'), false)
+
+    const collection = await api.resources.publishers.query({
+      simplified: false
+    })
+
+    assert.equal(collection.data.length, 1)
+    assertResourceRelationship(
+      collection.data[0],
+      'country',
+      resourceIdentifier('countries', country.data.id)
+    )
+    assert.equal(Object.hasOwn(collection.data[0].attributes, 'countryId'), false)
+  })
+
+  it('keeps primary belongsTo linkage when include is requested and adds included resources', async () => {
+    const country = await createCountry()
+    const publisher = await createPublisher(country.data.id)
+
+    const result = await api.resources.publishers.get({
+      id: publisher.data.id,
+      queryParams: {
+        include: ['country']
+      },
+      simplified: false,
+      returnFullRecord: 'full'
+    })
+
+    assertResourceRelationship(
+      result.data,
+      'country',
+      resourceIdentifier('countries', country.data.id)
+    )
+    assert.equal(Object.hasOwn(result.data.attributes, 'countryId'), false)
+    assert.equal(result.included?.length, 1)
+    assert.equal(result.included?.[0]?.type, 'countries')
+    assert.equal(result.included?.[0]?.id, country.data.id)
+  })
+
+  it('emits explicit null belongsTo linkage without exposing the foreign key attribute', async () => {
+    const country = await createCountry()
+    const publisher = await createPublisher(country.data.id)
+
+    const patched = await api.resources.publishers.patch({
+      id: publisher.data.id,
+      inputRecord: {
+        data: {
+          type: 'publishers',
+          id: publisher.data.id,
+          relationships: {
+            country: { data: null }
+          }
+        }
+      },
+      simplified: false,
+      returnFullRecord: 'full'
+    })
+
+    assert.equal(patched.data.relationships?.country?.data, null)
+    assert.equal(Object.hasOwn(patched.data.attributes, 'countryId'), false)
+
+    const single = await api.resources.publishers.get({
+      id: publisher.data.id,
+      simplified: false
+    })
+
+    assert.equal(single.data.relationships?.country?.data, null)
+    assert.equal(Object.hasOwn(single.data.attributes, 'countryId'), false)
+  })
+})