@cepharum/concrete-db 0.1.1 → 0.1.2-alpha.1

package/lib/shaper.mjs

@@ -1,38 +1,10 @@
-/**
- * (c) 2021 cepharum GmbH, Berlin, http://cepharum.de
- *
- * The MIT License (MIT)
- *
- * Copyright (c) 2021 cepharum GmbH
- *
- * Permission is hereby granted, free of charge, to any person obtaining a copy
- * of this software and associated documentation files (the "Software"), to deal
- * in the Software without restriction, including without limitation the rights
- * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
- * copies of the Software, and to permit persons to whom the Software is
- * furnished to do so, subject to the following conditions:
- *
- * The above copyright notice and this permission notice shall be included in all
- * copies or substantial portions of the Software.
- *
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
- * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
- * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
- * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
- * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
- * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
- * SOFTWARE.
- *
- * @author: cepharum
- */
-
 import EventEmitter from "events";
 
 import { Compiler, Functions } from "simple-terms";
 import merge from "lodash.merge";
 
 import { DefaultShaperOptions } from "./defaults.mjs";
-import { augmentedDataSpace, deepFreeze } from "./helper.mjs";
+import { augmentDataSpace } from "./helper.mjs";
 import * as TermFunctions from "./term-functions.mjs";
 
 
