@openforis/arena-core 2.3.32 → 2.3.34

package/dist/geo/points/equals.js.map

@@ -1 +1 @@
-{"version":3,"file":"equals.js","sourceRoot":"","sources":["../../../src/geo/points/equals.ts"],"names":[],"mappings":";;;AAEO,MAAM,MAAM,GAAG,CAAC,MAAa,EAAE,MAAa,EAAW,EAAE;IAC9D,IAAI,MAAM,KAAK,MAAM;QAAE,OAAO,IAAI,CAAA;IAClC,OAAO,MAAM,CAAC,GAAG,KAAK,MAAM,CAAC,GAAG,IAAI,MAAM,CAAC,CAAC,KAAK,MAAM,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC,KAAK,MAAM,CAAC,CAAC,CAAA;AACpF,CAAC,CAAA;AAHY,QAAA,MAAM,UAGlB"}
+{"version":3,"file":"equals.js","sourceRoot":"","sources":["../../../src/geo/points/equals.ts"],"names":[],"mappings":";;;AAEO,MAAM,MAAM,GAAG,CAAC,MAAa,EAAE,MAAa,EAAW,EAAE;IAC9D,IAAI,MAAM,KAAK,MAAM;QAAE,OAAO,IAAI,CAAA;IAClC,OAAO,MAAM,CAAC,GAAG,KAAK,MAAM,CAAC,GAAG,IAAI,MAAM,CAAC,CAAC,KAAK,MAAM,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC,KAAK,MAAM,CAAC,CAAC,CAAA;AACpF,CAAC,CAAA;AAHY,QAAA,MAAM,UAGlB","sourcesContent":["import { Point } from '../point'\n\nexport const equals = (point1: Point, point2: Point): boolean => {\n  if (point1 === point2) return true\n  return point1.srs === point2.srs && point1.x === point2.x && point1.y === point2.y\n}\n"]}

package/dist/geo/points/getSrs.js.map

@@ -1 +1 @@
-{"version":3,"file":"getSrs.js","sourceRoot":"","sources":["../../../src/geo/points/getSrs.ts"],"names":[],"mappings":";;;AAAA,mCAAsD;AAE/C,MAAM,MAAM,GAAG,CAAC,MAA4C,EAAmB,EAAE;IACtF,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,MAAM,CAAA;IACjC,IAAI,IAAI,KAAK,iBAAW,CAAC,IAAI,EAAE,CAAC;QAC9B,OAAO,iBAAW,CAAA;IACpB,CAAC;IACD,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAA;AACvB,CAAC,CAAA;AANY,QAAA,MAAM,UAMlB"}
+{"version":3,"file":"getSrs.js","sourceRoot":"","sources":["../../../src/geo/points/getSrs.ts"],"names":[],"mappings":";;;AAAA,mCAAsD;AAE/C,MAAM,MAAM,GAAG,CAAC,MAA4C,EAAmB,EAAE;IACtF,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,MAAM,CAAA;IACjC,IAAI,IAAI,KAAK,iBAAW,CAAC,IAAI,EAAE,CAAC;QAC9B,OAAO,iBAAW,CAAA;IACpB,CAAC;IACD,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAA;AACvB,CAAC,CAAA;AANY,QAAA,MAAM,UAMlB","sourcesContent":["import { DEFAULT_SRS, SRS, SRSIndex } from '../../srs'\n\nexport const getSrs = (params: { code: string; srsIndex: SRSIndex }): SRS | undefined => {\n  const { code, srsIndex } = params\n  if (code === DEFAULT_SRS.code) {\n    return DEFAULT_SRS\n  }\n  return srsIndex[code]\n}\n"]}

package/dist/geo/points/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/geo/points/index.ts"],"names":[],"mappings":";;;AAAA,uCAAmC;AACnC,yCAAqC;AACrC,qCAAiC;AACjC,uCAAmC;AACnC,uDAAmD;AACnD,mCAA+B;AAC/B,2CAAuC;AACvC,yCAAqC;AACrC,2CAAuC;AAE1B,QAAA,MAAM,GAAG;IACpB,OAAO,EAAP,iBAAO;IACP,QAAQ,EAAR,mBAAQ;IACR,MAAM,EAAN,eAAM;IACN,OAAO,EAAP,iBAAO;IACP,eAAe,EAAf,iCAAe;IACf,KAAK,EAAL,aAAK;IACL,SAAS,EAAT,qBAAS;IACT,QAAQ,EAAR,mBAAQ;IACR,SAAS,EAAT,qBAAS;CACV,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/geo/points/index.ts"],"names":[],"mappings":";;;AAAA,uCAAmC;AACnC,yCAAqC;AACrC,qCAAiC;AACjC,uCAAmC;AACnC,uDAAmD;AACnD,mCAA+B;AAC/B,2CAAuC;AACvC,yCAAqC;AACrC,2CAAuC;AAE1B,QAAA,MAAM,GAAG;IACpB,OAAO,EAAP,iBAAO;IACP,QAAQ,EAAR,mBAAQ;IACR,MAAM,EAAN,eAAM;IACN,OAAO,EAAP,iBAAO;IACP,eAAe,EAAf,iCAAe;IACf,KAAK,EAAL,aAAK;IACL,SAAS,EAAT,qBAAS;IACT,QAAQ,EAAR,mBAAQ;IACR,SAAS,EAAT,qBAAS;CACV,CAAA","sourcesContent":["import { bearing } from './bearing'\nimport { distance } from './distance'\nimport { equals } from './equals'\nimport { isValid } from './isValid'\nimport { pointAtDistance } from './pointAtDistance'\nimport { parse } from './parse'\nimport { toLatLong } from './toLatLong'\nimport { toString } from './toString'\nimport { transform } from './transform'\n\nexport const Points = {\n  bearing,\n  distance,\n  equals,\n  isValid,\n  pointAtDistance,\n  parse,\n  toLatLong,\n  toString,\n  transform,\n}\n"]}

package/dist/geo/points/isFilled.js.map

@@ -1 +1 @@
-{"version":3,"file":"isFilled.js","sourceRoot":"","sources":["../../../src/geo/points/isFilled.ts"],"names":[],"mappings":";;;AAAA,uCAAqC;AAG9B,MAAM,QAAQ,GAAG,CAAC,KAAY,EAAW,EAAE,CAChD,CAAC,eAAO,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,eAAO,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,eAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,eAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;AADrG,QAAA,QAAQ,YAC6F"}
+{"version":3,"file":"isFilled.js","sourceRoot":"","sources":["../../../src/geo/points/isFilled.ts"],"names":[],"mappings":";;;AAAA,uCAAqC;AAG9B,MAAM,QAAQ,GAAG,CAAC,KAAY,EAAW,EAAE,CAChD,CAAC,eAAO,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,eAAO,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,eAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,eAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;AADrG,QAAA,QAAQ,YAC6F","sourcesContent":["import { Objects } from '../../utils'\nimport { Point } from '../point'\n\nexport const isFilled = (point: Point): boolean =>\n  !Objects.isEmpty(point) && !Objects.isEmpty(point.srs) && !Objects.isEmpty(point.x) && !Objects.isEmpty(point.y)\n"]}

package/dist/geo/points/isValid.js

@@ -8,7 +8,7 @@ const equals_1 = require("./equals");
 const getSrs_1 = require("./getSrs");
 const isFilled_1 = require("./isFilled");
 const toLatLong_1 = require("./toLatLong");
