json-rest-api 1.0.7 → 1.0.8

package/example.js

@@ -1,301 +0,0 @@
-import { Api } from 'hooked-api';
-import { RestApiPlugin, RestApiKnexPlugin } from './index.js';
-import knexLib from 'knex';
-import util from 'util';
-
-
-// import { setupDatabase } from './setup-database.js';
-
-// 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',
-  version: '1.0.0'
-});
-
-// Install plugins
-await api.use(RestApiPlugin);
-await api.use(RestApiKnexPlugin, { knex });
-
-// Define schemas for our book catalog system
-
-// Countries table
-await api.addResource('countries', {
-  schema: {
-    name: { type: 'string', required: true, max: 100 },
-    code: { type: 'string', max: 2, unique: true }, // ISO country code
-  },
-  relationships: {
-    publishers: { hasMany: 'publishers', foreignKey: 'country_id' },
-    books: { hasMany: 'books', foreignKey: 'country_id' }
-  },
-  returnFullRecord: {
-    post: false,
-    patch: false,
-    put: false
-  },
-  // tableName: 'stocazzo',
-  // idProperty: 'anotherId'
-});
-await api.resources.countries.createKnexTable()
-
-// Publishers table
-await api.addResource('publishers', {
-  schema: {
-    name: { type: 'string', required: true, max: 200 },
-    country_id: { type: 'number',  belongsTo: 'countries', as: 'country' },
-  },
-  relationships: {
-    books: { hasMany: 'books', foreignKey: 'publisher_id' }
-  }
-});
-await api.resources.publishers.createKnexTable()
-
-// Authors table
-await api.addResource('authors', {
-  schema: {
-    name: { type: 'string', required: true, max: 200 },
-  },
-  relationships: {
-    books: { hasMany: 'books', through: 'book_authors', foreignKey: 'author_id', otherKey: 'book_id' }
-  }
-});
-await api.resources.authors.createKnexTable()
-
-// Books table
-await api.addResource('books', {
-  schema: {
-    title: { type: 'string', required: true, max: 300 },
-    country_id: { type: 'number', required: true, belongsTo: 'countries', as: 'country' },
-    publisher_id: { type: 'number', belongsTo: 'publishers', as: 'publisher' },
-  },
-  relationships: {
-    authors: { hasMany: 'authors', through: 'book_authors', foreignKey: 'book_id', otherKey: 'author_id' },
-  }
-});
-await api.resources.books.createKnexTable()
-
-// Book-Authors pivot table (many-to-many relationship)
-await api.addResource('book_authors', {
-  schema: {
-    book_id: { type: 'number', required: true, belongsTo: 'books', as: 'book' },
-    author_id: { type: 'number', required: true, belongsTo: 'authors', as: 'author' },
-  }
-});
-await api.resources.book_authors.createKnexTable()
-
-
-
-/////////////////////////////////////////////////////////////////////////////////////////////
-
-
-// Now you can use the API directly in your code
-try {
-
-  // Create a country
-  const countryResult1 = await api.resources.countries.post({
-    name: 'United States',
-    code: 'US'
-  });
-  console.log('Created country:', countryResult1);
-
-  // Create another country
-  const countryResult2 = await api.resources.countries.post({
-    name: 'United Kingdom',
-  });
-  console.log('Created country:', countryResult2);
-
-  // Create publisher using the OLD way (foreign key field name)
-  const publisher1Result = await api.resources.publishers.post({
-    name: 'Penguin Random House',
-    country_id: countryResult1.id
-  });
-  console.log('Created publisher1 (using country_id):', publisher1Result);
-
-  // Create publisher using the NEW way (relationship alias)
-  const publisher1bResult = await api.resources.publishers.post({
-    name: 'HarperCollins',
-    country: countryResult2.id  // Using 'country' instead of 'country_id'
-  });
-  console.log('Created publisher1b (using country alias):', publisher1bResult);
-
-  debugger
-  // Test error case: providing both country_id and country
-  try {
-    await api.resources.publishers.post({
-      name: 'Invalid Publisher',
-      country_id: countryResult1.id,
-      country: countryResult2.id  // ERROR: both specified!
-    });
-  } catch (error) {
-    console.log('Expected error when both country_id and country are provided:', error.message);
-  }
-
-    // Create another publisher. NOT the simplified version
-  const publisher2Result = await api.resources.publishers.post({
-    inputRecord: {
-      data: {
-        type: 'publishers',
-        attributes: {
-          name: 'Apress'
-        },
-        relationships: {
-          country: {
-            data: { type: 'countries', id: countryResult1.id }
-          }
-        }
-      }
-    },
-    simplified: false
-  });
-  console.log('Created publisher:', publisher2Result);
-
-
-  const fetchedPublisher = await api.resources.publishers.get({ 
-    id: publisher2Result.data.id,
-    queryParams: { include: ['country']},
-    simplified: false
-  }) 
-  console.log('Refetched publisher:', util.inspect(fetchedPublisher, { depth: 5 }));
-
-// Create a publisher
-  const publisherResult = await api.resources.publishers.post({
-    inputRecord: {
-      data: {
-        type: 'publishers',
-        attributes: {
-          name: 'Penguin Random House'
-        },
-        relationships: {
-          country: {
-            data: { type: 'countries', id: countryResult1.id }
-          }
-        }
-      }
-    }
-  });
-
-
-  // Create authors
-  const author1Result = await api.resources.authors.post({
-    inputRecord: {
-      data: {
-        type: 'authors',
-        attributes: {
-          name: 'George Orwell'
-        }
-      }
-    }
-  });
-  console.log('Created author:');
-
-  const author2Result = await api.resources.authors.post({
-    inputRecord: {
-      data: {
-        type: 'authors',
-        attributes: {
-          name: 'Aldous Huxley'
-        }
-      }
-    }
-  });
-  console.log('Created another author:');
-
-  // Create a book with relationships
-  const bookResult = await api.resources.books.post({
-    simplified: false,
-    queryParams: { include: ['authors'] },       
-     inputRecord: {
-      data: {
-        type: 'books',
-        attributes: {
-          title: '1984'
-        },
-        relationships: {
-          country: {
-            data: { type: 'countries', id: countryResult1.id }
-          },
-          publisher: {
-            data: { type: 'publishers', id: publisherResult.id }
-          },
-          authors: {
-            data: [
-              { type: 'authors', id: author1Result.id },
-              { type: 'authors', id: author2Result.id }
-
-            ]
-          }
-        }
-      }
-    }
-  });
-  console.log('Created book:', util.inspect(bookResult, { depth: 5 }))
-
-  const pivotRecords = await knex('book_authors').where('book_id', bookResult.data.id);
-console.log('Pivot records:', pivotRecords);  
-                                               
-
-
-  // Clean up database connection
-  await knex.destroy();
-  console.log('\nExample completed successfully!');
-
-
-
-  /*
-
-  // Create a book with relationships
-  const bookResult = await api.resources.books.post({
-    inputRecord: {
-      data: {
-        type: 'books',
-        attributes: {
-          title: '1984'
-        },
-        relationships: {
-          country: {
-            data: { type: 'countries', id: ukResult.data.id }
-          },
-          publisher: {
-            data: { type: 'publishers', id: publisherResult.data.id }
-          },
-          authors: {
-            data: [
-              { type: 'authors', id: author1Result.data.id }
-            ]
-          }
-        }
-      }
-    }
-  });
-  console.log('Created book:', bookResult.data);
-
-  // Query books with included relationships
-  const booksWithRelationships = await api.resources.books.query({
-    include: 'authors,publisher,country'
-  });
-  console.log('\nBooks with relationships:');
-  console.log(JSON.stringify(booksWithRelationships, null, 2));
-
-  // Clean up
-  await knex.destroy();
-  console.log('\nExample completed successfully!');
-
-*/
-
-} catch (error) {
-  console.error('Error:', error.message, error.details);
-  console.error('Stack trace:', error.stack);
-  await knex.destroy();
-  process.exit(1);
-}
-
-

