@fjell/core 4.4.50 → 4.4.51

package/src/operations/wrappers/createFindWrapper.ts

@@ -1,105 +0,0 @@
-/**
- * Wrapper for find() operation
- *
- * Provides automatic validation for find() operation parameters.
- */
-
-import type { Item } from "../../items";
-import type { LocKeyArray } from "../../keys";
-import type { Coordinate } from "../../Coordinate";
-import type { OperationParams } from "../Operations";
-import { validateFinderName, validateLocations, validateOperationParams, validatePK } from "../../validation";
-import type { FindMethod } from "../methods";
-import type { ErrorContext, WrapperOptions } from "./types";
-import LibLogger from "../../logger";
-
-const logger = LibLogger.get('operations', 'wrappers', 'find');
-
-/**
- * Creates a wrapped find() method with automatic parameter validation.
- *
- * @param coordinate - The coordinate defining the item hierarchy
- * @param implementation - The core logic for the operation
- * @param options - Optional configuration
- * @returns A fully validated find() method
- *
- * @example
- * ```typescript
- * const find = createFindWrapper(
- *   coordinate,
- *   async (finder, params, locations) => {
- *     return await database.executeFinder(finder, params, locations);
- *   }
- * );
- * ```
- */
-export function createFindWrapper<
-  V extends Item<S, L1, L2, L3, L4, L5>,
-  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>,
-  implementation: FindMethod<V, S, L1, L2, L3, L4, L5>,
-  options: WrapperOptions = {}
-): FindMethod<V, S, L1, L2, L3, L4, L5> {
-  
-  const operationName = options.operationName || 'find';
-  
-  return async (
-    finder: string,
-    params?: OperationParams,
-    locations?: LocKeyArray<L1, L2, L3, L4, L5> | []
-  ): Promise<V[]> => {
-    
-    if (options.debug) {
-      logger.debug(`[${operationName}] Called:`, { finder, params, locations });
-    }
-    
-    // Validate
-    if (!options.skipValidation) {
-      validateFinderName(finder, operationName);
-      validateOperationParams(params, operationName);
-      validateLocations(locations, coordinate, operationName);
-    }
-    
-    // Normalize
-    const normalizedParams = params ?? {};
-    const normalizedLocations = (locations ?? []) as LocKeyArray<L1, L2, L3, L4, L5> | [];
-    
-    // Execute
-    try {
-      const result = await implementation(finder, normalizedParams, normalizedLocations);
-      
-      if (options.debug) {
-        logger.debug(`[${operationName}] Found ${result.length} items for finder "${finder}"`);
-      }
-      
-      // Validate primary key types for all items
-      if (!options.skipValidation) {
-        return validatePK(result, coordinate.kta[0]) as V[];
-      }
-      
-      return result;
-      
-    } catch (error) {
-      if (options.onError) {
-        const context: ErrorContext = {
-          operationName,
-          params: [finder, params, locations],
-          coordinate
-        };
-        throw options.onError(error as Error, context);
-      }
-      
-      throw new Error(
-        `[${operationName}] Operation failed for finder "${finder}": ${(error as Error).message}`,
-        { cause: error }
-      );
-    }
-  };
-}
-

package/src/operations/wrappers/createGetWrapper.ts

