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.
This commit is contained in:
undergroundwires
2024-06-16 11:44:48 +02:00
parent 19ea8dbc5b
commit 48d6dbd700
96 changed files with 1417 additions and 1109 deletions

View File

@@ -0,0 +1,316 @@
import { describe, it, expect } from 'vitest';
import { CategoryStub } from '@tests/unit/shared/Stubs/CategoryStub';
import { ScriptStub } from '@tests/unit/shared/Stubs/ScriptStub';
import { itEachAbsentStringValue } from '@tests/unit/shared/TestCases/AbsentTests';
import type { Category } from '@/domain/Executables/Category/Category';
import type { Script } from '@/domain/Executables/Script/Script';
import { createCategory } from '@/domain/Executables/Category/CategoryFactory';
import type { ExecutableId } from '@/domain/Executables/Identifiable';
describe('CategoryFactory', () => {
describe('createCategory', () => {
describe('id', () => {
it('assigns id correctly', () => {
// arrange
const expectedId: ExecutableId = 'expected category id';
// act
const category = new TestContext()
.withId(expectedId)
.build();
// assert
const actualId = category.executableId;
expect(actualId).to.equal(expectedId);
});
describe('throws error if id is absent', () => {
itEachAbsentStringValue((absentValue) => {
// arrange
const expectedError = 'missing ID';
const id = absentValue;
// act
const construct = () => new TestContext()
.withId(id)
.build();
// assert
expect(construct).to.throw(expectedError);
}, { excludeNull: true, excludeUndefined: true });
});
});
describe('name', () => {
it('assigns name correctly', () => {
// arrange
const expectedName = 'expected category name';
// act
const category = new TestContext()
.withName(expectedName)
.build();
// assert
const actualName = category.name;
expect(actualName).to.equal(expectedName);
});
describe('throws error if name is absent', () => {
itEachAbsentStringValue((absentValue) => {
// arrange
const expectedError = 'missing name';
const name = absentValue;
// act
const construct = () => new TestContext()
.withName(name)
.build();
// assert
expect(construct).to.throw(expectedError);
}, { excludeNull: true, excludeUndefined: true });
});
});
describe('docs', () => {
it('assigns docs correctly', () => {
// arrange
const expectedDocs = ['expected', 'docs'];
// act
const category = new TestContext()
.withDocs(expectedDocs)
.build();
// assert
const actualDocs = category.docs;
expect(actualDocs).to.equal(expectedDocs);
});
});
describe('children', () => {
it('assigns scripts correctly', () => {
// arrange
const expectedScripts = [
new ScriptStub('expected-script-1'),
new ScriptStub('expected-script-2'),
];
// act
const category = new TestContext()
.withScripts(expectedScripts)
.build();
// assert
const actualScripts = category.docs;
expect(actualScripts).to.equal(expectedScripts);
});
it('assigns categories correctly', () => {
// arrange
const expectedCategories = [
new CategoryStub('expected-subcategory-1'),
new CategoryStub('expected-subcategory-2'),
];
// act
const category = new TestContext()
.withSubcategories(expectedCategories)
.build();
// assert
const actualCategories = category.subcategories;
expect(actualCategories).to.equal(expectedCategories);
});
it('throws error if no children are present', () => {
// arrange
const expectedError = 'A category must have at least one sub-category or script';
const scriptChildren: readonly Script[] = [];
const categoryChildren: readonly Category[] = [];
// act
const construct = () => new TestContext()
.withSubcategories(categoryChildren)
.withScripts(scriptChildren)
.build();
// assert
expect(construct).to.throw(expectedError);
});
});
describe('getAllScriptsRecursively', () => {
it('retrieves direct child scripts', () => {
// arrange
const expectedScripts: readonly Script[] = [
new ScriptStub('expected-script-1'),
new ScriptStub('expected-script-2'),
];
const category = new TestContext()
.withScripts(expectedScripts)
.build();
// act
const actual = category.getAllScriptsRecursively();
// assert
expect(actual).to.have.deep.members(expectedScripts);
});
it('retrieves scripts from direct child categories', () => {
// arrange
const expectedScriptIds: readonly string[] = [
'1', '2', '3', '4',
];
const subcategories: readonly Category[] = [
new CategoryStub('subcategory-1').withScriptIds('1', '2'),
new CategoryStub('subcategory-2').withScriptIds('3', '4'),
];
const category = new TestContext()
.withScripts([])
.withSubcategories(subcategories)
.build();
// act
const actualIds = category
.getAllScriptsRecursively()
.map((s) => s.executableId);
// assert
expect(actualIds).to.have.deep.members(expectedScriptIds);
});
it('retrieves scripts from both direct children and child categories', () => {
// arrange
const expectedScriptIds: readonly string[] = [
'1', '2', '3', '4', '5', '6',
];
const subcategories: readonly Category[] = [
new CategoryStub('subcategory-1').withScriptIds('1', '2'),
new CategoryStub('subcategory-2').withScriptIds('3', '4'),
];
const scripts: readonly Script[] = [
new ScriptStub('1'),
new ScriptStub('2'),
];
const category = new TestContext()
.withSubcategories(subcategories)
.withScripts(scripts)
.build();
// act
const actualIds = category
.getAllScriptsRecursively()
.map((s) => s.executableId);
// assert
expect(actualIds).to.have.deep.members(expectedScriptIds);
});
it('retrieves scripts from nested categories recursively', () => {
// arrange
const expectedScriptIds: readonly string[] = [
'1', '2', '3', '4', '5', '6',
];
const subcategories: readonly Category[] = [
new CategoryStub('subcategory-1')
.withScriptIds('1', '2')
.withCategory(
new CategoryStub('subcategory-1-subcategory-1')
.withScriptIds('3', '4'),
),
new CategoryStub('subcategory-2')
.withCategories(
new CategoryStub('subcategory-2-subcategory-1')
.withScriptIds('5')
.withCategory(
new CategoryStub('subcategory-2-subcategory-1-subcategory-1')
.withCategory(
new CategoryStub('subcategory-2-subcategory-1-subcategory-1-subcategory-1')
.withScriptIds('6'),
),
),
),
];
// assert
const category = new TestContext()
.withScripts([])
.withSubcategories(subcategories)
.build();
// act
const actualIds = category
.getAllScriptsRecursively()
.map((s) => s.executableId);
// assert
expect(actualIds).to.have.deep.members(expectedScriptIds);
});
});
describe('includes', () => {
it('returns false for scripts not included', () => {
// assert
const expectedResult = false;
const script = new ScriptStub('3');
const childCategory = new CategoryStub('subcategory')
.withScriptIds('1', '2');
const category = new TestContext()
.withSubcategories([childCategory])
.build();
// act
const actual = category.includes(script);
// assert
expect(actual).to.equal(expectedResult);
});
it('returns true for scripts directly included', () => {
// assert
const expectedResult = true;
const script = new ScriptStub('3');
const childCategory = new CategoryStub('subcategory')
.withScript(script)
.withScriptIds('non-related');
const category = new TestContext()
.withSubcategories([childCategory])
.build();
// act
const actual = category.includes(script);
// assert
expect(actual).to.equal(expectedResult);
});
it('returns true for scripts included in nested categories', () => {
// assert
const expectedResult = true;
const script = new ScriptStub('3');
const childCategory = new CategoryStub('subcategory')
.withScriptIds('non-related')
.withCategory(
new CategoryStub('nested-subcategory')
.withScript(script),
);
const category = new TestContext()
.withSubcategories([childCategory])
.build();
// act
const actual = category.includes(script);
// assert
expect(actual).to.equal(expectedResult);
});
});
});
});
class TestContext {
private id = `[${TestContext.name}] test category`;
private name = 'test-category';
private docs: ReadonlyArray<string> = [];
private subcategories: ReadonlyArray<Category> = [];
private scripts: ReadonlyArray<Script> = [
new ScriptStub(`[${TestContext.name}] script`),
];
public withId(id: string): this {
this.id = id;
return this;
}
public withName(name: string): this {
this.name = name;
return this;
}
public withDocs(docs: ReadonlyArray<string>): this {
this.docs = docs;
return this;
}
public withScripts(scripts: ReadonlyArray<Script>): this {
this.scripts = scripts;
return this;
}
public withSubcategories(subcategories: ReadonlyArray<Category>): this {
this.subcategories = subcategories;
return this;
}
public build(): ReturnType<typeof createCategory> {
return createCategory({
executableId: this.id,
name: this.name,
docs: this.docs,
subcategories: this.subcategories,
scripts: this.scripts,
});
}
}

