s3db.js 6.1.0 → 7.0.0

package/src/concerns/calculator.js

@@ -0,0 +1,204 @@
+/**
+ * Calculates the size in bytes of a string using UTF-8 encoding
+ * @param {string} str - The string to calculate size for
+ * @returns {number} - Size in bytes
+ */
+export function calculateUTF8Bytes(str) {
+  if (typeof str !== 'string') {
+    str = String(str);
+  }
+  
+  let bytes = 0;
+  for (let i = 0; i < str.length; i++) {
+    const codePoint = str.codePointAt(i);
+    
+    if (codePoint <= 0x7F) {
+      // 1 byte: U+0000 to U+007F (ASCII characters)
+      bytes += 1;
+    } else if (codePoint <= 0x7FF) {
+      // 2 bytes: U+0080 to U+07FF
+      bytes += 2;
+    } else if (codePoint <= 0xFFFF) {
+      // 3 bytes: U+0800 to U+FFFF
+      bytes += 3;
+    } else if (codePoint <= 0x10FFFF) {
+      // 4 bytes: U+10000 to U+10FFFF
+      bytes += 4;
+      // Skip the next character if it's a surrogate pair
+      if (codePoint > 0xFFFF) {
+        i++;
+      }
+    }
+  }
+  
+  return bytes;
+}
+
+/**
+ * Calculates the size in bytes of attribute names (mapped to digits)
+ * @param {Object} mappedObject - The object returned by schema.mapper()
+ * @returns {number} - Total size of attribute names in bytes
+ */
+export function calculateAttributeNamesSize(mappedObject) {
+  let totalSize = 0;
+  
+  for (const key of Object.keys(mappedObject)) {
+    totalSize += calculateUTF8Bytes(key);
+  }
+  
+  return totalSize;
+}
+
+/**
+ * Transforms a value according to the schema mapper rules
+ * @param {any} value - The value to transform
+ * @returns {string} - The transformed value as string
+ */
+export function transformValue(value) {
+  if (value === null || value === undefined) {
+    return '';
+  }
+  
+  if (typeof value === 'boolean') {
+    return value ? '1' : '0';
+  }
+  
+  if (typeof value === 'number') {
+    return String(value);
+  }
+  
+  if (typeof value === 'string') {
+    return value;
+  }
+  
+  if (Array.isArray(value)) {
+    // Handle arrays like in the schema mapper
+    if (value.length === 0) {
+      return '[]';
+    }
+    // For simplicity, join with | separator like in the schema
+    return value.map(item => String(item)).join('|');
+  }
+  
+  if (typeof value === 'object') {
+    return JSON.stringify(value);
+  }
+  
+  return String(value);
+}
+
+/**
+ * Calculates the size in bytes of each attribute in a mapped object
+ * @param {Object} mappedObject - The object returned by schema.mapper()
+ * @returns {Object} - Object with attribute names as keys and byte sizes as values
+ */
+export function calculateAttributeSizes(mappedObject) {
+  const sizes = {};
+  
+  for (const [key, value] of Object.entries(mappedObject)) {
+    const transformedValue = transformValue(value);
+    const byteSize = calculateUTF8Bytes(transformedValue);
+    sizes[key] = byteSize;
+  }
+  
+  return sizes;
+}
+
+/**
+ * Calculates the total size in bytes of a mapped object (including attribute names)
+ * @param {Object} mappedObject - The object returned by schema.mapper()
+ * @returns {number} - Total size in bytes
+ */
+export function calculateTotalSize(mappedObject) {
+  const valueSizes = calculateAttributeSizes(mappedObject);
+  const valueTotal = Object.values(valueSizes).reduce((total, size) => total + size, 0);
+  
+  // Add the size of attribute names (digits)
+  const namesSize = calculateAttributeNamesSize(mappedObject);
+  
+  return valueTotal + namesSize;
+}
+
+/**
+ * Gets detailed size information for a mapped object
+ * @param {Object} mappedObject - The object returned by schema.mapper()
+ * @returns {Object} - Object with sizes, total, and breakdown information
+ */
+export function getSizeBreakdown(mappedObject) {
+  const valueSizes = calculateAttributeSizes(mappedObject);
+  const namesSize = calculateAttributeNamesSize(mappedObject);
+  
+  const valueTotal = Object.values(valueSizes).reduce((sum, size) => sum + size, 0);
+  const total = valueTotal + namesSize;
+  
+  // Sort attributes by size (largest first)
+  const sortedAttributes = Object.entries(valueSizes)
+    .sort(([, a], [, b]) => b - a)
+    .map(([key, size]) => ({
+      attribute: key,
+      size,
+      percentage: ((size / total) * 100).toFixed(2) + '%'
+    }));
+  
+  return {
+    total,
+    valueSizes,
+    namesSize,
+    valueTotal,
+    breakdown: sortedAttributes,
+    // Add detailed breakdown including names
+    detailedBreakdown: {
+      values: valueTotal,
+      names: namesSize,
+      total: total
+    }
+  };
+}
+
+/**
+ * Calculates the minimum overhead required for system fields
+ * @param {Object} config - Configuration object
+ * @param {string} [config.version='1'] - Resource version
+ * @param {boolean} [config.timestamps=false] - Whether timestamps are enabled
+ * @param {string} [config.id=''] - Resource ID (if known)
+ * @returns {number} - Minimum overhead in bytes
+ */
+export function calculateSystemOverhead(config = {}) {
+  const { version = '1', timestamps = false, id = '' } = config;
+  
+  // System fields that are always present
+  const systemFields = {
+    '_v': String(version), // Version field (e.g., "1", "10", "100")
+  };
+  
+  // Optional system fields
+  if (timestamps) {
+    systemFields.createdAt = '2024-01-01T00:00:00.000Z'; // Example timestamp
+    systemFields.updatedAt = '2024-01-01T00:00:00.000Z'; // Example timestamp
+  }
+  
+  if (id) {
+    systemFields.id = id;
+  }
+  
+  // Calculate overhead for system fields
+  const overheadObject = {};
+  for (const [key, value] of Object.entries(systemFields)) {
+    overheadObject[key] = value;
+  }
+  
+  return calculateTotalSize(overheadObject);
+}
+
+/**
+ * Calculates the effective metadata limit considering system overhead
+ * @param {Object} config - Configuration object
+ * @param {number} [config.s3Limit=2048] - S3 metadata limit in bytes
+ * @param {Object} [config.systemConfig] - System configuration for overhead calculation
+ * @returns {number} - Effective limit in bytes
+ */
+export function calculateEffectiveLimit(config = {}) {
+  const { s3Limit = 2048, systemConfig = {} } = config;
+  const overhead = calculateSystemOverhead(systemConfig);
+  return s3Limit - overhead;
+}

