s3db.js 11.3.2 → 12.0.1

package/src/schema.class.js

@@ -15,7 +15,10 @@ import { encrypt, decrypt } from "./concerns/crypto.js";
 import { ValidatorManager } from "./validator.class.js";
 import { tryFn, tryFnSync } from "./concerns/try-fn.js";
 import { SchemaError } from "./errors.js";
-import { encode as toBase62, decode as fromBase62, encodeDecimal, decodeDecimal, encodeFixedPoint, decodeFixedPoint } from "./concerns/base62.js";
+import { encode as toBase62, decode as fromBase62, encodeDecimal, decodeDecimal, encodeFixedPoint, decodeFixedPoint, encodeFixedPointBatch, decodeFixedPointBatch } from "./concerns/base62.js";
+import { encodeIPv4, decodeIPv4, encodeIPv6, decodeIPv6, isValidIPv4, isValidIPv6 } from "./concerns/ip.js";
+import { encodeMoney, decodeMoney, getCurrencyDecimals } from "./concerns/money.js";
+import { encodeGeoLat, decodeGeoLat, encodeGeoLon, decodeGeoLon, encodeGeoPoint, decodeGeoPoint } from "./concerns/geo-encoding.js";
 
 /**
  * Generate base62 mapping for attributes
@@ -279,29 +282,33 @@ export const SchemaActions = {
       return value;
     }
     if (value.length === 0) {
-      return '';
+      return '^[]';
     }
-    const encodedItems = value.map(item => {
-      if (typeof item === 'number' && !isNaN(item)) {
-        return encodeFixedPoint(item, precision);
-      }
-      // fallback: try to parse as number, else keep as is
-      const n = Number(item);
-      return isNaN(n) ? '' : encodeFixedPoint(n, precision);
-    });
-    return encodedItems.join(separator);
+    // Use batch encoding for massive compression (17% additional savings)
+    // Format: ^[val1,val2,val3,...] instead of ^val1,^val2,^val3,...
+    return encodeFixedPointBatch(value, precision);
   },
   toArrayOfEmbeddings: (value, { separator, precision = 6 }) => {
     if (Array.isArray(value)) {
-      return value.map(v => (typeof v === 'number' ? v : decodeFixedPoint(v, precision)));
+      // Already an array, return as-is
+      return value;
     }
     if (value === null || value === undefined) {
       return value;
     }
-    if (value === '') {
+    if (value === '' || value === '^[]') {
       return [];
     }
+
     const str = String(value);
+
+    // Check if this is batch-encoded (^[...])
+    if (str.startsWith('^[')) {
+      return decodeFixedPointBatch(str, precision);
+    }
+
+    // Fallback: Legacy format with individual prefixes (^val,^val,^val)
+    // This maintains backwards compatibility with data encoded before batch optimization
     const items = [];
     let current = '';
     let i = 0;
@@ -329,6 +336,129 @@ export const SchemaActions = {
     });
   },
 
+  encodeIPv4: (value) => {
+    if (value === null || value === undefined) return value;
+    if (typeof value !== 'string') return value;
+    if (!isValidIPv4(value)) return value;
+    const [ok, err, encoded] = tryFnSync(() => encodeIPv4(value));
+    return ok ? encoded : value;
+  },
+  decodeIPv4: (value) => {
+    if (value === null || value === undefined) return value;
+    if (typeof value !== 'string') return value;
+    const [ok, err, decoded] = tryFnSync(() => decodeIPv4(value));
+    return ok ? decoded : value;
+  },
+
+  encodeIPv6: (value) => {
+    if (value === null || value === undefined) return value;
+    if (typeof value !== 'string') return value;
+    if (!isValidIPv6(value)) return value;
+    const [ok, err, encoded] = tryFnSync(() => encodeIPv6(value));
+    return ok ? encoded : value;
+  },
+  decodeIPv6: (value) => {
+    if (value === null || value === undefined) return value;
+    if (typeof value !== 'string') return value;
+    const [ok, err, decoded] = tryFnSync(() => decodeIPv6(value));
+    return ok ? decoded : value;
+  },
+
+  // Money type - Integer-based (banking standard)
+  // Simplified approach: decimals instead of currency
+  encodeMoney: (value, { decimals = 2 } = {}) => {
+    if (value === null || value === undefined) return value;
+    if (typeof value !== 'number') return value;
+
+    // Use decimal places directly instead of currency lookup
+    const multiplier = Math.pow(10, decimals);
+    const integerValue = Math.round(value * multiplier);
+
+    // Encode as base62 with $ prefix
+    const [ok, err, encoded] = tryFnSync(() => '$' + toBase62(integerValue));
+    return ok ? encoded : value;
+  },
+  decodeMoney: (value, { decimals = 2 } = {}) => {
+    if (value === null || value === undefined) return value;
+    if (typeof value !== 'string') return value;
+    if (!value.startsWith('$')) return value;
+
+    // Decode base62 and convert back to decimal
+    const [ok, err, integerValue] = tryFnSync(() => fromBase62(value.slice(1)));
+    if (!ok || isNaN(integerValue)) return value;
+
+    const divisor = Math.pow(10, decimals);
+    return integerValue / divisor;
+  },
+
+  // Decimal type - Fixed-point for non-monetary decimals
+  encodeDecimalFixed: (value, { precision = 2 } = {}) => {
+    if (value === null || value === undefined) return value;
+    if (typeof value !== 'number') return value;
+    const [ok, err, encoded] = tryFnSync(() => encodeFixedPoint(value, precision));
+    return ok ? encoded : value;
+  },
+  decodeDecimalFixed: (value, { precision = 2 } = {}) => {
+    if (value === null || value === undefined) return value;
+    if (typeof value !== 'string') return value;
+    const [ok, err, decoded] = tryFnSync(() => decodeFixedPoint(value, precision));
+    return ok ? decoded : value;
+  },
+
+  // Geo types - Latitude
+  encodeGeoLatitude: (value, { precision = 6 } = {}) => {
+    if (value === null || value === undefined) return value;
+    if (typeof value !== 'number') return value;
+    const [ok, err, encoded] = tryFnSync(() => encodeGeoLat(value, precision));
+    return ok ? encoded : value;
+  },
+  decodeGeoLatitude: (value, { precision = 6 } = {}) => {
+    if (value === null || value === undefined) return value;
+    if (typeof value !== 'string') return value;
+    const [ok, err, decoded] = tryFnSync(() => decodeGeoLat(value, precision));
+    return ok ? decoded : value;
+  },
+
+  // Geo types - Longitude
+  encodeGeoLongitude: (value, { precision = 6 } = {}) => {
+    if (value === null || value === undefined) return value;
+    if (typeof value !== 'number') return value;
+    const [ok, err, encoded] = tryFnSync(() => encodeGeoLon(value, precision));
+    return ok ? encoded : value;
+  },
+  decodeGeoLongitude: (value, { precision = 6 } = {}) => {
+    if (value === null || value === undefined) return value;
+    if (typeof value !== 'string') return value;
+    const [ok, err, decoded] = tryFnSync(() => decodeGeoLon(value, precision));
+    return ok ? decoded : value;
+  },
+
+  // Geo types - Point (lat+lon pair)
+  encodeGeoPointPair: (value, { precision = 6 } = {}) => {
+    if (value === null || value === undefined) return value;
+    // Accept object with lat/lon or array [lat, lon]
+    if (Array.isArray(value) && value.length === 2) {
+      const [ok, err, encoded] = tryFnSync(() => encodeGeoPoint(value[0], value[1], precision));
+      return ok ? encoded : value;
+    }
+    if (typeof value === 'object' && value.lat !== undefined && value.lon !== undefined) {
+      const [ok, err, encoded] = tryFnSync(() => encodeGeoPoint(value.lat, value.lon, precision));
+      return ok ? encoded : value;
+    }
+    if (typeof value === 'object' && value.latitude !== undefined && value.longitude !== undefined) {
+      const [ok, err, encoded] = tryFnSync(() => encodeGeoPoint(value.latitude, value.longitude, precision));
+      return ok ? encoded : value;
+    }
+    return value;
+  },
+  decodeGeoPointPair: (value, { precision = 6 } = {}) => {
+    if (value === null || value === undefined) return value;
+    if (typeof value !== 'string') return value;
+    const [ok, err, decoded] = tryFnSync(() => decodeGeoPoint(value, precision));
+    // Return as object { latitude, longitude }
+    return ok ? decoded : value;
+  },
+
 }
 
 export class Schema {
@@ -353,7 +483,7 @@ export class Schema {
     const processedAttributes = this.preprocessAttributesForValidation(this.attributes);
 
     this.validator = new ValidatorManager({ autoEncrypt: false }).compile(merge(
-      { $$async: true },
+      { $$async: true, $$strict: false },
       processedAttributes,
     ))
 
@@ -398,9 +528,11 @@ export class Schema {
     }
   }
 
-  addHook(hook, attribute, action) {
+  addHook(hook, attribute, action, params = {}) {
     if (!this.options.hooks[hook][attribute]) this.options.hooks[hook][attribute] = [];
-    this.options.hooks[hook][attribute] = uniq([...this.options.hooks[hook][attribute], action])
+    // Store action with parameters if provided
+    const hookEntry = Object.keys(params).length > 0 ? { action, params } : action;
+    this.options.hooks[hook][attribute] = uniq([...this.options.hooks[hook][attribute], hookEntry])
   }
 
   extractObjectKeys(obj, prefix = '') {
@@ -573,6 +705,97 @@ export class Schema {
         continue;
       }
 
+      // Handle ip4 type
+      if (defStr.includes("ip4") || defType === 'ip4') {
+        this.addHook("beforeMap", name, "encodeIPv4");
+        this.addHook("afterUnmap", name, "decodeIPv4");
+        continue;
+      }
+
+      // Handle ip6 type
+      if (defStr.includes("ip6") || defType === 'ip6') {
+        this.addHook("beforeMap", name, "encodeIPv6");
+        this.addHook("afterUnmap", name, "decodeIPv6");
+        continue;
+      }
+
+      // Handle money type (integer-based, decimal-aware)
+      if (defStr.includes("money") || defType === 'money' || defStr.includes("crypto") || defType === 'crypto') {
+        // Extract decimals from money:8 or crypto:8 notation
+        let decimals = 2; // Default for fiat money (2 decimal places)
+
+        // If it's crypto, default to 8 decimals (satoshi/standard crypto)
+        if (defStr.includes("crypto") || defType === 'crypto') {
+          decimals = 8;
+        }
+
+        // Override with explicit decimals if provided: money:8, crypto:18
+        const decimalsMatch = defStr.match(/(?:money|crypto):(\d+)/i);
+        if (decimalsMatch) {
+          decimals = parseInt(decimalsMatch[1], 10);
+        }
+
+        this.addHook("beforeMap", name, "encodeMoney", { decimals });
+        this.addHook("afterUnmap", name, "decodeMoney", { decimals });
+        continue;
+      }
+
+      // Handle decimal type (fixed-point for non-monetary decimals)
+      if (defStr.includes("decimal") || defType === 'decimal') {
+        // Extract precision from decimal:4 notation
+        let precision = 2; // Default precision
+        const precisionMatch = defStr.match(/decimal:(\d+)/);
+        if (precisionMatch) {
+          precision = parseInt(precisionMatch[1], 10);
+        }
+
+        this.addHook("beforeMap", name, "encodeDecimalFixed", { precision });
+        this.addHook("afterUnmap", name, "decodeDecimalFixed", { precision });
+        continue;
+      }
+
+      // Handle geo:lat type (latitude)
+      if (defStr.includes("geo:lat") || (defType === 'geo' && defStr.includes('lat'))) {
+        // Extract precision from geo:lat:6 notation
+        let precision = 6; // Default precision (GPS standard)
+        const precisionMatch = defStr.match(/geo:lat:(\d+)/);
+        if (precisionMatch) {
+          precision = parseInt(precisionMatch[1], 10);
+        }
+
+        this.addHook("beforeMap", name, "encodeGeoLatitude", { precision });
+        this.addHook("afterUnmap", name, "decodeGeoLatitude", { precision });
+        continue;
+      }
+
+      // Handle geo:lon type (longitude)
+      if (defStr.includes("geo:lon") || (defType === 'geo' && defStr.includes('lon'))) {
+        // Extract precision from geo:lon:6 notation
+        let precision = 6; // Default precision
+        const precisionMatch = defStr.match(/geo:lon:(\d+)/);
+        if (precisionMatch) {
+          precision = parseInt(precisionMatch[1], 10);
+        }
+
+        this.addHook("beforeMap", name, "encodeGeoLongitude", { precision });
+        this.addHook("afterUnmap", name, "decodeGeoLongitude", { precision });
+        continue;
+      }
+
+      // Handle geo:point type (lat+lon pair)
+      if (defStr.includes("geo:point") || defType === 'geo:point') {
+        // Extract precision from geo:point:6 notation
+        let precision = 6; // Default precision
+        const precisionMatch = defStr.match(/geo:point:(\d+)/);
+        if (precisionMatch) {
+          precision = parseInt(precisionMatch[1], 10);
+        }
+
+        this.addHook("beforeMap", name, "encodeGeoPointPair", { precision });
+        this.addHook("afterUnmap", name, "decodeGeoPointPair", { precision });
+        continue;
+      }
+
       // Handle numbers (only for non-array fields)
       if (defStr.includes("number") || defType === 'number') {
         // Check if it's specifically an integer field
@@ -704,12 +927,17 @@ export class Schema {
   async applyHooksActions(resourceItem, hook) {
     const cloned = cloneDeep(resourceItem);
     for (const [attribute, actions] of Object.entries(this.options.hooks[hook])) {
-      for (const action of actions) {
+      for (const actionEntry of actions) {
+        // Support both string actions and {action, params} objects
+        const actionName = typeof actionEntry === 'string' ? actionEntry : actionEntry.action;
+        const actionParams = typeof actionEntry === 'object' ? actionEntry.params : {};
+
         const value = get(cloned, attribute)
-        if (value !== undefined && typeof SchemaActions[action] === 'function') {
-          set(cloned, attribute, await SchemaActions[action](value, {
+        if (value !== undefined && typeof SchemaActions[actionName] === 'function') {
+          set(cloned, attribute, await SchemaActions[actionName](value, {
             passphrase: this.passphrase,
             separator: this.options.arraySeparator,
+            ...actionParams  // Merge custom parameters (currency, precision, etc.)
           }))
         }
       }
@@ -785,27 +1013,35 @@ export class Schema {
         }
       }
       // PATCH: ensure arrays are always arrays
+      // Skip automatic array conversion if there's an afterUnmap hook that will handle it
       if (this.attributes) {
         if (typeof attrDef === 'string' && attrDef.includes('array')) {
-          if (Array.isArray(parsedValue)) {
-            // Already an array
-          } else if (typeof parsedValue === 'string' && parsedValue.trim().startsWith('[')) {
-            const [okArr, errArr, arr] = tryFnSync(() => JSON.parse(parsedValue));
-            if (okArr && Array.isArray(arr)) {
-              parsedValue = arr;
+          if (!hasAfterUnmapHook) {
+            if (Array.isArray(parsedValue)) {
+              // Already an array
+            } else if (typeof parsedValue === 'string' && parsedValue.trim().startsWith('[')) {
+              const [okArr, errArr, arr] = tryFnSync(() => JSON.parse(parsedValue));
+              if (okArr && Array.isArray(arr)) {
+                parsedValue = arr;
+              }
+            } else {
+              parsedValue = SchemaActions.toArray(parsedValue, { separator: this.options.arraySeparator });
             }
-          } else {
-            parsedValue = SchemaActions.toArray(parsedValue, { separator: this.options.arraySeparator });
           }
         }
       }
       // PATCH: apply afterUnmap hooks for type restoration
       if (this.options.hooks && this.options.hooks.afterUnmap && this.options.hooks.afterUnmap[originalKey]) {
-        for (const action of this.options.hooks.afterUnmap[originalKey]) {
-          if (typeof SchemaActions[action] === 'function') {
-            parsedValue = await SchemaActions[action](parsedValue, {
+        for (const actionEntry of this.options.hooks.afterUnmap[originalKey]) {
+          // Support both string actions and {action, params} objects
+          const actionName = typeof actionEntry === 'string' ? actionEntry : actionEntry.action;
+          const actionParams = typeof actionEntry === 'object' ? actionEntry.params : {};
+
+          if (typeof SchemaActions[actionName] === 'function') {
+            parsedValue = await SchemaActions[actionName](parsedValue, {
               passphrase: this.passphrase,
               separator: this.options.arraySeparator,
+              ...actionParams  // Merge custom parameters (currency, precision, etc.)
             });
     }
         }
@@ -843,6 +1079,66 @@ export class Schema {
 
     for (const [key, value] of Object.entries(attributes)) {
       if (typeof value === 'string') {
+        // Expand ip4 shorthand to string type with custom validation
+        if (value === 'ip4' || value.startsWith('ip4|')) {
+          processed[key] = value.replace(/^ip4/, 'string');
+          continue;
+        }
+        // Expand ip6 shorthand to string type with custom validation
+        if (value === 'ip6' || value.startsWith('ip6|')) {
+          processed[key] = value.replace(/^ip6/, 'string');
+          continue;
+        }
+        // Expand money/crypto shorthand to number type with min validation
+        if (value === 'money' || value.startsWith('money:') || value.startsWith('money|') ||
+            value === 'crypto' || value.startsWith('crypto:') || value.startsWith('crypto|')) {
+          // Extract any modifiers after money:N or crypto:N
+          const rest = value.replace(/^(?:money|crypto)(?::\d+)?/, '');
+          // Money must be non-negative
+          const hasMin = rest.includes('min:');
+          processed[key] = hasMin ? `number${rest}` : `number|min:0${rest}`;
+          continue;
+        }
+        // Expand decimal shorthand to number type
+        if (value === 'decimal' || value.startsWith('decimal:') || value.startsWith('decimal|')) {
+          // Extract any modifiers after decimal:PRECISION
+          const rest = value.replace(/^decimal(:\d+)?/, '');
+          processed[key] = `number${rest}`;
+          continue;
+        }
+        // Expand geo:lat shorthand to number type with range validation
+        if (value.startsWith('geo:lat')) {
+          // Extract any modifiers after geo:lat:PRECISION
+          const rest = value.replace(/^geo:lat(:\d+)?/, '');
+          // Latitude range: -90 to 90
+          const hasMin = rest.includes('min:');
+          const hasMax = rest.includes('max:');
+          let validation = 'number';
+          if (!hasMin) validation += '|min:-90';
+          if (!hasMax) validation += '|max:90';
+          processed[key] = validation + rest;
+          continue;
+        }
+        // Expand geo:lon shorthand to number type with range validation
+        if (value.startsWith('geo:lon')) {
+          // Extract any modifiers after geo:lon:PRECISION
+          const rest = value.replace(/^geo:lon(:\d+)?/, '');
+          // Longitude range: -180 to 180
+          const hasMin = rest.includes('min:');
+          const hasMax = rest.includes('max:');
+          let validation = 'number';
+          if (!hasMin) validation += '|min:-180';
+          if (!hasMax) validation += '|max:180';
+          processed[key] = validation + rest;
+          continue;
+        }
+        // Expand geo:point shorthand to object with lat/lon
+        if (value.startsWith('geo:point')) {
+          // geo:point is an object or array with lat/lon
+          // For simplicity, allow it as any type (will be validated in hooks)
+          processed[key] = 'any';
+          continue;
+        }
         // Expand embedding:XXX shorthand to array|items:number|length:XXX
         if (value.startsWith('embedding:')) {
           const lengthMatch = value.match(/embedding:(\d+)/);
@@ -866,8 +1162,46 @@ export class Schema {
         const hasValidatorType = value.type !== undefined && key !== '$$type';
 
         if (hasValidatorType) {
-          // This is a validator type definition (e.g., { type: 'array', items: 'number' }), pass it through
-          processed[key] = value;
+          // Handle ip4 and ip6 object notation
+          if (value.type === 'ip4') {
+            processed[key] = { ...value, type: 'string' };
+          } else if (value.type === 'ip6') {
+            processed[key] = { ...value, type: 'string' };
+          } else if (value.type === 'money' || value.type === 'crypto') {
+            // Money/crypto type → number with min:0
+            processed[key] = { ...value, type: 'number', min: value.min !== undefined ? value.min : 0 };
+          } else if (value.type === 'decimal') {
+            // Decimal type → number
+            processed[key] = { ...value, type: 'number' };
+          } else if (value.type === 'geo:lat' || value.type === 'geo-lat') {
+            // Geo latitude → number with range [-90, 90]
+            processed[key] = {
+              ...value,
+              type: 'number',
+              min: value.min !== undefined ? value.min : -90,
+              max: value.max !== undefined ? value.max : 90
+            };
+          } else if (value.type === 'geo:lon' || value.type === 'geo-lon') {
+            // Geo longitude → number with range [-180, 180]
+            processed[key] = {
+              ...value,
+              type: 'number',
+              min: value.min !== undefined ? value.min : -180,
+              max: value.max !== undefined ? value.max : 180
+            };
+          } else if (value.type === 'geo:point' || value.type === 'geo-point') {
+            // Geo point → any (will be validated in hooks)
+            processed[key] = { ...value, type: 'any' };
+          } else if (value.type === 'object' && value.properties) {
+            // Recursively process nested object properties
+            processed[key] = {
+              ...value,
+              properties: this.preprocessAttributesForValidation(value.properties)
+            };
+          } else {
+            // This is a validator type definition (e.g., { type: 'array', items: 'number' }), pass it through
+            processed[key] = value;
+          }
         } else {
           // This is a nested object structure, wrap it for validation
           const isExplicitRequired = value.$$type && value.$$type.includes('required');

package/SECURITY.md

@@ -1,76 +0,0 @@
-# Security Policy
-
-## Supported Versions
-
-| Version | Supported          |
-| ------- | ------------------ |
-| 11.x.x  | :white_check_mark: |
-| < 11.0  | :x:                |
-
-## Known Security Advisories
-
-### Development Dependencies
-
-The following vulnerabilities exist in **development-only** dependencies and **do not affect** the published npm package or runtime security:
-
-#### pkg (GHSA-22r3-9w55-cj54) - MODERATE
-- **Status**: Acknowledged, monitored
-- **Impact**: Local privilege escalation
-- **Scope**: Only affects developers running `pnpm run build:binaries`
-- **Mitigation**: pkg is deprecated and archived. No patched version available (`<0.0.0`).
-- **Risk Assessment**: LOW - Only used for creating standalone binaries during release process
-- **Future Plans**: Migrate to Node.js Single Executable Applications (SEA) when stable
-
-#### tar-fs - HIGH
-- **Status**: RESOLVED in v11.1.1+
-- **Fix**: Updated to patched version 2.1.4+
-
-## Reporting a Vulnerability
-
-If you discover a security vulnerability in the **runtime code** (not dev dependencies), please report it by:
-
-1. **DO NOT** open a public issue
-2. Email: [security contact - update this]
-3. Include:
-   - Description of the vulnerability
-   - Steps to reproduce
-   - Potential impact
-   - Suggested fix (if any)
-
-### Response Timeline
-
-- **Initial Response**: Within 48 hours
-- **Status Update**: Within 7 days
-- **Fix Timeline**: Depends on severity
-  - Critical: 7 days
-  - High: 14 days
-  - Medium: 30 days
-  - Low: 60 days
-
-## Security Best Practices
-
-### For Users
-
-1. **Always encrypt sensitive data**: Use `secret` field type for passwords, tokens, etc.
-2. **Validate credentials**: Never commit AWS credentials to version control
-3. **Use IAM policies**: Implement least-privilege access for S3 buckets
-4. **Enable paranoid mode**: For production, use `paranoid: true` for soft deletes
-5. **Audit hooks**: Review serialized functions before deploying to production
-
-### For Contributors
-
-1. **No secrets in tests**: Use environment variables or LocalStack
-2. **Validate input**: All user input should be validated before S3 operations
-3. **Handle errors safely**: Never expose AWS error details to end users
-4. **Review dependencies**: Run `pnpm audit` before submitting PRs
-5. **Test encryption**: Verify `secret` fields are actually encrypted in S3
-
-## Audit Configuration
-
-This project uses `audit-level=high` in `.npmrc` to focus on critical vulnerabilities affecting production. Moderate/low severity issues in dev-only dependencies are monitored but may not block releases if:
-
-- They only affect development tools
-- No patch is available
-- The risk is assessed as acceptable
-
-Current audit threshold: **HIGH** (ignores moderate/low in dev dependencies)

package/src/partition-drivers/base-partition-driver.js

@@ -1,106 +0,0 @@
-import { EventEmitter } from 'events';
-import { PartitionDriverError } from '../errors.js';
-
-/**
- * Base class for all partition drivers
- * Defines the interface that all drivers must implement
- */
-export class BasePartitionDriver extends EventEmitter {
-  constructor(options = {}) {
-    super();
-    this.options = options;
-    this.stats = {
-      queued: 0,
-      processed: 0,
-      failed: 0,
-      processing: 0
-    };
-  }
-
-  /**
-   * Initialize the driver
-   */
-  async initialize() {
-    // Override in subclasses if needed
-  }
-
-  /**
-   * Queue partition operations for processing
-   * @param {Object} operation - The partition operation to queue
-   * @param {string} operation.type - 'create', 'update', or 'delete'
-   * @param {Object} operation.resource - The resource instance
-   * @param {Object} operation.data - The data for the operation
-   */
-  async queue(operation) {
-    throw new PartitionDriverError('queue() must be implemented by subclass', {
-      driver: this.name || 'BasePartitionDriver',
-      operation: 'queue',
-      suggestion: 'Extend BasePartitionDriver and implement the queue() method'
-    });
-  }
-
-  /**
-   * Process a single partition operation
-   */
-  async processOperation(operation) {
-    const { type, resource, data } = operation;
-    
-    try {
-      this.stats.processing++;
-      
-      switch (type) {
-        case 'create':
-          await resource.createPartitionReferences(data.object);
-          break;
-          
-        case 'update':
-          await resource.handlePartitionReferenceUpdates(data.original, data.updated);
-          break;
-          
-        case 'delete':
-          await resource.deletePartitionReferences(data.object);
-          break;
-          
-        default:
-          throw new PartitionDriverError(`Unknown partition operation type: ${type}`, {
-            driver: this.name || 'BasePartitionDriver',
-            operation: type,
-            availableOperations: ['create', 'update', 'delete'],
-            suggestion: 'Use one of the supported partition operations: create, update, or delete'
-          });
-      }
-      
-      this.stats.processed++;
-      this.emit('processed', operation);
-      
-    } catch (error) {
-      this.stats.failed++;
-      this.emit('error', { operation, error });
-      throw error;
-    } finally {
-      this.stats.processing--;
-    }
-  }
-
-  /**
-   * Flush any pending operations
-   */
-  async flush() {
-    // Override in subclasses if needed
-  }
-
-  /**
-   * Get driver statistics
-   */
-  getStats() {
-    return { ...this.stats };
-  }
-
-  /**
-   * Shutdown the driver
-   */
-  async shutdown() {
-    await this.flush();
-    this.removeAllListeners();
-  }
-}