@fjell/core 4.4.50 → 4.4.51

package/src/operations/wrappers/types.ts

@@ -1,63 +0,0 @@
-/**
- * Types for operation wrappers
- *
- * These wrappers provide automatic parameter validation for all Operations methods.
- */
-
-import type { Coordinate } from "../../Coordinate";
-
-/**
- * Options for configuring wrapper behavior
- */
-export interface WrapperOptions {
-  /**
-   * Skip automatic parameter validation.
-   * Use this if you're handling validation elsewhere.
-   * @default false
-   */
-  skipValidation?: boolean;
-  
-  /**
-   * Custom operation name for error messages.
-   * If not provided, uses the wrapper's default name.
-   */
-  operationName?: string;
-  
-  /**
-   * Enable debug logging for wrapper calls.
-   * @default false
-   */
-  debug?: boolean;
-  
-  /**
-   * Custom error handler.
-   * If provided, catches and transforms errors from the implementation.
-   */
-  onError?: (error: Error, context: ErrorContext) => Error | never;
-}
-
-/**
- * Context provided to error handlers
- */
-export interface ErrorContext {
-  operationName: string;
-  params: any[];
-  coordinate: Coordinate<any, any, any, any, any, any>;
-}
-
-/**
- * Internal context passed through wrapper execution
- */
-export interface WrapperContext<
-  S extends string,
-  L1 extends string = never,
-  L2 extends string = never,
-  L3 extends string = never,
-  L4 extends string = never,
-  L5 extends string = never
-> {
-  coordinate: Coordinate<S, L1, L2, L3, L4, L5>;
-  operationName: string;
-  options: WrapperOptions;
-}
-

package/src/validation/ItemValidator.ts