package/src/concerns/crypto.js

@@ -0,0 +1,142 @@
+import { CryptoError } from "../errors.js";
+import tryFn, { tryFnSync } from "./try-fn.js";
+
+async function dynamicCrypto() {
+  let lib;
+
+  if (typeof process !== 'undefined') {
+    const [ok, err, result] = await tryFn(async () => {
+      const { webcrypto } = await import('crypto');
+      return webcrypto;
+    });
+    if (ok) {
+      lib = result;
+    } else {
+      throw new CryptoError('Crypto API not available', { original: err, context: 'dynamicCrypto' });
+    }
+  } else if (typeof window !== 'undefined') {
+    lib = window.crypto;
+  }
+
+  if (!lib) throw new CryptoError('Could not load any crypto library', { context: 'dynamicCrypto' });
+  return lib;
+}
+
+export async function sha256(message) {
+  const [okCrypto, errCrypto, cryptoLib] = await tryFn(dynamicCrypto);
+  if (!okCrypto) throw new CryptoError('Crypto API not available', { original: errCrypto });
+
+  const encoder = new TextEncoder();
+  const data = encoder.encode(message);
+  const [ok, err, hashBuffer] = await tryFn(() => cryptoLib.subtle.digest('SHA-256', data));
+  if (!ok) throw new CryptoError('SHA-256 digest failed', { original: err, input: message });
+
+  // Convert buffer to hex string
+  const hashArray = Array.from(new Uint8Array(hashBuffer));
+  const hashHex = hashArray.map(b => b.toString(16).padStart(2, '0')).join('');
+
+  return hashHex;
+}
+
+export async function encrypt(content, passphrase) {
+  const [okCrypto, errCrypto, cryptoLib] = await tryFn(dynamicCrypto);
+  if (!okCrypto) throw new CryptoError('Crypto API not available', { original: errCrypto });
+
+  const salt = cryptoLib.getRandomValues(new Uint8Array(16)); // Generate a random salt
+  const [okKey, errKey, key] = await tryFn(() => getKeyMaterial(passphrase, salt));
+  if (!okKey) throw new CryptoError('Key derivation failed', { original: errKey, passphrase, salt });
+
+  const iv = cryptoLib.getRandomValues(new Uint8Array(12)); // 12-byte IV for AES-GCM
+
+  const encoder = new TextEncoder();
+  const encodedContent = encoder.encode(content);
+
+  const [okEnc, errEnc, encryptedContent] = await tryFn(() => cryptoLib.subtle.encrypt({ name: 'AES-GCM', iv: iv }, key, encodedContent));
+  if (!okEnc) throw new CryptoError('Encryption failed', { original: errEnc, content });
+
+  const encryptedData = new Uint8Array(salt.length + iv.length + encryptedContent.byteLength);
+  encryptedData.set(salt); // Prepend salt
+  encryptedData.set(iv, salt.length); // Prepend IV after salt
+  encryptedData.set(new Uint8Array(encryptedContent), salt.length + iv.length); // Append encrypted content
+
+  return arrayBufferToBase64(encryptedData);
+}
+
+export async function decrypt(encryptedBase64, passphrase) {
+  const [okCrypto, errCrypto, cryptoLib] = await tryFn(dynamicCrypto);
+  if (!okCrypto) throw new CryptoError('Crypto API not available', { original: errCrypto });
+
+  const encryptedData = base64ToArrayBuffer(encryptedBase64);
+
+  const salt = encryptedData.slice(0, 16); // Extract salt (first 16 bytes)
+  const iv = encryptedData.slice(16, 28); // Extract IV (next 12 bytes)
+  const encryptedContent = encryptedData.slice(28); // Remaining is the encrypted content
+
+  const [okKey, errKey, key] = await tryFn(() => getKeyMaterial(passphrase, salt));
+  if (!okKey) throw new CryptoError('Key derivation failed (decrypt)', { original: errKey, passphrase, salt });
+
+  const [okDec, errDec, decryptedContent] = await tryFn(() => cryptoLib.subtle.decrypt({ name: 'AES-GCM', iv: iv }, key, encryptedContent));
+  if (!okDec) throw new CryptoError('Decryption failed', { original: errDec, encryptedBase64 });
+
+  const decoder = new TextDecoder();
+  return decoder.decode(decryptedContent);
+}
+
+async function getKeyMaterial(passphrase, salt) {
+  const [okCrypto, errCrypto, cryptoLib] = await tryFn(dynamicCrypto);
+  if (!okCrypto) throw new CryptoError('Crypto API not available', { original: errCrypto });
+
+  const encoder = new TextEncoder();
+  const keyMaterial = encoder.encode(passphrase); // Convert passphrase to bytes
+
+  const [okImport, errImport, baseKey] = await tryFn(() => cryptoLib.subtle.importKey(
+    'raw',
+    keyMaterial,
+    { name: 'PBKDF2' },
+    false,
+    ['deriveKey']
+  ));
+  if (!okImport) throw new CryptoError('importKey failed', { original: errImport, passphrase });
+
+  const [okDerive, errDerive, derivedKey] = await tryFn(() => cryptoLib.subtle.deriveKey(
+    {
+      name: 'PBKDF2',
+      salt: salt,
+      iterations: 100000,
+      hash: 'SHA-256'
+    },
+    baseKey,
+    { name: 'AES-GCM', length: 256 },
+    true,
+    ['encrypt', 'decrypt']
+  ));
+  if (!okDerive) throw new CryptoError('deriveKey failed', { original: errDerive, passphrase, salt });
+  return derivedKey;
+}
+
+function arrayBufferToBase64(buffer) {
+  if (typeof process !== 'undefined') {
+    // Node.js version
+    return Buffer.from(buffer).toString('base64');
+  } else {
+    // Browser version
+    const [ok, err, binary] = tryFnSync(() => String.fromCharCode.apply(null, new Uint8Array(buffer)));
+    if (!ok) throw new CryptoError('Failed to convert ArrayBuffer to base64 (browser)', { original: err });
+    return window.btoa(binary);
+  }
+}
+
+function base64ToArrayBuffer(base64) {
+  if (typeof process !== 'undefined') {
+    return new Uint8Array(Buffer.from(base64, 'base64'));
+  } else {
+    const [ok, err, binaryString] = tryFnSync(() => window.atob(base64));
+    if (!ok) throw new CryptoError('Failed to decode base64 (browser)', { original: err });
+    const len = binaryString.length;
+    const bytes = new Uint8Array(len);
+    for (let i = 0; i < len; i++) {
+      bytes[i] = binaryString.charCodeAt(i);
+    }
+    return bytes;
+  }
+}

