@fjell/core 4.4.48 → 4.4.49

package/dist/item/IUtils.d.ts

@@ -1,7 +1,10 @@
 import { Item } from "../items";
-import { AllItemTypeArrays, ComKey, PriKey } from "../keys";
-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>[];
-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>;
+import { ComKey, PriKey } from "../keys";
+/**
+ * @deprecated Use validatePK from @fjell/core/validation instead
+ * Re-exported for backward compatibility
+ */
+export { validatePK, validateKeys } from '../validation/ItemValidator';
 export declare const isPriItem: <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>) => item is Item<S> & {
     key: PriKey<S>;
 };

package/dist/operations/OperationContext.d.ts

@@ -0,0 +1,10 @@
+import { ComKey, LocKeyArray, PriKey } from '../keys';
+import type { ErrorInfo } from '../errors/ActionError';
+export interface OperationContext {
+    itemType: string;
+    operationType: ErrorInfo['operation']['type'];
+    operationName: string;
+    params: Record<string, any>;
+    key?: PriKey<any> | ComKey<any, any, any, any, any, any>;
+    locations?: LocKeyArray<any, any, any, any, any>;
+}

package/dist/operations/Operations.d.ts

@@ -0,0 +1,259 @@
+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>;
+};
+/**
+ * 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.
+     *
+     * @param query - Optional query to filter items
+     * @param locations - Optional location hierarchy to scope the query
+     * @returns Array of items matching the query
+     *
+     * @example
+     * ```typescript
+     * // Get all users
+     * const users = await operations.all();
+     *
+     * // Get users with filter
+     * const activeUsers = await operations.all({ filter: { status: 'active' } });
+     *
+     * // Get items in specific location
+     * const comments = await operations.all({}, [{kt: 'post', lk: 'post-123'}]);
+     * ```
+     */
+    all(query?: ItemQuery, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<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
+     * @returns The updated item
+     */
+    update(key: PriKey<S> | ComKey<S, L1, L2, L3, L4, L5>, item: Partial<Item<S, L1, L2, L3, L4, L5>>): 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
+     * @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>): 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.
+     *
+     * @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
+     *
+     * @example
+     * ```typescript
+     * // Find users by email
+     * const users = await operations.find('byEmail', { email: 'alice@example.com' });
+     *
+     * // Find in specific location
+     * const comments = await operations.find(
+     *   'byAuthor',
+     *   { author: 'alice' },
+     *   [{kt: 'post', lk: 'post-123'}]
+     * );
+     * ```
+     */
+    find(finder: string, params?: OperationParams, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<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

@@ -0,0 +1,65 @@
+import { Item } from "../items";
+import { ComKey, LocKeyArray } from "../keys";
+import { ItemQuery } from "../item/ItemQuery";
+import { AffectedKeys, 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> | []): Promise<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>;
+    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>;
+}

package/dist/operations/errorEnhancer.d.ts

@@ -0,0 +1,79 @@
+import { ActionError } from "../errors/ActionError";
+import { OperationContext } from "./OperationContext";
+/**
+ * Executes an async operation and enhances any ActionError thrown with operation context.
+ *
+ * This is the primary utility for wrapping operations across all fjell packages.
+ *
+ * @param operation - The async operation to execute
+ * @param context - The operation context to add to any errors
+ * @returns The result of the operation
+ * @throws Enhanced ActionError or original error
+ *
+ * @example
+ * ```typescript
+ * // In fjell/lib
+ * return executeWithContext(
+ *   () => toWrap.get(key),
+ *   {
+ *     itemType: 'user',
+ *     operationType: 'get',
+ *     operationName: 'get',
+ *     params: { key },
+ *     key
+ *   }
+ * );
+ *
+ * // In express-router
+ * return executeWithContext(
+ *   () => operations.action('approve', params, key),
+ *   {
+ *     itemType: 'invoice',
+ *     operationType: 'action',
+ *     operationName: 'approve',
+ *     params,
+ *     key
+ *   }
+ * );
+ * ```
+ */
+export declare function executeWithContext<T>(operation: () => Promise<T>, context: OperationContext): Promise<T>;
+/**
+ * Synchronous version of executeWithContext for non-async operations.
+ *
+ * @param operation - The sync operation to execute
+ * @param context - The operation context to add to any errors
+ * @returns The result of the operation
+ * @throws Enhanced ActionError or original error
+ */
+export declare function executeWithContextSync<T>(operation: () => T, context: OperationContext): T;
+/**
+ * Enhances an error with operation context if it's an ActionError.
+ * If it's not an ActionError, returns the original error unchanged.
+ *
+ * This allows database implementations and business logic to throw
+ * ActionErrors with minimal context, and have that context filled in
+ * by the operation wrapper.
+ *
+ * @param error - The error to enhance
+ * @param context - The operation context to add
+ * @returns The enhanced or original error
+ */
+export declare function enhanceError(error: Error, context: OperationContext): Error;
+/**
+ * Type guard to check if an error is an ActionError.
+ *
+ * @param error - The error to check
+ * @returns True if the error is an ActionError
+ */
+export declare function isActionError(error: unknown): error is ActionError;
+/**
+ * Extracts error info from an ActionError, or creates a generic error info
+ * for non-ActionErrors.
+ *
+ * Useful for logging and error reporting.
+ *
+ * @param error - The error to extract info from
+ * @returns The error info
+ */
+export declare function getErrorInfo(error: unknown): any;

