@cubicweb/client 2.1.1 → 3.0.0-alpha.5

package/src/schema/classes/EntitySchema.ts

@@ -8,6 +8,8 @@ import { MatchedRelationDefinition, RelationDefinitionMatcher } from "./Utils";
  * Wrapper around raw entity schemas from the Schema.
  * You should never have to create this object yourself.
  * Instead, retrieve these objects from the methods in the `Schema` class.
+ *
+ * @category Schema
  */
 export class EntitySchema<
   E extends EntityRawSchemaArray = EntityRawSchemaArray,
@@ -49,43 +51,54 @@ export class EntitySchema<
   }
 
   /**
-   * Gets the list of relation definitions schemas with this entity as subject.
-   * In case a relation definition schema has this entity as both object and subject,
-   * there will be dupicates when used along with `objectRelationsDefinitions`.
+   * Gets the list of attribute schemas (relation definition schemas with final at false)
+   * for this entity schema.
    */
-  get subjectRelationDefinitions(): RelationDefinitionSchema<
+  get attributes(): RelationDefinitionSchema<
     E,
     R,
     MatchedRelationDefinition<
       E,
       R,
-      { subject: ERawSchema["type"]; final: false }
+      { subject: ERawSchema["type"]; final: true }
     >
   >[] {
     return this.schema.matchRelationDefinitions({
+      final: true,
       subject: this.type,
-      final: false,
     });
   }
 
-  /**
-   * Gets the list of relation definitions schemas with this entity as object.
-   * In case a relation definition schema has this entity as both object and subject,
-   * there will be dupicates when used along with `subjectRelationDefinitions`.
-   */
-  get objectRelationsDefinitions(): RelationDefinitionSchema<
-    E,
-    R,
-    MatchedRelationDefinition<
+  get relationDefinitions(): {
+    subject: RelationDefinitionSchema<
       E,
       R,
-      { object: ERawSchema["type"]; final: false }
-    >
-  >[] {
-    return this.schema.matchRelationDefinitions({
-      object: this.type,
-      final: false,
-    });
+      MatchedRelationDefinition<
+        E,
+        R,
+        { subject: ERawSchema["type"]; final: false }
+      >
+    >[];
+    object: RelationDefinitionSchema<
+      E,
+      R,
+      MatchedRelationDefinition<
+        E,
+        R,
+        { object: ERawSchema["type"]; final: false }
+      >
+    >[];
+  } {
+    return {
+      subject: this.schema.matchRelationDefinitions({
+        subject: this.type,
+        final: false,
+      }),
+      object: this.schema.matchRelationDefinitions({
+        object: this.type,
+        final: false,
+      }),
+    };
   }
 
   /**
@@ -103,23 +116,4 @@ export class EntitySchema<
   >[] {
     return this.schema.matchRelationDefinitions(matcher);
   }
-
-  /**
-   * Gets the list of attribute schemas (relation definition schemas with final at false)
-   * for this entity schema.
-   */
-  get attributes(): RelationDefinitionSchema<
-    E,
-    R,
-    MatchedRelationDefinition<
-      E,
-      R,
-      { subject: ERawSchema["type"]; final: true }
-    >
-  >[] {
-    return this.schema.matchRelationDefinitions({
-      final: true,
-      subject: this.type,
-    });
-  }
 }

package/src/schema/classes/RelationDefinitionSchema.ts

