json-rest-api 1.0.29 → 2.1.0

package/SINGLE_VALIDATION_CONTRACT_TODO.txt

@@ -1,172 +0,0 @@
-Single Validation Contract TODO
-
-Goal
-- Make `json-rest-schema` the single authored validation contract in `json-rest-api`.
-- Keep plain JSON Schema only as a derived transport artifact for connectors.
-- Remove the split between:
-  - resource/search validation via `json-rest-schema`
-  - hand-written JSON:API/query validators in `plugins/core/lib/querying-writing/payload-validators.js`
-
-Current audit status
-- [done] Audit the live validation paths and identify the actual indirection.
-
-Root cause
-- Validation is split across three places:
-  1. `plugins/core/lib/querying-writing/compile-schemas.js`
-     - compiles resource and search schemas with `createSchema(...)`
-  2. `plugins/core/lib/querying-writing/payload-validators.js`
-     - manually validates JSON:API request envelopes and query parameter objects
-  3. `plugins/core/connectors/lib/transport-route-schemas.js`
-     - separately builds connector-facing JSON Schemas from `schemaInfo`
-- This duplicates contract meaning across runtime and transport.
-- Route methods still call imperative payload validators before calling
-  `schemaInstance.create()`, `schemaInstance.replace()`, or `schemaInstance.patch()`.
-- `setupCommonRequest()` in `plugins/core/rest-api-plugin-methods/common.js`
-  also repeats some checks that are already transport-contract concerns.
-
-What the neat end state looks like
-- Authored contract:
-  - `json-rest-schema` only
-- Derived transport schema:
-  - plain JSON Schema, generated from the same compiled contract
-- Runtime write validation:
-  - uses the same compiled contract as Fastify pre-validation
-- Remaining imperative checks:
-  - only stateful/business checks that are not schema concerns
-  - examples: permission checks, record existence, relationship access, complete-replace semantics
-
-What should stay imperative
-- `validateRelationshipAccess()` in `plugins/core/rest-api-plugin-methods/common.js`
-- `validateCompleteReplacePayload()` in `plugins/core/rest-api-plugin-methods/common.js`
-- path/body cross-source checks such as URL id vs body id consistency
-- permission and data existence checks
-
-What should stop existing
-- `validateGetPayload()`
-- `validateQueryPayload()`
-- `validatePostPayload()`
-- `validatePutPayload()`
-- `validatePatchPayload()`
-- duplicate route/body/query syntax checks spread across route methods and `setupCommonRequest()`
-
-Work list
-
-1. [done] Define one compiled request-contract surface for resource `get/query/post/put/patch`.
-   Target files:
-   - `plugins/core/lib/querying-writing/compile-schemas.js`
-   - `plugins/core/connectors/lib/transport-route-schemas.js`
-   Deliverables:
-   - compile request contracts once per scope
-   - store them on `scope.vars.schemaInfo` or an adjacent compiled-contract object
-   - separate:
-     - write document contracts (`post`, `put`, `patch`)
-     - query/get contracts (`get`, `query`)
-     - relationship route contracts
-   Status:
-   - resource route contracts now compile once in `request-contracts.js`
-   - relationship route contracts are still separate and remain pending work
-
-2. [done] Replace manual write-document validation with compiled schema contracts.
-   Target files:
-   - `plugins/core/lib/querying-writing/payload-validators.js`
-   - `plugins/core/rest-api-plugin-methods/post.js`
-   - `plugins/core/rest-api-plugin-methods/put.js`
-   - `plugins/core/rest-api-plugin-methods/patch.js`
-   Deliverables:
-   - one compiled JSON:API document contract per write mode
-   - `data.type` constrained to the scope name inside the contract
-   - `data.id` required/optional according to mode
-   - `attributes` contract derived from `schemaInstance.toJsonSchema({ mode })`
-   - relationship identifier contracts derived from `schemaRelationships` and `belongsTo` metadata
-   - `included` rules expressed once in the contract rather than repeated manually
-
-3. [done] Replace manual GET/query parameter validation with compiled schema contracts.
-   Target files:
-   - `plugins/core/lib/querying-writing/payload-validators.js`
-   - `plugins/core/rest-api-plugin-methods/get.js`
-   - `plugins/core/rest-api-plugin-methods/query.js`
-   Deliverables:
-   - a compiled `get` contract for:
-     - `id`
-     - `queryParams.include`
-     - `queryParams.fields`
-   - a compiled `query` contract for:
-     - `include`
-     - `fields`
-     - `filters`
-     - `sort`
-     - `page`
-   - include-depth validation and sortable-field restrictions represented in the compiled contract, not duplicated in ad hoc code
-   Notes:
-   - `searchSchemaInstance` should remain the value contract for `filters`
-   - the query contract should validate the envelope/shape, not duplicate filter semantics
-
-4. [done] Collapse Fastify pre-validation and in-process validation onto the same source for resource write routes.
-   Target files:
-   - `plugins/core/connectors/lib/transport-route-schemas.js`
-   - `plugins/core/connectors/fastify-plugin.js`
-   - route methods in `plugins/core/rest-api-plugin-methods/`
-   Deliverables:
-   - Fastify consumes transport JSON Schema exported from the compiled request contract
-   - route methods consume the same compiled contract directly for runtime validation
-   - no second hand-written envelope contract path
-
-5. [done] Shrink `setupCommonRequest()` to non-schema responsibilities.
-   Target file:
-   - `plugins/core/rest-api-plugin-methods/common.js`
-   Deliverables:
-   - keep simplified-mode conversion, transaction setup, context wiring
-   - keep stateful/business checks only
-   - remove syntax/envelope checks that belong in the compiled contract
-   - keep only cross-input checks that a single schema cannot express cleanly
-
-6. [done] Delete `payload-validators.js`.
-   Target file:
-   - `plugins/core/lib/querying-writing/payload-validators.js`
-   Deliverables:
-   - no route method imports it anymore
-   - helper logic worth keeping is either:
-     - absorbed into compiled contracts
-     - or moved into narrowly named stateful helpers
-
-7. [done] Tighten tests around the single-contract flow.
-   Target areas:
-   - `tests/fastify-plugin.test.js`
-   - route method coverage exercised by the existing REST suites
-   - add one focused contract test suite if needed
-   Deliverables:
-   - prove Fastify pre-validation and runtime validation reject the same bad inputs
-   - cover:
-     - wrong `data.type`
-     - missing/invalid `data.id`
-     - invalid relationships
-     - invalid query/include/page/sort shapes
-   - verify there is no drift between transport schema and runtime schema behavior
-
-8. [done] Proof cleanup.
-   Deliverables:
-   - `rg` proof that route methods no longer import `payload-validators.js`
-   - `rg` proof that `validateGetPayload`, `validateQueryPayload`, `validatePostPayload`,
-     `validatePutPayload`, and `validatePatchPayload` are gone
-   - `npm test`
-
-Current state
-- Resource `get/query/post/put/patch` now use one compiled contract source.
-- Fastify transport schemas for those resource routes are derived from the same compiled contract.
-- `payload-validators.js` is deleted.
-- `npm test` passes.
-- The main remaining simplification is the separate relationship-route contract path.
-
-File map for the next implementation pass
-- Remaining relationship-route cleanup:
-  - `plugins/core/rest-api-plugin-methods/post-relationship.js`
-  - `plugins/core/rest-api-plugin-methods/patch-relationship.js`
-  - `plugins/core/rest-api-plugin-methods/delete-relationship.js`
-- Transport schema generator to reuse, not duplicate:
-  - `plugins/core/connectors/lib/transport-route-schemas.js`
-
-Explicit non-goals
-- Do not move permission checks into schemas.
-- Do not move DB existence checks into schemas.
-- Do not turn `searchSchema` into a generic filter DSL.
-- Do not add a compatibility layer that preserves both manual validators and compiled contracts.

