@platformatic/sql-openapi 3.4.1 → 3.5.0

package/lib/shared.js

@@ -1,8 +1,7 @@
-'use strict'
+import { mapSQLTypeToOpenAPIType } from '@platformatic/sql-json-schema-mapper'
+import { buildCursorUtils } from './cursor.js'
 
-const { mapSQLTypeToOpenAPIType } = require('@platformatic/sql-json-schema-mapper')
-
-function generateArgs (entity, ignore) {
+export function generateArgs (entity, ignore) {
   const sortedEntityFields = Object.keys(entity.fields).sort()
 
   const whereArgs = sortedEntityFields.reduce((acc, name) => {
@@ -18,7 +17,7 @@ function generateArgs (entity, ignore) {
         acc[key] = { type: mapSQLTypeToOpenAPIType(field.sqlType) }
       }
     } else {
-      for (const modifier of ['eq', 'neq', 'gt', 'gte', 'lt', 'lte', 'like']) {
+      for (const modifier of ['eq', 'neq', 'gt', 'gte', 'lt', 'lte', 'like', 'ilike']) {
         const key = baseKey + modifier
         acc[key] = { type: mapSQLTypeToOpenAPIType(field.sqlType), enum: field.enum }
       }
@@ -49,9 +48,9 @@ function generateArgs (entity, ignore) {
     'where.or': {
       type: 'array',
       items: {
-        type: 'string',
-      },
-    },
+        type: 'string'
+      }
+    }
   }
 
   Object.assign(whereArgs, whereOrArrayArgs)
@@ -59,111 +58,161 @@ function generateArgs (entity, ignore) {
   return { whereArgs, orderByArgs }
 }
 
-module.exports.generateArgs = generateArgs
-
-function rootEntityRoutes (app, entity, whereArgs, orderByArgs, entityLinks, entitySchema, fields, entitySchemaInput, ignoreRoutes) {
+export function rootEntityRoutes (
+  app,
+  entity,
+  whereArgs,
+  orderByArgs,
+  entityLinks,
+  entitySchema,
+  fields,
+  entitySchemaInput,
+  ignoreRoutes
+) {
   const ignoredGETRoute = ignoreRoutes.find(ignoreRoutes => {
     return ignoreRoutes.path === app.prefix && ignoreRoutes.method === 'GET'
   })
 
   if (!ignoredGETRoute) {
-    app.get('/', {
-      schema: {
-        operationId: 'get' + capitalize(entity.pluralName),
-        summary: `Get ${entity.pluralName}.`,
-        description: `Fetch ${entity.pluralName} from the database.`,
-        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' },
-            totalCount: { type: 'boolean', default: false },
-            fields,
-            ...whereArgs,
-            ...orderByArgs,
-          },
-          additionalProperties: false,
-        },
-        response: {
-          200: {
-            type: 'array',
-            items: entitySchema,
+    const { buildCursorHeaders, transformQueryToCursor } = buildCursorUtils(app, entity)
+
+    app.get(
+      '/',
+      {
+        schema: {
+          operationId: 'get' + capitalize(entity.pluralName),
+          summary: `Get ${entity.pluralName}.`,
+          description: `Fetch ${entity.pluralName} from the database.`,
+          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' },
+              totalCount: { type: 'boolean', default: false },
+              cursor: {
+                type: 'boolean',
+                default: false,
+                description: 'Include cursor headers in response. Cursor keys built from orderBy clause'
+              },
+              startAfter: {
+                type: 'string',
+                description: 'Cursor for forward pagination. List objects after this cursor position',
+                format: 'byte'
+              },
+              endBefore: {
+                type: 'string',
+                description: 'Cursor for backward pagination. List objects before this cursor position',
+                format: 'byte'
+              },
+              fields,
+              ...whereArgs,
+              ...orderByArgs
+            },
+            additionalProperties: false
           },
-        },
+          response: {
+            200: {
+              type: 'array',
+              items: entitySchema
+            }
+          }
+        }
       },
-    }, async function (request, reply) {
-      const query = request.query
-      const { limit, offset, fields } = query
-      const queryKeys = Object.keys(query)
-      const where = {}
-      const orderBy = []
-
-      for (let i = 0; i < queryKeys.length; i++) {
-        const key = queryKeys[i]
-        if (key.startsWith('where.or')) {
-          const orParam = query[key][0]
-          // NOTE: Remove the first and last character which are the brackets
-          // each or condition is separated by a pipe '|'
-          // the conditions inside the or statement are the same as it would normally be in the where statement
-          // except that the field name is not prefixed with 'where.'
-          // e.g. where.or=(name.eq=foo|name.eq=bar)
-          // e.g. where.or=(name.eq=foo|name.eq=bar|name.eq=baz)
-          //
-          // Also, the or statement supports in and nin operators
-          // e.g. where.or=(name.in=foo,bar|name.eq=baz)
-          const parsed = orParam.substring(1, orParam.length - 1).split('|').map((v) => v.split('=')).reduce((acc, [k, v]) => {
-            const [field, modifier] = k.split('.')
+      async function (request, reply) {
+        const query = request.query
+        const { limit, offset, fields, startAfter, endBefore } = query
+        const queryKeys = Object.keys(query)
+        const where = {}
+        const orderBy = []
+
+        for (let i = 0; i < queryKeys.length; i++) {
+          const key = queryKeys[i]
+          if (key.startsWith('where.or')) {
+            const orParam = query[key][0]
+            // NOTE: Remove the first and last character which are the brackets
+            // each or condition is separated by a pipe '|'
+            // the conditions inside the or statement are the same as it would normally be in the where statement
+            // except that the field name is not prefixed with 'where.'
+            // e.g. where.or=(name.eq=foo|name.eq=bar)
+            // e.g. where.or=(name.eq=foo|name.eq=bar|name.eq=baz)
+            //
+            // Also, the or statement supports in and nin operators
+            // e.g. where.or=(name.in=foo,bar|name.eq=baz)
+            const parsed = orParam
+              .substring(1, orParam.length - 1)
+              .split('|')
+              .map(v => v.split('='))
+              .reduce((acc, [k, v]) => {
+                const [field, modifier] = k.split('.')
+                if (modifier === 'in' || modifier === 'nin') {
+                  // TODO handle escaping of ,
+                  v = v.split(',')
+                  /* istanbul ignore next */
+                  if (mapSQLTypeToOpenAPIType(entity.camelCasedFields[field].sqlType) === 'integer') {
+                    v = v.map(v => parseInt(v))
+                  }
+                }
+                acc.push({ [field]: { [modifier]: parseNullableValue(field, v) } })
+                return acc
+              }, [])
+            where.or = parsed
+            continue
+          }
+
+          if (key.startsWith('where.')) {
+            const [, field, modifier] = key.split('.')
+            where[field] ||= {}
+            let value = query[key]
             if (modifier === 'in' || modifier === 'nin') {
               // TODO handle escaping of ,
-              v = v.split(',')
-              /* istanbul ignore next */
+              value = query[key].split(',')
               if (mapSQLTypeToOpenAPIType(entity.camelCasedFields[field].sqlType) === 'integer') {
-                v = v.map((v) => parseInt(v))
+                value = value.map(v => parseInt(v))
               }
             }
-            acc.push({ [field]: { [modifier]: v } })
-            return acc
-          }, [])
-          where.or = parsed
-          continue
-        }
 
-        if (key.startsWith('where.')) {
-          const [, field, modifier] = key.split('.')
-          where[field] ||= {}
-          let value = query[key]
-          if (modifier === 'in' || modifier === 'nin') {
-            // TODO handle escaping of ,
-            value = query[key].split(',')
-            if (mapSQLTypeToOpenAPIType(entity.camelCasedFields[field].sqlType) === 'integer') {
-              value = value.map((v) => parseInt(v))
-            }
+            where[field][modifier] = parseNullableValue(field, value)
+          } else if (key.startsWith('orderby.')) {
+            const [, field] = key.split('.')
+            orderBy[field] ||= {}
+            orderBy.push({ field, direction: query[key] })
           }
-          where[field][modifier] = value
-        } else if (key.startsWith('orderby.')) {
-          const [, field] = key.split('.')
-          orderBy[field] ||= {}
-          orderBy.push({ field, direction: query[key] })
         }
-      }
 
-      const ctx = { app: this, reply }
-      const res = await entity.find({ limit, offset, fields, orderBy, where, ctx })
+        const ctx = { app: this, reply }
+        const { cursor, nextPage } = transformQueryToCursor({ startAfter, endBefore })
+        const res = await entity.find({ limit, offset, fields, orderBy, where, ctx, cursor, nextPage })
 
-      // X-Total-Count header
-      if (query.totalCount) {
-        let totalCount
-        if ((((offset ?? 0) === 0) || (res.length > 0)) && ((limit !== undefined) && (res.length < limit))) {
-          totalCount = (offset ?? 0) + res.length
-        } else {
-          totalCount = await entity.count({ where, ctx })
+        // X-Total-Count header
+        if (query.totalCount) {
+          let totalCount
+          if (((offset ?? 0) === 0 || res.length > 0) && limit !== undefined && res.length < limit) {
+            totalCount = (offset ?? 0) + res.length
+          } else {
+            totalCount = await entity.count({ where, ctx })
+          }
+          reply.header('X-Total-Count', totalCount)
         }
-        reply.header('X-Total-Count', totalCount)
-      }
 
-      return res
-    })
+        // cursor headers
+        if ((query.cursor || startAfter || endBefore) && res.length > 0) {
+          const { startAfter, endBefore } = buildCursorHeaders({
+            findResult: res,
+            orderBy,
+            primaryKeys: entity.primaryKeys
+          })
+          reply.header('X-Start-After', startAfter)
+          reply.header('X-End-Before', endBefore)
+        }
+
+        return res
+      }
+    )
   }
 
   const ignoredPOSTRoute = ignoreRoutes.find(ignoreRoute => {
@@ -171,26 +220,68 @@ function rootEntityRoutes (app, entity, whereArgs, orderByArgs, entityLinks, ent
   })
 
   if (!ignoredPOSTRoute) {
-    app.post('/', {
-      schema: {
-        operationId: 'create' + capitalize(entity.singularName),
-        summary: `Create ${entity.singularName}.`,
-        description: `Add new ${entity.singularName} to the database.`,
-        body: entitySchemaInput,
-        tags: [entity.table],
-        response: {
-          200: entitySchema,
+    app.post(
+      '/',
+      {
+        schema: {
+          operationId: 'create' + capitalize(entity.singularName),
+          summary: `Create ${entity.singularName}.`,
+          description: `Add new ${entity.singularName} to the database.`,
+          body: entitySchemaInput,
+          tags: [entity.table],
+          querystring: {
+            type: 'object',
+            properties: {
+              fields
+            },
+            additionalProperties: false
+          },
+          response: {
+            200: entitySchema
+          }
         },
+        links: {
+          200: entityLinks
+        }
       },
-      links: {
-        200: entityLinks,
-      },
-    }, async function (request, reply) {
-      const ctx = { app: this, reply }
-      const res = await entity.save({ input: request.body, ctx })
-      reply.header('location', `${app.prefix}/${res.id}`)
-      return res
-    })
+      async function (request, reply) {
+        const { fields } = request.query
+        const ctx = { app: this, reply }
+
+        let queryFields
+        if (fields) {
+          queryFields = [...fields]
+          for (const key of entity.primaryKeys.values()) {
+            if (!fields.includes(key)) {
+              queryFields.push(key)
+            }
+          }
+        }
+
+        const res = await entity.save({ input: request.body, ctx, fields: queryFields })
+
+        reply.header('location', `${app.prefix}/${res[[...entity.primaryKeys][0]]}`)
+
+        if (fields) {
+          for (const key of entity.primaryKeys.values()) {
+            if (!fields.includes(key)) {
+              delete res[key]
+            }
+          }
+        }
+
+        return res
+      }
+    )
+  }
+
+  const parseNullableValue = (field, value) => {
+    const fieldIsNullable = entity.camelCasedFields[field].isNullable
+    if (fieldIsNullable && typeof value === 'string' && value.toLowerCase() === 'null') {
+      return null
+    } else {
+      return value
+    }
   }
 
   const ignoredPUTRoute = ignoreRoutes.find(ignoreRoute => {
@@ -208,19 +299,19 @@ function rootEntityRoutes (app, entity, whereArgs, orderByArgs, entityLinks, ent
           type: 'object',
           properties: {
             fields,
-            ...whereArgs,
+            ...whereArgs
           },
-          additionalProperties: false,
+          additionalProperties: false
         },
         response: {
           200: {
             type: 'array',
-            items: entitySchema,
-          },
-        },
+            items: entitySchema
+          }
+        }
       },
       links: {
-        200: entityLinks,
+        200: entityLinks
       },
       async handler (request, reply) {
         const ctx = { app: this, reply }
@@ -238,49 +329,43 @@ function rootEntityRoutes (app, entity, whereArgs, orderByArgs, entityLinks, ent
               // TODO handle escaping of ,
               value = query[key].split(',')
               if (mapSQLTypeToOpenAPIType(entity.camelCasedFields[field].sqlType) === 'integer') {
-                value = value.map((v) => parseInt(v))
+                value = value.map(v => parseInt(v))
               }
             }
-            where[field][modifier] = value
+            where[field][modifier] = parseNullableValue(field, value)
           }
         }
 
         const res = await entity.updateMany({
           input: {
-            ...request.body,
+            ...request.body
           },
           where,
           fields: request.query.fields,
-          ctx,
+          ctx
         })
         // TODO: Should find a way to test this line
         // if (!res) return reply.callNotFound()
         reply.header('location', `${app.prefix}`)
         return res
-      },
+      }
     })
   }
 }
 
-module.exports.rootEntityRoutes = rootEntityRoutes
-
-function capitalize (str) {
+export function capitalize (str) {
   return str.charAt(0).toUpperCase() + str.slice(1)
 }
 
-module.exports.capitalize = capitalize
-
-function getFieldsForEntity (entity, ignore) {
+export function getFieldsForEntity (entity, ignore) {
   return {
     type: 'array',
     items: {
       type: 'string',
       enum: Object.keys(entity.fields)
-        .map((field) => entity.fields[field].camelcase)
-        .filter((field) => !ignore[field])
-        .sort(),
-    },
+        .map(field => entity.fields[field].camelcase)
+        .filter(field => !ignore[field])
+        .sort()
+    }
   }
 }
-
-module.exports.getFieldsForEntity = getFieldsForEntity

package/lib/utils.js

@@ -1,5 +1,3 @@
-'use strict'
-
 const openApiPathItemNonOperationKeys = ['summary', 'description', 'servers', 'parameters']
 
 function removeOperationPropertiesFromOpenApiPathItem (pathItem) {
@@ -13,7 +11,7 @@ function removeOperationPropertiesFromOpenApiPathItem (pathItem) {
   }, {})
 }
 
-function getSchemaOverrideFromOpenApiPathItem (pathItem, method) {
+export function getSchemaOverrideFromOpenApiPathItem (pathItem, method) {
   method = method?.toLowerCase()
 
   const schemaOverride = removeOperationPropertiesFromOpenApiPathItem(pathItem)
@@ -22,12 +20,8 @@ function getSchemaOverrideFromOpenApiPathItem (pathItem, method) {
     return schemaOverride
   }
 
-  Object.keys(pathItem[method]).forEach((key) => {
+  Object.keys(pathItem[method]).forEach(key => {
     schemaOverride[key] = pathItem[method][key]
   })
   return schemaOverride
 }
-
-module.exports = {
-  getSchemaOverrideFromOpenApiPathItem,
-}

package/package.json

@@ -1,14 +1,15 @@
 {
   "name": "@platformatic/sql-openapi",
-  "version": "3.4.1",
+  "version": "3.5.0",
   "description": "Map a SQL database to OpenAPI, for Fastify",
   "main": "index.js",
+  "type": "module",
   "types": "index.d.ts",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/platformatic/platformatic.git"
   },
-  "author": "Matteo Collina <hello@matteocollina.com>",
+  "author": "Platformatic Inc. <oss@platformatic.dev> (https://platformatic.dev)",
   "license": "Apache-2.0",
   "bugs": {
     "url": "https://github.com/platformatic/platformatic/issues"
@@ -16,41 +17,43 @@
   "homepage": "https://github.com/platformatic/platformatic#readme",
   "devDependencies": {
     "@matteo.collina/snap": "^0.3.0",
-    "@matteo.collina/tspl": "^0.1.1",
-    "borp": "^0.17.0",
+    "cleaner-spec-reporter": "^0.5.0",
     "eslint": "^9.4.0",
     "fastify": "^5.0.0",
-    "neostandard": "^0.11.1",
+    "neostandard": "^0.12.0",
     "openapi-types": "^12.1.3",
-    "tsd": "^0.31.0",
+    "tsd": "^0.33.0",
     "typescript": "^5.5.4",
     "why-is-node-running": "^2.2.2",
     "yaml": "^2.4.1",
-    "@platformatic/sql-mapper": "3.4.1"
+    "@platformatic/sql-mapper": "3.5.0"
   },
   "dependencies": {
-    "@fastify/deepmerge": "^1.3.0",
+    "@fastify/deepmerge": "^2.0.0",
     "@fastify/error": "^4.0.0",
     "@fastify/swagger": "^9.0.0",
-    "@scalar/fastify-api-reference": "^1.19.5",
+    "@scalar/fastify-api-reference": "1.34.6",
     "camelcase": "^6.3.0",
     "fastify-plugin": "^5.0.0",
     "inflected": "^2.1.0",
-    "@platformatic/scalar-theme": "3.4.1",
-    "@platformatic/sql-json-schema-mapper": "3.4.1",
-    "@platformatic/utils": "3.4.1"
+    "@platformatic/foundation": "3.5.0",
+    "@platformatic/scalar-theme": "3.5.0",
+    "@platformatic/sql-json-schema-mapper": "3.5.0"
   },
   "tsd": {
     "directory": "test/types"
   },
+  "engines": {
+    "node": ">=22.19.0"
+  },
   "scripts": {
     "lint": "eslint",
-    "test": "npm run lint && npm run test:typescript && npm run test:postgresql && npm run test:mariadb && npm run test:mysql && npm run test:mysql8 && npm run test:sqlite",
-    "test:postgresql": "DB=postgresql borp --timeout=180000 --concurrency=1 test/*.test.js",
-    "test:mariadb": "DB=mariadb borp --timeout=180000 --concurrency=1",
-    "test:mysql": "DB=mysql borp --timeout=180000 --concurrency=1",
-    "test:mysql8": "DB=mysql8 borp --timeout=180000 --concurrency=1",
-    "test:sqlite": "DB=sqlite borp --timeout=180000 --concurrency=1",
+    "test": "npm run test:typescript && npm run test:postgresql && npm run test:mariadb && npm run test:mysql && npm run test:mysql8 && npm run test:sqlite",
+    "test:postgresql": "DB=postgresql node --test --test-reporter=cleaner-spec-reporter --test-concurrency=1 --test-timeout=2000000 test/*.test.js test/**/*.test.js",
+    "test:mariadb": "DB=mariadb node --test --test-reporter=cleaner-spec-reporter --test-concurrency=1 --test-timeout=2000000 test/*.test.js test/**/*.test.js",
+    "test:mysql": "DB=mysql node --test --test-reporter=cleaner-spec-reporter --test-concurrency=1 --test-timeout=2000000 test/*.test.js test/**/*.test.js",
+    "test:mysql8": "DB=mysql8 node --test --test-reporter=cleaner-spec-reporter --test-concurrency=1 --test-timeout=2000000 test/*.test.js test/**/*.test.js",
+    "test:sqlite": "DB=sqlite node --test --test-reporter=cleaner-spec-reporter --test-concurrency=1 --test-timeout=2000000 test/*.test.js test/**/*.test.js",
     "test:typescript": "tsd"
   }
 }