s3db.js 12.2.3 → 12.3.0

package/dist/s3db.es.js

@@ -13670,7 +13670,11 @@ class BigqueryReplicator extends BaseReplicator {
         }
         continue;
       }
-      const attributes = resource.config.versions[resource.config.currentVersion]?.attributes || {};
+      const allAttributes = resource.config.versions[resource.config.currentVersion]?.attributes || {};
+      const pluginAttrNames = resource.schema?._pluginAttributes ? Object.values(resource.schema._pluginAttributes).flat() : [];
+      const attributes = Object.fromEntries(
+        Object.entries(allAttributes).filter(([name]) => !pluginAttrNames.includes(name))
+      );
       for (const tableConfig of tableConfigs) {
         const tableName = tableConfig.table;
         const [okSync, errSync] = await tryFn(async () => {
@@ -14688,7 +14692,11 @@ class MySQLReplicator extends BaseReplicator {
         }
         continue;
       }
-      const attributes = resource.config.versions[resource.config.currentVersion]?.attributes || {};
+      const allAttributes = resource.config.versions[resource.config.currentVersion]?.attributes || {};
+      const pluginAttrNames = resource.schema?._pluginAttributes ? Object.values(resource.schema._pluginAttributes).flat() : [];
+      const attributes = Object.fromEntries(
+        Object.entries(allAttributes).filter(([name]) => !pluginAttrNames.includes(name))
+      );
       for (const tableConfig of tableConfigs) {
         const tableName = tableConfig.table;
         const [okSync, errSync] = await tryFn(async () => {
@@ -15067,7 +15075,11 @@ class PlanetScaleReplicator extends BaseReplicator {
         }
         continue;
       }
-      const attributes = resource.config.versions[resource.config.currentVersion]?.attributes || {};
+      const allAttributes = resource.config.versions[resource.config.currentVersion]?.attributes || {};
+      const pluginAttrNames = resource.schema?._pluginAttributes ? Object.values(resource.schema._pluginAttributes).flat() : [];
+      const attributes = Object.fromEntries(
+        Object.entries(allAttributes).filter(([name]) => !pluginAttrNames.includes(name))
+      );
       for (const tableConfig of tableConfigs) {
         const tableName = tableConfig.table;
         const [okSync, errSync] = await tryFn(async () => {
@@ -15388,7 +15400,11 @@ class PostgresReplicator extends BaseReplicator {
         }
         continue;
       }
-      const attributes = resource.config.versions[resource.config.currentVersion]?.attributes || {};
+      const allAttributes = resource.config.versions[resource.config.currentVersion]?.attributes || {};
+      const pluginAttrNames = resource.schema?._pluginAttributes ? Object.values(resource.schema._pluginAttributes).flat() : [];
+      const attributes = Object.fromEntries(
+        Object.entries(allAttributes).filter(([name]) => !pluginAttrNames.includes(name))
+      );
       for (const tableConfig of tableConfigs) {
         const tableName = tableConfig.table;
         const [okSync, errSync] = await tryFn(async () => {
@@ -16510,6 +16526,32 @@ function generateBase62Mapping(keys) {
   });
   return { mapping, reversedMapping };
 }
+function generatePluginAttributeHash(pluginName, attributeName) {
+  const input = `${pluginName}:${attributeName}`;
+  const hash = createHash("sha256").update(input).digest();
+  const num = hash.readUInt32BE(0);
+  const base62Hash = encode(num);
+  const paddedHash = base62Hash.padStart(3, "0").substring(0, 3);
+  return "p" + paddedHash.toLowerCase();
+}
+function generatePluginMapping(attributes) {
+  const mapping = {};
+  const reversedMapping = {};
+  const usedHashes = /* @__PURE__ */ new Set();
+  for (const { key, pluginName } of attributes) {
+    let hash = generatePluginAttributeHash(pluginName, key);
+    let counter = 1;
+    let finalHash = hash;
+    while (usedHashes.has(finalHash)) {
+      finalHash = `${hash}${counter}`;
+      counter++;
+    }
+    usedHashes.add(finalHash);
+    mapping[key] = finalHash;
+    reversedMapping[finalHash] = key;
+  }
+  return { mapping, reversedMapping };
+}
 const SchemaActions = {
   trim: (value) => value == null ? value : value.trim(),
   encrypt: async (value, { passphrase }) => {
@@ -16900,11 +16942,14 @@ class Schema {
   constructor(args) {
     const {
       map,
+      pluginMap,
       name,
       attributes,
       passphrase,
       version = 1,
-      options = {}
+      options = {},
+      _pluginAttributeMetadata,
+      _pluginAttributes
     } = args;
     this.name = name;
     this.version = version;
@@ -16912,6 +16957,8 @@ class Schema {
     this.passphrase = passphrase ?? "secret";
     this.options = merge({}, this.defaultOptions(), options);
     this.allNestedObjectsOptional = this.options.allNestedObjectsOptional ?? false;
+    this._pluginAttributeMetadata = _pluginAttributeMetadata || {};
+    this._pluginAttributes = _pluginAttributes || {};
     const processedAttributes = this.preprocessAttributesForValidation(this.attributes);
     this.validator = new ValidatorManager({ autoEncrypt: false }).compile(merge(
       { $$async: true, $$strict: false },
@@ -16926,9 +16973,43 @@ class Schema {
       const leafKeys = Object.keys(flatAttrs).filter((k) => !k.includes("$$"));
       const objectKeys = this.extractObjectKeys(this.attributes);
       const allKeys = [.../* @__PURE__ */ new Set([...leafKeys, ...objectKeys])];
-      const { mapping, reversedMapping } = generateBase62Mapping(allKeys);
+      const userKeys = [];
+      const pluginAttributes = [];
+      for (const key of allKeys) {
+        const attrDef = this.getAttributeDefinition(key);
+        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);
+        }
+      }
+      const { mapping, reversedMapping } = generateBase62Mapping(userKeys);
       this.map = mapping;
       this.reversedMap = reversedMapping;
+      const { mapping: pMapping, reversedMapping: pReversedMapping } = generatePluginMapping(pluginAttributes);
+      this.pluginMap = pMapping;
+      this.reversedPluginMap = pReversedMapping;
+      this._pluginAttributes = {};
+      for (const { key, pluginName } of pluginAttributes) {
+        if (!this._pluginAttributes[pluginName]) {
+          this._pluginAttributes[pluginName] = [];
+        }
+        this._pluginAttributes[pluginName].push(key);
+      }
+    }
+    if (!isEmpty(pluginMap)) {
+      this.pluginMap = pluginMap;
+      this.reversedPluginMap = invert(pluginMap);
+    }
+    if (!this.pluginMap) {
+      this.pluginMap = {};
+      this.reversedPluginMap = {};
+    }
+    if (!this._pluginAttributes) {
+      this._pluginAttributes = {};
     }
   }
   defaultOptions() {
@@ -17157,6 +17238,8 @@ class Schema {
   static import(data) {
     let {
       map,
+      pluginMap,
+      _pluginAttributeMetadata,
       name,
       options,
       version,
@@ -17167,11 +17250,15 @@ class Schema {
     attributes = attrs;
     const schema = new Schema({
       map,
+      pluginMap: pluginMap || {},
       name,
       options,
       version,
       attributes
     });
+    if (_pluginAttributeMetadata) {
+      schema._pluginAttributeMetadata = _pluginAttributeMetadata;
+    }
     return schema;
   }
   /**
@@ -17209,7 +17296,10 @@ class Schema {
       name: this.name,
       options: this.options,
       attributes: this._exportAttributes(this.attributes),
-      map: this.map
+      map: this.map,
+      pluginMap: this.pluginMap || {},
+      _pluginAttributeMetadata: this._pluginAttributeMetadata || {},
+      _pluginAttributes: this._pluginAttributes || {}
     };
     return data;
   }
@@ -17262,7 +17352,7 @@ class Schema {
     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;
+      const mappedKey = this.pluginMap[key] || this.map[key] || key;
       const attrDef = this.getAttributeDefinition(key);
       if (typeof value === "number" && typeof attrDef === "string" && attrDef.includes("number")) {
         rest[mappedKey] = encode(value);
@@ -17283,14 +17373,18 @@ class Schema {
     await this.applyHooksActions(rest, "afterMap");
     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;
+      let originalKey = reversedPluginMap[key] || reversedMap[key] || key;
+      if (!originalKey) {
+        originalKey = key;
+      }
       let parsedValue = value;
       const attrDef = this.getAttributeDefinition(originalKey);
       const hasAfterUnmapHook = this.options.hooks?.afterUnmap?.[originalKey];
@@ -17357,6 +17451,37 @@ 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("$$"));
+    const objectKeys = this.extractObjectKeys(this.attributes);
+    const allKeys = [.../* @__PURE__ */ new Set([...leafKeys, ...objectKeys])];
+    const pluginAttributes = [];
+    for (const key of allKeys) {
+      const attrDef = this.getAttributeDefinition(key);
+      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 });
+      }
+    }
+    const { mapping, reversedMapping } = generatePluginMapping(pluginAttributes);
+    this.pluginMap = mapping;
+    this.reversedPluginMap = reversedMapping;
+    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
@@ -17426,37 +17551,38 @@ class Schema {
       } else if (typeof value === "object" && value !== null && !Array.isArray(value)) {
         const hasValidatorType = value.type !== void 0 && key !== "$$type";
         if (hasValidatorType) {
-          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") {
-            processed[key] = { ...value, type: "number", min: value.min !== void 0 ? value.min : 0 };
-          } else if (value.type === "decimal") {
-            processed[key] = { ...value, type: "number" };
-          } else if (value.type === "geo:lat" || value.type === "geo-lat") {
+          const { __plugin__, __pluginCreated__, ...cleanValue } = value;
+          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") {
+            processed[key] = { ...cleanValue, type: "number", min: cleanValue.min !== void 0 ? cleanValue.min : 0 };
+          } else if (cleanValue.type === "decimal") {
+            processed[key] = { ...cleanValue, type: "number" };
+          } else if (cleanValue.type === "geo:lat" || cleanValue.type === "geo-lat") {
             processed[key] = {
-              ...value,
+              ...cleanValue,
               type: "number",
-              min: value.min !== void 0 ? value.min : -90,
-              max: value.max !== void 0 ? value.max : 90
+              min: cleanValue.min !== void 0 ? cleanValue.min : -90,
+              max: cleanValue.max !== void 0 ? cleanValue.max : 90
             };
-          } else if (value.type === "geo:lon" || value.type === "geo-lon") {
+          } else if (cleanValue.type === "geo:lon" || cleanValue.type === "geo-lon") {
             processed[key] = {
-              ...value,
+              ...cleanValue,
               type: "number",
-              min: value.min !== void 0 ? value.min : -180,
-              max: value.max !== void 0 ? value.max : 180
+              min: cleanValue.min !== void 0 ? cleanValue.min : -180,
+              max: cleanValue.max !== void 0 ? cleanValue.max : 180
             };
-          } else if (value.type === "geo:point" || value.type === "geo-point") {
-            processed[key] = { ...value, type: "any" };
-          } else if (value.type === "object" && value.properties) {
+          } else if (cleanValue.type === "geo:point" || cleanValue.type === "geo-point") {
+            processed[key] = { ...cleanValue, type: "any" };
+          } else if (cleanValue.type === "object" && cleanValue.properties) {
             processed[key] = {
-              ...value,
-              properties: this.preprocessAttributesForValidation(value.properties)
+              ...cleanValue,
+              properties: this.preprocessAttributesForValidation(cleanValue.properties)
             };
           } else {
-            processed[key] = value;
+            processed[key] = cleanValue;
           }
         } else {
           const isExplicitRequired = value.$$type && value.$$type.includes("required");
@@ -17774,7 +17900,11 @@ async function handleInsert$3({ resource, data, mappedData, originalData }) {
       excess: totalSize - 2047,
       data: originalData || data
     });
-    return { mappedData: { _v: mappedData._v }, body: JSON.stringify(mappedData) };
+    const metadataOnly = { _v: mappedData._v };
+    if (resource.schema?.pluginMap && Object.keys(resource.schema.pluginMap).length > 0) {
+      metadataOnly._pluginMap = JSON.stringify(resource.schema.pluginMap);
+    }
+    return { mappedData: metadataOnly, body: JSON.stringify(mappedData) };
   }
   return { mappedData, body: "" };
 }
@@ -17977,6 +18107,12 @@ async function handleInsert$1({ resource, data, mappedData, originalData }) {
     metadataFields._v = mappedData._v;
     currentSize += attributeSizes._v;
   }
+  if (resource.schema?.pluginMap && Object.keys(resource.schema.pluginMap).length > 0) {
+    const pluginMapStr = JSON.stringify(resource.schema.pluginMap);
+    const pluginMapSize = calculateUTF8Bytes("_pluginMap") + calculateUTF8Bytes(pluginMapStr);
+    metadataFields._pluginMap = pluginMapStr;
+    currentSize += pluginMapSize;
+  }
   let reservedLimit = effectiveLimit;
   for (const [fieldName, size] of sortedFields) {
     if (fieldName === "_v") continue;
@@ -18036,6 +18172,9 @@ async function handleInsert({ resource, data, mappedData }) {
     "_v": mappedData._v || String(resource.version)
   };
   metadataOnly._map = JSON.stringify(resource.schema.map);
+  if (resource.schema.pluginMap && Object.keys(resource.schema.pluginMap).length > 0) {
+    metadataOnly._pluginMap = JSON.stringify(resource.schema.pluginMap);
+  }
   const body = JSON.stringify(mappedData);
   return { mappedData: metadataOnly, body };
 }
@@ -18044,6 +18183,9 @@ async function handleUpdate({ resource, id, data, mappedData }) {
     "_v": mappedData._v || String(resource.version)
   };
   metadataOnly._map = JSON.stringify(resource.schema.map);
+  if (resource.schema.pluginMap && Object.keys(resource.schema.pluginMap).length > 0) {
+    metadataOnly._pluginMap = JSON.stringify(resource.schema.pluginMap);
+  }
   const body = JSON.stringify(mappedData);
   return { mappedData: metadataOnly, body };
 }
@@ -18424,6 +18566,118 @@ ${errorDetails}`,
     this.applyConfiguration();
     return { oldAttributes, newAttributes };
   }
+  /**
+   * Add a plugin-created attribute to the resource schema
+   * This ensures plugin attributes don't interfere with user-defined attributes
+   * by using a separate mapping namespace (p0, p1, p2, ...)
+   *
+   * @param {string} name - Attribute name (e.g., '_hasEmbedding', 'clusterId')
+   * @param {Object|string} definition - Attribute definition
+   * @param {string} pluginName - Name of plugin adding the attribute
+   * @returns {void}
+   *
+   * @example
+   * // VectorPlugin adding tracking field
+   * resource.addPluginAttribute('_hasEmbedding', {
+   *   type: 'boolean',
+   *   optional: true,
+   *   default: false
+   * }, 'VectorPlugin');
+   *
+   * // Shorthand notation
+   * resource.addPluginAttribute('clusterId', 'string|optional', 'VectorPlugin');
+   */
+  addPluginAttribute(name, definition, pluginName) {
+    if (!pluginName) {
+      throw new ResourceError(
+        "Plugin name is required when adding plugin attributes",
+        { resource: this.name, attribute: name }
+      );
+    }
+    const existingDef = this.schema.getAttributeDefinition(name);
+    if (existingDef && (!existingDef.__plugin__ || existingDef.__plugin__ !== pluginName)) {
+      throw new ResourceError(
+        `Attribute '${name}' already exists and is not from plugin '${pluginName}'`,
+        { resource: this.name, attribute: name, plugin: pluginName }
+      );
+    }
+    let defObject = definition;
+    if (typeof definition === "object" && definition !== null) {
+      defObject = { ...definition };
+    }
+    if (typeof defObject === "object" && defObject !== null) {
+      defObject.__plugin__ = pluginName;
+      defObject.__pluginCreated__ = Date.now();
+    }
+    this.schema.attributes[name] = defObject;
+    this.attributes[name] = defObject;
+    if (typeof defObject === "string") {
+      if (!this.schema._pluginAttributeMetadata) {
+        this.schema._pluginAttributeMetadata = {};
+      }
+      this.schema._pluginAttributeMetadata[name] = {
+        __plugin__: pluginName,
+        __pluginCreated__: Date.now()
+      };
+    }
+    this.schema.regeneratePluginMapping();
+    if (this.schema.options.generateAutoHooks) {
+      this.schema.generateAutoHooks();
+    }
+    const processedAttributes = this.schema.preprocessAttributesForValidation(this.schema.attributes);
+    this.schema.validator = new ValidatorManager({ autoEncrypt: false }).compile(merge(
+      { $$async: true, $$strict: false },
+      processedAttributes
+    ));
+    if (this.database) {
+      this.database.emit("plugin-attribute-added", {
+        resource: this.name,
+        attribute: name,
+        plugin: pluginName,
+        definition: defObject
+      });
+    }
+  }
+  /**
+   * Remove a plugin-created attribute from the resource schema
+   * Called when a plugin is uninstalled or no longer needs the attribute
+   *
+   * @param {string} name - Attribute name to remove
+   * @param {string} [pluginName] - Optional plugin name for safety check
+   * @returns {boolean} True if attribute was removed, false if not found
+   *
+   * @example
+   * resource.removePluginAttribute('_hasEmbedding', 'VectorPlugin');
+   */
+  removePluginAttribute(name, pluginName = null) {
+    const attrDef = this.schema.getAttributeDefinition(name);
+    const metadata = this.schema._pluginAttributeMetadata?.[name];
+    const isPluginAttr = typeof attrDef === "object" && attrDef?.__plugin__ || metadata;
+    if (!attrDef || !isPluginAttr) {
+      return false;
+    }
+    const actualPlugin = attrDef?.__plugin__ || metadata?.__plugin__;
+    if (pluginName && actualPlugin !== pluginName) {
+      throw new ResourceError(
+        `Attribute '${name}' belongs to plugin '${actualPlugin}', not '${pluginName}'`,
+        { resource: this.name, attribute: name, actualPlugin, requestedPlugin: pluginName }
+      );
+    }
+    delete this.schema.attributes[name];
+    delete this.attributes[name];
+    if (this.schema._pluginAttributeMetadata?.[name]) {
+      delete this.schema._pluginAttributeMetadata[name];
+    }
+    this.schema.regeneratePluginMapping();
+    if (this.database) {
+      this.database.emit("plugin-attribute-removed", {
+        resource: this.name,
+        attribute: name,
+        plugin: actualPlugin
+      });
+    }
+    return true;
+  }
   /**
    * Add a hook function for a specific event
    * @param {string} event - Hook event (beforeInsert, afterInsert, etc.)
@@ -20725,8 +20979,9 @@ ${errorDetails}`,
     const filterInternalFields = (obj) => {
       if (!obj || typeof obj !== "object") return obj;
       const filtered2 = {};
+      const pluginAttrNames = this.schema._pluginAttributes ? Object.values(this.schema._pluginAttributes).flat() : [];
       for (const [key, value] of Object.entries(obj)) {
-        if (!key.startsWith("_") || key === "_geohash" || key.startsWith("_geohash_zoom")) {
+        if (!key.startsWith("_") || key === "_geohash" || key.startsWith("_geohash_zoom") || pluginAttrNames.includes(key)) {
           filtered2[key] = value;
         }
       }
@@ -20752,7 +21007,16 @@ ${errorDetails}`,
       if (hasOverflow && body) {
         const [okBody, errBody, parsedBody] = await tryFn(() => Promise.resolve(JSON.parse(body)));
         if (okBody) {
-          const [okUnmap, errUnmap, unmappedBody] = await tryFn(() => this.schema.unmapper(parsedBody));
+          let pluginMapFromMeta = null;
+          if (metadata && metadata._pluginmap) {
+            const [okPluginMap, errPluginMap, parsedPluginMap] = await tryFn(
+              () => Promise.resolve(typeof metadata._pluginmap === "string" ? JSON.parse(metadata._pluginmap) : metadata._pluginmap)
+            );
+            pluginMapFromMeta = okPluginMap ? parsedPluginMap : null;
+          }
+          const [okUnmap, errUnmap, unmappedBody] = await tryFn(
+            () => this.schema.unmapper(parsedBody, void 0, pluginMapFromMeta)
+          );
           bodyData = okUnmap ? unmappedBody : {};
         }
       }
@@ -20769,11 +21033,16 @@ ${errorDetails}`,
     if (behavior === "body-only") {
       const [okBody, errBody, parsedBody] = await tryFn(() => Promise.resolve(body ? JSON.parse(body) : {}));
       let mapFromMeta = this.schema.map;
+      let pluginMapFromMeta = null;
       if (metadata && metadata._map) {
         const [okMap, errMap, parsedMap] = await tryFn(() => Promise.resolve(typeof metadata._map === "string" ? JSON.parse(metadata._map) : metadata._map));
         mapFromMeta = okMap ? parsedMap : this.schema.map;
       }
-      const [okUnmap, errUnmap, unmappedBody] = await tryFn(() => this.schema.unmapper(parsedBody, mapFromMeta));
+      if (metadata && metadata._pluginmap) {
+        const [okPluginMap, errPluginMap, parsedPluginMap] = await tryFn(() => Promise.resolve(typeof metadata._pluginmap === "string" ? JSON.parse(metadata._pluginmap) : metadata._pluginmap));
+        pluginMapFromMeta = okPluginMap ? parsedPluginMap : null;
+      }
+      const [okUnmap, errUnmap, unmappedBody] = await tryFn(() => this.schema.unmapper(parsedBody, mapFromMeta, pluginMapFromMeta));
       const result2 = okUnmap ? { ...unmappedBody, id } : { id };
       Object.keys(result2).forEach((k) => {
         result2[k] = fixValue(result2[k]);
@@ -20783,7 +21052,16 @@ ${errorDetails}`,
     if (behavior === "user-managed" && body && body.trim() !== "") {
       const [okBody, errBody, parsedBody] = await tryFn(() => Promise.resolve(JSON.parse(body)));
       if (okBody) {
-        const [okUnmap, errUnmap, unmappedBody] = await tryFn(() => this.schema.unmapper(parsedBody));
+        let pluginMapFromMeta = null;
+        if (metadata && metadata._pluginmap) {
+          const [okPluginMap, errPluginMap, parsedPluginMap] = await tryFn(
+            () => Promise.resolve(typeof metadata._pluginmap === "string" ? JSON.parse(metadata._pluginmap) : metadata._pluginmap)
+          );
+          pluginMapFromMeta = okPluginMap ? parsedPluginMap : null;
+        }
+        const [okUnmap, errUnmap, unmappedBody] = await tryFn(
+          () => this.schema.unmapper(parsedBody, void 0, pluginMapFromMeta)
+        );
         const bodyData = okUnmap ? unmappedBody : {};
         const merged = { ...bodyData, ...unmappedMetadata, id };
         Object.keys(merged).forEach((k) => {
@@ -21031,7 +21309,7 @@ class Database extends EventEmitter {
     this.id = idGenerator(7);
     this.version = "1";
     this.s3dbVersion = (() => {
-      const [ok, err, version] = tryFn(() => true ? "12.2.3" : "latest");
+      const [ok, err, version] = tryFn(() => true ? "12.3.0" : "latest");
       return ok ? version : "latest";
     })();
     this._resourcesMap = {};
@@ -23021,7 +23299,11 @@ class TursoReplicator extends BaseReplicator {
         }
         continue;
       }
-      const attributes = resource.config.versions[resource.config.currentVersion]?.attributes || {};
+      const allAttributes = resource.config.versions[resource.config.currentVersion]?.attributes || {};
+      const pluginAttrNames = resource.schema?._pluginAttributes ? Object.values(resource.schema._pluginAttributes).flat() : [];
+      const attributes = Object.fromEntries(
+        Object.entries(allAttributes).filter(([name]) => !pluginAttrNames.includes(name))
+      );
       for (const tableConfig of tableConfigs) {
         const tableName = tableConfig.table;
         const [okSync, errSync] = await tryFn(async () => {
@@ -36856,6 +37138,7 @@ class VectorPlugin extends Plugin {
    *
    * Detects large vector fields and warns if proper behavior is not set.
    * Can optionally auto-fix by setting body-overflow behavior.
+   * Auto-creates partitions for optional embedding fields to enable O(1) filtering.
    */
   validateVectorStorage() {
     for (const resource of Object.values(this.database.resources)) {
@@ -36892,8 +37175,217 @@ class VectorPlugin extends Plugin {
           }
         }
       }
+      this.setupEmbeddingPartitions(resource, vectorFields);
     }
   }
+  /**
+   * Setup automatic partitions for optional embedding fields
+   *
+   * Creates a partition that separates records with embeddings from those without.
+   * This enables O(1) filtering instead of O(n) full scans when searching/clustering.
+   *
+   * @param {Resource} resource - Resource instance
+   * @param {Array} vectorFields - Detected vector fields with metadata
+   */
+  setupEmbeddingPartitions(resource, vectorFields) {
+    if (!resource.config) return;
+    for (const vectorField of vectorFields) {
+      const isOptional = this.isFieldOptional(resource.schema.attributes, vectorField.name);
+      if (!isOptional) continue;
+      const partitionName = `byHas${this.capitalize(vectorField.name.replace(/\./g, "_"))}`;
+      const trackingFieldName = `_has${this.capitalize(vectorField.name.replace(/\./g, "_"))}`;
+      if (resource.config.partitions && resource.config.partitions[partitionName]) {
+        this.emit("vector:partition-exists", {
+          resource: resource.name,
+          vectorField: vectorField.name,
+          partition: partitionName,
+          timestamp: Date.now()
+        });
+        continue;
+      }
+      if (!resource.config.partitions) {
+        resource.config.partitions = {};
+      }
+      resource.config.partitions[partitionName] = {
+        fields: {
+          [trackingFieldName]: "boolean"
+        }
+      };
+      if (!resource.schema.attributes[trackingFieldName]) {
+        resource.addPluginAttribute(trackingFieldName, {
+          type: "boolean",
+          optional: true,
+          default: false
+        }, "VectorPlugin");
+      }
+      this.emit("vector:partition-created", {
+        resource: resource.name,
+        vectorField: vectorField.name,
+        partition: partitionName,
+        trackingField: trackingFieldName,
+        timestamp: Date.now()
+      });
+      console.log(`\u2705 VectorPlugin: Created partition '${partitionName}' for optional embedding field '${vectorField.name}' in resource '${resource.name}'`);
+      this.installEmbeddingHooks(resource, vectorField.name, trackingFieldName);
+    }
+  }
+  /**
+   * Check if a field is optional in the schema
+   *
+   * @param {Object} attributes - Resource attributes
+   * @param {string} fieldPath - Field path (supports dot notation)
+   * @returns {boolean} True if field is optional
+   */
+  isFieldOptional(attributes, fieldPath) {
+    const parts = fieldPath.split(".");
+    let current = attributes;
+    for (let i = 0; i < parts.length; i++) {
+      const part = parts[i];
+      const attr = current[part];
+      if (!attr) return true;
+      if (typeof attr === "string") {
+        const flags = attr.split("|");
+        if (flags.includes("required")) return false;
+        if (flags.includes("optional") || flags.some((f) => f.startsWith("optional:"))) return true;
+        return !flags.includes("required");
+      }
+      if (typeof attr === "object") {
+        if (i === parts.length - 1) {
+          if (attr.optional === true) return true;
+          if (attr.optional === false) return false;
+          return attr.optional !== false;
+        }
+        if (attr.type === "object" && attr.props) {
+          current = attr.props;
+        } else {
+          return true;
+        }
+      }
+    }
+    return true;
+  }
+  /**
+   * Capitalize first letter of string
+   *
+   * @param {string} str - Input string
+   * @returns {string} Capitalized string
+   */
+  capitalize(str) {
+    return str.charAt(0).toUpperCase() + str.slice(1);
+  }
+  /**
+   * Install hooks to maintain embedding partition tracking field
+   *
+   * @param {Resource} resource - Resource instance
+   * @param {string} vectorField - Vector field name
+   * @param {string} trackingField - Tracking field name
+   */
+  installEmbeddingHooks(resource, vectorField, trackingField) {
+    resource.registerHook("beforeInsert", async (data) => {
+      const hasVector = this.hasVectorValue(data, vectorField);
+      this.setNestedValue(data, trackingField, hasVector);
+      return data;
+    });
+    resource.registerHook("beforeUpdate", async (id, updates) => {
+      if (vectorField in updates || this.hasNestedKey(updates, vectorField)) {
+        const hasVector = this.hasVectorValue(updates, vectorField);
+        this.setNestedValue(updates, trackingField, hasVector);
+      }
+      return updates;
+    });
+    this.emit("vector:hooks-installed", {
+      resource: resource.name,
+      vectorField,
+      trackingField,
+      hooks: ["beforeInsert", "beforeUpdate"],
+      timestamp: Date.now()
+    });
+  }
+  /**
+   * Check if data has a valid vector value for the given field
+   *
+   * @param {Object} data - Data object
+   * @param {string} fieldPath - Field path (supports dot notation)
+   * @returns {boolean} True if vector exists and is valid
+   */
+  hasVectorValue(data, fieldPath) {
+    const value = this.getNestedValue(data, fieldPath);
+    return value != null && Array.isArray(value) && value.length > 0;
+  }
+  /**
+   * Check if object has a nested key
+   *
+   * @param {Object} obj - Object to check
+   * @param {string} path - Dot-notation path
+   * @returns {boolean} True if key exists
+   */
+  hasNestedKey(obj, path) {
+    const parts = path.split(".");
+    let current = obj;
+    for (const part of parts) {
+      if (current == null || typeof current !== "object") return false;
+      if (!(part in current)) return false;
+      current = current[part];
+    }
+    return true;
+  }
+  /**
+   * Get nested value from object using dot notation
+   *
+   * @param {Object} obj - Object to traverse
+   * @param {string} path - Dot-notation path
+   * @returns {*} Value at path or undefined
+   */
+  getNestedValue(obj, path) {
+    const parts = path.split(".");
+    let current = obj;
+    for (const part of parts) {
+      if (current == null || typeof current !== "object") return void 0;
+      current = current[part];
+    }
+    return current;
+  }
+  /**
+   * Set nested value in object using dot notation
+   *
+   * @param {Object} obj - Object to modify
+   * @param {string} path - Dot-notation path
+   * @param {*} value - Value to set
+   */
+  setNestedValue(obj, path, value) {
+    const parts = path.split(".");
+    let current = obj;
+    for (let i = 0; i < parts.length - 1; i++) {
+      const part = parts[i];
+      if (!(part in current) || typeof current[part] !== "object") {
+        current[part] = {};
+      }
+      current = current[part];
+    }
+    current[parts[parts.length - 1]] = value;
+  }
+  /**
+   * Get auto-created embedding partition for a vector field
+   *
+   * Returns partition configuration if an auto-partition exists for the given vector field.
+   * Auto-partitions enable O(1) filtering to only records with embeddings.
+   *
+   * @param {Resource} resource - Resource instance
+   * @param {string} vectorField - Vector field name
+   * @returns {Object|null} Partition config or null
+   */
+  getAutoEmbeddingPartition(resource, vectorField) {
+    if (!resource.config) return null;
+    const partitionName = `byHas${this.capitalize(vectorField.replace(/\./g, "_"))}`;
+    const trackingFieldName = `_has${this.capitalize(vectorField.replace(/\./g, "_"))}`;
+    if (resource.config.partitions && resource.config.partitions[partitionName]) {
+      return {
+        partitionName,
+        partitionValues: { [trackingFieldName]: true }
+      };
+    }
+    return null;
+  }
   /**
    * Auto-detect vector field from resource schema
    *
@@ -37031,11 +37523,12 @@ class VectorPlugin extends Plugin {
       } else if (!vectorField) {
         vectorField = "vector";
       }
-      const {
+      let {
         limit = 10,
         distanceMetric = this.config.distanceMetric,
         threshold = null,
-        partition = null
+        partition = null,
+        partitionValues = null
       } = options;
       const distanceFn = this.distanceFunctions[distanceMetric];
       if (!distanceFn) {
@@ -37051,31 +37544,61 @@ class VectorPlugin extends Plugin {
         });
         throw error;
       }
+      if (!partition) {
+        const autoPartition = this.getAutoEmbeddingPartition(resource, vectorField);
+        if (autoPartition) {
+          partition = autoPartition.partitionName;
+          partitionValues = autoPartition.partitionValues;
+          this._emitEvent("vector:auto-partition-used", {
+            resource: resource.name,
+            vectorField,
+            partition,
+            partitionValues,
+            timestamp: Date.now()
+          });
+        }
+      }
       this._emitEvent("vector:search-start", {
         resource: resource.name,
         vectorField,
         limit,
         distanceMetric,
         partition,
+        partitionValues,
         threshold,
         queryDimensions: queryVector.length,
         timestamp: startTime
       });
       try {
         let allRecords;
-        if (partition) {
+        if (partition && partitionValues) {
           this._emitEvent("vector:partition-filter", {
             resource: resource.name,
             partition,
+            partitionValues,
             timestamp: Date.now()
           });
-          allRecords = await resource.list({ partition, partitionValues: partition });
+          allRecords = await resource.list({ partition, partitionValues });
         } else {
-          allRecords = await resource.getAll();
+          allRecords = resource.getAll ? await resource.getAll() : await resource.list();
         }
         const totalRecords = allRecords.length;
         let processedRecords = 0;
         let dimensionMismatches = 0;
+        if (!partition && totalRecords > 1e3) {
+          const warning = {
+            resource: resource.name,
+            operation: "vectorSearch",
+            totalRecords,
+            vectorField,
+            recommendation: "Use partitions to filter data before vector search for better performance"
+          };
+          this._emitEvent("vector:performance-warning", warning);
+          console.warn(`\u26A0\uFE0F  VectorPlugin: Performing vectorSearch on ${totalRecords} records without partition filter`);
+          console.warn(`   Resource: '${resource.name}'`);
+          console.warn(`   Recommendation: Use partition parameter to reduce search space`);
+          console.warn(`   Example: resource.vectorSearch(vector, { partition: 'byCategory', partitionValues: { category: 'books' } })`);
+        }
         const results = allRecords.filter((record) => record[vectorField] && Array.isArray(record[vectorField])).map((record, index) => {
           try {
             const distance = distanceFn(queryVector, record[vectorField]);
@@ -37159,10 +37682,11 @@ class VectorPlugin extends Plugin {
       } else if (!vectorField) {
         vectorField = "vector";
       }
-      const {
+      let {
         k = 5,
         distanceMetric = this.config.distanceMetric,
         partition = null,
+        partitionValues = null,
         ...kmeansOptions
       } = options;
       const distanceFn = this.distanceFunctions[distanceMetric];
@@ -37179,30 +37703,62 @@ class VectorPlugin extends Plugin {
         });
         throw error;
       }
+      if (!partition) {
+        const autoPartition = this.getAutoEmbeddingPartition(resource, vectorField);
+        if (autoPartition) {
+          partition = autoPartition.partitionName;
+          partitionValues = autoPartition.partitionValues;
+          this._emitEvent("vector:auto-partition-used", {
+            resource: resource.name,
+            vectorField,
+            partition,
+            partitionValues,
+            timestamp: Date.now()
+          });
+        }
+      }
       this._emitEvent("vector:cluster-start", {
         resource: resource.name,
         vectorField,
         k,
         distanceMetric,
         partition,
+        partitionValues,
         maxIterations: kmeansOptions.maxIterations || 100,
         timestamp: startTime
       });
       try {
         let allRecords;
-        if (partition) {
+        if (partition && partitionValues) {
           this._emitEvent("vector:partition-filter", {
             resource: resource.name,
             partition,
+            partitionValues,
             timestamp: Date.now()
           });
-          allRecords = await resource.list({ partition, partitionValues: partition });
+          allRecords = await resource.list({ partition, partitionValues });
         } else {
-          allRecords = await resource.getAll();
+          allRecords = resource.getAll ? await resource.getAll() : await resource.list();
         }
         const recordsWithVectors = allRecords.filter(
           (record) => record[vectorField] && Array.isArray(record[vectorField])
         );
+        if (!partition && allRecords.length > 1e3) {
+          const warning = {
+            resource: resource.name,
+            operation: "cluster",
+            totalRecords: allRecords.length,
+            recordsWithVectors: recordsWithVectors.length,
+            vectorField,
+            recommendation: "Use partitions to filter data before clustering for better performance"
+          };
+          this._emitEvent("vector:performance-warning", warning);
+          console.warn(`\u26A0\uFE0F  VectorPlugin: Performing clustering on ${allRecords.length} records without partition filter`);
+          console.warn(`   Resource: '${resource.name}'`);
+          console.warn(`   Records with vectors: ${recordsWithVectors.length}`);
+          console.warn(`   Recommendation: Use partition parameter to reduce clustering space`);
+          console.warn(`   Example: resource.cluster({ k: 5, partition: 'byCategory', partitionValues: { category: 'books' } })`);
+        }
         if (recordsWithVectors.length === 0) {
           const error = new VectorError("No vectors found in resource", {
             operation: "cluster",
@@ -37446,9 +38002,13 @@ async function generateTypes(database, options = {}) {
   }
   const resourceInterfaces = [];
   for (const [name, resource] of Object.entries(database.resources)) {
-    const attributes = resource.config?.attributes || resource.attributes || {};
+    const allAttributes = resource.config?.attributes || resource.attributes || {};
     const timestamps = resource.config?.timestamps || false;
-    const interfaceDef = generateResourceInterface(name, attributes, timestamps);
+    const pluginAttrNames = resource.schema?._pluginAttributes ? Object.values(resource.schema._pluginAttributes).flat() : [];
+    const userAttributes = Object.fromEntries(
+      Object.entries(allAttributes).filter(([name2]) => !pluginAttrNames.includes(name2))
+    );
+    const interfaceDef = generateResourceInterface(name, userAttributes, timestamps);
     lines.push(interfaceDef);
     resourceInterfaces.push({
       name,