s3db.js 12.0.0 → 12.0.1

package/dist/s3db.d.ts

@@ -723,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>;
@@ -841,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[] }>;

package/dist/s3db.es.js

@@ -27,7 +27,7 @@ import { realpath, readlink, readdir as readdir$1, lstat } from 'node:fs/promise
 import { EventEmitter as EventEmitter$1 } from 'node:events';
 import Stream from 'node:stream';
 import { StringDecoder } from 'node:string_decoder';
-import require$$0 from 'node:crypto';
+import { createRequire } from 'node:module';
 import require$$1 from 'child_process';
 import require$$5 from 'url';
 
@@ -1963,44 +1963,31 @@ class PluginStorage {
    * @returns {Promise<boolean>} True if extended, false if not found or no TTL
    */
   async touch(key, additionalSeconds) {
-    const [ok, err, response] = await tryFn(() => this.client.getObject(key));
+    const [ok, err, response] = await tryFn(() => this.client.headObject(key));
     if (!ok) {
       return false;
     }
     const metadata = response.Metadata || {};
     const parsedMetadata = this._parseMetadataValues(metadata);
-    let data = parsedMetadata;
-    if (response.Body) {
-      const [ok2, err2, result] = await tryFn(async () => {
-        const bodyContent = await response.Body.transformToString();
-        if (bodyContent && bodyContent.trim()) {
-          const body = JSON.parse(bodyContent);
-          return { ...parsedMetadata, ...body };
-        }
-        return parsedMetadata;
-      });
-      if (!ok2) {
-        return false;
-      }
-      data = result;
-    }
-    const expiresAt = data._expiresat || data._expiresAt;
+    const expiresAt = parsedMetadata._expiresat || parsedMetadata._expiresAt;
     if (!expiresAt) {
       return false;
     }
-    data._expiresAt = expiresAt + additionalSeconds * 1e3;
-    delete data._expiresat;
-    const { metadata: newMetadata, body: newBody } = this._applyBehavior(data, "body-overflow");
-    const putParams = {
-      key,
-      metadata: newMetadata,
-      contentType: "application/json"
-    };
-    if (newBody !== null) {
-      putParams.body = JSON.stringify(newBody);
-    }
-    const [putOk] = await tryFn(() => this.client.putObject(putParams));
-    return putOk;
+    parsedMetadata._expiresAt = expiresAt + additionalSeconds * 1e3;
+    delete parsedMetadata._expiresat;
+    const encodedMetadata = {};
+    for (const [metaKey, metaValue] of Object.entries(parsedMetadata)) {
+      const { encoded } = metadataEncode(metaValue);
+      encodedMetadata[metaKey] = encoded;
+    }
+    const [copyOk] = await tryFn(() => this.client.copyObject({
+      from: key,
+      to: key,
+      metadata: encodedMetadata,
+      metadataDirective: "REPLACE",
+      contentType: response.ContentType || "application/json"
+    }));
+    return copyOk;
   }
   /**
    * Delete a single object
@@ -2135,12 +2122,41 @@ class PluginStorage {
   /**
    * Increment a counter value
    *
+   * Optimization: Uses HEAD + COPY for existing counters to avoid body transfer.
+   * Falls back to GET + PUT for non-existent counters or those with additional data.
+   *
    * @param {string} key - S3 key
    * @param {number} amount - Amount to increment (default: 1)
    * @param {Object} options - Options (e.g., ttl)
    * @returns {Promise<number>} New value
    */
   async increment(key, amount = 1, options = {}) {
+    const [headOk, headErr, headResponse] = await tryFn(() => this.client.headObject(key));
+    if (headOk && headResponse.Metadata) {
+      const metadata = headResponse.Metadata || {};
+      const parsedMetadata = this._parseMetadataValues(metadata);
+      const currentValue = parsedMetadata.value || 0;
+      const newValue = currentValue + amount;
+      parsedMetadata.value = newValue;
+      if (options.ttl) {
+        parsedMetadata._expiresAt = Date.now() + options.ttl * 1e3;
+      }
+      const encodedMetadata = {};
+      for (const [metaKey, metaValue] of Object.entries(parsedMetadata)) {
+        const { encoded } = metadataEncode(metaValue);
+        encodedMetadata[metaKey] = encoded;
+      }
+      const [copyOk] = await tryFn(() => this.client.copyObject({
+        from: key,
+        to: key,
+        metadata: encodedMetadata,
+        metadataDirective: "REPLACE",
+        contentType: headResponse.ContentType || "application/json"
+      }));
+      if (copyOk) {
+        return newValue;
+      }
+    }
     const data = await this.get(key);
     const value = (data?.value || 0) + amount;
     await this.set(key, { value }, options);
@@ -19140,7 +19156,17 @@ class Client extends EventEmitter {
       Bucket: this.config.bucket,
       Key: keyPrefix ? path$1.join(keyPrefix, key) : key
     };
-    const [ok, err, response] = await tryFn(() => this.sendCommand(new HeadObjectCommand(options)));
+    const [ok, err, response] = await tryFn(async () => {
+      const res = await this.sendCommand(new HeadObjectCommand(options));
+      if (res.Metadata) {
+        const decodedMetadata = {};
+        for (const [key2, value] of Object.entries(res.Metadata)) {
+          decodedMetadata[key2] = metadataDecode(value);
+        }
+        res.Metadata = decodedMetadata;
+      }
+      return res;
+    });
     this.emit("headObject", err || response, { key });
     if (!ok) {
       throw mapAwsError(err, {
@@ -19152,14 +19178,29 @@ class Client extends EventEmitter {
     }
     return response;
   }
-  async copyObject({ from, to }) {
+  async copyObject({ from, to, metadata, metadataDirective, contentType }) {
+    const keyPrefix = typeof this.config.keyPrefix === "string" ? this.config.keyPrefix : "";
     const options = {
       Bucket: this.config.bucket,
-      Key: this.config.keyPrefix ? path$1.join(this.config.keyPrefix, to) : to,
-      CopySource: path$1.join(this.config.bucket, this.config.keyPrefix ? path$1.join(this.config.keyPrefix, from) : from)
+      Key: keyPrefix ? path$1.join(keyPrefix, to) : to,
+      CopySource: path$1.join(this.config.bucket, keyPrefix ? path$1.join(keyPrefix, from) : from)
     };
+    if (metadataDirective) {
+      options.MetadataDirective = metadataDirective;
+    }
+    if (metadata && typeof metadata === "object") {
+      const encodedMetadata = {};
+      for (const [key, value] of Object.entries(metadata)) {
+        const { encoded } = metadataEncode(value);
+        encodedMetadata[key] = encoded;
+      }
+      options.Metadata = encodedMetadata;
+    }
+    if (contentType) {
+      options.ContentType = contentType;
+    }
     const [ok, err, response] = await tryFn(() => this.sendCommand(new CopyObjectCommand(options)));
-    this.emit("copyObject", err || response, { from, to });
+    this.emit("copyObject", err || response, { from, to, metadataDirective });
     if (!ok) {
       throw mapAwsError(err, {
         bucket: this.config.bucket,
@@ -22362,6 +22403,235 @@ ${errorDetails}`,
       return finalResult;
     }
   }
+  /**
+   * 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;
+    const hasNestedFields = Object.keys(fields).some((key) => key.includes("."));
+    if ((behavior === "enforce-limits" || behavior === "truncate-data") && !hasNestedFields) {
+      return await this._patchViaCopyObject(id, fields, options);
+    }
+    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;
+    const key = this.getResourceKey(id);
+    const headResponse = await this.client.headObject(key);
+    const currentMetadata = headResponse.Metadata || {};
+    let currentData = await this.schema.unmapper(currentMetadata);
+    if (!currentData.id) {
+      currentData.id = id;
+    }
+    const fieldsClone = cloneDeep(fields);
+    let mergedData = cloneDeep(currentData);
+    for (const [key2, value] of Object.entries(fieldsClone)) {
+      if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+        mergedData[key2] = merge({}, mergedData[key2], value);
+      } else {
+        mergedData[key2] = cloneDeep(value);
+      }
+    }
+    if (this.config.timestamps) {
+      mergedData.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+    }
+    const validationResult = await this.schema.validate(mergedData);
+    if (validationResult !== true) {
+      throw new ValidationError("Validation failed during patch", validationResult);
+    }
+    const newMetadata = await this.schema.mapper(mergedData);
+    newMetadata._v = String(this.version);
+    await this.client.copyObject({
+      from: key,
+      to: key,
+      metadataDirective: "REPLACE",
+      metadata: newMetadata
+    });
+    if (this.config.partitions && Object.keys(this.config.partitions).length > 0) {
+      const oldData = { ...currentData, id };
+      const newData = { ...mergedData, id };
+      if (this.config.asyncPartitions) {
+        setImmediate(() => {
+          this.handlePartitionReferenceUpdates(oldData, newData).catch((err) => {
+            this.emit("partitionIndexError", {
+              operation: "patch",
+              id,
+              error: err
+            });
+          });
+        });
+      } else {
+        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;
+    const dataClone = cloneDeep(fullData);
+    const attributesWithDefaults = this.applyDefaults(dataClone);
+    if (this.config.timestamps) {
+      if (!attributesWithDefaults.createdAt) {
+        attributesWithDefaults.createdAt = (/* @__PURE__ */ new Date()).toISOString();
+      }
+      attributesWithDefaults.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+    }
+    const completeData = { id, ...attributesWithDefaults };
+    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
+      });
+    }
+    const { id: validatedId, ...validatedAttributes } = validated;
+    const mappedMetadata = await this.schema.mapper(validatedAttributes);
+    mappedMetadata._v = String(this.version);
+    const behaviorImpl = getBehavior(this.behavior);
+    const { mappedData: finalMetadata, body } = await behaviorImpl.handleInsert({
+      resource: this,
+      data: validatedAttributes,
+      mappedData: mappedMetadata,
+      originalData: completeData
+    });
+    const key = this.getResourceKey(id);
+    let contentType = void 0;
+    if (body && body !== "") {
+      const [okParse] = await tryFn(() => Promise.resolve(JSON.parse(body)));
+      if (okParse) contentType = "application/json";
+    }
+    if (this.behavior === "body-only" && (!body || body === "")) {
+      throw new Error(`[Resource.replace] Attempt to save object without body! Data: id=${id}, resource=${this.name}`);
+    }
+    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;
+    }
+    const replacedObject = { id, ...validatedAttributes };
+    if (this.config.partitions && Object.keys(this.config.partitions).length > 0) {
+      if (this.config.asyncPartitions) {
+        setImmediate(() => {
+          this.handlePartitionReferenceUpdates({}, replacedObject).catch((err) => {
+            this.emit("partitionIndexError", {
+              operation: "replace",
+              id,
+              error: err
+            });
+          });
+        });
+      } else {
+        await this.handlePartitionReferenceUpdates({}, replacedObject);
+      }
+    }
+    return replacedObject;
+  }
   /**
    * Update with conditional check (If-Match ETag)
    * @param {string} id - Resource ID
@@ -23710,29 +23980,6 @@ ${errorDetails}`,
     }
     return filtered;
   }
-  async replace(id, attributes) {
-    await this.delete(id);
-    await new Promise((r) => setTimeout(r, 100));
-    const maxWait = 5e3;
-    const interval = 50;
-    const start = Date.now();
-    while (Date.now() - start < maxWait) {
-      const exists = await this.exists(id);
-      if (!exists) {
-        break;
-      }
-      await new Promise((r) => setTimeout(r, interval));
-    }
-    const [ok, err, result] = await tryFn(() => this.insert({ ...attributes, id }));
-    if (!ok) {
-      if (err && err.message && err.message.includes("already exists")) {
-        const updateResult = await this.update(id, attributes);
-        return updateResult;
-      }
-      throw err;
-    }
-    return result;
-  }
   // --- MIDDLEWARE SYSTEM ---
   _initMiddleware() {
     this._middlewares = /* @__PURE__ */ new Map();
@@ -23934,7 +24181,7 @@ class Database extends EventEmitter {
     this.id = idGenerator(7);
     this.version = "1";
     this.s3dbVersion = (() => {
-      const [ok, err, version] = tryFn(() => true ? "12.0.0" : "latest");
+      const [ok, err, version] = tryFn(() => true ? "12.0.1" : "latest");
       return ok ? version : "latest";
     })();
     this.resources = {};
@@ -26804,7 +27051,7 @@ class ReplicatorPlugin extends Plugin {
   async updateReplicatorLog(logId, updates) {
     if (!this.replicatorLog) return;
     const [ok, err] = await tryFn(async () => {
-      await this.replicatorLog.update(logId, {
+      await this.replicatorLog.patch(logId, {
         ...updates,
         lastAttempt: (/* @__PURE__ */ new Date()).toISOString()
       });
@@ -39784,6 +40031,9 @@ var runner = {};
 
 var createId = {};
 
+const require = createRequire(import.meta.url);
+function __require() { return require("node:crypto"); }
+
 var hasRequiredCreateId;
 
 function requireCreateId () {
@@ -39794,7 +40044,7 @@ function requireCreateId () {
 	};
 	Object.defineProperty(createId, "__esModule", { value: true });
 	createId.createID = createID;
-	const node_crypto_1 = __importDefault(require$$0);
+	const node_crypto_1 = __importDefault(__require());
 	function createID(prefix = '', length = 16) {
 	    const charset = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
 	    const values = node_crypto_1.default.randomBytes(length);