@cap-js/db-service 1.0.1 → 1.2.0

package/CHANGELOG.md

@@ -4,6 +4,34 @@
 - The format is based on [Keep a Changelog](http://keepachangelog.com/).
 - This project adheres to [Semantic Versioning](http://semver.org/).
 
+## Version 1.2.0 - 2023-09-06
+
+### Added
+
+- support for calculated elements on read. #113 #123
+- support for managed associations with default values. #193
+- introduced new operator `==` which translates to `IS NOT DISTINCT FROM`. #164
+
+### Fixed
+
+- resolved a type error which occured in some cases for deeply nested `expand`s. #173
+- path expression traversing non-foreign-key fields within infix filters are now properly rejected for `exists` predicates. #181
+- CQL functions: In the `args` of the `concat` function an `xpr` is now wrapped in parentheses. #196
+- Make `UPDATE` and `ofarray` typed column compatible. #184
+- Ensure that `INSERT` with `rows` always inserts into the correct column. #193
+- Allow `DateTime` columns to compare against their returned value. #206
+- Deep Insert using backlink associations as key #199.
+
+## 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
@@ -12,7 +40,6 @@
   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,17 @@ 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
+    // Storing query as non-enumerable property to avoid polluting trace output
+    Object.defineProperty(this, 'query', { value: query })
     this.results = results
   }
 
-  /*
+  /**
    * Lazy access to auto-generated keys.
    */
   get [iterator]() {
@@ -70,8 +75,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 +85,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,7 +4,21 @@ 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)
     this.on(['UPDATE'], this.transformStreamIntoCQN)
@@ -21,6 +35,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 +44,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,78 +72,107 @@ 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)
     if (rows.length)
       if (cqn.SELECT.expand) rows = rows.map(r => (typeof r._json_ === 'string' ? JSON.parse(r._json_) : r._json_ || r))
     if (cqn.SELECT.count) rows.$count = await this.count(query, rows)
-    return cqn.SELECT.one || query.SELECT.from.ref?.[0].cardinality?.max === 1 ? rows[0] : rows
+    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
+    if (!sql) return // Do nothing when there is nothing to be done // REVISIT: fix within mtxs
     const ps = await this.prepare(sql)
     const results = entries ? await Promise.all(entries.map(e => ps.run(e))) : await ps.run()
     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
+    if (!sql) return // Do nothing when there is nothing to be done // REVISIT: When does this happen?
     const ps = await this.prepare(sql)
     const results = entries ? await Promise.all(entries.map(e => ps.run(e))) : await ps.run()
-    return results.reduce((lastValue, currentValue) => (lastValue += currentValue.changes), 0)
+    // REVISIT: results isn't an array, when no entries -> how could that work? when do we have no entries?
+    return results.reduce((total, affectedRows) => (total += affectedRows.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)
+    const { one, sql, values } = this.cqn2sql(req.query)
     // writing stream
     if (req.query.STREAM.into) {
-      const stream = entries[0]
-      stream.on('error', () => stream.removeAllListeners('error'))
-      values.unshift(stream)
       const ps = await this.prepare(sql)
       return (await ps.run(values)).changes
     }
     // reading stream
     const ps = await this.prepare(sql)
-    let result = await ps.all(values)
-    if (result.length === 0) return
-
-    return Object.values(result[0])[0]
+    return ps.stream(values, one)
   }
 
-  /** 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)
+      // REVISIT: this is a hack the target of $now might not be a timestamp or date time
+      // Add input converter to CURRENT_TIMESTAMP inside views using $now
+      if(/^CREATE VIEW.* CURRENT_TIMESTAMP[( ]/is.test(query)) {
+        query = query.replace(/CURRENT_TIMESTAMP/gi, 'ISO(CURRENT_TIMESTAMP)')
+      }
+      DEBUG?.(query, data)
       const ps = await this.prepare(query)
       const exec = this.hasResults(query) ? d => ps.all(d) : d => ps.run(d)
       if (Array.isArray(data) && typeof data[0] === 'object') return await Promise.all(data.map(exec))
@@ -135,12 +180,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,
@@ -148,8 +201,9 @@ class SQLService extends DatabaseService {
       const [max, offset = 0] = one ? [1] : _ ? [_.rows?.val, _.offset?.val] : []
       if (max === undefined || (n < max && (n || !offset))) return n + offset
     }
+    // REVISIT: made uppercase count because of HANA reserved word quoting
     const cq = cds.ql.clone(query, {
-      columns: [{ func: 'count' }],
+      columns: [{ func: 'count', as: 'COUNT' }],
       localized: false,
       expand: false,
       limit: 0,
@@ -157,10 +211,14 @@ class SQLService extends DatabaseService {
     })
     const { sql, values } = this.cqn2sql(cq)
     const ps = await this.prepare(sql)
-    const { count } = await ps.get(values)
-    return count
+    const { count, COUNT } = await ps.get(values)
+    return count ?? COUNT
   }
 
+  /**
+   * Helper class for results of INSERTs.
+   * Subclasses may override this.
+   */
   static InsertResults = require('./InsertResults')
 
   /**
@@ -168,71 +226,110 @@ 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
   }
-  cqn2sql(q, values) {
-    const cqn = this.cqn4sql(q)
-
-    const cmd = cqn.cmd || Object.keys(cqn)[0]
-    if (cmd in { INSERT: 1, DELETE: 1, UPSERT: 1, UPDATE: 1 }) {
-      let resolvedCqn = resolveView(cqn, this.model, this)
-      if (resolvedCqn && resolvedCqn[cmd]._transitions?.[0].target) {
-        resolvedCqn = resolvedCqn || cqn
-        resolvedCqn.target = resolvedCqn?.[cmd]._transitions[0].target || cqn.target
-      }
-      return new this.class.CQN2SQL(this.context).render(resolvedCqn, values)
+
+  /**
+   * @param {import('@sap/cds/apis/cqn').Query} query
+   * @param {unknown} values
+   * @returns {typeof SQLService.CQN2SQL}
+   */
+  cqn2sql(query, values) {
+    let q = this.cqn4sql(query)
+    if (q.SELECT && q.elements) q.SELECT.expand = q.SELECT.expand ?? 'root'
+
+    let cmd = q.cmd || Object.keys(q)[0]
+    if (cmd in { INSERT: 1, DELETE: 1, UPSERT: 1, UPDATE: 1 } || q.STREAM?.into) {
+      q = resolveView(q, this.model, this) // REVISIT: before resolveView was called on flat cqn obtained from cqn4sql -> is it correct to call on original q instead?
+      let target = q[cmd]._transitions?.[0].target
+      if (target) q.target = target // REVISIT: Why isn't that done in resolveView?
     }
-    return new this.class.CQN2SQL(this.context).render(cqn, values)
+    let cqn2sql = new this.class.CQN2SQL(this)
+    return cqn2sql.render(q, 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)
+    if (!q.SELECT?.from?.join && !q.SELECT?.from?.SELECT && !this.model?.definitions[_target_name4(q)]) return _unquirked(q)
     return cqn4sql(q, this.model)
   }
 
   /**
    * Returns a Promise which resolves to a prepared statement object with
    * `{run,get,all}` signature as specified in {@link PreparedStatement}.
+   * @abstract
+   * @param {string} sql The SQL String to be prepared
    * @returns {PreparedStatement}
    */
