@schorts/shared-kernel 1.0.0

package/__tests__/criteria/order.test.ts

@@ -0,0 +1,14 @@
+import { expectTypeOf } from "expect-type";
+
+import { Order } from "../../src/criteria";
+
+type ExpectedOrder = {
+  field: string;
+  direction: "ASC" | "DESC" | "NONE";
+}
+
+describe('Order', () => {
+  it('should match the expected type', () => {
+    expectTypeOf<Order>().toEqualTypeOf<ExpectedOrder>();
+  });
+});

package/__tests__/domain-events/domain-event-primitives.test.ts

@@ -0,0 +1,34 @@
+import { expectTypeOf } from "expect-type";
+
+import { DomainEventPrimitives } from "../../src/domain-events";
+
+describe("DomainEventPrimitives", () => {
+  it('should have a "id" property of type string', () => {
+    expectTypeOf<DomainEventPrimitives>().toHaveProperty('id');
+    expectTypeOf<DomainEventPrimitives['id']>().toBeString();
+  });
+
+  it('should have a "occurred_at" property of type string', () => {
+    expectTypeOf<DomainEventPrimitives>().toHaveProperty('occurred_at');
+    expectTypeOf<DomainEventPrimitives['occurred_at']>().toBeString();
+  });
+
+  it('should have a "type" property of type string', () => {
+    expectTypeOf<DomainEventPrimitives>().toHaveProperty('type');
+    expectTypeOf<DomainEventPrimitives['type']>().toBeString();
+  });
+
+  it('should have a "version" property of type number', () => {
+    expectTypeOf<DomainEventPrimitives>().toHaveProperty('version');
+    expectTypeOf<DomainEventPrimitives['version']>().toBeNumber();
+  });
+
+  it('should have a "payload" property of type number', () => {
+    type PayloadSchema = {
+      name: string;
+    };
+
+    expectTypeOf<DomainEventPrimitives<PayloadSchema>>().toHaveProperty('payload');
+    expectTypeOf<DomainEventPrimitives<PayloadSchema>['payload']>().toEqualTypeOf<PayloadSchema>();
+  });
+});

package/__tests__/domain-events/domain-event.test.ts

@@ -0,0 +1,50 @@
+import { expectTypeOf } from "expect-type";
+
+import { DomainEvent, DomainEventPrimitives } from "../../src/domain-events";
+
+describe('DomainEvent', () => {
+  it('should have a "id" property of type string', () => {
+    expectTypeOf<DomainEvent>().toHaveProperty("id");
+    expectTypeOf<DomainEvent['id']>().toBeString();
+  });
+
+  it('should have a "occurredAt" property of type Date', () => {
+    expectTypeOf<DomainEvent>().toHaveProperty("occurredAt");
+    expectTypeOf<DomainEvent['occurredAt']>().toEqualTypeOf<Date>();
+  });
+
+  it('should have a "type" property of type string', () => {
+    expectTypeOf<DomainEvent>().toHaveProperty("type");
+    expectTypeOf<DomainEvent['type']>().toBeString();
+  });
+
+  it('should have a "version" property of type number', () => {
+    expectTypeOf<DomainEvent>().toHaveProperty("version");
+    expectTypeOf<DomainEvent['version']>().toBeNumber();
+  });
+
+  it('should have a "payload" property of customt type', () => {
+    type PayloadSchema = {
+      name: string;
+    };
+
+    expectTypeOf<DomainEvent<PayloadSchema>>().toHaveProperty("payload");
+    expectTypeOf<DomainEvent<PayloadSchema>['payload']>().toEqualTypeOf<PayloadSchema>();
+  });
+
+  it('should have a "getEventName" method that returns an string', () => {
+    expectTypeOf<DomainEvent>().toHaveProperty('getEventName');
+    expectTypeOf<DomainEvent['getEventName']>().toBeFunction();
+    expectTypeOf<DomainEvent['getEventName']>().returns.toBeString();
+  });
+
+  it('should declare a "toPrimitives" method', () => {
+    type PayloadSchema = {
+      name: string;
+    };
+
+    expectTypeOf<DomainEvent>().toHaveProperty('toPrimitives');
+    expectTypeOf<DomainEvent['toPrimitives']>().toBeFunction();
+    expectTypeOf<DomainEvent<PayloadSchema>['toPrimitives']>().returns.toEqualTypeOf<DomainEventPrimitives<PayloadSchema>>();
+  });
+});

