s3db.js 11.3.2 → 12.0.1

package/src/resource.class.js

@@ -13,7 +13,7 @@ import { ResourceReader, ResourceWriter } from "./stream/index.js"
 import { getBehavior, DEFAULT_BEHAVIOR } from "./behaviors/index.js";
 import { idGenerator as defaultIdGenerator } from "./concerns/id.js";
 import { calculateTotalSize, calculateEffectiveLimit } from "./concerns/calculator.js";
-import { mapAwsError, InvalidResourceItem, ResourceError, PartitionError } from "./errors.js";
+import { mapAwsError, InvalidResourceItem, ResourceError, PartitionError, ValidationError } from "./errors.js";
 
 
 export class Resource extends AsyncEventEmitter {
@@ -22,7 +22,7 @@ export class Resource extends AsyncEventEmitter {
    * @param {Object} config - Resource configuration
    * @param {string} config.name - Resource name
    * @param {Object} config.client - S3 client instance
-   * @param {string} [config.version='v0'] - Resource version
+   * @param {string} [config.version='v1'] - Resource version
    * @param {Object} [config.attributes={}] - Resource attributes schema
    * @param {string} [config.behavior='user-managed'] - Resource behavior strategy
    * @param {string} [config.passphrase='secret'] - Encryption passphrase
@@ -392,7 +392,8 @@ export class Resource extends AsyncEventEmitter {
     this.attributes = newAttributes;
 
     // Apply configuration to ensure timestamps and hooks are set up
-    this.applyConfiguration({ map: this.schema?.map });
+    // Don't pass old map - let it regenerate with new attributes
+    this.applyConfiguration();
 
     return { oldAttributes, newAttributes };
   }
@@ -1250,6 +1251,314 @@ export class Resource extends AsyncEventEmitter {
     }
   }
 
+  /**
+   * Patch resource (partial update optimized for metadata-only behaviors)
+   *
+   * This method provides an optimized update path for resources using metadata-only behaviors
+   * (enforce-limits, truncate-data). It uses HeadObject + CopyObject for atomic updates without
+   * body transfer, eliminating race conditions and reducing latency by ~50%.
+   *
+   * For behaviors that store data in body (body-overflow, body-only), it automatically falls
+   * back to the standard update() method.
+   *
+   * @param {string} id - Resource ID
+   * @param {Object} fields - Fields to update (partial data)
+   * @param {Object} options - Update options
+   * @param {string} options.partition - Partition name (if using partitions)
+   * @param {Object} options.partitionValues - Partition values (if using partitions)
+   * @returns {Promise<Object>} Updated resource data
+   *
+   * @example
+   * // Fast atomic update (enforce-limits behavior)
+   * await resource.patch('user-123', { status: 'active', loginCount: 42 });
+   *
+   * @example
+   * // With partitions
+   * await resource.patch('order-456', { status: 'shipped' }, {
+   *   partition: 'byRegion',
+   *   partitionValues: { region: 'US' }
+   * });
+   */
+  async patch(id, fields, options = {}) {
+    if (isEmpty(id)) {
+      throw new Error('id cannot be empty');
+    }
+
+    if (!fields || typeof fields !== 'object') {
+      throw new Error('fields must be a non-empty object');
+    }
+
+    const behavior = this.behavior;
+
+    // Check if fields contain dot notation (nested fields)
+    const hasNestedFields = Object.keys(fields).some(key => key.includes('.'));
+
+    // ✅ Optimization: HEAD + COPY for metadata-only behaviors WITHOUT nested fields
+    if ((behavior === 'enforce-limits' || behavior === 'truncate-data') && !hasNestedFields) {
+      return await this._patchViaCopyObject(id, fields, options);
+    }
+
+    // ⚠️ Fallback: GET + merge + PUT for:
+    // - Behaviors with body storage
+    // - Nested field updates (need full object merge)
+    return await this.update(id, fields, options);
+  }
+
+  /**
+   * Internal helper: Optimized patch using HeadObject + CopyObject
+   * Only works for metadata-only behaviors (enforce-limits, truncate-data)
+   * Only for simple field updates (no nested fields with dot notation)
+   * @private
+   */
+  async _patchViaCopyObject(id, fields, options = {}) {
+    const { partition, partitionValues } = options;
+
+    // Build S3 key
+    const key = this.getResourceKey(id);
+
+    // Step 1: HEAD to get current metadata (optimization: no body transfer)
+    const headResponse = await this.client.headObject(key);
+    const currentMetadata = headResponse.Metadata || {};
+
+    // Step 2: Decode metadata to user format
+    let currentData = await this.schema.unmapper(currentMetadata);
+
+    // Ensure ID is present
+    if (!currentData.id) {
+      currentData.id = id;
+    }
+
+    // Step 3: Merge with new fields (simple merge, no nested fields)
+    const fieldsClone = cloneDeep(fields);
+    let mergedData = cloneDeep(currentData);
+
+    for (const [key, value] of Object.entries(fieldsClone)) {
+      if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+        // Merge objects
+        mergedData[key] = merge({}, mergedData[key], value);
+      } else {
+        mergedData[key] = cloneDeep(value);
+      }
+    }
+
+    // Step 4: Update timestamps
+    if (this.config.timestamps) {
+      mergedData.updatedAt = new Date().toISOString();
+    }
+
+    // Step 5: Validate merged data
+    const validationResult = await this.schema.validate(mergedData);
+    if (validationResult !== true) {
+      throw new ValidationError('Validation failed during patch', validationResult);
+    }
+
+    // Step 6: Map/encode data to storage format
+    const newMetadata = await this.schema.mapper(mergedData);
+
+    // Add version metadata
+    newMetadata._v = String(this.version);
+
+    // Step 8: CopyObject with new metadata (atomic operation)
+    await this.client.copyObject({
+      from: key,
+      to: key,
+      metadataDirective: 'REPLACE',
+      metadata: newMetadata
+    });
+
+    // Step 9: Update partitions if needed
+    if (this.config.partitions && Object.keys(this.config.partitions).length > 0) {
+      const oldData = { ...currentData, id };
+      const newData = { ...mergedData, id };
+
+      if (this.config.asyncPartitions) {
+        // Async mode: update in background
+        setImmediate(() => {
+          this.handlePartitionReferenceUpdates(oldData, newData).catch(err => {
+            this.emit('partitionIndexError', {
+              operation: 'patch',
+              id,
+              error: err
+            });
+          });
+        });
+      } else {
+        // Sync mode: wait for completion
+        await this.handlePartitionReferenceUpdates(oldData, newData);
+      }
+    }
+
+    return mergedData;
+  }
+
+  /**
+   * Replace resource (full object replacement without GET)
+   *
+   * This method performs a direct PUT operation without fetching the current object.
+   * Use this when you already have the complete object and want to replace it entirely,
+   * saving 1 S3 request (GET).
+   *
+   * ⚠️ Warning: You must provide ALL required fields. Missing fields will NOT be preserved
+   * from the current object. This method does not merge with existing data.
+   *
+   * @param {string} id - Resource ID
+   * @param {Object} fullData - Complete object data (all required fields)
+   * @param {Object} options - Update options
+   * @param {string} options.partition - Partition name (if using partitions)
+   * @param {Object} options.partitionValues - Partition values (if using partitions)
+   * @returns {Promise<Object>} Replaced resource data
+   *
+   * @example
+   * // Replace entire object (must include ALL required fields)
+   * await resource.replace('user-123', {
+   *   name: 'John Doe',
+   *   email: 'john@example.com',
+   *   status: 'active',
+   *   loginCount: 42
+   * });
+   *
+   * @example
+   * // With partitions
+   * await resource.replace('order-456', fullOrderData, {
+   *   partition: 'byRegion',
+   *   partitionValues: { region: 'US' }
+   * });
+   */
+  async replace(id, fullData, options = {}) {
+    if (isEmpty(id)) {
+      throw new Error('id cannot be empty');
+    }
+
+    if (!fullData || typeof fullData !== 'object') {
+      throw new Error('fullData must be a non-empty object');
+    }
+
+    const { partition, partitionValues } = options;
+
+    // Clone data to avoid mutations
+    const dataClone = cloneDeep(fullData);
+
+    // Apply defaults before timestamps
+    const attributesWithDefaults = this.applyDefaults(dataClone);
+
+    // Add timestamps
+    if (this.config.timestamps) {
+      // Preserve createdAt if provided, otherwise set to now
+      if (!attributesWithDefaults.createdAt) {
+        attributesWithDefaults.createdAt = new Date().toISOString();
+      }
+      attributesWithDefaults.updatedAt = new Date().toISOString();
+    }
+
+    // Ensure ID is set
+    const completeData = { id, ...attributesWithDefaults };
+
+    // Validate data
+    const {
+      errors,
+      isValid,
+      data: validated,
+    } = await this.validate(completeData);
+
+    if (!isValid) {
+      const errorMsg = (errors && errors.length && errors[0].message) ? errors[0].message : 'Replace failed';
+      throw new InvalidResourceItem({
+        bucket: this.client.config.bucket,
+        resourceName: this.name,
+        attributes: completeData,
+        validation: errors,
+        message: errorMsg
+      });
+    }
+
+    // Extract id and attributes from validated data
+    const { id: validatedId, ...validatedAttributes } = validated;
+
+    // Map/encode data to storage format
+    const mappedMetadata = await this.schema.mapper(validatedAttributes);
+
+    // Add version metadata
+    mappedMetadata._v = String(this.version);
+
+    // Use behavior to store data (like insert, not update)
+    const behaviorImpl = getBehavior(this.behavior);
+    const { mappedData: finalMetadata, body } = await behaviorImpl.handleInsert({
+      resource: this,
+      data: validatedAttributes,
+      mappedData: mappedMetadata,
+      originalData: completeData
+    });
+
+    // Build S3 key
+    const key = this.getResourceKey(id);
+
+    // Determine content type based on body content
+    let contentType = undefined;
+    if (body && body !== "") {
+      const [okParse] = await tryFn(() => Promise.resolve(JSON.parse(body)));
+      if (okParse) contentType = 'application/json';
+    }
+
+    // Only throw if behavior is 'body-only' and body is empty
+    if (this.behavior === 'body-only' && (!body || body === "")) {
+      throw new Error(`[Resource.replace] Attempt to save object without body! Data: id=${id}, resource=${this.name}`);
+    }
+
+    // Store to S3 (overwrites if exists, creates if not - true replace/upsert)
+    const [okPut, errPut] = await tryFn(() => this.client.putObject({
+      key,
+      body,
+      contentType,
+      metadata: finalMetadata,
+    }));
+
+    if (!okPut) {
+      const msg = errPut && errPut.message ? errPut.message : '';
+      if (msg.includes('metadata headers exceed') || msg.includes('Replace failed')) {
+        const totalSize = calculateTotalSize(finalMetadata);
+        const effectiveLimit = calculateEffectiveLimit({
+          s3Limit: 2047,
+          systemConfig: {
+            version: this.version,
+            timestamps: this.config.timestamps,
+            id
+          }
+        });
+        const excess = totalSize - effectiveLimit;
+        errPut.totalSize = totalSize;
+        errPut.limit = 2047;
+        errPut.effectiveLimit = effectiveLimit;
+        errPut.excess = excess;
+        throw new ResourceError('metadata headers exceed', { resourceName: this.name, operation: 'replace', id, totalSize, effectiveLimit, excess, suggestion: 'Reduce metadata size or number of fields.' });
+      }
+      throw errPut;
+    }
+
+    // Build the final object to return
+    const replacedObject = { id, ...validatedAttributes };
+
+    // Update partitions if needed
+    if (this.config.partitions && Object.keys(this.config.partitions).length > 0) {
+      if (this.config.asyncPartitions) {
+        // Async mode: update partition indexes in background
+        setImmediate(() => {
+          this.handlePartitionReferenceUpdates({}, replacedObject).catch(err => {
+            this.emit('partitionIndexError', {
+              operation: 'replace',
+              id,
+              error: err
+            });
+          });
+        });
+      } else {
+        // Sync mode: update partition indexes immediately
+        await this.handlePartitionReferenceUpdates({}, replacedObject);
+      }
+    }
+
+    return replacedObject;
+  }
+
   /**
    * Update with conditional check (If-Match ETag)
    * @param {string} id - Resource ID
@@ -2291,7 +2600,7 @@ export class Resource extends AsyncEventEmitter {
 
   /**
    * Get schema for a specific version
-   * @param {string} version - Version string (e.g., 'v0', 'v1')
+   * @param {string} version - Version string (e.g., 'v1', 'v2')
    * @returns {Object} Schema object for the version
    */
   async getSchemaForVersion(version) {
@@ -2785,11 +3094,12 @@ export class Resource extends AsyncEventEmitter {
     const [ok, err, unmapped] = await tryFn(() => this.schema.unmapper(metadata));
     unmappedMetadata = ok ? unmapped : metadata;
     // Helper function to filter out internal S3DB fields
+    // Preserve geo-related fields (_geohash, _geohash_zoom*) for GeoPlugin
     const filterInternalFields = (obj) => {
       if (!obj || typeof obj !== 'object') return obj;
       const filtered = {};
       for (const [key, value] of Object.entries(obj)) {
-        if (!key.startsWith('_')) {
+        if (!key.startsWith('_') || key === '_geohash' || key.startsWith('_geohash_zoom')) {
           filtered[key] = value;
         }
       }
@@ -2865,37 +3175,6 @@ export class Resource extends AsyncEventEmitter {
     return filtered;
   }
 
-
-  async replace(id, attributes) {
-    await this.delete(id);
-    await new Promise(r => setTimeout(r, 100));
-    // Polling para garantir que a key foi removida do S3
-    const maxWait = 5000;
-    const interval = 50;
-    const start = Date.now();
-    let waited = 0;
-    while (Date.now() - start < maxWait) {
-      const exists = await this.exists(id);
-      if (!exists) {
-        break;
-      }
-      await new Promise(r => setTimeout(r, interval));
-      waited = Date.now() - start;
-    }
-    if (waited >= maxWait) {
-    }
-    try {
-      const result = await this.insert({ ...attributes, id });
-      return result;
-    } catch (err) {
-      if (err && err.message && err.message.includes('already exists')) {
-        const result = await this.update(id, attributes);
-        return result;
-      }
-      throw err;
-    }
-  }
-
   // --- MIDDLEWARE SYSTEM ---
   _initMiddleware() {
     // Map of methodName -> array of middleware functions

package/src/s3db.d.ts

@@ -319,6 +319,20 @@ declare module 's3db.js' {
     maxResults?: number;
   }
 
+  /** Geo Plugin resource config */
+  export interface GeoResourceConfig {
+    latField: string;
+    lonField: string;
+    precision?: number;
+    addGeohash?: boolean;
+  }
+
+  /** Geo Plugin config */
+  export interface GeoPluginConfig extends PluginConfig {
+    resources?: Record<string, GeoResourceConfig>;
+    verbose?: boolean;
+  }
+
   /** Metrics Plugin config */
   export interface MetricsPluginConfig extends PluginConfig {
     trackLatency?: boolean;
@@ -709,6 +723,8 @@ declare module 's3db.js' {
     get(id: string): Promise<any>;
     exists(id: string): Promise<boolean>;
     update(id: string, attributes: any): Promise<any>;
+    patch(id: string, fields: any, options?: { partition?: string; partitionValues?: Record<string, any> }): Promise<any>;
+    replace(id: string, fullData: any, options?: { partition?: string; partitionValues?: Record<string, any> }): Promise<any>;
     upsert(data: any): Promise<any>;
     delete(id: string): Promise<void>;
     deleteMany(ids: string[]): Promise<void>;
@@ -827,7 +843,13 @@ declare module 's3db.js' {
     }): Promise<any>;
     getObject(key: string): Promise<any>;
     headObject(key: string): Promise<any>;
-    copyObject(options: { from: string; to: string }): Promise<any>;
+    copyObject(options: {
+      from: string;
+      to: string;
+      metadata?: Record<string, any>;
+      metadataDirective?: 'COPY' | 'REPLACE';
+      contentType?: string;
+    }): Promise<any>;
     exists(key: string): Promise<boolean>;
     deleteObject(key: string): Promise<any>;
     deleteObjects(keys: string[]): Promise<{ deleted: any[]; notFound: any[] }>;
@@ -1016,6 +1038,16 @@ declare module 's3db.js' {
     getIndexStats(): any;
   }
 
+  /** Geo Plugin */
+  export class GeoPlugin extends Plugin {
+    constructor(config?: GeoPluginConfig);
+    encodeGeohash(latitude: number, longitude: number, precision?: number): string;
+    decodeGeohash(geohash: string): { latitude: number; longitude: number; error: { latitude: number; longitude: number } };
+    calculateDistance(lat1: number, lon1: number, lat2: number, lon2: number): number;
+    getNeighbors(geohash: string): string[];
+    getStats(): any;
+  }
+
   /** Metrics Plugin */
   export class MetricsPlugin extends Plugin {
     constructor(config?: MetricsPluginConfig);
@@ -1254,6 +1286,33 @@ declare module 's3db.js' {
   }
 
   /** Resource extensions added by EventualConsistencyPlugin */
+  export interface GeoResourceExtensions {
+    /** Find locations within radius of a point */
+    findNearby(options: {
+      lat: number;
+      lon: number;
+      radius?: number;
+      limit?: number;
+    }): Promise<Array<any & { _distance: number }>>;
+
+    /** Find locations within bounding box */
+    findInBounds(options: {
+      north: number;
+      south: number;
+      east: number;
+      west: number;
+      limit?: number;
+    }): Promise<any[]>;
+
+    /** Get distance between two records */
+    getDistance(id1: string, id2: string): Promise<{
+      distance: number;
+      unit: string;
+      from: string;
+      to: string;
+    }>;
+  }
+
   export interface EventualConsistencyResourceExtensions {
     /** Set field value (replaces current value) */
     set(id: string, field: string, value: number): Promise<number>;
@@ -1264,6 +1323,12 @@ declare module 's3db.js' {
     /** Decrement field value */
     sub(id: string, field: string, amount: number): Promise<number>;
 
+    /** Increment field value by 1 (shorthand for add(id, field, 1)) */
+    increment(id: string, field: string): Promise<number>;
+
+    /** Decrement field value by 1 (shorthand for sub(id, field, 1)) */
+    decrement(id: string, field: string): Promise<number>;
+
     /** Manually trigger consolidation */
     consolidate(id: string, field: string): Promise<number>;