meadow-endpoints 4.0.17 → 4.0.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "meadow-endpoints",
-  "version": "4.0.17",
+  "version": "4.0.19",
   "description": "Automatic API endpoints for Meadow data.",
   "main": "source/Meadow-Endpoints.js",
   "scripts": {
@@ -52,12 +52,12 @@
     "better-sqlite3": "^12.9.0",
     "chance": "^1.1.13",
     "gulp-util": "^3.0.8",
-    "meadow-connection-sqlite": "^1.0.18",
+    "meadow-connection-sqlite": "^1.0.19",
     "mysql2": "^3.22.1",
     "orator-serviceserver-restify": "^2.0.10",
     "papaparse": "^5.5.3",
     "pict-docuserve": "^0.1.5",
-    "quackage": "^1.1.2",
+    "quackage": "^1.2.3",
     "supertest": "^7.2.2",
     "typescript": "^5.9.3",
     "why-is-node-running": "^3.2.2"
@@ -67,9 +67,9 @@
     "fable": "^3.1.71",
     "fable-serviceproviderbase": "^3.0.19",
     "JSONStream": "^1.3.5",
-    "meadow": "^2.0.37",
+    "meadow": "^2.0.38",
     "meadow-filter": "^1.0.10",
-    "orator": "^6.0.4",
+    "orator": "^6.1.1",
     "underscore": "^1.13.8"
   }
 }

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,15 @@ 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`);
+			// REST-idiomatic PUT/PATCH-by-id: the URL path holds the primary key,
+			// matching GET/:IDRecord and DELETE/:IDRecord. The Update endpoint
+			// merges pRequest.params.IDRecord into the body so the row is updated
+			// in-place — no GET → DELETE → INSERT dance, primary key preserved.
+			// Registered AFTER the literal /Upsert(s) routes so those win on the
+			// :IDRecord match.
+			this.connectRoute(pServiceServer, 'putWithBodyParser', `/:IDRecord`, this._Endpoints.Update, `the internal behavior _Endpoints.Update (by-id PUT)`);
+			this.connectRoute(pServiceServer, 'patchWithBodyParser', `/:IDRecord`, this._Endpoints.Update, `the internal behavior _Endpoints.Update (by-id PATCH)`);
 		}
 		if (this._EnabledBehaviorSets.Delete)
 		{

package/source/endpoints/update/Meadow-Endpoint-Update.js

@@ -12,10 +12,26 @@ const doAPIEndpointUpdate = function(pRequest, pResponse, fNext)
 	[
 		(fStageComplete) =>
 		{
-			if (typeof(pRequest.body) !== 'object')
+			if (typeof(pRequest.body) !== 'object' || pRequest.body === null)
 			{
 				return fStageComplete(this.ErrorHandler.getError('Record update failure - a valid record is required.', 400));
 			}
+
+			// PUT|PATCH /Entity/:IDRecord puts the primary key in the URL path
+			// (REST-idiomatic, parallels GET/:IDRecord and DELETE/:IDRecord).
+			// When present, the URL ID is authoritative and overrides anything
+			// in the body. This is what lets clients update-in-place without
+			// the GET → DELETE → INSERT churn that loses the primary key.
+			if (pRequest.params && pRequest.params.IDRecord)
+			{
+				let tmpURLID = pRequest.params.IDRecord;
+				if (typeof(tmpURLID) === 'string' && /^-?\d+$/.test(tmpURLID))
+				{
+					tmpURLID = Number(tmpURLID);
+				}
+				pRequest.body[this.DAL.defaultIdentifier] = tmpURLID;
+			}
+
 			if (pRequest.body[this.DAL.defaultIdentifier] < 1)
 			{
 				return fStageComplete(this.ErrorHandler.getError('Record update failure - a valid record ID is required in the passed-in record.', 400));

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();
 		});