package/__tests__/entities/entity.test.ts

@@ -0,0 +1,114 @@
+import { expectTypeOf } from "expect-type";
+
+import { Entity } from "../../src/entities";
+import { ValueObject, UUIDValue } from "../../src/value-objects";
+import { DomainEvent, DomainEventPrimitives } from "../../src/domain-events";
+
+type Model = {
+  id: string;
+  name: string;
+};
+
+class TestDomainEvent extends DomainEvent {
+  static eventName = "shared.v1.tests.test_domain";
+
+  toPrimitives(): DomainEventPrimitives<{}> {
+    return {
+      id: this.id,
+      occurred_at: this.occurredAt.toString(),
+      payload: this.payload,
+      type: this.type,
+      version: this.version,
+    };
+  }
+ 
+  getEventName() {
+    return TestDomainEvent.eventName;
+  }
+}
+
+class IDValue extends UUIDValue {
+  readonly attributeName = "ID";
+}
+
+class TestEntity extends Entity<Model> {
+  toPrimitives(): Model {
+    return {
+      id: this.id.toString(),
+      name: "test",
+    };
+  }
+}
+
+describe('Entity', () => {
+  it('should have a "id" property of type string', () => {
+    expectTypeOf<Entity<Model>>().toHaveProperty("id");
+    expectTypeOf<Entity<Model>["id"]>().toEqualTypeOf<ValueObject>();
+  });
+
+  it('should have a private "domainEvents" property of type Array<DomainEvent>', () => {
+    expectTypeOf<Entity<Model>["domainEvents"]>().toEqualTypeOf<DomainEvent[]>();
+  });
+
+  describe('#pullDomainEvents', () => {
+    let testEntity: TestEntity;
+
+    beforeEach(() => {
+      testEntity = new TestEntity(new IDValue(""))
+    });
+
+    it('should return an array of DomainEvent', () => {
+      const domainEvents = testEntity.pullDomainEvents();
+
+      expectTypeOf<typeof domainEvents>().toEqualTypeOf<DomainEvent[]>();
+    });
+
+    it('should return the record domain events', () => {
+      const testDomainEvent = new TestDomainEvent(
+        "",
+        new Date(),
+        "Test",
+        1,
+        {},
+      );
+
+      testEntity.recordDomainEvent(testDomainEvent);
+
+      const domainEvents = testEntity.pullDomainEvents();
+      const expectedDomainEvents = [testDomainEvent];
+
+      expect(domainEvents).toEqual(expectedDomainEvents);
+    });
+  });
+
+  describe('#recordDomainEvent', () => {
+    let testEntity: TestEntity;
+
+    beforeEach(() => {
+      testEntity = new TestEntity(new IDValue(""))
+    });
+
+    it('should record a domain events', () => {
+      const testDomainEvent = new TestDomainEvent(
+        "",
+        new Date(),
+        "Test",
+        1,
+        {},
+      );
+
+      testEntity.recordDomainEvent(testDomainEvent);
+
+      const domainEvents = testEntity.pullDomainEvents();
+      const expectedDomainEvents = [testDomainEvent];
+
+      expect(domainEvents).toEqual(expectedDomainEvents);
+    });
+  });
+
+  it('should declare a "toPrimitives" method', () => {
+    expectTypeOf<Entity<Model>>().toHaveProperty('toPrimitives');
+    expectTypeOf<Entity<Model>['toPrimitives']>().toBeFunction();
+    expectTypeOf<Entity<Model>['toPrimitives']>().returns.toEqualTypeOf<Model>();
+  });
+});

package/__tests__/formatters/pascal-camel-to-snake.test.ts

