chore: improve typings

src/definition/model/relations/relation-definition.d.ts

@@ -2,11 +2,253 @@ import {RelationType} from './relation-type';
 
 /**
  * Relation definition.
+ *
+ * @example Available options.
+ * ```ts
+ * {
+ *   type: RelationType;
+ *   model?: string;
+ *   foreignKey?: string;
+ *   polymorphic?: boolean | string;
+ *   discriminator?: string;
+ * }
+ * ```
  */
-declare type RelationDefinition = {
-  type: RelationType;
-  model?: string;
+export declare type RelationDefinition =
+  // belongsTo
+  | BelongsToDefinition
+  | PolyBelongsToDefinition
+  // hasOne
+  | HasOneDefinition
+  | PolyHasOneDefinitionWithTargetRelationName
+  | PolyHasOneDefinitionWithTargetKeys
+  // hasMany
+  | HasManyDefinition
+  | PolyHasManyDefinitionWithTargetRelationName
+  | PolyHasManyDefinitionWithTargetKeys
+  // referencesMany
+  | ReferencesManyDefinition;
+
+/**
+ * The regular "belongsTo" relation.
+ *
+ * @example Required options only.
+ * ```
+ * {
+ *   type: RelationType.BELONGS_TO,
+ *   model: 'model',
+ * }
+ * ```
+ *
+ * @example Verbose definition.
+ * ```
+ * {
+ *   type: RelationType.BELONGS_TO,
+ *   model: 'model',
+ *   foreignKey: 'modelId',
+ * }
+ * ```
+ */
+export declare type BelongsToDefinition = {
+  type: RelationType.BELONGS_TO;
+  polymorphic?: false;
+  model: string;
+  foreignKey?: string;
+};
+
+/**
+ * The polymorphic "belongsTo" relation.
+ *
+ * @example Required fields only.
+ * ```
+ * {
+ *   type: RelationType.BELONGS_TO,
+ *   polymorphic: true,
+ * }
+ * ```
+ *
+ * @example Verbose definition.
+ * ```
+ * {
+ *   type: RelationType.BELONGS_TO,
+ *   polymorphic: true,
+ *   foreignKey: 'referenceId',
+ *   discriminator: 'referenceType,
+ * }
+ * ```
+ */
+export declare type PolyBelongsToDefinition = {
+  type: RelationType.BELONGS_TO;
+  polymorphic: true;
   foreignKey?: string;
-  polymorphic?: boolean | string;
   discriminator?: string;
 };
+
+/**
+ * The regular "hasOne" relation.
+ *
+ * @example
+ * ```ts
+ * {
+ *   type: RelationType.HAS_ONE,
+ *   model: 'model',
+ *   foreignKey: 'modelId',
+ * }
+ * ```
+ */
+export declare type HasOneDefinition = {
+  type: RelationType.HAS_ONE;
+  model: string;
+  polymorphic?: false;
+  foreignKey?: string;
+  discriminator?: undefined;
+};
+
+/**
+ * The polymorphic "hasOne" relation with a target relation name.
+ *
+ * @example
+ * ```ts
+ * {
+ *   type: RelationType.HAS_ONE,
+ *   model: 'model',
+ *   polymorphic: 'reference',
+ * }
+ * ```
+ */
+export declare type PolyHasOneDefinitionWithTargetRelationName = {
+  type: RelationType.HAS_ONE;
+  model: string;
+  polymorphic: string;
+  foreignKey?: undefined;
+  discriminator?: undefined;
+};
+
+/**
+ * The polymorphic "hasOne" relation with target relation keys.
+ *
+ * @example Required options only.
+ * ```
+ * {
+ *   type: RelationType.HAS_ONE,
+ *   model: 'model',
+ *   polymorphic: true,
+ * }
+ * ```
+ *
+ * @example Verbose definition.
+ * ```
+ * {
+ *   type: RelationType.HAS_ONE,
+ *   model: 'model',
+ *   polymorphic: true,
+ *   foreignKey: 'referenceId',
+ *   discriminator: 'referenceType,
+ * }
+ * ```
+ */
+export declare type PolyHasOneDefinitionWithTargetKeys = {
+  type: RelationType.HAS_ONE;
+  model: string;
+  polymorphic: true;
+  foreignKey?: string;
+  discriminator?: string;
+};
+
+/**
+ * The regular "hasMany" relation.
+ *
+ * @example
+ * ```ts
+ * {
+ *   type: RelationType.HAS_MANY,
+ *   model: 'model',
+ *   foreignKey: 'modelId',
+ * }
+ * ```
+ */
+export declare type HasManyDefinition = {
+  type: RelationType.HAS_MANY;
+  model: string;
+  polymorphic?: false;
+  foreignKey?: string;
+  discriminator?: undefined;
+};
+
+/**
+ * The polymorphic "hasMany" relation with a target relation name.
+ *
+ * @example
+ * ```ts
+ * {
+ *   type: RelationType.HAS_MANY,
+ *   model: 'model',
+ *   polymorphic: 'reference',
+ * }
+ * ```
+ */
+export declare type PolyHasManyDefinitionWithTargetRelationName = {
+  type: RelationType.HAS_MANY;
+  model: string;
+  polymorphic: string;
+  foreignKey?: undefined;
+  discriminator?: undefined;
+};
+
+/**
+ * The polymorphic "hasMany" relation with target relation keys.
+ *
+ * @example Required options only.
+ * ```
+ * {
+ *   type: RelationType.HAS_MANY,
+ *   model: 'model',
+ *   polymorphic: true,
+ * }
+ * ```
+ *
+ * @example Verbose definition.
+ * ```
+ * {
+ *   type: RelationType.HAS_MANY,
+ *   model: 'model',
+ *   polymorphic: true,
+ *   foreignKey: 'referenceId',
+ *   discriminator: 'referenceType,
+ * }
+ * ```
+ */
+export declare type PolyHasManyDefinitionWithTargetKeys = {
+  type: RelationType.HAS_MANY;
+  model: string;
+  polymorphic: true;
+  foreignKey?: string;
+  discriminator?: string;
+};
+
+/**
+ * The regular "referencesMany" relation.
+ *
+ * @example Required options only.
+ * ```
+ * {
+ *   type: RelationType.REFERENCES_MANY,
+ *   model: 'model',
+ * }
+ * ```
+ *
+ * @example Verbose definition.
+ * ```
+ * {
+ *   type: RelationType.REFERENCES_MANY,
+ *   model: 'model',
+ *   foreignKey: 'modelIds',
+ * }
+ * ```
+ */
+export declare type ReferencesManyDefinition = {
+  type: RelationType.REFERENCES_MANY;
+  model: string;
+  foreignKey?: string;
+  discriminator?: undefined;
+};

src/definition/model/relations/relations-definition-validator.js

@@ -78,9 +78,9 @@ export class RelationsDefinitionValidator extends Service {
   }
 
   /**
-   * Validate belongs to.
+   * Validate "belongsTo".
    *
-   * @example A regular "belongsTo" relation.
+   * @example The regular "belongsTo" relation.
    * ```
    * {
    *   type: RelationType.BELONGS_TO,
@@ -89,7 +89,7 @@ export class RelationsDefinitionValidator extends Service {
    * }
    * ```
    *
-   * @example A polymorphic "belongsTo" relation.
+   * @example The polymorphic "belongsTo" relation.
    * ```
    * {
    *   type: RelationType.BELONGS_TO,
@@ -166,9 +166,9 @@ export class RelationsDefinitionValidator extends Service {
   }
 
   /**
-   * Validate has one.
+   * Validate "hasOne".
    *
-   * @example A regular "hasOne" relation.
+   * @example The regular "hasOne" relation.
    * ```
    * {
    *   type: RelationType.HAS_ONE,
@@ -177,7 +177,7 @@ export class RelationsDefinitionValidator extends Service {
    * }
    * ```
    *
-   * @example A polymorphic "hasOne" relation with a target relation name.
+   * @example The polymorphic "hasOne" relation with a target relation name.
    * ```
    * {
    *   type: RelationType.HAS_ONE,
@@ -186,7 +186,7 @@ export class RelationsDefinitionValidator extends Service {
    * }
    * ```
    *
-   * @example A polymorphic "hasOne" relation with target relation keys.
+   * @example The polymorphic "hasOne" relation with target relation keys.
    * ```
    * {
    *   type: RelationType.HAS_ONE,
@@ -284,9 +284,9 @@ export class RelationsDefinitionValidator extends Service {
   }
 
   /**
-   * Validate has one.
+   * Validate "hasMany".
    *
-   * @example A regular "hasMany" relation.
+   * @example The regular "hasMany" relation.
    * ```
    * {
    *   type: RelationType.HAS_MANY,
@@ -295,7 +295,7 @@ export class RelationsDefinitionValidator extends Service {
    * }
    * ```
    *
-   * @example A polymorphic "hasMany" relation with a target relation name.
+   * @example The polymorphic "hasMany" relation with a target relation name.
    * ```
    * {
    *   type: RelationType.HAS_MANY,
@@ -304,7 +304,7 @@ export class RelationsDefinitionValidator extends Service {
    * }
    * ```
    *
-   * @example A polymorphic "hasMany" relation with target relation keys.
+   * @example The polymorphic "hasMany" relation with target relation keys.
    * ```
    * {
    *   type: RelationType.HAS_MANY,
@@ -402,7 +402,7 @@ export class RelationsDefinitionValidator extends Service {
   }
 
   /**
-   * Validate references many.
+   * Validate "referencesMany".
    *
    * @example
    * ```