@cap-js/db-service 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -4,6 +4,24 @@
 - The format is based on [Keep a Changelog](http://keepachangelog.com/).
 - This project adheres to [Semantic Versioning](http://semver.org/).
 
+## Version 1.1.0 - 2023-08-01
+
+### Fixed
+
+- `UPDATE` with path expressions do not end up in a dump anymore. Instead, a proper error message is emitted.
+- `UPDATE` is only noop if it does not include an element annotated with `@cds.on.update`.
+- `SELECT` with `'*'` that is not expanded creates now a clearer error when the column name is required.
+- `SELECT` with plain SQL statements will return correct result regardless of casing.
+- View resolving for streams.
+
+## Version 1.0.1 - 2023-07-03
+
+### Fixed
+
+- Paths addressing a column of the query via `$self.<column>` in `group by` / `order by`, `having` or `where`
+  are now correctly substituted.
+- Mapping for OData `average` function to ANSI SQL compliant `avg` function.
+
 ## Version 1.0.0 - 2023-06-23
 
-- Initial Release
+- Initial Release

package/index.js

@@ -1,4 +1,18 @@
+const DatabaseService = require('./lib/common/DatabaseService')
+const SQLService = require('./lib/SQLService')
+const CQN2SQL = require('./lib/cqn2sql').classDefinition
+
+/**
+ * @template T
+ * @typedef {import('./lib/common/factory').Factory<T>} Factory
+ */
+
+/**
+ * @typedef {import('./lib/SQLService').prototype.PreparedStatement} PreparedStatement
+ */
+
 module.exports = {
-  DatabaseService: require('./lib/common/DatabaseService'),
-  SQLService: require('./lib/SQLService'),
+  DatabaseService,
+  SQLService,
+  CQN2SQL,
 }

package/lib/InsertResults.js

@@ -12,12 +12,16 @@ const USAGE_SAMPLE = async () => {
 }
 
 module.exports = class InsertResult {
+  /**
+   * @param {import('@sap/cds/apis/cqn').INSERT} query
+   * @param {unknown[]} results
+   */
   constructor(query, results) {
     this.query = query
     this.results = results
   }
 
-  /*
+  /**
    * Lazy access to auto-generated keys.
    */
   get [iterator]() {
@@ -70,8 +74,9 @@ module.exports = class InsertResult {
     })
   }
 
-  /*
+  /**
    * the number of inserted (root) entries or the number of affectedRows in case of INSERT into SELECT
+   * @return {number}
    */
   get affectedRows() {
     const { INSERT: _ } = this.query
@@ -79,16 +84,28 @@ module.exports = class InsertResult {
     else return (super.affectedRows = _.entries?.length || _.rows?.length || this.results.length || 1)
   }
 
-  /*
+  /**
    * for checks such as res > 2
+   * @return {number}
    */
   valueOf() {
     return this.affectedRows
   }
 
+  /**
+   * The last id of the auto incremented key column
+   * @param {unknown[]} result
+   * @returns {number}
+   */
   insertedRowId4(result) {
     return result.lastID
   }
+
+  /**
+   * Number of affected rows
+   * @param {unknown[]} result
+   * @returns {number}
+   */
   affectedRows4(result) {
     return result.changes
   }

package/lib/SQLService.js

@@ -4,6 +4,19 @@ const { resolveView } = require('@sap/cds/libx/_runtime/common/utils/resolveView
 const DatabaseService = require('./common/DatabaseService')
 const cqn4sql = require('./cqn4sql')
 
+/**
+ * @callback next
+ * @param {Error} param0
+ * @returns {Promise<unknown>}
+ */
+
+/**
+ * @callback Handler
+ * @param {import('@sap/cds/apis/services').Request} param0
+ * @param {next} param1
+ * @returns {Promise<unknown>}
+ */
+
 class SQLService extends DatabaseService {
   init() {
     this.on(['SELECT'], this.transformStreamFromCQN)
@@ -21,6 +34,7 @@ class SQLService extends DatabaseService {
     return super.init()
   }
 
+  /** @type {Handler} */
   async transformStreamFromCQN({ query }, next) {
     if (!query._streaming) return next()
     const cqn = STREAM.from(query.SELECT.from).column(query.SELECT.columns[0].ref[0])
@@ -29,6 +43,7 @@ class SQLService extends DatabaseService {
     return stream && { value: stream }
   }
 
+  /** @type {Handler} */
   async transformStreamIntoCQN({ query, data, target }, next) {
     let col, type, etag
     const elements = query._target?.elements || target?.elements
@@ -56,11 +71,11 @@ class SQLService extends DatabaseService {
     return result
   }
 
-  /** Handler for SELECT */
+  /**
+   * Handler for SELECT
+   * @type {Handler}
+   */
   async onSELECT({ query, data }) {
-    // REVISIT: disable this for queries like (SELECT 1)
-    // Will return multiple rows with objects inside
-    query.SELECT.expand = 'root'
     const { sql, values, cqn } = this.cqn2sql(query, data)
     let ps = await this.prepare(sql)
     let rows = await ps.all(values)
@@ -70,6 +85,10 @@ class SQLService extends DatabaseService {
     return cqn.SELECT.one || query.SELECT.from.ref?.[0].cardinality?.max === 1 ? rows[0] : rows
   }
 
+  /**
+   * Handler for INSERT
+   * @type {Handler}
+   */
   async onINSERT({ query, data }) {
     const { sql, entries, cqn } = this.cqn2sql(query, data)
     if (!sql) return // Do nothing when there is nothing to be done
@@ -78,6 +97,10 @@ class SQLService extends DatabaseService {
     return new this.class.InsertResults(cqn, results)
   }
 
+  /**
+   * Handler for UPSERT
+   * @type {Handler}
+   */
   async onUPSERT({ query, data }) {
     const { sql, entries } = this.cqn2sql(query, data)
     if (!sql) return // Do nothing when there is nothing to be done
@@ -86,13 +109,25 @@ class SQLService extends DatabaseService {
     return results.reduce((lastValue, currentValue) => (lastValue += currentValue.changes), 0)
   }
 
-  /** Handler for UPDATE */
+  /**
+   * Handler for UPDATE
+   * @type {Handler}
+   */
   async onUPDATE(req) {
-    if (!req.query.UPDATE.data && !req.query.UPDATE.with) return 0
+    // noop if not a touch for @cds.on.update
+    if (
+      !req.query.UPDATE.data &&
+      !req.query.UPDATE.with &&
+      !Object.values(req.target?.elements || {}).some(e => e['@cds.on.update'])
+    )
+      return 0
     return this.onSIMPLE(req)
   }
 
-  /** Handler for Stream */
+  /**
+   * Handler for Stream
+   * @type {Handler}
+   */
   async onSTREAM(req) {
     const { sql, values, entries } = this.cqn2sql(req.query)
     // writing stream
@@ -111,20 +146,29 @@ class SQLService extends DatabaseService {
     return Object.values(result[0])[0]
   }
 
-  /** Handler for CREATE, DROP, UPDATE, DELETE, with simple CQN */
+  /**
+   * Handler for CREATE, DROP, UPDATE, DELETE, with simple CQN
+   * @type {Handler}
+   */
   async onSIMPLE({ query, data }) {
     const { sql, values } = this.cqn2sql(query, data)
     let ps = await this.prepare(sql)
     return (await ps.run(values)).changes
   }
 
-  /** Handler for BEGIN, COMMIT, ROLLBACK, which don't have any CQN */
+  /**
+   * Handler for BEGIN, COMMIT, ROLLBACK, which don't have any CQN
+   * @type {Handler}
+   */
   async onEVENT({ event }) {
     DEBUG?.(event) // in the other cases above DEBUG happens in cqn2sql
     return await this.exec(event)
   }
 
-  /** Handler for SQL statements which don't have any CQN */
+  /**
+   * Handler for SQL statements which don't have any CQN
+   * @type {Handler}
+   */
   async onPlainSQL({ query, data }, next) {
     if (typeof query === 'string') {
       DEBUG?.(query)
@@ -135,12 +179,20 @@ class SQLService extends DatabaseService {
     } else return next()
   }
 
-  /** Override in subclasses to detect more statements to be called with ps.all() */
+  /**
+   *  Override in subclasses to detect more statements to be called with ps.all()
+   * @param {string} sql
+   */
   hasResults(sql) {
-    return /^(SELECT|WITH|CALL|PRAGMA table_info)/.test(sql)
+    return /^(SELECT|WITH|CALL|PRAGMA table_info)/i.test(sql)
   }
 
-  /** Derives and executes a query to fill in `$count` for given query */
+  /**
+   * Derives and executes a query to fill in `$count` for given query
+   * @param {import('@sap/cds/apis/cqn').SELECT} query - SELECT CQN
+   * @param {unknown[]} ret - Results of the original query
+   * @returns {Promise<number>}
+   */
   async count(query, ret) {
     if (ret) {
       const { one, limit: _ } = query.SELECT,
@@ -168,15 +220,29 @@ class SQLService extends DatabaseService {
    * Subclasses commonly override this.
    */
   static CQN2SQL = require('./cqn2sql').class
-  constructor() {
-    super(...arguments)
+
+  /** @param {unknown[]} args */
+  constructor(...args) {
+    super(...args)
+    /** @type {unknown} */
     this.class = new.target // for IntelliSense
   }
+
+  /**
+   * @param {import('@sap/cds/apis/cqn').Query} q
+   * @param {unknown} values
+   * @returns {typeof SQLService.CQN2SQL}
+   */
   cqn2sql(q, values) {
     const cqn = this.cqn4sql(q)
 
+    // REVISIT: disable this for queries like (SELECT 1)
+    // Will return multiple rows with objects inside
+    // Only enable expand when the query is inferred
+    if (cqn.SELECT && cqn.elements) cqn.SELECT.expand = cqn.SELECT.expand ?? 'root'
+
     const cmd = cqn.cmd || Object.keys(cqn)[0]
-    if (cmd in { INSERT: 1, DELETE: 1, UPSERT: 1, UPDATE: 1 }) {
+    if (cmd in { INSERT: 1, DELETE: 1, UPSERT: 1, UPDATE: 1 } || cqn.STREAM?.into) {
       let resolvedCqn = resolveView(cqn, this.model, this)
       if (resolvedCqn && resolvedCqn[cmd]._transitions?.[0].target) {
         resolvedCqn = resolvedCqn || cqn
@@ -186,6 +252,11 @@ class SQLService extends DatabaseService {
     }
     return new this.class.CQN2SQL(this.context).render(cqn, values)
   }
+
+  /**
+   * @param {import('@sap/cds/apis/cqn').Query} q
+   * @returns {import('./infer/cqn').Query}
+   */
   cqn4sql(q) {
     // REVISIT: move this check to cqn4sql?
     if (!q.SELECT?.from?.join && !this.model?.definitions[_target_name4(q)]) return _unquirked(q)
@@ -204,35 +275,47 @@ class SQLService extends DatabaseService {
 
   /**
    * Used to execute simple SQL statement like BEGIN, COMMIT, ROLLBACK
+   * @param {string} sql
+   * @returns {Promise<unknown>} The result of the query
    */
-  // eslint-disable-next-line no-unused-vars
   async exec(sql) {
+    sql
     throw '2b overridden by subclass'
   }
 }
 
-/** Interface of prepared statement objects as returned by {@link SQLService#prepare} */
+/**
+ * Interface of prepared statement objects as returned by {@link SQLService#prepare}
+ * @class
+ * @interface
+ */
 class PreparedStatement {
-  // eslint-disable-line no-unused-vars
   /**
    * Executes a prepared DML query, i.e., INSERT, UPDATE, DELETE, CREATE, DROP
-   * @param {[]|{}} binding_params
+   * @param {unknown|unknown[]} binding_params
    */
-  async run(/*binding_params*/) {} // eslint-disable-line no-unused-vars
+  async run(binding_params) {
+    binding_params
+    return 0
+  }
   /**
    * Executes a prepared SELECT query and returns a single/first row only
-   * @param {[]|{}} binding_params
+   * @param {unknown|unknown[]} binding_params
+   * @returns {Promise<unknown>}
    */
-  async get(/*binding_params*/) {
+  async get(binding_params) {
+    binding_params
     return {}
-  } // eslint-disable-line no-unused-vars
+  }
   /**
    * Executes a prepared SELECT query and returns an array of all rows
-   * @param {[]|{}} binding_params
+   * @param {unknown|unknown[]} binding_params
+   * @returns {Promise<unknown[]>}
    */
-  async all(/*binding_params*/) {
+  async all(binding_params) {
+    binding_params
     return [{}]
-  } // eslint-disable-line no-unused-vars
+  }
 }
 SQLService.prototype.PreparedStatement = PreparedStatement
 
@@ -285,4 +368,5 @@ cds.extend(cds.ql.Query).with(
   },
 )
 
-module.exports = Object.assign(SQLService, { _target_name4 })
+Object.assign(SQLService, { _target_name4 })
+module.exports = SQLService

package/lib/common/DatabaseService.js

@@ -8,22 +8,38 @@ function Pool(factory, tenant) {
 }
 const { createPool } = require('@sap/cds-foss').pool
 
+/** @typedef {unknown} DatabaseDriver */
+
 class DatabaseService extends cds.Service {
   /**
    * Return a pool factory + options property as expected by
    * https://github.com/coopernurse/node-pool#createpool.
+   * @abstract
+   * @type {import('./factory').Factory<DatabaseDriver>}
    */
   get factory() {
     throw '2b overriden in subclass'
   }
   pools = { _factory: this.factory }
 
+  /**
+   * @returns {boolean} whether this service is multi tenant enabled
+   */
   get isMultitenant() {
     return 'multiTenant' in this.options ? this.options.multiTenant : cds.env.requires.multitenancy
   }
 
   /**
-   * Set one or more session context variables like so:
+   * @typedef {Object} DefaultSessionVariables
+   * @property {string} '$user.id'
+   * @property {string} '$user.locale'
+   * @property {string} '$valid.from'
+   * @property {string} '$valid.to'
+   */
+
+  /**
+   * Set one or more session context variables
+   * @example
    * ```js
    * const tx = cds.db.tx()
    * tx.set({
@@ -31,16 +47,25 @@ class DatabaseService extends cds.Service {
    *   '$user.role': 'admin'
    * })
    * ```
+   * @param {unknown|DefaultSessionVariables} variables
    */
-  // eslint-disable-next-line no-unused-vars
   set(variables) {
+    variables
     throw '2b overridden by subclass'
   }
 
+  /**
+   * @param {import('@sap/cds/apis/cqn').Query} q
+   * @param {import('@sap/cds/apis/csn').CSN} m
+   * @returns {import('../infer/cqn').Query}
+   */
   infer(q, m = this.model) {
     return infer(q, m)
   }
 
+  /**
+   * @returns {Promise<DatabaseService>}
+   */
   async begin() {
     const ctx = this.context
     if (!ctx) return this.tx().begin()
@@ -49,6 +74,7 @@ class DatabaseService extends cds.Service {
     const connections = pool._trackedConnections
     let dbc
     try {
+      /** @type {DatabaseDriver} */
       dbc = this.dbc = await pool.acquire()
     } catch (err) {
       // TODO: add acquire timeout error check
@@ -57,6 +83,9 @@ class DatabaseService extends cds.Service {
     }
     this._beginStack = new Error('begin called from:')
     connections.push(this)
+    /**
+     * @param {DatabaseDriver} dbc
+     */
     this._release = async dbc => {
       await pool.release(dbc)
       connections.splice(connections.indexOf(this), 1)
@@ -108,6 +137,9 @@ class DatabaseService extends cds.Service {
   }
 
   // REVISIT: should happen automatically after a configurable time
+  /**
+   * @param {string} tenant
+   */
   async disconnect(tenant) {
     const pool = this.pools[tenant]
     if (pool) delete this.pools[tenant]
@@ -116,17 +148,36 @@ class DatabaseService extends cds.Service {
     await pool.clear()
   }
 
+  /**
+   * Runs a Query on the database service
+   * @param {import("@sap/cds/apis/cqn").Query} query
+   * @param {unknown} data
+   * @param  {...unknown} etc
+   * @returns {Promise<unknown>}
+   */
   run(query, data, ...etc) {
     // Allow db.run('...',1,2,3,4)
     if (data !== undefined && typeof query === 'string' && typeof data !== 'object') data = [data, ...etc]
     return super.run(query, data)
   }
 
-  url4(/*tenant*/) {
-    // eslint-disable-line no-unused-vars
+  /**
+   * Generated the database url for the given tenant
+   * @param {string} tenant
+   * @returns {string}
+   */
+  url4(tenant) {
+    tenant
     let { url } = this.options?.credentials || this.options || {}
     return url
   }
+
+  /**
+   * Old name of url4
+   * @deprecated
+   * @param {string} tenant
+   * @returns {string}
+   */
   getDbUrl(tenant) {
     return this.url4(tenant)
   } // REVISIT: Remove after cds v6.7

package/lib/common/factory.d.ts

@@ -0,0 +1,5 @@
+import { Factory as GenericFactory, Options } from 'generic-pool'
+
+export interface Factory<T> extends GenericFactory<T> {
+  options: Options
+}

package/lib/converters.d.ts

@@ -0,0 +1,24 @@
+declare function ConverterFunction(expression: string): string
+export type Converter = typeof ConverterFunction
+
+export type Converters = {
+  UUID: Converter
+  String: Converter
+  LargeString: Converter
+  Binary: Converter
+  LargeBinary: Converter
+  Boolean: Converter
+  Integer: Converter
+  UInt8: Converter
+  Int16: Converter
+  Int32: Converter
+  Int64: Converter
+  Float: Converter
+  Double: Converter
+  Decimal: Converter
+  DecimalFloat: Converter
+  Date: Converter
+  Time: Converter
+  DateTime: Converter
+  Timestamp: Converter
+}