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.

$3

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.

$3

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 as ObjectType)
const properties = reflectClass.properties

const result: Record = {}

for (const property of properties) {
const isEmail = emailAddressOf(User, property.name as keyof User)
const value = await property.output()

result[property.name] = isEmail ? ${value} : 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.

$3

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.

$3

Enhanced reflection class that extends
@itrocks/reflect:ReflectClass 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>

Returns an iterable collection of ReflectProperty instances, one
for each property of the reflected class. All of them are upgraded to
the ReflectProperty defined by this package.

- property(name: KeyOf): ReflectProperty

Returns a single ReflectProperty 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.

$3

Enhanced property reflection class that extends
@itrocks/reflect:ReflectProperty 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

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

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

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

Convenience wrapper around output() that always wraps the result in
a mandatory HtmlContainer.

- async outputOptionalContainer(format: string = HTML): Promise

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.