@fjell/validation 4.4.0

package/LICENSE

@@ -0,0 +1,203 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2025 Fjell Project
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+

package/README.md

@@ -0,0 +1,24 @@
+# @fjell/validation
+
+Validation logic for Fjell items and keys. This package contains validators that can be used on both client and server side.
+
+## Installation
+
+```bash
+npm install @fjell/validation
+```
+
+## Usage
+
+```typescript
+import { ItemValidator, KeyValidator } from '@fjell/validation';
+import { PriKey } from '@fjell/types';
+
+const key: PriKey<'user'> = { kt: 'user', pk: '123' };
+
+// Validate a key
+if (KeyValidator.isPriKey(key)) {
+  console.log('Valid primary key');
+}
+```
+

package/dist/ItemValidator.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Item validation
+ *
+ * Validates that Item objects have correct key types and structures.
+ */
+import type { Item } from "@fjell/types";
+import type { AllItemTypeArrays } from "@fjell/types";
+/**
+ * Validates that an item or array of items have the correct primary key type
+ *
+ * @param input - The item or array of items to validate
+ * @param pkType - The expected primary key type
+ * @returns The validated item(s)
+ * @throws Error if any item is invalid or has wrong key type
+ *
+ * @example
+ * ```typescript
+ * // Validate single item
+ * const item = validatePK(fetchedItem, 'product');
+ *
+ * // Validate array of items
+ * const items = validatePK(fetchedItems, 'product');
+ * ```
+ */
+export declare 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>[];
+/**
+ * Validates that an item's key matches the expected key type array
+ *
+ * This is used to validate composite items where the key structure must match
+ * the complete hierarchy (e.g., [product, store, region])
+ *
+ * @param item - The item to validate
+ * @param keyTypes - The expected key type array
+ * @returns The validated item
+ * @throws Error if item is invalid or key types don't match
+ *
+ * @example
+ * ```typescript
+ * // Validate item has correct key structure
+ * const item = validateKeys(fetchedItem, ['product', 'store']);
+ * ```
+ */
+export declare 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>;

package/dist/KeyValidator.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Key validation (PriKey, ComKey)
+ *
+ * Validates key structures and ensures keys match the expected library type.
+ */
+import type { ComKey, PriKey } from "@fjell/types";
+import type { Coordinate } from "@fjell/types";
+/**
+ * Validates that a key is valid and matches the expected library type.
+ *
+ * This function performs comprehensive validation:
+ * 1. Validates key type (PriKey vs ComKey) matches library type (primary vs composite)
+ * 2. For composite keys, validates location key array order matches hierarchy
+ * 3. Validates key structure is correct
+ *
+ * @param key - The key to validate
+ * @param coordinate - The coordinate defining the library's key type hierarchy
+ * @param operation - The operation name (for error messages)
+ * @throws Error if key type doesn't match library type or location key array order is incorrect
+ *
+ * @example
+ * ```typescript
+ * // Validate a PriKey for a primary library
+ * validateKey(
+ *   { kt: 'product', pk: '123' },
+ *   coordinate,
+ *   'get'
+ * );
+ *
+ * // Validate a ComKey for a composite library
+ * validateKey(
+ *   { kt: 'product', pk: '123', loc: [{ kt: 'store', lk: '456' }] },
+ *   coordinate,
+ *   'get'
+ * );
+ * ```
+ */
+export declare const validateKey: <S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never>(key: PriKey<S> | ComKey<S, L1, L2, L3, L4, L5>, coordinate: Coordinate<S, L1, L2, L3, L4, L5>, operation: string) => void;
+/**
+ * Validates a PriKey structure
+ *
+ * @param key - The primary key to validate
+ * @param expectedType - The expected key type
+ * @param operation - The operation name (for error messages)
+ * @throws Error if key is invalid
+ */
+export declare const validatePriKey: <S extends string>(key: PriKey<S>, expectedType: S, operation: string) => void;
+/**
+ * Validates a ComKey structure
+ *
+ * @param key - The composite key to validate
+ * @param coordinate - The coordinate defining the expected hierarchy
+ * @param operation - The operation name (for error messages)
+ * @throws Error if key is invalid
+ */
+export declare const validateComKey: <S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never>(key: ComKey<S, L1, L2, L3, L4, L5>, coordinate: Coordinate<S, L1, L2, L3, L4, L5>, operation: string) => void;

