@fjell/core 4.4.61 → 4.4.63

package/dist/errors/ActionError.d.ts

@@ -36,6 +36,7 @@ export interface ErrorInfo {
         retryable?: boolean;
         conflictingValue?: any;
         expectedValue?: any;
+        fieldErrors?: any[];
     };
     technical?: {
         timestamp: string;

package/dist/errors/ValidationError.d.ts

@@ -1,4 +1,10 @@
 import { ActionError } from './ActionError';
+export interface FieldError {
+    path: (string | number)[];
+    message: string;
+    code: string;
+}
 export declare class ValidationError extends ActionError {
-    constructor(message: string, validOptions?: string[], suggestedAction?: string, conflictingValue?: any);
+    fieldErrors?: FieldError[];
+    constructor(message: string, validOptions?: string[], suggestedAction?: string, conflictingValue?: any, fieldErrors?: FieldError[]);
 }

package/dist/index.d.ts

@@ -15,7 +15,7 @@ export * from './validation';
 export * from './errors';
 export * from './operations';
 export * from './event';
-export type { Operations, OperationParams, AffectedKeys, CreateOptions } from './operations/Operations';
+export type { Operations, OperationParams, AffectedKeys, CreateOptions, UpdateOptions } from './operations/Operations';
 export { isPriKey as isOperationPriKey, isComKey as isOperationComKey } from './operations/Operations';
 export type { GetMethod, CreateMethod, UpdateMethod, RemoveMethod, UpsertMethod, AllMethod, OneMethod, FindMethod, FindOneMethod, FinderMethod, ActionMethod, ActionOperationMethod, AllActionMethod, AllActionOperationMethod, FacetMethod, FacetOperationMethod, AllFacetMethod, AllFacetOperationMethod, OperationsExtensions } from './operations/methods';
 export * from './operations/wrappers';

package/dist/index.js

@@ -1300,7 +1300,8 @@ var ActionError = class extends Error {
 
 // src/errors/ValidationError.ts
 var ValidationError = class extends ActionError {
-  constructor(message, validOptions, suggestedAction, conflictingValue) {
+  fieldErrors;
+  constructor(message, validOptions, suggestedAction, conflictingValue, fieldErrors) {
     super({
       code: "VALIDATION_ERROR",
       message,
@@ -1312,12 +1313,18 @@ var ValidationError = class extends ActionError {
         validOptions,
         suggestedAction,
         retryable: true,
-        conflictingValue
+        conflictingValue,
+        fieldErrors
       },
       technical: {
         timestamp: (/* @__PURE__ */ new Date()).toISOString()
       }
     });
+    this.fieldErrors = fieldErrors;
+    if (fieldErrors) {
+      if (!this.errorInfo.details) this.errorInfo.details = {};
+      this.errorInfo.details.fieldErrors = fieldErrors;
+    }
   }
 };
 
@@ -1953,9 +1960,9 @@ Received: ${Array.isArray(item) ? "array" : typeof item}`
 var logger13 = logger_default.get("operations", "wrappers", "update");
 function createUpdateWrapper(coordinate, implementation, options = {}) {
   const operationName = options.operationName || "update";
-  return async (key, item) => {
+  return async (key, item, updateOptions) => {
     if (options.debug) {
-      logger13.debug(`[${operationName}] Called with:`, { key, item });
+      logger13.debug(`[${operationName}] Called with:`, { key, item, updateOptions });
     }
     if (!options.skipValidation) {
       validateKey(key, coordinate, operationName);
@@ -1969,7 +1976,7 @@ Received: ${Array.isArray(item) ? "array" : typeof item}`
       }
     }
     try {
-      const result = await implementation(key, item);
+      const result = await implementation(key, item, updateOptions);
       if (options.debug) {
         logger13.debug(`[${operationName}] Updated item:`, result.key);
       }
@@ -1981,7 +1988,7 @@ Received: ${Array.isArray(item) ? "array" : typeof item}`
       if (options.onError) {
         const context = {
           operationName,
-          params: [key, item],
+          params: [key, item, updateOptions],
           coordinate
         };
         throw options.onError(error, context);
@@ -1998,13 +2005,12 @@ Received: ${Array.isArray(item) ? "array" : typeof item}`
 var logger14 = logger_default.get("operations", "wrappers", "upsert");
 function createUpsertWrapper(coordinate, implementation, options = {}) {
   const operationName = options.operationName || "upsert";
-  return async (key, item, locations) => {
+  return async (key, item, locations, updateOptions) => {
     if (options.debug) {
-      logger14.debug(`[${operationName}] Called with:`, { key, item, locations });
+      logger14.debug(`[${operationName}] Called with:`, { key, item, locations, updateOptions });
     }
     if (!options.skipValidation) {
       validateKey(key, coordinate, operationName);
-      validateLocations(locations, coordinate, operationName);
       if (!item || typeof item !== "object" || Array.isArray(item)) {
         throw new Error(
           `[${operationName}] Invalid item parameter.
@@ -2015,7 +2021,7 @@ Received: ${Array.isArray(item) ? "array" : typeof item}`
       }
     }
     try {
-      const result = await implementation(key, item);
+      const result = await implementation(key, item, locations, updateOptions);
       if (options.debug) {
         logger14.debug(`[${operationName}] Upserted item:`, result.key);
       }
@@ -2027,7 +2033,7 @@ Received: ${Array.isArray(item) ? "array" : typeof item}`
       if (options.onError) {
         const context = {
           operationName,
-          params: [key, item, locations],
+          params: [key, item, locations, updateOptions],
           coordinate
         };
         throw options.onError(error, context);

package/dist/operations/Operations.d.ts

@@ -19,6 +19,62 @@ export type CreateOptions<S extends string, L1 extends string = never, L2 extend
     key?: never;
     locations: LocKeyArray<L1, L2, L3, L4, L5>;
 };
+/**
+ * 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
@@ -119,18 +175,32 @@ export interface Operations<V extends Item<S, L1, L2, L3, L4, L5>, S extends str
      *
      * @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>>): Promise<V>;
+    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>): Promise<V>;
+    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.
      *

package/dist/operations/methods.d.ts

@@ -1,7 +1,7 @@
 import { Item } from "../items";
 import { ComKey, LocKeyArray, PriKey } from "../keys";
 import { ItemQuery } from "../item/ItemQuery";
-import { AffectedKeys, CreateOptions, OperationParams } from "./Operations";
+import { AffectedKeys, CreateOptions, OperationParams, UpdateOptions } from "./Operations";
 /**
  * Get method signature - retrieves single item by key
  */
@@ -18,7 +18,7 @@ export interface CreateMethod<V extends Item<S, L1, L2, L3, L4, L5>, S extends s
  * 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>;
+    (key: PriKey<S> | ComKey<S, L1, L2, L3, L4, L5>, item: Partial<Item<S, L1, L2, L3, L4, L5>>, options?: UpdateOptions): Promise<V>;
 }
 /**
  * Remove method signature - removes item
@@ -30,7 +30,7 @@ export interface RemoveMethod<V extends Item<S, L1, L2, L3, L4, L5>, S extends s
  * 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>;
+    (key: PriKey<S> | ComKey<S, L1, L2, L3, L4, L5>, item: Partial<Item<S, L1, L2, L3, L4, L5>>, locations?: LocKeyArray<L1, L2, L3, L4, L5>, options?: UpdateOptions): Promise<V>;
 }
 /**
  * All method signature - retrieves all items matching query

package/dist/operations/wrappers/createUpsertWrapper.d.ts

@@ -3,8 +3,8 @@
  *
  * Provides automatic validation for upsert() operation parameters.
  */
-import type { Item } from "../../items";
 import type { Coordinate } from "../../Coordinate";
+import type { Item } from "../../items";
 import type { UpsertMethod } from "../methods";
 import type { WrapperOptions } from "./types";
 /**
@@ -19,8 +19,8 @@ import type { WrapperOptions } from "./types";
  * ```typescript
  * const upsert = createUpsertWrapper(
  *   coordinate,
- *   async (key, item, locations) => {
- *     return await database.upsert(key, item, locations);
+ *   async (key, item, locations, options) => {
+ *     return await database.upsert(key, item, locations, options);
  *   }
  * );
  * ```

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fjell/core",
   "description": "Core Item and Key Framework for Fjell",
-  "version": "4.4.61",
+  "version": "4.4.63",
   "keywords": [
     "core",
     "fjell"