@schorts/shared-kernel 1.0.0

package/__tests__/value-objects/uuid-value.test.ts

@@ -0,0 +1,67 @@
+import { expectTypeOf } from "expect-type";
+
+import { ValueObject, UUIDValue } from "../../src/value-objects";
+
+class TestUUIDValue extends UUIDValue {
+  readonly attributeName = "test";
+}
+
+describe("UUIDValue", () => {
+  it('should implement "ValueObject" interface', () => {
+    expectTypeOf<UUIDValue>().toExtend<ValueObject>();
+  });
+
+  it('should have a "valueType" with "UUID" as value', () => {
+    const testUUIDvalue = new TestUUIDValue();
+
+    expect(testUUIDvalue.valueType).toEqual("UUID");
+  });
+
+  it('should have a "value" property of type string | undefined', () => {
+    expectTypeOf<UUIDValue["value"]>().toEqualTypeOf<string | undefined>();
+  });
+
+  it('should have a "optional" property of type boolean', () => {
+    expectTypeOf<UUIDValue["optional"]>().toBeBoolean();
+  });
+
+  it('should define the "equals" method', () => {
+    expectTypeOf<UUIDValue["equals"]>().toEqualTypeOf<(valueObject: unknown) => boolean>();
+  });
+
+  describe('when "value" is present', () => {
+    describe('when "value" is valid', () => {
+      it('should have a getter "isValid" that returns true', () => {
+        const testUUIDvalue = new TestUUIDValue("87a00bc1-c586-4d23-bfc7-dd637628777c");
+
+        expect(testUUIDvalue.isValid).toBeTruthy();
+      });
+    });
+
+    describe('when "value" is not valid', () => {
+      it('should have a getter "isValid" that returns false', () => {
+        const testUUIDvalue = new TestUUIDValue("dummy-uuid-12346-5734");
+
+        expect(testUUIDvalue.isValid).toBeFalsy();
+      });
+    });
+  });
+
+  describe('when "value" is not present', () => {
+    describe('when "value" is optional', () => {
+      it('should have a getter "isValid" that returns true', () => {
+        const testUUIDvalue = new TestUUIDValue(undefined, true);
+
+        expect(testUUIDvalue.isValid).toBeTruthy();
+      });
+    });
+
+    describe('when "value" is not optional', () => {
+      it('should have a getter "isValid" that runs the validations normally and returns false', () => {
+        const testUUIDvalue = new TestUUIDValue(undefined, false);
+
+        expect(testUUIDvalue.isValid).toBeFalsy();
+      });
+    });
+  });
+});

package/__tests__/value-objects/value-object.test.ts

@@ -0,0 +1,25 @@
+import { expectTypeOf } from "expect-type";
+
+import { ValueObject } from "../../src/value-objects";
+
+describe("ValueObject", () => {
+  it('should have a "value" property of type unknown', () => {
+    expectTypeOf<ValueObject>().toHaveProperty("value");
+    expectTypeOf<ValueObject['value']>().toBeUnknown();
+  });
+
+  it('should have a "isValid" property of type boolean', () => {
+    expectTypeOf<ValueObject>().toHaveProperty("isValid");
+    expectTypeOf<ValueObject['isValid']>().toBeBoolean();
+  });
+
+  it('should have a "valueType" property of type string', () => {
+    expectTypeOf<ValueObject>().toHaveProperty("valueType");
+    expectTypeOf<ValueObject['valueType']>().toBeString();
+  });
+
+  it('should have a "attributeName" property of type string', () => {
+    expectTypeOf<ValueObject>().toHaveProperty("attributeName");
+    expectTypeOf<ValueObject['attributeName']>().toBeString();
+  });
+});

package/jest.config.js