package/src/concerns/id.js

@@ -0,0 +1,8 @@
+import { customAlphabet, urlAlphabet } from 'nanoid'
+
+export const idGenerator = customAlphabet(urlAlphabet, 22)
+
+// Password generator using nanoid with custom alphabet for better readability
+// Excludes similar characters (0, O, 1, l, I) to avoid confusion
+const passwordAlphabet = 'ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz23456789'
+export const passwordGenerator = customAlphabet(passwordAlphabet, 16)

package/src/concerns/index.js

@@ -0,0 +1,5 @@
+export * from './base62.js';
+export * from './calculator.js'; 
+export * from './crypto.js';
+export * from './id.js';
+export * from './try-fn.js';

package/src/concerns/try-fn.js

@@ -0,0 +1,151 @@
+/**
+ * tryFn - A robust error handling utility for JavaScript functions and values.
+ * 
+ * This utility provides a consistent way to handle errors and return values across different types:
+ * - Synchronous functions
+ * - Asynchronous functions (Promises)
+ * - Direct values
+ * - Promises
+ * - null/undefined values
+ *
+ * @param {Function|Promise|*} fnOrPromise - The input to process, can be:
+ *   - A synchronous function that returns a value
+ *   - An async function that returns a Promise
+ *   - A Promise directly
+ *   - Any direct value (number, string, object, etc)
+ * 
+ * @returns {Array} A tuple containing:
+ *   - [0] ok: boolean - Indicates if the operation succeeded
+ *   - [1] err: Error|null - Error object if failed, null if succeeded
+ *   - [2] data: any - The result data if succeeded, undefined if failed
+ *
+ * Key Features:
+ * - Unified error handling interface for all types of operations
+ * - Preserves and enhances error stack traces for better debugging
+ * - Zero dependencies
+ * - TypeScript friendly return tuple
+ * - Handles edge cases like null/undefined gracefully
+ * - Perfect for functional programming patterns
+ * - Ideal for Promise chains and async/await flows
+ * - Reduces try/catch boilerplate code
+ *
+ * Error Handling:
+ * - All errors maintain their original properties
+ * - Stack traces are automatically enhanced to show the tryFn call site
+ * - Errors from async operations are properly caught and formatted
+ * 
+ * Common Use Cases:
+ * - API request wrappers
+ * - Database operations
+ * - File system operations
+ * - Data parsing and validation
+ * - Service integration points
+ * 
+ * Examples:
+ * ```js
+ * // Handling synchronous operations
+ * const [ok, err, data] = tryFn(() => JSON.parse(jsonString));
+ * 
+ * // Handling async operations
+ * const [ok, err, data] = await tryFn(async () => {
+ *   const response = await fetch(url);
+ *   return response.json();
+ * });
+ * 
+ * // Direct promise handling
+ * const [ok, err, data] = await tryFn(fetch(url));
+ * 
+ * // Value passthrough
+ * const [ok, err, data] = tryFn(42); // [true, null, 42]
+ * ```
+ */
+export function tryFn(fnOrPromise) {
+  if (fnOrPromise == null) {
+    const err = new Error('fnOrPromise cannot be null or undefined');
+    err.stack = new Error().stack;
+    return [false, err, undefined];
+  }
+
+  if (typeof fnOrPromise === 'function') {
+    try {
+      const result = fnOrPromise();
+
+      if (result == null) {
+        return [true, null, result];
+      }
+
+      if (typeof result.then === 'function') {
+        return result
+          .then(data => [true, null, data])
+          .catch(error => {
+            if (
+              error instanceof Error &&
+              Object.isExtensible(error)
+            ) {
+              const desc = Object.getOwnPropertyDescriptor(error, 'stack');
+              if (
+                desc && desc.writable && desc.configurable && error.hasOwnProperty('stack')
+              ) {
+                try {
+                  error.stack = new Error().stack;
+                } catch (_) {}
+              }
+            }
+            return [false, error, undefined];
+          });
+      }
+
+      return [true, null, result];
+
+    } catch (error) {
+      if (
+        error instanceof Error &&
+        Object.isExtensible(error)
+      ) {
+        const desc = Object.getOwnPropertyDescriptor(error, 'stack');
+        if (
+          desc && desc.writable && desc.configurable && error.hasOwnProperty('stack')
+        ) {
+          try {
+            error.stack = new Error().stack;
+          } catch (_) {}
+        }
+      }
+      return [false, error, undefined];
+    }
+  }
+
+  if (typeof fnOrPromise.then === 'function') {
+    return Promise.resolve(fnOrPromise)
+      .then(data => [true, null, data])
+      .catch(error => {
+        if (
+          error instanceof Error &&
+          Object.isExtensible(error)
+        ) {
+          const desc = Object.getOwnPropertyDescriptor(error, 'stack');
+          if (
+            desc && desc.writable && desc.configurable && error.hasOwnProperty('stack')
+          ) {
+            try {
+              error.stack = new Error().stack;
+            } catch (_) {}
+          }
+        }
+        return [false, error, undefined];
+      });
+  }
+
+  return [true, null, fnOrPromise];
+}
+
+export function tryFnSync(fn) {
+  try {
+    const result = fn();
+    return [true, null, result];
+  } catch (err) {
+    return [false, err, null];
+  }
+}
+
+export default tryFn;

