@fjell/core 4.4.48 → 4.4.50

package/src/operations/Operations.ts

@@ -0,0 +1,357 @@
+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 function isPriKey<S extends string>(
+  key: PriKey<S> | ComKey<S, any, any, any, any, any>
+): key is PriKey<S> {
+  return !('loc' in key) || !key.loc;
+}
+
+/**
+ * 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 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> {
+  return 'loc' in key && key.loc && Array.isArray(key.loc) && key.loc.length > 0;
+}
+

package/src/operations/contained.ts

@@ -0,0 +1,134 @@
+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'> {
+  
+  // Collection query operations - locations required
+  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>;
+
+  // Finder operations - locations required
+  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 operation - locations for context
+  create(
+    item: Partial<Item<S, L1, L2, L3, L4, L5>>,
+    options?: { locations?: LocKeyArray<L1, L2, L3, L4, L5> }
+  ): Promise<V>;
+
+  // CRUD operations - ComKey only
+  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 operations - ComKey for instance, locations for collections
+  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 operations - ComKey for instance, locations for collections
+  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/src/operations/errorEnhancer.ts

@@ -0,0 +1,204 @@
+import { ActionError, ErrorInfo } from "../errors/ActionError";
+import { OperationContext } from "./OperationContext";
+import { ComKey, PriKey } from "../keys";
+
+/**
+ * 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 async function executeWithContext<T>(
+  operation: () => Promise<T>,
+  context: OperationContext
+): Promise<T> {
+  try {
+    return await operation();
+  } catch (error) {
+    throw enhanceError(error as Error, context);
+  }
+}
+
+/**
+ * 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 function executeWithContextSync<T>(
+  operation: () => T,
+  context: OperationContext
+): T {
+  try {
+    return operation();
+  } catch (error) {
+    throw enhanceError(error as Error, context);
+  }
+}
+
+/**
+ * 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 function enhanceError(error: Error, context: OperationContext): Error {
+  if (!(error instanceof ActionError)) {
+    // Not an ActionError, return as-is
+    return error;
+  }
+
+  // Fill in operation context
+  error.errorInfo.operation = {
+    type: context.operationType,
+    name: context.operationName,
+    params: context.params
+  };
+
+  // Fill in item type (allow override if already set)
+  if (!error.errorInfo.context.itemType) {
+    error.errorInfo.context.itemType = context.itemType;
+  }
+
+  // Add key context if available and not already set (or if existing key has no meaningful data)
+  if (context.key) {
+    const existingKey = error.errorInfo.context.key;
+    const hasNoPrimaryKey = !existingKey || typeof existingKey.primary === 'undefined';
+    const hasNoCompositeKey = !existingKey || !existingKey.composite;
+    const shouldOverride = hasNoPrimaryKey && hasNoCompositeKey;
+    
+    if (shouldOverride) {
+      error.errorInfo.context.key = extractKeyInfo(context.key);
+    }
+  }
+
+  // Add location context if available and not already set
+  if (context.locations && context.locations.length > 0 && !error.errorInfo.context.parentLocation) {
+    error.errorInfo.context.parentLocation = {
+      id: context.locations[0].lk,
+      type: context.locations[0].kt
+    };
+  }
+
+  return error;
+}
+
+/**
+ * Extracts key information from a PriKey or ComKey for error context.
+ *
+ * @param key - The key to extract information from
+ * @returns The extracted key information
+ */
+function extractKeyInfo(
+  key: PriKey<any> | ComKey<any, any, any, any, any, any>
+): NonNullable<ErrorInfo['context']['key']> {
+  // Check if it's a ComKey (has loc property)
+  if ('loc' in key) {
+    // Composite key - convert from ComKey format to error info format
+    const ktaArray = Array.isArray(key.kt) ? key.kt : [key.kt];
+    const locations = Array.isArray(key.loc) ? key.loc : [];
+    
+    return {
+      composite: {
+        sk: key.pk,
+        kta: ktaArray,
+        locations: locations.map(loc => ({
+          lk: loc.lk,
+          kt: loc.kt
+        }))
+      }
+    };
+  } else if ('pk' in key) {
+    // Primary key
+    return { primary: key.pk };
+  }
+  
+  // Fallback for unknown key structure
+  return { primary: JSON.stringify(key) };
+}
+
+/**
+ * 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 function isActionError(error: unknown): error is ActionError {
+  return error instanceof 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 function getErrorInfo(error: unknown): any {
+  if (isActionError(error)) {
+    return error.toJSON();
+  }
+
+  // For non-ActionErrors, create a minimal error info
+  if (error instanceof Error) {
+    return {
+      code: 'UNKNOWN_ERROR',
+      message: error.message,
+      technical: {
+        timestamp: new Date().toISOString(),
+        stackTrace: error.stack
+      }
+    };
+  }
+
+  // For non-Error objects
+  return {
+    code: 'UNKNOWN_ERROR',
+    message: String(error),
+    technical: {
+      timestamp: new Date().toISOString()
+    }
+  };
+}
+

package/src/operations/index.ts

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