@@ -87,61 +59,561 @@ export class Shaper extends EventEmitter {
 	 * Reorganizes records to by grouped by model.
 	 *
 	 * @param {Map<string,CollectedRecord[]>} collection collection of records to transform
-	 * @returns {object<string,object<string, CollectedRecord[]>>} provided records grouped by model and unique item ID
+	 * @returns {Object<string,Object<string, CollectedRecord[]>>} provided records grouped by model and unique item ID
 	 */
 	groupByModel( collection ) {
-		const models = {};
-		const modelShapes = {};
-
-		for ( const records of collection.values() ) {
-			for ( const record of records ) {
-				const { segments, shape, data } = record;
-				const metaProperties = {
-					$segments: segments,
-				};
-				const wrapped = augmentedDataSpace( data, metaProperties );
-
-				const modelName = this.detectModel( wrapped, shape );
-				metaProperties.$model = modelName;
-
-				if ( !modelShapes.hasOwnProperty( modelName ) ) {
-					modelShapes[modelName] = deepFreeze( merge( {}, shape?.common, shape?.models?.[modelName] ) );
+		const globalItemsPerModel = {};
+		const postProcessingQueue = new Set();
+
+		for ( const source of collection.values() ) {
+			const localItemsPerModel = this.compileModelsOfSource( source );
+
+			this.processContributions( localItemsPerModel, postProcessingQueue );
+
+			this.mergeItemsPerModel( globalItemsPerModel, localItemsPerModel );
+		}
+
+		this.postProcessContributions( globalItemsPerModel, postProcessingQueue );
+
+		return globalItemsPerModel;
+	}
+
+	/**
+	 * Compiles all items according to collected records of provided source and
+	 * collect them grouped by items' model.
+	 *
+	 * @param {CollectedRecord[]} source list of records collected from a source
+	 * @returns {Object<string,Object<string,Object>>} compiled items grouped by model, addressable by either item's ID
+	 */
+	compileModelsOfSource( source ) {
+		const shapesPerModelCache = {};
+		const itemsPerModel = {};
+
+		for ( let read = 0, numRecords = source.length; read < numRecords; read++ ) {
+			const item = this.compileModelItemFromRecord( shapesPerModelCache, itemsPerModel, source[read] );
+			const modelPool = itemsPerModel[item.$model];
+
+			const variantId = this.computeVariantIdOfItem( item );
+			if ( variantId == null ) {
+				modelPool[item.$id] = modelPool[item.$id] ? merge( modelPool[item.$id], item ) : item;
+			} else {
+				const target = modelPool[item.$id];
+
+				if ( !target.$variants ) {
+					target.$variants = {};
 				}
 
-				const modelShape = modelShapes[modelName];
-				metaProperties.$shape = modelShape;
+				target.$variants[variantId] = target.$variants[variantId] ? merge( target.$variants[variantId], item ) : item;
+			}
+		}
+
+		return itemsPerModel;
+	}
+
+	/**
+	 * Compiles item of model from a provided source record. This includes
+	 * detecting model and selected ID of resulting item from provided record
+	 * based on record's shape.
+	 *
+	 * @param {Object<string,ShapeModel>} shapesPerModelCache caches per-model shapes compiled before
+	 * @param {Object<string,Object<string,Object>>} itemsPerModel collection of previously compiled items per model
+	 * @param {CollectedRecord} record augmented data collected from a source to be compiled
+	 * @returns {object} instance of model with hidden meta information injected
+	 */
+	compileModelItemFromRecord( shapesPerModelCache, itemsPerModel, record ) {
+		const { segments, shape, data } = record;
 
-				const id = this.identifyRecord( wrapped, modelShape );
-				metaProperties.$id = id;
+		const metaProperties = {
+			$segments: segments
+		};
 
-				let model = models[modelName];
-				if ( !model ) {
-					model = models[modelName] = {};
+		const augmentedData = augmentDataSpace( data, metaProperties );
 
-					Object.defineProperties( model, {
-						$shape: { value: modelShape },
-						$model: { value: modelName },
-					} );
+		metaProperties.$model = this.detectModel( augmentedData, shape );
+		metaProperties.$shape = this.getShapeOfModel( shapesPerModelCache, shape, metaProperties.$model );
+		metaProperties.$id = this.identifyRecord( augmentedData, metaProperties.$shape );
+
+		if ( !itemsPerModel.hasOwnProperty( metaProperties.$model ) ) {
+			// eslint-disable-next-line no-param-reassign
+			itemsPerModel[metaProperties.$model] = Object.defineProperties( {}, {
+				$model: { value: metaProperties.$model },
+				$shape: { value: metaProperties.$shape },
+			} );
+		}
+
+		const model = itemsPerModel[metaProperties.$model];
+
+		const { properties, defaults } = metaProperties.$shape;
+		const item = this.compileItem( augmentedData, properties, model[metaProperties.$id] ? {} : defaults );
+
+		Object.defineProperties( item, {
+			$original: { value: data },
+			$shape: { value: metaProperties.$shape },
+			$model: { value: metaProperties.$model },
+			$id: { value: metaProperties.$id },
+			$segments: { value: segments },
+			$localShape: { value: shape },
+		} );
+
+		return item;
+	}
+
+	/**
+	 * Re-compiles provided item this time based item's properties' themselves
+	 * instead of some record originally collected from a source.
+	 *
+	 * Re-compiling is used to compute data contributed by other models.
+	 *
+	 * @param {CollectedItem} item previously compiled item to re-compile
+	 * @returns {CollectedItem} re-compiled item
+	 */
+	recompileItem( item ) {
+		const data = augmentDataSpace( merge( {}, item.$original, item ), { ...item, $postcontribution: true } );
+		const updatedItem = this.compileItem( data, item.$shape.properties, {} );
+
+		Object.defineProperties( updatedItem, {
+			$original: { value: item.$original },
+			$shape: { value: item.$shape },
+			$model: { value: item.$model },
+			$id: { value: item.$id },
+			$segments: { value: item.$segments },
+			$localShape: { value: item.$localShape },
+		} );
+
+		return updatedItem;
+	}
+
+	/**
+	 * Computes ID of variant provided item is describing. If nullish, the item
+	 * isn't describing any variant but the base version of the item.
+	 *
+	 * @param {CollectedItem} item an item to get variant ID for
+	 * @returns {null|any} computed variant ID of provided item, nullish if item is not a variant
+	 */
+	computeVariantIdOfItem( item ) {
+		const term = item.$shape.variant;
+
+		if ( term == null ) {
+			return null;
+		}
+
+		// compile data space based on item's properties overlaying the item's originating record
+		const data = augmentDataSpace( merge( {}, item.$original, item ), item );
+
+		try {
+			return Compiler.compile( String( term ), this.termFunctions, this.termsCache )( data );
+		} catch ( cause ) {
+			throw new Error( `computing variant ID of ${item.$model}#${item.$id} failed: ${cause.message} in ${term}` );
+		}
+	}
+
+	/**
+	 * Fetches compiled shape of named model using provided cache.
+	 *
+	 * @param {Object<string,ShapeModel>} shapesPerModelCache cache to use on fetching shape for same model multiple times
+	 * @param {Shape} localShape shape including desired definition of selected model's shape
+	 * @param {string} modelName name of model
+	 * @returns {ShapeModel} compiled shape of model incorporating common definitions for all models
+	 */
+	getShapeOfModel( shapesPerModelCache, localShape, modelName ) {
+		if ( !shapesPerModelCache.hasOwnProperty( modelName ) ) {
+			// eslint-disable-next-line no-param-reassign
+			shapesPerModelCache[modelName] = merge( {}, localShape?.common, localShape?.models?.[modelName] );
+		}
+
+		return shapesPerModelCache[modelName];
+	}
+
+	/**
+	 * Computes dependencies of models on contributions by provided items
+	 * grouped by model.
+	 *
+	 * @param {Object<string,Object<string,Object>>} itemsPerModel compiled items grouped by model
+	 * @returns {string[]} sorted list of names of models in provided pool starting with model depending on other models' contributions the least
+	 */
+	listContributingModels( itemsPerModel ) {
+		const contributorsPerModel = {};
+
+		// create map of immediate relations between every two models involved
+		// in a contribution
+		for ( const model of Object.keys( itemsPerModel ) ) {
+			for ( const item of Object.values( itemsPerModel[model] ) ) {
+				for ( const contributedModel of Object.keys( item.$shape.contributions || {} ) ) {
+					if ( !contributorsPerModel.hasOwnProperty( contributedModel ) ) {
+						contributorsPerModel[contributedModel] = {};
+					}
+
+					contributorsPerModel[contributedModel][item.$model] = 1;
 				}
+			}
+		}
+
+		// surface mediate dependencies and collect all contributing models' names
+		const contributingModelNames = {};
+
+		for ( const surfaceModel of Object.keys( contributorsPerModel ) ) {
+			descend( surfaceModel, surfaceModel, [] );
+		}
+
+		// sort names of contributing models from models depending on other
+		// contributing models the least to those doing it the most
+		const names = Object.keys( contributingModelNames );
+
+		names.sort( ( left, right ) => {
+			if ( contributorsPerModel.hasOwnProperty( left ) && contributorsPerModel[left].hasOwnProperty( right ) ) {
+				// left model depends on contributions by right model
+				return 1;
+			}
 
-				const isVariant = model.hasOwnProperty( id );
-				const item = this.compileItem( wrapped, modelShape, !isVariant );
+			if ( contributorsPerModel.hasOwnProperty( right ) && contributorsPerModel[right].hasOwnProperty( left ) ) {
+				// right model depends on contributions by left model
+				return -1;
+			}
+
+			return 0;
+		} );
+
+		return names;
+
+		/**
+		 * Surfaces dependencies of a named model.
+		 *
+		 * @param {string} surfaceModel name of model triggering current processing
+		 * @param {string} currentModel name of currently processed model
+		 * @param {string[]} breadcrumb names of models processed while descending into dependencies
+		 * @returns {void}
+		 */
+		function descend( surfaceModel, currentModel, breadcrumb ) {
+			if ( breadcrumb.indexOf( currentModel ) > -1 ) {
+				throw new Error( `invalid circular dependency on contributing to model ${surfaceModel}: [${breadcrumb}]` );
+			}
+
+			if ( contributorsPerModel.hasOwnProperty( currentModel ) ) {
+				const current = contributorsPerModel[currentModel];
+				const surface = contributorsPerModel[surfaceModel];
+
+				for ( const contributingModel of Object.keys( current ) ) {
+					contributingModelNames[contributingModel] = true;
+
+					if ( !surface.hasOwnProperty( contributingModel ) ) {
+						surface[contributingModel] = -1;
+					} else if ( current[contributingModel] > 0 ) {
+						breadcrumb.push( currentModel );
+						descend( surfaceModel, contributingModel, breadcrumb );
+						breadcrumb.pop();
+					}
+				}
+			}
+		}
+	}
+
+	/**
+	 * Processes contributions of models in provided collection of items
+	 * augmenting that collection.
+	 *
+	 * @param {Object<string,Object<string,Object>>} itemsPerModel map of model names into either model's map of item IDs into related item
+	 * @param {Set<string>} contributedItems tracks IDs of items or their variants that have been contributed to
+	 * @returns {void}
+	 */
+	processContributions( itemsPerModel, contributedItems ) {
+		const contributingModels = this.listContributingModels( itemsPerModel );
+		const shapePerModelCache = {};
+
+		for ( const modelName of contributingModels ) {
+			const items = itemsPerModel[modelName];
+
+			for ( const item of Object.values( items ) ) {
+				const { contributions } = item.$shape;
+				if ( !contributions ) {
+					continue;
+				}
+
+				for ( const targetModelName of Object.keys( contributions ) ) {
+					const targetModelShape = this.getShapeOfModel( shapePerModelCache, item.$localShape, targetModelName );
+
+
+					// extract contributions to actually declared properties of target model
+					const contributionTerms = {};
+					let warn = false;
+
+					for ( const termTargetName of Object.keys( contributions[targetModelName] ) ) {
+						const propertyName = termTargetName.replace( /\s*\[]$/, "" );
+
+						if ( propertyName !== termTargetName && propertyName.startsWith( "$" ) ) {
+							throw new Error( `invalid collecting contribution of record #${item.$id} in model ${item.$model} to property ${propertyName} of model ${targetModelName}` ); // eslint-disable-line max-len
+						}
 
-				Object.defineProperties( item, {
-					$shape: { value: modelShape },
-					$model: { value: modelName },
-					$id: { value: id },
+						if ( Object.prototype.hasOwnProperty.call( targetModelShape.properties, propertyName ) ) {
+							if ( contributionTerms.hasOwnProperty( propertyName ) ) {
+								throw new Error( `double contribution of record #${item.$id} in model ${item.$model} to property ${propertyName} of model ${targetModelName}` ); // eslint-disable-line max-len
+							}
+
+							contributionTerms[propertyName] = contributions[targetModelName][termTargetName];
+						} else {
+							warn = true;
+						}
+					}
+
+					if ( Object.keys( contributionTerms ).length < 1 ) {
+						console.warn( `ignoring eventually empty contribution of record #${item.$id} in model ${item.$model} to model ${targetModelName}` );
+						continue;
+					}
+
+					if ( warn ) {
+						console.warn( `ignoring undeclared properties in contribution of record #${item.$id} in model ${item.$model} to model ${targetModelName}` ); // eslint-disable-line max-len
+					}
+
+
+					// compile values contributed to target model in context of current item
+					const augmentedData = augmentDataSpace( item, item );
+					const contribution = this.compileItem( augmentedData, contributionTerms, {}, ["$id"] );
+
+					if ( Object.keys( contribution ).length < 1 ) {
+						console.warn( `ignoring empty contribution of record #${item.$id} in model ${item.$model} to model ${targetModelName}` );
+						continue;
+					}
+
+
+					// use contribution data's $id property to pick item of target model to contribute to
+					const targetId = contribution.$id;
+					if ( !targetId ) {
+						throw new Error( `contribution of record #${item.$id} in model ${item.$model} to model ${targetModelName} failed due to lack of ID` );
+					}
+
+					const targetIds = Array.isArray( targetId ) ? targetId : [targetId];
+
+					// check if this contribution is regarding a variant of selected target item
+					let variantId;
+
+					if ( targetModelShape.variant ) {
+						// try computing variant ID based on this item's contribution to target item
+						variantId = this.computeVariantIdOfItem( {
+							...contribution,
+							$shape: targetModelShape,
+							$id: targetId,
+							$model: targetModelName,
+							$original: { ...item.$original, data: {} },
+							$segments: item.$segments,
+							$localShape: item.$localShape,
+						} );
+					}
+
+					if ( variantId == null ) {
+						variantId = null;
+					}
+
+
+					for ( const id of targetIds ) {
+						// track contributions to selected target item or its variant
+						contributedItems.add( JSON.stringify( [ targetModelName, id, variantId ] ) );
+
+
+						// gain access on selected target item, create its containers as necessary
+						let target;
+
+						if ( !itemsPerModel.hasOwnProperty( targetModelName ) ) {
+							// eslint-disable-next-line no-param-reassign
+							itemsPerModel[targetModelName] = Object.defineProperties( {}, {
+								$model: { value: targetModelName },
+								$shape: { value: targetModelShape },
+							} );
+						}
+
+						const model = itemsPerModel[targetModelName];
+
+						if ( !model.hasOwnProperty( id ) ) {
+							model[id] = Object.defineProperties( {}, {
+								$original: { value: {} },
+								$shape: { value: targetModelShape },
+								$model: { value: targetModelName },
+								$id: { value: id },
+								$segments: { value: item.$segments },
+								$localShape: { value: item.$localShape, configurable: true },
+							} );
+						}
+
+						const targetItem = model[id];
+
+						if ( variantId == null ) {
+							target = targetItem;
+						} else {
+							if ( !targetItem.$variants ) {
+								targetItem.$variants = {};
+							}
+
+							if ( !targetItem.$variants.hasOwnProperty( variantId ) ) {
+								targetItem.$variants[variantId] = {};
+							}
+
+							target = targetItem.$variants[variantId];
+						}
+
+
+						// merge this item's contribution with any previous contribution to the selected target
+						for ( const name of Object.keys( contribution ) ) {
+							if ( String( name ).startsWith( "$" ) ) {
+								continue;
+							}
+
+							const value = contribution[name];
+
+							if ( contributions[targetModelName][name] ) {
+								// contribution has been declared without suffix "[]"
+								// -> do not collect, but replace value in target
+								target[name] = value;
+							} else {
+								// contribution has been declared with suffix "[]"
+								// -> collect value in target
+								if ( Array.isArray( target[name] ) ) { // eslint-disable-line no-lonely-if,max-depth
+									target[name].push( value );
+								} else if ( target[name] == null ) {
+									target[name] = [value];
+								} else {
+									target[name] = [ target[name], value ];
+								}
+							}
+						}
+					}
+				}
+			}
+		}
+	}
+
+	/**
+	 * Re-compiles all items in provided pool that have been contributed to.
+	 *
+	 * @param {Object<string,Object<string,CollectedItem>>} itemsPerModel pool of items per model to update
+	 * @param {Set<string>} contributions lists IDs of items or their variants that have been contributed to
+	 * @returns {Object<string,Object<string,CollectedItem>>} pool of items per model as provided
+	 */
+	postProcessContributions( itemsPerModel, contributions ) {
+		for ( const track of contributions.values() ) {
+			const [ model, id, variantId ] = JSON.parse( track );
+
+			if ( !itemsPerModel.hasOwnProperty( model ) ) {
+				console.warn( `inconsistency: missing items pool of model ${model} though contributions have been tracked` );
+				continue;
+			}
+
+			const modelPool = itemsPerModel[model];
+
+			if ( !modelPool.hasOwnProperty( id ) ) {
+				console.warn( `inconsistency: missing item ${id} of model ${model} though contributions have been tracked` );
+				continue;
+			}
+
+			const item = modelPool[id];
+
+			if ( variantId == null ) {
+				modelPool[id] = this.recompileItem( item );
+			} else {
+				if ( !item.$variants ) {
+					console.warn( `inconsistency: missing variants of item ${id} of model ${model} though contributions have been tracked` );
+					continue;
+				}
+
+				const variants = item.$variants;
+
+				if ( !variants.hasOwnProperty( variantId ) ) {
+					console.warn( `inconsistency: missing variant ${variantId} of item ${id} of model ${model} though contributions have been tracked` );
+					continue;
+				}
+
+				variants[variantId] = this.recompileItem( variants[variantId] );
+			}
+		}
+
+		return itemsPerModel;
+	}
+
+	/**
+	 * Merges items collected per model from a single source into provided
+	 * target collection which is covering multiple possible sources.
+	 *
+	 * @param {Object<string,Object<string,Object>>} target collection of items per model to be augmented by provided source collection
+	 * @param {Object<string,Object<string,Object>>} source collection items per model to merge into target
+	 * @returns {void}
+	 */
+	mergeItemsPerModel( target, source ) {
+		for ( const modelName of Object.keys( source ) ) {
+			const sourcePool = source[modelName];
+
+			if ( target.hasOwnProperty( modelName ) ) {
+				// blend shapes of pools claiming to refer to same model
+				const mergedShape = merge( {}, target[modelName].$shape, sourcePool.$shape );
+
+				Object.defineProperties( target[modelName], {
+					$shape: { value: mergedShape, configurable: true },
+				} );
+			} else {
+				// create pool of items for target model as it hasn't been populated before
+				// eslint-disable-next-line no-param-reassign
+				target[modelName] = Object.defineProperties( {}, {
+					$model: { value: sourcePool.$model },
+					$shape: { value: sourcePool.$shape, configurable: true },
 				} );
+			}
+
+			const targetPool = target[modelName];
+
+			for ( const itemId of Object.keys( sourcePool ) ) {
+				if ( targetPool.hasOwnProperty( itemId ) ) {
+					const from = sourcePool[itemId];
+					const to = targetPool[itemId];
+
+					targetPool[itemId] = this.mergeItem( to, from );
+
+					if ( from.$variants ) {
+						if ( !to.$variants ) {
+							to.$variants = {};
+						}
 
-				if ( isVariant ) {
-					// FIXME implement variants or overlays or whatever there is to do with multiple records for the same item
+						for ( const variantId of Object.keys( from.$variants ) ) {
+							to.$variants[variantId] = this.mergeItem( to.$variants[variantId] || {}, from.$variants[variantId] );
+						}
+					}
+				} else {
+					targetPool[itemId] = sourcePool[itemId];
+				}
+			}
+		}
+	}
+
+	/**
+	 * Updates a given set of properties blending it with another set of item
+	 * properties.
+	 *
+	 * @param {object} to target object to merge properties of source into
+	 * @param {object} from properties to merge into target
+	 * @returns {object} provided target object, or new object if provided target was falsy
+	 */
+	mergeItem( to, from ) {
+		const _to = to || {};
+
+		for ( const name of Object.keys( from ) ) {
+			if ( !String( name ).startsWith( "$" ) ) {
+				// TODO reconsider this merging strategy for being beneficial
+				//      they way it is by now (e.g. for it keeps nullish data on
+				//      either end)
+				if ( Array.isArray( from[name] ) ) {
+					if ( Array.isArray( _to[name] ) ) {
+						_to[name].splice( _to[name].length, 0, ...from[name] );
+					} else if ( _to.hasOwnProperty( name ) ) {
+						_to[name] = [ _to[name], ...from[name] ];
+					} else {
+						_to[name] = [...from[name]];
+					}
+				} else if ( Array.isArray( _to[name] ) ) {
+					if ( from.hasOwnProperty( name ) ) {
+						_to[name].push( from[name] );
+					}
 				} else {
-					model[id] = item;
+					_to[name] = from[name];
 				}
 			}
 		}
 
-		return models;
+		return _to;
 	}
 
 	/**
@@ -193,33 +665,32 @@ export class Shaper extends EventEmitter {
 	/**
 	 * Compiles resulting item by evaluating properties declared in model shape.
 	 *
-	 * @param {object} data source of record
-	 * @param {ShapeModel} modelShape shape of particular model
-	 * @param {boolean} useDefaults set true to include defaults configured in shape
+	 * @param {object} data (augmented) source of record
+	 * @param {ShapeProperties} properties definition of resulting item's properties
+	 * @param {ShapePropertyDefaults} defaults definition of default values for resulting item's properties
+	 * @param {string[]} accept list names of properties to accept even when starting with a dollar sign
 	 * @returns {object} compiled item
 	 */
-	compileItem( data, modelShape, useDefaults = true ) {
-		const properties = modelShape?.properties || {};
-		const defaults = modelShape?.defaults || {};
+	compileItem( data, properties = {}, defaults = {}, accept = [] ) {
 		const item = {};
 
 		for ( const property of Object.keys( properties ) ) {
-			if ( !String( property ).startsWith( "$" ) ) {
-				const selector = properties[property];
-				if ( typeof selector !== "string" || selector.trim().length === 0 ) {
+			if ( accept.indexOf( property ) > -1 || !String( property ).startsWith( "$" ) ) {
+				const term = properties[property];
+				if ( typeof term !== "string" || term.trim().length === 0 ) {
 					throw new Error( `invalid or missing term for computing value of property ${data.$model}#${property}` );
 				}
 
 				let value;
 
 				try {
-					value = Compiler.compile( selector, this.termFunctions, this.termsCache )( data );
+					value = Compiler.compile( term, this.termFunctions, this.termsCache )( data );
 				} catch ( cause ) {
-					throw new Error( `fetching value of property ${data.$model}#${property} failed: ${cause.message} in ${selector}` );
+					throw new Error( `fetching value of property ${data.$model}#${property} failed: ${cause.message} in ${term}` );
 				}
 
 				if ( value == null ) {
-					if ( useDefaults && defaults.hasOwnProperty( property ) ) {
+					if ( defaults.hasOwnProperty( property ) ) {
 						const defaultValue = defaults[property];
 						const trimmed = typeof defaultValue === "string" ? defaultValue.trim() : "";
 
@@ -238,14 +709,16 @@ export class Shaper extends EventEmitter {
 			}
 		}
 
-		return item;
+		// deeply merge fresh object with compiled item to get rid of deep data
+		// exposed to terms as Proxy
+		return merge( {}, item );
 	}
 
 	/**
 	 * Populates pool of endpoints with collected records of discovered models.
 	 *
 	 * @param {DatabaseEndpoints} endpoints map of routes into data sets to expose eventually
-	 * @param {object<string,DatabaseKeyedCollection>} models pool of items per discovered model
+	 * @param {Object<string,Object<string,CollectedItem>>} models pool of items per discovered model
 	 * @returns {DatabaseEndpoints} map of routes into data sets to expose eventually
 	 */
 	populateModels( endpoints, models ) {
@@ -272,13 +745,13 @@ export class Shaper extends EventEmitter {
 	 * a model.
 	 *
 	 * @param {DatabaseEndpoints} endpoints map of routes into data sets to expose eventually
-	 * @param {object<string,DatabaseKeyedCollection>} models pool of items per discovered model
+	 * @param {Object<string,Object<string,CollectedItem>>} models pool of items per discovered model
 	 * @param {string} modelName name of model to process
 	 * @returns {DatabaseEndpoints} map of routes into data sets to expose eventually
 	 */
 	populateModelCollections( endpoints, models, modelName ) {
 		const model = models[modelName];
-		const collections = model.$shape?.collections || {};
+		const collections = model.$shape.collections || {};
 		const cache = {};
 
 		// prepare to process collection instances prior to collection references
@@ -339,14 +812,14 @@ export class Shaper extends EventEmitter {
 
 						for ( const key in collection ) {
 							if ( collection.hasOwnProperty( key ) ) {
-								this.populateSlicedEndpoint( endpoints, normalized.replace( ptnKey, key ), collection[key], false, modelName );
+								this.populateSlicedEndpoint( endpoints, normalized.replace( ptnKey, key ), collection[key], false, modelName, definition );
 							}
 						}
 					} else {
 						throw new Error( `invalid use of {key} in route "${normalized}" of regular collection of model "${modelName}"` );
 					}
 				} else {
-					this.populateSlicedEndpoint( endpoints, normalized, collection, isKeyed, modelName );
+					this.populateSlicedEndpoint( endpoints, normalized, collection, isKeyed, modelName, definition );
 				}
 			}
 		}
@@ -361,12 +834,13 @@ export class Shaper extends EventEmitter {
 	 *
 	 * @param {DatabaseEndpoints} endpoints map of routes into data sets to expose eventually
 	 * @param {string} route route of current collection
-	 * @param {{items: Array<object>}|object<string, Array<object>>} collection collection of items to expose
+	 * @param {{items: Array<object>}|Object<string, Array<object>>} collection collection of items to expose
 	 * @param {boolean} isKeyed indicates if collection lists item per key or all items in a single list
 	 * @param {string} modelName name of model this collection is defined for
+	 * @param {object} definition provided collection's definition in shape
 	 * @returns {void}
 	 */
-	populateSlicedEndpoint( endpoints, route, collection, isKeyed, modelName ) {
+	populateSlicedEndpoint( endpoints, route, collection, isKeyed, modelName, definition ) {
 		ptnOffset.lastIndex = 0;
 		const match = ptnOffset.exec( route );
 
@@ -387,22 +861,30 @@ export class Shaper extends EventEmitter {
 				const normalized = normalizePathname( prefix + route.replace( ptnOffset, offset ) );
 				endpoints[normalized] = { count: items.length, items: items.slice( offset, offset + limit ) }; // eslint-disable-line no-param-reassign
 			}
-		} else {
+		} else if ( isKeyed ) {
 			const normalized = normalizePathname( this.prefix + modelName + "/" + route );
+			const base = endpoints[normalized] = {}; // eslint-disable-line no-param-reassign
 
-			if ( isKeyed ) {
-				const qualified = endpoints[normalized] = {}; // eslint-disable-line no-param-reassign
+			for ( const key of Object.keys( collection ) ) {
+				const items = collection[key].items;
 
-				for ( const key of Object.keys( collection ) ) {
-					const items = collection[key].items;
+				base[key] = { count: items.length };
 
-					qualified[key] = { count: items.length, items };
-				}
-			} else {
-				const items = collection.items;
+				if ( definition.reduce ) {
+					// generate single endpoint listing all items of collection grouped by key
+					base[key].items = items;
+				} else {
+					// expose separate endpoint per group of items
+					const subNormalized = normalizePathname( this.prefix + modelName + "/" + route + "/" + key );
 
-				endpoints[normalized] = { count: items.length, items }; // eslint-disable-line no-param-reassign
+					endpoints[subNormalized] = { count: items.length, items }; // eslint-disable-line no-param-reassign
+				}
 			}
+		} else {
+			const normalized = normalizePathname( this.prefix + modelName + "/" + route );
+			const items = collection.items;
+
+			endpoints[normalized] = { count: items.length, items }; // eslint-disable-line no-param-reassign
 		}
 	}
 
@@ -410,7 +892,7 @@ export class Shaper extends EventEmitter {
 	 * Creates managed data space for evaluating terms in context of a set of
 	 * items.
 	 *
-	 * @param {object<string,DatabaseKeyedCollection>} models pool of items per discovered model
+	 * @param {Object<string,Object<string,CollectedItem>>} models pool of items per discovered model
 	 * @param {string} modelName name of model to process
 	 * @param {ShapeCollection} collectionDefinition rules controlling compilation of collection
 	 * @returns {{handler: {get: ((function(*, *=): (*))|*)}, context: {$models, $model, $collection}}} handler and extensible context for term evaluation
@@ -438,7 +920,7 @@ export class Shaper extends EventEmitter {
 	/**
 	 * Compiles collection according to its definition in provided shape.
 	 *
-	 * @param {object<string,DatabaseKeyedCollection>} models pool of items per discovered model
+	 * @param {Object<string,Object<string,CollectedItem>>} models pool of items per discovered model
 	 * @param {string} modelName name of model to process
 	 * @param {ShapeCollection} definition rules controlling compilation of collection
 	 * @param {string} route route for resulting collection
@@ -451,7 +933,7 @@ export class Shaper extends EventEmitter {
 		const collection = isKeyed ? {} : { items: [] };
 
 
-		const { handler, context } = this.createTermContextCollection();
+		const { handler, context } = this.createTermContextCollection( models, modelName, definition );
 
 
 		// prepare terms used in compiling collection
@@ -492,7 +974,7 @@ export class Shaper extends EventEmitter {
 
 		// process all items of model
 		for ( const id in model ) {
-			if ( model.hasOwnProperty( id ) && typeof id === "string" && id[0] !== "$" ) {
+			if ( model[id] && typeof id === "string" && id[0] !== "$" ) {
 				const item = model[id];
 				const data = new Proxy( item, handler );
 				let extracted;
@@ -548,7 +1030,7 @@ export class Shaper extends EventEmitter {
 	/**
 	 * Sorts provided collection either in-place or as a copy.
 	 *
-	 * @param {object<string,DatabaseKeyedCollection>} models pool of items per discovered model
+	 * @param {Object<string,Object<string,CollectedItem>>} models pool of items per discovered model
 	 * @param {string} modelName name of model to process
 	 * @param {ShapeCollection} collectionDefinition rules controlling compilation of collection
 	 * @param {string} route route for resulting collection