pict-section-recordset 1.17.0 → 1.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pict-section-recordset",
-  "version": "1.17.0",
+  "version": "1.19.0",
   "description": "Pict dynamic record set management views",
   "main": "source/Pict-Section-RecordSet.js",
   "files": [

package/source/providers/RecordSet-AssociationManager.js

@@ -38,6 +38,31 @@ class PictRecordSetAssociationManager extends libPictProvider
 
 		/** @type {Record<string, any>} - Lazily-created EntityProviders scoped to a non-default URL prefix. */
 		this._scopedEntityProviders = {};
+
+		/** @type {string} - EntityProvider cache scope for join-list reads; cleared on every join write so
+		 * the editor and pickers never show a stale (cached) association list after an add or remove. */
+		this._cacheScope = 'RecordSetAssociation';
+	}
+
+	/**
+	 * Invalidate the cached join-list reads after a write so the next list reflects it immediately
+	 * (pict's EntityProvider caches getEntitySet by filter for ~10s; clearScope no-ops on the default
+	 * empty scope, which is why join reads run under a dedicated scope).
+	 * @param {Record<string, any>} pEntityProvider - the (scoped) EntityProvider used for the join.
+	 */
+	_clearAssociationCache(pEntityProvider)
+	{
+		try
+		{
+			if (pEntityProvider && (typeof pEntityProvider.clearScope === 'function'))
+			{
+				pEntityProvider.clearScope(this._cacheScope);
+			}
+		}
+		catch (pError)
+		{
+			this.pict.log.warn(`AssociationManager: association cache clear failed: ${pError.message || pError}`);
+		}
 	}
 
 	/**
@@ -53,10 +78,20 @@ class PictRecordSetAssociationManager extends libPictProvider
 		const tmpSide = pSide || {};
 		const tmpEntity = tmpSide.Entity || tmpSide.RecordSet;
 		const tmpDisplayField = tmpSide.DisplayField || 'Name';
+		const tmpIDField = tmpSide.IDField || `ID${tmpEntity}`;
 		return {
 			RecordSet: tmpSide.RecordSet || tmpEntity,
 			Entity: tmpEntity,
-			IDField: tmpSide.IDField || `ID${tmpEntity}`,
+			// The field on THIS SIDE's record that identifies it for association purposes — the picker
+			// value, the display lookup key, and (by default) the value stored in the join. Usually the
+			// primary key (`ID<Entity>`), but can be any unique field (e.g. ObservationManifest is keyed
+			// by 'Name' on its join, so its side is { IDField: 'Name' }).
+			IDField: tmpIDField,
+			// The column on the JOIN ENTITY that references this side. Defaults to IDField — the common
+			// case where the join column has the same name as the side's id field. Set it when the join
+			// names this side differently: ProjectObservationManifestJoin stores the manifest by
+			// 'ObservationManifestName', so the manifest side is { IDField: 'Name', JoinField: 'ObservationManifestName' }.
+			JoinField: tmpSide.JoinField || tmpIDField,
 			DisplayField: tmpDisplayField,
 			SearchFields: (Array.isArray(tmpSide.SearchFields) && tmpSide.SearchFields.length > 0) ? tmpSide.SearchFields : [ tmpDisplayField ],
 			// No default sort: alphabetical-by-display sorts empty values first (blank rows). The picker's
@@ -110,6 +145,17 @@ class PictRecordSetAssociationManager extends libPictProvider
 		return `FOP~0~(~0~${tmpInner}~FCP~0~)~0`;
 	}
 
+	/**
+	 * URL-encode each value and comma-join, for `INN`/`NIN` filter lists. Numeric ids pass through; this
+	 * keeps string keys (e.g. manifest names with spaces) intact when a side is keyed by a name column.
+	 * @param {Array<string|number>} pValues
+	 * @return {string}
+	 */
+	_encodeList(pValues)
+	{
+		return (Array.isArray(pValues) ? pValues : []).map((pValue) => encodeURIComponent(pValue)).join(',');
+	}
+
 	/**
 	 * Fetch one page of a side's records for the matrix table (search across its SearchFields + optional
 	 * Sort, offset/limit paging). Returns the raw records + a `hasMore` flag.
@@ -161,6 +207,17 @@ class PictRecordSetAssociationManager extends libPictProvider
 			JoinEntity: pDefinition.JoinEntity,
 			JoinURLPrefix: pDefinition.JoinURLPrefix || '',
 			DefaultJoinValues: pDefinition.DefaultJoinValues || {},
+			// Per-join config columns the editor renders as inline-editable on each association row — for
+			// "rich" joins that carry settings (e.g. Journal/Spreadsheet/Ordinal). Each entry:
+			// { Field, Label?, Type? ('checkbox'|'number'|'text'|'select'), Options?, Width? }.
+			JoinEditableFields: Array.isArray(pDefinition.JoinEditableFields) ? pDefinition.JoinEditableFields : [],
+			// The defaults lifecycle hook — the overridable seam the host implements. An async
+			// `(context) => Array<{ value, joinValues? }>` returning the OTHER side's key values (+ optional
+			// per-join config) to seed for an anchor record. PSRS owns APPLYING them (dedupe + createJoin),
+			// so every association synthesizes defaults the same way; the host only decides what they are.
+			SynthesizeDefaults: (typeof pDefinition.SynthesizeDefaults === 'function') ? pDefinition.SynthesizeDefaults : false,
+			// Opt-in: auto-run synthesizeDefaults the first time the editor opens an anchor with zero joins.
+			AutoSynthesizeWhenEmpty: (pDefinition.AutoSynthesizeWhenEmpty === true),
 			SideA: this._normalizeSide(pDefinition.SideA),
 			SideB: this._normalizeSide(pDefinition.SideB),
 		};
@@ -283,7 +340,7 @@ class PictRecordSetAssociationManager extends libPictProvider
 			return Promise.resolve([]);
 		}
 		const tmpEntityProvider = this._entityProvider(tmpSides.association.JoinURLPrefix);
-		const tmpFilter = `FBV~${tmpSides.thisSide.IDField}~EQ~${encodeURIComponent(pThisID)}`;
+		const tmpFilter = `FBV~${tmpSides.thisSide.JoinField}~EQ~${encodeURIComponent(pThisID)}`;
 		return new Promise((resolve) =>
 		{
 			tmpEntityProvider.getEntitySet(tmpSides.association.JoinEntity, tmpFilter, (pError, pRecords) =>
@@ -294,7 +351,7 @@ class PictRecordSetAssociationManager extends libPictProvider
 					return resolve([]);
 				}
 				return resolve(Array.isArray(pRecords) ? pRecords : []);
-			});
+			}, '', { Scope: this._cacheScope, NoCount: true });
 		});
 	}
 
@@ -315,7 +372,7 @@ class PictRecordSetAssociationManager extends libPictProvider
 			return Promise.resolve([]);
 		}
 		const tmpEntityProvider = this._entityProvider(tmpSides.association.JoinURLPrefix);
-		const tmpFilter = `FBL~${tmpSides.thisSide.IDField}~INN~${pThisIDs.join(',')}`;
+		const tmpFilter = `FBL~${tmpSides.thisSide.JoinField}~INN~${this._encodeList(pThisIDs)}`;
 		return new Promise((resolve) =>
 		{
 			tmpEntityProvider.getEntitySet(tmpSides.association.JoinEntity, tmpFilter, (pError, pRecords) =>
@@ -326,7 +383,7 @@ class PictRecordSetAssociationManager extends libPictProvider
 					return resolve([]);
 				}
 				return resolve(Array.isArray(pRecords) ? pRecords : []);
-			});
+			}, '', { Scope: this._cacheScope, NoCount: true });
 		});
 	}
 
@@ -347,7 +404,7 @@ class PictRecordSetAssociationManager extends libPictProvider
 		}
 		const tmpJoins = await this.listJoinRecords(pAssociationHash, pThisRecordSetName, pThisID);
 		return tmpJoins
-			.map((pJoin) => pJoin[tmpSides.otherSide.IDField])
+			.map((pJoin) => pJoin[tmpSides.otherSide.JoinField])
 			.filter((pValue) => (pValue !== undefined && pValue !== null && pValue !== ''));
 	}
 
@@ -372,14 +429,14 @@ class PictRecordSetAssociationManager extends libPictProvider
 		const tmpJoinIDField = this.getJoinIDField(tmpSides.association);
 		const tmpJoins = await this.listJoinRecords(pAssociationHash, pThisRecordSetName, pThisID);
 		const tmpOtherIDs = tmpJoins
-			.map((pJoin) => pJoin[tmpSides.otherSide.IDField])
+			.map((pJoin) => pJoin[tmpSides.otherSide.JoinField])
 			.filter((pValue) => (pValue !== undefined && pValue !== null && pValue !== ''));
 
 		let tmpByID = {};
 		if (tmpOtherIDs.length > 0)
 		{
 			const tmpEntityProvider = this._entityProvider(tmpSides.otherSide.URLPrefix);
-			const tmpFilter = `FBL~${tmpSides.otherSide.IDField}~INN~${tmpOtherIDs.join(',')}`;
+			const tmpFilter = `FBL~${tmpSides.otherSide.IDField}~INN~${this._encodeList(tmpOtherIDs)}`;
 			const tmpOthers = await new Promise((resolve) =>
 			{
 				tmpEntityProvider.getEntitySet(tmpSides.otherSide.Entity, tmpFilter, (pError, pRecords) =>
@@ -399,10 +456,10 @@ class PictRecordSetAssociationManager extends libPictProvider
 		}
 
 		return tmpJoins
-			.filter((pJoin) => (pJoin[tmpSides.otherSide.IDField] !== undefined && pJoin[tmpSides.otherSide.IDField] !== null && pJoin[tmpSides.otherSide.IDField] !== ''))
+			.filter((pJoin) => (pJoin[tmpSides.otherSide.JoinField] !== undefined && pJoin[tmpSides.otherSide.JoinField] !== null && pJoin[tmpSides.otherSide.JoinField] !== ''))
 			.map((pJoin) =>
 			{
-				const tmpOtherID = pJoin[tmpSides.otherSide.IDField];
+				const tmpOtherID = pJoin[tmpSides.otherSide.JoinField];
 				const tmpOtherRecord = tmpByID[tmpOtherID] || {};
 				const tmpDisplay = (tmpOtherRecord[tmpSides.otherSide.DisplayField] !== undefined && tmpOtherRecord[tmpSides.otherSide.DisplayField] !== null && tmpOtherRecord[tmpSides.otherSide.DisplayField] !== '')
 					? tmpOtherRecord[tmpSides.otherSide.DisplayField]
@@ -426,18 +483,20 @@ class PictRecordSetAssociationManager extends libPictProvider
 	 * @param {string} pThisRecordSetName
 	 * @param {string|number} pThisID
 	 * @param {string|number} pOtherID
+	 * @param {Record<string, any>} [pJoinValues] - Optional extra columns to stamp on the join row (e.g.
+	 *   per-association config like { Journal: 1, Ordinal: 3 } from a synthesized default).
 	 * @return {Promise<Record<string, any>>}
 	 */