package/plugins/core/HELPER_MODULES.md

@@ -1,285 +0,0 @@
-
-# Diagram of helpers and their dependencies
-
-## Refactoring Pattern
-
-All helper functions have been refactored to use a consistent `(scope, deps)` signature:
-
-**Before:**
-```javascript
-function helperFunction(param1, param2, param3, param4, param5) {
-  // Many individual parameters
-}
-```
-
-**After:**
-```javascript
-function helperFunction(scope, deps) {
-  // Extract from scope (resource-specific data)
-  const { vars: { schemaInfo } } = scope;
-  
-  // Extract from deps (dependencies and context)
-  const { api, context, transaction } = deps;
-  const { scopeName, queryParams } = context;
-}
-```
-
-This pattern reduces parameters by 50-70% and provides clear separation between:
-- **scope**: Resource configuration and schema information
-- **deps**: Dependencies (api, knex) and request context
-
-## Pure Utility Functions (utils/ directory)
-
-### utils/field-utils.js
-```
-┌─────────────────────────────┐
-│   getForeignKeyFields()     │ - Extracts foreign key fields from schema
-│   (schema)                  │ - Identifies belongsTo relationships  
-│                             │ - Returns: Set(['author_id', ...])
-└─────────────────────────────┘
-
-┌─────────────────────────────┐
-│  filterAttributeFields()    │ - Filters out foreign keys & internals
-│  (attributes,               │ - Removes polymorphic fields
-│   foreignKeyFields,         │ - Returns: cleaned attributes object
-│   polymorphicFields)        │
-└─────────────────────────────┘
-```
-
-### utils/knex-query-helpers-base.js
-```
-┌─────────────────────────────┐
-│    parseIncludeTree()       │ - Parses include parameter string
-│    (includeParam)           │ - Converts "author,comments.user"
-│                             │ - Returns: nested object tree
-└─────────────────────────────┘
-```
-
-## Functions with (scope, deps) Pattern (lib/ directory)
-
-### lib/knex-json-api-helpers.js
-```
-┌─────────────────────────────┐
-│      toJsonApi()            │ - Converts DB record to JSON:API format
-│  (scope, record, deps)      │ - Filters out foreign keys
-│                             │ - Returns: {type, id, attributes}
-│  deps.context: {            │
-│    scopeName,               │
-│    schemaInfo,              │
-│    polymorphicFields        │
-│  }                          │
-└─────────────────────────────┘
-```
-
-### lib/knex-relationship-includes.js  
-```
-┌─────────────────────────────┐
-│  groupByPolymorphicType()   │ - Groups records by polymorphic type
-│  (records, typeField,       │ - Used for batch loading
-│   idField)                  │ - Returns: {type: [ids...]}
-└─────────────────────────────┘
-```
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                     buildIncludedResources()                    │
-│ (scope, records, deps)                                          │
-│                                                                 │
-│ Main entry point - orchestrates the include loading process     │
-│                                                                 │
-│ deps: {                                                         │
-│   includeParam, fields, included, processedPaths                │
-│ }                                                               │
-│                                                                 │
-│ 1. Parses includes ──────────────┐                              │
-│                                  ▼                              │
-│ 2. Calls processIncludes ─────► processIncludes()               │
-│                                                                 │
-│ 3. Returns: {included: [...], recordsWithRelationships: [...]}  │
-└─────────────────────────────────────────────────────────────────┘
-                                    │
-                                    ▼
-┌────────────────────────────────────────────────────────────────┐
-│                        processIncludes()                       │
-│ (scope, records, deps)                                         │
-│                                                                │
-│ Recursive function that examines schema and calls loaders      │
-│                                                                │
-│ deps: {                                                        │
-│   includeTree, included, processedPaths, currentPath, fields   │
-│ }                                                              │
-│                                                                │
-│ Dispatches to: ─────────────────┬───────────────┬──────────────┤
-└─────────────────────────────────┴───────────────┴──────────────┘
-                    │                     │                │
-                    ▼                     ▼                ▼
-┌───────────────────────────┐ ┌─────────────────────┐ ┌──────────────────────────┐
-│     loadBelongsTo()       │ │    loadHasMany()    │ │ loadPolymorphicBelongsTo │
-│ (scope, records, deps)    │ │ (scope, records,    │ │ (scope, records, deps)   │
-│                           │ │  deps)              │ │                          │
-│ deps: {                   │ │                     │ │ deps: {                  │
-│   fieldName, fieldDef,    │ │ deps: {             │ │   relName, relDef,       │
-│   includeName,            │ │   includeName,      │ │   subIncludes, included, │
-│   subIncludes, included,  │ │   relDef,           │ │   processedPaths,        │
-│   processedPaths,         │ │   subIncludes,      │ │   currentPath, fields    │
-│   currentPath, fields     │ │   included,         │ │ }                        │
-│ }                         │ │   processedPaths,   │ │                          │
-│                           │ │   currentPath,      │ │ Loads polymorphic        │
-│ Loads many-to-one         │ │   fields            │ │ e.g. comment→(article    │
-│ e.g. comment→article      │ │ }                   │ │      or video)           │
-│                           │ │                     │ │                          │
-│ ┌─────────────────┐       │ │ Loads one-to-many   │ │ ┌──────────────────┐     │
-│ │ Recursively     │       │ │ or many-to-many     │ │ │ Recursively      │     │
-│ │ calls           │◄──────┼─┤ e.g. article→       │ │ │ calls            │◄────┤
-│ │ processIncludes │       │ │      comments       │ │ │ processIncludes  │     │
-│ └─────────────────┘       │ │                     │ │ └──────────────────┘     │
-└───────────────────────────┘ │ ┌─────────────────┐ │ └──────────────────────────┘
-                              │ │ Recursively     │ │
-                              │ │ calls           │◄┤
-                              │ │ processIncludes │ │           Also dispatches to:
-                              │ └─────────────────┘ │                    │
-                              └─────────────────────┘                    ▼
-                                                      ┌──────────────────────────┐
-                                                      │ loadReversePolymorphic() │
-                                                      │ (scope, records, deps)   │
-                                                      │                          │
-                                                      │ deps: {                  │
-                                                      │   includeName, relDef,   │
-                                                      │   subIncludes, included, │
-                                                      │   processedPaths,        │
-                                                      │   currentPath, fields    │
-                                                      │ }                        │
-                                                      │                          │
-                                                      │ Loads via relationships  │
-                                                      │ e.g. article→comments    │
-                                                      │      (via commentable)   │
-                                                      │                          │
-                                                      │ ┌──────────────────┐     │
-                                                      │ │ Recursively      │     │
-                                                      │ │ calls            │◄────┤
-                                                      │ │ processIncludes  │     │
-                                                      │ └──────────────────┘     │
-                                                      └──────────────────────────┘
-```
-
-### lib/simplified-helpers.js
-```
-┌─────────────────────────────────────────────────────────────────┐
-│              transformSimplifiedToJsonApi()                     │
-│ (scope, deps)                                                   │
-│                                                                 │
-│ Converts plain objects to JSON:API format                       │
-│ - Handles both foreign key names and 'as' aliases               │
-│ - Converts relationships to proper JSON:API structure            │
-│                                                                 │
-│ scope: { inputRecord }                                          │
-│ deps.context: { scopeName, schemaStructure, schemaRelationships }│
-└─────────────────────────────────────────────────────────────────┘
-
-┌─────────────────────────────────────────────────────────────────┐
-│             transformJsonApiToSimplified()                      │
-│ (scope, deps)                                                   │
-│                                                                 │
-│ Converts JSON:API responses to plain objects                    │
-│ - Restores foreign keys from relationships                      │
-│ - Handles both single resources and collections                  │
-│                                                                 │
-│ scope: { record }                                               │
-│ deps.context: { schemaStructure, schemaRelationships }          │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-### lib/many-to-many-manipulations.js
-```
-┌─────────────────────────────────────────────────────────────────┐
-│           updateManyToManyRelationship()                        │
-│ (scope, deps)                                                   │
-│                                                                 │
-│ Intelligently syncs many-to-many relationships                  │
-│ - Preserves existing pivot data                                 │
-│ - Only creates/deletes changed relationships                    │
-│                                                                 │
-│ deps.context: {                                                 │
-│   resourceId, relDef, relData, transaction                      │
-│ }                                                               │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-### lib/relationship-processor.js
-```
-┌─────────────────────────────────────────────────────────────────┐
-│              processRelationships()                             │
-│ (scope, deps)                                                   │
-│                                                                 │
-│ Extracts relationship data from JSON:API payloads               │
-│ - Converts belongsTo to foreign keys                            │
-│ - Handles polymorphic relationships                             │
-│ - Prepares many-to-many operations                              │
-│                                                                 │
-│ deps.context: { inputRecord }                                   │
-│ Returns: { belongsToUpdates, manyToManyRelationships }          │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-## Module: lib/knex-process-includes.js
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                      processIncludes()                          │
-│ (records, scopeName, queryParams, transaction, dependencies)    │
-│                                                                 │
-│ High-level orchestrator that:                                   │
-│ 1. Extracts scopes, log, knex from dependencies                 │
-│ 2. Uses transaction if provided, otherwise uses knex            │
-│ 3. Calls buildIncludedResources with all parameters             │
-│ 4. Returns just the included array                              │
-│                                                                 │
-│ Called by: REST API plugin dataGet/dataQuery methods            │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-## Data Flow:
-```
-REST API Plugin
-    │
-    ├─► processIncludes (lib/knex-process-includes.js)
-    │       │
-    │       └─► buildIncludedResources (lib/knex-relationship-includes.js)
-    │               │
-    │               ├─► Uses pure utilities:
-    │               │   - parseIncludeTree (utils/knex-query-helpers-base.js)
-    │               │   - getForeignKeyFields (utils/field-utils.js)
-    │               │
-    │               └─► processIncludes (recursive orchestrator)
-    │                       │
-    │                       ├─► loadBelongsTo
-    │                       ├─► loadHasMany
-    │                       ├─► loadPolymorphicBelongsTo
-    │                       └─► loadReversePolymorphic
-    │                             │
-    │                             └─► All loaders use:
-    │                                 - toJsonApi (lib/knex-json-api-helpers.js)
-    │                                 - groupByPolymorphicType (lib/knex-relationship-includes.js)
-    │
-    └─► Returns: Array of included resources in JSON:API format
-```
-
-## File Organization:
-
-### Pure Utilities (utils/ directory)
-- `field-utils.js` - Schema field inspection utilities
-- `knex-query-helpers-base.js` - Query parsing utilities
-- `knex-constants.js` - Shared constants
-- `connectors-query-parser.js` - Connector query parsing
-
-### Scoped Functions (lib/ directory) 
-- `knex-json-api-helpers.js` - JSON:API transformation with (scope, deps)
-- `knex-relationship-includes.js` - Relationship loading with (scope, deps)
-- `knex-process-includes.js` - Top-level orchestrator
-- `knex-field-helpers.js` - Field selection and filtering with (scope, deps)
-- `knex-window-queries.js` - Window query builders
-- `simplified-helpers.js` - Simplified/JSON:API transformations with (scope, deps)
-- `many-to-many-manipulations.js` - Many-to-many relationship updates with (scope, deps)
-- `relationship-processor.js` - Relationship processing with (scope, deps)
-- `compile-schemas.js` - Schema compilation with (scope, deps)
-- `default-data-helpers.js` - Default data helper creation