@@ -1,131 +0,0 @@
-/**
- * Item validation
- *
- * Validates that Item objects have correct key types and structures.
- */
-
-import type { Item } from "../items";
-import { toKeyTypeArray } from "../key/KUtils";
-import type { AllItemTypeArrays, ComKey, PriKey } from "../keys";
-import LibLogger from '../logger';
-
-const logger = LibLogger.get('validation', 'ItemValidator');
-
-/**
- * Validates that a single item has the correct primary key type
- *
- * @param item - The item to validate
- * @param pkType - The expected primary key type
- * @returns The validated item
- * @throws Error if item is invalid or has wrong key type
- */
-const validatePKForItem = <
-  S extends string,
-  L1 extends string = never,
-  L2 extends string = never,
-  L3 extends string = never,
-  L4 extends string = never,
-  L5 extends string = never,
->(item: Item<S, L1, L2, L3, L4, L5>, pkType: S): Item<S, L1, L2, L3, L4, L5> => {
-  if (!item) {
-    logger.error('Validating PK, Item is undefined', { item });
-    throw new Error('Validating PK, Item is undefined');
-  }
-  if (!item.key) {
-    logger.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 as ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>);
-  if (keyTypeArray[0] !== pkType) {
-    logger.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;
-};
-
-/**
- * Validates that an item or array of items have the correct primary key type
- *
- * @param input - The item or array of items to validate
- * @param pkType - The expected primary key type
- * @returns The validated item(s)
- * @throws Error if any item is invalid or has wrong key type
- *
- * @example
- * ```typescript
- * // Validate single item
- * const item = validatePK(fetchedItem, 'product');
- *
- * // Validate array of items
- * const items = validatePK(fetchedItems, 'product');
- * ```
- */
-export const validatePK = <
-  S extends string,
-  L1 extends string = never,
-  L2 extends string = never,
-  L3 extends string = never,
-  L4 extends string = never,
-  L5 extends string = never,
->(
-    input: Item<S, L1, L2, L3, L4, L5> | Item<S, L1, L2, L3, L4, L5>[],
-    pkType: S,
-  ): Item<S, L1, L2, L3, L4, L5> | Item<S, L1, L2, L3, L4, L5>[] => {
-  logger.trace('Checking Return Type', { input });
-
-  if (Array.isArray(input)) {
-    return input.map((item) => validatePKForItem(item, pkType));
-  }
-  return validatePKForItem(input, pkType);
-};
-
-/**
- * Validates that an item's key matches the expected key type array
- *
- * This is used to validate composite items where the key structure must match
- * the complete hierarchy (e.g., [product, store, region])
- *
- * @param item - The item to validate
- * @param keyTypes - The expected key type array
- * @returns The validated item
- * @throws Error if item is invalid or key types don't match
- *
- * @example
- * ```typescript
- * // Validate item has correct key structure
- * const item = validateKeys(fetchedItem, ['product', 'store']);
- * ```
- */
-export const validateKeys = <
-  S extends string,
-  L1 extends string = never,
-  L2 extends string = never,
-  L3 extends string = never,
-  L4 extends string = never,
-  L5 extends string = never,
->(
-    item: Item<S, L1, L2, L3, L4, L5>,
-    keyTypes: AllItemTypeArrays<S, L1, L2, L3, L4, L5>,
-  ): Item<S, L1, L2, L3, L4, L5> => {
-  logger.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 as ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>);
-  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: boolean = JSON.stringify(keyTypeArray) === JSON.stringify(keyTypes);
-  if (!match) {
-    logger.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;
-};
-

package/src/validation/KeyValidator.ts

@@ -1,365 +0,0 @@
-/**
- * Key validation (PriKey, ComKey)
- *
- * Validates key structures and ensures keys match the expected library type.
- */
-
-import type { ComKey, PriKey } from "../keys";
-import type { Coordinate } from "../Coordinate";
-import { isComKey, isPriKey } from "../key/KUtils";
-import LibLogger from "../logger";
-
-const logger = LibLogger.get('validation', 'KeyValidator');
-
-/**
- * Validates that the location key array in a ComKey matches the expected hierarchy
- * defined by the coordinate's key type array (kta).
- *
- * @param key - The composite key to validate
- * @param coordinate - The coordinate defining the library's key type hierarchy
- * @param operation - The operation name (for error messages)
- * @throws Error if location key array order is incorrect
- */
-const validateLocationKeyOrder = <
-  S extends string,
-  L1 extends string = never,
-  L2 extends string = never,
-  L3 extends string = never,
-  L4 extends string = never,
-  L5 extends string = never
->(
-    key: ComKey<S, L1, L2, L3, L4, L5>,
-    coordinate: Coordinate<S, L1, L2, L3, L4, L5>,
-    operation: string
-  ): void => {
-  const keyTypeArray = coordinate.kta;
-  const expectedLocationTypes = keyTypeArray.slice(1); // Remove primary key type
-  const actualLocationTypes = key.loc.map(loc => loc.kt);
-  
-  // Check if lengths match
-  if (expectedLocationTypes.length !== actualLocationTypes.length) {
-    logger.error('Location key array length mismatch', {
-      expected: expectedLocationTypes.length,
-      actual: actualLocationTypes.length,
-      key,
-      coordinate,
-      operation
-    });
-    
-    // Build detailed error message
-    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.\n` +
-      `\n` +
-      `Expected ${expectedLocationTypes.length} location keys but received ${actualLocationTypes.length}.\n` +
-      `\n` +
-      `Expected location key order for '${keyTypeArray[0]}':\n` +
-      `${expectedOrder}\n` +
-      `\n` +
-      `Received location key order:\n` +
-      `${actualOrder}`
-    );
-  }
-  
-  // Check if each position matches
-  for (let i = 0; i < expectedLocationTypes.length; i++) {
-    if (expectedLocationTypes[i] !== actualLocationTypes[i]) {
-      logger.error('Location key array order mismatch', {
-        position: i,
-        expected: expectedLocationTypes[i],
-        actual: actualLocationTypes[i],
-        key,
-        coordinate,
-        operation
-      });
-      
-      // Build detailed error message
-      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 order mismatch for ${operation} operation.\n` +
-        `\n` +
-        `At position ${i}, expected key type "${expectedLocationTypes[i]}" but received "${actualLocationTypes[i]}".\n` +
-        `\n` +
-        `Expected location key order for '${keyTypeArray[0]}':\n` +
-        `${expectedOrder}\n` +
-        `\n` +
-        `Received location key order:\n` +
-        `${actualOrder}\n` +
-        `\n` +
-        `Tip: Location keys must be ordered according to the hierarchy: [${expectedLocationTypes.join(', ')}]`
-      );
-    }
-  }
-};
-
-/**
- * Validates that a key is valid and matches the expected library type.
- *
- * This function performs comprehensive validation:
- * 1. Validates key type (PriKey vs ComKey) matches library type (primary vs composite)
- * 2. For composite keys, validates location key array order matches hierarchy
- * 3. Validates key structure is correct
- *
- * @param key - The key to validate
- * @param coordinate - The coordinate defining the library's key type hierarchy
- * @param operation - The operation name (for error messages)
- * @throws Error if key type doesn't match library type or location key array order is incorrect
- *
- * @example
- * ```typescript
- * // Validate a PriKey for a primary library
- * validateKey(
- *   { kt: 'product', pk: '123' },
- *   coordinate,
- *   'get'
- * );
- *
- * // Validate a ComKey for a composite library
- * validateKey(
- *   { kt: 'product', pk: '123', loc: [{ kt: 'store', lk: '456' }] },
- *   coordinate,
- *   'get'
- * );
- * ```
- */
-export const validateKey = <
-  S extends string,
-  L1 extends string = never,
-  L2 extends string = never,
-  L3 extends string = never,
-  L4 extends string = never,
-  L5 extends string = never
->(
-    key: PriKey<S> | ComKey<S, L1, L2, L3, L4, L5>,
-    coordinate: Coordinate<S, L1, L2, L3, L4, L5>,
-    operation: string
-  ): void => {
-  logger.debug(`Validating key for ${operation}`, { key, coordinate: coordinate.kta });
-  
-  // Check for null/undefined early
-  if (!key || key === null) {
-    throw new Error(
-      `Invalid key structure for ${operation} operation.\n` +
-      `\n` +
-      `The provided key is null or undefined.\n` +
-      `\n` +
-      `Valid key formats:\n` +
-      `  PriKey: { kt: string, pk: string|number }\n` +
-      `  ComKey: { kt: string, pk: string|number, loc: Array<{ kt: string, lk: string|number }> }`
-    );
-  }
-  
-  // Runtime validation: Check if the key type matches the library type
-  const isCompositeLibrary = coordinate.kta.length > 1;
-  const keyIsComposite = isComKey(key);
-  const keyIsPrimary = isPriKey(key);
-  
-  // Validate that the key type matches the library type
-  if (isCompositeLibrary && !keyIsComposite) {
-    // This is a composite library but received a primary key
-    logger.error(`Composite library received primary key in ${operation}`, { key, coordinate });
-    
-    const keyTypeArray = coordinate.kta;
-    
-    throw new Error(
-      `Invalid key type for ${operation} operation.\n` +
-      `\n` +
-      `This is a composite item library. You must provide a ComKey with location keys.\n` +
-      `\n` +
-      `Expected: ComKey with format:\n` +
-      `  {\n` +
-      `    kt: '${keyTypeArray[0]}',\n` +
-      `    pk: string|number,\n` +
-      `    loc: [\n` +
-      keyTypeArray.slice(1).map(kt => `      { kt: '${kt}', lk: string|number }`).join(',\n') + '\n' +
-      `    ]\n` +
-      `  }\n` +
-      `\n` +
-      `Received: PriKey with format:\n` +
-      `  ${JSON.stringify(key, null, 2)}\n` +
-      `\n` +
-      `Example correct usage:\n` +
-      `  library.operations.${operation}({\n` +
-      `    kt: '${keyTypeArray[0]}',\n` +
-      `    pk: 'item-id',\n` +
-      `    loc: [${keyTypeArray.slice(1).map(kt => `{ kt: '${kt}', lk: 'parent-id' }`).join(', ')}]\n` +
-      `  })`
-    );
-  }
-  
-  if (!isCompositeLibrary && keyIsComposite) {
-    // This is a primary library but received a composite key
-    logger.error(`Primary library received composite key in ${operation}`, { key, coordinate });
-    
-    const keyTypeArray = coordinate.kta;
-    
-    throw new Error(
-      `Invalid key type for ${operation} operation.\n` +
-      `\n` +
-      `This is a primary item library. You should provide a PriKey without location keys.\n` +
-      `\n` +
-      `Expected: PriKey with format:\n` +
-      `  { kt: '${keyTypeArray[0]}', pk: string|number }\n` +
-      `\n` +
-      `Received: ComKey with format:\n` +
-      `  ${JSON.stringify(key, null, 2)}\n` +
-      `\n` +
-      `Example correct usage:\n` +
-      `  library.operations.${operation}({ kt: '${keyTypeArray[0]}', pk: 'item-id' })`
-    );
-  }
-  
-  if (!keyIsPrimary && !keyIsComposite) {
-    // Invalid key structure
-    logger.error(`Invalid key structure in ${operation}`, { key, coordinate });
-    
-    throw new Error(
-      `Invalid key structure for ${operation} operation.\n` +
-      `\n` +
-      `The provided key does not match PriKey or ComKey format.\n` +
-      `\n` +
-      `Received:\n` +
-      `  ${JSON.stringify(key, null, 2)}\n` +
-      `\n` +
-      `Valid key formats:\n` +
-      `  PriKey: { kt: string, pk: string|number }\n` +
-      `  ComKey: { kt: string, pk: string|number, loc: Array<{ kt: string, lk: string|number }> }`
-    );
-  }
-  
-  // Validate that the key's kt field matches the expected primary key type
-  const expectedKeyType = coordinate.kta[0];
-  if ((key as any).kt !== expectedKeyType) {
-    logger.error(`Key type mismatch in ${operation}`, {
-      expected: expectedKeyType,
-      received: (key as any).kt,
-      key,
-      coordinate
-    });
-    
-    throw new Error(
-      `Invalid key type for ${operation} operation.\n` +
-      `\n` +
-      `Expected key type: '${expectedKeyType}'\n` +
-      `Received key type: '${(key as any).kt}'\n` +
-      `\n` +
-      `Example correct usage:\n` +
-      `  library.operations.${operation}({ kt: '${expectedKeyType}', pk: 'item-id', ... })`
-    );
-  }
-  
-  // For composite keys, validate the location key array order
-  if (keyIsComposite) {
-    const comKey = key as ComKey<S, L1, L2, L3, L4, L5>;
-    
-    // Empty loc array is a special case: it means "find by primary key across all locations"
-    // This is used for foreign key references to composite items where the location context is unknown
-    if (comKey.loc.length === 0) {
-      logger.debug(`Empty loc array detected in ${operation} - will search across all locations`, { key });
-    } else {
-      // For non-empty loc arrays, validate the order matches the expected hierarchy
-      validateLocationKeyOrder(comKey, coordinate, operation);
-    }
-  }
-  
-  logger.debug(`Key validation passed for ${operation}`, { key });
-};
-
-/**
- * Validates a PriKey structure
- *
- * @param key - The primary key to validate
- * @param expectedType - The expected key type
- * @param operation - The operation name (for error messages)
- * @throws Error if key is invalid
- */
-export const validatePriKey = <S extends string>(
-  key: PriKey<S>,
-  expectedType: S,
-  operation: string
-): void => {
-  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.\n` +
-      `Expected: '${expectedType}'\n` +
-      `Received: '${key.kt}'`
-    );
-  }
-  
-  if (typeof key.pk === 'undefined' || key.pk === null) {
-    throw new Error(`[${operation}] PriKey is missing 'pk' field`);
-  }
-};
-
-/**
- * Validates a ComKey structure
- *
- * @param key - The composite key to validate
- * @param coordinate - The coordinate defining the expected hierarchy
- * @param operation - The operation name (for error messages)
- * @throws Error if key is invalid
- */
-export const validateComKey = <
-  S extends string,
-  L1 extends string = never,
-  L2 extends string = never,
-  L3 extends string = never,
-  L4 extends string = never,
-  L5 extends string = never
->(
-    key: ComKey<S, L1, L2, L3, L4, L5>,
-    coordinate: Coordinate<S, L1, L2, L3, L4, L5>,
-    operation: string
-  ): void => {
-  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.\n` +
-      `Expected: '${coordinate.kta[0]}'\n` +
-      `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)`);
-  }
-  
-  // Validate location key order if loc is not empty
-  if (key.loc.length > 0) {
-    validateLocationKeyOrder(key, coordinate, operation);
-  }
-};
-

