Type Fix for Returned Schemas

CHANGELOG.md

@@ -5,7 +5,7 @@ x.x.x Release notes (yyyy-MM-dd)
 
 ### Fixed
 * <How to hit and notice issue? what was the impact?> ([#????](https://github.com/realm/realm-js/issues/????), since v?.?.?)
-* None.
+* Add canonical schema type for returned schemas ([#4580](https://github.com/realm/realm-js/pull/4580))
 
 ### Compatibility
 * MongoDB Realm Cloud.

docs/realm.js

@@ -54,7 +54,7 @@ class Realm {
   /**
    * A normalized representation of the schema provided in the
    * {@link Realm~Configuration Configuration} when this Realm was constructed.
-   * @type {Realm~ObjectSchema[]}
+   * @type {Realm~CanonicalObjectSchema[]}
    * @readonly
    * @since 0.12.0
    */
@@ -499,6 +499,33 @@ class Realm {
  *   name. Queries can be done using both the public and the underlying property name.
  */
 
+/**
+ * The retreived schema from an open Realm has a different structure as the input schema.
+ * @typedef Realm~CanonicalObjectSchema
+ * @type {Object}
+ * @property {string} name - Represents the object type.
+ * @property {string} [primaryKey] - The name of a `"string"` or `"int"` property
+ *   that must be unique across all objects of this type within the same Realm.
+ * @property {boolean} [embedded] - True if the object type is embedded. An embedded object
+ *   can be linked to by at most one parent object. Default value: false.
+ * @property {Object<string, (Realm~PropertyType|Realm~ObjectSchemaProperty|Realm~ObjectSchema)>} properties -
+ *   An object where the keys are property names and the values represent the property type.
+ */
+
+/**
+ * @typedef Realm~CanonicalObjectSchemaProperty
+ * @type {Object}
+ * @property {string} name - The name of this property.
+ * @property {Realm~PropertyType} type - The type of this property.
+ * @property {string} [property] - When using `"linkingObjects"` this value will represent the linked property on the linked object
+ * @property {boolean} optional - Signals that this property may be assigned `null` or `undefined`.
+ *   For `"list"`, `"dictionary"` or `"set"` properties of non-object types, this instead signals whether the values inside the list may be assigned `null` or `undefined`.
+ *   This is not supported for `"list"` or `"set"` properties of object types and `"linkingObjects"` properties.
+ * @property {boolean} indexed - Signals that this property is indexed. Only supported for
+ *   `"string"`, `"int"`, and `"bool"` properties.
+ * @property {string} mapTo - The name of the alias this property has been set to.
+ */
+
 /**
  * The type of an object may either be specified as a string equal to the `name` in a
  * {@link Realm~ObjectSchema ObjectSchema} definition, **or** a constructor that was specified

integration-tests/tests/src/tests/dynamic-schema-updates.ts

@@ -72,7 +72,7 @@ describe("realm._updateSchema", () => {
     // Copy the schema
     const updatedSchema = [...realm.schema];
     // Locate the Dog schema
-    const dogSchema = updatedSchema.find((s) => s.name === "Dog");
+    const dogSchema = updatedSchema.find((s) => s.name === "Dog") as Realm.ObjectSchema;
     if (!dogSchema) throw new Error("Schema not found");
 
     // Add a fields property

types/index.d.ts

@@ -40,6 +40,7 @@ declare namespace Realm {
 
     /**
      * ObjectSchemaProperty
+     * This is the structure of a schema as input when configuring a Realm
      * @see { @link https://realm.io/docs/javascript/latest/api/Realm.html#~ObjectSchemaProperty }
      */
     interface ObjectSchemaProperty {
@@ -52,9 +53,28 @@ declare namespace Realm {
         mapTo?: string;
     }
 
+    /**
+     * CanonicalObjectSchemaProperty
+     * This depicts the structure of a schema retrieved from a Realm
+     * @see { @link https://realm.io/docs/javascript/latest/api/Realm.html#~CanonicalObjectSchemaProperty }
+     */
+    interface CanonicalObjectSchemaProperty {
+        name: string;
+        type: PropertyType;
+        objectType: string;
+        property?: string;
+        optional: boolean;
+        indexed: boolean;
+        mapTo: string;
+    }
+
     // properties types
     interface PropertiesTypes {
-        [keys: string]: PropertyType | ObjectSchemaProperty | ObjectSchema;
+        [keys: string]: ObjectSchemaProperty | ObjectSchema | PropertyType;
+    }
+
+    interface CanonicalPropertiesTypes {
+        [keys: string]: CanonicalObjectSchemaProperty;
     }
 
     enum UpdateMode {
@@ -67,13 +87,21 @@ declare namespace Realm {
      * ObjectSchema
      * @see { @link https://realm.io/docs/javascript/latest/api/Realm.html#~ObjectSchema }
      */
-    interface ObjectSchema {
+
+    interface BaseObjectSchema {
         name: string;
         primaryKey?: string;
         embedded?: boolean;
+    }
+
+    interface ObjectSchema extends BaseObjectSchema {
         properties: PropertiesTypes;
     }
 
+    interface CanonicalObjectSchema extends BaseObjectSchema {
+        properties: CanonicalPropertiesTypes;
+    }
+
     /**
      * ObjectClass
      * @see { @link https://realm.io/docs/javascript/latest/api/Realm.html#~ObjectClass }
@@ -960,7 +988,7 @@ declare class Realm {
     readonly empty: boolean;
     readonly path: string;
     readonly readOnly: boolean;
-    readonly schema: Realm.ObjectSchema[];
+    readonly schema: Realm.CanonicalObjectSchema[];
     readonly schemaVersion: number;
     readonly isInTransaction: boolean;
     readonly isClosed: boolean;