json-rest-api 1.0.29 → 2.1.0

package/tests/README.md

@@ -1,202 +0,0 @@
-# JSON-REST-API Test Suite
-
-This directory contains comprehensive tests for the JSON-REST-API library. All tests follow strict patterns to ensure proper JSON:API compliance and database integrity.
-
-## Test Files
-
-- **rest-api.test.js** - Basic CRUD operations (POST, GET, PATCH, DELETE)
-- **relationships.test.js** - One-to-one and many-to-many relationship operations
-- **queries.test.js** - Filtering, sorting, and pagination tests
-- **fixtures/api-configs.js** - API configuration factories
-- **helpers/test-utils.js** - Utility functions for JSON:API validation
-
-## Key Testing Principles
-
-### 1. Strict Mode
-
-All tests MUST use `simplified: false` to ensure JSON:API compliance:
-
-```javascript
-const result = await api.resources.resourceName.method({
-  inputRecord: jsonApiDocument,
-  simplified: false,
-  returnFullRecord: 'full' // Use 'no', 'minimal', or 'full' based on needs
-});
-```
-
-### 2. Relationship Handling
-
-Foreign keys must be set via relationships, NOT attributes:
-
-```javascript
-// ❌ WRONG - Will fail in strict mode
-const bookDoc = createJsonApiDocument('books', {
-  title: 'My Book',
-  country_id: countryId  // Foreign key in attributes
-});
-
-// ✅ CORRECT - Use relationships
-const bookDoc = createJsonApiDocument('books',
-  { title: 'My Book' },
-  {
-    country: createRelationship(resourceIdentifier('countries', countryId))
-  }
-);
-```
-
-### 3. Database Operations
-
-Only these Knex operations are allowed directly:
-
-```javascript
-// Counting records
-const count = await countRecords(knex, 'table_name');
-
-// Cleaning tables between tests
-await cleanTables(knex, ['table1', 'table2']);
-```
-
-All other operations MUST go through the API.
-
-### 4. API Configuration
-
-Always use the same schema pattern (Countries, Publishers, Authors, Books):
-
-```javascript
-// Each API config must use unique table prefixes
-tableName: 'basic_countries'  // For basicApi
-tableName: 'ext_countries'    // For extendedApi
-```
-
-### 5. Search & Sort Configuration
-
-Enable search on fields that need filtering:
-
-```javascript
-schema: {
-  title: { type: 'string', search: true },
-  country_id: { type: 'number', belongsTo: 'countries', as: 'country', search: true }
-}
-```
-
-Configure sortable fields in plugin options:
-
-```javascript
-await api.use(RestApiPlugin, {
-  sortableFields: ['id', 'title', 'country_id', 'price']
-});
-```
-
-## Common Test Patterns
-
-### Creating Resources with Relationships
-
-```javascript
-// One-to-one (belongsTo)
-const publisherDoc = createJsonApiDocument('publishers',
-  { name: 'Publisher Name' },
-  {
-    country: createRelationship(resourceIdentifier('countries', countryId))
-  }
-);
-
-// Many-to-many
-const bookDoc = createJsonApiDocument('books',
-  { title: 'Book Title' },
-  {
-    authors: createToManyRelationship([
-      resourceIdentifier('authors', author1Id),
-      resourceIdentifier('authors', author2Id)
-    ])
-  }
-);
-```
-
-### Validating Responses
-
-```javascript
-// Validate JSON:API structure
-validateJsonApiStructure(result, false);  // false = single resource
-
-// Validate attributes
-assertResourceAttributes(result.data, {
-  name: 'Expected Name',
-  code: 'EX'
-});
-
-// Validate relationships
-assertResourceRelationship(result.data, 'country',
-  resourceIdentifier('countries', countryId));
-```
-
-### Query Operations
-
-```javascript
-// Filtering
-const result = await api.resources.books.query({
-  queryParams: {
-    filters: { language: 'en', price: '9.99' }
-  },
-  simplified: false
-});
-
-// Sorting
-const result = await api.resources.books.query({
-  queryParams: {
-    sort: ['title', '-price']  // title ASC, price DESC
-  },
-  simplified: false
-});
-
-// Pagination
-const result = await api.resources.books.query({
-  queryParams: {
-    page: { number: 2, size: 10 }
-  },
-  simplified: false
-});
-```
-
-## Running Tests
-
-```bash
-# Run all tests
-npm test
-
-# Run the focused normalizeId verification path plus docs rebuild
-npm run verify
-
-# Run all tests against the AnyAPI storage backend
-npm run test:anyapi
-
-# Run only the normalizeId contract suites
-npm run test:id-contracts
-npm run test:id-contracts:anyapi
-
-# Windows PowerShell (AnyAPI run)
-$Env:JSON_REST_API_STORAGE = 'anyapi'; npm test
-
-# Run specific test file
-npm test -- tests/relationships.test.js
-
-# Run with verbose output
-DEBUG=* npm test
-```
-
-## Adding New Tests
-
-1. Create test file following naming convention: `feature-name.test.js`
-2. Import necessary utilities from `helpers/test-utils.js`
-3. Use API configurations from `fixtures/api-configs.js`
-4. Follow the established patterns for:
-   - Setting up test data
-   - Making API calls with `simplified: false`
-   - Validating JSON:API responses
-   - Cleaning data between tests
-
-## Important Notes
-
-- Tests intentionally generate ERROR logs for validation testing
-- All tests should pass with exit code 0
-- Database connections are properly closed in `after` hooks
-- Pivot table operations use `simplified: true` internally for foreign keys

