feat(refs): support direct declarations of Refs

package.json

@@ -76,13 +76,13 @@
     "postinstall": "[ -d .git ] && npx husky install || exit 0"
   },
   "dependencies": {
-    "@ehmpathy/error-fns": "1.3.1",
+    "@ehmpathy/error-fns": "1.3.7",
     "@oclif/core": "3.26.6",
     "@oclif/plugin-help": "6.0.22",
     "chalk": "2.4.2",
     "change-case": "4.1.1",
     "domain-objects": "0.22.1",
-    "domain-objects-metadata": "0.7.4",
+    "domain-objects-metadata": "0.7.5",
     "fast-glob": "3.2.2",
     "joi": "17.4.0",
     "lodash.omit": "4.5.0",

src/domain/objects/SqlSchemaReferenceMetadata.ts

@@ -3,7 +3,19 @@ import { DomainObjectReferenceMetadata } from 'domain-objects-metadata';
 import Joi from 'joi';
 
 export enum SqlSchemaReferenceMethod {
+  /**
+   * .what = when a domain literal is directly nested in another domain object
+   */
   DIRECT_BY_NESTING = 'DIRECT_BY_NESTING',
+
+  /**
+   * .what = when a domain object is explicitly referenced, via Ref<>, in another domain object
+   */
+  DIRECT_BY_DECLARATION = 'DIRECT_BY_DECLARATION',
+
+  /**
+   * .what = when a domain object is implicitly referenced, via uuid, in another domain object
+   */
   IMPLICIT_BY_UUID = 'IMPLICIT_BY_UUID',
 }
 

src/logic/__test_assets__/exampleProject/src/domain/objects/CarriageCargo.ts

@@ -0,0 +1,35 @@
+import { DomainEntity, Ref } from 'domain-objects';
+import { Carriage } from './Carriage';
+
+/**
+ * .what = cargo which has been allocated to a carriage at a given point in time
+ */
+export interface CarriageCargo {
+  id?: number;
+  uuid?: string;
+
+  /**
+   * the itinerary during which it is allocated
+   */
+  itineraryUuid: string; // todo: ref to an itinerary once we declare it
+
+  /**
+   * the carriage it has been allocated to
+   */
+  carriageRef: Ref<typeof Carriage>;
+
+  /**
+   * the slot that it has been allocated to on the carriage
+   */
+  slot: number;
+
+  /**
+   * the cargo that has been allocated
+   */
+  cargoExid: null | string;
+}
+export class CarriageCargo extends DomainEntity<CarriageCargo> implements CarriageCargo {
+  public static primary = ['uuid'] as const;
+  public static unique = ['itineraryUuid', 'carriageRef', 'slot'] as const;
+  public static updatable = ['cargoExid'];
+}

src/logic/__test_assets__/exampleProject/src/domain/objects/index.ts

@@ -1,4 +1,5 @@
 export * from './AsyncTaskPredictStationCongestion'
+export * from './CarriageCargo';
 export * from './Carriage';
 export * from './Certificate';
 export * from './Engineer';

src/logic/config/getConfig/extractDomainObjectMetadatasFromConfigCriteria.integration.test.ts

@@ -10,7 +10,7 @@ describe('extractDomainObjectMetadatasFromConfigCriteria', () => {
       exclude: null,
     });
     // console.log(JSON.stringify(metadatas, null, 2));
-    expect(metadatas.length).toEqual(12);
+    expect(metadatas.length).toEqual(13);
   });
   it('should find all of the domain objects findable by all search paths in a directory, with no dupes', async () => {
     const metadatas = await extractDomainObjectMetadatasFromConfigCriteria({
@@ -27,7 +27,7 @@ describe('extractDomainObjectMetadatasFromConfigCriteria', () => {
       exclude: null,
     });
     // console.log(JSON.stringify(metadatas, null, 2));
-    expect(metadatas.length).toEqual(12);
+    expect(metadatas.length).toEqual(13);
   });
   it('should only find the domain objects imported from the files in the search paths', async () => {
     const metadatas = await extractDomainObjectMetadatasFromConfigCriteria({
@@ -55,7 +55,7 @@ describe('extractDomainObjectMetadatasFromConfigCriteria', () => {
       exclude: ['TrainLocatedEvent'],
     });
     // console.log(JSON.stringify(metadatas, null, 2));
-    expect(metadatas.length).toEqual(11);
+    expect(metadatas.length).toEqual(12);
   });
   it('should only keep the one named in the `include` list, if provided', async () => {
     const metadatas = await extractDomainObjectMetadatasFromConfigCriteria({

src/logic/config/getConfig/getAllPathsMatchingGlobs.test.ts

@@ -16,7 +16,7 @@ describe('getAllPathsMatchingGlobs', () => {
     expect(files).toContain('src/domain/objects/Train.ts');
     expect(files).toContain('src/domain/objects/TrainLocatedEvent.ts');
     expect(files).toContain('src/domain/objects/Station.ts');
-    expect(files.length).toEqual(14);
+    expect(files.length).toEqual(15);
   });
   it('should return paths that match each glob', async () => {
     const files = await getAllPathsMatchingGlobs({

src/logic/config/getConfig/readConfig.integration.test.ts

@@ -37,7 +37,7 @@ describe('readConfig', () => {
         },
       },
     });
-    expect(config.for.objects.length).toEqual(11);
+    expect(config.for.objects.length).toEqual(12);
     expect(config).toMatchSnapshot({ rootDir: expect.anything() }); // to log an example of the output; ignore the rootDir, to make it machine independent
   });
 });