@cubicweb/client 1.4.0 → 1.5.0

package/src/api/Transaction.ts

@@ -1,36 +1,78 @@
 import { TransactionClosedError } from "../Errors";
 import Api, { RQLParams } from "./Api";
 
+/**
+ * Class used to handle CubicWeb's transactions.
+ * A transaction allows to execute several RQL requests without altering the database until all
+ * changes are committed.
+ *
+ * You should never have to create this object yourself.
+ * Instead, retrieve this object from the methods in the `Client` class.
+ */
 export default class Transaction {
   private _uuid: string | null = null;
   private _closed = false;
 
+  /**
+   * Class used to handle CubicWeb's transactions.
+   * A transaction allows to execute several RQL requests without altering the database until all
+   * changes are committed.
+   *
+   * You should never have to create this object yourself.
+   * Instead, retrieve this object from the methods in the `Client` class.
+   *
+   * @param api The API object used to communicate with the CubicWeb backend.
+   */
   constructor(private api: Api) {}
 
+  /**
+   * @returns True if the connection is closed.
+   */
   isClosed() {
     return this._closed;
   }
 
+  /**
+   * This transaction unique identifier.
+   */
   get uuid() {
     return this._uuid;
   }
 
+  /**
+   * Begins a new transaction an retrieves the associated uuid.
+   */
   async begin() {
     this._closed = false;
     this._uuid = await this.api.transactionBegin();
   }
 
+  /**
+   * Executes the given query and waits for the response.
+   * Make sure you called `begin` before using this method.
+   * As this is a transaction changes will only be applied when you call the `commit` method.
+   *
+   * @param query The RQL query to send
+   * @param params The additional parameters for the request
+   * @returns A promise with the request's result set
+   */
   async execute(query: string, params: RQLParams = {}) {
     this.preventUsageIfClosed();
     return await this.api.transactionExecute(this.uuid, query, params);
   }
 
+  /**
+   * Commits the transaction to apply all the RQL queries sent with `execute`.
+   */
   async commit() {
     this.preventUsageIfClosed();
     await this.api.transactionCommit(this.uuid);
     this._closed = true;
   }
 
+  /**
+   * Rollbacks all the queries sent with `execute` and closes the transaction.
+   */
   async rollback() {
     this.preventUsageIfClosed();
     await this.api.transactionRollback(this.uuid);

package/src/index.ts

@@ -1,13 +1,20 @@
-export {
-  getLooseSchema,
-  Schema,
-  EntitySchema,
-  RelationDefinitionSchema,
-} from "./schema/Schema";
-export * from "./schema/SchemaJSON";
+// Raw Schema
+export * from "./schema/raw/Constraints";
+export * from "./schema/raw/Entities";
+export * from "./schema/raw/RelationDefinitions";
+export * from "./schema/raw/Schema";
+export * from "./schema/raw/Utils";
+
+// Schema Abstraction class
+export * from "./schema/classes/EntitySchema";
+export * from "./schema/classes/RelationDefinitionSchema";
+export * from "./schema/classes/Schema";
+export * from "./schema/classes/Utils";
+
 export * from "./Errors";
+
+// API
 export { default as Client } from "./api/Client";
-export { default as Api } from "./api/Api";
 export { default as Transaction } from "./api/Transaction";
 export {
   RQLQuery,

package/src/schema/classes/EntitySchema.ts

@@ -0,0 +1,125 @@
+import { EntityRawSchemaArray } from "../raw/Entities";
+import { RelationDefinitionRawSchemaArray } from "../raw/RelationDefinitions";
+import { RelationDefinitionSchema } from "./RelationDefinitionSchema";
+import { Schema } from "./Schema";
+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.
+ */
+export class EntitySchema<
+  E extends EntityRawSchemaArray = EntityRawSchemaArray,
+  R extends RelationDefinitionRawSchemaArray<E> = RelationDefinitionRawSchemaArray<E>,
+  ERawSchema extends E[number] = E[number]
+> {
+  /**
+   * 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.
+   *
+   * @param schema The Schema abstraction class used to create this object
+   * @param entityRawSchema The raw entity schema
+   */
+  constructor(
+    private schema: Schema<E, R>,
+    private entityRawSchema: ERawSchema
+  ) {}
+
+  /**
+   * The type of the entity schema. This can also be referred to as the entity schema's name.
+   */
+  get type(): ERawSchema["type"] {
+    return this.entityRawSchema.type;
+  }
+
+  /**
+   * A short description which can be used as documentation for the entity schema.
+   */
+  get description(): ERawSchema["description"] {
+    return this.entityRawSchema.description;
+  }
+
+  /**
+   * True if the current entity schema is a primitive type such as string or int
+   */
+  get final(): ERawSchema["final"] {
+    return this.entityRawSchema.final;
+  }
+
+  /**
+   * 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`.
+   */
+  get subjectRelationDefinitions(): RelationDefinitionSchema<
+    E,
+    R,
+    MatchedRelationDefinition<
+      E,
+      R,
+      { subject: ERawSchema["type"]; final: false }
+    >
+  >[] {
+    return this.schema.matchRelationDefinitions({
+      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<
+      E,
+      R,
+      { object: ERawSchema["type"]; final: false }
+    >
+  >[] {
+    return this.schema.matchRelationDefinitions({
+      object: this.type,
+      final: false,
+    });
+  }
+
+  /**
+   * Finds relations in the Schema matching the partial relation given.
+   *
+   * @param matcher Partial relation definition to match against
+   * @returns Matched relation schema classes
+   */
+  matchRelationDefinitions<M extends RelationDefinitionMatcher<E>>(
+    matcher: M
+  ): RelationDefinitionSchema<
+    E,
+    R,
+    MatchedRelationDefinition<E, R, { subject: ERawSchema["type"] }>
+  >[] {
+    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

@@ -0,0 +1,156 @@
+import { InconsistentSchemaError } from "../../Errors";
+import { EntityRawSchemaArray } from "../raw/Entities";
+import {
+  RelationDefinitionRawSchemaArray,
+  Cardinality,
+} from "../raw/RelationDefinitions";
+import { IsLooseSchema, EntityRawSchemaByType } from "../raw/Utils";
+import { EntitySchema } from "./EntitySchema";
+import { Schema } from "./Schema";
+import { cardinalityRequired } 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.
+ */
+export class RelationDefinitionSchema<
+  E extends EntityRawSchemaArray = EntityRawSchemaArray,
+  R extends RelationDefinitionRawSchemaArray<E> = RelationDefinitionRawSchemaArray<E>,
+  RDef extends R[number] = R[number]
+> {
+  /**
+   * 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.
+   *
+   * @param schema The Schema abstractin class used to create this object
+   * @param relDef The raw relation definition schema
+   */
+  constructor(private schema: Schema<E, R>, private relDef: RDef) {}
+
+  /**
+   * The type of the relation definition. This can also be referred to as the relation definition's name.
+   */
+  get type(): RDef["type"] {
+    return this.relDef.type;
+  }
+
+  /**
+   * A short description which can be used as documentation for the relation definition schema.
+   */
+  get description(): RDef["description"] {
+    return this.relDef.description;
+  }
+
+  /**
+   * True if the object of the relation definition schema is a primitive type.
+   * In this case the relation is called an "attribute".
+   */
+  get final(): RDef["final"] {
+    return this.relDef.final;
+  }
+
+  /**
+   * The list of options set for this relation definition schema.
+   * The returned type will change if this relationd definition schema
+   * describes an attribute or a relation.
+   */
+  get options(): RDef["options"] {
+    return this.relDef.options;
+  }
+
+  /**
+   * The list of constraints set for this relation definition schema.
+   * The returned type will change if this relationd definition schema
+   * describes an attribute or a relation.
+   */
+  get constraints(): RDef["constraints"] {
+    return this.relDef.constraints;
+  }
+
+  /**
+   * The default value for this relation.
+   * It can be used when creating new relations if the user did not enter a value (even if required).
+   */
+  get default(): RDef extends { default: infer V } ? V : undefined {
+    type Default = RDef extends { default: infer V } ? V : undefined;
+
+    return (
+      "default" in this.relDef ? this.relDef.default : undefined
+    ) as Default;
+  }
+
+  /**
+   * 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;
+  }
+
+  /**
+   * Gets the entity associated to this relation definition schema's subject.
+   *
+   * @throws InconsistentSchemaError if the relation definition schema's subject is not a valid entity
+   */
+  get subject(): IsLooseSchema<E> extends true
+    ? EntitySchema<E, R, E[number]>
+    : EntitySchema<E, R, EntityRawSchemaByType<E, RDef["subject"]>> {
+    const subjectSchema = this.schema.getEntity(this.relDef.subject);
+    if (subjectSchema === null) {
+      throw new InconsistentSchemaError(
+        `entity type ${this.relDef.subject} used as subject of relation ${this.type} is not declared`
+      );
+    }
+    // @ts-ignore: Cannot be null as we checked for this above
+    return subjectSchema;
+  }
+
+  /**
+   * Gets the entity associated to this relation definition schema's object.
+   *
+   * @throws InconsistentSchemaError if the relation definition schema's object is not a valid entity
+   */
+  get object(): IsLooseSchema<E> extends true
+    ? EntitySchema<E, R, E[number]>
+    : EntitySchema<E, R, EntityRawSchemaByType<E, RDef["object"]>> {
+    const objectSchema = this.schema.getEntity(this.relDef.object);
+    if (objectSchema === null) {
+      throw new InconsistentSchemaError(
+        `entity type ${this.relDef.object} used as object of relation ${this.type} is not declared`
+      );
+    }
+    // @ts-ignore: Cannot be null as we checked for this above
+    return objectSchema;
+  }
+
+  /**
+   * Checks if the relation is required when using the subject or object point of view.
+   *
+   * @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);
+  }
+}

package/src/schema/classes/Schema.ts

@@ -0,0 +1,122 @@
+import { EntityRawSchemaArray } from "../raw/Entities";
+import {
+  RelationDefinitionRawSchema,
+  RelationDefinitionRawSchemaArray,
+} from "../raw/RelationDefinitions";
+import { RawSchema } from "../raw/Schema";
+import {
+  EntityRawSchemaByType,
+  IsETypeInStrictSchema,
+  IsLooseSchema,
+} from "../raw/Utils";
+import { EntitySchema } from "./EntitySchema";
+import { RelationDefinitionSchema } from "./RelationDefinitionSchema";
+import { RelationDefinitionMatcher, MatchedRelationDefinition } from "./Utils";
+
+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.
+ */
+export class Schema<
+  E extends EntityRawSchemaArray = EntityRawSchemaArray,
+  R extends RelationDefinitionRawSchemaArray<E> = RelationDefinitionRawSchemaArray<E>
+> {
+  [rawSchemaKey]: RawSchema<E, R>;
+
+  /**
+   * 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.
+   *
+   * @param rawSchema The raw JSON schema to create the wrapper from.
+   */
+  constructor(rawSchema: RawSchema<E, R>) {
+    this[rawSchemaKey] = rawSchema;
+  }
+
+  /**
+   * Returns the list of entity schemas in the schema using the EntitySchema abstraction class.
+   */
+  get entities(): EntitySchema<E, R, E[number]>[] {
+    return this[rawSchemaKey].entities.map(
+      (eSchema) => new EntitySchema(this, eSchema)
+    );
+  }
+
+  /**
+   * Returns the list of relation definitions schemas in the schema
+   * using the RelationDefinitionSchema abstraction class.
+   */
+  get relationsDefinitions(): RelationDefinitionSchema<E, R, R[number]>[] {
+    return this[rawSchemaKey].relations_definitions.map(
+      (rdefSchema) => new RelationDefinitionSchema(this, rdefSchema)
+    );
+  }
+
+  /**
+   * Returns the entity schema for the given entity type if it exists.
+   * When using TypeScript, this method can detect if the given type does not exist
+   * in the schema.
+   *
+   * @param entityType The entity type string
+   * @returns A new EntitySchema or null if the type does not exist
+   */
+  getEntity<EType extends string>(
+    entityType: EType
+  ): IsLooseSchema<E> extends true
+    ? EntitySchema<E, R, E[number]> | null
+    : IsETypeInStrictSchema<E, EType> extends true
+    ? EntitySchema<E, R, EntityRawSchemaByType<E, EType>>
+    : null {
+    const entityRawSchema = this[rawSchemaKey].entities.filter(
+      (eSchema) => eSchema.type === entityType
+    )[0];
+    if (!entityRawSchema) {
+      // @ts-ignore: Is only null when the given type is not in the schema.
+      // Thus the return type will be (EntitySchema | null)
+      // but TypeScript does not understand this
+      return null;
+    }
+    // @ts-ignore: see above
+    return new EntitySchema<E, R, E[number]>(
+      this,
+      entityRawSchema as EntityRawSchemaByType<E, EType>
+    );
+  }
+
+  /**
+   * Finds relations definition schemas in the Schema matching the
+   * raw partial relation definition schema given.
+   *
+   * @param matcher Partial raw relation definition schema to match against
+   * @returns Array of matched relation definition schema classes
+   */
+  matchRelationDefinitions<M extends RelationDefinitionMatcher<E>>(
+    matcher: M
+  ): RelationDefinitionSchema<
+    E,
+    R,
+    MatchedRelationDefinition<E, R, { subject: E[number]["type"] }>
+  >[] {
+    const matchArray = this[rawSchemaKey].relations_definitions.filter(
+      (relDef) => {
+        for (const key of Object.keys(
+          matcher
+        ) as (keyof RelationDefinitionRawSchema<E>)[]) {
+          if (matcher[key] !== relDef[key]) {
+            return false;
+          }
+        }
+        return true;
+      }
+    ) as MatchedRelationDefinition<
+      E,
+      R,
+      MatchedRelationDefinition<E, R, { subject: E[number]["type"] }>
+    >[];
+    return matchArray.map((m) => new RelationDefinitionSchema(this, m));
+  }
+}

package/src/schema/classes/Utils.ts

@@ -0,0 +1,52 @@
+import { EntityRawSchemaArray } from "../raw/Entities";
+import {
+  Cardinality,
+  RelationDefinitionRawSchema,
+  RelationDefinitionRawSchemaArray,
+} from "../raw/RelationDefinitions";
+import { Schema } from "./Schema";
+
+/**
+ * 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
+ */
+export const getLooseSchema = <
+  E extends EntityRawSchemaArray = EntityRawSchemaArray,
+  R extends RelationDefinitionRawSchemaArray<E> = RelationDefinitionRawSchemaArray<E>
+>(
+  schema: Schema<E, R>
+) => {
+  return schema as unknown as Schema;
+};
+
+/**
+ * Checks if the given cardinality requires at least one entity to be present
+ *
+ * @param cardinality The cardinality to check
+ * @returns True if the cardinality is 1 or +
+ */
+export function cardinalityRequired(cardinality: Cardinality): boolean {
+  return cardinality === "1" || cardinality === "+";
+}
+
+/**
+ * Partial raw relation definition schema type.
+ */
+export type RelationDefinitionMatcher<E extends EntityRawSchemaArray> = Partial<
+  RelationDefinitionRawSchema<E>
+>;
+
+/**
+ * Type representing a raw relation definition matched from a partial raw relation definition schema.
+ * 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.
+ */
+export type MatchedRelationDefinition<
+  E extends EntityRawSchemaArray,
+  R extends RelationDefinitionRawSchemaArray<EntityRawSchemaArray>,
+  M extends RelationDefinitionMatcher<E>
+> = R[number] extends infer RDef ? (RDef extends M ? RDef : never) : never;

package/src/schema/raw/Constraints.ts

@@ -0,0 +1,77 @@
+/**
+ * Base type used to describe a constraint.
+ */
+type ConstraintBase<
+  T extends string,
+  V extends Record<string, unknown> | null
+> = {
+  type: T;
+  value: V;
+};
+
+/**
+ * All the possible operators inside a constraint.
+ */
+export type ConstraintOperator = ">" | ">=" | "<" | "<=";
+
+/**
+ * THe type of a constraint message when one is present.
+ */
+type ConstraintMessage = string | null;
+
+export type UniqueConstraint = ConstraintBase<"UniqueConstraint", null>;
+
+export type SizeConstraint = ConstraintBase<
+  "SizeConstraint",
+  { min: number | null; max: number | null; msg: ConstraintMessage }
+>;
+
+export type RegexpConstraint = ConstraintBase<
+  "RegexpConstraint",
+  { regexp: string; flags: number; msg: ConstraintMessage }
+>;
+
+export type BoundaryConstraint = ConstraintBase<
+  "BoundaryConstraint",
+  { boundary: number | null; op: ConstraintOperator; msg: ConstraintMessage }
+>;
+export type IntervalBoundConstraint = ConstraintBase<
+  "IntervalBoundConstraint",
+  { minvalue: number | null; maxvalue: number | null; msg: ConstraintMessage }
+>;
+
+export type StaticVocabularyConstraint = ConstraintBase<
+  "StaticVocabularyConstraint",
+  { values: string[]; msg: ConstraintMessage }
+>;
+
+export type FormatConstraint = ConstraintBase<
+  "FormatConstraint",
+  {
+    values: ["text/rest", "text/markdown", "text/html", "text/plain"];
+    msg: ConstraintMessage;
+  }
+>;
+
+export type RQLVocabularyConstraint = ConstraintBase<
+  "RQLVocabularyConstraint",
+  { expression: string; mainvars: string[] }
+>;
+
+/**
+ * Type representing all possible constraints for attributes.
+ */
+export type AttributeConstraint = Readonly<
+  | UniqueConstraint
+  | SizeConstraint
+  | RegexpConstraint
+  | BoundaryConstraint
+  | IntervalBoundConstraint
+  | StaticVocabularyConstraint
+  | FormatConstraint
+>;
+
+/**
+ * Type representing all possible constraints for relations.
+ */
+export type RelationConstraint = Readonly<RQLVocabularyConstraint>;

package/src/schema/raw/Entities.ts

@@ -0,0 +1,13 @@
+/**
+ * Type representing an entity schema.
+ */
+export type EntityRawSchema = {
+  type: string;
+  final: boolean;
+  description: string;
+};
+
+/**
+ * Type representing a list of entity schemas.
+ */
+export type EntityRawSchemaArray = ReadonlyArray<EntityRawSchema>;