@cap-js/db-service 1.0.1 → 1.2.0

package/lib/common/DatabaseService.js

@@ -1,143 +1,148 @@
+const SessionContext = require('./session-context')
+const ConnectionPool = require('./generic-pool')
 const infer = require('../infer')
-const cds = require('@sap/cds')
+const cds = require('@sap/cds/lib')
 
-function Pool(factory, tenant) {
-  const pool = createPool({ __proto__: factory, create: factory.create.bind(undefined, tenant) }, factory.options)
-  pool._trackedConnections = []
-  return pool
-}
-const { createPool } = require('@sap/cds-foss').pool
+/** @typedef {unknown} DatabaseDriver */
 
 class DatabaseService extends cds.Service {
+  /**
+   * Dictionary of connection pools per tenant
+   */
+  pools = { _factory: this.factory }
+
   /**
    * 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 }
-
-  get isMultitenant() {
-    return 'multiTenant' in this.options ? this.options.multiTenant : cds.env.requires.multitenancy
-  }
 
   /**
    * Set one or more session context variables like so:
-   * ```js
-   * const tx = cds.db.tx()
-   * tx.set({
-   *   '$user.name': 'Alice',
-   *   '$user.role': 'admin'
-   * })
-   * ```
+   *
+   *     const tx = cds.db.tx()
+   *     tx.set({ foo: 'bar' })
+   *
+   * This is used in this.begin() for standard properties
+   * like `$user.id` or `$user.locale`.
    */
   // eslint-disable-next-line no-unused-vars
   set(variables) {
     throw '2b overridden by subclass'
   }
 
-  infer(q, m = this.model) {
-    return infer(q, m)
-  }
-
+  /**
+   * Acquires a pooled connection and starts a session, including setting
+   * session context like `$user.id` or `$user.locale`, and starting a
+   * transaction with `BEGIN`
+   * @returns this
+   */
   async begin() {
+    // We expect tx.begin() being called for an txed db service
     const ctx = this.context
-    if (!ctx) return this.tx().begin()
-    const tenant = this.isMultitenant && ctx.tenant
-    const pool = (this.pools[tenant] ??= new Pool(this.pools._factory, tenant))
-    const connections = pool._trackedConnections
-    let dbc
-    try {
-      dbc = this.dbc = await pool.acquire()
-    } catch (err) {
-      // TODO: add acquire timeout error check
-      err.stack += `\nActive connections:${connections.length}\n${connections.map(c => c._beginStack.stack).join('\n')}`
-      throw err
-    }
-    this._beginStack = new Error('begin called from:')
-    connections.push(this)
-    this._release = async dbc => {
-      await pool.release(dbc)
-      connections.splice(connections.indexOf(this), 1)
-    }
+    if (!ctx) return this.tx().begin() // REVISIT: Is this correct? When does this happen?
+
+    // REVISIT: tenant should be undefined if !this.isMultitenant
+    let isMultitenant = 'multiTenant' in this.options ? this.options.multiTenant : cds.env.requires.multitenancy
+    let tenant = isMultitenant && ctx.tenant
+
+    // Setting this.pool as used in this.acquire() and this.release()
+    this.pool = this.pools[tenant] ??= new ConnectionPool(this.pools._factory, tenant)
+
+    // Acquire a pooled connection
+    this.dbc = await this.acquire()
+
+    // Begin a session...
     try {
-      // Setting session context variables
-      await this.set({
-        get '$user.id'() {
-          return _set(this, '$user.id', ctx.user?.id || 'anonymous')
-        },
-        get '$user.locale'() {
-          return _set(this, '$user.locale', ctx.locale || cds.env.i18n.default_language)
-        },
-        get '$valid.from'() {
-          return _set(this, '$valid.from', ctx._?.['VALID-FROM'] ?? ctx._?.['VALID-AT'] ?? '1970-01-01T00:00:00.000Z')
-        },
-        get '$valid.to'() {
-          return _set(
-            this,
-            '$valid.to',
-            ctx._?.['VALID-TO'] ?? _validTo4(ctx._?.['VALID-AT']) ?? '9999-11-11T22:22:22.000Z',
-          )
-        },
-      })
-      // Run BEGIN
+      await this.set(new SessionContext(ctx))
       await this.send('BEGIN')
     } catch (e) {
-      this._release(dbc)
+      this.release()
       throw e
     }
     return this
   }
 
+  /**
+   * Commits a transaction and releases the connection to the pool.
+   */
   async commit() {
-    const dbc = this.dbc
-    if (!dbc) return
+    if (!this.dbc) return
     await this.send('COMMIT')
-    this._release(dbc) // only release on successful commit as otherwise released on rollback
+    this.release() // only release on successful commit as otherwise released on rollback
   }
 
+  /**
+   * Rolls back a transaction and releases the connection to the pool.
+   */
   async rollback() {
-    const dbc = this.dbc
-    if (!dbc) return
-    try {
-      await this.send('ROLLBACK')
-    } finally {
-      this._release(dbc)
-    }
+    if (!this.dbc) return
+    else
+      try {
+        await this.send('ROLLBACK')
+      } finally {
+        this.release()
+      }
+  }
+
+  /**
+   * Acquires a connection from this.pool, stored into this.dbc
+   * This is for subclasses to intercept, if required.
+   */
+  async acquire() {
+    return await this.pool.acquire()
+  }
+
+  /**
+   * Releases own connection, i.e. tix.dbc, from this.pool
+   * This is for subclasses to intercept, if required.
+   */
+  async release() {
+    return this.pool.release(this.dbc)
   }
 
   // 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]
-    else return
+    if (!pool) return
     await pool.drain()
     await pool.clear()
+    delete this.pools[tenant]
   }
 