-  // eslint-disable-next-line no-unused-vars
-  async prepare(/*sql*/) {
+  async prepare(sql) {
+    sql
     throw '2b overridden by subclass'
   }
 
   /**
    * 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
+   * @abstract
+   * @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
+   * @abstract
+   * @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
+   * @abstract
+   * @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
+  }
+  /**
+   * Executes a prepared SELECT query and returns a stream of the result
+   * @abstract
+   * @param {unknown|unknown[]} binding_params
+   * @returns {ReadableStream<string|Buffer>} A stream of the result
+   */
+  async stream(binding_params) {
+    binding_params
+  }
 }
 SQLService.prototype.PreparedStatement = PreparedStatement
 
@@ -246,29 +343,26 @@ const _target_name4 = q => {
     q.CREATE?.entity ||
     q.DROP?.entity ||
     q.STREAM?.from ||
-    q.STREAM?.into ||
-    undefined
-  if (target?.SET?.op === 'union') throw new cds.error('”UNION” based queries are not supported')
+    q.STREAM?.into
+  if (target?.SET?.op === 'union') throw new cds.error('UNION-based queries are not supported')
   if (!target?.ref) return target
   const [first] = target.ref
   return first.id || first
 }
 
 const _unquirked = q => {
-  if (typeof q.INSERT?.into === 'string') q.INSERT.into = { ref: [q.INSERT.into] }
-  if (typeof q.UPSERT?.into === 'string') q.UPSERT.into = { ref: [q.UPSERT.into] }
-  if (typeof q.UPDATE?.entity === 'string') q.UPDATE.entity = { ref: [q.UPDATE.entity] }
-  if (typeof q.DELETE?.from === 'string') q.DELETE.from = { ref: [q.DELETE.from] }
-  if (typeof q.CREATE?.entity === 'string') q.CREATE.entity = { ref: [q.CREATE.entity] }
-  if (typeof q.DROP?.entity === 'string') q.DROP.entity = { ref: [q.DROP.entity] }
+  if (!q) return q
+  else if (typeof q.SELECT?.from === 'string') q.SELECT.from = { ref: [q.SELECT.from] }
+  else if (typeof q.INSERT?.into === 'string') q.INSERT.into = { ref: [q.INSERT.into] }
+  else if (typeof q.UPSERT?.into === 'string') q.UPSERT.into = { ref: [q.UPSERT.into] }
+  else if (typeof q.UPDATE?.entity === 'string') q.UPDATE.entity = { ref: [q.UPDATE.entity] }
+  else if (typeof q.DELETE?.from === 'string') q.DELETE.from = { ref: [q.DELETE.from] }
+  else if (typeof q.CREATE?.entity === 'string') q.CREATE.entity = { ref: [q.CREATE.entity] }
+  else if (typeof q.DROP?.entity === 'string') q.DROP.entity = { ref: [q.DROP.entity] }
   return q
 }
 
-const sqls = new (class extends SQLService {
-  get factory() {
-    return null
-  }
-})()
+const sqls = new class extends SQLService { get factory() { return null } }
 cds.extend(cds.ql.Query).with(
   class {
     forSQL() {
@@ -276,6 +370,7 @@ cds.extend(cds.ql.Query).with(
       return this.flat(cqn)
     }
     toSQL() {
+      if (this.SELECT) this.SELECT.expand = 'root' // Enforces using json functions always for top-level SELECTS
       let { sql, values } = (cds.db || sqls).cqn2sql(this)
       return { sql, values } // skipping .cqn property
     }
@@ -285,4 +380,5 @@ cds.extend(cds.ql.Query).with(
   },
 )
 
-module.exports = Object.assign(SQLService, { _target_name4 })
+Object.assign(SQLService, { _target_name4 })
+module.exports = SQLService