@fjell/core 4.4.72 → 4.4.74

package/dist/validation/index.js

@@ -1,592 +0,0 @@
-// src/logger.ts
-import Logging from "@fjell/logging";
-var LibLogger = Logging.getLogger("@fjell/core");
-var logger_default = LibLogger;
-
-// src/validation/LocationValidator.ts
-var logger = logger_default.get("validation", "LocationValidator");
-var validateLocations = (locations, coordinate, operation) => {
-  if (!locations || locations.length === 0) {
-    return;
-  }
-  const keyTypeArray = coordinate.kta;
-  const expectedLocationTypes = keyTypeArray.slice(1);
-  const actualLocationTypes = locations.map((loc) => loc.kt);
-  logger.debug(`Validating locations for ${operation}`, {
-    expected: expectedLocationTypes,
-    actual: actualLocationTypes,
-    coordinate: keyTypeArray
-  });
-  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(", ")}])`
-    );
-  }
-  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 });
-};
-var isValidLocations = (locations, coordinate, operation) => {
-  try {
-    validateLocations(locations, coordinate, operation);
-    return { valid: true };
-  } catch (error) {
-    return {
-      valid: false,
-      error: error instanceof Error ? error.message : String(error)
-    };
-  }
-};
-
-// src/key/KUtils.ts
-var logger2 = logger_default.get("KUtils");
-var isComKey = (key) => {
-  logger2.trace("isComKey", { key });
-  return key !== void 0 && (key.pk !== void 0 && key.kt !== void 0) && (key.loc !== void 0 && Array.isArray(key.loc));
-};
-var isPriKey = (key) => {
-  logger2.trace("isPriKey", { key });
-  return key !== void 0 && (key.pk !== void 0 && key.kt !== void 0) && key.loc === void 0;
-};
-var toKeyTypeArray = (ik) => {
-  logger2.trace("toKeyTypeArray", { ik });
-  if (isComKey(ik)) {
-    const ck = ik;
-    return [ck.kt, ...ck.loc.map((l) => l.kt)];
-  } else {
-    return [ik.kt];
-  }
-};
-
-// src/validation/KeyValidator.ts
-var logger3 = logger_default.get("validation", "KeyValidator");
-var validateLocationKeyOrder = (key, coordinate, operation) => {
-  const keyTypeArray = coordinate.kta;
-  const expectedLocationTypes = keyTypeArray.slice(1);
-  const actualLocationTypes = key.loc.map((loc) => loc.kt);
-  if (expectedLocationTypes.length !== actualLocationTypes.length) {
-    logger3.error("Location key array length mismatch", {
-      expected: expectedLocationTypes.length,
-      actual: actualLocationTypes.length,
-      key,
-      coordinate,
-      operation
-    });
-    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.
-
-Expected ${expectedLocationTypes.length} location keys but received ${actualLocationTypes.length}.
-
-Expected location key order for '${keyTypeArray[0]}':
-${expectedOrder}
-
-Received location key order:
-${actualOrder}`
-    );
-  }
-  for (let i = 0; i < expectedLocationTypes.length; i++) {
-    if (expectedLocationTypes[i] !== actualLocationTypes[i]) {
-      logger3.error("Location key array order mismatch", {
-        position: i,
-        expected: expectedLocationTypes[i],
-        actual: actualLocationTypes[i],
-        key,
-        coordinate,
-        operation
-      });
-      const expectedOrder = expectedLocationTypes.map(
-        (kt, i2) => `  [${i2}] { kt: '${kt}', lk: <value> }`
-      ).join("\n");
-      const actualOrder = key.loc.map(
-        (loc, i2) => `  [${i2}] { kt: '${loc.kt}', lk: ${JSON.stringify(loc.lk)} }`
-      ).join("\n");
-      throw new Error(
-        `Location key array order mismatch for ${operation} operation.
-
-At position ${i}, expected key type "${expectedLocationTypes[i]}" but received "${actualLocationTypes[i]}".
-
-Expected location key order for '${keyTypeArray[0]}':
-${expectedOrder}
-
-Received location key order:
-${actualOrder}
-
-Tip: Location keys must be ordered according to the hierarchy: [${expectedLocationTypes.join(", ")}]`
-      );
-    }
-  }
-};
-var validateKey = (key, coordinate, operation) => {
-  logger3.debug(`Validating key for ${operation}`, { key, coordinate: coordinate.kta });
-  if (!key || key === null) {
-    throw new Error(
-      `Invalid key structure for ${operation} operation.
-
-The provided key is null or undefined.
-
-Valid key formats:
-  PriKey: { kt: string, pk: string|number }
-  ComKey: { kt: string, pk: string|number, loc: Array<{ kt: string, lk: string|number }> }`
-    );
-  }
-  const isCompositeLibrary = coordinate.kta.length > 1;
-  const keyIsComposite = isComKey(key);
-  const keyIsPrimary = isPriKey(key);
-  if (isCompositeLibrary && !keyIsComposite) {
-    logger3.error(`Composite library received primary key in ${operation}`, { key, coordinate });
-    const keyTypeArray = coordinate.kta;
-    throw new Error(
-      `Invalid key type for ${operation} operation.
-
-This is a composite item library. You must provide a ComKey with location keys.
-
-Expected: ComKey with format:
-  {
-    kt: '${keyTypeArray[0]}',
-    pk: string|number,
-    loc: [
-` + keyTypeArray.slice(1).map((kt) => `      { kt: '${kt}', lk: string|number }`).join(",\n") + `
-    ]
-  }
-
-Received: PriKey with format:
-  ${JSON.stringify(key, null, 2)}
-
-Example correct usage:
-  library.operations.${operation}({
-    kt: '${keyTypeArray[0]}',
-    pk: 'item-id',
-    loc: [${keyTypeArray.slice(1).map((kt) => `{ kt: '${kt}', lk: 'parent-id' }`).join(", ")}]
-  })`
-    );
-  }
-  if (!isCompositeLibrary && keyIsComposite) {
-    logger3.error(`Primary library received composite key in ${operation}`, { key, coordinate });
-    const keyTypeArray = coordinate.kta;
-    throw new Error(
-      `Invalid key type for ${operation} operation.
-
-This is a primary item library. You should provide a PriKey without location keys.
-
-Expected: PriKey with format:
-  { kt: '${keyTypeArray[0]}', pk: string|number }
-
-Received: ComKey with format:
-  ${JSON.stringify(key, null, 2)}
-
-Example correct usage:
-  library.operations.${operation}({ kt: '${keyTypeArray[0]}', pk: 'item-id' })`
-    );
-  }
-  if (!keyIsPrimary && !keyIsComposite) {
-    logger3.error(`Invalid key structure in ${operation}`, { key, coordinate });
-    throw new Error(
-      `Invalid key structure for ${operation} operation.
-
-The provided key does not match PriKey or ComKey format.
-
-Received:
-  ${JSON.stringify(key, null, 2)}
-
-Valid key formats:
-  PriKey: { kt: string, pk: string|number }
-  ComKey: { kt: string, pk: string|number, loc: Array<{ kt: string, lk: string|number }> }`
-    );
-  }
-  const expectedKeyType = coordinate.kta[0];
-  if (key.kt !== expectedKeyType) {
-    logger3.error(`Key type mismatch in ${operation}`, {
-      expected: expectedKeyType,
-      received: key.kt,
-      key,
-      coordinate
-    });
-    throw new Error(
-      `Invalid key type for ${operation} operation.
-
-Expected key type: '${expectedKeyType}'
-Received key type: '${key.kt}'
-
-Example correct usage:
-  library.operations.${operation}({ kt: '${expectedKeyType}', pk: 'item-id', ... })`
-    );
-  }
-  if (keyIsComposite) {
-    const comKey = key;
-    if (comKey.loc.length === 0) {
-      logger3.debug(`Empty loc array detected in ${operation} - will search across all locations`, { key });
-    } else {
-      validateLocationKeyOrder(comKey, coordinate, operation);
-    }
-  }
-  logger3.debug(`Key validation passed for ${operation}`, { key });
-};
-var validatePriKey = (key, expectedType, operation) => {
-  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.
-Expected: '${expectedType}'
-Received: '${key.kt}'`
-    );
-  }
-  if (typeof key.pk === "undefined" || key.pk === null) {
-    throw new Error(`[${operation}] PriKey is missing 'pk' field`);
-  }
-};
-var validateComKey = (key, coordinate, operation) => {
-  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.
-Expected: '${coordinate.kta[0]}'
-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)`);
-  }
-  if (key.loc.length > 0) {
-    validateLocationKeyOrder(key, coordinate, operation);
-  }
-};
-
-// src/validation/ItemValidator.ts
-var logger4 = logger_default.get("validation", "ItemValidator");
-var validatePKForItem = (item, pkType) => {
-  if (!item) {
-    logger4.error("Validating PK, Item is undefined", { item });
-    throw new Error("Validating PK, Item is undefined");
-  }
-  if (!item.key) {
-    logger4.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);
-  if (keyTypeArray[0] !== pkType) {
-    logger4.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;
-};
-var validatePK = (input, pkType) => {
-  logger4.trace("Checking Return Type", { input });
-  if (Array.isArray(input)) {
-    return input.map((item) => validatePKForItem(item, pkType));
-  }
-  return validatePKForItem(input, pkType);
-};
-var validateKeys = (item, keyTypes) => {
-  logger4.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);
-  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 = JSON.stringify(keyTypeArray) === JSON.stringify(keyTypes);
-  if (!match) {
-    logger4.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;
-};
-
-// src/validation/QueryValidator.ts
-var logger5 = logger_default.get("validation", "QueryValidator");
-var validateQuery = (query, operation) => {
-  if (typeof query === "undefined" || query === null) {
-    return;
-  }
-  if (typeof query !== "object") {
-    logger5.error(`Invalid query type for ${operation}`, { query, type: typeof query });
-    throw new Error(
-      `[${operation}] Invalid query parameter.
-
-Expected: object or undefined
-Received: ${typeof query}
-
-Example valid queries:
-  {}
-  { filter: { status: 'active' } }
-  { limit: 10, sort: { field: 'name', order: 'asc' } }`
-    );
-  }
-  if (Array.isArray(query)) {
-    logger5.error(`Query cannot be an array for ${operation}`, { query });
-    throw new Error(
-      `[${operation}] Invalid query parameter.
-
-Query cannot be an array.
-Received: ${JSON.stringify(query)}`
-    );
-  }
-  logger5.debug(`Query validation passed for ${operation}`, { query });
-};
-var validateOperationParams = (params, operation) => {
-  if (typeof params === "undefined") {
-    return;
-  }
-  if (params === null) {
-    logger5.error(`Params cannot be null for ${operation}`, { params });
-    throw new Error(
-      `[${operation}] Invalid operation parameters.
-
-Parameters cannot be null.
-Expected: object or undefined
-Received: null
-
-Example valid parameters:
-  {}
-  { email: 'user@example.com' }
-  { status: 'active', limit: 10 }`
-    );
-  }
-  if (typeof params !== "object") {
-    logger5.error(`Invalid params type for ${operation}`, { params, type: typeof params });
-    throw new Error(
-      `[${operation}] Invalid operation parameters.
-
-Expected: object or undefined
-Received: ${typeof params}
-
-Example valid parameters:
-  {}
-  { email: 'user@example.com' }
-  { status: 'active', limit: 10 }`
-    );
-  }
-  if (Array.isArray(params)) {
-    logger5.error(`Params cannot be an array for ${operation}`, { params });
-    throw new Error(
-      `[${operation}] Invalid operation parameters.
-
-Parameters cannot be an array.
-Received: ${JSON.stringify(params)}`
-    );
-  }
-  for (const [key, value] of Object.entries(params)) {
-    const valueType = typeof value;
-    const isValidType = valueType === "string" || valueType === "number" || valueType === "boolean" || value instanceof Date || Array.isArray(value) && value.every(
-      (v) => typeof v === "string" || typeof v === "number" || typeof v === "boolean" || v instanceof Date
-    );
-    if (!isValidType) {
-      logger5.error(`Invalid param value type for ${operation}`, { key, value, valueType });
-      throw new Error(
-        `[${operation}] Invalid value type for parameter "${key}".
-
-Allowed types: string, number, boolean, Date, or arrays of these types
-Received: ${valueType}
-Value: ${JSON.stringify(value)}`
-      );
-    }
-  }
-  logger5.debug(`Operation params validation passed for ${operation}`, { params });
-};
-var validateFinderName = (finder, operation) => {
-  if (!finder || typeof finder !== "string") {
-    logger5.error(`Invalid finder name for ${operation}`, { finder, type: typeof finder });
-    throw new Error(
-      `[${operation}] Finder name must be a non-empty string.
-
-Received: ${JSON.stringify(finder)}`
-    );
-  }
-  if (finder.trim().length === 0) {
-    logger5.error(`Empty finder name for ${operation}`, { finder });
-    throw new Error(
-      `[${operation}] Finder name cannot be empty or whitespace only.
-
-Received: "${finder}"`
-    );
-  }
-  logger5.debug(`Finder name validation passed for ${operation}`, { finder });
-};
-var validateActionName = (action, operation) => {
-  if (!action || typeof action !== "string") {
-    logger5.error(`Invalid action name for ${operation}`, { action, type: typeof action });
-    throw new Error(
-      `[${operation}] Action name must be a non-empty string.
-
-Received: ${JSON.stringify(action)}`
-    );
-  }
-  if (action.trim().length === 0) {
-    logger5.error(`Empty action name for ${operation}`, { action });
-    throw new Error(
-      `[${operation}] Action name cannot be empty or whitespace only.
-
-Received: "${action}"`
-    );
-  }
-  logger5.debug(`Action name validation passed for ${operation}`, { action });
-};
-var validateFacetName = (facet, operation) => {
-  if (!facet || typeof facet !== "string") {
-    logger5.error(`Invalid facet name for ${operation}`, { facet, type: typeof facet });
-    throw new Error(
-      `[${operation}] Facet name must be a non-empty string.
-
-Received: ${JSON.stringify(facet)}`
-    );
-  }
-  if (facet.trim().length === 0) {
-    logger5.error(`Empty facet name for ${operation}`, { facet });
-    throw new Error(
-      `[${operation}] Facet name cannot be empty or whitespace only.
-
-Received: "${facet}"`
-    );
-  }
-  logger5.debug(`Facet name validation passed for ${operation}`, { facet });
-};
-
-// src/errors/ActionError.ts
-var ActionError = class extends Error {
-  constructor(errorInfo, cause) {
-    super(errorInfo.message);
-    this.errorInfo = errorInfo;
-    this.name = "ActionError";
-    this.cause = cause;
-    if (!this.errorInfo.technical) {
-      this.errorInfo.technical = { timestamp: (/* @__PURE__ */ new Date()).toISOString() };
-    }
-    if (!this.errorInfo.technical.timestamp) {
-      this.errorInfo.technical.timestamp = (/* @__PURE__ */ new Date()).toISOString();
-    }
-  }
-  toJSON() {
-    return this.errorInfo;
-  }
-};
-
-// src/errors/ValidationError.ts
-var ValidationError = class extends ActionError {
-  fieldErrors;
-  constructor(message, validOptions, suggestedAction, conflictingValue, fieldErrors) {
-    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,
-        fieldErrors
-      },
-      technical: {
-        timestamp: (/* @__PURE__ */ new Date()).toISOString()
-      }
-    });
-    this.fieldErrors = fieldErrors;
-    if (fieldErrors) {
-      if (!this.errorInfo.details) this.errorInfo.details = {};
-      this.errorInfo.details.fieldErrors = fieldErrors;
-    }
-  }
-};
-
-// src/validation/schema.ts
-async function validateSchema(data, schema) {
-  if (!schema) {
-    return data;
-  }
-  try {
-    if (schema.parseAsync) {
-      return await schema.parseAsync(data);
-    }
-    const result = schema.safeParse(data);
-    if (result.success) {
-      return result.data;
-    } else {
-      throw result.error;
-    }
-  } catch (error) {
-    if (error && Array.isArray(error.issues)) {
-      const fieldErrors = error.issues.map((issue) => ({
-        path: issue.path,
-        message: issue.message,
-        code: issue.code
-      }));
-      const validationError = new ValidationError(
-        "Schema validation failed",
-        // eslint-disable-next-line no-undefined
-        void 0,
-        // eslint-disable-next-line no-undefined
-        void 0,
-        // eslint-disable-next-line no-undefined
-        void 0,
-        fieldErrors
-      );
-      throw validationError;
-    }
-    if (error instanceof ValidationError) {
-      throw error;
-    }
-    throw new ValidationError(`Validation failed: ${error.message || "Unknown error"}`);
-  }
-}
-export {
-  isValidLocations,
-  validateActionName,
-  validateComKey,
-  validateFacetName,
-  validateFinderName,
-  validateKey,
-  validateKeys,
-  validateLocations,
-  validateOperationParams,
-  validatePK,
-  validatePriKey,
-  validateQuery,
-  validateSchema
-};