+  /**
+   * Infers the given query with this DatabaseService instance's model.
+   * In general `this.model` is the same then `cds.model`
+   * @param {CQN} query - the query to infer
+   * @returns {CQN} the inferred query
+   */
+  infer(query) {
+    return infer(query, this.model)
+  }
+
+  /**
+   * DatabaseServices also support passing native query strings to underlying databases.
+   */
   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)
   }
 
+  /**
+   * @returns {string} A url-like string used to print log output,
+   * e.g., in cds.deploy()
+   */
   url4(/*tenant*/) {
-    // eslint-disable-line no-unused-vars
-    let { url } = this.options?.credentials || this.options || {}
-    return url
+    return this.options.credentials?.url || this.options.url
   }
-  getDbUrl(tenant) {
-    return this.url4(tenant)
-  } // REVISIT: Remove after cds v6.7
-}
-
-const _set = (context, variable, value) => {
-  Object.defineProperty(context, variable, { value, configurable: true })
-  return value
-}
-const _validTo4 = validAt => {
-  return validAt?.replace(/(\dZ?)$/, d => parseInt(d[0]) + 1 + d[1] || '')
 }
 
 DatabaseService.prototype.isDatabaseService = true

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/common/generic-pool.js

@@ -0,0 +1,34 @@
+const { createPool } = require('@sap/cds-foss').pool
+
+class ConnectionPool {
+  constructor(factory, tenant) {
+    let bound_factory = { __proto__: factory, create: factory.create.bind(null, tenant) }
+    return _track_connections4(createPool(bound_factory, factory.options))
+  }
+}
+
+// REVISIT: Is that really neccessary ?!
+function _track_connections4(pool) {
+  const { acquire, release } = pool
+  return Object.assign(pool, {
+    async acquire() {
+      const connections = (this._trackedConnections ??= new Set())
+      try {
+        let dbc = await acquire.call(this)
+        connections.add((dbc._beginStack = new Error('begin called from:')))
+        return dbc
+      } catch (err) {
+        // TODO: add acquire timeout error check
+        err.stack += `\nActive connections:${connections.size}\n${[...connections].map(e => e.stack).join('\n')}`
+        throw err
+      }
+    },
+
+    release(dbc) {
+      this._trackedConnections?.delete(dbc._beginStack)
+      return release.call(this, dbc)
+    },
+  })
+}
+
+module.exports = ConnectionPool

package/lib/common/session-context.js