package/dist/operations/index.d.ts

@@ -0,0 +1,2 @@
+export * from './OperationContext';
+export * from './errorEnhancer';

package/dist/operations/methods.d.ts

@@ -0,0 +1,134 @@
+import { Item } from "../items";
+import { ComKey, LocKeyArray, PriKey } from "../keys";
+import { ItemQuery } from "../item/ItemQuery";
+import { AffectedKeys, CreateOptions, OperationParams } from "./Operations";
+/**
+ * Get method signature - retrieves single item by key
+ */
+export interface GetMethod<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> {
+    (key: PriKey<S> | ComKey<S, L1, L2, L3, L4, L5>): Promise<V | null>;
+}
+/**
+ * Create method signature - creates new item
+ */
+export interface CreateMethod<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> {
+    (item: Partial<Item<S, L1, L2, L3, L4, L5>>, options?: CreateOptions<S, L1, L2, L3, L4, L5>): Promise<V>;
+}
+/**
+ * Update method signature - updates existing item
+ */
+export interface UpdateMethod<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> {
+    (key: PriKey<S> | ComKey<S, L1, L2, L3, L4, L5>, item: Partial<Item<S, L1, L2, L3, L4, L5>>): Promise<V>;
+}
+/**
+ * Remove method signature - removes item
+ */
+export interface RemoveMethod<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> {
+    (key: PriKey<S> | ComKey<S, L1, L2, L3, L4, L5>): Promise<V | void>;
+}
+/**
+ * Upsert method signature - updates or creates item
+ */
+export interface UpsertMethod<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> {
+    (key: PriKey<S> | ComKey<S, L1, L2, L3, L4, L5>, item: Partial<Item<S, L1, L2, L3, L4, L5>>): Promise<V>;
+}
+/**
+ * All method signature - retrieves all items matching query
+ */
+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[]>;
+}
+/**
+ * One method signature - retrieves first item matching query
+ */
+export interface OneMethod<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 | null>;
+}
+/**
+ * Find method signature - finds multiple items using finder
+ */
+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[]>;
+}
+/**
+ * FindOne method signature - finds single item using finder
+ */
+export interface FindOneMethod<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 | null>;
+}
+/**
+ * Finder method signature - finds multiple items
+ *
+ * @example
+ * ```typescript
+ * const byEmailFinder: FinderMethod<User, 'user'> = async (params) => {
+ *   return await database.findUsers({ email: params.email });
+ * };
+ * ```
+ */
+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[]>;
+}
+/**
+ * Action operation method signature - executes action on specific item by key
+ */
+export interface ActionOperationMethod<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> {
+    (key: PriKey<S> | ComKey<S, L1, L2, L3, L4, L5>, action: string, params?: OperationParams): Promise<[V, AffectedKeys]>;
+}
+/**
+ * Action method signature - user-defined action implementation
+ */
+export interface ActionMethod<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> {
+    (item: V, params: OperationParams): Promise<[V, AffectedKeys]>;
+}
+/**
+ * AllAction operation method signature - executes action on all items
+ */
+export interface AllActionOperationMethod<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> {
+    (action: string, params?: OperationParams, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<[V[], AffectedKeys]>;
+}
+/**
+ * All-action method signature - user-defined all-action implementation
+ */
+export interface AllActionMethod<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[], AffectedKeys]>;
+}
+/**
+ * Facet operation method signature - executes facet on specific item by key
+ */
+export interface FacetOperationMethod<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>, facet: string, params?: OperationParams): Promise<any>;
+}
+/**
+ * Facet method signature - user-defined facet implementation
+ */
+export interface FacetMethod<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> {
+    (item: V, params: OperationParams): Promise<any>;
+}
+/**
+ * AllFacet operation method signature - executes facet on all items
+ */
+export interface AllFacetOperationMethod<L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never> {
+    (facet: string, params?: OperationParams, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<any>;
+}
+/**
+ * All-facet method signature - user-defined all-facet implementation
+ */
+export interface AllFacetMethod<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<any>;
+}
+/**
+ * Extension maps for operations
+ */
+export interface OperationsExtensions<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> {
+    /** Registered finder methods */
+    finders?: Record<string, FinderMethod<V, S, L1, L2, L3, L4, L5>>;
+    /** Registered action methods */
+    actions?: Record<string, ActionMethod<V, S, L1, L2, L3, L4, L5>>;
+    /** Registered facet methods */
+    facets?: Record<string, FacetMethod<V, S, L1, L2, L3, L4, L5>>;
+    /** Registered all-action methods */
+    allActions?: Record<string, AllActionMethod<V, S, L1, L2, L3, L4, L5>>;
+    /** Registered all-facet methods */
+    allFacets?: Record<string, AllFacetMethod<L1, L2, L3, L4, L5>>;
+}

