Refactor to use string IDs for executables #262

This commit unifies the concepts of executables having same ID
structure. It paves the way for more complex ID structure and using IDs
in collection files as part of new ID solution (#262). Using string IDs
also leads to more expressive test code.

This commit also refactors the rest of the code to adopt to the changes.

This commit:

- Separate concerns from entities for data access (in repositories) and
  executables. Executables use `Identifiable` meanwhile repositories use
  `RepositoryEntity`.
- Refactor unnecessary generic parameters for enttities and ids,
  enforcing string gtype everwyhere.
- Changes numeric IDs to string IDs for categories to unify the
  retrieval and construction for executables, using pseudo-ids (their
  names) just like scripts.
- Remove `BaseEntity` for simplicity.
- Simplify usage and construction of executable objects.
  Move factories responsible for creation of category/scripts to domain
  layer. Do not longer export `CollectionCategorY` and
  `CollectionScript`.
- Use named typed for string IDs for better differentation of different
  ID contexts in code.

docs/collection-files.md

@@ -30,6 +30,8 @@ Related documentation:
 
 ### Executables
 
+They represent independently executable tweaks with documentation and reversibility.
+
 An Executable is a logical entity that can
 
 - execute once compiled,

src/application/Context/ApplicationContext.ts

@@ -1,6 +1,6 @@
 import type { IApplication } from '@/domain/IApplication';
 import { OperatingSystem } from '@/domain/OperatingSystem';
-import type { ICategoryCollection } from '@/domain/ICategoryCollection';
+import type { ICategoryCollection } from '@/domain/Collection/ICategoryCollection';
 import { EventSource } from '@/infrastructure/Events/EventSource';
 import { assertInRange } from '@/application/Common/Enum';
 import { CategoryCollectionState } from './State/CategoryCollectionState';

src/application/Context/State/CategoryCollectionState.ts

@@ -1,4 +1,4 @@
-import type { ICategoryCollection } from '@/domain/ICategoryCollection';
+import type { ICategoryCollection } from '@/domain/Collection/ICategoryCollection';
 import { OperatingSystem } from '@/domain/OperatingSystem';
 import { AdaptiveFilterContext } from './Filter/AdaptiveFilterContext';
 import { ApplicationCode } from './Code/ApplicationCode';

src/application/Context/State/Code/Event/CodeChangedEvent.ts

@@ -36,12 +36,12 @@ export class CodeChangedEvent implements ICodeChangedEvent {
   }
 
   public getScriptPositionInCode(script: Script): ICodePosition {
-    return this.getPositionById(script.id);
+    return this.getPositionById(script.executableId);
   }
 
   private getPositionById(scriptId: string): ICodePosition {
     const position = [...this.scripts.entries()]
-      .filter(([s]) => s.id === scriptId)
+      .filter(([s]) => s.executableId === scriptId)
       .map(([, pos]) => pos)
       .at(0);
     if (!position) {

src/application/Context/State/Filter/AdaptiveFilterContext.ts

@@ -1,5 +1,5 @@
 import { EventSource } from '@/infrastructure/Events/EventSource';
-import type { ICategoryCollection } from '@/domain/ICategoryCollection';
+import type { ICategoryCollection } from '@/domain/Collection/ICategoryCollection';
 import { FilterChange } from './Event/FilterChange';
 import { LinearFilterStrategy } from './Strategy/LinearFilterStrategy';
 import type { FilterResult } from './Result/FilterResult';

src/application/Context/State/Filter/Strategy/FilterStrategy.ts

@@ -1,4 +1,4 @@
-import type { ICategoryCollection } from '@/domain/ICategoryCollection';
+import type { ICategoryCollection } from '@/domain/Collection/ICategoryCollection';
 import type { FilterResult } from '../Result/FilterResult';
 
 export interface FilterStrategy {

src/application/Context/State/Filter/Strategy/LinearFilterStrategy.ts

@@ -1,7 +1,7 @@
 import type { Category } from '@/domain/Executables/Category/Category';
 import type { ScriptCode } from '@/domain/Executables/Script/Code/ScriptCode';
 import type { Documentable } from '@/domain/Executables/Documentable';
-import type { ICategoryCollection } from '@/domain/ICategoryCollection';
+import type { ICategoryCollection } from '@/domain/Collection/ICategoryCollection';
 import type { Script } from '@/domain/Executables/Script/Script';
 import { AppliedFilterResult } from '../Result/AppliedFilterResult';
 import type { FilterStrategy } from './FilterStrategy';

src/application/Context/State/ICategoryCollectionState.ts

@@ -1,4 +1,4 @@
-import type { ICategoryCollection } from '@/domain/ICategoryCollection';
+import type { ICategoryCollection } from '@/domain/Collection/ICategoryCollection';
 import { OperatingSystem } from '@/domain/OperatingSystem';
 import type { IApplicationCode } from './Code/IApplicationCode';
 import type { ReadonlyFilterContext, FilterContext } from './Filter/FilterContext';

src/application/Context/State/Selection/Category/CategorySelectionChange.ts

@@ -1,3 +1,5 @@
+import type { ExecutableId } from '@/domain/Executables/Identifiable';
+
 type CategorySelectionStatus = {
   readonly isSelected: true;
   readonly isReverted: boolean;
@@ -6,7 +8,7 @@ type CategorySelectionStatus = {
 };
 
 export interface CategorySelectionChange {
-  readonly categoryId: number;
+  readonly categoryId: ExecutableId;
   readonly newStatus: CategorySelectionStatus;
 }
 

src/application/Context/State/Selection/Category/ScriptToCategorySelectionMapper.ts

@@ -1,5 +1,5 @@
 import type { Category } from '@/domain/Executables/Category/Category';
-import type { ICategoryCollection } from '@/domain/ICategoryCollection';
+import type { ICategoryCollection } from '@/domain/Collection/ICategoryCollection';
 import type { CategorySelectionChange, CategorySelectionChangeCommand } from './CategorySelectionChange';
 import type { CategorySelection } from './CategorySelection';
 import type { ScriptSelection } from '../Script/ScriptSelection';
@@ -23,7 +23,7 @@ export class ScriptToCategorySelectionMapper implements CategorySelection {
       return false;
     }
     return scripts.every(
-      (script) => selectedScripts.some((selected) => selected.id === script.id),
+      (script) => selectedScripts.some((selected) => selected.id === script.executableId),
     );
   }
 
@@ -50,7 +50,7 @@ export class ScriptToCategorySelectionMapper implements CategorySelection {
     const scripts = category.getAllScriptsRecursively();
     const scriptsChangesInCategory = scripts
       .map((script): ScriptSelectionChange => ({
-        scriptId: script.id,
+        scriptId: script.executableId,
         newStatus: {
           ...change.newStatus,
         },

src/application/Context/State/Selection/Script/DebouncedScriptSelection.ts

@@ -2,7 +2,7 @@ import { InMemoryRepository } from '@/infrastructure/Repository/InMemoryReposito
 import type { Script } from '@/domain/Executables/Script/Script';
 import { EventSource } from '@/infrastructure/Events/EventSource';
 import type { ReadonlyRepository, Repository } from '@/application/Repository/Repository';
-import type { ICategoryCollection } from '@/domain/ICategoryCollection';
+import type { ICategoryCollection } from '@/domain/Collection/ICategoryCollection';
 import { batchedDebounce } from '@/application/Common/Timing/BatchedDebounce';
 import { UserSelectedScript } from './UserSelectedScript';
 import type { ScriptSelection } from './ScriptSelection';
@@ -16,7 +16,7 @@ export type DebounceFunction = typeof batchedDebounce<ScriptSelectionChangeComma
 export class DebouncedScriptSelection implements ScriptSelection {
   public readonly changed = new EventSource<ReadonlyArray<SelectedScript>>();
 
-  private readonly scripts: Repository<string, SelectedScript>;
+  private readonly scripts: Repository<SelectedScript>;
 
   public readonly processChanges: ScriptSelection['processChanges'];
 
@@ -25,7 +25,7 @@ export class DebouncedScriptSelection implements ScriptSelection {
     selectedScripts: ReadonlyArray<SelectedScript>,
     debounce: DebounceFunction = batchedDebounce,
   ) {
-    this.scripts = new InMemoryRepository<string, SelectedScript>();
+    this.scripts = new InMemoryRepository<SelectedScript>();
     for (const script of selectedScripts) {
       this.scripts.addItem(script);
     }
@@ -49,7 +49,7 @@ export class DebouncedScriptSelection implements ScriptSelection {
   public selectAll(): void {
     const scriptsToSelect = this.collection
       .getAllScripts()
-      .filter((script) => !this.scripts.exists(script.id))
+      .filter((script) => !this.scripts.exists(script.executableId))
       .map((script) => new UserSelectedScript(script, false));
     if (scriptsToSelect.length === 0) {
       return;
@@ -116,9 +116,9 @@ export class DebouncedScriptSelection implements ScriptSelection {
   private applyChange(change: ScriptSelectionChange): number {
     const script = this.collection.getScript(change.scriptId);
     if (change.newStatus.isSelected) {
-      return this.addOrUpdateScript(script.id, change.newStatus.isReverted);
+      return this.addOrUpdateScript(script.executableId, change.newStatus.isReverted);
     }
-    return this.removeScript(script.id);
+    return this.removeScript(script.executableId);
   }
 
   private addOrUpdateScript(scriptId: string, revert: boolean): number {
@@ -152,24 +152,24 @@ function assertNonEmptyScriptSelection(selectedItems: readonly Script[]) {
 }
 
 function getScriptIdsToBeSelected(
-  existingItems: ReadonlyRepository<string, SelectedScript>,
+  existingItems: ReadonlyRepository<SelectedScript>,
   desiredScripts: readonly Script[],
 ): string[] {
   return desiredScripts
-    .filter((script) => !existingItems.exists(script.id))
-    .map((script) => script.id);
+    .filter((script) => !existingItems.exists(script.executableId))
+    .map((script) => script.executableId);
 }
 
 function getScriptIdsToBeDeselected(
-  existingItems: ReadonlyRepository<string, SelectedScript>,
+  existingItems: ReadonlyRepository<SelectedScript>,
   desiredScripts: readonly Script[],
 ): string[] {
   return existingItems
     .getItems()
-    .filter((existing) => !desiredScripts.some((script) => existing.id === script.id))
+    .filter((existing) => !desiredScripts.some((script) => existing.id === script.executableId))
     .map((script) => script.id);
 }
 
 function equals(a: SelectedScript, b: SelectedScript): boolean {
-  return a.script.equals(b.script.id) && a.revert === b.revert;
+  return a.script.executableId === b.script.executableId && a.revert === b.revert;
 }

src/application/Context/State/Selection/Script/SelectedScript.ts

@@ -1,9 +1,7 @@
-import type { IEntity } from '@/infrastructure/Entity/IEntity';
 import type { Script } from '@/domain/Executables/Script/Script';
+import type { RepositoryEntity } from '@/application/Repository/RepositoryEntity';
 
-type ScriptId = Script['id'];
-
-export interface SelectedScript extends IEntity<ScriptId> {
+export interface SelectedScript extends RepositoryEntity {
   readonly script: Script;
   readonly revert: boolean;
 }

src/application/Context/State/Selection/Script/UserSelectedScript.ts

@@ -1,17 +1,16 @@
-import { BaseEntity } from '@/infrastructure/Entity/BaseEntity';
 import type { Script } from '@/domain/Executables/Script/Script';
-import type { SelectedScript } from './SelectedScript';
+import type { RepositoryEntity } from '@/application/Repository/RepositoryEntity';
 
-type SelectedScriptId = SelectedScript['id'];
+export class UserSelectedScript implements RepositoryEntity {
+  public readonly id: string;
 
-export class UserSelectedScript extends BaseEntity<SelectedScriptId> {
   constructor(
     public readonly script: Script,
     public readonly revert: boolean,
   ) {
-    super(script.id);
+    this.id = script.executableId;
     if (revert && !script.canRevert()) {
-      throw new Error(`The script with ID '${script.id}' is not reversible and cannot be reverted.`);
+      throw new Error(`The script with ID '${script.executableId}' is not reversible and cannot be reverted.`);
     }
   }
 }

src/application/Context/State/Selection/UserSelectionFacade.ts

@@ -1,4 +1,4 @@
-import type { ICategoryCollection } from '@/domain/ICategoryCollection';
+import type { ICategoryCollection } from '@/domain/Collection/ICategoryCollection';
 import { ScriptToCategorySelectionMapper } from './Category/ScriptToCategorySelectionMapper';
 import { DebouncedScriptSelection } from './Script/DebouncedScriptSelection';
 import type { CategorySelection } from './Category/CategorySelection';

src/application/Parser/CategoryCollectionParser.ts

@@ -1,7 +1,7 @@
 import type { CollectionData } from '@/application/collections/';
 import { OperatingSystem } from '@/domain/OperatingSystem';
-import type { ICategoryCollection } from '@/domain/ICategoryCollection';
-import { CategoryCollection } from '@/domain/CategoryCollection';
+import type { ICategoryCollection } from '@/domain/Collection/ICategoryCollection';
+import { CategoryCollection } from '@/domain/Collection/CategoryCollection';
 import type { ProjectDetails } from '@/domain/Project/ProjectDetails';
 import { createEnumParser, type EnumParser } from '../Common/Enum';
 import { parseCategory, type CategoryParser } from './Executable/CategoryParser';

src/application/Parser/Executable/CategoryParser.ts

@@ -3,16 +3,14 @@ import type {
 } from '@/application/collections/';
 import { wrapErrorWithAdditionalContext, type ErrorWithContextWrapper } from '@/application/Parser/Common/ContextualError';
 import type { Category } from '@/domain/Executables/Category/Category';
-import { CollectionCategory } from '@/domain/Executables/Category/CollectionCategory';
 import type { Script } from '@/domain/Executables/Script/Script';
+import { createCategory, type CategoryFactory } from '@/domain/Executables/Category/CategoryFactory';
 import { parseDocs, type DocsParser } from './DocumentationParser';
 import { parseScript, type ScriptParser } from './Script/ScriptParser';
 import { createExecutableDataValidator, type ExecutableValidator, type ExecutableValidatorFactory } from './Validation/ExecutableValidator';
 import { ExecutableType } from './Validation/ExecutableType';
 import type { CategoryCollectionSpecificUtilities } from './CategoryCollectionSpecificUtilities';
 
-let categoryIdCounter = 0;
-
 export const parseCategory: CategoryParser = (
   category: CategoryData,
   collectionUtilities: CategoryCollectionSpecificUtilities,
@@ -59,7 +57,7 @@ function parseCategoryRecursively(
   }
   try {
     return context.categoryUtilities.createCategory({
-      id: categoryIdCounter++,
+      executableId: context.categoryData.category, // arbitrary ID
       name: context.categoryData.category,
       docs: context.categoryUtilities.parseDocs(context.categoryData),
       subcategories: children.subcategories,
@@ -166,10 +164,6 @@ function hasProperty(
   return Object.prototype.hasOwnProperty.call(object, propertyName);
 }
 
-export type CategoryFactory = (
-  ...parameters: ConstructorParameters<typeof CollectionCategory>
-) => Category;
-
 interface CategoryParserUtilities {
   readonly createCategory: CategoryFactory;
   readonly wrapError: ErrorWithContextWrapper;
@@ -179,7 +173,7 @@ interface CategoryParserUtilities {
 }
 
 const DefaultCategoryParserUtilities: CategoryParserUtilities = {
-  createCategory: (...parameters) => new CollectionCategory(...parameters),
+  createCategory,
   wrapError: wrapErrorWithAdditionalContext,
   createValidator: createExecutableDataValidator,
   parseScript,

src/application/Parser/Executable/Script/ScriptParser.ts

@@ -1,7 +1,6 @@
 import type { ScriptData, CodeScriptData, CallScriptData } from '@/application/collections/';
 import { NoEmptyLines } from '@/application/Parser/Executable/Script/Validation/Rules/NoEmptyLines';
 import type { ILanguageSyntax } from '@/application/Parser/Executable/Script/Validation/Syntax/ILanguageSyntax';
-import { CollectionScript } from '@/domain/Executables/Script/CollectionScript';
 import { RecommendationLevel } from '@/domain/Executables/Script/RecommendationLevel';
 import type { ScriptCode } from '@/domain/Executables/Script/Code/ScriptCode';
 import type { ICodeValidator } from '@/application/Parser/Executable/Script/Validation/ICodeValidator';
@@ -10,6 +9,7 @@ import type { ScriptCodeFactory } from '@/domain/Executables/Script/Code/ScriptC
 import { createScriptCode } from '@/domain/Executables/Script/Code/ScriptCodeFactory';
 import type { Script } from '@/domain/Executables/Script/Script';
 import { createEnumParser, type EnumParser } from '@/application/Common/Enum';
+import { createScript, type ScriptFactory } from '@/domain/Executables/Script/ScriptFactory';
 import { parseDocs, type DocsParser } from '../DocumentationParser';
 import { ExecutableType } from '../Validation/ExecutableType';
 import { createExecutableDataValidator, type ExecutableValidator, type ExecutableValidatorFactory } from '../Validation/ExecutableValidator';
@@ -37,6 +37,7 @@ export const parseScript: ScriptParser = (
   validateScript(data, validator);
   try {
     const script = scriptUtilities.createScript({
+      executableId: data.name, // arbitrary ID
       name: data.name,
       code: parseCode(
         data,
@@ -132,14 +133,6 @@ interface ScriptParserUtilities {
   readonly parseDocs: DocsParser;
 }
 
-export type ScriptFactory = (
-  ...parameters: ConstructorParameters<typeof CollectionScript>
-) => Script;
-
-const createScript: ScriptFactory = (...parameters) => {
-  return new CollectionScript(...parameters);
-};
-
 const DefaultUtilities: ScriptParserUtilities = {
   levelParser: createEnumParser(RecommendationLevel),
   createScript,

src/application/Repository/Repository.ts

@@ -1,17 +1,19 @@
-import type { IEntity } from '@/infrastructure/Entity/IEntity';
+import type { RepositoryEntity } from './RepositoryEntity';
 
-export interface ReadonlyRepository<TKey, TEntity extends IEntity<TKey>> {
+type EntityId = RepositoryEntity['id'];
+
+export interface ReadonlyRepository<TEntity extends RepositoryEntity> {
   readonly length: number;
   getItems(predicate?: (entity: TEntity) => boolean): readonly TEntity[];
-  getById(id: TKey): TEntity;
-  exists(id: TKey): boolean;
+  getById(id: EntityId): TEntity;
+  exists(id: EntityId): boolean;
 }
 
-export interface MutableRepository<TKey, TEntity extends IEntity<TKey>> {
+export interface MutableRepository<TEntity extends RepositoryEntity> {
   addItem(item: TEntity): void;
   addOrUpdateItem(item: TEntity): void;
-  removeItem(id: TKey): void;
+  removeItem(id: EntityId): void;
 }
 
-export interface Repository<TKey, TEntity extends IEntity<TKey>>
-  extends ReadonlyRepository<TKey, TEntity>, MutableRepository<TKey, TEntity> { }
+export interface Repository<TEntity extends RepositoryEntity>
+  extends ReadonlyRepository<TEntity>, MutableRepository<TEntity> { }

src/application/Repository/RepositoryEntity.ts

@@ -0,0 +1,6 @@
+/** Aggregate root */
+export type RepositoryEntityId = string;
+
+export interface RepositoryEntity {
+  readonly id: RepositoryEntityId;
+}

src/domain/Application.ts

@@ -1,6 +1,6 @@
 import { OperatingSystem } from './OperatingSystem';
 import type { IApplication } from './IApplication';
-import type { ICategoryCollection } from './ICategoryCollection';
+import type { ICategoryCollection } from './Collection/ICategoryCollection';
 import type { ProjectDetails } from './Project/ProjectDetails';
 
 export class Application implements IApplication {