package/tests/TEST_TEMPLATE.test.js

@@ -1,178 +0,0 @@
-import { describe, it, before, after, beforeEach } from 'node:test'
-import assert from 'node:assert/strict'
-import knexLib from 'knex'
-import {
-  validateJsonApiStructure,
-  cleanTables,
-  createJsonApiDocument,
-  assertResourceAttributes
-} from './helpers/test-utils.js'
-import { createBasicApi } from './fixtures/api-configs.js'
-
-/**
- * TEST TEMPLATE - BEST PRACTICES LEARNED
- *
- * CRITICAL RULES:
- * 1. Create API instance ONLY ONCE in before() - NOT in beforeEach()
- * 2. Use cleanTables() in beforeEach() to reset data between tests
- * 3. Always pass context as SECOND parameter to resource methods
- * 4. Clean up any intervals/timers in after() hook
- * 5. SQLite returns numeric IDs - JSON:API expects string IDs
- * 6. For auth tests, context.auth must be set via JWT token or passed manually
- *
- * NOTICE TO CLAUDE/AI ASSISTANTS:
- *
- * API CONFIGURATION RULES - EXTREMELY IMPORTANT:
- * 1. NEVER add resources with api.addResource() in test files!
- * 2. ALL resources MUST be defined in api-configs.js
- * 3. NEVER create resources in test files - this is a CRITICAL RULE!
- * 4. If createBasicApi doesn't have the resources you need:
- *    - DO NOT modify createBasicApi
- *    - Create a NEW function in api-configs.js like:
- *      export async function createExtendedApi(knex, pluginOptions) {
- *        const api = await createApi();
- *        // Install plugins
- *        // Add YOUR resources here with api.addResource()
- *        // Create tables
- *        return api;
- *      }
- * 5. Example structure in api-configs.js:
- *    - createBasicApi() - has countries, publishers, authors, books
- *    - createAuthApi() - might have users, roles, permissions
- *    - createYourCustomApi() - whatever resources you need
- *
- * RESOURCE CREATION RULE (REPEAT FOR EMPHASIS):
- * Resources are ONLY created in api-configs.js, NEVER in test files!
- * If you need new resources, create a new function in api-configs.js!
- *
- * DATA ACCESS RULES - EXTREMELY IMPORTANT:
- * 1. NEVER query the database directly with knex('table').select()
- * 2. ALWAYS use API methods to check data:
- *    - Use api.resources.[resource].get() to fetch a single item
- *    - Use api.resources.[resource].query() to fetch multiple items
- *    - Use api.resources.[resource].post() to create items
- * 3. Why? The API methods:
- *    - Apply proper schema transformations
- *    - Handle relationships correctly
- *    - Return data in the expected JSON:API format
- *    - Include computed fields and enriched attributes
- * 4. Direct DB queries will give you raw data that doesn't match what the API returns!
- *
- * BAD EXAMPLE:
- *   const record = await knex('basic_countries').where('id', 1).first();  // NO!
- *
- * GOOD EXAMPLE:
- *   const result = await api.resources.countries.get({ id: 1 });
- *   const record = result.data;  // YES!
- */
-
-// Create Knex instance for tests - always use SQLite in-memory
-const knex = knexLib({
-  client: 'better-sqlite3',
-  connection: {
-    filename: ':memory:'
-  },
-  useNullAsDefault: true
-})
-
-// API instance that persists across ALL tests
-let api
-
-describe('Your Feature Name (Template Example)', () => {
-  // IMPORTANT: before() runs ONCE for the entire test suite
-  before(async () => {
-    // Create API instance ONCE - this is reused for all tests
-    // NOTE: If you need different resources than what createBasicApi provides,
-    // create a new function in api-configs.js!
-    api = await createBasicApi(knex)
-
-    // Install your plugin if testing a specific plugin
-    // await api.use(YourPlugin, {
-    //   option1: 'value1',
-    //   option2: 'value2'
-    // });
-
-    // NO api.addResource() HERE! Resources are defined in api-configs.js!
-    // createBasicApi already created tables for: countries, publishers, authors, books
-  })
-
-  // IMPORTANT: after() cleans up resources
-  after(async () => {
-    // Clean up any intervals/timers your plugin might have created
-    // Example from JWT plugin:
-    // if (api.vars.yourPluginCleanupJob) {
-    //   clearInterval(api.vars.yourPluginCleanupJob);
-    // }
-
-    // Always destroy knex connection to allow tests to exit
-    await knex.destroy()
-  })
-
-  // IMPORTANT: beforeEach() cleans data but does NOT recreate API
-  beforeEach(async () => {
-    // Clean all tables - list ALL tables your tests use
-    await cleanTables(knex, [
-      'basic_countries',      // From createBasicApi
-      'basic_publishers',     // From createBasicApi
-      'basic_authors',        // From createBasicApi
-      'basic_books',          // From createBasicApi
-      'basic_book_authors'    // From createBasicApi (junction table)
-      // Add any additional tables used by your tests here
-    ])
-  })
-
-  // ONE SIMPLE EXAMPLE TEST
-  it('should create and retrieve a country', async () => {
-    // Create a country using the API
-    const doc = createJsonApiDocument('countries', {
-      name: 'Test Country',
-      code: 'TC'
-    })
-
-    // Create the country
-    // IMPORTANT: Context is SECOND parameter, not inside first parameter!
-    const createResult = await api.resources.countries.post({
-      inputRecord: doc,
-      simplified: false
-    }, { /* optional context goes here */ })
-
-    // Validate the creation response
-    validateJsonApiStructure(createResult)
-    assert.equal(createResult.data.type, 'countries')
-    assertResourceAttributes(createResult.data, {
-      name: 'Test Country',
-      code: 'TC'
-    })
-
-    // Retrieve the country we just created
-    const getResult = await api.resources.countries.get({
-      id: createResult.data.id,
-      simplified: false
-    })
-
-    // Validate the retrieved country
-    validateJsonApiStructure(getResult)
-    assert.equal(getResult.data.id, createResult.data.id)
-    assert.equal(getResult.data.attributes.name, 'Test Country')
-    assert.equal(getResult.data.attributes.code, 'TC')
-  })
-})
-
-/**
- * COMMON PITFALLS TO AVOID:
- *
- * 1. DON'T create API in beforeEach - it's expensive and unnecessary
- * 2. DON'T forget to clean tables between tests
- * 3. DON'T pass context inside params object - it's a separate parameter
- * 4. DON'T assume IDs are strings - SQLite returns numbers
- * 5. DON'T forget to clean up intervals/timers
- * 6. DON'T skip error cases - test both success and failure paths
- *
- * DEBUGGING TIPS:
- *
- * 1. Use console.log liberally when debugging, but remove before committing
- * 2. Check if your auth context is properly structured
- * 3. Validate that required fields are present in your test data
- * 4. Remember that HTTP routes have /api/ prefix by default
- * 5. Use debugger statements to pause execution and inspect state
- */

