@schorts/shared-kernel 1.0.4 → 1.1.0

package/CHANGELOG

@@ -5,6 +5,23 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.1.0] - 2025-09-30
+
+### Changed
+
+- Now the `ValueObject` for ID property on `Entity` is required.
+
+### Added
+
+- Added `EntityRegistry` to dynamically instantiate entities in the DAO implementation.
+
+## [1.0.5] - 2025-09-30
+
+### Added
+
+- Introduce `DAO` concept for a related package with a `Firestore` implementation.
+- Introduce `UnitOfWOrk` concept for a related package with a `Firestore` implementation.
+
 ## [1.0.4] - 2025-09-30
 
 ### Fixed
@@ -21,5 +38,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Removed indirect dependencies from the `package.json`.
 
-[1.0.3]: https://github.com/schorts99/shared-kernel/compare/v1.0.3...v0.0.4
+[1.0.5]: https://github.com/schorts99/shared-kernel/compare/v1.0.5...v1.1.0
+[1.0.5]: https://github.com/schorts99/shared-kernel/compare/v1.0.4...v0.0.5
+[1.0.4]: https://github.com/schorts99/shared-kernel/compare/v1.0.3...v0.0.4
 [1.0.3]: https://github.com/schorts99/shared-kernel/releases/tag/v1.0.3

package/README.md

@@ -26,6 +26,7 @@ npm install @schorts/shared-kernel --save
 ### 🧬 Entities
 
 - **Entity:** Base class for identity-based domain entities.
+- **EntityRegistry:** Dynamic registry for entity constructors, enabling polymorphic and type-safe instantiation of domain entities from serialized data.
 
 ### 🧹 Formatters
 
@@ -44,6 +45,11 @@ npm install @schorts/shared-kernel --save
 
 - **BaseModel:** Base class for serializable, type-safe models.
 
+### 🛠 Persistence
+
+- **DAO:** Generic interface defining data access operations for domain entities.
+- **UnitOfWork:** Interface enabling transactional coordination across multiple persistence operations.
+
 ### 🧠 State Manager
 
 - **StateManager:** Abstract reactive state manager with listener support.

package/__tests__/auth/auth-provider.test.ts

@@ -2,13 +2,18 @@ import { expectTypeOf } from "expect-type";
 
 import { AuthProvider } from "../../src/auth";
 import { Entity } from "../../src/entities";
+import { UUIDValue } from "../../src/value-objects";
 
 type Model = {
   id: string;
   name: string;
 };
 
