@emkodev/emkore 1.0.3

package/example/README.md

@@ -0,0 +1,200 @@
+# Emkore Example - Modern Production Patterns
+
+This example demonstrates the recommended patterns for using emkore in
+production, based on real-world usage in the hardkore codebase.
+
+## Structure
+
+```
+example/
+├── interface/              # Use case interfaces (contracts)
+│   ├── create-user.usecase.ts
+│   └── user.repository.ts
+├── dto/                    # Data Transfer Objects
+│   └── user.dto.ts
+├── entity/                 # Business entities
+│   └── user.entity.ts
+└── create-user.interactor.ts  # Use case implementation
+```
+
+## Key Patterns
+
+### 1. Import Style
+
+When using emkore in your project, import as a namespace from the published
+package:
+
+```typescript
+import * as emkore from "@emkodev/emkore";
+```
+
+Within the emkore package examples, we use relative imports:
+
+```typescript
+import * as emkore from "../mod.ts"; // For interactor files
+import * as emkore from "../../mod.ts"; // For nested files
+```
+
+### 2. Input/Output Types
+
+- **Input**: Use `interface` for input types
+- **Output**: Use type alias pointing to the DTO
+- **Validation**: Use separate validation functions
+
+```typescript
+export interface CreateUserInput {
+  readonly name: string;
+  readonly email: string;
+  readonly owner: emkore.ResourceScope;
+}
+
+export type CreateUserOutput = UserDto;
+
+export const validateCreateUserInput = (
+  input: CreateUserInput,
+): emkore.ValidationResult =>
+  new emkore.ValidatorBuilder()
+    .string("name", input.name, { required: true })
+    .email("email", input.email, true)
+    .build();
+```
+
+### 3. Entity Pattern
+
+Entities extend `emkore.Entity` and provide:
+
+- Business logic methods
+- `toDto()` for persistence
+- `isValid()` for validation
+
+```typescript
+export class UserEntity extends emkore.Entity {
+  readonly type = "user";
+
+  override toDto(): UserDto {
+    return {
+      ...super.toDto(),
+      name: this.name,
+      email: this.email,
+    };
+  }
+}
+```
+
+### 4. DTO Pattern
+
+DTOs extend `emkore.Dto` and represent the persistence structure:
+
+```typescript
+export interface UserDto extends emkore.Dto {
+  readonly name: string;
+  readonly email: string;
+  readonly role?: string;
+}
+```
+
+### 5. Use Case Pattern
+
+Use cases define the contract with:
+
+- `override` keyword for abstract properties
+- Proper API definitions for RPC/documentation
+- Resource scope support
+
+```typescript
+export abstract class CreateUserUsecase extends emkore.Usecase<
+  CreateUserInput,
+  CreateUserOutput
+> {
+  override usecaseName: emkore.UsecaseName = ["create", "user"];
+
+  override apiDefinition: emkore.ApiDefinition = {
+    name: this.usecaseName.join("_"),
+    description: "Create a new user in the system",
+    // ...
+  };
+
+  override get requiredPermissions(): emkore.Permission[] {
+    return [{ action: "create", resource: "user" }];
+  }
+}
+```
+
+### 6. Interactor Pattern
+
+Interactors implement the business logic with:
+
+- Input validation
+- Entity creation
+- Repository operations within transactions
+- DTO validation
+
+```typescript
+export class CreateUserInteractor extends CreateUserUsecase {
+  protected async _execute(
+    actor: emkore.Actor,
+    input: CreateUserInput,
+  ): Promise<CreateUserOutput> {
+    // 1. Validate input
+    const validation = validateCreateUserInput(input);
+    if (!validation.isValid) {
+      throw new emkore.ValidationException(validation.errors.join(", "));
+    }
+
+    // 2. Create entity
+    const entity = new UserEntity({
+      id: emkore.Entity.generateId("user"),
+      ownerId: input.owner === emkore.ResourceScope.BUSINESS
+        ? actor.businessId
+        : actor.id,
+      // ...
+    });
+
+    // 3. Persist with transaction
+    return await this._uowFactory.transaction(actor.businessId, async (uow) => {
+      const createdDto = await uow.userRepository.create(entity.toDto());
+
+      // 4. Validate returned DTO
+      const dtoValidation = validateUserDto(createdDto);
+      if (!dtoValidation.isValid) {
+        throw new emkore.ValidationException("Invalid DTO");
+      }
+
+      return createdDto;
+    });
+  }
+}
+```
+
+## Best Practices
+
+1. **Always validate input** before processing
+2. **Use ResourceScope** for proper ownership (USER vs BUSINESS)
+3. **Validate DTOs** returned from repositories
+4. **Use transactions** for all database operations
+5. **Generate IDs** with proper prefixes using `Entity.generateId("prefix")`
+6. **Keep entities pure** - business logic only, no persistence concerns
+7. **Use the override keyword** for all abstract properties
+
+## Running the Example
+
+This example is meant to demonstrate patterns. To use it in your application:
+
+1. Implement a concrete `UnitOfWorkFactory` for your database
+2. Implement repositories for your storage layer
+3. Wire up dependencies with your DI container
+4. Register use cases in your registry for RPC exposure
+
+## Migration from Old Patterns
+
+If you're using older patterns:
+
+| Old Pattern               | New Pattern                                 |
+| ------------------------- | ------------------------------------------- |
+| Relative imports          | `import * as emkore from "@emkodev/emkore"` |
+| Abstract class for Input  | `interface` for Input                       |
+| Abstract class for Output | Type alias to DTO                           |
+| Static validation methods | Separate validation functions               |
+| No Entity class           | Entity extends `emkore.Entity`              |
+| Direct DTO manipulation   | Entity with `toDto()` method                |
+| No `override` keyword     | Use `override` for all abstract properties  |