-	createJoin(pAssociationHash, pThisRecordSetName, pThisID, pOtherID)
+	createJoin(pAssociationHash, pThisRecordSetName, pThisID, pOtherID, pJoinValues)
 	{
 		const tmpSides = this.resolveSides(pAssociationHash, pThisRecordSetName);
 		if (!tmpSides)
 		{
 			return Promise.reject(new Error(`AssociationManager: cannot create join for [${pAssociationHash}] from [${pThisRecordSetName}].`));
 		}
-		const tmpRecord = Object.assign({}, tmpSides.association.DefaultJoinValues);
-		tmpRecord[tmpSides.thisSide.IDField] = pThisID;
-		tmpRecord[tmpSides.otherSide.IDField] = pOtherID;
+		const tmpRecord = Object.assign({}, tmpSides.association.DefaultJoinValues, pJoinValues || {});
+		tmpRecord[tmpSides.thisSide.JoinField] = pThisID;
+		tmpRecord[tmpSides.otherSide.JoinField] = pOtherID;
 		const tmpEntityProvider = this._entityProvider(tmpSides.association.JoinURLPrefix);
 		return new Promise((resolve, reject) =>
 		{
@@ -447,6 +506,7 @@ class PictRecordSetAssociationManager extends libPictProvider
 				{
 					return reject(pError);
 				}
+				this._clearAssociationCache(tmpEntityProvider);
 				return resolve(pBody);
 			});
 		});
