json-rest-api 1.0.6 → 1.0.8

package/{RELATIONSHIPS_ADVANCED.md → docs/README_VARIOUS/RELATIONSHIPS_ADVANCED.md}

@@ -223,13 +223,13 @@ api.addResource('users', {
 ```javascript
 searchSchema: {
   // Simple field search
-  title: { type: 'string', filterUsing: 'like' },
+  title: { type: 'string', filterOperator: 'like' },
   
   // Cross-table search
   authorName: {
     type: 'string',
     actualField: 'users.name',  // Table.field notation
-    filterUsing: 'like'
+    filterOperator: 'like'
   },
   
   // Multi-field search
@@ -254,7 +254,7 @@ searchSchema: {
 searchSchema: {
   trackableTitle: {
     type: 'string',
-    filterUsing: 'like',
+    filterOperator: 'like',
     polymorphicField: 'trackable',  // References relationship name
     targetFields: {
       articles: 'title',      // When type=articles, search title

package/{correct-schema-format.md → docs/README_VARIOUS/correct-schema-format.md}

@@ -6,7 +6,7 @@ The format you're using with `indexed: true` is not recognized by the REST API p
 ```javascript
 // INCORRECT - This won't work for filtering
 {
-  title: { type: 'string', indexed: true, search: { filterUsing: 'like' } },
+  title: { type: 'string', indexed: true, search: { filterOperator: 'like' } },
   status: { type: 'string', indexed: true, search: true }
 }
 ```
@@ -43,13 +43,13 @@ For partial string matching:
   title: { 
     type: 'string',
     search: {
-      filterUsing: 'like'  // Enables LIKE filtering
+      filterOperator: 'like'  // Enables LIKE filtering
     }
   },
   body: {
     type: 'string',
     search: {
-      filterUsing: 'like'
+      filterOperator: 'like'
     }
   }
 }
@@ -67,10 +67,10 @@ For creating multiple filter parameters from a single field:
     type: 'datetime',
     search: {
       published_after: {
-        filterUsing: '>='
+        filterOperator: '>='
       },
       published_before: {
-        filterUsing: '<='
+        filterOperator: '<='
       }
     }
   }
@@ -119,7 +119,7 @@ api.addResource('products', {
   searchSchema: {
     name: {
       type: 'string',
-      filterUsing: 'like'
+      filterOperator: 'like'
     },
     category: {
       type: 'string'  // Exact match
@@ -127,12 +127,12 @@ api.addResource('products', {
     price_min: {
       type: 'number',
       actualField: 'price',
-      filterUsing: '>='
+      filterOperator: '>='
     },
     price_max: {
       type: 'number',
       actualField: 'price',
-      filterUsing: '<='
+      filterOperator: '<='
     }
   }
 });
@@ -151,7 +151,7 @@ const articlesSchema = {
     type: 'string', 
     required: true,
     search: {
-      filterUsing: 'like'  // Enables contains/LIKE search
+      filterOperator: 'like'  // Enables contains/LIKE search
     }
   },
   
@@ -173,10 +173,10 @@ const articlesSchema = {
     type: 'datetime',
     search: {
       created_after: {
-        filterUsing: '>='
+        filterOperator: '>='
       },
       created_before: {
-        filterUsing: '<='
+        filterOperator: '<='
       }
     }
   },
@@ -199,8 +199,8 @@ api.addResource('articles', {
 
 1. **Remove `indexed: true`** - This property is not used by the REST API plugin for filtering
 2. **Use `search: true`** for simple equality filters
-3. **Use `search: { filterUsing: 'like' }`** for contains/partial matching
-4. **Use `search: { field_name: { filterUsing: 'operator' } }`** for custom filter names
+3. **Use `search: { filterOperator: 'like' }`** for contains/partial matching
+4. **Use `search: { field_name: { filterOperator: 'operator' } }`** for custom filter names
 5. The filter validation happens in the `query` method of the REST API plugin
 6. If no `searchSchema` is provided, it's automatically generated from fields with the `search` property
 

package/{pagination.md → docs/README_VARIOUS/pagination.md}

@@ -165,31 +165,34 @@ const secondPage = await api.resources.books.query({
       "pageSize": 5,
       "hasMore": true,
       "cursor": {
-        "next": "eyJpZCI6MTB9"  // Base64 encoded cursor
+        "next": "id:10"  // Simple cursor format
       }
     }
   },
   "links": {
     "self": "https://api.example.com/v1/books?page[size]=5&sort=-id",
     "first": "https://api.example.com/v1/books?page[size]=5&sort=-id",
-    "next": "https://api.example.com/v1/books?page[size]=5&sort=-id&page[after]=eyJpZCI6MTB9"
+    "next": "https://api.example.com/v1/books?page[size]=5&sort=-id&page[after]=id:10"
   }
 }
 ```
 
 ### How Cursors Work
 
-Cursors are Base64-encoded JSON objects containing the sort field values of the last record:
+Cursors use a simple format containing the sort field values of the last record:
 
 ```javascript
-// Cursor for record with id=10
-const cursor = "eyJpZCI6MTB9";
+// Single field cursor (id=10)
+const cursor = "id:10";
 
-// Decoded:
-// {"id": 10}
+// Multi-field cursor (category='Fruit', name='Cherry')
+const cursor = "category:Fruit,name:Cherry";
+
+// With special characters (URL-encoded values)
+const cursor = "title:Chapter%202%3A%20The%20Journey";
 ```
 
-This allows efficient pagination by using WHERE clauses instead of OFFSET.
+This allows efficient pagination by using WHERE clauses instead of OFFSET. Values are URL-encoded to safely handle special characters like colons and commas.
 
 ## Pagination Metadata
 

package/docs/assets/css/style.scss

@@ -180,13 +180,86 @@ pre code {
   line-height: 1.5;
 }
 
-.language-javascript .k { color: #569cd6; }
-.language-javascript .s { color: #ce9178; }
-.language-javascript .c { color: #6a9955; }
-.language-javascript .n { color: #9cdcfe; }
-.language-javascript .o { color: #d4d4d4; }
+/* Rouge syntax highlighting - VS Code Dark+ theme */
+.highlight .hll { background-color: #515151 }
+.highlight  { color: #d4d4d4; }
+.highlight .c { color: #6a9955 } /* Comment */
+.highlight .err { color: #f44747 } /* Error */
+.highlight .k { color: #569cd6 } /* Keyword */
+.highlight .l { color: #b5cea8 } /* Literal */
+.highlight .n { color: #d4d4d4 } /* Name */
+.highlight .o { color: #d4d4d4 } /* Operator */
+.highlight .p { color: #d4d4d4 } /* Punctuation */
+.highlight .cm { color: #6a9955 } /* Comment.Multiline */
+.highlight .cp { color: #6a9955 } /* Comment.Preproc */
+.highlight .c1 { color: #6a9955 } /* Comment.Single */
+.highlight .cs { color: #6a9955 } /* Comment.Special */
+.highlight .gd { color: #f44747 } /* Generic.Deleted */
+.highlight .ge { font-style: italic } /* Generic.Emph */
+.highlight .gh { color: #d4d4d4; font-weight: bold } /* Generic.Heading */
+.highlight .gi { color: #4ec9b0 } /* Generic.Inserted */
+.highlight .gp { color: #6a9955; font-weight: bold } /* Generic.Prompt */
+.highlight .gs { font-weight: bold } /* Generic.Strong */
+.highlight .gu { color: #d4d4d4; font-weight: bold } /* Generic.Subheading */
+.highlight .kc { color: #569cd6 } /* Keyword.Constant */
+.highlight .kd { color: #569cd6 } /* Keyword.Declaration */
+.highlight .kn { color: #c586c0 } /* Keyword.Namespace */
+.highlight .kp { color: #569cd6 } /* Keyword.Pseudo */
+.highlight .kr { color: #569cd6 } /* Keyword.Reserved */
+.highlight .kt { color: #4ec9b0 } /* Keyword.Type */
+.highlight .ld { color: #ce9178 } /* Literal.Date */
+.highlight .m { color: #b5cea8 } /* Literal.Number */
+.highlight .s { color: #ce9178 } /* Literal.String */
+.highlight .na { color: #9cdcfe } /* Name.Attribute */
+.highlight .nb { color: #9cdcfe } /* Name.Builtin */
+.highlight .nc { color: #4ec9b0 } /* Name.Class */
+.highlight .no { color: #569cd6 } /* Name.Constant */
+.highlight .nd { color: #c586c0 } /* Name.Decorator */
+.highlight .ni { color: #d4d4d4 } /* Name.Entity */
+.highlight .ne { color: #4ec9b0 } /* Name.Exception */
+.highlight .nf { color: #dcdcaa } /* Name.Function */
+.highlight .nl { color: #d4d4d4 } /* Name.Label */
+.highlight .nn { color: #d4d4d4 } /* Name.Namespace */
+.highlight .nx { color: #9cdcfe } /* Name.Other */
+.highlight .py { color: #d4d4d4 } /* Name.Property */
+.highlight .nt { color: #569cd6 } /* Name.Tag */
+.highlight .nv { color: #9cdcfe } /* Name.Variable */
+.highlight .ow { color: #c586c0 } /* Operator.Word */
+.highlight .w { color: #d4d4d4 } /* Text.Whitespace */
+.highlight .mf { color: #b5cea8 } /* Literal.Number.Float */
+.highlight .mh { color: #b5cea8 } /* Literal.Number.Hex */
+.highlight .mi { color: #b5cea8 } /* Literal.Number.Integer */
+.highlight .mo { color: #b5cea8 } /* Literal.Number.Oct */
+.highlight .sb { color: #ce9178 } /* Literal.String.Backtick */
+.highlight .sc { color: #ce9178 } /* Literal.String.Char */
+.highlight .sd { color: #6a9955 } /* Literal.String.Doc */
+.highlight .s2 { color: #ce9178 } /* Literal.String.Double */
+.highlight .se { color: #d7ba7d } /* Literal.String.Escape */
+.highlight .sh { color: #ce9178 } /* Literal.String.Heredoc */
+.highlight .si { color: #ce9178 } /* Literal.String.Interpol */
+.highlight .sx { color: #ce9178 } /* Literal.String.Other */
+.highlight .sr { color: #d16969 } /* Literal.String.Regex */
+.highlight .s1 { color: #ce9178 } /* Literal.String.Single */
+.highlight .ss { color: #ce9178 } /* Literal.String.Symbol */
+.highlight .bp { color: #9cdcfe } /* Name.Builtin.Pseudo */
+.highlight .vc { color: #9cdcfe } /* Name.Variable.Class */
+.highlight .vg { color: #9cdcfe } /* Name.Variable.Global */
+.highlight .vi { color: #9cdcfe } /* Name.Variable.Instance */
+.highlight .il { color: #b5cea8 } /* Literal.Number.Integer.Long */
+
+/* Language-specific adjustments */
+.language-javascript .nx { color: #9cdcfe }
+.language-javascript .s1,
+.language-javascript .s2 { color: #ce9178 }
+.language-javascript .kd { color: #569cd6 }
+.language-javascript .k { color: #c586c0 }
+.language-javascript .o { color: #d4d4d4 }
+.language-javascript .p { color: #d4d4d4 }
+.language-javascript .c1 { color: #6a9955 }
 
 .language-bash { color: #4ec9b0; }
+.language-bash .nv { color: #9cdcfe; }
+.language-bash .s2 { color: #ce9178; }
 
 ul, ol {
   margin-bottom: 16px;

package/docs/index.md

@@ -50,6 +50,7 @@ JSON REST API is a lightweight, plugin-based framework that makes building REST
     <p>Follow industry standards with native JSON:API support. Compatible with any JSON:API client library.</p>
   </div>
   
+  <!--
   <div class="feature-card">
     <h3>🌐 Microservices Ready</h3>
     <p>Build distributed systems with native microservices support. Multiple transports, service discovery, and more.</p>
@@ -64,6 +65,7 @@ JSON REST API is a lightweight, plugin-based framework that makes building REST
     <h3>🔄 API Gateway</h3>
     <p>Transform into an API gateway to orchestrate external services with circuit breakers and saga support.</p>
   </div>
+  -->
 </div>
 
 ## Quick Example
@@ -137,15 +139,3 @@ npm install json-rest-api
 - [API Reference]({{ '/API' | relative_url }}) - Detailed API documentation
 - [Tutorial]({{ '/ONBOARDING' | relative_url }}) - Step-by-step walkthrough
 - [GitHub](https://github.com/mobily-enterprises/json-rest-api) - Source code and issues
-
-### Advanced Topics
-
-- [API Gateway]({{ '/GUIDE_8_API_Gateway' | relative_url }}) - Orchestrate external services
-- [CLI Interface]({{ '/GUIDE_9_CLI_Interface' | relative_url }}) - Command-line interface for your API
-
-### Enterprise Features
-
-- [Enterprise Guide]({{ '/enterprise/ENTERPRISE_GUIDE' | relative_url }}) - Complete guide for enterprise teams
-- [Microservices Architecture]({{ '/enterprise/GUIDE_8_Microservices' | relative_url }}) - Build distributed systems
-- [CQRS Pattern]({{ '/enterprise/GUIDE_9_CQRS' | relative_url }}) - Command Query Responsibility Segregation
-- [Domain-Driven Design]({{ '/enterprise/GUIDE_11_Domain_Driven_Design' | relative_url }}) - DDD patterns and implementation

package/helper-reorganization-plan.md

@@ -0,0 +1,85 @@
+# Helper Reorganization Plan
+
+## Files to Split and Move
+
+### 1. payload-validators.js
+This file contains method-specific validators that should be split:
+
+**Move to `querying/payload-validators-querying.js`:**
+- `validateGetPayload` (used only by GET)
+- `validateQueryPayload` (used only by QUERY)
+- `validateIncludeDepth` (helper used by GET/QUERY validators)
+
+**Move to `writing/payload-validators-writing.js`:**
+- `validatePostPayload` (used only by POST)
+- `validatePutPayload` (used only by PUT)
+- `validatePatchPayload` (used only by PATCH)
+- `validateResourceIdentifier` (helper used by writing validators)
+- `validateRelationship` (helper used by writing validators)
+
+### 2. knex-field-helpers.js
+This file has mixed functions:
+
+**Move to `querying/knex-field-helpers-querying.js`:**
+- `buildFieldSelection` (used only by GET/QUERY for sparse fieldsets)
+- `getRequestedComputedFields` (used only by GET/QUERY)
+
+**Keep in `querying-writing/knex-field-helpers.js`:**
+- `isNonDatabaseField` (used by both reading and writing)
+- `getForeignKeyFields` (re-exported, used by both)
+- `filterHiddenFields` (re-exported, used by both)
+
+### 3. knex-json-api-transformers.js
+This file has functions with different usage:
+
+**Move to `querying/knex-json-api-transformers-querying.js`:**
+- `toJsonApiRecord` (used only by QUERY)
+- `buildJsonApiResponse` (used only by GET/QUERY)
+
+**Move to `writing/knex-json-api-transformers-writing.js`:**
+- `processBelongsToRelationships` (used only by PUT/PATCH)
+
+**Keep in `querying-writing/knex-json-api-transformers.js`:**
+- `toJsonApiRecordWithBelongsTo` (used by GET minimal and DELETE)
+
+### 4. simplified-helpers.js
+Based on the analysis, this file likely contains:
+- `transformSimplifiedToJsonApi` - used by writing methods
+- `transformJsonApiToSimplified` - used by all methods (should stay shared)
+- `transformSingleJsonApiToSimplified` - used by all methods (should stay shared)
+
+Need to verify the actual usage of each function.
+
+## Summary of New Structure
+
+### `querying/` (10 files total)
+- knex-cross-table-search.js ✓
+- knex-pagination-helpers.js ✓
+- knex-process-includes.js ✓
+- knex-query-helpers.js ✓
+- knex-relationship-includes.js ✓
+- knex-window-queries.js ✓
+- **payload-validators-querying.js** (NEW - split from payload-validators.js)
+- **knex-field-helpers-querying.js** (NEW - split from knex-field-helpers.js)
+- **knex-json-api-transformers-querying.js** (NEW - split from knex-json-api-transformers.js)
+
+### `writing/` (5 files total)
+- many-to-many-manipulations.js ✓
+- relationship-processor.js ✓
+- **payload-validators-writing.js** (NEW - split from payload-validators.js)
+- **knex-json-api-transformers-writing.js** (NEW - split from knex-json-api-transformers.js)
+- **simplified-helpers-writing.js** (NEW - if transformSimplifiedToJsonApi is only used by writing)
+
+### `querying-writing/` (remaining shared files)
+- compile-schemas.js ✓
+- database-capabilities.js ✓
+- database-value-normalizers.js ✓
+- default-data-helpers.js ✓
+- knex-field-helpers.js (reduced - only shared functions)
+- knex-json-api-helpers.js ✓
+- knex-json-api-transformers.js (reduced - only shared functions)
+- schema-helpers.js ✓
+- scope-validations.js ✓
+- simplified-helpers.js (possibly reduced if some functions move to writing)
+
+This reorganization will create a much more balanced structure with clearer separation of concerns.

package/helper-usage-analysis.md

@@ -0,0 +1,94 @@
+# REST API Helper Usage Analysis
+
+This document analyzes which helpers from `plugins/core/lib/` are used by each REST API method (get, query, post, put, patch, delete).
+
+## Helper Categorization
+
+### 1. Helpers Used ONLY by Querying Methods (GET, QUERY)
+
+#### From rest-api-plugin.js:
+- **parseJsonApiQuery** - Parses JSON:API query strings into query parameters
+- **getRequestedComputedFields** - Determines which computed fields are requested based on sparse fieldsets
+
+#### From rest-api-knex-plugin.js:
+- **buildFieldSelection** - Builds field selection for sparse fieldsets and tracks computed field dependencies
+- **buildQuerySelection** - Applies field selection to Knex query
+- **loadRelationshipIdentifiers** - Loads hasMany relationship identifiers for included resources
+- **processIncludes** - Processes relationship includes based on query parameters
+- **toJsonApiRecord** - Transforms database records to JSON:API format
+- **buildJsonApiResponse** - Builds complete JSON:API response with data and included resources
+- **polymorphicFiltersHook** - Handles filtering for polymorphic relationships
+- **crossTableFiltersHook** - Handles cross-table filtering with JOINs
+- **basicFiltersHook** - Handles basic table filtering
+- **calculatePaginationMeta** - Calculates pagination metadata
+- **generatePaginationLinks** - Generates pagination links for offset-based pagination
+- **generateCursorPaginationLinks** - Generates pagination links for cursor-based pagination
+- **buildCursorMeta** - Builds cursor pagination metadata
+- **parseCursor** - Parses cursor strings for cursor pagination
+
+### 2. Helpers Used ONLY by Writing Methods (POST, PUT, PATCH, DELETE)
+
+#### From rest-api-plugin.js:
+- **validatePostPayload** - Validates POST request payload
+- **validatePutPayload** - Validates PUT request payload  
+- **validatePatchPayload** - Validates PATCH request payload
+- **processRelationships** - Extracts foreign keys from JSON:API relationships
+- **updateManyToManyRelationship** - Updates many-to-many relationships intelligently
+- **createPivotRecords** - Creates pivot table records for many-to-many relationships
+- **transformSimplifiedToJsonApi** - Transforms simplified API format to JSON:API
+
+#### From rest-api-knex-plugin.js:
+- **processBelongsToRelationships** - Processes belongsTo relationships to extract foreign keys
+- **stripNonDatabaseFields** - Removes computed and virtual fields before database operations
+
+### 3. Helpers Used by BOTH Querying and Writing Methods
+
+#### From rest-api-plugin.js:
+- **validateQueryPayload** - Used by QUERY method
+- **validateGetPayload** - Used by GET method
+- **compileSchemas** - Used during scope initialization (affects all methods)
+- **normalizeRecordAttributes** - Normalizes database values (used by GET and QUERY)
+- **transformJsonApiToSimplified** - Transforms JSON:API to simplified format (used by all methods when simplified mode is enabled)
+- **filterHiddenFields** - Filters hidden fields from responses (used by all methods)
+- **createDefaultDataHelpers** - Creates default helper implementations
+
+#### From rest-api-knex-plugin.js:
+- **toJsonApiRecordWithBelongsTo** - Used by GET (minimal record) and data fetching operations
+- **getForeignKeyFields** - While imported, not directly used in the analyzed code
+- **isNonDatabaseField** - While imported, not directly used in the analyzed code
+
+## Summary by Method
+
+### GET Method
+**Uses:** validateGetPayload, getRequestedComputedFields, normalizeRecordAttributes, filterHiddenFields, transformJsonApiToSimplified, buildFieldSelection, buildQuerySelection, loadRelationshipIdentifiers, processIncludes, buildJsonApiResponse, toJsonApiRecordWithBelongsTo
+
+### QUERY Method  
+**Uses:** validateQueryPayload, getRequestedComputedFields, normalizeRecordAttributes, filterHiddenFields, transformJsonApiToSimplified, parseJsonApiQuery, buildFieldSelection, buildQuerySelection, polymorphicFiltersHook, crossTableFiltersHook, basicFiltersHook, calculatePaginationMeta, generatePaginationLinks, generateCursorPaginationLinks, buildCursorMeta, parseCursor, loadRelationshipIdentifiers, processIncludes, buildJsonApiResponse
+
+### POST Method
+**Uses:** validatePostPayload, processRelationships, createPivotRecords, transformSimplifiedToJsonApi, filterHiddenFields, transformJsonApiToSimplified, stripNonDatabaseFields
+
+### PUT Method
+**Uses:** validatePutPayload, processRelationships, updateManyToManyRelationship, createPivotRecords, transformSimplifiedToJsonApi, filterHiddenFields, transformJsonApiToSimplified, processBelongsToRelationships, stripNonDatabaseFields
+
+### PATCH Method
+**Uses:** validatePatchPayload, processRelationships, updateManyToManyRelationship, transformSimplifiedToJsonApi, filterHiddenFields, transformJsonApiToSimplified, processBelongsToRelationships, stripNonDatabaseFields
+
+### DELETE Method
+**Uses:** toJsonApiRecordWithBelongsTo (for minimal record fetching)
+
+## Key Observations
+
+1. **Clear Separation**: There's a clear separation between read and write helpers, with minimal overlap.
+
+2. **Query Complexity**: Query methods use the most helpers due to filtering, pagination, includes, and sparse fieldsets.
+
+3. **Relationship Handling**: Write methods focus heavily on relationship processing and validation.
+
+4. **Format Transformation**: Both read and write methods use format transformation helpers for simplified API mode.
+
+5. **DELETE Simplicity**: DELETE method uses the fewest helpers, only needing minimal record fetching.
+
+6. **Validation Pattern**: Each write method has its own specific payload validator.
+
+7. **Database Abstraction**: The knex plugin handles all direct database operations, while the REST API plugin handles validation and transformation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "json-rest-api",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "main": "index.js",
   "type": "module",
   "scripts": {
@@ -22,8 +22,9 @@
   "homepage": "https://github.com/mobily-enterprises/jsonrestapi#readme",
   "description": "REST API plugin for hooked-api with JSON:API compliance",
   "dependencies": {
-    "hooked-api": "^1.0.8",
-    "json-rest-schema": "^1.0.6"
+    "hooked-api": "^1.0.14",
+    "json-rest-schema": "^1.0.8",
+    "semver": "^7.7.2"
   },
   "peerDependencies": {
     "@socket.io/redis-adapter": "^8.3.0",
@@ -79,7 +80,7 @@
   },
   "devDependencies": {
     "@socket.io/redis-adapter": "^8.3.0",
-    "better-sqlite3": "^11.0.0",
+    "better-sqlite3": "^11.10.0",
     "express": "^5.1.0",
     "fractional-indexing": "^3.2.0",
     "jsonwebtoken": "^9.0.2",

package/plugins/core/bulk-operations-plugin.js

@@ -348,8 +348,8 @@ export const BulkOperationsPlugin = {
 
     // Hook into scope creation to add bulk routes
     addHook('afterAddScope', 'bulkOperationsRoutes', {}, async ({ scopeName }) => {
-      const resourceUrlPrefix = api.vars.resourceUrlPrefix || '/api';
-      const scopePath = `${resourceUrlPrefix}/${scopeName}`;
+      const urlPrefix = api.vars.transport?.mountPath || '';
+      const scopePath = `${urlPrefix}/${scopeName}`;
 
       // Create route handlers
       const createBulkRouteHandler = (method) => {