View File

@@ -1,217 +0,0 @@
import { describe, it, expect } from 'vitest';
import { CollectionCategory } from '@/domain/Executables/Category/CollectionCategory';
import { CategoryStub } from '@tests/unit/shared/Stubs/CategoryStub';
import { ScriptStub } from '@tests/unit/shared/Stubs/ScriptStub';
import { itEachAbsentStringValue } from '@tests/unit/shared/TestCases/AbsentTests';
import type { Category } from '@/domain/Executables/Category/Category';
import type { Script } from '@/domain/Executables/Script/Script';
describe('CollectionCategory', () => {
describe('ctor', () => {
describe('throws error if name is absent', () => {
itEachAbsentStringValue((absentValue) => {
// arrange
const expectedError = 'missing name';
const name = absentValue;
// act
const construct = () => new CategoryBuilder()
.withName(name)
.build();
// assert
expect(construct).to.throw(expectedError);
}, { excludeNull: true, excludeUndefined: true });
});
it('throws error if no children are present', () => {
// arrange
const expectedError = 'A category must have at least one sub-category or script';
const scriptChildren: readonly Script[] = [];
const categoryChildren: readonly Category[] = [];
// act
const construct = () => new CategoryBuilder()
.withSubcategories(categoryChildren)
.withScripts(scriptChildren)
.build();
// assert
expect(construct).to.throw(expectedError);
});
});
describe('getAllScriptsRecursively', () => {
it('retrieves direct child scripts', () => {
// arrange
const expectedScripts = [new ScriptStub('1'), new ScriptStub('2')];
const sut = new CategoryBuilder()
.withScripts(expectedScripts)
.build();
// act
const actual = sut.getAllScriptsRecursively();
// assert
expect(actual).to.have.deep.members(expectedScripts);
});
it('retrieves scripts from direct child categories', () => {
// arrange
const expectedScriptIds = ['1', '2', '3', '4'];
const categories = [
new CategoryStub(31).withScriptIds('1', '2'),
new CategoryStub(32).withScriptIds('3', '4'),
];
const sut = new CategoryBuilder()
.withScripts([])
.withSubcategories(categories)
.build();
// act
const actualIds = sut
.getAllScriptsRecursively()
.map((s) => s.id);
// assert
expect(actualIds).to.have.deep.members(expectedScriptIds);
});
it('retrieves scripts from both direct children and child categories', () => {
// arrange
const expectedScriptIds = ['1', '2', '3', '4', '5', '6'];
const categories = [
new CategoryStub(31).withScriptIds('1', '2'),
new CategoryStub(32).withScriptIds('3', '4'),
];
const scripts = [new ScriptStub('5'), new ScriptStub('6')];
const sut = new CategoryBuilder()
.withSubcategories(categories)
.withScripts(scripts)
.build();
// act
const actualIds = sut
.getAllScriptsRecursively()
.map((s) => s.id);
// assert
expect(actualIds).to.have.deep.members(expectedScriptIds);
});
it('retrieves scripts from nested categories recursively', () => {
// arrange
const expectedScriptIds = ['1', '2', '3', '4', '5', '6'];
const categories = [
new CategoryStub(31)
.withScriptIds('1', '2')
.withCategory(
new CategoryStub(32)
.withScriptIds('3', '4'),
),
new CategoryStub(33)
.withCategories(
new CategoryStub(34)
.withScriptIds('5')
.withCategory(
new CategoryStub(35)
.withCategory(
new CategoryStub(35).withScriptIds('6'),
),
),
),
];
// assert
const sut = new CategoryBuilder()
.withScripts([])
.withSubcategories(categories)
.build();
// act
const actualIds = sut
.getAllScriptsRecursively()
.map((s) => s.id);
// assert
expect(actualIds).to.have.deep.members(expectedScriptIds);
});
});
describe('includes', () => {
it('returns false for scripts not included', () => {
// assert
const expectedResult = false;
const script = new ScriptStub('3');
const childCategory = new CategoryStub(33)
.withScriptIds('1', '2');
const sut = new CategoryBuilder()
.withSubcategories([childCategory])
.build();
// act
const actual = sut.includes(script);
// assert
expect(actual).to.equal(expectedResult);
});
it('returns true for scripts directly included', () => {
// assert
const expectedResult = true;
const script = new ScriptStub('3');
const childCategory = new CategoryStub(33)
.withScript(script)
.withScriptIds('non-related');
const sut = new CategoryBuilder()
.withSubcategories([childCategory])
.build();
// act
const actual = sut.includes(script);
// assert
expect(actual).to.equal(expectedResult);
});
it('returns true for scripts included in nested categories', () => {
// assert
const expectedResult = true;
const script = new ScriptStub('3');
const childCategory = new CategoryStub(22)
.withScriptIds('non-related')
.withCategory(new CategoryStub(33).withScript(script));
const sut = new CategoryBuilder()
.withSubcategories([childCategory])
.build();
// act
const actual = sut.includes(script);
// assert
expect(actual).to.equal(expectedResult);
});
});
});
class CategoryBuilder {
private id = 3264;
private name = 'test-script';
private docs: ReadonlyArray<string> = [];
private subcategories: ReadonlyArray<Category> = [];
private scripts: ReadonlyArray<Script> = [
new ScriptStub(`[${CategoryBuilder.name}] script`),
];
public withId(id: number): this {
this.id = id;
return this;
}
public withName(name: string): this {
this.name = name;
return this;
}
public withDocs(docs: ReadonlyArray<string>): this {
this.docs = docs;
return this;
}
public withScripts(scripts: ReadonlyArray<Script>): this {
this.scripts = scripts;
return this;
}
public withSubcategories(subcategories: ReadonlyArray<Category>): this {
this.subcategories = subcategories;
return this;
}
public build(): CollectionCategory {
return new CollectionCategory({
id: this.id,
name: this.name,
docs: this.docs,
subcategories: this.subcategories,
scripts: this.scripts,
});
}
}