@@ -0,0 +1,19 @@
+import { PascalCamelToSnake } from "../../src/formatters";
+
+describe('PascalCamelToSnake', () => {
+  describe('.format', () => {
+    it('should return a pascal case to snake case', () => {
+      const resultID = PascalCamelToSnake.format("ID");
+      const resultExampleDAO = PascalCamelToSnake.format("ExampleDAO");
+
+      expect(resultID).toEqual("id");
+      expect(resultExampleDAO).toEqual("example_dao");
+    });
+
+    it('should return a camel case to snake case', () => {
+      const resultAlgoClass = PascalCamelToSnake.format("algoClass");
+
+      expect(resultAlgoClass).toEqual("algo_class");
+    });
+  });
+});

package/__tests__/http/fetch-http-provider.test.ts

@@ -0,0 +1,155 @@
+import { FetchHTTPProvider, HTTPException } from "../../src/http";
+
+const url = new URL("https://api.example.com/resource");
+
+function createMockResponse({
+  ok = true,
+  status = 200,
+  contentType = "application/json",
+  body = {},
+}: {
+  ok?: boolean;
+  status?: number;
+  contentType?: string;
+  body?: any;
+}): Promise<Response> {
+  return Promise.resolve({
+    ok,
+    status,
+    headers: {
+      get: (key: string) =>
+        key.toLowerCase() === "content-type" ? contentType : null,
+    },
+    json: async () => body,
+    text: async () => (typeof body === "string" ? body : JSON.stringify(body)),
+    blob: async () =>
+      new Blob([typeof body === "string" ? body : JSON.stringify(body)], {
+        type: contentType,
+      }),
+  } as unknown as Response);
+}
+
+describe("FetchHTTPProvider", () => {
+  let provider: FetchHTTPProvider;
+
+  beforeEach(() => {
+    provider = new FetchHTTPProvider();
+    global.fetch = jest.fn();
+  });
+
+  afterEach(() => {
+    jest.resetAllMocks();
+  });
+
+  it("parses JSON response", async () => {
+    const mockJson = { message: "success" };
+
+    (global.fetch as jest.Mock).mockImplementation(() =>
+      createMockResponse({ body: mockJson })
+    );
+
+    const result = await provider.get<typeof mockJson>(url);
+
+    expect(result).toEqual(mockJson);
+  });
+
+  it("parses text response", async () => {
+    const mockText = "plain text";
+
+    (global.fetch as jest.Mock).mockImplementation(() =>
+      createMockResponse({ contentType: "text/plain", body: mockText })
+    );
+
+    const result = await provider.get<string>(url);
+
+    expect(result).toEqual(mockText);
+  });
+
+  it("parses blob response", async () => {
+    const mockBinary = "image data";
+
+    (global.fetch as jest.Mock).mockImplementation(() =>
+      createMockResponse({ contentType: "image/png", body: mockBinary })
+    );
+
+    const result = await provider.get<Blob>(url);
+
+    expect(result).toBeInstanceOf(Blob);
+  });
+
+  it("returns undefined for 204 No Content", async () => {
+    (global.fetch as jest.Mock).mockImplementation(() =>
+      createMockResponse({ status: 204, body: undefined })
+    );
+
+    const result = await provider.get<undefined>(url);
+
+    expect(result).toBeUndefined();
+  });
+
+  it("throws HTTPException on failed JSON response", async () => {
+    const errorJson = { title: "Unauthorized", code: 401 };
+
+    (global.fetch as jest.Mock).mockImplementation(() =>
+      createMockResponse({ ok: false, status: 401, body: errorJson })
+    );
+
+    await expect(provider.get(url)).rejects.toThrow(HTTPException);
+  });
+
+  it("throws HTTPException on failed text response", async () => {
+    const errorText = "Forbidden";
+
+    (global.fetch as jest.Mock).mockImplementation(() =>
+      createMockResponse({
+        ok: false,
+        status: 403,
+        contentType: "text/plain",
+        body: errorText,
+      })
+    );
+
+    await expect(provider.get(url)).rejects.toThrow(HTTPException);
+  });
+
+  it("deduplicates ongoing requests", async () => {
+    const mockJson = { message: "deduplicated" };
+    
+    (global.fetch as jest.Mock).mockImplementation(() =>
+      createMockResponse({ body: mockJson })
+    );
+
+    const promise1 = provider.get<typeof mockJson>(url);
+    const promise2 = provider.get<typeof mockJson>(url);
+
+    expect(promise1).toStrictEqual(promise2);
+
+    const result = await promise1;
+
+    expect(result).toEqual(mockJson);
+    expect(global.fetch).toHaveBeenCalledTimes(1);
+  });
+
+  it("cleans up ongoingRequests after completion", async () => {
+    const mockJson = { message: "done" };
+
+    (global.fetch as jest.Mock).mockImplementation(() =>
+      createMockResponse({ body: mockJson })
+    );
+
+    await provider.get<typeof mockJson>(url);
+
+    const key = `GET:${url.href}:`;
+    const internalMap = (provider as any).ongoingRequests as Map<string, Promise<any>>;
+
+    expect(internalMap.has(key)).toBe(false);
+  });
+
+  it("throws if fetch returns undefined", async () => {
+    (global.fetch as jest.Mock).mockImplementation(() =>
+      Promise.resolve(undefined as any)
+    );    
+
+    await expect(provider.get(url)).rejects.toThrow(HTTPException);
+  });
+});

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

