@mountainpass/addressr 2.1.5 → 2.3.0

package/lib/client/elasticsearch.js

@@ -111,6 +111,14 @@ async function initIndex(esClient, clear, synonyms) {
             }
           }
         },
+        // ADR 026: range-number address expansion. Multi-valued text field
+        // populated with one expanded address per in-range number for range-
+        // numbered G-NAF docs (span cap 20). Absent on non-range docs
+        // (asymmetric population). No .raw sub-field — never sorted on.
+        sla_range_expanded: {
+          type: 'text',
+          analyzer: 'my_analyzer'
+        },
         confidence: {
           type: 'integer'
         },

package/lib/service/address-service.js

@@ -30,6 +30,7 @@ var _unzipStream = _interopRequireDefault(require("unzip-stream"));
 var _elasticsearch = require("../client/elasticsearch");
 var _streamDown = _interopRequireDefault(require("../utils/stream-down"));
 var _setLinkOptions = require("./set-link-options");
+var _rangeExpansion = require("./range-expansion");
 var _keyv = require("keyv");
 var _keyvFile = require("keyv-file");
 var _nodeCrypto = _interopRequireDefault(require("node:crypto"));
@@ -675,18 +676,34 @@ function mapAddressDetails(d, context, index, count) {
   };
   rval.mla = mapToMla(rval.structured);
   rval.sla = mapToSla(rval.mla);
