@fjell/core 4.4.63 → 4.4.65

package/README.md

@@ -134,10 +134,51 @@ import {
   validateLocations, 
   validateKey, 
   validatePK, 
-  validateKeys 
+  validateKeys,
+  validateSchema,
+  SchemaValidator
 } from '@fjell/core/validation';
 ```
 
+#### Schema Validation (Zod, Yup, etc.)
+
+Universal schema validation that works with any validator matching the `SchemaValidator` interface. Zod is supported out of the box via duck typing:
+
+```typescript
+import { validateSchema } from '@fjell/core/validation';
+import { z } from 'zod';
+
+// Define a Zod schema
+const userSchema = z.object({
+  name: z.string().min(3),
+  age: z.number().min(18),
+  email: z.string().email().optional()
+});
+
+// Validate data before caching, sending to API, or persisting
+const validatedUser = await validateSchema(userData, userSchema);
+
+// Validation throws ValidationError with FieldError[] on failure
+try {
+  await validateSchema({ name: 'Al', age: 10 }, userSchema);
+} catch (error) {
+  if (error instanceof ValidationError) {
+    console.log(error.fieldErrors);
+    // [
+    //   { path: ['name'], message: 'String must contain at least 3 character(s)', code: 'too_small' },
+    //   { path: ['age'], message: 'Number must be greater than or equal to 18', code: 'too_small' }
+    // ]
+  }
+}
+```
+
+**Schema Validation Features:**
+- **Universal**: Works with Zod, Yup, Joi, or any validator matching the interface
+- **Type-Safe**: Full TypeScript support with type inference
+- **Error Transformation**: Automatically converts validator errors to Fjell `ValidationError`
+- **Async Support**: Handles both sync and async validation
+- **Available Everywhere**: Use in cache layers, APIs, persistence, or any system boundary
+
 #### Location Validation
 
 Validates that location key arrays match the expected coordinate hierarchy:

package/dist/index.d.ts

@@ -15,7 +15,7 @@ export * from './validation';
 export * from './errors';
 export * from './operations';
 export * from './event';
-export type { Operations, OperationParams, AffectedKeys, CreateOptions, UpdateOptions } from './operations/Operations';
+export type { Operations, OperationParams, AffectedKeys, CreateOptions, UpdateOptions, PaginationOptions, AllOptions, FindOptions, PaginationMetadata, OperationResult, AllOperationResult, FindOperationResult } from './operations/Operations';
 export { isPriKey as isOperationPriKey, isComKey as isOperationComKey } from './operations/Operations';
 export type { GetMethod, CreateMethod, UpdateMethod, RemoveMethod, UpsertMethod, AllMethod, OneMethod, FindMethod, FindOneMethod, FinderMethod, ActionMethod, ActionOperationMethod, AllActionMethod, AllActionOperationMethod, FacetMethod, FacetOperationMethod, AllFacetMethod, AllFacetOperationMethod, OperationsExtensions } from './operations/methods';
 export * from './operations/wrappers';

package/dist/index.js

@@ -1438,6 +1438,47 @@ var DuplicateError = class extends ActionError {
   }
 };
 
+// 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"}`);
+  }
+}
+
 // src/operations/errorEnhancer.ts
 async function executeWithContext(operation, context) {
   try {
@@ -1826,35 +1867,49 @@ function createOneWrapper(coordinate, implementation, options = {}) {
 
 // src/operations/wrappers/createAllWrapper.ts
 var logger10 = logger_default.get("operations", "wrappers", "all");
-function createAllWrapper(coordinate, implementation, options = {}) {
-  const operationName = options.operationName || "all";
-  return async (query, locations) => {
-    if (options.debug) {
-      logger10.debug(`[${operationName}] Called with:`, { query, locations });
+function createAllWrapper(coordinate, implementation, wrapperOptions = {}) {
+  const operationName = wrapperOptions.operationName || "all";
+  return async (query, locations, allOptions) => {
+    if (wrapperOptions.debug) {
+      logger10.debug(`[${operationName}] Called with:`, { query, locations, allOptions });
     }
-    if (!options.skipValidation) {
+    if (!wrapperOptions.skipValidation) {
       validateQuery(query, operationName);
       validateLocations(locations, coordinate, operationName);
+      if (allOptions && "limit" in allOptions && allOptions.limit != null) {
+        if (!Number.isInteger(allOptions.limit) || allOptions.limit < 1) {
+          throw new Error(`[${operationName}] limit must be a positive integer, got: ${allOptions.limit}`);
+        }
+      }
+      if (allOptions && "offset" in allOptions && allOptions.offset != null) {
+        if (!Number.isInteger(allOptions.offset) || allOptions.offset < 0) {
+          throw new Error(`[${operationName}] offset must be a non-negative integer, got: ${allOptions.offset}`);
+        }
+      }
     }
     const normalizedQuery = query ?? {};
     const normalizedLocations = locations ?? [];
     try {
-      const result = await implementation(normalizedQuery, normalizedLocations);
-      if (options.debug) {
-        logger10.debug(`[${operationName}] Result: ${result.length} items`);
+      const result = await implementation(normalizedQuery, normalizedLocations, allOptions);
+      if (wrapperOptions.debug) {
+        logger10.debug(`[${operationName}] Result: ${result.items.length} items, total: ${result.metadata.total}`);
       }
-      if (!options.skipValidation) {
-        return validatePK(result, coordinate.kta[0]);
+      if (!wrapperOptions.skipValidation) {
+        const validatedItems = validatePK(result.items, coordinate.kta[0]);
+        return {
+          items: validatedItems,
+          metadata: result.metadata
+        };
       }
       return result;
     } catch (error) {
-      if (options.onError) {
+      if (wrapperOptions.onError) {
         const context = {
           operationName,
-          params: [query, locations],
+          params: [query, locations, allOptions],
           coordinate
         };
-        throw options.onError(error, context);
+        throw wrapperOptions.onError(error, context);
       }
       throw new Error(
         `[${operationName}] Operation failed: ${error.message}`,
@@ -2082,11 +2137,38 @@ function createRemoveWrapper(coordinate, implementation, options = {}) {
 
 // src/operations/wrappers/createFindWrapper.ts
 var logger16 = logger_default.get("operations", "wrappers", "find");
+function isFindOperationResult(value) {
+  return value && typeof value === "object" && "items" in value && "metadata" in value && Array.isArray(value.items) && value.metadata && typeof value.metadata === "object" && "total" in value.metadata;
+}
+function applyPagination(items, options) {
+  const total = items.length;
+  const offset = options?.offset ?? 0;
+  const limit = options?.limit;
+  let paginatedItems = items;
+  if (offset > 0) {
+    paginatedItems = paginatedItems.slice(offset);
+  }
+  if (limit != null && limit >= 0) {
+    paginatedItems = paginatedItems.slice(0, limit);
+  }
+  const returned = paginatedItems.length;
+  const hasMore = limit != null && offset + returned < total;
+  return {
+    items: paginatedItems,
+    metadata: {
+      total,
+      returned,
+      offset,
+      limit,
+      hasMore
+    }
+  };
+}
 function createFindWrapper(coordinate, implementation, options = {}) {
   const operationName = options.operationName || "find";
-  return async (finder, params, locations) => {
+  return async (finder, params, locations, findOptions) => {
     if (options.debug) {
-      logger16.debug(`[${operationName}] Called:`, { finder, params, locations });
+      logger16.debug(`[${operationName}] Called:`, { finder, params, locations, findOptions });
     }
     if (!options.skipValidation) {
       validateFinderName(finder, operationName);
@@ -2096,19 +2178,36 @@ function createFindWrapper(coordinate, implementation, options = {}) {
     const normalizedParams = params ?? {};
     const normalizedLocations = locations ?? [];
     try {
-      const result = await implementation(finder, normalizedParams, normalizedLocations);
-      if (options.debug) {
-        logger16.debug(`[${operationName}] Found ${result.length} items for finder "${finder}"`);
-      }
-      if (!options.skipValidation) {
-        return validatePK(result, coordinate.kta[0]);
+      const result = await implementation(finder, normalizedParams, normalizedLocations, findOptions);
+      if (isFindOperationResult(result)) {
+        if (options.debug) {
+          logger16.debug(`[${operationName}] Finder "${finder}" opted-in to pagination, found ${result.items.length} items (total: ${result.metadata.total})`);
+        }
+        if (!options.skipValidation) {
+          const validatedItems = validatePK(result.items, coordinate.kta[0]);
+          return {
+            items: validatedItems,
+            metadata: result.metadata
+          };
+        }
+        return result;
+      } else {
+        if (options.debug) {
+          logger16.debug(`[${operationName}] Finder "${finder}" using legacy signature, applying post-processing pagination`);
+        }
+        let validatedItems;
+        if (!options.skipValidation) {
+          validatedItems = validatePK(result, coordinate.kta[0]);
+        } else {
+          validatedItems = result;
+        }
+        return applyPagination(validatedItems, findOptions);
       }
-      return result;
     } catch (error) {
       if (options.onError) {
         const context = {
           operationName,
-          params: [finder, params, locations],
+          params: [finder, params, locations, findOptions],
           coordinate
         };
         throw options.onError(error, context);
@@ -2440,5 +2539,6 @@ export {
   validateOperationParams,
   validatePK,
   validatePriKey,
-  validateQuery
+  validateQuery,
+  validateSchema
 };

package/dist/operations/Operations.d.ts

@@ -19,6 +19,185 @@ export type CreateOptions<S extends string, L1 extends string = never, L2 extend
     key?: never;
     locations: LocKeyArray<L1, L2, L3, L4, L5>;
 };
+/**
+ * Base options for pagination operations (all() and find()).
+ *
+ * Contains the common pagination parameters shared by both operations.
+ *
+ * @public
+ */
+export interface PaginationOptions {
+    /**
+     * Maximum number of items to return.
+     *
+     * - Must be a positive integer (>= 1)
+     * - When not provided, returns all matching items
+     * - Takes precedence over query.limit when both are specified
+     */
+    limit?: number;
+    /**
+     * Number of items to skip before returning results.
+     *
+     * - Must be a non-negative integer (>= 0)
+     * - Defaults to 0 when not provided
+     * - Takes precedence over query.offset when both are specified
+     */
+    offset?: number;
+}
+/**
+ * Options for the all() operation with pagination support.
+ *
+ * When provided, these options take precedence over any limit/offset
+ * specified in the ItemQuery.
+ *
+ * @public
+ *
+ * @example
+ * ```typescript
+ * // Fetch first 50 items
+ * const result = await operations.all(query, [], { limit: 50, offset: 0 });
+ *
+ * // Fetch next page
+ * const nextPage = await operations.all(query, [], { limit: 50, offset: 50 });
+ * ```
+ */
+export interface AllOptions extends PaginationOptions {
+}
+/**
+ * Options for the find() operation with pagination support.
+ *
+ * When provided, these options take precedence over any limit/offset
+ * passed to finder functions.
+ *
+ * @public
+ *
+ * @example
+ * ```typescript
+ * // Find with pagination
+ * const findResult = await operations.find('byEmail', { email: 'test@example.com' }, [], { limit: 10 });
+ * ```
+ */
+export interface FindOptions extends PaginationOptions {
+}
+/**
+ * Metadata about the pagination state for an all() operation.
+ *
+ * This metadata enables proper pagination UI and logic by providing
+ * the total count of matching items before limit/offset are applied.
+ *
+ * @public
+ */
+export interface PaginationMetadata {
+    /**
+     * Total count of items matching the query BEFORE limit/offset applied.
+     *
+     * This represents the complete result set size and is used to:
+     * - Display "Showing X of Y results"
+     * - Calculate total pages
+     * - Determine if more items exist
+     */
+    total: number;
+    /**
+     * Number of items actually returned in this response.
+     *
+     * This equals `items.length` and is provided for convenience.
+     * When offset + returned < total, more items exist.
+     */
+    returned: number;
+    /**
+     * The limit that was applied, if any.
+     *
+     * - Undefined when no limit was applied
+     * - Reflects the effective limit (options.limit ?? query.limit)
+     */
+    limit?: number;
+    /**
+     * The offset that was applied.
+     *
+     * - 0 when no offset was applied
+     * - Reflects the effective offset (options.offset ?? query.offset ?? 0)
+     */
+    offset: number;
+    /**
+     * Convenience field indicating whether more items exist beyond this page.
+     *
+     * Calculated as: `offset + returned < total`
+     *
+     * Useful for:
+     * - "Load More" buttons
+     * - Infinite scroll implementations
+     * - "Next Page" button state
+     */
+    hasMore: boolean;
+}
+/**
+ * Base result structure for paginated operations.
+ *
+ * This structure provides both the items and metadata needed for
+ * implementing proper pagination in applications.
+ *
+ * @template T - The item type being returned
+ *
+ * @public
+ */
+export interface OperationResult<T> {
+    /**
+     * Array of items matching the query, with limit/offset applied.
+     */
+    items: T[];
+    /**
+     * Pagination metadata for the result set.
+     */
+    metadata: PaginationMetadata;
+}
+/**
+ * Result structure for the all() operation with pagination support.
+ *
+ * This structure provides both the items and metadata needed for
+ * implementing proper pagination in applications.
+ *
+ * @template T - The item type being returned
+ *
+ * @public
+ *
+ * @example
+ * ```typescript
+ * const result = await operations.all(query, [], { limit: 50, offset: 0 });
+ *
+ * console.log(`Showing ${result.metadata.returned} of ${result.metadata.total}`);
+ * // "Showing 50 of 1234"
+ *
+ * if (result.metadata.hasMore) {
+ *   // Load next page
+ * }
+ * ```
+ */
+export interface AllOperationResult<T> extends OperationResult<T> {
+}
+/**
+ * Result structure for the find() operation with pagination support.
+ *
+ * This structure provides both the items and metadata needed for
+ * implementing proper pagination in find operations.
+ *
+ * @template T - The item type being returned
+ *
+ * @public
+ *
+ * @example
+ * ```typescript
+ * const result = await operations.find('byEmail', { email: 'test@example.com' }, [], { limit: 10 });
+ *
+ * console.log(`Found ${result.metadata.returned} of ${result.metadata.total} results`);
+ * // "Found 10 of 25 results"
+ *
+ * if (result.metadata.hasMore) {
+ *   // Load next page
+ * }
+ * ```
+ */
+export interface FindOperationResult<T> extends OperationResult<T> {
+}
 /**
  * Options for update operations across all Fjell libraries.
  *
@@ -97,25 +276,38 @@ export interface UpdateOptions {
  */
 export interface Operations<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> {
     /**
-     * Retrieves all items matching the query.
+     * Retrieves all items matching the query with optional pagination.
      *
-     * @param query - Optional query to filter items
+     * @param query - Optional query to filter items (may include limit/offset for backwards compatibility)
      * @param locations - Optional location hierarchy to scope the query
-     * @returns Array of items matching the query
+     * @param options - Optional pagination options (takes precedence over query limit/offset)
+     * @returns Result containing items and pagination metadata
      *
-     * @example
+     * @example Get all items
      * ```typescript
-     * // Get all users
-     * const users = await operations.all();
+     * const result = await operations.all();
+     * // result.items = all items
+     * // result.metadata.total = items.length
+     * ```
      *
-     * // Get users with filter
-     * const activeUsers = await operations.all({ filter: { status: 'active' } });
+     * @example Get paginated items
+     * ```typescript
+     * const result = await operations.all({}, [], { limit: 50, offset: 0 });
+     * // result.items = first 50 items
+     * // result.metadata.total = total matching count
+     * // result.metadata.hasMore = true if more exist
+     * ```
      *
-     * // Get items in specific location
-     * const comments = await operations.all({}, [{kt: 'post', lk: 'post-123'}]);
+     * @example Get items in specific location with pagination
+     * ```typescript
+     * const result = await operations.all(
+     *   {},
+     *   [{kt: 'post', lk: 'post-123'}],
+     *   { limit: 20, offset: 0 }
+     * );
      * ```
      */
-    all(query?: ItemQuery, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<V[]>;
+    all(query?: ItemQuery, locations?: LocKeyArray<L1, L2, L3, L4, L5> | [], options?: AllOptions): Promise<AllOperationResult<V>>;
     /**
      * Retrieves the first item matching the query.
      *
@@ -209,27 +401,36 @@ export interface Operations<V extends Item<S, L1, L2, L3, L4, L5>, S extends str
      */
     remove(key: PriKey<S> | ComKey<S, L1, L2, L3, L4, L5>): Promise<V | void>;
     /**
-     * Executes a finder method by name.
+     * Executes a finder method by name with optional pagination support.
+     *
+     * Supports hybrid pagination approach:
+     * - If finder returns FindOperationResult<V>, uses it directly (opt-in)
+     * - If finder returns V[], framework applies post-processing pagination
      *
      * @param finder - Name of the finder method
      * @param params - Parameters for the finder
      * @param locations - Optional location hierarchy to scope the query
-     * @returns Array of items found
+     * @param options - Optional pagination options (limit, offset)
+     * @returns Result containing items and pagination metadata
      *
      * @example
      * ```typescript
-     * // Find users by email
-     * const users = await operations.find('byEmail', { email: 'alice@example.com' });
+     * // Find users by email (no pagination)
+     * const result = await operations.find('byEmail', { email: 'alice@example.com' });
+     * const users = result.items;
      *
-     * // Find in specific location
-     * const comments = await operations.find(
+     * // Find with pagination
+     * const result = await operations.find(
      *   'byAuthor',
      *   { author: 'alice' },
-     *   [{kt: 'post', lk: 'post-123'}]
+     *   [{kt: 'post', lk: 'post-123'}],
+     *   { limit: 10, offset: 0 }
      * );
+     * const comments = result.items;
+     * const total = result.metadata.total;
      * ```
      */
-    find(finder: string, params?: OperationParams, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<V[]>;
+    find(finder: string, params?: OperationParams, locations?: LocKeyArray<L1, L2, L3, L4, L5> | [], options?: FindOptions): Promise<FindOperationResult<V>>;
     /**
      * Executes a finder method and returns the first result.
      *

package/dist/operations/contained.d.ts

@@ -1,7 +1,7 @@
 import { Item } from "../items";
 import { ComKey, LocKeyArray } from "../keys";
 import { ItemQuery } from "../item/ItemQuery";
-import { AffectedKeys, OperationParams, Operations } from "./Operations";
+import { AffectedKeys, AllOperationResult, AllOptions, FindOperationResult, FindOptions, OperationParams, Operations } from "./Operations";
 /**
  * Contained Operations interface - specialized for contained (hierarchical) items only.
  *
@@ -47,9 +47,9 @@ import { AffectedKeys, OperationParams, Operations } from "./Operations";
  * ```
  */
 export interface ContainedOperations<V extends Item<S, L1, L2, L3, L4, L5>, S extends string, L1 extends string, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never> extends Omit<Operations<V, S, L1, L2, L3, L4, L5>, 'get' | 'update' | 'remove' | 'upsert' | 'create' | 'action' | 'facet' | 'allAction' | 'allFacet' | 'all' | 'one' | 'find' | 'findOne'> {
-    all(query: ItemQuery | undefined, locations: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<V[]>;
+    all(query: ItemQuery | undefined, locations: LocKeyArray<L1, L2, L3, L4, L5> | [], allOptions?: AllOptions): Promise<AllOperationResult<V>>;
     one(query: ItemQuery | undefined, locations: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<V | null>;
-    find(finder: string, params: OperationParams | undefined, locations: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<V[]>;
+    find(finder: string, params: OperationParams | undefined, locations: LocKeyArray<L1, L2, L3, L4, L5> | [], options?: FindOptions): Promise<FindOperationResult<V>>;
     findOne(finder: string, params: OperationParams | undefined, locations: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<V | null>;
     create(item: Partial<Item<S, L1, L2, L3, L4, L5>>, options?: {
         locations?: LocKeyArray<L1, L2, L3, L4, L5>;

package/dist/operations/methods.d.ts

@@ -1,7 +1,7 @@
 import { Item } from "../items";
 import { ComKey, LocKeyArray, PriKey } from "../keys";
 import { ItemQuery } from "../item/ItemQuery";
-import { AffectedKeys, CreateOptions, OperationParams, UpdateOptions } from "./Operations";
+import { AffectedKeys, AllOperationResult, AllOptions, CreateOptions, FindOperationResult, FindOptions, OperationParams, UpdateOptions } from "./Operations";
 /**
  * Get method signature - retrieves single item by key
  */
@@ -33,10 +33,34 @@ export interface UpsertMethod<V extends Item<S, L1, L2, L3, L4, L5>, S extends s
     (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>, options?: UpdateOptions): Promise<V>;
 }
 /**
- * All method signature - retrieves all items matching query
+ * All method signature - retrieves all items matching query with optional pagination.
+ *
+ * @param query - Optional query to filter items (may include limit/offset for backwards compatibility)
+ * @param locations - Optional location hierarchy to scope the query
+ * @param options - Optional pagination options (takes precedence over query limit/offset)
+ * @returns Result containing items and pagination metadata
+ *
+ * @example Without options (backwards compatible)
+ * ```typescript
+ * const result = await operations.all({ compoundCondition: {...} });
+ * // result.items = [...all matching items...]
+ * // result.metadata.total = result.items.length
+ * ```
+ *
+ * @example With options (new pattern)
+ * ```typescript
+ * const result = await operations.all(
+ *   { compoundCondition: {...} },
+ *   [],
+ *   { limit: 50, offset: 0 }
+ * );
+ * // result.items = [...first 50 items...]
+ * // result.metadata.total = total matching count
+ * // result.metadata.hasMore = true if more items exist
+ * ```
  */
 export interface AllMethod<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> {
-    (query?: ItemQuery, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<V[]>;
+    (query?: ItemQuery, locations?: LocKeyArray<L1, L2, L3, L4, L5> | [], options?: AllOptions): Promise<AllOperationResult<V>>;
 }
 /**
  * One method signature - retrieves first item matching query
@@ -45,10 +69,29 @@ export interface OneMethod<V extends Item<S, L1, L2, L3, L4, L5>, S extends stri
     (query?: ItemQuery, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<V | null>;
 }
 /**
- * Find method signature - finds multiple items using finder
+ * Find method signature - finds multiple items using finder with optional pagination.
+ *
+ * Supports hybrid approach:
+ * - If finder returns FindOperationResult<V>, uses it directly (opt-in)
+ * - If finder returns V[], framework applies post-processing pagination
+ *
+ * @param finder - Name of the finder method
+ * @param params - Parameters for the finder
+ * @param locations - Optional location hierarchy to scope the query
+ * @param options - Optional pagination options (limit, offset)
+ * @returns Result containing items and pagination metadata
+ *
+ * @example
+ * ```typescript
+ * // Without pagination (returns all results)
+ * const result = await operations.find('byEmail', { email: 'test@example.com' });
+ *
+ * // With pagination
+ * const result = await operations.find('byEmail', { email: 'test@example.com' }, [], { limit: 10, offset: 0 });
+ * ```
  */
 export interface FindMethod<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> {
-    (finder: string, params: OperationParams, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<V[]>;
+    (finder: string, params: OperationParams, locations?: LocKeyArray<L1, L2, L3, L4, L5> | [], options?: FindOptions): Promise<FindOperationResult<V>>;
 }
 /**
  * FindOne method signature - finds single item using finder
@@ -57,17 +100,44 @@ export interface FindOneMethod<V extends Item<S, L1, L2, L3, L4, L5>, S extends
     (finder: string, params: OperationParams, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<V | null>;
 }
 /**
- * Finder method signature - finds multiple items
+ * Finder method signature - finds multiple items.
  *
- * @example
+ * Supports hybrid approach for pagination:
+ * - **Legacy signature**: Return `Promise<V[]>` - framework applies post-processing pagination
+ * - **Opt-in signature**: Return `Promise<FindOperationResult<V>>` - finder handles pagination at source
+ *
+ * @example Legacy finder (framework handles pagination)
  * ```typescript
  * const byEmailFinder: FinderMethod<User, 'user'> = async (params) => {
  *   return await database.findUsers({ email: params.email });
  * };
  * ```
+ *
+ * @example Opt-in finder (finder handles pagination)
+ * ```typescript
+ * const byEmailFinder: FinderMethod<User, 'user'> = async (params, locations, options) => {
+ *   const query = buildQuery({ email: params.email });
+ *   const total = await database.count(query);
+ *
+ *   if (options?.offset) query.offset(options.offset);
+ *   if (options?.limit) query.limit(options.limit);
+ *
+ *   const items = await database.find(query);
+ *   return {
+ *     items,
+ *     metadata: {
+ *       total,
+ *       returned: items.length,
+ *       offset: options?.offset ?? 0,
+ *       limit: options?.limit,
+ *       hasMore: (options?.offset ?? 0) + items.length < total
+ *     }
+ *   };
+ * };
+ * ```
  */
 export interface FinderMethod<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> {
-    (params: OperationParams, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<V[]>;
+    (params: OperationParams, locations?: LocKeyArray<L1, L2, L3, L4, L5> | [], options?: FindOptions): Promise<V[] | FindOperationResult<V>>;
 }
 /**
  * Action operation method signature - executes action on specific item by key

package/dist/operations/primary.d.ts

@@ -1,7 +1,7 @@
 import { Item } from "../items";
 import { PriKey } from "../keys";
 import { ItemQuery } from "../item/ItemQuery";
-import { AffectedKeys, OperationParams, Operations } from "./Operations";
+import { AffectedKeys, AllOperationResult, AllOptions, FindOperationResult, FindOptions, OperationParams, Operations } from "./Operations";
 /**
  * Primary Operations interface - specialized for primary (top-level) items only.
  *
@@ -39,9 +39,9 @@ import { AffectedKeys, OperationParams, Operations } from "./Operations";
  * ```
  */
 export interface PrimaryOperations<V extends Item<S>, S extends string> extends Omit<Operations<V, S>, 'all' | 'one' | 'create' | 'get' | 'update' | 'upsert' | 'remove' | 'find' | 'findOne' | 'action' | 'allAction' | 'facet' | 'allFacet'> {
-    all(query?: ItemQuery): Promise<V[]>;
+    all(query?: ItemQuery, locations?: [], allOptions?: AllOptions): Promise<AllOperationResult<V>>;
     one(query?: ItemQuery): Promise<V | null>;
-    find(finder: string, params?: OperationParams): Promise<V[]>;
+    find(finder: string, params?: OperationParams, locations?: [], options?: FindOptions): Promise<FindOperationResult<V>>;
     findOne(finder: string, params?: OperationParams): Promise<V | null>;
     create(item: Partial<Item<S>>, options?: {
         key?: PriKey<S>;

package/dist/operations/wrappers/createAllWrapper.d.ts

@@ -19,10 +19,10 @@ import type { WrapperOptions } from "./types";
  * ```typescript
  * const all = createAllWrapper(
  *   coordinate,
- *   async (query, locations) => {
- *     return await database.findAll(query, locations);
+ *   async (query, locations, options) => {
+ *     return await database.findAll(query, locations, options);
  *   }
  * );
  * ```
  */
-export declare 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>;
+export declare 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>, wrapperOptions?: WrapperOptions): AllMethod<V, S, L1, L2, L3, L4, L5>;

package/dist/operations/wrappers/createFindWrapper.d.ts

@@ -1,26 +1,32 @@
 /**
  * Wrapper for find() operation
  *
- * Provides automatic validation for find() operation parameters.
+ * Provides automatic validation for find() operation parameters and supports
+ * hybrid pagination approach:
+ * - If finder returns FindOperationResult<V>, uses it directly (opt-in)
+ * - If finder returns V[], applies post-processing pagination
  */
 import type { Item } from "../../items";
 import type { Coordinate } from "../../Coordinate";
 import type { FindMethod } from "../methods";
 import type { WrapperOptions } from "./types";
 /**
- * Creates a wrapped find() method with automatic parameter validation.
+ * Creates a wrapped find() method with automatic parameter validation and hybrid pagination support.
  *
  * @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
+ * @returns A fully validated find() method that returns FindOperationResult<V>
  *
  * @example
  * ```typescript
  * const find = createFindWrapper(
  *   coordinate,
- *   async (finder, params, locations) => {
- *     return await database.executeFinder(finder, params, locations);
+ *   async (finder, params, locations, findOptions) => {
+ *     const finderMethod = finders[finder];
+ *     const result = await finderMethod(params, locations, findOptions);
+ *     // Framework handles hybrid detection and post-processing if needed
+ *     return result;
  *   }
  * );
  * ```

package/dist/validation/index.d.ts

@@ -7,9 +7,11 @@
  * - Items (Item key type validation)
  * - Queries (ItemQuery validation)
  * - Operation parameters (OperationParams validation)
+ * - Schema validation (Zod, Yup, etc.)
  */
-export type { ValidationOptions, ValidationResult } from './types';
+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';

package/dist/validation/index.js

@@ -485,6 +485,96 @@ 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,
@@ -497,5 +587,6 @@ export {
   validateOperationParams,
   validatePK,
   validatePriKey,
-  validateQuery
+  validateQuery,
+  validateSchema
 };

package/dist/validation/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/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

@@ -36,3 +36,34 @@ export interface ValidationResult {
      */
     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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fjell/core",
   "description": "Core Item and Key Framework for Fjell",
-  "version": "4.4.63",
+  "version": "4.4.65",
   "keywords": [
     "core",
     "fjell"
@@ -41,14 +41,14 @@
     "docs:test": "cd docs && npm run test"
   },
   "dependencies": {
-    "@fjell/logging": "^4.4.58",
+    "@fjell/logging": "^4.4.59",
     "deepmerge": "^4.3.1",
     "luxon": "^3.7.2"
   },
   "devDependencies": {
     "@eslint/eslintrc": "^3.3.1",
     "@eslint/js": "^9.39.1",
-    "@fjell/common-config": "^1.1.30",
+    "@fjell/common-config": "^1.1.31",
     "@swc/core": "^1.15.2",
     "@tsconfig/recommended": "^1.0.13",
     "@types/luxon": "^3.7.1",