typeorm-extensions 2.1.0 → 2.2.0-rc.1

package/dist/utils/time-zone.utils.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readInTimeZone = exports.assertTimeZone = void 0;
+const DAY_MS = 24 * 60 * 60 * 1000;
+const MAX_CACHED_FORMATTERS = 500;
+const DATE_TIME = /^(\d{4})-(\d{2})-(\d{2})(?:[T ](\d{2}):(\d{2})(?::(\d{2})(?:\.(\d{1,9}))?)?(Z|[+-]\d{2}(?::?\d{2})?)?)?$/i;
+const OFFSET = /^([+-])(\d{2}):?(\d{2})?$/;
+const formatters = new Map();
+function getFormatter(timeZone) {
+    let formatter = formatters.get(timeZone);
+    if (formatter === undefined) {
+        try {
+            formatter = new Intl.DateTimeFormat('en-US', {
+                timeZone,
+                hour12: false,
+                era: 'short',
+                year: 'numeric',
+                month: 'numeric',
+                day: 'numeric',
+                hour: 'numeric',
+                minute: 'numeric',
+                second: 'numeric',
+            });
+        }
+        catch {
+            throw new TypeError(`Invalid timeZone "${timeZone}": not an IANA time zone`);
+        }
+        // the keys are caller input: Intl accepts any letter case of a zone name
+        if (formatters.size >= MAX_CACHED_FORMATTERS) {
+            formatters.clear();
+        }
+        formatters.set(timeZone, formatter);
+    }
+    return formatter;
+}
+/** The wall clock of an instant in a time zone, as milliseconds of the same wall clock in UTC. */
+function getWallClock(instant, timeZone) {
+    const parts = {};
+    for (const { type, value } of getFormatter(timeZone).formatToParts(new Date(instant))) {
+        parts[type] = value;
+    }
+    const year = parts.era === 'BC' ? 1 - Number(parts.year) : Number(parts.year);
+    const wallClock = new Date(0);
+    // some ICU versions write midnight as 24 with hour12: false
+    wallClock.setUTCFullYear(year, Number(parts.month) - 1, Number(parts.day));
+    wallClock.setUTCHours(Number(parts.hour) % 24, Number(parts.minute), Number(parts.second), 0);
+    return wallClock.getTime() + (((instant % 1000) + 1000) % 1000);
+}
+/**
+ * The instant at which the wall clock of a time zone shows `wallClock` (milliseconds of that wall clock in
+ * UTC). Like PostgreSQL: a time skipped by a forward transition takes the offset before it, and a time that
+ * occurs twice is read with the offset after the transition, the later of the two instants.
+ */
+function wallClockToInstant(wallClock, timeZone) {
+    const offsets = new Set([wallClock - DAY_MS, wallClock, wallClock + DAY_MS].map((instant) => getWallClock(instant, timeZone) - instant));
+    const candidates = [...offsets].map((offset) => wallClock - offset);
+    const matching = candidates.filter((instant) => getWallClock(instant, timeZone) === wallClock);
+    return Math.max(...(matching.length > 0 ? matching : candidates));
+}
+/** Throws a `TypeError` for a time zone the runtime doesn't know. */
+function assertTimeZone(timeZone) {
+    getFormatter(timeZone);
+}
+exports.assertTimeZone = assertTimeZone;
+/**
+ * Reads a date (`'2024-01-31'`, its midnight) or a date-time without an offset (`'2024-01-31 10:00'`) as
+ * the wall clock of `timeZone`, and returns that instant. A date-time with an offset (`Z`, `+02:00`) is an
+ * instant already: it is returned as that `Date`. Any other string throws a `TypeError` naming `name`.
+ */
+function readInTimeZone(value, timeZone, name) {
+    const match = DATE_TIME.exec(value);
+    if (match === null) {
+        throw new TypeError(`Invalid ${name} "${value}": with timeZone, expected a Date, a date (YYYY-MM-DD) or a date-time ` +
+            '(YYYY-MM-DD HH:mm[:ss[.sss]]) with or without an offset');
+    }
+    const [, year, month, day, hour = '0', minute = '0', second = '0', fraction = '', offset] = match;
+    const wallClock = new Date(0);
+    wallClock.setUTCFullYear(Number(year), Number(month) - 1, Number(day));
+    // a Date keeps milliseconds: finer fractions are dropped
+    wallClock.setUTCHours(Number(hour), Number(minute), Number(second), Number(fraction.padEnd(3, '0').slice(0, 3)));
+    const roundTrip = wallClock.toISOString();
+    const expected = `${year}-${month}-${day}T${hour.padStart(2, '0')}:${minute.padStart(2, '0')}:${second.padStart(2, '0')}`;
+    if (isNaN(wallClock.getTime()) || roundTrip.slice(0, 19) !== expected) {
+        throw new TypeError(`Invalid ${name} "${value}": not a calendar date and time`);
+    }
+    if (offset === undefined) {
+        return new Date(wallClockToInstant(wallClock.getTime(), timeZone));
+    }
+    // an offset makes it an instant already; as text the databases would read it each their own way
+    return new Date(wallClock.getTime() - getOffsetMinutes(offset, value, name) * 60000);
+}
+exports.readInTimeZone = readInTimeZone;
+function getOffsetMinutes(offset, value, name) {
+    if (offset.toUpperCase() === 'Z') {
+        return 0;
+    }
+    const [, sign, hours, minutes = '00'] = OFFSET.exec(offset);
+    if (Number(hours) > 23 || Number(minutes) > 59) {
+        throw new TypeError(`Invalid ${name} "${value}": not a UTC offset`);
+    }
+    return (sign === '-' ? -1 : 1) * (Number(hours) * 60 + Number(minutes));
+}

