@typetron/framework 0.5.30 → 0.5.31

package/AGENTS.md

@@ -0,0 +1,31 @@
+# Typetron Framework Guide
+
+Read the documentation for the module you are changing before editing its source. Nested features are documented by their owning module; for
+example, HTTP and WebSocket routing are covered by Router, while migrations and seeders are covered by Database.
+
+## Module Documentation
+
+- [Cache](Cache/Readme.md) - cache contracts and memory, file, and database stores.
+- [Container](Container/Readme.md) - dependency injection, bindings, resolvers, and scopes.
+- [Database](Database/Readme.md) - connections, queries, entities, relationships, migrations, and seeders.
+- [Encryption](Encryption/Readme.md) - password hashing and JSON Web Tokens.
+- [Forms](Forms/Readme.md) - typed input objects and field validation.
+- [Framework](Framework/Readme.md) - application bootstrap, configuration, providers, authentication, and middleware.
+- [Mail](Mail/Readme.md) - mailables, recipients, and transports.
+- [Models](Models/Readme.md) - explicit response and data projections.
+- [Router](Router/Readme.md) - controllers, HTTP routes, WebSocket actions, middleware, and servers.
+- [Storage](Storage/Readme.md) - files, directories, and image data.
+- [Support](Support/Readme.md) - shared types, utilities, and prototype helpers.
+- [Testing](Testing/Readme.md) - application-aware HTTP and WebSocket test helpers.
+- [Validation](Validation/Readme.md) - built-in and custom validation rules.
+- [Angular](Frontend/Angular/Readme.md) - Angular form integration.
+- [Browser WebSockets](Frontend/Websockets/Readme.md) - the Typetron WebSocket browser client.
+
+## Working in This Repository
+
+- Treat each capitalized source directory as a framework module.
+- Use the nearest module barrel or the documented `@Typetron/<Module>` path for public imports.
+- Look for corresponding behavior tests under `tests/<Module>` before changing an implementation.
+- Do not edit `build/`; it is generated by `npm run build`.
+- Keep module documentation aligned with public behavior. Update the relevant `Readme.md` when an API, default, error, or example changes.
+- Keep documentation examples short and executable in shape. Do not document planned or commented-out features as available.

package/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/Cache/Readme.md

