bajo-spatial 2.2.0 → 2.3.0

package/index.js

@@ -1,24 +1,47 @@
 /**
- * Plugin factory
+ * Plugin factory.
+ *
+ * **Never** call this function directly!!! It's only-meant to be called by the {@link https://ardhi.github.io/bajo|Bajo framework} during plugin initialization.
  *
  * @param {string} pkgName - NPM package name
- * @returns {class}
+ * @returns {class} BajoSpatial
  */
 async function factory (pkgName) {
   const me = this
 
   /**
-   * BajoSpatial class
+   * BajoSpatial class definition
    *
    * @class
    */
   class BajoSpatial extends this.app.baseClass.Base {
+    /**
+     * Creates an instance of BajoSpatial.
+     */
     constructor () {
       super(pkgName, me.app)
+      /**
+       * @property {object} config - Configuration object
+       */
       this.config = {}
     }
 
-    buildBboxQuery = async ({ bbox, query = {}, model, options = {} } = {}) => {
+    /**
+     * Builds a bounding box query for a given model.
+     *
+     * @async
+     * @method
+     * @param {object} params - Parameters for building the query.
+     * @param {string} params.bbox - Bounding box coordinates.
+     * @param {object} [params.query={}] - Existing query object to merge with.
+     * @param {object} params.model - {@link https://ardhi.github.io/dobo|Dobo model} to apply the query to.
+     * @param {object} [params.options={}] - Additional options for query building.
+     * @param {string} [params.options.bboxLatField='lat'] - Latitude field name in the model.
+     * @param {string} [params.options.bboxLngField='lng'] - Longitude field name in the model.
+     * @returns {object} - The modified query object with bounding box conditions.
+     */
+    buildBboxQuery = async (params = {}) => {
+      let { bbox, query = {}, model, options = {} } = params
       const { merge, isEmpty } = this.app.lib._
       const props = model.properties.map(item => item.name)
       const { bboxLatField = 'lat', bboxLngField = 'lng' } = options
@@ -42,6 +65,15 @@ async function factory (pkgName) {
       return query
     }
 
+    /**
+     * Gets the bounding box for a given country ID.
+     * Requires the `bajoCommonDb` and `dobo` plugins to be available. Otherwise, it will return undefined.
+     *
+     * @async
+     * @method
+     * @param {string} item - Country ID.
+     * @returns {Promise<string|undefined>} - The bounding box string or undefined if not found.
+     */
     getCountryBbox = async (item) => {
       item = item + ''
       if (item.includes(',')) return
@@ -52,6 +84,14 @@ async function factory (pkgName) {
       throw this.error('Invalid country bbox \'%s\'', item, { statusCode: 400 })
     }
 
+    /**
+     * Parses a bounding box input.
+     *
+     * @async
+     * @method
+     * @param {string} input - The bounding box input, either a country ID or coordinates.
+     * @returns {Promise<Array<number>|undefined>} - The parsed bounding box coordinates or undefined if not found.
+     */
     parseBbox = async (input) => {
       const { isSet } = this.app.lib.aneka
       if (input.length === 2 && !input.includes(',')) return await this.getCountryBbox(input)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bajo-spatial",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Spatial functions for Bajo Framework",
   "main": "index.js",
   "scripts": {
@@ -34,7 +34,9 @@
     "geolib": "^3.3.4"
   },
   "devDependencies": {
+    "chai": "^6.2.2",
     "clean-jsdoc-theme": "^4.3.0",
-    "jsdoc-plugin-intersection": "^1.0.4"
+    "jsdoc-plugin-intersection": "^1.0.4",
+    "mocha": "^11.7.6"
   }
 }

package/test/bajo-spatial.test.js

@@ -0,0 +1,181 @@
+/* global describe, it, beforeEach */
+
+import { expect } from 'chai'
+
+import factory from '../index.js'
+
+describe('BajoSpatial', () => {
+  let app
+  let BajoSpatial
+  let spatial
+
+  beforeEach(async () => {
+    app = {
+      lib: {
+        _: {
+          merge: (target, source) => Object.assign(target, source),
+          isEmpty: (value) => {
+            if (value == null) return true
+            if (Array.isArray(value) || typeof value === 'string') return value.length === 0
+            if (typeof value === 'object') return Object.keys(value).length === 0
+            return false
+          }
+        },
+        aneka: {
+          isSet: (value) => value !== null && value !== undefined
+        }
+      },
+      baseClass: {
+        Base: class Base {
+          constructor (pkgName, appRef) {
+            this.pkgName = pkgName
+            this.app = appRef
+          }
+
+          error (msg, item) {
+            const text = msg.replace('%s', item)
+            return new Error(text)
+          }
+        }
+      }
+    }
+
+    BajoSpatial = await factory.call({ app }, 'bajo-spatial')
+    spatial = new BajoSpatial()
+  })
+
+  it('initializes with empty config object', () => {
+    expect(spatial.config).to.deep.equal({})
+  })
+
+  it('parseBbox parses valid coordinates', async () => {
+    const result = await spatial.parseBbox('100,-10,120,10')
+
+    expect(result).to.deep.equal([100, -10, 120, 10])
+  })
+
+  it('parseBbox throws for invalid coordinates', async () => {
+    try {
+      await spatial.parseBbox('100,-10,200,10')
+      expect.fail('Expected parseBbox to throw')
+    } catch (err) {
+      expect(err.message).to.equal("Invalid bbox '100,-10,200,10'")
+    }
+  })
+
+  it('parseBbox resolves country code through getCountryBbox', async () => {
+    spatial.getCountryBbox = async (code) => {
+      expect(code).to.equal('ID')
+      return [95, -11, 141, 6]
+    }
+
+    const result = await spatial.parseBbox('ID')
+
+    expect(result).to.deep.equal([95, -11, 141, 6])
+  })
+
+  it('buildBboxQuery returns merged query when fields exist', async () => {
+    const model = { properties: [{ name: 'lat' }, { name: 'lng' }] }
+
+    const result = await spatial.buildBboxQuery({
+      bbox: '100,-10,120,10',
+      query: { status: 'active' },
+      model
+    })
+
+    expect(result).to.deep.equal({
+      status: 'active',
+      lng: { $gte: 100, $lte: 120 },
+      lat: { $gte: -10, $lte: 10 }
+    })
+  })
+
+  it('buildBboxQuery appends bbox query to $and', async () => {
+    const model = { properties: [{ name: 'lat' }, { name: 'lng' }] }
+    const query = { $and: [{ status: 'active' }] }
+
+    const result = await spatial.buildBboxQuery({
+      bbox: '100,-10,120,10',
+      query,
+      model
+    })
+
+    expect(result.$and).to.have.lengthOf(2)
+    expect(result.$and[1]).to.deep.equal({
+      lng: { $gte: 100, $lte: 120 },
+      lat: { $gte: -10, $lte: 10 }
+    })
+  })
+
+  it('buildBboxQuery converts $or query into $and with bbox query', async () => {
+    const model = { properties: [{ name: 'lat' }, { name: 'lng' }] }
+    const query = { $or: [{ status: 'active' }, { status: 'pending' }] }
+
+    const result = await spatial.buildBboxQuery({
+      bbox: '100,-10,120,10',
+      query,
+      model
+    })
+
+    expect(result).to.deep.equal({
+      $and: [
+        [{ status: 'active' }, { status: 'pending' }],
+        {
+          lng: { $gte: 100, $lte: 120 },
+          lat: { $gte: -10, $lte: 10 }
+        }
+      ]
+    })
+  })
+
+  it('buildBboxQuery returns original query when model fields are missing', async () => {
+    const model = { properties: [{ name: 'latitude' }, { name: 'longitude' }] }
+    const query = { status: 'active' }
+
+    const result = await spatial.buildBboxQuery({
+      bbox: '100,-10,120,10',
+      query,
+      model
+    })
+
+    expect(result).to.deep.equal({ status: 'active' })
+  })
+
+  it('getCountryBbox returns undefined for direct bbox string or missing dependencies', async () => {
+    expect(await spatial.getCountryBbox('1,2,3,4')).to.equal(undefined)
+    expect(await spatial.getCountryBbox('ID')).to.equal(undefined)
+  })
+
+  it('getCountryBbox returns bbox from CdbCountry model', async () => {
+    app.bajoCommonDb = {}
+    app.dobo = {
+      getModel: () => ({
+        getRecord: async (id, opts) => {
+          expect(id).to.equal('ID')
+          expect(opts).to.deep.equal({ throwNotFound: false })
+          return { bbox: '95,-11,141,6' }
+        }
+      })
+    }
+
+    const result = await spatial.getCountryBbox('ID')
+
+    expect(result).to.equal('95,-11,141,6')
+  })
+
+  it('getCountryBbox throws when country id is unknown', async () => {
+    app.bajoCommonDb = {}
+    app.dobo = {
+      getModel: () => ({
+        getRecord: async () => null
+      })
+    }
+
+    try {
+      await spatial.getCountryBbox('ID')
+      expect.fail('Expected getCountryBbox to throw')
+    } catch (err) {
+      expect(err.message).to.equal("Invalid country bbox 'ID'")
+    }
+  })
+})

package/wiki/CHANGES.md

@@ -1,5 +1,10 @@
 # Changes
 
+## 2026-06-27
+
+- [2.3.0] Add documentations
+- [2.3.0] Add tests
+
 ## 2026-01-07
 
 - [2.2.0] Ported to match ```bajo@2.2.x``` specs