@cepharum/concrete-db 0.2.2 → 0.4.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2022 cepharum GmbH
+Copyright (c) 2026 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

package/cure.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import File from "fs";
 import Path from "path";
+import { pathToFileURL } from "url";
 
 import minimist from "minimist";
 import YAML from "yaml";
@@ -28,7 +29,8 @@ Supported options are:
         --debug             be extra verbose
  -s  /  --shape=file        selects global shape controlling transformation
  -o  /  --output=folder     selects folder resulting files are written to
- -c  /  --clean             remove all existing files from output folder
+ -c  /  --clean             remove stale files from output folder that aren't
+                            part of the freshly cured database
  -l  /  --library=file      selects file exposing custom term functions to use
                             in addition to regular ones
 ` );
@@ -56,17 +58,14 @@ if ( args.V || args.version ) {
 
 	options.library = {};
 	for ( const library of libraries ) {
-		let pathname = Path.resolve( ".", library );
+		const pathname = Path.resolve( ".", library );
 
 		if ( options.verbose ) {
 			console.error( `including library ${pathname}` );
 		}
 
-		if ( /^[a-z]:/i.test( pathname ) ) {
-			pathname = "file://" + pathname.replace( /\//g, "%2F" );
-		}
-
-		const functions = await import( pathname ); // eslint-disable-line no-await-in-loop
+		// import via file URL so absolute paths work cross-platform (incl. Windows drive letters)
+		const functions = await import( pathToFileURL( pathname ).href ); // eslint-disable-line no-await-in-loop
 
 		for ( const name of Object.keys( functions ) ) {
 			if ( options.verbose > 1 ) {

package/lib/generator.mjs

@@ -44,6 +44,10 @@ export class Generator extends EventEmitter {
 				console.error( `cleaning output folder ${subfolder} ...` );
 			}
 
+			// routes of all endpoints to keep (matching the names of files written
+			// below), used to detect stale files left over from previous curing
+			const known = new Set( Object.keys( endpoints ).map( key => key.replace( /\.json$/, "" ) ) );
+
 			await FileEssentials.find( subfolder, {
 				depthFirst: true,
 				filter: ( localPath, fullPath, stat ) => {
@@ -54,10 +58,23 @@ export class Generator extends EventEmitter {
 					return stat.isFile();
 				},
 				converter: ( localPath, fullPath, stat ) => {
-					const name = fullPath.replace( /\.json$/, "" );
+					if ( stat.isDirectory() ) {
+						// keep the freshly created prefix folder itself even when
+						// it is (currently) empty
+						if ( Path.resolve( fullPath ) === Path.resolve( subfolder ) ) {
+							return undefined;
+						}
+
+						// drop directories that became empty after removing stale
+						// files (depth-first ensures children are handled first);
+						// keep directories still holding files of the database
+						return File.promises.rmdir( fullPath ).catch( () => undefined );
+					}
+
+					const route = Path.relative( folder, fullPath ).replace( /\.json$/, "" ).split( Path.sep ).join( "/" );
 
-					if ( !database.hasOwnProperty( name ) ) {
-						return stat.isDirectory() ? File.promises.rmdir( fullPath ) : File.promises.unlink( fullPath );
+					if ( !known.has( route ) ) {
+						return File.promises.unlink( fullPath );
 					}
 
 					return undefined;

package/lib/helper.mjs

@@ -1,5 +1,3 @@
-export * from "simple-terms/lib/helper.js";
-
 /**
  * Wraps provided object in a proxy offering case-insensitive access on
  * object's properties. Any accessed property's value is wrapped before
@@ -93,10 +91,22 @@ export class ForeignKey {
 /**
  * Deeply freezes provided object and all its properties recursively.
  *
+ * Non-object values are returned as-is. Already frozen objects are skipped which
+ * keeps the recursion safe in case of cyclic references.
+ *
  * @param {object} object object to freeze deeply; will be frozen on return, too
  * @returns {object} deeply frozen object
  */
 export function deepFreeze( object ) {
-	// FIXME implement actually deep freezing of provided object
-	return Object.freeze( object );
+	if ( !object || typeof object !== "object" || Object.isFrozen( object ) ) {
+		return object;
+	}
+
+	Object.freeze( object );
+
+	for ( const value of Object.values( object ) ) {
+		deepFreeze( value );
+	}
+
+	return object;
 }

package/lib/shaper.mjs

@@ -1,4 +1,5 @@
 // noinspection ExceptionCaughtLocallyJS
+/* eslint-disable no-await-in-loop */
 
 import EventEmitter from "events";
 
@@ -50,16 +51,17 @@ export class Shaper extends EventEmitter {
 	 * @param {Shape[]} localShapes local shapes of folders records have been collected from
 	 * @returns {Database} resulting database records
 	 */
-	transform( recordsCollection, localShapes ) {
+	async transform( recordsCollection, localShapes ) {
 		if ( recordsCollection.size > 0 && !localShapes?.length ) {
 			throw new Error( "invalid use of Shaper: missing list of local shapes per folder records have been collected from" );
 		}
 
 		const mergedLocalShapes = merge( {}, DefaultShape, ...localShapes );
-		const models = this.handleContributions( this.groupByModel( recordsCollection ), mergedLocalShapes );
+		const grouped = await this.groupByModel( recordsCollection );
+		const models = await this.handleContributions( grouped, mergedLocalShapes );
 		const endpoints = {};
 
-		this.populateModels( endpoints, models, mergedLocalShapes );
+		await this.populateModels( endpoints, models, mergedLocalShapes );
 
 		return { prefix: this.prefix, endpoints };
 	}
@@ -70,7 +72,7 @@ export class Shaper extends EventEmitter {
 	 * @param {Map<string,CollectedRecord[]>} collectedRecordsByName collection of records to transform
 	 * @returns {Object<string,Object<string, ModelItem>>} provided records grouped by model and unique item ID
 	 */
-	groupByModel( collectedRecordsByName ) {
+	async groupByModel( collectedRecordsByName ) {
 		const globalItemsPerModel = {};
 		let index = 0;
 
@@ -83,7 +85,7 @@ export class Shaper extends EventEmitter {
 				process.stderr.write( `\r[${++index}/${collectedRecordsByName.size}]` );
 			}
 
-			this.compileRecords( globalItemsPerModel, records );
+			await this.compileRecords( globalItemsPerModel, records );
 		}
 
 		return globalItemsPerModel;
@@ -97,20 +99,20 @@ export class Shaper extends EventEmitter {
 	 * @param {Shape} mergedLocalShapes local shapes of source folders merged in order of collecting records
 	 * @returns {Object<string,Object<string, CollectedRecord[]>>} collections of items per model as provided
 	 */
-	handleContributions( globalItemsPerModel, mergedLocalShapes ) {
+	async handleContributions( globalItemsPerModel, mergedLocalShapes ) {
 		const postProcessingQueue = new Set();
 
 		if ( this.options.verbose ) {
 			console.error( `\nprocessing contributions ...` );
 		}
 
-		this.processContributions( globalItemsPerModel, postProcessingQueue, mergedLocalShapes );
+		await this.processContributions( globalItemsPerModel, postProcessingQueue, mergedLocalShapes );
 
 		if ( this.options.verbose ) {
 			console.error( `post-processing ${postProcessingQueue.size} contributions` );
 		}
 
-		this.recompileContributionTargets( globalItemsPerModel, postProcessingQueue );
+		await this.recompileContributionTargets( globalItemsPerModel, postProcessingQueue );
 
 		return globalItemsPerModel;
 	}
@@ -123,11 +125,11 @@ export class Shaper extends EventEmitter {
 	 * @param {CollectedRecord[]} records list of records collected from a source
 	 * @returns {Object<string,Object<string,ModelItem>>} compiled items grouped by model, addressable by either item's ID
 	 */
-	compileRecords( itemsPerModel, records ) {
+	async compileRecords( itemsPerModel, records ) {
 		const shapesPerModelCache = {};
 
 		for ( let read = 0, numRecords = records.length; read < numRecords; read++ ) {
-			const item = this.compileModelItemFromRecord( shapesPerModelCache, itemsPerModel, records[read] );
+			const item = await this.compileModelItemFromRecord( shapesPerModelCache, itemsPerModel, records[read] );
 			const modelPool = itemsPerModel[item.$model];
 
 			if ( item.$variantId == null ) {
@@ -154,9 +156,9 @@ export class Shaper extends EventEmitter {
 	 * @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
+	 * @returns {Promise<ModelItem>} instance of model with hidden meta information injected
 	 */
-	compileModelItemFromRecord( shapesPerModelCache, itemsPerModel, record ) {
+	async compileModelItemFromRecord( shapesPerModelCache, itemsPerModel, record ) {
 		const { segments, shape, data } = record;
 
 		const metaProperties = {
@@ -165,19 +167,19 @@ export class Shaper extends EventEmitter {
 
 		const augmentedData = augmentDataSpace( data, metaProperties );
 
-		metaProperties.$model = this.detectModel( augmentedData, shape );
+		metaProperties.$model = await this.detectModel( augmentedData, shape );
 		metaProperties.$shape = this.getShapeOfModel( shapesPerModelCache, shape, metaProperties.$model );
-		metaProperties.$id = this.identifyRecord( augmentedData, metaProperties.$shape );
+		metaProperties.$id = await this.identifyRecord( augmentedData, metaProperties.$shape );
 
 		if ( !itemsPerModel.hasOwnProperty( metaProperties.$model ) ) {
-			// eslint-disable-next-line no-param-reassign
+
 			itemsPerModel[metaProperties.$model] = {};
 		}
 
 		const model = itemsPerModel[metaProperties.$model];
 
 		const { properties, defaults } = metaProperties.$shape;
-		const item = this.compileItem( augmentedData, properties, model[metaProperties.$id] ? {} : defaults );
+		const item = await this.compileItem( augmentedData, properties, model[metaProperties.$id] ? {} : defaults );
 
 		Object.defineProperties( item, {
 			$segments: { value: segments },
@@ -185,7 +187,7 @@ export class Shaper extends EventEmitter {
 			$shape: { value: metaProperties.$shape, configurable: true },
 			$model: { value: metaProperties.$model },
 			$id: { value: metaProperties.$id },
-			$variantId: { value: this.computeVariantIdOfItem( metaProperties.$shape.properties.$variant, augmentedData ) },
+			$variantId: { value: await this.computeVariantIdOfItem( metaProperties.$shape.properties.$variant, augmentedData ) },
 		} );
 
 		return item;
@@ -200,9 +202,9 @@ export class Shaper extends EventEmitter {
 	 * @param {ModelItem} item previously compiled item to re-compile
 	 * @returns {ModelItem} re-compiled item
 	 */
-	recompileItem( item ) {
+	async recompileItem( item ) {
 		const data = augmentDataSpace( merge( {}, item.$original, item ), { ...item, $post: true } );
-		const updatedItem = this.compileItem( data, item.$shape.properties, {} );
+		const updatedItem = await this.compileItem( data, item.$shape.properties, {} );
 
 		Object.defineProperties( updatedItem, {
 			$segments: { value: item.$segments },
@@ -221,9 +223,9 @@ export class Shaper extends EventEmitter {
 	 *
 	 * @param {string?} term term expressing computation of variant ID
 	 * @param {ModelItem} item an item to get variant ID for
-	 * @returns {null|any} computed variant ID of provided item, nullish if item is not a variant
+	 * @returns {Promise<null|any>} computed variant ID of provided item, nullish if item is not a variant
 	 */
-	computeVariantIdOfItem( term, item ) {
+	async computeVariantIdOfItem( term, item ) {
 		if ( term == null ) {
 			return null;
 		}
@@ -232,7 +234,7 @@ export class Shaper extends EventEmitter {
 		const data = augmentDataSpace( merge( {}, item.$original, item ), item );
 
 		try {
-			const value = Compiler.compile( String( term ), this.termFunctions, this.termsCache )( data );
+			const value = await Compiler.compile( String( term ), this.termFunctions, this.termsCache )( data );
 
 			// support processed term requesting to fail computation of variant ID
 			if ( value instanceof Error ) {
@@ -255,8 +257,15 @@ export class Shaper extends EventEmitter {
 	 */
 	getShapeOfModel( shapesPerModelCache, localShape, modelName ) {
 		if ( !shapesPerModelCache.hasOwnProperty( modelName ) ) {
-			// eslint-disable-next-line no-param-reassign
-			shapesPerModelCache[modelName] = merge( { defaults: DefaultShape.common.defaults }, localShape?.common, localShape?.models?.[modelName] );
+
+			// NOTE: `{ defaults: {} }` must be a fresh target so the subsequent
+			// merges never write into the shared module-level DefaultShape.
+			shapesPerModelCache[modelName] = merge(
+				{ defaults: {} },
+				{ defaults: DefaultShape.common.defaults },
+				localShape?.common,
+				localShape?.models?.[modelName]
+			);
 		}
 
 		return shapesPerModelCache[modelName];
@@ -354,7 +363,7 @@ export class Shaper extends EventEmitter {
 	 * @param {Shape} mergedLocalShapes local shapes of source folders merged in order of collecting records
 	 * @returns {void}
 	 */
-	processContributions( itemsPerModel, contributedItems, mergedLocalShapes ) {
+	async processContributions( itemsPerModel, contributedItems, mergedLocalShapes ) {
 		const contributingModels = this.listContributingModels( itemsPerModel );
 		const shapePerModelCache = {};
 
@@ -427,7 +436,7 @@ export class Shaper extends EventEmitter {
 					};
 
 					const augmentedData = augmentDataSpace( item, contributionMeta );
-					const targetId = this.computeId( contributionTerms.$id, augmentedData );
+					const targetId = await this.computeId( contributionTerms.$id, augmentedData );
 
 					if ( !isOptionalContribution && ( !targetId || ( Array.isArray( targetId ) && !targetId.length ) ) ) {
 						console.warn( `ignoring contribution of record #${item.$id} in model ${item.$model} to model ${targetModelName} due to lack of target ID` ); // eslint-disable-line max-len
