@fjell/core 4.4.48 → 4.4.50

package/dist/validation/QueryValidator.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Query and parameter validation
+ *
+ * Validates ItemQuery and OperationParams structures.
+ */
+import type { ItemQuery } from "../item/ItemQuery";
+import type { OperationParams } from "../operations/Operations";
+/**
+ * Validates that a query parameter is a valid ItemQuery object.
+ *
+ * @param query - The query to validate
+ * @param operation - The operation name (for error messages)
+ * @throws Error if query is invalid
+ *
+ * @example
+ * ```typescript
+ * validateQuery({ filter: { status: 'active' } }, 'one');
+ * ```
+ */
+export declare const validateQuery: (query: ItemQuery | undefined, operation: string) => void;
+/**
+ * Validates that operation parameters are valid.
+ *
+ * @param params - The parameters to validate
+ * @param operation - The operation name (for error messages)
+ * @throws Error if parameters are invalid
+ *
+ * @example
+ * ```typescript
+ * validateOperationParams({ email: 'test@example.com' }, 'find');
+ * ```
+ */
+export declare const validateOperationParams: (params: OperationParams | undefined, operation: string) => void;
+/**
+ * Validates that a finder name is valid.
+ *
+ * @param finder - The finder name to validate
+ * @param operation - The operation name (for error messages)
+ * @throws Error if finder name is invalid
+ */
+export declare const validateFinderName: (finder: string | undefined, operation: string) => void;
+/**
+ * Validates that an action name is valid.
+ *
+ * @param action - The action name to validate
+ * @param operation - The operation name (for error messages)
+ * @throws Error if action name is invalid
+ */
+export declare const validateActionName: (action: string | undefined, operation: string) => void;
+/**
+ * Validates that a facet name is valid.
+ *
+ * @param facet - The facet name to validate
+ * @param operation - The operation name (for error messages)
+ * @throws Error if facet name is invalid
+ */
+export declare const validateFacetName: (facet: string | undefined, operation: string) => void;

package/dist/validation/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Validation module
+ *
+ * Provides centralized validation functions for:
+ * - Location arrays (LocKeyArray validation against Coordinate hierarchy)
+ * - Keys (PriKey, ComKey validation)
+ * - Items (Item key type validation)
+ * - Queries (ItemQuery validation)
+ * - Operation parameters (OperationParams validation)
+ */
+export type { ValidationOptions, ValidationResult } from './types';
+export { validateLocations, isValidLocations } from './LocationValidator';
+export { validateKey, validatePriKey, validateComKey } from './KeyValidator';
+export { validatePK, validateKeys } from './ItemValidator';
+export { validateQuery, validateOperationParams, validateFinderName, validateActionName, validateFacetName } from './QueryValidator';

package/dist/validation/index.js

