From 0ffe2838c1ec30d676a4edf9127b9eb7ac303d4d Mon Sep 17 00:00:00 2001
From: Pablo Baleztena <pablo@ultharsoftware.com>
Date: Wed, 4 Sep 2024 19:58:59 -0300
Subject: [PATCH] [fabric-core] Improve some JSDocs, improve some names, and
 re-organice some files

---
 .../fabric/core/src/domain/entity/files/domain-file.ts   | 2 +-
 .../fabric/core/src/domain/entity/files/image-file.ts    | 2 +-
 packages/fabric/core/src/domain/entity/files/index.ts    | 8 --------
 packages/fabric/core/src/domain/entity/index.ts          | 1 -
 packages/fabric/core/src/domain/events/event.ts          | 3 +++
 packages/fabric/core/src/domain/security/policy-map.ts   | 3 +++
 packages/fabric/core/src/domain/types/index.ts           | 2 +-
 .../core/src/domain/types/{sem-ver.ts => semver.ts}      | 0
 packages/fabric/core/src/domain/use-case/use-case.ts     | 5 -----
 packages/fabric/core/src/error/is-error.ts               | 9 +--------
 packages/fabric/core/src/error/tagged-error.ts           | 4 +---
 packages/fabric/core/src/error/unexpected-error.ts       | 8 ++++----
 .../core/src/{domain/entity => }/files/base-file.ts      | 0
 .../fabric/core/src/{domain/entity => }/files/bytes.ts   | 0
 packages/fabric/core/src/files/index.ts                  | 8 ++++++++
 .../{domain/entity => }/files/invalid-file-type-error.ts | 2 +-
 .../src/{domain/entity => }/files/is-mime-type.spec.ts   | 0
 .../core/src/{domain/entity => }/files/is-mime-type.ts   | 6 +++---
 .../src/{domain/entity => }/files/is-uploaded-file.ts    | 2 +-
 .../core/src/{domain/entity => }/files/media-file.ts     | 2 +-
 .../core/src/{domain/entity => }/files/mime-type.ts      | 0
 .../core/src/{domain/entity => }/files/uploaded-file.ts  | 2 +-
 packages/fabric/core/src/time/timeout.spec.ts            | 2 +-
 23 files changed, 31 insertions(+), 40 deletions(-)
 rename packages/fabric/core/src/domain/types/{sem-ver.ts => semver.ts} (100%)
 rename packages/fabric/core/src/{domain/entity => }/files/base-file.ts (100%)
 rename packages/fabric/core/src/{domain/entity => }/files/bytes.ts (100%)
 create mode 100644 packages/fabric/core/src/files/index.ts
 rename packages/fabric/core/src/{domain/entity => }/files/invalid-file-type-error.ts (69%)
 rename packages/fabric/core/src/{domain/entity => }/files/is-mime-type.spec.ts (100%)
 rename packages/fabric/core/src/{domain/entity => }/files/is-mime-type.ts (63%)
 rename packages/fabric/core/src/{domain/entity => }/files/is-uploaded-file.ts (92%)
 rename packages/fabric/core/src/{domain/entity => }/files/media-file.ts (74%)
 rename packages/fabric/core/src/{domain/entity => }/files/mime-type.ts (100%)
 rename packages/fabric/core/src/{domain/entity => }/files/uploaded-file.ts (74%)

diff --git a/packages/fabric/core/src/domain/entity/files/domain-file.ts b/packages/fabric/core/src/domain/entity/files/domain-file.ts
index bfb7992..74a36ca 100644
--- a/packages/fabric/core/src/domain/entity/files/domain-file.ts
+++ b/packages/fabric/core/src/domain/entity/files/domain-file.ts
@@ -1,5 +1,5 @@
+import { BaseFile } from "../../../files/base-file.js";
 import { Entity } from "../entity.js";
