@cubicweb/client 2.1.1 → 3.0.0-alpha.10

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,32 +66,36 @@ 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;
-  offset: TimeDelta;
+  offset: TimeDelta | null;
 }
 
 /**
  * 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",
   {
-    boundary: Attribute | Today | Now | number | null;
+    boundary: Attribute | Today | Now | number | string | null;
     op: ConstraintOperator;
     msg: ConstraintMessage;
   }
 >;
 export type IntervalBoundConstraint = ConstraintBase<
   "IntervalBoundConstraint",
-  { minvalue: number | null; maxvalue: number | null; msg: ConstraintMessage }
+  {
+    minvalue: number | string | null;
+    maxvalue: number | string | null;
+    msg: ConstraintMessage;
+  }
 >;
 
 export type StaticVocabularyConstraint = ConstraintBase<
@@ -115,6 +123,8 @@ export type RQLConstraint = ConstraintBase<
 
 /**
  * Type representing all possible constraints for attributes.
+ *
+ * @category Schema
  */
 export type AttributeConstraint = Readonly<
   | UniqueConstraint
@@ -129,6 +139,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,