package/example/create-user.interactor.ts

@@ -0,0 +1,88 @@
+import * as emkore from "../mod.ts";
+import { UserEntity } from "./entity/user.entity.ts";
+import { validateUserDto } from "./dto/user.dto.ts";
+import {
+  type CreateUserInput,
+  type CreateUserOutput,
+  CreateUserUsecase,
+  validateCreateUserInput,
+} from "./interface/create-user.usecase.ts";
+import type { UserRepository } from "./interface/user.repository.ts";
+
+// Example concrete UnitOfWorkFactory implementation
+interface ExampleUnitOfWork extends emkore.UnitOfWork {
+  userRepository: UserRepository;
+}
+
+interface ExampleUnitOfWorkFactory extends emkore.UnitOfWorkFactory {
+  transaction<T>(
+    businessId: string,
+    callback: (uow: ExampleUnitOfWork) => Promise<T>,
+  ): Promise<T>;
+}
+
+/**
+ * Concrete implementation of CreateUserUsecase.
+ *
+ * This Interactor:
+ * 1. Extends the abstract CreateUserUsecase (inherits all metadata)
+ * 2. Accepts dependencies through constructor (UnitOfWorkFactory)
+ * 3. Implements only the _execute method with HOW to create a user
+ * 4. Uses UoW pattern for transaction management
+ * 5. Follows production patterns from hardkore codebase
+ */
+export class CreateUserInteractor extends CreateUserUsecase {
+  constructor(private readonly _uowFactory: ExampleUnitOfWorkFactory) {
+    super();
+  }
+
+  protected async _execute(
+    actor: emkore.Actor,
+    input: CreateUserInput,
+  ): Promise<CreateUserOutput> {
+    // Validate input
+    const validation = validateCreateUserInput(input);
+    if (!validation.isValid) {
+      throw new emkore.ValidationException(validation.errors.join(", "));
+    }
+
+    // Create entity
+    const entity = new UserEntity({
+      id: emkore.Entity.generateId("user"),
+      ownerId: input.owner === emkore.ResourceScope.BUSINESS
+        ? actor.businessId
+        : actor.id,
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+      name: input.name,
+      email: input.email,
+      ...(input.role && { role: input.role }),
+    });
+
+    // Persist via repository using transaction
+    return await this._uowFactory.transaction(actor.businessId, async (uow) => {
+      // Check for existing email
+      const existingUser = await uow.userRepository.findByEmail(input.email);
+      if (existingUser) {
+        throw new emkore.ValidationException(
+          `Email ${input.email} already exists`,
+        );
+      }
+
+      // Create the user
+      const createdDto = await uow.userRepository.create(entity.toDto());
+
+      // Validate the returned DTO
+      const dtoValidation = validateUserDto(createdDto);
+      if (!dtoValidation.isValid) {
+        throw new emkore.ValidationException(
+          `Invalid DTO returned from repository: ${
+            dtoValidation.errors.join(", ")
+          }`,
+        );
+      }
+
+      return createdDto;
+    });
+  }
+}

