@onehat/data 1.22.36 → 1.22.37

package/.github/copilot-instructions.md

@@ -0,0 +1,65 @@
+# Copilot Instructions
+
+## General Principles
+- Be direct, concise, and critical. Do not apologize, agree blindly, be sycophantic, or use flattery.
+- If a request is inefficient or flawed, point it out and suggest a better, more secure, or more idiomatic approach.
+- Use "Uncle Bob's Clean Code" principles as a baseline for code quality.
+- Prioritize clarity over cleverness.
+- Avoid unnecessary abstractions.
+- Prefer explicit code over magic.
+- Follow the project's existing coding style and conventions.
+- Do not introduce new dependencies unless absolutely necessary.
+- Always consider security implications and best practices.
+- Aim for full test coverage of new code, and suggest tests for existing code when appropriate.
+
+<!-- ## Coding Standards
+
+### Naming
+- Use descriptive variable and function names.
+- Do not abbreviate unless universally understood.
+- Use camelCase for JavaScript variables and functions.
+- Use PascalCase for React components.
+- Use snake_case for database columns.
+
+### Comments
+- Do not write obvious comments.
+- Only comment non-obvious business logic.
+- Prefer self-documenting code.
+
+## Error Handling
+- Always handle errors explicitly.
+- Do not swallow exceptions.
+- Return meaningful error messages.
+
+## Security
+- Never expose secrets or API keys.
+- Validate and sanitize all user input.
+- Use prepared statements for database queries.
+
+## Project-Specific Notes
+
+### Backend (PHP / CakePHP)
+- Follow PSR-12 formatting.
+- Use dependency injection where appropriate.
+- Do not use deprecated framework methods.
+- Prefer modern APIs over legacy helpers.
+
+### Frontend (React / Expo)
+- Use functional components only.
+- Prefer hooks over class components.
+- Avoid inline styles unless necessary.
+- Keep components under 200 lines.
+
+## Testing
+- Suggest unit tests for new logic.
+- Mock external dependencies.
+- Keep tests deterministic.
+
+## Performance
+- Avoid unnecessary loops.
+- Do not perform database queries inside loops.
+- Prefer memoization when appropriate.
+
+## Output Expectations
+- Produce production-ready code.
+- Avoid TODO comments unless necessary. -->

package/cypress/e2e/Repository/Repository.cy.js

@@ -1214,6 +1214,56 @@ describe('Repository Base', function() {
 			expect(unmapped).to.be.eql(data);
 		});
 
