@platformatic/sql-openapi 3.4.1 → 3.5.1

package/README.md

@@ -1,6 +1,6 @@
 # @platformatic/sql-openapi
 
-Check out the full documentation on [our website](https://docs.platformatic.dev/docs/packages/sql-openapi/overview).
+Check out the full documentation on [our website](https://docs.platformatic.dev/docs/reference/sql-openapi/overview).
 
 ## Install
 

package/eslint.config.js

@@ -1,3 +1,3 @@
-'use strict'
+import neostandard from 'neostandard'
 
-module.exports = require('neostandard')({ ts: true })
+export default neostandard({ ts: true })

package/index.d.ts

@@ -27,4 +27,7 @@ export default plugin
 export module errors {
   export const UnableToCreateTheRouteForTheReverseRelationshipError: () => FastifyError
   export const UnableToCreateTheRouteForThePKColRelationshipError: () => FastifyError
+  export const UnableToParseCursorStrError: () => FastifyError
+  export const CursorValidationError: () => FastifyError
+  export const PrimaryKeyNotIncludedInOrderByInCursorPaginationError: () => FastifyError
 }

package/index.js

@@ -1,39 +1,38 @@
-'use strict'
-
-const Swagger = require('@fastify/swagger')
-const ScalarApiReference = require('@scalar/fastify-api-reference')
-const deepmerge = require('@fastify/deepmerge')({ all: true })
-const { mapSQLEntityToJSONSchema } = require('@platformatic/sql-json-schema-mapper')
-const { findNearestString } = require('@platformatic/utils')
-const entityPlugin = require('./lib/entity-to-routes')
-const manyToMany = require('./lib/many-to-many')
-const { getSchemaOverrideFromOpenApiPathItem } = require('./lib/utils')
-const fp = require('fastify-plugin')
-const errors = require('./lib/errors')
+import Swagger from '@fastify/swagger'
+import { deepmerge, findNearestString } from '@platformatic/foundation'
+import { mapSQLEntityToJSONSchema } from '@platformatic/sql-json-schema-mapper'
+import fp from 'fastify-plugin'
+import { entityPlugin } from './lib/entity-to-routes.js'
+import { manyToMany } from './lib/many-to-many.js'
+import { getSchemaOverrideFromOpenApiPathItem } from './lib/utils.js'
 
 async function setupOpenAPI (app, opts) {
   const prefix = opts.prefix || ''
-  const openapiConfig = deepmerge({
-    exposeRoute: true,
-    info: {
-      title: 'Platformatic DB',
-      description: 'Exposing a SQL database as REST',
-      version: '1.0.0',
+  const openapiConfig = deepmerge(
+    {
+      exposeRoute: true,
+      info: {
+        title: 'Platformatic DB',
+        description: 'Exposing a SQL database as REST',
+        version: '1.0.0'
+      },
+      servers: [{ url: globalThis.platformatic?.runtimeBasePath ?? '/' }]
     },
-  }, opts)
+    opts
+  )
   app.log.trace({ openapi: openapiConfig })
   await app.register(Swagger, {
     exposeRoute: openapiConfig.exposeRoute,
     openapi: {
-      ...openapiConfig,
+      ...openapiConfig
     },
     refResolver: {
       buildLocalReference (json, baseUri, fragment, i) {
         // TODO figure out if we need def-${i}
         /* istanbul ignore next */
         return json.$id || `def-${i}`
-      },
-    },
+      }
+    }
   })
 
   const ignore = opts.ignore || []
@@ -42,26 +41,27 @@ async function setupOpenAPI (app, opts) {
   const paths = opts.paths || {}
 
   const { default: scalarTheme } = await import('@platformatic/scalar-theme')
+  const { default: scalarApiReference } = await import('@scalar/fastify-api-reference')
   const routePrefix = opts.swaggerPrefix || '/documentation'
 
   app.get(`${routePrefix}/json`, { schema: { hide: true }, logLevel: 'warn' }, async () => app.swagger())
   app.get(`${routePrefix}/yaml`, { schema: { hide: true }, logLevel: 'warn' }, async () => app.swagger({ yaml: true }))
 
-  app.register(ScalarApiReference, {
+  app.register(scalarApiReference, {
     ...opts,
     logLevel: 'warn',
     prefix: undefined,
     routePrefix,
     configuration: {
-      customCss: scalarTheme.theme,
-    },
+      customCss: scalarTheme.theme
+    }
   })
 
-  app.addHook('onRoute', (routeOptions) => {
+  app.addHook('onRoute', routeOptions => {
     if (paths[routeOptions.url]) {
       routeOptions.schema = {
         ...routeOptions.schema,
-        ...getSchemaOverrideFromOpenApiPathItem(paths[routeOptions.url], routeOptions.method),
+        ...getSchemaOverrideFromOpenApiPathItem(paths[routeOptions.url], routeOptions.method)
       }
     }
   })
@@ -97,7 +97,7 @@ async function setupOpenAPI (app, opts) {
       const targetEntity = app.platformatic.entities[targetEntityName]
       const reverseRelationship = {
         sourceEntity: relation.entityName,
-        relation,
+        relation
       }
       /* istanbul ignore next */
       targetEntity.reverseRelationships = targetEntity.reverseRelationships || []
@@ -105,8 +105,7 @@ async function setupOpenAPI (app, opts) {
     }
   }
 
-  const entitiesNames = Object.values(app.platformatic.entities)
-    .map(entity => entity.singularName)
+  const entitiesNames = Object.values(app.platformatic.entities).map(entity => entity.singularName)
 
   for (const ignoredEntity of Object.keys(ignore)) {
     if (!entitiesNames.includes(ignoredEntity)) {
@@ -141,7 +140,7 @@ async function setupOpenAPI (app, opts) {
         entity,
         prefix: localPrefix,
         ignore: ignore[entity.singularName] || {},
-        ignoreRoutes,
+        ignoreRoutes
       })
     } else {
       // TODO support ignore
@@ -149,11 +148,11 @@ async function setupOpenAPI (app, opts) {
         entity,
         prefix: localPrefix,
         ignore,
-        ignoreRoutes,
+        ignoreRoutes
       })
     }
   }
 }
 
-module.exports = fp(setupOpenAPI)
-module.exports.errors = errors
+export default fp(setupOpenAPI)
+export * as errors from './lib/errors.js'

package/lib/cursor.js

@@ -0,0 +1,94 @@
+import Ajv from 'ajv'
+import camelCase from 'camelcase'
+import fjs from 'fast-json-stringify'
+import fastUri from 'fast-uri'
+import sjson from 'secure-json-parse'
+import {
+  CursorValidationError,
+  PrimaryKeyNotIncludedInOrderByInCursorPaginationError,
+  UnableToParseCursorStrError
+} from './errors.js'
+
+const ajvOptions = {
+  coerceTypes: 'array',
+  useDefaults: true,
+  removeAdditional: true,
+  uriResolver: fastUri,
+  addUsedSchema: false,
+  allErrors: false
+}
+const ajv = new Ajv(ajvOptions)
+
+export function buildCursorUtils (app, entity) {
+  const entitySchema = app.getSchema(entity.name)
+  const cursorSchema = {
+    $id: entity.name + 'Cursor',
+    title: entitySchema.title + ' Cursor',
+    description: entitySchema.description + ' cursor',
+    type: 'object',
+    properties: entitySchema.properties,
+    additionalProperties: false
+  }
+  const validateCursor = ajv.compile(cursorSchema)
+  const stringifyCursor = fjs(cursorSchema, {
+    ajv: ajvOptions
+  })
+
+  function encodeCursor (cursor) {
+    return Buffer.from(stringifyCursor(cursor)).toString('base64')
+  }
+
+  function decodeCursor (cursorBase64) {
+    const cursorString = Buffer.from(cursorBase64, 'base64').toString()
+    let parsedCursor
+    try {
+      parsedCursor = sjson.parse(cursorString)
+    } catch (error) {
+      throw new UnableToParseCursorStrError(error.message)
+    }
+    if (!validateCursor(parsedCursor)) {
+      const error = validateCursor.errors[0]
+      throw new CursorValidationError(`${error.instancePath} ${error.message}`)
+    }
+    return parsedCursor
+  }
+
+  function transformQueryToCursor ({ startAfter, endBefore }) {
+    const parsedData = {
+      nextPage: true,
+      cursor: null
+    }
+    if (startAfter) {
+      parsedData.cursor = decodeCursor(startAfter)
+    } else if (endBefore) {
+      parsedData.cursor = decodeCursor(endBefore)
+      parsedData.nextPage = false
+    }
+    return parsedData
+  }
+
+  function buildCursorHeaders ({ findResult, orderBy, primaryKeys }) {
+    const firstItem = findResult.at(0)
+    const lastItem = findResult.at(-1)
+    const firstItemCursor = {}
+    const lastItemCursor = {}
+    const camelCasedPrimaryKeys = Array.from(primaryKeys).map(key => camelCase(key))
+    let hasPrimaryKey = false
+    for (const { field } of orderBy) {
+      if (firstItem[field] === undefined) continue
+      firstItemCursor[field] = firstItem[field]
+      lastItemCursor[field] = lastItem[field]
+      if (camelCasedPrimaryKeys.includes(field)) hasPrimaryKey = true
+    }
+    if (!hasPrimaryKey) throw new PrimaryKeyNotIncludedInOrderByInCursorPaginationError()
+    return {
+      endBefore: encodeCursor(firstItemCursor),
+      startAfter: encodeCursor(lastItemCursor)
+    }
+  }
+
+  return {
+    transformQueryToCursor,
+    buildCursorHeaders
+  }
+}