package/dist/validation/schema.d.ts

@@ -1,23 +0,0 @@
-import { SchemaValidator } from "./types";
-/**
- * Validates data against a schema validator (Zod, Yup, etc.)
- *
- * Supports both synchronous and asynchronous validation.
- * Transforms validator errors into Fjell ValidationError with FieldError[].
- *
- * @template T - The validated/parsed type
- * @param data - The data to validate
- * @param schema - Optional schema validator
- * @returns Promise resolving to validated/parsed data
- * @throws ValidationError if validation fails
- *
- * @example
- * ```typescript
- * import { validateSchema } from '@fjell/core/validation';
- * import { z } from 'zod';
- *
- * const schema = z.object({ name: z.string() });
- * const validated = await validateSchema({ name: 'Alice' }, schema);
- * ```
- */
-export declare function validateSchema<T>(data: unknown, schema?: SchemaValidator<T>): Promise<T>;

package/dist/validation/types.d.ts

@@ -1,69 +0,0 @@
-/**
- * Shared validation types and options
- */
-/**
- * Options for validation functions
- */
-export interface ValidationOptions {
-    /**
-     * Custom error message prefix
-     */
-    errorPrefix?: string;
-    /**
-     * Whether to allow undefined (treated as empty array for location validation)
-     */
-    allowUndefined?: boolean;
-    /**
-     * Whether to throw errors or return validation results
-     * @default true
-     */
-    throwOnError?: boolean;
-}
-/**
- * Result of a validation operation (for non-throwing mode)
- */
-export interface ValidationResult {
-    /**
-     * Whether validation passed
-     */
-    valid: boolean;
-    /**
-     * Error message if validation failed
-     */
-    error?: string;
-    /**
-     * Detailed validation context
-     */
-    context?: Record<string, unknown>;
-}
-/**
- * Generic interface for schema validators (Zod, Yup, Joi, etc.)
- *
- * This interface enables duck typing - any validator that implements
- * these methods will work with validateSchema.
- *
- * @template T - The validated/parsed type
- */
-export interface SchemaValidator<T> {
-    /**
-     * Synchronous parse method.
-     * Should throw an error if invalid, or return the parsed data.
-     */
-    parse: (data: unknown) => T;
-    /**
-     * Safe parse method that returns a result object instead of throwing.
-     * Used as fallback if parseAsync is not available.
-     */
-    safeParse: (data: unknown) => {
-        success: true;
-        data: T;
-    } | {
-        success: false;
-        error: any;
-    };
-    /**
-     * Optional asynchronous parse method.
-     * Preferred over parse/safeParse if available.
-     */
-    parseAsync?: (data: unknown) => Promise<T>;
-}