meadow-endpoints 4.0.17 → 4.0.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "meadow-endpoints",
-  "version": "4.0.17",
+  "version": "4.0.18",
   "description": "Automatic API endpoints for Meadow data.",
   "main": "source/Meadow-Endpoints.js",
   "scripts": {

package/source/Meadow-Endpoints.js

@@ -82,6 +82,7 @@ class MeadowEndpoints
 
 			Upsert: require('./endpoints/upsert/Meadow-Endpoint-Upsert.js'),
 			Upserts: require('./endpoints/upsert/Meadow-Endpoint-BulkUpsert.js'),
+			UpsertsDetailed: require('./endpoints/upsert/Meadow-Endpoint-BulkUpsertDetailed.js'),
 
 			Delete: require('./endpoints/delete/Meadow-Endpoint-Delete.js'),
 			Undelete: require('./endpoints/delete/Meadow-Endpoint-Undelete.js'),
@@ -211,6 +212,7 @@ class MeadowEndpoints
 			this.connectRoute(pServiceServer, 'putWithBodyParser', `s`, this._Endpoints.Updates, `the internal behavior _Endpoints.Updates`);
 			this.connectRoute(pServiceServer, 'putWithBodyParser', `/Upsert`, this._Endpoints.Upsert, `the internal behavior _Endpoints.Upsert`);
 			this.connectRoute(pServiceServer, 'putWithBodyParser', `/Upserts`, this._Endpoints.Upserts, `the internal behavior _Endpoints.Upserts`);
+			this.connectRoute(pServiceServer, 'putWithBodyParser', `/Upserts/Detailed`, this._Endpoints.UpsertsDetailed, `the internal behavior _Endpoints.UpsertsDetailed`);
 		}
 		if (this._EnabledBehaviorSets.Delete)
 		{

package/source/endpoints/upsert/Meadow-Endpoint-BulkUpsert.js

@@ -40,11 +40,35 @@ const doAPIEndpointUpserts = function(pRequest, pResponse, fNext)
 			fBehaviorInjector(`UpsertBulk-PostOperation`),
 			(fStageComplete) =>
 			{
+				// Surface per-row error counts to the caller via response
+				// headers BEFORE streaming the success array. Without these,
+				// callers can only see "N records came back" and have no
+				// signal that other records were silently dropped (e.g.
+				// from a NOT NULL constraint or a column-too-long error).
+				// We keep the response body shape stable (bare array of
+				// upserted records) for back-compat — the headers are the
+				// non-breaking surface for the failure count + total.
+				let tmpInputCount = (tmpRequestState.BulkRecords && tmpRequestState.BulkRecords.length) || 0;
+				let tmpErrorCount = (tmpRequestState.ErrorRecords && tmpRequestState.ErrorRecords.length) || 0;
+				let tmpUpsertedCount = (tmpRequestState.UpsertedRecords && tmpRequestState.UpsertedRecords.length) || 0;
+				try
+				{
+					pResponse.header('X-Meadow-Upsert-Total', String(tmpInputCount));
+					pResponse.header('X-Meadow-Upsert-Succeeded', String(tmpUpsertedCount));
+					pResponse.header('X-Meadow-Upsert-Errored', String(tmpErrorCount));
+				}
+				catch (pHdrErr) { /* response.header may not exist on all servers; degrade silently */ }
+
 				return this.doStreamRecordArray(pResponse, marshalLiteList.call(this, tmpRequestState.UpsertedRecords, pRequest), fStageComplete);
 			},
 			(fStageComplete) =>
 			{
-				this.log.requestCompletedSuccessfully(pRequest, tmpRequestState, `Bulk upsert complete -- ${tmpRequestState.UpsertedRecords.length} records processed`);
+				let tmpUpsertedCount = (tmpRequestState.UpsertedRecords && tmpRequestState.UpsertedRecords.length) || 0;
+				let tmpErrorCount = (tmpRequestState.ErrorRecords && tmpRequestState.ErrorRecords.length) || 0;
+				let tmpMessage = (tmpErrorCount > 0)
+					? `Bulk upsert complete -- ${tmpUpsertedCount} records succeeded, ${tmpErrorCount} errored`
+					: `Bulk upsert complete -- ${tmpUpsertedCount} records processed`;
+				this.log.requestCompletedSuccessfully(pRequest, tmpRequestState, tmpMessage);
 				return fStageComplete();
 			}
 		], (pError) =>

package/source/endpoints/upsert/Meadow-Endpoint-BulkUpsertDetailed.js