@@ -476,11 +536,143 @@ class PictRecordSetAssociationManager extends libPictProvider
 				{
 					return reject(pError);
 				}
+				this._clearAssociationCache(tmpEntityProvider);
 				return resolve(pBody);
 			});
 		});
 	}
 
+	/**
+	 * Update the config columns of an existing join row (a "rich" join's per-association settings, e.g.
+	 * Journal / Spreadsheet / Ordinal). Merges pValues over the join record and PUTs it.
+	 *
+	 * @param {string} pAssociationHash
+	 * @param {Record<string, any>} pJoinRecord - the full join row (as carried by listAssociatedRecords).
+	 * @param {Record<string, any>} pValues - the columns to change.
+	 * @return {Promise<Record<string, any>>}
+	 */
+	updateJoin(pAssociationHash, pJoinRecord, pValues)
+	{
+		const tmpAssociation = this.associations[pAssociationHash];
+		if (!tmpAssociation || !pJoinRecord)
+		{
+			return Promise.reject(new Error(`AssociationManager: cannot update join for [${pAssociationHash}].`));
+		}
+		const tmpRecord = Object.assign({}, pJoinRecord, pValues || {});
+		const tmpEntityProvider = this._entityProvider(tmpAssociation.JoinURLPrefix);
+		return new Promise((resolve, reject) =>
+		{
+			tmpEntityProvider.updateEntity(tmpAssociation.JoinEntity, tmpRecord, (pError, pBody) =>
+			{
+				if (pError)
+				{
+					return reject(pError);
+				}
+				this._clearAssociationCache(tmpEntityProvider);
+				return resolve(pBody);
+			});
+		});
+	}
+
+	/**
+	 * The per-join config columns an association exposes as inline-editable (empty for a plain join).
+	 * @param {string} pAssociationHash
+	 * @return {Array<Record<string, any>>}
+	 */
+	getJoinEditableFields(pAssociationHash)
+	{
+		const tmpAssociation = this.associations[pAssociationHash];
+		return (tmpAssociation && Array.isArray(tmpAssociation.JoinEditableFields)) ? tmpAssociation.JoinEditableFields : [];
+	}
+
+	/**
+	 * Whether an association has a host-provided defaults synthesizer registered.
+	 * @param {string} pAssociationHash
+	 * @return {boolean}
+	 */
+	hasDefaultSynthesizer(pAssociationHash)
+	{
+		const tmpAssociation = this.associations[pAssociationHash];
+		return !!(tmpAssociation && (typeof tmpAssociation.SynthesizeDefaults === 'function'));
+	}
+
+	/**
+	 * Synthesize default associations for one anchor record — THE consistent defaults lifecycle function.
+	 * PSRS owns the "apply" half (dedupe against existing joins, then createJoin each new one with its
+	 * config); the host owns only WHAT the defaults are, via the association's overridable
+	 * `SynthesizeDefaults(context)` hook. No-op when no hook is registered.
+	 *
+	 * The hook receives `{ association, thisSide, otherSide, thisID, existingJoins, manager, pict }` and
+	 * returns `Array<{ value, joinValues? }>` — `value` is the OTHER side's key value (what goes in the
+	 * join's other JoinField), `joinValues` is optional extra config to stamp on that join row.
+	 *
+	 * @param {string} pAssociationHash
+	 * @param {string} pThisRecordSetName
+	 * @param {string|number} pThisID
+	 * @return {Promise<{ created: number, skipped: number }>}
+	 */
+	async synthesizeDefaults(pAssociationHash, pThisRecordSetName, pThisID)
+	{
+		const tmpSides = this.resolveSides(pAssociationHash, pThisRecordSetName);
+		if (!tmpSides || !this.hasDefaultSynthesizer(pAssociationHash) || pThisID === undefined || pThisID === null || pThisID === '')
+		{
+			return { created: 0, skipped: 0 };
+		}
+		const tmpExistingJoins = await this.listJoinRecords(pAssociationHash, pThisRecordSetName, pThisID);
+		const tmpExisting = {};
+		tmpExistingJoins.forEach((pJoin) =>
+		{
+			const tmpValue = pJoin[tmpSides.otherSide.JoinField];
+			if (tmpValue !== undefined && tmpValue !== null && tmpValue !== '') { tmpExisting[`${tmpValue}`] = true; }
+		});
+
+		let tmpDefaults = [];
+		try
+		{
+			tmpDefaults = await tmpSides.association.SynthesizeDefaults(
+				{
+					association: tmpSides.association,
+					thisSide: tmpSides.thisSide,
+					otherSide: tmpSides.otherSide,
+					thisID: pThisID,
+					existingJoins: tmpExistingJoins,
+					manager: this,
+					pict: this.pict,
+				});
+		}
+		catch (pError)
+		{
+			this.pict.log.error(`AssociationManager: SynthesizeDefaults hook for [${pAssociationHash}] threw: ${pError.message || pError}`);
+			return { created: 0, skipped: 0 };
+		}
+
+		let tmpCreated = 0;
+		let tmpSkipped = 0;
+		const tmpList = Array.isArray(tmpDefaults) ? tmpDefaults : [];
+		for (let i = 0; i < tmpList.length; i++)
+		{
+			const tmpDefault = tmpList[i] || {};
+			const tmpValue = (tmpDefault.value !== undefined) ? tmpDefault.value : tmpDefault.Value;
+			if (tmpValue === undefined || tmpValue === null || tmpValue === '' || tmpExisting[`${tmpValue}`])
+			{
+				tmpSkipped++;
+				continue;
+			}
+			try
+			{
+				await this.createJoin(pAssociationHash, pThisRecordSetName, pThisID, tmpValue, tmpDefault.joinValues || tmpDefault.JoinValues || {});
+				tmpExisting[`${tmpValue}`] = true;
+				tmpCreated++;
+			}
+			catch (pError)
+			{
+				this.pict.log.warn(`AssociationManager: synthesize createJoin failed for [${pAssociationHash}] value [${tmpValue}]: ${pError.message || pError}`);
+				tmpSkipped++;
+			}
+		}
+		return { created: tmpCreated, skipped: tmpSkipped };
+	}
+
 	/**
 	 * Build a `createEntityPicker` config for one side, optionally culling a live set of ids (a function
 	 * so the cull re-evaluates on every search as associations change).
@@ -511,7 +703,7 @@ class PictRecordSetAssociationManager extends libPictProvider
 			tmpConfig.BaseFilter = () =>
 			{
 				const tmpIDs = pGetExcludedIDsFn();
-				return (Array.isArray(tmpIDs) && tmpIDs.length > 0) ? `FBL~${pSide.IDField}~NIN~${tmpIDs.join(',')}` : '';
+				return (Array.isArray(tmpIDs) && tmpIDs.length > 0) ? `FBL~${pSide.IDField}~NIN~${this._encodeList(tmpIDs)}` : '';
 			};
 		}
 		return Object.assign(tmpConfig, pOverrides || {});