@@ -1,96 +0,0 @@
-/**
- * Wrapper for get() operation
- *
- * Provides automatic validation for get() operation parameters.
- */
-
-import type { Item } from "../../items";
-import type { ComKey, PriKey } from "../../keys";
-import type { Coordinate } from "../../Coordinate";
-import { validateKey, validatePK } from "../../validation";
-import type { GetMethod } from "../methods";
-import type { ErrorContext, WrapperOptions } from "./types";
-import LibLogger from "../../logger";
-
-const logger = LibLogger.get('operations', 'wrappers', 'get');
-
-/**
- * Creates a wrapped get() method with automatic parameter validation.
- *
- * @param coordinate - The coordinate defining the item hierarchy
- * @param implementation - The core logic for the operation
- * @param options - Optional configuration
- * @returns A fully validated get() method
- *
- * @example
- * ```typescript
- * const get = createGetWrapper(
- *   coordinate,
- *   async (key) => {
- *     return await database.findByKey(key);
- *   }
- * );
- * ```
- */
-export function createGetWrapper<
-  V extends Item<S, L1, L2, L3, L4, L5>,
-  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>,
-  implementation: GetMethod<V, S, L1, L2, L3, L4, L5>,
-  options: WrapperOptions = {}
-): GetMethod<V, S, L1, L2, L3, L4, L5> {
-  
-  const operationName = options.operationName || 'get';
-  
-  return async (
-    key: PriKey<S> | ComKey<S, L1, L2, L3, L4, L5>
-  ): Promise<V | null> => {
-    
-    if (options.debug) {
-      logger.debug(`[${operationName}] Called with key:`, key);
-    }
-    
-    // Validate key structure
-    if (!options.skipValidation) {
-      validateKey(key, coordinate, operationName);
-    }
-    
-    // Execute
-    try {
-      const result = await implementation(key);
-      
-      if (options.debug) {
-        logger.debug(`[${operationName}] Result:`, result ? 'found' : 'not found');
-      }
-      
-      // Validate primary key type if result exists
-      if (result && !options.skipValidation) {
-        return validatePK(result, coordinate.kta[0]) as V;
-      }
-      
-      return result;
-      
-    } catch (error) {
-      if (options.onError) {
-        const context: ErrorContext = {
-          operationName,
-          params: [key],
-          coordinate
-        };
-        throw options.onError(error as Error, context);
-      }
-      
-      throw new Error(
-        `[${operationName}] Operation failed: ${(error as Error).message}`,
-        { cause: error }
-      );
-    }
-  };
-}
-

package/src/operations/wrappers/createOneWrapper.ts

@@ -1,128 +0,0 @@
-/**
- * Wrapper for one() operation
- *
- * Provides automatic validation for one() operation parameters.
- */
-
-import type { Item } from "../../items";
-import type { ItemQuery } from "../../item/ItemQuery";
-import type { LocKeyArray } from "../../keys";
-import type { Coordinate } from "../../Coordinate";
-import { validateLocations, validatePK, validateQuery } from "../../validation";
-import type { OneMethod } from "../methods";
-import type { ErrorContext, WrapperOptions } from "./types";
-import LibLogger from "../../logger";
-
-const logger = LibLogger.get('operations', 'wrappers', 'one');
-
-/**
- * Creates a wrapped one() method with automatic parameter validation.
- *
- * The wrapper handles:
- * - Query validation
- * - Location array validation against coordinate
- * - Parameter normalization (undefined → defaults)
- * - Consistent error handling
- *
- * @param coordinate - The coordinate defining the item hierarchy
- * @param implementation - The core logic for the operation (no validation needed)
- * @param options - Optional configuration
- * @returns A fully validated one() method
- *
- * @example
- * ```typescript
- * const one = createOneWrapper(
- *   coordinate,
- *   async (query, locations) => {
- *     // Just implement the logic - validation is automatic
- *     return await database.findOne(query, locations);
- *   }
- * );
- *
- * // Usage
- * const item = await one({ status: 'active' }, [{ kt: 'org', lk: '123' }]);
- * ```
- */
-export function createOneWrapper<
-  V extends Item<S, L1, L2, L3, L4, L5>,
-  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>,
-  implementation: OneMethod<V, S, L1, L2, L3, L4, L5>,
-  options: WrapperOptions = {}
-): OneMethod<V, S, L1, L2, L3, L4, L5> {
-  
-  const operationName = options.operationName || 'one';
-  
-  return async (
-    query?: ItemQuery,
-    locations?: LocKeyArray<L1, L2, L3, L4, L5> | []
-  ): Promise<V | null> => {
-    
-    // Debug logging if enabled
-    if (options.debug) {
-      logger.debug(`[${operationName}] Called with:`, { query, locations });
-    }
-    
-    // 1. Validate parameters (unless explicitly skipped)
-    if (!options.skipValidation) {
-      try {
-        validateQuery(query, operationName);
-        validateLocations(locations, coordinate, operationName);
-      } catch (error) {
-        // Validation errors are already well-formatted
-        throw error;
-      }
-    }
-    
-    // 2. Normalize parameters
-    const normalizedQuery = query ?? {};
-    const normalizedLocations = (locations ?? []) as LocKeyArray<L1, L2, L3, L4, L5> | [];
-    
-    // 3. Call implementation with validated params
-    try {
-      const result = await implementation(normalizedQuery, normalizedLocations);
-      
-      if (options.debug) {
-        logger.debug(`[${operationName}] Result:`, result ? 'found' : 'not found');
-      }
-      
-      // Validate primary key type if result exists
-      if (result && !options.skipValidation) {
-        return validatePK(result, coordinate.kta[0]) as V;
-      }
-      
-      return result;
-      
-    } catch (error) {
-      // 4. Handle errors
-      if (options.onError) {
-        const context: ErrorContext = {
-          operationName,
-          params: [query, locations],
-          coordinate
-        };
-        throw options.onError(error as Error, context);
-      }
-      
-      // Default error enhancement
-      const enhanced = new Error(
-        `[${operationName}] Operation failed: ${(error as Error).message}`,
-        { cause: error }
-      );
-      
-      // Preserve stack trace
-      if ((error as Error).stack) {
-        enhanced.stack = (error as Error).stack;
-      }
-      
-      throw enhanced;
-    }
-  };
-}
-