package/example/dto/user.dto.ts

@@ -0,0 +1,34 @@
+import * as emkore from "../../mod.ts";
+
+/**
+ * User Data Transfer Object.
+ * This represents the data structure for persistence.
+ */
+export interface UserDto extends emkore.Dto {
+  readonly name: string;
+  readonly email: string;
+  readonly role?: string;
+}
+
+/**
+ * Validates a User DTO.
+ */
+export const validateUserDto = (dto: UserDto): emkore.ValidationResult =>
+  new emkore.ValidatorBuilder()
+    .entityId("id", dto.id, "user", true)
+    .string("ownerId", dto.ownerId, { required: true })
+    .string("name", dto.name, {
+      required: true,
+      minLength: 1,
+      maxLength: 100,
+    })
+    .email("email", dto.email, true)
+    .string("role", dto.role, { required: false })
+    .dateTime("createdAt", new Date(dto.createdAt), { required: true })
+    .dateTime("updatedAt", new Date(dto.updatedAt), { required: true })
+    .dateTime(
+      "deletedAt",
+      dto.deletedAt ? new Date(dto.deletedAt) : undefined,
+      { required: false },
+    )
+    .build();

package/example/entity/user.entity.ts

@@ -0,0 +1,54 @@
+import * as emkore from "../../mod.ts";
+import { type UserDto, validateUserDto } from "../dto/user.dto.ts";
+
+/**
+ * User Entity class.
+ * This represents the business object with behavior.
+ */
+export class UserEntity extends emkore.Entity {
+  readonly type = "user";
+
+  readonly name: string;
+  readonly email: string;
+  readonly role?: string;
+
+  constructor(dto: UserDto) {
+    super(dto);
+    this.name = dto.name;
+    this.email = dto.email;
+    if (dto.role) this.role = dto.role;
+  }
+
+  /**
+   * Converts the entity back to a DTO for persistence.
+   */
+  override toDto(): UserDto {
+    return {
+      ...super.toDto(),
+      name: this.name,
+      email: this.email,
+      ...(this.role && { role: this.role }),
+    };
+  }
+
+  /**
+   * Validates the entity's data.
+   */
+  isValid(): boolean {
+    return validateUserDto(this.toDto()).isValid;
+  }
+
+  /**
+   * Business logic example: Check if user has admin role.
+   */
+  isAdmin(): boolean {
+    return this.role === "admin";
+  }
+
+  /**
+   * Business logic example: Format display name.
+   */
+  getDisplayName(): string {
+    return this.name || this.email.split("@")[0];
+  }
+}

package/example/index.ts

@@ -0,0 +1,18 @@
+/**
+ * Example exports demonstrating modern emkore patterns.
+ *
+ * This example shows production-ready patterns based on real-world usage.
+ */
+
+// DTOs
+export * from "./dto/user.dto.ts";
+
+// Entities
+export * from "./entity/user.entity.ts";
+
+// Interfaces
+export * from "./interface/create-user.usecase.ts";
+export * from "./interface/user.repository.ts";
+
+// Interactors
+export * from "./create-user.interactor.ts";

package/example/interface/create-user.usecase.ts