@@ -0,0 +1,55 @@
+import { expectTypeOf } from "expect-type";
+
+import { HTTPProvider } from "../../src/http";
+
+describe('HTTPProvider', () => {
+  describe('#get', () => {
+    it('should receive an URL', () => {
+      expectTypeOf<HTTPProvider["get"]>().parameters.toEqualTypeOf<[URL]>();
+    });
+
+    it('should return a Promise<ResponseType>', () => {
+      expectTypeOf<HTTPProvider["get"]>().returns.toEqualTypeOf<Promise<unknown>>();
+    });
+  });
+
+  describe('#post', () => {
+    it('should receive an URL and a body', () => {
+      expectTypeOf<HTTPProvider["post"]>().parameters.toEqualTypeOf<[URL, unknown]>();
+    });
+
+    it('should return a Promise<ResponseType>', () => {
+      expectTypeOf<HTTPProvider["post"]>().returns.toEqualTypeOf<Promise<unknown>>();
+    });
+  });
+
+  describe('#put', () => {
+    it('should receive an URL and a body', () => {
+      expectTypeOf<HTTPProvider["put"]>().parameters.toEqualTypeOf<[URL, unknown]>();
+    });
+
+    it('should return a Promise<ResponseType>', () => {
+      expectTypeOf<HTTPProvider["put"]>().returns.toEqualTypeOf<Promise<unknown>>();
+    });
+  });
+
+  describe('#patch', () => {
+    it('should receive an URL and a body', () => {
+      expectTypeOf<HTTPProvider["patch"]>().parameters.toEqualTypeOf<[URL, unknown]>();
+    });
+
+    it('should return a Promise<ResponseType>', () => {
+      expectTypeOf<HTTPProvider["patch"]>().returns.toEqualTypeOf<Promise<unknown>>();
+    });
+  });
+
+  describe('#delete', () => {
+    it('should receive an URL', () => {
+      expectTypeOf<HTTPProvider["delete"]>().parameters.toEqualTypeOf<[URL]>();
+    });
+
+    it('should return a Promise<ResponseType>', () => {
+      expectTypeOf<HTTPProvider["delete"]>().returns.toEqualTypeOf<Promise<unknown>>();
+    });
+  });
+});

package/__tests__/json-api/json-api-connector.test.ts