-class TestUser extends Entity<Model> {
+class IDValue extends UUIDValue {
+  attributeName = "ID";
+}
+
+class TestUser extends Entity<IDValue, Model> {
   toPrimitives(): Model {
     return {
       id: this.id.toString(),

package/__tests__/dao/dao.test.ts

@@ -0,0 +1,109 @@
+import { expectTypeOf } from "expect-type";
+
+import { DAO } from "../../src/dao";
+import { Entity } from "../../src/entities";
+import { Criteria } from "../../src/criteria";
+import { UUIDValue } from "../../src/value-objects";
+
+type Model = {
+  id: string;
+  name: string;
+};
+
+class IDValue extends UUIDValue {
+  attributeName = "ID";
+}
+
+class ModelEntity extends Entity<IDValue, Model> {
+  toPrimitives(): Model {
+    throw new Error("Method not implemented.");
+  }
+}
+
+describe("DAO", () => {
+  describe('#getAll', () => {
+    it('should declare the method', () => {
+      expectTypeOf<DAO<Model, ModelEntity>>().toHaveProperty("getAll");
+    });
+
+    it('should no require any arguments', () => {
+      expectTypeOf<DAO<Model, ModelEntity>['getAll']>().parameters.toEqualTypeOf<[]>();
+    });
+
+    it('should return a promise with the Entity', () => {
+      expectTypeOf<DAO<Model, ModelEntity>['getAll']>().returns.toEqualTypeOf<Promise<ModelEntity[]>>();
+    });
+  });
+
+  describe('#findByID', () => {
+    it('should declare the method', () => {
+      expectTypeOf<DAO<Model, ModelEntity>>().toHaveProperty("findByID");
+    });
+
+    it('should require the ID argument', () => {
+      expectTypeOf<DAO<Model, ModelEntity>['findByID']>().parameters.toEqualTypeOf<[ModelEntity["id"]["value"]]>();
+    });
+
+    it('should return a promise with the Entity or null', () => {
+      expectTypeOf<DAO<Model, ModelEntity>['findByID']>().returns.toEqualTypeOf<Promise<ModelEntity | null>>();
+    });
+  });
+
+  describe('#findOneBy', () => {
+    it('should declare the method', () => {
+      expectTypeOf<DAO<Model, ModelEntity>>().toHaveProperty("findOneBy");
+    });
+
+    it('should receive the criteria', () => {
+      expectTypeOf<DAO<Model, ModelEntity>['findOneBy']>().parameters.toEqualTypeOf<[Criteria]>();
+    });
+
+    it('should return a promise with the Entity or null', () => {
+      expectTypeOf<DAO<Model, ModelEntity>['findOneBy']>().returns.toEqualTypeOf<Promise<ModelEntity | null>>();
+    });
+  });
+
+  describe('#search', () => {
+    it('should declare the method', () => {
+      expectTypeOf<DAO<Model, ModelEntity>>().toHaveProperty("search");
+    });
+
+    it('should receive the criteria argument', () => {
+      expectTypeOf<DAO<Model, ModelEntity>['search']>().parameters.toEqualTypeOf<[Criteria]>();
+    });
+
+    it('should return a promise with an array of entities', () => {
+      expectTypeOf<DAO<Model, ModelEntity>['search']>().returns.toEqualTypeOf<Promise<ModelEntity[]>>();
+    });
+  });
+
+  describe('#create', () => {
+    it('should declare the method', () => {
+      expectTypeOf<DAO<Model, ModelEntity>>().toHaveProperty("create");
+    });
+
+    it('should return a promise with the created entity', () => {
+      expectTypeOf<DAO<Model, ModelEntity>['create']>().returns.toEqualTypeOf<Promise<ModelEntity>>();
+    });
+  });
+
+  describe('#update', () => {
+    it('should declare the method', () => {
+      expectTypeOf<DAO<Model, ModelEntity>>().toHaveProperty("update");
+    });
+
+    it('should return a promise with the updated entity', () => {
+      expectTypeOf<DAO<Model, ModelEntity>['update']>().returns.toEqualTypeOf<Promise<ModelEntity>>();
+    });
+  });
+
+  describe('#delete', () => {
+    it('should declare the method', () => {
+      expectTypeOf<DAO<Model, ModelEntity>>().toHaveProperty("delete");
+    });
+
+    it('should return a promise with the deleted entity', () => {
+      expectTypeOf<DAO<Model, ModelEntity>['delete']>().returns.toEqualTypeOf<Promise<ModelEntity>>();
+    });
+  });
+});

package/__tests__/entities/entity-registry.test.ts

@@ -0,0 +1,71 @@
+import { EntityRegistry, Entity, EntityNotRegistered } from "../../src/entities";
+import { UUIDValue } from "../../src/value-objects";
+
+type MockModel = {
+  id: string;
+};
+
+class IDValue extends UUIDValue {
+  attributeName = 'ID';
+}
+
+class MockEntity extends Entity<IDValue, MockModel> {
+  constructor(id: IDValue) {
+    super(id);
+  }
+
+  toPrimitives(): MockModel {
+    return {
+      id: this.id.value,
+    };
+  }
+
+  static fromPrimitives<MockModel>(model: MockModel): MockEntity {
+    return new MockEntity(
+      new IDValue(model["id"]),
+    );
+  }
+}
+
+describe("EntityRegistry", () => {
+  const type = "mock";
+
+  beforeEach(() => {
+    (EntityRegistry as any).registry.clear();
+  });
+
+  it("registers an entity constructor", () => {
+    EntityRegistry.register(type, MockEntity);
+
+    const resolved = EntityRegistry.resolve(type);
+
+    expect(resolved).toBe(MockEntity);
+  });
+
+  it("resolves a registered entity constructor", () => {
+    EntityRegistry.register(type, MockEntity);
+
+    const resolved = EntityRegistry.resolve(type);
+
+    expect(resolved?.fromPrimitives).toBeDefined();
+  });
+
+  it("returns null for unregistered types", () => {
+    const resolved = EntityRegistry.resolve("unknown");
+
+    expect(resolved).toBeNull();
+  });
+
+  it("creates an entity from a registered constructor", () => {
+    EntityRegistry.register(type, MockEntity);
+
+    const entity = EntityRegistry.create(type, { id: '123', name: 'Jorge' });
+
+    expect(entity).toBeInstanceOf(MockEntity);
+    expect(entity.id.value).toEqual('123');
+  });
+
+  it("throws EntityNotRegistered for unknown type", () => {
+    expect(() => EntityRegistry.create("unknown", { id: '123' })).toThrow(EntityNotRegistered);
+  });
+});

package/__tests__/entities/entity.test.ts

@@ -31,7 +31,7 @@ class IDValue extends UUIDValue {
   readonly attributeName = "ID";
 }
 
-class TestEntity extends Entity<Model> {
+class TestEntity extends Entity<IDValue, Model> {
   toPrimitives(): Model {
     return {
       id: this.id.toString(),
@@ -42,12 +42,12 @@ class TestEntity extends Entity<Model> {
 
 describe('Entity', () => {
   it('should have a "id" property of type string', () => {
-    expectTypeOf<Entity<Model>>().toHaveProperty("id");
-    expectTypeOf<Entity<Model>["id"]>().toEqualTypeOf<ValueObject>();
+    expectTypeOf<Entity<IDValue, Model>>().toHaveProperty("id");
+    expectTypeOf<Entity<IDValue, Model>["id"]>().toEqualTypeOf<IDValue>();
   });
 
   it('should have a private "domainEvents" property of type Array<DomainEvent>', () => {
-    expectTypeOf<Entity<Model>["domainEvents"]>().toEqualTypeOf<DomainEvent[]>();
+    expectTypeOf<Entity<IDValue, Model>["domainEvents"]>().toEqualTypeOf<DomainEvent[]>();
   });
 
   describe('#pullDomainEvents', () => {
@@ -107,8 +107,8 @@ describe('Entity', () => {
   });
 
   it('should declare a "toPrimitives" method', () => {
-    expectTypeOf<Entity<Model>>().toHaveProperty('toPrimitives');
-    expectTypeOf<Entity<Model>['toPrimitives']>().toBeFunction();
-    expectTypeOf<Entity<Model>['toPrimitives']>().returns.toEqualTypeOf<Model>();
+    expectTypeOf<Entity<IDValue, Model>>().toHaveProperty('toPrimitives');
+    expectTypeOf<Entity<IDValue, Model>['toPrimitives']>().toBeFunction();
+    expectTypeOf<Entity<IDValue, Model>['toPrimitives']>().returns.toEqualTypeOf<Model>();
   });
 });

package/__tests__/unit-of-work/unit-of-work.test.ts

@@ -0,0 +1,47 @@
+import { expectTypeOf } from "expect-type";
+
+import { UnitOfWork } from "../../src/unit-of-work";
+
+describe("UnitOfWork", () => {
+  describe('#begin', () => {
+    it('should declare the method', () => {
+      expectTypeOf<UnitOfWork>().toHaveProperty("begin");
+    });
+
+    it('should no require any arguments', () => {
+      expectTypeOf<UnitOfWork['begin']>().parameters.toEqualTypeOf<[]>();
+    });
+
+    it('should return a promise', () => {
+      expectTypeOf<UnitOfWork['begin']>().returns.toEqualTypeOf<Promise<void>>();
+    });
+  })
+
+  describe('#commit', () => {
+    it('should declare the method', () => {
+      expectTypeOf<UnitOfWork>().toHaveProperty("commit");
+    });
+
+    it('should no require any arguments', () => {
+      expectTypeOf<UnitOfWork['commit']>().parameters.toEqualTypeOf<[]>();
+    });
+
+    it('should return a promise', () => {
+      expectTypeOf<UnitOfWork['commit']>().returns.toEqualTypeOf<Promise<void>>();
+    });
+  })
+
+  describe('#rollback', () => {
+    it('should declare the method', () => {
+      expectTypeOf<UnitOfWork>().toHaveProperty("rollback");
+    });
+
+    it('should no require any arguments', () => {
+      expectTypeOf<UnitOfWork['rollback']>().parameters.toEqualTypeOf<[]>();
+    });
+
+    it('should return a promise', () => {
+      expectTypeOf<UnitOfWork['rollback']>().returns.toEqualTypeOf<Promise<void>>();
+    });
+  })
+});

package/jest.config.js

@@ -1,5 +1,5 @@
-  // jest.config.js
-  const { defaults: tsjPreset } = require("ts-jest/presets");
+// jest.config.js
+const { defaults: tsjPreset } = require("ts-jest/presets");
 const { transform } = require("typescript");
 
   module.exports = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@schorts/shared-kernel",
-  "version": "1.0.4",
+  "version": "1.1.0",
   "description": "A modular, type-safe foundation for building expressive, maintainable applications. This package provides core abstractions for domain modeling, HTTP integration, authentication, state management, and more — designed to be framework-agnostic and highly extensible.",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -13,6 +13,10 @@
       "import": "./dist/criteria/index.js",
       "types": "./dist/criteria/index.d.ts"
     },
+    "./dao": {
+      "import": "./dist/dao/index.js",
+      "types": "./dist/dao/index.d.ts"
+    },
     "./domain-events": {
       "import": "./dist/domain-events/index.js",
       "types": "./dist/domain-events/index.d.ts"
@@ -41,6 +45,10 @@
       "import": "./dist/models/index.js",
       "types": "./dist/models/index.d.ts"
     },
+    "./unit-of-work": {
+      "import": "./dist/unit-of-work/index.js",
+      "types": "./dist/unit-of-work/index.d.ts"
+    },
     "./utils": {
       "import": "./dist/utils/index.js",
       "types": "./dist/utils/index.d.ts"
@@ -81,6 +89,7 @@
     "shared-kernel",
     "auth",
     "jsonapi",
+    "dao",
     "kernel",
     "value-objects",
     "criteria",

package/src/auth/auth-provider.ts

@@ -1,7 +1,8 @@
 import { Entity } from "../entities";
 import { BaseModel } from "../models";
+import { ValueObject } from "../value-objects";
 
-export interface AuthProvider<UserEntity extends Entity<BaseModel>> {
+export interface AuthProvider<UserEntity extends Entity<ValueObject, BaseModel>> {
   authenticate(...args: any[]): Promise<void>;
   logout(): Promise<void>;
   isAuthenticated(): Promise<boolean>;

package/src/dao/dao.ts

@@ -0,0 +1,15 @@
+import { BaseModel } from "../models";
+import { Entity as BaseEntity } from "../entities";
+import { Criteria } from "../criteria";
+import { UnitOfWork } from "../unit-of-work";
+import { ValueObject } from "../value-objects";
+
+export interface DAO<Model extends BaseModel, Entity extends BaseEntity<ValueObject, Model>> {
+  getAll(): Promise<Entity[]>;
+  findByID(id: Entity["id"]["value"]): Promise<Entity | null>;
+  findOneBy(criteria: Criteria): Promise<Entity | null>;
+  search(criteria: Criteria): Promise<Entity[]>;
+  create(entity: Entity, uow?: UnitOfWork): Promise<Entity>;
+  update(entity: Entity, uow?: UnitOfWork): Promise<Entity>;
+  delete(entity: Entity, uow?: UnitOfWork): Promise<Entity>;
+}

package/src/dao/index.ts

@@ -0,0 +1 @@
+export type { DAO } from "./dao";

package/src/entities/entity-registry.ts

@@ -0,0 +1,30 @@
+import { BaseModel } from "../models";
+import { Entity } from "./entity";
+import { EntityNotRegistered } from "./exceptions";
+import { ValueObject } from "../value-objects";
+
+type EntityConstructor<Model extends BaseModel = BaseModel> = {
+  fromPrimitives(model: Model): Entity<ValueObject, Model>;
+};
+
+export class EntityRegistry {
+  private static registry = new Map<string, EntityConstructor>();
+
+  static register<Model extends BaseModel>(type: string, entity: EntityConstructor<Model>): void {
+    this.registry.set(type, entity);
+  }
+
+  static resolve<Model extends BaseModel>(type: string): EntityConstructor<Model> | null {
+    return (this.registry.get(type) || null) as EntityConstructor<Model> | null;
+  }  
+
+  static create<Model extends BaseModel>(type: string, model: Model): Entity<ValueObject, Model> {
+    const entity = this.resolve<Model>(type);
+
+    if (!entity) {
+      throw new EntityNotRegistered(`Entity type "${type}" not registered`);
+    }
+
+    return entity.fromPrimitives(model);
+  }
+}

package/src/entities/entity.ts

@@ -2,10 +2,10 @@ import { ValueObject } from "../value-objects";
 import { BaseModel } from "../models";
 import { DomainEvent } from "../domain-events";
 
-export abstract class Entity<Model extends BaseModel> {
+export abstract class Entity<IDValue extends ValueObject, Model extends BaseModel> {
   private domainEvents: Array<DomainEvent> = [];
 
-  constructor(readonly id: ValueObject) {}
+  constructor(readonly id: IDValue) {}
 
   pullDomainEvents(): Array<DomainEvent> {
     const domainEvents = [...this.domainEvents];
@@ -19,4 +19,7 @@ export abstract class Entity<Model extends BaseModel> {
   }
 
   abstract toPrimitives(): Model;
+  static fromPrimitives<Model extends BaseModel>(_model: Model) {
+    throw new Error("Method not implemented.");
+  }
 }

package/src/entities/exceptions/entity-not-registered.ts

@@ -0,0 +1 @@
+export class EntityNotRegistered extends Error {}

package/src/entities/exceptions/index.ts

@@ -0,0 +1 @@
+export { EntityNotRegistered } from "./entity-not-registered";

package/src/entities/index.ts

@@ -1 +1,3 @@
 export { Entity } from "./entity";
+export { EntityRegistry } from "./entity-registry";
+export { EntityNotRegistered } from "./exceptions";

package/src/unit-of-work/index.ts

@@ -0,0 +1 @@
+export type { UnitOfWork } from "./unit-of-work";

package/src/unit-of-work/unit-of-work.ts

@@ -0,0 +1,5 @@
+export interface UnitOfWork {
+  begin(): Promise<void>;
+  commit(): Promise<void>;
+  rollback(): Promise<void>;
+}