@@ -0,0 +1,63 @@
+# Cache
+
+- [Introduction](#introduction)
+- [Using a Cache Store](#using-a-cache-store)
+- [Retrieving and Remembering Values](#retrieving-and-remembering-values)
+- [Available Stores](#available-stores)
+- [Removing Values](#removing-values)
+
+## Introduction
+
+Typetron provides one cache contract for values stored in memory, on disk, or in the configured database. Each store supports the same
+asynchronous operations, so application code may depend on `Cache` without knowing where values are kept.
+
+## Using a Cache Store
+
+The `CacheProvider` binds the configured store to the `Cache` class. A store may also be constructed directly when no application container
+is available:
+
+```ts
+import { MemoryStore } from '@Typetron/Cache'
+
+const cache = new MemoryStore()
+
+await cache.set('user:1', {name: 'John'}, 60)
+const user = await cache.get<{name: string}>('user:1')
+```
+
+The optional duration passed to `set` is measured in seconds. Omitting it keeps the value until it is removed or the store is flushed.
+
+## Retrieving and Remembering Values
+
+The `get` method accepts either a value or a function as its fallback. Use `remember` when the fallback should also be stored:
+
+```ts
+const users = await cache.remember('users', async () => {
+    return [{id: 1, name: 'John'}]
+}, 300)
+```
+
+The fallback is evaluated only when the key is unavailable. `get` returns `undefined` when no cached value or fallback is provided.
+
+## Available Stores
+
+`MemoryStore` keeps values in the current process. `FileStore` hashes each key and stores its serialized value below a configured directory.
+`DatabaseStore` stores serialized values in a table and creates that table when it first writes a value.
+
+The application-level `CacheConfig` supports the `memory`, `file`, and `database` drivers. The `CacheProvider` creates the selected
+implementation.
+
+> Note: Memory cache values disappear when the process exits. File and database stores persist values, but their values must be JSON
+> serializable.
+
+## Removing Values
+
+Use `delete` to remove one key or `flush` to clear the entire store:
+
+```ts
+await cache.delete('user:1')
+await cache.flush()
+```
+
+Calling `has` checks whether a key is present. Expired memory values are removed during this check, while persisted stores enforce
+expiration when values are read.

package/Container/Readme.md

@@ -0,0 +1,95 @@
+# Service Container
+
+- [Introduction](#introduction)
+- [Resolving Classes](#resolving-classes)
+- [Binding Values](#binding-values)
+- [Dependency Injection](#dependency-injection)
+- [Scopes and Child Containers](#scopes-and-child-containers)
+- [Custom Resolvers](#custom-resolvers)
+
+## Introduction
+
+The service container constructs classes and resolves their dependencies. Typetron uses it for controllers, providers, middleware, and other
+framework services, but it may also resolve application classes directly.
+
+## Resolving Classes
+
+Concrete classes require no manual registration. Pass the constructor to `get` and the container will build it:
+
+```ts
+import { Container } from '@Typetron/Container'
+
+class UserRepository {}
+
+const container = new Container()
+const users = container.get(UserRepository)
+```
+
+Classes use singleton scope by default, so subsequent calls return the same resolved instance.
+
+## Binding Values
+
+Use `set` when an abstraction, symbol, or string should resolve to a particular value:
+
+```ts
+abstract class StorageContract {}
+
+class LocalStorage extends StorageContract {}
+
+container.set(StorageContract, new LocalStorage())
+container.set('appName', 'Typetron')
+
+const storage = container.get(StorageContract)
+```
+
+A missing string binding throws `No instance found for '<name>'`.
+
+## Dependency Injection
+
+Constructor types are resolved automatically. The `@Inject` decorator provides property injection and may name an explicit binding:
+
+```ts
+import { Inject, Injectable } from '@Typetron/Container'
+
+@Injectable()
+class UserService {
+    constructor(public users: UserRepository) {}
+}
+
+class UserController {
+    @Inject()
+    users: UserService
+
+    @Inject('appName')
+    appName: string
+}
+
+const controller = container.get(UserController)
+```
+
+Decorator-based injection requires TypeScript decorator metadata to be enabled, as it is in this repository's `tsconfig.json`.
+
+## Scopes and Child Containers
+
+Pass a `Scope` to `@Injectable` when the default singleton lifetime is not appropriate:
+
+```ts
+import { Injectable, Scope } from '@Typetron/Container'
+
+@Injectable(Scope.TRANSIENT)
+class Operation {}
+
+const first = container.get(Operation)
+const second = container.get(Operation)
+```
+
+`first` and `second` are different instances. `REQUEST` services are isolated to request containers, while `CONNECTION` services may live in
+a connection container and be reused by its request children. Create those boundaries with `createChildContainer('connection')` and
+`createChildContainer('request')`.
+
+## Custom Resolvers
+
+Extend `BaseResolver` to resolve values the default class resolver cannot construct. Add the resolver near the beginning of
+`container.resolvers` when it should take precedence, and implement `canResolve` and `resolve`.
+
+> Note: A resolver may return a promise. In that case, callers must await the value returned by `container.get`.

package/Database/Readme.md

@@ -0,0 +1,139 @@
+# Database
+
+- [Introduction](#introduction)
+- [Configuration](#configuration)
+- [Queries and Entities](#queries-and-entities)
+- [Relationships](#relationships)
+- [Migrations and Seeders](#migrations-and-seeders)
+
+## Introduction
+
+The Database module contains Typetron's connection layer, SQL query builder, schema drivers, and entity ORM. SQLite and MySQL use the same
+`Query` and `Entity` APIs.
+
+## Configuration
+
+Applications configure the active driver through `DatabaseConfig` and register `DatabaseProvider`. Outside an application, assign
+`Query.connection` before creating queries:
+
+```ts
+import { Connection, Query, SqliteDriver } from '@Typetron/Database'
+import { DatabaseConfig } from '@Typetron/Framework'
+
+export const config = new DatabaseConfig({
+    driver: 'sqlite',
+    migrationsDirectory: 'Database/migrations',
+    seedersDirectory: 'Database/seeders',
+})
+
+Query.connection = new Connection(new SqliteDriver(':memory:'))
+```
+
+The built-in SQLite driver reads `process.env.database` and otherwise uses `database.sqlite`. The MySQL driver reads the database host,
+user, password, and database environment values. All queries and entities use the static `Query.connection`.
+
+## Queries and Entities
+
+Start a query with `Query.table`, or extend `Entity` and decorate mapped properties. The following example defines an entity and exercises
+both APIs:
+
+```ts
+import {
+    Column,
+    CreatedAt,
+    Entity,
+    HasMany,
+    Options,
+    PrimaryColumn,
+    Query,
+    Relation,
+    UpdatedAt,
+} from '@Typetron/Database'
+import { Post } from '../Entities/Post'
+
+@Options({table: 'users'})
+class User extends Entity {
+    @PrimaryColumn()
+    id: number
+
+    @Column()
+    name: string
+
+    @Column()
+    email: string
+
+    @CreatedAt()
+    createdAt: Date
+
+    @UpdatedAt()
+    updatedAt: Date
+
+    @Relation(() => Post, 'author')
+    posts: HasMany<Post>
+}
+
+const id = await Query.table('users').insertOne({name: 'John'})
+const user = await User.create({
+    name: 'Jane',
+    email: 'jane@example.com',
+})
+
+const users = await User
+    .whereLike('email', '%@example.com')
+    .orderBy('name', 'ASC')
+    .get()
+
+user.name = 'Janet'
+await user.save()
+```
+
+The query builder supports selection, joins, grouping, ordering, limits, aggregates, subqueries, and common `where` variants. Use `first`,
+`insert`, `insertOne`, `update`, and `delete` to execute work; `insertOne` resolves to the identifier supplied by the active driver.
+
+Without `@Options`, an entity table defaults to the lowercase class name. `@Column('column_name')` maps another column name, while
+`@JSONColumn` serializes objects as JSON. Use `find` or `first` when absence is expected; `findOrFail` throws `EntityNotFoundError`.
+`firstOrNew` returns an unsaved entity, while `firstOrCreate` persists it.
+
+## Relationships
+
+Typetron supports `BelongsTo`, `HasOne`, `HasMany`, and `BelongsToMany`. Declare both sides with `@Relation`, naming the inverse property:
+
+The `User.posts` property above pairs with a `Post.author: BelongsTo<User>` relation whose inverse name is `posts`. Load the relation with
+`User.with('posts').get()`, or use `User.withCount('posts').get()` to add a `postsCount` value.
+
+`with` accepts nested relation paths and constrained relation queries. `withCount` places the loaded count on the corresponding
+`<relation>Count` property.
+
+## Migrations and Seeders
+
+Migration classes implement `up` and `down` with the provided connection. Seeders implement `run` against the active connection:
+
+```ts
+import { Query } from '@Typetron/Database'
+import { Migration } from '@Typetron/Database/Migrations'
+import { Seeder } from '@Typetron/Database/Seeders'
+
+export class CreateUsersTable extends Migration {
+    async up() {
+        await this.connection.runRaw(
+            'CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)'
+        )
+    }
+
+    async down() {
+        await this.connection.runRaw('DROP TABLE users')
+    }
+}
+
+export class UserSeeder extends Seeder {
+    async run() {
+        await Query.table('users').insert({name: 'John'})
+    }
+}
+```
+
+`Migrator.migrate` discovers pending TypeScript files and records batches. `rollback(steps)` and `reset` invoke migration `down` methods.
+`SeederManager.seed` discovers TypeScript seeder files and runs them.
+
+> Warning: `reset` reverses migrations against the active database. `migrate({fresh: true})` clears only the migration history; it does not
+> drop existing application tables before rerunning migrations.

package/Encryption/Readme.md

@@ -0,0 +1,54 @@
+# Encryption
+
+- [Introduction](#introduction)
+- [Hashing Passwords](#hashing-passwords)
+- [Signing Tokens](#signing-tokens)
+- [Verifying Tokens](#verifying-tokens)
+
+## Introduction
+
+The Encryption module wraps password hashing and JSON Web Token operations in promise-based services that can be resolved through Typetron's
+container.
+
+## Hashing Passwords
+
+Use `Crypt.hash` before storing a password and `Crypt.compare` when checking a submitted value:
+
+```ts
+import { Crypt } from '@Typetron/Encryption'
+
+const crypt = new Crypt()
+const password = await crypt.hash('secret', 12)
+const matches = await crypt.compare('secret', password)
+```
+
+The second argument to `hash` is the bcrypt salt-round count. Both operations reject when bcrypt cannot process the supplied value.
+
+## Signing Tokens
+
+The `JWT` service exposes the asynchronous form of `jsonwebtoken.sign`:
+
+```ts
+import { JWT } from '@Typetron/Encryption'
+
+const jwt = new JWT()
+const token = await jwt.sign(
+    {sub: 1},
+    process.env.APP_SECRET!,
+    {expiresIn: '1h'}
+)
+```
+
+Payload and signing options follow the `jsonwebtoken` package.
+
+## Verifying Tokens
+
+Pass the token and the same public key or secret to `verify`:
+
+```ts
+const payload = await jwt.verify<number>(token, process.env.APP_SECRET!)
+
+console.log(payload.sub)
+```
+
+The promise resolves to the decoded payload, including `sub`, `iat`, and `exp`, or rejects when the token is invalid or expired.

package/Forms/Readme.md

@@ -0,0 +1,79 @@
+# Forms
+
+- [Introduction](#introduction)
+- [Defining Forms](#defining-forms)
+- [Filling Forms](#filling-forms)
+- [Validating Forms](#validating-forms)
+- [Optional Fields](#optional-fields)
+
+## Introduction
+
+Forms describe the input an application accepts. A form declares its fields, applies Validation module rules, and exposes only those fields
+when it is filled or serialized.
+
+## Defining Forms
+
+Extend `Form` and decorate each accepted property with `@Field`. Apply validation with `@Rules`:
+
+```ts
+import { Field, Form, Rules } from '@Typetron/Forms'
+import { Email, MinLength, Required } from '@Typetron/Validation'
+
+class UserForm extends Form {
+    @Field()
+    @Rules(Required, MinLength(3))
+    name: string
+
+    @Field()
+    @Rules(Required, Email)
+    email: string
+}
+```
+
+`@Field('externalName')` may be used when the exposed field name differs from the property name.
+
+## Filling Forms
+
+The `fill` method copies decorated fields from an input object and ignores other properties:
+
+```ts
+const form = new UserForm()
+
+form.fill({
+    name: 'John',
+    email: 'john@example.com',
+})
+
+const value = form.value()
+```
+
+`value` and `toJSON` return an object containing all declared fields. `validated` returns the truthy fields that do not currently have
+validation errors.
+
+## Validating Forms
+
+Call `valid` after filling the form:
+
+```ts
+if (!form.valid()) {
+    console.log(form.errors)
+}
+```
+
+Errors are grouped first by field name and then by rule identifier, such as `required` or `email`.
+
+## Optional Fields
+
+Use `Optional` before other constraints when a missing value is allowed:
+
+```ts
+import { MinLength, Optional } from '@Typetron/Validation'
+
+class ProfileForm extends Form {
+    @Field()
+    @Rules(Optional, MinLength(10))
+    biography?: string
+}
+```
+
+A value of `undefined` or `null` skips all rules for an optional field. An empty string is still validated by the remaining rules.

package/Framework/Readme.md

@@ -0,0 +1,138 @@
+# Application Framework
+
+- [Introduction](#introduction)
+- [Creating an Application](#creating-an-application)
+- [Configuration](#configuration)
+- [Providers and Middleware](#providers-and-middleware)
+- [Authentication](#authentication)
+- [Automatic Parameter Resolution](#automatic-parameter-resolution)
+- [Accessing Services](#accessing-services)
+
+## Introduction
+
+The Framework module bootstraps a Typetron application. It loads configuration, prepares the service container, registers providers and
+parameter resolvers, and starts the selected HTTP and WebSocket servers.
+
+## Creating an Application
+
+Use `Application.create` with the application's root directory, then start its server:
+
+```ts
+import {
+    AppConfig,
+    Application,
+    AuthConfig,
+    CacheProvider,
+    DatabaseProvider,
+    MailProvider,
+} from '@Typetron/Framework'
+import { User } from './Entities/User'
+
+export const appConfig = new AppConfig({
+    environment: 'development',
+    server: 'node',
+    port: 3000,
+    providers: [DatabaseProvider, CacheProvider, MailProvider],
+})
+
+export const authConfig = new AuthConfig({
+    entity: User,
+    identityColumn: 'id',
+    signature: process.env.APP_SECRET!,
+    duration: 3600,
+    saltRounds: 12,
+})
+
+const app = await Application.create(process.cwd())
+app.startServer()
+```
+
+In a real application, each config instance is the default export of a TypeScript file in `config`. Configuration loads before
+`Application.create` resolves. The second argument may select another config directory.
+
+## Configuration
+
+The module includes `AppConfig`, `AuthConfig`, `CacheConfig`, `DatabaseConfig`, and `MailConfig`. Constructor values replace defaults when
+the application loads each file.
+
+`AppConfig.server` selects the Node or uWebSockets HTTP server. A configured `websocketsPort` starts the separate WebSocket provider. Static
+assets are served when `staticAssets` entries are present.
+
+Authentication configuration must provide a signing `signature`. If it is missing, application creation throws an error stating that
+`APP_SECRET` is not set up.
+
+## Providers and Middleware
+
+Providers bind application services. Middleware surrounds requests and may be global, HTTP-only, WebSocket-only, or attached by the Router:
+
+```ts
+import { AppConfig, Provider } from '@Typetron/Framework'
+import { RequestHandler } from '@Typetron/Router'
+import { Request } from '@Typetron/Router/Http'
+import { HttpMiddleware } from '@Typetron/Router/Http/Middleware'
+
+class SearchService {}
+
+class SearchProvider extends Provider {
+    register() {
+        this.app.set(SearchService, new SearchService())
+    }
+}
+
+class ResponseHeader extends HttpMiddleware {
+    async handle(request: Request, next: RequestHandler) {
+        const response = await next(request)
+        response.setHeader('x-powered-by', 'Typetron')
+        return response
+    }
+}
+
+export const config = new AppConfig({
+    port: 3000,
+    providers: [SearchProvider],
+    middleware: {
+        global: [],
+        http: [ResponseHeader],
+        websocket: [],
+    },
+})
+```
+
+Typetron includes providers for database, cache, mail, and WebSockets, together with `AuthMiddleware`, `CorsMiddleware`, and
+`StaticAssetsMiddleware`.
+
+## Authentication
+
+The `Auth` service signs and verifies user tokens. Your user may extend the provided `User` entity or implement `Authenticatable` by naming
+its identity, username, and password columns.
+
+Protect an HTTP controller with `AuthMiddleware`, then resolve the current user with `@AuthUser`:
+
+```ts
+import { AuthUser, User } from '@Typetron/Framework/Auth'
+import { AuthMiddleware } from '@Typetron/Framework/Middleware'
+import { Controller, Get, Middleware } from '@Typetron/Router'
+
+@Controller('account')
+@Middleware(AuthMiddleware)
+class AccountController {
+    @Get('me')
+    me(@AuthUser() user: User) {
+        return user
+    }
+}
+```
+
+The middleware accepts a bearer token from the `Authorization` header or a `token` field in the body. Invalid or expired tokens produce an
+unauthenticated HTTP response.
+
+## Automatic Parameter Resolution
+
+Application bootstrap registers resolvers for forms, entities, and authenticated users. A controller parameter extending `Form` is filled
+from the request body and files, then validated; failure produces status `422`. An entity parameter is loaded from a route parameter named
+after its class.
+
+## Accessing Services
+
+An `Application` is also the root container. Resolve services with `app.get`, or use `App.get` after creation. For example, `App.get(Cache)`
+returns the store registered by `CacheProvider`.

package/Frontend/Angular/Readme.md

@@ -0,0 +1,68 @@
+# Typetron Angular
+
+- [Introduction](#introduction)
+- [Installation](#installation)
+- [Building Angular Forms](#building-angular-forms)
+- [Validation](#validation)
+
+## Introduction
+
+The `@typetron/angular` package turns a Typetron `Form` class into an Angular reactive `FormGroup`. Backend field names, initial values, and
+validation rules can therefore be reused by an Angular application.
+
+## Installation
+
+Install the package with Angular's reactive forms dependencies:
+
+```bash
+npm install @typetron/angular @angular/forms
+```
+
+The package expects compatible `@angular/core`, `@angular/common`, and `@angular/forms` packages, together with `@typetron/framework`.
+
+## Building Angular Forms
+
+Define the form with Typetron decorators, then pass its class to `FormBuilder.build`:
+
+```ts
+import { Component } from '@angular/core'
+import { ReactiveFormsModule } from '@angular/forms'
+import { FormBuilder } from '@typetron/angular'
+import { Field, Form, Rules } from '@Typetron/Forms'
+import { Email, Required } from '@Typetron/Validation'
+
+class UserForm extends Form {
+    @Field()
+    @Rules(Required)
+    name: string
+
+    @Field()
+    @Rules(Required, Email)
+    email: string
+}
+
+@Component({
+    imports: [ReactiveFormsModule],
+    template: `<form [formGroup]="form"></form>`,
+})
+export class UserEditor {
+    form = FormBuilder.build(UserForm)
+}
+```
+
+The resulting `FormGroup` contains one control for every `@Field` in `UserForm`.
+
+## Validation
+
+Each Angular control delegates validation to the corresponding Typetron `FormField`. Validation failures are returned using the Typetron
+rule identifiers and messages.
+
+```ts
+const email = this.form.controls.email
+
+email.setValue('invalid')
+console.log(email.errors?.email)
+```
+
+> Note: The builder creates a new Typetron form to obtain default field values. Set defaults on the form class before calling
+`FormBuilder.build`.