@fjell/core 4.4.73 → 4.4.75

package/dist/operations/Operations.d.ts

@@ -1,530 +0,0 @@
-import { Item } from "../items";
-import { ComKey, LocKeyArray, PriKey } from "../keys";
-import { ItemQuery } from "../item/ItemQuery";
-/**
- * Standard operation parameters type
- */
-export type OperationParams = Record<string, string | number | boolean | Date | Array<string | number | boolean | Date>>;
-/**
- * Type for affected keys returned by actions
- */
-export type AffectedKeys = Array<PriKey<any> | ComKey<any, any, any, any, any, any> | LocKeyArray<any, any, any, any, any>>;
-/**
- * Options for create operation
- */
-export type CreateOptions<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>;
-    locations?: never;
-} | {
-    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.
- *
- * These options provide explicit control over update behavior,
- * with safe defaults that prevent accidental data loss.
- *
- * @public
- */
-export interface UpdateOptions {
-    /**
-     * Controls whether the update replaces the entire document/record or merges with existing data.
-     *
-     * **Default: `false` (merge/partial update)**
-     *
-     * When `false` (default):
-     * - Only the specified fields are updated
-     * - All other existing fields are preserved
-     * - Safe for partial updates
-     * - Recommended for most use cases
-     *
-     * When `true`:
-     * - The entire document/record is replaced with the provided data
-     * - Any fields not included in the update payload are DELETED
-     * - Use with extreme caution
-     * - Logs warning before operation (in implementations)
-     *
-     * ⚠️ **WARNING**: Setting `replace: true` can lead to permanent data loss.
-     * Always verify that your update payload contains ALL fields you want to preserve.
-     *
-     * @default false
-     *
-     * @example Merge update (default - safe)
-     * ```typescript
-     * // Existing: { id: '123', name: 'John', email: 'john@example.com', status: 'active' }
-     * await operations.update(
-     *   { kt: 'user', pk: '123' },
-     *   { status: 'inactive' }
-     * );
-     * // Result: { id: '123', name: 'John', email: 'john@example.com', status: 'inactive' }
-     * // ✅ All fields preserved except status
-     * ```
-     *
-     * @example Full replacement (use with caution)
-     * ```typescript
-     * // Existing: { id: '123', name: 'John', email: 'john@example.com', status: 'active' }
-     * await operations.update(
-     *   { kt: 'user', pk: '123' },
-     *   { status: 'inactive' },
-     *   { replace: true }
-     * );
-     * // Result: { status: 'inactive' }
-     * // ❌ name and email are DELETED!
-     * ```
-     */
-    replace?: boolean;
-}
-/**
- * Core Operations interface for Item-based data access.
- * This interface defines the standard contract for all fjell libraries
- * that operate on Items.
- *
- * @template V - The Item type
- * @template S - The primary key type
- * @template L1-L5 - Location key types (optional, for contained items)
- *
- * @example
- * ```typescript
- * // Primary item operations
- * const userOps: Operations<User, 'user'> = ...;
- * const users = await userOps.all();
- *
- * // Contained item operations
- * const commentOps: Operations<Comment, 'comment', 'post'> = ...;
- * const comments = await commentOps.all({}, [{kt: 'post', lk: 'post-123'}]);
- * ```
- */
-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 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 Get all items
-     * ```typescript
-     * const result = await operations.all();
-     * // result.items = all items
-     * // result.metadata.total = items.length
-     * ```
-     *
-     * @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
-     * ```
-     *
-     * @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> | [], options?: AllOptions): Promise<AllOperationResult<V>>;
-    /**
-     * Retrieves the first item matching the query.
-     *
-     * @param query - Optional query to filter items
-     * @param locations - Optional location hierarchy to scope the query
-     * @returns Single item or null if not found
-     */
-    one(query?: ItemQuery, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<V | null>;
-    /**
-     * Creates a new item.
-     *
-     * @param item - Partial item properties for creation
-     * @param options - Optional key or locations for the new item
-     * @returns The created item
-     *
-     * @example
-     * ```typescript
-     * // Create with auto-generated key
-     * const user = await operations.create({ name: 'Alice' });
-     *
-     * // Create with specific key
-     * const user = await operations.create(
-     *   { name: 'Alice' },
-     *   { key: { kt: 'user', pk: 'alice-123' } }
-     * );
-     *
-     * // Create in specific location
-     * const comment = await operations.create(
-     *   { text: 'Great post!' },
-     *   { locations: [{kt: 'post', lk: 'post-123'}] }
-     * );
-     * ```
-     */
-    create(item: Partial<Item<S, L1, L2, L3, L4, L5>>, options?: CreateOptions<S, L1, L2, L3, L4, L5>): Promise<V>;
-    /**
-     * Retrieves a single item by its key.
-     *
-     * @param key - Primary or composite key
-     * @returns The item or null if not found
-     *
-     * @example
-     * ```typescript
-     * // Get by primary key
-     * const user = await operations.get({ kt: 'user', pk: 'user-123' });
-     *
-     * // Get by composite key
-     * const comment = await operations.get({
-     *   kt: 'comment',
-     *   pk: 'comment-456',
-     *   loc: [{kt: 'post', lk: 'post-123'}]
-     * });
-     * ```
-     */
-    get(key: PriKey<S> | ComKey<S, L1, L2, L3, L4, L5>): Promise<V | null>;
-    /**
-     * Updates an existing item.
-     *
-     * @param key - Primary or composite key
-     * @param item - Partial item properties to update
-     * @param options - Optional update options (controls merge vs replace behavior)
-     * @returns The updated item
-     *
-     * @example Merge update (default - safe)
-     * ```typescript
-     * await operations.update(key, { status: 'active' });
-     * // Merges with existing data, preserves other fields
-     * ```
-     *
-     * @example Replace update (dangerous)
-     * ```typescript
-     * await operations.update(key, { status: 'active' }, { replace: true });
-     * // Replaces entire document, deletes unspecified fields
-     * ```
-     */
-    update(key: PriKey<S> | ComKey<S, L1, L2, L3, L4, L5>, item: Partial<Item<S, L1, L2, L3, L4, L5>>, options?: UpdateOptions): Promise<V>;
-    /**
-     * Updates an item if it exists, creates it if it doesn't.
-     *
-     * @param key - Primary or composite key
-     * @param item - Partial item properties
-     * @param locations - Optional locations for creation
-     * @param options - Optional update options (used only if item exists, ignored for creation)
-     * @returns The upserted item
-     */
-    upsert(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>;
-    /**
-     * Removes an item.
-     *
-     * @param key - Primary or composite key
-     * @returns The removed item or void
-     */
-    remove(key: PriKey<S> | ComKey<S, L1, L2, L3, L4, L5>): Promise<V | void>;
-    /**
-     * 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
-     * @param options - Optional pagination options (limit, offset)
-     * @returns Result containing items and pagination metadata
-     *
-     * @example
-     * ```typescript
-     * // Find users by email (no pagination)
-     * const result = await operations.find('byEmail', { email: 'alice@example.com' });
-     * const users = result.items;
-     *
-     * // Find with pagination
-     * const result = await operations.find(
-     *   'byAuthor',
-     *   { author: 'alice' },
-     *   [{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> | [], options?: FindOptions): Promise<FindOperationResult<V>>;
-    /**
-     * Executes a finder method and returns the first result.
-     *
-     * @param finder - Name of the finder method
-     * @param params - Parameters for the finder
-     * @param locations - Optional location hierarchy to scope the query
-     * @returns Single item or null
-     */
-    findOne(finder: string, params?: OperationParams, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<V | null>;
-    /**
-     * Executes an action on a specific item.
-     * Actions are operations that may have side effects or modify the item.
-     *
-     * @param key - Primary or composite key
-     * @param action - Name of the action
-     * @param params - Parameters for the action
-     * @returns Tuple of [updated item, affected keys for cache invalidation]
-     *
-     * @example
-     * ```typescript
-     * const [user, affectedKeys] = await operations.action(
-     *   { kt: 'user', pk: 'user-123' },
-     *   'promote',
-     *   { role: 'admin' }
-     * );
-     * ```
-     */
-    action(key: PriKey<S> | ComKey<S, L1, L2, L3, L4, L5>, action: string, params?: OperationParams): Promise<[V, AffectedKeys]>;
-    /**
-     * Executes an action on all items matching criteria.
-     *
-     * @param action - Name of the action
-     * @param params - Parameters for the action
-     * @param locations - Optional location hierarchy to scope the action
-     * @returns Tuple of [updated items, affected keys for cache invalidation]
-     */
-    allAction(action: string, params?: OperationParams, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<[V[], AffectedKeys]>;
-    /**
-     * Executes a facet query on a specific item.
-     * Facets are read-only computed views of item data.
-     *
-     * @param key - Primary or composite key
-     * @param facet - Name of the facet
-     * @param params - Parameters for the facet
-     * @returns Facet result data
-     *
-     * @example
-     * ```typescript
-     * const stats = await operations.facet(
-     *   { kt: 'user', pk: 'user-123' },
-     *   'statistics',
-     *   { period: 'month' }
-     * );
-     * ```
-     */
-    facet(key: PriKey<S> | ComKey<S, L1, L2, L3, L4, L5>, facet: string, params?: OperationParams): Promise<any>;
-    /**
-     * Executes a facet query on all items matching criteria.
-     * Facets are read-only computed views of item data.
-     *
-     * @param facet - Name of the facet
-     * @param params - Parameters for the facet
-     * @param locations - Optional location hierarchy to scope the query
-     * @returns Facet result data
-     */
-    allFacet(facet: string, params?: OperationParams, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<any>;
-}
-/**
- * Type guard to check if key is a PriKey
- *
- * @param key - Key to check
- * @returns true if key is a PriKey
- *
- * @example
- * ```typescript
- * if (isPriKey(key)) {
- *   // key is PriKey<S>
- *   console.log(key.kt, key.pk);
- * }
- * ```
- */
-export declare function isPriKey<S extends string>(key: PriKey<S> | ComKey<S, any, any, any, any, any>): key is PriKey<S>;
-/**
- * Type guard to check if key is a ComKey
- *
- * @param key - Key to check
- * @returns true if key is a ComKey
- *
- * @example
- * ```typescript
- * if (isComKey(key)) {
- *   // key is ComKey<S, L1, L2, L3, L4, L5>
- *   console.log(key.kt, key.pk, key.loc);
- * }
- * ```
- */
-export declare function isComKey<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>): key is ComKey<S, L1, L2, L3, L4, L5>;

package/dist/operations/contained.d.ts

@@ -1,65 +0,0 @@
-import { Item } from "../items";
-import { ComKey, LocKeyArray } from "../keys";
-import { ItemQuery } from "../item/ItemQuery";
-import { AffectedKeys, AllOperationResult, AllOptions, FindOperationResult, FindOptions, OperationParams, Operations } from "./Operations";
-/**
- * Contained Operations interface - specialized for contained (hierarchical) items only.
- *
- * This interface narrows the generic Operations interface to work exclusively
- * with ComKey and requires locations for collection operations.
- *
- * Contained items exist within a location hierarchy and belong to parent items.
- * Examples: Comments (in Posts), Annotations (in Documents), Tasks (in Projects)
- *
- * Use this for:
- * - Libraries that store contained items
- * - Caches for contained items
- * - API clients for contained endpoints
- * - Any operations that work with hierarchical data
- *
- * @example
- * ```typescript
- * // Define a contained item type
- * interface Comment extends Item<'comment', 'post'> {
- *   text: string;
- *   author: string;
- * }
- *
- * // Create operations for contained items
- * const commentOps: ContainedOperations<Comment, 'comment', 'post'> = createCommentOperations();
- *
- * // Only ComKey allowed - includes location hierarchy
- * await commentOps.get({
- *   kt: 'comment',
- *   pk: '123',
- *   loc: [{ kt: 'post', lk: 'post-1' }]
- * });
- *
- * await commentOps.update(
- *   { kt: 'comment', pk: '123', loc: [{ kt: 'post', lk: 'post-1' }] },
- *   { text: 'Updated comment' }
- * );
- *
- * // Locations required on collection methods
- * await commentOps.all({}, [{ kt: 'post', lk: 'post-1' }]);
- * await commentOps.find('recent', {}, [{ kt: 'post', lk: 'post-1' }]);
- * await commentOps.allAction('archive', {}, [{ kt: 'post', lk: 'post-1' }]);
- * ```
- */
-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> | [], 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> | [], 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>;
-    }): Promise<V>;
-    get(key: ComKey<S, L1, L2, L3, L4, L5>): Promise<V | null>;
-    update(key: ComKey<S, L1, L2, L3, L4, L5>, item: Partial<Item<S, L1, L2, L3, L4, L5>>): Promise<V>;
-    upsert(key: ComKey<S, L1, L2, L3, L4, L5>, item: Partial<Item<S, L1, L2, L3, L4, L5>>): Promise<V>;
-    remove(key: ComKey<S, L1, L2, L3, L4, L5>): Promise<V | void>;
-    action(key: ComKey<S, L1, L2, L3, L4, L5>, action: string, params?: OperationParams): Promise<[V, AffectedKeys]>;
-    allAction(action: string, params: OperationParams | undefined, locations: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<[V[], AffectedKeys]>;
-    facet(key: ComKey<S, L1, L2, L3, L4, L5>, facet: string, params?: OperationParams): Promise<any>;
-    allFacet(facet: string, params: OperationParams | undefined, locations: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<any>;
-}