package/src/validation/LocationValidator.ts

@@ -1,136 +0,0 @@
-/**
- * Location array validation
- *
- * Validates that LocKeyArray parameters match the expected Coordinate hierarchy.
- */
-
-import type { LocKey, LocKeyArray } from "../keys";
-import type { Coordinate } from "../Coordinate";
-import LibLogger from "../logger";
-import type { ValidationResult } from "./types";
-
-const logger = LibLogger.get('validation', 'LocationValidator');
-
-/**
- * Validates that a standalone LocKeyArray parameter matches the expected hierarchy
- * defined by the coordinate's key type array (kta).
- *
- * This is used to validate the `locations` parameter passed to operations like
- * all(), find(), create(), etc.
- *
- * @param locations - The location key array to validate
- * @param coordinate - The coordinate defining the library's key type hierarchy
- * @param operation - The operation name (for error messages)
- * @throws Error if location key array order is incorrect
- *
- * @example
- * ```typescript
- * validateLocations(
- *   [{kt: 'store', lk: '123'}],
- *   coordinate,
- *   'find'
- * );
- * ```
- */
-export const validateLocations = <
-  S extends string,
-  L1 extends string = never,
-  L2 extends string = never,
-  L3 extends string = never,
-  L4 extends string = never,
-  L5 extends string = never
->(
-    locations: LocKeyArray<L1, L2, L3, L4, L5> | [] | undefined,
-    coordinate: Coordinate<S, L1, L2, L3, L4, L5>,
-    operation: string
-  ): void => {
-  // Skip validation if locations is empty or undefined
-  if (!locations || locations.length === 0) {
-    return;
-  }
-  
-  const keyTypeArray = coordinate.kta;
-  const expectedLocationTypes = keyTypeArray.slice(1); // Remove primary key type
-  const actualLocationTypes = (locations as Array<LocKey<L1 | L2 | L3 | L4 | L5>>).map(loc => loc.kt);
-  
-  logger.debug(`Validating locations for ${operation}`, {
-    expected: expectedLocationTypes,
-    actual: actualLocationTypes,
-    coordinate: keyTypeArray
-  });
-  
-  // Check if lengths match
-  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(', ')}])`
-    );
-  }
-  
-  // Check if each position matches the expected hierarchy
-  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 });
-};
-
-/**
- * Non-throwing version of validateLocations that returns a ValidationResult
- *
- * @param locations - The location key array to validate
- * @param coordinate - The coordinate defining the library's key type hierarchy
- * @param operation - The operation name (for error messages)
- * @returns ValidationResult with valid flag and optional error message
- */
-export const isValidLocations = <
-  S extends string,
-  L1 extends string = never,
-  L2 extends string = never,
-  L3 extends string = never,
-  L4 extends string = never,
-  L5 extends string = never
->(
-    locations: LocKeyArray<L1, L2, L3, L4, L5> | [] | undefined,
-    coordinate: Coordinate<S, L1, L2, L3, L4, L5>,
-    operation: string
-  ): ValidationResult => {
-  try {
-    validateLocations(locations, coordinate, operation);
-    return { valid: true };
-  } catch (error) {
-    return {
-      valid: false,
-      error: error instanceof Error ? error.message : String(error)
-    };
-  }
-};
-