@@ -0,0 +1,96 @@
+/**
+* Meadow Endpoint - Upsert a set of Records, with detailed envelope response.
+*
+* Same upsert pipeline as Meadow-Endpoint-BulkUpsert.js, but the
+* response body is an envelope:
+*
+*   {
+*     "Counts":          { "Total": N, "Succeeded": K, "Errored": M },
+*     "UpsertedRecords": [ ... lite-marshaled successes ... ],
+*     "ErrorRecords":    [ { "Record": {...}, "Operation": "...", "Error": "..." }, ... ]
+*   }
+*
+* The vanilla `/Upserts` endpoint streams a bare array of successes for
+* back-compat; this `/Upserts/Detailed` variant trades that compatibility
+* for full per-row error visibility. Same X-Meadow-Upsert-* response
+* headers are set on both.
+*/
+const doUpsert = require('./Meadow-Operation-Upsert.js');
+
+const marshalLiteList = require('../read/Meadow-Marshal-LiteList.js');
+
+const doAPIEndpointUpsertsDetailed = function(pRequest, pResponse, fNext)
+{
+	let tmpRequestState = this.initializeRequestState(pRequest, 'UpsertBulkDetailed');
+	let fBehaviorInjector = (pBehaviorHash) => { return (fStageComplete) => { this.BehaviorInjection.runBehavior(pBehaviorHash, this, pRequest, tmpRequestState, fStageComplete); }; };
+
+	tmpRequestState.CreatedRecords = [];
+	tmpRequestState.UpdatedRecords = [];
+	tmpRequestState.UpsertedRecords = [];
+	tmpRequestState.ErrorRecords = [];
+
+	this.waterfall(
+		[
+			(fStageComplete) =>
+			{
+				if (!Array.isArray(pRequest.body))
+				{
+					return fStageComplete(this.ErrorHandler.getError(`Record bulk upsert (detailed) failure - a valid array of records is required.`, 500));
+				}
+
+				tmpRequestState.BulkRecords = pRequest.body;
+
+				return fStageComplete();
+			},
+			fBehaviorInjector(`UpsertBulk-PreOperation`),
+			(fStageComplete) =>
+			{
+				this.eachLimit(tmpRequestState.BulkRecords, 1,
+					(pRecord, fCallback) =>
+					{
+						doUpsert.call(this, pRecord, pRequest, tmpRequestState, pResponse, fCallback);
+					}, fStageComplete);
+			},
+			fBehaviorInjector(`UpsertBulk-PostOperation`),
+			(fStageComplete) =>
+			{
+				let tmpInputCount = (tmpRequestState.BulkRecords && tmpRequestState.BulkRecords.length) || 0;
+				let tmpErrorCount = (tmpRequestState.ErrorRecords && tmpRequestState.ErrorRecords.length) || 0;
+				let tmpUpsertedCount = (tmpRequestState.UpsertedRecords && tmpRequestState.UpsertedRecords.length) || 0;
+
+				// Mirror the X-Meadow-Upsert-* headers from /Upserts so a
+				// caller can dispatch to either endpoint and read the same
+				// summary surface. The body envelope adds the per-row
+				// detail; the headers stay the structured summary.
+				try
+				{
+					pResponse.header('X-Meadow-Upsert-Total', String(tmpInputCount));
+					pResponse.header('X-Meadow-Upsert-Succeeded', String(tmpUpsertedCount));
+					pResponse.header('X-Meadow-Upsert-Errored', String(tmpErrorCount));
+				}
+				catch (pHdrErr) { /* response.header may not exist on all servers; degrade silently */ }
+
+				let tmpEnvelope = {
+					Counts: { Total: tmpInputCount, Succeeded: tmpUpsertedCount, Errored: tmpErrorCount },
+					UpsertedRecords: marshalLiteList.call(this, tmpRequestState.UpsertedRecords, pRequest),
+					ErrorRecords: tmpRequestState.ErrorRecords || []
+				};
+				pResponse.send(tmpEnvelope);
+				return fStageComplete();
+			},
+			(fStageComplete) =>
+			{
+				let tmpUpsertedCount = (tmpRequestState.UpsertedRecords && tmpRequestState.UpsertedRecords.length) || 0;
+				let tmpErrorCount = (tmpRequestState.ErrorRecords && tmpRequestState.ErrorRecords.length) || 0;
+				let tmpMessage = (tmpErrorCount > 0)
+					? `Bulk upsert (detailed) complete -- ${tmpUpsertedCount} records succeeded, ${tmpErrorCount} errored`
+					: `Bulk upsert (detailed) complete -- ${tmpUpsertedCount} records processed`;
+				this.log.requestCompletedSuccessfully(pRequest, tmpRequestState, tmpMessage);
+				return fStageComplete();
+			}
+		], (pError) =>
+		{
+			return this.ErrorHandler.handleErrorIfSet(pRequest, tmpRequestState, pResponse, pError, fNext);
+		});
+};
+module.exports = doAPIEndpointUpsertsDetailed;

package/source/endpoints/upsert/Meadow-Operation-Upsert.js

@@ -126,6 +126,21 @@ const doUpsert = function(pRecordToUpsert, pRequest, pRequestState, pResponse, f
 			if (pError)
 			{
 				tmpRequestState.Record.Error = pError;
+				// Surface per-row failures back to the bulk caller. The
+				// parent BulkUpsert endpoint reads this array to count
+				// errors and signal partial-success to clients via a
+				// response header. Without this push, individual upsert
+				// failures vanish silently and the bulk response only
+				// reflects what survived.
+				if (tmpRequestState.ParentRequestState && Array.isArray(tmpRequestState.ParentRequestState.ErrorRecords))
+				{
+					let tmpErrorMessage = (pError && (pError.message || pError.Error)) ? (pError.message || pError.Error) : String(pError);
+					tmpRequestState.ParentRequestState.ErrorRecords.push({
+						Record: tmpRequestState.Record,
+						Operation: tmpRequestState.Operation || 'Unknown',
+						Error: tmpErrorMessage
+					});
+				}
 			}
 			return fCallback();
 		});