package/TODO.todo

@@ -1,13 +0,0 @@
-  Potential Enhancements
-
-  1. Provider Priority: Consider adding a "primary_provider" field to handle users who authenticate through multiple providers.
-  2. Field Cleanup: Maybe add a helper to remove provider fields when a user unlinks that provider.
-  3. Migration Safety: The automatic column creation via RestApiKnexPlugin is convenient, but you might want provider plugins to check if their
-  fields already exist before extending.
-
-  
-☐ Delete "Creating Custom Storage Plugins for JSON REST API", make an op plugin instead.
-☐ Improve the look of the CSS, especially black and long code fragments, title fonts
-☐ Check manually that the API is OK 
-☐ Check that the guide has full coverage of features, map the missing parts
-

package/connectors_ideas/fastify.js

@@ -1,217 +0,0 @@
-/**
- * http-plugin-fastify.js
- * This plugin for Hooked API provides a high-performance HTTP layer using the Fastify framework.
- * It automatically generates JSON:API compliant RESTful routes and schemas for each scope.
- *
- * You'll need to install dependencies: npm install fastify
- */
-import { HookedApiError } from './hooked-api.js'
-import { handleFastifyApiError } from './error-handler-fastify.js'
-
-/**
- * **UPGRADED:** Automatically generates a comprehensive Fastify schema object that conforms
- * to the full JSON:API specification, including relationships, links, and meta.
- * @param {string} scopeName - The name of the resource type (e.g., 'articles').
- * @param {object} scopeOptions - The full options object for the scope.
- * @returns {object} A complete Fastify schema for all CRUD routes.
- */
-function _generateFastifySchema (scopeName, scopeOptions = {}) {
-  const appSchema = scopeOptions.schema || {}
-  const relationshipsSchema = scopeOptions.relationships || {}
-
-  // --- Reusable Schema Components ---
-  const metaObject = { type: 'object', additionalProperties: true }
-  const linksObject = {
-    type: 'object',
-    properties: {
-      self: { type: 'string', format: 'uri-reference' },
-      related: { type: 'string', format: 'uri-reference' },
-    }
-  }
-  const resourceIdentifierObject = {
-    type: 'object',
-    required: ['type', 'id'],
-    properties: {
-      type: { type: 'string' },
-      id: { type: 'string' }
-    }
-  }
-
-  // --- Build Attribute Properties from simple schema ---
-  const attributeProperties = {}
-  const requiredAttributes = []
-  for (const [key, value] of Object.entries(appSchema)) {
-    let jsonSchemaType = 'string'
-    if (value.type === 'number') jsonSchemaType = 'number'
-    if (value.type === 'boolean') jsonSchemaType = 'boolean'
-
-    attributeProperties[key] = { type: jsonSchemaType }
-    if (value.format) attributeProperties[key].format = value.format
-    if (value.required) requiredAttributes.push(key)
-  }
-
-  // --- Build Relationship Properties ---
-  const relationshipProperties = {}
-  for (const [key, value] of Object.entries(relationshipsSchema)) {
-    const isToMany = value.type === 'hasMany'
-    relationshipProperties[key] = {
-      type: 'object',
-      properties: {
-        links: linksObject,
-        data: isToMany
-          ? { type: 'array', items: resourceIdentifierObject }
-          : resourceIdentifierObject
-      }
-    }
-  }
-
-  // --- Define the core Resource Object schema ---
-  const resourceObject = {
-    type: 'object',
-    required: ['type', 'id'],
-    properties: {
-      id: { type: 'string' },
-      type: { type: 'string', const: scopeName },
-      attributes: {
-        type: 'object',
-        properties: attributeProperties
-      },
-      relationships: {
-        type: 'object',
-        properties: relationshipProperties
-      },
-      links: linksObject
-    }
-  }
-
-  // --- Define the full top-level JSON:API Document ---
-  const singleDocument = {
-    type: 'object',
-    properties: {
-      data: resourceObject,
-      included: { type: 'array', items: { type: 'object' } }, // Generic included for simplicity
-      links: linksObject,
-      meta: metaObject
-    }
-  }
-  const collectionDocument = {
-    type: 'object',
-    properties: {
-      data: { type: 'array', items: resourceObject },
-      included: { type: 'array', items: { type: 'object' } },
-      links: { ...linksObject, properties: { ...linksObject.properties, next: { type: 'string' }, prev: { type: 'string' } } },
-      meta: metaObject
-    }
-  }
-
-  // --- Build the final schema for each route ---
-  return {
-    post: {
-      body: {
-        type: 'object',
-        required: ['data'],
-        properties: {
-          data: {
-            type: 'object',
-            required: ['type', 'attributes'],
-            properties: {
-              type: { type: 'string', const: scopeName },
-              attributes: {
-                type: 'object',
-                required: requiredAttributes,
-                properties: attributeProperties
-              },
-              relationships: {
-                type: 'object',
-                properties: relationshipProperties
-              }
-            }
-          }
-        }
-      },
-      response: { 201: singleDocument }
-    },
-    get: {
-      response: { 200: singleDocument }
-    },
-    query: {
-      response: { 200: collectionDocument }
-    },
-    patch: {
-      body: { /* A more complex partial schema would be needed for full validation */ },
-      response: { 200: singleDocument }
-    },
-    put: {
-      body: { /* Similar to POST body */ },
-      response: { 200: singleDocument }
-    }
-  }
-}
-
-export const HttpFastifyPlugin = {
-  name: 'http-fastify',
-
-  install (context, api) {
-    const { pluginOptions, log } = context
-    const httpOptions = pluginOptions.http || {}
-    const { app, prefix = '/api' } = httpOptions
-
-    if (!app) {
-      throw new HookedApiError(
-        "The 'http-fastify' plugin requires a Fastify 'app' instance to be passed in the options. Example: api.use(HttpFastifyPlugin, { http: { app: myFastifyApp } })",
-        'CONFIGURATION_ERROR'
-      )
-    }
-
-    log.info(`Fastify HTTP plugin installed. Routes will be prefixed with '${prefix}'.`)
-
-    const _createFastifyHandler = (methodName) => {
-      return async (request, reply) => {
-        const { scopeName, id } = request.params
-        const apiParams = {
-          id,
-          inputRecord: request.body,
-          queryParams: request.query,
-        }
-        log.debug(`Fastify request for ${scopeName}.${methodName}`, { id, query: apiParams.queryParams })
-        const result = await api.scopes[scopeName][methodName](apiParams)
-        switch (methodName) {
-          case 'post':
-            reply.code(201).send(result)
-            break
-          case 'delete':
-            reply.code(204).send()
-            break
-          default:
-            reply.code(200).send(result)
-        }
-      }
-    }
-
-    const _createScopePlugin = (scopeName, scopeOptions) => {
-      const fastifySchema = scopeOptions.fastifySchema || _generateFastifySchema(scopeName, scopeOptions)
-
-      return async (fastifyInstance) => {
-        log.info(`Creating Fastify HTTP routes for scope: '${scopeName}'`)
-        fastifyInstance.get(`/${scopeName}`, { schema: fastifySchema.query }, _createFastifyHandler('query'))
-        fastifyInstance.get(`/${scopeName}/:id`, { schema: fastifySchema.get }, _createFastifyHandler('get'))
-        fastifyInstance.post(`/${scopeName}`, { schema: fastifySchema.post }, _createFastifyHandler('post'))
-        fastifyInstance.put(`/${scopeName}/:id`, { schema: fastifySchema.put }, _createFastifyHandler('put'))
-        fastifyInstance.patch(`/${scopeName}/:id`, { schema: fastifySchema.patch }, _createFastifyHandler('patch'))
-        fastifyInstance.delete(`/${scopeName}/:id`, { schema: fastifySchema.delete }, _createFastifyHandler('delete'))
-      }
-    }
-
-    const originalAddScope = api.addScope
-
-    api.addScope = (name, options, extras) => {
-      const result = originalAddScope.call(api, name, options, extras)
-      app.register(_createScopePlugin(name, options), { prefix })
-      return result
-    }
-
-    app.setErrorHandler((error, request, reply) => {
-      handleFastifyApiError(error, request, reply, log)
-    })
-  }
-}