@@ -0,0 +1,501 @@
+// src/logger.ts
+import Logging from "@fjell/logging";
+var LibLogger = Logging.getLogger("@fjell/core");
+var logger_default = LibLogger;
+
+// src/validation/LocationValidator.ts
+var logger = logger_default.get("validation", "LocationValidator");
+var validateLocations = (locations, coordinate, operation) => {
+  if (!locations || locations.length === 0) {
+    return;
+  }
+  const keyTypeArray = coordinate.kta;
+  const expectedLocationTypes = keyTypeArray.slice(1);
+  const actualLocationTypes = locations.map((loc) => loc.kt);
+  logger.debug(`Validating locations for ${operation}`, {
+    expected: expectedLocationTypes,
+    actual: actualLocationTypes,
+    coordinate: keyTypeArray
+  });
+  if (actualLocationTypes.length > expectedLocationTypes.length) {
+    logger.error("Location key array has too many elements", {
+      expected: expectedLocationTypes.length,
+      actual: actualLocationTypes.length,
+      expectedTypes: expectedLocationTypes,
+      actualTypes: actualLocationTypes,
+      coordinate,
+      operation
+    });
+    throw new Error(
+      `Invalid location key array for ${operation}: Expected at most ${expectedLocationTypes.length} location keys (hierarchy: [${expectedLocationTypes.join(", ")}]), but received ${actualLocationTypes.length} (types: [${actualLocationTypes.join(", ")}])`
+    );
+  }
+  for (let i = 0; i < actualLocationTypes.length; i++) {
+    if (expectedLocationTypes[i] !== actualLocationTypes[i]) {
+      logger.error("Location key array order mismatch", {
+        position: i,
+        expected: expectedLocationTypes[i],
+        actual: actualLocationTypes[i],
+        expectedHierarchy: expectedLocationTypes,
+        actualOrder: actualLocationTypes,
+        coordinate,
+        operation
+      });
+      throw new Error(
+        `Invalid location key array order for ${operation}: At position ${i}, expected key type "${expectedLocationTypes[i]}" but received "${actualLocationTypes[i]}". Location keys must be ordered according to the hierarchy: [${expectedLocationTypes.join(", ")}]. Received order: [${actualLocationTypes.join(", ")}]`
+      );
+    }
+  }
+  logger.debug(`Location key array validation passed for ${operation}`, { locations });
+};
+var isValidLocations = (locations, coordinate, operation) => {
+  try {
+    validateLocations(locations, coordinate, operation);
+    return { valid: true };
+  } catch (error) {
+    return {
+      valid: false,
+      error: error instanceof Error ? error.message : String(error)
+    };
+  }
+};
+
+// src/key/KUtils.ts
+var logger2 = logger_default.get("KUtils");
+var isComKey = (key) => {
+  logger2.trace("isComKey", { key });
+  return key !== void 0 && (key.pk !== void 0 && key.kt !== void 0) && (key.loc !== void 0 && Array.isArray(key.loc));
+};
+var isPriKey = (key) => {
+  logger2.trace("isPriKey", { key });
+  return key !== void 0 && (key.pk !== void 0 && key.kt !== void 0) && key.loc === void 0;
+};
+var toKeyTypeArray = (ik) => {
+  logger2.trace("toKeyTypeArray", { ik });
+  if (isComKey(ik)) {
+    const ck = ik;
+    return [ck.kt, ...ck.loc.map((l) => l.kt)];
+  } else {
+    return [ik.kt];
+  }
+};
+
+// src/validation/KeyValidator.ts
+var logger3 = logger_default.get("validation", "KeyValidator");
+var validateLocationKeyOrder = (key, coordinate, operation) => {
+  const keyTypeArray = coordinate.kta;
+  const expectedLocationTypes = keyTypeArray.slice(1);
+  const actualLocationTypes = key.loc.map((loc) => loc.kt);
+  if (expectedLocationTypes.length !== actualLocationTypes.length) {
+    logger3.error("Location key array length mismatch", {
+      expected: expectedLocationTypes.length,
+      actual: actualLocationTypes.length,
+      key,
+      coordinate,
+      operation
+    });
+    const expectedOrder = expectedLocationTypes.map(
+      (kt, i) => `  [${i}] { kt: '${kt}', lk: <value> }`
+    ).join("\n");
+    const actualOrder = key.loc.map(
+      (loc, i) => `  [${i}] { kt: '${loc.kt}', lk: ${JSON.stringify(loc.lk)} }`
+    ).join("\n");
+    throw new Error(
+      `Location key array length mismatch for ${operation} operation.
+
+Expected ${expectedLocationTypes.length} location keys but received ${actualLocationTypes.length}.
+
+Expected location key order for '${keyTypeArray[0]}':
+${expectedOrder}
+
+Received location key order:
+${actualOrder}`
+    );
+  }
+  for (let i = 0; i < expectedLocationTypes.length; i++) {
+    if (expectedLocationTypes[i] !== actualLocationTypes[i]) {
+      logger3.error("Location key array order mismatch", {
+        position: i,
+        expected: expectedLocationTypes[i],
+        actual: actualLocationTypes[i],
+        key,
+        coordinate,
+        operation
+      });
+      const expectedOrder = expectedLocationTypes.map(
+        (kt, i2) => `  [${i2}] { kt: '${kt}', lk: <value> }`
+      ).join("\n");
+      const actualOrder = key.loc.map(
+        (loc, i2) => `  [${i2}] { kt: '${loc.kt}', lk: ${JSON.stringify(loc.lk)} }`
+      ).join("\n");
+      throw new Error(
+        `Location key array order mismatch for ${operation} operation.
+
+At position ${i}, expected key type "${expectedLocationTypes[i]}" but received "${actualLocationTypes[i]}".
+
+Expected location key order for '${keyTypeArray[0]}':
+${expectedOrder}
+
+Received location key order:
+${actualOrder}
+
+Tip: Location keys must be ordered according to the hierarchy: [${expectedLocationTypes.join(", ")}]`
+      );
+    }
+  }
+};
+var validateKey = (key, coordinate, operation) => {
+  logger3.debug(`Validating key for ${operation}`, { key, coordinate: coordinate.kta });
+  if (!key || key === null) {
+    throw new Error(
+      `Invalid key structure for ${operation} operation.
+
+The provided key is null or undefined.
+
+Valid key formats:
+  PriKey: { kt: string, pk: string|number }
+  ComKey: { kt: string, pk: string|number, loc: Array<{ kt: string, lk: string|number }> }`
+    );
+  }
+  const isCompositeLibrary = coordinate.kta.length > 1;
+  const keyIsComposite = isComKey(key);
+  const keyIsPrimary = isPriKey(key);
+  if (isCompositeLibrary && !keyIsComposite) {
+    logger3.error(`Composite library received primary key in ${operation}`, { key, coordinate });
+    const keyTypeArray = coordinate.kta;
+    throw new Error(
+      `Invalid key type for ${operation} operation.
+
+This is a composite item library. You must provide a ComKey with location keys.
+
+Expected: ComKey with format:
+  {
+    kt: '${keyTypeArray[0]}',
+    pk: string|number,
+    loc: [
+` + keyTypeArray.slice(1).map((kt) => `      { kt: '${kt}', lk: string|number }`).join(",\n") + `
+    ]
+  }
+
+Received: PriKey with format:
+  ${JSON.stringify(key, null, 2)}
+
+Example correct usage:
+  library.operations.${operation}({
+    kt: '${keyTypeArray[0]}',
+    pk: 'item-id',
+    loc: [${keyTypeArray.slice(1).map((kt) => `{ kt: '${kt}', lk: 'parent-id' }`).join(", ")}]
+  })`
+    );
+  }
+  if (!isCompositeLibrary && keyIsComposite) {
+    logger3.error(`Primary library received composite key in ${operation}`, { key, coordinate });
+    const keyTypeArray = coordinate.kta;
+    throw new Error(
+      `Invalid key type for ${operation} operation.
+
+This is a primary item library. You should provide a PriKey without location keys.
+
+Expected: PriKey with format:
+  { kt: '${keyTypeArray[0]}', pk: string|number }
+
+Received: ComKey with format:
+  ${JSON.stringify(key, null, 2)}
+
+Example correct usage:
+  library.operations.${operation}({ kt: '${keyTypeArray[0]}', pk: 'item-id' })`
+    );
+  }
+  if (!keyIsPrimary && !keyIsComposite) {
+    logger3.error(`Invalid key structure in ${operation}`, { key, coordinate });
+    throw new Error(
+      `Invalid key structure for ${operation} operation.
+
+The provided key does not match PriKey or ComKey format.
+
+Received:
+  ${JSON.stringify(key, null, 2)}
+
+Valid key formats:
+  PriKey: { kt: string, pk: string|number }
+  ComKey: { kt: string, pk: string|number, loc: Array<{ kt: string, lk: string|number }> }`
+    );
+  }
+  const expectedKeyType = coordinate.kta[0];
+  if (key.kt !== expectedKeyType) {
+    logger3.error(`Key type mismatch in ${operation}`, {
+      expected: expectedKeyType,
+      received: key.kt,
+      key,
+      coordinate
+    });
+    throw new Error(
+      `Invalid key type for ${operation} operation.
+
+Expected key type: '${expectedKeyType}'
+Received key type: '${key.kt}'
+
+Example correct usage:
+  library.operations.${operation}({ kt: '${expectedKeyType}', pk: 'item-id', ... })`
+    );
+  }
+  if (keyIsComposite) {
+    const comKey = key;
+    if (comKey.loc.length === 0) {
+      logger3.debug(`Empty loc array detected in ${operation} - will search across all locations`, { key });
+    } else {
+      validateLocationKeyOrder(comKey, coordinate, operation);
+    }
+  }
+  logger3.debug(`Key validation passed for ${operation}`, { key });
+};
+var validatePriKey = (key, expectedType, operation) => {
+  if (!key || key === null) {
+    throw new Error(`[${operation}] PriKey is undefined or null`);
+  }
+  if (!key.kt) {
+    throw new Error(`[${operation}] PriKey is missing 'kt' field`);
+  }
+  if (key.kt !== expectedType) {
+    throw new Error(
+      `[${operation}] PriKey has incorrect type.
+Expected: '${expectedType}'
+Received: '${key.kt}'`
+    );
+  }
+  if (typeof key.pk === "undefined" || key.pk === null) {
+    throw new Error(`[${operation}] PriKey is missing 'pk' field`);
+  }
+};
+var validateComKey = (key, coordinate, operation) => {
+  if (!key || key === null) {
+    throw new Error(`[${operation}] ComKey is undefined or null`);
+  }
+  if (!key.kt) {
+    throw new Error(`[${operation}] ComKey is missing 'kt' field`);
+  }
+  if (key.kt !== coordinate.kta[0]) {
+    throw new Error(
+      `[${operation}] ComKey has incorrect type.
+Expected: '${coordinate.kta[0]}'
+Received: '${key.kt}'`
+    );
+  }
+  if (typeof key.pk === "undefined" || key.pk === null) {
+    throw new Error(`[${operation}] ComKey is missing 'pk' field`);
+  }
+  if (!Array.isArray(key.loc)) {
+    throw new Error(`[${operation}] ComKey is missing or invalid 'loc' field (must be an array)`);
+  }
+  if (key.loc.length > 0) {
+    validateLocationKeyOrder(key, coordinate, operation);
+  }
+};
+
+// src/validation/ItemValidator.ts
+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");
+  }
+  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");
+  }
+  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]}`);
+  }
+  return item;
+};
+var validatePK = (input, pkType) => {
+  logger4.trace("Checking Return Type", { input });
+  if (Array.isArray(input)) {
+    return input.map((item) => validatePKForItem(item, pkType));
+  }
+  return validatePKForItem(input, pkType);
+};
+var validateKeys = (item, keyTypes) => {
+  logger4.trace("Checking Return Type", { item });
+  if (!item) {
+    throw new Error("validating keys, item is undefined");
+  }
+  if (!item.key) {
+    throw new Error("validating keys, item does not have a key: " + JSON.stringify(item));
+  }
+  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}`);
+  }
+  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(", ")}]`);
+  }
+  return item;
+};
+
+// src/validation/QueryValidator.ts
+var logger5 = logger_default.get("validation", "QueryValidator");
+var validateQuery = (query, operation) => {
+  if (typeof query === "undefined" || query === null) {
+    return;
+  }
+  if (typeof query !== "object") {
+    logger5.error(`Invalid query type for ${operation}`, { query, type: typeof query });
+    throw new Error(
+      `[${operation}] Invalid query parameter.
+
+Expected: object or undefined
+Received: ${typeof query}
+
+Example valid queries:
+  {}
+  { filter: { status: 'active' } }
+  { limit: 10, sort: { field: 'name', order: 'asc' } }`
+    );
+  }
+  if (Array.isArray(query)) {
+    logger5.error(`Query cannot be an array for ${operation}`, { query });
+    throw new Error(
+      `[${operation}] Invalid query parameter.
+
+Query cannot be an array.
+Received: ${JSON.stringify(query)}`
+    );
+  }
+  logger5.debug(`Query validation passed for ${operation}`, { query });
+};
+var validateOperationParams = (params, operation) => {
+  if (typeof params === "undefined") {
+    return;
+  }
+  if (params === null) {
+    logger5.error(`Params cannot be null for ${operation}`, { params });
+    throw new Error(
+      `[${operation}] Invalid operation parameters.
+
+Parameters cannot be null.
+Expected: object or undefined
+Received: null
+
+Example valid parameters:
+  {}
+  { email: 'user@example.com' }
+  { status: 'active', limit: 10 }`
+    );
+  }
+  if (typeof params !== "object") {
+    logger5.error(`Invalid params type for ${operation}`, { params, type: typeof params });
+    throw new Error(
+      `[${operation}] Invalid operation parameters.
+
+Expected: object or undefined
+Received: ${typeof params}
+
+Example valid parameters:
+  {}
+  { email: 'user@example.com' }
+  { status: 'active', limit: 10 }`
+    );
+  }
+  if (Array.isArray(params)) {
+    logger5.error(`Params cannot be an array for ${operation}`, { params });
+    throw new Error(
+      `[${operation}] Invalid operation parameters.
+
+Parameters cannot be an array.
+Received: ${JSON.stringify(params)}`
+    );
+  }
+  for (const [key, value] of Object.entries(params)) {
+    const valueType = typeof value;
+    const isValidType = valueType === "string" || valueType === "number" || valueType === "boolean" || value instanceof Date || Array.isArray(value) && value.every(
+      (v) => typeof v === "string" || typeof v === "number" || typeof v === "boolean" || v instanceof Date
+    );
+    if (!isValidType) {
+      logger5.error(`Invalid param value type for ${operation}`, { key, value, valueType });
+      throw new Error(
+        `[${operation}] Invalid value type for parameter "${key}".
+
+Allowed types: string, number, boolean, Date, or arrays of these types
+Received: ${valueType}
+Value: ${JSON.stringify(value)}`
+      );
+    }
+  }
+  logger5.debug(`Operation params validation passed for ${operation}`, { params });
+};
+var validateFinderName = (finder, operation) => {
+  if (!finder || typeof finder !== "string") {
+    logger5.error(`Invalid finder name for ${operation}`, { finder, type: typeof finder });
+    throw new Error(
+      `[${operation}] Finder name must be a non-empty string.
+
+Received: ${JSON.stringify(finder)}`
+    );
+  }
+  if (finder.trim().length === 0) {
+    logger5.error(`Empty finder name for ${operation}`, { finder });
+    throw new Error(
+      `[${operation}] Finder name cannot be empty or whitespace only.
+
+Received: "${finder}"`
+    );
+  }
+  logger5.debug(`Finder name validation passed for ${operation}`, { finder });
+};
+var validateActionName = (action, operation) => {
+  if (!action || typeof action !== "string") {
+    logger5.error(`Invalid action name for ${operation}`, { action, type: typeof action });
+    throw new Error(
+      `[${operation}] Action name must be a non-empty string.
+
+Received: ${JSON.stringify(action)}`
+    );
+  }
+  if (action.trim().length === 0) {
+    logger5.error(`Empty action name for ${operation}`, { action });
+    throw new Error(
+      `[${operation}] Action name cannot be empty or whitespace only.
+
+Received: "${action}"`
+    );
+  }
+  logger5.debug(`Action name validation passed for ${operation}`, { action });
+};
+var validateFacetName = (facet, operation) => {
+  if (!facet || typeof facet !== "string") {
+    logger5.error(`Invalid facet name for ${operation}`, { facet, type: typeof facet });
+    throw new Error(
+      `[${operation}] Facet name must be a non-empty string.
+
+Received: ${JSON.stringify(facet)}`
+    );
+  }
+  if (facet.trim().length === 0) {
+    logger5.error(`Empty facet name for ${operation}`, { facet });
+    throw new Error(
+      `[${operation}] Facet name cannot be empty or whitespace only.
+
+Received: "${facet}"`
+    );
+  }
+  logger5.debug(`Facet name validation passed for ${operation}`, { facet });
+};
+export {
+  isValidLocations,
+  validateActionName,
+  validateComKey,
+  validateFacetName,
+  validateFinderName,
+  validateKey,
+  validateKeys,
+  validateLocations,
+  validateOperationParams,
+  validatePK,
+  validatePriKey,
+  validateQuery
+};

package/dist/validation/types.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Shared validation types and options
+ */
+/**
+ * Options for validation functions
+ */
+export interface ValidationOptions {
+    /**
+     * Custom error message prefix
+     */
+    errorPrefix?: string;
+    /**
+     * Whether to allow undefined (treated as empty array for location validation)
+     */
+    allowUndefined?: boolean;
+    /**
+     * Whether to throw errors or return validation results
+     * @default true
+     */
+    throwOnError?: boolean;
+}
+/**
+ * Result of a validation operation (for non-throwing mode)
+ */
+export interface ValidationResult {
+    /**
+     * Whether validation passed
+     */
+    valid: boolean;
+    /**
+     * Error message if validation failed
+     */
+    error?: string;
+    /**
+     * Detailed validation context
+     */
+    context?: Record<string, unknown>;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fjell/core",
   "description": "Core Item and Key Framework for Fjell",
-  "version": "4.4.48",
+  "version": "4.4.50",
   "keywords": [
     "core",
     "fjell"
@@ -15,6 +15,11 @@
       "import": "./dist/index.js",
       "default": "./dist/index.js"
     },
+    "./validation": {
+      "types": "./dist/validation/index.d.ts",
+      "import": "./dist/validation/index.js",
+      "default": "./dist/validation/index.js"
+    },
     "./browser": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
@@ -36,7 +41,7 @@
     "docs:test": "cd docs && npm run test"
   },
   "dependencies": {
-    "@fjell/logging": "^4.4.47",
+    "@fjell/logging": "^4.4.49",
     "deepmerge": "^4.3.1",
     "luxon": "^3.7.1"
   },

package/src/Coordinate.ts

@@ -0,0 +1,35 @@
+import type { ItemTypeArray } from "./keys";
+import LibLogger from "./logger";
+
+const logger = LibLogger.get("Coordinate");
+
+export interface Coordinate<
+  S extends string,
+  L1 extends string = never,
+  L2 extends string = never,
+  L3 extends string = never,
+  L4 extends string = never,
+  L5 extends string = never,
+> {
+  kta: ItemTypeArray<S, L1, L2, L3, L4, L5>;
+  scopes: string[];
+  toString: () => string;
+}
+
+export const createCoordinate = <
+  S extends string,
+  L1 extends string = never,
+  L2 extends string = never,
+  L3 extends string = never,
+  L4 extends string = never,
+  L5 extends string = never,
+>(kta: ItemTypeArray<S, L1, L2, L3, L4, L5> | S, scopes: string[] = []): Coordinate<S, L1, L2, L3, L4, L5> => {
+  const ktArray = Array.isArray(kta) ? kta : [kta];
+  const toString = () => {
+    logger.debug("toString", { kta, scopes });
+    return `${ktArray.join(', ')} - ${scopes.join(', ')}`;
+  }
+  logger.debug("createCoordinate", { kta: ktArray, scopes, toString });
+  return { kta: ktArray as ItemTypeArray<S, L1, L2, L3, L4, L5>, scopes, toString };
+}
+