package/dist/LocationValidator.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Location array validation
+ *
+ * Validates that LocKeyArray parameters match the expected Coordinate hierarchy.
+ */
+import type { LocKeyArray } from "@fjell/types";
+import type { Coordinate } from "@fjell/types";
+import type { ValidationResult } from "./types";
+/**
+ * Validates that a standalone LocKeyArray parameter matches the expected hierarchy
+ * defined by the coordinate's key type array (kta).
+ *
+ * This is used to validate the `locations` parameter passed to operations like
+ * all(), find(), create(), etc.
+ *
+ * @param locations - The location key array to validate
+ * @param coordinate - The coordinate defining the library's key type hierarchy
+ * @param operation - The operation name (for error messages)
+ * @throws Error if location key array order is incorrect
+ *
+ * @example
+ * ```typescript
+ * validateLocations(
+ *   [{kt: 'store', lk: '123'}],
+ *   coordinate,
+ *   'find'
+ * );
+ * ```
+ */
+export declare const validateLocations: <S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never>(locations: LocKeyArray<L1, L2, L3, L4, L5> | [] | undefined, coordinate: Coordinate<S, L1, L2, L3, L4, L5>, operation: string) => void;
+/**
+ * Non-throwing version of validateLocations that returns a ValidationResult
+ *
+ * @param locations - The location key array to validate
+ * @param coordinate - The coordinate defining the library's key type hierarchy
+ * @param operation - The operation name (for error messages)
+ * @returns ValidationResult with valid flag and optional error message
+ */
+export declare const isValidLocations: <S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never>(locations: LocKeyArray<L1, L2, L3, L4, L5> | [] | undefined, coordinate: Coordinate<S, L1, L2, L3, L4, L5>, operation: string) => ValidationResult;

package/dist/QueryValidator.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Query and parameter validation
+ *
+ * Validates ItemQuery and OperationParams structures.
+ */
+import type { ItemQuery, OperationParams } from "@fjell/types";
+/**
+ * Validates that a query parameter is a valid ItemQuery object.
+ *
+ * @param query - The query to validate
+ * @param operation - The operation name (for error messages)
+ * @throws Error if query is invalid
+ *
+ * @example
+ * ```typescript
+ * validateQuery({ filter: { status: 'active' } }, 'one');
+ * ```
+ */
+export declare const validateQuery: (query: ItemQuery | undefined, operation: string) => void;
+/**
+ * Validates that operation parameters are valid.
+ *
+ * @param params - The parameters to validate
+ * @param operation - The operation name (for error messages)
+ * @throws Error if parameters are invalid
+ *
+ * @example
+ * ```typescript
+ * validateOperationParams({ email: 'test@example.com' }, 'find');
+ * ```
+ */
+export declare const validateOperationParams: (params: OperationParams | undefined, operation: string) => void;
+/**
+ * Validates that a finder name is valid.
+ *
+ * @param finder - The finder name to validate
+ * @param operation - The operation name (for error messages)
+ * @throws Error if finder name is invalid
+ */
+export declare const validateFinderName: (finder: string | undefined, operation: string) => void;
+/**
+ * Validates that an action name is valid.
+ *
+ * @param action - The action name to validate
+ * @param operation - The operation name (for error messages)
+ * @throws Error if action name is invalid
+ */
+export declare const validateActionName: (action: string | undefined, operation: string) => void;
+/**
+ * Validates that a facet name is valid.
+ *
+ * @param facet - The facet name to validate
+ * @param operation - The operation name (for error messages)
+ * @throws Error if facet name is invalid
+ */
+export declare const validateFacetName: (facet: string | undefined, operation: string) => void;

package/dist/errors.d.ts

