s3db.js 11.3.2 → 12.0.1

package/src/concerns/money.js

@@ -0,0 +1,193 @@
+/**
+ * Money Encoding/Decoding - Integer-based (Banking Standard)
+ *
+ * IMPORTANT: Money should NEVER use floats/decimals due to precision errors.
+ * Always store as integers in smallest currency unit (cents, satoshis, etc).
+ *
+ * Examples:
+ *   $19.99 USD → 1999 cents → encoded as "$w7"
+ *   0.00012345 BTC → 12345 satoshis → encoded as "$3d9"
+ *
+ * Benefits:
+ * - Zero precision loss (no 0.1 + 0.2 = 0.30000004 bugs)
+ * - Faster integer arithmetic
+ * - Banking industry standard
+ * - 40-67% compression vs JSON floats
+ */
+
+import { encode, decode } from './base62.js';
+
+/**
+ * Currency decimal places (number of decimals in smallest unit)
+ *
+ * Fiat currencies:
+ * - Most: 2 decimals (cents)
+ * - Some: 0 decimals (yen, won)
+ *
+ * Cryptocurrencies:
+ * - BTC: 8 decimals (satoshis)
+ * - ETH: 18 decimals (wei) - but commonly use 9 (gwei)
+ * - Stablecoins: 6-8 decimals
+ */
+export const CURRENCY_DECIMALS = {
+  // Fiat with cents (2 decimals)
+  'USD': 2, 'BRL': 2, 'EUR': 2, 'GBP': 2, 'CAD': 2, 'AUD': 2,
+  'MXN': 2, 'ARS': 2, 'COP': 2, 'PEN': 2, 'UYU': 2,
+  'CHF': 2, 'SEK': 2, 'NOK': 2, 'DKK': 2, 'PLN': 2, 'CZK': 2,
+  'HUF': 2, 'RON': 2, 'BGN': 2, 'HRK': 2, 'RSD': 2, 'TRY': 2,
+  'ZAR': 2, 'EGP': 2, 'NGN': 2, 'KES': 2, 'GHS': 2,
+  'INR': 2, 'PKR': 2, 'BDT': 2, 'LKR': 2, 'NPR': 2,
+  'THB': 2, 'MYR': 2, 'SGD': 2, 'PHP': 2, 'IDR': 2,
+  'CNY': 2, 'HKD': 2, 'TWD': 2,
+  'ILS': 2, 'SAR': 2, 'AED': 2, 'QAR': 2, 'KWD': 3,
+  'RUB': 2, 'UAH': 2, 'KZT': 2,
+
+  // Fiat without decimals
+  'JPY': 0,  // Japanese Yen
+  'KRW': 0,  // Korean Won
+  'VND': 0,  // Vietnamese Dong
+  'CLP': 0,  // Chilean Peso
+  'ISK': 0,  // Icelandic Króna
+  'PYG': 0,  // Paraguayan Guaraní
+
+  // Cryptocurrencies
+  'BTC': 8,   // Bitcoin (satoshis)
+  'ETH': 18,  // Ethereum (wei) - often use 9 for gwei
+  'GWEI': 9,  // Ethereum gwei (common unit)
+  'USDT': 6,  // Tether
+  'USDC': 6,  // USD Coin
+  'BUSD': 18, // Binance USD
+  'DAI': 18,  // Dai
+  'BNB': 18,  // Binance Coin
+  'XRP': 6,   // Ripple
+  'ADA': 6,   // Cardano
+  'SOL': 9,   // Solana
+  'MATIC': 18, // Polygon
+  'AVAX': 18, // Avalanche
+  'DOT': 10,  // Polkadot
+  'LINK': 18, // Chainlink
+  'UNI': 18,  // Uniswap
+};
+
+/**
+ * Get decimal places for a currency
+ * @param {string} currency - Currency code (e.g., 'USD', 'BTC')
+ * @returns {number} Number of decimal places
+ */
+export function getCurrencyDecimals(currency) {
+  const normalized = currency.toUpperCase();
+  return CURRENCY_DECIMALS[normalized] ?? 2; // Default to 2 (cents)
+}
+
+/**
+ * Encode money value to integer-based base62
+ *
+ * @param {number} value - Decimal value (e.g., 19.99)
+ * @param {string} currency - Currency code (default: 'USD')
+ * @returns {string} Encoded string with '$' prefix
+ *
+ * @throws {Error} If value is negative
+ *
+ * @example
+ * encodeMoney(19.99, 'USD')     // → "$w7" (1999 cents)
+ * encodeMoney(1000.50, 'BRL')   // → "$6Dl" (100050 centavos)
+ * encodeMoney(0.00012345, 'BTC') // → "$3d9" (12345 satoshis)
+ */
+export function encodeMoney(value, currency = 'USD') {
+  if (value === null || value === undefined) return value;
+  if (typeof value !== 'number' || isNaN(value)) return value;
+  if (!isFinite(value)) return value;
+
+  // Money cannot be negative (validation should happen at schema level)
+  if (value < 0) {
+    throw new Error(`Money value cannot be negative: ${value}`);
+  }
+
+  const decimals = getCurrencyDecimals(currency);
+  const multiplier = Math.pow(10, decimals);
+
+  // Convert to smallest unit (cents, satoshis, wei, etc)
+  // Use Math.round to handle floating point precision issues
+  const integerValue = Math.round(value * multiplier);
+
+  // Encode as pure integer using base62
+  return '$' + encode(integerValue);
+}
+
+/**
+ * Decode money from base62 to decimal value
+ *
+ * @param {string} encoded - Encoded string (must start with '$')
+ * @param {string} currency - Currency code (default: 'USD')
+ * @returns {number} Decoded decimal value
+ *
+ * @example
+ * decodeMoney('$w7', 'USD')     // → 19.99
+ * decodeMoney('$6Dl', 'BRL')    // → 1000.50
+ * decodeMoney('$3d9', 'BTC')    // → 0.00012345
+ */
+export function decodeMoney(encoded, currency = 'USD') {
+  if (typeof encoded !== 'string') return encoded;
+  if (!encoded.startsWith('$')) return encoded;
+
+  const integerValue = decode(encoded.slice(1));
+  if (isNaN(integerValue)) return NaN;
+
+  const decimals = getCurrencyDecimals(currency);
+  const divisor = Math.pow(10, decimals);
+
+  // Convert back to decimal
+  return integerValue / divisor;
+}
+
+/**
+ * Validate if a currency code is supported
+ * @param {string} currency - Currency code
+ * @returns {boolean} True if supported
+ */
+export function isSupportedCurrency(currency) {
+  const normalized = currency.toUpperCase();
+  return normalized in CURRENCY_DECIMALS;
+}
+
+/**
+ * Get list of all supported currencies
+ * @returns {string[]} Array of currency codes
+ */
+export function getSupportedCurrencies() {
+  return Object.keys(CURRENCY_DECIMALS);
+}
+
+/**
+ * Format money value for display
+ * @param {number} value - Decimal value
+ * @param {string} currency - Currency code
+ * @param {string} locale - Locale for formatting (default: 'en-US')
+ * @returns {string} Formatted money string
+ *
+ * @example
+ * formatMoney(19.99, 'USD')     // → "$19.99"
+ * formatMoney(1000.50, 'BRL', 'pt-BR')  // → "R$ 1.000,50"
+ * formatMoney(0.00012345, 'BTC') // → "0.00012345 BTC"
+ */
+export function formatMoney(value, currency = 'USD', locale = 'en-US') {
+  const decimals = getCurrencyDecimals(currency);
+
+  // For fiat currencies, use Intl.NumberFormat
+  if (decimals <= 3 && currency !== 'BTC' && !currency.includes('USDT')) {
+    try {
+      return new Intl.NumberFormat(locale, {
+        style: 'currency',
+        currency: currency,
+        minimumFractionDigits: decimals,
+        maximumFractionDigits: decimals
+      }).format(value);
+    } catch (err) {
+      // Fallback for unsupported currencies
+      return `${value.toFixed(decimals)} ${currency}`;
+    }
+  }
+
+  // For crypto, just show the value with correct decimals
+  return `${value.toFixed(decimals)} ${currency}`;
+}