package/src/operations/wrappers/createRemoveWrapper.ts

@@ -1,91 +0,0 @@
-/**
- * Wrapper for remove() operation
- *
- * Provides automatic validation for remove() operation parameters.
- */
-
-import type { Item } from "../../items";
-import type { ComKey, PriKey } from "../../keys";
-import type { Coordinate } from "../../Coordinate";
-import { validateKey } from "../../validation";
-import type { RemoveMethod } from "../methods";
-import type { ErrorContext, WrapperOptions } from "./types";
-import LibLogger from "../../logger";
-
-const logger = LibLogger.get('operations', 'wrappers', 'remove');
-
-/**
- * Creates a wrapped remove() method with automatic parameter validation.
- *
- * @param coordinate - The coordinate defining the item hierarchy
- * @param implementation - The core logic for the operation
- * @param options - Optional configuration
- * @returns A fully validated remove() method
- *
- * @example
- * ```typescript
- * const remove = createRemoveWrapper(
- *   coordinate,
- *   async (key) => {
- *     return await database.delete(key);
- *   }
- * );
- * ```
- */
-export function createRemoveWrapper<
-  V extends Item<S, L1, L2, L3, L4, L5>,
-  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>,
-  implementation: RemoveMethod<V, S, L1, L2, L3, L4, L5>,
-  options: WrapperOptions = {}
-): RemoveMethod<V, S, L1, L2, L3, L4, L5> {
-  
-  const operationName = options.operationName || 'remove';
-  
-  return async (
-    key: PriKey<S> | ComKey<S, L1, L2, L3, L4, L5>
-  ): Promise<V | void> => {
-    
-    if (options.debug) {
-      logger.debug(`[${operationName}] Called with key:`, key);
-    }
-    
-    // Validate key structure
-    if (!options.skipValidation) {
-      validateKey(key, coordinate, operationName);
-    }
-    
-    // Execute
-    try {
-      const result = await implementation(key);
-      
-      if (options.debug) {
-        logger.debug(`[${operationName}] Removed item:`, key);
-      }
-      
-      return result;
-      
-    } catch (error) {
-      if (options.onError) {
-        const context: ErrorContext = {
-          operationName,
-          params: [key],
-          coordinate
-        };
-        throw options.onError(error as Error, context);
-      }
-      
-      throw new Error(
-        `[${operationName}] Operation failed: ${(error as Error).message}`,
-        { cause: error }
-      );
-    }
-  };
-}
-