@@ -0,0 +1,9 @@
+export interface FieldError {
+    path: (string | number)[];
+    message: string;
+    code: string;
+}
+export declare class ValidationError extends Error {
+    fieldErrors?: FieldError[];
+    constructor(message: string, fieldErrors?: FieldError[]);
+}

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Validation module
+ *
+ * Provides centralized validation functions for:
+ * - Location arrays (LocKeyArray validation against Coordinate hierarchy)
+ * - Keys (PriKey, ComKey validation)
+ * - Items (Item key type validation)
+ * - Queries (ItemQuery validation)
+ * - Operation parameters (OperationParams validation)
+ * - Schema validation (Zod, Yup, etc.)
+ */
+export type { ValidationOptions, ValidationResult, SchemaValidator } from './types';
+export { validateLocations, isValidLocations } from './LocationValidator';
+export { validateKey, validatePriKey, validateComKey } from './KeyValidator';
+export { validatePK, validateKeys } from './ItemValidator';
+export { validateQuery, validateOperationParams, validateFinderName, validateActionName, validateFacetName } from './QueryValidator';
+export { validateSchema } from './schema';
+export { ValidationError } from './errors';
+export type { FieldError } from './errors';

package/dist/index.js

@@ -0,0 +1,607 @@
+// src/LocationValidator.ts
+import Logging from "@fjell/logging";
+var logger = Logging.getLogger("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/utils.ts
+var isComKey = (key) => {
+  return typeof key !== "undefined" && (typeof key.pk !== "undefined" && typeof key.kt !== "undefined") && (typeof key.loc !== "undefined" && Array.isArray(key.loc));
+};
+var isPriKey = (key) => {
+  return typeof key !== "undefined" && (typeof key.pk !== "undefined" && typeof key.kt !== "undefined") && typeof key.loc === "undefined";
+};
+var toKeyTypeArray = (ik) => {
+  if (isComKey(ik)) {
+    const ck = ik;
+    return [ck.kt, ...ck.loc.map((l) => l.kt)];
+  } else {
+    return [ik.kt];
+  }
+};
+
+// src/KeyValidator.ts
+import Logging2 from "@fjell/logging";
+var logger2 = Logging2.getLogger("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) {
+    logger2.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]) {
+      logger2.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) => {
+  logger2.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) {
+    logger2.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) {
+    logger2.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) {
+    logger2.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) {
+    logger2.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) {
+      logger2.debug(`Empty loc array detected in ${operation} - will search across all locations`, { key });
+    } else {
+      validateLocationKeyOrder(comKey, coordinate, operation);
+    }
+  }
+  logger2.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/ItemValidator.ts
+import Logging3 from "@fjell/logging";
+var logger3 = Logging3.getLogger("validation.ItemValidator");
+var validatePKForItem = (item, pkType) => {
+  if (!item) {
+    logger3.error("Item validation failed - item is undefined", {
+      component: "core",
+      operation: "validatePK",
+      expectedType: pkType,
+      item,
+      suggestion: "Ensure the operation returns a valid item object, not undefined/null"
+    });
+    throw new Error(
+      `Item validation failed: item is undefined. Expected item of type '${pkType}'. This usually indicates a database operation returned null/undefined unexpectedly.`
+    );
+  }
+  if (!item.key) {
+    logger3.error("Item validation failed - item missing key", {
+      component: "core",
+      operation: "validatePK",
+      expectedType: pkType,
+      item,
+      suggestion: "Ensure the item has a valid key property with kt and pk fields"
+    });
+    throw new Error(
+      `Item validation failed: item does not have a key property. Expected key with type '${pkType}'. Item: ${JSON.stringify(item)}. This indicates a database processing error.`
+    );
+  }
+  const keyTypeArray = toKeyTypeArray(item.key);
+  if (keyTypeArray[0] !== pkType) {
+    logger3.error("Key type mismatch during validation", {
+      component: "core",
+      operation: "validatePK",
+      expectedType: pkType,
+      actualType: keyTypeArray[0],
+      keyTypeArray,
+      itemKey: item.key,
+      suggestion: `Ensure the item key has kt: '${pkType}', not '${keyTypeArray[0]}'`
+    });
+    throw new Error(
+      `Item has incorrect primary key type. Expected '${pkType}', got '${keyTypeArray[0]}'. Key: ${JSON.stringify(item.key)}. This indicates a data model mismatch.`
+    );
+  }
+  return item;
+};
+var validatePK = (input, pkType) => {
+  logger3.trace("Checking Return Type", { input });
+  if (Array.isArray(input)) {
+    return input.map((item) => validatePKForItem(item, pkType));
+  }
+  return validatePKForItem(input, pkType);
+};
+var validateKeys = (item, keyTypes) => {
+  logger3.trace("Checking Return Type", { item });
+  if (!item) {
+    logger3.error("Key validation failed - item is undefined", {
+      component: "core",
+      operation: "validateKeys",
+      expectedKeyTypes: keyTypes,
+      suggestion: "Ensure the operation returns a valid item object, not undefined/null"
+    });
+    throw new Error(
+      `Key validation failed: item is undefined. Expected item with key types [${keyTypes.join(", ")}]. This usually indicates a database operation returned null/undefined unexpectedly.`
+    );
+  }
+  if (!item.key) {
+    logger3.error("Key validation failed - item missing key", {
+      component: "core",
+      operation: "validateKeys",
+      expectedKeyTypes: keyTypes,
+      item: JSON.stringify(item),
+      suggestion: "Ensure the item has a valid key property"
+    });
+    throw new Error(
+      `Key validation failed: item does not have a key property. Expected key with types [${keyTypes.join(", ")}]. Item: ${JSON.stringify(item)}. This indicates a database processing error.`
+    );
+  }
+  const keyTypeArray = toKeyTypeArray(item.key);
+  if (keyTypeArray.length !== keyTypes.length) {
+    logger3.error("Key hierarchy depth mismatch", {
+      component: "core",
+      operation: "validateKeys",
+      expectedKeyTypes: keyTypes,
+      expectedDepth: keyTypes.length,
+      actualKeyTypes: keyTypeArray,
+      actualDepth: keyTypeArray.length,
+      itemKey: item.key,
+      suggestion: `Check coordinate definition. Expected hierarchy depth of ${keyTypes.length}, got ${keyTypeArray.length}`
+    });
+    throw new Error(
+      `Item has incorrect key hierarchy depth. Expected ${keyTypes.length} levels [${keyTypes.join(" > ")}], but got ${keyTypeArray.length} levels [${keyTypeArray.join(" > ")}]. Key: ${JSON.stringify(item.key)}. This indicates a coordinate/hierarchy mismatch.`
+    );
+  }
+  const match = JSON.stringify(keyTypeArray) === JSON.stringify(keyTypes);
+  if (!match) {
+    logger3.error("Key Type Array Mismatch", {
+      component: "core",
+      operation: "validateKeys",
+      expectedKeyTypes: keyTypes,
+      actualKeyTypes: keyTypeArray,
+      itemKey: item.key,
+      suggestion: `Ensure item key matches expected hierarchy: [${keyTypes.join(" > ")}]`
+    });
+    throw new Error(
+      `Item has incorrect key types. Expected [${keyTypes.join(" > ")}], but got [${keyTypeArray.join(" > ")}]. Key: ${JSON.stringify(item.key)}. This indicates a data model mismatch.`
+    );
+  }
+  return item;
+};
+
+// src/QueryValidator.ts
+import Logging4 from "@fjell/logging";
+var logger4 = Logging4.getLogger("validation.QueryValidator");
+var validateQuery = (query, operation) => {
+  if (typeof query === "undefined" || query === null) {
+    return;
+  }
+  if (typeof query !== "object") {
+    logger4.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)) {
+    logger4.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)}`
+    );
+  }
+  logger4.debug(`Query validation passed for ${operation}`, { query });
+};
+var validateOperationParams = (params, operation) => {
+  if (typeof params === "undefined") {
+    return;
+  }
+  if (params === null) {
+    logger4.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") {
+    logger4.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)) {
+    logger4.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) {
+      logger4.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)}`
+      );
+    }
+  }
+  logger4.debug(`Operation params validation passed for ${operation}`, { params });
+};
+var validateFinderName = (finder, operation) => {
+  if (!finder || typeof finder !== "string") {
+    logger4.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) {
+    logger4.error(`Empty finder name for ${operation}`, { finder });
+    throw new Error(
+      `[${operation}] Finder name cannot be empty or whitespace only.
+
+Received: "${finder}"`
+    );
+  }
+  logger4.debug(`Finder name validation passed for ${operation}`, { finder });
+};
+var validateActionName = (action, operation) => {
+  if (!action || typeof action !== "string") {
+    logger4.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) {
+    logger4.error(`Empty action name for ${operation}`, { action });
+    throw new Error(
+      `[${operation}] Action name cannot be empty or whitespace only.
+
+Received: "${action}"`
+    );
+  }
+  logger4.debug(`Action name validation passed for ${operation}`, { action });
+};
+var validateFacetName = (facet, operation) => {
+  if (!facet || typeof facet !== "string") {
+    logger4.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) {
+    logger4.error(`Empty facet name for ${operation}`, { facet });
+    throw new Error(
+      `[${operation}] Facet name cannot be empty or whitespace only.
+
+Received: "${facet}"`
+    );
+  }
+  logger4.debug(`Facet name validation passed for ${operation}`, { facet });
+};
+
+// src/errors.ts
+var ValidationError = class extends Error {
+  fieldErrors;
+  constructor(message, fieldErrors) {
+    super(message);
+    this.name = "ValidationError";
+    this.fieldErrors = fieldErrors;
+  }
+};
+
+// src/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",
+        fieldErrors
+      );
+      throw validationError;
+    }
+    if (error instanceof ValidationError) {
+      throw error;
+    }
+    throw new ValidationError(`Validation failed: ${error.message || "Unknown error"}`);
+  }
+}
+export {
+  ValidationError,
+  isValidLocations,
+  validateActionName,
+  validateComKey,
+  validateFacetName,
+  validateFinderName,
+  validateKey,
+  validateKeys,
+  validateLocations,
+  validateOperationParams,
+  validatePK,
+  validatePriKey,
+  validateQuery,
+  validateSchema
+};