package/src/concerns/partition-queue.js

@@ -1,5 +1,6 @@
 import { EventEmitter } from 'events';
 import { PartitionDriverError } from '../errors.js';
+import tryFn from './try-fn.js';
 
 /**
  * Robust partition operation queue with retry and persistence
@@ -52,17 +53,19 @@ export class PartitionQueue extends EventEmitter {
     
     while (this.queue.length > 0) {
       const item = this.queue.shift();
-      
-      try {
+
+      const [ok, error] = await tryFn(async () => {
         await this.executeOperation(item);
         item.status = 'completed';
         this.emit('success', item);
-        
+
         // Remove from persistence
         if (this.persistence) {
           await this.persistence.remove(item.id);
         }
-      } catch (error) {
+      });
+
+      if (!ok) {
         item.retries++;
         item.lastError = error;
         

package/src/concerns/plugin-storage.js

@@ -174,16 +174,19 @@ export class PluginStorage {
 
     // If has body, merge with metadata
     if (response.Body) {
-      try {
+      const [ok, parseErr, result] = await tryFn(async () => {
         const bodyContent = await response.Body.transformToString();
 
         // Only parse if body has content
         if (bodyContent && bodyContent.trim()) {
           const body = JSON.parse(bodyContent);
           // Body takes precedence over metadata for same keys
-          data = { ...parsedMetadata, ...body };
+          return { ...parsedMetadata, ...body };
         }
-      } catch (parseErr) {
+        return parsedMetadata;
+      });
+
+      if (!ok) {
         throw new PluginStorageError(`Failed to parse JSON body`, {
           pluginSlug: this.pluginSlug,
           key,
@@ -192,6 +195,8 @@ export class PluginStorage {
           suggestion: 'Body content may be corrupted. Check S3 object integrity'
         });
       }
+
+      data = result;
     }
 
     // Check TTL expiration (S3 lowercases metadata keys)
@@ -224,12 +229,12 @@ export class PluginStorage {
           (value.startsWith('{') && value.endsWith('}')) ||
           (value.startsWith('[') && value.endsWith(']'))
         ) {
-          try {
-            parsed[key] = JSON.parse(value);
+          const [ok, err, result] = tryFn(() => JSON.parse(value));
+          if (ok) {
+            parsed[key] = result;
             continue;
-          } catch {
-            // Not JSON, keep as string
           }
+          // Not JSON, keep as string
         }
 
         // Try to parse as number
@@ -373,15 +378,20 @@ export class PluginStorage {
     let data = parsedMetadata;
 
     if (response.Body) {
-      try {
+      const [ok, err, result] = await tryFn(async () => {
         const bodyContent = await response.Body.transformToString();
         if (bodyContent && bodyContent.trim()) {
           const body = JSON.parse(bodyContent);
-          data = { ...parsedMetadata, ...body };
+          return { ...parsedMetadata, ...body };
         }
-      } catch {
-        return true;
+        return parsedMetadata;
+      });
+
+      if (!ok) {
+        return true; // Parse error = expired
       }
+
+      data = result;
     }
 
     // S3 lowercases metadata keys
@@ -412,15 +422,20 @@ export class PluginStorage {
     let data = parsedMetadata;
 
     if (response.Body) {
-      try {
+      const [ok, err, result] = await tryFn(async () => {
         const bodyContent = await response.Body.transformToString();
         if (bodyContent && bodyContent.trim()) {
           const body = JSON.parse(bodyContent);
-          data = { ...parsedMetadata, ...body };
+          return { ...parsedMetadata, ...body };
         }
-      } catch {
-        return null;
+        return parsedMetadata;
+      });
+
+      if (!ok) {
+        return null; // Parse error
       }
+
+      data = result;
     }
 
     // S3 lowercases metadata keys
@@ -441,7 +456,9 @@ export 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));
+    // Optimization: Use HEAD + COPY instead of GET + PUT for metadata-only updates
+    // This avoids transferring the body when only updating the TTL
+    const [ok, err, response] = await tryFn(() => this.client.headObject(key));
 
     if (!ok) {
       return false;
@@ -450,45 +467,34 @@ export class PluginStorage {
     const metadata = response.Metadata || {};
     const parsedMetadata = this._parseMetadataValues(metadata);
 
-    let data = parsedMetadata;
-
-    if (response.Body) {
-      try {
-        const bodyContent = await response.Body.transformToString();
-        if (bodyContent && bodyContent.trim()) {
-          const body = JSON.parse(bodyContent);
-          data = { ...parsedMetadata, ...body };
-        }
-      } catch {
-        return false;
-      }
-    }
-
     // S3 lowercases metadata keys
-    const expiresAt = data._expiresat || data._expiresAt;
+    const expiresAt = parsedMetadata._expiresat || parsedMetadata._expiresAt;
     if (!expiresAt) {
       return false; // No TTL to extend
     }
 
     // Extend TTL - use the standard field name (will be lowercased by S3)
-    data._expiresAt = expiresAt + (additionalSeconds * 1000);
-    delete data._expiresat; // Remove lowercased version
-
-    // Save back (reuse same behavior)
-    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);
+    parsedMetadata._expiresAt = expiresAt + (additionalSeconds * 1000);
+    delete parsedMetadata._expiresat; // Remove lowercased version
+
+    // Encode metadata for S3
+    const encodedMetadata = {};
+    for (const [metaKey, metaValue] of Object.entries(parsedMetadata)) {
+      const { encoded } = metadataEncode(metaValue);
+      encodedMetadata[metaKey] = encoded;
     }
 
-    const [putOk] = await tryFn(() => this.client.putObject(putParams));
-    return putOk;
+    // Use COPY with MetadataDirective: REPLACE to update metadata atomically
+    // This preserves the body without re-transferring it
+    const [copyOk] = await tryFn(() => this.client.copyObject({
+      from: key,
+      to: key,
+      metadata: encodedMetadata,
+      metadataDirective: 'REPLACE',
+      contentType: response.ContentType || 'application/json'
+    }));
+
+    return copyOk;
   }
 
   /**
@@ -655,12 +661,56 @@ export 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 = {}) {
+    // Try optimized path first: HEAD + COPY for existing counters
+    const [headOk, headErr, headResponse] = await tryFn(() => this.client.headObject(key));
+
+    if (headOk && headResponse.Metadata) {
+      // Counter exists, use optimized HEAD + COPY
+      const metadata = headResponse.Metadata || {};
+      const parsedMetadata = this._parseMetadataValues(metadata);
+
+      const currentValue = parsedMetadata.value || 0;
+      const newValue = currentValue + amount;
+
+      // Update only the value field
+      parsedMetadata.value = newValue;
+
+      // Handle TTL if specified
+      if (options.ttl) {
+        parsedMetadata._expiresAt = Date.now() + (options.ttl * 1000);
+      }
+
+      // Encode metadata
+      const encodedMetadata = {};
+      for (const [metaKey, metaValue] of Object.entries(parsedMetadata)) {
+        const { encoded } = metadataEncode(metaValue);
+        encodedMetadata[metaKey] = encoded;
+      }
+
+      // Atomic update via COPY
+      const [copyOk] = await tryFn(() => this.client.copyObject({
+        from: key,
+        to: key,
+        metadata: encodedMetadata,
+        metadataDirective: 'REPLACE',
+        contentType: headResponse.ContentType || 'application/json'
+      }));
+
+      if (copyOk) {
+        return newValue;
+      }
+    }
+
+    // Fallback: counter doesn't exist or has body data, use traditional path
     const data = await this.get(key);
     const value = (data?.value || 0) + amount;
     await this.set(key, { value }, options);