@@ -0,0 +1,32 @@
+const cds = require('@sap/cds/lib')
+
+class SessionContext {
+  constructor(ctx) {
+    Object.defineProperty(this, 'ctx', { value: ctx })
+  }
+  get '$user.id'() {
+    return (super['$user.id'] = this.ctx.user?.id || 'anonymous')
+  }
+  get '$user.locale'() {
+    return (super['$user.locale'] = this.ctx.locale || cds.env.i18n.default_language)
+  }
+  // REVISIT: should be decided in spec meeting for definitive name
+  get $now() {
+    return (super.$now = (this.ctx.timestamp || new Date()).toISOString())
+  }
+}
+
+class TemporalSessionContext extends SessionContext {
+  get '$valid.from'() {
+    return (super['$valid.from'] = this.ctx._?.['VALID-FROM'] ?? this.ctx._?.['VALID-AT'] ?? new Date().toISOString())
+  }
+  get '$valid.to'() {
+    return (super['$valid.to'] =
+      this.ctx._?.['VALID-TO'] ??
+      this.ctx._?.['VALID-AT']?.replace(/(\dZ?)$/, d => parseInt(d[0]) + 1 + d[1] || '') ??
+      new Date().toISOString().replace(/(\dZ?)$/, d => parseInt(d[0]) + 1 + d[1] || ''))
+  }
+}
+
+// REVISIT: only set temporal context if required!
+module.exports = TemporalSessionContext

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
+}

package/lib/cql-functions.js