package/tests/anyapi-basic.test.js

@@ -1,105 +0,0 @@
-import { describe, it, before, beforeEach, after } from 'node:test'
-import assert from 'node:assert/strict'
-import knexLib from 'knex'
-import { Api } from 'hooked-api'
-
-import { RestApiPlugin, RestApiAnyapiKnexPlugin } from '../index.js'
-import { ensureAnyApiSchema } from '../plugins/core/lib/anyapi/schema-utils.js'
-
-const knex = knexLib({
-  client: 'better-sqlite3',
-  connection: { filename: ':memory:' },
-  useNullAsDefault: true,
-})
-
-let api
-
-describe('AnyAPI Knex Plugin - Basic Attributes', () => {
-  before(async () => {
-    try {
-      await ensureAnyApiSchema(knex)
-
-      api = new Api({ name: 'anyapi-test', log: { level: 'warn' } })
-      await api.use(RestApiPlugin, { simplifiedApi: false, simplifiedTransport: false })
-      await api.use(RestApiAnyapiKnexPlugin, { knex })
-
-      await api.addResource('countries', {
-        schema: {
-          id: { type: 'id' },
-          name: { type: 'string', required: true },
-          code: { type: 'string', required: true },
-        },
-      })
-
-      if (api.resources.countries?.createKnexTable) {
-        await api.resources.countries.createKnexTable()
-      }
-    } catch (error) {
-      console.error('Setup failed', error)
-      throw error
-    }
-  })
-
-  after(async () => {
-    await api.release()
-    await knex.destroy()
-  })
-
-  beforeEach(async () => {
-    await knex('any_records').truncate()
-  })
-
-  it('creates and retrieves records', async () => {
-    const result = await api.resources.countries.post({
-      inputRecord: {
-        data: {
-          type: 'countries',
-          attributes: {
-            name: 'Australia',
-            code: 'AU',
-          },
-        },
-      },
-      simplified: false,
-    }).catch((error) => {
-      console.error('POST failed', error)
-      throw error
-    })
-
-    assert.ok(result.data.id, 'should return new id')
-    assert.equal(result.data.attributes.name, 'Australia')
-
-    const stored = await knex('any_records').first()
-    assert.equal(stored.logical_id, result.data.id)
-    assert.equal(stored.string_1, 'Australia')
-    assert.equal(stored.string_2, 'AU')
-
-    const fetched = await api.resources.countries.get({ id: result.data.id, simplified: false })
-      .catch((error) => {
-        console.error('GET failed', error)
-        throw error
-      })
-    assert.equal(fetched.data.attributes.name, 'Australia')
-  })
-
-  it('lists records', async () => {
-    await knex('any_records').insert([{
-      logical_id: '1',
-      tenant_id: 'default',
-      resource: 'countries',
-      string_1: 'Canada',
-      string_2: 'CA',
-    }, {
-      logical_id: '2',
-      tenant_id: 'default',
-      resource: 'countries',
-      string_1: 'Brazil',
-      string_2: 'BR',
-    }])
-
-    const result = await api.resources.countries.query({ simplified: false })
-    assert.equal(result.data.length, 2)
-    const names = result.data.map((entry) => entry.attributes.name).sort()
-    assert.deepEqual(names, ['Brazil', 'Canada'])
-  })
-})

