@typetron/framework 0.5.30 → 0.5.32

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,188 @@
+# Storage
+
+- [Introduction](#introduction)
+- [Configuring Disks](#configuring-disks)
+- [Using Disks](#using-disks)
+- [Writing and Reading](#writing-and-reading)
+- [Listing Files](#listing-files)
+- [Uploads and Metadata](#uploads-and-metadata)
+- [URLs and Visibility](#urls-and-visibility)
+- [Scoped and Read-Only Disks](#scoped-and-read-only-disks)
+- [Testing](#testing)
+- [Custom Drivers](#custom-drivers)
+- [Framework Filesystem](#framework-filesystem)
+- [Image Data](#image-data)
+
+## Introduction
+
+Storage provides one asynchronous API for local files, AWS S3, and S3-compatible object stores. Applications work with logical keys relative
+to a configured disk rather than operating-system paths. `Storage` resolves named disks lazily and forwards methods to the default disk.
+
+Each disk wraps a `StorageDriver`. Drivers translate portable operations to a backend while `StorageDisk` supplies shared conveniences such
+as uploads, JSON decoding, URL generation, and testing assertions.
+
+## Configuring Disks
+
+```ts
+import { StorageConfig } from '@Typetron/Framework'
+
+export default new StorageConfig({
+    default: 'local',
+    disks: {
+        local: {
+            driver: 'local',
+            root: 'storage/app',
+            url: '/storage',
+        },
+        s3: {
+            driver: 's3',
+            bucket: process.env.AWS_BUCKET!,
+            region: process.env.AWS_REGION!,
+        },
+        objects: {
+            driver: 's3',
+            bucket: process.env.OBJECT_BUCKET!,
+            region: process.env.OBJECT_REGION!,
+            endpoint: process.env.OBJECT_ENDPOINT,
+            forcePathStyle: true,
+            credentials: {
+                accessKeyId: process.env.OBJECT_ACCESS_KEY!,
+                secretAccessKey: process.env.OBJECT_SECRET_KEY!,
+            },
+        },
+    },
+})
+```
+
+AWS disks use the SDK's default credential chain when `credentials` is omitted. The S3 driver is loaded only when an S3 disk is resolved;
+applications using it must install `@aws-sdk/client-s3` and `@aws-sdk/s3-request-presigner`.
+
+## Using Disks
+
+Register `StorageProvider`, then inject or resolve `Storage`. Methods on `Storage` target the default disk; `disk` selects another
+configured
+disk. `build` creates an uncached on-demand disk.
+
+```ts
+await storage.put('users/1.txt', 'John')
+await storage.disk('s3').put('backups/data.json', '{}')
+
+const temporary = storage.build({driver: 'local', root: '/tmp/exports'})
+```
+
+Named disks are constructed once and cached. Use `forget(name)` to discard a cached disk so its next lookup rebuilds it.
+
+## Writing and Reading
+
+`put` accepts a string, `Buffer`, or Node `Readable` and returns a lightweight `File`. `read` returns a `Buffer`; use `readStream` for large
+objects and `json` for JSON content.
+
+```ts
+const file = await storage.put('users/1.json', JSON.stringify({name: 'John'}), {
+    mimeType: 'application/json',
+    visibility: 'private',
+})
+
+const user = await storage.json<{name: string}>(file.key)
+const stream = await storage.readStream(file.key)
+```
+
+Use `copy` and `move` within one disk. Moving copies first and deletes the source only after a successful copy. Cross-disk copies are not
+implicit; stream the source into the destination when that behavior is required.
+
+## Listing Files
+
+`list` is an `AsyncIterable`, so paginated object-store listings do not have to be retained in memory. `files` collects file entries into
+`File` instances.
+
+```ts
+for await (const entry of storage.list('users', {recursive: true})) {
+    console.log(entry.type, entry.key)
+}
+
+const files = await storage.files('users', {recursive: true})
+```
+
+Directories are logical prefixes. Writing `users/1/avatar.jpg` creates required local directories, while S3 stores only the object key.
+`deleteDirectory('users/1')` removes that non-empty prefix recursively; an empty prefix is rejected.
+
+## Uploads and Metadata
+
+HTTP multipart parsing produces `UploadedFile` instances backed by temporary local files. `putFile` streams the upload to its destination.
+
+```ts
+const avatar = request.files.avatar as UploadedFile
+await storage.disk('s3').putFile(`avatars/${user.id}.jpg`, avatar)
+```
+
+Use `stat` for size, last modification, MIME type, ETag, and backend metadata. A `File` may contain metadata already returned by a listing
+or
+write, but Storage does not issue an extra metadata request merely to fill every optional field.
+
+## URLs and Visibility
+
+`url` returns a public URL when the disk supports or configures one. `temporaryUrl` creates an expiring S3 URL. Unsupported operations throw
+`UnsupportedStorageOperation`.
+
+```ts
+const publicUrl = storage.disk('s3').url('avatars/1.jpg')
+const privateUrl = await storage.disk('s3').temporaryUrl('reports/1.pdf', 300)
+await storage.setVisibility('avatars/1.jpg', 'public')
+```
+
+Visibility is `public` or `private`. Local disks map it to file permissions; S3 maps it to object ACLs. Bucket policies may still forbid
+public ACLs.
+
+## Scoped and Read-Only Disks
+
+Composition drivers wrap any named disk without changing its implementation:
+
+```
+disks: {
+    s3: {driver: 's3', bucket: 'app', region: 'eu-central-1'},
+    avatars: {driver: 'scoped', disk: 's3', prefix: 'users/avatars'},
+    assets: {driver: 'read-only', disk: 's3'},
+}
+```
+
+A scoped disk exposes only keys below its prefix. Mutating a read-only disk throws `ReadOnlyStorage`.
+
+## Testing
+
+`fake` replaces a named disk with an isolated in-memory driver:
+
+```ts
+const avatars = storage.fake('avatars')
+await service.uploadAvatar(upload)
+await avatars.assertExists('users/1.jpg')
+await avatars.assertCount('users', 1, true)
+```
+
+## Custom Drivers
+
+Register a driver factory with `extend`. The factory receives its disk configuration, name, and Storage manager and returns a
+`StorageDriver`. Drivers implement backend translation only; shared application conveniences belong on `StorageDisk`.
+
+## Framework Filesystem
+
+`Filesystem` is a separate local operating-system service used by Typetron to load configuration, controllers, entities, migrations,
+seeders, static assets, and file cache data. It is available before `StorageConfig` is loaded, accepts real host paths, and keeps these
+framework paths independent of the application's default object-storage disk.
+
+`Filesystem` is framework-internal and is not the local-disk API intended for applications. Application code should use `Storage` or a
+named disk such as `storage.disk('local')`. Its synchronous `files` method exists only because framework modules are currently discovered
+synchronously during bootstrap; configured storage listings remain asynchronous and backend-neutral.
+
+## 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.