@@ -2,49 +2,202 @@ const StandardFunctions = {
   // OData: https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part2-url-conventions.html#sec_CanonicalFunctions
 
   // String and Collection Functions
-  // length     : (x) => `length(${x})`,
+  /**
+   * Generates SQL statement that produces the length of a given string
+   * @param {string} x
+   * @returns {string}
+   */
+  length: x => `length(${x})`,
+  /**
+   * Generates SQL statement that produces the average of a given expression
+   * @param {string} x
+   * @returns {string}
+   */
   average: x => `avg(${x})`,
+  /**
+   * Generates SQL statement that produces a boolean value indicating whether the search term is contained in the given columns
+   * @param {string} ref
+   * @param {string} arg
+   * @returns {string}
+   */
   search: function (ref, arg) {
     if (!('val' in arg)) throw `SQLite only supports single value arguments for $search`
     const refs = ref.list || [ref],
       { toString } = ref
     return '(' + refs.map(ref2 => this.contains(this.tolower(toString(ref2)), this.tolower(arg))).join(' or ') + ')'
   },
-  concat: (...args) => args.join('||'),
+  /**
+   * Generates SQL statement that produces a string with all provided strings concatenated
+   * @param  {...string} args
+   * @returns {string}
+   */
+  concat: (...args) => args.map(a => a.xpr ? `(${a})` : a).join(' || '),
+
+  /**
+   * Generates SQL statement that produces a boolean value indicating whether the first string contains the second string
+   * @param  {...string} args
+   * @returns {string}
+   */
   contains: (...args) => `ifnull(instr(${args}),0)`,
+  /**
+   * Generates SQL statement that produces the number of elements in a given collection
+   * @param {string} x
+   * @returns {string}
+   */
   count: x => `count(${x || '*'})`,
+  /**
+   * Generates SQL statement that produces the number of distinct values of a given expression
+   * @param {string} x
+   * @returns {string}
+   */
   countdistinct: x => `count(distinct ${x || '*'})`,
+  /**
+   * Generates SQL statement that produces the index of the first occurrence of the second string in the first string
+   * @param {string} x
+   * @param {string} y
+   * @returns {string}
+   */
   indexof: (x, y) => `instr(${x},${y}) - 1`, // sqlite instr is 1 indexed
+  /**
+   * Generates SQL statement that produces a boolean value indicating whether the first string starts with the second string
+   * @param {string} x
+   * @param {string} y
+   * @returns {string}
+   */
   startswith: (x, y) => `instr(${x},${y}) = 1`, // sqlite instr is 1 indexed
   // takes the end of the string of the size of the target and compares it with the target
+  /**
+   * Generates SQL statement that produces a boolean value indicating whether the first string ends with the second string
+   * @param {string} x
+   * @param {string} y
+   * @returns {string}
+   */
   endswith: (x, y) => `substr(${x}, length(${x}) + 1 - length(${y})) = ${y}`,
+  /**
+   * Generates SQL statement that produces the substring of a given string
+   * @example
+   * // returns 'bc'
+   * {func:'substring',args:[{val:'abc'},{val:1}]}
+   * @example
+   * // returns 'b'
+   * {func:'substring',args:[{val:'abc'},{val:1},{val:1}]}
+   * @param {string} x
+   * @param {string} y
+   * @param {string} z
+   * @returns {string}
+   */
   substring: (x, y, z) =>
     z
       ? `substr( ${x}, case when ${y} < 0 then length(${x}) + ${y} + 1 else ${y} + 1 end, ${z} )`
       : `substr( ${x}, case when ${y} < 0 then length(${x}) + ${y} + 1 else ${y} + 1 end )`,
 
   // String Functions
+  /**
+   * Generates SQL statement that matches the given string against a regular expression
+   * @param {string} x
+   * @param {string} y
+   * @returns {string}
+   */
   matchesPattern: (x, y) => `${x} regexp ${y})`,
+  /**
+   * Generates SQL statement that produces the lower case value of a given string
+   * @param {string} x
+   * @returns {string}
+   */
   tolower: x => `lower(${x})`,
+  /**
+   * Generates SQL statement that produces the upper case value of a given string
+   * @param {string} x
+   * @returns {string}
+   */
   toupper: x => `upper(${x})`,
-  // trim           : (x) => `trim(${x})`,
+  /**
+   * Generates SQL statement that produces the trimmed value of a given string
+   * @param {string} x
+   * @returns {string}
+   */
+  trim: x => `trim(${x})`,
 
   // Arithmetic Functions
+  /**
+   * Generates SQL statement that produces the rounded up value of a given number
+   * @param {string} x
+   * @returns {string}
+   */
   ceiling: x => `ceil(${x})`,
-  // floor    : (x) => `floor(${x})`,
-  // round    : (x) => `round(${x})`,
+  /**
+   * Generates SQL statement that produces the rounded down value of a given number
+   * @param {string} x
+   * @returns {string}
+   */
+  floor: x => `floor(${x})`,
+  /**
+   * Generates SQL statement that produces the rounded value of a given number
+   * @param {string} x
+   * @param {string} p precision
+   * @returns {string}
+   */
+  round: (x, p) => `round(${x}${p ? `,${p}` : ''})`,
 
   // Date and Time Functions
+
+  current_date: p => p ? `current_date(${p})`: 'current_date',
+  current_time: p => p ? `current_time(${p})`: 'current_time',
+  current_timestamp: p => p ? `current_timestamp(${p})`: 'current_timestamp',
+
+  /**
+   * Generates SQL statement that produces the year of a given timestamp
+   * @param {string} x
+   * @returns {string}
+   */
   year: x => `cast( strftime('%Y',${x}) as Integer )`,
+  /**
+   * Generates SQL statement that produces the month of a given timestamp
+   * @param {string} x
+   * @returns {string}
+   */
   month: x => `cast( strftime('%m',${x}) as Integer )`,
+  /**
+   * Generates SQL statement that produces the day of a given timestamp
+   * @param {string} x
+   * @returns {string}
+   */
   day: x => `cast( strftime('%d',${x}) as Integer )`,
+  /**
+   * Generates SQL statement that produces the hours of a given timestamp
+   * @param {string} x
+   * @returns {string}
+   */
   hour: x => `cast( strftime('%H',${x}) as Integer )`,
+  /**
+   * Generates SQL statement that produces the minutes of a given timestamp
+   * @param {string} x
+   * @returns {string}
+   */
   minute: x => `cast( strftime('%M',${x}) as Integer )`,
+  /**
+   * Generates SQL statement that produces the seconds of a given timestamp
+   * @param {string} x
+   * @returns {string}
+   */
   second: x => `cast( strftime('%S',${x}) as Integer )`,
 
+  /**
+   * Generates SQL statement that produces the fractional seconds of a given timestamp
+   * @param {string} x
+   * @returns {string}
+   */
   fractionalseconds: x => `cast( strftime('%f0000',${x}) as Integer )`,
 
+  /**
+   * maximum date time value
+   * @returns {string}
+   */
   maxdatetime: () => '9999-12-31 23:59:59.999',
+  /**
+   * minimum date time value
+   * @returns {string}
+   */
   mindatetime: () => '0001-01-01 00:00:00.000',
 
   // odata spec defines the date time offset type as a normal ISO time stamp
@@ -52,6 +205,11 @@ const StandardFunctions = {
   // sqlite understands this so by splitting the timezone from the actual date
   // prefixing it with 1970 it allows sqlite to give back the number of seconds
   // which can be divided by 60 back to minutes
+  /**
+   * Generates SQL statement that produces the offset in minutes of a given date time offset string
+   * @param {string} x
+   * @returns {string}
+   */
   totaloffsetminutes: x => `case
     when substr(${x}, length(${x})) = 'z' then 0
     else strftime('%s', '1970-01-01T00:00:00' || substr(${x}, length(${x}) - 5)) / 60
@@ -65,6 +223,11 @@ const StandardFunctions = {
   // the number of seconds in a day
   // As sqlite is most accurate with juliandays it is better to do then then using actual second function
   // while the odata specification states that the seconds has to be fractional which only julianday allows
+  /**
+   * Generates SQL statement that produces an OData compliant duration string like: P12DT23H59M59.999999999999S
+   * @param {string} x
+   * @returns {string}
+   */
   totalseconds: x => `(
     (
       (
@@ -84,18 +247,43 @@ const StandardFunctions = {
       )
     ) * 86400
   )`,
+
+  /**
+   * Generates SQL statement that calls the session_context function with the given parameter
+   * @param {string} x session variable name or SQL expression
+   * @returns {string}
+   */
+  session_context: x => `session_context('${x.val}')`,
 }
 
 const HANAFunctions = {
   // https://help.sap.com/docs/SAP_HANA_PLATFORM/4fe29514fd584807ac9f2a04f6754767/f12b86a6284c4aeeb449e57eb5dd3ebd.html
 
   // Time functions
+  /**
+   * Generates SQL statement that calculates the difference in 100nanoseconds between two timestamps
+   * @param {string} x left timestamp
+   * @param {string} y right timestamp
+   * @returns {string}
+   */
   nano100_between: (x, y) => `(julianday(${y}) - julianday(${x})) * 864000000000`,
+  /**
+   * Generates SQL statement that calculates the difference in seconds between two timestamps
+   * @param {string} x left timestamp
+   * @param {string} y right timestamp
+   * @returns {string}
+   */
   seconds_between: (x, y) => `(julianday(${y}) - julianday(${x})) * 86400`,
   // Calculates the difference in full days using julian day
   // Using the exact time of the day to determine whether 24 hours have passed or not to add the final day
   // When just comparing the julianday values with each other there are leap seconds included
   // Which on the day resolution are included as the individual days therefor ignoring them to match HANA
+  /**
+   * Generates SQL statement that calculates the difference in days between two timestamps
+   * @param {string} x left timestamp
+   * @param {string} y right timestamp
+   * @returns {string}
+   */
   days_between: (x, y) => `(
     cast ( julianday(${y}) as Integer ) - cast ( julianday(${x}) as Integer )
   ) + (
@@ -122,6 +310,12 @@ const HANAFunctions = {
 
   Also check whether the result will be positive or negative to make sure to not subtract an extra month
   */
+  /**
+   * Generates SQL statement that calculates the difference in months between two timestamps
+   * @param {string} x left timestamp
+   * @param {string} y right timestamp
+   * @returns {string}
+   */
   months_between: (x, y) => `
   (
     (
@@ -139,6 +333,12 @@ const HANAFunctions = {
       )
     )
   )`,
+  /**
+   * Generates SQL statement that calculates the difference in years between two timestamps
+   * @param {string} x left timestamp
+   * @param {string} y right timestamp
+   * @returns {string}
+   */
   years_between(x, y) {
     return `floor(${this.months_between(x, y)} / 12)`
   },