@typetron/framework 0.5.29 → 0.5.31

package/Frontend/Websockets/Readme.md

@@ -0,0 +1,96 @@
+# Typetron WebSockets
+
+- [Introduction](#introduction)
+- [Installation](#installation)
+- [Using the Connection](#using-the-connection)
+- [Errors and Reconnection](#errors-and-reconnection)
+- [Message Format](#message-format)
+
+## Introduction
+
+The `@typetron/websockets` package is a browser client for Typetron WebSocket actions. It queues outgoing actions until the connection
+opens, exposes responses as RxJS observables, and correlates requests by ID.
+
+## Installation
+
+Install the package and RxJS:
+
+```bash
+npm install @typetron/websockets rxjs
+```
+
+The client requires the browser `WebSocket` API and a module-aware frontend build.
+
+## Using the Connection
+
+Construct `Websocket` with the server URL. Use `on` for a response stream, `emit` for a one-way action, or `request` to await one correlated
+response:
+
+```ts
+import { Websocket } from '@typetron/websockets'
+
+interface User {
+    id: number
+    name: string
+}
+
+const socket = new Websocket('ws://localhost:3001')
+
+const subscription = socket.on<User>('users.updated').subscribe(user => {
+    console.log(user.name)
+})
+
+socket.emit('users.save', {
+    body: {name: 'John'},
+})
+
+const user = await socket.request<User>('users.save', {
+    body: {name: 'John'},
+})
+
+socket.onError({except: ['health.check']}).subscribe(response => {
+    console.error(response.action, response.message)
+})
+
+socket.onConnect(() => console.log('connected'))
+socket.onDisconnect(() => console.log('disconnected'))
+```
+
+The optional message may contain `body` and `parameters`. Actions emitted before the connection opens remain queued. `request` resolves with
+the response's `message`, while an error response rejects it. Unsubscribe from RxJS listeners when they are no longer needed.
+
+## Errors and Reconnection
+
+Action errors reach the corresponding listener and the shared `onError` stream. The optional `except` list suppresses action names from that
+shared stream.
+
+When the browser socket closes, the client invokes the disconnect callback, resets its outgoing queue, and attempts to reconnect after one
+second. `isConnected` is `true` only while the underlying socket is open.
+
+## Message Format
+
+Actions sent to the server use this shape:
+
+```json
+{
+    "$id": "request-id",
+    "action": "users.save",
+    "message": {
+        "body": {"name": "John"},
+        "parameters": [1]
+    }
+}
+```
+
+Responses use the same ID and action name:
+
+```json
+{
+    "$id": "request-id",
+    "action": "users.save",
+    "status": "OK",
+    "message": {"id": 1, "name": "John"}
+}
+```
+
+The status is `OK` or `Error`.

package/Mail/Readme.md

@@ -0,0 +1,99 @@
+# Mail
+
+- [Introduction](#introduction)
+- [Configuration](#configuration)
+- [Defining Mailables](#defining-mailables)
+- [Sending Mail](#sending-mail)
+- [Recipients and Message Details](#recipients-and-message-details)
+- [Transports and Testing](#transports-and-testing)
+
+## Introduction
+
+Typetron provides a fluent API for building and sending email. A `Mailer` collects recipients and message details, while a transport
+performs the delivery.
+
+## Configuration
+
+Applications normally register `MailProvider` and configure `MailConfig`. The `default` mailer may be `memory` or `SendGrid`, and `from`
+supplies the default sender.
+
+```ts
+import { MailConfig } from '@Typetron/Framework'
+
+export default new MailConfig({
+    default: 'memory',
+    from: {
+        email: 'hello@example.com',
+        name: 'Typetron',
+    },
+})
+```
+
+The SendGrid transport also requires `mailers.SendGrid.key`. Constructing `Mailer` without a transport throws an error instructing the
+application to register `MailProvider` or bind a mailer manually.
+
+## Defining Mailables
+
+Represent a reusable message by extending `Mailable` and implementing `content`:
+
+```ts
+import { Mailable } from '@Typetron/Mail'
+
+class OrderShipped extends Mailable {
+    constructor(public orderId: number) {
+        super()
+    }
+
+    content() {
+        return {
+            html: `<h1>Order #${this.orderId} shipped</h1>`,
+            text: `Order #${this.orderId} shipped`,
+        }
+    }
+}
+```
+
+`content` may return a string or an object containing both `html` and `text`.
+
+## Sending Mail
+
+Begin a message with `Mailer.to`, configure it, and call `send`:
+
+```ts
+import { Mailer, MemoryTransport } from '@Typetron/Mail'
+
+const transport = new MemoryTransport()
+const mail = new Mailer({email: 'hello@example.com'}, transport)
+
+const sent = await mail
+    .to('john@example.com')
+    .subject('Your order has shipped')
+    .send(new OrderShipped(1234))
+```
+
+`send` resolves to the transport's `SentMessage` after the transport accepts the message.
+
+## Recipients and Message Details
+
+The pending message supports `from`, `to`, `replyTo`, `cc`, `bcc`, and `subject`. A plain string or `{html, text}` object may be sent
+instead of a custom mailable:
+
+```ts
+await mail
+    .to('john@example.com')
+    .replyTo('support@example.com')
+    .cc('manager@example.com')
+    .send('Welcome to Typetron')
+```
+
+## Transports and Testing
+
+`MemoryTransport` stores sent messages in its public `messages` array and is suitable for tests and local development. `SendGridTransport`
+sends through `@sendgrid/mail` and converts SendGrid failures into an HTTP error.
+
+```ts
+const [message] = transport.messages
+
+console.log(message.to)
+console.log(message.body)
+```

package/Models/Readme.md

@@ -0,0 +1,85 @@
+# Models
+
+- [Introduction](#introduction)
+- [Defining Models](#defining-models)
+- [Transforming Values](#transforming-values)
+- [Nested Models](#nested-models)
+- [Transforming Collections](#transforming-collections)
+
+## Introduction
+
+Models create explicit data projections. They are useful for returning only selected fields from entities or plain objects without modifying
+the original value.
+
+## Defining Models
+
+Extend `Model` and mark every exposed property with `@Field`:
+
+```ts
+import { Field, Model } from '@Typetron/Models'
+
+class UserModel extends Model {
+    @Field()
+    id: number
+
+    @Field()
+    name: string
+}
+```
+
+Properties without `@Field` are omitted. Pass a source name to `@Field('user_name')` when the model property reads from a differently named
+input field.
+
+## Transforming Values
+
+Call the model's static `from` method with an object:
+
+```ts
+const user = UserModel.from({
+    id: 1,
+    name: 'John',
+    password: 'secret',
+})
+```
+
+The result contains `id` and `name`; `password` is not included.
+
+## Nested Models
+
+A property typed as another model is transformed recursively. Use `@FieldMany` for a collection:
+
+```ts
+import { Field, FieldMany, Model } from '@Typetron/Models'
+
+class PostModel extends Model {
+    @Field()
+    title: string
+}
+
+class AuthorModel extends Model {
+    @Field()
+    name: string
+
+    @Field()
+    @FieldMany(PostModel)
+    posts: PostModel[]
+}
+```
+
+Nested values with a `toJSON` method are serialized before they are projected.
+
+## Transforming Collections
+
+`Model.from` accepts a single object, any iterable of objects, or a promise resolving to either form:
+
+```ts
+const users = UserModel.from([
+    {id: 1, name: 'John'},
+    {id: 2, name: 'Jane'},
+])
+
+const promisedUser = await UserModel.from(Promise.resolve({
+    id: 3,
+    name: 'Alex',
+}))
+```

package/Router/Readme.md

@@ -0,0 +1,145 @@
+# Router
+
+- [Introduction](#introduction)
+- [HTTP Controllers](#http-controllers)
+- [Request Data and Responses](#request-data-and-responses)
+- [Middleware and Guards](#middleware-and-guards)
+- [WebSocket Actions](#websocket-actions)
+- [Loading Controllers and Starting Servers](#loading-controllers-and-starting-servers)
+
+## Introduction
+
+The Router maps HTTP routes and WebSocket action names to controller methods. Both transports resolve controllers and typed parameters
+through the service container, and both support middleware and guards.
+
+## HTTP Controllers
+
+Decorate a class with `@Controller` and methods with `@Get`, `@Post`, `@Put`, `@Patch`, or `@Delete`:
+
+```ts
+import {
+    Body,
+    Controller,
+    Get,
+    Post,
+    Query,
+} from '@Typetron/Router'
+import { Http, Response } from '@Typetron/Router/Http'
+import { User } from '../Entities/User'
+
+@Controller('users')
+class UserController {
+    @Get('', 'index')
+    index(@Query('active') active?: string) {
+        return User.where('active', active === 'true').get()
+    }
+
+    @Get(':User', 'read')
+    read(user: User) {
+        return user
+    }
+
+    @Post('', 'create')
+    async create(@Body() data: {name: string}) {
+        const user = await User.create(data)
+        return new Response(user, Http.Status.CREATED)
+    }
+}
+```
+
+These routes are named `users.index`, `users.read`, and `users.create`. Without an explicit method name, the controller method name is used.
+Two routes may share a path when their HTTP methods differ; registering the same path and method twice throws an error.
+
+## Request Data and Responses
+
+Prefix a path segment with `:` to capture it. Primitive `string` and `number` parameters are resolved in route order. `@Body` returns the
+body, while `@Query('name')` reads one query value and converts it to a number when the decorated parameter is typed as `number`.
+
+An entity parameter is loaded when the route parameter uses its class name, such as `:User` above. The Framework resolver calls `User.find`
+and throws `EntityNotFoundError` when no row exists.
+
+Plain controller return values become a status `200` `Response`. Return `Response` directly to control status and headers; convenience
+constructors include `ok`, `notFound`, and `badRequest`.
+
+## Middleware and Guards
+
+Middleware surrounds the action, while guards decide whether resolved parameters may reach it:
+
+```ts
+import {
+    AllowIf,
+    Controller,
+    Get,
+    Middleware,
+    RequestHandler,
+} from '@Typetron/Router'
+import { Guard } from '@Typetron/Router/Guard'
+import { Request } from '@Typetron/Router/Http'
+import { HttpMiddleware } from '@Typetron/Router/Http/Middleware'
+import { User } from '../Entities/User'
+
+class ResponseHeader extends HttpMiddleware {
+    async handle(request: Request, next: RequestHandler) {
+        const response = await next(request)
+        response.setHeader('x-powered-by', 'Typetron')
+        return response
+    }
+}
+
+class CanReadUser extends Guard {
+    async condition(user: User) {
+        return user.id > 0
+    }
+}
+
+@Controller('users')
+@Middleware(ResponseHeader)
+class UserController {
+    @Get(':User', 'read')
+    @AllowIf(CanReadUser)
+    read(user: User) {
+        return user
+    }
+}
+```
+
+Apply `@Middleware` and `@AllowIf` to a controller or method. The default `Guard.onFail` throws HTTP `401 Unauthorized`; override it when
+another failure is required. Transport-specific middleware extends `HttpMiddleware` or `WebsocketMiddleware`, while `GlobalMiddleware` may
+wrap both.
+
+## WebSocket Actions
+
+Use `@Action` for controller methods called by an action name:
+
+```ts
+import { Action, Body, Controller, OnClose, OnOpen } from '@Typetron/Router'
+
+@Controller('users')
+class UserActions {
+    @Action('save')
+    save(@Body() data: {name: string}) {
+        return {id: 1, ...data}
+    }
+
+    @OnOpen
+    opened() {}
+
+    @OnClose
+    closed() {}
+}
+```
+
+The action is registered as `users.save`. Results use the same `Response` wrapper as HTTP routes. Duplicate action names throw during
+registration; `@OnOpen` and `@OnClose` register optional connection lifecycle handlers.
+
+Messages sent or published through the injected `WebSocket` while handling an action retain the incoming request's `$id`. This allows
+clients to correlate every streamed message with the action that initiated it, including when multiple actions run concurrently on one
+connection. Messages initiated outside an action may omit `$id`.
+
+## Loading Controllers and Starting Servers
+
+`Router.loadControllers(directory)` imports TypeScript controller files recursively. Importing decorated classes registers their routes and
+actions.
+
+The Framework starts the Node or uWebSockets HTTP server selected by `AppConfig.server`. Configuring `websocketsPort` starts the separate
+WebSocket provider.

package/Storage/Readme.md

@@ -0,0 +1,83 @@
+# Storage
+
+- [Introduction](#introduction)
+- [Writing and Reading Files](#writing-and-reading-files)
+- [Working With File Objects](#working-with-file-objects)
+- [Listing Files](#listing-files)
+- [Directories and Deletion](#directories-and-deletion)
+- [Image Data](#image-data)
+
+## Introduction
+
+The Storage module provides a small filesystem abstraction used by uploads, migrations, cache files, and static assets. Its asynchronous
+methods operate on paths while `File` carries a file's name and directory.
+
+## Writing and Reading Files
+
+Use `put` to write content and receive a `File` describing the result:
+
+```ts
+import { Storage } from '@Typetron/Storage'
+
+const storage = new Storage()
+const file = await storage.put('storage/users/1.txt', 'John')
+const content = await storage.read(file.path)
+
+console.log(content.toString())
+```
+
+Missing parent directories are created automatically. `read` resolves to a `Buffer`.
+
+## Working With File Objects
+
+A `File` derives its `path` and `extension` from its name and directory:
+
+```ts
+import { File } from '@Typetron/Storage'
+
+const upload = new File('avatar.png', '/tmp/uploads')
+
+console.log(upload.path)
+console.log(upload.extension)
+```
+
+Use `save(file, directory)` to copy an existing file into another directory. The destination directory is created when needed.
+
+## Listing Files
+
+`files(directory)` returns immediate files as `File` instances. Pass `true` as the second argument to include nested directories:
+
+```ts
+const migrations = storage
+    .files('Database/migrations', true)
+    .where('extension', 'ts')
+```
+
+File listing is synchronous internally even though most other storage operations are asynchronous.
+
+## Directories and Deletion
+
+Use `exists`, `makeDirectory`, and `deleteDirectory` for directories. Use `delete` only for file paths:
+
+```ts
+if (await storage.exists(file.path)) {
+    await storage.delete(file.path)
+}
+```
+
+Deleting a missing file has no effect. Passing a directory to `delete` throws an error; use `deleteDirectory` for recursive directory
+removal.
+
+## Image Data
+
+The `fromBase64` helper decodes an image data URL:
+
+```ts
+import { fromBase64 } from '@Typetron/Storage'
+
+const image = fromBase64('data:image/png;base64,iVBORw0KGgo=')
+
+await storage.put(`storage/avatar.${image.extension}`, image.content)
+```
+
+Invalid image data throws `InvalidImage` with the message `The image has an invalid data format`.

package/Support/Readme.md

@@ -0,0 +1,71 @@
+# Support
+
+- [Introduction](#introduction)
+- [Array Helpers](#array-helpers)
+- [String Helpers](#string-helpers)
+- [Number Helpers](#number-helpers)
+- [JSON Parsing](#json-parsing)
+- [Shared Types](#shared-types)
+
+## Introduction
+
+The Support module contains shared TypeScript types and lightweight helpers used throughout Typetron. Importing `@Typetron/Support` also
+installs the framework's array, string, and math prototype extensions.
+
+## Array Helpers
+
+Arrays gain collection-style operations for common filtering and transformation tasks:
+
+```ts
+import '@Typetron/Support'
+
+const users = [
+    {id: 1, name: 'John', active: true},
+    {id: 2, name: 'Jane', active: false},
+]
+
+const names = users.where('active', true).pluck('name')
+const byId = users.groupBy('id')
+```
+
+Other helpers include `first`, `last`, `findWhere`, `whereIn`, `whereNotIn`, `sortBy`, `unique`, `sum`, `mapAsync`, and `forEachAsync`.
+Methods such as `sortBy` and `remove` mutate the original array; filtering and mapping helpers return new arrays.
+
+## String Helpers
+
+Strings may be capitalized or limited, and the `String` constructor can create random values:
+
+```ts
+const title = 'typetron'.capitalize()
+const excerpt = 'A longer description'.limit(10)
+const token = String.randomAlphaNum(24)
+```
+
+`limit` uses `...` by default and counts that ending inside the requested length.
+
+## Number Helpers
+
+`Math.randomInt(min, max)` returns an integer including both boundaries:
+
+```ts
+const dice = Math.randomInt(1, 6)
+```
+
+## JSON Parsing
+
+`JSONSafeParse` returns `undefined` instead of throwing when input is empty or invalid:
+
+```ts
+import { JSONSafeParse } from '@Typetron/Support/utils'
+
+const settings = JSONSafeParse<{theme: string}>('{"theme":"dark"}')
+const invalid = JSONSafeParse('{')
+```
+
+## Shared Types
+
+The module exports reusable types including `Type`, `Constructor`, `Abstract`, `AnyFunction`, `KeysOfType`, `ChildKeys`, and `ChildObject`.
+These types describe constructors and derive child-specific keys or objects without adding runtime behavior.
+
+> Note: Prototype helpers are global after the Support module is imported. Check for an existing helper before adding another extension with
+> the same name.

package/Testing/Readme.md

@@ -0,0 +1,80 @@
+# Testing
+
+- [Introduction](#introduction)
+- [Creating a Test Case](#creating-a-test-case)
+- [Making HTTP Requests](#making-http-requests)
+- [Authentication](#authentication)
+- [Testing WebSocket Actions](#testing-websocket-actions)
+
+## Introduction
+
+`TestCase` boots a Typetron application once, creates an isolated child container before each test, and provides helpers for exercising
+named HTTP routes and WebSocket actions without starting a network server.
+
+## Creating a Test Case
+
+Extend `TestCase` and implement `bootstrapApp`:
+
+```ts
+import { Application } from '@Typetron/Framework'
+import { TestCase } from '@Typetron/Testing/TestCase'
+
+class UsersTest extends TestCase {
+    bootstrapApp() {
+        return Application.create(process.cwd())
+    }
+}
+```
+
+The base `before` hook re-registers `DatabaseProvider` and replaces password hashing with a deterministic test double. Call the inherited
+lifecycle hook when a test framework override would otherwise bypass it.
+
+## Making HTTP Requests
+
+HTTP helpers resolve the route by its registered name rather than by URL:
+
+```ts
+const response = await this.get<{id: number, name: string}>('users.read')
+
+console.log(response.status)
+console.log(response.body)
+```
+
+Use `post`, `patch`, `put`, or `delete` with a body and optional headers. For named routes with parameters, pass a tuple to those helpers:
+
+```ts
+await this.put(
+    ['users.update', {User: 1}],
+    {name: 'John'},
+)
+```
+
+A route name that is not registered throws `Route '<name>' not found`. HTTP errors are converted to normal `Response` objects so assertions
+may inspect their status and body.
+
+## Authentication
+
+Use `actingAs` with a user entity or `loginById` with an identity. Subsequent HTTP helpers add the generated bearer token automatically:
+
+```ts
+await this.actingAs(user)
+const response = await this.get('users.me')
+```
+
+The older `login(user)` helper is deprecated; prefer `actingAs` or `loginById`.
+
+## Testing WebSocket Actions
+
+Call `action` with the registered action name and optional message data:
+
+```ts
+this.on<{id: number}>('users.created', user => {
+    console.log(user.id)
+})
+
+const response = await this.action<{id: number}>('users.create', {
+    body: {name: 'John'},
+})
+```
+
+The WebSocket object is mocked. Calls to `send` and `publishAndSend` are delivered to callbacks registered with `on`.