@@ -446,13 +455,15 @@ export class Shaper extends EventEmitter {
 
 
 						// try computing variant ID based on contributing item
-						const variantId = this.computeVariantIdOfItem( contributionTerms.$variant, {
+						const variantId = await this.computeVariantIdOfItem( contributionTerms.$variant, {
 							...item,
 							$segments: item.$segments,
 							$original: item.$original,
 							$shape: targetModelShape,
 							$model: targetModelName,
-							$id: targetId,
+							$id: id,
+							$targetid: id,
+							$targetindex: index,
 						} );
 
 						// track contributions to selected target item or its variant
@@ -463,7 +474,7 @@ export class Shaper extends EventEmitter {
 						let target;
 
 						if ( !itemsPerModel.hasOwnProperty( targetModelName ) ) {
-							// eslint-disable-next-line no-param-reassign
+
 							itemsPerModel[targetModelName] = {};
 						}
 
@@ -490,7 +501,15 @@ export class Shaper extends EventEmitter {
 							}
 
 							if ( !targetItem.$variants.hasOwnProperty( variantId ) ) {
-								targetItem.$variants[variantId] = {};
+								// a variant target needs the same meta properties as a
+								// regular target item so it can be recompiled afterwards
+								targetItem.$variants[variantId] = Object.defineProperties( {}, {
+									$segments: { value: item.$segments },
+									$original: { value: {}, configurable: true },
+									$shape: { value: targetModelShape, configurable: true },
+									$model: { value: targetModelName },
+									$id: { value: id },
+								} );
 							}
 
 							target = targetItem.$variants[variantId];
@@ -499,7 +518,7 @@ export class Shaper extends EventEmitter {
 
 						// compile actual properties of contribution
 						const contributionDefaults = targetItemExists || variantId != null ? {} : targetModelShape.defaults;
-						const contribution = this.compileItem( augmentedData, contributionTerms, contributionDefaults );
+						const contribution = await this.compileItem( augmentedData, contributionTerms, contributionDefaults );
 
 
 						// merge this item's contribution with existing
@@ -523,7 +542,7 @@ export class Shaper extends EventEmitter {
 							if ( $isCollecting ) {
 								// contribution has been declared with one or more suffices, e.g. []
 								// -> collect value in target
-								if ( Array.isArray( target[name] ) ) { // eslint-disable-line no-lonely-if,max-depth
+								if ( Array.isArray( target[name] ) ) { // eslint-disable-line max-depth
 									target[name].push( value );
 								} else if ( target[name] == null ) {
 									target[name] = [value];
@@ -614,7 +633,7 @@ export class Shaper extends EventEmitter {
 	 * @param {Set<string>} contributions lists IDs of items or their variants that have been contributed to
 	 * @returns {Object<string,Object<string,ModelItem>>} pool of items per model as provided
 	 */
-	recompileContributionTargets( itemsPerModel, contributions ) {
+	async recompileContributionTargets( itemsPerModel, contributions ) {
 		for ( const track of contributions.values() ) {
 			const [ model, id, variantId ] = JSON.parse( track );
 
@@ -633,7 +652,7 @@ export class Shaper extends EventEmitter {
 			const item = modelPool[id];
 
 			if ( variantId == null ) {
-				modelPool[id] = this.recompileItem( item );
+				modelPool[id] = await this.recompileItem( item );
 			} else {
 				if ( !item.$variants ) {
 					console.warn( `inconsistency: missing variants of item ${id} of model ${model} though contributions have been tracked` );
@@ -647,7 +666,7 @@ export class Shaper extends EventEmitter {
 					continue;
 				}
 
-				variants[variantId] = this.recompileItem( variants[variantId] );
+				variants[variantId] = await this.recompileItem( variants[variantId] );
 			}
 		}
 
@@ -659,16 +678,16 @@ export class Shaper extends EventEmitter {
 	 *
 	 * @param {object} data source of record
 	 * @param {Shape} shape shape of database affecting record
-	 * @returns {string} name of model to use
+	 * @returns {Promise<string>} name of model to use
 	 */
-	detectModel( data, shape ) {
+	async detectModel( data, shape ) {
 		const selector = shape?.common?.properties?.$model;
 
 		if ( !selector || typeof selector !== "string" ) {
 			throw new Error( "missing or invalid definition of common property $model in shape" );
 		}
 
-		const name = Compiler.compile( selector, this.termFunctions, this.termsCache )( data );
+		const name = await Compiler.compile( selector, this.termFunctions, this.termsCache )( data );
 
 		// support processed term requesting to fail model detection
 		if ( name instanceof Error ) {
@@ -687,10 +706,10 @@ export class Shaper extends EventEmitter {
 	 *
 	 * @param {object} data source of record
 	 * @param {ShapeModel} modelShape shape of particular model
-	 * @returns {string} ID of record
+	 * @returns {Promise<string>} ID of record
 	 */
-	identifyRecord( data, modelShape ) {
-		const id = this.computeId( modelShape?.properties?.$id, data );
+	async identifyRecord( data, modelShape ) {
+		const id = await this.computeId( modelShape?.properties?.$id, data );
 
 		if ( !id ) {
 			throw new Error( `detecting ID of item related to record ${data.$segments.join( "/" )} failed` );
@@ -706,9 +725,9 @@ export class Shaper extends EventEmitter {
 	 * @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
+	 * @returns {Promise<Partial<ModelItem>>} compiled item
 	 */
-	compileItem( data, properties = {}, defaults = {}, accept = [] ) {
+	async compileItem( data, properties = {}, defaults = {}, accept = [] ) {
 		const item = {};
 
 		for ( const property of Object.keys( properties ) ) {
@@ -728,7 +747,7 @@ export class Shaper extends EventEmitter {
 				let value;
 
 				try {
-					value = Compiler.compile( term, this.termFunctions, this.termsCache )( data );
+					value = await Compiler.compile( term, this.termFunctions, this.termsCache )( data );
 
 					// support processed term requesting to fail computation of property's value
 					if ( value instanceof Error ) {
@@ -745,7 +764,7 @@ export class Shaper extends EventEmitter {
 
 						try {
 							const code = trimmed.startsWith( "=" ) ? trimmed.slice( 1 ) : undefined;
-							value = code ? Compiler.compile( code, this.termFunctions, this.termsCache )( data ) : defaultValue;
+							value = code ? await Compiler.compile( code, this.termFunctions, this.termsCache )( data ) : defaultValue;
 
 							// support processed term requesting to fail computation of default value
 							if ( value instanceof Error ) {
@@ -759,7 +778,7 @@ export class Shaper extends EventEmitter {
 
 				if ( value != null ) {
 					if ( isCollecting ) {
-						if ( Array.isArray( item[propertyName] ) ) { // eslint-disable-line no-lonely-if
+						if ( Array.isArray( item[propertyName] ) ) {
 							item[propertyName].push( value );
 						} else if ( item[propertyName] == null ) {
 							item[propertyName] = [value];
@@ -783,15 +802,15 @@ export class Shaper extends EventEmitter {
 	 *
 	 * @param {string} term term to process
 	 * @param {object} data data space available to term processing
-	 * @returns {any} processed term's result
+	 * @returns {Promise<any>} processed term's result
 	 */
-	computeId( term, data ) {
+	async computeId( term, data ) {
 		if ( !term || typeof term !== "string" ) {
 			throw new Error( `missing or invalid term for computing ID of ${data.$segments.join( "/" )}` );
 		}
 
 		try {
-			const value = Compiler.compile( term, this.termFunctions, this.termsCache )( data );
+			const value = await Compiler.compile( term, this.termFunctions, this.termsCache )( data );
 
 			// support processed term requesting to fail computation of ID
 			if ( value instanceof Error ) {
@@ -812,7 +831,7 @@ export class Shaper extends EventEmitter {
 	 * @param {Shape} mergedLocalShapes local shapes of source folders merged in order of collecting records
 	 * @returns {DatabaseEndpoints} map of routes into data sets to expose eventually
 	 */
-	populateModels( endpoints, models, mergedLocalShapes ) {
+	async populateModels( endpoints, models, mergedLocalShapes ) {
 		const modelNames = Object.keys( models );
 		let index = 0;
 
@@ -834,10 +853,10 @@ export class Shaper extends EventEmitter {
 					throw new Error( `item ID "${itemId}" of model "${modelName}" results in invalid route for endpoint exposing it` );
 				}
 
-				endpoints[normalized] = model[itemId]; // eslint-disable-line no-param-reassign
+				endpoints[normalized] = model[itemId];
 			}
 
-			this.populateModelCollections( endpoints, models, modelName, mergedLocalShapes );
+			await this.populateModelCollections( endpoints, models, modelName, mergedLocalShapes );
 		}
 
 		return endpoints;
@@ -853,26 +872,11 @@ export class Shaper extends EventEmitter {
 	 * @param {Shape} mergedLocalShapes local shapes of source folders merged in order of collecting records
 	 * @returns {DatabaseEndpoints} map of routes into data sets to expose eventually
 	 */
-	populateModelCollections( endpoints, models, modelName, mergedLocalShapes ) {
+	async populateModelCollections( endpoints, models, modelName, mergedLocalShapes ) {
 		const finalModelShape = merge( {}, mergedLocalShapes.common, mergedLocalShapes.models[modelName] );
 		const collections = finalModelShape.collections || {};
-		const cache = {};
-
-		// prepare to process collection instances prior to collection references
 		const keys = Object.keys( collections );
 
-		keys.sort( ( l, r ) => {
-			if ( l.reference ) {
-				cache[l.reference] = null;
-			}
-
-			if ( r.reference ) {
-				cache[r.reference] = null;
-			}
-
-			return l.reference ? r.reference ? 0 : 1 : r.reference ? -1 : 0;
-		} );
-
 		// process collection by collection
 		let index = 0;
 
@@ -889,28 +893,20 @@ export class Shaper extends EventEmitter {
 
 			const definition = collections[route];
 			if ( definition && typeof definition === "object" ) {
-				let collection;
-				let isKeyed;
-
-				// compile (and cache) collection or re-use collection found in cache?
-				if ( definition.reference ) {
-					collection = cache[definition.reference];
-					isKeyed = collection.$isKeyed;
-				} else {
-					collection = this.compileCollection( models, modelName, definition, normalized );
-					isKeyed = definition.key && typeof definition.key === "string";
-
-					Object.defineProperties( collection, {
-						$isKeyed: { value: isKeyed },
-					} );
-
-					if ( cache.hasOwnProperty( normalized ) ) {
-						cache[route] = collection;
-					}
+				// The `reference` rule for re-using another collection's extracted
+				// items has been retired: it never worked correctly and is
+				// superseded by YAML anchors/aliases for sharing definitions.
+				// (Check for presence, not truthiness — the documented usage was
+				// `reference: ""` addressing the unnamed root collection.)
+				if ( Object.prototype.hasOwnProperty.call( definition, "reference" ) ) {
+					throw new Error( `collection "${normalized}" of model "${modelName}" uses the retired "reference" rule; `
+						+ `share collection definitions via YAML anchors/aliases instead` );
 				}
 
-				const isCached = definition.reference || cache.hasOwnProperty( route );
-				collection = this.sortCollection( models, modelName, definition, normalized, collection, isKeyed, isCached );
+				const isKeyed = definition.key && typeof definition.key === "string";
+				let collection = await this.compileCollection( models, modelName, definition, normalized );
+
+				collection = this.sortCollection( models, modelName, definition, normalized, collection, isKeyed );
 
 				// provide separate endpoints per key of collection?
 				ptnKey.lastIndex = 0;
@@ -968,12 +964,12 @@ export class Shaper extends EventEmitter {
 			const items = collection.items;
 
 			for ( let offset = 0; offset < items.length; offset += limit ) {
-				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
+				const normalized = normalizePathname( prefix + route.replace( ptnOffset, String( offset ) ) );
+				endpoints[normalized] = { count: items.length, items: items.slice( offset, offset + limit ) };
 			}
 		} else if ( isKeyed ) {
 			const normalized = normalizePathname( this.prefix + modelName + "/" + route );
-			const base = endpoints[normalized] = {}; // eslint-disable-line no-param-reassign
+			const base = endpoints[normalized] = {};
 
 			for ( const key of Object.keys( collection ) ) {
 				const items = collection[key].items;
@@ -987,14 +983,14 @@ export class Shaper extends EventEmitter {
 					// expose separate endpoint per group of items
 					const subNormalized = normalizePathname( this.prefix + modelName + "/" + route + "/" + key );
 
-					endpoints[subNormalized] = { count: items.length, items }; // eslint-disable-line no-param-reassign
+					endpoints[subNormalized] = { count: items.length, items };
 				}
 			}
 		} else {
 			const normalized = normalizePathname( this.prefix + modelName + "/" + route );
 			const items = collection.items;
 
-			endpoints[normalized] = { count: items.length, items }; // eslint-disable-line no-param-reassign
+			endpoints[normalized] = { count: items.length, items };
 		}
 	}
 
@@ -1036,7 +1032,7 @@ export class Shaper extends EventEmitter {
 	 * @param {string} route route for resulting collection
 	 * @returns {DatabaseCollection} compiled collection
 	 */
-	compileCollection( models, modelName, definition, route ) {
+	async compileCollection( models, modelName, definition, route ) {
 		const model = models[modelName];
 		const { key: $key, filter: $filter, properties: $properties } = definition;
 		const isKeyed = $key && typeof $key === "string";
@@ -1107,9 +1103,9 @@ export class Shaper extends EventEmitter {
 				context.$id = id;
 
 				// ignore this item or prepare its spot in resulting collection?
-				if ( !filterFn || filterFn( data ) ) {
+				if ( !filterFn || await filterFn( data ) ) {
 					if ( isKeyed ) {
-						const key = keyFn( data );
+						const key = await keyFn( data );
 						if ( key != null ) {
 							const _key = String( key );
 
@@ -1135,7 +1131,7 @@ export class Shaper extends EventEmitter {
 					if ( propertiesFn ) {
 						// compile custom representation of item in collection
 						for ( const fn of propertiesFn ) {
-							extracted[fn.target] = fn( data );
+							extracted[fn.target] = await fn( data );
 						}
 					} else {
 						// expose all properties of item in collection, too
@@ -1153,7 +1149,7 @@ export class Shaper extends EventEmitter {
 	}
 
 	/**
-	 * Sorts provided collection either in-place or as a copy.
+	 * Sorts provided collection in-place.
 	 *
 	 * @param {Object<string,Object<string,ModelItem>>} models pool of items per discovered model
 	 * @param {string} modelName name of model to process
@@ -1161,10 +1157,9 @@ export class Shaper extends EventEmitter {
 	 * @param {string} route route for resulting collection
 	 * @param {DatabaseCollection} collection collection to sort
 	 * @param {boolean} isKeyed true if collection is a keyed collection instead of regular one
-	 * @param {boolean} copy true if collection must not be sorted in-place
-	 * @returns {DatabaseCollection} sorted collection, can be same as `collection` or some copy of it
+	 * @returns {DatabaseCollection} provided collection sorted in-place
 	 */
-	sortCollection( models, modelName, collectionDefinition, route, collection, isKeyed, copy = false ) {
+	sortCollection( models, modelName, collectionDefinition, route, collection, isKeyed ) {
 		let $sort = collectionDefinition.sort;
 
 		try {
@@ -1213,7 +1208,7 @@ export class Shaper extends EventEmitter {
 
 				if ( _tl === _tr ) {
 					if ( _tl === "number" ) {
-						return dir * ( _tl - _tr );
+						return dir * ( _l - _r );
 					}
 
 					return dir * String( _l ).localeCompare( String( _r ) );
@@ -1231,30 +1226,17 @@ export class Shaper extends EventEmitter {
 			};
 		}
 
-		const sorted = copy ? {} : collection;
-
 		if ( isKeyed ) {
 			for ( const key in collection ) {
 				if ( collection.hasOwnProperty( key ) ) {
-					if ( copy ) {
-						const items = collection[key].items.slice( 0 );
-						items.sort( sorterFn );
-						sorted[key] = { items };
-					} else {
-						collection[key].items.sort( sorterFn );
-					}
+					collection[key].items.sort( sorterFn );
 				}
 			}
-		} else if ( copy ) {
-			const items = collection.items.slice( 0 );
-			items.sort( sorterFn );
-			sorted.items = items;
 		} else {
 			collection.items.sort( sorterFn );
 		}
 
-
-		return sorted;
+		return collection;
 	}
 }
 

package/package.json

@@ -1,45 +1,53 @@
 {
 	"name": "@cepharum/concrete-db",
-	"version": "0.2.2",
+	"version": "0.4.0",
 	"description": "a read-only web database generator",
-	"main": "lib/collector.mjs",
+	"type": "module",
+	"main": "lib/index.mjs",
 	"types": "concrete-db.d.ts",
+	"exports": {
+		".": {
+			"types": "./concrete-db.d.ts",
+			"import": "./lib/index.mjs"
+		},
+		"./package.json": "./package.json"
+	},
 	"bin": {
 		"cure": "cure.mjs"
 	},
 	"scripts": {
 		"cure": "node ./cure.mjs",
-		"lint": "eslint lib/**/*.{js,mjs,cjs} test/**/*.{js,mjs,cjs} cure.mjs",
-		"lint:fix": "eslint --fix lib/**/*.{js,mjs,cjs} test/**/*.{js,mjs,cjs} cure.mjs",
-		"test": "c8 mocha --ui=tdd --recursive test/**/*.spec.*",
+		"lint": "eslint .",
+		"lint:fix": "eslint --fix .",
+		"test": "vitest run",
+		"test:watch": "vitest",
+		"coverage": "vitest run --coverage",
 		"test:getting-started": "node ./test/curing.shell.mjs",
-		"docs:dev": "vuepress dev docs",
-		"docs:build": "vuepress build docs"
+		"docs:dev": "vitepress dev docs",
+		"docs:build": "vitepress build docs"
 	},
 	"keywords": [],
 	"author": "cepharum GmbH",
 	"license": "MIT",
 	"dependencies": {
-		"ajv": "^8.11.0",
 		"file-essentials": "^0.1.2",
 		"lodash.merge": "^4.6.2",
-		"minimist": "^1.2.6",
+		"minimist": "^1.2.8",
 		"promise-essentials": "^0.2.0",
-		"simple-terms": "^0.4.0",
-		"yaml": "^2.1.0"
+		"simple-terms": "^0.5.0",
+		"yaml": "^2.9.0"
 	},
 	"devDependencies": {
-		"c8": "^7.11.3",
-		"eslint": "^8.16.0",
-		"eslint-config-cepharum": "^1.0.12",
-		"eslint-plugin-promise": "^6.0.0",
-		"mocha": "^10.0.0",
-		"should": "^13.2.3",
-		"vuepress": "^1.9.7",
-		"vuepress-plugin-mermaidjs": "^1.9.1"
+		"@vitest/coverage-v8": "^4.1.9",
+		"eslint": "^10.6.0",
+		"eslint-config-cepharum": "^2.0.2",
+		"mermaid": "^11.16.0",
+		"vitepress": "^1.6.4",
+		"vitepress-plugin-mermaid": "^2.0.17",
+		"vitest": "^4.1.9"
 	},
 	"engines": {
-		"node": ">=10"
+		"node": ">=20"
 	},
 	"files": [
 		"lib",