@@ -0,0 +1,78 @@
+import { JSONAPIConnector } from "../../src/json-api";
+import { Criteria } from "../../src/criteria";
+import type { HTTPProvider } from "../../src/http";
+
+describe("JSONAPIConnector", () => {
+  const base = new URL("https://api.example.com/users");
+  let http: jest.Mocked<HTTPProvider>;
+  let connector: JSONAPIConnector;
+
+  beforeEach(() => {
+    http = {
+      get: jest.fn(),
+      post: jest.fn(),
+      patch: jest.fn(),
+      put: jest.fn(),
+      delete: jest.fn(),
+    };
+    connector = new JSONAPIConnector(http);
+  });
+
+  it("calls findOne with correct URL and criteria", async () => {
+    const criteria = new Criteria().where("status", "EQUAL", "active");
+    const include = ["roles"];
+
+    await connector.findOne(base, criteria, include);
+
+    expect(http.get).toHaveBeenCalledWith(expect.any(URL));
+
+    const calledUrl = http.get.mock.calls[0][0];
+    
+    expect(calledUrl.searchParams.get("filter[status]")).toBe("active");
+    expect(calledUrl.href).toContain("include=roles");
+  });
+
+  it("calls findMany with sorting and pagination", async () => {
+    const criteria = new Criteria()
+      .orderBy("createdAt", "DESC")
+      .limitResults(10)
+      .offsetResults(20);
+
+    await connector.findMany(base, criteria);
+
+    const calledUrl = http.get.mock.calls[0][0];
+
+    expect(calledUrl.href).toContain("sort=-createdAt");
+    expect(calledUrl.searchParams.get("page[limit]")).toBe("10");
+    expect(calledUrl.searchParams.get("page[offset]")).toBe("20");
+  });
+
+  it("calls create with correct payload", async () => {
+    const payload = {
+      type: "users",
+      attributes: { name: "Jorge", email: "jorge@example.com" },
+    };
+
+    await connector.create(base, payload);
+
+    expect(http.post).toHaveBeenCalledWith(base, { data: payload });
+  });
+
+  it("calls update with correct payload", async () => {
+    const payload = {
+      id: "123",
+      type: "users",
+      attributes: { name: "Jorge Updated" },
+    };
+
+    await connector.update(base, payload);
+
+    expect(http.patch).toHaveBeenCalledWith(base, { data: payload });
+  });
+
+  it("calls delete with correct URL", async () => {
+    await connector.delete(base);
+
+    expect(http.delete).toHaveBeenCalledWith(base);
+  });
+});

package/__tests__/json-api/json-api-list.test.ts

@@ -0,0 +1,24 @@
+import { expectTypeOf } from "expect-type";
+
+import { JSONAPIList } from "../../src/json-api";
+import { BaseModel } from "../../src/models";
+
+type ExpectedJSONAPIList<EntityAttributes> = {
+  data: Array<{
+    id: string;
+    type: string;
+    attributes: Omit<EntityAttributes, "id">;
+  }>;
+  included?: Array<{
+    id: string;
+    type: string;
+    attributes: Record<string, any>;
+  }>;
+  meta?: Record<string, any>;
+};
+
+describe('JSONAPIList', () => {
+  it('should match the expected schema', () => {
+    expectTypeOf<JSONAPIList<BaseModel>>().toEqualTypeOf<ExpectedJSONAPIList<BaseModel>>()
+  });
+});

package/__tests__/json-api/json-api-single.test.ts

@@ -0,0 +1,24 @@
+import { expectTypeOf } from "expect-type";
+
+import { JSONAPISingle } from "../../src/json-api";
+import { BaseModel } from "../../src/models";
+
+type ExpectedJSONAPISingle<EntityAttributes> = {
+  data: {
+    id: string;
+    type: string;
+    attributes: Omit<EntityAttributes, "id">;
+  };
+  included?: Array<{
+    id: string;
+    type: string;
+    attributes: Omit<Record<string, any>, "id">;
+  }>;
+  meta?: Record<string, any>;
+};
+
+describe('JSONAPISingle', () => {
+  it('should match the expected schema', () => {
+    expectTypeOf<JSONAPISingle<BaseModel>>().toEqualTypeOf<ExpectedJSONAPISingle<BaseModel>>()
+  });
+});

package/__tests__/json-api/url-criteria-builder.test.ts

