@platformatic/sql-openapi 3.4.1 → 3.5.0

package/lib/entity-to-routes.js

@@ -1,12 +1,13 @@
-'use strict'
-
-const { mapSQLTypeToOpenAPIType } = require('@platformatic/sql-json-schema-mapper')
-const { findNearestString } = require('@platformatic/utils')
-const camelcase = require('camelcase')
-const { generateArgs, rootEntityRoutes, capitalize, getFieldsForEntity } = require('./shared')
-const errors = require('./errors')
-
-const getEntityLinksForEntity = (app, entity) => {
+import { findNearestString } from '@platformatic/foundation'
+import { mapSQLTypeToOpenAPIType } from '@platformatic/sql-json-schema-mapper'
+import camelcase from 'camelcase'
+import {
+  UnableToCreateTheRouteForThePKColRelationshipError,
+  UnableToCreateTheRouteForTheReverseRelationshipError
+} from './errors.js'
+import { capitalize, generateArgs, getFieldsForEntity, rootEntityRoutes } from './shared.js'
+
+function getEntityLinksForEntity (app, entity) {
   const entityLinks = {}
   for (const relation of entity.relations) {
     const ownField = camelcase(relation.column_name)
@@ -17,8 +18,8 @@ const getEntityLinksForEntity = (app, entity) => {
     entityLinks[getEntityById] = {
       operationId: `get${relatedEntity.name}By${relatedEntityPrimaryKeyCamelcaseCapitalized}`,
       parameters: {
-        [relatedEntityPrimaryKeyCamelcase]: `$response.body#/${ownField}`,
-      },
+        [relatedEntityPrimaryKeyCamelcase]: `$response.body#/${ownField}`
+      }
     }
   }
 
@@ -34,35 +35,34 @@ const getEntityLinksForEntity = (app, entity) => {
     entityLinks[getEntities] = {
       operationId: `get${capitalize(relatedEntity.pluralName)}`,
       parameters: {
-        [`where.${theirField}.eq`]: `$response.body#/${ownField}`,
-      },
+        [`where.${theirField}.eq`]: `$response.body#/${ownField}`
+      }
     }
   }
   return entityLinks
 }
 
