@onlineapps/service-wrapper 3.0.6 → 3.0.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlineapps/service-wrapper",
-  "version": "3.0.6",
+  "version": "3.0.8",
   "description": "Thin orchestration layer for microservices - delegates all infrastructure concerns to specialized connectors",
   "main": "src/index.js",
   "scripts": {

package/src/OperationContext.js

@@ -1,5 +1,7 @@
 'use strict';
 
+const { ValidationError } = require('./ErrorMapper');
+
 /**
  * OperationContext — immutable per-invocation context passed to every
  * business handler by ServiceWrapper.invokeOperation().
@@ -29,12 +31,19 @@
  *     abortSignal     — AbortSignal
  *     config          — read-only service config snapshot
  *
+ * Prototype-level helpers (not fields, not frozen on the instance):
+ *   - normalizeDateRange(dateFrom, dateTo) → { from: Date, to: Date }
+ *       Promoted from property/v3 statements handler (W2-R-D3) so every biz
+ *       service can normalise `{dateFrom, dateTo}` query parameters the same
+ *       way. Fail-fast: throws ValidationError on null/undefined, non-string,
+ *       unparseable, or inverted range.
+ *
  * Design notes:
- *   - No getter helpers, no `.scoped()`, no methods. The handler destructures
- *     what it needs: `const { tenant_id, db, logger } = ctx;`.
  *   - `Object.freeze` prevents reassignment of top-level fields
  *     (`ctx.tenant_id = 99` throws in strict mode) but is shallow by design —
  *     `ctx.db.query(...)` and `ctx.logger.info(...)` must remain callable.
+ *     Prototype methods like `normalizeDateRange` live on the prototype and
+ *     are therefore unaffected by the instance freeze.
  *   - Lifecycle (release of db client, logger flush) is owned by ContextBuilder;
  *     see its `build()` return contract.
  */
@@ -54,6 +63,103 @@ class OperationContext {
     Object.assign(this, fields);
     Object.freeze(this);
   }
+
+  /**
+   * Normalise a `{dateFrom, dateTo}` pair into two JavaScript `Date` objects
+   * suitable for SQL range predicates (e.g. `BETWEEN :from AND :to`).
+   *
+   * Input rules:
+   *   - Bare ISO date `YYYY-MM-DD`:
+   *       from → 00:00:00.000 UTC of that day
+   *       to   → 23:59:59.999 UTC of that day
+   *   - ISO datetime (`YYYY-MM-DDTHH:MM[:SS[.sss]][Z|±HH:MM]`):
+   *       time is preserved as given (UTC-anchored by JS `Date` semantics).
+   *
+   * Fail-fast (throws {@link ValidationError}) if either argument is:
+   *   - null / undefined
+   *   - not a string
+   *   - unparseable as ISO date or datetime
+   *   and if the resulting `to` is earlier than `from`.
+   *
+   * @param {string} dateFrom - ISO date or datetime string.
+   * @param {string} dateTo   - ISO date or datetime string.
+   * @returns {{ from: Date, to: Date }}
+   * @throws {ValidationError}
+   */
+  normalizeDateRange(dateFrom, dateTo) {
+    const from = OperationContext._parseBoundary(dateFrom, 'dateFrom', 'start');
+    const to = OperationContext._parseBoundary(dateTo, 'dateTo', 'end');
+
+    if (to.getTime() < from.getTime()) {
+      throw new ValidationError({
+        message:
+          '[OperationContext.normalizeDateRange] dateTo is earlier than dateFrom - ' +
+          'Expected ISO date string (YYYY-MM-DD) or ISO datetime'
+      });
+    }
+
+    return { from, to };
+  }
+
+  /**
+   * @private
+   * @param {*}      value - candidate boundary
+   * @param {string} field - 'dateFrom' | 'dateTo' (used in error messages)
+   * @param {'start'|'end'} mode - defaults applied to bare-date inputs
+   * @returns {Date}
+   */
+  static _parseBoundary(value, field, mode) {
+    if (value === null || value === undefined) {
+      throw new ValidationError({
+        message:
+          `[OperationContext.normalizeDateRange] ${field} is null or undefined - ` +
+          'Expected ISO date string (YYYY-MM-DD) or ISO datetime'
+      });
+    }
+    if (typeof value !== 'string') {
+      throw new ValidationError({
+        message:
+          `[OperationContext.normalizeDateRange] ${field} is not a string - ` +
+          'Expected ISO date string (YYYY-MM-DD) or ISO datetime'
+      });
+    }
+
+    const trimmed = value.trim();
+    if (trimmed.length === 0) {
+      throw new ValidationError({
+        message:
+          `[OperationContext.normalizeDateRange] ${field} is empty - ` +
+          'Expected ISO date string (YYYY-MM-DD) or ISO datetime'
+      });
+    }
+
+    const isoDate = /^\d{4}-\d{2}-\d{2}$/;
+    const isoDateTime = /^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}(:\d{2})?(\.\d+)?(Z|[+-]\d{2}:?\d{2})?$/;
+
+    let d;
+    if (isoDate.test(trimmed)) {
+      const suffix = mode === 'end' ? 'T23:59:59.999Z' : 'T00:00:00.000Z';
+      d = new Date(`${trimmed}${suffix}`);
+    } else if (isoDateTime.test(trimmed)) {
+      d = new Date(trimmed);
+    } else {
+      throw new ValidationError({
+        message:
+          `[OperationContext.normalizeDateRange] ${field} is unparseable - ` +
+          'Expected ISO date string (YYYY-MM-DD) or ISO datetime'
+      });
+    }
+
+    if (isNaN(d.getTime())) {
+      throw new ValidationError({
+        message:
+          `[OperationContext.normalizeDateRange] ${field} is unparseable - ` +
+          'Expected ISO date string (YYYY-MM-DD) or ISO datetime'
+      });
+    }
+
+    return d;
+  }
 }
 
 module.exports = { OperationContext };