json-rest-api 1.0.22 → 1.0.24

package/tests/searchschema-knex-behavior.test.js

@@ -0,0 +1,187 @@
+import { describe, it, before, beforeEach, after } from 'node:test'
+import assert from 'node:assert/strict'
+import knexLib from 'knex'
+import {
+  cleanTables,
+  createJsonApiDocument,
+} from './helpers/test-utils.js'
+import { storageMode } from './helpers/storage-mode.js'
+import { createSearchSchemaMergeApi } from './fixtures/api-configs.js'
+
+const maybeDescribe = storageMode.isAnyApi() ? describe.skip : describe
+
+// Create Knex instance for tests - always use SQLite in-memory
+const knex = knexLib({
+  client: 'better-sqlite3',
+  connection: {
+    filename: ':memory:'
+  },
+  useNullAsDefault: true
+})
+
+maybeDescribe('SearchSchema Merge Behavior (Knex execution)', () => {
+  let api
+
+  before(async () => {
+    api = await createSearchSchemaMergeApi(knex)
+  })
+
+  after(async () => {
+    await knex.destroy()
+  })
+
+  beforeEach(async () => {
+    await cleanTables(knex, ['searchmerge_products', 'searchmerge_users', 'searchmerge_orders'])
+  })
+
+  it('should use exact matching for search:true strings unless filterOperator is explicit', async () => {
+    const context = {}
+
+    await api.resources.users.post({
+      inputRecord: createJsonApiDocument('users', {
+        username: 'ann',
+        email: 'ann@example.com',
+        bio: 'Writes API guides'
+      })
+    }, context)
+
+    await api.resources.users.post({
+      inputRecord: createJsonApiDocument('users', {
+        username: 'anna',
+        email: 'anna@example.com',
+        bio: 'Writing API tutorials'
+      })
+    }, context)
+
+    const usernameResults = await api.resources.users.query({
+      queryParams: {
+        filters: {
+          username: 'ann'
+        }
+      }
+    }, context)
+
+    assert.equal(usernameResults.data.length, 1, 'search:true username should use exact matching')
+    assert.equal(usernameResults.data[0].attributes.username, 'ann')
+
+    const bioResults = await api.resources.users.query({
+      queryParams: {
+        filters: {
+          bio: 'Writ'
+        }
+      }
+    }, context)
+
+    assert.equal(bioResults.data.length, 2, 'explicit like operator should still support partial matching')
+  })
+
+  it('should allow filtering with merged searchSchema fields', async () => {
+    const context = {}
+
+    await api.resources.products.post({
+      inputRecord: createJsonApiDocument('products', {
+        name: 'Widget A',
+        description: 'A great widget',
+        price: 50,
+        sku: 'WGT-001',
+        status: 'active'
+      })
+    }, context)
+
+    await api.resources.products.post({
+      inputRecord: createJsonApiDocument('products', {
+        name: 'Widget B',
+        description: 'Another widget',
+        price: 150,
+        sku: 'WGT-002',
+        status: 'inactive'
+      })
+    }, context)
+
+    const nameResults = await api.resources.products.query({
+      queryParams: {
+        filters: {
+          name: 'Widget A'
+        }
+      }
+    }, context)
+    assert.equal(nameResults.data.length, 1, 'Should find one product by name')
+    assert.equal(nameResults.data[0].attributes.name, 'Widget A')
+
+    const priceResults = await api.resources.products.query({
+      queryParams: {
+        filters: {
+          price: [40, 60]
+        }
+      }
+    }, context)
+    assert.equal(priceResults.data.length, 1, 'Should find one product in price range')
+    assert.equal(priceResults.data[0].attributes.price, 50)
+
+    const statusResults = await api.resources.products.query({
+      queryParams: {
+        filters: {
+          status: ['active']
+        }
+      }
+    }, context)
+    assert.equal(statusResults.data.length, 1, 'Should find one active product')
+    assert.equal(statusResults.data[0].attributes.status, 'active')
+
+    const skuResults = await api.resources.products.query({
+      queryParams: {
+        filters: {
+          sku: 'WGT-002'
+        }
+      }
+    }, context)
+    assert.equal(skuResults.data.length, 1, 'Should find one product by SKU')
+    assert.equal(skuResults.data[0].attributes.sku, 'WGT-002')
+  })
+
+  it('should support arbitrary public filter keys when searchSchema maps them intentionally', async () => {
+    const context = {}
+
+    await api.resources.products.post({
+      inputRecord: createJsonApiDocument('products', {
+        name: 'Widget Alpha',
+        description: 'The great all-purpose widget',
+        price: 50,
+        sku: 'WGT-101',
+        status: 'active'
+      })
+    }, context)
+
+    await api.resources.products.post({
+      inputRecord: createJsonApiDocument('products', {
+        name: 'Widget Beta',
+        description: 'A quiet replacement unit',
+        price: 60,
+        sku: 'WGT-102',
+        status: 'inactive'
+      })
+    }, context)
+
+    const aliasResults = await api.resources.products.query({
+      queryParams: {
+        filters: {
+          term: 'great'
+        }
+      }
+    }, context)
+
+    assert.equal(aliasResults.data.length, 1, 'term should be resolved by backend search mapping')
+    assert.equal(aliasResults.data[0].attributes.name, 'Widget Alpha')
+
+    const customResults = await api.resources.products.query({
+      queryParams: {
+        filters: {
+          availability: true
+        }
+      }
+    }, context)
+
+    assert.equal(customResults.data.length, 1, 'availability should be interpreted by backend custom filter logic')
+    assert.equal(customResults.data[0].attributes.status, 'active')
+  })
+})

