@fjell/core 4.4.50 → 4.4.52

package/src/operations/methods.ts

@@ -1,363 +0,0 @@
-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/src/operations/primary.ts

@@ -1,101 +0,0 @@
-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'> {
-  
-  // Collection query operations - no locations needed
-  all(query?: ItemQuery): Promise<V[]>;
-  one(query?: ItemQuery): Promise<V | null>;
-
-  // Finder operations - no locations
-  find(finder: string, params?: OperationParams): Promise<V[]>;
-  findOne(finder: string, params?: OperationParams): Promise<V | null>;
-
-  // CRUD operations - PriKey only
-  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 operations - PriKey only, no locations
-  action(
-    key: PriKey<S>,
-    action: string,
-    params?: OperationParams
-  ): Promise<[V, AffectedKeys]>;
-
-  allAction(
-    action: string,
-    params?: OperationParams
-  ): Promise<[V[], AffectedKeys]>;
-
-  // Facet operations - PriKey only, no locations
-  facet(
-    key: PriKey<S>,
-    facet: string,
-    params?: OperationParams
-  ): Promise<any>;
-
-  allFacet(
-    facet: string,
-    params?: OperationParams
-  ): Promise<any>;
-}
-

package/src/operations/specialized.ts

@@ -1,71 +0,0 @@
-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
-> {
-  // Query operations
-  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 new items
-  create(item: Partial<Item<S, L1, L2, L3, L4, L5>>, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<V>;
-  
-  // Collection-level operations
-  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
-> {
-  // Retrieve specific item
-  get(key: PriKey<S> | ComKey<S, L1, L2, L3, L4, L5>): Promise<V | null>;
-  
-  // Modify specific item
-  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>;
-  
-  // Instance-level operations
-  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>;
-}
-

package/src/operations/wrappers/createActionWrapper.ts

@@ -1,108 +0,0 @@
-/**
- * Wrapper for action() operation
- *
- * Provides automatic validation for action() operation parameters.
- */
-
-import type { Item } from "../../items";
-import type { ComKey, PriKey } from "../../keys";
-import type { Coordinate } from "../../Coordinate";
-import type { AffectedKeys, OperationParams } from "../Operations";
-import { validateActionName, validateKey, validateOperationParams, validatePK } from "../../validation";
-import type { ActionOperationMethod } from "../methods";
-import type { ErrorContext, WrapperOptions } from "./types";
-import LibLogger from "../../logger";
-
-const logger = LibLogger.get('operations', 'wrappers', 'action');
-
-/**
- * Creates a wrapped action() method with automatic parameter validation.
- *
- * @param coordinate - The coordinate defining the item hierarchy
- * @param implementation - The core logic for the operation
- * @param options - Optional configuration
- * @returns A fully validated action() method
- *
- * @example
- * ```typescript
- * const action = createActionWrapper(
- *   coordinate,
- *   async (key, action, params) => {
- *     return await database.executeAction(key, action, params);
- *   }
- * );
- * ```
- */
-export function createActionWrapper<
-  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: ActionOperationMethod<V, S, L1, L2, L3, L4, L5>,
-  options: WrapperOptions = {}
-): ActionOperationMethod<V, S, L1, L2, L3, L4, L5> {
-  
-  const operationName = options.operationName || 'action';
-  
-  return async (
-    key: PriKey<S> | ComKey<S, L1, L2, L3, L4, L5>,
-    action: string,
-    params?: OperationParams
-  ): Promise<[V, AffectedKeys]> => {
-    
-    if (options.debug) {
-      logger.debug(`[${operationName}] Called:`, { key, action, params });
-    }
-    
-    // Validate
-    if (!options.skipValidation) {
-      validateKey(key, coordinate, operationName);
-      validateActionName(action, operationName);
-      validateOperationParams(params, operationName);
-    }
-    
-    // Normalize
-    const normalizedParams = params ?? {};
-    
-    // Execute
-    try {
-      const result = await implementation(key, action, normalizedParams);
-      
-      if (options.debug) {
-        logger.debug(`[${operationName}] Action "${action}" completed:`, {
-          itemKey: result[0].key,
-          affectedKeys: result[1].length
-        });
-      }
-      
-      // Validate primary key type of the returned item
-      if (!options.skipValidation) {
-        const validatedItem = validatePK(result[0], coordinate.kta[0]) as V;
-        return [validatedItem, result[1]];
-      }
-      
-      return result;
-      
-    } catch (error) {
-      if (options.onError) {
-        const context: ErrorContext = {
-          operationName,
-          params: [key, action, params],
-          coordinate
-        };
-        throw options.onError(error as Error, context);
-      }
-      
-      throw new Error(
-        `[${operationName}] Action "${action}" failed: ${(error as Error).message}`,
-        { cause: error }
-      );
-    }
-  };
-}
-