+		it('unmapData with scalar vs nested mapping conflict', function() {
+			// Test for the WorkOrders issue:
+			// work_orders__meter_reading (scalar) maps to 'meter_reading'
+			// meter_readings__id, meter_readings__date, etc. (nested) map to 'meter_reading.id', 'meter_reading.date', etc.
+			// The scalar mapping should take precedence, and nested properties should be skipped
+			const
+				schema = new Schema({
+					name: 'conflict_test',
+					model: {
+						idProperty: 'id',
+						displayProperty: 'name',
+						properties: [
+							{ name: 'id', type: 'int' },
+							{ name: 'name' },
+							{ name: 'meter_reading_scalar', mapping: 'meter_reading', type: 'int', defaultValue: null }, // scalar
+							{ name: 'meter_readings__id', mapping: 'meter_reading.id', type: 'int', defaultValue: null }, // nested (conflict!)
+							{ name: 'meter_readings__date', mapping: 'meter_reading.date', type: 'date', defaultValue: null }, // nested (conflict!)
+							{ name: 'meter_readings__value', mapping: 'meter_reading.value', type: 'int', defaultValue: null }, // nested (conflict!)
+						],
+					},
+				});
+			this.repository.schema = schema;
+
+			// Test unmapping: scalar value should be preserved, nested properties should be skipped
+			const mapped = {
+				id: 1,
+				name: 'test',
+				meter_reading_scalar: 42, // The scalar value that should be preserved
+				meter_readings__id: 999, // Should be skipped due to conflict
+				meter_readings__date: '2025-01-01', // Should be skipped due to conflict
+				meter_readings__value: 888, // Should be skipped due to conflict
+			};
+
+			const unmapped = this.repository.unmapData(mapped);
+			
+			// The scalar value should be preserved
+			expect(unmapped.meter_reading).to.equal(42);
+			
+			// The nested properties should NOT have created an object structure
+			// because they were skipped due to the conflict
+			if (typeof unmapped.meter_reading === 'number') {
+				// Correct: scalar value is intact and is a number
+				expect(unmapped.meter_reading).to.equal(42);
+			} else {
+				// If unmapped.meter_reading is an object, check that it wasn't corrupted by merge operations
+				// The test will show if there's a problem
+				expect(unmapped.meter_reading).to.be.a('number');
+			}
+		});
+
 		it('toString', function() {
 			const str = this.repository.toString();
 			expect(str).to.be.eq('NullRepository {bar} - foo');

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@onehat/data",
-	"version": "1.22.36",
+	"version": "1.22.37",
 	"description": "JS data modeling package with adapters for many storage mediums.",
 	"main": "src/index.js",
 	"type": "module",

package/src/Repository/Repository.js

@@ -2196,12 +2196,20 @@ export default class Repository extends EventEmitter {
 			throw Error('No properties defined!');
 		}
 
-		// Simply the definitions
+		// Build property maps for conflict detection
 		const
 			UNMAPPED = 'UNMAPPED',
-			properties = {};
+			properties = {},
+			scalarRoots = new Set(); // Tracks root paths that are bound to scalar properties
+		
 		_.each(propertiesDef, (def) => {
-			properties[def.name] = def.mapping || UNMAPPED;
+			const mapping = def.mapping || UNMAPPED;
+			properties[def.name] = mapping;
+			
+			// Track scalar mappings (single-level) to detect conflicts with nested properties
+			if (mapping !== UNMAPPED && !mapping.includes('.')) {
+				scalarRoots.add(mapping);
+			}
 		});
 
 		// Build the unmapped data
@@ -2213,10 +2221,18 @@ export default class Repository extends EventEmitter {
 				unmappedData[field] = value;
 			} else {
 				// This is the more complicated one. Need to build up the hierarchy of unmapped data
+				const mapStack = mapping.split('.');
+				
+				// CONFLICT DETECTION:
+				// If this property has a nested mapping (a.b.c) and a scalar property already
+				// maps to the root (a), skip this property to avoid overwriting the scalar value.
+				// This prevents: work_orders__meter_reading (scalar, maps to 'meter_reading')
+				// from being overwritten by meter_readings__id (nested, maps to 'meter_reading.id')
+				if (mapStack.length > 1 && scalarRoots.has(mapStack[0])) {
+					return; // Skip this nested property to preserve the scalar value
+				}
 
-				const
-					mapStack = mapping.split('.'),
-					rawValue = value;
+				const rawValue = value;
 		
 				// Build up the hierarchy
 				let thisValue = {},

package/src/Schema/Schema.js

@@ -173,6 +173,7 @@ export default class Schema extends EventEmitter {
 		this.isDestroyed = false;
 
 		this.normalizeRepositoryConfig();
+		this._validatePropertyMappings();
 		
 		this.registerEvents([
 			'destroy',
@@ -189,6 +190,62 @@ export default class Schema extends EventEmitter {
 		}
 	}
 
+	/**
+	 * Validates property mappings to detect conflicts between scalar and nested properties.
+	 * Warns if a scalar property maps to a path that is also used as a root path by nested properties.
+	 * Example conflict:
+	 * - work_orders__meter_reading maps to 'meter_reading' (scalar)
+	 * - meter_readings__id maps to 'meter_reading.id' (nested, uses 'meter_reading' as root)
+	 * This conflict can cause the scalar value to be overwritten by an object.
+	 * @private
+	 */
+	_validatePropertyMappings = () => {
+		if (!this.model || !this.model.properties || this.model.properties.length === 0) {
+			return;
+		}
+
+		const mappings = {};
+		const scalarRoots = new Set();
+
+		// First pass: collect all mappings and identify scalar roots
+		_.each(this.model.properties, (property) => {
+			if (!property.mapping) {
+				return;
+			}
+			const mapping = property.mapping;
+			if (!mappings[mapping]) {
+				mappings[mapping] = [];
+			}
+			mappings[mapping].push(property.name);
+
+			// If this is a scalar mapping (no dots), track the root
+			if (!mapping.includes('.')) {
+				scalarRoots.add(mapping);
+			}
+		});
+
+		// Second pass: detect conflicts
+		_.each(this.model.properties, (property) => {
+			if (!property.mapping) {
+				return;
+			}
+			const mapping = property.mapping;
+			const mapStack = mapping.split('.');
+
+			// Check if this is a nested property (has dots) and conflicts with a scalar root
+			if (mapStack.length > 1 && scalarRoots.has(mapStack[0])) {
+				console.warn(
+					`[OneHatData Schema Warning] Scalar-vs-nested property mapping conflict in schema "${this.name}": ` +
+					`Property "${property.name}" (mapping: "${mapping}") has a nested path, ` +
+					`but another property maps to the scalar root "${mapStack[0]}". ` +
+					`This can cause data conflicts during unmapping. ` +
+					`Consider renaming one of the properties or adjusting their mappings. ` +
+					`The unmapData() method will skip this nested property to preserve the scalar value.`
+				);
+			}
+		});
+	}
+
 	/**
 	 * Sets the Repository bound to this Schema.
 	 * @param {object} _boundRepository - The bound Repository

package/src/Util/Formatters.js

@@ -1,6 +1,6 @@
 import numeral from 'numeral';
 import moment from 'moment';
-import accounting from 'accounting-js';
+import * as accounting from 'accounting-js';
 import _ from 'lodash';
 
 class Formatters {

package/src/Util/Parsers.js

@@ -1,6 +1,6 @@
 import moment from 'moment';
 import momentAlt from 'relative-time-parser'; // Notice this version of moment is imported from 'relative-time-parser', and may be out of sync with our general 'moment' package
-import accounting from 'accounting-js';
+import * as accounting from 'accounting-js';
 // import * as chrono from 'chrono-node'; // Doesn't yet work in React Native ("SyntaxError: Invalid RegExp: Quantifier has nothing to repeat, js engine: hermes")  Github ticket: https://github.com/facebook/hermes/blob/main/doc/RegExp.md
 import _ from 'lodash';