@fjell/core 4.4.47 → 4.4.49

package/src/errors/ActionError.ts

@@ -0,0 +1,69 @@
+export interface ErrorInfo {
+  code: string;
+  message: string;
+  operation: {
+    type: 'get' | 'create' | 'update' | 'remove' | 'upsert' |
+          'all' | 'one' | 'find' | 'findOne' |
+          'action' | 'allAction' | 'facet' | 'allFacet';
+    name: string;
+    params: Record<string, any>;
+  };
+  context: {
+    itemType: string;
+    key?: {
+      primary?: string | number;
+      composite?: {
+        sk: string | number;
+        kta: string[];
+        locations?: Array<{ lk: string | number; kt: string }>;
+      };
+    };
+    affectedItems?: Array<{
+      id: string | number;
+      type: string;
+      displayName?: string;
+    }>;
+    parentLocation?: {
+      id: string | number;
+      type: string;
+    };
+    requiredPermission?: string;
+  };
+  details?: {
+    validOptions?: string[];
+    suggestedAction?: string;
+    retryable?: boolean;
+    conflictingValue?: any;
+    expectedValue?: any;
+  };
+  technical?: {
+    timestamp: string;
+    requestId?: string;
+    stackTrace?: string;
+    cause?: any;
+  };
+}
+
+export class ActionError extends Error {
+  constructor(
+    public readonly errorInfo: ErrorInfo,
+    cause?: Error
+  ) {
+    super(errorInfo.message);
+    this.name = 'ActionError';
+    this.cause = cause;
+    
+    // Ensure timestamp is always set
+    if (!this.errorInfo.technical) {
+      this.errorInfo.technical = { timestamp: new Date().toISOString() };
+    }
+    if (!this.errorInfo.technical.timestamp) {
+      this.errorInfo.technical.timestamp = new Date().toISOString();
+    }
+  }
+
+  toJSON(): ErrorInfo {
+    return this.errorInfo;
+  }
+}
+

package/src/errors/BusinessLogicError.ts

@@ -0,0 +1,24 @@
+import { ActionError } from './ActionError';
+
+export class BusinessLogicError extends ActionError {
+  constructor(
+    message: string,
+    suggestedAction?: string,
+    retryable: boolean = false
+  ) {
+    super({
+      code: 'BUSINESS_LOGIC_ERROR',
+      message,
+      operation: { type: 'action', name: '', params: {} },
+      context: { itemType: '' },
+      details: {
+        suggestedAction,
+        retryable
+      },
+      technical: {
+        timestamp: new Date().toISOString()
+      }
+    });
+  }
+}
+

package/src/errors/DuplicateError.ts

@@ -0,0 +1,57 @@
+import { ActionError } from './ActionError';
+
+export class DuplicateError extends ActionError {
+  constructor(
+    message: string,
+    existingItemIdOrKey?: string | number | any,
+    duplicateField?: string
+  ) {
+    // Extract ID and build key info
+    let existingItemId: string | number | null = null;
+    let keyInfo: any = null;
+    
+    if (typeof existingItemIdOrKey === 'object' && existingItemIdOrKey !== null) {
+      // It's a key object - extract the primary key value and build proper key structure
+      existingItemId = existingItemIdOrKey.pk || existingItemIdOrKey.id || existingItemIdOrKey.primary || null;
+      
+      // Build key info with primary field set
+      if (existingItemId !== null) {
+        keyInfo = {
+          primary: existingItemId,
+          ...existingItemIdOrKey
+        };
+      } else {
+        keyInfo = existingItemIdOrKey;
+      }
+    } else if (typeof existingItemIdOrKey !== 'undefined') {
+      // It's a simple ID
+      existingItemId = existingItemIdOrKey;
+      keyInfo = { primary: existingItemId };
+    }
+    
+    super({
+      code: 'DUPLICATE_ERROR',
+      message,
+      operation: { type: 'create', name: '', params: {} },
+      context: {
+        itemType: '',
+        ...(keyInfo && { key: keyInfo }),
+        ...(existingItemId && {
+          affectedItems: [{
+            id: existingItemId,
+            type: '',
+            displayName: `Existing item with ${duplicateField || 'key'}`
+          }]
+        })
+      },
+      details: {
+        retryable: false,
+        conflictingValue: duplicateField
+      },
+      technical: {
+        timestamp: new Date().toISOString()
+      }
+    });
+  }
+}
+

package/src/errors/NotFoundError.ts

@@ -0,0 +1,24 @@
+import { ActionError } from './ActionError';
+
+export class NotFoundError extends ActionError {
+  constructor(
+    message: string,
+    itemType: string,
+    key?: any
+  ) {
+    super({
+      code: 'NOT_FOUND',
+      message,
+      operation: { type: 'get', name: '', params: {} },
+      context: {
+        itemType,
+        key: typeof key === 'object' ? key : { primary: key }
+      },
+      details: { retryable: false },
+      technical: {
+        timestamp: new Date().toISOString()
+      }
+    });
+  }
+}
+

package/src/errors/PermissionError.ts

@@ -0,0 +1,31 @@
+import { ActionError } from './ActionError';
+
+export class PermissionError extends ActionError {
+  constructor(
+    message: string,
+    requiredPermission?: string,
+    currentPermissions?: string[]
+  ) {
+    super({
+      code: 'PERMISSION_DENIED',
+      message,
+      operation: { type: 'action', name: '', params: {} },
+      context: {
+        itemType: '',
+        ...(requiredPermission && { requiredPermission })
+      },
+      details: {
+        ...(requiredPermission && {
+          suggestedAction: `Required permission: ${requiredPermission}`,
+          expectedValue: requiredPermission
+        }),
+        ...(currentPermissions && { conflictingValue: currentPermissions }),
+        retryable: false
+      },
+      technical: {
+        timestamp: new Date().toISOString()
+      }
+    });
+  }
+}
+