package/dist/utils/where.utils.d.ts

@@ -1,5 +1,5 @@
 import type { ObjectLiteral, WhereExpressionBuilder } from 'typeorm';
-import type { WhereMethods } from '../types/extensions/where.types';
+import type { HavingMethods, WhereMethods } from '../types/extensions/where.types';
 export declare function getValuePlaceholder<T>(value: T, paramName?: string): string;
 /**
  * Whether `params` is a `{ name: value }` params object (a plain object or a class instance such
@@ -12,7 +12,7 @@ export declare function isParamsObject(params: unknown): params is Record<string
  * so `::type` casts and colons inside literals don't count unless they name a `params` key.
  */
 export declare function hasParamPlaceholder(conditions: string, params?: unknown): boolean;
-export declare function attachWhere<QB extends WhereExpressionBuilder>(builder: QB, method: WhereMethods, field: string, conditions: string, params?: unknown, options?: {
+export declare function attachWhere<QB extends WhereExpressionBuilder>(builder: QB, method: WhereMethods | HavingMethods, field: string, conditions: string, params?: unknown, options?: {
     addValue?: boolean;
 }): QB;
 /**

package/dist/utils/where.utils.js

@@ -49,14 +49,35 @@ function hasParamPlaceholder(conditions, params) {
     return false;
 }
 exports.hasParamPlaceholder = hasParamPlaceholder;
+/**
+ * A params object whose value goes after the condition (`'='`, `{ id: 1 }`) holds that one value. With other
+ * keys only the first was used and the rest dropped; with none the column was compared with NULL.
+ */
+function assertSingleValueParams(field, params) {
+    if (!isParamsObject(params)) {
+        return;
+    }
+    const keys = Object.keys(params);
+    if (keys.length !== 1) {
+        throw new TypeError(`Condition on "${field}": a params object without a placeholder in the condition holds the one value to compare with, ` +
+            `got ${keys.length} keys (${keys.join(', ') || 'none'}). Pass the value itself, or name the keys in the condition: '= :id'`);
+    }
+}
+/** The builder's `where` / `having` method, bound to it: only a SelectQueryBuilder has `having`. */
+function addCondition(builder, method) {
+    const add = builder[method];
+    return (condition, parameters) => add.call(builder, condition, parameters);
+}
 function attachWhere(builder, method, field, conditions, params, options) {
     let { addValue } = options || {};
     if (method && typeof field === 'string' && typeof conditions === 'string') {
+        const fieldName = field;
         field = (0, query_builder_utils_1.toFieldSql)(builder, field);
         const hasParams = typeof params !== 'undefined';
         // `addValue` defaults to `true` unless `conditions` already references one of the `params` keys
         addValue = addValue !== null && addValue !== void 0 ? addValue : !hasParamPlaceholder(conditions, params);
         if (addValue && hasParams) {
+            assertSingleValueParams(fieldName, params);
             // pick first value from params object or pass as is (a Date or a Buffer is a value too)
             const firstValue = isParamsObject(params) ? Object.values(params)[0] : params;
             // 0, false, '' are valid values like any other
@@ -69,10 +90,10 @@ function attachWhere(builder, method, field, conditions, params, options) {
                 : undefined;
             const queryParams = paramName && valueIsValid ? { [paramName]: firstValue } : undefined;
             const valuePlaceholder = getValuePlaceholder(firstValue, paramName);
-            return builder[method](`${field} ${conditions} ${valuePlaceholder}`, queryParams);
+            return addCondition(builder, method)(`${field} ${conditions} ${valuePlaceholder}`, queryParams);
         }
         else {
-            return builder[method](`${field} ${conditions}`, params);
+            return addCondition(builder, method)(`${field} ${conditions}`, params);
         }
     }
     return builder;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typeorm-extensions",
-  "version": "2.1.0",
+  "version": "2.2.0-rc.1",
   "description": "typeorm commonly used extensions",
   "main": "./dist/index.js",
   "types": "dist/index.d.ts",
@@ -14,7 +14,7 @@
   "scripts": {
     "build": "tsc -p .",
     "lint": "eslint . --ext .ts",
-    "test:types": "tsc -p test/types"
+    "test:types": "tsc -p test/types && tsc -p test/types/tsconfig.loose.json"
   },
   "keywords": [
     "typeorm",
@@ -24,7 +24,7 @@
     "utils"
   ],
   "author": "koenigstag",
-  "license": "ISC",
+  "license": "MIT",
   "peerDependencies": {
     "typeorm": "^0.3.12 || ^1.0.0"
   },