@platformatic/sql-mapper 3.4.1 → 3.5.1

package/README.md

@@ -1,6 +1,6 @@
 # @platformatic/sql-mapper
 
-Check out the full documentation on [our website](https://docs.platformatic.dev/docs/packages/sql-mapper/fastify-plugin/#sql-mapper-fastify-plugin).
+Check out the full documentation on [our website](https://docs.platformatic.dev/docs/reference/sql-mapper/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/{mapper.d.ts → index.d.ts}

@@ -69,6 +69,12 @@ export interface DBEntityField {
   autoTimestamp?: boolean
 }
 
+export type WhereClause = {
+  or?: WhereCondition[];
+} | {
+  [columnName: string]: WhereCondition[string];
+}
+
 export interface WhereCondition {
   [columnName: string]: {
     /**
@@ -134,12 +140,16 @@ export interface WhereCondition {
   }
 }
 
+export type Cursor = {
+  [columnName: string]: string | number | boolean | null,
+}
+
 interface Find<EntityFields> {
   (options?: {
     /**
      * SQL where condition.
      */
-    where?: WhereCondition,
+    where?: WhereClause,
     /**
      * List of fields to be returned for each object
      */
@@ -156,10 +166,29 @@ interface Find<EntityFields> {
      * Number of entities to skip.
      */
     offset?: number,
+    /**
+     * If false pagination is disabled.
+     * @default true
+     */
+    paginate?: boolean,
+    /**
+     * Cursor to paginate the results.
+     */
+    cursor?: Cursor,
+    /**
+      * If set to false, the previous page will be fetched in cursor pagination.
+     * @default true
+     */
+    nextPage?: boolean,
     /**
      * If present, the entity participates in transaction
      */
     tx?: Database
+    /**
+     * Passing this to all sql-mapper functions allow to apply
+     * authorization rules to the database queries (amongst other things).
+     */
+    ctx?: PlatformaticContext
   }): Promise<Partial<EntityFields>[]>
 }
 
@@ -168,11 +197,16 @@ interface Count {
     /**
      * SQL where condition.
      */
-    where?: WhereCondition,
+    where?: WhereClause,
     /**
      * If present, the entity participates in transaction
      */
-    tx?: Database
+    tx?: Database,
+    /**
+     * Passing this to all sql-mapper functions allow to apply
+     * authorization rules to the database queries (amongst other things).
+     */
+    ctx?: PlatformaticContext
   }): Promise<number>
 }
 
@@ -189,7 +223,12 @@ interface Insert<EntityFields> {
     /**
      * If present, the entity participates in transaction
      */
-    tx?: Database
+    tx?: Database,
+    /**
+     * Passing this to all sql-mapper functions allow to apply
+     * authorization rules to the database queries (amongst other things).
+     */
+    ctx?: PlatformaticContext
   }): Promise<Partial<EntityFields>[]>
 }
 
@@ -206,7 +245,12 @@ interface Save<EntityFields> {
     /**
      * If present, the entity participates in transaction
      */
-    tx?: Database
+    tx?: Database,
+    /**
+     * Passing this to all sql-mapper functions allow to apply
+     * authorization rules to the database queries (amongst other things).
+     */
+    ctx?: PlatformaticContext
   }): Promise<Partial<EntityFields>>
 }
 
@@ -215,7 +259,7 @@ interface Delete<EntityFields> {
     /**
      * SQL where condition.
      */
-    where?: WhereCondition,
+    where?: WhereClause,
     /**
      * List of fields to be returned for each object
      */
@@ -223,7 +267,12 @@ interface Delete<EntityFields> {
     /**
      * If present, the entity participates in transaction
      */
-    tx?: Database
+    tx?: Database,
+    /**
+     * Passing this to all sql-mapper functions allow to apply
+     * authorization rules to the database queries (amongst other things).
+     */
+    ctx?: PlatformaticContext
   }): Promise<Partial<EntityFields>[]>,
 }
 
