@happyvertical/smrt-core 0.36.8 → 0.37.0

package/dist/object.js

@@ -289,12 +289,13 @@ class SmrtObject extends SmrtClass {
     const options = this.options;
     if (options.created_at !== void 0) this.created_at = options.created_at;
     if (options.updated_at !== void 0) this.updated_at = options.updated_at;
-    if (options._meta_type !== void 0) {
+    if (typeof options._meta_type === "string") {
       this.setMetaType(options._meta_type);
     }
     const fields = await fieldsFromClass(
       this.constructor
     );
+    const writable = this;
     for (const [key, field] of Object.entries(fields)) {
       if (options[key] !== void 0) {
         const clonedValue = this.cloneValue(options[key]);
@@ -307,7 +308,7 @@ class SmrtObject extends SmrtClass {
           }
         }
         if (!descriptor || descriptor.set || descriptor.writable === true) {
-          this[key] = clonedValue;
+          writable[key] = clonedValue;
         }
       }
     }
@@ -463,17 +464,18 @@ class SmrtObject extends SmrtClass {
       });
     }
     if (isSTI) {
-      if (!formattedData._meta_type) {
+      const metaType = formattedData._meta_type;
+      if (!metaType) {
         throw new Error(
           `STI validation failed: Missing _meta_type discriminator in database row for ${className}. Ensure the row was saved with STI support enabled.`
         );
       }
-      if (!isValidMetaType(formattedData._meta_type, className)) {
+      if (!isValidMetaType(metaType, className)) {
         throw new Error(
-          `STI validation failed: Type mismatch when loading ${className}. Database row has _meta_type='${formattedData._meta_type}' but expected '${getExpectedMetaType(className)}'. This usually means you're trying to load a row with the wrong class.`
+          `STI validation failed: Type mismatch when loading ${className}. Database row has _meta_type='${metaType}' but expected '${getExpectedMetaType(className)}'. This usually means you're trying to load a row with the wrong class.`
         );
       }
-      this.setMetaType(formattedData._meta_type);
+      this.setMetaType(metaType);
     }
     if (process.env.DEBUG_STI) {
       logger.debug("[loadDataFromDb] Starting field hydration", {
@@ -483,6 +485,7 @@ class SmrtObject extends SmrtClass {
     }
     let hydratedCount = 0;
     let skippedCount = 0;
+    const writable = this;
     for (const field in fields) {
       if (Object.hasOwn(fields, field)) {
         let descriptor = Object.getOwnPropertyDescriptor(this, field);
@@ -501,7 +504,7 @@ class SmrtObject extends SmrtClass {
               valueType: typeof value
             });
           }
-          this[field] = value;
+          writable[field] = value;
           hydratedCount++;
         } else {
           skippedCount++;
@@ -555,6 +558,11 @@ class SmrtObject extends SmrtClass {
    *
    * @returns Object containing field definitions with current values
    */
+  // Explicit `any` return (documented S4 #1579 leaf): subclasses legitimately
+  // OVERRIDE getFields() with domain-specific shapes (e.g. projects'
+  // `Project.getFields(): Promise<ProjectField[]>`), which a precise field-map
+  // return type would reject. The body below stays internally typed.
+  // biome-ignore lint/suspicious/noExplicitAny: subclasses OVERRIDE getFields() with domain shapes (e.g. `Project.getFields(): Promise<ProjectField[]>`); a precise base return type would reject those overrides. S4 #1579.
   async getFields() {
     const className = this.getResolvedClassName();
     const cachedFields = await ObjectRegistry.getAllFields(className);
@@ -595,7 +603,9 @@ class SmrtObject extends SmrtClass {
    * class Article extends SmrtObject {
    *   body: string = '';
    *
-   *   protected transformJSON(data: any): any {
+   *   protected transformJSON(
+   *     data: Record<string, unknown>,
+   *   ): Record<string, unknown> {
    *     return {
    *       ...data,
    *       wordCount: this.body.split(/\s+/).length,
@@ -636,13 +646,15 @@ class SmrtObject extends SmrtClass {
       created_at: this.created_at,
       updated_at: this.updated_at
     };
+    const self = this;
     const tableStrategy = ObjectRegistry.getTableStrategy(
       this.getResolvedQualifiedName()
     );
     const isSTI = tableStrategy === "sti";
+    const metaData = {};
     if (isSTI) {
       data._meta_type = this.getResolvedQualifiedName();
-      data._meta_data = {};
+      data._meta_data = metaData;
     }
     const registered = ObjectRegistry.getClass(className);
     let registeredFields = registered?.inheritedFields || ObjectRegistry.getFields(className);
@@ -665,7 +677,7 @@ class SmrtObject extends SmrtClass {
     }
     for (const key of registeredFields.keys()) {
       if (key.startsWith("_") || key === "id" || key === "slug" || key === "context" || key === "created_at" || key === "updated_at" || key === "options" || // Skip options object (not a database column)
-      typeof this[key] === "function") {
+      typeof self[key] === "function") {
         continue;
       }
       const fieldDef = registeredFields.get(key);
@@ -675,21 +687,22 @@ class SmrtObject extends SmrtClass {
       if (fieldDef && (fieldDef.type === "oneToMany" || fieldDef.type === "manyToMany")) {
         continue;
       }
-      const prop = this[key];
+      const prop = self[key];
       const value = this.getPropertyValue(key);
       if (value === void 0) {
         const fieldType = prop && typeof prop === "object" && "type" in prop && prop.type || fieldDef?.type;
         if (fieldType === "text") {
-          const hasTenancyMarker = prop && typeof prop === "object" && "__tenancy" in prop && prop.__tenancy?.isTenantIdField || fieldDef?.__tenancy?.isTenantIdField || fieldDef?._meta?.__tenancy?.isTenantIdField;
+          const propTenancy = prop && typeof prop === "object" && "__tenancy" in prop ? prop.__tenancy : void 0;
+          const hasTenancyMarker = propTenancy?.isTenantIdField || fieldDef?.__tenancy?.isTenantIdField || fieldDef?._meta?.__tenancy?.isTenantIdField;
           if (hasTenancyMarker) {
             if (isSTI && fieldDef?.type === "meta") {
-              data._meta_data[key] = null;
+              metaData[key] = null;
             } else {
               data[key] = null;
             }
           } else {
             if (isSTI && fieldDef?.type === "meta") {
-              data._meta_data[key] = "";
+              metaData[key] = "";
             } else {
               data[key] = "";
             }
@@ -697,7 +710,7 @@ class SmrtObject extends SmrtClass {
         } else if (fieldType === "json") {
           const defaultValue = fieldDef?.default ?? null;
           if (isSTI && fieldDef?.type === "meta") {
-            data._meta_data[key] = defaultValue;
+            metaData[key] = defaultValue;
           } else {
             data[key] = defaultValue;
           }
@@ -705,7 +718,7 @@ class SmrtObject extends SmrtClass {
         continue;
       }
       if (isSTI && fieldDef && fieldDef.type === "meta") {
-        data._meta_data[key] = value;
+        metaData[key] = value;
       } else {
         data[key] = value;
       }
@@ -899,13 +912,14 @@ class SmrtObject extends SmrtClass {
    */
   async getSlug() {
     if (!this.slug) {
+      const self = this;
       let sourceField = null;
-      if (this.name) {
-        sourceField = String(this.name);
-      } else if (this.title) {
-        sourceField = String(this.title);
-      } else if (this.label) {
-        sourceField = String(this.label);
+      if (self.name) {
+        sourceField = String(self.name);
+      } else if (self.title) {
+        sourceField = String(self.title);
+      } else if (self.label) {
+        sourceField = String(self.label);
       } else if (this.id) {
         sourceField = String(this.id);
       }
@@ -1263,9 +1277,12 @@ See issue #377: https://github.com/happyvertical/smrt/issues/377`
       }
       return;
     }
-    const fields = await fieldsFromClass(this.constructor);
+    const fields = await fieldsFromClass(
+      this.constructor
+    );
     for (const [fieldName, field] of Object.entries(fields)) {
-      if (field.options?.required) {
+      const options = field?.options;
+      if (options?.required) {
         const value = this.getFieldValue(fieldName);
         if (value === null || value === void 0 || value === "") {
           throw ValidationError.requiredField(fieldName, className);
@@ -1822,6 +1839,26 @@ Based on the content body, please follow the instructions and provide a response
   isRelatedLoaded(fieldName) {
     return this._loadedRelationships.has(fieldName);
   }
+  /**
+   * Internal: seed the lazy-load relationship cache from an external batch
+   * loader.
+   *
+   * `SmrtCollection`'s eager `include:` and `getOrUpsert` paths resolve
+   * relationships in bulk and need to prime each instance's cache so a later
+   * {@link loadRelated}/{@link loadRelatedMany} call returns the already-fetched
+   * value instead of re-querying. This method is the sanctioned write path into
+   * the otherwise-private `_loadedRelationships` map, so collaborators never have
+   * to structurally cast into the private field (which the no-private-reach-ins
+   * convention forbids). The leading underscore keeps it out of the generated
+   * REST/CLI/MCP surface, like other framework-internal members.
+   *
+   * @param fieldName - Relationship field whose value is being cached
+   * @param value - The loaded relationship (a `SmrtObject`, an array of them, or
+   *   `null`), stored verbatim
+   */
+  _setLoadedRelationship(fieldName, value) {
+    this._loadedRelationships.set(fieldName, value);
+  }
   /**
    * Lazy-loads a `foreignKey` or `crossPackageRef` relationship and caches the
    * result.
@@ -1859,6 +1896,10 @@ Based on the content body, please follow the instructions and provide a response
    *
    * @see {@link getRelated} for a convenience wrapper that auto-detects relationship type
    */
+  // Returns a polymorphic related object whose concrete subclass type only the
+  // CALLER knows (e.g. `metafield.validateValue(...)`). Typed `any` so callers
+  // can use the concrete API without a cast at every site; a generic with a
+  // `SmrtObject` default wouldn't help untyped callers. Documented S4 #1579 leaf.
   async loadRelated(fieldName, opts) {
     if (this._loadedRelationships.has(fieldName)) {
       const cached = this._loadedRelationships.get(fieldName);
@@ -1995,6 +2036,8 @@ Based on the content body, please follow the instructions and provide a response
    * console.log(`${orders.length} orders found`);
    * ```
    */
+  // Polymorphic related objects; concrete type is caller-known (see loadRelated).
+  // Documented S4 #1579 leaf.
   async loadRelatedMany(fieldName, opts) {
     if (this._loadedRelationships.has(fieldName)) {
       const cached = this._loadedRelationships.get(fieldName);
@@ -2104,7 +2147,8 @@ Based on the content body, please follow the instructions and provide a response
       fieldName
     );
     const opts = relationship.options || {};
-    const through = decorator?.through ?? opts.through ?? opts._meta?.through;
+    const optsMeta = opts._meta && typeof opts._meta === "object" ? opts._meta : void 0;
+    const through = decorator?.through ?? opts.through ?? optsMeta?.through;
     if (!through) {
       throw RuntimeError.invalidState(
         `manyToMany field ${fieldName} on ${relationship.sourceClass} is missing the 'through' join table name`,
@@ -2113,12 +2157,12 @@ Based on the content body, please follow the instructions and provide a response
     }
     const targetSimpleName = relationship.targetClass.includes(":") ? relationship.targetClass.split(":").pop() : relationship.targetClass;
     const sourceSimpleName = relationship.sourceClass.includes(":") ? relationship.sourceClass.split(":").pop() : relationship.sourceClass;
-    const sourceColumn = decorator?.sourceKey ?? opts.sourceKey ?? opts._meta?.sourceKey ?? `${toSnakeCase(sourceSimpleName)}_id`;
-    const targetColumn = decorator?.targetKey ?? opts.targetKey ?? opts._meta?.targetKey ?? `${toSnakeCase(targetSimpleName)}_id`;
+    const sourceColumn = decorator?.sourceKey ?? opts.sourceKey ?? optsMeta?.sourceKey ?? `${toSnakeCase(sourceSimpleName)}_id`;
+    const targetColumn = decorator?.targetKey ?? opts.targetKey ?? optsMeta?.targetKey ?? `${toSnakeCase(targetSimpleName)}_id`;
     return {
       through: String(through),
-      sourceColumn,
-      targetColumn,
+      sourceColumn: String(sourceColumn),
+      targetColumn: String(targetColumn),
       targetClassName: relationship.targetClass
     };
   }
@@ -2145,6 +2189,8 @@ Based on the content body, please follow the instructions and provide a response
    * const orders = await customer.getRelated('orders');
    * ```
    */
+  // Polymorphic related object(s); concrete type is caller-known (see
+  // loadRelated). Documented S4 #1579 leaf.
   async getRelated(fieldName, opts) {
     if (this._loadedRelationships.has(fieldName)) {
       const cached = this._loadedRelationships.get(fieldName);
@@ -2337,7 +2383,7 @@ Based on the content body, please follow the instructions and provide a response
     }
     if (result) {
       try {
-        return JSON.parse(result.value);
+        return JSON.parse(String(result.value));
       } catch (error) {
         logger.warn("Skipping corrupted _smrt_contexts value in recall()", {
           ownerClass: this._className,