@@ -0,0 +1,93 @@
+import * as emkore from "../../mod.ts";
+import type { UserDto } from "../dto/user.dto.ts";
+
+/**
+ * Input data for creating a new user.
+ */
+export interface CreateUserInput {
+  readonly name: string;
+  readonly email: string;
+  readonly role?: string;
+  readonly owner: emkore.ResourceScope;
+}
+
+/**
+ * Output data for create operation.
+ * Returns plain DTO object, not Entity class.
+ */
+export type CreateUserOutput = UserDto;
+
+/**
+ * Validates the create user input.
+ */
+export const validateCreateUserInput = (
+  input: CreateUserInput,
+): emkore.ValidationResult =>
+  new emkore.ValidatorBuilder()
+    .string("name", input.name, {
+      required: true,
+      minLength: 1,
+      maxLength: 100,
+    })
+    .email("email", input.email, true)
+    .string("role", input.role, { required: false })
+    .enum("owner", input.owner, Object.values(emkore.ResourceScope))
+    .build();
+
+/**
+ * Abstract Usecase defining the contract for creating a user.
+ * This defines WHAT the usecase does, not HOW it does it.
+ */
+export abstract class CreateUserUsecase extends emkore.Usecase<
+  CreateUserInput,
+  CreateUserOutput
+> {
+  override usecaseName: emkore.UsecaseName = ["create", "user"];
+
+  override apiDefinition: emkore.ApiDefinition = {
+    name: this.usecaseName.join("_"),
+    description: "Create a new user in the system",
+    parameters: [
+      {
+        name: "name",
+        type: "string",
+        description: "User full name",
+        isRequired: true,
+      },
+      {
+        name: "email",
+        type: "string",
+        description: "User email address",
+        isRequired: true,
+      },
+      {
+        name: "role",
+        type: "string",
+        description: "Optional user role",
+        isRequired: false,
+      },
+      {
+        name: "owner",
+        type: "string",
+        description: `Resource scope owner (${
+          Object.values(emkore.ResourceScope).join(", ")
+        })`,
+        isRequired: true,
+      },
+    ],
+    returns: {
+      type: "object",
+      description:
+        "Result containing the created user with id, name, email, and timestamps",
+    },
+  };
+
+  override get requiredPermissions(): emkore.Permission[] {
+    return [
+      {
+        action: "create",
+        resource: "user",
+      },
+    ];
+  }
+}

package/example/interface/user.repository.ts

@@ -0,0 +1,23 @@
+import type * as emkore from "../../mod.ts";
+import type { UserDto } from "../dto/user.dto.ts";
+
+/**
+ * User Repository interface.
+ * Extends the base repository with user-specific methods.
+ */
+export interface UserRepository extends emkore.Repository<UserDto> {
+  /**
+   * Find a user by email address.
+   */
+  findByEmail(email: string): Promise<UserDto | null>;
+
+  /**
+   * Find users by role.
+   */
+  findByRole(role: string): Promise<UserDto[]>;
+
+  /**
+   * Check if email exists in the system.
+   */
+  emailExists(email: string): Promise<boolean>;
+}

package/mod.ts

@@ -0,0 +1 @@
+export * from "./src/index.ts";

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@emkodev/emkore",
+  "version": "1.0.3",
+  "description": "A TypeScript foundation framework for building robust, type-safe business applications with clean architecture patterns",
+  "license": "MIT",
+  "author": "emko.dev",
+  "type": "module",
+  "keywords": [
+    "typescript",
+    "clean-architecture",
+    "business-logic",
+    "framework",
+    "patterns"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/emkore/emkore.git"
+  },
+  "exports": {
+    ".": "./mod.ts"
+  },
+  "scripts": {
+    "test": "bun test",
+    "check": "bun run tsc --noEmit",
+    "lint": "biome lint ./src ./test",
+    "fmt": "biome format --write ./src ./test"
+  },
+  "devDependencies": {
+    "bun-types": "^1.3.9",
+    "typescript": "^5.9.3"
+  }
+}

package/src/common/abstract.actor.ts

