s3db.js 12.2.4 → 12.3.0

package/src/schema.class.js

@@ -1,4 +1,5 @@
 import { flatten, unflatten } from "flat";
+import { createHash } from "crypto";
 
 import {
   set,
@@ -36,6 +37,73 @@ function generateBase62Mapping(keys) {
   return { mapping, reversedMapping };
 }
 
+/**
+ * Generate stable hash for plugin attribute ID
+ * Uses plugin name + attribute name to create deterministic, stable IDs
+ * This ensures IDs don't change when other plugins are added/removed
+ *
+ * Uses base62 encoding for maximum compactness (3 chars = 238,328 combinations)
+ * Perfect for realistic plugin usage (2-15 plugins per resource)
+ *
+ * @param {string} pluginName - Name of the plugin
+ * @param {string} attributeName - Name of the attribute
+ * @returns {string} Stable hash ID like 'pX7k' (3 chars base62)
+ */
+function generatePluginAttributeHash(pluginName, attributeName) {
+  const input = `${pluginName}:${attributeName}`;
+  const hash = createHash('sha256').update(input).digest();
+
+  // Convert first 4 bytes to integer
+  const num = hash.readUInt32BE(0);
+
+  // Convert to base62 and take first 3 characters
+  const base62Hash = toBase62(num);
+
+  // Pad with zeros if needed and take first 3 chars
+  const paddedHash = base62Hash.padStart(3, '0').substring(0, 3);
+
+  // S3 metadata keys are case-insensitive and stored in lowercase
+  // So we must lowercase the hash to ensure consistency
+  return 'p' + paddedHash.toLowerCase();
+}
+
+/**
+ * Generate plugin attribute mapping with stable hash-based IDs
+ * Each plugin attribute gets a unique, stable ID based on plugin name + attribute name
+ * IDs don't change when other plugins are added/removed, preventing data corruption
+ *
+ * Uses 3-char base62 encoding for maximum compactness:
+ * - 62^3 = 238,328 possible combinations
+ * - Perfect for realistic usage (2-15 plugins per resource)
+ * - Saves ~62.5% metadata space vs 8-char hex format
+ *
+ * @param {Array<{key: string, pluginName: string}>} attributes - Array of plugin attributes with metadata
+ * @returns {Object} Mapping object with stable hash-based keys (e.g., 'pX7k')
+ */
+function generatePluginMapping(attributes) {
+  const mapping = {};
+  const reversedMapping = {};
+  const usedHashes = new Set();
+
+  for (const { key, pluginName } of attributes) {
+    let hash = generatePluginAttributeHash(pluginName, key);
+
+    // Handle collisions by appending counter
+    let counter = 1;
+    let finalHash = hash;
+    while (usedHashes.has(finalHash)) {
+      finalHash = `${hash}${counter}`;  // e.g., pX7k1, pX7k2
+      counter++;
+    }
+
+    usedHashes.add(finalHash);
+    mapping[key] = finalHash;
+    reversedMapping[finalHash] = key;
+  }
+
+  return { mapping, reversedMapping };
+}
+
 export const SchemaActions = {
   trim: (value) => value == null ? value : value.trim(),
 
@@ -463,11 +531,14 @@ export class Schema {
   constructor(args) {
     const {
       map,
+      pluginMap,
       name,
       attributes,
       passphrase,
       version = 1,
-      options = {}
+      options = {},
+      _pluginAttributeMetadata,
+      _pluginAttributes
     } = args;
 
     this.name = name;
@@ -477,6 +548,10 @@ export class Schema {
     this.options = merge({}, this.defaultOptions(), options);
     this.allNestedObjectsOptional = this.options.allNestedObjectsOptional ?? false;
 
+    // Initialize plugin attribute metadata tracking
+    this._pluginAttributeMetadata = _pluginAttributeMetadata || {};
+    this._pluginAttributes = _pluginAttributes || {};
+
     // Preprocess attributes to handle nested objects for validator compilation
     const processedAttributes = this.preprocessAttributesForValidation(this.attributes);
 
@@ -494,19 +569,65 @@ export class Schema {
     else {
       const flatAttrs = flatten(this.attributes, { safe: true });
       const leafKeys = Object.keys(flatAttrs).filter(k => !k.includes('$$'));
-      
+
       // Also include parent object keys for objects that can be empty
       const objectKeys = this.extractObjectKeys(this.attributes);
-      
+
       // Combine leaf keys and object keys, removing duplicates
       const allKeys = [...new Set([...leafKeys, ...objectKeys])];
-      
-      // Generate base62 mapping instead of sequential numbers
-      const { mapping, reversedMapping } = generateBase62Mapping(allKeys);
+
+      // Separate user attributes from plugin attributes
+      const userKeys = [];
+      const pluginAttributes = []; // Array of {key, pluginName}
+
+      for (const key of allKeys) {
+        const attrDef = this.getAttributeDefinition(key);
+        // Check if it's a plugin attribute (object with __plugin__ OR string with metadata)
+        if (typeof attrDef === 'object' && attrDef !== null && attrDef.__plugin__) {
+          pluginAttributes.push({ key, pluginName: attrDef.__plugin__ });
+        } else if (typeof attrDef === 'string' && this._pluginAttributeMetadata && this._pluginAttributeMetadata[key]) {
+          const pluginName = this._pluginAttributeMetadata[key].__plugin__;
+          pluginAttributes.push({ key, pluginName });
+        } else {
+          userKeys.push(key);
+        }
+      }
+
+      // Generate base62 mapping for user attributes
+      const { mapping, reversedMapping } = generateBase62Mapping(userKeys);
       this.map = mapping;
       this.reversedMap = reversedMapping;
-      
 
+      // Generate plugin mapping with stable hash-based IDs
+      const { mapping: pMapping, reversedMapping: pReversedMapping } = generatePluginMapping(pluginAttributes);
+      this.pluginMap = pMapping;
+      this.reversedPluginMap = pReversedMapping;
+
+      // Build _pluginAttributes reverse mapping (pluginName -> array of attribute names)
+      this._pluginAttributes = {};
+      for (const { key, pluginName } of pluginAttributes) {
+        if (!this._pluginAttributes[pluginName]) {
+          this._pluginAttributes[pluginName] = [];
+        }
+        this._pluginAttributes[pluginName].push(key);
+      }
+    }
+
+    // If pluginMap was provided, use it
+    if (!isEmpty(pluginMap)) {
+      this.pluginMap = pluginMap;
+      this.reversedPluginMap = invert(pluginMap);
+    }
+
+    // Initialize plugin maps if not set
+    if (!this.pluginMap) {
+      this.pluginMap = {};
+      this.reversedPluginMap = {};
+    }
+
+    // Initialize _pluginAttributes if not set
+    if (!this._pluginAttributes) {
+      this._pluginAttributes = {};
     }
   }
 
@@ -839,6 +960,8 @@ export class Schema {
   static import(data) {
     let {
       map,
+      pluginMap,
+      _pluginAttributeMetadata,
       name,
       options,
       version,
@@ -852,11 +975,18 @@ export class Schema {
 
     const schema = new Schema({
       map,
+      pluginMap: pluginMap || {},
       name,
       options,
       version,
       attributes
     });
+
+    // Restore plugin metadata for string definitions
+    if (_pluginAttributeMetadata) {
+      schema._pluginAttributeMetadata = _pluginAttributeMetadata;
+    }
+
     return schema;
   }
 
@@ -898,6 +1028,9 @@ export class Schema {
       options: this.options,
       attributes: this._exportAttributes(this.attributes),
       map: this.map,
+      pluginMap: this.pluginMap || {},
+      _pluginAttributeMetadata: this._pluginAttributeMetadata || {},
+      _pluginAttributes: this._pluginAttributes || {}
     };
     return data;
   }
@@ -956,8 +1089,10 @@ export class Schema {
     // Then flatten the object
     const flattenedObj = flatten(obj, { safe: true });
     const rest = { '_v': this.version + '' };
+
     for (const [key, value] of Object.entries(flattenedObj)) {
-      const mappedKey = this.map[key] || key;
+      // Try plugin map first, then user map, then use original key
+      const mappedKey = this.pluginMap[key] || this.map[key] || key;
       // Always map numbers to base36
       const attrDef = this.getAttributeDefinition(key);
       if (typeof value === 'number' && typeof attrDef === 'string' && attrDef.includes('number')) {
@@ -980,14 +1115,22 @@ export class Schema {
     return rest;
   }
 
-  async unmapper(mappedResourceItem, mapOverride) {
+  async unmapper(mappedResourceItem, mapOverride, pluginMapOverride) {
     let obj = cloneDeep(mappedResourceItem);
     delete obj._v;
     obj = await this.applyHooksActions(obj, "beforeUnmap");
     const reversedMap = mapOverride ? invert(mapOverride) : this.reversedMap;
+    const reversedPluginMap = pluginMapOverride ? invert(pluginMapOverride) : this.reversedPluginMap;
     const rest = {};
     for (const [key, value] of Object.entries(obj)) {
-      const originalKey = reversedMap && reversedMap[key] ? reversedMap[key] : key;
+      // Try plugin reversed map first, then user reversed map, then use original key
+      let originalKey = reversedPluginMap[key] || reversedMap[key] || key;
+
+      // If key not found in either map, use original key
+      if (!originalKey) {
+        originalKey = key;
+      }
+
       let parsedValue = value;
       const attrDef = this.getAttributeDefinition(originalKey);
       const hasAfterUnmapHook = this.options.hooks?.afterUnmap?.[originalKey];
@@ -1067,6 +1210,50 @@ export class Schema {
     return def;
   }
 
+  /**
+   * Regenerate plugin attribute mapping
+   * Called when plugin attributes are added or removed
+   * @returns {void}
+   */
+  regeneratePluginMapping() {
+    const flatAttrs = flatten(this.attributes, { safe: true });
+    const leafKeys = Object.keys(flatAttrs).filter(k => !k.includes('$$'));
+
+    // Also include parent object keys for objects that can be empty
+    const objectKeys = this.extractObjectKeys(this.attributes);
+
+    // Combine leaf keys and object keys, removing duplicates
+    const allKeys = [...new Set([...leafKeys, ...objectKeys])];
+
+    // Extract only plugin attributes
+    const pluginAttributes = []; // Array of {key, pluginName}
+    for (const key of allKeys) {
+      const attrDef = this.getAttributeDefinition(key);
+      // Check if it's a plugin attribute (object with __plugin__ OR string with metadata)
+      if (typeof attrDef === 'object' && attrDef !== null && attrDef.__plugin__) {
+        pluginAttributes.push({ key, pluginName: attrDef.__plugin__ });
+      } else if (typeof attrDef === 'string' && this._pluginAttributeMetadata && this._pluginAttributeMetadata[key]) {
+        // String definition with plugin metadata
+        const pluginName = this._pluginAttributeMetadata[key].__plugin__;
+        pluginAttributes.push({ key, pluginName });
+      }
+    }
+
+    // Regenerate plugin mapping with stable hash-based IDs
+    const { mapping, reversedMapping } = generatePluginMapping(pluginAttributes);
+    this.pluginMap = mapping;
+    this.reversedPluginMap = reversedMapping;
+
+    // Rebuild _pluginAttributes reverse mapping (pluginName -> array of attribute names)
+    this._pluginAttributes = {};
+    for (const { key, pluginName } of pluginAttributes) {
+      if (!this._pluginAttributes[pluginName]) {
+        this._pluginAttributes[pluginName] = [];
+      }
+      this._pluginAttributes[pluginName].push(key);
+    }
+  }
+
   /**
    * Preprocess attributes to convert nested objects into validator-compatible format
    * @param {Object} attributes - Original attributes
@@ -1160,45 +1347,48 @@ export class Schema {
         const hasValidatorType = value.type !== undefined && key !== '$$type';
 
         if (hasValidatorType) {
+          // Remove plugin metadata from all object definitions
+          const { __plugin__, __pluginCreated__, ...cleanValue } = 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') {
+          if (cleanValue.type === 'ip4') {
+            processed[key] = { ...cleanValue, type: 'string' };
+          } else if (cleanValue.type === 'ip6') {
+            processed[key] = { ...cleanValue, type: 'string' };
+          } else if (cleanValue.type === 'money' || cleanValue.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') {
+            processed[key] = { ...cleanValue, type: 'number', min: cleanValue.min !== undefined ? cleanValue.min : 0 };
+          } else if (cleanValue.type === 'decimal') {
             // Decimal type → number
-            processed[key] = { ...value, type: 'number' };
-          } else if (value.type === 'geo:lat' || value.type === 'geo-lat') {
+            processed[key] = { ...cleanValue, type: 'number' };
+          } else if (cleanValue.type === 'geo:lat' || cleanValue.type === 'geo-lat') {
             // Geo latitude → number with range [-90, 90]
             processed[key] = {
-              ...value,
+              ...cleanValue,
               type: 'number',
-              min: value.min !== undefined ? value.min : -90,
-              max: value.max !== undefined ? value.max : 90
+              min: cleanValue.min !== undefined ? cleanValue.min : -90,
+              max: cleanValue.max !== undefined ? cleanValue.max : 90
             };
-          } else if (value.type === 'geo:lon' || value.type === 'geo-lon') {
+          } else if (cleanValue.type === 'geo:lon' || cleanValue.type === 'geo-lon') {
             // Geo longitude → number with range [-180, 180]
             processed[key] = {
-              ...value,
+              ...cleanValue,
               type: 'number',
-              min: value.min !== undefined ? value.min : -180,
-              max: value.max !== undefined ? value.max : 180
+              min: cleanValue.min !== undefined ? cleanValue.min : -180,
+              max: cleanValue.max !== undefined ? cleanValue.max : 180
             };
-          } else if (value.type === 'geo:point' || value.type === 'geo-point') {
+          } else if (cleanValue.type === 'geo:point' || cleanValue.type === 'geo-point') {
             // Geo point → any (will be validated in hooks)
-            processed[key] = { ...value, type: 'any' };
-          } else if (value.type === 'object' && value.properties) {
+            processed[key] = { ...cleanValue, type: 'any' };
+          } else if (cleanValue.type === 'object' && cleanValue.properties) {
             // Recursively process nested object properties
             processed[key] = {
-              ...value,
-              properties: this.preprocessAttributesForValidation(value.properties)
+              ...cleanValue,
+              properties: this.preprocessAttributesForValidation(cleanValue.properties)
             };
           } else {
-            // This is a validator type definition (e.g., { type: 'array', items: 'number' }), pass it through
-            processed[key] = value;
+            // This is a validator type definition (e.g., { type: 'array', items: 'number' })
+            processed[key] = cleanValue;
           }
         } else {
           // This is a nested object structure, wrap it for validation