View File

@@ -1,21 +1,35 @@
import { describe, it, expect } from 'vitest';
import { getEnumValues } from '@/application/Common/Enum';
import { CollectionScript } from '@/domain/Executables/Script/CollectionScript';
import { RecommendationLevel } from '@/domain/Executables/Script/RecommendationLevel';
import type { ScriptCode } from '@/domain/Executables/Script/Code/ScriptCode';
import { ScriptCodeStub } from '@tests/unit/shared/Stubs/ScriptCodeStub';
import { createScript } from '@/domain/Executables/Script/ScriptFactory';
import type { ExecutableId } from '@/domain/Executables/Identifiable';
describe('CollectionScript', () => {
describe('ctor', () => {
describe('ScriptFactory', () => {
describe('createScript', () => {
describe('id', () => {
it('correctly assigns id', () => {
// arrange
const expectedId: ExecutableId = 'expected-id';
// act
const script = new TestContext()
.withId(expectedId)
.build();
// assert
const actualId = script.executableId;
expect(actualId).to.equal(expectedId);
});
});
describe('scriptCode', () => {
it('assigns code correctly', () => {
// arrange
const expected = new ScriptCodeStub();
const sut = new ScriptBuilder()
const script = new TestContext()
.withCode(expected)
.build();
// act
const actual = sut.code;
const actual = script.code;
// assert
expect(actual).to.deep.equal(expected);
});
@@ -23,21 +37,21 @@ describe('CollectionScript', () => {
describe('canRevert', () => {
it('returns false without revert code', () => {
// arrange
const sut = new ScriptBuilder()
const script = new TestContext()
.withCodes('code')
.build();
// act
const actual = sut.canRevert();
const actual = script.canRevert();
// assert
expect(actual).to.equal(false);
});
it('returns true with revert code', () => {
// arrange
const sut = new ScriptBuilder()
const script = new TestContext()
.withCodes('code', 'non empty revert code')
.build();
// act
const actual = sut.canRevert();
const actual = script.canRevert();
// assert
expect(actual).to.equal(true);
});
@@ -48,7 +62,7 @@ describe('CollectionScript', () => {
const invalidValue: RecommendationLevel = 55 as never;
const expectedError = 'invalid level';
// act
const construct = () => new ScriptBuilder()
const construct = () => new TestContext()
.withRecommendationLevel(invalidValue)
.build();
// assert
@@ -58,43 +72,46 @@ describe('CollectionScript', () => {
// arrange
const expected = undefined;
// act
const sut = new ScriptBuilder()
const script = new TestContext()
.withRecommendationLevel(expected)
.build();
// assert
expect(sut.level).to.equal(expected);
expect(script.level).to.equal(expected);
});
it('correctly assigns valid recommendation levels', () => {
// arrange
for (const expected of getEnumValues(RecommendationLevel)) {
getEnumValues(RecommendationLevel).forEach((enumValue) => {
// arrange
const expectedRecommendationLevel = enumValue;
// act
const sut = new ScriptBuilder()
.withRecommendationLevel(expected)
const script = new TestContext()
.withRecommendationLevel(expectedRecommendationLevel)
.build();
// assert
const actual = sut.level;
expect(actual).to.equal(expected);
}
const actualRecommendationLevel = script.level;
expect(actualRecommendationLevel).to.equal(expectedRecommendationLevel);
});
});
});
describe('docs', () => {
it('correctly assigns docs', () => {
// arrange
const expected = ['doc1', 'doc2'];
const expectedDocs = ['doc1', 'doc2'];
// act
const sut = new ScriptBuilder()
.withDocs(expected)
const script = new TestContext()
.withDocs(expectedDocs)
.build();
const actual = sut.docs;
// assert
expect(actual).to.equal(expected);
const actualDocs = script.docs;
expect(actualDocs).to.equal(expectedDocs);
});
});
});
});
class ScriptBuilder {
private name = 'test-script';
class TestContext {
private name = `[${TestContext.name}]test-script`;
private id: ExecutableId = `[${TestContext.name}]id`;
private code: ScriptCode = new ScriptCodeStub();
@@ -109,6 +126,11 @@ class ScriptBuilder {
return this;
}
public withId(id: ExecutableId): this {
this.id = id;
return this;
}
public withCode(code: ScriptCode): this {
this.code = code;
return this;
@@ -129,8 +151,9 @@ class ScriptBuilder {
return this;
}
public build(): CollectionScript {
return new CollectionScript({
public build(): ReturnType<typeof createScript> {
return createScript({
executableId: this.id,
name: this.name,
code: this.code,
docs: this.docs,