package/connectors_ideas/koa-plugin.js

@@ -1,112 +0,0 @@
-/**
- * http-plugin-koa.js
- * This plugin for Hooked API provides a lightweight HTTP layer using the Koa.js framework.
- * It automatically generates JSON:API compliant RESTful routes for each scope using `koa-router`.
- *
- * It assumes you have `koa-bodyparser` installed and used before this plugin.
- * You'll need to install dependencies: npm install koa koa-router koa-bodyparser qs
- */
-import KoaRouter from 'koa-router'
-import qs from 'qs' // The same query string parser Express uses
-import { HookedApiError } from './hooked-api.js'
-import { handleKoaApiError } from './error-handler-koa.js'
-
-export const HttpKoaPlugin = {
-  name: 'http-koa',
-
-  install (context, api) {
-    const { pluginOptions, log } = context
-    const httpOptions = pluginOptions.http || {}
-    const { app, prefix = '/api' } = httpOptions
-
-    if (!app) {
-      throw new HookedApiError(
-        "The 'http-koa' plugin requires a Koa 'app' instance to be passed in the options. Example: api.use(HttpKoaPlugin, { http: { app: myKoaApp } })",
-        'CONFIGURATION_ERROR'
-      )
-    }
-
-    // Create a router instance for our API routes
-    const router = new KoaRouter({ prefix })
-
-    /**
-     * Creates a generic Koa middleware for a specific API method.
-     * @param {string} methodName - The name of the scope method to call (e.g., 'get', 'query').
-     * @returns {Function} An async Koa middleware function.
-     */
-    const _createKoaHandler = (methodName) => {
-      return async (ctx) => {
-        const { scopeName, id } = ctx.params
-
-        try {
-          // 1. Translate Koa ctx into API method params
-          const apiParams = {}
-
-          if (['get', 'put', 'patch', 'delete'].includes(methodName)) {
-            apiParams.id = id
-          }
-          if (['post', 'put', 'patch'].includes(methodName)) {
-            // Assumes koa-bodyparser is used
-            apiParams.inputRecord = ctx.request.body
-          }
-          // Use qs to properly parse nested query objects
-          apiParams.queryParams = ctx.querystring ? qs.parse(ctx.querystring) : {}
-
-          log.debug(`Koa request for ${scopeName}.${methodName}`, { id, query: apiParams.queryParams })
-
-          // 2. Execute the corresponding API method
-          const result = await api.scopes[scopeName][methodName](apiParams)
-
-          // 3. Set the successful Koa response
-          switch (methodName) {
-            case 'post':
-              ctx.status = 201
-              ctx.body = result
-              break
-            case 'delete':
-              ctx.status = 204
-              // No body for 204
-              break
-            default:
-              ctx.status = 200
-              ctx.body = result
-          }
-        } catch (error) {
-          // 4. Handle any errors thrown by the API
-          handleKoaApiError(error, ctx, log)
-        }
-      }
-    }
-
-    /**
-     * Creates all the standard RESTful routes for a given scope on the router.
-     * @param {string} scopeName - The name of the scope to create routes for.
-     */
-    const _createRoutesForScope = (scopeName) => {
-      const collectionPath = `/${scopeName}`
-      const resourcePath = `${collectionPath}/:id`
-
-      log.info(`Creating Koa HTTP routes for scope: '${scopeName}'`)
-
-      router.get(collectionPath, _createKoaHandler('query'))
-      router.get(resourcePath, _createKoaHandler('get'))
-      router.post(collectionPath, _createKoaHandler('post'))
-      router.put(resourcePath, _createKoaHandler('put'))
-      router.patch(resourcePath, _createKoaHandler('patch'))
-      router.del(resourcePath, _createKoaHandler('delete')) // .del is koa-router's alias for delete
-    }
-
-    // --- Main Logic: Wrap `addScope` to automate route creation ---
-    const originalAddScope = api.addScope
-
-    api.addScope = (name, options, extras) => {
-      const result = originalAddScope.call(api, name, options, extras)
-      _createRoutesForScope(name)
-      return result
-    }
-
-    // Apply the router middleware to the Koa app
-    app.use(router.routes()).use(router.allowedMethods())
-    log.info(`Koa router installed with prefix '${prefix}'.`)
-  }
-}

package/docs/.bundle/config

@@ -1,2 +0,0 @@
----
-BUNDLE_PATH: "vendor/bundle"