@fjell/core 4.4.48 → 4.4.49

package/src/operations/wrappers/createAllActionWrapper.ts

@@ -0,0 +1,109 @@
+/**
+ * Wrapper for allAction() operation
+ *
+ * Provides automatic validation for allAction() operation parameters.
+ */
+
+import type { Item } from "../../items";
+import type { LocKeyArray } from "../../keys";
+import type { Coordinate } from "../../Coordinate";
+import type { AffectedKeys, OperationParams } from "../Operations";
+import { validateActionName, validateLocations, validateOperationParams, validatePK } from "../../validation";
+import type { AllActionOperationMethod } from "../methods";
+import type { ErrorContext, WrapperOptions } from "./types";
+import LibLogger from "../../logger";
+
+const logger = LibLogger.get('operations', 'wrappers', 'allAction');
+
+/**
+ * Creates a wrapped allAction() 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 allAction() method
+ *
+ * @example
+ * ```typescript
+ * const allAction = createAllActionWrapper(
+ *   coordinate,
+ *   async (action, params, locations) => {
+ *     return await database.executeAllAction(action, params, locations);
+ *   }
+ * );
+ * ```
+ */
+export function createAllActionWrapper<
+  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: AllActionOperationMethod<V, S, L1, L2, L3, L4, L5>,
+  options: WrapperOptions = {}
+): AllActionOperationMethod<V, S, L1, L2, L3, L4, L5> {
+  
+  const operationName = options.operationName || 'allAction';
+  
+  return async (
+    action: string,
+    params?: OperationParams,
+    locations?: LocKeyArray<L1, L2, L3, L4, L5> | []
+  ): Promise<[V[], AffectedKeys]> => {
+    
+    if (options.debug) {
+      logger.debug(`[${operationName}] Called:`, { action, params, locations });
+    }
+    
+    // Validate
+    if (!options.skipValidation) {
+      validateActionName(action, 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(action, normalizedParams, normalizedLocations);
+      
+      if (options.debug) {
+        logger.debug(`[${operationName}] Action "${action}" completed:`, {
+          itemsAffected: result[0].length,
+          affectedKeys: result[1].length
+        });
+      }
+      
+      // Validate primary key types for all returned items
+      if (!options.skipValidation) {
+        const validatedItems = validatePK(result[0], coordinate.kta[0]) as V[];
+        return [validatedItems, result[1]];
+      }
+      
+      return result;
+      
+    } catch (error) {
+      if (options.onError) {
+        const context: ErrorContext = {
+          operationName,
+          params: [action, params, locations],
+          coordinate
+        };
+        throw options.onError(error as Error, context);
+      }
+      
+      throw new Error(
+        `[${operationName}] Action "${action}" failed: ${(error as Error).message}`,
+        { cause: error }
+      );
+    }
+  };
+}
+

package/src/operations/wrappers/createAllFacetWrapper.ts

@@ -0,0 +1,98 @@
+/**
+ * Wrapper for allFacet() operation
+ *
+ * Provides automatic validation for allFacet() operation parameters.
+ */
+
+import type { LocKeyArray } from "../../keys";
+import type { Coordinate } from "../../Coordinate";
+import type { OperationParams } from "../Operations";
+import { validateFacetName, validateLocations, validateOperationParams } from "../../validation";
+import type { AllFacetOperationMethod } from "../methods";
+import type { ErrorContext, WrapperOptions } from "./types";
+import LibLogger from "../../logger";
+
+const logger = LibLogger.get('operations', 'wrappers', 'allFacet');
+
+/**
+ * Creates a wrapped allFacet() 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 allFacet() method
+ *
+ * @example
+ * ```typescript
+ * const allFacet = createAllFacetWrapper(
+ *   coordinate,
+ *   async (facet, params, locations) => {
+ *     return await database.executeAllFacet(facet, params, locations);
+ *   }
+ * );
+ * ```
+ */
+export function createAllFacetWrapper<
+  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: AllFacetOperationMethod<L1, L2, L3, L4, L5>,
+  options: WrapperOptions = {}
+): AllFacetOperationMethod<L1, L2, L3, L4, L5> {
+  
+  const operationName = options.operationName || 'allFacet';
+  
+  return async (
+    facet: string,
+    params?: OperationParams,
+    locations?: LocKeyArray<L1, L2, L3, L4, L5> | []
+  ): Promise<any> => {
+    
+    if (options.debug) {
+      logger.debug(`[${operationName}] Called:`, { facet, params, locations });
+    }
+    
+    // Validate
+    if (!options.skipValidation) {
+      validateFacetName(facet, 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(facet, normalizedParams, normalizedLocations);
+      
+      if (options.debug) {
+        logger.debug(`[${operationName}] Facet "${facet}" completed`);
+      }
+      
+      return result;
+      
+    } catch (error) {
+      if (options.onError) {
+        const context: ErrorContext = {
+          operationName,
+          params: [facet, params, locations],
+          coordinate
+        };
+        throw options.onError(error as Error, context);
+      }
+      
+      throw new Error(
+        `[${operationName}] Facet "${facet}" failed: ${(error as Error).message}`,
+        { cause: error }
+      );
+    }
+  };
+}
+

package/src/operations/wrappers/createAllWrapper.ts

@@ -0,0 +1,103 @@
+/**
+ * Wrapper for all() operation
+ *
+ * Provides automatic validation for all() 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 { AllMethod } from "../methods";
+import type { ErrorContext, WrapperOptions } from "./types";
+import LibLogger from "../../logger";
+
+const logger = LibLogger.get('operations', 'wrappers', 'all');
+
+/**
+ * Creates a wrapped all() 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 all() method
+ *
+ * @example
+ * ```typescript
+ * const all = createAllWrapper(
+ *   coordinate,
+ *   async (query, locations) => {
+ *     return await database.findAll(query, locations);
+ *   }
+ * );
+ * ```
+ */
+export function createAllWrapper<
+  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: AllMethod<V, S, L1, L2, L3, L4, L5>,
+  options: WrapperOptions = {}
+): AllMethod<V, S, L1, L2, L3, L4, L5> {
+  
+  const operationName = options.operationName || 'all';
+  
+  return async (
+    query?: ItemQuery,
+    locations?: LocKeyArray<L1, L2, L3, L4, L5> | []
+  ): Promise<V[]> => {
+    
+    if (options.debug) {
+      logger.debug(`[${operationName}] Called with:`, { query, locations });
+    }
+    
+    // Validate
+    if (!options.skipValidation) {
+      validateQuery(query, operationName);
+      validateLocations(locations, coordinate, operationName);
+    }
+    
+    // Normalize
+    const normalizedQuery = query ?? {};
+    const normalizedLocations = (locations ?? []) as LocKeyArray<L1, L2, L3, L4, L5> | [];
+    
+    // Execute
+    try {
+      const result = await implementation(normalizedQuery, normalizedLocations);
+      
+      if (options.debug) {
+        logger.debug(`[${operationName}] Result: ${result.length} items`);
+      }
+      
+      // 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: [query, 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/createCreateWrapper.ts

@@ -0,0 +1,117 @@
+/**
+ * Wrapper for create() operation
+ *
+ * Provides automatic validation for create() operation parameters.
+ */
+
+import type { Item } from "../../items";
+import type { Coordinate } from "../../Coordinate";
+import { validateKey, validateLocations, validatePK } from "../../validation";
+import type { CreateMethod } from "../methods";
+import type { CreateOptions } from "../Operations";
+import type { ErrorContext, WrapperOptions } from "./types";
+import LibLogger from "../../logger";
+
+const logger = LibLogger.get('operations', 'wrappers', 'create');
+
+/**
+ * Creates a wrapped create() method with automatic parameter validation.
+ *
+ * @param coordinate - The coordinate defining the item hierarchy
+ * @param implementation - The core logic for the operation
+ * @param options - Optional wrapper configuration
+ * @returns A fully validated create() method
+ *
+ * @example
+ * ```typescript
+ * const create = createCreateWrapper(
+ *   coordinate,
+ *   async (item, options) => {
+ *     return await database.create(item, options);
+ *   }
+ * );
+ * ```
+ */
+export function createCreateWrapper<
+  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: CreateMethod<V, S, L1, L2, L3, L4, L5>,
+  wrapperOptions: WrapperOptions = {}
+): CreateMethod<V, S, L1, L2, L3, L4, L5> {
+  
+  const operationName = wrapperOptions.operationName || 'create';
+  
+  return async (
+    item: Partial<Item<S, L1, L2, L3, L4, L5>>,
+    createOptions?: CreateOptions<S, L1, L2, L3, L4, L5>
+  ): Promise<V> => {
+    
+    if (wrapperOptions.debug) {
+      logger.debug(`[${operationName}] Called with:`, { item, options: createOptions });
+    }
+    
+    // Validate
+    if (!wrapperOptions.skipValidation) {
+      // Validate item is an object
+      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}`
+        );
+      }
+      
+      // Validate create options
+      if (createOptions) {
+        if ('key' in createOptions) {
+          // Validate the key (even if null, let validateKey handle it)
+          validateKey(createOptions.key as any, coordinate, operationName);
+        }
+        if ('locations' in createOptions) {
+          // Validate the locations (even if undefined, let validateLocations handle it)
+          validateLocations(createOptions.locations, coordinate, operationName);
+        }
+      }
+    }
+    
+    // Execute
+    try {
+      const result = await implementation(item, createOptions);
+      
+      if (wrapperOptions.debug) {
+        logger.debug(`[${operationName}] Created item:`, result.key);
+      }
+      
+      // Validate primary key type
+      if (!wrapperOptions.skipValidation) {
+        return validatePK(result, coordinate.kta[0]) as V;
+      }
+      
+      return result;
+      
+    } catch (error) {
+      if (wrapperOptions.onError) {
+        const context: ErrorContext = {
+          operationName,
+          params: [item, createOptions],
+          coordinate
+        };
+        throw wrapperOptions.onError(error as Error, context);
+      }
+      
+      throw new Error(
+        `[${operationName}] Operation failed: ${(error as Error).message}`,
+        { cause: error }
+      );
+    }
+  };
+}
+

package/src/operations/wrappers/createFacetWrapper.ts

@@ -0,0 +1,97 @@
+/**
+ * Wrapper for facet() operation
+ *
+ * Provides automatic validation for facet() operation parameters.
+ */
+
+import type { ComKey, PriKey } from "../../keys";
+import type { Coordinate } from "../../Coordinate";
+import type { OperationParams } from "../Operations";
+import { validateFacetName, validateKey, validateOperationParams } from "../../validation";
+import type { FacetOperationMethod } from "../methods";
+import type { ErrorContext, WrapperOptions } from "./types";
+import LibLogger from "../../logger";
+
+const logger = LibLogger.get('operations', 'wrappers', 'facet');
+
+/**
+ * Creates a wrapped facet() 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 facet() method
+ *
+ * @example
+ * ```typescript
+ * const facet = createFacetWrapper(
+ *   coordinate,
+ *   async (key, facet, params) => {
+ *     return await database.executeFacet(key, facet, params);
+ *   }
+ * );
+ * ```
+ */
+export function createFacetWrapper<
+  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: FacetOperationMethod<S, L1, L2, L3, L4, L5>,
+  options: WrapperOptions = {}
+): FacetOperationMethod<S, L1, L2, L3, L4, L5> {
+  
+  const operationName = options.operationName || 'facet';
+  
+  return async (
+    key: PriKey<S> | ComKey<S, L1, L2, L3, L4, L5>,
+    facet: string,
+    params?: OperationParams
+  ): Promise<any> => {
+    
+    if (options.debug) {
+      logger.debug(`[${operationName}] Called:`, { key, facet, params });
+    }
+    
+    // Validate
+    if (!options.skipValidation) {
+      validateKey(key, coordinate, operationName);
+      validateFacetName(facet, operationName);
+      validateOperationParams(params, operationName);
+    }
+    
+    // Normalize
+    const normalizedParams = params ?? {};
+    
+    // Execute
+    try {
+      const result = await implementation(key, facet, normalizedParams);
+      
+      if (options.debug) {
+        logger.debug(`[${operationName}] Facet "${facet}" completed`);
+      }
+      
+      return result;
+      
+    } catch (error) {
+      if (options.onError) {
+        const context: ErrorContext = {
+          operationName,
+          params: [key, facet, params],
+          coordinate
+        };
+        throw options.onError(error as Error, context);
+      }
+      
+      throw new Error(
+        `[${operationName}] Facet "${facet}" failed: ${(error as Error).message}`,
+        { cause: error }
+      );
+    }
+  };
+}
+

package/src/operations/wrappers/createFindOneWrapper.ts

@@ -0,0 +1,105 @@
+/**
+ * Wrapper for findOne() operation
+ *
+ * Provides automatic validation for findOne() 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 { FindOneMethod } from "../methods";
+import type { ErrorContext, WrapperOptions } from "./types";
+import LibLogger from "../../logger";
+
+const logger = LibLogger.get('operations', 'wrappers', 'findOne');
+
+/**
+ * Creates a wrapped findOne() 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 findOne() method
+ *
+ * @example
+ * ```typescript
+ * const findOne = createFindOneWrapper(
+ *   coordinate,
+ *   async (finder, params, locations) => {
+ *     return await database.executeFinderOne(finder, params, locations);
+ *   }
+ * );
+ * ```
+ */
+export function createFindOneWrapper<
+  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: FindOneMethod<V, S, L1, L2, L3, L4, L5>,
+  options: WrapperOptions = {}
+): FindOneMethod<V, S, L1, L2, L3, L4, L5> {
+  
+  const operationName = options.operationName || 'findOne';
+  
+  return async (
+    finder: string,
+    params?: OperationParams,
+    locations?: LocKeyArray<L1, L2, L3, L4, L5> | []
+  ): Promise<V | null> => {
+    
+    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}] Result for finder "${finder}":`, 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: [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 }
+      );
+    }
+  };
+}
+