-async function entityPlugin (app, opts) {
+export async function entityPlugin (app, opts) {
   const entity = opts.entity
   const ignore = opts.ignore
   const ignoreRoutes = opts.ignoreRoutes
 
   const entitySchema = {
-    $ref: entity.name + '#',
+    $ref: entity.name + '#'
   }
 
   const entitySchemaInput = {
-    $ref: entity.name + 'Input#',
+    $ref: entity.name + 'Input#'
   }
 
-  const entityFieldsNames = Object.values(entity.fields)
-    .map(field => field.camelcase)
+  const entityFieldsNames = Object.values(entity.fields).map(field => field.camelcase)
 
   for (const ignoredField of Object.keys(ignore)) {
     if (!entityFieldsNames.includes(ignoredField)) {
       const nearestField = findNearestString(entityFieldsNames, ignoredField)
       app.log.warn(
         `Ignored openapi field "${ignoredField}" not found in entity "${entity.singularName}".` +
-        ` Did you mean "${nearestField}"?`
+          ` Did you mean "${nearestField}"?`
       )
     }
   }
@@ -74,7 +74,7 @@ async function entityPlugin (app, opts) {
 
   const { whereArgs, orderByArgs } = generateArgs(entity, ignore)
 
-  app.addHook('preValidation', async (req) => {
+  app.addHook('preValidation', async req => {
     if (typeof req.query.fields === 'string') {
       req.query.fields = req.query.fields.split(',')
     }
@@ -82,7 +82,17 @@ async function entityPlugin (app, opts) {
 
   const fields = getFieldsForEntity(entity, ignore)
 
-  rootEntityRoutes(app, entity, whereArgs, orderByArgs, entityLinks, entitySchema, fields, entitySchemaInput, ignoreRoutes)
+  rootEntityRoutes(
+    app,
+    entity,
+    whereArgs,
+    orderByArgs,
+    entityLinks,
+    entitySchema,
+    fields,
+    entitySchemaInput,
+    ignoreRoutes
+  )
 
   const openapiPath = `${app.prefix}/{${primaryKeyCamelcase}}`
   const ignoredGETRoute = ignoreRoutes.find(ignoreRoute => {
@@ -90,42 +100,46 @@ async function entityPlugin (app, opts) {
   })
 
   if (!ignoredGETRoute) {
-    app.get(`/:${primaryKeyCamelcase}`, {
-      schema: {
-        operationId: `get${entity.name}By${capitalize(primaryKeyCamelcase)}`,
-        summary: `Get ${entity.name} by ${primaryKeyCamelcase}.`,
-        description: `Fetch ${entity.name} using its ${primaryKeyCamelcase} from the database.`,
-        params: primaryKeyParams,
-        tags: [entity.table],
-        querystring: {
-          type: 'object',
-          properties: {
-            fields,
+    app.get(
+      `/:${primaryKeyCamelcase}`,
+      {
+        schema: {
+          operationId: `get${entity.name}By${capitalize(primaryKeyCamelcase)}`,
+          summary: `Get ${entity.name} by ${primaryKeyCamelcase}.`,
+          description: `Fetch ${entity.name} using its ${primaryKeyCamelcase} from the database.`,
+          params: primaryKeyParams,
+          tags: [entity.table],
+          querystring: {
+            type: 'object',
+            properties: {
+              fields
+            }
           },
+          response: {
+            200: entitySchema
+          }
         },
-        response: {
-          200: entitySchema,
-        },
-      },
-      links: {
-        200: entityLinks,
+        links: {
+          200: entityLinks
+        }
       },
-    }, async function (request, reply) {
-      const ctx = { app: this, reply }
-      const res = await entity.find({
-        ctx,
-        where: {
-          [primaryKeyCamelcase]: {
-            eq: request.params[primaryKeyCamelcase],
+      async function (request, reply) {
+        const ctx = { app: this, reply }
+        const res = await entity.find({
+          ctx,
+          where: {
+            [primaryKeyCamelcase]: {
+              eq: request.params[primaryKeyCamelcase]
+            }
           },
-        },
-        fields: request.query.fields,
-      })
-      if (res.length === 0) {
-        return reply.callNotFound()
+          fields: request.query.fields
+        })
+        if (res.length === 0) {
+          return reply.callNotFound()
+        }
+        return res[0]
       }
-      return res[0]
-    })
+    )
   }
 
   const mapRoutePathNamesReverseRelations = new Map()
@@ -136,15 +150,16 @@ async function entityPlugin (app, opts) {
     const targetEntity = app.platformatic.entities[targetEntityName]
     const targetForeignKeyCamelcase = camelcase(reverseRelationship.relation.column_name)
     const targetEntitySchema = {
-      $ref: targetEntity.name + '#',
+      $ref: targetEntity.name + '#'
     }
     const entityLinks = getEntityLinksForEntity(app, targetEntity)
     // e.g. getQuotesForMovie
     const operationId = `get${capitalize(targetEntity.pluralName)}For${capitalize(entity.singularName)}`
 
-    let routePathName = targetEntity.relations.length > 1
-      ? camelcase([reverseRelationship.sourceEntity, targetForeignKeyCamelcase])
-      : targetEntity.pluralName
+    let routePathName =
+      targetEntity.relations.length > 1
+        ? camelcase([reverseRelationship.sourceEntity, targetForeignKeyCamelcase])
+        : targetEntity.pluralName
 
     if (mapRoutePathNamesReverseRelations.get(routePathName)) {
       idxRoutePathNamesReverseRelations++
@@ -160,69 +175,96 @@ async function entityPlugin (app, opts) {
 
     if (!ignoredReversedGETRoute) {
       try {
-        app.get(`/:${camelcase(primaryKey)}/${routePathName}`, {
-          schema: {
-            operationId,
-            summary: `Get ${targetEntity.pluralName} for ${entity.singularName}.`,
-            description: `Fetch all the ${targetEntity.pluralName} for ${entity.singularName} from the database.`,
-            params: getPrimaryKeyParams(entity, ignore),
-            tags: [entity.table],
-            querystring: {
-              type: 'object',
-              properties: {
-                fields: getFieldsForEntity(targetEntity, ignore),
-              },
-            },
-            response: {
-              200: {
-                type: 'array',
-                items: targetEntitySchema,
+        app.get(
+          `/:${camelcase(primaryKey)}/${routePathName}`,
+          {
+            schema: {
+              operationId,
+              summary: `Get ${targetEntity.pluralName} for ${entity.singularName}.`,
+              description: `Fetch all the ${targetEntity.pluralName} for ${entity.singularName} from the database.`,
+              params: getPrimaryKeyParams(entity, ignore),
+              tags: [entity.table],
+              querystring: {
+                type: 'object',
+                properties: {
+                  limit: {
+                    type: 'integer',
+                    description:
+                      'Limit will be applied by default if not passed. If the provided value exceeds the maximum allowed value a validation error will be thrown'
+                  },
+                  offset: { type: 'integer' },
+                  fields: getFieldsForEntity(targetEntity, ignore),
+                  totalCount: { type: 'boolean', default: false }
+                }
               },
+              response: {
+                200: {
+                  type: 'array',
+                  items: targetEntitySchema
+                }
+              }
             },
+            links: {
+              200: entityLinks
+            }
           },
-          links: {
-            200: entityLinks,
-          },
-        }, async function (request, reply) {
-          const ctx = { app: this, reply }
-          // IF we want to have HTTP/404 in case the entity does not exist
-          // we need to do 2 queries. One to check if the entity exists. the other to get the related entities
-          // Improvement: this could be also done with a single query with a join,
-
-          // check that the entity exists
-          const resEntity = await entity.count({
-            ctx,
-            where: {
-              [primaryKeyCamelcase]: {
-                eq: request.params[primaryKeyCamelcase],
-              },
-            },
-          })
-          if (resEntity === 0) {
-            return reply.callNotFound()
-          }
-
-          // get the related entities
-          const res = await targetEntity.find({
-            ctx,
-            where: {
+          async function (request, reply) {
+            const { limit, offset, fields } = request.query
+            const ctx = { app: this, reply }
+            // IF we want to have HTTP/404 in case the entity does not exist
+            // we need to do 2 queries. One to check if the entity exists. the other to get the related entities
+            // Improvement: this could be also done with a single query with a join,
+
+            // check that the entity exists
+            const resEntity = await entity.count({
+              ctx,
+              where: {
+                [primaryKeyCamelcase]: {
+                  eq: request.params[primaryKeyCamelcase]
+                }
+              }
+            })
+            if (resEntity === 0) {
+              return reply.callNotFound()
+            }
+
+            const where = {
               [targetForeignKeyCamelcase]: {
-                eq: request.params[primaryKeyCamelcase],
-              },
-            },
-            fields: request.query.fields,
-
-          })
-          if (res.length === 0) {
-          // This is a query on a FK, so
-            return []
+                eq: request.params[primaryKeyCamelcase]
+              }
+            }
+
+            // get the related entities
+            const res = await targetEntity.find({
+              ctx,
+              where,
+              fields,
+              limit,
+              offset
+            })
+
+            // X-Total-Count header
+            if (request.query.totalCount) {
+              let totalCount
+              if (((offset ?? 0) === 0 || res.length > 0) && limit !== undefined && res.length < limit) {
+                totalCount = (offset ?? 0) + res.length
+              } else {
+                totalCount = await targetEntity.count({ where, ctx })
+              }
+              reply.header('X-Total-Count', totalCount)
+            }
+
+            if (res.length === 0) {
+              // This is a query on a FK, so
+              return []
+            }
+            return res
           }
-          return res
-        })
+        )
       } catch (error) /* istanbul ignore next */ {
         app.log.error(error)
         app.log.info({ routePathName, targetEntityName, targetEntitySchema, operationId })
-        throw new errors.UnableToCreateTheRouteForTheReverseRelationshipError()
+        throw new UnableToCreateTheRouteForTheReverseRelationshipError()
       }
     }
   }
@@ -246,7 +288,7 @@ async function entityPlugin (app, opts) {
     }
 
     const targetEntitySchema = {
-      $ref: targetEntity.name + '#',
+      $ref: targetEntity.name + '#'
     }
     const entityLinks = getEntityLinksForEntity(app, targetEntity)
     // e.g. getMovieForQuote
@@ -260,62 +302,68 @@ async function entityPlugin (app, opts) {
 
     if (!ignoredReversedGETRoute) {
       try {
-        app.get(`/:${camelcase(primaryKey)}/${targetRelation}`, {
-          schema: {
-            operationId,
-            summary: `Get ${targetEntity.singularName} for ${entity.singularName}.`,
-            description: `Fetch the ${targetEntity.singularName} for ${entity.singularName} from the database.`,
-            params: getPrimaryKeyParams(entity, ignore),
-            tags: [entity.table],
-            querystring: {
-              type: 'object',
-              properties: {
-                fields: getFieldsForEntity(targetEntity, ignore),
+        app.get(
+          `/:${camelcase(primaryKey)}/${targetRelation}`,
+          {
+            schema: {
+              operationId,
+              summary: `Get ${targetEntity.singularName} for ${entity.singularName}.`,
+              description: `Fetch the ${targetEntity.singularName} for ${entity.singularName} from the database.`,
+              params: getPrimaryKeyParams(entity, ignore),
+              tags: [entity.table],
+              querystring: {
+                type: 'object',
+                properties: {
+                  fields: getFieldsForEntity(targetEntity, ignore)
+                }
               },
+              response: {
+                200: targetEntitySchema
+              }
             },
-            response: {
-              200: targetEntitySchema,
-            },
-          },
-          links: {
-            200: entityLinks,
+            links: {
+              200: entityLinks
+            }
           },
-        }, async function (request, reply) {
-          const ctx = { app: this, reply }
-          // check that the entity exists
-          const resEntity = (await entity.find({
-            ctx,
-            where: {
-              [primaryKeyCamelcase]: {
-                eq: request.params[primaryKeyCamelcase],
+          async function (request, reply) {
+            const ctx = { app: this, reply }
+            // check that the entity exists
+            const resEntity = (
+              await entity.find({
+                ctx,
+                where: {
+                  [primaryKeyCamelcase]: {
+                    eq: request.params[primaryKeyCamelcase]
+                  }
+                }
+              })
+            )[0]
+
+            if (!resEntity) {
+              return reply.callNotFound()
+            }
+
+            // get the related entity
+            const res = await targetEntity.find({
+              ctx,
+              where: {
+                [targetForeignKeyCamelcase]: {
+                  eq: resEntity[targetColumnCamelcase]
+                }
               },
-            },
-          }))[0]
-
-          if (!resEntity) {
-            return reply.callNotFound()
-          }
-
-          // get the related entity
-          const res = await targetEntity.find({
-            ctx,
-            where: {
-              [targetForeignKeyCamelcase]: {
-                eq: resEntity[targetColumnCamelcase],
-              },
-            },
-            fields: request.query.fields,
-          })
+              fields: request.query.fields
+            })
 
-          if (res.length === 0) {
-            return reply.callNotFound()
+            if (res.length === 0) {
+              return reply.callNotFound()
+            }
+            return res[0]
           }
-          return res[0]
-        })
+        )
       } catch (error) /* istanbul ignore next */ {
         app.log.error(error)
         app.log.info({ primaryKey, targetRelation, targetEntitySchema, targetEntityName, targetEntity, operationId })
-        throw new errors.UnableToCreateTheRouteForThePKColRelationshipError()
+        throw new UnableToCreateTheRouteForThePKColRelationshipError()
       }
     }
   }
@@ -337,15 +385,15 @@ async function entityPlugin (app, opts) {
         querystring: {
           type: 'object',
           properties: {
-            fields,
-          },
+            fields
+          }
         },
         response: {
-          200: entitySchema,
-        },
+          200: entitySchema
+        }
       },
       links: {
-        200: entityLinks,
+        200: entityLinks
       },
       async handler (request, reply) {
         const id = request.params[primaryKeyCamelcase]
@@ -354,18 +402,18 @@ async function entityPlugin (app, opts) {
           ctx,
           input: {
             ...request.body,
-            [primaryKeyCamelcase]: id,
+            [primaryKeyCamelcase]: id
           },
           where: {
             [primaryKeyCamelcase]: {
-              eq: id,
-            },
+              eq: id
+            }
           },
-          fields: request.query.fields,
+          fields: request.query.fields
         })
         reply.header('location', `${app.prefix}/${res[primaryKeyCamelcase]}`)
         return res
-      },
+      }
     })
   }
 
@@ -373,39 +421,43 @@ async function entityPlugin (app, opts) {
     return ignoreRoute.path === openapiPath && ignoreRoute.method === 'DELETE'
   })
   if (!ignoredDELETERoute) {
-    app.delete(`/:${primaryKeyCamelcase}`, {
-      schema: {
-        operationId: 'delete' + capitalize(entity.pluralName),
-        summary: `Delete ${entity.pluralName}.`,
-        description: `Delete one or more ${entity.pluralName} from the Database.`,
-        params: primaryKeyParams,
-        tags: [entity.table],
-        querystring: {
-          type: 'object',
-          properties: {
-            fields,
+    app.delete(
+      `/:${primaryKeyCamelcase}`,
+      {
+        schema: {
+          operationId: 'delete' + capitalize(entity.pluralName),
+          summary: `Delete ${entity.pluralName}.`,
+          description: `Delete one or more ${entity.pluralName} from the Database.`,
+          params: primaryKeyParams,
+          tags: [entity.table],
+          querystring: {
+            type: 'object',
+            properties: {
+              fields
+            }
           },
-        },
-        response: {
-          200: entitySchema,
-        },
+          response: {
+            200: entitySchema
+          }
+        }
       },
-    }, async function (request, reply) {
-      const ctx = { app: this, reply }
-      const res = await entity.delete({
-        ctx,
-        where: {
-          [primaryKeyCamelcase]: {
-            eq: request.params[primaryKeyCamelcase],
+      async function (request, reply) {
+        const ctx = { app: this, reply }
+        const res = await entity.delete({
+          ctx,
+          where: {
+            [primaryKeyCamelcase]: {
+              eq: request.params[primaryKeyCamelcase]
+            }
           },
-        },
-        fields: request.query.fields,
-      })
-      if (res.length === 0) {
-        return reply.callNotFound()
+          fields: request.query.fields
+        })
+        if (res.length === 0) {
+          return reply.callNotFound()
+        }
+        return res[0]
       }
-      return res[0]
-    })
+    )
   }
 }
 
@@ -414,13 +466,11 @@ function getPrimaryKeyParams (entity, ignore) {
   const fields = entity.fields
   const field = fields[primaryKey]
   const properties = {
-    [field.camelcase]: { type: mapSQLTypeToOpenAPIType(field.sqlType, ignore) },
+    [field.camelcase]: { type: mapSQLTypeToOpenAPIType(field.sqlType, ignore) }
   }
 
   return {
     type: 'object',
-    properties,
+    properties
   }
 }
-
-module.exports = entityPlugin

package/lib/errors.js

@@ -1,10 +1,27 @@
-'use strict'
+import createError from '@fastify/error'
 
-const createError = require('@fastify/error')
+export const ERROR_PREFIX = 'PLT_SQL_OPENAPI'
 
-const ERROR_PREFIX = 'PLT_SQL_OPENAPI'
-
-module.exports = {
-  UnableToCreateTheRouteForTheReverseRelationshipError: createError(`${ERROR_PREFIX}_UNABLE_CREATE_ROUTE_FOR_REVERSE_RELATIONSHIP`, 'Unable to create the route for the reverse relationship'),
-  UnableToCreateTheRouteForThePKColRelationshipError: createError(`${ERROR_PREFIX}_UNABLE_CREATE_ROUTE_FOR_PK_COL_RELATIONSHIP`, 'Unable to create the route for the PK col relationship'),
-}
+export const UnableToCreateTheRouteForTheReverseRelationshipError = createError(
+  `${ERROR_PREFIX}_UNABLE_CREATE_ROUTE_FOR_REVERSE_RELATIONSHIP`,
+  'Unable to create the route for the reverse relationship'
+)
+export const UnableToCreateTheRouteForThePKColRelationshipError = createError(
+  `${ERROR_PREFIX}_UNABLE_CREATE_ROUTE_FOR_PK_COL_RELATIONSHIP`,
+  'Unable to create the route for the PK col relationship'
+)
+export const UnableToParseCursorStrError = createError(
+  `${ERROR_PREFIX}_UNABLE_TO_PARSE_CURSOR_STR`,
+  'Unable to parse cursor string. Make sure to provide valid encoding of cursor object. Error: %s',
+  400
+)
+export const CursorValidationError = createError(
+  `${ERROR_PREFIX}_CURSOR_VALIDATION_ERROR`,
+  'Cursor validation error. %s',
+  400
+)
+export const PrimaryKeyNotIncludedInOrderByInCursorPaginationError = createError(
+  `${ERROR_PREFIX}_PRIMARY_KEY_NOT_INCLUDED_IN_ORDER_BY_IN_CURSOR_PAGINATION`,
+  'At least one primary key must be included in orderBy clause in case of cursor pagination',
+  400
+)