@cepharum/concrete-db 0.3.0 → 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

@@ -172,7 +172,7 @@ export class Shaper extends EventEmitter {
 		metaProperties.$id = await this.identifyRecord( augmentedData, metaProperties.$shape );
 
 		if ( !itemsPerModel.hasOwnProperty( metaProperties.$model ) ) {
-			// eslint-disable-next-line no-param-reassign
+
 			itemsPerModel[metaProperties.$model] = {};
 		}
 
@@ -257,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];
@@ -454,7 +461,9 @@ export class Shaper extends EventEmitter {
 							$original: item.$original,
 							$shape: targetModelShape,
 							$model: targetModelName,
-							$id: targetId,
+							$id: id,
+							$targetid: id,
+							$targetindex: index,
 						} );
 
 						// track contributions to selected target item or its variant
@@ -465,7 +474,7 @@ export class Shaper extends EventEmitter {
 						let target;
 
 						if ( !itemsPerModel.hasOwnProperty( targetModelName ) ) {
-							// eslint-disable-next-line no-param-reassign
+
 							itemsPerModel[targetModelName] = {};
 						}
 
@@ -492,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];
@@ -525,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];
@@ -761,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];
@@ -836,7 +853,7 @@ 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];
 			}
 
 			await this.populateModelCollections( endpoints, models, modelName, mergedLocalShapes );
@@ -858,23 +875,8 @@ export class Shaper extends EventEmitter {
 	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;
 
@@ -891,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 = await 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;
@@ -971,11 +965,11 @@ export class Shaper extends EventEmitter {
 
 			for ( let offset = 0; offset < items.length; offset += limit ) {
 				const normalized = normalizePathname( prefix + route.replace( ptnOffset, String( offset ) ) );
-				endpoints[normalized] = { count: items.length, items: items.slice( offset, offset + limit ) }; // eslint-disable-line no-param-reassign
+				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;
@@ -989,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 };
 		}
 	}
 
@@ -1155,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
@@ -1163,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 {
@@ -1215,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 ) );
@@ -1233,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.3.0",
+	"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.12.0",
 		"file-essentials": "^0.1.2",
 		"lodash.merge": "^4.6.2",
 		"minimist": "^1.2.8",
 		"promise-essentials": "^0.2.0",
-		"simple-terms": "^0.4.1",
-		"yaml": "^2.2.2"
+		"simple-terms": "^0.5.0",
+		"yaml": "^2.9.0"
 	},
 	"devDependencies": {
-		"c8": "^7.13.0",
-		"eslint": "^8.40.0",
-		"eslint-config-cepharum": "^1.0.13",
-		"eslint-plugin-promise": "^6.1.1",
-		"mocha": "^10.2.0",
-		"should": "^13.2.3",
-		"vuepress": "^1.9.9",
-		"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",