@platformatic/sql-mapper 0.0.23

package/lib/queries/sqlite.js

@@ -0,0 +1,169 @@
+'use strict'
+
+const { randomUUID } = require('crypto')
+
+async function listTables (db, sql) {
+  const tables = await db.query(sql`
+    SELECT name FROM sqlite_master
+    WHERE type='table'
+  `)
+  return tables.map(t => t.name)
+}
+
+module.exports.listTables = listTables
+
+async function listColumns (db, sql, table) {
+  const columns = await db.query(sql`
+    SELECT * FROM pragma_table_info(${table})
+  `)
+  for (const column of columns) {
+    column.column_name = column.name
+    // convert varchar(42) in varchar
+    column.udt_name = column.type.replace(/^([^(]+).*/, '$1').toLowerCase()
+    // convert is_nullable
+    column.is_nullable = column.notnull === 0 && column.pk === 0 ? 'YES' : 'NO'
+  }
+  return columns
+}
+
+module.exports.listColumns = listColumns
+
+async function listConstraints (db, sql, table) {
+  const constraints = []
+  const pks = await db.query(sql`
+    SELECT *
+    FROM pragma_table_info(${table})
+    WHERE pk > 0
+  `)
+
+  if (pks.length > 1) {
+    throw new Error(`Table ${table} has ${pks.length} primary keys`)
+  }
+
+  if (pks.length === 1) {
+    constraints.push({
+      column_name: pks[0].name,
+      constraint_type: 'PRIMARY KEY'
+    })
+  }
+
+  const foreignKeys = await db.query(sql`
+    SELECT *
+    FROM pragma_foreign_key_list(${table})
+  `)
+
+  for (const foreignKey of foreignKeys) {
+    constraints.push({
+      table_name: table,
+      column_name: foreignKey.from,
+      constraint_type: 'FOREIGN KEY',
+      foreign_table_name: foreignKey.table,
+      foreign_column_name: foreignKey.to
+    })
+  }
+  return constraints
+}
+
+module.exports.listConstraints = listConstraints
+
+async function insertOne (db, sql, table, input, primaryKey, useUUID, fieldsToRetrieve) {
+  const keysToSql = Object.keys(input).map((key) => sql.ident(key))
+  keysToSql.push(sql.ident(primaryKey))
+  const keys = sql.join(
+    keysToSql,
+    sql`, `
+  )
+
+  const valuesToSql = Object.keys(input).map((key) => {
+    return sql.value(input[key])
+  })
+  let primaryKeyValue
+  // TODO add test for this
+  if (useUUID) {
+    primaryKeyValue = randomUUID()
+    valuesToSql.push(sql.value(primaryKeyValue))
+  } else {
+    valuesToSql.push(sql.value(null))
+  }
+  const values = sql.join(
+    valuesToSql,
+    sql`, `
+  )
+
+  const insert = sql`
+    INSERT INTO ${sql.ident(table)} (${keys})
+    VALUES(${values})
+  `
+  await db.query(insert)
+
+  if (!useUUID) {
+    const res2 = await db.query(sql`
+      SELECT last_insert_rowid()
+    `)
+
+    primaryKeyValue = res2[0]['last_insert_rowid()']
+  }
+
+  const res = await db.query(sql`
+    SELECT ${sql.join(fieldsToRetrieve, sql`, `)}
+    FROM ${sql.ident(table)}
+    WHERE ${sql.ident(primaryKey)} = ${sql.value(primaryKeyValue)}
+  `)
+
+  return res[0]
+}
+
+module.exports.insertOne = insertOne
+
+async function updateOne (db, sql, table, input, primaryKey, fieldsToRetrieve) {
+  const pairs = Object.keys(input).map((key) => {
+    const value = input[key]
+    return sql`${sql.ident(key)} = ${value}`
+  })
+
+  const update = sql`
+    UPDATE ${sql.ident(table)}
+    SET ${sql.join(pairs, sql`, `)}
+    WHERE ${sql.ident(primaryKey)} = ${sql.value(input[primaryKey])}
+  `
+  await db.query(update)
+
+  const select = sql`
+    SELECT ${sql.join(fieldsToRetrieve, sql`, `)}
+    FROM ${sql.ident(table)}
+    WHERE ${sql.ident(primaryKey)} = ${sql.value(input[primaryKey])}
+  `
+  const res = await db.query(select)
+  return res[0]
+}
+
+module.exports.updateOne = updateOne
+
+async function deleteAll (db, sql, table, criteria, fieldsToRetrieve) {
+  let query = sql`
+    SELECT ${sql.join(fieldsToRetrieve, sql`, `)}
+    FROM ${sql.ident(table)}
+  `
+
+  /* istanbul ignore else */
+  if (criteria.length > 0) {
+    query = sql`${query} WHERE ${sql.join(criteria, sql` AND `)}`
+  }
+
+  const data = await db.query(query)
+
+  query = sql`
+    DELETE FROM ${sql.ident(table)}
+  `
+
+  /* istanbul ignore else */
+  if (criteria.length > 0) {
+    query = sql`${query} WHERE ${sql.join(criteria, sql` AND `)}`
+  }
+
+  await db.query(query)
+
+  return data
+}
+
+module.exports.deleteAll = deleteAll

package/lib/utils.js

@@ -0,0 +1,14 @@
+'use strict'
+
+const { singularize } = require('inflected')
+const camelcase = require('camelcase')
+
+function toSingular (str) {
+  str = camelcase(singularize(str))
+  str = str[0].toUpperCase() + str.slice(1)
+  return str
+}
+
+module.exports = {
+  toSingular
+}

package/mapper.d.ts

@@ -0,0 +1,308 @@
+import { FastifyPluginAsync } from 'fastify'
+import { SQL, SQLQuery } from '@databases/sql'
+
+interface ILogger {
+  trace(): any,
+  error(): any
+}
+
+export interface Database {
+  /**
+   * An option that is true if a Postgres database is used.
+   */
+  isPg?: boolean,
+  /**
+   * An option that is true if a MariaDB database is used.
+   */
+  isMariaDB?: boolean,
+  /**
+   * An option that is true if a MySQL database is used.
+   */
+  isMySQL?: boolean,
+  /**
+   * An option that is true if a SQLite database is used.
+   */
+  isSQLite?: boolean,
+  /**
+   * Run an SQL Query and get a promise for an array of results. If your query contains multiple statements, only the results of the final statement are returned.
+   */
+  query(query: SQLQuery): Promise<any[]>,
+  /**
+   * Dispose the connection. Once this is called, any subsequent queries will fail.
+   */
+  dispose(): Promise<void>
+}
+
+export interface DBEntityField {
+  /**
+   * Field type in the database.
+   */
+  sqlType: string,
+  /**
+   * Camel cased field name.
+   */
+  camelcase: string,
+  /**
+   * An option that is true if field is a primary key.
+   */
+  primaryKey?: boolean,
+  /**
+   * An option that is true if field is a foreignKey key.
+   */
+  foreignKey?: boolean,
+  /**
+   * An option that is true if field is nullable.
+   */
+  isNullable: boolean,
+  /**
+   * An option that is true if auto timestamp enabled for this field.
+   */
+  autoTimestamp?: boolean
+}
+
+export interface WhereCondition {
+  [columnName: string]: {
+    /**
+     * Equal to value.
+     */
+    eq?: string,
+    /**
+     * Not equal to value.
+     */
+    neq?: string,
+    /**
+     * Greater than value.
+     */
+    gr?: any,
+    /**
+     * Greater than or equal to value.
+     */
+    gte?: any,
+    /**
+     * Less than value.
+     */
+    lt?: any,
+    /**
+     * Less than or equal to value.
+     */
+    lte?: any,
+    /**
+     * In values.
+     */
+    in?: any[],
+    /**
+     * Not in values.
+     */
+    nin?: any[]
+  }
+}
+
+interface Find<EntityFields> {
+  (options?: {
+    /**
+     * SQL where condition.
+     */
+    where?: WhereCondition,
+    /**
+     * List of fields to be returned for each object
+     */
+    fields?: string[],
+    /**
+     * Entity fields to order by.
+     */
+    orderBy?: Array<{ field: string, direction: 'asc' | 'desc' }>,
+    /**
+     * Number of entities to select.
+     */
+    limit?: number,
+    /**
+     * Number of entities to skip.
+     */
+    offset?: number,
+  }): Promise<Partial<EntityFields>[]>
+}
+
+interface Insert<EntityFields> {
+  (options: {
+    /**
+     * Entities to insert.
+     */
+    inputs: EntityFields[],
+    /**
+     * List of fields to be returned for each object
+     */
+    fields?: string[]
+  }): Promise<Partial<EntityFields>[]>
+}
+
+interface Save<EntityFields> {
+  (options: {
+    /**
+     * Entity to save.
+     */
+    input: EntityFields,
+    /**
+     * List of fields to be returned for each object
+     */
+    fields?: string[]
+  }): Promise<Partial<EntityFields>>
+}
+
+interface Delete<EntityFields> {
+  (options?: {
+    /**
+     * SQL where condition.
+     */
+    where: WhereCondition,
+    /**
+     * List of fields to be returned for each object
+     */
+    fields: string[]
+  }): Promise<Partial<EntityFields>[]>,
+}
+
+export interface Entity<EntityFields = any> {
+  /**
+   * The origin name of the database entity.
+   */
+  name: string,
+  /**
+   * The name of the database object in the singular.
+   */
+  singularName: string,
+  /**
+   * The plural name of the database entity.
+   */
+  pluralName: string,
+  /**
+   * The primary key of the database entity.
+   */
+  primaryKey: string,
+  /**
+   * The table of the database entity.
+   */
+  table: string,
+  /**
+   * Fields of the database entity.
+   */
+  fields: { [columnName: string]: DBEntityField },
+  /**
+   * Camel cased fields of the database entity.
+   */
+  camelCasedFields: { [columnName: string]: DBEntityField },
+  /**
+   * Relations with other database entities.
+   */
+  relations: any[],
+  /**
+   * Converts entities fields names to database column names.
+   */
+  fixInput(input: { [columnName: string]: any }): { [columnName: string]: any },
+  /**
+   * Converts database column names to entities fields names.
+   */
+  fixOutput(input: { [columnName: string]: any }): { [columnName: string]: any },
+  /**
+   * Selects matching entities from the database.
+   */
+  find: Find<EntityFields>,
+  /**
+   * Inserts entities to the database.
+   */
+  insert: Insert<EntityFields>,
+  /**
+   * Saves entity to the database.
+   */
+  save: Save<EntityFields>,
+  /**
+   * Deletes entities from the database.
+   */
+  delete: Delete<EntityFields>,
+}
+
+
+export interface EntityHooks<EntityFields = any> {
+  [entityName: string]: {
+    find?: Find<EntityFields>,
+    insert?: Insert<EntityFields>,
+    save?: Save<EntityFields>,
+    delete?: Delete<EntityFields>,
+  }
+}
+
+export interface SQLMapperPluginOptions {
+  /**
+   * Database connection string.
+   */
+  connectionString: string,
+  /**
+   * Set to true to enable auto timestamping for updated_at and inserted_at fields.
+   */
+  autoTimestamp?: boolean,
+  /**
+   * A logger object (like [Pino](https://getpino.io))
+   */
+  log?: ILogger,
+  /**
+   * Database table to ignore when mapping to entities.
+   */
+  ignore?: {
+    [tableName: string]: {
+      [columnName: string]: boolean
+    } | boolean
+  },
+  /**
+   * For each entity name (like `Page`) you can customize any of the entity API function. Your custom function will receive the original function as first parameter, and then all the other parameters passed to it.
+   */
+  hooks?: EntityHooks,
+  /**
+   * An async function that is called after the connection is established.
+   */
+  onDatabaseLoad?(db: Database, sql: SQL): any,
+}
+
+export interface Entities {
+  [entityName: string]: Entity
+}
+
+export interface SQLMapperPluginInterface {
+  /**
+   * A Database abstraction layer from [@Databases](https://www.atdatabases.org/)
+   */
+  db: Database,
+  /**
+   * The SQL builder from [@Databases](https://www.atdatabases.org/)
+   */
+  sql: SQL,
+  /**
+   * An object containing a key for each table found in the schema, with basic CRUD operations. See [entity.md](./entity.md) for details.
+   */
+  entities: Entities,
+  /**
+   * Adds hooks to the entity.
+   */
+  addEntityHooks(entityName: string, hooks: EntityHooks): any
+}
+
+declare module 'fastify' {
+  interface FastifyInstance {
+    platformatic: SQLMapperPluginInterface
+  }
+}
+
+/**
+ * Connects to the database and maps the tables to entities.
+ */
+export function connect(options: SQLMapperPluginOptions): Promise<SQLMapperPluginInterface>
+/**
+ * Fastify plugin that connects to the database and maps the tables to entities.
+ */
+export const plugin: FastifyPluginAsync<SQLMapperPluginOptions>
+export default plugin
+
+/**
+ * An object that contains utility functions.
+ */
+export module utils {
+  export function toSingular (str: string): string
+}

package/mapper.js

@@ -0,0 +1,155 @@
+'use strict'
+
+const buildEntity = require('./lib/entity')
+const queriesFactory = require('./lib/queries')
+const fp = require('fastify-plugin')
+
+// Ignore the function as it is only used only for MySQL and PostgreSQL
+/* istanbul ignore next */
+async function buildConnection (log, createConnectionPool, connectionString) {
+  const db = await createConnectionPool({
+    connectionString,
+    bigIntMode: 'string',
+    onQueryStart: (_query, { text, values }) => {
+      log.trace({
+        query: {
+          text,
+          values
+        }
+      }, 'start query')
+    },
+    onQueryResults: (_query, { text }, results) => {
+      log.trace({
+        query: {
+          text,
+          results: results.length
+        }
+      }, 'end query')
+    },
+    onQueryError: (_query, { text }, err) => {
+      log.error({
+        query: {
+          text,
+          error: err.message
+        }
+      }, 'query error')
+    }
+  })
+  return db
+}
+
+async function connect ({ connectionString, log, onDatabaseLoad, ignore = {}, autoTimestamp = true, hooks = {} }) {
+  // TODO validate config using the schema
+  if (!connectionString) {
+    throw new Error('connectionString is required')
+  }
+
+  let queries
+  let sql
+  let db
+
+  /* istanbul ignore next */
+  if (connectionString.indexOf('postgres') === 0) {
+    const createConnectionPoolPg = require('@databases/pg')
+    db = await buildConnection(log, createConnectionPoolPg, connectionString)
+    sql = createConnectionPoolPg.sql
+    queries = queriesFactory.pg
+    db.isPg = true
+  } else if (connectionString.indexOf('mysql') === 0) {
+    const createConnectionPoolMysql = require('@databases/mysql')
+    db = await buildConnection(log, createConnectionPoolMysql, connectionString)
+    sql = createConnectionPoolMysql.sql
+    const version = (await db.query(sql`SELECT VERSION()`))[0]['VERSION()']
+    db.version = version
+    db.isMariaDB = version.indexOf('maria') !== -1
+    if (db.isMariaDB) {
+      queries = queriesFactory.mariadb
+    } else {
+      db.isMySQL = true
+      queries = queriesFactory.mysql
+    }
+  } else if (connectionString.indexOf('sqlite') === 0) {
+    const sqlite = require('@databases/sqlite')
+    const path = connectionString.replace('sqlite://', '')
+    db = sqlite(connectionString === 'sqlite://:memory:' ? undefined : path)
+    sql = sqlite.sql
+    queries = queriesFactory.sqlite
+    db.isSQLite = true
+  } else {
+    throw new Error('You must specify either postgres, mysql or sqlite as protocols')
+  }
+
+  const entities = {}
+
+  try {
+    /* istanbul ignore else */
+    if (typeof onDatabaseLoad === 'function') {
+      await onDatabaseLoad(db, sql)
+    }
+
+    const tables = await queries.listTables(db, sql)
+
+    for (const table of tables) {
+      // The following line is a safety net when developing this module,
+      // it should never happen.
+      /* istanbul ignore next */
+      if (typeof table !== 'string') {
+        throw new Error(`Table must be a string, got '${table}'`)
+      }
+      if (ignore[table] === true) {
+        continue
+      }
+
+      const entity = await buildEntity(db, sql, log, table, queries, autoTimestamp, ignore[table] || {})
+      // Check for primary key of all entities
+      if (!entity.primaryKey) {
+        throw new Error(`Cannot find primary key for ${entity.name} entity`)
+      }
+      entities[entity.singularName] = entity
+      if (hooks[entity.name]) {
+        addEntityHooks(entity.singularName, hooks[entity.name])
+      } else if (hooks[entity.singularName]) {
+        addEntityHooks(entity.singularName, hooks[entity.singularName])
+      }
+    }
+  } catch (err) /* istanbul ignore next */ {
+    db.dispose()
+    throw err
+  }
+
+  return {
+    db,
+    sql,
+    entities,
+    addEntityHooks
+  }
+
+  function addEntityHooks (entityName, hooks) {
+    const entity = entities[entityName]
+    if (!entity) {
+      throw new Error('Cannot find entity ' + entityName)
+    }
+    for (const key of Object.keys(hooks)) {
+      if (hooks[key] && entity[key]) {
+        entity[key] = hooks[key].bind(null, entity[key])
+      }
+    }
+  }
+}
+
+async function sqlMapper (app, opts) {
+  const mapper = await connect({
+    log: app.log,
+    ...opts
+  })
+
+  app.onClose(() => mapper.db.dispose())
+  // TODO this would need to be refactored as other plugins
+  // would need to use this same namespace
+  app.decorate('platformatic', mapper)
+}
+
+module.exports = fp(sqlMapper)
+module.exports.connect = connect
+module.exports.plugin = module.exports
+module.exports.utils = require('./lib/utils')

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@platformatic/sql-mapper",
+  "version": "0.0.23",
+  "description": "A data mapper utility for SQL databases",
+  "main": "mapper.js",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/platformatic/platformatic.git"
+  },
+  "author": "Matteo Collina <hello@matteocollina.com>",
+  "license": "Apache-2.0",
+  "bugs": {
+    "url": "https://github.com/platformatic/platformatic/issues"
+  },
+  "homepage": "https://github.com/platformatic/platformatic#readme",
+  "devDependencies": {
+    "fastify": "^4.5.3",
+    "snazzy": "^9.0.0",
+    "standard": "^17.0.0",
+    "tap": "^16.0.0",
+    "tsd": "^0.24.0"
+  },
+  "dependencies": {
+    "@databases/mysql": "^5.2.0",
+    "@databases/pg": "^5.3.0",
+    "@databases/sql": "^3.2.0",
+    "@databases/sqlite": "^4.0.0",
+    "camelcase": "^6.0.0",
+    "fastify-plugin": "^4.1.0",
+    "inflected": "^2.1.0"
+  },
+  "tsd": {
+    "directory": "test/types"
+  },
+  "scripts": {
+    "test": "standard | snazzy && 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 tap test/*.test.js",
+    "test:mariadb": "DB=mariadb tap test/*.test.js",
+    "test:mysql": "DB=mysql tap test/*.test.js",
+    "test:mysql8": "DB=mysql8 tap test/*.test.js",
+    "test:sqlite": "DB=sqlite tap test/*.test.js",
+    "test:typescript": "tsd"
+  }
+}