@@ -7,12 +7,14 @@ import {
 import { IsLooseSchema, EntityRawSchemaByType } from "../raw/Utils";
 import { EntitySchema } from "./EntitySchema";
 import { Schema } from "./Schema";
-import { cardinalityRequired } from "./Utils";
+import { EntityRole, isCardinalityRequired } from "./Utils";
 
 /**
  * Wrapper around raw relation definition schemas from the Schema.
  * You should never have to create this object yourself.
  * Instead, retrieve these objects from the methods in the `Schema` class.
+ *
+ * @category Schema
  */
 export class RelationDefinitionSchema<
   E extends EntityRawSchemaArray = EntityRawSchemaArray,
@@ -84,22 +86,11 @@ export class RelationDefinitionSchema<
   /**
    * The cardinality of this relation definition schema.
    */
-  get cardinality(): RDef["cardinality"] {
-    return this.relDef.cardinality;
-  }
-
-  /**
-   * The cardinality of this relation definition schema's subject.
-   */
-  get subjectCardinality(): Cardinality {
-    return this.relDef.cardinality[0] as Cardinality;
-  }
-
-  /**
-   * The cardinality of this relation definition schema's object.
-   */
-  get objectCardinality(): Cardinality {
-    return this.relDef.cardinality[1] as Cardinality;
+  get cardinality(): { subject: Cardinality; object: Cardinality } {
+    return {
+      subject: this.relDef.cardinality[0] as Cardinality,
+      object: this.relDef.cardinality[1] as Cardinality,
+    };
   }
 
   /**
@@ -144,13 +135,7 @@ export class RelationDefinitionSchema<
    * @param role The point of view to use
    * @returns
    */
-  isRequired(role: "subject" | "object") {
-    let cardinality: Cardinality;
-    if (role === "subject") {
-      cardinality = this.subjectCardinality;
-    } else {
-      cardinality = this.objectCardinality;
-    }
-    return cardinalityRequired(cardinality);
+  isRequired(role: EntityRole) {
+    return isCardinalityRequired(this.cardinality[role]);
   }
 }

package/src/schema/classes/Schema.ts

@@ -19,6 +19,8 @@ const rawSchemaKey: unique symbol = Symbol("Indexer of the rawSchema");
  * Wrapper around the raw JSON Schema.
  * It is recommended to use this class instead of the raw JSON Schema
  * as it is more robust to schema changes and provides utility functions.
+ *
+ * @category Schema
  */
 export class Schema<
   E extends EntityRawSchemaArray = EntityRawSchemaArray,

package/src/schema/classes/Utils.ts

@@ -7,12 +7,26 @@ import {
 import { Schema } from "./Schema";
 import { EntitySchema } from "./EntitySchema";
 
+// This prefix is often applied to relation types as convention
+// indicating a relation is viewed from the object's point of view
+// We do not export it and instead encourage users to use the utility functions
+const REVERSE_INDICATOR = "reverse_";
+
+/**
+ * An entity role in a relation.
+ *
+ * @category Utils
+ */
+export type EntityRole = "subject" | "object";
+
 /**
  * Returns the given schema using loose typing.
  * Can be useful when working with generic schemas
  *
  * @param schema The schema to create a loose type for
  * @returns A loosely typed schema
+ *
+ * @category Utils
  */
 export const getLooseSchema = <
   E extends EntityRawSchemaArray = EntityRawSchemaArray,
@@ -28,13 +42,174 @@ export const getLooseSchema = <
  *
  * @param cardinality The cardinality to check
  * @returns True if the cardinality is 1 or +
+ *
+ * @category Utils
  */
-export function cardinalityRequired(cardinality: Cardinality): boolean {
+export function isCardinalityRequired(cardinality: Cardinality): boolean {
   return cardinality === "1" || cardinality === "+";
 }
 
+/**
+ * Checks if the cardinality allows multiple entities to be present
+ *
+ * @param cardinality The cardinility to check
+ * @returns True if the cardinality is `*` or `+`
+ *
+ * @category Utils
+ */
+export const isCardinalityMultiple = (cardinality: Cardinality): boolean => {
+  return cardinality === "*" || cardinality === "+";
+};
+
+/**
+ * Checks if the cardinality allows entities to be absent
+ *
+ * @param cardinality The cardinility to check
+ * @returns True if the cardinality is `?` or `*`
+ *
+ * @category Utils
+ */
+export const isCardinalityOptional = (cardinality: Cardinality): boolean => {
+  return cardinality === "?" || cardinality === "*";
+};
+
+/**
+ * Reverses the given role name
+ *
+ * @param role The role to reverse
+ * @returns "object" if the given role was "subject", "subject" otherwise
+ *
+ * @category Utils
+ */
+export function getOppositeRelationRole(role: EntityRole): EntityRole {
+  return role === "subject" ? "object" : "subject";
+}
+
+/**
+ * Checks if the given relation type is reversed.
+ *
+ * A reversed relation means the relation is considered from the object entity
+ * point of view.
+ * The reverse indicator is a prefix added as a convention in CubicWeb.
+ *
+ * @param relationType The relation type to check
+ * @returns True if the relation type starts with the reverse indicator
+ *
+ * @category Utils
+ */
+export const isRelationTypeReversed = (relationType: string): boolean => {
+  return relationType.startsWith(REVERSE_INDICATOR);
+};
+
+/**
+ * Gets the entity role in the given relation type by
+ * checking for the reverse indicator
+ *
+ * A reversed relation means the relation is considered from the object entity
+ * point of view.
+ * The reverse indicator is a prefix added as a convention in CubicWeb.
+ *
+ * @param relationType The relation type to check
+ * @returns "subject" if the relation is not reversed, "object" otherwise
+ *
+ * @category Utils
+ */
+export const getRoleFromRelationType = (relationType: string): EntityRole => {
+  return isRelationTypeReversed(relationType) ? "object" : "subject";
+};
+
+/**
+ * Adds the reverse indicator from the relation type if it is not already present.
+ *
+ * A reversed relation means the relation is considered from the object entity
+ * point of view.
+ * The reverse indicator is a prefix added as a convention in CubicWeb.
+ *
+ * @param relationType The relation type to transform
+ * @returns The relation type with the reverse indicator added or removed
+ *
+ * @category Utils
+ */
+export const getReverseRelationType = (relationType: string): string => {
+  if (!isRelationTypeReversed(relationType)) {
+    return `${REVERSE_INDICATOR}${relationType}`;
+  } else {
+    return relationType;
+  }
+};
+
+/**
+ * Clears the reverse indicator from the relation type if it is present.
+ *
+ * A reversed relation means the relation is considered from the object entity
+ * point of view.
+ * The reverse indicator is a prefix added as a convention in CubicWeb.
+ *
+ * @param relationType The relation type to transform
+ * @returns The relation type with the reverse indicator added or removed
+ *
+ * @category Utils
+ */
+export const getRawRelationType = (relationType: string): string => {
+  if (isRelationTypeReversed(relationType)) {
+    return relationType.replace(REVERSE_INDICATOR, "");
+  } else {
+    return relationType;
+  }
+};
+
+/**
+ * Returns the relation type with the reverse indicator added if necessary.
+ *
+ * A reversed relation means the relation is considered from the object entity
+ * point of view.
+ * The reverse indicator is a prefix added as a convention in CubicWeb.
+ *
+ * @param relationType The relation type to transform
+ * @param role The entity role in the relation
+ * @returns A relation type with the reverse indicator if necessary
+ *
+ * @category Utils
+ */
+export const getRelationType = (relationType: string, role: EntityRole) => {
+  return role === "subject"
+    ? relationType
+    : getReverseRelationType(relationType);
+};
+
+/**
+ * Finds the relation matching the provided source, relation typ and target
+ *
+ * @param entitySchema The entity schema the relation is from
+ * @param sourceType The entity type acting as source for the relation
+ * @param relationType The type of the relation to use. Can have the reverse indicator to decide the role of the source/target entities
+ * @param targetType The entity type acting as target for the relation
+ * @returns The relation definition matching the triplet source relation target
+ *
+ * @category Utils
+ */
+export const getRelationDefinition = (
+  entitySchema: EntitySchema,
+  sourceType: string,
+  relationType: string,
+  targetType: string
+) => {
+  const role = getRoleFromRelationType(relationType);
+  const match = entitySchema.matchRelationDefinitions({
+    [role]: sourceType,
+    type: getRawRelationType(relationType),
+    [getOppositeRelationRole(role)]: targetType,
+  });
+  if (match.length > 0) {
+    return match[0];
+  }
+  return undefined;
+};
+
 /**
  * Partial raw relation definition schema type.
+ *
+ * @category Utils
  */
 export type RelationDefinitionMatcher<E extends EntityRawSchemaArray> = Partial<
   RelationDefinitionRawSchema<E>
@@ -45,6 +220,8 @@ export type RelationDefinitionMatcher<E extends EntityRawSchemaArray> = Partial<
  * If it finds a relation definition matching the partial one given, it will return its type.
  * If it cannot find any relation definition matching, it will return the `never` type
  * and TypeScript will give compile errors.
+ *
+ * @category Utils
  */
 export type MatchedRelationDefinition<
   E extends EntityRawSchemaArray,

package/src/schema/raw/Constraints.ts

@@ -10,7 +10,7 @@ type ConstraintBase<
 };
 
 /**
- * THe type of a constraint message when one is present.
+ * The type of a constraint message when one is present.
  */
 type ConstraintMessage = string | null;
 
@@ -33,6 +33,8 @@ export type RegexpConstraint = ConstraintBase<
  * Reference to an attribute used in constraints.
  *
  * @property \_\_attribute\_\_ name of the attribute in the same entity
+ *
+ * @category Schema
  */
 export interface Attribute {
   __attribute__: string;
@@ -50,6 +52,8 @@ export interface TimeDelta {
  * @property \_\_today\_\_ always true
  * @property offset delta to current date at the time of the check
  * @property type name of the Python class used to do the comparison
+ *
+ * @category Schema
  */
 export interface Today {
   __today__: true;
@@ -62,6 +66,8 @@ export interface Today {
  *
  * @property \_\_now\_\_ always true
  * @property offset delta to current date at the time of the check
+ *
+ * @category Schema
  */
 export interface Now {
   __now__: true;
@@ -70,13 +76,11 @@ export interface Now {
 
 /**
  * All the possible operators inside a constraint.
+ *
+ * @category Schema
  */
 export type ConstraintOperator = ">" | ">=" | "<" | "<=";
 
-/**
- * @property value.boundary boudary value to compare the attribut
- *
- */
 export type BoundaryConstraint = ConstraintBase<
   "BoundaryConstraint",
   {
@@ -115,6 +119,8 @@ export type RQLConstraint = ConstraintBase<
 
 /**
  * Type representing all possible constraints for attributes.
+ *
+ * @category Schema
  */
 export type AttributeConstraint = Readonly<
   | UniqueConstraint
@@ -129,6 +135,8 @@ export type AttributeConstraint = Readonly<
 
 /**
  * Type representing all possible constraints for relations.
+ *
+ * @category Schema
  */
 export type RelationConstraint = Readonly<
   RQLVocabularyConstraint | RQLConstraint

package/src/schema/raw/Entities.ts

@@ -1,5 +1,7 @@
 /**
  * Type representing an entity schema.
+ *
+ * @category Schema
  */
 export type EntityRawSchema = {
   type: string;
@@ -9,5 +11,7 @@ export type EntityRawSchema = {
 
 /**
  * Type representing a list of entity schemas.
+ *
+ * @category Schema
  */
 export type EntityRawSchemaArray = ReadonlyArray<EntityRawSchema>;

package/src/schema/raw/RelationDefinitions.ts

@@ -1,13 +1,18 @@
+import { EntityRole } from "../classes/Utils";
 import { AttributeConstraint, RelationConstraint } from "./Constraints";
 import { EntityRawSchema, EntityRawSchemaArray } from "./Entities";
 
 /**
  * Type representing all the possible cardinalities in CubicWeb.
+ *
+ * @category Schema
  */
 export type Cardinality = "*" | "1" | "?" | "+";
 
 /**
  * Type representing a cardinality pair as used in relation definitions.
+ *
+ * @category Schema
  */
 export type CardinalityPair = `${Cardinality}${Cardinality}`;
 
@@ -109,6 +114,8 @@ export type BuildObj = Readonly<
 
 /**
  * Type representing the possible options for an attribute.
+ *
+ * @category Schema
  */
 export type AttributeOptions = {
   indexed?: boolean;
@@ -118,12 +125,14 @@ export type AttributeOptions = {
 
 /**
  * Type representing the possible options for a relation definition.
+ *
+ * @category Schema
  */
 export type RelationOptions = {
   symmetric?: boolean;
   inlined?: boolean;
-  fulltext_container?: "subject" | "object";
-  composite?: "subject" | "object";
+  fulltext_container?: EntityRole;
+  composite?: EntityRole;
 };
 
 /**
@@ -131,6 +140,8 @@ export type RelationOptions = {
  * It can represent both attributes and relations depending on the value of Final.
  *
  * It can infer default values type depending on the object type if the relation is final.
+ *
+ * @category Schema
  */
 export type RelationDefinitionRawSchema<
   ESchemas extends EntityRawSchemaArray,
@@ -157,6 +168,8 @@ export type RelationDefinitionRawSchema<
 
 /**
  * Type representing a list of relation definitions.
+ *
+ * @category Schema
  */
 export type RelationDefinitionRawSchemaArray<
   ESchemas extends EntityRawSchemaArray

package/src/schema/raw/Schema.ts

@@ -6,6 +6,8 @@ import { RelationDefinitionRawSchemaArray } from "./RelationDefinitions";
  * You can export this schema from your CubicWeb instance using the command:
  *
  * `cubicweb-ctl export-schema -f typescript <YOUR_INSTANCE_NAME>`
+ *
+ * @category Schema
  */
 export type RawSchema<
   E extends EntityRawSchemaArray = EntityRawSchemaArray,

package/src/schema/raw/Utils.ts

@@ -6,6 +6,8 @@ import { EntityRawSchemaArray } from "./Entities";
  *
  * In the given EntityRawSchemaArray, if the entities type is a string, the schema is loosely typed.
  * If the schema is strongly typed, the entities type would be a word (which is stricter than string).
+ *
+ * @category Schema
  */
 export type IsLooseSchema<E extends EntityRawSchemaArray> =
   string extends E[number]["type"] ? true : false;
@@ -13,6 +15,8 @@ export type IsLooseSchema<E extends EntityRawSchemaArray> =
 /**
  * Checks if the given entity type is present in the EntityRawSchemaArray.
  * Use this to create conditional types.
+ *
+ * @category Schema
  */
 export type IsETypeInStrictSchema<
   E extends EntityRawSchemaArray,
@@ -22,6 +26,8 @@ export type IsETypeInStrictSchema<
 /**
  * Type representing the entity's raw schema matching this type.
  * This type only works for EntityRawSchemaArray with literals as "type" property.
+ *
+ * @category Schema
  */
 export type EntityRawSchemaByType<
   E extends EntityRawSchemaArray,