@@ -0,0 +1,59 @@
+import type { Permission } from "./type/permission.type.ts";
+
+export abstract class Actor {
+  private _permissions = new Set<Permission>();
+  private _cachedTeamIds?: string[] | undefined;
+
+  abstract get id(): string;
+  abstract get businessId(): string;
+  abstract get token(): string;
+
+  get permissions(): Permission[] {
+    return Array.from(this._permissions);
+  }
+
+  set permissions(permissions: Permission[]) {
+    this._permissions = new Set(permissions);
+    this._cachedTeamIds = undefined; // Invalidate cache when permissions change
+  }
+
+  addPermission(permission: Permission): void {
+    this._permissions.add(permission);
+    this._cachedTeamIds = undefined; // Invalidate cache
+  }
+
+  addPermissions(permissions: Permission[]): void {
+    permissions.forEach((permission) => this._permissions.add(permission));
+    this._cachedTeamIds = undefined; // Invalidate cache
+  }
+
+  /**
+   * Extract unique team IDs from user permissions.
+   *
+   * Team membership is derived from permissions with `constraints.teamId`.
+   * A user is a member of a team if they have ANY permission with that teamId.
+   *
+   * Result is cached for performance within the actor's lifetime (request scope).
+   *
+   * @returns Array of team IDs the actor belongs to
+   * @example
+   * ```typescript
+   * const teamIds = actor.getTeamIds(); // ["1100-legal", "1100-sales"]
+   * ```
+   */
+  getTeamIds(): string[] {
+    if (this._cachedTeamIds) {
+      return this._cachedTeamIds;
+    }
+
+    const teamIds = new Set<string>();
+    for (const permission of this._permissions) {
+      if (permission.constraints?.teamId) {
+        teamIds.add(permission.constraints.teamId);
+      }
+    }
+
+    this._cachedTeamIds = Array.from(teamIds);
+    return this._cachedTeamIds;
+  }
+}

package/src/common/abstract.entity.ts

@@ -0,0 +1,59 @@
+import type { ValidationResult } from "./validation/validation-result.ts";
+import { ValidatorBuilder } from "./validation/validators.ts";
+
+export interface Dto {
+  readonly id: string;
+  readonly ownerId: string;
+  readonly createdAt: string;
+  readonly updatedAt: string;
+  readonly deletedAt?: string;
+}
+
+export const validateDto = (): ValidationResult =>
+  new ValidatorBuilder()
+    .string("id", "id")
+    .string("ownerId", "")
+    .dateTime("createdAt", new Date())
+    .build();
+
+export abstract class Entity {
+  readonly id: string;
+  readonly ownerId: string;
+  readonly createdAt: Date;
+  readonly updatedAt: Date;
+  readonly deletedAt?: Date;
+
+  constructor(dto: Dto) {
+    this.id = dto.id;
+    this.ownerId = dto.ownerId;
+    this.createdAt = new Date(dto.createdAt);
+    this.updatedAt = new Date(dto.updatedAt);
+    if (dto.deletedAt) {
+      this.deletedAt = new Date(dto.deletedAt);
+    }
+  }
+
+  get isDeleted(): boolean {
+    return this.deletedAt !== undefined;
+  }
+
+  toDto(): Dto {
+    return {
+      id: this.id,
+      ownerId: this.ownerId,
+      createdAt: this.createdAt.toISOString(),
+      updatedAt: this.updatedAt.toISOString(),
+      ...(this.deletedAt && { deletedAt: this.deletedAt.toISOString() }),
+    };
+  }
+
+  static generateId(prefix: string): string {
+    const validSymbols = /^[0-9a-fA-F]{4}$/;
+    if (!validSymbols.test(prefix)) {
+      throw new Error(
+        "Prefix must be exactly four hexadecimal characters (0-9, a-f, A-F), no hyphens.",
+      );
+    }
+    return `${prefix}-${crypto.randomUUID()}`;
+  }
+}

package/src/common/abstract.interceptor.ts

@@ -0,0 +1,17 @@
+import type { InterceptorContext } from "./type/interceptor-context.type.ts";
+
+export interface Interceptor<Input, Output> {
+  readonly name: string;
+
+  beforeExecute?(
+    input: Input,
+    context: InterceptorContext,
+  ): Input | Promise<Input>;
+
+  afterExecute?(
+    result: Output,
+    context: InterceptorContext,
+  ): Output | Promise<Output>;
+
+  onError?(error: Error, context: InterceptorContext): void | Promise<void>;
+}