@cubicweb/client 0.1.0

package/src/schema/Schema.ts

@@ -0,0 +1,414 @@
+import { Cardinality } from "..";
+import { InconsistentSchemaError, RelationNotFoundError } from "../Errors";
+import {
+  RawSchema,
+  RelationDefinitionRawSchema,
+  RelationDefinitionRawSchemaArray,
+  EntityRawSchemaArray,
+  EntityRawSchemaByType,
+  IsLooseSchema,
+  IsETypeInStrictSchema,
+} from "./SchemaJSON";
+
+const rawSchemaKey: unique symbol = Symbol("Indexer of the rawSchema");
+
+/**
+ * Returns the given schema using loose typing.
+ * Can be useful when working for generic schemas
+ *
+ * @param schema The schema to create a loose type for
+ * @returns
+ */
+export const getLooseSchema = <
+  E extends EntityRawSchemaArray = EntityRawSchemaArray, // List of all entities
+  R extends RelationDefinitionRawSchemaArray<E> = RelationDefinitionRawSchemaArray<E> // List of all relation defintions
+>(
+  schema: Schema<E, R>
+) => {
+  return schema as unknown as Schema<
+    EntityRawSchemaArray,
+    RelationDefinitionRawSchemaArray<EntityRawSchemaArray>
+  >;
+};
+
+/**
+ * Wrapper around the raw JSON Schema
+ */
+export class Schema<
+  E extends EntityRawSchemaArray = EntityRawSchemaArray, // List of all entities
+  R extends RelationDefinitionRawSchemaArray<E> = RelationDefinitionRawSchemaArray<E> // List of all relation defintions
+> {
+  [rawSchemaKey]: RawSchema<E, R>;
+
+  constructor(rawSchema: RawSchema<E, R>) {
+    this[rawSchemaKey] = rawSchema;
+  }
+
+  get entities(): EntitySchema<E, R, E[number]>[] {
+    return this[rawSchemaKey].entities.map(
+      (eSchema) => new EntitySchema(this, eSchema)
+    );
+  }
+
+  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) {
+      // 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
+      // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+      // @ts-ignore
+      return null;
+    }
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+    // @ts-ignore
+    return new EntitySchema<E, R, E[number]>(
+      this,
+      entityRawSchema as EntityRawSchemaByType<E, EType>
+    );
+  }
+
+  /**
+   * 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: 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));
+  }
+}
+
+/**
+ * Wrapper around raw entities from the Schema
+ */
+export class EntitySchema<
+  E extends EntityRawSchemaArray = EntityRawSchemaArray, // List of all entities
+  R extends RelationDefinitionRawSchemaArray<E> = RelationDefinitionRawSchemaArray<E>, // List of all relation defintions
+  ERawSchema extends E[number] = E[number] // JSON of the represented entity
+> {
+  constructor(
+    private schema: Schema<E, R>,
+    private entityRawSchema: ERawSchema
+  ) {}
+
+  /**
+   * The type of the entity. This can also be referred to as the entity' name.
+   */
+  get type(): ERawSchema["type"] {
+    return this.entityRawSchema.type;
+  }
+
+  /**
+   * A short description which can be used as documentation for the entity.
+   */
+  get description(): ERawSchema["description"] {
+    return this.entityRawSchema.description;
+  }
+
+  /**
+   * True if the current entity is a primitive type such as string or int
+   */
+  get final(): ERawSchema["final"] {
+    return this.entityRawSchema.final;
+  }
+
+  /**
+   * Gets the list of relation definitions with this entity as subject
+   */
+  get subjectRelationDefinitions(): RelationDefinitionSchema<
+    E,
+    R,
+    MatchedRelationDefinition<E, R, { subject: ERawSchema["type"] }>
+  >[] {
+    return this.schema.matchRelationDefinitions({
+      subject: this.type,
+      final: false,
+    });
+  }
+
+  /**
+   * Gets the list of relation definitions with this entity as object
+   */
+  get objectRelationsDefinitions(): RelationDefinitionSchema<
+    E,
+    R,
+    MatchedRelationDefinition<E, R, { object: ERawSchema["type"] }>
+  >[] {
+    return this.schema.matchRelationDefinitions({
+      object: this.type,
+      final: false,
+    });
+  }
+
+  /**
+   * Finds the first relation of the given type with this entity as subject
+   *
+   * @param relationType The relation type to find
+   * @throws RelationNotFoundError if the current entity is not a subject of the given relation
+   * @returns The found relation
+   */
+  getSubjectRelationDefinition<
+    RelationType extends MatchedRelationDefinition<
+      E,
+      R,
+      { subject: ERawSchema["type"] }
+    >["type"]
+  >(
+    relationType: RelationType
+  ): RelationDefinitionSchema<
+    E,
+    R,
+    MatchedRelationDefinition<
+      E,
+      R,
+      { subject: ERawSchema["type"]; type: RelationType }
+    >
+  > {
+    const resultArray = this.schema.matchRelationDefinitions({
+      subject: this.type,
+      type: relationType,
+    });
+    if (resultArray.length > 0) {
+      return resultArray[0];
+    }
+    throw new RelationNotFoundError(relationType, "subject", this.type);
+  }
+
+  /**
+   * Finds the first relation of the given type with this entity as object
+   *
+   * @param relationType The relation type to find
+   * @throws RelationNotFoundError if the current entity is not an object of the given relation
+   * @returns The found relation
+   */
+  getObjectRelationDefinition<
+    RelationType extends MatchedRelationDefinition<
+      E,
+      R,
+      { object: ERawSchema["type"] }
+    >["type"]
+  >(
+    relationType: RelationType
+  ): RelationDefinitionSchema<
+    E,
+    R,
+    MatchedRelationDefinition<
+      E,
+      R,
+      { object: ERawSchema["type"]; type: RelationType }
+    >
+  > {
+    const resultArray = this.schema.matchRelationDefinitions({
+      object: this.type,
+      type: relationType,
+    });
+    if (resultArray.length > 0) {
+      return resultArray[0];
+    }
+    throw new RelationNotFoundError(relationType, "object", this.type);
+  }
+
+  /**
+   * Gets the list of attributes names for this entity
+   */
+  get attributes(): RelationDefinitionSchema<E, R, R[number]>[] {
+    return this.schema.matchRelationDefinitions({
+      final: true,
+      subject: this.type,
+    });
+  }
+
+  /**
+   * Checks whether the current entity is required for the given relation and role
+   *
+   * @param relationType The relation to check
+   * @param role The role for this entity in the given relation
+   * @returns True if this entity is required in the relation for the given role
+   */
+  isRelationRequired<
+    RelationType extends MatchedRelationDefinition<
+      E,
+      R,
+      { subject: ERawSchema["type"] } | { object: ERawSchema["type"] }
+    >["type"]
+  >(relationType: RelationType, role: "subject" | "object"): boolean {
+    let relation;
+    let cardinality: Cardinality;
+    if (role === "subject") {
+      relation = this.getSubjectRelationDefinition(relationType);
+      cardinality = relation.cardinality[0];
+    } else {
+      relation = this.getObjectRelationDefinition(relationType);
+      cardinality = relation.cardinality[1];
+    }
+    return cardinalityRequired(cardinality);
+  }
+}
+
+/**
+ * Wrapper around raw relation definitions from the Schema
+ */
+export class RelationDefinitionSchema<
+  E extends EntityRawSchemaArray = EntityRawSchemaArray, // List of all entities
+  R extends RelationDefinitionRawSchemaArray<E> = RelationDefinitionRawSchemaArray<E>, // List of all relation defintions
+  RDef extends R[number] = R[number] // JSON of the represented relation definition
+> {
+  constructor(private schema: Schema<E, R>, private relDef: RDef) {}
+
+  /**
+   * The type of the relation. This can also be referred to as the relation's name.
+   */
+  get type(): RDef["type"] {
+    return this.relDef.type;
+  }
+
+  /**
+   * A short description which can be used as documentation for the relation.
+   */
+  get description(): RDef["description"] {
+    return this.relDef.description;
+  }
+
+  /**
+   * True if the object of the relation is a primitive type.
+   * In this case the relation iscalled an "attribute"
+   */
+  get final(): RDef["final"] {
+    return this.relDef.final;
+  }
+
+  /**
+   * The list of constraints if any. Only attributes (relations with final = true) have constraints.
+   * In other cases this returns null.
+   */
+  get constraints(): RDef["constraints"] {
+    return this.relDef.constraints;
+  }
+
+  /**
+   * The default value for this relation.
+   * It can be used when creating new relations if 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;
+  }
+
+  get cardinality(): RDef["cardinality"] {
+    return this.relDef.cardinality;
+  }
+
+  get subjectCardinality(): Cardinality {
+    return this.relDef.cardinality[0] as Cardinality;
+  }
+
+  get objectCardinality(): Cardinality {
+    return this.relDef.cardinality[1] as Cardinality;
+  }
+
+  /**
+   * Gets the entity associated to this relation's subject
+   *
+   * @throws InconsistentSchemaError if the relation'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`
+      );
+    }
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+    // @ts-ignore
+    return subjectSchema;
+  }
+
+  /**
+   * Gets the entity associated to this relation's object
+   *
+   * @throws InconsistentSchemaError if the relation'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`
+      );
+    }
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+    // @ts-ignore
+    return objectSchema;
+  }
+}
+
+/**
+ * Checks if the given cardinality requires at least one entity to be present
+ *
+ * @param cardinality The cardinality to check
+ * @returns
+ */
+function cardinalityRequired(cardinality: Cardinality): boolean {
+  return cardinality === "1" || cardinality === "+";
+}
+
+export type RelationDefinitionMatcher<E extends EntityRawSchemaArray> = Partial<
+  RelationDefinitionRawSchema<E>
+>;
+
+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/SchemaJSON.ts

@@ -0,0 +1,195 @@
+type ConstraintBase<
+  T extends string,
+  V extends Record<string, unknown> | null
+> = {
+  type: T;
+  value: V;
+};
+
+export type ConstraintOperator = ">" | ">=" | "<" | "<=";
+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 Constraint = Readonly<
+  | UniqueConstraint
+  | SizeConstraint
+  | RegexpConstraint
+  | BoundaryConstraint
+  | IntervalBoundConstraint
+  | StaticVocabularyConstraint
+  | FormatConstraint
+>;
+
+type BuildObjBase<T extends string> = {
+  object: T;
+  final: true;
+  required?: boolean;
+};
+
+interface StringBuildObj extends BuildObjBase<"String"> {
+  default: string | null;
+}
+
+interface PasswordBuildObj extends BuildObjBase<"Password"> {
+  default: string | null;
+}
+
+interface BytesBuildObj extends BuildObjBase<"Bytes"> {
+  default: string | null;
+}
+
+interface IntBuildObj extends BuildObjBase<"Int"> {
+  default: number | null;
+}
+
+interface BigIntBuildObj extends BuildObjBase<"BigInt"> {
+  default: number | null;
+}
+
+interface FloatBuildObj extends BuildObjBase<"Float"> {
+  default: number | null;
+}
+
+interface BooleanBuildObj extends BuildObjBase<"Boolean"> {
+  default: boolean | null;
+}
+
+interface DecimalBuildObj extends BuildObjBase<"Decimal"> {
+  default: number | null;
+}
+
+interface DateBuildObj extends BuildObjBase<"Date"> {
+  default: unknown;
+}
+
+interface TimeBuildObj extends BuildObjBase<"Time"> {
+  default: unknown;
+}
+
+interface DatetimeBuildObj extends BuildObjBase<"Datetime"> {
+  default: Date | "NOW" | "TODAY" | null;
+}
+
+interface TZTimeBuildObj extends BuildObjBase<"TZTime"> {
+  default: unknown;
+}
+
+interface TZDatetimeBuildObj extends BuildObjBase<"TZDatetime"> {
+  default: unknown;
+}
+
+interface IntervalBuildObj extends BuildObjBase<"Interval"> {
+  default: unknown;
+}
+
+export type BuildObj = Readonly<
+  | StringBuildObj
+  | PasswordBuildObj
+  | BytesBuildObj
+  | IntBuildObj
+  | BigIntBuildObj
+  | FloatBuildObj
+  | BooleanBuildObj
+  | DecimalBuildObj
+  | DateBuildObj
+  | TimeBuildObj
+  | DatetimeBuildObj
+  | TZTimeBuildObj
+  | TZDatetimeBuildObj
+  | IntervalBuildObj
+>;
+
+export type Cardinality = "*" | "1" | "?" | "+";
+
+export type CardinalityPair = `${Cardinality}${Cardinality}`;
+
+export type EntityRawSchema = {
+  type: string;
+  final: boolean;
+  description: string;
+};
+
+export type EntityRawSchemaArray = ReadonlyArray<EntityRawSchema>;
+
+export type RelationDefinitionRawSchema<
+  ESchemas extends EntityRawSchemaArray,
+  Final extends boolean = boolean
+> = Readonly<
+  {
+    type: string;
+    description: string;
+    cardinality: CardinalityPair;
+    subject: ESchemas[number]["type"];
+  } & (Final extends true
+    ? BuildObj & {
+        constraints: Constraint[];
+      }
+    : { object: EntityRawSchema["type"]; final: false; constraints: null })
+>;
+
+export type RelationDefinitionRawSchemaArray<
+  ESchemas extends EntityRawSchemaArray
+> = ReadonlyArray<RelationDefinitionRawSchema<ESchemas, boolean>>;
+
+export type RawSchema<
+  E extends EntityRawSchemaArray = EntityRawSchemaArray,
+  R extends RelationDefinitionRawSchemaArray<E> = RelationDefinitionRawSchemaArray<E>
+> = {
+  entities: E;
+  relations_definitions: R;
+};
+
+export type IsLooseSchema<E extends EntityRawSchemaArray> =
+  string extends E[number]["type"] ? true : false;
+
+export type IsETypeInStrictSchema<
+  E extends EntityRawSchemaArray,
+  EType extends string
+> = EType extends E[number]["type"] ? true : false;
+
+/**
+ * Type representing the entity's raw schema matching this type.
+ * This type only works for EntityRawSchemaArray with literals as "type" property.
+ *
+ **/
+export type EntityRawSchemaByType<
+  E extends EntityRawSchemaArray,
+  T extends string
+> = E[number] extends infer ESchema
+  ? ESchema extends { type: T }
+    ? ESchema
+    : never
+  : never; // Will never happen E[number] always has a type