package/src/operations/wrappers/createUpdateWrapper.ts

@@ -1,106 +0,0 @@
-/**
- * Wrapper for update() operation
- *
- * Provides automatic validation for update() operation parameters.
- */
-
-import type { Item } from "../../items";
-import type { ComKey, PriKey } from "../../keys";
-import type { Coordinate } from "../../Coordinate";
-import { validateKey, validatePK } from "../../validation";
-import type { UpdateMethod } from "../methods";
-import type { ErrorContext, WrapperOptions } from "./types";
-import LibLogger from "../../logger";
-
-const logger = LibLogger.get('operations', 'wrappers', 'update');
-
-/**
- * Creates a wrapped update() method with automatic parameter validation.
- *
- * @param coordinate - The coordinate defining the item hierarchy
- * @param implementation - The core logic for the operation
- * @param options - Optional configuration
- * @returns A fully validated update() method
- *
- * @example
- * ```typescript
- * const update = createUpdateWrapper(
- *   coordinate,
- *   async (key, item) => {
- *     return await database.update(key, item);
- *   }
- * );
- * ```
- */
-export function createUpdateWrapper<
-  V extends Item<S, L1, L2, L3, L4, L5>,
-  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>,
-  implementation: UpdateMethod<V, S, L1, L2, L3, L4, L5>,
-  options: WrapperOptions = {}
-): UpdateMethod<V, S, L1, L2, L3, L4, L5> {
-  
-  const operationName = options.operationName || 'update';
-  
-  return async (
-    key: PriKey<S> | ComKey<S, L1, L2, L3, L4, L5>,
-    item: Partial<Item<S, L1, L2, L3, L4, L5>>
-  ): Promise<V> => {
-    
-    if (options.debug) {
-      logger.debug(`[${operationName}] Called with:`, { key, item });
-    }
-    
-    // Validate
-    if (!options.skipValidation) {
-      validateKey(key, coordinate, operationName);
-      
-      if (!item || typeof item !== 'object' || Array.isArray(item)) {
-        throw new Error(
-          `[${operationName}] Invalid item parameter.\n` +
-          `\n` +
-          `Expected: object\n` +
-          `Received: ${Array.isArray(item) ? 'array' : typeof item}`
-        );
-      }
-    }
-    
-    // Execute
-    try {
-      const result = await implementation(key, item);
-      
-      if (options.debug) {
-        logger.debug(`[${operationName}] Updated item:`, result.key);
-      }
-      
-      // Validate primary key type
-      if (!options.skipValidation) {
-        return validatePK(result, coordinate.kta[0]) as V;
-      }
-      
-      return result;
-      
-    } catch (error) {
-      if (options.onError) {
-        const context: ErrorContext = {
-          operationName,
-          params: [key, item],
-          coordinate
-        };
-        throw options.onError(error as Error, context);
-      }
-      
-      throw new Error(
-        `[${operationName}] Operation failed: ${(error as Error).message}`,
-        { cause: error }
-      );
-    }
-  };
-}
-

package/src/operations/wrappers/createUpsertWrapper.ts

