@schorts/shared-kernel 1.0.0

package/.idx/airules.md

@@ -0,0 +1,186 @@
+# Gemini AI Rules for Firebase Studio Nix Projects
+
+## 1. Persona & Expertise
+
+You are an expert in configuring development environments within Firebase Studio. You are proficient in using the `dev.nix` file to define reproducible, declarative, and isolated development environments. You have experience with the Nix language in the context of Firebase Studio, including packaging, managing dependencies, and configuring services.
+
+## 2. Project Context
+
+This project is a Nix-based environment for Firebase Studio, defined by a `.idx/dev.nix` file. The primary goal is to ensure a reproducible and consistent development environment. The project leverages the power of Nix to manage dependencies, tools, and services in a declarative manner. **Note:** This is not a Nix Flake-based environment.
+
+## 3. `dev.nix` Configuration
+
+The `.idx/dev.nix` file is the single source of truth for the development environment. Here are some of the most common configuration options:
+
+### `channel`
+The `nixpkgs` channel determines which package versions are available.
+
+```nix
+{ pkgs, ... }: {
+  channel = "stable-24.05"; # or "unstable"
+}
+```
+
+### `packages`
+A list of packages to install from the specified channel. You can search for packages on the [NixOS package search](https://search.nixos.org/packages).
+
+```nix
+{ pkgs, ... }: {
+  packages = [
+    pkgs.nodejs_20
+    pkgs.go
+  ];
+}
+```
+
+### `env`
+A set of environment variables to define within the workspace.
+
+```nix
+{ pkgs, ... }: {
+  env = {
+    API_KEY = "your-secret-key";
+  };
+}
+```
+
+### `idx.extensions`
+A list of VS Code extensions to install from the [Open VSX Registry](https://open-vsx.org/).
+
+```nix
+{ pkgs, ... }: {
+  idx = {
+    extensions = [
+      "vscodevim.vim"
+      "golang.go"
+    ];
+  };
+}
+```
+
+### `idx.workspace`
+Workspace lifecycle hooks.
+
+- **`onCreate`:** Runs when a workspace is first created.
+- **`onStart`:** Runs every time the workspace is (re)started.
+
+```nix
+{ pkgs, ... }: {
+  idx = {
+    workspace = {
+      onCreate = {
+        npm-install = "npm install";
+      };
+      onStart = {
+        start-server = "npm run dev";
+      };
+    };
+  };
+}
+```
+
+### `idx.previews`
+Configure a web preview for your application. The `$PORT` variable is dynamically assigned.
+
+```nix
+{ pkgs, ... }: {
+  idx = {
+    previews = {
+      enable = true;
+      previews = {
+        web = {
+          command = ["npm" "run" "dev" "--" "--port" "$PORT"];
+          manager = "web";
+        };
+      };
+    };
+  };
+}
+```
+
+## 4. Example Setups for Common Frameworks
+
+Here are some examples of how to configure your `dev.nix` for common languages and frameworks.
+
+### Node.js Web Server
+This example sets up a Node.js environment, installs dependencies, and runs a development server with a web preview.
+
+```nix
+{ pkgs, ... }: {
+  packages = [ pkgs.nodejs_20 ];
+  idx = {
+    extensions = [ "dbaeumer.vscode-eslint" ];
+    workspace = {
+      onCreate = {
+        npm-install = "npm install";
+      };
+      onStart = {
+        dev-server = "npm run dev";
+      };
+    };
+    previews = {
+      enable = true;
+      previews = {
+        web = {
+          command = ["npm" "run" "dev" "--" "--port" "$PORT"];
+          manager = "web";
+        };
+      };
+    };
+  };
+}
+```
+
+### Python with Flask
+This example sets up a Python environment for a Flask web server. Remember to create a `requirements.txt` file with `Flask` in it.
+
+```nix
+{ pkgs, ... }: {
+  packages = [ pkgs.python3 pkgs.pip ];
+  idx = {
+    extensions = [ "ms-python.python" ];
+    workspace = {
+      onCreate = {
+        pip-install = "pip install -r requirements.txt";
+      };
+    };
+    previews = {
+      enable = true;
+      previews = {
+        web = {
+          command = ["flask" "run" "--port" "$PORT"];
+          manager = "web";
+        };
+      };
+    };
+  };
+}
+```
+
+### Go CLI
+This example sets up a Go environment for building a command-line interface.
+
+```nix
+{ pkgs, ... }: {
+  packages = [ pkgs.go ];
+  idx = {
+    extensions = [ "golang.go" ];
+    workspace = {
+      onCreate = {
+        go-mod = "go mod tidy";
+      };
+      onStart = {
+        run-app = "go run .";
+      };
+    };
+  };
+}
+```
+
+## 5. Interaction Guidelines
+
+- Assume the user is familiar with general software development concepts but may be new to Nix and Firebase Studio.
+- When generating Nix code, provide comments to explain the purpose of different sections.
+- Explain the benefits of using `dev.nix` for reproducibility and dependency management.
+- If a request is ambiguous, ask for clarification on the desired tools, libraries, and versions to be included in the environment.
+- When suggesting changes to `dev.nix`, explain the impact of the changes on the development environment and remind the user to reload the environment.

package/.idx/dev.nix

@@ -0,0 +1,54 @@
+# To learn more about how to use Nix to configure your environment
+# see: https://developers.google.com/idx/guides/customize-idx-env
+{ pkgs, ... }: {
+  # Which nixpkgs channel to use.
+  channel = "stable-24.05"; # or "unstable"
+  # Use https://search.nixos.org/packages to find packages
+  packages = [
+    # pkgs.go
+    # pkgs.python311
+    # pkgs.python311Packages.pip
+    pkgs.nodejs_20
+    # pkgs.nodePackages.nodemon
+  ];
+  # Sets environment variables in the workspace
+  env = {};
+  idx = {
+    # Search for the extensions you want on https://open-vsx.org/ and use "publisher.id"
+    extensions = [
+      # "vscodevim.vim"
+      "google.gemini-cli-vscode-ide-companion"
+    ];
+    # Enable previews
+    previews = {
+      enable = true;
+      previews = {
+        # web = {
+        #   # Example: run "npm run dev" with PORT set to IDX's defined port for previews,
+        #   # and show it in IDX's web preview panel
+        #   command = ["npm" "run" "dev"];
+        #   manager = "web";
+        #   env = {
+        #     # Environment variables to set for your server
+        #     PORT = "$PORT";
+        #   };
+        # };
+      };
+    };
+    # Workspace lifecycle hooks
+    workspace = {
+      # Runs when a workspace is first created
+      onCreate = {
+        # Example: install JS dependencies from NPM
+        # npm-install = "npm install";
+        # Open editors for the following files by default, if they exist:
+        default.openFiles = [ ".idx/dev.nix" "README.md" ];
+      };
+      # Runs when the workspace is (re)started
+      onStart = {
+        # Example: start a background task to watch and re-build backend code
+        # watch-backend = "npm run watch-backend";
+      };
+    };
+  };
+}

package/.vscode/settings.json

@@ -0,0 +1,7 @@
+{
+	"editor.tabSize": 2,
+	"files.exclude": {
+		"**/node_modules": true,
+		"**/dist": true
+	}
+}

package/README.md

@@ -0,0 +1,98 @@
+# 📦 Shared Kernel
+
+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.
+
+## 🚀 Installation
+
+```bash
+npm install @schorts/shared-kernel --save
+```
+
+## 🧱 Modules
+
+### 🔐 Auth
+
+- **AuthProvider:** Abstract interface for authentication strategies.
+- **RequireAuthDecorator:** Method-level decorator for enforcing authentication.
+
+### 📊 Criteria
+
+- **Criteria:** Fluent query builder for filtering, sorting, and pagination.
+
+### 📣 Domain Events
+
+- **DomainEvent:** Base class for domain-driven event dispatching.
+
+### 🧬 Entities
+
+- **Entity:** Base class for identity-based domain entities.
+
+### 🧹 Formatters
+
+- **PascalCamelToSnake:** Utility for converting PascalCase or camelCase to snake_case.
+
+### 🌐 HTTP
+
+- **HTTPProvider:** Abstract interface for HTTP transport.
+- **FetchHTTPProvider:** Concrete implementation using fetch.
+
+### 🔗 JSON:API
+
+- **JSONAPIConnector:** Connector for interacting with JSON:API-compliant endpoints.
+
+### 🧩 Models
+
+- **BaseModel:** Base class for serializable, type-safe models.
+
+### 🧠 State Manager
+
+- **StateManager:** Abstract reactive state manager with listener support.
+
+### 🧪 Value Objects
+
+- **CoordinatesValue**
+- **EmailValue**
+- **EnumValue**
+- **IntegerValue**
+- **PhoneValue**
+- **SlugValue**
+- **StringValue**
+- **UUIDValue**
+
+Each value object enforces domain constraints and immutability, ensuring correctness at the boundary of your system.
+
+## 🧠 Philosophy
+
+This kernel is built around:
+
+- **Type safety:** Every abstraction is strongly typed and composable.
+- **Domain expressiveness:** Value objects, entities, and events encode business logic directly.
+- **Extensibility:** Plug in your own HTTP, auth, or state strategies.
+- **Framework independence:** Use it with Node.js, frontend apps, or serverless functions.
+
+## 📦 Example Usage
+
+```ts
+import { Criteria, JSONAPIConnector, FetchHTTPProvider } from "@schorts/shared-kernel";
+
+const criteria = new Criteria()
+  .where("status", "EQUAL", "active")
+  .orderBy("created_at", "DESC")
+  .limitResults(10);
+
+const connector = new JSONAPIConnector(new FetchHTTPProvider());
+
+const users = await connector.findMany(new URL("/users", base), criteria);
+```
+
+## 🧪 Testing
+
+Each module is fully covered with unit tests. To run them:
+
+```bash
+npm run test
+```
+
+## 📜 License
+
+LGPL

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

@@ -0,0 +1,45 @@
+import { expectTypeOf } from "expect-type";
+
+import { AuthProvider } from "../../src/auth";
+import { Entity } from "../../src/entities";
+
+type Model = {
+  id: string;
+  name: string;
+};
+
+class TestUser extends Entity<Model> {
+  toPrimitives(): Model {
+    return {
+      id: this.id.toString(),
+      name: "test",
+    };
+  }
+}
+
+describe('AuthProvider', () => {
+  it('should declare an "authenticate" method', () => {
+    expectTypeOf<AuthProvider<TestUser>['authenticate']>().toBeFunction();
+    expectTypeOf<AuthProvider<TestUser>['authenticate']>().returns.toEqualTypeOf<Promise<void>>();
+  });
+
+  it('should declare a "logout" method', () => {
+    expectTypeOf<AuthProvider<TestUser>['logout']>().toBeFunction();
+    expectTypeOf<AuthProvider<TestUser >['logout']>().returns.toEqualTypeOf<Promise<void>>();
+  });
+
+  it('should declare a "isAuthenticated" method', () => {
+    expectTypeOf<AuthProvider<TestUser>['isAuthenticated']>().toBeFunction();
+    expectTypeOf<AuthProvider<TestUser>['isAuthenticated']>().returns.toEqualTypeOf<Promise<boolean>>();
+  });
+
+  it('should declare a "currentUser" method', () => {
+    expectTypeOf<AuthProvider<TestUser>['currentUser']>().toBeFunction();
+    expectTypeOf<AuthProvider<TestUser>['currentUser']>().returns.toEqualTypeOf<Promise<TestUser  | null>>();
+  });
+
+  it('should declare a "onAuthChange" method', () => {
+    expectTypeOf<AuthProvider<TestUser>['onAuthChange']>().toBeFunction();
+    expectTypeOf<AuthProvider<TestUser>['onAuthChange']>().returns.toEqualTypeOf<() => void>();
+  });
+});

package/__tests__/auth/require-auth.decorator.test.ts

@@ -0,0 +1,88 @@
+import { RequireAuth, NotAuthenticated } from '../../src/auth';
+
+class FakeAuthProvider {
+  constructor(private authenticated: boolean) {}
+  async isAuthenticated() {
+    return this.authenticated;
+  }
+}
+
+class TestService {
+  authProvider: FakeAuthProvider;
+
+  constructor(authenticated: boolean) {
+    this.authProvider = new FakeAuthProvider(authenticated);
+  }
+
+  async securedMethod(): Promise<string> {
+    return 'should not reach';
+  }
+}
+
+describe('RequireAuth decorator (manual application)', () => {
+  it('should throw NotAuthenticated when not authenticated and no onFail', async () => {
+    const service = new TestService(false);
+    const originalMethod = service.securedMethod;
+    const decorated = RequireAuth()(originalMethod, {
+      kind: 'method',
+      name: 'securedMethod',
+      access: { has: () => true, get: () => originalMethod },
+      static: false,
+      private: false,
+      addInitializer: () => {},
+      metadata: {
+        get: () => undefined,
+        set: () => {},
+      },
+    });
+    const wrappedMethod = typeof decorated === 'function' ? decorated : decorated?.value;
+    service.securedMethod = wrappedMethod.bind(service);
+
+    await expect(service.securedMethod()).rejects.toThrow(NotAuthenticated);
+  });
+
+  it('should return fallback value when not authenticated and onFail is provided', async () => {
+    const service = new TestService(false);
+    const fallback = () => 'fallback';
+    const originalMethod = service.securedMethod;
+    const decorated = RequireAuth(fallback)(originalMethod, {
+      kind: 'method',
+      name: 'securedMethod',
+      access: { has: () => true, get: () => originalMethod },
+      static: false,
+      private: false,
+      addInitializer: () => {},
+      metadata: {
+        get: () => undefined,
+        set: () => {},
+      },
+    });
+    const wrappedMethod = typeof decorated === 'function' ? decorated : decorated?.value;
+    service.securedMethod = wrappedMethod.bind(service);
+    const result = await service.securedMethod();
+
+    expect(result).toBe('fallback');
+  });
+
+  it('should call original method when authenticated', async () => {
+    const service = new TestService(true);
+    const originalMethod = service.securedMethod;
+    const decorated = RequireAuth()(originalMethod, {
+      kind: 'method',
+      name: 'securedMethod',
+      access: { has: () => true, get: () => originalMethod },
+      static: false,
+      private: false,
+      addInitializer: () => {},
+      metadata: {
+        get: () => undefined,
+        set: () => {},
+      },
+    });
+    const wrappedMethod = typeof decorated === 'function' ? decorated : decorated?.value;
+    service.securedMethod = wrappedMethod.bind(service);
+    const result = await service.securedMethod();
+
+    expect(result).toBe('should not reach');
+  });
+});

package/__tests__/criteria/criteria.test.ts

@@ -0,0 +1,159 @@
+import { expectTypeOf } from "expect-type";
+
+import {
+  Criteria,
+  FilterCriterion,
+  Order,
+  Operator,
+  Direction,
+  PaginationNotValid,
+  OffsetNotValid,
+  LimitNotValid,
+} from "../../src/criteria";
+
+describe('Criteria', () => {
+  describe('filters', () => {
+    it('should be defined', () => {
+      expectTypeOf<Criteria>().toHaveProperty("filters");
+    });
+
+    it('should be of type Record<string, FilterCriterion>', () => {
+      expectTypeOf<Criteria["filters"]>().toEqualTypeOf<Record<string, FilterCriterion>>();
+    });
+
+    it('should be empty', () => {
+      const criteria = new Criteria();
+      const filters = criteria.filters;
+      const filterKeys = Object.keys(filters);
+
+      expect(filterKeys).toHaveLength(0);
+    });
+  });
+
+  describe('orders', () => {
+    it('should be defined', () => {
+      expectTypeOf<Criteria>().toHaveProperty("orders");
+    });
+
+    it('should be of type Array<Order>', () => {
+      expectTypeOf<Criteria["orders"]>().toEqualTypeOf<Array<Order>>();
+    });
+
+    it('should be empty', () => {
+      const criteria = new Criteria();
+      const orders = criteria.orders;
+
+      expect(orders).toHaveLength(0);
+    });
+  });
+
+  it('should have a "limit" property of type number or undefined', () => {
+    expectTypeOf<Criteria>().toHaveProperty("limit");
+    expectTypeOf<Criteria["limit"]>().toEqualTypeOf<number | undefined>();
+  });
+
+  it('should have a "offset" property of type number or undefined', () => {
+    expectTypeOf<Criteria>().toHaveProperty("offset");
+    expectTypeOf<Criteria["offset"]>().toEqualTypeOf<number | undefined>();
+  });
+
+  describe('#where', () => {
+    it('should receive field, operator and value', () => {
+      expectTypeOf<Criteria["where"]>().parameters.toEqualTypeOf<[string, Operator, any]>();
+    });
+
+    it('should return the same instance', () => {
+      const criteria = new Criteria();
+      const result = criteria.where('field', 'EQUAL', 'value');
+
+      expect(result).toEqual(criteria);
+    });
+
+    it('should add the filter to the "filters" property', () => {
+      const criteria = new Criteria();
+      const result = criteria.where('field', 'EQUAL', 'value');
+      const filters = result.filters;
+      const expectedFilters = { field: { value: "value", operator: "EQUAL" } };
+
+      expect(filters["field"]).toBeDefined();
+      expect(filters).toEqual(expectedFilters);
+    });
+  });
+
+  describe('#orderBy', () => {
+    it('should receive field and direction', () => {
+      expectTypeOf<Criteria["orderBy"]>().parameters.toEqualTypeOf<[string, Direction?]>();
+    });
+
+    it('should return the same instance', () => {
+      const criteria = new Criteria();
+      const result = criteria.orderBy('field', 'DESC');
+
+      expect(result).toEqual(criteria);
+    });
+
+    it('should add the order to the "orders" property', () => {
+      const criteria = new Criteria();
+      const result = criteria.orderBy("field", "DESC");
+      const orders = result.orders;
+      const expectedOrders = [{ field: "field", direction: "DESC" }];
+
+      expect(orders).toHaveLength(1);
+      expect(orders).toEqual(expectedOrders);
+    });
+  });
+
+  describe('#limitResults', () => {
+    it('should receive a number', () => {
+      expectTypeOf<Criteria["limitResults"]>().parameters.toEqualTypeOf<[number]>();
+    });
+
+    it('should return the same instance', () => {
+      const criteria = new Criteria();
+      const result = criteria.limitResults(1);
+
+      expect(result).toEqual(criteria);
+    });
+
+    it('should assign the value to the "limit" property', () => {
+      const criteria = new Criteria();
+      const limit = 1;
+      const result = criteria.limitResults(limit);
+
+      expect(result.limit).toEqual(limit);
+    });
+
+    it('should throw an LimitNotValid exception if value is less than 1', () => {
+      const criteria = new Criteria();
+
+      expect(() => criteria.limitResults(0)).toThrow(LimitNotValid);
+    });
+  });
+
+  describe('#offsetResults', () => {
+    it('should receive a number', () => {
+      expectTypeOf<Criteria["offsetResults"]>().parameters.toEqualTypeOf<[number]>();
+    });
+
+    it('should return the same instance', () => {
+      const criteria = new Criteria();
+      const result = criteria.offsetResults(1);
+
+      expect(result).toEqual(criteria);
+    });
+
+    it('should assign the value to the "offset" property', () => {
+      const criteria = new Criteria();
+      const offset = 1;
+      const result = criteria.offsetResults(offset);
+
+      expect(result.offset).toEqual(offset);
+    });
+
+    it('should throw an OffsetNotValid exception if value is less than 1', () => {
+      const criteria = new Criteria();
+
+      expect(() => criteria.offsetResults(0)).toThrow(OffsetNotValid);
+    });
+  });
+});

package/__tests__/criteria/direction.test.ts

@@ -0,0 +1,11 @@
+import { expectTypeOf } from "expect-type";
+
+import { Direction } from "../../src/criteria";
+
+type ExpectedDirection = "ASC" | "DESC";
+
+describe('Direction', () => {
+  it('should match the expected type', () => {
+    expectTypeOf<Direction>().toEqualTypeOf<ExpectedDirection>();
+  });
+});

package/__tests__/criteria/filter-criterion.test.ts

@@ -0,0 +1,15 @@
+import { expectTypeOf } from "expect-type";
+
+import { FilterCriterion, Operator } from "../../src/criteria";
+
+type ExpectedFilterCriterion = {
+  value: any;
+  operator: Operator;
+}
+
+describe('FilterCriterion', () => {
+  it('should match the expected type', () => {
+    expectTypeOf<FilterCriterion>().toEqualTypeOf<ExpectedFilterCriterion>();
+  });
+});
+

package/__tests__/criteria/operator.test.ts

@@ -0,0 +1,22 @@
+import { expectTypeOf } from "expect-type";
+
+import { Operator } from "../../src/criteria";
+
+type ExpectedOperator =
+  | "EQUAL"
+  | "GREATER_THAN"
+  | "LESS_THAN"
+  | "GREATER_THAN_OR_EQUAL"
+  | "LESS_THAN_OR_EQUAL"
+  | "NOT_EQUAL"
+  | "IN"
+  | "NOT_IN"
+  | "LIKE"
+  | "BETWEEN"
+  | "GEO_RADIUS";
+
+describe('Operator', () => {
+  it('should match the expected type', () => {
+    expectTypeOf<Operator>().toEqualTypeOf<ExpectedOperator>();
+  });
+});