@fjell/core 4.4.63 → 4.4.64

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, AllOptions, PaginationMetadata, AllOperationResult } 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

@@ -1826,35 +1826,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}`,

package/dist/operations/Operations.d.ts

@@ -19,6 +19,124 @@ export type CreateOptions<S extends string, L1 extends string = never, L2 extend
     key?: never;
     locations: LocKeyArray<L1, L2, L3, L4, L5>;
 };
+/**
+ * Options for the all() operation to control pagination.
+ *
+ * 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 {
+    /**
+     * 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;
+}
+/**
+ * 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;
+}
+/**
+ * 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> {
+    /**
+     * Array of items matching the query, with limit/offset applied.
+     */
+    items: T[];
+    /**
+     * Pagination metadata for the result set.
+     */
+    metadata: PaginationMetadata;
+}
 /**
  * Options for update operations across all Fjell libraries.
  *
@@ -97,25 +215,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.
      *

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, OperationParams, Operations } from "./Operations";
 /**
  * Contained Operations interface - specialized for contained (hierarchical) items only.
  *
@@ -47,7 +47,7 @@ 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[]>;
     findOne(finder: string, params: OperationParams | undefined, locations: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<V | null>;

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, 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

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, OperationParams, Operations } from "./Operations";
 /**
  * Primary Operations interface - specialized for primary (top-level) items only.
  *
@@ -39,7 +39,7 @@ 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[]>;
     findOne(finder: string, params?: OperationParams): Promise<V | null>;

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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fjell/core",
   "description": "Core Item and Key Framework for Fjell",
-  "version": "4.4.63",
+  "version": "4.4.64",
   "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",