Layer
Layers are named groups of handlers that organise code by functional concern within a realm. For the conceptual overview and the list of well-known layer names, see concepts/layer.
Folder Structure
Well-known layer folders are auto-discovered — no layer.server.ts is needed:
realmname/
├── server.ts # Optional — only for realm-level shared config
├── error/ # Auto-activated (server, integration)
│ └── error.ts
├── adapter/ # Auto-activated (server, integration)
│ ├── db.ts # Self-contained adapter with config + validation
│ └── db/ # Handler group: realmname.db
│ ├── userUserAdd.ts
│ └── userUserFind.ts
├── orchestrator/ # Auto-activated (server, integration)
│ ├── dispatch.ts # Self-contained orchestrator with config + validation
│ └── user/ # Handler group: realmname.user
│ ├── ~.schema.ts # Auto-generated validation schema
│ └── userUserAdd.ts
├── gateway/ # Auto-activated (server, integration)
│ └── api/
│ └── user.yaml
├── sim/ # Auto-activated (server, integration)
│ └── backend.ts
├── server/ # Server-only well-known sub-layers
│ ├── api/ # Auto-activated (server, integration)
│ ├── init/ # Auto-activated (server, default)
│ └── test/ # Server tap tests (server, integration)
│ └── test/
│ └── testUser.ts
└── test/ # BROWSER layer (Playwright *.play.ts) — auto-activated (browser, integration)
└── user.play.ts
Custom layer folders (non-well-known names) require a layer.server.ts or layer.browser.ts:
// myCustomLayer/layer.server.ts
import {layer} from '@feasibleone/blong';
export default layer({
default: true, // active in all environments
microservice: true, // additionally active in microservice deployment
});
Self-Contained Layer Pattern
Each layer owns its configuration and validation. Avoid putting layer config in the parent
server.ts — this makes the layer reusable and reduces the number of files to change when adding a
new adapter or orchestrator.
Adapter
// adapter/db.ts
import {adapter} from '@feasibleone/blong';
export default adapter(blong => ({
extends: 'adapter.knex',
validation: blong.type.Object({
namespace: blong.type.Union([blong.type.String(), blong.type.Array(blong.type.String())]),
imports: blong.type.Union([blong.type.String(), blong.type.Array(blong.type.String())]),
logLevel: blong.type.Optional(blong.type.String()),
}),
activation: {
default: {
namespace: 'db/$subject',
imports: '$subject.db',
},
dev: {logLevel: 'trace'},
prod: {logLevel: 'warn'},
},
}));
Orchestrator
// orchestrator/dispatch.ts
import {orchestrator} from '@feasibleone/blong';
export default orchestrator(blong => ({
extends: 'orchestrator.dispatch',
validation: blong.type.Object({
namespace: blong.type.Union([blong.type.String(), blong.type.Array(blong.type.String())]),
imports: blong.type.Union([
blong.type.String(),
blong.type.Array(blong.type.String()),
blong.type.Array(blong.type.RegExp()),
]),
destination: blong.type.Optional(blong.type.String()),
}),
activation: {
default: {
destination: 'db',
namespace: ['$subject'],
imports: [/^$subject\./],
},
},
}));
Realm Entry Point (only when needed)
server.ts is optional. Include it only when config or validation must be shared across layers:
// server.ts
import {realm} from '@feasibleone/blong';
export default realm(blong => ({
url: import.meta.url,
validation: blong.type.Object({
myService: blong.type.Object({url: blong.type.String()}),
}),
activation: {
default: {
myService: {url: 'http://localhost:8080'},
},
},
}));
Configuration Levels
Configuration sits next to the thing it configures, and the levels override each other in a fixed order — the last one that sets a value wins:
| Level | Where | Scope |
|---|---|---|
| Component config | activation in the layer file (or its validation) | one adapter/orchestrator |
| Handler group defaults | config.ts in the group folder | one realmname.foldername |
| Realm override | config.namespace.<group> in the realm's server.ts | one group, for one deployment |
A component's own config is merged as default → each active intent → the platform's configs → ci
when the process runs on CI, so a dev: block overrides a default: one and a prod: block
overrides neither unless prod is active. See the configuration pattern for
the global merge chain that decides the effective values, and concepts/layer
for why the config belongs in the layer.
Group-Level Default Config
Each handler group folder can contain a config.ts that sets defaults for all handlers in that
group:
// orchestrator/payment/config.ts
export default {
default: {
timeout: 30000,
endpoint: 'https://api.payment.example.com',
},
dev: {
endpoint: 'https://api.dev.payment.example.com',
},
};
The blocks are merged in the order default, then the active intents, so a handler in that folder
reads the effective object as its config. A realm can override one value for a deployment without
touching the folder — the realm's namespace.<folder> entry is merged on top:
// server.ts — the override wins over the group's own config.ts
export default realm(blong => ({
url: import.meta.url,
config: {
prod: {
namespace: {
payment: {endpoint: 'https://payment.internal'},
},
},
},
}));
Portability
Because each layer declares when it is active, the same realm runs as a monolith and as separate
services without edits: a layer whose activation also names microservice is loaded when the
realm is deployed on its own, and the realm's server.ts never had to know which case it was in.
Handler Group Naming
Groups are named realmname.foldername. For example, a realm named user with a folder
orchestrator/user/ produces the group name user.user.
Reference groups in the imports property:
activation: {
default: {
namespace: ['user', 'role'],
imports: ['user.user', 'user.role'],
},
},
Error Layer
// realmname/error/error.ts
export default {
userNotFound: 'User not found',
userExists: 'User already exists',
permissionDenied: 'Permission denied',
};
One Handler Per File
Each handler lives in its own file named after the semantic triple:
userUserAdd→userUserAdd.tspaymentTransferSend→paymentTransferSend.ts
This makes ctrl+p / quick-open discovery fast: typing uua immediately finds userUserAdd.ts.
Best Practices
- Co-locate config — put validation and activation inside the layer file, not
server.ts. - One file per handler — keeps diffs small and discovery fast.
- Group by entity — place handlers for the same business entity in the same folder.
- Use
~.schema.tsfor auto-generated validation (see validation). - Error first — define errors in the
errorlayer before implementing any business logic.
Examples
- Complete realm:
test/framework/demo/ - EIP patterns with mocks:
demo/blong-eip/