-import { BaseFile } from "./base-file.js";
 
 /**
  * Represents a file as managed by the domain.
diff --git a/packages/fabric/core/src/domain/entity/files/image-file.ts b/packages/fabric/core/src/domain/entity/files/image-file.ts
index bdbca39..e92aaba 100644
--- a/packages/fabric/core/src/domain/entity/files/image-file.ts
+++ b/packages/fabric/core/src/domain/entity/files/image-file.ts
@@ -1,5 +1,5 @@
+import { ImageMimeType } from "../../../files/mime-type.js";
 import { DomainFile } from "./domain-file.js";
-import { ImageMimeType } from "./mime-type.js";
 
 /**
  * Represents an image file.
diff --git a/packages/fabric/core/src/domain/entity/files/index.ts b/packages/fabric/core/src/domain/entity/files/index.ts
index dde7c34..dad6bbf 100644
--- a/packages/fabric/core/src/domain/entity/files/index.ts
+++ b/packages/fabric/core/src/domain/entity/files/index.ts
@@ -1,10 +1,2 @@
-export * from "./base-file.js";
-export * from "./bytes.js";
 export * from "./domain-file.js";
 export * from "./image-file.js";
-export * from "./invalid-file-type-error.js";
-export * from "./is-mime-type.js";
-export * from "./is-uploaded-file.js";
-export * from "./media-file.js";
-export * from "./mime-type.js";
-export * from "./uploaded-file.js";
diff --git a/packages/fabric/core/src/domain/entity/index.ts b/packages/fabric/core/src/domain/entity/index.ts
index 9e932a0..c42a26d 100644
--- a/packages/fabric/core/src/domain/entity/index.ts
+++ b/packages/fabric/core/src/domain/entity/index.ts
@@ -1,2 +1 @@
 export * from "./entity.js";
-export * from "./files/index.js";
diff --git a/packages/fabric/core/src/domain/events/event.ts b/packages/fabric/core/src/domain/events/event.ts
index 6c57cbb..9001dfe 100644
--- a/packages/fabric/core/src/domain/events/event.ts
+++ b/packages/fabric/core/src/domain/events/event.ts
@@ -1,5 +1,8 @@
 import { TaggedVariant } from "../../variant/variant.js";
 
+/**
+ * An event is a tagged variant with a payload and a timestamp.
+ */
 export interface Event<TTag extends string, TPayload>
   extends TaggedVariant<TTag> {
   payload: TPayload;
diff --git a/packages/fabric/core/src/domain/security/policy-map.ts b/packages/fabric/core/src/domain/security/policy-map.ts
index 0a87745..df9a5de 100644
--- a/packages/fabric/core/src/domain/security/policy-map.ts
+++ b/packages/fabric/core/src/domain/security/policy-map.ts
@@ -1,3 +1,6 @@
+/**
+ * A PolicyMap maps user types to their security policies.
+ */
 export type PolicyMap<
   UserType extends string,
   PolicyType extends string,
diff --git a/packages/fabric/core/src/domain/types/index.ts b/packages/fabric/core/src/domain/types/index.ts
index 3495344..ea45bfc 100644
--- a/packages/fabric/core/src/domain/types/index.ts
+++ b/packages/fabric/core/src/domain/types/index.ts
@@ -1,3 +1,3 @@
 export * from "./email.js";
-export * from "./sem-ver.js";
+export * from "./semver.js";
 export * from "./uuid.js";
diff --git a/packages/fabric/core/src/domain/types/sem-ver.ts b/packages/fabric/core/src/domain/types/semver.ts
similarity index 100%
rename from packages/fabric/core/src/domain/types/sem-ver.ts
rename to packages/fabric/core/src/domain/types/semver.ts
diff --git a/packages/fabric/core/src/domain/use-case/use-case.ts b/packages/fabric/core/src/domain/use-case/use-case.ts
index 4d16295..54610a5 100644
--- a/packages/fabric/core/src/domain/use-case/use-case.ts
+++ b/packages/fabric/core/src/domain/use-case/use-case.ts
@@ -3,11 +3,6 @@ import { AsyncResult } from "../../result/async-result.js";
 
 /**
  * A use case is a piece of domain logic that can be executed.
- *
- * It can be one of two types:
- *
- *  - `Query`: A use case that only reads data.
- *  - `Command`: A use case that modifies data.
  */
 export type UseCase<
   TDependencies,
diff --git a/packages/fabric/core/src/error/is-error.ts b/packages/fabric/core/src/error/is-error.ts
index c653499..1dda468 100644
--- a/packages/fabric/core/src/error/is-error.ts
+++ b/packages/fabric/core/src/error/is-error.ts
@@ -1,15 +1,8 @@
-import { VariantTag } from "../variant/variant.js";
 import { TaggedError } from "./tagged-error.js";
 
 /**
  * Indicates if a value is an error.
- *
- * In case it is an error, the type of the error is able to be inferred.
  */
 export function isError(err: unknown): err is TaggedError<string> {
-  return (
-    err instanceof Error &&
-    VariantTag in err &&
-    typeof err[VariantTag] === "string"
-  );
+  return err instanceof TaggedError;
 }
diff --git a/packages/fabric/core/src/error/tagged-error.ts b/packages/fabric/core/src/error/tagged-error.ts
index d489886..01175a1 100644
--- a/packages/fabric/core/src/error/tagged-error.ts
+++ b/packages/fabric/core/src/error/tagged-error.ts
@@ -1,9 +1,7 @@
 import { TaggedVariant, VariantTag } from "../variant/index.js";
 
 /**
- * Un TaggedError es un error que tiene un tag que lo identifica, lo cual
- * permite a los consumidores de la instancia de error identificar el tipo de
- * error que ocurrió.
+ * A TaggedError is a tagged variant with an error message.
  */
 export class TaggedError<Tag extends string>
   extends Error
diff --git a/packages/fabric/core/src/error/unexpected-error.ts b/packages/fabric/core/src/error/unexpected-error.ts
index 4a72754..de2dee6 100644
--- a/packages/fabric/core/src/error/unexpected-error.ts
+++ b/packages/fabric/core/src/error/unexpected-error.ts
@@ -1,11 +1,11 @@
 import { TaggedError } from "./tagged-error.js";
 
 /**
- * `UnexpectedError` representa cualquier tipo de error inesperado.
+ * `UnexpectedError` represents any type of unexpected error.
  *
- * Este error se utiliza para representar errores que no deberían ocurrir en
- * la lógica de la aplicación, pero que siempre podrían suceder y
- * debemos estar preparados para manejarlos.
+ * This error is used to represent errors that should not occur in
+ * the application logic, but that could always happen and
+ * we must be prepared to handle.
  */
 export class UnexpectedError extends TaggedError<"UnexpectedError"> {
   constructor() {
diff --git a/packages/fabric/core/src/domain/entity/files/base-file.ts b/packages/fabric/core/src/files/base-file.ts
similarity index 100%
rename from packages/fabric/core/src/domain/entity/files/base-file.ts
rename to packages/fabric/core/src/files/base-file.ts
diff --git a/packages/fabric/core/src/domain/entity/files/bytes.ts b/packages/fabric/core/src/files/bytes.ts
similarity index 100%
rename from packages/fabric/core/src/domain/entity/files/bytes.ts
rename to packages/fabric/core/src/files/bytes.ts
diff --git a/packages/fabric/core/src/files/index.ts b/packages/fabric/core/src/files/index.ts
new file mode 100644
index 0000000..ed4ec55
--- /dev/null
+++ b/packages/fabric/core/src/files/index.ts
@@ -0,0 +1,8 @@
+export * from "./base-file.js";
+export * from "./bytes.js";
+export * from "./invalid-file-type-error.js";
+export * from "./is-mime-type.js";
+export * from "./is-uploaded-file.js";
+export * from "./media-file.js";
+export * from "./mime-type.js";
+export * from "./uploaded-file.js";
diff --git a/packages/fabric/core/src/domain/entity/files/invalid-file-type-error.ts b/packages/fabric/core/src/files/invalid-file-type-error.ts
similarity index 69%
rename from packages/fabric/core/src/domain/entity/files/invalid-file-type-error.ts
rename to packages/fabric/core/src/files/invalid-file-type-error.ts
index a69aa8e..5bc5f11 100644
--- a/packages/fabric/core/src/domain/entity/files/invalid-file-type-error.ts
+++ b/packages/fabric/core/src/files/invalid-file-type-error.ts
@@ -1,4 +1,4 @@
-import { TaggedError } from "../../../error/tagged-error.js";
+import { TaggedError } from "../error/tagged-error.js";
 
 export class InvalidFileTypeError extends TaggedError<"InvalidFileTypeError"> {
   constructor() {
diff --git a/packages/fabric/core/src/domain/entity/files/is-mime-type.spec.ts b/packages/fabric/core/src/files/is-mime-type.spec.ts
similarity index 100%
rename from packages/fabric/core/src/domain/entity/files/is-mime-type.spec.ts
rename to packages/fabric/core/src/files/is-mime-type.spec.ts
diff --git a/packages/fabric/core/src/domain/entity/files/is-mime-type.ts b/packages/fabric/core/src/files/is-mime-type.ts
similarity index 63%
rename from packages/fabric/core/src/domain/entity/files/is-mime-type.ts
rename to packages/fabric/core/src/files/is-mime-type.ts
index c4630b4..418aa4e 100644
--- a/packages/fabric/core/src/domain/entity/files/is-mime-type.ts
+++ b/packages/fabric/core/src/files/is-mime-type.ts
@@ -5,7 +5,7 @@ import { MimeType } from "./mime-type.js";
  */
 export function isMimeType<T extends MimeType>(
   expectedMimeType: T,
-  actualFileType: string,
-): actualFileType is T {
-  return actualFileType.match("^" + expectedMimeType + "$") !== null;
+  actualMimeType: string,
+): actualMimeType is T {
+  return actualMimeType.match("^" + expectedMimeType + "$") !== null;
 }
diff --git a/packages/fabric/core/src/domain/entity/files/is-uploaded-file.ts b/packages/fabric/core/src/files/is-uploaded-file.ts
similarity index 92%
rename from packages/fabric/core/src/domain/entity/files/is-uploaded-file.ts
rename to packages/fabric/core/src/files/is-uploaded-file.ts
index 8e37630..18556df 100644
--- a/packages/fabric/core/src/domain/entity/files/is-uploaded-file.ts
+++ b/packages/fabric/core/src/files/is-uploaded-file.ts
@@ -1,5 +1,5 @@
 import validator from "validator";
-import { isRecord } from "../../../record/is-record.js";
+import { isRecord } from "../record/is-record.js";
 import { InMemoryFile } from "./uploaded-file.js";
 
 const { isBase64, isMimeType } = validator;
diff --git a/packages/fabric/core/src/domain/entity/files/media-file.ts b/packages/fabric/core/src/files/media-file.ts
similarity index 74%
rename from packages/fabric/core/src/domain/entity/files/media-file.ts
rename to packages/fabric/core/src/files/media-file.ts
index c27232a..edf0b82 100644
--- a/packages/fabric/core/src/domain/entity/files/media-file.ts
+++ b/packages/fabric/core/src/files/media-file.ts
@@ -1,4 +1,4 @@
-import { DomainFile } from "./domain-file.js";
+import { DomainFile } from "../domain/entity/files/domain-file.js";
 
 /**
  * Represents a media file, either an image, a video or an audio file.
diff --git a/packages/fabric/core/src/domain/entity/files/mime-type.ts b/packages/fabric/core/src/files/mime-type.ts
similarity index 100%
rename from packages/fabric/core/src/domain/entity/files/mime-type.ts
rename to packages/fabric/core/src/files/mime-type.ts
diff --git a/packages/fabric/core/src/domain/entity/files/uploaded-file.ts b/packages/fabric/core/src/files/uploaded-file.ts
similarity index 74%
rename from packages/fabric/core/src/domain/entity/files/uploaded-file.ts
rename to packages/fabric/core/src/files/uploaded-file.ts
index 040e739..8c25367 100644
--- a/packages/fabric/core/src/domain/entity/files/uploaded-file.ts
+++ b/packages/fabric/core/src/files/uploaded-file.ts
@@ -1,4 +1,4 @@
-import { Base64String } from "../../types/base-64.js";
+import { Base64String } from "../domain/types/base-64.js";
 import { BaseFile } from "./base-file.js";
 
 /**
diff --git a/packages/fabric/core/src/time/timeout.spec.ts b/packages/fabric/core/src/time/timeout.spec.ts
index aa5c98e..8d9c3f9 100644
--- a/packages/fabric/core/src/time/timeout.spec.ts
+++ b/packages/fabric/core/src/time/timeout.spec.ts
@@ -32,7 +32,7 @@ describe("timeout", () => {
     },
   );
 
-  test("using ms we can define a timeout in milliseconds", async () => {
+  test("using timeout we can define a timeout in milliseconds", async () => {
     const start = Date.now();
     await timeout(100);
     const end = Date.now();