package/tests/anyapi-cursor-pagination.test.js

@@ -1,148 +0,0 @@
-import { describe, it, before, beforeEach, after } from 'node:test'
-import assert from 'node:assert/strict'
-import knexLib from 'knex'
-import { createPaginationApi } from './fixtures/api-configs.js'
-import {
-  cleanTables,
-  createJsonApiDocument,
-  createRelationship,
-  resourceIdentifier,
-} from './helpers/test-utils.js'
-import { storageMode } from './helpers/storage-mode.js'
-import { parseJsonApiQuery } from '../plugins/core/lib/querying-writing/connectors-query-parser.js'
-
-const isAnyApi = storageMode.isAnyApi()
-
-const maybeDescribe = isAnyApi ? describe : describe.skip
-
-const parseLinkQuery = (link) => {
-  const url = new URL(link, 'https://example.test')
-  return parseJsonApiQuery(url.search.slice(1))
-}
-
-maybeDescribe('AnyAPI Cursor Pagination', () => {
-  const knex = knexLib({
-    client: 'better-sqlite3',
-    connection: { filename: ':memory:' },
-    useNullAsDefault: true,
-  })
-
-  let api
-
-  before(async () => {
-    api = await createPaginationApi(knex)
-  })
-
-  after(async () => {
-    await knex.destroy()
-  })
-
-  beforeEach(async () => {
-    await cleanTables(knex, [
-      'pagination_countries',
-      'pagination_publishers',
-      'pagination_books',
-    ])
-
-    const country = await api.resources.countries.post({
-      inputRecord: createJsonApiDocument('countries', { name: 'Cursorland', code: 'CL' }),
-      simplified: false,
-    })
-
-    const publisher = await api.resources.publishers.post({
-      inputRecord: createJsonApiDocument(
-        'publishers',
-        { name: 'Cursor Press' },
-        { country: createRelationship(resourceIdentifier('countries', country.data.id)) }
-      ),
-      simplified: false,
-    })
-
-    const titles = ['Book A', 'Book B', 'Book C', 'Book D', 'Book E', 'Book F']
-    for (const title of titles) {
-      await api.resources.books.post({
-        inputRecord: createJsonApiDocument(
-          'books',
-          { title },
-          {
-            country: createRelationship(resourceIdentifier('countries', country.data.id)),
-            publisher: createRelationship(resourceIdentifier('publishers', publisher.data.id)),
-          }
-        ),
-        simplified: false,
-      })
-    }
-  })
-
-  it('returns cursor metadata and links when requesting the first page', async () => {
-    const result = await api.resources.books.query({
-      queryParams: {
-        page: { size: 2 },
-      },
-      simplified: false,
-    })
-
-    assert.equal(result.data.length, 2)
-    assert(result.meta?.pagination?.cursor?.next, 'Should include next cursor')
-    assert(parseLinkQuery(result.links?.next).page.after, 'Next link should include cursor parameter')
-  })
-
-  it('paginates forward using page[after]', async () => {
-    const firstPage = await api.resources.books.query({
-      queryParams: {
-        page: { size: 2 },
-      },
-      simplified: false,
-    })
-
-    const cursor = firstPage.meta.pagination.cursor.next
-    const secondPage = await api.resources.books.query({
-      queryParams: {
-        page: { size: 2, after: cursor },
-      },
-      simplified: false,
-    })
-
-    assert.equal(secondPage.data.length, 2)
-    const firstIds = firstPage.data.map((book) => book.id)
-    const secondIds = secondPage.data.map((book) => book.id)
-    assert(!secondIds.some((id) => firstIds.includes(id)), 'Second page should not repeat first page records')
-  })
-
-  it('paginates backward using page[before]', async () => {
-    const firstPage = await api.resources.books.query({
-      queryParams: {
-        page: { size: 2 },
-      },
-      simplified: false,
-    })
-
-    const secondPage = await api.resources.books.query({
-      queryParams: {
-        page: {
-          size: 2,
-          after: firstPage.meta.pagination.cursor.next,
-        },
-      },
-      simplified: false,
-    })
-
-    const beforeCursor = `id:${encodeURIComponent(secondPage.data[0].id)}`
-
-    const previousPage = await api.resources.books.query({
-      queryParams: {
-        page: {
-          size: 2,
-          before: beforeCursor,
-        },
-      },
-      simplified: false,
-    })
-
-    const secondIds = secondPage.data.map((book) => book.id)
-    const previousIds = previousPage.data.map((book) => book.id)
-    assert(!previousIds.some((id) => secondIds.includes(id)), 'Page[before] should return different records')
-    const firstIds = firstPage.data.map((book) => book.id)
-    assert(previousIds.every((id) => firstIds.includes(id)), 'Page[before] should return earlier records')
-  })
-})