@@ -1,108 +0,0 @@
-/**
- * Wrapper for upsert() operation
- *
- * Provides automatic validation for upsert() operation parameters.
- */
-
-import type { Item } from "../../items";
-import type { ComKey, LocKeyArray, PriKey } from "../../keys";
-import type { Coordinate } from "../../Coordinate";
-import { validateKey, validateLocations, validatePK } from "../../validation";
-import type { UpsertMethod } from "../methods";
-import type { ErrorContext, WrapperOptions } from "./types";
-import LibLogger from "../../logger";
-
-const logger = LibLogger.get('operations', 'wrappers', 'upsert');
-
-/**
- * Creates a wrapped upsert() method with automatic parameter validation.
- *
- * @param coordinate - The coordinate defining the item hierarchy
- * @param implementation - The core logic for the operation
- * @param options - Optional configuration
- * @returns A fully validated upsert() method
- *
- * @example
- * ```typescript
- * const upsert = createUpsertWrapper(
- *   coordinate,
- *   async (key, item, locations) => {
- *     return await database.upsert(key, item, locations);
- *   }
- * );
- * ```
- */
-export function createUpsertWrapper<
-  V extends Item<S, L1, L2, L3, L4, L5>,
-  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>,
-  implementation: UpsertMethod<V, S, L1, L2, L3, L4, L5>,
-  options: WrapperOptions = {}
-): UpsertMethod<V, S, L1, L2, L3, L4, L5> {
-  
-  const operationName = options.operationName || 'upsert';
-  
-  return async (
-    key: PriKey<S> | ComKey<S, L1, L2, L3, L4, L5>,
-    item: Partial<Item<S, L1, L2, L3, L4, L5>>,
-    locations?: LocKeyArray<L1, L2, L3, L4, L5>
-  ): Promise<V> => {
-    
-    if (options.debug) {
-      logger.debug(`[${operationName}] Called with:`, { key, item, locations });
-    }
-    
-    // Validate
-    if (!options.skipValidation) {
-      validateKey(key, coordinate, operationName);
-      validateLocations(locations, coordinate, operationName);
-      
-      if (!item || typeof item !== 'object' || Array.isArray(item)) {
-        throw new Error(
-          `[${operationName}] Invalid item parameter.\n` +
-          `\n` +
-          `Expected: object\n` +
-          `Received: ${Array.isArray(item) ? 'array' : typeof item}`
-        );
-      }
-    }
-    
-    // Execute
-    try {
-      const result = await implementation(key, item);
-      
-      if (options.debug) {
-        logger.debug(`[${operationName}] Upserted item:`, result.key);
-      }
-      
-      // Validate primary key type
-      if (!options.skipValidation) {
-        return validatePK(result, coordinate.kta[0]) as V;
-      }
-      
-      return result;
-      
-    } catch (error) {
-      if (options.onError) {
-        const context: ErrorContext = {
-          operationName,
-          params: [key, item, locations],
-          coordinate
-        };
-        throw options.onError(error as Error, context);
-      }
-      
-      throw new Error(
-        `[${operationName}] Operation failed: ${(error as Error).message}`,
-        { cause: error }
-      );
-    }
-  };
-}
-

package/src/operations/wrappers/index.ts

@@ -1,39 +0,0 @@
-/**
- * Operation wrapper functions that provide automatic parameter validation.
- *
- * These wrappers eliminate boilerplate validation code in Operations implementations.
- *
- * @example
- * ```typescript
- * import { createOneWrapper } from '@fjell/core';
- *
- * const one = createOneWrapper(
- *   coordinate,
- *   async (query, locations) => {
- *     // Validation happens automatically
- *     return await database.findOne(query, locations);
- *   }
- * );
- * ```
- *
- * @module wrappers
- */
-
-// Types
-export type { WrapperOptions, ErrorContext, WrapperContext } from './types';
-
-// Wrapper functions
-export { createOneWrapper } from './createOneWrapper';
-export { createAllWrapper } from './createAllWrapper';
-export { createGetWrapper } from './createGetWrapper';
-export { createCreateWrapper } from './createCreateWrapper';
-export { createUpdateWrapper } from './createUpdateWrapper';
-export { createUpsertWrapper } from './createUpsertWrapper';
-export { createRemoveWrapper } from './createRemoveWrapper';
-export { createFindWrapper } from './createFindWrapper';
-export { createFindOneWrapper } from './createFindOneWrapper';
-export { createActionWrapper } from './createActionWrapper';
-export { createAllActionWrapper } from './createAllActionWrapper';
-export { createFacetWrapper } from './createFacetWrapper';
-export { createAllFacetWrapper } from './createAllFacetWrapper';
-