package/tests/searchschema-merge.test.js

@@ -3,8 +3,6 @@ import assert from 'node:assert/strict'
 import knexLib from 'knex'
 import {
   cleanTables,
-  createJsonApiDocument,
-  createRelationship
 } from './helpers/test-utils.js'
 import { createSearchSchemaMergeApi } from './fixtures/api-configs.js'
 
@@ -63,11 +61,18 @@ describe('SearchSchema Merge Behavior', () => {
     assert.ok(searchSchema.structure.price, 'price field should be searchable')
     assert.equal(searchSchema.structure.price.filterOperator, 'between', 'price should use between operator from searchSchema')
 
+    // Check that arbitrary public filter keys are allowed when defined intentionally
+    assert.ok(searchSchema.structure.term, 'term alias should be searchable')
+    assert.deepEqual(searchSchema.structure.term.oneOf, ['name', 'description'], 'term should map to multiple fields')
+
     // Check that virtual fields from searchSchema are present
     assert.ok(searchSchema.structure.category_name, 'category_name virtual field should be searchable')
     assert.equal(searchSchema.structure.category_name.filterOperator, 'like', 'category_name should use like operator')
     assert.equal(searchSchema.structure.category_name.actualField, 'category.name', 'category_name should map to category.name')
 
+    assert.ok(searchSchema.structure.availability, 'availability custom filter should be searchable')
+    assert.equal(typeof searchSchema.structure.availability.applyFilter, 'function', 'availability should use custom backend logic')
+
     // Check explicit searchSchema field not marked with search:true
     assert.ok(searchSchema.structure.status, 'status field should be searchable from searchSchema')
     assert.equal(searchSchema.structure.status.filterOperator, 'in', 'status should use in operator')
@@ -111,72 +116,19 @@ describe('SearchSchema Merge Behavior', () => {
     assert.ok(!searchSchema.structure.total, 'total should not be searchable')
   })
 
-  it('should allow filtering with merged searchSchema fields', async () => {
-    const context = {}
-
-    // Create some test data using API methods
-    const product1 = await api.resources.products.post({
-      inputRecord: createJsonApiDocument('products', {
-        name: 'Widget A',
-        description: 'A great widget',
-        price: 50,
-        sku: 'WGT-001',
-        status: 'active'
-      })
-    }, context)
-
-    const product2 = await api.resources.products.post({
-      inputRecord: createJsonApiDocument('products', {
-        name: 'Widget B',
-        description: 'Another widget',
-        price: 150,
-        sku: 'WGT-002',
-        status: 'inactive'
-      })
-    }, context)
-
-    // Test filtering with field from search:true
-    const nameResults = await api.resources.products.query({
-      queryParams: {
-        filters: {
-          name: 'Widget A'
-        }
-      }
-    }, context)
-    assert.equal(nameResults.data.length, 1, 'Should find one product by name')
-    assert.equal(nameResults.data[0].attributes.name, 'Widget A')
-
-    // Test filtering with field from explicit searchSchema (between operator)
-    const priceResults = await api.resources.products.query({
-      queryParams: {
-        filters: {
-          price: [40, 60]  // Between 40 and 60
-        }
-      }
-    }, context)
-    assert.equal(priceResults.data.length, 1, 'Should find one product in price range')
-    assert.equal(priceResults.data[0].attributes.price, 50)
-
-    // Test filtering with explicit searchSchema field (in operator)
-    const statusResults = await api.resources.products.query({
-      queryParams: {
-        filters: {
-          status: ['active']
-        }
-      }
-    }, context)
-    assert.equal(statusResults.data.length, 1, 'Should find one active product')
-    assert.equal(statusResults.data[0].attributes.status, 'active')
-
-    // Test filtering with search:true field that wasn't overridden
-    const skuResults = await api.resources.products.query({
-      queryParams: {
-        filters: {
-          sku: 'WGT-002'
-        }
-      }
-    }, context)
-    assert.equal(skuResults.data.length, 1, 'Should find one product by SKU')
-    assert.equal(skuResults.data[0].attributes.sku, 'WGT-002')
+  it('should reject invalid filter keys that are not part of the public searchSchema contract', async () => {
+    await assert.rejects(
+      async () => {
+        await api.resources.products.query({
+          queryParams: {
+            filters: {
+              invalid_field: 'nope'
+            }
+          }
+        })
+      },
+      (error) => error?.code === 'REST_API_VALIDATION',
+      'Should reject fields that are not defined in searchSchema'
+    )
   })
 })

package/tests/storage-mapping.test.js

@@ -0,0 +1,259 @@
+import { describe, it, before, after, beforeEach } from 'node:test'
+import assert from 'node:assert/strict'
+import knexLib from 'knex'
+import { Api } from 'hooked-api'
+import { RestApiPlugin } from '../plugins/core/rest-api-plugin.js'
+import { RestApiKnexPlugin } from '../plugins/core/rest-api-knex-plugin.js'
+import {
+  cleanTables,
+  createJsonApiDocument,
+  createRelationship,
+  resourceIdentifier,
+  assertResourceAttributes,
+  assertResourceRelationship,
+  validateJsonApiStructure,
+} from './helpers/test-utils.js'
+
+const knex = knexLib({
+  client: 'better-sqlite3',
+  connection: {
+    filename: ':memory:'
+  },
+  useNullAsDefault: true
+})
+
+let api
+
+const serializeDateTimeForSql = (value) => {
+  if (value == null) return null
+  if (!(value instanceof Date)) {
+    throw new Error('serializeDateTimeForSql expects a Date value after schema normalization')
+  }
+
+  return value.toISOString().replace('T', ' ').slice(0, 19)
+}
+
+describe('Storage mapping', () => {
+  before(async () => {
+    api = new Api({
+      name: 'storage-mapping-test',
+    })
+
+    await api.use(RestApiPlugin, {
+      simplifiedApi: false,
+      simplifiedTransport: false,
+      returnRecordApi: {
+        post: 'full',
+        put: 'full',
+        patch: 'full'
+      },
+      returnRecordTransport: {
+        post: 'full',
+        put: 'full',
+        patch: 'full'
+      }
+    })
+    await api.use(RestApiKnexPlugin, { knex })
+
+    await api.addResource('countries', {
+      schema: {
+        id: { type: 'id' },
+        name: { type: 'string', required: true }
+      },
+      relationships: {
+        profiles: { type: 'hasMany', target: 'profiles', foreignKey: 'country_id' }
+      },
+      tableName: 'mapped_countries'
+    })
+    await api.resources.countries.createKnexTable()
+
+    await api.addResource('profiles', {
+      schema: {
+        id: { type: 'id' },
+        displayName: { type: 'string', required: true, search: true },
+        loginCount: { type: 'number', defaultTo: 0 },
+        lastSeenAt: {
+          type: 'dateTime',
+          nullable: true,
+          storage: {
+            serialize: serializeDateTimeForSql
+          }
+        },
+        countryId: {
+          type: 'id',
+          nullable: true,
+          belongsTo: 'countries',
+          as: 'country'
+        },
+        externalRef: { type: 'string', nullable: true, search: true, storage: { column: 'legacy_ref' } },
+        confirmationToken: { type: 'string', virtual: true }
+      },
+      tableName: 'mapped_profiles'
+    })
+    await api.resources.profiles.createKnexTable()
+
+    await api.addResource('verbatim_profiles', {
+      storage: { naming: 'exact' },
+      schema: {
+        id: { type: 'id' },
+        displayName: { type: 'string', required: true },
+        loginCount: { type: 'number', defaultTo: 0 }
+      },
+      tableName: 'verbatim_profiles'
+    })
+    await api.resources.verbatim_profiles.createKnexTable()
+  })
+
+  after(async () => {
+    await knex.destroy()
+  })
+
+  beforeEach(async () => {
+    await cleanTables(knex, ['mapped_profiles', 'mapped_countries', 'verbatim_profiles'])
+  })
+
+  it('persists mapped columns while exposing logical field names', async () => {
+    const country = await api.resources.countries.post({
+      inputRecord: createJsonApiDocument('countries', {
+        name: 'Australia'
+      })
+    })
+
+    const createResult = await api.resources.profiles.post({
+      inputRecord: createJsonApiDocument(
+        'profiles',
+        {
+          displayName: 'Mercury',
+          loginCount: 7,
+          lastSeenAt: '2026-01-02T03:04:05Z',
+          externalRef: 'legacy-001',
+          confirmationToken: 'secret-token'
+        },
+        {
+          country: createRelationship(resourceIdentifier('countries', country.data.id))
+        }
+      )
+    })
+
+    validateJsonApiStructure(createResult)
+    assertResourceAttributes(createResult.data, {
+      displayName: 'Mercury',
+      loginCount: 7
+    })
+    assert.equal(createResult.data.attributes.confirmationToken, 'secret-token')
+    assert.ok(createResult.data.attributes.lastSeenAt instanceof Date)
+    assert.equal(createResult.data.attributes.lastSeenAt.toISOString(), '2026-01-02T03:04:05.000Z')
+    assert.ok(!('display_name' in createResult.data.attributes))
+    assert.ok(!('country_id' in createResult.data.attributes))
+
+    const dbRecord = await knex('mapped_profiles').first()
+    assert.equal(dbRecord.display_name, 'Mercury')
+    assert.equal(dbRecord.login_count, 7)
+    assert.equal(dbRecord.last_seen_at, '2026-01-02 03:04:05')
+    assert.equal(String(dbRecord.country_id), country.data.id)
+    assert.equal(dbRecord.legacy_ref, 'legacy-001')
+    assert.ok(!('displayName' in dbRecord))
+    assert.ok(!('countryId' in dbRecord))
+    assert.ok(!('confirmationToken' in dbRecord))
+
+    const getResult = await api.resources.profiles.get({
+      id: createResult.data.id,
+      queryParams: {
+        include: ['country']
+      }
+    })
+
+    validateJsonApiStructure(getResult)
+    assertResourceAttributes(getResult.data, {
+      displayName: 'Mercury',
+      loginCount: 7
+    })
+    assert.ok(getResult.data.attributes.lastSeenAt instanceof Date)
+    assert.equal(getResult.data.attributes.lastSeenAt.toISOString(), '2026-01-02T03:04:05.000Z')
+    assert.ok(!('display_name' in getResult.data.attributes))
+    assertResourceRelationship(
+      getResult.data,
+      'country',
+      resourceIdentifier('countries', country.data.id)
+    )
+
+    const queryResult = await api.resources.profiles.query({
+      queryParams: {
+        filters: {
+          displayName: 'Mercury',
+          externalRef: 'legacy-001'
+        }
+      }
+    })
+
+    validateJsonApiStructure(queryResult, true)
+    assert.equal(queryResult.data.length, 1)
+    assertResourceAttributes(queryResult.data[0], {
+      displayName: 'Mercury',
+      externalRef: 'legacy-001'
+    })
+  })
+
+  it('applies storage mapping on PATCH updates and sparse fieldsets', async () => {
+    const created = await api.resources.profiles.post({
+      inputRecord: createJsonApiDocument('profiles', {
+        displayName: 'Before',
+        loginCount: 1,
+        lastSeenAt: '2026-01-01T00:00:00Z'
+      })
+    })
+
+    const patchResult = await api.resources.profiles.patch({
+      id: created.data.id,
+      inputRecord: {
+        data: {
+          type: 'profiles',
+          id: created.data.id,
+          attributes: {
+            displayName: 'After',
+            lastSeenAt: '2026-02-03T04:05:06Z',
+            confirmationToken: 'updated-token'
+          }
+        }
+      },
+      queryParams: {
+        fields: {
+          profiles: 'displayName,lastSeenAt,confirmationToken'
+        }
+      }
+    })
+
+    validateJsonApiStructure(patchResult)
+    assert.deepEqual(Object.keys(patchResult.data.attributes).sort(), ['confirmationToken', 'displayName', 'lastSeenAt'])
+    assert.equal(patchResult.data.attributes.displayName, 'After')
+    assert.equal(patchResult.data.attributes.confirmationToken, 'updated-token')
+    assert.ok(patchResult.data.attributes.lastSeenAt instanceof Date)
+    assert.equal(patchResult.data.attributes.lastSeenAt.toISOString(), '2026-02-03T04:05:06.000Z')
+
+    const dbRecord = await knex('mapped_profiles').where('id', created.data.id).first()
+    assert.equal(dbRecord.display_name, 'After')
+    assert.equal(dbRecord.last_seen_at, '2026-02-03 04:05:06')
+    assert.ok(!('displayName' in dbRecord))
+  })
+
+  it('can opt out of snake_case translation for an entire resource', async () => {
+    const created = await api.resources.verbatim_profiles.post({
+      inputRecord: createJsonApiDocument('verbatim_profiles', {
+        displayName: 'Exact Mode',
+        loginCount: 3
+      })
+    })
+
+    validateJsonApiStructure(created)
+    assertResourceAttributes(created.data, {
+      displayName: 'Exact Mode',
+      loginCount: 3
+    })
+
+    const dbRecord = await knex('verbatim_profiles').where('id', created.data.id).first()
+    assert.equal(dbRecord.displayName, 'Exact Mode')
+    assert.equal(dbRecord.loginCount, 3)
+    assert.equal(Object.hasOwn(dbRecord, 'display_name'), false)
+    assert.equal(Object.hasOwn(dbRecord, 'login_count'), false)
+  })
+})

package/audit/00-charter.md

@@ -1,103 +0,0 @@
-# Technical Audit Charter
-
-## Mission
-Produce a formal, evidence-driven audit of architecture quality, code quality, standards alignment, competitive positioning, and operational risk for:
-- `/home/merc/Development/current/json-rest-api`
-- `/home/merc/Development/current/json-rest-schema`
-
-## Scope
-### Included
-- Runtime architecture, data/control flow, and plugin interactions for non-`anyapi` code paths.
-- Schema compilation/validation behavior in `json-rest-schema` and its integration surface in `json-rest-api`.
-- Test and documentation alignment for critical behavior.
-- Runtime/test corroboration for risk classification.
-
-### Explicit Exclusions
-- `anyapi` implementation and behavior are fully out-of-scope for conclusions, scoring, and recommendations.
-- Excluded path classes (json-rest-api):
-  - `plugins/core/lib/anyapi/**`
-  - `plugins/core/rest-api-anyapi-knex-plugin.js`
-  - `tests/anyapi-*.test.js`
-  - `scripts/*anyapi*`
-
-## Baseline Freeze
-- Baseline commits: `audit/evidence/runtime/baseline-commits.txt`
-- Environment metadata: `audit/evidence/runtime/environment.txt`
-- DB adapter assumptions: `audit/evidence/runtime/db-adapter-assumptions.txt`
-- Standards/competitor corpus freeze: `audit/evidence/external/corpus-freeze.md`
-
-## Evidence Policy
-1. No claim without file-level and/or runtime/test evidence reference.
-2. No high-severity risk without corroborating runtime/test signal.
-3. Critical files require dual-pass review (pass 1 + cross-review pass 2).
-4. Assertions must be tagged as:
-   - `Verified`: directly confirmed by code/runtime/test evidence.
-   - `Inferred`: logically derived from verified evidence.
-   - `Unknown`: evidence missing or inconclusive.
-5. Unknowns are tracked explicitly in subsystem reports and findings.
-
-## Severity Model
-- Inputs:
-  - Impact: `1-5`
-  - Likelihood: `1-5`
-  - Detectability: `1-5` (higher means easier to detect)
-- Formula:
-  - `severity_score = impact * likelihood * (6 - detectability)`
-  - Range: `1..125`
-- Bands:
-  - `High`: `>= 60`
-  - `Medium`: `30-59`
-  - `Low`: `< 30`
-
-## Confidence Model
-- `C1 Very Low`: weak signal, mostly inferred.
-- `C2 Low`: limited direct evidence.
-- `C3 Medium`: direct code evidence + partial corroboration.
-- `C4 High`: direct code evidence + test/runtime corroboration.
-- `C5 Very High`: repeated corroboration across code, runtime, and tests.
-
-## Scoring Model
-Each major dimension scored `1-5`, evidence-backed:
-- Correctness
-- Security
-- Resilience
-- Performance
-- Maintainability
-- Observability
-- Test quality
-
-Aggregate score is reported as profile (not single opaque number) plus weighted composite:
-- Correctness `20%`
-- Security `20%`
-- Resilience `15%`
-- Performance `15%`
-- Maintainability `15%`
-- Observability `5%`
-- Test quality `10%`
-
-## Deliverables
-- `audit/00-charter.md`
-- `audit/01-scope-map.md`
-- `audit/02-coverage-matrix.csv`
-- `audit/03-invariants.md`
-- `audit/04-standards-rubric.md`
-- `audit/05-competitor-rubric.md`
-- `audit/06-findings.md`
-- `audit/07-risk-register.csv`
-- `audit/08-remediation-roadmap.md`
-- `audit/subsystems/*.md`
-- `audit/traces/*.md`
-- `audit/evidence/**`
-
-## Signoff Criteria
-1. 100% critical-file dual-pass coverage.
-2. 100% invariants not left unknown in final state.
-3. 100% high-severity risks have mitigation + verification test.
-4. Standards and competitor matrices complete with evidence.
-5. Prioritized remediation roadmap with exit criteria.
-6. Final synthesis includes residual risk and confidence summary.
-
-## Reproducibility Commands (Baseline)
-- `git rev-parse HEAD` in each repo.
-- `node -v && npm -v && uname -a`
-- `git ls-files` inventories captured under `audit/evidence/code/`.