package/src/errors/ValidationError.ts

@@ -0,0 +1,27 @@
+import { ActionError } from './ActionError';
+
+export class ValidationError extends ActionError {
+  constructor(
+    message: string,
+    validOptions?: string[],
+    suggestedAction?: string,
+    conflictingValue?: any
+  ) {
+    super({
+      code: 'VALIDATION_ERROR',
+      message,
+      operation: { type: 'create', name: '', params: {} }, // Will be filled by wrapper
+      context: { itemType: '' }, // Will be filled by wrapper
+      details: {
+        validOptions,
+        suggestedAction,
+        retryable: true,
+        conflictingValue
+      },
+      technical: {
+        timestamp: new Date().toISOString()
+      }
+    });
+  }
+}
+

package/src/errors/index.ts

@@ -0,0 +1,7 @@
+export * from './ActionError';
+export * from './ValidationError';
+export * from './NotFoundError';
+export * from './BusinessLogicError';
+export * from './PermissionError';
+export * from './DuplicateError';
+

package/src/index.ts

@@ -1,6 +1,7 @@
 export * from "./dictionary";
 export * from "./keys";
 export * from "./items";
+export * from "./Coordinate";
 export { IFactory } from "./item/IFactory";
 export { AItemService } from "./AItemService";
 
@@ -11,3 +12,55 @@ export * from './item/IQFactory';
 export * from './item/IQUtils';
 export * from './item/IUtils';
 export * from './item/ItemQuery';
+
+// Validation module
+export * from './validation';
+
+// Error types and handling
+export * from './errors';
+export * from './operations';
+
+// Operations interfaces
+export type {
+  Operations,
+  OperationParams,
+  AffectedKeys,
+  CreateOptions
+} from './operations/Operations';
+export {
+  isPriKey as isOperationPriKey,
+  isComKey as isOperationComKey
+} from './operations/Operations';
+export type {
+  GetMethod,
+  CreateMethod,
+  UpdateMethod,
+  RemoveMethod,
+  UpsertMethod,
+  AllMethod,
+  OneMethod,
+  FindMethod,
+  FindOneMethod,
+  FinderMethod,
+  ActionMethod,
+  ActionOperationMethod,
+  AllActionMethod,
+  AllActionOperationMethod,
+  FacetMethod,
+  FacetOperationMethod,
+  AllFacetMethod,
+  AllFacetOperationMethod,
+  OperationsExtensions
+} from './operations/methods';
+
+// Operation wrappers - automatic validation for all operations
+export * from './operations/wrappers';
+// Core architectural patterns
+export type { PrimaryOperations } from './operations/primary';
+export type { ContainedOperations } from './operations/contained';
+
+// UI usage patterns (React providers, etc.)
+export type {
+  CollectionOperations,
+  InstanceOperations
+} from './operations/specialized';

package/src/item/IUtils.ts

@@ -1,88 +1,17 @@
 /* eslint-disable indent */
  
 import { Item } from "../items";
-import { isComKey, isPriKey, toKeyTypeArray } from "../key/KUtils";
-import { AllItemTypeArrays, ComKey, PriKey } from "../keys";
+import { isComKey, isPriKey } from "../key/KUtils";
+import { ComKey, PriKey } from "../keys";
 
-import LibLogger from '../logger';
+/**
+ * @deprecated Use validatePK from @fjell/core/validation instead
+ * Re-exported for backward compatibility
+ */
+export { validatePK, validateKeys } from '../validation/ItemValidator';
 
-const logger = LibLogger.get('IUtils');
-
-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;
-};
-
-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);
-};
-
-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;
-};
+// validatePK and validateKeys have been moved to ../validation/ItemValidator.ts
+// They are re-exported above for backward compatibility
 
 export const isPriItem = <
   S extends string,

package/src/key/KUtils.ts

@@ -192,13 +192,13 @@ export const isItemKey = (key: any): boolean => {
 export const isComKey = (key: any): boolean => {
   logger.trace('isComKey', { key });
   return key !== undefined &&
-    (key.pk !== undefined && key.kt !== undefined) && (key.loc !== undefined && key.loc.length > 0);
+    (key.pk !== undefined && key.kt !== undefined) && (key.loc !== undefined && Array.isArray(key.loc));
 }
 
 export const isPriKey = (key: any): boolean => {
   logger.trace('isPriKey', { key });
   return key !== undefined &&
-    (key.pk !== undefined && key.kt !== undefined) && (key.loc === undefined || key.loc.length === 0);
+    (key.pk !== undefined && key.kt !== undefined) && (key.loc === undefined);
 }
 
 export const isLocKey = (key: any): boolean => {

package/src/operations/OperationContext.ts

@@ -0,0 +1,12 @@
+import { ComKey, LocKeyArray, PriKey } from '../keys';
+import type { ErrorInfo } from '../errors/ActionError';
+
+export interface OperationContext {
+  itemType: string;
+  operationType: ErrorInfo['operation']['type'];
+  operationName: string;
+  params: Record<string, any>;
+  key?: PriKey<any> | ComKey<any, any, any, any, any, any>;
+  locations?: LocKeyArray<any, any, any, any, any>;
+}
+