@@ -0,0 +1,25 @@
+  // jest.config.js
+  const { defaults: tsjPreset } = require("ts-jest/presets");
+const { transform } = require("typescript");
+
+  module.exports = {
+    preset: "ts-jest/presets/default-esm",
+    testEnvironment: "node",
+    extensionsToTreatAsEsm: [".ts"],
+    transform: {
+      '^.+\\.(ts|tsx)$': ['ts-jest', { useESM: true }],
+    },
+    moduleFileExtensions: ["ts", "js", "json", "node"],
+    testMatch: ["**/__tests__/**/*.ts", "**/?(*.)+(spec|test).ts"],
+    collectCoverageFrom: [
+      "src/**/*.ts",
+      "!src/**/*.d.ts",
+      "!src/index.ts",
+    ],
+    coverageDirectory: "coverage",
+    coverageReporters: ["text", "lcov", "html"],
+    moduleNameMapper: {
+      "^@schorts/shared-kernel/(.*)$": "<rootDir>/src/$1",
+    },
+  };
+  

package/package.json

@@ -0,0 +1,289 @@
+{
+  "name": "@schorts/shared-kernel",
+  "version": "1.0.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",
+  "exports": {
+    "./auth": {
+      "import": "./dist/auth/index.js",
+      "types": "./dist/auth/index.d.ts"
+    },
+    "./criteria": {
+      "import": "./dist/criteria/index.js",
+      "types": "./dist/criteria/index.d.ts"
+    },
+    "./domain-events": {
+      "import": "./dist/domain-events/index.js",
+      "types": "./dist/domain-events/index.d.ts"
+    },
+    "./entities": {
+      "import": "./dist/entities/index.js",
+      "types": "./dist/entities/index.d.ts"
+    },
+    "./formatters": {
+      "import": "./dist/formatters/index.js",
+      "types": "./dist/formatters/index.d.ts"
+    },
+    "./http": {
+      "import": "./dist/http/index.js",
+      "types": "./dist/http/index.d.ts"
+    },
+    "./json-api": {
+      "import": "./dist/json-api/index.js",
+      "types": "./dist/json-api/index.d.ts"
+    },
+    "./messages": {
+      "import": "./dist/messages/index.js",
+      "types": "./dist/messages/index.d.ts"
+    },
+    "./models": {
+      "import": "./dist/models/index.js",
+      "types": "./dist/models/index.d.ts"
+    },
+    "./utils": {
+      "import": "./dist/utils/index.js",
+      "types": "./dist/utils/index.d.ts"
+    },
+    "./state-manager": {
+      "import": "./dist/state-manager/index.js",
+      "types": "./dist/state-manager/index.d.ts"
+    },
+    "./value-objects": {
+      "import": "./dist/value-objects/index.js",
+      "types": "./dist/value-objects/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "test:ci": "jest --ci --coverage --watchAll=false"
+  },
+  "author": "Jorge Castillo (https://github.com/schorts)",
+  "license": "LGPL-3.0-or-later",
+  "devDependencies": {
+    "@jest/globals": "^30.1.2",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^24.5.2",
+    "expect-type": "^1.2.2",
+    "jest": "^30.1.3",
+    "jest-html-reporter": "^4.3.0",
+    "ts-jest": "^29.4.4",
+    "typescript": "^5.9.2"
+  },
+  "dependencies": {
+    "ansi-escapes": "^4.3.2",
+    "ansi-regex": "^6.2.2",
+    "ansi-styles": "^4.3.0",
+    "anymatch": "^3.1.3",
+    "argparse": "^1.0.10",
+    "babel-jest": "^30.1.2",
+    "babel-plugin-istanbul": "^7.0.1",
+    "babel-plugin-jest-hoist": "^30.0.1",
+    "babel-preset-current-node-syntax": "^1.2.0",
+    "babel-preset-jest": "^30.0.1",
+    "balanced-match": "^1.0.2",
+    "baseline-browser-mapping": "^2.8.6",
+    "brace-expansion": "^2.0.2",
+    "braces": "^3.0.3",
+    "browserslist": "^4.26.2",
+    "bs-logger": "^0.2.6",
+    "bser": "^2.1.1",
+    "buffer-from": "^1.1.2",
+    "callsites": "^3.1.0",
+    "camelcase": "^5.3.1",
+    "caniuse-lite": "^1.0.30001743",
+    "chalk": "^4.1.2",
+    "char-regex": "^1.0.2",
+    "ci-info": "^4.3.0",
+    "cjs-module-lexer": "^2.1.0",
+    "cliui": "^8.0.1",
+    "co": "^4.6.0",
+    "collect-v8-coverage": "^1.0.2",
+    "color-convert": "^2.0.1",
+    "color-name": "^1.1.4",
+    "concat-map": "^0.0.1",
+    "convert-source-map": "^2.0.0",
+    "cross-spawn": "^7.0.6",
+    "dateformat": "^3.0.2",
+    "debug": "^4.4.3",
+    "dedent": "^1.7.0",
+    "deepmerge": "^4.3.1",
+    "detect-newline": "^3.1.0",
+    "eastasianwidth": "^0.2.0",
+    "electron-to-chromium": "^1.5.223",
+    "emittery": "^0.13.1",
+    "emoji-regex": "^9.2.2",
+    "error-ex": "^1.3.4",
+    "escalade": "^3.2.0",
+    "escape-string-regexp": "^2.0.0",
+    "esprima": "^4.0.1",
+    "execa": "^5.1.1",
+    "exit-x": "^0.2.2",
+    "expect": "^30.1.2",
+    "fast-json-stable-stringify": "^2.1.0",
+    "fb-watchman": "^2.0.2",
+    "fill-range": "^7.1.1",
+    "find-up": "^4.1.0",
+    "foreground-child": "^3.3.1",
+    "fs.realpath": "^1.0.0",
+    "gensync": "^1.0.0-beta.2",
+    "get-caller-file": "^2.0.5",
+    "get-package-type": "^0.1.0",
+    "get-stream": "^6.0.1",
+    "glob": "^10.4.5",
+    "graceful-fs": "^4.2.11",
+    "handlebars": "^4.7.8",
+    "has-flag": "^4.0.0",
+    "html-escaper": "^2.0.2",
+    "human-signals": "^2.1.0",
+    "import-local": "^3.2.0",
+    "imurmurhash": "^0.1.4",
+    "inflight": "^1.0.6",
+    "inherits": "^2.0.4",
+    "is-arrayish": "^0.2.1",
+    "is-fullwidth-code-point": "^3.0.0",
+    "is-generator-fn": "^2.1.0",
+    "is-number": "^7.0.0",
+    "is-stream": "^2.0.1",
+    "isexe": "^2.0.0",
+    "istanbul-lib-coverage": "^3.2.2",
+    "istanbul-lib-instrument": "^6.0.3",
+    "istanbul-lib-report": "^3.0.1",
+    "istanbul-lib-source-maps": "^5.0.6",
+    "istanbul-reports": "^3.2.0",
+    "jackspeak": "^3.4.3",
+    "jest-changed-files": "^30.0.5",
+    "jest-circus": "^30.1.3",
+    "jest-cli": "^30.1.3",
+    "jest-config": "^30.1.3",
+    "jest-diff": "^30.1.2",
+    "jest-docblock": "^30.0.1",
+    "jest-each": "^30.1.0",
+    "jest-environment-node": "^30.1.2",
+    "jest-haste-map": "^30.1.0",
+    "jest-leak-detector": "^30.1.0",
+    "jest-matcher-utils": "^30.1.2",
+    "jest-message-util": "^30.1.0",
+    "jest-mock": "^30.0.5",
+    "jest-pnp-resolver": "^1.2.3",
+    "jest-regex-util": "^30.0.1",
+    "jest-resolve": "^30.1.3",
+    "jest-resolve-dependencies": "^30.1.3",
+    "jest-runner": "^30.1.3",
+    "jest-runtime": "^30.1.3",
+    "jest-snapshot": "^30.1.2",
+    "jest-util": "^30.0.5",
+    "jest-validate": "^30.1.0",
+    "jest-watcher": "^30.1.3",
+    "jest-worker": "^30.1.0",
+    "js-tokens": "^4.0.0",
+    "js-yaml": "^3.14.1",
+    "jsesc": "^3.1.0",
+    "json-parse-even-better-errors": "^2.3.1",
+    "json5": "^2.2.3",
+    "leven": "^3.1.0",
+    "lines-and-columns": "^1.2.4",
+    "locate-path": "^5.0.0",
+    "lodash.memoize": "^4.1.2",
+    "lru-cache": "^5.1.1",
+    "make-dir": "^4.0.0",
+    "make-error": "^1.3.6",
+    "makeerror": "^1.0.12",
+    "merge-stream": "^2.0.0",
+    "micromatch": "^4.0.8",
+    "mimic-fn": "^2.1.0",
+    "minimatch": "^9.0.5",
+    "minimist": "^1.2.8",
+    "minipass": "^7.1.2",
+    "mkdirp": "^1.0.4",
+    "ms": "^2.1.3",
+    "napi-postinstall": "^0.3.3",
+    "natural-compare": "^1.4.0",
+    "neo-async": "^2.6.2",
+    "node-int64": "^0.4.0",
+    "node-releases": "^2.0.21",
+    "normalize-path": "^3.0.0",
+    "npm-run-path": "^4.0.1",
+    "once": "^1.4.0",
+    "onetime": "^5.1.2",
+    "p-limit": "^3.1.0",
+    "p-locate": "^4.1.0",
+    "p-try": "^2.2.0",
+    "package-json-from-dist": "^1.0.1",
+    "parse-json": "^5.2.0",
+    "path-exists": "^4.0.0",
+    "path-is-absolute": "^1.0.1",
+    "path-key": "^3.1.1",
+    "path-scurry": "^1.11.1",
+    "picocolors": "^1.1.1",
+    "picomatch": "^2.3.1",
+    "pirates": "^4.0.7",
+    "pkg-dir": "^4.2.0",
+    "pretty-format": "^30.0.5",
+    "pure-rand": "^7.0.1",
+    "react-is": "^18.3.1",
+    "require-directory": "^2.1.1",
+    "resolve-cwd": "^3.0.0",
+    "resolve-from": "^5.0.0",
+    "semver": "^6.3.1",
+    "shebang-command": "^2.0.0",
+    "shebang-regex": "^3.0.0",
+    "signal-exit": "^4.1.0",
+    "slash": "^3.0.0",
+    "source-map": "^0.6.1",
+    "source-map-support": "^0.5.13",
+    "sprintf-js": "^1.0.3",
+    "stack-utils": "^2.0.6",
+    "string-length": "^4.0.2",
+    "string-width": "^5.1.2",
+    "string-width-cjs": "^4.2.3",
+    "strip-ansi": "^7.1.2",
+    "strip-ansi-cjs": "^6.0.1",
+    "strip-bom": "^4.0.0",
+    "strip-final-newline": "^2.0.0",
+    "strip-json-comments": "^3.1.1",
+    "supports-color": "^7.2.0",
+    "synckit": "^0.11.11",
+    "test-exclude": "^6.0.0",
+    "tmpl": "^1.0.5",
+    "to-regex-range": "^5.0.1",
+    "type-detect": "^4.0.8",
+    "type-fest": "^0.21.3",
+    "uglify-js": "^3.19.3",
+    "undici-types": "^7.12.0",
+    "unrs-resolver": "^1.11.1",
+    "update-browserslist-db": "^1.1.3",
+    "v8-to-istanbul": "^9.3.0",
+    "walker": "^1.0.8",
+    "which": "^2.0.2",
+    "wordwrap": "^1.0.0",
+    "wrap-ansi": "^8.1.0",
+    "wrap-ansi-cjs": "^7.0.0",
+    "wrappy": "^1.0.2",
+    "write-file-atomic": "^5.0.1",
+    "xmlbuilder": "^15.0.0",
+    "y18n": "^5.0.8",
+    "yallist": "^3.1.1",
+    "yargs": "^17.7.2",
+    "yargs-parser": "^21.1.1",
+    "yocto-queue": "^0.1.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/schorts/shared-kernel.git"
+  },
+  "keywords": [
+    "shared-kernel",
+    "auth",
+    "jsonapi",
+    "kernel",
+    "value-objects"
+  ],
+  "bugs": {
+    "url": "https://github.com/schorts/shared-kernel/issues"
+  },
+  "homepage": "https://github.com/schorts/shared-kernel#readme"
+}

package/src/auth/auth-provider.ts

@@ -0,0 +1,10 @@
+import { Entity } from "../entities";
+import { BaseModel } from "../models";
+
+export interface AuthProvider<UserEntity extends Entity<BaseModel>> {
+  authenticate(...args: any[]): Promise<void>;
+  logout(): Promise<void>;
+  isAuthenticated(): Promise<boolean>;
+  currentUser(): Promise<UserEntity | null>;
+  onAuthChange(callback: (user: UserEntity | null) => void): () => void;
+}

package/src/auth/exceptions/index.ts

@@ -0,0 +1 @@
+export { NotAuthenticated } from "./not-authenticated";

package/src/auth/exceptions/not-authenticated.ts

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

package/src/auth/index.ts

@@ -0,0 +1,3 @@
+export type { AuthProvider } from "./auth-provider";
+export { RequireAuth } from "./require-auth.decorator";
+export { NotAuthenticated } from "./exceptions";

package/src/auth/require-auth.decorator.ts

@@ -0,0 +1,41 @@
+import { AuthProvider } from "./auth-provider";
+import { NotAuthenticated } from './exceptions';
+
+export function RequireAuth(onFail?: () => any) {
+  function wrapper<T extends { authProvider?: AuthProvider<any> }, A extends any[], R>(
+    originalMethod: (this: T, ...args: A) => Promise<R>
+  ): (this: T, ...args: A) => Promise<R> {
+    return async function (this: T, ...args: A): Promise<R> {
+      if (!this.authProvider) {
+        throw new Error("authProvider: AuthProvider is required on this instance");
+      }
+
+      const isAuthenticated = await this.authProvider.isAuthenticated();
+
+      if (!isAuthenticated) {
+        if (onFail) {
+          return onFail();
+        } else {
+          throw new NotAuthenticated();
+        }
+      }
+
+      return await originalMethod.apply(this, args);
+    };
+  }
+
+  return function (...args: any[]) {
+    if (args.length === 3 && typeof args[2] === 'object') {
+      const descriptor = args[2] as PropertyDescriptor;
+      descriptor.value = wrapper(descriptor.value);
+      return descriptor;
+    }
+
+    if (args.length === 2 && typeof args[1] === 'object' && 'kind' in args[1]) {
+      const [originalMethod] = args;
+      return wrapper(originalMethod);
+    }
+
+    throw new Error("RequireAuth decorator used incorrectly");
+  };
+}

package/src/criteria/criteria.ts

@@ -0,0 +1,51 @@
+import { FilterCriterion } from "./filter-criterion";
+import { Order } from "./order";
+import { Operator } from "./operator";
+import { Direction } from "./direction";
+import { OffsetNotValid, LimitNotValid } from "./exceptions";
+
+export class Criteria {
+  readonly filters: Record<string, FilterCriterion> = {};
+  readonly orders: Array<Order> = [];
+  limit?: number;
+  offset?: number;
+
+  where(
+    field: string,
+    operator: Operator,
+    value: any,
+  ): Criteria {
+    this.filters[field] = { value, operator };
+
+    return this;
+  }
+
+  orderBy(
+    field: string,
+    direction: Direction = "ASC",
+  ): Criteria {
+    this.orders.push({ field, direction });
+
+    return this;
+  }
+
+  limitResults(limit: number): Criteria {
+    if (limit < 1) {
+      throw new LimitNotValid();
+    }
+
+    this.limit = limit;
+
+    return this;
+  }
+
+  offsetResults(offset: number): Criteria {
+    if (offset < 1) {
+      throw new OffsetNotValid();
+    }
+
+    this.offset = offset;
+
+    return this;
+  }
+}

package/src/criteria/direction.ts

@@ -0,0 +1 @@
+export type Direction = "ASC" | "DESC";

package/src/criteria/exceptions/index.ts

@@ -0,0 +1,2 @@
+export { OffsetNotValid } from "./offset-not-valid";
+export { LimitNotValid } from "./limit-not-valid";

package/src/criteria/exceptions/limit-not-valid.ts

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

package/src/criteria/exceptions/offset-not-valid.ts

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

package/src/criteria/filter-criterion.ts

@@ -0,0 +1,6 @@
+import { Operator } from "./operator";
+
+export type FilterCriterion = {
+  value: any;
+  operator: Operator;
+}

package/src/criteria/index.ts

@@ -0,0 +1,7 @@
+export type { Operator } from "./operator";
+export type { Order } from "./order";
+export type { FilterCriterion } from "./filter-criterion";
+export type { Direction } from "./direction";
+
+export { Criteria } from "./criteria";
+export { OffsetNotValid, LimitNotValid } from "./exceptions";

package/src/criteria/operator.ts

@@ -0,0 +1,12 @@
+export type Operator =
+  | "EQUAL"
+  | "GREATER_THAN"
+  | "LESS_THAN"
+  | "GREATER_THAN_OR_EQUAL"
+  | "LESS_THAN_OR_EQUAL"
+  | "NOT_EQUAL"
+  | "IN"
+  | "NOT_IN"
+  | "LIKE"
+  | "BETWEEN"
+  | "GEO_RADIUS";

package/src/criteria/order.ts

@@ -0,0 +1,4 @@
+export type Order = {
+  field: string;
+  direction: "ASC" | "DESC" | "NONE";
+}

package/src/domain-events/domain-event-primitives.ts

@@ -0,0 +1,7 @@
+export type DomainEventPrimitives<PayloadSchema = {}> = {
+  id: string;
+  occurred_at: string;
+  type: string;
+  version: number;
+  payload: PayloadSchema;
+};

package/src/domain-events/domain-event.ts

@@ -0,0 +1,15 @@
+import { Message } from "../messages";
+import { DomainEventPrimitives } from "./domain-event-primitives";
+
+export abstract class DomainEvent<PayloadSchema = {}> implements Message<DomainEventPrimitives<PayloadSchema>> {  
+  constructor(
+    readonly id: string,
+    readonly occurredAt: Date,
+    readonly type: string,
+    readonly version: number,
+    readonly payload: PayloadSchema,
+  ) {}
+
+  abstract getEventName(): string;
+  abstract toPrimitives(): DomainEventPrimitives<PayloadSchema>;
+}

package/src/domain-events/index.ts

@@ -0,0 +1,2 @@
+export { DomainEvent } from "./domain-event";
+export type { DomainEventPrimitives } from "./domain-event-primitives";

package/src/entities/entity.ts

@@ -0,0 +1,22 @@
+import { ValueObject } from "../value-objects";
+import { BaseModel } from "../models";
+import { DomainEvent } from "../domain-events";
+
+export abstract class Entity<Model extends BaseModel> {
+  private domainEvents: Array<DomainEvent> = [];
+
+  constructor(readonly id: ValueObject) {}
+
+  pullDomainEvents(): Array<DomainEvent> {
+    const domainEvents = [...this.domainEvents];
+    this.domainEvents = [];
+
+    return domainEvents;
+  }
+
+  recordDomainEvent(domainEvent: DomainEvent): void {
+    this.domainEvents.push(domainEvent);
+  }
+
+  abstract toPrimitives(): Model;
+}

package/src/entities/index.ts

@@ -0,0 +1 @@
+export { Entity } from "./entity";

package/src/formatters/index.ts

@@ -0,0 +1 @@
+export { PascalCamelToSnake } from "./pascal-camel-to-snake";

package/src/formatters/pascal-camel-to-snake.ts

@@ -0,0 +1,8 @@
+export class PascalCamelToSnake {
+  static format(text: string) {
+    return text
+      .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+      .replace(/([A-Z]+)([A-Z][a-z])/g, '$1_$2')
+      .toLowerCase();
+  }
+}

package/src/http/exceptions/http-exception.ts

@@ -0,0 +1,8 @@
+export class HTTPException extends Error {
+  constructor(
+    readonly message: string,
+    readonly statusCode: number,
+  ) {
+    super()
+  }
+}

package/src/http/exceptions/index.ts

@@ -0,0 +1 @@
+export { HTTPException } from "./http-exception";