@fjell/core 4.4.48 → 4.4.49

package/README.md

@@ -109,6 +109,98 @@ const query = IQFactory.create('user')
 const results = await IQUtils.execute(query)
 ```
 
+### Operations Interface
+
+@fjell/core provides the standard Operations interface used across all fjell libraries. This interface defines the contract for working with Items:
+
+```typescript
+import { Operations, PrimaryOperations, ContainedOperations } from '@fjell/core';
+
+// For primary items
+const userOps: PrimaryOperations<User, 'user'> = ...;
+
+// For contained items
+const commentOps: ContainedOperations<Comment, 'comment', 'post'> = ...;
+```
+
+See [Operations README](src/operations/README.md) for detailed documentation.
+
+### Validation Module
+
+@fjell/core provides centralized validation functions for ensuring data integrity across the Fjell ecosystem:
+
+```typescript
+import { 
+  validateLocations, 
+  validateKey, 
+  validatePK, 
+  validateKeys 
+} from '@fjell/core/validation';
+```
+
+#### Location Validation
+
+Validates that location key arrays match the expected coordinate hierarchy:
+
+```typescript
+import { validateLocations } from '@fjell/core/validation';
+
+// Validate location array order
+validateLocations(
+  [{ kt: 'store', lk: 'store-1' }],
+  coordinate,
+  'create'  // operation name for error context
+);
+
+// Non-throwing validation
+import { isValidLocations } from '@fjell/core/validation';
+const result = isValidLocations(
+  [{ kt: 'store', lk: 'store-1' }],
+  coordinate,
+  'create'
+);
+if (!result.valid) {
+  console.log(result.error); // Validation error message
+}
+```
+
+#### Key Validation
+
+Validates PriKey and ComKey structures match library type:
+
+```typescript
+import { validateKey, validatePriKey, validateComKey } from '@fjell/core/validation';
+
+// Validate any key type
+validateKey(key, coordinate, 'get');
+
+// Validate specific key types
+validatePriKey(priKey, coordinate, 'update');
+validateComKey(comKey, coordinate, 'remove');
+```
+
+#### Item Validation
+
+Validates Item keys match expected types:
+
+```typescript
+import { validatePK, validateKeys } from '@fjell/core/validation';
+
+// Validate item has correct primary key type
+const validatedItem = validatePK(item, 'product');
+
+// Validate item key types match key type array
+const validatedItem = validateKeys(item, ['product', 'store']);
+```
+
+**Features:**
+- **Comprehensive Error Messages**: Detailed context including operation name, expected vs actual values
+- **Type Safety**: Full TypeScript support with proper type inference
+- **Performance**: Optimized O(n) validation with minimal overhead
+- **Flexible**: Both throwing and non-throwing variants available
+
+See [Validation Examples](examples/validation-example.ts) for detailed usage patterns.
+
 ## Architecture Philosophy
 
 Fjell Core is designed around **progressive enhancement**:

package/dist/Coordinate.d.ts

@@ -0,0 +1,7 @@
+import type { ItemTypeArray } from "./keys";
+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 declare 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>;

package/dist/errors/ActionError.d.ts

@@ -0,0 +1,51 @@
+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 declare class ActionError extends Error {
+    readonly errorInfo: ErrorInfo;
+    constructor(errorInfo: ErrorInfo, cause?: Error);
+    toJSON(): ErrorInfo;
+}

package/dist/errors/BusinessLogicError.d.ts

@@ -0,0 +1,4 @@
+import { ActionError } from './ActionError';
+export declare class BusinessLogicError extends ActionError {
+    constructor(message: string, suggestedAction?: string, retryable?: boolean);
+}

package/dist/errors/DuplicateError.d.ts

@@ -0,0 +1,4 @@
+import { ActionError } from './ActionError';
+export declare class DuplicateError extends ActionError {
+    constructor(message: string, existingItemIdOrKey?: string | number | any, duplicateField?: string);
+}

package/dist/errors/NotFoundError.d.ts

@@ -0,0 +1,4 @@
+import { ActionError } from './ActionError';
+export declare class NotFoundError extends ActionError {
+    constructor(message: string, itemType: string, key?: any);
+}

package/dist/errors/PermissionError.d.ts

@@ -0,0 +1,4 @@
+import { ActionError } from './ActionError';
+export declare class PermissionError extends ActionError {
+    constructor(message: string, requiredPermission?: string, currentPermissions?: string[]);
+}

package/dist/errors/ValidationError.d.ts

@@ -0,0 +1,4 @@
+import { ActionError } from './ActionError';
+export declare class ValidationError extends ActionError {
+    constructor(message: string, validOptions?: string[], suggestedAction?: string, conflictingValue?: any);
+}

package/dist/errors/index.d.ts

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

package/dist/index.d.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";
 export * from './key/KUtils';
@@ -9,3 +10,13 @@ export * from './item/IQFactory';
 export * from './item/IQUtils';
 export * from './item/IUtils';
 export * from './item/ItemQuery';
+export * from './validation';
+export * from './errors';
+export * from './operations';
+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';
+export * from './operations/wrappers';
+export type { PrimaryOperations } from './operations/primary';
+export type { ContainedOperations } from './operations/contained';
+export type { CollectionOperations, InstanceOperations } from './operations/specialized';