@fjell/core 4.4.70 → 4.4.73

package/dist/index.js

@@ -316,7 +316,9 @@ var locKeyArrayToItemKey = (lka) => {
     const comKey = { kt: priKey.kt, pk: priKey.pk, loc: locs };
     return comKey;
   } else {
-    throw new Error("locKeyArrayToItemKey: lka is undefined or empty");
+    throw new Error(
+      "locKeyArrayToItemKey: lka is undefined or empty. Expected non-empty LocKeyArray. Suggestion: Ensure you are passing a valid location key array, not undefined/null/empty array."
+    );
   }
 };
 var isValidPriKey = (key) => {
@@ -818,17 +820,43 @@ var abbrevCondition = (condition) => {
 var logger5 = logger_default.get("validation", "ItemValidator");
 var validatePKForItem = (item, pkType) => {
   if (!item) {
-    logger5.error("Validating PK, Item is undefined", { item });
-    throw new Error("Validating PK, Item is undefined");
+    logger5.error("Item validation failed - item is undefined", {
+      component: "core",
+      operation: "validatePK",
+      expectedType: pkType,
+      item,
+      suggestion: "Ensure the operation returns a valid item object, not undefined/null"
+    });
+    throw new Error(
+      `Item validation failed: item is undefined. Expected item of type '${pkType}'. This usually indicates a database operation returned null/undefined unexpectedly.`
+    );
   }
   if (!item.key) {
-    logger5.error("Validating PK, Item does not have a key", { item });
-    throw new Error("Validating PK, Item does not have a key");
+    logger5.error("Item validation failed - item missing key", {
+      component: "core",
+      operation: "validatePK",
+      expectedType: pkType,
+      item,
+      suggestion: "Ensure the item has a valid key property with kt and pk fields"
+    });
+    throw new Error(
+      `Item validation failed: item does not have a key property. Expected key with type '${pkType}'. Item: ${JSON.stringify(item)}. This indicates a database processing error.`
+    );
   }
   const keyTypeArray = toKeyTypeArray(item.key);
   if (keyTypeArray[0] !== pkType) {
-    logger5.error("Key Type Array Mismatch", { keyTypeArray, pkType });
-    throw new Error(`Item does not have the correct primary key type. Expected ${pkType}, got ${keyTypeArray[0]}`);
+    logger5.error("Key type mismatch during validation", {
+      component: "core",
+      operation: "validatePK",
+      expectedType: pkType,
+      actualType: keyTypeArray[0],
+      keyTypeArray,
+      itemKey: item.key,
+      suggestion: `Ensure the item key has kt: '${pkType}', not '${keyTypeArray[0]}'`
+    });
+    throw new Error(
+      `Item has incorrect primary key type. Expected '${pkType}', got '${keyTypeArray[0]}'. Key: ${JSON.stringify(item.key)}. This indicates a data model mismatch.`
+    );
   }
   return item;
 };
@@ -842,19 +870,57 @@ var validatePK = (input, pkType) => {
 var validateKeys = (item, keyTypes) => {
   logger5.trace("Checking Return Type", { item });
   if (!item) {
-    throw new Error("validating keys, item is undefined");
+    logger5.error("Key validation failed - item is undefined", {
+      component: "core",
+      operation: "validateKeys",
+      expectedKeyTypes: keyTypes,
+      suggestion: "Ensure the operation returns a valid item object, not undefined/null"
+    });
+    throw new Error(
+      `Key validation failed: item is undefined. Expected item with key types [${keyTypes.join(", ")}]. This usually indicates a database operation returned null/undefined unexpectedly.`
+    );
   }
   if (!item.key) {
-    throw new Error("validating keys, item does not have a key: " + JSON.stringify(item));
+    logger5.error("Key validation failed - item missing key", {
+      component: "core",
+      operation: "validateKeys",
+      expectedKeyTypes: keyTypes,
+      item: JSON.stringify(item),
+      suggestion: "Ensure the item has a valid key property"
+    });
+    throw new Error(
+      `Key validation failed: item does not have a key property. Expected key with types [${keyTypes.join(", ")}]. Item: ${JSON.stringify(item)}. This indicates a database processing error.`
+    );
   }
   const keyTypeArray = toKeyTypeArray(item.key);
   if (keyTypeArray.length !== keyTypes.length) {
-    throw new Error(`Item does not have the correct number of keys. Expected ${keyTypes.length}, but got ${keyTypeArray.length}`);
+    logger5.error("Key hierarchy depth mismatch", {
+      component: "core",
+      operation: "validateKeys",
+      expectedKeyTypes: keyTypes,
+      expectedDepth: keyTypes.length,
+      actualKeyTypes: keyTypeArray,
+      actualDepth: keyTypeArray.length,
+      itemKey: item.key,
+      suggestion: `Check coordinate definition. Expected hierarchy depth of ${keyTypes.length}, got ${keyTypeArray.length}`
+    });
+    throw new Error(
+      `Item has incorrect key hierarchy depth. Expected ${keyTypes.length} levels [${keyTypes.join(" > ")}], but got ${keyTypeArray.length} levels [${keyTypeArray.join(" > ")}]. Key: ${JSON.stringify(item.key)}. This indicates a coordinate/hierarchy mismatch.`
+    );
   }
   const match = JSON.stringify(keyTypeArray) === JSON.stringify(keyTypes);
   if (!match) {
-    logger5.error("Key Type Array Mismatch", { keyTypeArray, thisKeyTypes: keyTypes });
-    throw new Error(`Item does not have the correct key types. Expected [${keyTypes.join(", ")}], but got [${keyTypeArray.join(", ")}]`);
+    logger5.error("Key Type Array Mismatch", {
+      component: "core",
+      operation: "validateKeys",
+      expectedKeyTypes: keyTypes,
+      actualKeyTypes: keyTypeArray,
+      itemKey: item.key,
+      suggestion: `Ensure item key matches expected hierarchy: [${keyTypes.join(" > ")}]`
+    });
+    throw new Error(
+      `Item has incorrect key types. Expected [${keyTypes.join(" > ")}], but got [${keyTypeArray.join(" > ")}]. Key: ${JSON.stringify(item.key)}. This indicates a data model mismatch.`
+    );
   }
   return item;
 };
@@ -1317,7 +1383,7 @@ var ValidationError = class extends ActionError {
       // Will be filled by wrapper
       details: {
         validOptions,
-        suggestedAction,
+        suggestedAction: suggestedAction || (validOptions && validOptions.length > 0 ? `Valid options are: ${validOptions.join(", ")}. Please use one of these values.` : "Check the validation requirements and ensure all fields meet the required format, type, and constraints."),
         retryable: true,
         conflictingValue,
         fieldErrors
@@ -1345,7 +1411,10 @@ var NotFoundError = class extends ActionError {
         itemType,
         key: typeof key === "object" ? key : { primary: key }
       },
-      details: { retryable: false },
+      details: {
+        suggestedAction: "Verify the item ID/key is correct, check if the item was deleted, or create the item if it should exist.",
+        retryable: false
+      },
       technical: {
         timestamp: (/* @__PURE__ */ new Date()).toISOString()
       }
@@ -1363,7 +1432,7 @@ var BusinessLogicError = class extends ActionError {
       operation: { type: "action", name: "", params: {} },
       context: { itemType: "" },
       details: {
-        suggestedAction,
+        suggestedAction: suggestedAction || "Review the business logic requirements and ensure all conditions are met before retrying.",
         retryable
       },
       technical: {
@@ -1434,6 +1503,7 @@ var DuplicateError = class extends ActionError {
         }
       },
       details: {
+        suggestedAction: duplicateField ? `An item with this ${duplicateField} already exists. Use a different ${duplicateField} value or update the existing item.` : "An item with this key already exists. Use a different key or update the existing item using upsert.",
         retryable: false,
         conflictingValue: duplicateField
       },
@@ -1884,7 +1954,17 @@ function createAllWrapper(coordinate, implementation, wrapperOptions = {}) {
       validateLocations(locations, coordinate, operationName);
       if (allOptions && "limit" in allOptions && allOptions.limit != null) {
         if (!Number.isInteger(allOptions.limit) || allOptions.limit < 1) {
-          throw new Error(`[${operationName}] limit must be a positive integer, got: ${allOptions.limit}`);
+          logger10.error(`Invalid limit parameter in ${operationName}`, {
+            component: "core",
+            wrapper: "createAllWrapper",
+            operation: operationName,
+            limit: allOptions.limit,
+            limitType: typeof allOptions.limit,
+            suggestion: "Use a positive integer (1, 2, 3, ...) for limit parameter"
+          });
+          throw new Error(
+            `[${operationName}] limit must be a positive integer, got: ${allOptions.limit} (${typeof allOptions.limit}). Suggestion: Use limit: 10 or similar positive integer value.`
+          );
         }
       }
       if (allOptions && "offset" in allOptions && allOptions.offset != null) {
@@ -1955,8 +2035,27 @@ function createGetWrapper(coordinate, implementation, options = {}) {
         throw options.onError(error, context);
       }
       if (error instanceof NotFoundError) {
+        logger11.debug(`[${operationName}] Item not found`, {
+          component: "core",
+          wrapper: "createGetWrapper",
+          operation: operationName,
+          key: JSON.stringify(key),
+          itemType: coordinate.kta[0],
+          note: "This is expected behavior when item does not exist"
+        });
         throw error;
       }
+      logger11.error(`[${operationName}] Operation failed in wrapper`, {
+        component: "core",
+        wrapper: "createGetWrapper",
+        operation: operationName,
+        key: JSON.stringify(key),
+        itemType: coordinate.kta[0],
+        errorType: error.constructor?.name,
+        errorMessage: error.message,
+        suggestion: "Check key validity, database connectivity, and implementation error handling",
+        coordinate: JSON.stringify(coordinate)
+      });
       throw new Error(
         `[${operationName}] Operation failed: ${error.message}`,
         { cause: error }
@@ -2009,6 +2108,18 @@ Received: ${Array.isArray(item) ? "array" : typeof item}`
         };
         throw wrapperOptions.onError(error, context);
       }
+      logger12.error(`[${operationName}] Operation failed in wrapper`, {
+        component: "core",
+        wrapper: "createCreateWrapper",
+        operation: operationName,
+        itemType: coordinate.kta[0],
+        hasKey: createOptions && "key" in createOptions,
+        hasLocations: createOptions && "locations" in createOptions,
+        errorType: error.constructor?.name,
+        errorMessage: error.message,
+        suggestion: "Check validation rules, required fields, unique constraints, and database connectivity",
+        coordinate: JSON.stringify(coordinate)
+      });
       throw new Error(
         `[${operationName}] Operation failed: ${error.message}`,
         { cause: error }
@@ -2133,6 +2244,17 @@ function createRemoveWrapper(coordinate, implementation, options = {}) {
         };
         throw options.onError(error, context);
       }
+      logger15.error(`[${operationName}] Operation failed in wrapper`, {
+        component: "core",
+        wrapper: "createRemoveWrapper",
+        operation: operationName,
+        key: JSON.stringify(key),
+        itemType: coordinate.kta[0],
+        errorType: error.constructor?.name,
+        errorMessage: error.message,
+        suggestion: "Check item exists, delete permissions, referential integrity, and database connectivity",
+        coordinate: JSON.stringify(coordinate)
+      });
       throw new Error(
         `[${operationName}] Operation failed: ${error.message}`,
         { cause: error }
@@ -2315,6 +2437,19 @@ function createActionWrapper(coordinate, implementation, options = {}) {
         };
         throw options.onError(error, context);
       }
+      logger18.error(`[${operationName}] Action failed in wrapper`, {
+        component: "core",
+        wrapper: "createActionWrapper",
+        operation: operationName,
+        action,
+        key: JSON.stringify(key),
+        params: JSON.stringify(params),
+        itemType: coordinate.kta[0],
+        errorType: error.constructor?.name,
+        errorMessage: error.message,
+        suggestion: "Check action name is valid, item exists, and action implementation",
+        coordinate: JSON.stringify(coordinate)
+      });
       throw new Error(
         `[${operationName}] Action "${action}" failed: ${error.message}`,
         { cause: error }

package/dist/validation/index.js

@@ -296,17 +296,43 @@ Received: '${key.kt}'`
 var logger4 = logger_default.get("validation", "ItemValidator");
 var validatePKForItem = (item, pkType) => {
   if (!item) {
-    logger4.error("Validating PK, Item is undefined", { item });
-    throw new Error("Validating PK, Item is undefined");
+    logger4.error("Item validation failed - item is undefined", {
+      component: "core",
+      operation: "validatePK",
+      expectedType: pkType,
+      item,
+      suggestion: "Ensure the operation returns a valid item object, not undefined/null"
+    });
+    throw new Error(
+      `Item validation failed: item is undefined. Expected item of type '${pkType}'. This usually indicates a database operation returned null/undefined unexpectedly.`
+    );
   }
   if (!item.key) {
-    logger4.error("Validating PK, Item does not have a key", { item });
-    throw new Error("Validating PK, Item does not have a key");
+    logger4.error("Item validation failed - item missing key", {
+      component: "core",
+      operation: "validatePK",
+      expectedType: pkType,
+      item,
+      suggestion: "Ensure the item has a valid key property with kt and pk fields"
+    });
+    throw new Error(
+      `Item validation failed: item does not have a key property. Expected key with type '${pkType}'. Item: ${JSON.stringify(item)}. This indicates a database processing error.`
+    );
   }
   const keyTypeArray = toKeyTypeArray(item.key);
   if (keyTypeArray[0] !== pkType) {
-    logger4.error("Key Type Array Mismatch", { keyTypeArray, pkType });
-    throw new Error(`Item does not have the correct primary key type. Expected ${pkType}, got ${keyTypeArray[0]}`);
+    logger4.error("Key type mismatch during validation", {
+      component: "core",
+      operation: "validatePK",
+      expectedType: pkType,
+      actualType: keyTypeArray[0],
+      keyTypeArray,
+      itemKey: item.key,
+      suggestion: `Ensure the item key has kt: '${pkType}', not '${keyTypeArray[0]}'`
+    });
+    throw new Error(
+      `Item has incorrect primary key type. Expected '${pkType}', got '${keyTypeArray[0]}'. Key: ${JSON.stringify(item.key)}. This indicates a data model mismatch.`
+    );
   }
   return item;
 };
@@ -320,19 +346,57 @@ var validatePK = (input, pkType) => {
 var validateKeys = (item, keyTypes) => {
   logger4.trace("Checking Return Type", { item });
   if (!item) {
-    throw new Error("validating keys, item is undefined");
+    logger4.error("Key validation failed - item is undefined", {
+      component: "core",
+      operation: "validateKeys",
+      expectedKeyTypes: keyTypes,
+      suggestion: "Ensure the operation returns a valid item object, not undefined/null"
+    });
+    throw new Error(
+      `Key validation failed: item is undefined. Expected item with key types [${keyTypes.join(", ")}]. This usually indicates a database operation returned null/undefined unexpectedly.`
+    );
   }
   if (!item.key) {
-    throw new Error("validating keys, item does not have a key: " + JSON.stringify(item));
+    logger4.error("Key validation failed - item missing key", {
+      component: "core",
+      operation: "validateKeys",
+      expectedKeyTypes: keyTypes,
+      item: JSON.stringify(item),
+      suggestion: "Ensure the item has a valid key property"
+    });
+    throw new Error(
+      `Key validation failed: item does not have a key property. Expected key with types [${keyTypes.join(", ")}]. Item: ${JSON.stringify(item)}. This indicates a database processing error.`
+    );
   }
   const keyTypeArray = toKeyTypeArray(item.key);
   if (keyTypeArray.length !== keyTypes.length) {
-    throw new Error(`Item does not have the correct number of keys. Expected ${keyTypes.length}, but got ${keyTypeArray.length}`);
+    logger4.error("Key hierarchy depth mismatch", {
+      component: "core",
+      operation: "validateKeys",
+      expectedKeyTypes: keyTypes,
+      expectedDepth: keyTypes.length,
+      actualKeyTypes: keyTypeArray,
+      actualDepth: keyTypeArray.length,
+      itemKey: item.key,
+      suggestion: `Check coordinate definition. Expected hierarchy depth of ${keyTypes.length}, got ${keyTypeArray.length}`
+    });
+    throw new Error(
+      `Item has incorrect key hierarchy depth. Expected ${keyTypes.length} levels [${keyTypes.join(" > ")}], but got ${keyTypeArray.length} levels [${keyTypeArray.join(" > ")}]. Key: ${JSON.stringify(item.key)}. This indicates a coordinate/hierarchy mismatch.`
+    );
   }
   const match = JSON.stringify(keyTypeArray) === JSON.stringify(keyTypes);
   if (!match) {
-    logger4.error("Key Type Array Mismatch", { keyTypeArray, thisKeyTypes: keyTypes });
-    throw new Error(`Item does not have the correct key types. Expected [${keyTypes.join(", ")}], but got [${keyTypeArray.join(", ")}]`);
+    logger4.error("Key Type Array Mismatch", {
+      component: "core",
+      operation: "validateKeys",
+      expectedKeyTypes: keyTypes,
+      actualKeyTypes: keyTypeArray,
+      itemKey: item.key,
+      suggestion: `Ensure item key matches expected hierarchy: [${keyTypes.join(" > ")}]`
+    });
+    throw new Error(
+      `Item has incorrect key types. Expected [${keyTypes.join(" > ")}], but got [${keyTypeArray.join(" > ")}]. Key: ${JSON.stringify(item.key)}. This indicates a data model mismatch.`
+    );
   }
   return item;
 };
@@ -518,7 +582,7 @@ var ValidationError = class extends ActionError {
       // Will be filled by wrapper
       details: {
         validOptions,
-        suggestedAction,
+        suggestedAction: suggestedAction || (validOptions && validOptions.length > 0 ? `Valid options are: ${validOptions.join(", ")}. Please use one of these values.` : "Check the validation requirements and ensure all fields meet the required format, type, and constraints."),
         retryable: true,
         conflictingValue,
         fieldErrors

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fjell/core",
   "description": "Core Item and Key Framework for Fjell",
-  "version": "4.4.70",
+  "version": "4.4.73",
   "keywords": [
     "core",
     "fjell"
@@ -41,14 +41,14 @@
     "docs:test": "cd docs && npm run test"
   },
   "dependencies": {
-    "@fjell/logging": "^4.4.60",
+    "@fjell/logging": "^4.4.65",
     "deepmerge": "^4.3.1",
     "luxon": "^3.7.2"
   },
   "devDependencies": {
     "@eslint/eslintrc": "^3.3.1",
     "@eslint/js": "^9.39.1",
-    "@fjell/common-config": "^1.1.31",
+    "@fjell/common-config": "^1.1.36",
     "@swc/core": "^1.15.2",
     "@tsconfig/recommended": "^1.0.13",
     "@types/luxon": "^3.7.1",