@emkodev/emkore 1.0.3

package/CHANGELOG.md

@@ -0,0 +1,269 @@
+# Changelog
+
+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.0.0/),
+and this project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.3] - 2026-01-20
+
+### Added
+
+- **Authorization**: Added `PROJECT` resource scope for project-level
+  permissions
+  - `ResourceScope.PROJECT` is now available as a scope parallel to `TEAM` under
+    `BUSINESS`
+  - Project scope satisfies PROJECT and OWNED scopes
+  - BUSINESS scope now satisfies PROJECT scope (in addition to TEAM and OWNED)
+  - Added `projectId` field to `ResourceConstraints` for project-scoped
+    permissions
+  - Authorization interceptor now validates `projectId` constraints similar to
+    `teamId`
+
+## [1.0.2] - 2026-01-19
+
+### Added
+
+- **Type Utilities**: Export `Lowercase`, `LowercaseArray`, and
+  `LowercaseArrayUnion` types for enforcing lowercase string literals in const
+  arrays
+
+## [1.0.1] - 2026-01-16
+
+### Fixed
+
+- **Documentation**: Removed unsubstantiated claims from README
+  - Fixed inconsistent test coverage claims
+  - Removed "minimal `any` usage" contradiction
+  - Clarified browser support (removed unverified browser claim)
+  - Simplified code quality metrics to avoid misleading claims
+
+## [1.0.0] - 2026-01-15
+
+### 🎉 Stable Release
+
+First stable release of Emkore! The framework is now production-ready with a
+stable API.
+
+### Changed
+
+- **Type Safety Improvements**: Eliminated all `Record<string, any>` usage
+  - Replaced with proper `JsonSchema` and `MutableJsonSchema` types
+  - Added dedicated `Metadata` type for type-safe metadata handling
+  - Full TypeScript strict mode compliance with zero `any` types (except where
+    absolutely necessary)
+
+- **Enhanced Examples**: Complete rewrite of examples to match production
+  patterns
+  - Separated concerns with Entity/DTO pattern
+  - Added proper validation functions
+  - Improved interface definitions
+  - Added comprehensive example documentation
+
+### Added
+
+- **New Type Definitions**:
+  - `JsonSchema` and `MutableJsonSchema` for JSON Schema handling
+  - `Metadata` type for consistent metadata typing
+  - Proper type exports in main index
+
+### Fixed
+
+- **TypeScript Compilation**: Resolved all type errors
+  - Fixed readonly vs mutable property assignments
+  - Corrected type incompatibilities in API definitions
+  - Fixed array spread operator issues with readonly arrays
+
+- **Linting Issues**: Cleaned up entire codebase
+  - Removed unnecessary `async` keywords from synchronous methods
+  - Fixed import declarations (import type where appropriate)
+  - Corrected lint-ignore comment placement
+  - Cleaned up test imports
+
+- **Performance Interceptor**: Fixed async method signatures to match interface
+
+### Quality
+
+- Zero linting errors across entire codebase
+- All tests passing (100% success rate)
+- Full TypeScript strict mode compliance
+- Production-ready code quality
+
+## [0.4.3] - 2026-01-14
+
+### Added
+
+- **BaseFilter<TDto>** type for repository query filtering
+  - Extracts business fields from DTO while adding type-safe date range queries
+  - Supports createdAt, updatedAt, and deletedAt range filtering
+  - Exported from main index for public API usage
+
+- **Lowercase utility types** for compile-time validation
+  - `Lowercase<T>` type ensures string literals contain only lowercase
+    characters
+  - `LowercaseArray` ensures all array elements are lowercase strings
+  - `LowercaseArrayUnion<T>` helper to extract union types from lowercase arrays
+  - Enforces consistency with kebab-case naming conventions
+
+## [0.4.2] - 2024-12-24
+
+### Changed
+
+- **LlmParameter and LlmReturnValue**: Refactored to use type-safe discriminated
+  unions for JSON Schema 2020-12 compliance
+  - Added support for primitive types: `string`, `number`, `integer`, `boolean`,
+    `null`
+  - Array types now require `items` field with proper type definitions
+  - Object types now support optional `properties` and `required` fields
+  - TypeScript enforces correct fields based on type (e.g., `items` only on
+    arrays)
+- **apiDefinitionToJsonSchema**: Updated to properly handle `items` for arrays
+  and `properties`/`required` for objects
+- Moved test files to proper `test/unit/` directory structure
+
+### Added
+
+- Comprehensive test suite for `apiDefinitionToJsonSchema` with 19 test cases
+  covering all type variations
+
+## [0.4.1] - 2025-12-21
+
+### Added
+
+- **Actor.getTeamIds()**: New method to extract unique team IDs from actor
+  permissions
+  - Returns array of team IDs based on permissions with `constraints.teamId`
+  - Implements caching for performance within actor lifetime (request scope)
+  - Cache automatically invalidates when permissions are modified
+  - Comprehensive test coverage with 15 test cases covering edge cases, caching
+    behavior, and real-world scenarios
+
+## [0.4.0] - 2025-12-20
+
+### Added
+
+- **Money class**: Type-safe monetary value object with multi-currency support
+  - Stores amounts in cents (minor units) to avoid floating-point precision
+    errors
+  - Enforces currency consistency in all arithmetic operations (throws on USD +
+    EUR)
+  - Provides locale-aware formatting with Intl.NumberFormat
+  - Supports all common monetary operations: add, subtract, multiply, divide
+  - Immutable - all operations return new instances
+  - Comprehensive comparison methods (equals, lessThan, greaterThan, etc.)
+  - **Currency is REQUIRED** - no defaults to prevent accidental currency mixing
+    bugs
+- **Cents type**: Type alias for monetary amounts in minor units
+  - Makes it explicit that values are in cents, not dollars/euros
+  - Use in DTOs and value objects for self-documenting code
+- 67 comprehensive unit tests for Money class
+- Full JSDoc documentation with examples for all Money methods
+
+### Examples
+
+```typescript
+// Basic usage
+const price = Money.fromCents(14999, "USD"); // $149.99
+const tax = price.multiply(0.08); // 8% tax
+const total = price.add(tax); // $161.99
+console.log(total.format()); // "$149.99"
+
+// Currency safety
+const usd = Money.fromCents(100, "USD");
+const eur = Money.fromCents(100, "EUR");
+usd.add(eur); // ❌ Throws: "Cannot operate on Money with different currencies"
+
+// DTOs with Cents type
+interface PriceDto {
+  unitPrice: Cents; // Explicit: this is in cents!
+  currency: string;
+}
+```
+
+## [0.3.0] - 2025-12-20
+
+### Fixed
+
+- **SECURITY**: Removed hardcoded `AuthorizationInterceptor` from `Usecase`
+  global interceptors. This was a critical security flaw that forced
+  authorization on all usecases by default without explicit opt-in.
+
+### BREAKING CHANGE (Security Fix)
+
+**IMPORTANT**: If you were relying on automatic authorization, you MUST now
+explicitly register the `AuthorizationInterceptor`:
+
+```typescript
+import { Usecase } from "@emkodev/emkore";
+import { AuthorizationInterceptor } from "@emkodev/emkore";
+
+// Add this at your application startup:
+Usecase.use([new AuthorizationInterceptor()]);
+```
+
+Without this explicit registration, your usecases will NO LONGER have
+authorization checks applied automatically. Review your security requirements
+and update your code accordingly.
+
+## [0.2.1] - 2024-12-26
+
+### Changed
+
+- Refactored UseCase registry system to dedicated module
+- Moved `UseCaseRegistryEntry` and `UseCaseRegistryHelpers` to
+  `src/common/registry/usecase-registry.ts`
+- Improved code organization and module structure
+
+## [0.2.0] - 2024-12-26
+
+### Added
+
+- Cross-platform environment variable abstraction (`getEnv`, `getEnvOrDefault`)
+- Support for Node.js, Deno, and browser environments
+- UseCase registry system for auto-discovery and dynamic routing
+- HTTP method and path mapping utilities for REST API generation
+
+### Changed
+
+- Replaced Deno-specific `Deno.env.get()` calls with platform-agnostic functions
+- Enhanced JSR compatibility and cross-platform support
+
+## [0.1.0] - 2024-12-25
+
+### Added
+
+- Initial release of Emkore Core
+- Base `Entity` class with id generation, ownership tracking, and soft deletion
+- Abstract `Usecase` class with interceptor support for authorization and
+  logging
+- `Actor` class for representing users and systems
+- Permission-based authorization system with resource scoping
+- `Money` value object for type-safe monetary calculations
+- Fluent `ValidatorBuilder` for input validation
+- `BaseRepository` interface for data persistence patterns
+- Unit of Work pattern interfaces
+- Configuration management with `ConfigSection` and `ConfigRegistry`
+- Comprehensive exception hierarchy
+- Built-in interceptors for authorization, performance tracking, and audit
+  logging
+- LLM API definition types for code generation
+- Complete test suite with unit and integration tests
+- Developer documentation with coding philosophy and best practices
+
+### Features
+
+- Zero external dependencies
+- Strict TypeScript with no type casting
+- Clean architecture patterns
+- Extensible interceptor system
+- 12-factor app configuration support
+- Type-safe JSON handling
+- Working examples and comprehensive documentation
+
+---
+
+_This project follows [Semantic Versioning](https://semver.org/). Breaking
+changes will increment the major version._

package/DEVELOPER_GUIDE.md

@@ -0,0 +1,227 @@
+# Developer Guide
+
+## Philosophy & Vision
+
+This codebase follows a pragmatic, clean code philosophy that prioritizes
+simplicity, maintainability, and type safety without sacrificing developer
+experience.
+
+### Core Principles
+
+#### 1. No Type Casting
+
+- **Never use `as` type assertions** - If TypeScript can't infer it, the code
+  structure is wrong
+- Avoid `any` types - Use `unknown` when type is genuinely unknown
+- Let TypeScript's inference do the work - explicit types only when necessary
+
+```typescript
+// ❌ Bad
+const result = someFunction() as SomeType;
+
+// ✅ Good
+const result: SomeType = someFunction(); // Let it fail if types don't match
+```
+
+#### 2. Avoid `| undefined` Union Types
+
+- Use optional properties (`?`) instead of union types with undefined
+- Handle undefined cases through conditional logic, not type unions
+- Keep types clean and readable
+
+```typescript
+// ❌ Bad
+interface Entity {
+  deletedAt: Date | undefined;
+}
+
+// ✅ Good
+interface Entity {
+  deletedAt?: Date;
+}
+```
+
+#### 3. DRY (Don't Repeat Yourself)
+
+- Never duplicate code for slight variations
+- Use spread operators, destructuring, and composition
+- If you're copying code, you're doing it wrong
+
+```typescript
+// ❌ Bad
+if (condition) {
+  return { id, name, age, status: "active" };
+} else {
+  return { id, name, age, status: "inactive" };
+}
+
+// ✅ Good
+return { id, name, age, status: condition ? "active" : "inactive" };
+```
+
+#### 4. Minimal External Dependencies
+
+- Avoid third-party packages unless absolutely necessary
+- Don't import a library to use one or two easily reproducible functions
+- Every dependency is technical debt
+
+#### 5. No Nullable Lists
+
+- Lists/arrays should never be null or undefined
+- Use empty arrays instead of null/undefined for collections
+- This simplifies consumption and prevents null checks
+
+```typescript
+// ❌ Bad
+interface Response {
+  items?: Item[] | null;
+}
+
+// ✅ Good
+interface Response {
+  items: Item[]; // Empty array when no items
+}
+```
+
+#### 6. Clean Commit History
+
+- No watermarks in code, comments, or commit messages
+- Commit messages should be concise and meaningful
+- No auto-generated signatures or unnecessary metadata
+
+## Architecture Guidelines
+
+### Emkore - The Foundation
+
+- **Pure abstractions** - No implementation details
+- **Zero dependencies** - Must remain dependency-free
+- **Extensible interfaces** - Consumers implement their own specifics
+- **Optional guidance** - Provide optional methods/properties as reminders
+
+### Pattern Implementation
+
+#### Repository Pattern
+
+- Keep interfaces minimal
+- Let consumers decide on implementation details
+- Don't force specific database paradigms
+
+#### Unit of Work
+
+- Provide transaction boundaries
+- Optional tracking methods for advanced implementations
+- Don't prescribe how state management works
+
+#### Validation
+
+- Chainable, fluent API
+- Return comprehensive results, not throw exceptions
+- Let consumers decide how to handle validation failures
+
+### Testing Philosophy
+
+- **Unit tests for foundations** - Test core abstractions thoroughly
+- **Integration tests for implementations** - Test real-world usage
+- **No mocking for the sake of it** - Test real behavior when possible
+- **Fast feedback** - Tests should run quickly
+
+### Code Style
+
+#### TypeScript Configuration
+
+- Use strict mode - catch errors at compile time
+- Enable all strict flags - better to be safe
+- But handle strictness elegantly (no ugly workarounds)
+
+#### Formatting
+
+- Let tools handle formatting (Deno fmt)
+- Focus on logic, not spaces
+- Consistency through automation
+
+### Performance Considerations
+
+- **Optimize when measured** - Don't guess, profile
+- **Use appropriate data structures** - Maps for lookups, Sets for uniqueness
+- **Batch operations** - Reduce round trips
+- **Cache computations** - But invalidate properly
+
+### Error Handling
+
+- **Be explicit about errors** - Use custom exception types
+- **Fail fast** - Validate early
+- **Provide context** - Error messages should be actionable
+- **Don't swallow errors** - Let them bubble appropriately
+
+## Contributing
+
+When contributing to this codebase:
+
+1. **Understand the existing patterns** - Read the code first
+2. **Follow conventions** - Don't introduce new patterns without discussion
+3. **Write tests** - Untested code is broken code
+4. **Keep it simple** - Clever code is hard to maintain
+5. **Document intentions** - Why, not what
+
+## Examples of Good Code
+
+### Clean Entity Implementation
+
+```typescript
+// Simple, no type casting, handles optional properly
+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);
+  }
+}
+```
+
+### Efficient Permission Checking
+
+```typescript
+// Pre-computed lookups, no repeated iterations
+private static readonly SCOPE_SATISFIES = new Map<ResourceScope, Set<ResourceScope>>([
+  [ResourceScope.ALL, new Set([ResourceScope.ALL, ResourceScope.BUSINESS, ResourceScope.PROJECT, ResourceScope.TEAM, ResourceScope.OWNED])],
+  // ...
+]);
+```
+
+### Type-Safe Constants
+
+```typescript
+// Derive types from constants, not the other way around
+const COMMON_ACTIONS_ARRAY = [
+  "create",
+  "retrieve",
+  "list",
+  "count",
+  "update",
+  "delete",
+] as const;
+
+export type CommonAction = typeof COMMON_ACTIONS_ARRAY[number];
+```
+
+## What We're Building
+
+This is not just another framework. It's a foundation for building robust,
+type-safe business applications with:
+
+- **Clear separation of concerns** - Business logic separate from infrastructure
+- **Testable by design** - Not by accident
+- **Extensible without modification** - Open/closed principle
+- **Performance when needed** - Not premature optimization
+
+The goal is code that:
+
+- A new developer can understand quickly
+- Doesn't fight TypeScript's type system
+- Scales without rewrites
+- Makes the right thing easy and the wrong thing hard
+
+Remember: We're building for the long term. Every line of code is a liability.
+Make each one count.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Emkore Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,126 @@
+# Emkore
+
+[![JSR](https://jsr.io/badges/@emkodev/emkore)](https://jsr.io/@emkodev/emkore)
+[![JSR Score](https://jsr.io/badges/@emkodev/emkore/score)](https://jsr.io/@emkodev/emkore)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0%2B-blue)](https://www.typescriptlang.org/)
+[![Zero Dependencies](https://img.shields.io/badge/Dependencies-0-brightgreen)](./deno.json)
+
+A TypeScript foundation framework for building robust, type-safe business
+applications with clean architecture patterns.
+
+## Why Emkore?
+
+- **Clean architecture patterns** - Built on Domain-Driven Design and SOLID
+  principles
+- **Type-safe** - TypeScript with strict mode
+- **Framework agnostic** - Works with Deno, Node.js, and Bun
+- **Zero dependencies** - No external dependencies, pure TypeScript
+- **Comprehensive** - Complete framework with all essential building blocks
+- **Developer-friendly** - Intuitive APIs with comprehensive documentation
+
+## Philosophy
+
+Emkore provides pure abstractions and patterns for building scalable business
+applications without imposing implementation details. It follows a pragmatic,
+clean code philosophy that prioritizes simplicity, maintainability, and type
+safety.
+
+## Key Features
+
+- **Zero Dependencies**: Lightweight core with no external dependencies
+- **Type Safety**: Strict TypeScript with comprehensive type checking
+- **Clean Architecture**: Separation of business logic from infrastructure
+- **Extensible**: Pure abstractions that you implement according to your needs
+- **Testing-Friendly**: Built with testability in mind
+
+## Code Quality Metrics
+
+- 📊 **Pure TypeScript** - No JavaScript required
+- ✅ **Comprehensive Tests** - Extensive unit and integration test suite
+- 🚀 **Direct Execution** - No build step required, runs directly
+- 📦 **Zero Dependencies** - No external packages to manage or audit
+- 📐 **Strict Mode Compliant** - No warnings with strictest TypeScript settings
+
+## Installation
+
+### Deno
+
+```bash
+deno add @emkodev/emkore
+```
+
+### Node.js / npm
+
+```bash
+npx jsr add @emkodev/emkore
+```
+
+### Bun
+
+```bash
+bunx jsr add @emkodev/emkore
+```
+
+## Quick Start
+
+See the [example](./example/) directory for a complete working example of how
+to:
+
+- Create use cases with the `Usecase` base class
+- Implement business logic with proper authorization
+- Use the Entity pattern with DTOs
+- Handle validation and permissions
+
+## Core Concepts
+
+### Entities
+
+Base `Entity` class with built-in id generation, ownership tracking, and soft
+deletion support.
+
+### Use Cases
+
+Abstract `Usecase<Input, Output>` class with interceptor support for
+authorization, logging, and performance tracking.
+
+### Validation
+
+Fluent `ValidatorBuilder` for input validation with comprehensive error
+reporting.
+
+### Repository Pattern
+
+`BaseRepository` interface for data persistence with Unit of Work support.
+
+### Authorization
+
+Permission-based authorization with `Actor` and resource scoping.
+
+### Money Value Object
+
+Type-safe `Money` class for monetary calculations.
+
+## Documentation
+
+- [Developer Guide](./DEVELOPER_GUIDE.md) - Philosophy, principles, and best
+  practices
+- [TypeScript Guide](./TYPESCRIPT.md) - TypeScript-specific guidelines
+- [Platform Dependencies](./PLATFORM-DEPENDENCIES.md) - Platform-specific
+  considerations
+- [Examples](./example/) - Working code examples
+
+## Contributing
+
+1. Read the [Developer Guide](./DEVELOPER_GUIDE.md) to understand our philosophy
+2. Follow existing code patterns and conventions
+3. Write tests for new functionality
+4. Keep it simple and maintainable
+
+## License
+
+MIT License - see [LICENSE](./LICENSE) file for details.
+
+## Release Status
+
+**Version 1.0.0** - Stable release with a mature, well-tested API.

package/bun.lock

@@ -0,0 +1,22 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "@emkodev/emkore",
+      "devDependencies": {
+        "bun-types": "^1.3.9",
+        "typescript": "^5.9.3",
+      },
+    },
+  },
+  "packages": {
+    "@types/node": ["@types/node@25.3.0", "", { "dependencies": { "undici-types": "~7.18.0" } }, "sha512-4K3bqJpXpqfg2XKGK9bpDTc6xO/xoUP/RBWS7AtRMug6zZFaRekiLzjVtAoZMquxoAbzBvy5nxQ7veS5eYzf8A=="],
+
+    "bun-types": ["bun-types@1.3.9", "", { "dependencies": { "@types/node": "*" } }, "sha512-+UBWWOakIP4Tswh0Bt0QD0alpTY8cb5hvgiYeWCMet9YukHbzuruIEeXC2D7nMJPB12kbh8C7XJykSexEqGKJg=="],
+
+    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
+
+    "undici-types": ["undici-types@7.18.2", "", {}, "sha512-AsuCzffGHJybSaRrmr5eHr81mwJU3kjw6M+uprWvCXiNeN9SOGwQ3Jn8jb8m3Z6izVgknn1R0FTCEAP2QrLY/w=="],
+  }
+}