@@ -232,11 +281,11 @@ interface UpdateMany<EntityFields> {
     /**
      * SQL where condition.
      */
-    where: WhereCondition,
+    where?: WhereClause,
     /**
      * Entity fields to update.
      */
-    input: EntityFields,
+    input: Partial<EntityFields>,
     /**
      * List of fields to be returned for each object
      */
@@ -244,7 +293,12 @@ interface UpdateMany<EntityFields> {
     /**
      * If present, the entity participates in transaction
      */
-    tx?: Database
+    tx?: Database,
+    /**
+     * Passing this to all sql-mapper functions allow to apply
+     * authorization rules to the database queries (amongst other things).
+     */
+    ctx?: PlatformaticContext
   }): Promise<Partial<EntityFields>[]>
 }
 
@@ -265,6 +319,10 @@ export interface Entity<EntityFields = any> {
    * The primary key of the database entity.
    */
   primaryKey: string,
+  /**
+   * Primary keys of the database entity.
+   */
+  primaryKeys: Set<string>,
   /**
    * The table of the database entity.
    */

package/{mapper.js → index.js}

@@ -1,19 +1,31 @@
-'use strict'
-
-const fp = require('fastify-plugin')
-const { findNearestString } = require('@platformatic/utils')
-const buildEntity = require('./lib/entity')
-const buildCleanUp = require('./lib/clean-up')
-const queriesFactory = require('./lib/queries')
-const { areSchemasSupported } = require('./lib/utils')
-const errors = require('./lib/errors')
-const setupCache = require('./lib/cache')
-const { setupTelemetry } = require('./lib/telemetry')
-const { getConnectionInfo } = require('./lib/connection-info')
+import { findNearestString } from '@platformatic/foundation'
+import fp from 'fastify-plugin'
+import { setupCache } from './lib/cache.js'
+import { buildCleanUp } from './lib/clean-up.js'
+import { getConnectionInfo } from './lib/connection-info.js'
+import { buildEntity } from './lib/entity.js'
+import {
+  CannotFindEntityError,
+  ConnectionStringRequiredError,
+  SpecifyProtocolError,
+  TableMustBeAStringError
+} from './lib/errors.js'
+import * as queriesFactory from './lib/queries/index.js'
+import { setupTelemetry } from './lib/telemetry.js'
+import { areSchemasSupported } from './lib/utils.js'
 
 // Ignore the function as it is only used only for MySQL and PostgreSQL
 /* istanbul ignore next */
-async function buildConnection (log, createConnectionPool, connectionString, poolSize, schema, idleTimeoutMilliseconds, queueTimeoutMilliseconds, acquireLockTimeoutMilliseconds) {
+async function buildConnection (
+  log,
+  createConnectionPool,
+  connectionString,
+  poolSize,
+  schema,
+  idleTimeoutMilliseconds,
+  queueTimeoutMilliseconds,
+  acquireLockTimeoutMilliseconds
+) {
   const db = await createConnectionPool({
     connectionString,
     bigIntMode: 'string',
@@ -22,40 +34,56 @@ async function buildConnection (log, createConnectionPool, connectionString, poo
     queueTimeoutMilliseconds,
     acquireLockTimeoutMilliseconds,
     onQueryStart: (_query, { text, values }) => {
-      log.trace({
-        query: {
-          text,
-          values,
+      log.trace(
+        {
+          query: {
+            text,
+            values
+          }
         },
-      }, 'start query')
+        'start query'
+      )
     },
     onQueryResults: (_query, { text }, results) => {
-      log.trace({
-        query: {
-          text,
-          results: results.length,
+      log.trace(
+        {
+          query: {
+            text,
+            results: results.length
+          }
         },
-      }, 'end query')
+        'end query'
+      )
     },
     onQueryError: (_query, { text }, err) => {
-      log.error({
-        query: {
-          text,
-          error: err.message,
+      log.error(
+        {
+          query: {
+            text,
+            error: err.message
+          }
         },
-      }, 'query error')
+        'query error'
+      )
     },
-    schema,
+    schema
   })
   return db
 }
 
 const defaultAutoTimestampFields = {
   createdAt: 'created_at',
-  updatedAt: 'updated_at',
+  updatedAt: 'updated_at'
 }
 
-async function createConnectionPool ({ log, connectionString, poolSize, idleTimeoutMilliseconds, queueTimeoutMilliseconds, acquireLockTimeoutMilliseconds }) {
+export async function createConnectionPool ({
+  log,
+  connectionString,
+  poolSize,
+  idleTimeoutMilliseconds,
+  queueTimeoutMilliseconds,
+  acquireLockTimeoutMilliseconds
+}) {
   let db
   let sql
 
@@ -63,13 +91,31 @@ async function createConnectionPool ({ log, connectionString, poolSize, idleTime
 
   /* istanbul ignore next */
   if (connectionString.indexOf('postgres') === 0) {
-    const createConnectionPoolPg = require('@databases/pg')
-    db = await buildConnection(log, createConnectionPoolPg, connectionString, poolSize, null, idleTimeoutMilliseconds, queueTimeoutMilliseconds, acquireLockTimeoutMilliseconds)
+    const { default: createConnectionPoolPg } = await import('@databases/pg')
+    db = await buildConnection(
+      log,
+      createConnectionPoolPg,
+      connectionString,
+      poolSize,
+      null,
+      idleTimeoutMilliseconds,
+      queueTimeoutMilliseconds,
+      acquireLockTimeoutMilliseconds
+    )
     sql = createConnectionPoolPg.sql
     db.isPg = true
   } else if (connectionString.indexOf('mysql') === 0) {
-    const createConnectionPoolMysql = require('@databases/mysql')
-    db = await buildConnection(log, createConnectionPoolMysql, connectionString, poolSize, null, idleTimeoutMilliseconds, queueTimeoutMilliseconds, acquireLockTimeoutMilliseconds)
+    const { default: createConnectionPoolMysql } = await import('@databases/mysql')
+    db = await buildConnection(
+      log,
+      createConnectionPoolMysql,
+      connectionString,
+      poolSize,
+      null,
+      idleTimeoutMilliseconds,
+      queueTimeoutMilliseconds,
+      acquireLockTimeoutMilliseconds
+    )
     sql = createConnectionPoolMysql.sql
     const version = (await db.query(sql`SELECT VERSION()`))[0]['VERSION()']
     db.version = version
@@ -78,27 +124,34 @@ async function createConnectionPool ({ log, connectionString, poolSize, idleTime
       db.isMySql = true
     }
   } else if (connectionString.indexOf('sqlite') === 0) {
-    const sqlite = require('@matteo.collina/sqlite-pool')
+    const { default: sqlite } = await import('@matteo.collina/sqlite-pool')
     const path = connectionString.replace('sqlite://', '')
-    db = sqlite.default(connectionString === 'sqlite://:memory:' ? undefined : path, {}, {
-      // TODO make this configurable
-      maxSize: 1,
-      // TODO make this configurable
-      // 10s max time to wait for a connection
-      releaseTimeoutMilliseconds: 10000,
-      onQuery ({ text, values }) {
-        log.trace({
-          query: {
-            text,
-          },
-        }, 'query')
-      },
-    })
+    db = sqlite.default(
+      connectionString === 'sqlite://:memory:' ? undefined : path,
+      {},
+      {
+        // TODO make this configurable
+        maxSize: 1,
+        // TODO make this configurable
+        // 10s max time to wait for a connection
+        releaseTimeoutMilliseconds: 10000,
+        onQuery ({ text, values }) {
+          log.trace(
+            {
+              query: {
+                text
+              }
+            },
+            'query'
+          )
+        }
+      }
+    )
     sql = sqlite.sql
     db.isSQLite = true
     db.sql = sql
   } else {
-    throw new errors.SpecifyProtocolError()
+    throw new SpecifyProtocolError()
   }
 
   // These info are necessary for telemetry attributes
@@ -108,17 +161,40 @@ async function createConnectionPool ({ log, connectionString, poolSize, idleTime
   return { db, sql }
 }
 
-async function connect ({ connectionString, log, onDatabaseLoad, poolSize, include = {}, ignore = {}, autoTimestamp = true, hooks = {}, schema, limit = {}, dbschema, cache, idleTimeoutMilliseconds, queueTimeoutMilliseconds, acquireLockTimeoutMilliseconds }) {
+export async function connect ({
+  connectionString,
+  log,
+  onDatabaseLoad,
+  poolSize,
+  include = {},
+  ignore = {},
+  autoTimestamp = true,
+  hooks = {},
+  schema,
+  limit = {},
+  dbschema,
+  cache,
+  idleTimeoutMilliseconds,
+  queueTimeoutMilliseconds,
+  acquireLockTimeoutMilliseconds
+}) {
   if (typeof autoTimestamp === 'boolean' && autoTimestamp === true) {
     autoTimestamp = defaultAutoTimestampFields
   }
   // TODO validate config using the schema
   if (!connectionString) {
-    throw new errors.ConnectionStringRequiredError()
+    throw new ConnectionStringRequiredError()
   }
 
   let queries
-  const { db, sql } = await createConnectionPool({ log, connectionString, poolSize, queueTimeoutMilliseconds, acquireLockTimeoutMilliseconds, idleTimeoutMilliseconds })
+  const { db, sql } = await createConnectionPool({
+    log,
+    connectionString,
+    poolSize,
+    queueTimeoutMilliseconds,
+    acquireLockTimeoutMilliseconds,
+    idleTimeoutMilliseconds
+  })
 
   /* istanbul ignore next */
   if (db.isPg) {
@@ -200,7 +276,7 @@ async function connect ({ connectionString, log, onDatabaseLoad, poolSize, inclu
       // it should never happen.
       /* istanbul ignore next */
       if (typeof table !== 'string') {
-        throw new errors.TableMustBeAStringError(table)
+        throw new TableMustBeAStringError(table)
       }
       // If include is being used and a table is not explicitly included add it to the ignore object
       if (Object.keys(include).length && !include[table]) {
@@ -209,7 +285,21 @@ async function connect ({ connectionString, log, onDatabaseLoad, poolSize, inclu
       if (ignore[table] === true) {
         continue
       }
-      const entity = buildEntity(db, sql, log, table, queries, autoTimestamp, schema, useSchema, ignore[table] || {}, limit, schemaList, columns, constraints)
+      const entity = buildEntity(
+        db,
+        sql,
+        log,
+        table,
+        queries,
+        autoTimestamp,
+        schema,
+        useSchema,
+        ignore[table] || {},
+        limit,
+        schemaList,
+        columns,
+        constraints
+      )
       // Check for primary key of all entities
       if (entity.primaryKeys.size === 0) {
         log.warn({ table }, 'Cannot find any primary keys for table')
@@ -231,7 +321,7 @@ async function connect ({ connectionString, log, onDatabaseLoad, poolSize, inclu
       entities,
       cleanUpAllEntities: buildCleanUp(db, sql, log, entities, queries),
       addEntityHooks,
-      dbschema,
+      dbschema
     }
 
     if (cache) {
@@ -247,7 +337,7 @@ async function connect ({ connectionString, log, onDatabaseLoad, poolSize, inclu
   function addEntityHooks (entityName, hooks) {
     const entity = entities[entityName]
     if (!entity) {
-      throw new errors.CannotFindEntityError(entityName)
+      throw new CannotFindEntityError(entityName)
     }
     for (const key of Object.keys(hooks)) {
       if (hooks[key] && entity[key]) {
@@ -260,7 +350,7 @@ async function connect ({ connectionString, log, onDatabaseLoad, poolSize, inclu
 async function sqlMapper (app, opts) {
   const mapper = await connect({
     log: app.log,
-    ...opts,
+    ...opts
   })
 
   app.onClose(() => mapper.db.dispose())
@@ -276,7 +366,7 @@ async function sqlMapper (app, opts) {
   app.addHook('onRequest', function (req, reply, done) {
     req.platformaticContext = {
       app: this, // uses the encapsulated fastify instance of the route
-      reply,
+      reply
     }
     done()
   })
@@ -300,7 +390,7 @@ async function dropTable (db, sql, table) {
   }
 }
 
-async function dropAllTables (db, sql, schemas) {
+export async function dropAllTables (db, sql, schemas) {
   let queries
   /* istanbul ignore next */
   if (db.isPg) {
@@ -313,13 +403,15 @@ async function dropAllTables (db, sql, schemas) {
     queries = queriesFactory.sqlite
   }
 
-  const tables = new Set((await queries.listTables(db, sql, schemas)).map((t) => {
-    /* istanbul ignore next */
-    if (t.schema) {
-      return `${t.schema}.${t.table}`
-    }
-    return t.table
-  }))
+  const tables = new Set(
+    (await queries.listTables(db, sql, schemas)).map(t => {
+      /* istanbul ignore next */
+      if (t.schema) {
+        return `${t.schema}.${t.table}`
+      }
+      return t.table
+    })
+  )
   let count = 0
 
   while (tables.size > 0) {
@@ -341,10 +433,7 @@ async function dropAllTables (db, sql, schemas) {
   }
 }
 
-module.exports = fp(sqlMapper)
-module.exports.connect = connect
-module.exports.createConnectionPool = createConnectionPool
-module.exports.plugin = module.exports
-module.exports.utils = require('./lib/utils')
-module.exports.errors = errors
-module.exports.dropAllTables = dropAllTables
+export const plugin = fp(sqlMapper)
+export default plugin
+export * as errors from './lib/errors.js'
+export * as utils from './lib/utils.js'

package/lib/cache.js

@@ -1,7 +1,6 @@
-'use strict'
-const { createCache } = require('async-cache-dedupe')
+import { createCache } from 'async-cache-dedupe'
 
-function setupCache (res, opts) {
+export function setupCache (res, opts) {
   // TODO validate opts
   if (opts === true) {
     opts = { ttl: 0 }
@@ -17,18 +16,22 @@ function setupCache (res, opts) {
     const fnName = `${entity.name}Find`
     const originalFn = entity.find
 
-    cache.define(fnName, {
-      serialize (query) {
-        const serialized = {
-          ...query,
-          ctx: undefined,
+    cache.define(
+      fnName,
+      {
+        serialize (query) {
+          const serialized = {
+            ...query,
+            ctx: undefined
+          }
+          return serialized
         }
-        return serialized
       },
-    }, async function (query) {
-      const res = await originalFn.call(entity, query)
-      return res
-    })
+      async function (query) {
+        const res = await originalFn.call(entity, query)
+        return res
+      }
+    )
 
     addEntityHooks(entity.singularName, {
       find (originalFn, query) {
@@ -36,11 +39,9 @@ function setupCache (res, opts) {
           return originalFn(query)
         }
         return cache[fnName](query)
-      },
+      }
     })
   }
 
   return cache
 }
-
-module.exports = setupCache

package/lib/clean-up.js

@@ -1,9 +1,7 @@
-'use strict'
+import { Sorter } from '@hapi/topo'
+import { tableName } from './utils.js'
 
-const { tableName } = require('./utils')
-const { Sorter } = require('@hapi/topo')
-
-function buildCleanUp (db, sql, logger, entities) {
+export function buildCleanUp (db, sql, logger, entities) {
   return async function cleanUp () {
     logger.trace('cleaning up')
     await db.tx(async tx => {
@@ -32,5 +30,3 @@ function buildCleanUp (db, sql, logger, entities) {
     })
   }
 }
-
-module.exports = buildCleanUp

package/lib/connection-info.js

@@ -1,7 +1,7 @@
 // The most general way to get the connection info is through the driver.
 // In this way, we don't need to do any assumptions about the connection string
 // (with the exception of SQLite)
-const getConnectionInfo = async (db, connectionString) => {
+export async function getConnectionInfo (db, connectionString) {
   let database, host, port, user
   let dbSystem = 'unknown'
   if (db.isPg) {
@@ -35,8 +35,6 @@ const getConnectionInfo = async (db, connectionString) => {
     isPg: !!db.isPg,
     isMySql: !!db.isMySql,
     isSQLite: !!db.isSQLite,
-    dbSystem,
+    dbSystem
   }
 }
-
-module.exports = { getConnectionInfo }