@elysiumjs/styx 0.8.2 → 0.9.1

package/CHANGELOG.md

@@ -1,5 +1,115 @@
 # @elysiumjs/styx
 
+## 0.9.1
+
+### Patch Changes
+
+- Updated dependencies [[`651a755`](https://github.com/na2axl/elysiumjs/commit/651a7557173ce2c6155bcfa8d90cf388ac419821)]:
+  - @elysiumjs/core@0.12.0
+  - @elysiumjs/runtime-bun@0.1.1
+
+## 0.9.0
+
+### Minor Changes
+
+- [#10](https://github.com/na2axl/elysiumjs/pull/10) [`0057b67`](https://github.com/na2axl/elysiumjs/commit/0057b67df0e3abecab8a9accff6b55a6a64c21df) Thanks [@na2axl](https://github.com/na2axl)! - `styx routes:generate` writes the route types of an app to `src/routes.gen.ts`: an `AppRoutes` type for Eden (`treaty<AppRoutes>(url)`), built from the controllers of every module. Request types come from the method parameters decorated with `@Http.param`, `@Http.query` and `@Http.body`, and response types from the method return types. The file holds types only; requests are served by the decorated controllers. New projects run the command in their `typecheck` script and keep the file out of git.
+
+  `Http.describe(controller)` reports the routes of an HTTP controller, and `Application.moduleGraph()` builds the module graph of an app class without booting it.
+
+- [#9](https://github.com/na2axl/elysiumjs/pull/9) [`8a30cc3`](https://github.com/na2axl/elysiumjs/commit/8a30cc35a82438fe9da08fcea91ef9b46f3430f1) Thanks [@na2axl](https://github.com/na2axl)! - Styx is a global command: install it with `bun add -g @elysiumjs/styx`, then run `styx create my-app` to start a project (template, runtime, modules, plugins and features, from prompts or options). Inside a project, the global `styx` hands every command to the project's own Styx. The code generators (`make:*`, `module:*`) run without starting the app, and new projects install Styx as a dev dependency.
+
+  When a project installs `@elysiumjs/hephaestus` as a dev dependency, Styx provides its commands. Standalone `styx` executables are built with Hephaestus (`bun run build:bin`), with the stubs and templates embedded. The Hephaestus asset embedder includes dotfiles.
+
+  `create-elysium` runs `styx create`; the project templates live in `@elysiumjs/styx`.
+
+- [#16](https://github.com/na2axl/elysiumjs/pull/16) [`ac96e55`](https://github.com/na2axl/elysiumjs/commit/ac96e55874b0ffe350b287c4278cd85afecb7576) Thanks [@na2axl](https://github.com/na2axl)! - Redis, databases, logs, jobs and builds on Bun, Node.js and Cloudflare Workers.
+
+  Breaking:
+
+  - The level shortcuts of `InteractsWithConsole` (`info`, `success`, `warning`, `error` and `debug`) write a tag (`[I]`, `[S]`, `[W]`, `[E]` and `[D]`, in color) before the message, which `InteractsWithConsole.useTags()` changes. `trace()` writes to stderr.
+  - Outside Bun, a Drizzle connection needs a `driver`. Without one, the `connection` and `client` props are a Bun SQL connection, which is only available on Bun; elsewhere the connection throws `MissingDriverError`, which names the drivers.
+
+  Added:
+
+  - Redis adapters (`@elysiumjs/redis`): `ioredis(create)` plugs an ioredis client into the Redis port on Node.js, and `upstash({ token, url?, fetch? })` talks to Upstash over its REST API, for Workers (no pub/sub). `bunRedis` explains which adapter to use when it runs outside Bun.
+  - Drizzle drivers (`@elysiumjs/mnemosyne-drizzle`): a `DrizzleDriver` port set with the `driver` prop of a connection, and drivers on subpaths so that only the chosen database client is imported: `/bun-sql` (`bunSql()`), `/postgres-js` (`postgresJs()`), `/node-postgres` (`nodePostgres()`) and `/hyperdrive` (`hyperdrive({ binding, driver })`, a client per Worker invocation over a Cloudflare Hyperdrive binding). `DrizzleModule` closes connections through their driver, and `migration:run` runs on any driver.
+  - `InteractsWithConsole.write()` and `Runtime.write()` take the level of the line (`OutputLevel`), which the level shortcuts pass. On Cloudflare Workers, a line is written with the console method of its level, so Workers Logs keep it.
+  - `JsonConsoleLogger` (`@elysiumjs/hermes`): JSON lines through the console of the runtime (warnings and errors on stderr), with levels, error serialization and `child()`. `HermesModule.with({ transport: 'console' | 'pino' })` picks it, and it is the default on Workers. `RequestLogInterceptor` writes one structured line per request: method, route, status, duration, client address and request id.
+  - Scheduled jobs (`@elysiumjs/heracles`): `@Schedule(cron, { timezone, args })` on a job class, a five-field cron parser (`Cron`, with lists, ranges, steps and names), and a `Scheduler` that dispatches the jobs on time on Bun and Node.js, taking a Redis lock per tick when a Redis connection is set. The `heracles:schedule` command runs it.
+  - `@elysiumjs/heracles-workers`: `CloudflareQueueTransport` sends jobs to a Cloudflare Queue (dispatch delays become `delaySeconds`), and `HeraclesWorkersModule` consumes them in the Worker's `queue` handler (ack on success, retry with a delay up to the job's retries) and dispatches the `@Schedule()` jobs whose expression is the cron of a trigger.
+  - Queue handlers (`@elysiumjs/runtime-workers`) can settle a message themselves with `ack()` or `retry({ delaySeconds })`; the messages they leave are acked when no handler failed on them.
+  - `styx build --target node` (`@elysiumjs/hephaestus`) bundles the app into one ES module for Node.js, with decorator metadata emitted at build time, run with `node dist/server.js serve`. `styx build --target workers` runs from the CLI, resolves packages to their browser entry, and leaves Node.js modules imported by bare names to workerd (`nodejs_compat`).
+  - `styx create` (`@elysiumjs/styx`) takes `--runtime bun|node|workers`, `--database`, `--cache` and `--package-manager bun|npm|pnpm`. Each runtime gets its entry, tsconfig types, scripts and drivers: postgres.js and ioredis on Node.js; Hyperdrive, Upstash, console logs and a `wrangler.jsonc` on Workers.
+
+- [#12](https://github.com/na2axl/elysiumjs/pull/12) [`98a16aa`](https://github.com/na2axl/elysiumjs/commit/98a16aae889d46f7a9fb5573188f4cbe3629dd3b) Thanks [@na2axl](https://github.com/na2axl)! - `createWorker(app)` from `@elysiumjs/runtime-workers` builds an application and returns the handlers a Cloudflare Worker exports: `fetch` serves the routes, `queue` hands each batch to the service methods marked `@Workers.queue(name)`, and `scheduled` calls the methods marked `@Workers.cron(expression)`. Each invocation runs with its own env and execution context: `Workers.env()`, `Workers.context()` and `Workers.binding(name)` read them, and `WorkersModule` provides them, and the bindings it lists, as request-scoped services injected with `@Workers.inject(name)`. `KeyvWorkersKV` stores mnemosyne caches in a KV namespace. `bun run check:wrangler` runs a sample Worker in `wrangler dev`.
+
+  `MnemosyneModule` takes other Keyv stores in `cache.stores`, read with `Cache.store(name)`.
+
+  `styx build --target workers` (Hephaestus `hephaestus:build --target workers`, `WorkersBuilder`) bundles a Worker with its routes compiled ahead of time and refuses a bundle that generates code at runtime.
+
+  In core, `Application.boot()` initialises the modules once, for hosts that handle more than requests; `Kernel.serviceClasses(node)` lists the service classes of a module; console output falls back to `console` where the host has no output streams; and a singleton depending on a request-scoped service throws `ScopeMismatchError` even when it is built outside a request.
+
+### Patch Changes
+
+- [#20](https://github.com/na2axl/elysiumjs/pull/20) [`87299fd`](https://github.com/na2axl/elysiumjs/commit/87299fd9da82d1a408ced1891c0c3d42991444e5) Thanks [@na2axl](https://github.com/na2axl)! - The framework event bus is `Lifecycle`: `Lifecycle.on`, `Lifecycle.once`, `Lifecycle.emit`, `Lifecycle.off`, `@Lifecycle.on()` and `@Lifecycle.once()`, with the `LifecycleEvent` and `LifecycleHandler` types. It carries the framework's own signals (`elysium:error`, app and server lifecycle, heracles queue events) and in-process listeners.
+
+- [#22](https://github.com/na2axl/elysiumjs/pull/22) [`bee66bd`](https://github.com/na2axl/elysiumjs/commit/bee66bdc874b8f23fea356f7d3adf7555a48ca64) Thanks [@na2axl](https://github.com/na2axl)! - Decorators take their main identifier first and their options second.
+
+  - `@Http.controller(path, options)` and the route decorators `@Http.get(path, options)`, `post`, `put`, `patch`, `del`, `head`, `options`, `trace` and `sse`. The path defaults to `/`. `@Http.custom(method, path, options)` takes its method first. The options are `HttpControllerOptions` and `HttpRouteOptions`.
+  - `@Websocket.controller(path, options)`, where the options are those of the websocket server.
+  - `@Flow.controller(name, options)`, and `@Flow.step(name, options)` or `@Flow.step(options)` for a step named after its method.
+  - `@Lifecycle.on(event, options)` and `@Lifecycle.once(event, options)`, like their function forms `Lifecycle.on(event, handler)`.
+  - The styx controller stubs generate the same forms.
+
+- [#13](https://github.com/na2axl/elysiumjs/pull/13) [`1ea417e`](https://github.com/na2axl/elysiumjs/commit/1ea417e3583250bc2f975d795f398b7ff736115d) Thanks [@na2axl](https://github.com/na2axl)! - Hardening of the runtimes, the container and the CLI, checked by a conformance suite that runs on Bun, Node.js and workerd.
+
+  Breaking changes:
+
+  - `Runtime` gains the required `argv()`, `write(stream, text)` and `terminal()` members: core reaches the host's arguments, output streams and terminal only through the runtime. Custom runtimes must implement them.
+  - The third parameter of `InteractsWithConsole.write` is now `'stdout' | 'stderr'`.
+  - The WebSocket options are narrowed to `idleTimeout`, `maxPayloadLength` and `perMessageDeflate`, and the `bun` WebSocket types are replaced by `ElysiumWebSocket`.
+  - Redis connections are `RedisConnection`s, a port any Redis client can implement, instead of `Bun.RedisClient`.
+  - `styx create @scope/name` creates the project in `name/`, and refuses project and module names with upper-case letters.
+  - Queue handlers no longer reject the batch: after the handlers ran, each message is acked or retried on its own. `@Workers.queue(name, { each: true })` receives one message at a time, so a failure retries only that message.
+
+  Fixes:
+
+  - Request-scoped services are destroyed when the request ends, also on failure, and an async `onInit` is awaited. A second dispose of a request scope waits for the one in progress, so a Worker's `waitUntil` covers an async `onDestroy`.
+  - A failed module or service `onInit` no longer breaks later requests: the boot is retried, and the module's event listeners are unwired.
+  - `@elysiumjs/runtime-node` serves through `node:http`, keeping the Host header authoritative.
+  - `styx create` validates names before creating files, ships `.gitignore`, declares the dependencies of created projects and imports their default controllers.
+
+- [#14](https://github.com/na2axl/elysiumjs/pull/14) [`0956186`](https://github.com/na2axl/elysiumjs/commit/0956186db0ca5a83c0a6636aeb2a4c81a0033de4) Thanks [@na2axl](https://github.com/na2axl)! - The request pipeline: problem details, exception filters, interceptors, typed configuration, HTTP security options and an HTTP test client, checked on Bun, Node.js, workerd and AOT-compiled Workers.
+
+  Breaking changes:
+
+  - Error responses are RFC 9457 problem details (`application/problem+json`). Request validation errors answer 422 with an `errors` list of JSON pointers (`problems.validationStatus: 400` keeps 400). Server errors only show their message and stack in development. Thrown statuses (`c.status(...)`) are sent as they are.
+  - Client errors (4xx) are no longer reported to `onError`, the `elysium:error` event or the trace.
+  - `Runtime.serve` may return a handle with `close()`, which the application calls on shutdown.
+  - Request bodies are limited to 1 MiB by default (`http.bodyLimit`), also when chunked.
+  - The environment schema is validated when the app is built or run, with every error reported at once, instead of in the constructor.
+
+  Features:
+
+  - `DomainError`, with `status`, `type`, `title`, `detail` and extensions, and shortcuts such as `DomainError.notFound()`.
+  - Exception filters (`@Catch()`, `filters` on routes, controllers, modules and the app) and interceptors (`interceptors` on the same levels), with `TimingInterceptor`, `TransformInterceptor` and mnemosyne's `CacheInterceptor`.
+  - Typed configuration: `Secret` values, module `envSchema`s merged into the app's, `InvalidEnvironmentError`.
+  - `http` options: CORS, security headers, body limits and trusted proxies (`ctx.ip`). Runtimes report the client address through `clientAddress`.
+  - `createTestingHttpApp` and `createHttpClient` send requests to an app in memory, with `expectStatus()`.
+
+  Fixes:
+
+  - App-level `onRequest` middlewares run in the request scope.
+  - On Workers, the request scope of a streamed response is disposed when the body ends, not when `fetch` returns.
+  - `KeyvWorkersKV.clear()` stays within an operation budget (`maxOperations`).
+  - The Node.js bridge treats a destroyed socket as a client abort.
+  - Heracles performance metrics report through the Redis port (`connection` or `client`), not a Bun client.
+  - `styx routes:generate` names anonymous default controllers after their file; `styx create` pins `@elysiumjs/*` packages to the versions it was released with; invalid names are reported as Elysium errors.
+
+- Updated dependencies [[`6bc48fe`](https://github.com/na2axl/elysiumjs/commit/6bc48febd51f7090c582e73f349eaeff7261241c), [`e9c3d98`](https://github.com/na2axl/elysiumjs/commit/e9c3d98dd2714b69100215f7c8a80046da463148), [`557a3ca`](https://github.com/na2axl/elysiumjs/commit/557a3cab7af8053a8bab9944e492e5022d91aa82), [`ccc3f5b`](https://github.com/na2axl/elysiumjs/commit/ccc3f5bb904d1bf52d8c72ebf7ea8d10f617a8c4), [`6789879`](https://github.com/na2axl/elysiumjs/commit/678987976ecfd46b534b65276e0de3f448977562), [`87299fd`](https://github.com/na2axl/elysiumjs/commit/87299fd9da82d1a408ced1891c0c3d42991444e5), [`bee66bd`](https://github.com/na2axl/elysiumjs/commit/bee66bdc874b8f23fea356f7d3adf7555a48ca64), [`0057b67`](https://github.com/na2axl/elysiumjs/commit/0057b67df0e3abecab8a9accff6b55a6a64c21df), [`632d77b`](https://github.com/na2axl/elysiumjs/commit/632d77b561fc43ade605fb69b06ac1b9b9a2ffc4), [`1ea417e`](https://github.com/na2axl/elysiumjs/commit/1ea417e3583250bc2f975d795f398b7ff736115d), [`0956186`](https://github.com/na2axl/elysiumjs/commit/0956186db0ca5a83c0a6636aeb2a4c81a0033de4), [`fbcc7da`](https://github.com/na2axl/elysiumjs/commit/fbcc7dad127db29da42e7a4a5c2124966731cd88), [`ac96e55`](https://github.com/na2axl/elysiumjs/commit/ac96e55874b0ffe350b287c4278cd85afecb7576), [`98a16aa`](https://github.com/na2axl/elysiumjs/commit/98a16aae889d46f7a9fb5573188f4cbe3629dd3b)]:
+  - @elysiumjs/core@0.11.0
+  - @elysiumjs/runtime-bun@0.1.0
+
 ## 0.8.2
 
 ### Patch Changes

package/README.md

@@ -1,78 +1,89 @@
 # @elysiumjs/styx
 
-CLI tool for Elysium.js framework.
+The command line tool of the Elysium.js framework. It creates projects, generates code and runs your app's commands.
 
 ## Installation
 
+Install it globally to create projects and use it anywhere:
+
 ```bash
-bun install @elysiumjs/styx
+bun add -g @elysiumjs/styx
 ```
 
-## Usage
-
-The `styx` command needs to be run inside an Elysium.js project. It loads `src/app.ts` (or `index.ts`) and starts the exported `Application` subclass.
+Projects also install it as a dev dependency (`styx create` does this). Inside a project, the global `styx` hands every command to the project's own copy, so each project runs the Styx version it was written for.
 
-Add `StyxModule` to the modules of your application to get the commands below. It is only active in development (`NODE_ENV=development`, the default), so the `make:*` and `module:*` commands are absent in production. The `migration:*` commands come from your database module (`DrizzleModule`) and stay available in production.
+Standalone executables, which need neither Bun nor the package files, are built with `bun run build:bin` (current platform) or `bun run build:bin --all` (Linux, macOS and Windows). They embed the code stubs and project templates with Hephaestus.
 
-```ts
-import { Application } from '@elysiumjs/core';
-import { StyxModule } from '@elysiumjs/styx';
+## Creating a project
 
-@Application.register({
-	modules: [StyxModule /* , your other modules */]
-})
-export class App extends Application {}
+```bash
+styx create my-app
 ```
 
-To create new items:
+Without options, it asks for the template (single or multi module), the runtime, the modules, plugins and features. Options skip the prompts:
 
 ```bash
-bun styx make:command [options]
-bun styx make:controller [options]
-bun styx make:job [options]
-bun styx make:middleware [options]
-bun styx make:model [options]
-bun styx make:repository [options]
-bun styx make:service [options]
-bun styx make:validator [options]
+styx create my-app --template multi --modules users,billing --features prettier,hephaestus --git false
 ```
 
-To manage migrations:
+`--install false` writes the files without installing dependencies, `--force` replaces a folder that is not empty, and `--yes` takes the defaults for every option not given. `bun create elysium my-app` runs the same command.
 
-```bash
-bun styx migration:generate [options]
-bun styx migration:run [options]
-```
+## Generating code
 
-To manage modules:
+The generators write files from stubs and never start your app, so they work before the app can boot:
 
 ```bash
-bun styx module:new [options]
-bun styx module:rename [options]
+styx make:command --name SendReport
+styx make:controller --name UserController
+styx make:job --name ImportUsers
+styx make:middleware --name AuthMiddleware
+styx make:model --name User
+styx make:repository --name UserRepository
+styx make:service --name UserService
+styx make:validator --name CreateUser
+styx module:new --name billing
+styx module:rename --module billing --name payments
 ```
 
-To start the Elysium.js project:
+In a multi module project, pass `--module <name>`. Run `styx help <command>` for every option.
 
-```bash
-bun styx serve
-```
+## Typed clients
 
-To execute a custom command:
+`styx routes:generate` writes the route types of the app to `src/routes.gen.ts` (set `routes` in `.elysiumrc` or pass `--out` to change it). The file exports `AppRoutes`, for Eden:
 
-```bash
-bun styx <command>
+```ts
+import type { AppRoutes } from './routes.gen';
+
+import { treaty } from '@elysia/eden';
+
+const api = treaty<AppRoutes>('http://localhost:3000');
+const { data } = await api.users({ id }).get();
 ```
 
-To show all available commands:
+The types come from the controller methods: the parameters decorated with `@Http.param`, `@Http.query` and `@Http.body` give the request types, and the return type gives the response type, so annotate the return type of methods that return different shapes. The file holds types only and is written again by `typecheck` in new projects, so keep it out of git.
+
+## Running the app
+
+Every other command loads the project's app (`src/app.ts` or `index.ts`) and runs there:
 
 ```bash
-bun styx list
+styx serve
+styx migration:generate
+styx migration:run
+styx <your command>
 ```
 
-To get help for a specific command:
+These need `@elysiumjs/styx` in the project's dev dependencies.
+
+## Build tools
+
+When the project installs `@elysiumjs/hephaestus` (as a dev dependency), its `hephaestus:*` commands are available through `styx` without adding anything to the app.
+
+## Listing commands
 
 ```bash
-bun styx help <command>
+styx list
+styx help <command>
 ```
 
 ## Contributing

package/dist/assets.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The files Styx ships beside its code: the code generator stubs (`stubs/`) and the project
+ * templates of `styx create` (`templates/`). They are read from the package folder, or from the
+ * asset loader that Hephaestus embeds in the standalone executables.
+ */
+/**
+ * The asset loader generated by Hephaestus (`AssetEmbedder`), keyed by the path in the package.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type EmbeddedAssets = {
+    getAssetString(path: string): string | null;
+    listAssets(): string[];
+};
+/**
+ * Uses the assets embedded in a standalone executable. Called by its entry point.
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @param assets The asset loader generated by Hephaestus.
+ */
+export declare const useEmbeddedAssets: (assets: EmbeddedAssets | undefined) => void;
+/**
+ * Reads an asset as text.
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @param path The path of the asset in the package, such as `stubs/job.stub`.
+ */
+export declare const readAsset: (path: string) => Promise<string>;
+/**
+ * Lists the assets under a folder, with their paths relative to it.
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @param folder The folder in the package, such as `templates/template-single`.
+ */
+export declare const listAssets: (folder: string) => Promise<string[]>;

package/dist/cli/app.d.ts

@@ -0,0 +1,15 @@
+import type { ModuleClass } from '@elysiumjs/core';
+import { Module } from '@elysiumjs/core';
+/**
+ * The commands Styx runs itself: `create`, the code generators and `routes:generate`.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare class StyxCliModule extends Module {
+}
+/**
+ * Runs a command of the global `styx` CLI, without loading any project.
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @param argv The command and its arguments.
+ * @param tools Modules of build tools found in the project (such as Hephaestus).
+ */
+export declare const runCli: (argv: string[], tools?: ModuleClass[]) => Promise<void>;

package/dist/cli/route.d.ts

@@ -0,0 +1,51 @@
+/**
+ * What the `styx` command does with its arguments.
+ * - `version`: print the version.
+ * - `cli`: run Styx's own commands (`create`, the code generators) without loading a project.
+ * - `handoff`: run the project's own Styx, so the project's versions are used.
+ * - `app`: load the project's app and run the command there (`serve`, the app's commands).
+ * - `error`: say why the command cannot run here.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type Route = {
+    kind: 'version';
+} | {
+    kind: 'cli';
+    argv: string[];
+} | {
+    kind: 'handoff';
+    cli: string;
+    argv: string[];
+} | {
+    kind: 'app';
+    project: string;
+    argv: string[];
+} | {
+    kind: 'error';
+    message: string;
+};
+/** Where the `styx` command runs. */
+export type RouteContext = {
+    /** The project folder (holding `.elysiumrc`), when inside one. */
+    project?: string;
+    /** The entry of the project's own Styx, when the project installs it. */
+    projectCli?: string;
+    /** The entry of the running Styx. */
+    self: string;
+};
+/** Code generators: they write files and never load the app. */
+export declare const isGenerator: (command: string | undefined) => boolean;
+/**
+ * Commands that read the app's code without booting it, with the project's own packages.
+ * `build` runs `hephaestus:build`.
+ */
+export declare const isAppTool: (command: string | undefined) => boolean;
+/** Commands Styx runs itself inside a project: the code generators and the app tools. */
+export declare const isCliCommand: (command: string | undefined) => boolean;
+/**
+ * Decides what `styx` does with its arguments.
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @param argv The arguments, without the executable and script.
+ * @param context Where the command runs.
+ */
+export declare const route: (argv: string[], context: RouteContext) => Route;

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+export {};