-const INVALID_LAT_LONG_POINT = pointFactory_1.PointFactory.createInstance({ x: 0, y: 90 });
+const INVALID_LAT_LONG_POINT = pointFactory_1.PointFactory.createInstance({ x: 0, y: 90 }); // Proj4 returns [0,90] when a wrong coordinate is projected into lat-lon
 const isValid = (point, srsIndex = srs_1.DEFAULT_SRS_INDEX) => {
     if (!point || !(0, isFilled_1.isFilled)(point))
         return false;

package/dist/geo/points/isValid.js.map

@@ -1 +1 @@
-{"version":3,"file":"isValid.js","sourceRoot":"","sources":["../../../src/geo/points/isValid.ts"],"names":[],"mappings":";;;AAAA,mCAAuD;AACvD,uCAAqC;AAErC,kDAA8C;AAC9C,qCAAiC;AACjC,qCAAiC;AACjC,yCAAqC;AACrC,2CAAuC;AAEvC,MAAM,sBAAsB,GAAU,2BAAY,CAAC,cAAc,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAA;AAE3E,MAAM,OAAO,GAAG,CAAC,KAAY,EAAE,WAAqB,uBAAiB,EAAW,EAAE;IACvF,IAAI,CAAC,KAAK,IAAI,CAAC,IAAA,mBAAQ,EAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAA;IAE5C,IAAI,CAAC,IAAA,eAAM,EAAC,EAAE,IAAI,EAAE,KAAK,CAAC,GAAG,EAAE,QAAQ,EAAE,CAAC;QAAE,OAAO,KAAK,CAAA;IAExD,MAAM,YAAY,GAAG,IAAA,qBAAS,EAAC,KAAK,EAAE,QAAQ,CAAC,CAAA;IAC/C,IAAI,CAAC,YAAY,IAAI,IAAA,eAAM,EAAC,YAAY,EAAE,sBAAsB,CAAC;QAAE,OAAO,KAAK,CAAA;IAE/E,OAAO,eAAO,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI,eAAO,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAA;AAC/F,CAAC,CAAA;AATY,QAAA,OAAO,WASnB"}
+{"version":3,"file":"isValid.js","sourceRoot":"","sources":["../../../src/geo/points/isValid.ts"],"names":[],"mappings":";;;AAAA,mCAAuD;AACvD,uCAAqC;AAErC,kDAA8C;AAC9C,qCAAiC;AACjC,qCAAiC;AACjC,yCAAqC;AACrC,2CAAuC;AAEvC,MAAM,sBAAsB,GAAU,2BAAY,CAAC,cAAc,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAA,CAAC,yEAAyE;AAErJ,MAAM,OAAO,GAAG,CAAC,KAAY,EAAE,WAAqB,uBAAiB,EAAW,EAAE;IACvF,IAAI,CAAC,KAAK,IAAI,CAAC,IAAA,mBAAQ,EAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAA;IAE5C,IAAI,CAAC,IAAA,eAAM,EAAC,EAAE,IAAI,EAAE,KAAK,CAAC,GAAG,EAAE,QAAQ,EAAE,CAAC;QAAE,OAAO,KAAK,CAAA;IAExD,MAAM,YAAY,GAAG,IAAA,qBAAS,EAAC,KAAK,EAAE,QAAQ,CAAC,CAAA;IAC/C,IAAI,CAAC,YAAY,IAAI,IAAA,eAAM,EAAC,YAAY,EAAE,sBAAsB,CAAC;QAAE,OAAO,KAAK,CAAA;IAE/E,OAAO,eAAO,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI,eAAO,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAA;AAC/F,CAAC,CAAA;AATY,QAAA,OAAO,WASnB","sourcesContent":["import { DEFAULT_SRS_INDEX, SRSIndex } from '../../srs'\nimport { Numbers } from '../../utils'\nimport { Point } from '../point'\nimport { PointFactory } from '../pointFactory'\nimport { equals } from './equals'\nimport { getSrs } from './getSrs'\nimport { isFilled } from './isFilled'\nimport { toLatLong } from './toLatLong'\n\nconst INVALID_LAT_LONG_POINT: Point = PointFactory.createInstance({ x: 0, y: 90 }) // Proj4 returns [0,90] when a wrong coordinate is projected into lat-lon\n\nexport const isValid = (point: Point, srsIndex: SRSIndex = DEFAULT_SRS_INDEX): boolean => {\n  if (!point || !isFilled(point)) return false\n\n  if (!getSrs({ code: point.srs, srsIndex })) return false\n\n  const pointLatLong = toLatLong(point, srsIndex)\n  if (!pointLatLong || equals(pointLatLong, INVALID_LAT_LONG_POINT)) return false\n\n  return Numbers.between(pointLatLong.x, -180, 180) && Numbers.between(pointLatLong.y, -90, 90)\n}\n"]}

package/dist/geo/points/parse.d.ts

@@ -1,2 +1,11 @@
 import { Point } from '../point';
+/**
+ * Parses a point in the format: SRID=SRS_CODE;POINT(X Y)
+ * (X and Y separated by a space). Valid examples are:
+ * - SRID=EPSG:4326;POINT(12.489060 41.882788)
+ * - SRID=4326;POINT(12 41).
+ *
+ * @param {!(string | object)} value - The point to parse. It can be a string or an object.
+ * @returns {Point} - The parsed Point object.
+ */
 export declare const parse: (value: string | object) => Point | null;

package/dist/geo/points/parse.js

@@ -3,6 +3,15 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.parse = void 0;
 const pointFactory_1 = require("../pointFactory");
 const POINT_REGEX = /SRID=((EPSG:)?(\w+));POINT\((-?\d+(\.\d+)?) (-?\d+(\.\d+)?)\)/;
+/**
+ * Parses a point in the format: SRID=SRS_CODE;POINT(X Y)
+ * (X and Y separated by a space). Valid examples are:
+ * - SRID=EPSG:4326;POINT(12.489060 41.882788)
+ * - SRID=4326;POINT(12 41).
+ *
+ * @param {!(string | object)} value - The point to parse. It can be a string or an object.
+ * @returns {Point} - The parsed Point object.
+ */
 const parse = (value) => {
     if (!value)
         return null;

package/dist/geo/points/parse.js.map

@@ -1 +1 @@
-{"version":3,"file":"parse.js","sourceRoot":"","sources":["../../../src/geo/points/parse.ts"],"names":[],"mappings":";;;AACA,kDAA8C;AAE9C,MAAM,WAAW,GAAG,+DAA+D,CAAA;AAW5E,MAAM,KAAK,GAAG,CAAC,KAAsB,EAAgB,EAAE;IAC5D,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAA;IAEvB,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAc,CAAA;IAEpD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,MAAM,KAAK,GAAG,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QACrC,IAAI,CAAC,KAAK;YAAE,OAAO,IAAI,CAAA;QAEvB,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,CAAA;QACpB,MAAM,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA;QAC1B,MAAM,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA;QAC1B,OAAO,2BAAY,CAAC,cAAc,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAA;IACnD,CAAC;IACD,OAAO,IAAI,CAAA;AACb,CAAC,CAAA;AAfY,QAAA,KAAK,SAejB"}
+{"version":3,"file":"parse.js","sourceRoot":"","sources":["../../../src/geo/points/parse.ts"],"names":[],"mappings":";;;AACA,kDAA8C;AAE9C,MAAM,WAAW,GAAG,+DAA+D,CAAA;AAEnF;;;;;;;;GAQG;AACI,MAAM,KAAK,GAAG,CAAC,KAAsB,EAAgB,EAAE;IAC5D,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAA;IAEvB,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAc,CAAA;IAEpD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,MAAM,KAAK,GAAG,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QACrC,IAAI,CAAC,KAAK;YAAE,OAAO,IAAI,CAAA;QAEvB,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,CAAA;QACpB,MAAM,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA;QAC1B,MAAM,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA;QAC1B,OAAO,2BAAY,CAAC,cAAc,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAA;IACnD,CAAC;IACD,OAAO,IAAI,CAAA;AACb,CAAC,CAAA;AAfY,QAAA,KAAK,SAejB","sourcesContent":["import { Point } from '../point'\nimport { PointFactory } from '../pointFactory'\n\nconst POINT_REGEX = /SRID=((EPSG:)?(\\w+));POINT\\((-?\\d+(\\.\\d+)?) (-?\\d+(\\.\\d+)?)\\)/\n\n/**\n * Parses a point in the format: SRID=SRS_CODE;POINT(X Y)\n * (X and Y separated by a space). Valid examples are:\n * - SRID=EPSG:4326;POINT(12.489060 41.882788)\n * - SRID=4326;POINT(12 41).\n *\n * @param {!(string | object)} value - The point to parse. It can be a string or an object.\n * @returns {Point} - The parsed Point object.\n */\nexport const parse = (value: string | object): Point | null => {\n  if (!value) return null\n\n  if (typeof value === 'object') return value as Point\n\n  if (typeof value === 'string') {\n    const match = POINT_REGEX.exec(value)\n    if (!match) return null\n\n    const srs = match[3]\n    const x = Number(match[4])\n    const y = Number(match[6])\n    return PointFactory.createInstance({ srs, x, y })\n  }\n  return null\n}\n"]}

package/dist/geo/points/pointAtDistance.d.ts

@@ -1,5 +1,14 @@
 import { SRSIndex } from '../../srs';
 import { Point } from '../point';
+/**
+ * Takes a point, a distance in meters, and a bearing in degrees, and returns the location of the point at the specified distance and bearing from the original point.
+ * @param params
+ * @param params.origin - The original point from which to calculate the new location.
+ * @param params.distanceMeters - The distance in meters from the original point to the new location.
+ * @param params.bearingDeg - The bearing in degrees from the original point to the new location.
+ * @param params.srsIndex - SRSs indexed by SRS code.
+ * @returns The new point at the specified distance and bearing from the original point, or null if the calculation fails.
+ */
 export declare const pointAtDistance: ({ origin, distanceMeters, bearingDeg, srsIndex, }: {
     origin: Point;
     distanceMeters: number;

package/dist/geo/points/pointAtDistance.js

@@ -10,8 +10,18 @@ const pointFactory_1 = require("../pointFactory");
 const toLatLong_1 = require("./toLatLong");
 const transform_1 = require("./transform");
 const isValid_1 = require("./isValid");
+/**
+ * Takes a point, a distance in meters, and a bearing in degrees, and returns the location of the point at the specified distance and bearing from the original point.
+ * @param params
+ * @param params.origin - The original point from which to calculate the new location.
+ * @param params.distanceMeters - The distance in meters from the original point to the new location.
+ * @param params.bearingDeg - The bearing in degrees from the original point to the new location.
+ * @param params.srsIndex - SRSs indexed by SRS code.
+ * @returns The new point at the specified distance and bearing from the original point, or null if the calculation fails.
+ */
 const pointAtDistance = ({ origin, distanceMeters, bearingDeg, srsIndex = srs_1.DEFAULT_SRS_INDEX, }) => {
     const originLatLong = (0, toLatLong_1.toLatLong)(origin, srsIndex);
+    // Validate numeric inputs and lat/long bounds before calling turfDestination
     if (!originLatLong || !(0, isValid_1.isValid)(originLatLong, srsIndex)) {
         return null;
     }

package/dist/geo/points/pointAtDistance.js.map

@@ -1 +1 @@
-{"version":3,"file":"pointAtDistance.js","sourceRoot":"","sources":["../../../src/geo/points/pointAtDistance.ts"],"names":[],"mappings":";;;;;;AAAA,oEAA+C;AAE/C,mCAAuD;AAEvD,kDAA8C;AAC9C,2CAAuC;AACvC,2CAAuC;AACvC,uCAAmC;AAW5B,MAAM,eAAe,GAAG,CAAC,EAC9B,MAAM,EACN,cAAc,EACd,UAAU,EACV,QAAQ,GAAG,uBAAiB,GAM7B,EAAgB,EAAE;IACjB,MAAM,aAAa,GAAG,IAAA,qBAAS,EAAC,MAAM,EAAE,QAAQ,CAAC,CAAA;IAGjD,IAAI,CAAC,aAAa,IAAI,CAAC,IAAA,iBAAO,EAAC,aAAa,EAAE,QAAQ,CAAC,EAAE,CAAC;QACxD,OAAO,IAAI,CAAA;IACb,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,cAAc,CAAC,IAAI,cAAc,GAAG,CAAC,EAAE,CAAC;QAC3D,OAAO,IAAI,CAAA;IACb,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;QACjC,OAAO,IAAI,CAAA;IACb,CAAC;IACD,MAAM,MAAM,GAAG,IAAA,qBAAe,EAAC,CAAC,aAAa,CAAC,CAAC,EAAE,aAAa,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,UAAU,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAA;IACnH,MAAM,kBAAkB,GAAG,2BAAY,CAAC,cAAc,CAAC;QACrD,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC;QACjC,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC;KAClC,CAAC,CAAA;IACF,OAAO,IAAA,qBAAS,EAAC,kBAAkB,EAAE,MAAM,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAA;AAC5D,CAAC,CAAA;AA7BY,QAAA,eAAe,mBA6B3B"}
+{"version":3,"file":"pointAtDistance.js","sourceRoot":"","sources":["../../../src/geo/points/pointAtDistance.ts"],"names":[],"mappings":";;;;;;AAAA,oEAA+C;AAE/C,mCAAuD;AAEvD,kDAA8C;AAC9C,2CAAuC;AACvC,2CAAuC;AACvC,uCAAmC;AAEnC;;;;;;;;GAQG;AACI,MAAM,eAAe,GAAG,CAAC,EAC9B,MAAM,EACN,cAAc,EACd,UAAU,EACV,QAAQ,GAAG,uBAAiB,GAM7B,EAAgB,EAAE;IACjB,MAAM,aAAa,GAAG,IAAA,qBAAS,EAAC,MAAM,EAAE,QAAQ,CAAC,CAAA;IAEjD,6EAA6E;IAC7E,IAAI,CAAC,aAAa,IAAI,CAAC,IAAA,iBAAO,EAAC,aAAa,EAAE,QAAQ,CAAC,EAAE,CAAC;QACxD,OAAO,IAAI,CAAA;IACb,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,cAAc,CAAC,IAAI,cAAc,GAAG,CAAC,EAAE,CAAC;QAC3D,OAAO,IAAI,CAAA;IACb,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;QACjC,OAAO,IAAI,CAAA;IACb,CAAC;IACD,MAAM,MAAM,GAAG,IAAA,qBAAe,EAAC,CAAC,aAAa,CAAC,CAAC,EAAE,aAAa,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,UAAU,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAA;IACnH,MAAM,kBAAkB,GAAG,2BAAY,CAAC,cAAc,CAAC;QACrD,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC;QACjC,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC;KAClC,CAAC,CAAA;IACF,OAAO,IAAA,qBAAS,EAAC,kBAAkB,EAAE,MAAM,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAA;AAC5D,CAAC,CAAA;AA7BY,QAAA,eAAe,mBA6B3B","sourcesContent":["import turfDestination from '@turf/destination'\n\nimport { DEFAULT_SRS_INDEX, SRSIndex } from '../../srs'\nimport { Point } from '../point'\nimport { PointFactory } from '../pointFactory'\nimport { toLatLong } from './toLatLong'\nimport { transform } from './transform'\nimport { isValid } from './isValid'\n\n/**\n * Takes a point, a distance in meters, and a bearing in degrees, and returns the location of the point at the specified distance and bearing from the original point.\n * @param params\n * @param params.origin - The original point from which to calculate the new location.\n * @param params.distanceMeters - The distance in meters from the original point to the new location.\n * @param params.bearingDeg - The bearing in degrees from the original point to the new location.\n * @param params.srsIndex - SRSs indexed by SRS code.\n * @returns The new point at the specified distance and bearing from the original point, or null if the calculation fails.\n */\nexport const pointAtDistance = ({\n  origin,\n  distanceMeters,\n  bearingDeg,\n  srsIndex = DEFAULT_SRS_INDEX,\n}: {\n  origin: Point\n  distanceMeters: number\n  bearingDeg: number\n  srsIndex?: SRSIndex\n}): Point | null => {\n  const originLatLong = toLatLong(origin, srsIndex)\n\n  // Validate numeric inputs and lat/long bounds before calling turfDestination\n  if (!originLatLong || !isValid(originLatLong, srsIndex)) {\n    return null\n  }\n  if (!Number.isFinite(distanceMeters) || distanceMeters < 0) {\n    return null\n  }\n  if (!Number.isFinite(bearingDeg)) {\n    return null\n  }\n  const target = turfDestination([originLatLong.x, originLatLong.y], distanceMeters, bearingDeg, { units: 'meters' })\n  const targetPointLatLong = PointFactory.createInstance({\n    x: target.geometry.coordinates[0],\n    y: target.geometry.coordinates[1],\n  })\n  return transform(targetPointLatLong, origin.srs, srsIndex)\n}\n"]}

package/dist/geo/points/toLatLong.js.map

@@ -1 +1 @@
-{"version":3,"file":"toLatLong.js","sourceRoot":"","sources":["../../../src/geo/points/toLatLong.ts"],"names":[],"mappings":";;;AAAA,mCAAiD;AAEjD,2CAAuC;AAEhC,MAAM,SAAS,GAAG,CAAC,KAAY,EAAE,QAAkB,EAAgB,EAAE,CAC1E,IAAA,qBAAS,EAAC,KAAK,EAAE,iBAAW,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAA;AADjC,QAAA,SAAS,aACwB"}
+{"version":3,"file":"toLatLong.js","sourceRoot":"","sources":["../../../src/geo/points/toLatLong.ts"],"names":[],"mappings":";;;AAAA,mCAAiD;AAEjD,2CAAuC;AAEhC,MAAM,SAAS,GAAG,CAAC,KAAY,EAAE,QAAkB,EAAgB,EAAE,CAC1E,IAAA,qBAAS,EAAC,KAAK,EAAE,iBAAW,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAA;AADjC,QAAA,SAAS,aACwB","sourcesContent":["import { DEFAULT_SRS, SRSIndex } from '../../srs'\nimport { Point } from '../point'\nimport { transform } from './transform'\n\nexport const toLatLong = (point: Point, srsIndex: SRSIndex): Point | null =>\n  transform(point, DEFAULT_SRS.code, srsIndex)\n"]}

package/dist/geo/points/toString.js.map

@@ -1 +1 @@
-{"version":3,"file":"toString.js","sourceRoot":"","sources":["../../../src/geo/points/toString.ts"],"names":[],"mappings":";;;AAEO,MAAM,QAAQ,GAAG,CAAC,KAAY,EAAU,EAAE,CAAC,QAAQ,KAAK,CAAC,GAAG,UAAU,KAAK,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,GAAG,CAAA;AAArF,QAAA,QAAQ,YAA6E"}
+{"version":3,"file":"toString.js","sourceRoot":"","sources":["../../../src/geo/points/toString.ts"],"names":[],"mappings":";;;AAEO,MAAM,QAAQ,GAAG,CAAC,KAAY,EAAU,EAAE,CAAC,QAAQ,KAAK,CAAC,GAAG,UAAU,KAAK,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,GAAG,CAAA;AAArF,QAAA,QAAQ,YAA6E","sourcesContent":["import { Point } from '../point'\n\nexport const toString = (point: Point): string => `SRID=${point.srs};POINT(${point.x} ${point.y})`\n"]}

package/dist/geo/points/transform.d.ts

@@ -1,3 +1,11 @@
 import { SRSIndex } from '../../srs';
 import { Point } from '../point';
+/**
+ * Trasforms the specified point from one SRS into another.
+ *
+ * @param {!Point} point - The point to transform.
+ * @param {!string} srsCodeTo - The SRS code to transform the coordinate into.
+ * @param {SRSIndex} srsIndex - SRSs indexed by SRS code.
+ * @returns {Point|null} - The transformed Point object, null if an error occurred.
+ */
 export declare const transform: (point: Point, srsCodeTo: string, srsIndex?: SRSIndex) => Point | null;

package/dist/geo/points/transform.js

@@ -9,6 +9,7 @@ const srs_1 = require("../../srs");
 const pointFactory_1 = require("../pointFactory");
 const isFilled_1 = require("./isFilled");
 const getSrs_1 = require("./getSrs");
+// proj4 parses both WKT strings every time it is called with them: cache the converters by WKT pair
 const convertersCache = new Map();
 const getConverter = (wktFrom, wktTo) => {
     const key = `${wktFrom}\n${wktTo}`;
@@ -19,19 +20,30 @@ const getConverter = (wktFrom, wktTo) => {
     }
     return converter;
 };
+/**
+ * Trasforms the specified point from one SRS into another.
+ *
+ * @param {!Point} point - The point to transform.
+ * @param {!string} srsCodeTo - The SRS code to transform the coordinate into.
+ * @param {SRSIndex} srsIndex - SRSs indexed by SRS code.
+ * @returns {Point|null} - The transformed Point object, null if an error occurred.
+ */
 const transform = (point, srsCodeTo, srsIndex = srs_1.DEFAULT_SRS_INDEX) => {
     if (!(0, isFilled_1.isFilled)(point))
         return null;
     const { srs: srsCodeFrom } = point;
     if (srsCodeFrom === srsCodeTo) {
+        // projection is not needed
         return point;
     }
     const srsFrom = (0, getSrs_1.getSrs)({ code: srsCodeFrom, srsIndex });
     if (!srsFrom) {
+        // invalid srs specified in point
         return null;
     }
     const srsTo = (0, getSrs_1.getSrs)({ code: srsCodeTo, srsIndex });
     if (!srsTo) {
+        // invalid target srs code
         return null;
     }
     try {

package/dist/geo/points/transform.js.map

@@ -1 +1 @@
-{"version":3,"file":"transform.js","sourceRoot":"","sources":["../../../src/geo/points/transform.ts"],"names":[],"mappings":";;;;;;AAAA,kDAAyB;AAEzB,mCAAuD;AAEvD,kDAA8C;AAC9C,yCAAqC;AACrC,qCAAiC;AAGjC,MAAM,eAAe,GAAG,IAAI,GAAG,EAA2B,CAAA;AAE1D,MAAM,YAAY,GAAG,CAAC,OAAe,EAAE,KAAa,EAAmB,EAAE;IACvE,MAAM,GAAG,GAAG,GAAG,OAAO,KAAK,KAAK,EAAE,CAAA;IAClC,IAAI,SAAS,GAAG,eAAe,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IACxC,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,SAAS,GAAG,IAAA,eAAK,EAAC,OAAO,EAAE,KAAK,CAAC,CAAA;QACjC,eAAe,CAAC,GAAG,CAAC,GAAG,EAAE,SAAS,CAAC,CAAA;IACrC,CAAC;IACD,OAAO,SAAS,CAAA;AAClB,CAAC,CAAA;AAUM,MAAM,SAAS,GAAG,CAAC,KAAY,EAAE,SAAiB,EAAE,WAAqB,uBAAiB,EAAgB,EAAE;IACjH,IAAI,CAAC,IAAA,mBAAQ,EAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAA;IAEjC,MAAM,EAAE,GAAG,EAAE,WAAW,EAAE,GAAG,KAAK,CAAA;IAElC,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;QAE9B,OAAO,KAAK,CAAA;IACd,CAAC;IACD,MAAM,OAAO,GAAG,IAAA,eAAM,EAAC,EAAE,IAAI,EAAE,WAAW,EAAE,QAAQ,EAAE,CAAC,CAAA;IACvD,IAAI,CAAC,OAAO,EAAE,CAAC;QAEb,OAAO,IAAI,CAAA;IACb,CAAC;IAED,MAAM,KAAK,GAAG,IAAA,eAAM,EAAC,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,CAAA;IACnD,IAAI,CAAC,KAAK,EAAE,CAAC;QAEX,OAAO,IAAI,CAAA;IACb,CAAC;IACD,IAAI,CAAC;QACH,MAAM,EAAE,CAAC,EAAE,CAAC,EAAE,GAAG,KAAK,CAAA;QACtB,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,GAAG,YAAY,CAAC,OAAO,CAAC,GAAG,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;QAExF,OAAO,2BAAY,CAAC,cAAc,iCAAM,KAAK,KAAE,GAAG,EAAE,SAAS,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,IAAG,CAAA;IACnF,CAAC;IAAC,WAAM,CAAC;QACP,OAAO,IAAI,CAAA;IACb,CAAC;AACH,CAAC,CAAA;AA5BY,QAAA,SAAS,aA4BrB"}
+{"version":3,"file":"transform.js","sourceRoot":"","sources":["../../../src/geo/points/transform.ts"],"names":[],"mappings":";;;;;;AAAA,kDAAyB;AAEzB,mCAAuD;AAEvD,kDAA8C;AAC9C,yCAAqC;AACrC,qCAAiC;AAEjC,oGAAoG;AACpG,MAAM,eAAe,GAAG,IAAI,GAAG,EAA2B,CAAA;AAE1D,MAAM,YAAY,GAAG,CAAC,OAAe,EAAE,KAAa,EAAmB,EAAE;IACvE,MAAM,GAAG,GAAG,GAAG,OAAO,KAAK,KAAK,EAAE,CAAA;IAClC,IAAI,SAAS,GAAG,eAAe,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IACxC,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,SAAS,GAAG,IAAA,eAAK,EAAC,OAAO,EAAE,KAAK,CAAC,CAAA;QACjC,eAAe,CAAC,GAAG,CAAC,GAAG,EAAE,SAAS,CAAC,CAAA;IACrC,CAAC;IACD,OAAO,SAAS,CAAA;AAClB,CAAC,CAAA;AAED;;;;;;;GAOG;AACI,MAAM,SAAS,GAAG,CAAC,KAAY,EAAE,SAAiB,EAAE,WAAqB,uBAAiB,EAAgB,EAAE;IACjH,IAAI,CAAC,IAAA,mBAAQ,EAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAA;IAEjC,MAAM,EAAE,GAAG,EAAE,WAAW,EAAE,GAAG,KAAK,CAAA;IAElC,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;QAC9B,2BAA2B;QAC3B,OAAO,KAAK,CAAA;IACd,CAAC;IACD,MAAM,OAAO,GAAG,IAAA,eAAM,EAAC,EAAE,IAAI,EAAE,WAAW,EAAE,QAAQ,EAAE,CAAC,CAAA;IACvD,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,iCAAiC;QACjC,OAAO,IAAI,CAAA;IACb,CAAC;IAED,MAAM,KAAK,GAAG,IAAA,eAAM,EAAC,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,CAAA;IACnD,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,0BAA0B;QAC1B,OAAO,IAAI,CAAA;IACb,CAAC;IACD,IAAI,CAAC;QACH,MAAM,EAAE,CAAC,EAAE,CAAC,EAAE,GAAG,KAAK,CAAA;QACtB,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,GAAG,YAAY,CAAC,OAAO,CAAC,GAAG,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;QAExF,OAAO,2BAAY,CAAC,cAAc,iCAAM,KAAK,KAAE,GAAG,EAAE,SAAS,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,IAAG,CAAA;IACnF,CAAC;IAAC,WAAM,CAAC;QACP,OAAO,IAAI,CAAA;IACb,CAAC;AACH,CAAC,CAAA;AA5BY,QAAA,SAAS,aA4BrB","sourcesContent":["import proj4 from 'proj4'\n\nimport { DEFAULT_SRS_INDEX, SRSIndex } from '../../srs'\nimport { Point } from '../point'\nimport { PointFactory } from '../pointFactory'\nimport { isFilled } from './isFilled'\nimport { getSrs } from './getSrs'\n\n// proj4 parses both WKT strings every time it is called with them: cache the converters by WKT pair\nconst convertersCache = new Map<string, proj4.Converter>()\n\nconst getConverter = (wktFrom: string, wktTo: string): proj4.Converter => {\n  const key = `${wktFrom}\\n${wktTo}`\n  let converter = convertersCache.get(key)\n  if (!converter) {\n    converter = proj4(wktFrom, wktTo)\n    convertersCache.set(key, converter)\n  }\n  return converter\n}\n\n/**\n * Trasforms the specified point from one SRS into another.\n *\n * @param {!Point} point - The point to transform.\n * @param {!string} srsCodeTo - The SRS code to transform the coordinate into.\n * @param {SRSIndex} srsIndex - SRSs indexed by SRS code.\n * @returns {Point|null} - The transformed Point object, null if an error occurred.\n */\nexport const transform = (point: Point, srsCodeTo: string, srsIndex: SRSIndex = DEFAULT_SRS_INDEX): Point | null => {\n  if (!isFilled(point)) return null\n\n  const { srs: srsCodeFrom } = point\n\n  if (srsCodeFrom === srsCodeTo) {\n    // projection is not needed\n    return point\n  }\n  const srsFrom = getSrs({ code: srsCodeFrom, srsIndex })\n  if (!srsFrom) {\n    // invalid srs specified in point\n    return null\n  }\n\n  const srsTo = getSrs({ code: srsCodeTo, srsIndex })\n  if (!srsTo) {\n    // invalid target srs code\n    return null\n  }\n  try {\n    const { x, y } = point\n    const [long, lat] = getConverter(srsFrom.wkt, srsTo.wkt).forward([Number(x), Number(y)])\n\n    return PointFactory.createInstance({ ...point, srs: srsCodeTo, x: long, y: lat })\n  } catch {\n    return null\n  }\n}\n"]}

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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","sourcesContent":["export type { AppInfo } from './app'\n\nexport { Authorizer, AuthGroupName, UserStatus, Permission, UserTitle, UserFactory, Users } from './auth'\nexport type {\n  AuthGroup,\n  User,\n  UserAuthGroup,\n  UserAuthGroupProps,\n  AuthToken,\n  UserAuthTokenPayload,\n  UserAuthTokenService,\n  UserPrefs,\n  UserPrefSurveys,\n  UserProps,\n  UserAuthRefreshToken,\n  UserAuthRefreshTokenProps,\n  UserAuthRefreshTokenPayload,\n  UserService,\n  UserTokenPayload,\n  DownloadAuthTokenPayload,\n  UserGroup,\n  UserGroupProps,\n  UserGroupQualifier,\n  UserInvitation,\n} from './auth'\n\nexport { CategoryFactory, CategoryImportColumnType, CategoryItemFactory, CategoryLevelFactory } from './category'\nexport type {\n  CategoryItemProps,\n  Category,\n  CategoryItem,\n  CategoryLevel,\n  CategoryLevelProps,\n  CategoryImportSummary,\n  CategoryImportSummaryColumn,\n  CategoryItemService,\n  CategoryLevelService,\n  CategoryProps,\n  CategoryService,\n} from './category'\n\nexport { Categories, CategoryItems } from './category'\n\nexport { ChainFactory, ChainStatusExec, ChainNodeDefFactory } from './chain'\nexport type {\n  Chain,\n  ChainProps,\n  ChainService,\n  ChainNodeDef,\n  ChainNodeDefProps,\n  ChainNodeDefService,\n  ChainNodeDefAggregate,\n  ChainNodeDefAggregateProps,\n} from './chain'\n\nexport { TraverseMethod } from './common'\nexport type { ArenaObject, ArenaService, Dictionary, Factory, I18n } from './common'\n\nexport type { FlatDataExportOptions, ArenaExportInfoFactoryParams, ArenaExportInfo } from './dataExport'\nexport {\n  FlatDataExportDefaultOptions,\n  FlatDataExportOption,\n  FlatDataFiles,\n  FlatDataExportModel,\n  FlatDataExportColumnDataType,\n  ArenaExportInfoFactory,\n  UniqueFileNamesGenerator,\n} from './dataExport'\n\nexport { DataQueryMode, DataQuerySummaries } from './dataQuery'\nexport type { DataQuery, DataQuerySummary, DataQuerySummaryProps } from './dataQuery'\n\nexport { SystemError } from './error'\n\nexport {\n  ExpressionNodeType,\n  ExpressionNodeEvaluator,\n  ExpressionVariable,\n  JavascriptExpressionEvaluator,\n  JavascriptExpressionParser,\n} from './expression'\nexport type {\n  ArrayExpression,\n  BinaryExpression,\n  CallExpression,\n  CompoundExpression,\n  ConditionalExpression,\n  ExpressionContext,\n  ExpressionEvaluator,\n  ExpressionFunction,\n  ExpressionFunctions,\n  ExpressionNode,\n  ExpressionNodeEvaluatorConstructor,\n  MemberExpression,\n  IdentifierExpression,\n  LiteralExpression,\n  SequenceExpression,\n  ThisExpression,\n  UnaryExpression,\n} from './expression'\n\nexport { ExtraPropDataType, ExtraPropsDataGenerator } from './extraProp'\nexport type { ExtraPropDef, ExtraPropDefs } from './extraProp'\n\nexport { PointFactory, Points } from './geo'\nexport type { Point } from './geo'\n\nexport { JobBase, JobEventType, JobStatus } from './job'\nexport type { Job, JobContext, JobEvent, JobSerialized } from './job'\n\nexport { LanguageCode, Languages, LanguagesISO639part2 } from './language'\nexport type { Labels } from './language'\n\nexport type { Logger } from './logger'\n\nexport type { Message } from './message'\nexport { MessageNotificationType, MessagePropsKey, MessageStatus, MessageTargetUserType, Messages } from './message'\n\nexport { NodeFactory, NodeKeys, NodeMetaKeys, Nodes, NodeValueFormatter, NodeValues } from './node'\nexport type {\n  Node,\n  Node as ArenaRecordNode,\n  NodeMeta,\n  NodePointer,\n  NodeRefData,\n  NodeService,\n  NodesMap,\n  NodeValueCode,\n  NodeValueCoordinate,\n  NodeValueFile,\n  NodeValueTaxon,\n} from './node'\n\nexport {\n  NodeDefCountType,\n  NodeDefType,\n  NodeDefFactory,\n  NodeDefs,\n  NodeDefEntityRenderType,\n  NodeDefFileType,\n  NodeDefTextInputType,\n  NodeDefTextRenderType,\n  FormHeaderColor,\n} from './nodeDef'\n\nexport { NodeDefExpressionEvaluator, NodeDefExpressionValidator } from './nodeDefExpressionEvaluator'\nexport type { CategoryItemProvider, TaxonProvider } from './nodeDefExpressionEvaluator'\n\nexport type {\n  NodeDef,\n  NodeDefLayout,\n  NodeDefMeta,\n  NodeDefProps,\n  NodeDefPropsWithLayout,\n  NodeDefBoolean,\n  NodeDefBooleanProps,\n  NodeDefCode,\n  NodeDefCodeLayout,\n  NodeDefCodeProps,\n  NodeDefCoordinate,\n  NodeDefCoordinateProps,\n  NodeDefDate,\n  NodeDefDecimal,\n  NodeDefDecimalProps,\n  NodeDefEntity,\n  NodeDefEntityChildPosition,\n  NodeDefEntityLayout,\n  NodeDefEntityProps,\n  NodeDefPrintOrientation,\n  NodeDefFile,\n  NodeDefFileProps,\n  NodeDefFormHeader,\n  NodeDefFormHeaderProps,\n  NodeDefInteger,\n  NodeDefPropsAdvanced,\n  NodeDefTaxon,\n  NodeDefTaxonProps,\n  NodeDefText,\n  NodeDefTextProps,\n  NodeDefTextLayout,\n  NodeDefTime,\n  NodeDefTimeProps,\n  NodeDefExpression,\n  NodeDefMap,\n  NodeDefService,\n  NodeDefValidations,\n} from './nodeDef'\n\nexport {\n  NodePointers,\n  RecordCloner,\n  RecordFactory,\n  RecordFixer,\n  Records,\n  RECORD_STEP_DEFAULT,\n  RecordExpressionEvaluator,\n  RecordNodesUpdater,\n  RecordPrettyPrinter,\n  RecordUpdater,\n  RecordUpdateResult,\n  RecordValidator,\n  RecordValidations,\n} from './record'\nexport type {\n  AttributeValidatorParams,\n  AttributesValidatorParams,\n  NodeCreateParams,\n  NodesUpdateParams,\n  Record,\n  Record as ArenaRecord,\n  RecordExpressionContext,\n  RecordExpressionEvaluationContext,\n  RecordService,\n  RecordUpdateOptions,\n  RecordValidatorParams,\n  SortedAttributesValidatorParams,\n} from './record'\n\nexport { ServiceRegistry, ServiceType } from './registry'\n\nexport { DEFAULT_SRS, DEFAULT_SRS_INDEX, SRSFactory } from './srs'\nexport type { SRS, SRSIndex } from './srs'\n\nexport {\n  NodeDefsFixer,\n  SurveyDocImages,\n  SurveyDocImageFactory,\n  SurveyDocPlace,\n  SurveyDependencyType,\n  SurveyFactory,\n  SurveyFileFactory,\n  SurveyFileType,\n  SurveyRefDataFactory,\n  SurveySecurityProp,\n  Surveys,\n  surveyDocImagePropKeys,\n  surveySecurityDefaults,\n  defaultCycle,\n} from './survey'\nexport type {\n  Survey,\n  SurveyCycle,\n  SurveyDependency,\n  SurveyDependencyGraph,\n  SurveyDocImage,\n  SurveyDocImageFactoryParams,\n  SurveyDocImageProps,\n  SurveyFile,\n  SurveyFileFactoryParams,\n  SurveyFileProps,\n  SurveyProps,\n  SurveyRefData,\n  SurveySecurity,\n  SurveyService,\n} from './survey'\n\nexport { Taxa, Taxonomies, TaxonomyFactory, TaxonFactory, TaxonGenerator, VernacularNameFactory } from './taxonomy'\nexport type {\n  VernacularNameParams,\n  TaxonomyFactoryParams,\n  TaxonFactoryParams,\n  Taxonomy,\n  TaxonomyService,\n  VernacularNameProps,\n  VernacularName,\n  TaxonProps,\n  Taxon,\n  TaxonomyProps,\n  TaxonService,\n} from './taxonomy'\n\nexport { SurveyBuilder, SurveyObjectBuilders } from './tests/builder/surveyBuilder'\nexport { RecordBuilder, RecordNodeBuilders } from './tests/builder/recordBuilder'\n\nexport {\n  Arrays,\n  DateFormats,\n  Dates,\n  FileNames,\n  FileProcessor,\n  Numbers,\n  Objects,\n  Promises,\n  Queue,\n  RetryProcessor,\n  Strings,\n  UnitOfTime,\n  UUIDs,\n  Versions,\n} from './utils'\n\nexport type { FileProcessorConstructorArgs, ParsedVersion } from './utils'\n\nexport {\n  FieldValidators,\n  ValidationFactory,\n  ValidationResultFactory,\n  ValidationResults,\n  Validations,\n  ValidationSeverity,\n  Validator,\n  ValidatorErrorKeys,\n} from './validation'\nexport type { FieldValidator, Validation, ValidationFields, ValidationResult, ValidationCounts } from './validation'\n"]}

package/dist/job/JobBase.d.ts

@@ -9,6 +9,27 @@ export interface JobConstructor {
     new <C extends JobContext, R>(context: C, innerJobs?: JobBase<any>[]): JobBase<C, R>;
     readonly prototype: JobBase<any, any>;
 }
+/**
+ * Asynchronous task handler.
+ *
+ * Status workflow:
+ * - pending
+ * - running
+ * - (end)
+ * -- succeeded
+ * -- failed
+ * -- canceled
+ *
+ * Methods that can be overwritten by subclasses:
+ * - shouldExecute (in tx)
+ * - onStart (in tx)
+ * - execute (in tx)
+ * - beforeSuccess (in tx)
+ * - generateResult (in tx)
+ * - beforeEnd (in tx)
+ * - onEnd (out of tx)
+ * - getErrorInfo
+ */
 export declare abstract class JobBase<C extends JobContext, R = undefined> implements Job<R> {
     static readonly keysContext: {
         surveyId: string;
@@ -48,6 +69,10 @@ export declare abstract class JobBase<C extends JobContext, R = undefined> imple
     protected getContextProp<T = any>(prop: string, defaultValue?: T | null): T | null;
     protected setContext(context: Partial<C>): void;
     protected deleteContextProps(...propNames: string[]): void;
+    /**
+     * Registers the listener notified of job events (status changes and progress).
+     * Only one listener can be registered at a time; registering a new one replaces the previous one.
+     */
     onEvent(listener: (event: JobEvent) => void): this;
     isPending(): boolean;
     isRunning(): boolean;
@@ -63,21 +88,70 @@ export declare abstract class JobBase<C extends JobContext, R = undefined> imple
         canceledByAdmin?: boolean;
     }): Promise<void>;
     private isCancelRequestedOrNotRunning;
+    /**
+     * Runs beforeEnd only once (it can be called by cancel() and when the job execution ends).
+     */
     private runBeforeEnd;
     start(client?: any): Promise<void>;
     private executeInTransaction;
+    /**
+     * Generates a plain JSON-serializable representation of the job, including its inner jobs.
+     */
     toJSON(): JobSerialized<R>;
     private executeJobs;
+    /**
+     * Runs the job's own work when it has no inner jobs. Default implementation is a no-op, so
+     * subclasses that only supply inner jobs (and never override this) don't need to. It also means
+     * a subclass can safely call `super.execute()` defensively without knowing whether any ancestor
+     * overrides it - if this were `abstract` instead, TypeScript would compile away any runtime
+     * property for it entirely, so `super.execute()` would throw the moment no ancestor overrides it
+     * (confirmed in production: a subclass whose immediate parent didn't override `execute()` crashed
+     * with "(intermediate value).execute is not a function" the instant it called `super.execute()`).
+     */
     protected execute(): Promise<void>;
+    /**
+     * Determines whether the job should actually run.
+     * When it returns false, "execute" (or the inner jobs) will be skipped, but the job will still succeed.
+     */
     protected shouldExecute(): Promise<boolean>;
     protected incrementProcessedItems(incrementBy?: number): void;
     protected setStatus(status: JobStatus): Promise<void>;
+    /**
+     * Inner job event handler.
+     */
     protected onInnerJobEvent(event: JobEvent): Promise<void>;
+    /**
+     * Called when the job just has been started.
+     */
     protected onStart(): Promise<void>;
+    /**
+     * Called before beforeEnd only if the status will change to 'success'.
+     * Default implementation stores the value returned by generateResult() via setResult().
+     * It runs INSIDE the current db transaction.
+     */
     protected beforeSuccess(): Promise<void>;
+    /**
+     * Computes the value beforeSuccess() will store as this job's result.
+     * Default implementation returns whatever is already in `this.result`
+     * (e.g. accumulated via earlier setResult() calls during execute()).
+     */
     protected generateResult(): Promise<R | undefined>;
+    /**
+     * Updates this job's result. When both the current and incoming values are plain objects,
+     * they are merged (Object.assign); otherwise the incoming value replaces the current one.
+     * This keeps it safe for subclasses whose result is a primitive (e.g. a plain number) as
+     * well as ones that build an object result incrementally across multiple setResult() calls.
+     */
     protected setResult(result: R | undefined): void;
+    /**
+     * Called before onEnd. Useful for flushing resources used by the job before it terminates completely.
+     * It runs INSIDE the current db transaction.
+     */
     protected beforeEnd(): Promise<void>;
+    /**
+     * Called when the job status changes to success, failed or canceled
+     * (it runs OUTSIDE of the current db transaction)
+     */
     protected onEnd(): Promise<void>;
     protected addError(error: any, errorKey?: string): void;
     protected throwError(errorKey: string, params?: Dictionary<any>): void;
@@ -94,7 +168,14 @@ export declare abstract class JobBase<C extends JobContext, R = undefined> imple
     private calculatePartialProgress;
     private calculateProgressPercent;
     private calculateElapsedMillis;
+    /**
+     * Notifies a progress event to the registered listener, throttled so that fast-changing
+     * progress does not flood consumers (e.g. web socket clients).
+     */
     private notifyProgress;
+    /**
+     * Cancels any pending throttled progress notification and resets the throttle state.
+     */
     private cancelNotifyProgress;
     private notifyEvent;
 }

package/dist/job/JobBase.js

@@ -15,6 +15,27 @@ const utils_1 = require("../utils");
 const jobEvent_1 = require("./jobEvent");
 const status_1 = require("./status");
 const PROGRESS_NOTIFICATION_THROTTLE_MILLIS = 1000;
+/**
+ * Asynchronous task handler.
+ *
+ * Status workflow:
+ * - pending
+ * - running
+ * - (end)
+ * -- succeeded
+ * -- failed
+ * -- canceled
+ *
+ * Methods that can be overwritten by subclasses:
+ * - shouldExecute (in tx)
+ * - onStart (in tx)
+ * - execute (in tx)
+ * - beforeSuccess (in tx)
+ * - generateResult (in tx)
+ * - beforeEnd (in tx)
+ * - onEnd (out of tx)
+ * - getErrorInfo
+ */
 class JobBase {
     constructor(context, innerJobs = []) {
         var _a;
@@ -27,14 +48,18 @@ class JobBase {
         this.progressThrottleTimeoutId = undefined;
         this.progressThrottleLastRunTime = 0;
         this._stopOnInnerJobFailure = true;
+        // set as soon as cancel() is called (the canceled status is set only after beforeEnd has run)
         this.cancelRequested = false;
         this.beforeEndCalled = false;
+        // inner job events are handled in sequence; executeJobs waits for them before going on
         this.innerJobEventsQueue = Promise.resolve();
         this.context = Object.assign({}, context);
         this.innerJobs = innerJobs;
         this.uuid = utils_1.UUIDs.v4();
         this.type = (_a = this.context.type) !== null && _a !== void 0 ? _a : this.constructor.name;
         this.total = innerJobs.length > 0 ? innerJobs.length : 1;
+        // Created last, so that createLogger() overrides can safely build the logger name out of
+        // the job identity (e.g. arena's `Job <ClassName> (<uuid>)` log correlation id).
         this.logger = this.createLogger();
     }
     get processed() {
@@ -75,6 +100,10 @@ class JobBase {
             delete this.context[propName];
         });
     }
+    /**
+     * Registers the listener notified of job events (status changes and progress).
+     * Only one listener can be registered at a time; registering a new one replaces the previous one.
+     */
     onEvent(listener) {
         this.eventListener = listener;
         return this;
@@ -121,10 +150,13 @@ class JobBase {
             this.cancelRequested = true;
             const currentInnerJob = this.getCurrentInnerJob();
             if (currentInnerJob === null || currentInnerJob === void 0 ? void 0 : currentInnerJob.isRunning()) {
+                // the parent job status will be set to canceled when handling the canceled event of the inner job
                 yield currentInnerJob.cancel({ canceledByAdmin });
                 return;
             }
+            // no inner job running (job without inner jobs, or between two inner jobs)
             this.canceledByAdmin = canceledByAdmin;
+            // release the resources (temp files/directories, streams) allocated before the cancellation
             yield this.runBeforeEnd();
             yield this.setStatus(status_1.JobStatus.canceled);
         });
@@ -132,6 +164,9 @@ class JobBase {
     isCancelRequestedOrNotRunning() {
         return this.cancelRequested || !this.isRunning();
     }
+    /**
+     * Runs beforeEnd only once (it can be called by cancel() and when the job execution ends).
+     */
     runBeforeEnd() {
         return __awaiter(this, void 0, void 0, function* () {
             if (this.beforeEndCalled)
@@ -189,6 +224,7 @@ class JobBase {
                 }
             }
             finally {
+                // runs only if not already run by cancel()
                 yield this.runBeforeEnd();
                 this.context.tx = undefined;
             }
@@ -197,6 +233,9 @@ class JobBase {
             }
         });
     }
+    /**
+     * Generates a plain JSON-serializable representation of the job, including its inner jobs.
+     */
     toJSON() {
         const { errors, processed, result, status, total, type, userUuid, uuid } = this;
         return {
@@ -233,13 +272,20 @@ class JobBase {
                 }
                 currentInnerJob.context = this.context;
                 currentInnerJob.onEvent((event) => {
+                    // handle the inner job events in sequence; errors are logged (they would be unhandled rejections otherwise)
                     this.innerJobEventsQueue = this.innerJobEventsQueue
                         .then(() => this.onInnerJobEvent(event))
                         .catch((error) => { var _a; return this.logError((_a = error === null || error === void 0 ? void 0 : error.stack) !== null && _a !== void 0 ? _a : error); });
                 });
+                // The inner job shares this very context object, and its own start()/executeInTransaction()
+                // clear `context.tx` when they terminate: without saving and restoring it here, the first
+                // inner job would wipe the parent's transaction handle, leaving every following inner job
+                // (and the parent's own beforeSuccess()/beforeEnd()) running outside of the transaction.
+                // start() never throws (it swallows/records errors internally), so a plain restore is enough.
                 const parentTx = this.context.tx;
                 yield currentInnerJob.start(parentTx);
                 this.context.tx = parentTx;
+                // the inner job events (e.g. canceled, failed) update the status of this job
                 yield this.innerJobEventsQueue;
                 if (this.cancelRequested || this.isCanceled() || currentInnerJob.isCanceled()) {
                     break;
@@ -254,10 +300,24 @@ class JobBase {
             this.logDebug(`- ${this.processed} inner jobs processed successfully`);
         });
     }
+    /**
+     * Runs the job's own work when it has no inner jobs. Default implementation is a no-op, so
+     * subclasses that only supply inner jobs (and never override this) don't need to. It also means
+     * a subclass can safely call `super.execute()` defensively without knowing whether any ancestor
+     * overrides it - if this were `abstract` instead, TypeScript would compile away any runtime
+     * property for it entirely, so `super.execute()` would throw the moment no ancestor overrides it
+     * (confirmed in production: a subclass whose immediate parent didn't override `execute()` crashed
+     * with "(intermediate value).execute is not a function" the instant it called `super.execute()`).
+     */
     execute() {
         return __awaiter(this, void 0, void 0, function* () {
+            // to be extended by subclasses
         });
     }
+    /**
+     * Determines whether the job should actually run.
+     * When it returns false, "execute" (or the inner jobs) will be skipped, but the job will still succeed.
+     */
     shouldExecute() {
         return Promise.resolve(true);
     }
@@ -280,6 +340,9 @@ class JobBase {
             this.notifyEvent(event);
         });
     }
+    /**
+     * Inner job event handler.
+     */
     onInnerJobEvent(event) {
         return __awaiter(this, void 0, void 0, function* () {
             var _a, _b, _c, _d;
@@ -289,6 +352,7 @@ class JobBase {
                 return this.setStatus(status);
             }
             if (status === status_1.JobStatus.failed) {
+                // report the errors of the failed inner job in the failed event (and in the errors) of this job
                 Object.assign(this.errors, (_d = (_c = this.getCurrentInnerJob()) === null || _c === void 0 ? void 0 : _c.errors) !== null && _d !== void 0 ? _d : {});
                 return this.setStatus(status);
             }
@@ -304,20 +368,39 @@ class JobBase {
             this.logDebug(`Unknown inner job status: ${status}`);
         });
     }
+    /**
+     * Called when the job just has been started.
+     */
     onStart() {
         return __awaiter(this, void 0, void 0, function* () {
             this.startTime = new Date();
             yield this.setStatus(status_1.JobStatus.running);
         });
     }
+    /**
+     * Called before beforeEnd only if the status will change to 'success'.
+     * Default implementation stores the value returned by generateResult() via setResult().
+     * It runs INSIDE the current db transaction.
+     */
     beforeSuccess() {
         return __awaiter(this, void 0, void 0, function* () {
             this.setResult(yield this.generateResult());
         });
     }
+    /**
+     * Computes the value beforeSuccess() will store as this job's result.
+     * Default implementation returns whatever is already in `this.result`
+     * (e.g. accumulated via earlier setResult() calls during execute()).
+     */
     generateResult() {
         return Promise.resolve(this.result);
     }
+    /**
+     * Updates this job's result. When both the current and incoming values are plain objects,
+     * they are merged (Object.assign); otherwise the incoming value replaces the current one.
+     * This keeps it safe for subclasses whose result is a primitive (e.g. a plain number) as
+     * well as ones that build an object result incrementally across multiple setResult() calls.
+     */
     setResult(result) {
         if (result && typeof result === 'object' && this.result && typeof this.result === 'object') {
             Object.assign(this.result, result);
@@ -326,10 +409,18 @@ class JobBase {
             this.result = result;
         }
     }
+    /**
+     * Called before onEnd. Useful for flushing resources used by the job before it terminates completely.
+     * It runs INSIDE the current db transaction.
+     */
     beforeEnd() {
         this.logDebug('Cleanup');
         return Promise.resolve();
     }
+    /**
+     * Called when the job status changes to success, failed or canceled
+     * (it runs OUTSIDE of the current db transaction)
+     */
     onEnd() {
         this.endTime = new Date();
         this.cancelNotifyProgress();
@@ -340,6 +431,7 @@ class JobBase {
         this.errors[key] = error;
     }
     throwError(errorKey, params) {
+        // SystemError: getErrorInfo will report the translatable key instead of a generic error
         throw new error_1.SystemError(errorKey, params);
     }
     getErrorInfo(error) {
@@ -391,6 +483,10 @@ class JobBase {
             return 0;
         return ((_a = this.endTime) !== null && _a !== void 0 ? _a : new Date()).getTime() - this.startTime.getTime();
     }
+    /**
+     * Notifies a progress event to the registered listener, throttled so that fast-changing
+     * progress does not flood consumers (e.g. web socket clients).
+     */
     notifyProgress() {
         const run = () => {
             this.progressThrottleTimeoutId = undefined;
@@ -412,6 +508,9 @@ class JobBase {
             this.progressThrottleTimeoutId = setTimeout(run, PROGRESS_NOTIFICATION_THROTTLE_MILLIS - elapsed);
         }
     }
+    /**
+     * Cancels any pending throttled progress notification and resets the throttle state.
+     */
     cancelNotifyProgress() {
         if (this.progressThrottleTimeoutId) {
             clearTimeout(this.progressThrottleTimeoutId);