package/dist/operations/primary.d.ts

@@ -0,0 +1,57 @@
+import { Item } from "../items";
+import { PriKey } from "../keys";
+import { ItemQuery } from "../item/ItemQuery";
+import { AffectedKeys, OperationParams, Operations } from "./Operations";
+/**
+ * Primary Operations interface - specialized for primary (top-level) items only.
+ *
+ * This interface narrows the generic Operations interface to work exclusively
+ * with PriKey. All operations accept only PriKey, never ComKey or locations.
+ *
+ * Primary items are top-level entities that don't belong to a location hierarchy.
+ * Examples: Users, Organizations, Products, Documents
+ *
+ * Use this for:
+ * - Libraries that store primary items
+ * - Caches for primary items
+ * - API clients for primary endpoints
+ * - Any operations that work with non-hierarchical data
+ *
+ * @example
+ * ```typescript
+ * // Define a primary item type
+ * interface User extends Item<'user'> {
+ *   name: string;
+ *   email: string;
+ * }
+ *
+ * // Create operations for primary items
+ * const userOps: PrimaryOperations<User, 'user'> = createUserOperations();
+ *
+ * // Only PriKey allowed - no locations
+ * await userOps.get({ kt: 'user', pk: '123' });
+ * await userOps.update({ kt: 'user', pk: '123' }, { name: 'Updated' });
+ *
+ * // No locations parameter on collection methods
+ * await userOps.all({});
+ * await userOps.find('byEmail', { email: 'test@example.com' });
+ * await userOps.allAction('deactivate', { reason: 'inactive' });
+ * ```
+ */
+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[]>;
+    one(query?: ItemQuery): Promise<V | null>;
+    find(finder: string, params?: OperationParams): Promise<V[]>;
+    findOne(finder: string, params?: OperationParams): Promise<V | null>;
+    create(item: Partial<Item<S>>, options?: {
+        key?: PriKey<S>;
+    }): Promise<V>;
+    get(key: PriKey<S>): Promise<V | null>;
+    update(key: PriKey<S>, item: Partial<Item<S>>): Promise<V>;
+    upsert(key: PriKey<S>, item: Partial<Item<S>>): Promise<V>;
+    remove(key: PriKey<S>): Promise<V | void>;
+    action(key: PriKey<S>, action: string, params?: OperationParams): Promise<[V, AffectedKeys]>;
+    allAction(action: string, params?: OperationParams): Promise<[V[], AffectedKeys]>;
+    facet(key: PriKey<S>, facet: string, params?: OperationParams): Promise<any>;
+    allFacet(facet: string, params?: OperationParams): Promise<any>;
+}

package/dist/operations/specialized.d.ts

@@ -0,0 +1,41 @@
+import { Item } from "../items";
+import { ComKey, LocKeyArray, PriKey } from "../keys";
+import { ItemQuery } from "../item/ItemQuery";
+import { AffectedKeys, OperationParams } from "./Operations";
+/**
+ * Specialized Operations Interfaces
+ *
+ * This file contains operation interfaces for specific usage patterns.
+ * These are primarily used in UI layers (like React providers) to group
+ * operations by their usage pattern rather than data structure.
+ *
+ * For core architectural patterns (Primary vs. Contained), see:
+ * - primary.ts - Operations for top-level items
+ * - contained.ts - Operations for hierarchical items
+ */
+/**
+ * Collection-focused operations interface.
+ * Optimized for working with groups of items.
+ * Used by React providers for array/list contexts.
+ */
+export interface CollectionOperations<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> {
+    all(query?: ItemQuery, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<V[]>;
+    one(query?: ItemQuery, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<V | null>;
+    find(finder: string, params?: OperationParams, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<V[]>;
+    findOne(finder: string, params?: OperationParams, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<V | null>;
+    create(item: Partial<Item<S, L1, L2, L3, L4, L5>>, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<V>;
+    allAction(action: string, params?: OperationParams, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<[V[], AffectedKeys]>;
+    allFacet(facet: string, params?: OperationParams, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<any>;
+}
+/**
+ * Instance-focused operations interface.
+ * Optimized for working with a single specific item.
+ * Used by React providers for single-item contexts.
+ */
+export interface InstanceOperations<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> {
+    get(key: PriKey<S> | ComKey<S, L1, L2, L3, L4, L5>): Promise<V | null>;
+    update(key: PriKey<S> | ComKey<S, L1, L2, L3, L4, L5>, item: Partial<Item<S, L1, L2, L3, L4, L5>>): Promise<V>;
+    remove(key: PriKey<S> | ComKey<S, L1, L2, L3, L4, L5>): Promise<V | void>;
+    action(key: PriKey<S> | ComKey<S, L1, L2, L3, L4, L5>, action: string, params?: OperationParams): Promise<[V, AffectedKeys]>;
+    facet(key: PriKey<S> | ComKey<S, L1, L2, L3, L4, L5>, facet: string, params?: OperationParams): Promise<any>;
+}