package/dist/schema.d.ts

@@ -0,0 +1,23 @@
+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/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/types.d.ts

@@ -0,0 +1,69 @@
+/**
+ * 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>;
+}

package/dist/utils.d.ts

@@ -0,0 +1,4 @@
+import { ComKey, PriKey } from "@fjell/types";
+export declare const isComKey: (key: any) => key is ComKey<any, any, any, any, any, any>;
+export declare const isPriKey: (key: any) => key is PriKey<any>;
+export declare const toKeyTypeArray: <S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never>(ik: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>) => string[];

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@fjell/validation",
+  "description": "Validation Logic for Fjell Items and Keys",
+  "version": "4.4.0",
+  "keywords": [
+    "validation",
+    "fjell"
+  ],
+  "license": "Apache-2.0",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "type": "module",
+  "scripts": {
+    "lint": "eslint . --ext .ts --fix",
+    "dev": "concurrently \"tsc --noEmit --watch\" \"node build.js --watch\"",
+    "build": "npm run lint && node build.js",
+    "clean": "rm -rf dist",
+    "test": "npm run lint && vitest run --coverage",
+    "precommit": "npm run clean && npm run lint && npm run build && npm run test",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "dependencies": {
+    "@fjell/logging": "^4.4.65",
+    "@fjell/types": "4.4.4"
+  },
+  "devDependencies": {
+    "@eslint/eslintrc": "^3.3.1",
+    "@eslint/js": "^9.39.1",
+    "@fjell/common-config": "^1.1.36",
+    "@swc/core": "^1.15.2",
+    "@tsconfig/recommended": "^1.0.13",
+    "@types/luxon": "^3.7.1",
+    "@typescript-eslint/eslint-plugin": "^8.46.4",
+    "@typescript-eslint/parser": "^8.46.4",
+    "@vitest/coverage-v8": "4.0.9",
+    "concurrently": "^9.2.1",
+    "esbuild": "0.25.11",
+    "eslint": "^9.38.0",
+    "typescript": "^5.9.3",
+    "vitest": "4.0.9"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/getfjell/validation.git"
+  }
+}
+