package/src/connection-string.class.js

@@ -0,0 +1,75 @@
+export const S3_DEFAULT_REGION = "us-east-1";
+export const S3_DEFAULT_ENDPOINT = "https://s3.us-east-1.amazonaws.com";
+
+import tryFn, { tryFnSync } from "./concerns/try-fn.js";
+import { ConnectionStringError } from "./errors.js";
+
+export class ConnectionString {
+  constructor(connectionString) {
+    let uri;
+
+    const [ok, err, parsed] = tryFn(() => new URL(connectionString));
+    if (!ok) {
+      throw new ConnectionStringError("Invalid connection string: " + connectionString, { original: err, input: connectionString });
+    }
+    uri = parsed;
+    // defaults:
+    this.region = S3_DEFAULT_REGION;
+    
+    // config:
+    if (uri.protocol === "s3:") this.defineFromS3(uri);
+    else this.defineFromCustomUri(uri);
+    
+    for (const [k, v] of uri.searchParams.entries()) {
+      this[k] = v;
+    }
+  }
+
+  defineFromS3(uri) {
+    const [okBucket, errBucket, bucket] = tryFnSync(() => decodeURIComponent(uri.hostname));
+    if (!okBucket) throw new ConnectionStringError("Invalid bucket in connection string", { original: errBucket, input: uri.hostname });
+    this.bucket = bucket || 's3db';
+    const [okUser, errUser, user] = tryFnSync(() => decodeURIComponent(uri.username));
+    if (!okUser) throw new ConnectionStringError("Invalid accessKeyId in connection string", { original: errUser, input: uri.username });
+    this.accessKeyId = user;
+    const [okPass, errPass, pass] = tryFnSync(() => decodeURIComponent(uri.password));
+    if (!okPass) throw new ConnectionStringError("Invalid secretAccessKey in connection string", { original: errPass, input: uri.password });
+    this.secretAccessKey = pass;
+    this.endpoint = S3_DEFAULT_ENDPOINT;
+
+    if (["/", "", null].includes(uri.pathname)) {
+      this.keyPrefix = "";
+    } else {
+      let [, ...subpath] = uri.pathname.split("/");
+      this.keyPrefix = [...(subpath || [])].join("/");
+    }
+  }
+
+  defineFromCustomUri(uri) {
+    this.forcePathStyle = true;
+    this.endpoint = uri.origin;
+    const [okUser, errUser, user] = tryFnSync(() => decodeURIComponent(uri.username));
+    if (!okUser) throw new ConnectionStringError("Invalid accessKeyId in connection string", { original: errUser, input: uri.username });
+    this.accessKeyId = user;
+    const [okPass, errPass, pass] = tryFnSync(() => decodeURIComponent(uri.password));
+    if (!okPass) throw new ConnectionStringError("Invalid secretAccessKey in connection string", { original: errPass, input: uri.password });
+    this.secretAccessKey = pass;
+
+    if (["/", "", null].includes(uri.pathname)) {
+      this.bucket = "s3db";
+      this.keyPrefix = "";
+    } else {
+      let [, bucket, ...subpath] = uri.pathname.split("/");
+      if (!bucket) {
+        this.bucket = "s3db";
+      } else {
+        const [okBucket, errBucket, bucketDecoded] = tryFnSync(() => decodeURIComponent(bucket));
+        if (!okBucket) throw new ConnectionStringError("Invalid bucket in connection string", { original: errBucket, input: bucket });
+        this.bucket = bucketDecoded;
+      }
+      this.keyPrefix = [...(subpath || [])].join("/");
+    }
+  }
+}
+
+export default ConnectionString;