@itrocks/framework 0.2.1 → 0.2.2

package/README.md

@@ -7,3 +7,254 @@
 # it.rocks framework
 
 RAD framework for intuitive web application development, blending data and domain-driven design with modular architecture.
+
+*This documentation was written by an artificial intelligence and may contain errors or approximations.
+It has not yet been fully reviewed by a human. If anything seems unclear or incomplete,
+please feel free to contact the author of this package.*
+
+## Installation
+
+```bash
+npm i @itrocks/framework
+```
+
+In a typical it.rocks application you install the framework together with
+the modules that provide your domain model, actions and UI pieces. The
+framework itself focuses on wiring everything together.
+
+## Usage
+
+Importing `@itrocks/framework` has two main effects:
+
+- it boots the framework at runtime (composition of modules, configuration
+  loading, HTTP server and main loop),
+- it exposes enhanced reflection helpers `ReflectClass` and
+  `ReflectProperty` that integrate with the rest of the it.rocks
+  ecosystem.
+
+Most of the time you do **not** import low‑level files from this package
+directly. Instead you:
+
+1. Start your application by importing the compiled entry point
+   `@itrocks/framework/cjs/framework.js` (or the plain `@itrocks/framework`
+   export from Node when appropriate).
+2. Use `ReflectClass` / `ReflectProperty` from `@itrocks/framework` when you
+   need reflection that understands it.rocks‑specific concepts such as
+   `uses` and HTML transformers.
+
+### Minimal bootstrap example
+
+The simplest way to start an it.rocks application is to import the
+framework once at startup. It will:
+
+- scan configuration files (`config.yaml`, `local.yaml`) of your
+  application and its dependencies,
+- compose all registered modules (actions, routes, templates, stores,
+  transformers, …),
+- build the default action workflow,
+- bind framework dependencies,
+- run the main server loop.
+
+```ts
+// index.ts
+import '@itrocks/framework'
+
+// Import your application modules so that their configuration, actions
+// and templates are discovered during composition.
+import '@itrocks/home'
+import './src/domain'
+```
+
+When this file is executed with Node (after TypeScript compilation), the
+framework starts automatically and exposes your routes and actions.
+
+### Using framework reflection helpers
+
+`ReflectClass` and `ReflectProperty` behave like their counterparts from
+`@itrocks/reflect`, but they add framework‑level knowledge:
+
+- `ReflectClass` understands mixins declared through `@itrocks/uses` and
+  merges their property types,
+- `ReflectProperty` is able to render property values using
+  transformers from `@itrocks/transformer` and
+  `@itrocks/core-transformers`.
+
+```ts
+import type { ObjectType }              from '@itrocks/class-type'
+import { ReflectClass }                 from '@itrocks/framework'
+import { EmailAddress, emailAddressOf } from '@itrocks/email-address'
+
+class User {
+  @EmailAddress()
+  email = ''
+
+  name = ''
+}
+
+async function renderUserSummary(user: User) {
+  const reflectClass = new ReflectClass<User>(User as ObjectType<User>)
+  const properties   = reflectClass.properties
+
+  const result: Record<string, string> = {}
+
+  for (const property of properties) {
+    const isEmail = emailAddressOf(User, property.name as keyof User)
+    const value   = await property.output()
+
+    result[property.name] = isEmail ? `<a href="mailto:${value}">${value}</a>` : String(value ?? '')
+  }
+
+  return result
+}
+```
+
+In this example:
+
+- `ReflectClass` gives you `ReflectProperty` instances rather than the
+  bare properties from `@itrocks/reflect`,
+- each `ReflectProperty` can render its value using configured
+  transformers (`property.output()`),
+- you can combine metadata from other packages (like
+  `@itrocks/email-address`) to build higher‑level behaviour.
+
+## API
+
+`@itrocks/framework` exposes two main public symbols and the side‑effect
+of bootstrapping the framework when its main module is imported.
+
+### Framework bootstrap (side‑effect of importing `@itrocks/framework`)
+
+When the compiled JavaScript entry point (`cjs/framework.js`) is loaded,
+the following steps are executed:
+
+1. `scanConfigFiles()` from `@itrocks/config` is called to build the
+   global `config` object from all discovered `config.yaml` / `local.yaml`
+   files.
+2. The application composition is built with `compose()` from
+   `@itrocks/compose`, wiring stores, actions, routes, templates and other
+   components declared by installed modules.
+3. `build()` from `@itrocks/default-action-workflow` is invoked to
+   register the default actions workflow (list/new/delete, login/signup,
+   output/edit/print/delete, …).
+4. `bind()` from the local `dependencies` module wires framework
+   dependencies (such as HTTP server, logging and storage bindings).
+5. `run()` from the local `main` module starts the framework main loop
+   (HTTP server and request handling in a typical application).
+
+You normally do not call any of these functions directly. Importing the
+module once at startup is enough to run your application, provided that
+you have configured your routes and modules.
+
+### `class ReflectClass<T extends object = object> extends RC<T>`
+
+Enhanced reflection class that extends
+`@itrocks/reflect:ReflectClass<T>` and adds framework‑specific
+behaviour.
+
+Typical usage:
+
+```ts
+import { ReflectClass } from '@itrocks/framework'
+
+const reflectClass = new ReflectClass(SomeDomainClass)
+```
+
+#### Methods and properties
+
+- `inheritedPropertyTypes(propertyTypes: PropertyTypes): void`
+
+  Extends the base implementation by also merging property types coming
+  from classes declared in the `uses` of the current type (via
+  `@itrocks/uses`). This lets you treat mixin properties as if they were
+  declared directly on the class.
+
+- `get parent(): ReflectClass | undefined`
+
+  Returns the parent `ReflectClass` if the current type inherits from
+  another class. The parent is wrapped so that it also benefits from the
+  framework‑specific methods.
+
+- `get properties(): Iterable<ReflectProperty<T>>`
+
+  Returns an iterable collection of `ReflectProperty<T>` instances, one
+  for each property of the reflected class. All of them are upgraded to
+  the `ReflectProperty` defined by this package.
+
+- `property(name: KeyOf<T>): ReflectProperty<T>`
+
+  Returns a single `ReflectProperty<T>` instance for the given property
+  name. This is the preferred way to work with properties when you want
+  to use framework helpers like `output()` and `edit()`.
+
+- `get uses(): Type[]`
+
+  Returns the list of mixin classes attached to the current type through
+  `@itrocks/uses`. The result is cached on the instance.
+
+### `class ReflectProperty<T extends object> extends RP<T>`
+
+Enhanced property reflection class that extends
+`@itrocks/reflect:ReflectProperty<T>` and knows how to call transformers
+from `@itrocks/transformer` / `@itrocks/core-transformers` in the
+context of the framework.
+
+Typical usage:
+
+```ts
+import { ReflectClass } from '@itrocks/framework'
+
+async function renderProperty(object: any, name: string) {
+  const reflectClass    = new ReflectClass(object.constructor)
+  const reflectProperty = reflectClass.property(name as never)
+  return await reflectProperty.output()
+}
+```
+
+#### Properties
+
+- `get class: ReflectClass<T>`
+
+  Returns the owning `ReflectClass` instance, upgraded from the base
+  implementation so that it always exposes the framework‑aware
+  `ReflectClass`.
+
+#### Methods
+
+- `async edit(format: string = HTML): Promise<any>`
+
+  Applies the `EDIT` transformer chain to the property and returns the
+  result, usually an HTML fragment representing an input field or an
+  editable widget. You can change the `format` to use an alternative
+  representation if you have registered other transformers.
+
+- `async output(format: string = HTML, askFor?: HtmlContainer): Promise<any>`
+
+  Applies the `OUTPUT` transformer chain to the property and returns the
+  result (often an HTML fragment for display). The optional `askFor`
+  `HtmlContainer` lets you drive how the output is wrapped.
+
+- `async outputMandatoryContainer(format: string = HTML): Promise<any>`
+
+  Convenience wrapper around `output()` that always wraps the result in
+  a mandatory `HtmlContainer`.
+
+- `async outputOptionalContainer(format: string = HTML): Promise<any>`
+
+  Convenience wrapper around `output()` that wraps the result in an
+  optional `HtmlContainer`.
+
+## Typical use cases
+
+- Quickly bootstrap a full it.rocks web application by importing the
+  framework once at startup; it takes care of configuration loading,
+  module composition and action workflow wiring.
+- Integrate multiple it.rocks modules (actions, routes, templates,
+  storage, translations, UI components, …) without writing plumbing
+  code.
+- Use `ReflectClass` / `ReflectProperty` when you need to:
+  - inspect domain models and their properties (including mixins),
+  - generate forms and views using the configured transformers,
+  - render property values consistently across your application.
+- Build higher‑level tooling (CRUD generators, admin dashboards,
+  documentation tools) on top of the reflection API exposed by the
+  framework.

package/package.json

@@ -76,8 +76,12 @@
 		"business",
 		"domain",
 		"driven",
+		"dynamics",
 		"framework",
-		"it.rocks"
+		"http",
+		"itrocks",
+		"it.rocks",
+		"package"
 	],
 	"license": "ISC",
 	"name": "@itrocks/framework",
@@ -91,5 +95,5 @@
 		"build:front": "tsc -p src/front/tsconfig.json && sed -i 's#../../##g' *.js *.d.ts"
 	},
 	"types": "./cjs/framework.d.ts",
-	"version": "0.2.1"
+	"version": "0.2.2"
 }