@@ -0,0 +1,74 @@
+import { URLCriteriaBuilder } from "../../src/json-api";
+import { Criteria } from "../../src/criteria";
+
+const base = new URL("https://api.example.com/resources");
+
+describe("URLCriteriaBuilder", () => {
+  it("encodes EQUAL filters as filter[field]=value", () => {
+    const criteria = new Criteria().where("status", "EQUAL", "active");
+    const url = new URLCriteriaBuilder(base, criteria).build();
+
+    expect(url.searchParams.get("filter[status]")).toBe("active");
+  });
+
+  it("encodes IN filters as comma-separated values", () => {
+    const criteria = new Criteria().where("role", "IN", ["admin", "editor"]);
+    const url = new URLCriteriaBuilder(base, criteria).build();
+
+    expect(url.searchParams.get("filter[role]")).toBe("admin,editor");
+  });
+
+  it("encodes other operators as filter[field][operator]=value", () => {
+    const criteria = new Criteria().where("createdAt", "GREATER_THAN", "2023-01-01");
+    const url = new URLCriteriaBuilder(base, criteria).build();
+
+    expect(url.searchParams.get("filter[createdAt][GREATER_THAN]")).toBe("2023-01-01");
+  });
+
+  it("supports nested filters using dot notation", () => {
+    const criteria = new Criteria().where("roles.name", "EQUAL", "admin");
+    const url = new URLCriteriaBuilder(base, criteria).build();
+
+    expect(url.searchParams.get("filter[roles.name]")).toBe("admin");
+  });
+
+  it("encodes sorting correctly", () => {
+    const criteria = new Criteria()
+      .orderBy("createdAt", "DESC")
+      .orderBy("name", "ASC");
+    const url = new URLCriteriaBuilder(base, criteria).build();
+
+    expect(url.searchParams.get("sort")).toBe("-createdAt,name");
+  });
+
+  it("encodes pagination correctly", () => {
+    const criteria = new Criteria().limitResults(20).offsetResults(40);
+    const url = new URLCriteriaBuilder(base, criteria).build();
+
+    expect(url.searchParams.get("page[limit]")).toBe("20");
+    expect(url.searchParams.get("page[offset]")).toBe("40");
+  });
+
+  it("adds include parameters", () => {
+    const url = new URLCriteriaBuilder(base, undefined, ["roles", "permissions"]).build();
+
+    expect(url.searchParams.getAll("include")).toEqual(["roles", "permissions"]);
+  });
+
+  it("builds full query with filters, sort, pagination, and includes", () => {
+    const criteria = new Criteria()
+      .where("status", "EQUAL", "active")
+      .where("roles.name", "EQUAL", "admin")
+      .orderBy("createdAt", "DESC")
+      .limitResults(10)
+      .offsetResults(30);
+    const url = new URLCriteriaBuilder(base, criteria, ["roles"]).build();
+
+    expect(url.searchParams.get("filter[status]")).toBe("active");
+    expect(url.searchParams.get("filter[roles.name]")).toBe("admin");
+    expect(url.searchParams.get("sort")).toBe("-createdAt");
+    expect(url.searchParams.get("page[limit]")).toBe("10");
+    expect(url.searchParams.get("page[offset]")).toBe("30");
+    expect(url.searchParams.getAll("include")).toEqual(["roles"]);
+  });
+});

package/__tests__/messages/message.test.ts

@@ -0,0 +1,16 @@
+import { expectTypeOf } from "expect-type";
+
+import { Message } from "../../src/messages";
+
+type MessagePrimitives = {
+  id: string;
+};
+
+describe("Message", () => {
+  it('should declare a "toPrimitives" method', () => {
+    expectTypeOf<Message>().toHaveProperty('toPrimitives');
+    expectTypeOf<Message['toPrimitives']>().toBeFunction();
+    expectTypeOf<Message<MessagePrimitives>['toPrimitives']>().returns.toEqualTypeOf<MessagePrimitives>();
+  });
+});
+

package/__tests__/models/base-model.test.ts

@@ -0,0 +1,10 @@
+import { expectTypeOf } from "expect-type";
+
+import { BaseModel } from "../../src/models";
+
+describe("BaseModel", () => {
+  it('should have a "id" property of type string or number', () => {
+    expectTypeOf<BaseModel>().toHaveProperty("id");
+    expectTypeOf<BaseModel['id']>().toEqualTypeOf<string | number>();
+  });
+});