-  if (rval.structured.flat != undefined) {
+  if (rval.structured.flat == undefined) {
+    // Symmetric ssla so BM25 summation across sla+ssla does not favour
+    // sub-unit docs over exact street-level matches. See ADR 025 / P007.
+    rval.ssla = rval.sla;
+  } else {
     rval.smla = mapToShortMla(rval.structured);
     rval.ssla = mapToSla(rval.smla);
   }
+  // ADR 026: asymmetric population of sla_range_expanded — one expanded
+  // alias per in-range number for range-numbered records up to SPAN_CAP.
+  // Non-range docs leave the field absent. expandRangeAliases returns []
+  // for span>cap or invalid inputs; in that case we keep the field absent
+  // rather than storing an empty array so OpenSearch _source stays clean.
+  if (rval.structured.number?.last?.number !== undefined) {
+    const s = rval.structured;
+    const streetType = s.street.type ? ` ${s.street.type.name}` : '';
+    const streetSuffix = s.street.suffix ? ` ${s.street.suffix.name}` : '';
+    rval.sla_range_expanded = (0, _rangeExpansion.expandRangeAliases)(Number(s.number.number), Number(s.number.last.number), `${s.street.name}${streetType}${streetSuffix}`, `${s.locality.name} ${s.state.abbreviation} ${s.postcode}`);
+    if (rval.sla_range_expanded.length === 0) {
+      delete rval.sla_range_expanded;
+    }
+  }
   if (count) {
     if (index % Math.ceil(count / 100) === 0) {
-      logger('addr', JSON.stringify(rval, undefined, 2));
       logger(`${index / count * 100}%`);
     }
   } else {
     if (index % 10_000 === 0) {
-      logger('addr', JSON.stringify(rval, undefined, 2));
       logger(`${index} rows`);
     }
   }
@@ -853,7 +870,14 @@ async function searchForAddress(searchString, p, pageSize = PAGE_SIZE) {
               }
             }, {
               multi_match: {
-                fields: ['sla', 'ssla'],
+                // ADR 026: sla_range_expanded added HERE ONLY (not in the
+                // bool_prefix clause above). phrase_prefix uses best_fields
+                // max with tie_breaker default 0.0, so an absent field on
+                // non-range docs contributes 0 to the max — no P007-shape
+                // asymmetry. Adding sla_range_expanded to the bool_prefix
+                // fields would reintroduce the summation asymmetry ADR 025
+                // resolved. DO NOT move this field into the clause above.
+                fields: ['sla', 'ssla', 'sla_range_expanded'],
                 query: searchString,
                 // fuzziness: 'AUTO',
                 type: 'phrase_prefix',
@@ -1590,20 +1614,27 @@ async function getAddress(addressId) {
     };
   } catch (error_) {
     error('error getting record from elastic search', error_);
-    if (error_.body.found === false) {
+    if (error_.body && error_.body.found === false) {
       return {
         statusCode: 404,
         json: {
           error: 'not found'
         }
       };
-    } else if (error_.body.error.type === 'index_not_found_exception') {
+    } else if (error_.body && error_.body.error && error_.body.error.type === 'index_not_found_exception') {
       return {
         statusCode: 503,
         json: {
           error: 'service unavailable'
         }
       };
+    } else if (error_.displayName === 'RequestTimeout') {
+      return {
+        statusCode: 504,
+        json: {
+          error: 'gateway timeout'
+        }
+      };
     } else {
       return {
         statusCode: 500,

package/lib/service/address-service.test.js

@@ -0,0 +1,131 @@
+"use strict";
+
+var _nodeTest = require("node:test");
+var _strict = _interopRequireDefault(require("node:assert/strict"));
+var _addressService = require("./address-service.js");
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+// Regression test for P007 / issue #375 — see ADR 025.
+// Sub-unit documents populate both `sla` and `ssla`; street-level documents
+// historically populated only `sla`, which caused BM25 per-field score
+// summation to favour sub-unit docs over exact street-level matches.
+// The fix: always populate `ssla` (= `sla` when no flat) so scoring is
+// symmetric across all documents.
+
+const baseAuthorityContext = {
+  Authority_Code_LOCALITY_CLASS_AUT_psv: [{
+    CODE: 'G',
+    NAME: 'GAZETTED LOCALITY'
+  }],
+  Authority_Code_STREET_CLASS_AUT_psv: [{
+    CODE: 'C',
+    NAME: 'CONFIRMED'
+  }],
+  Authority_Code_STREET_TYPE_AUT_psv: [{
+    CODE: 'ROAD',
+    NAME: 'RD',
+    DESCRIPTION: 'RD'
+  }],
+  Authority_Code_STREET_SUFFIX_AUT_psv: [],
+  Authority_Code_FLAT_TYPE_AUT_psv: [{
+    CODE: 'UNIT',
+    NAME: 'UNIT'
+  }],
+  Authority_Code_LEVEL_TYPE_AUT_psv: [],
+  Authority_Code_GEOCODED_LEVEL_TYPE_AUT_psv: [],
+  Authority_Code_GEOCODE_TYPE_AUT_psv: [],
+  Authority_Code_GEOCODE_RELIABILITY_AUT_psv: [],
+  state: 'QLD',
+  stateName: 'QUEENSLAND'
+};
+function buildContext(streetLocalityPid, streetLocality, localityPid, locality) {
+  const context = {
+    ...baseAuthorityContext,
+    streetLocalityIndexed: [],
+    localityIndexed: []
+  };
+  context.streetLocalityIndexed[streetLocalityPid] = streetLocality;
+  context.localityIndexed[localityPid] = locality;
+  return context;
+}
+const streetLocality = {
+  STREET_LOCALITY_PID: 'QLD180101',
+  DATE_CREATED: '2017-08-10',
+  DATE_RETIRED: '',
+  STREET_CLASS_CODE: 'C',
+  STREET_NAME: 'AERODROME',
+  STREET_TYPE_CODE: 'ROAD',
+  STREET_SUFFIX_CODE: '',
+  LOCALITY_PID: 'QLD69',
+  GNAF_STREET_PID: '3169537',
+  GNAF_STREET_CONFIDENCE: '2',
+  GNAF_RELIABILITY_CODE: '4'
+};
+const locality = {
+  LOCALITY_PID: 'QLD69',
+  DATE_CREATED: '2016-08-10',
+  DATE_RETIRED: '',
+  LOCALITY_NAME: 'APPLETHORPE',
+  PRIMARY_POSTCODE: '',
+  LOCALITY_CLASS_CODE: 'G',
+  STATE_PID: '3',
+  GNAF_LOCALITY_PID: '198011',
+  GNAF_RELIABILITY_CODE: '5'
+};
+function addressDetail(overrides = {}) {
+  return {
+    ADDRESS_DETAIL_PID: 'GAQLD163157353',
+    DATE_CREATED: '2010-04-21',
+    DATE_LAST_MODIFIED: '2018-08-03',
+    DATE_RETIRED: '',
+    BUILDING_NAME: '',
+    LOT_NUMBER_PREFIX: '',
+    LOT_NUMBER: '',
+    LOT_NUMBER_SUFFIX: '',
+    FLAT_TYPE_CODE: '',
+    FLAT_NUMBER_PREFIX: '',
+    FLAT_NUMBER: '',
+    FLAT_NUMBER_SUFFIX: '',
+    LEVEL_TYPE_CODE: '',
+    LEVEL_NUMBER_PREFIX: '',
+    LEVEL_NUMBER: '',
+    LEVEL_NUMBER_SUFFIX: '',
+    NUMBER_FIRST_PREFIX: '',
+    NUMBER_FIRST: '42',
+    NUMBER_FIRST_SUFFIX: '',
+    NUMBER_LAST_PREFIX: '',
+    NUMBER_LAST: '',
+    NUMBER_LAST_SUFFIX: '',
+    STREET_LOCALITY_PID: 'QLD180101',
+    LOCATION_DESCRIPTION: '',
+    LOCALITY_PID: 'QLD69',
+    ALIAS_PRINCIPAL: 'P',
+    POSTCODE: '4378',
+    PRIVATE_STREET: '',
+    LEGAL_PARCEL_ID: '',
+    CONFIDENCE: '0',
+    ADDRESS_SITE_PID: '',
+    LEVEL_GEOCODED_CODE: '',
+    PROPERTY_PID: '',
+    GNAF_PROPERTY_PID: '',
+    PRIMARY_SECONDARY: '',
+    ...overrides
+  };
+}
+(0, _nodeTest.describe)('P007 — ssla population (ADR 025)', () => {
+  (0, _nodeTest.it)('populates ssla equal to sla for a street-level address with no sub-unit', () => {
+    const context = buildContext('QLD180101', streetLocality, 'QLD69', locality);
+    const mapped = (0, _addressService.mapAddressDetails)(addressDetail(), context, 1, 1);
+    _strict.default.equal(typeof mapped.sla, 'string', 'sla must be present on every indexed address');
+    _strict.default.equal(mapped.ssla, mapped.sla, 'ssla must equal sla when the address has no sub-unit, so BM25 per-field ' + 'score summation across [sla, ssla] is symmetric across documents');
+  });
+  (0, _nodeTest.it)('populates ssla from the short-form address for a sub-unit', () => {
+    const context = buildContext('QLD180101', streetLocality, 'QLD69', locality);
+    const mapped = (0, _addressService.mapAddressDetails)(addressDetail({
+      FLAT_TYPE_CODE: 'UNIT',
+      FLAT_NUMBER: '1'
+    }), context, 1, 1);
+    _strict.default.ok(mapped.ssla && mapped.ssla !== mapped.sla, 'for a sub-unit, ssla should be the short-form address (distinct from sla)');
+    _strict.default.match(mapped.sla, /UNIT 1/, 'sub-unit sla includes the unit prefix');
+    _strict.default.doesNotMatch(mapped.ssla, /UNIT 1/, 'sub-unit ssla strips the unit prefix (preserving slash-form matching)');
+  });
+});

package/lib/service/range-expansion.js

@@ -0,0 +1,25 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.SPAN_CAP = void 0;
+exports.expandRangeAliases = expandRangeAliases;
+// ADR 026: range-number address expansion via multi-valued text alias field.
+// Pure helper — no I/O, no OpenSearch dependency. Invoked by `mapToMla` in
+// `service/address-service.js` when a G-NAF address has NUMBER_LAST set.
+// See docs/problems/015-range-number-addresses-not-searchable-by-base-number.open.md
+// for the range-distribution measurements that justify SPAN_CAP = 20.
+
+const SPAN_CAP = exports.SPAN_CAP = 20;
+function expandRangeAliases(first, last, streetPart, localityPart) {
+  if (!Number.isInteger(first) || !Number.isInteger(last)) return [];
+  if (first <= 0 || last <= 0) return [];
+  if (first >= last) return [];
+  if (last - first > SPAN_CAP) return [];
+  const aliases = [];
+  for (let n = first; n <= last; n++) {
+    aliases.push(`${n} ${streetPart}, ${localityPart}`);
+  }
+  return aliases;
+}

package/lib/src/waycharter-server.js

@@ -999,6 +999,12 @@ function startRest2Server() {
         }],
         headers: {
           etag: `"${_version.version}"`,
+          // Long-lived by design (P018 parked). New rels are added
+          // infrequently and every client page load fetches this for
+          // HATEOAS discovery; a short TTL would cost an origin
+          // round-trip per request. When the rel set does change,
+          // request a RapidAPI CF purge (natural expiry up to 7 days
+          // per P017 close notes).
           'cache-control': `public, max-age=${ONE_WEEK}`
         }
       };

package/lib/version.js

@@ -5,4 +5,4 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.version = void 0;
 // Generated by genversion.
-const version = exports.version = '2.1.5';
+const version = exports.version = '2.3.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mountainpass/addressr",
-  "version": "2.1.5",
+  "version": "2.3.0",
   "description": "Australian Address Validation, Search and Autocomplete",
   "author": {
     "name": "Mountain Pass",
@@ -107,6 +107,8 @@
     "dotest:cli2:geo": "ADDRESSR_ENABLE_GEO=1 ES_INDEX_NAME=test COVERED_STATES=OT TEST_PROFILE=cli2 cucumber-js -p cli2 -- --harmony_async_iteration",
     "cover:cli:geo": "nyc --report-dir coverage/cli --temp-dir coverage/cli/.nyc_output npm run test:cli:nogeo",
     "test:mcp:smoke": "node --test test/mcp/smoke.test.mjs",
+    "test:precommit": "node --test test/precommit/*.test.mjs",
+    "test:js": "node --test test/js/__tests__/*.test.mjs",
     "test:nodejs:QLD:nogeo": "PORT=$npm_package_config_localport ES_INDEX_NAME=test COVERED_STATES=QLD DEBUG=error,api,express:*,swagger-tools*,test,es TEST_PROFILE=default cucumber-js -p default -- --harmony_async_iteration",
     "test:nodejs:QLD:geo": "PORT=$npm_package_config_localport ADDRESSR_ENABLE_GEO=1 ES_INDEX_NAME=test-geo COVERED_STATES=QLD DEBUG=error,api,express:*,swagger-tools*,test,es TEST_PROFILE=default NODE_OPTIONS=--max_old_space_size=8196 cucumber-js -p default -- --harmony_async_iteration",
     "prebuildX": "npm run genversion && cat ./templates/LICENSE.md | envsubst '${PRODUCT},${VERSION},${COMPANY},${YEAR}' > ./LICENSE.md",
@@ -122,7 +124,8 @@
     "docker:push": "docker push \"mountainpass/addressr:${npm_package_version}\"",
     "postdocker:push": "docker push \"mountainpass/addressr:latest\"",
     "check-licenses": "license-checker --production --onlyAllow 'MIT;Apache-2.0;ISC;Custom: http://github.com/substack/node-bufferlist;Unlicense;BSD-2-Clause;BSD-3-Clause;WTFPL;0BSD;MIT*;Python-2.0;MPL-2.0;BlueOak-1.0.0' --summary",
-    "pre-commit": "lint-staged && npm run check-licenses",
+    "pre-commit": "lint-staged && npm run check-licenses && npm run check:not-cli2-tags && npm run test:js",
+    "check:not-cli2-tags": "node scripts/check-not-cli2-tags.mjs",
     "check-deps": "dry-aged-deps --check",
     "test:performance": "k6 run --out csv=target/stress.csv test/k6/script.js",
     "add-changeset": "changeset add --open",